rdbms-playground/docs/handoff/20260524-handoff-36.md

# Session handoff — 2026-05-24 (36)

Thirty-sixth handover. This session **implemented ADR-0006
(undo/snapshot) end-to-end** (§8 steps 1–8 + a `/runda` data-loss
fix) and then **drafted ADR-0035 — advanced-mode SQL DDL** (Phase 4
of the ADR-0030 roadmap, status **Proposed**). The next session
**begins implementing ADR-0035, starting at sub-phase 4a**. See §4.

## §1. State at handoff

**Branch:** `main`. **Tests: 1698 passing, 0 failing, 0 skipped,
1 ignored** (the unchanged `friendly/mod.rs` doctest). **Clippy:**
clean (`cargo clippy --all-targets -- -D warnings`).

**Latest commit (local-only):**

```
a079200 docs: ADR-0035 — advanced-mode SQL DDL (Phase 4)
```

`origin/main` is at `df6aa69`; **1 commit is local-only** (a079200).
The undo/snapshot work (through `df6aa69`) is already pushed.
Unpushed commits are a normal working state; pushing is the user's
step — do not prompt about it.

## §2. What shipped this session

- **ADR-0006 (undo/snapshot) fully implemented** — the U1/U2 half;
  the replay/journal half (U3/U4) had shipped via ADR-0034. Built
  across §8 steps 1–8 of the plan
  (`docs/plans/20260524-adr-0006-undo-snapshots.md`):
  - `src/undo.rs` — `SnapshotStore`: a persisted undo ring + redo
    stack under `<project>/.snapshots/` (`index.yaml` + per-snapshot
    payload dirs). Hybrid whole-project snapshot — db via the online
    backup API + `project.yaml`/`data/*.csv` copied; restore is
    text-first, db-last (ADR-0015 §6).
  - `src/db.rs` — `snapshot_then` brackets all **19 mutating dispatch
    arms** (stage→run→finalise/discard), gated on a **user command
    `source`** (internal ops like open-time rebuild are *not*
    snapshotted); `BeginBatch`/`EndBatch` (a `replay`/batch = one undo
    step); `Undo`/`Redo`/`PeekUndo`/`PeekRedo` handled in
    `worker_loop` with `&mut conn`.
  - `undo`/`redo` app commands + `Modal::UndoConfirm` confirm flow;
    `--no-undo` CLI flag; `.snapshots/` git-ignored + export-excluded
    + temp-cleanup-allowlisted.
  - **`/runda` found + fixed a silent data-loss bug**: a committed
    mutation whose snapshot couldn't be *staged* left the redo stack
    stale (redo-clear was a side effect of `finalize`), so a later
    `redo` discarded the new work. Now `clear_redo` runs on that path
    (`snapshot_then`/`end_batch`); commit `df6aa69`, regression-tested.
  - ADR-0006 marked implemented (Amendment 1 + Implementation note);
    `requirements.md` U1/U2 → `[x]`; `CLAUDE.md` updated.
- **ADR-0035 drafted** (`docs/adr/0035-advanced-mode-sql-ddl.md`,
  commit `a079200`, **Proposed**) — the next job (§3/§4).

## §3. ADR-0035 design — settled with the user (do not re-litigate)

All user-confirmed through discussion this session.

1. **Own per-statement `Sql*` DDL commands** — `SqlCreateTable`,
   `SqlAlterTable`, `SqlDropTable`, `SqlCreateIndex`, `SqlDropIndex`
   (granularity mirrors the DML `Sql*` set). **Clarifies ADR-0030 §4**:
   DDL gets its own advanced commands, but **unlike DML they execute
   *structurally*, not verbatim** — raw execution would lose the
   playground's types, named relationships, and `STRICT`. ("Verbatim"
   for DML was a convenience, not a rule.) **Simple mode is untouched**
   (additive). Handlers **reuse the low-level schema/metadata helpers**
   where the op matches simple mode, **stand alone where the SQL
   surface is richer** (multi-FK `CREATE TABLE`) — clarity over forced
   refactoring.
2. **Dispatch:** `create`/`drop` reuse ADR-0033 Amendment 1's
   category-grouped, mode-aware dispatch (SQL-first in advanced, simple
   fallback); **`alter` is a new advanced-only entry word.**
3. **Type vocabulary** (ADR-0030 §5): playground keywords + standard-SQL
   aliases mapped (`integer`→`int`, `varchar`→`text`, `timestamp`→
   `datetime`, …); length args accepted-and-ignored; no engine type
   names in/out.
4. **FK → named relationships:** inline `REFERENCES` + table-level
   `FOREIGN KEY` create the table **and** its relationship metadata in
   one command (= **one undo step**); `ON DELETE`/`ON UPDATE` →
   ADR-0013 actions; constraint name → relationship name.
5. **Column-type conversion — unified** (ADR-0017 engine, mode policy):
   clean auto-converts both modes; incompatible + own-type-static cases
   refuse both modes; **lossy refuses-by-default in simple mode
   (`--force-conversion`), but advanced mode performs it with a post-op
   loss note and relies on `undo` as the net** (no force flag, no
   dropping to simple mode).
6. **Table rename (`C1`)** — advanced-only `ALTER TABLE … RENAME TO`;
   **new low-level op** (rename table + its CSV file + the relationship
   metadata rows). No simple-mode form.
7. **Surface** = full, no pre-emptive cuts; **9 sub-phases 4a–4i**
   (ADR §13), each with exit + DA gates.
8. **Integration is structural, not free of authoring** (ADR §11):
   the walker *mechanisms* (highlighting, `[ERR]`/`[WRN]`, usage
   skeleton, completion engine) come free; each node still **authors**
   the right `IdentSource` on schema-name slots, its hint/usage catalog
   keys, and DDL-specific walker diagnostics (the DDL peers of the DML
   ones ADR-0033 added).
9. **Replay:** `create`/`drop`/`alter` are schema-write entry words,
   **not** in ADR-0034's app-lifecycle skip set, so SQL DDL **replays
   as a write — no replay-filter change** (unlike `undo`/`redo`).

## §4. ADR-0035 implementation — the NEXT job

**Begin Phase 4 at sub-phase 4a**, test-first, following the ADR-0033
sub-phase model. **Recommended first action:** read ADR-0035 in full,
then write a short plan doc
(`docs/plans/<date>-adr-0035-sql-ddl.md`) and confirm any open
micro-calls with the user before coding — exactly how ADR-0033/0034/
0006 were run.

**Sub-phases (ADR-0035 §13):**

- **4a** — dispatch + `CREATE TABLE` core (columns + the §3 type map +
  column constraints + single/compound `PRIMARY KEY`); no FK yet.
- **4b** — FK in `CREATE TABLE` (inline + table-level) → relationships.
- **4c** — `DROP TABLE`.
- **4d** — `CREATE [UNIQUE] INDEX` / `DROP INDEX`.
- **4e** — `ALTER TABLE` add/drop/rename column.
- **4f** — `ALTER TABLE … ALTER COLUMN TYPE` (the §7 conversion model).
- **4g** — `ALTER TABLE` add/drop constraint, add FK.
- **4h** — `ALTER TABLE … RENAME TO` (the §6 new low-level op).
- **4i** — verification sweep (typing-surface/matrix, engine-neutral
  errors, undo parity, `help`/usage).

**Concrete must-not-forget for the implementer:**

- **Undo wiring for the new commands.** Each `Sql*` DDL command becomes
  a **new `Request` variant in `src/db.rs`** and **must be wrapped with
  `snapshot_then`** like the existing 19 mutating arms (so it's one undo
  step). `handle_request`'s exhaustive match will force you to handle
  each new variant — wrap it, don't `reply.send` it raw. `create`/
  `drop`/`alter` need **no** `is_app_lifecycle_entry_word` change
  (they're writes, §3.9).
- **Grammar lives in `src/dsl/grammar/`** (`CommandNode` + the
  `REGISTRY` in `mod.rs`, tagged `CommandCategory`); mirror the
  ADR-0033 DML nodes (`src/dsl/grammar/sql_*`). `CHECK`/`DEFAULT`
  expressions reuse the ADR-0031 `sql_expr` fragment.
- **`ALTER`/column ops build on the ADR-0013 rebuild-table primitive**
  (already used by drop/rename/change-column).
- **Catalog + keys lockstep** (`src/friendly/strings/en-US.yaml` +
  `src/friendly/keys.rs`, validated by `keys_validate_against_catalog`):
  every new `help_id`/`usage_id`/diagnostic key needs both a catalog
  body and a keys.rs entry; engine-neutral wording (the vocab audit
  enforces it).
- **Tests:** four tiers (ADR-0008). Per-sub-phase Tier-3 like
  `tests/sql_insert.rs`/`sql_update.rs`/`sql_delete.rs`, plus an
  end-to-end `tests/sql_ddl_e2e.rs` (mirror `sql_dml_e2e.rs`), plus
  typing-surface/matrix coverage. **Add a DDL undo test** (each
  statement = one undo step; `CREATE TABLE` with FK = one step).

**Open micro-calls to escalate when reached** (not yet decided):

- `CREATE UNIQUE INDEX` — ADR-0025's index model may need a `unique`
  flag (ADR §4/§13 4d flags this).
- Exact `ALTER COLUMN … TYPE` spelling, and whether `IF [NOT] EXISTS`
  is admitted or an ordinary parse error (ADR §12 leans OOS).
- Status flip: ADR-0035 is **Proposed**; flip to **Accepted** once 4a
  validates the path end-to-end (the ADR-0033 lifecycle).

## §5. Other tracked deferred items (nothing lost)

- **(A)** App-lifecycle-command *runtime*-failure journalling (small
  ADR-0034 follow-up; recorded in ADR-0034's Implementation note).
- **M4** — execution-time mode side-channel (deferred by ADR-0033
  Amendment 3; needs its own ADR).
- **`blob` value literal** (`src/dsl/value.rs`) — pre-existing gap.
- **Undo residual edge** (ADR-0006 Implementation note): if the entire
  `.snapshots/` dir is unwritable, `clear_redo` can also fail and a
  stale redo could survive — accepted (whole undo subsystem is broken
  then).
- **CI / TT5**, **DSL→SQL teaching echo** (ADR-0030 Phase 5), **DDL as
  the last SQL phase before §6 polish**.

## §6. Process pins (unchanged, still binding)

- **Confirm every commit.** Propose the message; wait for the go-ahead.
  (Every commit this session was user-approved.)
- **Push is the user's step.** Never push; never prompt about it.
- **No AI attribution** in commits (global rule).
- **Probe, don't reason.** The `/runda` round this session found a real
  silent-data-loss bug by *running a throwaway probe*, not by
  reasoning. Reproduce/print before concluding; delete probes before
  committing.
- **Escalate ADR-vs-implementation mismatches and scope calls.** The
  whole ADR-0035 design was settled by escalating (the
  reuse-vs-own-command question, the conversion model) rather than
  guessing — and corrected twice when the user pushed back.
- **Keep docs in lockstep.** ADR status flips update
  `docs/adr/README.md` in the same edit; behaviour changes update
  `requirements.md`.
- **Terminology:** the **DSL is the one unified command grammar**;
  the real axis is **mode-availability** (simple / advanced / both),
  not "DSL vs SQL". Avoid calling simple-mode commands "the DSL".

## §7. How to take over

1. **Read, in order:** this file → `docs/adr/0035-advanced-mode-sql-ddl.md`
   (**the next job**) → `docs/adr/0030-advanced-mode-sql-surface.md`
   (§4/§5 architecture) + `docs/adr/0033-sql-dml-grammar.md` (the
   dispatch + sub-phase precedent to mirror) → `CLAUDE.md` →
   `docs/requirements.md` (`Q4`/`C1`).
2. **Baseline:**
   ```
   cargo test    # expect 1698 passing / 0 failing / 0 skipped / 1 ignored
   cargo clippy --all-targets -- -D warnings   # clean
   ```
3. **Start ADR-0035** per §4: read the ADR, draft a short plan, confirm
   the open micro-calls with the user, then implement 4a test-first.
4. **Escalate** anything not settled in ADR-0035; the user wants
   mismatches and scope calls surfaced, not silently decided.