9126697d87
Add a SQLite SessionPersistence backend (node:sqlite), a SECOND implementation built to prove the abstract seam + the shared runPersistenceContract suite are genuinely backend-agnostic. Each SessionEvent maps 1:1 onto an events row (session_id, seq, type, time, data); append is an INSERT inside a transaction asserting the contiguous-seq contract; the mutable SessionSummary lives in the sessions metadata row. It satisfies the SAME contract semantics as the JSONL backend, expressed over rows instead of file bytes: - Lazy materialization: create() records intent in memory; no row until the first append (a never-appended session is absent from has()/list() via a materialized flag set inside the first append transaction). - Crash-tail-on-load: load() returns events only through the last complete turn/end and deletes the uncommitted tail; a seq gap in the committed region makes the session unloadable. - Transactional append: a mid-batch failure (a UNIQUE seq collision from a concurrent writer) rolls back entirely, keeping the cursor truthful. Like the JSONL backend it is also the write-path plugin (session/event → buffer → session/flush drain, onCreated seed/adopt/collision handling, HMR seeding, dispose-to-quiescence). The package runs the shared runPersistenceContract suite plus SQLite-specific tests (transaction rollback, crash-tail cut, schema version, HMR adoption). Docs flip every "SQLite is future/deferred" reference (ADR 0016, architecture.md, the persistence module doc + README) to "implemented; the contract holds both backends to identical semantics".
@deepseek-ai/dsh-session-persistence
The abstract durable session-persistence seam (ctx.sessionPersistence). Defines WHAT a persistence backend does — durably store, reload, list, and update sessions — without saying HOW. Mirrors the dsh-bash capability-seam template (ADR 0009): an abstract service here, a concrete implementation in a sibling package, consumers that inject the interface.
The persisted unit IS the existing SessionEvent (event-sourced model — the log is the single source of truth), so there is no parallel "persisted message" type. Metadata that is NOT replayable conversation state (format version, cwd, lineage) travels separately as SessionMeta, owned by dsh-session and re-exported here.
Service API (ctx.sessionPersistence)
| Method | Contract |
|---|---|
create(meta): Promise<void> |
Register a new session's metadata. MAY defer the physical write until the first append (lazy materialization). |
append(id, events): Promise<void> |
Durably persist a batch (from the session/flush drain). Append-only; first event seq == stored next-seq after any repair; rejects non-JSON-serializable data naming the offending type. |
load(id): Promise<{ meta; events }> |
Reload meta + log up to the last complete turn/end; events contiguous (events[i].seq === i); rejects a mid-log gap/parse error or unknown version. |
list(): Promise<SessionMeta[]> |
Lightweight listing from metadata, no full-log parse. |
has(id) / delete(id) |
Existence / removal. A zero-event lazily-materialized session is absent from has/list. |
update(id, summary): Promise<void> |
Update mutable SessionSummary fields without touching the append-only log. |
Invariants every backend must honor
- Append-only. Committed events (at or below a flushed
turn/end) are never rewritten. The only exception is the one-time truncation-repair of a never-committed crash tail on the firstappendafter aload. - Contiguous seq.
loadrejects aseqgap/parse error in the MIDDLE of the log;append's firstseqmust equal the stored next-seq. - JSON-serializable data.
appendrejects non-serializableevent.data; backends snapshot each event when buffering (the livesession.eventsobject is mutable). - Durability.
appendreturns only once the batch is durable.
Testing backends
Import runPersistenceContract from tests/contract.ts and call it with a factory that yields a fresh, empty backend plus a teardown. Every backend is held to the same append-only / contiguous-seq / lazy-materialization / serializability semantics; a backend's own spec adds implementation-specific tests (crash repair, path sanitization) on top.
Two backends run this suite: dsh-session-persistence-jsonl (append-only file log) and dsh-session-persistence-sqlite (node:sqlite, each SessionEvent one row (session_id, seq, type, time, data)). Both passing the same contract is the proof that the seam is genuinely backend-agnostic — lazy materialization, crash-tail-on-load, and contiguous-seq hold identically over file bytes and over a transactional store.
Metadata types
Re-exported from dsh-session: SessionHeader (immutable: version, id, createdAt, cwd?, parentSession?), SessionSummary (mutable: updatedAt, title?, firstPrompt?), SessionMeta (their intersection).