rdbms-playground/docs/handoff/20260602-handoff-57.md

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".