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

# Session handoff — 2026-06-15 (71)

Short, focused handover. Continues immediately from handoff-70 (which
shipped H2 / the contextual `hint`, ADR-0053). **A user smoke-test
surfaced a correctness bug in the hint content, and it implicates the
whole corpus.** This handoff exists so the next session does a
**systematic semantic verification pass over every hint block** — context
ran too low to do it now.

## §1. State

**Branch:** `main`, clean, all committed (local; push pending). **2499
pass / 1 ignored, clippy clean.** Open issues: #35–#38 (see handoff-70).
H2 / ADR-0053 is *functionally* complete; the **content is not
trustworthy** until the pass below is done.

## §2. The bug (confirmed)

`hint.cmd.create_table` (in `src/friendly/strings/en-US.yaml`) reads:

```
What:    Create a new table — its columns, their types, and a primary key.
Example: create table Customers with pk id(serial), name(text), email(text)
Concept: A table is a set of rows that share the same columns. The primary
         key uniquely identifies each row; a `serial` key numbers the rows for you.
```

**This is wrong.** In the DSL, **everything after `with pk` is the
primary-key column list** (a possibly *compound* PK, ADR-0005). So the
example does **not** create a table with `pk=id` plus regular columns
`name`/`email` — it creates a table whose **compound primary key is
(id, name, email)**. Non-key columns are added *separately* with
`add column`. The `what` ("its columns, their types") and the example
both mislead a learner badly.

- **Evidence:** real test usage is `create table Orders with pk
  id(serial), CustId(int)` (a 2-column *compound PK*) and the common form
  `create table X with pk id(int)` (single-column PK only). The usage
  template `create table <Name> with pk [<col>(<type>)[, ...]]` is itself
  misleading — the `[, ...]` is the PK list, not regular columns.
- **Correct mental model:** `create table <T> with pk <pk-cols…>` then
  `add column <T>: <name> (<type>)` for each non-key column. Confirm
  against ADR-0005 (compound PK) and ADR-0009 (DSL syntax) when fixing.

## §3. Root cause — why this needs a *full* pass

During Phase C I verified *some* examples against `parse.usage.*`
templates and real test greps, but for others I **extrapolated** beyond
verified syntax. For `create_table` I saw `... with pk id(int)` (single
col) and wrongly generalised to "pk + more columns," misreading the
`with pk` list as a column list. The examples are **syntactically**
checked but not **semantically** — i.e. not verified to *do what the
`what`/`concept` claims*.

So the corpus needs a pass that, for **every** `hint.cmd.*` and
`hint.err.*` block, checks:
1. the `example` parses **and runs**, and
2. it actually demonstrates what `what`/`concept` says, and
3. `what`/`concept` are factually true of the real behaviour.

**Don't trust grep+extrapolation.** Prefer: run the example in the app
(or a Tier-3 test), or check it against the authoritative ADR.

## §4. The pass — how to do it (next session)

The corpus lives in `src/friendly/strings/en-US.yaml` under `hint.cmd.*`
(per command form) and `hint.err.*` (per runtime error class). The
inventory and authoritative syntax sources:

- **`hint.cmd.<form>`** — for each, cross-check the example against the
  matching `parse.usage.<form>` template **and** the form's ADR, and run
  it. Highest-risk (extrapolated, verify first): **DDL** — `create_table`
  (known wrong), `add_column`, `add_index`, `add_constraint`,
  `change_column`, `drop_*`, `create_m2n`; **advanced-SQL** — confirm
  each is in the supported SQL subset (`select`, `with` CTE,
  `sql_insert/update/delete`, `sql_create_table`, `sql_alter_table`,
  `sql_create_index/drop_index/drop_table`, `explain_sql`); **DML** —
  `seed` forms, `explain`, `show_*`, `update`/`delete` (`--all-rows` /
  required-WHERE wording). App commands are lower-risk (reference-style).
- **`hint.err.<class>`** — verify the fix recipe in `example` is actually
  the right remedy and `concept` matches the engine's real behaviour
  (FK sides, `on delete` actions, check/not_null/unique semantics).
- Relevant ADRs: 0005 (types + compound PK), 0009 (DSL syntax), 0011 (FK
  type compat), 0013 (relationships/rebuild), 0014 (data ops +
  required-WHERE), 0025 (indexes), 0028/0039 (explain), 0030–0036 (SQL
  subset), 0048 (seed). `docs/requirements.md` for scope.

**Suggested method:** drive the app (`/run` or a small PTY/Tier-3 harness)
and actually execute each example; or add a test that parses+runs every
`hint.cmd.*` example and asserts success. The latter would also be a
durable regression guard — consider adding it as part of the pass (it
upgrades the comprehensiveness coverage test from "a block exists" to
"the example actually works").

## §5. Immediate fix ready to apply

`create_table` is diagnosed (§2). The corrected block should make the
example a PK-only `create table` and move the regular columns to a
follow-up `add column`, e.g.:

```
What:    Create a new table with its primary key.
Example: create table Customers with pk id(serial)
Concept: A table is a set of rows sharing the same columns. `with pk`
         declares the primary key (one column, or several for a compound
         key); add the other columns afterwards with `add column`.
```

Apply this (and re-check `create_m2n` / `add_*` while there), but only as
part of the systematic pass — a one-off fix risks leaving siblings wrong.

## §6. How to take over

1. Read handoffs 70 → 71, `CLAUDE.md`.
2. Confirm green: `cargo test` (2499 / 1 ignored), `cargo clippy
   --all-targets`.
3. Do the §4 pass (consider the run-every-example test in §4). Test-first,
   `/runda` before commit, confirm the commit message with the user.
4. Pedagogy wins — these are teaching strings; correctness and clarity
   over cleverness.