docs: session handoff 57 — H1 verified done, target/ 38 GB → 1.6 GB, tests consolidated

Captures the post-handoff-56 arc: H1 (ADR-0019) verified already shipped
(not "partial"); build-hygiene fixes (incremental off, line-tables debug,
cargo-sweep) cutting target/ from 38 GB to ~1.6 GB; and consolidating 25
integration crates into one `it` binary (disk win, not the predicted
speed win). Flags the new test layout (add tests under tests/it/ + a mod
line) and points the next session at H1a (ADR-0021) as the queued job.

docs/handoff/20260602-handoff-57.md

@@ -0,0 +1,143 @@
+# Session handoff — 2026-06-02 (57)
+
+Fifty-seventh handover, same day as 54–56. Continues directly from
+handoff-56 (serde_norway). This stretch was **not** feature work — it
+was a verification + hygiene arc that came out of a single question
+("why is `target/` 38 GB?") and ended up correcting stale docs, slashing
+the build tree, and restructuring the test layout. **The next job is the
+feature work that was queued and never started: H1a.** See §6.
+
+## §1. State at handoff
+
+**Branch:** `main`. **HEAD `9efae59`.** **3 commits ahead of
+`origin/main`** (this stretch; #11 and serde_norway from handoffs 55/56
+are already pushed). **Tests: 2151 passing / 0 failing / 1 ignored**
+(lib-only 1578). **Clippy clean** (nursery, all targets, `-D warnings`).
+**`target/` ≈ 1.6 GB** (was 38 GB). Push is the user's step.
+
+Commits since handoff-56's `56d9671`:
+
+```
+9efae59 test: consolidate 25 integration crates into one `it` binary
+42f9553 chore: bound target/ growth — incremental off, line-tables debug
+be7b078 docs: mark H1 done — friendly DB-error layer is shipped
+```
+
+## §2. What happened this stretch
+
+### H1 verification — it was already done (be7b078)
+
+We set out (handoff-55's option C) to verify H1 and then do H1a.
+Verification found **H1 (ADR-0019) fully implemented and shipped**, not
+"partial" as `requirements.md`/CLAUDE.md claimed: `friendly::
+translate_error` is wired on the live failure path (`runtime.rs:2453`,
+`app.rs:1838`, `db.rs:411`), covers all five error categories (UNIQUE /
+FK both sides / NOT NULL / CHECK / type-mismatch) with
+operation×kind×verbosity catalog wording, the `messages` verbosity
+command, and §6 row-pinpointing via runtime-resolved facts — backed by
+**44 friendly unit tests + 12 full-stack `friendly_enrichment`
+integration tests** that assert the rendered wording through a real DB.
+Even advanced-mode SQL errors route through the same translator (no
+engine-name leak). **Don't re-do H1.** What remains of ADR-0019 is its
+*explicitly separable* follow-ons: §9 i18n migration sweep of *other*
+strings (largely done), §OOS-2 advanced-SQL error *sanitisation*,
+§OOS-3 `messages` persistence (awaits a settings ADR). `requirements.md`
+H1 is now `[x]`; the stale "always None" comment in `translate.rs` was
+fixed (pinpointing landed long ago in `431645a`).
+
+### Build-hygiene / the 38 GB (42f9553)
+
+`target/` had reached **38 GB**. Breakdown: **16 GB incremental cache**
+(≈28 compilation units × every historical config, never evicted), ~3 GB
+of test binaries, orphaned example binaries. Root cause: **cargo has no
+`target/` garbage collection** — it caches aggressively and never
+evicts. Actions:
+
+- `[profile.dev]` (inherited by `test`): **`incremental = false`** (the
+  16 GB cache earns little in a full-suite workflow) + **`debug =
+  "line-tables-only"`** (default `debug = 2` was ~85–90 % of each test
+  binary; line tables keep file:line in panics/backtraces — we debug via
+  `tracing` logs).
+- **`cargo-sweep` installed**; documented in CLAUDE.md "Build hygiene"
+  (the stamp/build/`--file` workflow = the GC cargo lacks; `--installed`
+  frees nothing for same-toolchain cruft — verified).
+- Net: a clean full build is now **≈1.6 GB** and stays bounded.
+
+### Test consolidation (9efae59)
+
+25 of the 26 top-level `tests/*.rs` were each their own crate → their
+own binary (each statically linking the bundled engine). Moved them into
+**`tests/it/`** under one **`tests/it/main.rs`** (`mod`-includes; cargo
+auto-detects it as the `it` target — no `[[test]]` entry needed).
+`typing_surface_matrix.rs` stays its own already-consolidated binary.
+**End state: 2 integration-test binaries instead of 26.**
+
+**Honest correction recorded in the commit + `docs/plans/
+20260602-test-consolidation.md`:** the predicted *build-speed* win did
+**not** materialise (clean 22.9 s→22.4 s; lib-edit relink 13.3 s→12.4 s).
+Wall-clock is dominated by *compiling* (lib + ~290 deps + test codegen),
+not *linking*. The real win is **disk** — `deps/` 1.5 GB → 629 MB
+(−58 %). Minor cost: editing one test file now recompiles the whole `it`
+module set.
+
+## §3. ⚠️ Test layout — read before adding a test
+
+Integration tests now live in **`tests/it/<name>.rs`**, wired as modules
+from **`tests/it/main.rs`**. **To add a new integration test: drop the
+file in `tests/it/` and add one `mod <name>;` line to
+`tests/it/main.rs`.** Do **not** add a new top-level `tests/*.rs` — that
+re-creates a separate binary and re-fragments the very thing 9efae59
+consolidated. (`tests/typing_surface_matrix.rs` is the deliberate
+exception — its own consolidated binary.)
+
+## §4. Still open from earlier (carried, unchanged)
+
+- **arboard decisions (handoff-55 §3), open-for-correction:** native
+  Linux is X11-only (no `wayland-data-control` — OSC 52 covers Wayland);
+  `copy` reproduces on-screen text *including* the `[system]` tags. Both
+  one-line changes if revisited.
+- Closed-issue / push bookkeeping: the 3 commits here are unpushed
+  (user's step). No GitHub issues open (the whole #1–#18 backlog is
+  resolved; #11 closed this session-arc).
+
+## §5. Other tracks (from `requirements.md`)
+
+Unchanged from handoff-55/56: Track 2 Iter 6 leftovers (history.log
+input-history hydration polish, migration-framework exercise); C3a
+modify relationship; C4 m:n convenience; **H1 done**; V4 session-log /
+Markdown export (clipboard V6 shipped as a complementary path); I1/I1b
+multi-line + readline; I3/I4 input UX; TU1 tutorial (needs ADR).
+
+## §6. Next job — H1a (ADR-0021), start here
+
+**H1a is the queued feature work.** It is the **separate sibling of H1**,
+not part of it: H1 = friendly *database*-error layer (done, ADR-0019);
+**H1a = strong syntax-help in *parse* errors (ADR-0021, Accepted)** —
+when the user types something near-correct, name the *missing
+keyword/clause* instead of pointing at the unexpected character
+(e.g. `insert into T ('Oli')` → "missing `values`"; `update T set x=1`
+→ "no WHERE — add one or `--all-rows`").
+
+**Start with a scope audit, don't assume it's greenfield.** ADR-0021 is
+Accepted and substantial parse-error infrastructure already exists
+(per-command `usage_ids` on every `CommandNode`, typed-value-slot
+wording, ~61 parse-error/usage references) — `requirements.md` H1a says
+"shipping piecemeal so far." So: (1) read ADR-0021 + ADR-0020
+(tokenization) + ADR-0009; (2) audit what H1a already delivers vs. its
+full intent; (3) gap-fill **test-first** via the typing-surface matrix +
+`parse_error_pedagogy` (now `tests/it/parse_error_pedagogy.rs`);
+(4) escalate genuine design choices.
+
+## §7. How to take over
+
+1. Read handoffs 55 → 56 → 57 in order, then `CLAUDE.md` (note the new
+   "Build hygiene" section + the test-layout rule in §3 above),
+   `docs/requirements.md` (H1 now `[x]`), `docs/adr/README.md`.
+2. Codebase on `main` at `9efae59`, clean, 3 unpushed.
+3. **Next job: H1a** (§6) — audit-first, test-first.
+4. Process pins that earned their keep this arc: **verify, don't trust
+   the docs** (H1 was marked partial but was done; the consolidation's
+   speed win was assumed but false — both caught by measuring/reading
+   before acting), **escalate genuine choices**, **commits
+   user-confirmed, append-only, no AI attribution**, and **measure
+   before/after** for any "optimisation".