rdbms-playground/docs/handoff/20260515-handoff-14.md

# Session handoff — 2026-05-15 (14)

Fourteenth handover. This session cleared the remaining
handoff-12 backlog: every §2.1 carry-forward and the §2.2
deferred items. Eight focused commits, each a deliberate
decision the user signed off on.

**Headline: the handoff-12 §2 catalogue is now empty of
actionable items, and ADR-0024 is confirmed fully
implemented.** The two items §3 originally flagged are both
resolved. The next session's work is the product roadmap in
`docs/requirements.md` (reconciled this session) — see §4.

## State at handoff

**Branch:** `main`. Working tree clean. `origin/main` is at
`42cf851` (handoff-13); local HEAD is **8 commits ahead** — this
session's work, unpushed (the user pushes asynchronously).

Commits since handoff-13:

```
50b7825 Remove dead parse.token.* catalog entries
bcc5ad2 Matrix: pin natural candidate ordering
f1ff597 Hint: pedagogical Form-A pointer at Form B's first value slot
911a537 Walker: node-attached HintMode via Node::Hinted
9bbb96e Walker: memoize DynamicSubgrammar resolution to bound the Box::leak
90e3f5d Insert grammar: Form C type-awareness via lookahead
f46606b Runtime: schema-aware replay parsing
03dd900 Help: consume CommandNode.help_id — REGISTRY-driven in-app help
```

**Tests:** **1006 passing, 0 failing, 1 ignored** (up from 989).
The ignored test is the long-standing `` ```ignore `` doc-test
in `src/friendly/mod.rs`.

**Clippy:** clean with `nursery` lints + `-D warnings`.

## §1. What shipped — handoff-12 backlog cleared

### Dead `parse.token.*` catalog entries removed (50b7825)

The 5 structural-class + 3 lex-error entries handoff-12 §2.1
listed as unreachable are gone (catalog YAML + `keys.rs`).

### Ranker / natural candidate ordering (bcc5ad2)

The user's actual ranker need — `to` before `table` so
`add column to table T` reads in order; keywords before schema
identifiers — **already worked** via declaration-order
preservation + keywords-first sectioning in
`candidates_at_cursor`. Nothing pinned it; 8 matrix tests in
`tests/typing_surface/candidate_ordering.rs` now do. See §3 for
the `Ranker` *type* itself.

### serial/shortid pedagogical Form-A hint (f1ff597)

handoff-12 §2.2: at the first value slot of `insert into T
values (…)` for a table with auto-generated columns, the hint
now appends "(`id` auto-generated — skipped here; list columns
explicitly … to set it)". `hint_resolution_at_input` derives
the skipped columns from the post-walk `WalkContext` (Form B =
no `user_listed_columns` + table has serial/shortid columns);
the note fires only at the first slot. New
`HintResolution::form_b_autogen_skipped`, catalog key
`hint.value_slot_autogen_skipped`.

### Node-attached HintMode (911a537)

handoff-12 §2.1: the hint resolver's signature-matching (does
the expected set contain all five literal forms? an
`Ident{NewName}`?) is replaced by a grammar-declared
annotation. New `Node::Hinted { mode, inner }` wrapper; the
walker records the mode in `WalkContext::pending_hint_mode` on
entry and clears it on **any successful match** (the cursor
moved past the slot — this also undoes the leak where a failed
`Hinted` branch of a `Choice` would strand a stale mode). The
resolver reads `pending_hint_mode` directly.

Mechanism note: handoff-12 sketched threading `HintMode` through
the `Expectation` enum. ADR-0024 §HintMode only says "nodes
carry `HintMode`, the walker propagates it" — mechanism-
agnostic. The `WalkContext::pending_hint_mode` route (mirroring
the existing `pending_value_type`) was chosen as lower-risk; the
user was told and did not object.

### DynamicSubgrammar memoization (9bbb96e)

handoff-12 §2.1's `Box::leak`-per-walk. The handoff's arena
sketch was unworkable (it needs a lifetime-generic `Node` — a
major refactor). Instead `resolve_dynamic` memoizes factory
output on the schema state the factory reads (keyed by factory
fn-pointer + ctx fields). Each distinct value-list shape leaks
**once** — total leak bounded by distinct (schema × form)
combinations, not keystroke count. `TableColumn` gained `Hash`.

### Form C type-awareness (90e3f5d)

handoff-12 §2.2. Form C (`insert into T (vals)`) shared the `(`
opener with Form A, so its values weren't typed. The
explicit-`Choice`-branch split is impossible (committed-choice
semantics commit after `(` matches), so a new
`Node::Lookahead(fn(&WalkContext, &str, usize) -> Node)`
variant peeks the source: a value-literal first token routes
the paren through the typed `column_value_list` (Form B
dispatch contract); an identifier or empty paren routes to a
Form A column-name list. Form C values are now type- and
count-checked at parse time. `insert into T (` cleanly shows
Form A column candidates instead of mixed Form-A/C suggestions.

### Schema-aware replay (f46606b)

handoff-12 §2.1: `run_replay` parsed schemalessly. It now
re-snapshots the schema per line (extracted `build_schema_cache`,
shared with the interactive path) and parses with
`parse_command_with_schema` — typed-slot rejections fire at
replay parse time, matching interactive. New integration test
`replay_rejects_typed_slot_violation_at_parse_time`.

### help_id consumption (03dd900)

handoff-12 §2.1: every `CommandNode` declared an unused
`help_id`. `note_help` now iterates the command `REGISTRY` and
translates each `help_id` — a new command appears in `help`
automatically. 20 per-command catalog entries + 3 framing
entries; `help.in_app_body` removed. `CommandNode.help_id` lost
its `#[allow(dead_code)]`.

## §2. Bug found this session

**`libyml` 0.0.5 scanner panic on long space runs in
double-quoted YAML scalars.** While authoring the help entries,
a space-aligned double-quoted catalog string
(`"quit          — exit"`) panicked the YAML scanner with
"String join would overflow memory bounds". Block scalars
(`|-`) are unaffected — that's why the old block-scalar help
worked. Bisected and worked around: all per-command help
entries use `|-`. **If you author new catalog entries, avoid
long internal space runs in double-quoted (`"…"`) values — use
a block scalar or keep runs short.** A catalog comment in
`en-US.yaml` records this.

## §3. Flagged items — both now resolved

Both items this section originally flagged were ruled on by
the user after the main work:

**3.1 The `Ranker` type — KEEP.** `completion::Ranker` /
`candidates_at_cursor_with` have no production caller passing a
non-identity ranker (the candidate-ordering need is met by
declaration-order preservation). The user ruled: **keep it** —
it is intentional scaffolding for future frequency / content-
aware ranking (ADR-0024 §"out of scope" explicitly anticipates
this). No longer an open question.

**3.2 `CommandNode.hint_mode` — REMOVED.** The per-command
`hint_mode` field predated the node-attached HintMode work and
was read by nothing. Removed (field + 20 `None` initialisers)
in commit `6d2b929`.

## §4. What's next — the standing roadmap

**handoff-12 §2's backlog is cleared, and ADR-0024 is
confirmed fully implemented** (audited this session — Phases
A–F done; Phase F shipped "minimal" with `parser.rs` retained
as the router, now recorded in an ADR-0024 implementation
note). There is no migration or carry-forward debt left.

**The next session's work is the product roadmap, tracked in
`docs/requirements.md`** — reconciled this session against
what handoffs 10–14 actually built (test baseline refreshed to
1006; `U4` replay marked satisfied; `A1` / `H1a` / `H3`
progress notes corrected). `requirements.md` is now the
trustworthy "what's open" tracker — read it, not the
(coarser) `CLAUDE.md` "Things deliberately deferred" list.

Notable open clusters in `requirements.md` (prioritisation is
a **user product decision** — do not pick unilaterally):

- **Indexes** (`C3` partial) — `add index` / `drop index`,
  then `EXPLAIN QUERY PLAN` rendering (`QA1`). Self-contained.
- **Complex WHERE expressions** (`C5a`, `[~]`) — AND/OR /
  comparison / LIKE in UPDATE/DELETE/show-data filters. Needs
  an ADR. The bridge from DSL toward real SQL.
- **SQL in advanced mode** (`Q1`/`Q4`, `[~]`) — `sqlparser-rs`
  + a defined subset. Needs an ADR.
- **Snapshot / undo** (`U1`/`U2`) — designed in ADR-0006, not
  built. (`replay`, `U4`, is now done.)
- **m:n convenience** (`C4`), **modify relationship** (`C3a`,
  `[~]`), **table rename** (`C1`).
- **Friendly error layer** (`H1`) — partial; full SQL→English
  translation pending. **Syntax-help in parse errors**
  (`H1a`) — piecemeal so far.
- **Session log + Markdown export** (`V4`, `[~]`),
  **multi-line input** (`I1`), **readline shortcuts**
  (`I1b`), **seeding** (`SD1`), **CI** (`TT5`),
  **tutorial system** (`TU1`, `[~]`).

Two handoff-13 items the user already **accepted** (not work,
just recorded):

- **Partial entry words classify as `DefiniteErrorAt`**
  (handoff-13 §3) — documented by the matrix test
  `app_commands::partial_entry_word_classifies_as_definite_error_but_completes`.
- **Matrix scope** (handoff-13 §4) — cursor coverage is
  "meaningful transitions" not every byte offset; assertion (5)
  is parse-layer, not a live dispatch differential.

## §5. Architectural delta (vs. handoff-13)

### New `Node` variants

- `Node::Hinted { mode: HintMode, inner: &'static Node }` —
  node-attached hint-mode annotation.
- `Node::Lookahead(fn(&WalkContext, &str, usize) -> Node)` —
  source-aware dynamic subgrammar (Form A/C discrimination).

### New `WalkContext` field

- `pending_hint_mode: Option<HintMode>` — set on `Hinted`
  entry, cleared on any match.

### Walker driver

- `walk_node` split into a wrapper (clears `pending_hint_mode`
  on match) + `walk_node_inner` (the dispatch).
- `resolve_dynamic` + `DYNAMIC_CACHE` — memoized
  `DynamicSubgrammar` resolution.
- `Node::Lookahead` arm — not memoized (source-dependent),
  returns a small node.

### New API surface

- `input_render::classify_input_with_schema` (added handoff-13,
  noted here for completeness).
- `HintResolution::form_b_autogen_skipped: Vec<String>`.
- `runtime::build_schema_cache` (extracted from
  `refresh_schema_cache`).

### Catalog

- Removed: `parse.token.*` (×8), `help.in_app_body`.
- Added: `hint.value_slot_autogen_skipped`,
  `parse.custom.insert_form_a_missing_values` (handoff-13),
  `help.intro` / `help.dsl_section` / `help.types_reference`,
  `help.{app,ddl,data}.*` (×20).

### Post-handoff cleanup (this section's work)

After the eight items above, three follow-ups landed:

- `CommandNode.hint_mode` field removed (commit `6d2b929`) —
  see §3.2.
- ADR-0024 amended with a "Phase F minimal" implementation
  note (`parser.rs` retained as the router); `docs/adr/README.md`
  index line updated to match.
- `docs/requirements.md` reconciled — see §4.

## §6. How to take over

1. **Read this file, then handoff-13, then 12** for the chain.
2. **Read `CLAUDE.md`** — the working-style rules. This session
   escalated every ambiguous fork (HintMode mechanism, the
   `Box::leak` arena's true cost, the Form C restructure twice)
   rather than deciding unilaterally.
3. **Read `docs/requirements.md`** — reconciled this session;
   it is the authoritative "what's open" tracker (§4).
4. **Run `cargo test`** — 1006 passing, 0 failing, 1 ignored.
5. **Run `cargo clippy --all-targets -- -D warnings`** — clean.
6. **Pick the next work from §4 / `requirements.md`** — but
   prioritisation is a user product decision; ask, don't
   assume. handoff-12's backlog and ADR-0024 are both fully
   done — there is no carry-forward debt.

### Note on the typing-surface matrix

`tests/typing_surface/` (now 144 cells) is the regression net
for everything walker/hint/completion. After any grammar or
walker change: a failing matrix cell with *correct* new
behaviour → update its snapshot
(`INSTA_UPDATE=always cargo test --test typing_surface_matrix
<family>`); a failing cell with *wrong* behaviour → the cell
earned its keep. The Form C type-awareness work this session
was guarded entirely by it.