rdbms-playground/docs/handoff/20260523-handoff-34.md

Session handoff — 2026-05-23 (34)

Thirty-fourth handover. This session completed ADR-0033 sub-phase 3k — the Phase-3 verification sweep — closing Phase 3 of the ADR-0030 advanced-mode SQL surface. A user-invoked /runda round hardened the matrix attributions and closed two small coverage gaps. ADR-0033 is now Accepted.

The next session (or the continuation of this one) starts the ADR-0034 implementation. See §4.

§1. State at handoff

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

Latest committed (local-only):

380c423 test+docs: 3k Phase-3 verification sweep — e2e DML + filled cross-cut matrix

origin/main is at 6b8888f (3h), so 10 commits are local-only (the 3i series, handoff-32, 3j d5c7f63, handoff-33 a5cdb00, and this session's 3k 380c423). Unpushed commits are a normal working state; pushing is the user's step — do not prompt about it.

Uncommitted at the moment of writing this handoff (the ADR-0033 acceptance flip + this handoff doc):

• docs/adr/0033-sql-dml-grammar.md — Status Proposed → Accepted.
• docs/adr/README.md — ADR-0033 index line flipped to Accepted (same-edit index-upkeep rule).
• docs/handoff/20260523-handoff-34.md — this file.

These three should be committed together (proposed message in §8).

§2. What shipped this session (3k)

Authoritative detail lives in the phase-exit report: docs/handoff/20260523-phase-3-verification.md — read it for the filled matrix, the requirements-to-test mapping, and the DA review. Summary:

• tests/sql_dml_e2e.rs (new) — 11 Tier-3 end-to-end DML tests (parse-in-Advanced → worker → persist/history): INSERT… SELECT cross-table, all-ten-type multi-row INSERT + RETURNING type recovery, UPDATE-with-subquery-in-SET, cascade DELETE, UPSERT round-trip, RETURNING ×3, history.log replay of Phase-3 forms, the full §13 OOS rejections, a trailing-; guard, and the [WRN] validity indicator driven by a SQL DML diagnostic.
• Cross-cut gap-fill in src/: walker/mod.rs (5 inherited-diagnostic cross-cuts — DELETE/UPDATE WHERE schema-existence, like-numeric on DELETE WHERE, the corrected row-scoped predicate slots), highlight.rs (DML-keyword highlight), completion.rs (INSERT INTO target-table), input_render.rs (advanced-mode DML hint-panel — added in the /runda round).
• Cross-cut matrix filled in docs/plans/20260520-adr-0033-phase-3.md — 85 ✅, 1 N/A, 0 ❌, every row a verified file::function.
• ADR-0033 → Accepted (this handoff's commit).

§3. Decisions settled this session (do not re-litigate)

Both escalated and user-confirmed before any matrix/test edit (via AskUserQuestion); recorded in the phase-exit report §4 and the matrix footnotes [d]/[e]:

1. Predicate-warning-in-VALUES (matrix I7) — claim corrected. Predicate warnings (eq_null / like_numeric / type_mismatch) fire on every DML sql_expr slot with row scope (UPDATE/ DELETE WHERE, UPDATE SET incl. CASE, INSERT…SELECT projection & WHERE) but not in plain INSERT … VALUES — a VALUES literal has no row to compare against. This matches ADR-0033 §8.4 ("WHERE and CASE"); the original "(e.g. = with NULL in VALUES)" example was an over-statement. Backed by new row-scoped tests.

2. Auto-snapshot (ADR-0006 / ADR-0033 §10) — N/A, deferred. ADR-0006 auto-snapshot/undo is unimplemented for both the DSL and SQL paths (the U-series). The "same as DSL" parity holds vacuously; Phase 3 introduces no regression. The matrix row is N/A, not red.

The /runda round additionally corrected the A6 attribution (the hint-panel tests ran in Simple mode via ambient_hint, which defaults to Mode::Simple; added an advanced-mode DML hint test) and closed OOS-5/OOS-6 (INDEXED BY / multi-statement — both parse-reject; a single trailing ; still parses).

§4. ADR-0034 — the NEXT job

Implement ADR-0034 (docs/adr/0034-history-journal-and-replay-filter.md, Accepted). This is the user's standing "extra tasks after Phase 3" item; it subsumes the old TASK #8 + TASK #9 and fixes a real, currently-broken behaviour verified this session:

replay history.log fails on line 1. run_replay (src/runtime.rs:1630) feeds each whole raw line straight to parse_command_with_schema and only skips blank/# lines — it does not understand the <ts>|<status>|<source> journal format that history.rs already writes. So replay only works on hand-written bare-command .commands scripts, never on the actual journal. No test catches this (existing replay tests + the new 3k e2e replay test all use bare-command scripts).

Concrete work (ADR-0034 §§1–4):

1. Writer records every command, tagged ok / err (today history.rs hardcodes ok). err lines are journalled best-effort from the runtime/app error path (a parse failure never reaches the worker); ok lines stay worker-journalled, transactionally coupled to the state change.
2. Hydration reads all records (ok + err) so cross-session recall matches the in-session ring (req I2 is marked done but only covers ok today — err lines are lost across sessions).
3. Replay learns the journal format: detect the <iso8601>|<status>| prefix, extract+unescape <source>, skip non-ok; bare commands still replay as-is. Detection by the leading timestamp+status prefix so a | inside a bare command isn't misread.
4. Escape/unescape parity with the existing history.rs helpers.

Test-first (global rule): the first move is a failing test that replays an actual history.log (with the <ts>|ok| prefix) and currently dies on line 1 — then make it green. Also add an err-line round-trip test (write → hydrate-reads-it → replay-skips-it).

Open question to settle with the user first: ADR-0034 has no plan doc (unlike Phases 2–3). It is smaller; a lightweight phased pass in one session may suffice. The user said we can "continue in this session afterwards with the ADR-0034 plan" — so the immediate next action is to produce that plan (or confirm a plan-less test-first pass), then implement.

§5. Other tracked deferred items (nothing lost)

• ADR-0006 auto-snapshot / undo (U-series) — surfaced by 3k's N/A matrix row; implement for both DSL and SQL worker handlers so parity is real, not vacuous.
• M4 — execution-time mode side-channel (three-way Mode threaded Action→worker, for mode-dependent output). Needs its own ADR (ADR-0033 Amendment 3; requirements.md M4). Not a prerequisite for anything above.
• Phase 4 — DDL as SQL (CREATE/DROP/ALTER TABLE, CREATE/DROP INDEX). The next ADR-0030 roadmap phase, but no ADR exists yet (latest is 0034) — needs its own ADR before implementation.
• blob value literal — src/dsl/value.rs has no blob literal yet; the 3k all-types test inserts NULL for blob (type still round-trips). Pre-existing gap.
• Q1 / Q2 (SQL subset completeness; polished out-of-subset rejection message naming the construct) — multi-phase, still [ ]; the 3k OOS tests assert rejection only, not message quality (Q2 is "Implementation pending").
• Cosmetic: tests/sql_*.rs helper names (run_sqlinsert etc.) keep their dev-word-era spelling though they parse the real words.

§6. Process pins (unchanged, still binding)

• Confirm every commit. Propose the message; wait for the go-ahead. (The 3k commit 380c423 and the acceptance flip were both 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. This session's catalog sub-agents fabricated test names and mis-attributed dispatch/inherited- diagnostic rows; every matrix row was re-verified by reading the actual test. The /runda round caught a mode mismatch the same way. Reproduce/print before concluding.
• Escalate ADR-vs-implementation mismatches; never classify work "out of scope" without user confirmation. Both 3k findings (I7, auto-snapshot) were escalated, not silently resolved.

§7. How to take over

1. Read, in order: this file → docs/handoff/20260523-phase-3-verification.md (the Phase-3 close-out) → docs/adr/0034-history-journal-and-replay-filter.md (the next job) → CLAUDE.md → docs/requirements.md.
2. Baseline:

   cargo test    # expect 1645 passing / 0 failing / 0 skipped / 1 ignored
   cargo clippy --all-targets -- -D warnings   # clean
   

3. Start ADR-0034 per §4: settle plan-vs-no-plan with the user, then a test-first pass beginning with the failing replay history.log reproduction.
4. Escalate anything not settled in ADR-0034; the user wants mismatches surfaced, not silently fixed.