rdbms-playground/docs/handoff/20260615-handoff-72.md

Session handoff — 2026-06-15 (72)

Short, focused handover. Continues from handoff-71, which asked the next session to run a systematic semantic verification pass over every hint block (handoff-70 shipped H2 / ADR-0053, but a user smoke-test found a wrong hint and implicated the whole corpus). That pass is now done. Four content errors fixed, a durable parse-guard added, two stale docs corrected. Commit 5a37437.

§1. State

Branch: main, clean, all committed (local; push pending — your step). 2500 pass / 0 fail / 1 ignored (the long-standing friendly doctest), clippy clean (nursery, all targets). The +1 vs handoff-71's 2499 is the new guard test. Open Gitea issues unchanged: #35–#38.

§2. The verification pass (commit 5a37437)

Method: cross-checked every hint.cmd.* example against its parse.usage.* template, ground-truthed every concept claim against the authoritative ADR and a named existing test (not grep+extrapolation — the trap handoff-71 §3 warned about), and parse-validated all 49 command examples via a new guard.

Four content errors fixed (src/friendly/strings/en-US.yaml)

Block	Bug	Fix
cmd.create_table	Example with pk id(serial), name(text), email(text) declares a 3-column compound PK, not a PK + regular columns. Every with pk column is a key member — confirmed by the grammar test comment "Every create table column is a primary-key column" (ddl.rs), ADR-0005.	Single-column PK + add column for the rest; what/concept aligned.
cmd.save	save as my-shop does not parse — build_save yields AppCommand::SaveAs with no inline name; save as opens a path-entry modal (iteration4b tests).	Example → save as; what de-implied; added an accurate temp-vs-named-auto-save concept.
cmd.import	Target shop-copy does not parse — the as <target> slot is an IdentSource::NewName ident that tokenises only up to the hyphen. (The zip path is a BarePath and does accept hyphens, hence export my-shop.zip is fine.)	→ shop_copy.
err.foreign_key.child_side.concept	Offered on delete set null/cascade as the remedy — but error_hint_class maps child_side to insert/update violations; on delete governs the parent direction. The tier-1 hint (line 64) correctly omits it.	Corrected: parent must exist first; clarified on delete is the other direction.

Durable guard added

every_cmd_hint_example_parses_in_its_mode (src/dsl/grammar/mod.rs, in the hint_key_tests module). Catalog-driven — it iterates catalog().keys() for hint.cmd.*.example rather than the REGISTRY, so an orphaned/mis-keyed block can't slip past; floor-asserts ≥49 examples. Each parses in its taught mode (advanced for the SQL surface, simple otherwise). It caught the save and import errors test-first (red before the YAML fix). Registered the new hint.cmd.save.concept key in keys.rs (the keys_validate_against_catalog test requires every catalog key be declared).

Verified correct (not changed)

All other cmd/err blocks. Notably the guard-concept claims were each confirmed against a named runtime test, not assumed: drop_column_refuses_primary_key / …_column_in_a_relationship, drop_table_with_inbound_relationship_errors, add_not_null_column_without_default_to_populated_table_is_refused. The corrected create_table story stays coherent with the Customers- referencing examples (id serial PK → add column name/email → insert skips the auto id).

§3. Docs corrected (same commit)

Discovered while verifying create_m2n (which is implemented — db.rs::do_create_m2n_relationship + tests/it/m2n.rs):

• CLAUDE.md carried two stale "deferred" claims, both already implemented. Removed/updated: (a) the at-a-glance project-format line said export/import (Iter 5) + --resume/input-history/migration (Iter 6) were "pending" — all [x] in requirements.md (ADR-0015); (b) the "Things deliberately deferred" list still had the m:n convenience (C4) bullet and the same project-storage bullet. requirements.md was already correct (C4 done 2026-06-10, ADR-0045), so only a verification-pass note was appended to its H2 entry.

§4. Scope note — what the guard does not do

The bug class here is semantic (an example that parses and runs but misrepresents the prose — e.g. create_table). The guard enforces only the syntactic floor: examples parse in their mode. It backstops future typos/clause-drift but cannot police meaning. Semantic correctness of the current corpus rests on this session's review (recorded in the commit + requirements.md H2). A stronger-but-brittler option was offered to the user and not built pending their call: per-form assertions that each example resolves to the expected command shape (e.g. create_table → single-column PK). hint.err.* examples are fix-recipe prose, not runnable, so they're verified by review only — inherent.

§5. Next session — start here

The hint corpus is now trustworthy. Open roadmap (verify against the CI merge first, per handoff-70 §5):

1. Push (your step) — this commit + the still-unpushed backlog from handoffs 70/71 (the CI merge + all of H2).
2. #35 (cargo fmt gate) — the natural pairing with the merged CI; the user wanted it done once, before first publication. The tree is not fmt-clean (~1800 pre-existing diffs).
3. Other requirements.md open items: TT4 PTY tier-4 (unwired), I1 multi-line input, I5/B3 in-flight cancellation, V4 session journal (own ADR), TU1 tutorial system (own ADR).
4. Hint follow-ups if wanted: #37 clause-concept hints, #38 diagnostic route + diagnostic.* blocks, #36 help advanced-SQL.

§6. How to take over

1. Read handoffs 70 → 71 → 72, CLAUDE.md, docs/requirements.md.
2. Confirm green: cargo test (2500 / 1 ignored) + cargo clippy --all-targets (clean).
3. For anything in the hint area, read ADR-0053 first. For the corpus, src/friendly/strings/en-US.yaml (hint.cmd.* / hint.err.*) is the content; the guard in src/dsl/grammar/mod.rs is the regression net.
4. Workflow unchanged: phased, test-first, /runda + DA before commits, ADR amendment + README index-upkeep for decided-area changes, confirm commit messages with the user.
5. Consider a cargo sweep at this milestone (target/ grows; see CLAUDE.md "Build hygiene").