rdbms-playground/docs/handoff/20260611-handoff-66.md

# Session handoff — 2026-06-11 (66)

Sixty-sixth handover. Continues from handoff-65 (ADR-0048 `seed`
Phase 1). This session built **ADR-0048 Phase 2** end to end: the
**`set` override clause** (D2) and the **`<table>.<column>`
column-fill** form (D1 form 2) — the two surfaces Phase 1 deliberately
deferred. Designed-then-DA-vetted (a `/runda` pass that caught a real
ADR-vs-grammar conflict), then built test-first.

## §1. State at handoff

**Branch:** `main`. All Phase-2 work is in the working tree;
**commits are pending the user's approval** (see §6). Unpushed is the
normal working state.

**Tests: 2400 passing / 0 failing / 0 skipped / 1 ignored** (the
long-standing `friendly` doctest). **Clippy clean** (nursery, all
targets). +42 over handoff-65's 2358.

## §2. What landed (read ADR-0048 — Status + D1/D2/D9/D13)

`seed <T>[.<col>] [count] [set <overrides>] [--seed <n>]`.

- **`set` override clause (D2):** four forms, comma-separated —
  `status = 'active'` (fixed), `role in ('a','b')` (pick-list),
  `work_addr as email` (named generator), `price between 10 and 100`
  (range; numeric **and quoted dates**). Type-aware; an override
  **drops its column from the generic-fill advisory** (D13). Value
  slots reuse `update`'s typed `current_column_value` (quoting
  enforced structurally — a bare word is rejected).
- **Column-fill (D1 form 2):** `seed users.email [set …]` fills one
  column across **existing** rows (an UPDATE). Refuses PK / autogen
  (`serial`/`shortid`/`blob`) targets; **empty table → friendly
  no-op**; FK target samples the parent; UNIQUE/identifier target gets
  collision-free values; **one undo step**; `set` may only adjust the
  filled column; a row count is refused.
- **Named-generator vocabulary (D9):** `src/seed/vocabulary.rs` —
  `KNOWN_GENERATORS` + `generator_for_name` + `is_known_generator_prefix`,
  the single source of truth for completion, validity, and the executor.
- **Range generator:** `Generator::Range { low, high }` in
  `src/seed/generators.rs`, interpreted per destination type;
  `range_bounds_reason` validates compatibility before generation.
- **Ambient wiring:** completion (generator names after `as`, the
  `set <col>` and `.col` column slots, the `set` keyword); highlight
  (new `HighlightClass::Function` → existing `tok_function`); validity
  (new `IdentSource::Generators` — unknown generator flagged `[ERR]`;
  unknown column in `set`/`.col` flagged via the existing Columns
  path); help (`help.data.seed`); parse-error pedagogy near-miss rows;
  the D13 advisory's **Phase-2/3 wording** (points at `set` and the
  column-fill repair). Both modes (D5).

## §3. The ADR amendment (a real DA find)

The pre-build `/runda` pass found that **ADR-0048 D2's "dates stay
unquoted" was impossible** — this DSL has **no date-literal token**
(`Value` is `Number`/`Text`; dates are quoted strings validated by
`bind_date`). Escalated to the user, who chose **quoted dates +
amend the ADR** (the grammar-consistent option). D2 now carries a
dated amendment; the range form uses `between '2023-01-01' and
'2024-12-31'`. This was the only divergence from the ADR text; numbers
remain unquoted.

## §4. Where the code lives

- **`src/dsl/command.rs`** — `Command::Seed` gains `target_column:
  Option<String>` + `overrides: Vec<SeedOverride>`; new `SeedOverride`
  / `SeedOverrideKind`.
- **`src/dsl/grammar/data.rs`** — `SEED_SET_CLAUSE` + `SEED_DOT_COLUMN`
  grammar; `SEED_GENERATOR` slot (`IdentSource::Generators`,
  `HighlightClass::Function`); `build_seed` + the override fold
  (`build_seed_overrides` / `parse_seed_override_tail`).
- **`src/dsl/grammar/mod.rs`** — `IdentSource::Generators` +
  `HighlightClass::Function`.
- **`src/db.rs`** — `apply_seed_overrides` / `seed_override_plan` /
  `seed_override_literal`; `do_seed_column_fill`; `do_seed` +
  `Database::seed` + worker wiring threaded with the new params.
- **`src/seed/`** — `vocabulary.rs` (new); `generators.rs` (range
  generator + `range_bounds_reason`); `mod.rs` (`Generator::Range`).
- **`src/completion.rs`** — generator candidates after `as`; generator
  validity. **`src/input_render.rs`** — `"generator"` invalid-ident
  kind. **`src/theme.rs`** — `Function → tok_function`.
- **Catalog** — `help.data.seed`, `parse.usage.seed`,
  `seed.advisory_generic` (Phase-2/3 wording) in `en-US.yaml`;
  `keys.rs` placeholders updated.
- **Tests** — `tests/it/seed.rs` (+~30: builder fold, executor
  set/column-fill, undo, advanced mode), `src/seed/{vocabulary,
  generators}.rs` (range + vocabulary units), `src/completion.rs`
  (generator + column validity), `src/dsl/walker/highlight.rs`,
  `tests/typing_surface/mod.rs` (completion slots),
  `tests/it/parse_error_pedagogy.rs` (near-miss rows).

## §5. Two implementation refinements vs. the ADR (both met the contract)

- **Quoted dates** (the D2 amendment, §3).
- **Value slots reuse `current_column_value`** (the `update … set`
  typed slot) rather than the raw ADR-0026 expression operand — no
  spurious column-ref match, typed narrowing, consistent with
  `update`. The user-facing contract (quoted literals, type-aware) is
  fully met.

The `seed_take_value` / `seed_set_error` builder paths are
drift-guards (the typed slots only ever match value literals, so a bare
word is rejected at the grammar level) — they use the generic
`parse.error_wrapper`, mirroring `expr::build_expr`.

## §6. How to take over / next steps

1. Read handoffs 64 → 65 → 66, `CLAUDE.md`, `docs/requirements.md`,
   `docs/adr/0048-…md` (Status block + D1/D2/D9/D13 + the amendment).
2. **Seed is feature-complete (SD1 + SD2).** `requirements.md`: **SD1
   `[x]`, SD2 `[x]`**. The only open A1 gap is `hint`/**H2** (own ADR).
3. **Commits pending approval.** Suggested split:
   - `feat(seed): set override clause + column-fill (ADR-0048 Phase 2)`
     — all `src/` + `tests/` changes.
   - `docs: ADR-0048 Phase 2 implemented + handoff 66` — ADR / README /
     requirements / this file.
4. Next options (user's call): **H2 `hint`** (closes A1); **TT5 CI**;
   the larger **V4 journal** / **tutorial** ADRs; or Tier-4 PTY (TT4).
5. Consider a `cargo sweep` at this milestone (`target/` grows).

## §7. Post-implementation `/runda` pass (done this session)

A DA pass over the completed code found **no correctness bugs and no
dropped requirements**; all D1–D18 acceptance criteria verified met,
tests confirmed to catch regressions. One **design fork** was surfaced
and **resolved by the user**:

- **Bounded override × UNIQUE column** — a fixed value / too-short
  pick-list on a single-column-UNIQUE target used to silently cap the
  run (e.g. `seed users 100 set email = 'x'` → 1 row). Now a **friendly
  error** up front (`seed_override_capacity_guard`, `src/db.rs`), for
  both whole-row and column-fill; generators/ranges stay cap-based
  (unbounded sources). ADR-0048 D2 documents it; two tests pin it.

Remaining **non-blocking** edges (noted, not bugs):

- Overriding an **FK column** with a literal: the override wins (D2); a
  non-parent value fails safely through the FK-error layer.
- **Column-fill of one column of a *compound* FK** samples that column
  independently → an invalid tuple fails safely (UPDATE rejected,
  rollback), never corrupts. Single-column FKs / non-FK columns are
  exact.
- The generator slot uses the **default candidate-ladder hint** (offers
  the vocabulary), not a dedicated prose intro — discoverability is met
  by completion; a prose intro is optional polish.