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

Session handoff — 2026-06-15 (70)

Seventieth handover. Continues from handoff-69 (which closed the last four Gitea issues and left the tracker empty). This session did the ADR-0052 follow-up (unwinding vestigial worker source plumbing), then designed and fully implemented H2 — the contextual hint command + F1 keybinding (ADR-0053) end to end (Phases A–D). The CI branch was also merged into main mid-session (not my work — see §5).

Net: 2 feature areas shipped, 1 new ADR (0053) + 1 ADR amendment (0052), 4 new Gitea issues (#35–#38), the hint corpus (~57 teaching blocks), and A1 + H2 closed in requirements.md.

§1. State at handoff

Branch: main. Working tree clean; all work committed. Commits are local (push is the user's step).

Tests: 2499 passing / 0 failing / 0 skipped / 1 ignored (the long-standing friendly doctest). Clippy clean (nursery, all targets). Breakdown: 1799 lib + 500 it + 200 typing-surface-matrix.

Open Gitea issues (4, all enhancement, all filed this session):

• #35 — enforce cargo fmt across the codebase (single reformat + CI gate). The tree is not fmt-clean (~1800 pre-existing diffs); do it once, coordinated with CI, before first publication.
• #36 — help collapses advanced-SQL forms onto their simple sibling (a help-list dedup artifact); they deserve distinct help content.
• #37 — hint clause-concept hints (on delete actions, constraint slots, with pk, cardinality) — a deferred hint.concept.<topic> layer.
• #38 — hint pre-submit-diagnostic route + the ~33 diagnostic.* tier-3 blocks (deferred; Diagnostic carries no class key).

§2. ADR-0052 follow-up — vestigial worker source unwind (e8fa859)

The first task from handoff-69 §3. ADR-0052 moved success-journaling out of the worker, leaving the source that handlers threaded purely for the old history.log write dead. Bigger than the handoff estimated (it framed it as ~28 call-site edits): the cascade ran through ~30 worker handlers + the DescribeTable/QueryData/RunSelect request fields + their DatabaseHandle methods (~164 mostly-test call sites). Fully unwound, compiler-guided, no behaviour change (journaling uses a source_for_journal clone at the spawn, independent of the worker). The only worker source left is the snapshot/undo label. Amended ADR-0052 Consequences + README. (Two scope forks escalated + user-approved.)

§3. H2 — contextual hint (ADR-0053), Phases A–D — shipped

The bulk of the session. ADR-0053 settles the hint slot ADR-0003 left "ADR pending"; closes A1 (all 15 app commands now exist) and requirements H2. Read ADR-0053 before touching this area — it went through three revisions and several user decisions.

The design (all user-chosen)

• Two surfaces: an F1 keybinding → tier-3 hint for the live partial input (read-only overlay — never touches buffer/cursor/memo); a submitted hint command → expands on the most recent runtime error. No topic arg (contextual only; help <topic> owns reference).
• Tier-3 teaching layer beneath the existing tier-1 (colour / error headline) and tier-2 (ambient one-liner; the error hint: shown by default since Verbosity::Verbose is the default). Each block is what / example / concept, rendered as a Hint heading + aligned labels.
• Per-form keying (Phase-B revision — the original per-node hint_id was too coarse for multi-form commands like add/drop/show): a new hint_ids: &[&str] field on CommandNode mirroring usage_ids, resolved by hint_key_for_input_in_mode (reuses usage_key's form-word disambiguation + a mode-primary fallback for shared entry words so advanced insert → sql_insert, simple → insert).
• Comprehensive for v1 = command forms + 9 runtime error classes (the ~33 diagnostic.* classes were deferred, #38 — see §4).

Key files

• src/dsl/command.rs — AppCommand::Hint.
• src/dsl/grammar/app.rs — HINT node + build_hint.
• src/dsl/grammar/mod.rs — the hint_ids field, hint_key_for_input_in_mode, the factored pick_form_key, and the two comprehensiveness coverage tests (every node has a resolving hint.cmd.*; every runtime error class has a hint.err.*).
• src/app.rs — F1 arm in handle_key (read-only overlay, placed before the completion-memo clear); note_hint_for_input / note_hint_for_recent_error / note_getting_started / emit_tier3_block; last_error_hint_key state (set in handle_dsl_failure, cleared in submit for DSL commands).
• src/friendly/translate.rs — error_hint_class (maps a DbError + ctx to its hint.err.<class>; mirrors translate's dispatch — keep in sync, unit-tested).
• src/friendly/strings/en-US.yaml + keys.rs — the corpus under hint.cmd.<form> / hint.err.<class> + hint.block.* labels + shortcut.hint.
• src/ui.rs — ADR-0051 strip advertises F1 (editing + default states); 12 full-panel snapshots re-accepted.

Phases (one commit each unless noted)

• A (050b363) skeleton + tier-2 fallback; B (4a5fd1b) per-form keying + 3 exemplars; C content in 5 batches (4bdfce6 app, 6429b56 DDL, 9c4d520 DML, 97970f2 advanced-SQL, b6b98ad runtime errors) + 417cbc8 diagnostic deferral; D (447112b) coverage gate
  • F1 strip + status flips; /runda fix (329adfc) — see §3.1.

3.1 — what the final /runda caught (don't skip)

Per-batch substring tests masked a presentation gap: emit_tier3_block was emitting three bare, unlabelled lines, deviating from the approved exemplar format. Fixed to render a Hint heading + aligned What: / Example: / Concept: lines, locked by an insta snapshot (hint_block_insert). Also confirmed the Next: line (ADR D2 exemplar) is correctly omitted — tier-2 ambient already owns live position-awareness. Lesson for the next content/UI work: add a rendered snapshot early; substring asserts don't see layout.

§4. Deferrals (all tracked, all user-confirmed)

• #38 diagnostic route + diagnostic.* blocks — Diagnostic (walker/outcome.rs) carries only its rendered message, not a class key, so the F1 diagnostic route would need a class field threaded through every diagnostic site (broad) for marginal value (tier-2 already surfaces diagnostics; many duplicate runtime classes). F1 still shows the useful command block when a diagnostic is present.
• #37 clause-concept hints — per-form is the right tier-3 granularity; clause-level concepts are a separate hint.concept.<topic> layer for later.
• #36 help advanced-SQL — out of H2's scope (touches shipped help).

§5. CI branch merged into main (not my work)

Mid-session the ci branch was merged (commits 47a0816, 138e766

• the ci:/build:/docs(ci): commits). main now carries a CI pipeline, a nix flake, and D1 cross-platform release builds (matrix + macOS), documented under a new docs/ci/adr/ namespace (ci-001..003). Implications for the roadmap: D1 (cross-platform binaries) is now substantially underway — re-assess D1/D2/D3 status against what landed before treating them as open. My H2 work is layered cleanly on top (all green post-merge).

§6. Next session — start here

1. Push (user step) — 30-odd local commits incl. the CI merge + all of H2.
2. Re-baseline the roadmap against the merged CI work: D1/D2/D3 and TT5 CI are partly/largely done now — read docs/ci/adr/ and the workflows before assuming they're open (handoff-69 §5 predates this).
3. #35 (cargo fmt gate) is the natural pairing with the now-merged CI — the user wanted it done once, before first publication.
4. Other requirements.md open items (verify against CI merge first): TT4 PTY tier-4 (still unwired), I1 multi-line input, I5/B3 in-flight cancellation, V4 session journal (own ADR), TU1 tutorial system (own ADR). H2/A1 are now done.
5. The H2 deferrals (#36/#37/#38) are available if the user wants to round out the hint/help surface.

§7. How to take over

1. Read handoffs 68 → 69 → 70, CLAUDE.md, docs/requirements.md.
2. Confirm green: cargo test (expect 2499 pass / 1 ignored) + cargo clippy --all-targets (clean).
3. Read docs/ci/adr/ (the merged CI work) before touching CI/release/D*.
4. For anything in the hint area, read ADR-0053 first (3 revisions
   • deferrals #37/#38). For journaling, ADR-0052 (+ its 2026-06-14 follow-up note).
5. Project workflow unchanged: phased, test-first, /runda + DA before commits, ADR amendment + README index-upkeep for decided-area changes, confirm commit messages with the user.
6. Consider a cargo sweep at this milestone (target/ grows; see CLAUDE.md "Build hygiene").