Codex review: needs real behavior proof before merge. Reviewed June 24, 2026, 7:25 PM ET / 23:25 UTC.

Summary
The PR adds an unused SQLite session/transcript store foundation with per-agent schema v2 tables, generated Kysely types, SQLite accessor helpers, checkpoint branch/restore helpers, and shared file/SQLite conformance coverage.

PR surface: Source +2349, Tests +1694, Generated +220. Total +4263 across 7 files.

Reproducibility: no. current-main runtime reproduction applies because this is an unmerged internal storage refactor. Source inspection of the PR head gives a high-confidence reproduction of the review blockers in the new SQLite helper/schema paths.

Review metrics: 2 noteworthy metrics.

• Stored schema expansion: schema version 1 -> 2; 7 session/transcript tables added. This is persistent data-model foundation work, so maintainers need migration, retention, and upgrade confidence before merge.
• SQLite read open mode: 6 read helpers use the create/migrate open path. Doctor and startup previews must be able to inspect absent SQLite state without creating new agent databases.

Stored data model
Persistent data-model change detected: database schema: src/state/openclaw-agent-db.test.ts, database schema: src/state/openclaw-agent-schema.generated.ts, database schema: src/state/openclaw-agent-schema.sql, serialized state: src/config/sessions/session-accessor.conformance.test.ts, serialized state: src/config/sessions/session-accessor.sqlite.ts, serialized state: src/state/openclaw-agent-db.generated.d.ts, and 9 more. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #88838
Summary: This PR is an implementation candidate for the active core session/transcript SQLite migration tracker, with adjacent open SQLite adapter PRs and merged seam work in the same Path 3 migration stack.

Members:

• canonical: Track core session/transcript SQLite migration via accessor seam #88838 - The tracker is explicitly referenced by the PR body and owns the remaining Path 3 SQLite session/transcript migration work.
• same_root_cause: refactor: add SQLite transcript identity adapter #90437 - Open draft PR for the SQLite transcript identity adapter in the same tracker/migration stack.
• same_root_cause: refactor: add SQLite embedded run target adapter #90438 - Open draft PR for the SQLite embedded run target adapter, based on this foundation branch.
• partial_overlap: refactor: add session accessor seam with gateway consumer #90463 - Merged session accessor seam that this foundation sits behind.
• partial_overlap: fix: make sqlite session entry writes atomic #91491 - Closed unmerged atomic-write PR whose caller-side semantics were explicitly requested to move into this slice.
• 1 more in the report.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🧂 unranked krab
Proof: 🧂 unranked krab
Patch quality: 🧂 unranked krab
Result: blocked until real behavior proof is added.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P1] Add redacted real behavior proof from a real typed SQLite foundation path and update the PR body so ClawSweeper re-reviews it.
• [P1] Implement no-create/read-only SQLite reads with absent-DB coverage.
• [P1] Add structural export-before-delete protection for transcript/session cascade paths.

Proof guidance:

• [P1] Needs real behavior proof before merge: The PR body lists focused checks but no redacted terminal output, logs, live output, recording, or linked artifact proving the real typed SQLite foundation path after this head; the contributor should add proof, redact private data, and update the PR body so ClawSweeper re-reviews.

Risk before merge

• [P1] Schema version 2 and seven new session/transcript tables are persistent data-model changes, so upgrade and migration safety need explicit maintainer confidence before merge.
• [P1] SQLite read helpers can create, migrate, and register missing agent DBs during future doctor or startup preview scans unless a no-create/read-only path lands first.
• [P1] Deleting a sessions root row can cascade transcript rows before a durable archive/export receipt is structurally required.
• [P1] The full-entry entry_json bridge can become a permanent parallel blob path unless the transition and retirement contract is documented at the schema/read site.
• [P1] The PR body lists checks but still lacks redacted real behavior proof from a real typed SQLite foundation path.

Maintainer options:

1. Fix storage safety before merge (recommended)
   Add no-create/read-only DB opens with absent-DB coverage, require an export or retention receipt before session-root cascade deletes, document the entry_json bridge, and refresh real proof on the current head.
2. Accept foundation-only risk deliberately
   Maintainers could accept the unused foundation as-is only if they explicitly block any production or doctor preview caller from using these helpers before the missing guards land.
3. Pause behind the tracker
   If the retention or adapter contract is still unsettled, pause this branch and let the tracker define a narrower next SQLite slice before merge.

Next step before merge

• [P1] Protected maintainer-labeled storage migration work needs human review, contributor proof, and storage-safety fixes rather than an automated repair lane.

Security
Needs attention: The diff introduces security-sensitive transcript/session storage deletion paths that need export/retention guardrails before merge.

Review findings

• [P1] Use no-create opens for SQLite read helpers — src/config/sessions/session-accessor.sqlite.ts:146
• [P1] Require export receipts before cascading transcript deletes — src/config/sessions/session-accessor.sqlite.ts:1018
• [P3] Document the transitional entry_json bridge — src/state/openclaw-agent-schema.sql:106

Requesting changes to lock in the 3.2 scope agreed on the #88838 tracker. The foundation direction is confirmed good — typed relational schema (sessions, conversations, session_routes, transcript_events (session_id, seq), transcript_event_identities) and the atomic row-patch write path (re-read inside the write transaction, merge, onConflict().doUpdateSet()) is exactly the shape we want. The items below are required additions before this slice is flip-ready.

1. Absorb the caller-side plumbing from #91491 (closed; its semantics move here)
The store-level atomicity is covered, but #91491's caller-facing work is not yet:

• SingleEntryPersistencePatch.patch + mode threading through updateSessionStore/saveSessionStoreUnlocked so single-entry persistence carries the field-level patch, not the whole merged entry.
• deriveRunMetadataPatch-style field-diffing in src/agents/command/session-store.ts (replacing removeLifecycleStateFromMetadataPatch) so post-run persistence writes only changed, non-transient fields.
• Patch plumbing at the call sites: attempt-execution.shared.ts, commands-session-store.ts (explicit abort patch), session-updates.ts, gateway/server-methods/agent.ts.
• Mode mapping at the seam sites: recordSessionMetaFromInbound → preserve-activity/merge, updateLastRoute → preserve-activity, upsertSessionEntry → replace (present in the accessor, missing on the store.ts file path).
• Post-write cache reconciliation (reconcileFreshSessionStoreForCache equivalent).
• The regression test proving updateSessionStoreEntry preserves an external SQLite write made while its callback runs.

2. Add a no-create/read-only open path
Every SQLite read here (loadSqliteSessionEntry, listSqliteSessionEntries, readSqliteSessionUpdatedAt, loadSqliteTranscriptEventsSync) routes through openOpenClawAgentDatabase, which unconditionally creates the DB file and runs schema DDL. Nothing wires doctor/preview to these yet, so it is not a violation today — but read-only scans creating DBs was the exact P1 flagged on #91322's doctor preview, and the flip slice will need preview semantics. A DatabaseSync(path, { readOnly: true })-style open that refuses to create (returning empty results when the DB is absent) should land in this foundation, not be retrofitted under flip pressure.

3. Guard export-before-delete against the CASCADE
transcript_events cascades on session delete. The RFC 0007 retention design requires archive export to be durable before rows are deleted, and the cascade makes the wrong ordering a silent one-liner. Please enforce structurally (e.g., the only deletion API for sessions with transcript rows takes an already-completed export receipt, or deletion asserts the export marker) rather than by convention.

4. Confirm and document the entry_json hybrid as transitional
session_entries (session_key PK, session_id FK, entry_json, updated_at) keeps the whole entry as a JSON column while the typed sessions columns are backfilled but not yet the read source. Acceptable as a transitional stage, but per the inline-comment policy it needs a comment at the schema/read site naming the contract: typed columns become canonical, entry_json is the bridge, and which milestone retires it. Without that, the blob column reads as the cache_entries design returning through the side door.

5. Minor

• fix: make sqlite session entry writes atomic #91491 ran walMaintenance.checkpoint() per write; this branch relies on wal_autocheckpoint=1000. Likely fine — worth a one-line comment stating the choice so it reads as intentional.
• The disposable-integration proofs on the early 3.1b slices were run against the pre-revert blob-era foundation; once this branch rebases onto the new seam head, those validations should be re-run against this typed foundation.

Context for reviewers: per maintainer decisions on #88838, the seam is permanent internal API, the flip is one-way (no reverse migration), and doctor preview must never create DBs — items 2 and 3 derive directly from those decisions plus the #91322 postmortem.

Closing as superseded by #96625. The SQLite storage flip PR now carries the remaining Path 3 implementation line, including the foundation/adapter work that this older 3.2 PR was meant to stage. Please use #96625 and tracker #88838 for remaining review/proof instead of rebasing this stale split PR.