diff --git a/docs/handoff/20260602-handoff-57.md b/docs/handoff/20260602-handoff-57.md new file mode 100644 index 0000000..a3995f3 --- /dev/null +++ b/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/.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 ;` 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".