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