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

Session handoff — 2026-05-24 (35)

Thirty-fifth handover. This session closed ADR-0033 Phase 3 (marked Accepted) and implemented ADR-0034 (history journal + replay filter) end-to-end, including a safety fix surfaced by a /runda round. The next session starts ADR-0006 — the undo / snapshot feature (U-series). See §4.

§1. State at handoff

Branch: main. Tests: 1659 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):

e4f2f5f feat: ADR-0034 — history journal records err + replay parses/filters the journal

origin/main is at 6b8888f (3h); 13 commits are local-only. Unpushed commits are a normal working state; pushing is the user's step — do not prompt about it.

§2. What shipped this session

• ADR-0033 → Accepted. Phase 3 (advanced-mode SQL DML) was verified through sub-phase 3k and marked Accepted (commit 55b7845); see docs/handoff/20260523-phase-3-verification.md.
• ADR-0034 implemented (commits 504c24c plan, e4f2f5f code). history.log is now a complete journal and replay understands it:
  • Replay parses the journal format (§3): replay history.log works (it died on line 1 before); ok records run, non-ok skip; bare .commands scripts still work.
  • Journal records failures (§1/§2): failed commands are recorded err via a new Action::JournalFailure (emitted by the pure-sync App for parse failures and worker-execution failures; runtime appends best-effort, never fatal). Hydration reads all records → typos recallable across sessions.
  • Amendment 1 — replay filters app-lifecycle commands (found via /runda; see §3).

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

All user-confirmed.

1. Replay skips app-lifecycle commands (ADR-0034 Amendment 1). A working replay history.log exposed that the journal also records save as/load/new/export/import/rebuild/mode — which would panic the worker dispatch (unreachable! on Command::App) or abort replay (the modal forms don't parse). Replay now re-applies only schema/data write commands and skips every app-lifecycle command + nested replay, classified by entry word (so modal/incomplete forms and quit skip uniformly). All skips continue — never abort; this reversed the prior nested-replay refusal (a journal containing a once-run replay must not force hand-editing, and skipping closes the infinite-loop footgun). import and nested replay emit a [skip] warning (skipping them can leave replayed state incomplete); the rest skip silently.
2. err journalling scope. Covers parse failures of any submitted line + DSL/SQL worker execution failures (via DslFailed, which gained a source field). Deferred follow-up (A, user-confirmed): an app-lifecycle command that parses then fails at the runtime stage (e.g. save as / import failing on I/O) is not yet journalled err — those surface as their own runtime events, not DslFailed. Recorded in ADR-0034's Implementation note.
3. Runtime event-loop glue is unit-tested, not loop-tested (user-accepted). The App emit + append_history_failure + hydration + run_replay + warnings-render are each tested; the project has no full interactive-loop harness, so the one-line runtime glue isn't end-to-end tested.

/runda also fixed: a mode(bare)/q abort bug (→ entry-word classification over the complete app set), and doc drift in requirements.md U3/U4 (U4 had said "nested replay refused").

§4. ADR-0006 (undo / snapshot, U-series) — the NEXT job

Implement ADR-0006's undo/snapshot half (docs/adr/0006-…, Accepted). The replay/journal half (U3/U4) is now done; the undo/snapshot half (U1/U2) is the last unimplemented part:

• U1 — auto-snapshot before every destructive operation into a ring buffer (initial size N=10, tunable), via the engine's online backup API.
• U2 — undo / redo app-level commands (both modes), each prompting for confirmation with the snapshot timestamp + a summary of the changes that will be discarded.

Why this is next (verified): it's the only Accepted, unplanned, unimplemented ADR — M4 and Phase-4/DDL both need their own ADR first (latest ADR is 0034). It also closes the Phase-3 N/A matrix row ("auto-snapshot fires for SQL DML the same as DSL" — currently vacuous because neither path snapshots).

Scope considerations for the implementer:

• Destructive ops now span DSL and SQL — delete/drop/… and SqlDelete/SqlInsert/SqlUpdate + DDL. The snapshot trigger lives in the worker handlers (src/db.rs) and must cover both paths (this is exactly the Phase-3 parity the N/A row flagged). Mind the timing vs the existing finalize_persistence → tx.commit() ordering (ADR-0015, commit-db-last / crash-recoverable state).
• Ring-buffer storage needs a design call — where snapshots live (playground.db is a derived artifact per ADR-0015, so not there; temp dir? a snapshots subdir? memory?). ADR-0006 says "ring buffer of recent snapshots" but not where.
• Two new app commands + confirmation modals — undo/redo join the AppCommand set; the modal flow mirrors the existing rebuild/load-picker modals. (Note: adding AppCommand variants means updating runtime::is_app_lifecycle_entry_word so replay skips them — see ADR-0034 Amendment 1.)
• Engine-neutral user-facing strings (ADR-0002 posture): no "SQLite"/"backup API"/"PRAGMA" in notes or modal text.
• ADR-0006 is an early design ADR. Like ADR-0033/0034, implementation will likely surface details warranting a plan doc first (recommended) and possibly an amendment. Escalate design calls (ring-buffer location, snapshot granularity, redo-after-new-work semantics) rather than guessing.

Recommended first action: read ADR-0006 in full, then produce a short plan doc (docs/plans/<date>-adr-0006-undo-snapshots.md) and confirm the open design calls with the user before coding — test-first throughout.

§5. Other tracked deferred items (nothing lost)

• (A) App-command runtime-failure journalling (§3.2) — small ADR-0034 follow-up; recorded in ADR-0034's Implementation note.
• 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).
• Phase 4 — DDL as SQL (CREATE/DROP/ALTER TABLE, CREATE/DROP INDEX). Next ADR-0030 roadmap phase; no ADR exists yet — needs one before implementation.
• blob value literal (src/dsl/value.rs) — pre-existing gap; the Phase-3 all-types test inserts NULL for blob.
• Q1 / Q2 — SQL subset completeness; polished out-of-subset rejection message naming the construct (multi-phase, still [ ]).

§6. Process pins (unchanged, still binding)

• Confirm every commit. Propose the message; wait for the go-ahead. (Each 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. Both /runda rounds this session found real issues by running throwaway probes (the mode/q abort bug; the replay-app-command panic). Reproduce/print before concluding; delete probes before committing.
• Escalate ADR-vs-implementation mismatches and scope calls. The replay app-command filter, the err-journalling mechanism (Option A), and the deferred (A) boundary were all escalated and user-confirmed, then recorded as ADR-0034 Amendment 1 / notes.
• Keep docs in lockstep. ADR status flips update docs/adr/README.md in the same edit; behaviour changes update requirements.md (this session corrected U3/U4).

§7. How to take over

1. Read, in order: this file → docs/adr/0006-undo-snapshots-and-replay-log.md (the next job) → docs/handoff/20260523-phase-3-verification.md (Phase-3 close) + docs/adr/0034-history-journal-and-replay-filter.md (just shipped) → CLAUDE.md → docs/requirements.md (U1/U2 are the targets).
2. Baseline:

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

3. Start ADR-0006 per §4: read the ADR, draft a short plan, confirm the open design calls (ring-buffer location, snapshot timing, redo semantics) with the user, then implement test-first.
4. Escalate anything not settled in ADR-0006; the user wants mismatches and scope calls surfaced, not silently decided.