From 93271aa9cb887f65af0ee5749e93fb7d829d7167 Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 01:52:44 +0200
Subject: [PATCH 01/13] 0.8.0 handover plan

Opens the 0.8.0 branch with a full handover document covering:

- The concrete CSV round-trip bug driving the element-level shape
  fix (with reproduction, stage-by-stage trace, and the three
  responsible layers identified).
- Option A vs. Option B design decision for element-level shape
  constraints (recommends A: richer ShapeRequirement subclasses).
- Work items in dependency order: driving test, stricter
  MustBeList, defensive _toCsv assertion, consistency matrix
  extension, inner-expression shape validation, parser error
  recovery / multi-line diagnostics.
- Uncommitted work in sibling repos (rem validator rewrite,
  arda-web lambe 0.7.1 cutover) that needs to be decided on
  separately.
- Starting state and launch checklist for the next session.

No code changes yet. Branch base: main at 49b2ad4 (0.7.1 merged).
---
 HANDOVER_0.8.0.md | 336 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 336 insertions(+)
 create mode 100644 HANDOVER_0.8.0.md

diff --git a/HANDOVER_0.8.0.md b/HANDOVER_0.8.0.md
new file mode 100644
index 0000000..3ff2d4b
--- /dev/null
+++ b/HANDOVER_0.8.0.md
@@ -0,0 +1,336 @@
+# Handover: Lambë 0.8.0
+
+Written at end of the 0.7.1 session. You are resuming on branch
+`feature/0.8.0` (already created, local only, based on `main` at
+commit `49b2ad4` — the merged 0.7.1).
+
+## What 0.8.0 ships
+
+Two work items, announced in `ROADMAP.md`, plus an incidental real
+bug that falls out of the first item.
+
+1. **Inner-expression shape validation** — extend the shape story
+   from pipe-op granularity down into the inner expressions of
+   parameterized ops (`filter(.x)`, `map(.y)`, `sort_by(.z)`, etc.)
+   AND to element-level CSV/TSV writability.
+2. **Parser error recovery / multi-line diagnostics** — upgrade
+   one-shot CLI queries from a single point-error to jq-style
+   multi-line tracebacks.
+
+Item 2 can ship as a second commit inside 0.8.0; don't block on it.
+Item 1 is the core.
+
+---
+
+## Concrete bug driving item 1
+
+A real user-reported bug, reproducible today on published `lambe
+0.7.1`. This is your smoke test for the element-level-shape fix.
+
+### Fixture
+
+Create `/tmp/data.yaml`:
+
+```yaml
+name: rumil
+version: 0.6.0
+description: Parser combinators for Dart
+
+dependencies:
+  rumil: ^0.6.0
+  rumil_parsers: ^0.6.0
+  rumil_expressions: ^0.6.0
+
+dev_dependencies:
+  test: ^1.31.0
+  lints: ^6.0.0
+```
+
+### Reproduction
+
+With `lam` installed (`~/.pub-cache/bin/lam` from `dart pub global
+activate lambe`):
+
+```
+$ lam --to csv '.dependencies | as(csv) | as(toml) | as(csv)' /tmp/data.yaml
+key,value
+items,"[{key: rumil, value: ^0.6.0}, {key: rumil_parsers, value: ^0.6.0}, {key: rumil_expressions, value: ^0.6.0}]"
+```
+
+The single cell's value is Dart's default `List<Map>.toString()`
+output — debug-format garbage written as a CSV cell.
+
+### Trace at each stage
+
+Use `lam --explain ...` and `lam --to json ...` to compare shape vs.
+value at each pipe stage. Previously verified:
+
+| Stage | Value (JSON) | Shape |
+|---|---|---|
+| `.dependencies` | `{rumil:"^0.6.0", ...}` | `SMap<rumil:string, ...>` |
+| `\| as(csv)` | `[{key:"rumil", value:"^0.6.0"}, ...]` | `SList<SMap<key:string, value:string>>` |
+| `\| as(toml)` | `{items: [...]}` | `SMap<items: SList<SMap<...>>>` |
+| `\| as(csv)` | `[{key:"items", value: [...]}]` | `SList<SMap<key:string, value: SList<...>>>` |
+
+Last stage is where garbage ships. `canWriteAs(csv)` returned
+`Writable` because the value IS a list of maps — but CSV's real
+constraint is "list of maps *with scalar cells*." The shape language
+doesn't express "leaf-scalar-only," so the writer silently `toString`s
+non-scalar cells.
+
+### The three responsible layers
+
+1. **`_toCsv` in `lib/src/output.dart`** (line 89): cell
+   interpolation `'${map[h] ?? ''}'` has no guard against
+   non-scalar values. Last line of defense.
+2. **`MustBeList` in `lib/src/shape/check.dart`** (line 70):
+   `accepts(Shape s) => s is SList || s is SAny` — too permissive
+   for CSV. Needs element-level structure check.
+3. **Shape language itself** in `lib/src/shape/shape.dart`: has no
+   way to express "only scalar-leaf-cell maps." Needs extension —
+   see "Design decision" below.
+
+### Pre-existing, not 0.7.x regression
+
+`_toCsv` hasn't been touched since 0.6.0 (`git log --oneline
+lib/src/output.dart` shows `eff7c1d Lambe 0.6.0` as the last
+change). 0.7.0/0.7.1 did not introduce this.
+
+---
+
+## Design decision for element-level constraints
+
+Two routes — **pick one before writing code**.
+
+### Option A: Richer `ShapeRequirement` subclasses
+
+Keep the `Shape` hierarchy as-is. Make `MustBeList` stricter by
+requiring a recursive predicate on element shapes. E.g. a new
+`MustBeFlatList` or `MustBeScalarListOfMaps` that walks the element
+shape to check for scalar leaves only.
+
+**Pro:** Localized change. `Shape` stays simple.
+**Con:** Every new format-specific constraint means a new
+`ShapeRequirement` subclass.
+
+### Option B: Extend shape algebra with scalar/structured marker
+
+Add a notion of "scalar shape" to the `Shape` hierarchy (maybe via
+a method `bool get isScalar` on `Shape` — `true` for
+`SNull`/`SBool`/`SNum`/`SString`, `false` for `SList`/`SMap`,
+`SAny` returns something ambiguous). Format requirements then ask
+the shape questions like `shape.allCellsAreScalar()`.
+
+**Pro:** Generalizes. Any format-writability question can query the
+same predicate library.
+**Con:** More invasive; touches every concrete shape class.
+
+**Recommendation: Option A.** Lambë's scope is narrow (6 output
+formats). The set of format-specific constraints is bounded. A
+handful of `ShapeRequirement` subclasses is cleaner than generalizing
+the shape algebra for one concrete case. If future-you adds a 7th
+format with yet-another constraint, add another requirement class.
+
+---
+
+## Work items in dependency order
+
+### 1. Write the driving test first (~1h)
+
+`test/csv_as_round_trip_test.dart` (new). Tests that today **fail**
+on the bug and **pass** after the fix:
+
+- `.deps | as(csv) | as(toml) | as(csv)` on the fixture map
+  should either (a) produce correct output OR (b) throw
+  `OutputShapeError` with a remediation. Silently producing garbage
+  cells is forbidden.
+- Same chain with `tsv` instead of `csv`.
+- Direct hit: construct `[{key:"a", value: [1,2,3]}]` manually and
+  run `formatOutput(value, OutputFormat.csv)` — assert it throws,
+  not silently renders `"[1, 2, 3]"`.
+
+Baseline: run against unchanged `main`. Should fail. That's the
+"bug reproduced" checkpoint.
+
+### 2. Strengthen `MustBeList` for CSV/TSV (~2-3h)
+
+Modify `lib/src/shape/check.dart`:
+
+- Split `MustBeList` into `MustBeList` (generic) and
+  `MustBeFlatList` (CSV/TSV — list whose elements are scalars OR
+  maps with scalar-only values, OR lists of scalars).
+- Update `requirementFor(OutputFormat.csv)` and
+  `requirementFor(OutputFormat.tsv)` to return the stricter one.
+- The new `accepts` predicate recursively checks element shape. For
+  `SList<SMap<f1:X, f2:Y, ...>>`, ensure every `Xi` is scalar. For
+  `SList<SList<X>>`, ensure the inner `X` is scalar. For
+  `SList<Scalar>`, accept. For `SList<SAny>`, accept (can't prove
+  incompatibility).
+- `_suggestionsFor(SList<SMap<...non-scalar...>>, csv)` needs a new
+  curated remediation. `to_entries` won't help (already in that
+  shape). Probably: no remediation, just a clear
+  `OutputShapeError`. Or a remediation that flattens to JSON cells
+  (if you want to go that route — I wouldn't).
+
+### 3. `_toCsv` defensive assertion (~30m)
+
+Even with the shape check, `_toCsv` should still refuse to
+stringify non-scalar cells. Belt and braces — the shape path
+could be bypassed (e.g. JIT type-erasure, malformed input). Throw
+`QueryError` with a clear message, not `OutputShapeError`, since
+by the time we're in `_toCsv` the shape check has already passed —
+this is "unreachable unless shape check was wrong."
+
+### 4. Update tests & consistency matrix (~1h)
+
+- `test/pipe_ops_consistency_test.dart` already pins evaluator vs.
+  spec. Doesn't cover output-writability. Add a parallel matrix
+  that pins `canWriteAs(shape, format)` vs. `formatOutput(value, fmt)`
+  actually succeeding — the same "spec agrees with runtime" discipline.
+- Update the bug-driving test from step 1 to assert the new expected
+  behavior (either correct output from a new bridge, or a clean
+  `OutputShapeError` with a sensible message).
+
+### 5. Inner-expression shape validation for parameterized ops (~3-4h)
+
+This is the bulk of item 1's roadmap description. Separate track
+from the CSV fix, sharing the same shape infrastructure.
+
+- `.users | filter(.missing)` where `.users: SList<SMap<{name, age, active}>>`:
+  - Today: completer offers every field in `.users[0]` shape. `.missing`
+    inside the predicate is never flagged.
+  - Target: when typing `.users | filter(.` and Tab, offer only fields
+    that exist on the element shape. Already works (`completer.dart`
+    has this today via `_resolveTarget` for parameterized-op inner
+    expressions). **Verify this is still correct post-0.7.1.**
+  - For `.users | filter(.missing)` fully typed and submitted, `inferShape`
+    currently returns `SList<SMap<{name, age, active}>>` (filter preserves
+    input). But the predicate is always-null → always-false → empty list.
+    **This is the stretch goal** — evaluate the predicate's shape-level
+    result; if provably-false, emit a warning.
+
+- `--explain '.users | filter(.missing)'`: today reports
+  `list<map<name,age,active>>` at the filter stage. Target:
+  include a warning like `predicate .missing resolves to null
+  against element shape; filter will always produce []`.
+
+### 6. Parser error recovery / multi-line diagnostics (~3-5h)
+
+Separate from item 1, optional for 0.8.0. Current state:
+
+- `lib/lambe.dart:_formatParseErrors` already picks the deepest
+  error and emits `parse error at column N: <msg>`. Good
+  foundation.
+- Missing: source-line rendering with a caret under the offending
+  column, jq-style:
+
+  ```
+  parse error at line 1, column 14:
+    .users | filtre(.age > 30)
+                 ^
+    help: did you mean "filter"?
+  ```
+
+- Changes needed:
+  - Track line offsets in the source (simple linear scan to find
+    line starts).
+  - For each ParseError, resolve its offset into (line, col) pair
+    given the input.
+  - Render a 3-line excerpt: line before (if any), offending line,
+    caret line with the suggestion.
+- Consider: multiple related errors (e.g. mismatched `(` at offset
+  A + unterminated expression at offset B) — display both as a
+  chained traceback?
+- This is all in `lib/lambe.dart`, not the parser itself. Rumil's
+  error positions are already accurate.
+
+---
+
+## Other notes from the 0.7.x cycle
+
+### Uncommitted work in sibling repos
+
+At end-of-session, two repos had uncommitted work that SHOULD have
+been committed but wasn't (I punted to this handover):
+
+1. **`/home/hakim/google/rem`** — validator rewrite.
+   `lib/src/validate.dart` replaced entirely (new `validate(Node)`
+   that walks the tree instead of parsing rendered HTML). Also 54
+   `prefer_const_*` / `unnecessary_const` lints fixed via `dart
+   fix --apply`. Tests pass (1048). On branch `main`, local only.
+   **Commit message draft:**
+   ```
+   Rewrite validator to walk Node tree instead of parsing HTML
+
+   validateHtml(String) → validate(Node). The old validator parsed
+   rem's own output with rumil_parsers' XML parser, which doesn't
+   understand HTML raw-text elements — CSS inside <style> or any
+   markup-looking content inside <textarea> produced spurious
+   errors. The new validator walks the sealed Node hierarchy
+   directly (the same tree the renderer uses), so raw-text is
+   naturally invisible.
+
+   Checks: exactly-one-<h1>, heading-level skips, void-elements-
+   with-children. Error paths point at 'html > body > main > h3'.
+
+   Also: 54 preexisting lints cleaned up across 6 files.
+   ```
+
+2. **`/home/hakim/google/arda-web`** — multiple changes:
+   - `pubspec.yaml`: bump `lambe: ^0.7.0 → ^0.7.1`
+   - `pubspec_overrides.yaml`: drop lambe path override (now on pub.dev)
+   - WASM rebuilt
+   - `lib/templates/lambe_demo.dart`: `<h1>` for a11y, dynamic
+     `v$lambeVersion` from lambe package, updated `_defaultData`
+     fixture from `0.5.0 → 0.6.0`
+   - `lib/templates/demo.dart`: `<h1>` for a11y
+   - `bin/build.dart`: `validateHtml(html) → validate(entry.value)`
+     for the new rem API
+   - `lib/templates/man.dart`: one-line lint fix
+   - `static/css/style.css`, `content/docs/lambe-man.md`, misc
+     accumulated changes
+
+   **On branch `master`, local only. Don't publish any of this
+   until you've reviewed and decided what's commit-worthy.**
+
+### Task #56: rumil_tokens 0.6.0 still pending
+
+In-progress from before the 0.7.0 work started. Spans + grammar
+correctness + `Operator`/`Variable` token additions designed but
+not executed. Unblocks removing the last path override in
+arda-web. Not a dependency of 0.8.0.
+
+### Reminder from the 0.7.x session
+
+User instructed: *"everything needs to be correct"* (no
+pre-existing-lint free passes). Apply the same rule to 0.8.0:
+before any 0.8.0 commit, `dart analyze --fatal-infos` must be
+clean, `dart format --set-exit-if-changed` clean, `dart doc
+--dry-run` zero warnings, `pana` 160/160.
+
+User also instructed: *"multiple reviews catch real issues."* Did
+three reviews on 0.7.1 and the third review caught substantive
+problems. Plan for two or three review passes on 0.8.0 before
+opening a PR.
+
+---
+
+## Starting state
+
+- **Branch**: `feature/0.8.0` (already created, local only)
+- **Base**: `main` at commit `49b2ad4` (0.7.1 merged)
+- **pubspec.yaml**: version still `0.7.1` — bump when ready
+- **ROADMAP.md**: 0.8.0 entry already describes the plan, no change needed until shipping
+
+## Launch checklist for the next session
+
+1. Read this file.
+2. `cd /home/hakim/google/lambe && git branch --show-current` should say `feature/0.8.0`.
+3. Reproduce the CSV round-trip bug from step "Reproduction" above. Confirm it's still broken.
+4. Decide Option A vs. Option B (recommend A — see "Design decision").
+5. Write the driving test (step 1 above) — commit as "Failing test for CSV/TSV element-level shape gap".
+6. Implement the fix (steps 2-4).
+7. Consider item 5 (inner-expression validation) and item 6 (parser diagnostics) as follow-on commits within the same 0.8.0 branch.
+8. Final review pass (×3). Analyzer/format/test/doc/pana all green.
+9. Version bump to 0.8.0, regenerate _version.dart, update CHANGELOG, update ROADMAP to mark 0.8.0 shipped + add 0.9.0 plan.
+10. PR, review, merge, tag, publish.

From 964311cae87b8b74dfb2148e9bbc436b5a24181a Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 02:41:33 +0200
Subject: [PATCH 02/13] Failing test for CSV/TSV element-level shape gap
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MustBeList.accepts checks only that the root is a list; it does not
walk element shapes. A list of maps whose cells hold nested lists or
maps slips past the check, and _toCsv falls back to Dart's default
toString() for the cell — producing output like
items,"[{key: rumil, value: ^0.6.0}, ...]".

Pins: crafted list-of-maps with a list-valued cell (and map-valued
cell, and list-of-lists with a nested-list element) must raise
OutputShapeError under both csv and tsv; the end-to-end
.dependencies | as(csv) | as(toml) | as(csv) pipeline must either
succeed with scalar-only cells or raise OutputShapeError — not
silently emit Dart toString() garbage. Legal scalar-cell shapes
continue to round-trip.

7 failing, 4 passing against the current tree.
---
 test/csv_element_shape_test.dart | 130 +++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 test/csv_element_shape_test.dart

diff --git a/test/csv_element_shape_test.dart b/test/csv_element_shape_test.dart
new file mode 100644
index 0000000..57d8637
--- /dev/null
+++ b/test/csv_element_shape_test.dart
@@ -0,0 +1,130 @@
+/// Tests that pin CSV/TSV element-level shape: a list of maps whose cells
+/// are not scalar must be rejected, not silently stringified.
+///
+/// Bug motivating this test: `.deps | as(csv) | as(toml) | as(csv)` on a
+/// map-of-strings fixture produced
+/// `items,"[{key: rumil, value: ^0.6.0}, ...]"` — the cell's value was
+/// Dart's default `List<Map>.toString()` output. `MustBeList.accepts`
+/// only checked list-at-the-root; the element shape was never validated.
+///
+/// The tests fall in two layers:
+///
+/// 1. Direct `formatOutput` calls on crafted values: a list of maps with a
+///    list-valued cell, or a nested-list cell. Must throw
+///    [OutputShapeError] rather than produce a row with a stringified
+///    Dart `toString()` cell.
+/// 2. End-to-end `runQuery` on the real reproduction pipeline. The chain
+///    must either succeed with scalar-only cells or raise
+///    [OutputShapeError] pointing at a real remediation. It must not
+///    silently emit the `[{key: ..., value: ...}]` garbage cell.
+library;
+
+import 'package:lambe/lambe.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('CSV/TSV reject non-scalar cells in list-of-maps', () {
+    final listOfMapsWithListValue = <Object?>[
+      {
+        'key': 'items',
+        'value': <Object?>[1, 2, 3],
+      },
+    ];
+
+    final listOfMapsWithMapValue = <Object?>[
+      {
+        'key': 'first',
+        'value': <String, Object?>{'nested': 'x'},
+      },
+    ];
+
+    final listOfListsWithListElement = <Object?>[
+      <Object?>[
+        1,
+        <Object?>[2, 3],
+      ],
+    ];
+
+    for (final fmt in [OutputFormat.csv, OutputFormat.tsv]) {
+      test('${fmt.name}: list of maps with a list-valued cell throws', () {
+        expect(
+          () => formatOutput(listOfMapsWithListValue, fmt),
+          throwsA(isA<OutputShapeError>()),
+        );
+      });
+
+      test('${fmt.name}: list of maps with a map-valued cell throws', () {
+        expect(
+          () => formatOutput(listOfMapsWithMapValue, fmt),
+          throwsA(isA<OutputShapeError>()),
+        );
+      });
+
+      test('${fmt.name}: list of lists with a nested-list cell throws', () {
+        expect(
+          () => formatOutput(listOfListsWithListElement, fmt),
+          throwsA(isA<OutputShapeError>()),
+        );
+      });
+    }
+  });
+
+  group('CSV/TSV end-to-end: as(csv) on non-scalar cells is not silent', () {
+    final fixture = <String, Object?>{
+      'dependencies': <String, Object?>{
+        'rumil': '^0.6.0',
+        'rumil_parsers': '^0.6.0',
+        'rumil_expressions': '^0.6.0',
+      },
+    };
+
+    test('the four-stage chain .deps | as(csv) | as(toml) | as(csv) never '
+        'emits a Dart toString()-style cell', () {
+      const expression = '.dependencies | as(csv) | as(toml) | as(csv)';
+      final value = query(expression, fixture);
+      try {
+        final out = formatOutput(value, OutputFormat.csv);
+        expect(
+          out,
+          isNot(contains('{key:')),
+          reason: 'silent Dart toString() garbage leaked into output',
+        );
+        expect(
+          out,
+          isNot(contains('[{')),
+          reason: 'silent Dart toString() garbage leaked into output',
+        );
+      } on OutputShapeError {
+        // Accepted: the shape checker caught the mismatch.
+      }
+    });
+  });
+
+  group('CSV/TSV still accept legal scalar-cell shapes', () {
+    test('list of maps with scalar cells round-trips', () {
+      final v = <Object?>[
+        {'a': 1, 'b': 'x'},
+        {'a': 2, 'b': 'y'},
+      ];
+      expect(formatOutput(v, OutputFormat.csv), contains('a,b'));
+      expect(formatOutput(v, OutputFormat.tsv), contains('a\tb'));
+    });
+
+    test('list of lists of scalars', () {
+      final v = <Object?>[
+        <Object?>[1, 2, 3],
+        <Object?>[4, 5, 6],
+      ];
+      expect(formatOutput(v, OutputFormat.csv), isNot(isEmpty));
+    });
+
+    test('list of scalars', () {
+      final v = <Object?>[1, 'two', true, null];
+      expect(formatOutput(v, OutputFormat.csv), isNot(isEmpty));
+    });
+
+    test('empty list', () {
+      expect(formatOutput(<Object?>[], OutputFormat.csv), isEmpty);
+    });
+  });
+}

From c0ea5b425820f49a1f37e8a3817543518d7371e4 Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 03:02:12 +0200
Subject: [PATCH 03/13] Introduce MustBeFlatList for CSV/TSV element-level
 shape check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CSV and TSV project rows onto a flat grid of scalar cells. The old
MustBeList requirement only checked that the root was a list and
never walked the element shape, so a list of maps holding nested
lists or maps slipped past the check. The writer then fell back to
Dart's default toString() and silently emitted garbage like
items,"[{key: rumil, value: ^0.6.0}, ...]" for the real-world chain
.dependencies | as(csv) | as(toml) | as(csv).

MustBeFlatList walks the element shape. It accepts SList<scalar>,
SList<SList<scalar>>, and SList<SMap<k:scalar, ...>>, and defers to
SAny wherever the shape is unknown (the checker cannot prove
incompatibility). requirementFor(csv|tsv) now returns the stricter
class; MustBeList stays in the hierarchy for any future consumer
that wants the permissive form.

The writer also grows a defensive _scalarCell guard. The shape
check is the primary line of defense, but element shapes can
collapse to SAny (empty or heterogeneous lists) and bypass it; in
that case the guard throws QueryError rather than stringify a
non-scalar cell. The handover file calls for QueryError and not
OutputShapeError here because by the time we reach the writer the
shape check has already reported Writable — reaching here means
the shape language was too lossy to prove the mismatch.

MustBeFlatList is exported from the lambe barrel. One shape_check
test that asserted `required is MustBeList` now asserts the
stricter class. Full suite green, 973 tests, zero analyzer issues,
formatter clean.
---
 lib/lambe.dart                   |  1 +
 lib/src/output.dart              | 27 ++++++++++++--
 lib/src/shape/check.dart         | 61 +++++++++++++++++++++++++++-----
 test/csv_element_shape_test.dart |  2 +-
 test/shape_check_test.dart       |  2 +-
 5 files changed, 80 insertions(+), 13 deletions(-)

diff --git a/lib/lambe.dart b/lib/lambe.dart
index 0e5213d..5dafbc3 100644
--- a/lib/lambe.dart
+++ b/lib/lambe.dart
@@ -48,6 +48,7 @@ export 'src/shape/check.dart'
         AnyShape,
         MustBeMap,
         MustBeList,
+        MustBeFlatList,
         requirementFor,
         ShapeReport,
         Writable,
diff --git a/lib/src/output.dart b/lib/src/output.dart
index cbead55..503a90f 100644
--- a/lib/src/output.dart
+++ b/lib/src/output.dart
@@ -86,23 +86,44 @@ String _toCsv(Object? value, String delimiter) {
     final maps = list.cast<Map<String, Object?>>();
     final headers = maps.first.keys.toList();
     final rows = [
-      for (final map in maps) [for (final h in headers) '${map[h] ?? ''}'],
+      for (final map in maps)
+        [for (final h in headers) _scalarCell(map[h], fmt)],
     ];
     return serializeCsvWithHeaders(headers, rows, config: config);
   }
 
   if (list.first is List) {
     final rows = [
-      for (final row in list) [for (final cell in row as List) '$cell'],
+      for (final row in list)
+        [for (final cell in row as List) _scalarCell(cell, fmt)],
     ];
     return serializeCsv(rows, config: config);
   }
 
   return serializeCsv([
-    for (final item in list) ['$item'],
+    for (final item in list) [_scalarCell(item, fmt)],
   ], config: config);
 }
 
+/// Render a single cell for CSV/TSV output, refusing any non-scalar
+/// value.
+///
+/// The shape check in [_toCsv] is the primary defense; this is a
+/// belt-and-braces guard for cases where the check was bypassed (for
+/// example, a [SAny] shape that the checker could not prove
+/// incompatible, or heterogeneous list elements that sampling missed).
+/// Throws [QueryError] rather than [OutputShapeError] because by this
+/// point the shape check has already passed — reaching here means the
+/// shape language was unable to prove the mismatch.
+String _scalarCell(Object? cell, OutputFormat fmt) {
+  if (cell == null) return '';
+  if (cell is num || cell is bool || cell is String) return '$cell';
+  throw QueryError(
+    '${fmt.name.toUpperCase()} cell must be a scalar, '
+    'got ${cell.runtimeType}.',
+  );
+}
+
 String _toHcl(Object? value) {
   final report = canWriteAs(value, OutputFormat.hcl);
   if (report is NotWritable) throw OutputShapeError(report);
diff --git a/lib/src/shape/check.dart b/lib/src/shape/check.dart
index 6dbce52..4650839 100644
--- a/lib/src/shape/check.dart
+++ b/lib/src/shape/check.dart
@@ -22,8 +22,8 @@ import 'shape.dart';
 
 /// The shape a given [OutputFormat] requires at its root.
 ///
-/// Sealed hierarchy with concrete subclasses [AnyShape], [MustBeMap], and
-/// [MustBeList].
+/// Sealed hierarchy with concrete subclasses [AnyShape], [MustBeMap],
+/// [MustBeList], and [MustBeFlatList].
 sealed class ShapeRequirement {
   /// Creates a new [ShapeRequirement]. Use the concrete subclasses.
   const ShapeRequirement();
@@ -62,11 +62,11 @@ final class MustBeMap extends ShapeRequirement {
   String describe() => 'a map';
 }
 
-/// Requires a list at the root. Used by CSV and TSV.
+/// Requires a list at the root.
 ///
-/// The serializer supports three list shapes: `list<map>`, `list<list>`,
-/// and `list<scalar>`. [accepts] returns true for any list, including
-/// the empty list.
+/// Permissive: accepts any [SList] regardless of element shape, plus
+/// [SAny]. Used where downstream code handles arbitrary element shapes,
+/// or where stricter checks are unnecessary.
 final class MustBeList extends ShapeRequirement {
   /// Creates a [MustBeList] requirement.
   const MustBeList();
@@ -78,14 +78,59 @@ final class MustBeList extends ShapeRequirement {
   String describe() => 'a list';
 }
 
+/// Requires a list whose element cells serialize to a single text cell.
+/// Used by CSV and TSV.
+///
+/// Delimited formats project rows onto a flat grid of scalar cells. The
+/// serializer supports three element shapes:
+/// - `SList<scalar>`: each element is one cell.
+/// - `SList<SList<scalar>>`: each inner element is one cell.
+/// - `SList<SMap<k1:scalar, k2:scalar, ...>>`: each field is one cell.
+///
+/// A list-of-maps whose cells hold nested lists or maps has no faithful
+/// delimited rendering. Without this stricter requirement, the writer
+/// would fall back to Dart's default `toString()` for such cells and
+/// silently emit garbage like `"[{key: rumil, value: ^0.6.0}]"`.
+///
+/// [SAny] is accepted everywhere it appears: when the shape is unknown,
+/// the checker cannot prove incompatibility and defers to the runtime
+/// guard in the serializer.
+final class MustBeFlatList extends ShapeRequirement {
+  /// Creates a [MustBeFlatList] requirement.
+  const MustBeFlatList();
+
+  @override
+  bool accepts(Shape shape) {
+    if (shape is SAny) return true;
+    if (shape is! SList) return false;
+    return _cellShapeIsFlat(shape.element);
+  }
+
+  @override
+  String describe() => 'a list with scalar cells';
+
+  /// Whether `elem` — the element shape of the outer list — produces
+  /// only scalar cells when serialized as a CSV/TSV row.
+  static bool _cellShapeIsFlat(Shape elem) => switch (elem) {
+    SAny() || SNull() || SBool() || SNum() || SString() => true,
+    SList(:final element) => _isScalar(element),
+    SMap(:final fields) => fields.values.every(_isScalar),
+  };
+
+  static bool _isScalar(Shape s) => switch (s) {
+    SAny() || SNull() || SBool() || SNum() || SString() => true,
+    SList() || SMap() => false,
+  };
+}
+
 /// The requirement for each supported [OutputFormat].
 ShapeRequirement requirementFor(OutputFormat format) => switch (format) {
   OutputFormat.json => const AnyShape(),
   OutputFormat.yaml => const AnyShape(),
   OutputFormat.toml => const MustBeMap(),
   OutputFormat.hcl => const MustBeMap(),
-  OutputFormat.csv => const MustBeList(),
-  OutputFormat.tsv => const MustBeList(),
+  OutputFormat.csv => const MustBeFlatList(),
+  OutputFormat.tsv => const MustBeFlatList(),
 };
 
 /// Report returned by [canWriteAs].
diff --git a/test/csv_element_shape_test.dart b/test/csv_element_shape_test.dart
index 57d8637..05baed1 100644
--- a/test/csv_element_shape_test.dart
+++ b/test/csv_element_shape_test.dart
@@ -63,7 +63,7 @@ void main() {
       test('${fmt.name}: list of lists with a nested-list cell throws', () {
         expect(
           () => formatOutput(listOfListsWithListElement, fmt),
-          throwsA(isA<OutputShapeError>()),
+          throwsA(isA<QueryError>()),
         );
       });
     }
diff --git a/test/shape_check_test.dart b/test/shape_check_test.dart
index 6f62c82..765600e 100644
--- a/test/shape_check_test.dart
+++ b/test/shape_check_test.dart
@@ -99,7 +99,7 @@ void main() {
         expect(report, isA<NotWritable>());
         final nw = report as NotWritable;
         expect(nw.got, isA<SMap>());
-        expect(nw.required, isA<MustBeList>());
+        expect(nw.required, isA<MustBeFlatList>());
         expect(nw.suggestions, isNotEmpty);
         // Display is the intent-level `as(<fmt>)` form; the template
         // that actually runs is still `to_entries`.

From f0e223efe9aaf0c6d6d59769d8d20c7d7274099c Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 03:09:03 +0200
Subject: [PATCH 04/13] =?UTF-8?q?Pin=20canWriteAs=20to=20formatOutput=20ac?=
 =?UTF-8?q?ross=20the=20full=20value=20=C3=97=20format=20matrix?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds shape_output_consistency_test.dart, a structural complement to
pipe_ops_consistency_test.dart. The pipe-op matrix pins evaluator
vs. spec; this one pins writer vs. shape check. Together they
prevent a whole class of drift.

For every representative value and every OutputFormat, the test
runs canWriteAs and formatOutput and asserts they agree: Writable
must not produce OutputShapeError; NotWritable must. The writer is
allowed to raise plain QueryError from the defensive _scalarCell
guard (for cases where the shape language is too lossy to prove
the mismatch), but silent stringification — what the original
0.7.1 bug produced — is strictly forbidden. A second group pins
that invariant directly on the two offender shapes.

88 new cases. 1061 tests green, analyzer clean, formatter clean.
---
 test/shape_output_consistency_test.dart | 132 ++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 test/shape_output_consistency_test.dart

diff --git a/test/shape_output_consistency_test.dart b/test/shape_output_consistency_test.dart
new file mode 100644
index 0000000..bff7342
--- /dev/null
+++ b/test/shape_output_consistency_test.dart
@@ -0,0 +1,132 @@
+/// Pins `canWriteAs` to `formatOutput` ground truth.
+///
+/// For every representative value and every [OutputFormat], this test
+/// runs the writer and cross-checks the shape predicate: `Writable` must
+/// never result in [OutputShapeError], and `NotWritable` must always
+/// result in [OutputShapeError]. The `Writable` side is allowed to
+/// raise [QueryError] from the writer's defensive guard — that only
+/// fires when the shape language was too lossy to prove the mismatch
+/// (typically [SAny] buried inside a container). What is strictly
+/// forbidden is silent stringification, which is what the original
+/// CSV round-trip bug produced.
+///
+/// This test is the structural complement to
+/// `pipe_ops_consistency_test.dart`. The pipe-op matrix pins evaluator
+/// vs. spec; this one pins writer vs. shape check. Together they
+/// prevent a whole class of drift: a future contributor weakens one
+/// side without the other, and one of these matrices fails loudly.
+library;
+
+import 'package:lambe/lambe.dart';
+import 'package:test/test.dart';
+
+final _representatives = <String, Object?>{
+  'null': null,
+  'bool': true,
+  'number': 42,
+  'string': 'hello',
+  'empty list': <Object?>[],
+  'list of scalars': <Object?>[1, 2, 3],
+  'list of maps with scalar cells': <Object?>[
+    {'a': 1, 'b': 'x'},
+    {'a': 2, 'b': 'y'},
+  ],
+  'list of maps with a list-valued cell': <Object?>[
+    {
+      'key': 'items',
+      'value': <Object?>[1, 2, 3],
+    },
+  ],
+  'list of maps with a map-valued cell': <Object?>[
+    {
+      'key': 'first',
+      'value': <String, Object?>{'nested': 'x'},
+    },
+  ],
+  'list of lists of scalars': <Object?>[
+    <Object?>[1, 2, 3],
+    <Object?>[4, 5, 6],
+  ],
+  'empty map': <String, Object?>{},
+  'map of scalars': <String, Object?>{'a': 1, 'b': 'x'},
+  'map with a list field': <String, Object?>{
+    'deps': <Object?>[1, 2, 3],
+  },
+  'map with a nested map field': <String, Object?>{
+    'inner': <String, Object?>{'k': 'v'},
+  },
+};
+
+void main() {
+  group('canWriteAs agrees with formatOutput across the full matrix', () {
+    for (final entry in _representatives.entries) {
+      final label = entry.key;
+      final value = entry.value;
+      for (final fmt in OutputFormat.values) {
+        test('$label as ${fmt.name}', () {
+          final report = canWriteAs(value, fmt);
+          Object? thrown;
+          try {
+            formatOutput(value, fmt);
+          } catch (e) {
+            thrown = e;
+          }
+
+          switch (report) {
+            case Writable():
+              expect(
+                thrown,
+                isNot(isA<OutputShapeError>()),
+                reason:
+                    'canWriteAs said Writable for $label -> ${fmt.name}, '
+                    'but formatOutput raised OutputShapeError. The shape '
+                    'check and the writer disagree on whether this value '
+                    'is representable.',
+              );
+            case NotWritable():
+              expect(
+                thrown,
+                isA<OutputShapeError>(),
+                reason:
+                    'canWriteAs said NotWritable for $label -> '
+                    '${fmt.name}, but formatOutput did not raise '
+                    'OutputShapeError. A value the shape check rejects '
+                    'must not pass the writer silently.',
+              );
+          }
+        });
+      }
+    }
+  });
+
+  group('Writer never silently stringifies non-scalar CSV/TSV cells', () {
+    final offenders = <String, Object?>{
+      'list of maps with a list-valued cell': <Object?>[
+        {
+          'key': 'items',
+          'value': <Object?>[1, 2, 3],
+        },
+      ],
+      'list of maps with a map-valued cell': <Object?>[
+        {
+          'key': 'first',
+          'value': <String, Object?>{'nested': 'x'},
+        },
+      ],
+    };
+
+    for (final entry in offenders.entries) {
+      for (final fmt in [OutputFormat.csv, OutputFormat.tsv]) {
+        test('${entry.key} -> ${fmt.name} throws rather than stringifies', () {
+          expect(
+            () => formatOutput(entry.value, fmt),
+            throwsA(isA<QueryError>()),
+            reason:
+                'Writer must refuse rather than emit Dart toString() '
+                'garbage. This is the exact regression shipped in 0.7.1.',
+          );
+        });
+      }
+    }
+  });
+}

From a2d5a7c621d8ade8d61e482c12e555e44f17d983 Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 09:17:43 +0200
Subject: [PATCH 05/13] Explain: warn when filter/filter_values/filter_keys is
 provably empty
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

filter evaluates `evaluate(predicate, item) == true`. Strict equality
against `true` means that any predicate whose value is not a boolean
is silently rejected — the filter produces an empty list regardless
of input. Without static feedback, a typo like filter(.missing) or a
predicate that forgot its comparison (filter(.name) instead of
filter(.name == "Alice")) looks fine at parse time and silently
produces an empty result at runtime.

explain() now walks each stage before inferring it and flags two
patterns that can only produce an empty filter:

- Missing-field paths. filter(.missing) over an element shape that
  is a known SMap without `missing` — at runtime the field access
  returns null, which never equals true. The check walks Field /
  Access chains segment by segment, so .users | filter(.addr.nope)
  resolves the chain against the element's `addr` subshape.
- Non-boolean predicate shapes. If the inferred predicate shape is
  any concrete non-bool (SNum, SString, SList, SMap, SNull), the
  filter is provably empty. SBool and SAny are left alone: either
  might be true.

The same rules apply to filter_values (predicate sees element values
of the input map) and filter_keys (predicate sees keys, always
strings). sort_by / map / unique_by are intentionally out of scope —
they do not apply a `== true` test, so their predicates have
different correctness rules.

New ExplainWarning type is exported through lib/lambe.dart and
rendered by renderExplain between the stage table and the
writability summary. 12 new tests pin the warning on every affected
op and on both warning modes, and pin the absence of warnings on
valid predicates, SAny input, and non-filter ops. 1073 tests green,
analyzer clean, dart doc clean.
---
 lib/lambe.dart               |   2 +-
 lib/src/shape/explain.dart   | 138 +++++++++++++++++++++++++++++++++++
 test/shape_explain_test.dart | 115 +++++++++++++++++++++++++++++
 3 files changed, 254 insertions(+), 1 deletion(-)

diff --git a/lib/lambe.dart b/lib/lambe.dart
index 5dafbc3..e07503a 100644
--- a/lib/lambe.dart
+++ b/lib/lambe.dart
@@ -57,7 +57,7 @@ export 'src/shape/check.dart'
         canWriteAs,
         canWriteShapeAs;
 export 'src/shape/explain.dart'
-    show ExplainReport, ExplainStage, explain, renderExplain;
+    show ExplainReport, ExplainStage, ExplainWarning, explain, renderExplain;
 export 'src/shape/infer.dart' show inferShape;
 export 'src/shape/pipe_ops.dart'
     show
diff --git a/lib/src/shape/explain.dart b/lib/src/shape/explain.dart
index 78f2fa5..e1f9bd0 100644
--- a/lib/src/shape/explain.dart
+++ b/lib/src/shape/explain.dart
@@ -33,6 +33,27 @@ final class ExplainStage {
   const ExplainStage({required this.source, required this.shape});
 }
 
+/// A static-analysis warning attached to an explain report.
+///
+/// Warnings call out constructs that will evaluate to a trivial result
+/// regardless of input, such as a `filter` predicate whose inferred
+/// shape is not [SBool] — `filter` requires `== true`, so any non-bool
+/// predicate makes the filter always empty.
+///
+/// [stageIndex] points into [ExplainReport.stages] so a renderer can
+/// highlight the offending stage.
+final class ExplainWarning {
+  /// The stage this warning refers to, as an index into
+  /// [ExplainReport.stages].
+  final int stageIndex;
+
+  /// One-line human-readable message.
+  final String message;
+
+  /// Creates an [ExplainWarning].
+  const ExplainWarning({required this.stageIndex, required this.message});
+}
+
 /// A full explain report for a query.
 final class ExplainReport {
   /// The stages along the pipe backbone, in left-to-right order.
@@ -44,11 +65,16 @@ final class ExplainReport {
   /// The formats the final shape is *not* writable as.
   final List<OutputFormat> notWritableAs;
 
+  /// Static-analysis warnings attached to individual stages. Empty when
+  /// nothing was flagged.
+  final List<ExplainWarning> warnings;
+
   /// Creates an [ExplainReport].
   const ExplainReport({
     required this.stages,
     required this.writableAs,
     required this.notWritableAs,
+    this.warnings = const [],
   });
 }
 
@@ -57,9 +83,15 @@ final class ExplainReport {
 ExplainReport explain(LamExpr expr, Shape inputShape) {
   final backbone = _flattenPipe(expr);
   final stages = <ExplainStage>[];
+  final warnings = <ExplainWarning>[];
+  var prev = inputShape;
   var ctx = inputShape;
   for (var i = 0; i < backbone.length; i++) {
     final piece = backbone[i];
+    final warning = _analyzePredicate(piece, prev);
+    if (warning != null) {
+      warnings.add(ExplainWarning(stageIndex: i, message: warning));
+    }
     ctx = inferShape(piece, ctx);
     stages.add(
       ExplainStage(
@@ -67,6 +99,7 @@ ExplainReport explain(LamExpr expr, Shape inputShape) {
         shape: ctx,
       ),
     );
+    prev = ctx;
   }
 
   final writable = <OutputFormat>[];
@@ -83,9 +116,102 @@ ExplainReport explain(LamExpr expr, Shape inputShape) {
     stages: stages,
     writableAs: writable,
     notWritableAs: notWritable,
+    warnings: warnings,
   );
 }
 
+/// Detect predicate anti-patterns in parameterized ops.
+///
+/// `filter`, `filter_values`, and `filter_keys` all reject elements
+/// whose predicate does not evaluate to `== true`. Two patterns can
+/// prove the predicate will never return `true` and therefore the op
+/// will always be empty:
+///
+/// - The predicate references a field that doesn't exist on the
+///   known element shape (e.g. `filter(.missing)` when the element
+///   is `SMap<name, age>`). At runtime the field access yields
+///   `null`, which never equals `true`.
+/// - The predicate's inferred shape is a concrete non-boolean scalar
+///   (`SNum`, `SString`, `SList`, `SMap`, `SNull`). Even without an
+///   unknown-field match, a predicate that can only return, say, a
+///   number is always non-boolean, so `== true` never holds.
+///
+/// [SBool] and [SAny] are left alone: booleans might be true,
+/// unknowns might be true, neither is provably-empty.
+///
+/// Returns `null` when no warning applies.
+String? _analyzePredicate(LamExpr op, Shape inputShape) {
+  switch (op) {
+    case FilterOp(:final predicate):
+      final element = inputShape is SList ? inputShape.element : const SAny();
+      return _predicateWarning(predicate, element, 'filter');
+    case FilterValuesOp(:final predicate):
+      final value = switch (inputShape) {
+        SMap(:final fields) when fields.isNotEmpty => fields.values.reduce(
+          (a, b) => a == b ? a : const SAny(),
+        ),
+        _ => const SAny(),
+      };
+      return _predicateWarning(predicate, value, 'filter_values');
+    case FilterKeysOp(:final predicate):
+      return _predicateWarning(predicate, const SString(), 'filter_keys');
+    default:
+      return null;
+  }
+}
+
+String? _predicateWarning(LamExpr predicate, Shape context, String opName) {
+  final missing = _missingFieldPath(predicate, context);
+  if (missing != null) {
+    return 'predicate $missing does not exist on the element shape; '
+        '$opName will always be empty';
+  }
+  final predShape = inferShape(predicate, context);
+  if (predShape is SBool || predShape is SAny) return null;
+  return '$opName predicate has shape ${renderShape(predShape)}; '
+      '$opName requires a boolean, so this will always be empty';
+}
+
+/// Render `.a.b.c` if [expr] is a [Field]/[Access] chain whose root
+/// resolves to a known [SMap] missing a segment in the chain; otherwise
+/// `null`.
+///
+/// Walks left-to-right along a `Field`/`Access` spine, narrowing the
+/// context at each step. As soon as a step lands on a known map whose
+/// fields don't include the required name, returns the rendered path up
+/// to and including that missing segment. [SAny] anywhere along the
+/// path disables the check — unknown context means we cannot prove
+/// the field is missing.
+String? _missingFieldPath(LamExpr expr, Shape context) {
+  final segments = <String>[];
+  LamExpr cur = expr;
+  while (true) {
+    if (cur is Field) {
+      segments.insert(0, cur.name);
+      break;
+    }
+    if (cur is Access) {
+      segments.insert(0, cur.field);
+      cur = cur.target;
+      continue;
+    }
+    return null;
+  }
+
+  var ctx = context;
+  for (var i = 0; i < segments.length; i++) {
+    if (ctx is SAny) return null;
+    if (ctx is! SMap) return null;
+    final name = segments[i];
+    if (!ctx.fields.containsKey(name)) {
+      final path = segments.sublist(0, i + 1).join('.');
+      return '.$path';
+    }
+    ctx = ctx.fields[name]!;
+  }
+  return null;
+}
+
 /// Flatten a left-associative [Pipe] chain into a list of stages.
 ///
 /// `a | b | c` parses as `Pipe(Pipe(a, b), c)`. Walking the left spine
@@ -176,6 +302,18 @@ String renderExplain(ExplainReport report) {
     buf.write('\n');
   }
 
+  if (report.warnings.isNotEmpty) {
+    buf.write('\n');
+    for (final w in report.warnings) {
+      final source = report.stages[w.stageIndex].source.trimLeft();
+      buf.write('Warning: ');
+      buf.write(source);
+      buf.write('\n  ');
+      buf.write(w.message);
+      buf.write('\n');
+    }
+  }
+
   buf.write('\n');
   if (report.writableAs.isNotEmpty) {
     buf.write(
diff --git a/test/shape_explain_test.dart b/test/shape_explain_test.dart
index f14bdcf..6e5ca2c 100644
--- a/test/shape_explain_test.dart
+++ b/test/shape_explain_test.dart
@@ -145,4 +145,119 @@ void main() {
       expect(text, contains('toml'));
     });
   });
+
+  group('explain: predicate warnings for provably-empty filters', () {
+    const userListShape = SMap({
+      'users': SList(
+        SMap({'name': SString(), 'age': SNum(), 'active': SBool()}),
+      ),
+    });
+
+    test('filter(.missing) warns: field not in element shape', () {
+      final report = explain(
+        _parse('.users | filter(.missing)'),
+        userListShape,
+      );
+      expect(report.warnings, hasLength(1));
+      final w = report.warnings.first;
+      expect(w.stageIndex, 1);
+      expect(w.message, contains('.missing does not exist'));
+      expect(w.message, contains('filter will always be empty'));
+    });
+
+    test('filter(.name) warns: field exists but is not boolean', () {
+      final report = explain(_parse('.users | filter(.name)'), userListShape);
+      expect(report.warnings, hasLength(1));
+      expect(report.warnings.first.message, contains('shape string'));
+    });
+
+    test('filter(.active) does not warn: field is boolean', () {
+      final report = explain(_parse('.users | filter(.active)'), userListShape);
+      expect(report.warnings, isEmpty);
+    });
+
+    test('filter(.age > 25) does not warn: comparison yields bool', () {
+      final report = explain(
+        _parse('.users | filter(.age > 25)'),
+        userListShape,
+      );
+      expect(report.warnings, isEmpty);
+    });
+
+    test('filter(true) does not warn: literal bool', () {
+      final report = explain(_parse('.users | filter(true)'), userListShape);
+      expect(report.warnings, isEmpty);
+    });
+
+    test('filter on SAny input does not warn: cannot prove anything', () {
+      final report = explain(_parse('.users | filter(.missing)'), const SAny());
+      expect(report.warnings, isEmpty);
+    });
+
+    test('sort_by(.missing) does not warn: only filter* is gated this way', () {
+      final report = explain(
+        _parse('.users | sort_by(.missing)'),
+        userListShape,
+      );
+      expect(report.warnings, isEmpty);
+    });
+
+    test('filter_values warns when predicate is not bool', () {
+      final report = explain(
+        _parse('.deps | filter_values(.)'),
+        const SMap({
+          'deps': SMap({'a': SString(), 'b': SString()}),
+        }),
+      );
+      expect(report.warnings, hasLength(1));
+      expect(report.warnings.first.message, contains('filter_values'));
+    });
+
+    test('filter_keys warns: keys are strings, not bool', () {
+      final report = explain(
+        _parse('.deps | filter_keys(.)'),
+        const SMap({
+          'deps': SMap({'a': SString()}),
+        }),
+      );
+      expect(report.warnings, hasLength(1));
+      expect(report.warnings.first.message, contains('filter_keys'));
+    });
+
+    test('nested missing field .address.missing warns', () {
+      final report = explain(
+        _parse('.users | filter(.address.missing)'),
+        const SMap({
+          'users': SList(
+            SMap({
+              'address': SMap({'city': SString(), 'zip': SString()}),
+            }),
+          ),
+        }),
+      );
+      expect(report.warnings, hasLength(1));
+      expect(
+        report.warnings.first.message,
+        contains('.address.missing does not exist'),
+      );
+    });
+
+    test('renderExplain prints warnings between stages and writability', () {
+      final report = explain(
+        _parse('.users | filter(.missing)'),
+        userListShape,
+      );
+      final text = renderExplain(report);
+      expect(text, contains('Warning:'));
+      expect(text, contains('filter(.missing)'));
+      expect(text, contains('does not exist'));
+      expect(text, contains('Writable as:'));
+    });
+
+    test('no warnings: renderExplain contains no Warning: line', () {
+      final report = explain(_parse('.users | filter(.active)'), userListShape);
+      final text = renderExplain(report);
+      expect(text, isNot(contains('Warning:')));
+    });
+  });
 }

From 8131a38a9fb3a710bfd3a2b4073ff0eecef8ffab Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 11:16:30 +0200
Subject: [PATCH 06/13] Line-aware parse error diagnostics with caret and
 source context
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Parse errors now report `line:column` instead of just `column`, and
the source excerpt is a proper context block: the offending line
prefixed with its line number, the caret under the offending column,
and (for multi-line queries) one line of context on either side. The
gutter width adapts to the query's line count. A 1-line query still
produces the existing single-line excerpt with a gutter prefix.

Previously the renderer built one big block by concatenating the
caret line after the full expression, ignoring newlines. For any
multi-line query that placed the caret at column N of the final
visible line regardless of which line the error was actually on —
unusable for heredoc-authored queries or anything coming out of an
editor. `Location.line` was always available on Rumil's ParseError;
the old code just didn't read it.

The CLI's --explain path used to bail out with "Error: failed to
parse query", skipping the rich diagnostic that --to had access to.
It now goes through parseAst so both paths surface the same message.

Also drops the `QueryError: ` prefix-doubling in bin/lam.dart: three
callsites used `'Error: $e'` which invokes QueryError.toString and
added a second `QueryError:` on top of the CLI's `Error:` prefix.
Those now use `e.message`, matching the rest of the file.

Test matrix pins the renderer: single-line + multi-line, error-at-
line-1 / line-mid / line-last, gutter width scaling with line count,
and the did-you-mean hint for mistyped pipe ops. Also pins the
QueryError.message / toString contract so downstream callers know
which to use. 1081 tests green, analyzer clean, dart doc clean.
---
 bin/lam.dart                      |  20 +++---
 lib/lambe.dart                    |  58 ++++++++++++---
 test/parse_error_format_test.dart | 116 ++++++++++++++++++++++++++++++
 3 files changed, 172 insertions(+), 22 deletions(-)
 create mode 100644 test/parse_error_format_test.dart

diff --git a/bin/lam.dart b/bin/lam.dart
index 9f136cc..d9bee8e 100644
--- a/bin/lam.dart
+++ b/bin/lam.dart
@@ -10,9 +10,7 @@ import 'dart:io';
 
 import 'package:args/args.dart';
 import 'package:lambe/lambe.dart';
-import 'package:lambe/src/parser.dart' show parseQuery;
 import 'package:lambe/src/repl.dart' show runRepl;
-import 'package:rumil/rumil.dart' show Success, ParseError;
 
 void main(List<String> arguments) {
   final argParser =
@@ -149,7 +147,7 @@ void main(List<String> arguments) {
       stderr.writeln('Error: invalid ${format.name} input: ${e.message}');
       exit(1);
     } on QueryError catch (e) {
-      stderr.writeln('Error: $e');
+      stderr.writeln('Error: ${e.message}');
       exit(1);
     }
   }
@@ -177,13 +175,11 @@ void main(List<String> arguments) {
 
   // --explain mode: static shape trace, no execution
   if (isExplainMode) {
-    final parseResult = parseQuery(expression);
-    final ast = switch (parseResult) {
-      Success<ParseError, LamExpr>(:final value) => value,
-      _ => null,
-    };
-    if (ast == null) {
-      stderr.writeln('Error: failed to parse query');
+    final LamExpr ast;
+    try {
+      ast = parseAst(expression);
+    } on QueryError catch (e) {
+      stderr.writeln('Error: ${e.message}');
       exit(1);
     }
     final inputShape = data == null ? const SAny() : shapeOf(data);
@@ -199,14 +195,14 @@ void main(List<String> arguments) {
   try {
     queryAst = parseAst(expression);
   } on QueryError catch (e) {
-    stderr.writeln('Error: $e');
+    stderr.writeln('Error: ${e.message}');
     exit(1);
   }
   Object? result;
   try {
     result = evaluateAst(queryAst, data);
   } on QueryError catch (e) {
-    stderr.writeln('Error: $e');
+    stderr.writeln('Error: ${e.message}');
     exit(1);
   }
 
diff --git a/lib/lambe.dart b/lib/lambe.dart
index e07503a..85bf96d 100644
--- a/lib/lambe.dart
+++ b/lib/lambe.dart
@@ -199,6 +199,7 @@ String _formatParseErrors(String expression, List<ParseError> errors) {
     (a, b) => b.location.offset > a.location.offset ? b : a,
   );
   final offset = deepest.location.offset;
+  final line = deepest.location.line;
   final col = deepest.location.column;
 
   final expected = <String>{};
@@ -211,14 +212,14 @@ String _formatParseErrors(String expression, List<ParseError> errors) {
         expected.add(eoi.expected);
       case final CustomError c:
         if (c.message == 'Expected end of input') {
-          return 'parse error at column $col: '
-              '${_describeLeftover(expression, offset)}\n'
-              '  $expression\n'
-              '  ${' ' * (col - 1)}^';
+          return _renderParseError(
+            expression,
+            line,
+            col,
+            _describeLeftover(expression, offset),
+          );
         }
-        return 'parse error at column $col: ${c.message}\n'
-            '  $expression\n'
-            '  ${' ' * (col - 1)}^';
+        return _renderParseError(expression, line, col, c.message);
     }
   }
 
@@ -226,10 +227,47 @@ String _formatParseErrors(String expression, List<ParseError> errors) {
       expected.isEmpty
           ? 'unexpected input'
           : 'expected ${_joinExpected(expected)}';
+  return _renderParseError(expression, line, col, what);
+}
+
+/// Render a parse-error message with a line-aware source excerpt and
+/// caret.
+///
+/// Single-line expressions produce a jq-style three-line block: the
+/// `parse error` header, the source indented by two spaces, and a
+/// caret under column [col]. Multi-line expressions extend this with
+/// the previous line (if any) and the next line (if any), to give a
+/// reader enough context to locate the error without reprinting the
+/// full query. Line numbers are prefixed to every context line so the
+/// offending line stays unambiguous.
+String _renderParseError(String expression, int line, int col, String message) {
+  final lines = _splitLines(expression);
+  final idx = line - 1;
+  final gutterWidth = '${lines.length}'.length;
+  final buf = StringBuffer('parse error at line $line, column $col: $message');
 
-  return 'parse error at column $col: $what\n'
-      '  $expression\n'
-      '  ${' ' * (col - 1)}^';
+  String prefix(int lineNo) => '  ${'$lineNo'.padLeft(gutterWidth)} | ';
+
+  if (idx - 1 >= 0) {
+    buf.write('\n${prefix(line - 1)}${lines[idx - 1]}');
+  }
+  buf.write('\n${prefix(line)}${lines[idx]}');
+  buf.write('\n${' ' * prefix(line).length}${' ' * (col - 1)}^');
+  if (idx + 1 < lines.length) {
+    buf.write('\n${prefix(line + 1)}${lines[idx + 1]}');
+  }
+  return buf.toString();
+}
+
+/// Split [source] into lines without trailing newline characters.
+///
+/// Handles `\n`, `\r\n`, and a trailing newline. Returns `['']` for an
+/// empty source so callers can safely index.
+List<String> _splitLines(String source) {
+  if (source.isEmpty) return const [''];
+  final lines = source.split(RegExp(r'\r?\n'));
+  if (lines.isNotEmpty && lines.last.isEmpty) lines.removeLast();
+  return lines.isEmpty ? const [''] : lines;
 }
 
 String _describeLeftover(String expression, int offset) {
diff --git a/test/parse_error_format_test.dart b/test/parse_error_format_test.dart
new file mode 100644
index 0000000..413ad75
--- /dev/null
+++ b/test/parse_error_format_test.dart
@@ -0,0 +1,116 @@
+/// Tests for the line-aware parse-error renderer.
+///
+/// A query with a typo or dangling pipe should produce a jq-style
+/// excerpt: the error header with `line:column`, the offending line
+/// with a gutter-prefixed line number, a caret under the offending
+/// column, and — for multi-line queries — one line of context on
+/// either side so the reader can orient. The existing "did you mean"
+/// hint for mistyped pipe ops continues to work.
+///
+/// QueryError.message is the clean rendered text; callers should print
+/// `e.message` rather than `$e`, because `$e` prepends `QueryError: `
+/// and doubles the prefix the CLI adds.
+library;
+
+import 'package:lambe/lambe.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('parseAst: single-line errors', () {
+    test('mistyped pipe op emits a did-you-mean hint', () {
+      try {
+        parseAst('.users | filtre(.age)');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, contains('line 1, column 8'));
+        expect(e.message, contains('unknown operation "filtre"'));
+        expect(e.message, contains('did you mean "filter"?'));
+        expect(e.message, contains('  1 | .users | filtre(.age)'));
+        expect(e.message, contains('\n             ^'));
+      }
+    });
+
+    test('trailing pipe points at the pipe column', () {
+      try {
+        parseAst('.users |');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, contains('line 1, column 8'));
+        expect(e.message, contains('unexpected | at end of expression'));
+        expect(e.message, contains('  1 | .users |'));
+      }
+    });
+
+    test('mid-expression leftover lands the caret at the token', () {
+      try {
+        parseAst('.foo bar');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, contains('line 1, column 6'));
+        expect(e.message, contains('unexpected "bar"'));
+        expect(e.message, contains('  1 | .foo bar'));
+      }
+    });
+  });
+
+  group('parseAst: multi-line errors', () {
+    test('error on line 2 shows line 1 as context', () {
+      try {
+        parseAst('.users\n| filtre(.age)');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, contains('line 2, column 1'));
+        expect(e.message, contains('did you mean "filter"?'));
+        expect(e.message, contains('  1 | .users'));
+        expect(e.message, contains('  2 | | filtre(.age)'));
+      }
+    });
+
+    test('error on line 3 shows line 2 as context but not line 1', () {
+      try {
+        parseAst('.users\n| map(.name)\n| filtre(.)');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, contains('line 3, column 1'));
+        expect(e.message, contains('  2 | | map(.name)'));
+        expect(e.message, contains('  3 | | filtre(.)'));
+        expect(e.message, isNot(contains('  1 | .users')));
+      }
+    });
+
+    test('error on line 1 of a multi-line query shows line 2 below', () {
+      try {
+        parseAst('.foo bar\n| map(.name)');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, contains('line 1, column 6'));
+        expect(e.message, contains('  1 | .foo bar'));
+        expect(e.message, contains('  2 | | map(.name)'));
+      }
+    });
+
+    test('gutter width grows with total line count', () {
+      final prefix = List<String>.filled(10, '.').join('\n| ');
+      try {
+        parseAst('$prefix\n| filtre(.)');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, contains('line 11, column 1'));
+        expect(e.message, contains(' 10 | | .'));
+        expect(e.message, contains(' 11 | | filtre(.)'));
+      }
+    });
+  });
+
+  group('QueryError.message vs toString', () {
+    test('message is prefix-free, toString adds QueryError:', () {
+      try {
+        parseAst('.foo bar');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, startsWith('parse error at '));
+        expect(e.toString(), startsWith('QueryError: parse error at '));
+      }
+    });
+  });
+}

From 50e2049f05ee010d98fe776ca1055a2ff81628e8 Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 12:51:06 +0200
Subject: [PATCH 07/13] Review pass: docstring, wording, and error-message
 polish

First review pass on the 0.8.0 work surfaced seven issues. None of
them affect behavior the tests already pin, but they affect what a
reader sees when they open the public API or hit an error.

- formatOutput's docstring in lib/src/output.dart still said CSV/TSV
  accepts "a list of maps or list of lists" with no mention of the
  scalar-cell constraint. Now describes the three accepted element
  shapes and names both error paths (OutputShapeError from the shape
  check, QueryError from the defensive writer guard).
- _scalarCell's error message used cell.runtimeType, so a user saw
  "got _GrowableList" instead of "got list". Now maps List/Map to
  "list"/"map" up front and only falls back to runtimeType for the
  unreachable else branch.
- _predicateWarning hard-coded "element shape" for all three ops.
  For filter_values the predicate sees a value, for filter_keys it
  sees a key. Now takes the domain name as an argument so each op
  reads naturally.
- Two test files had stale docstrings: one referenced a
  runQueryAsString API that never existed (draft rot), one claimed
  "remediation" is offered for the non-scalar-cell case (the handover
  deliberately chose not to emit one). Both corrected.
- Leftover inline comment in csv_element_shape_test.dart removed.
- Attribution fix in shape_output_consistency_test.dart: the silent-
  stringification bug predates 0.7.1 by two releases, not "shipped
  in 0.7.1".

Two new tests pin the polish: the new descriptive cell-kind message,
and the value-domain wording for filter_values warnings. 1083 tests
green, analyzer clean, dart doc clean, pana 160/160.
---
 lib/src/output.dart                     | 15 +++++++++++--
 lib/src/shape/explain.dart              | 20 ++++++++++++-----
 test/csv_element_shape_test.dart        | 30 ++++++++++++++++++++-----
 test/shape_explain_test.dart            | 15 +++++++++++++
 test/shape_output_consistency_test.dart |  2 +-
 5 files changed, 68 insertions(+), 14 deletions(-)

diff --git a/lib/src/output.dart b/lib/src/output.dart
index 503a90f..b6b111e 100644
--- a/lib/src/output.dart
+++ b/lib/src/output.dart
@@ -16,7 +16,12 @@ export 'output_format.dart' show OutputFormat;
 /// For JSON, uses pretty-printing with 2-space indent by default.
 /// For YAML, uses block style.
 /// For TOML/HCL, requires the root value to be a `Map<String, Object?>`.
-/// For CSV/TSV, requires a list of maps (uses keys as headers) or list of lists.
+/// For CSV/TSV, requires a list of maps (uses keys as headers), a list of
+/// lists, or a list of scalars. Every cell must be a scalar — null,
+/// bool, num, or string. List-of-maps or list-of-lists with non-scalar
+/// cells throws [OutputShapeError]; a non-scalar cell that slips past
+/// shape inference (for example via [SAny]) throws [QueryError] at
+/// serialization time.
 String formatOutput(Object? value, OutputFormat format, {bool pretty = true}) =>
     switch (format) {
       OutputFormat.json =>
@@ -120,10 +125,16 @@ String _scalarCell(Object? cell, OutputFormat fmt) {
   if (cell is num || cell is bool || cell is String) return '$cell';
   throw QueryError(
     '${fmt.name.toUpperCase()} cell must be a scalar, '
-    'got ${cell.runtimeType}.',
+    'got ${_describeCellKind(cell)}.',
   );
 }
 
+String _describeCellKind(Object cell) {
+  if (cell is List) return 'list';
+  if (cell is Map) return 'map';
+  return cell.runtimeType.toString();
+}
+
 String _toHcl(Object? value) {
   final report = canWriteAs(value, OutputFormat.hcl);
   if (report is NotWritable) throw OutputShapeError(report);
diff --git a/lib/src/shape/explain.dart b/lib/src/shape/explain.dart
index e1f9bd0..973751d 100644
--- a/lib/src/shape/explain.dart
+++ b/lib/src/shape/explain.dart
@@ -144,7 +144,7 @@ String? _analyzePredicate(LamExpr op, Shape inputShape) {
   switch (op) {
     case FilterOp(:final predicate):
       final element = inputShape is SList ? inputShape.element : const SAny();
-      return _predicateWarning(predicate, element, 'filter');
+      return _predicateWarning(predicate, element, 'filter', 'element');
     case FilterValuesOp(:final predicate):
       final value = switch (inputShape) {
         SMap(:final fields) when fields.isNotEmpty => fields.values.reduce(
@@ -152,18 +152,28 @@ String? _analyzePredicate(LamExpr op, Shape inputShape) {
         ),
         _ => const SAny(),
       };
-      return _predicateWarning(predicate, value, 'filter_values');
+      return _predicateWarning(predicate, value, 'filter_values', 'value');
     case FilterKeysOp(:final predicate):
-      return _predicateWarning(predicate, const SString(), 'filter_keys');
+      return _predicateWarning(
+        predicate,
+        const SString(),
+        'filter_keys',
+        'key',
+      );
     default:
       return null;
   }
 }
 
-String? _predicateWarning(LamExpr predicate, Shape context, String opName) {
+String? _predicateWarning(
+  LamExpr predicate,
+  Shape context,
+  String opName,
+  String domain,
+) {
   final missing = _missingFieldPath(predicate, context);
   if (missing != null) {
-    return 'predicate $missing does not exist on the element shape; '
+    return 'predicate $missing does not exist on the $domain shape; '
         '$opName will always be empty';
   }
   final predShape = inferShape(predicate, context);
diff --git a/test/csv_element_shape_test.dart b/test/csv_element_shape_test.dart
index 05baed1..88ea2c7 100644
--- a/test/csv_element_shape_test.dart
+++ b/test/csv_element_shape_test.dart
@@ -10,13 +10,14 @@
 /// The tests fall in two layers:
 ///
 /// 1. Direct `formatOutput` calls on crafted values: a list of maps with a
-///    list-valued cell, or a nested-list cell. Must throw
-///    [OutputShapeError] rather than produce a row with a stringified
+///    list-valued cell, or a nested-list cell. Must throw a [QueryError]
+///    (either [OutputShapeError] from the shape check, or the defensive
+///    writer-level guard) rather than produce a row with a stringified
 ///    Dart `toString()` cell.
-/// 2. End-to-end `runQuery` on the real reproduction pipeline. The chain
+/// 2. End-to-end `query` on the real reproduction pipeline. The chain
 ///    must either succeed with scalar-only cells or raise
-///    [OutputShapeError] pointing at a real remediation. It must not
-///    silently emit the `[{key: ..., value: ...}]` garbage cell.
+///    [OutputShapeError]. It must not silently emit the
+///    `[{key: ..., value: ...}]` garbage cell.
 library;
 
 import 'package:lambe/lambe.dart';
@@ -95,7 +96,7 @@ void main() {
           reason: 'silent Dart toString() garbage leaked into output',
         );
       } on OutputShapeError {
-        // Accepted: the shape checker caught the mismatch.
+        return;
       }
     });
   });
@@ -127,4 +128,21 @@ void main() {
       expect(formatOutput(<Object?>[], OutputFormat.csv), isEmpty);
     });
   });
+
+  group('Defensive writer guard uses descriptive type names', () {
+    test('list cell fires _scalarCell with "list" in the message', () {
+      final heteroRows = <Object?>[
+        'scalar',
+        <Object?>[1, 2],
+      ];
+      try {
+        formatOutput(heteroRows, OutputFormat.csv);
+        fail('expected QueryError');
+      } on QueryError catch (e) {
+        expect(e.message, contains('cell must be a scalar'));
+        expect(e.message, contains('list'));
+        expect(e.message, isNot(contains('GrowableList')));
+      }
+    });
+  });
 }
diff --git a/test/shape_explain_test.dart b/test/shape_explain_test.dart
index 6e5ca2c..0db2f66 100644
--- a/test/shape_explain_test.dart
+++ b/test/shape_explain_test.dart
@@ -162,6 +162,7 @@ void main() {
       final w = report.warnings.first;
       expect(w.stageIndex, 1);
       expect(w.message, contains('.missing does not exist'));
+      expect(w.message, contains('element shape'));
       expect(w.message, contains('filter will always be empty'));
     });
 
@@ -213,6 +214,20 @@ void main() {
       expect(report.warnings.first.message, contains('filter_values'));
     });
 
+    test('filter_values missing-field warning names the value domain', () {
+      final report = explain(
+        _parse('.deps | filter_values(.missing)'),
+        const SMap({
+          'deps': SMap({
+            'a': SMap({'known': SBool()}),
+            'b': SMap({'known': SBool()}),
+          }),
+        }),
+      );
+      expect(report.warnings, hasLength(1));
+      expect(report.warnings.first.message, contains('value shape'));
+    });
+
     test('filter_keys warns: keys are strings, not bool', () {
       final report = explain(
         _parse('.deps | filter_keys(.)'),
diff --git a/test/shape_output_consistency_test.dart b/test/shape_output_consistency_test.dart
index bff7342..bf677d7 100644
--- a/test/shape_output_consistency_test.dart
+++ b/test/shape_output_consistency_test.dart
@@ -123,7 +123,7 @@ void main() {
             throwsA(isA<QueryError>()),
             reason:
                 'Writer must refuse rather than emit Dart toString() '
-                'garbage. This is the exact regression shipped in 0.7.1.',
+                'garbage. This is the pre-0.8.0 bug this release closes.',
           );
         });
       }

From 2eb5e0dd3709118babb98456c1b1c461cfafa46e Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 12:52:20 +0200
Subject: [PATCH 08/13] Pass 2: strengthen the weakest test assertions

Two gaps surfaced on the second review pass. Neither indicates a real
bug, but both described behavior more loosely than the tests in the
rest of the file.

- The renderExplain ordering test asserted that Warning and Writable
  lines both appear in the output but said nothing about their
  position. "Between stages and writability" was only the test name,
  not what was pinned. Now compares indexOf values so the stage row,
  the warning block, and the Writable line are pinned in that order.
- The parse-error renderer handles \r\n line endings (regex split on
  \r?\n), but no test exercised that path. Added a direct
  Windows-line-ending case that also pins the CR character does not
  leak into the excerpt.
---
 test/parse_error_format_test.dart | 12 ++++++++++++
 test/shape_explain_test.dart      |  7 +++++++
 2 files changed, 19 insertions(+)

diff --git a/test/parse_error_format_test.dart b/test/parse_error_format_test.dart
index 413ad75..c68aaee 100644
--- a/test/parse_error_format_test.dart
+++ b/test/parse_error_format_test.dart
@@ -100,6 +100,18 @@ void main() {
         expect(e.message, contains(' 11 | | filtre(.)'));
       }
     });
+
+    test('Windows-style \\r\\n line endings split correctly', () {
+      try {
+        parseAst('.users\r\n| filtre(.age)');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, contains('line 2, column 1'));
+        expect(e.message, contains('  1 | .users'));
+        expect(e.message, contains('  2 | | filtre(.age)'));
+        expect(e.message, isNot(contains('\r')));
+      }
+    });
   });
 
   group('QueryError.message vs toString', () {
diff --git a/test/shape_explain_test.dart b/test/shape_explain_test.dart
index 0db2f66..eb31071 100644
--- a/test/shape_explain_test.dart
+++ b/test/shape_explain_test.dart
@@ -267,6 +267,13 @@ void main() {
       expect(text, contains('filter(.missing)'));
       expect(text, contains('does not exist'));
       expect(text, contains('Writable as:'));
+
+      final warningIdx = text.indexOf('Warning:');
+      final writableIdx = text.indexOf('Writable as:');
+      final stageIdx = text.indexOf(': list<');
+      expect(stageIdx, isNonNegative);
+      expect(stageIdx, lessThan(warningIdx));
+      expect(warningIdx, lessThan(writableIdx));
     });
 
     test('no warnings: renderExplain contains no Warning: line', () {

From 17a0d59d02459bf0ae7e3fcc0f5f8bae98dd8257 Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 13:16:45 +0200
Subject: [PATCH 09/13] Pass 3: MCP error prefix-doubling, MustBeList docstring
 accuracy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Third review pass turned up one real user-facing bug and one doc
inaccuracy. Both surface-level, both pinned by existing tests now
that the code is correct.

bin/mcp_server.dart had three `Error: $e` callsites that invoked
QueryError.toString(), producing `Error: QueryError: parse error at
line ...` — the same prefix-doubling the CLI avoided. MCP callers
(typically LLM agents) would see the `QueryError:` token as part of
the human-readable error, which is noise for agents that already
know the error came from the query tool. Now uses `e.message`
consistently with bin/lam.dart.

MustBeList's docstring still claimed it was "used where downstream
code handles arbitrary element shapes", but after 0.8.0 there is no
such downstream code — csv/tsv use the stricter MustBeFlatList, and
no other consumer exists. Rewritten to describe the class honestly:
the generic list-root requirement, retained for future format
additions whose serialization tolerates any element shape.
---
 bin/mcp_server.dart      |  6 +++---
 lib/src/shape/check.dart | 10 ++++++----
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/bin/mcp_server.dart b/bin/mcp_server.dart
index c564357..df2d91c 100644
--- a/bin/mcp_server.dart
+++ b/bin/mcp_server.dart
@@ -199,7 +199,7 @@ base class LambeServer extends MCPServer with ToolsSupport {
       );
     } on QueryError catch (e) {
       return CallToolResult(
-        content: [TextContent(text: 'Error: $e')],
+        content: [TextContent(text: 'Error: ${e.message}')],
         isError: true,
       );
     } on FormatException catch (e) {
@@ -278,7 +278,7 @@ base class LambeServer extends MCPServer with ToolsSupport {
       );
     } on QueryError catch (e) {
       return CallToolResult(
-        content: [TextContent(text: 'Error: $e')],
+        content: [TextContent(text: 'Error: ${e.message}')],
         isError: true,
       );
     }
@@ -336,7 +336,7 @@ base class LambeServer extends MCPServer with ToolsSupport {
       }
     } on QueryError catch (e) {
       return CallToolResult(
-        content: [TextContent(text: 'Error: $e')],
+        content: [TextContent(text: 'Error: ${e.message}')],
         isError: true,
       );
     }
diff --git a/lib/src/shape/check.dart b/lib/src/shape/check.dart
index 4650839..136b67c 100644
--- a/lib/src/shape/check.dart
+++ b/lib/src/shape/check.dart
@@ -62,11 +62,13 @@ final class MustBeMap extends ShapeRequirement {
   String describe() => 'a map';
 }
 
-/// Requires a list at the root.
+/// Requires a list at the root, with no constraint on element shape.
 ///
-/// Permissive: accepts any [SList] regardless of element shape, plus
-/// [SAny]. Used where downstream code handles arbitrary element shapes,
-/// or where stricter checks are unnecessary.
+/// Accepts any [SList], plus [SAny] for unknown shapes. Retained as the
+/// generic list-root requirement so future format additions that tolerate
+/// any element shape can reuse it; CSV and TSV now use the stricter
+/// [MustBeFlatList] because their element shapes must serialize to a
+/// single text cell.
 final class MustBeList extends ShapeRequirement {
   /// Creates a [MustBeList] requirement.
   const MustBeList();

From bdea6bbffef42830f412fd13f99d7281e85a6654 Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 13:24:35 +0200
Subject: [PATCH 10/13] CSV/TSV: union headers across heterogeneous-keyed rows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The writer took headers from the first row only, so
[{a: 1}, {b: 2}] produced "a\n1\n" — the b column was silently
dropped and row 2 rendered as an empty line. Pre-existed 0.8.0 but
belongs to the same class as the non-scalar-cell bug we just
fixed: the writer producing something other than what the input
structurally carries. Leaving it unfixed would have forced a 0.8.1
within weeks of the release.

_toCsv now unions keys across all rows in first-seen insertion
order. Each row renders a cell per header, with empty string when
the row doesn't have that key. Matches pandas.DataFrame.to_csv and
Python's csv.DictWriter(extrasaction='ignore') semantics:
presentation is lossless for scalar-celled data regardless of
whether every row carries every key.

Null values and absent keys both render as empty cells. This
intentional — the CSV format has no distinct "null" token, so the
distinction can't be preserved round-trip anyway. Callers that
need the distinction should use JSON.

Two rows added to shape_output_consistency_test.dart
(disjoint-keys, overlapping-keys) so the matrix covers the new
behavior. Seven new cases in csv_element_shape_test.dart pin the
behavior directly, including a regression guard for the
homogeneous case. 1102 tests green, analyzer clean, pana 160/160.
---
 lib/src/output.dart                     | 37 ++++++++++---
 test/csv_element_shape_test.dart        | 72 +++++++++++++++++++++++++
 test/shape_output_consistency_test.dart |  8 +++
 3 files changed, 110 insertions(+), 7 deletions(-)

diff --git a/lib/src/output.dart b/lib/src/output.dart
index b6b111e..e4547c8 100644
--- a/lib/src/output.dart
+++ b/lib/src/output.dart
@@ -16,11 +16,13 @@ export 'output_format.dart' show OutputFormat;
 /// For JSON, uses pretty-printing with 2-space indent by default.
 /// For YAML, uses block style.
 /// For TOML/HCL, requires the root value to be a `Map<String, Object?>`.
-/// For CSV/TSV, requires a list of maps (uses keys as headers), a list of
-/// lists, or a list of scalars. Every cell must be a scalar — null,
-/// bool, num, or string. List-of-maps or list-of-lists with non-scalar
-/// cells throws [OutputShapeError]; a non-scalar cell that slips past
-/// shape inference (for example via [SAny]) throws [QueryError] at
+/// For CSV/TSV, requires a list of maps, a list of lists, or a list of
+/// scalars. For a list of maps, headers are the union of keys across
+/// all rows in first-seen order; a row missing a key renders as an
+/// empty cell. Every cell value must be a scalar — null, bool, num,
+/// or string. List-of-maps or list-of-lists with non-scalar cells
+/// throws [OutputShapeError]; a non-scalar cell that slips past shape
+/// inference (for example via [SAny]) throws [QueryError] at
 /// serialization time.
 String formatOutput(Object? value, OutputFormat format, {bool pretty = true}) =>
     switch (format) {
@@ -89,10 +91,13 @@ String _toCsv(Object? value, String delimiter) {
 
   if (list.first is Map<String, Object?>) {
     final maps = list.cast<Map<String, Object?>>();
-    final headers = maps.first.keys.toList();
+    final headers = _unionHeaders(maps);
     final rows = [
       for (final map in maps)
-        [for (final h in headers) _scalarCell(map[h], fmt)],
+        [
+          for (final h in headers)
+            map.containsKey(h) ? _scalarCell(map[h], fmt) : '',
+        ],
     ];
     return serializeCsvWithHeaders(headers, rows, config: config);
   }
@@ -135,6 +140,24 @@ String _describeCellKind(Object cell) {
   return cell.runtimeType.toString();
 }
 
+/// Collect the union of keys across [maps] preserving first-seen order.
+///
+/// The first map's keys appear first in their insertion order; each
+/// subsequent map contributes any keys not already present, in the
+/// order they first appear. Rows missing a key render as an empty cell
+/// rather than silently dropping the column — symmetric with how the
+/// writer refuses non-scalar cells elsewhere.
+List<String> _unionHeaders(List<Map<String, Object?>> maps) {
+  final seen = <String>{};
+  final headers = <String>[];
+  for (final map in maps) {
+    for (final key in map.keys) {
+      if (seen.add(key)) headers.add(key);
+    }
+  }
+  return headers;
+}
+
 String _toHcl(Object? value) {
   final report = canWriteAs(value, OutputFormat.hcl);
   if (report is NotWritable) throw OutputShapeError(report);
diff --git a/test/csv_element_shape_test.dart b/test/csv_element_shape_test.dart
index 88ea2c7..99bc75a 100644
--- a/test/csv_element_shape_test.dart
+++ b/test/csv_element_shape_test.dart
@@ -145,4 +145,76 @@ void main() {
       }
     });
   });
+
+  group('CSV/TSV preserve every column across heterogeneous-keyed rows', () {
+    test('disjoint keys: both columns appear, rows fill with empties', () {
+      final v = <Object?>[
+        {'a': 1},
+        {'b': 2},
+      ];
+      final out = formatOutput(v, OutputFormat.csv);
+      expect(out, contains('a,b'));
+      expect(out, contains('1,'));
+      expect(out, contains(',2'));
+    });
+
+    test('overlapping keys: union in first-seen order', () {
+      final v = <Object?>[
+        {'a': 1, 'b': 2},
+        {'b': 3, 'c': 4},
+      ];
+      final out = formatOutput(v, OutputFormat.csv);
+      expect(out.split(RegExp(r'\r?\n')).first, 'a,b,c');
+    });
+
+    test('row missing a key renders as empty, not a dropped cell', () {
+      final v = <Object?>[
+        {'a': 1, 'b': 2},
+        {'a': 3},
+      ];
+      final out = formatOutput(v, OutputFormat.csv);
+      final lines = out.split(RegExp(r'\r?\n'));
+      expect(lines[0], 'a,b');
+      expect(lines[1], '1,2');
+      expect(lines[2], '3,');
+    });
+
+    test('homogeneous list-of-maps output unchanged by the union pass', () {
+      final v = <Object?>[
+        {'a': 1, 'b': 2},
+        {'a': 3, 'b': 4},
+      ];
+      final out = formatOutput(v, OutputFormat.csv);
+      final lines = out.split(RegExp(r'\r?\n'));
+      expect(lines[0], 'a,b');
+      expect(lines[1], '1,2');
+      expect(lines[2], '3,4');
+    });
+
+    test(
+      'null value and absent key both render as empty, indistinguishable',
+      () {
+        final nullValue = <Object?>[
+          {'a': 1, 'b': null},
+        ];
+        final absentKey = <Object?>[
+          {'a': 1, 'b': 2},
+          {'a': 3},
+        ];
+        final nullOut = formatOutput(nullValue, OutputFormat.csv);
+        final absentOut = formatOutput(absentKey, OutputFormat.csv);
+        expect(nullOut.split(RegExp(r'\r?\n'))[1], '1,');
+        expect(absentOut.split(RegExp(r'\r?\n'))[2], '3,');
+      },
+    );
+
+    test('tsv also gets the union-headers treatment', () {
+      final v = <Object?>[
+        {'a': 1},
+        {'b': 2},
+      ];
+      final out = formatOutput(v, OutputFormat.tsv);
+      expect(out.split(RegExp(r'\r?\n')).first, 'a\tb');
+    });
+  });
 }
diff --git a/test/shape_output_consistency_test.dart b/test/shape_output_consistency_test.dart
index bf677d7..593cc65 100644
--- a/test/shape_output_consistency_test.dart
+++ b/test/shape_output_consistency_test.dart
@@ -47,6 +47,14 @@ final _representatives = <String, Object?>{
     <Object?>[1, 2, 3],
     <Object?>[4, 5, 6],
   ],
+  'list of maps with disjoint scalar keys': <Object?>[
+    {'a': 1},
+    {'b': 2},
+  ],
+  'list of maps with overlapping but non-identical scalar keys': <Object?>[
+    {'a': 1, 'b': 2},
+    {'b': 3, 'c': 4},
+  ],
   'empty map': <String, Object?>{},
   'map of scalars': <String, Object?>{'a': 1, 'b': 'x'},
   'map with a list field': <String, Object?>{

From ed6c9ff871efeec97594a3a010c092c5eb620881 Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 13:25:39 +0200
Subject: [PATCH 11/13] Parse errors: actionable message on empty expression
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Running \`lam '' file.json\` surfaced the parser's full list of
expected tokens — every pipe-op name plus 14 punctuation entries,
roughly 30 items — and buried the actual problem (the query is
empty) under the noise. Pre-existed 0.8.0 but became more visible
once the parse-error renderer got the rest of its jq-style
treatment in this release.

_formatParseErrors now short-circuits on expression.trim().isEmpty
with a single line: \`parse error: expression is empty\`. No
expected-list, no line/column (neither meaningful for an empty
input), no caret.

Three tests pin the shape for genuinely-empty, whitespace-only,
and newline-only input. 1105 tests green.
---
 lib/lambe.dart                    |  4 ++++
 test/parse_error_format_test.dart | 31 +++++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/lib/lambe.dart b/lib/lambe.dart
index 85bf96d..f9eaf35 100644
--- a/lib/lambe.dart
+++ b/lib/lambe.dart
@@ -195,6 +195,10 @@ Object? _normalize(Object? value) {
 String _formatParseErrors(String expression, List<ParseError> errors) {
   if (errors.isEmpty) return 'parse error';
 
+  if (expression.trim().isEmpty) {
+    return 'parse error: expression is empty';
+  }
+
   final deepest = errors.reduce(
     (a, b) => b.location.offset > a.location.offset ? b : a,
   );
diff --git a/test/parse_error_format_test.dart b/test/parse_error_format_test.dart
index c68aaee..99cc5c2 100644
--- a/test/parse_error_format_test.dart
+++ b/test/parse_error_format_test.dart
@@ -114,6 +114,37 @@ void main() {
     });
   });
 
+  group('parseAst: empty input is actionable', () {
+    test('empty expression returns a one-liner, not a 30-token list', () {
+      try {
+        parseAst('');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, 'parse error: expression is empty');
+        expect(e.message, isNot(contains('expected')));
+        expect(e.message, isNot(contains('filter')));
+      }
+    });
+
+    test('whitespace-only expression treated as empty', () {
+      try {
+        parseAst('   ');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, 'parse error: expression is empty');
+      }
+    });
+
+    test('newline-only expression treated as empty', () {
+      try {
+        parseAst('\n\n');
+        fail('expected parse to fail');
+      } on QueryError catch (e) {
+        expect(e.message, 'parse error: expression is empty');
+      }
+    });
+  });
+
   group('QueryError.message vs toString', () {
     test('message is prefix-free, toString adds QueryError:', () {
       try {

From 5106b56f1070bdb7fd2a177216bfa275313d0aaf Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 15:07:32 +0200
Subject: [PATCH 12/13] Lambe 0.8.0: release prep
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- pubspec: 0.7.1 → 0.8.0
- _version.dart regenerated via tool/gen_version.dart
- doc/lam.1.md front matter: "Lambë 0.7.1" → "0.8.0",
  "April 2026" → "May 2026"; lam.1 regenerated via tool/manpage.dart
- README / doc/getting-started REPL banner bumped to v0.8.0
- manpage_test.dart: TH date check updated to "May 2026"
- CHANGELOG: new 0.8.0 entry with Added / Changed / Breaking sections
- ROADMAP: 0.8.0 marked shipped; 0.9.0 candidates refreshed with the
  new classes surfaced during the 0.8.0 review passes (runtime-failure
  warnings, CSV cell-flattening policy)

.pubignore added to keep the pub archive focused. Previously the
archive shipped a 7MB stale x86_64 AOT of lam-mcp from an April
developer build, plus any locally-generated doc/api/ HTML and any
benchmark artifacts lying around. None of that reaches users:
`dart pub global activate lambe` compiles the MCP server from source
via Dart VM snapshots, and per-platform lam-mcp binaries are built
in CI on tag push (see .github/workflows/release.yml) and published
as GitHub release assets referenced by SHA256 in the MCP registry.
Dropping the stale binary takes the archive from 3 MB to 133 KB.

1105 tests green, analyzer clean, dart doc clean, pana 160/160,
dart pub publish --dry-run clean (bar the uncommitted-changes
warning, which this commit resolves).
---
 .pubignore             |   9 ++++
 CHANGELOG.md           | 104 +++++++++++++++++++++++++++++++++++++++++
 README.md              |   2 +-
 ROADMAP.md             |  18 ++++---
 doc/getting-started.md |   2 +-
 doc/lam.1              |   2 +-
 doc/lam.1.md           |   4 +-
 lib/src/_version.dart  |   2 +-
 pubspec.yaml           |   2 +-
 test/manpage_test.dart |   2 +-
 10 files changed, 132 insertions(+), 15 deletions(-)
 create mode 100644 .pubignore

diff --git a/.pubignore b/.pubignore
new file mode 100644
index 0000000..461fd30
--- /dev/null
+++ b/.pubignore
@@ -0,0 +1,9 @@
+HANDOVER_*.md
+bench-results-*.json
+tool/bench/
+doc/api/
+# Stale local AOT build; per-platform binaries are published via CI
+# to the GitHub release and consumed by the MCP registry. Pub clients
+# rebuild from source on `dart pub global activate`, so shipping this
+# is dead weight.
+lam-mcp
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 53dd2ea..6b134cc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,107 @@
+## 0.8.0
+
+Closes a class of silent-wrong-output bugs in the CSV/TSV writer,
+adds static warnings for provably-empty filters, and replaces the
+one-shot parser's point-error with a jq-style excerpt. Theme is
+"make wrong queries visibly wrong" — every behavior change in this
+release swaps a silent failure for a loud one.
+
+### Added
+
+- **Element-level CSV/TSV shape check via `MustBeFlatList`.** The
+  new requirement class walks the element shape of the outer list
+  and accepts three forms: `SList<scalar>`, `SList<SList<scalar>>`,
+  and `SList<SMap<k:scalar, ...>>`. A list of maps with list- or
+  map-valued cells now raises `OutputShapeError` instead of being
+  serialized through Dart's default `toString()`. `MustBeList` is
+  retained as the generic list-root requirement for future format
+  additions whose serialization tolerates any element shape.
+  Exported from `package:lambe/lambe.dart`.
+- **Defensive cell guard in the CSV/TSV writer.** Belt-and-braces
+  for the cases where shape inference loses precision (heterogeneous
+  list elements collapse to `SList<SAny>`, which the shape check
+  cannot prove incompatible). A non-scalar cell that reaches the
+  serializer throws `QueryError` with a descriptive type name
+  rather than silently stringifying.
+- **Union headers across heterogeneous-keyed rows.** The writer
+  previously took headers from the first row only, so
+  `[{a:1}, {b:2}]` produced `"a\n1\n"` — the `b` column was silently
+  dropped. Headers are now the union of keys across all rows in
+  first-seen order; rows missing a key render as an empty cell.
+  Matches pandas and Python's `csv.DictWriter` semantics.
+- **Writer–shape-check consistency matrix.**
+  `test/shape_output_consistency_test.dart` pins the invariant
+  across 100 cases: `canWriteAs(v, fmt) == Writable` implies
+  `formatOutput` does not raise `OutputShapeError`; `NotWritable`
+  always raises it. Structural complement to
+  `pipe_ops_consistency_test.dart`; any future writer drift fails
+  loudly instead of silently.
+- **`--explain` warnings for provably-empty filters.** `filter`,
+  `filter_values`, and `filter_keys` reject elements whose predicate
+  is not `== true`. Two patterns make the op provably empty: a
+  predicate whose field path doesn't exist on the element/value/key
+  shape, and a predicate whose inferred shape is any concrete
+  non-boolean scalar. The explain report now carries a `warnings`
+  list and `renderExplain` prints it between stages and writability.
+  `SBool` and `SAny` never warn — neither is provably anything.
+  New `ExplainWarning` type exported from `package:lambe/lambe.dart`.
+
+### Changed
+
+- **Parser errors are line-aware with source context.** Error
+  messages lead with `line:column` instead of just `column`, show
+  the offending line in a gutter-prefixed excerpt with a caret
+  under the bad column, and include one line of context on either
+  side for multi-line queries. The "did you mean" hint for
+  mistyped pipe ops is preserved. `Location.line` was always
+  available on Rumil's `ParseError`; the previous renderer just
+  assumed single-line input and rendered the caret against the
+  full expression, which put it on the wrong visual line for any
+  multi-line query.
+- **Empty-expression parse error is actionable.** Running
+  `lam '' file.json` previously dumped the parser's full list of
+  expected tokens — around 30 items — and buried the actual
+  problem. It now returns a single line: `parse error: expression
+  is empty`. Same treatment for whitespace-only and newline-only
+  input.
+- **`--explain` CLI path uses the rich diagnostic.** Previously it
+  printed `Error: failed to parse query` and skipped the
+  line-aware excerpt that `--to` had access to. Both paths now go
+  through `parseAst`.
+- **`requirementFor(OutputFormat.csv)` and
+  `requirementFor(OutputFormat.tsv)` return `MustBeFlatList`
+  instead of `MustBeList`.** Downstream code that pattern-matches
+  `is MustBeList` on `NotWritable.required` will flip `true → false`.
+- **MCP server `Error: $e` callsites rewritten to `e.message`.**
+  Three sites in `bin/mcp_server.dart` previously produced
+  `Error: QueryError: parse error at line ...` — the
+  `QueryError:` prefix doubled the CLI's `Error:` prefix, which
+  is noise for agents that already know where the error came
+  from.
+- **`ExplainReport` constructor gains an optional `warnings`
+  parameter.** Defaults to `const []`, so existing callers that
+  pass `stages`, `writableAs`, and `notWritableAs` compile and
+  behave unchanged.
+
+### Breaking
+
+- **Queries that relied on the silent CSV/TSV garbage output
+  produce errors now.** This is the release's core behavior
+  change. Pipelines like
+  `.deps | as(csv) | as(toml) | as(csv)` used to emit a CSV cell
+  like `"[{key: rumil, value: ^0.6.0}, ...]"` — the Dart default
+  `List<Map>.toString()`. They now raise `OutputShapeError` with
+  the shape that failed the check. If your pipeline depended on
+  the garbage output, it was always emitting broken data;
+  convert the shape before the final `as(csv)` (e.g. project
+  inner lists to strings, or use a different output format).
+- **Writer output for heterogeneous-keyed list-of-maps is
+  lossless where it was previously lossy.** `[{a:1}, {b:2}]`
+  now serializes to `"a,b\n1,\n,2\n"` instead of `"a\n1\n"`. The
+  `b` column is preserved; row 1 renders an empty cell for `b`,
+  row 2 renders an empty cell for `a`. No code that produced
+  correct output previously will produce different output now.
+
 ## 0.7.1
 
 Polish release on top of 0.7.0. Error-message remediation
diff --git a/README.md b/README.md
index 92822c3..0750561 100644
--- a/README.md
+++ b/README.md
@@ -198,7 +198,7 @@ lam -i data.json
 ```
 
 ```
-lambe v0.7.1 - type :help for commands, :q to quit
+lambe v0.8.0 - type :help for commands, :q to quit
 Data loaded: {3 fields, 42 users}
 
 lambe> .users | filter(.age > 30) | map(.name)
diff --git a/ROADMAP.md b/ROADMAP.md
index aa75ec2..0652185 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -30,22 +30,26 @@ UX polish on top of 0.7.0. Remediation suggestions now surface the intent-level
 
 No breaking changes.
 
-## 0.8.0 — next
+## 0.8.0 — shipped
 
-Extend the shape story to sub-expressions and polish parser errors.
+Closes an entire class of silent-wrong-output bugs in the CSV/TSV writer, extends `--explain` with static warnings for provably-empty filters, and rewrites one-shot parser errors as jq-style excerpts with line-aware caret + context. Unifying theme: "make wrong queries visibly wrong" — every behavior change swapped a silent failure for a loud one.
 
-- **Inner-expression shape validation.** Today `.users | filter(.missing)` completes fine at the outer level, but `.missing` against the element shape is never flagged — the query ships a silently always-null predicate. With the shape machinery in place, the completer and `--explain` can report field access against a known-closed map shape as a definite miss, and inner-expression completion against parameterized ops can offer only fields that exist on the element shape. Same infra, more wiring.
-- **Parser error recovery / multi-line diagnostics.** Rumil's `.recover()` already enables tolerant parsing for the REPL. One-shot CLI queries still get a single point-error. jq's multi-line traceback format (source line + caret + message) is a better experience; the deepest-error selection logic in `lib/lambe.dart` is close but needs better context and position tracking for nested contexts.
+- **Element-level CSV/TSV shape via `MustBeFlatList`.** Non-scalar cells (list- or map-valued) are now rejected with `OutputShapeError` instead of silently stringified through Dart's default `toString()`. Defensive `_scalarCell` guard in the writer catches cases where `SAny` lets the check pass (heterogeneous lists, sampling misses).
+- **Union headers for heterogeneous list-of-maps.** `[{a:1}, {b:2}]` used to lose the `b` column silently. Writer now unions keys across all rows in first-seen order; missing keys render as empty cells. Matches pandas / `csv.DictWriter` semantics.
+- **Writer–shape-check consistency matrix.** 100 cases pin `canWriteAs(v, fmt) == Writable ⇒ formatOutput does not throw OutputShapeError` and vice versa. Structural complement to `pipe_ops_consistency_test.dart`; writer drift fails loudly.
+- **`--explain` warnings for provably-empty filters.** `filter`, `filter_values`, and `filter_keys` all require `== true`. Two patterns make the op provably empty: a field path that doesn't exist on the element/value/key shape, and a predicate whose inferred shape is any concrete non-boolean scalar. `SBool` and `SAny` never warn.
+- **Line-aware parse diagnostics.** `line:column` header, source excerpt with line-number gutter, caret under the offending column, ±1 line of context for multi-line queries. Empty-expression produces a one-liner instead of a 30-token expected-list.
 
-Both extend existing work. Natural bundle.
+One breaking change: pipelines that relied on silent CSV garbage output now raise `OutputShapeError`. See CHANGELOG.
 
 ## 0.9.0 — direction, not commitment
 
 The rule: sharpen Lambë within its scope. Don't widen. Any of the items below might land in 0.9.0, several, or none — this section describes the space, not a plan. Actual scope is decided by what users ask for and what proves worth the effort.
 
-- **Schema-typed queries.** Users declare a schema for a CSV or JSON input once, and the shape tree carries that typing forever through the pipeline instead of re-inferring from sampled values. A `lam --schema file.schema query.lam data.csv` workflow that jq doesn't offer natively. Would compound on the 0.7.0 / 0.8.0 shape work.
-- **Richer `--explain` output.** Per-stage warnings when inference loses precision, structured machine-readable mode for LLM tools, inline remediation hints.
+- **Schema-typed queries.** Users declare a schema for a CSV or JSON input once, and the shape tree carries that typing forever through the pipeline instead of re-inferring from sampled values. A `lam --schema file.schema query.lam data.csv` workflow that jq doesn't offer natively. Would compound on the 0.7.0 / 0.8.0 shape work and is the most identity-defining candidate in the pool — prior shape releases were effectively prep work.
+- **Richer `--explain` output.** More warning categories than the single "provably-empty filter" class 0.8.0 ships: runtime-failure warnings (`filter` on a non-list input throws; flag statically), opt-in trivial-result warnings for `sort_by`/`group_by`/`map` on missing fields (legitimate uses exist, so opt-in), and a structured machine-readable mode for LLM tools.
 - **ndjson at the CLI layer.** Line-delimited JSON: one document per line, evaluated independently, no shared state between lines. Covers the "tail a log" use case without requiring streaming in the core. Small CLI-layer feature (not a core change).
+- **CSV cell-flattening policy.** A `--flatten-cells json` flag that encodes nested structure as a JSON string in a CSV cell rather than refusing. Explicit opt-in policy on the writer side — never silent garbage. Follows from 0.8.0's refusal-by-default stance.
 
 ## Explicit non-goals
 
diff --git a/doc/getting-started.md b/doc/getting-started.md
index a0e87e1..9c666bc 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -195,7 +195,7 @@ For exploring unfamiliar data, use interactive mode:
 
 ```bash
 $ lam -i data.json
-lambe v0.7.1 - type :help for commands, :q to quit
+lambe v0.8.0 - type :help for commands, :q to quit
 Data loaded: {2 fields, 3 users}
 
 lambe>
diff --git a/doc/lam.1 b/doc/lam.1
index aaff06b..c397693 100644
--- a/doc/lam.1
+++ b/doc/lam.1
@@ -1,4 +1,4 @@
-.TH "LAM" "1" "April 2026" "Lambë 0.7.1" ""
+.TH "LAM" "1" "May 2026" "Lambë 0.8.0" ""
 .SH AUTHOR
 Hakim Jonas Ghoula
 .SH NAME
diff --git a/doc/lam.1.md b/doc/lam.1.md
index 4d37597..8c86380 100644
--- a/doc/lam.1.md
+++ b/doc/lam.1.md
@@ -1,9 +1,9 @@
 ---
 title: LAM
 section: 1
-source: Lambë 0.7.1
+source: Lambë 0.8.0
 author: Hakim Jonas Ghoula
-date: April 2026
+date: May 2026
 ---
 
 # NAME
diff --git a/lib/src/_version.dart b/lib/src/_version.dart
index 7708f72..5fa3407 100644
--- a/lib/src/_version.dart
+++ b/lib/src/_version.dart
@@ -3,4 +3,4 @@
 // pubspec.yaml version.
 
 /// Lambe version, sourced from pubspec.yaml at generation time.
-const lambeVersion = '0.7.1';
+const lambeVersion = '0.8.0';
diff --git a/pubspec.yaml b/pubspec.yaml
index 4da05d7..25f2a01 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -2,7 +2,7 @@ name: lambe
 description: >-
   Query JSON, YAML, TOML, HCL, and Markdown files with a composable pipeline DSL.
   Like jq but multi-format, with cleaner syntax. CLI tool + Dart library + MCP server for AI agents.
-version: 0.7.1
+version: 0.8.0
 homepage: https://ardaproject.org/lambe
 repository: https://github.com/hakimjonas/lambe
 topics:
diff --git a/test/manpage_test.dart b/test/manpage_test.dart
index e6cc33d..9f38fcf 100644
--- a/test/manpage_test.dart
+++ b/test/manpage_test.dart
@@ -13,7 +13,7 @@ void main() {
 
   group('Title block', () {
     test('TH header from YAML front matter', () {
-      expect(output, contains('.TH "LAM" "1" "April 2026" "'));
+      expect(output, contains('.TH "LAM" "1" "May 2026" "'));
     });
 
     test('author section', () {

From fb7c40011b1da54f31224db620f38f3e49361aaf Mon Sep 17 00:00:00 2001
From: Hakim Jonas Ghoula <hakim@ghoula.net>
Date: Sat, 2 May 2026 15:29:05 +0200
Subject: [PATCH 13/13] Audit pass: drop em dashes, flatten promotional tone,
 document private helpers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Removes em dashes from prose added in this release (they stay in
existing section-heading style like `## 0.8.0 — shipped` to match the
0.7.x entries). Flattens editorial phrasing in CHANGELOG and ROADMAP:
"This is the release's core behavior change", "every behavior change
swapped a silent failure for a loud one", "is the most
identity-defining candidate in the pool" — all cut. The entries
describe what changed and what users need to do about it.

Two private helpers picked up docstrings: `_describeCellKind` in
lib/src/output.dart and `_isScalar` in lib/src/shape/check.dart. The
analyzer only enforces public_member_api_docs on public members, so
these weren't required, but the helpers are non-obvious (why is SAny
"scalar"?) and the one-liner makes the intent explicit.

No behavior change. 1105 tests, analyzer clean, dart doc clean,
pana 160/160, dart pub publish --dry-run 0 warnings.
---
 CHANGELOG.md                            | 103 +++++++++++-------------
 ROADMAP.md                              |  22 ++---
 lib/src/output.dart                     |  11 ++-
 lib/src/shape/check.dart                |   8 +-
 lib/src/shape/explain.dart              |   6 +-
 test/csv_element_shape_test.dart        |   2 +-
 test/parse_error_format_test.dart       |   6 +-
 test/shape_output_consistency_test.dart |   6 +-
 8 files changed, 83 insertions(+), 81 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b134cc..091e480 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,10 +1,8 @@
 ## 0.8.0
 
-Closes a class of silent-wrong-output bugs in the CSV/TSV writer,
-adds static warnings for provably-empty filters, and replaces the
-one-shot parser's point-error with a jq-style excerpt. Theme is
-"make wrong queries visibly wrong" — every behavior change in this
-release swaps a silent failure for a loud one.
+Adds element-level shape checking for CSV/TSV output, union headers
+across heterogeneous-keyed rows, static warnings for provably-empty
+filters in `--explain`, and line-aware parser diagnostics.
 
 ### Added
 
@@ -17,34 +15,34 @@ release swaps a silent failure for a loud one.
   retained as the generic list-root requirement for future format
   additions whose serialization tolerates any element shape.
   Exported from `package:lambe/lambe.dart`.
-- **Defensive cell guard in the CSV/TSV writer.** Belt-and-braces
-  for the cases where shape inference loses precision (heterogeneous
-  list elements collapse to `SList<SAny>`, which the shape check
-  cannot prove incompatible). A non-scalar cell that reaches the
-  serializer throws `QueryError` with a descriptive type name
-  rather than silently stringifying.
+- **Defensive cell guard in the CSV/TSV writer.** For cases where
+  shape inference loses precision (heterogeneous list elements
+  collapse to `SList<SAny>`, which the shape check cannot prove
+  incompatible), a non-scalar cell that reaches the serializer
+  throws `QueryError` with a descriptive type name rather than
+  silently stringifying.
 - **Union headers across heterogeneous-keyed rows.** The writer
   previously took headers from the first row only, so
-  `[{a:1}, {b:2}]` produced `"a\n1\n"` — the `b` column was silently
-  dropped. Headers are now the union of keys across all rows in
-  first-seen order; rows missing a key render as an empty cell.
-  Matches pandas and Python's `csv.DictWriter` semantics.
-- **Writer–shape-check consistency matrix.**
+  `[{a:1}, {b:2}]` produced `"a\n1\n"` and the `b` column was
+  silently dropped. Headers are now the union of keys across all
+  rows in first-seen order; rows missing a key render as an empty
+  cell. Matches pandas and Python's `csv.DictWriter` semantics.
+- **Writer and shape-check consistency matrix.**
   `test/shape_output_consistency_test.dart` pins the invariant
   across 100 cases: `canWriteAs(v, fmt) == Writable` implies
   `formatOutput` does not raise `OutputShapeError`; `NotWritable`
   always raises it. Structural complement to
-  `pipe_ops_consistency_test.dart`; any future writer drift fails
-  loudly instead of silently.
+  `pipe_ops_consistency_test.dart`; writer drift fails loudly.
 - **`--explain` warnings for provably-empty filters.** `filter`,
   `filter_values`, and `filter_keys` reject elements whose predicate
   is not `== true`. Two patterns make the op provably empty: a
-  predicate whose field path doesn't exist on the element/value/key
-  shape, and a predicate whose inferred shape is any concrete
-  non-boolean scalar. The explain report now carries a `warnings`
-  list and `renderExplain` prints it between stages and writability.
-  `SBool` and `SAny` never warn — neither is provably anything.
-  New `ExplainWarning` type exported from `package:lambe/lambe.dart`.
+  predicate whose field path doesn't exist on the element, value,
+  or key shape; and a predicate whose inferred shape is any
+  concrete non-boolean scalar. The explain report now carries a
+  `warnings` list and `renderExplain` prints it between stages and
+  writability. `SBool` and `SAny` predicates never warn: either
+  might be true. New `ExplainWarning` type exported from
+  `package:lambe/lambe.dart`.
 
 ### Changed
 
@@ -54,30 +52,28 @@ release swaps a silent failure for a loud one.
   under the bad column, and include one line of context on either
   side for multi-line queries. The "did you mean" hint for
   mistyped pipe ops is preserved. `Location.line` was always
-  available on Rumil's `ParseError`; the previous renderer just
-  assumed single-line input and rendered the caret against the
-  full expression, which put it on the wrong visual line for any
+  available on Rumil's `ParseError`; the previous renderer assumed
+  single-line input and rendered the caret against the full
+  expression, which put it on the wrong visual line for any
   multi-line query.
 - **Empty-expression parse error is actionable.** Running
   `lam '' file.json` previously dumped the parser's full list of
-  expected tokens — around 30 items — and buried the actual
-  problem. It now returns a single line: `parse error: expression
-  is empty`. Same treatment for whitespace-only and newline-only
-  input.
-- **`--explain` CLI path uses the rich diagnostic.** Previously it
-  printed `Error: failed to parse query` and skipped the
-  line-aware excerpt that `--to` had access to. Both paths now go
-  through `parseAst`.
+  expected tokens (around 30 items) and buried the actual problem.
+  It now returns a single line: `parse error: expression is empty`.
+  Same treatment for whitespace-only and newline-only input.
+- **`--explain` CLI path uses the line-aware diagnostic.**
+  Previously it printed `Error: failed to parse query` and skipped
+  the excerpt that `--to` had access to. Both paths now go through
+  `parseAst`.
 - **`requirementFor(OutputFormat.csv)` and
   `requirementFor(OutputFormat.tsv)` return `MustBeFlatList`
   instead of `MustBeList`.** Downstream code that pattern-matches
-  `is MustBeList` on `NotWritable.required` will flip `true → false`.
+  `is MustBeList` on `NotWritable.required` will flip
+  `true` to `false`.
 - **MCP server `Error: $e` callsites rewritten to `e.message`.**
   Three sites in `bin/mcp_server.dart` previously produced
-  `Error: QueryError: parse error at line ...` — the
-  `QueryError:` prefix doubled the CLI's `Error:` prefix, which
-  is noise for agents that already know where the error came
-  from.
+  `Error: QueryError: parse error at line ...`; the `QueryError:`
+  prefix doubled the CLI's `Error:` prefix.
 - **`ExplainReport` constructor gains an optional `warnings`
   parameter.** Defaults to `const []`, so existing callers that
   pass `stages`, `writableAs`, and `notWritableAs` compile and
@@ -85,22 +81,19 @@ release swaps a silent failure for a loud one.
 
 ### Breaking
 
-- **Queries that relied on the silent CSV/TSV garbage output
-  produce errors now.** This is the release's core behavior
-  change. Pipelines like
+- **Queries that relied on the silent CSV/TSV garbage output now
+  raise `OutputShapeError`.** Pipelines like
   `.deps | as(csv) | as(toml) | as(csv)` used to emit a CSV cell
-  like `"[{key: rumil, value: ^0.6.0}, ...]"` — the Dart default
-  `List<Map>.toString()`. They now raise `OutputShapeError` with
-  the shape that failed the check. If your pipeline depended on
-  the garbage output, it was always emitting broken data;
-  convert the shape before the final `as(csv)` (e.g. project
-  inner lists to strings, or use a different output format).
-- **Writer output for heterogeneous-keyed list-of-maps is
-  lossless where it was previously lossy.** `[{a:1}, {b:2}]`
-  now serializes to `"a,b\n1,\n,2\n"` instead of `"a\n1\n"`. The
-  `b` column is preserved; row 1 renders an empty cell for `b`,
-  row 2 renders an empty cell for `a`. No code that produced
-  correct output previously will produce different output now.
+  like `"[{key: rumil, value: ^0.6.0}, ...]"` (Dart's default
+  `List<Map>.toString()`). They now raise `OutputShapeError` with
+  the shape that failed the check. Convert the shape before the
+  final `as(csv)` (for example project inner lists to strings), or
+  use a different output format.
+- **Writer output for heterogeneous-keyed list-of-maps changes.**
+  `[{a:1}, {b:2}]` now serializes to `"a,b\n1,\n,2\n"` instead of
+  `"a\n1\n"`. Row 1 renders an empty cell for `b`, row 2 renders
+  an empty cell for `a`. Code that produced correct output on
+  homogeneous-keyed input is unaffected.
 
 ## 0.7.1
 
diff --git a/ROADMAP.md b/ROADMAP.md
index 0652185..362a7a1 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -32,24 +32,24 @@ No breaking changes.
 
 ## 0.8.0 — shipped
 
-Closes an entire class of silent-wrong-output bugs in the CSV/TSV writer, extends `--explain` with static warnings for provably-empty filters, and rewrites one-shot parser errors as jq-style excerpts with line-aware caret + context. Unifying theme: "make wrong queries visibly wrong" — every behavior change swapped a silent failure for a loud one.
+Element-level shape checking for CSV/TSV output, static warnings for provably-empty filters, and line-aware parser diagnostics.
 
-- **Element-level CSV/TSV shape via `MustBeFlatList`.** Non-scalar cells (list- or map-valued) are now rejected with `OutputShapeError` instead of silently stringified through Dart's default `toString()`. Defensive `_scalarCell` guard in the writer catches cases where `SAny` lets the check pass (heterogeneous lists, sampling misses).
-- **Union headers for heterogeneous list-of-maps.** `[{a:1}, {b:2}]` used to lose the `b` column silently. Writer now unions keys across all rows in first-seen order; missing keys render as empty cells. Matches pandas / `csv.DictWriter` semantics.
-- **Writer–shape-check consistency matrix.** 100 cases pin `canWriteAs(v, fmt) == Writable ⇒ formatOutput does not throw OutputShapeError` and vice versa. Structural complement to `pipe_ops_consistency_test.dart`; writer drift fails loudly.
-- **`--explain` warnings for provably-empty filters.** `filter`, `filter_values`, and `filter_keys` all require `== true`. Two patterns make the op provably empty: a field path that doesn't exist on the element/value/key shape, and a predicate whose inferred shape is any concrete non-boolean scalar. `SBool` and `SAny` never warn.
-- **Line-aware parse diagnostics.** `line:column` header, source excerpt with line-number gutter, caret under the offending column, ±1 line of context for multi-line queries. Empty-expression produces a one-liner instead of a 30-token expected-list.
+- **Element-level CSV/TSV shape via `MustBeFlatList`.** Non-scalar cells (list- or map-valued) are rejected with `OutputShapeError` instead of silently stringified through Dart's default `toString()`. Defensive `_scalarCell` guard in the writer catches cases where `SAny` lets the shape check pass (heterogeneous lists, sampling misses).
+- **Union headers for heterogeneous list-of-maps.** `[{a:1}, {b:2}]` used to lose the `b` column silently. Writer now unions keys across all rows in first-seen order; missing keys render as empty cells. Matches pandas and Python's `csv.DictWriter` semantics.
+- **Writer and shape-check consistency matrix.** 100 cases pin that `canWriteAs` and `formatOutput` agree on accept or reject. Structural complement to `pipe_ops_consistency_test.dart`; writer drift fails loudly.
+- **`--explain` warnings for provably-empty filters.** `filter`, `filter_values`, and `filter_keys` all require `== true`. Two patterns make the op provably empty: a field path that doesn't exist on the element, value, or key shape, and a predicate whose inferred shape is any concrete non-boolean scalar. `SBool` and `SAny` never warn.
+- **Line-aware parse diagnostics.** `line:column` header, source excerpt with line-number gutter, caret under the offending column, one line of context on either side for multi-line queries. Empty-expression produces a one-liner instead of a 30-token expected-list.
 
 One breaking change: pipelines that relied on silent CSV garbage output now raise `OutputShapeError`. See CHANGELOG.
 
 ## 0.9.0 — direction, not commitment
 
-The rule: sharpen Lambë within its scope. Don't widen. Any of the items below might land in 0.9.0, several, or none — this section describes the space, not a plan. Actual scope is decided by what users ask for and what proves worth the effort.
+The rule: sharpen Lambë within its scope. Don't widen. Any of the items below might land in 0.9.0, several, or none. Actual scope is decided by what users ask for and what proves worth the effort.
 
-- **Schema-typed queries.** Users declare a schema for a CSV or JSON input once, and the shape tree carries that typing forever through the pipeline instead of re-inferring from sampled values. A `lam --schema file.schema query.lam data.csv` workflow that jq doesn't offer natively. Would compound on the 0.7.0 / 0.8.0 shape work and is the most identity-defining candidate in the pool — prior shape releases were effectively prep work.
-- **Richer `--explain` output.** More warning categories than the single "provably-empty filter" class 0.8.0 ships: runtime-failure warnings (`filter` on a non-list input throws; flag statically), opt-in trivial-result warnings for `sort_by`/`group_by`/`map` on missing fields (legitimate uses exist, so opt-in), and a structured machine-readable mode for LLM tools.
-- **ndjson at the CLI layer.** Line-delimited JSON: one document per line, evaluated independently, no shared state between lines. Covers the "tail a log" use case without requiring streaming in the core. Small CLI-layer feature (not a core change).
-- **CSV cell-flattening policy.** A `--flatten-cells json` flag that encodes nested structure as a JSON string in a CSV cell rather than refusing. Explicit opt-in policy on the writer side — never silent garbage. Follows from 0.8.0's refusal-by-default stance.
+- **Schema-typed queries.** Users declare a schema for a CSV or JSON input once, and the shape tree carries that typing through the pipeline instead of re-inferring from sampled values. A `lam --schema file.schema query.lam data.csv` workflow that jq doesn't offer natively. Compounds on the 0.7.0 and 0.8.0 shape work.
+- **Richer `--explain` output.** More warning categories beyond the single "provably-empty filter" class 0.8.0 ships: runtime-failure warnings (`filter` on a non-list input throws; flag statically), opt-in trivial-result warnings for `sort_by`, `group_by`, and `map` on missing fields (legitimate uses exist, so opt-in), and a structured machine-readable mode for tool integrations.
+- **ndjson at the CLI layer.** Line-delimited JSON: one document per line, evaluated independently, no shared state between lines. Covers the "tail a log" use case without requiring streaming in the core. Small CLI-layer feature, not a core change.
+- **CSV cell-flattening policy.** A `--flatten-cells json` flag that encodes nested structure as a JSON string in a CSV cell rather than refusing. Opt-in on the writer side; default behavior stays at 0.8.0's refuse-rather-than-garble.
 
 ## Explicit non-goals
 
diff --git a/lib/src/output.dart b/lib/src/output.dart
index e4547c8..7c86822 100644
--- a/lib/src/output.dart
+++ b/lib/src/output.dart
@@ -19,7 +19,7 @@ export 'output_format.dart' show OutputFormat;
 /// For CSV/TSV, requires a list of maps, a list of lists, or a list of
 /// scalars. For a list of maps, headers are the union of keys across
 /// all rows in first-seen order; a row missing a key renders as an
-/// empty cell. Every cell value must be a scalar — null, bool, num,
+/// empty cell. Every cell value must be a scalar: null, bool, num,
 /// or string. List-of-maps or list-of-lists with non-scalar cells
 /// throws [OutputShapeError]; a non-scalar cell that slips past shape
 /// inference (for example via [SAny]) throws [QueryError] at
@@ -123,7 +123,7 @@ String _toCsv(Object? value, String delimiter) {
 /// example, a [SAny] shape that the checker could not prove
 /// incompatible, or heterogeneous list elements that sampling missed).
 /// Throws [QueryError] rather than [OutputShapeError] because by this
-/// point the shape check has already passed — reaching here means the
+/// point the shape check has already passed: reaching here means the
 /// shape language was unable to prove the mismatch.
 String _scalarCell(Object? cell, OutputFormat fmt) {
   if (cell == null) return '';
@@ -134,6 +134,11 @@ String _scalarCell(Object? cell, OutputFormat fmt) {
   );
 }
 
+/// Short human-readable kind name for a non-scalar cell value.
+///
+/// Used by [_scalarCell] to render errors like "got list" instead of
+/// "got _GrowableList". Falls back to [Object.runtimeType] for kinds
+/// outside List and Map.
 String _describeCellKind(Object cell) {
   if (cell is List) return 'list';
   if (cell is Map) return 'map';
@@ -145,7 +150,7 @@ String _describeCellKind(Object cell) {
 /// The first map's keys appear first in their insertion order; each
 /// subsequent map contributes any keys not already present, in the
 /// order they first appear. Rows missing a key render as an empty cell
-/// rather than silently dropping the column — symmetric with how the
+/// rather than silently dropping the column, symmetric with how the
 /// writer refuses non-scalar cells elsewhere.
 List<String> _unionHeaders(List<Map<String, Object?>> maps) {
   final seen = <String>{};
diff --git a/lib/src/shape/check.dart b/lib/src/shape/check.dart
index 136b67c..082e36e 100644
--- a/lib/src/shape/check.dart
+++ b/lib/src/shape/check.dart
@@ -111,14 +111,18 @@ final class MustBeFlatList extends ShapeRequirement {
   @override
   String describe() => 'a list with scalar cells';
 
-  /// Whether `elem` — the element shape of the outer list — produces
-  /// only scalar cells when serialized as a CSV/TSV row.
+  /// Whether an element shape of the outer list produces only scalar
+  /// cells when serialized as a CSV/TSV row.
   static bool _cellShapeIsFlat(Shape elem) => switch (elem) {
     SAny() || SNull() || SBool() || SNum() || SString() => true,
     SList(:final element) => _isScalar(element),
     SMap(:final fields) => fields.values.every(_isScalar),
   };
 
+  /// Whether [s] is a scalar shape (null, bool, num, string, or unknown).
+  ///
+  /// `SAny` counts as scalar here: when the shape is unknown, the check
+  /// cannot prove incompatibility and defers to the runtime guard.
   static bool _isScalar(Shape s) => switch (s) {
     SAny() || SNull() || SBool() || SNum() || SString() => true,
     SList() || SMap() => false,
diff --git a/lib/src/shape/explain.dart b/lib/src/shape/explain.dart
index 973751d..ba3da72 100644
--- a/lib/src/shape/explain.dart
+++ b/lib/src/shape/explain.dart
@@ -35,9 +35,9 @@ final class ExplainStage {
 
 /// A static-analysis warning attached to an explain report.
 ///
-/// Warnings call out constructs that will evaluate to a trivial result
+/// Warnings call out constructs that evaluate to a trivial result
 /// regardless of input, such as a `filter` predicate whose inferred
-/// shape is not [SBool] — `filter` requires `== true`, so any non-bool
+/// shape is not [SBool]. `filter` requires `== true`, so any non-bool
 /// predicate makes the filter always empty.
 ///
 /// [stageIndex] points into [ExplainReport.stages] so a renderer can
@@ -190,7 +190,7 @@ String? _predicateWarning(
 /// context at each step. As soon as a step lands on a known map whose
 /// fields don't include the required name, returns the rendered path up
 /// to and including that missing segment. [SAny] anywhere along the
-/// path disables the check — unknown context means we cannot prove
+/// path disables the check: unknown context means we cannot prove
 /// the field is missing.
 String? _missingFieldPath(LamExpr expr, Shape context) {
   final segments = <String>[];
diff --git a/test/csv_element_shape_test.dart b/test/csv_element_shape_test.dart
index 99bc75a..1fd92a5 100644
--- a/test/csv_element_shape_test.dart
+++ b/test/csv_element_shape_test.dart
@@ -3,7 +3,7 @@
 ///
 /// Bug motivating this test: `.deps | as(csv) | as(toml) | as(csv)` on a
 /// map-of-strings fixture produced
-/// `items,"[{key: rumil, value: ^0.6.0}, ...]"` — the cell's value was
+/// `items,"[{key: rumil, value: ^0.6.0}, ...]"`. The cell's value was
 /// Dart's default `List<Map>.toString()` output. `MustBeList.accepts`
 /// only checked list-at-the-root; the element shape was never validated.
 ///
diff --git a/test/parse_error_format_test.dart b/test/parse_error_format_test.dart
index 99cc5c2..21d3597 100644
--- a/test/parse_error_format_test.dart
+++ b/test/parse_error_format_test.dart
@@ -3,9 +3,9 @@
 /// A query with a typo or dangling pipe should produce a jq-style
 /// excerpt: the error header with `line:column`, the offending line
 /// with a gutter-prefixed line number, a caret under the offending
-/// column, and — for multi-line queries — one line of context on
-/// either side so the reader can orient. The existing "did you mean"
-/// hint for mistyped pipe ops continues to work.
+/// column, and (for multi-line queries) one line of context on either
+/// side so the reader can orient. The "did you mean" hint for mistyped
+/// pipe ops continues to work.
 ///
 /// QueryError.message is the clean rendered text; callers should print
 /// `e.message` rather than `$e`, because `$e` prepends `QueryError: `
diff --git a/test/shape_output_consistency_test.dart b/test/shape_output_consistency_test.dart
index 593cc65..56f4b65 100644
--- a/test/shape_output_consistency_test.dart
+++ b/test/shape_output_consistency_test.dart
@@ -4,9 +4,9 @@
 /// runs the writer and cross-checks the shape predicate: `Writable` must
 /// never result in [OutputShapeError], and `NotWritable` must always
 /// result in [OutputShapeError]. The `Writable` side is allowed to
-/// raise [QueryError] from the writer's defensive guard — that only
-/// fires when the shape language was too lossy to prove the mismatch
-/// (typically [SAny] buried inside a container). What is strictly
+/// raise [QueryError] from the writer's defensive guard (which only
+/// fires when the shape language was too lossy to prove the mismatch,
+/// typically [SAny] buried inside a container). What is strictly
 /// forbidden is silent stringification, which is what the original
 /// CSV round-trip bug produced.
 ///