# Session handoff — 2026-05-20 (29)

Twenty-ninth handover. This session **closed ADR-0032 Phase 2**
(see `docs/handoff/20260520-handoff-28.md`) and **drafted
ADR-0033** as the planning artifact for ADR-0030 Phase 3 (SQL
DML in Advanced mode). The next session starts implementation
at **sub-phase 3a** — see §3 below for the concrete entry point.

## §1. State at handoff

**Branch:** `main`. The Phase-2 commits were pushed by the user
mid-session; the Phase-3 planning commits in this session are
local-only and ready to be pushed at the user's convenience.

**Tests:** **1446 passing, 0 failing, 1 ignored** (unchanged
from handoff-28 — Phase 3 is planning-only this session).

**Clippy:** clean.

**This session's commits (Phase 3 planning):**

```
<this handoff>
<ADR-0033 + README index commit, pending>
fa417a4 docs: session handoff 28 — Phase 2 closed; Phase 3 is next
```

(All Phase-2 implementation commits are already pushed; see
handoff-28 §1 for the full list.)

## §2. Phase 3 design — settled

Ten design questions were discussed and settled in this session.
The full rationale lives in **`docs/adr/0033-sql-dml-grammar.md`**;
this is the index:

| Q   | Topic                                                          | Decision                                                                                                |
|-----|----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
| Q1  | `INSERT … SELECT` as a row source                              | **In scope** — recurses through `SQL_SELECT_COMPOUND`                                                   |
| Q2  | `INSERT INTO t DEFAULT VALUES`                                 | **OOS** — the planned seed feature covers this case                                                     |
| Q3  | `RETURNING` clause on INSERT / UPDATE / DELETE                 | **In scope** on all three                                                                               |
| Q4  | UPSERT (`ON CONFLICT … DO NOTHING / DO UPDATE`)                | **Full UPSERT in scope** — including `excluded` pseudo-table                                            |
| Q5  | `INSERT OR REPLACE / IGNORE / ABORT / FAIL / ROLLBACK`         | **OOS** — SQLite-specific                                                                               |
| Q6  | `UPDATE table FROM other_table` (multi-table)                  | **OOS** — SQLite/PostgreSQL extension, confusing pedagogically                                          |
| Q7  | `shortid` auto-fill on SQL INSERT                              | **Worker post-fill** (parity with DSL `do_insert`)                                                      |
| Q8a | INSERT column-count arity mismatch                             | **Walker ERROR diagnostic** — `diagnostic.insert_arity_mismatch`                                        |
| Q8b | Auto-gen column override warning                               | **Walker WARNING** — `diagnostic.auto_column_overridden`                                                |
| Q8c | NOT-NULL-missing-on-INSERT                                     | **Walker WARNING (advisory)** — `diagnostic.not_null_missing`                                           |
| Q9  | Cascade summary on SQL DELETE                                  | **Parity with DSL** — shared formatter, WHERE-clause byte-range injection into pre-count subqueries     |
| Q10 | `Command` shape for DML execution                              | **Three typed variants** — `SqlInsert` / `SqlUpdate` / `SqlDelete`                                      |

**Dispatch architecture (the hardest call):** Advanced mode runs
SQL-first with DSL fallback via `Choice(SQL_shape, DSL_shape)`
per shared entry word. The mode-gating mechanism requires a new
walker capability — `Node::Guard(fn)`, a zero-byte-consumption
gating node — which is the very first sub-phase's work (§3a in
the ADR).

## §3. Where the next session starts

**Sub-phase 3a — `Node::Guard` + mode-gated Choice mechanism.**
This is the foundation; if it doesn't work cleanly, the
mitigation paths (alternative dispatch mechanisms) are evaluated
before any DML grammar lands. ADR-0033 §"Open implementation
risks" R1 budgets for this explicitly.

**Concrete first-day tasks:**

1. **Read** the following, in order:
   - This handoff (you're already doing it).
   - `docs/handoff/20260520-handoff-28.md` (Phase 2 closing
     state + the four non-blocking observations).
   - `docs/adr/0030-advanced-mode-sql-surface.md` (the source
     roadmap).
   - `docs/adr/0033-sql-dml-grammar.md` (the Phase-3 grammar
     ADR — the controlling document for all DML decisions).
   - `CLAUDE.md` (project conventions; DA discipline reminder
     in particular).

2. **Run baseline:**
   ```
   cargo test    # expect 1446 / 0 / 1
   cargo clippy --all-targets -- -D warnings   # clean
   ```

3. **Write the Phase-3 implementation plan doc** at
   `docs/plans/<date>-adr-0033-phase-3.md`, modelled on
   `docs/plans/20260520-adr-0032-phase-2.md`. ADR-0033's
   per-sub-phase exit gates are detailed enough that the
   plan doc can be focused on the **cross-cut verification
   matrix scaffold** (the rows to fill in during 3k). Suggested
   matrix sources:
   - ADR-0033 §1 (statement shapes) — one row per shape per
     row-source variant (VALUES single, VALUES multi-row,
     INSERT…SELECT, …).
   - ADR-0033 §2 (dispatch) — one row per mode × DSL/SQL
     branch.
   - ADR-0033 §5 (RETURNING) — one row per statement kind.
   - ADR-0033 §6 (shortid auto-fill) — single-row, multi-row,
     INSERT…SELECT, override case.
   - ADR-0033 §7 (cascade summary) — DSL parity row + WHERE
     subquery case (R2 mitigation).
   - ADR-0033 §8 (diagnostics) — positive + negative per key.
   - ADR-0033 §9 (UPSERT) — DO NOTHING + DO UPDATE rows.

4. **Implement sub-phase 3a** per ADR-0033 §Implementation
   notes:
   - Add `Node::Guard(fn(&WalkContext) -> Result<(),
     ValidationError>)` to `src/dsl/grammar/mod.rs::Node`.
   - Add `walk_guard` to `src/dsl/walker/driver.rs`.
   - Add the `reject_sql_in_simple_mode` guard function.
   - Build the smoke-test grammar (a single experimental
     `CommandNode` with a `Choice(SQL_branch_gated,
     DSL_branch)` shape that uses two distinguishable tokens).
   - Verify the four exit-gate test cases in ADR-0033 §3a.

5. **DA gate (sub-phase 3a):** apply the written DA gate from
   ADR-0033 §3a verbatim. The "Does the Guard actually fire
   BEFORE the Seq commits?" question is the make-or-break
   test — write that test explicitly. If it fails, R1's
   mitigation reopens sub-phase 3a with mechanism option (b)
   or (c).

6. **Commit** with a message that explicitly names the
   mechanism choice (a/b/c) actually used. If you had to fall
   back to option (b) or (c), update ADR-0033 §2's "Default
   choice" sentence in the same commit.

## §4. Process pins from this session

These are NOT new project rules — they're lessons reinforced
this session that the next session should keep in mind.

### 4.1. DA discipline — first pass is rubber-stamp risk

Phase 2's verification report shipped with a rubber-stamp PASS
on the first DA pass. The user had to challenge it to get
specific critiques. This session's ADR-0033 DA review took two
passes: the first pass produced seven specific critiques, all
addressed in the body; the second pass surfaced an eighth real
gap (the `Node::Guard` capability didn't exist) and added it.

**Pin for sub-phase exits:** DA review lists specific critiques
first, concludes after. A clean PASS without critiques is a
process failure even if the work is sound — the DA hat has to
PROVE engagement.

### 4.2. Defer-trap reflexes

Phase 2 surfaced this pattern repeatedly: when scope expanded,
the implementer's reflex was to label items "out of scope" or
"non-blocking" without user approval, per CLAUDE.md's explicit
prohibition. The user corrected this several times.

**Pin for Phase 3:** every "out of scope" classification must
either (a) be already declared OOS by an ADR, or (b) be
escalated to the user. The default is "in scope, in this
sub-phase, now."

### 4.3. Tests-first on gap closure

Phase 2's 2g rework added 13 tests AFTER the gaps were
discovered, not before. The work was sound but the ordering was
backwards.

**Pin for Phase 3:** when a sub-phase's exit gate exposes a gap
in an earlier sub-phase, write the failing test FIRST, then fix.
This is the bug-fix discipline from CLAUDE.md applied to
gap-closure.

### 4.4. Matrix attribution must be SQL tests, not DSL tests

Phase 2's matrix row "validity indicator fires for SQL" was
attributed to a DSL test (the user-visible bug it left was
fixed in the rework). Generalisable lesson:

**Pin for Phase 3:** when filling the matrix in sub-phase 3k,
each row pointing at a SQL surface must point at a test whose
INPUT is SQL syntax. Cross-check at attribution time, not at
DA-review time.

## §5. Pinned non-blocking observations from Phase 2

These items are from `docs/handoff/20260520-handoff-28.md` §3.
**They're not blockers for Phase 3** but a Phase-3 implementer
may decide to address one or more if they're nearby:

- §3.1 `translate_generic`'s "group by" pattern overbreadth in
  `src/friendly/translate.rs`.
- §3.2 Look-ahead probe cost in `src/completion.rs` — second
  walk per Tab press when leading scope is empty; not
  benchmarked.
- §3.3 Process: tests-after-code on matrix coverage.
- §3.4 Process: matrix attribution wasn't verified row-by-row.

## §6. Open work — unchanged from handoff-28

Same list as handoff-28 §6. Phase 3 (this session's planning
target) is one of the items; the others remain:

- Project storage Iter 5/6.
- Snapshot / replay / undo (U-series).
- m:n convenience (C4); modify relationship (C3a); rename
  table (C1); column drops/renames/type changes (B2/C2).
- Friendly-error sweep (H1); strong syntax-help in parse
  errors (H1a).
- CI (TT5).
- Session log + Markdown export (V4).
- Readline shortcuts (I1b), multi-line input (I1), tab
  completion polish (I3), syntax highlighting (I4).
- ER diagram export (V3).
- Tutorial / lesson system.

## §7. How to take over

1. **Read this file in full.** Then handoff-28, then
   ADR-0033, then `CLAUDE.md`.
2. **`cargo test`** — expect **1446 passing, 0 failed, 1
   ignored**.
3. **`cargo clippy --all-targets -- -D warnings`** — clean.
4. **First task: write the Phase-3 plan doc** (per §3 step 3).
   Don't skip this — the cross-cut matrix is the scaffolding
   that lets sub-phases 3b–3k know what they're aiming at.
5. **Second task: sub-phase 3a** (`Node::Guard` + mode-gated
   Choice mechanism). Per §3 steps 4–6.
6. **Escalate** any ambiguity not already settled in ADR-0033.
   Don't decide silently; don't classify items "out of scope"
   without checking.