Tianyi Cui
01621d38b6
A durable persistence backend must not treat a storage fault as absence.
listCwdDirs() and exists() swallowed EVERY error and reported "no
sessions" / "not found", so EACCES/ENOTDIR/transient I/O could make
list() return nothing, load() report not-found, and collision checks
proceed under a false absence assumption.
- Add an isENOENT() helper; listCwdDirs() and exists() now return the
empty/absent result ONLY for ENOENT and rethrow every other error.
Regression tests drive ENOTDIR through both paths.
TODO-level hardening also addressed:
- writeSidecar() now uses an exclusive owner-only temp open ('wx', 0o600)
like the log-materialization path, instead of a truncating writeFile —
the sidecar can carry user data (title/firstPrompt), so a predictable/
pre-existing temp path must never be silently followed.
- The shared runPersistenceContract serializability case now exercises
EVERY value isJsonValue rejects (BigInt, undefined, Infinity, function,
symbol, Map, circular), not just BigInt, so a backend cannot pass the
contract while accepting values that corrupt the round-trip. The mock
MemoryPersistence now validates via the canonical isJsonValue.
@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.
TODO (validate the abstraction with a second backend):
dsh-session-persistence-jsonlis currently the only implementation, so the interface andrunPersistenceContractare only proven against one storage model. A second backend — a SQLite implementation (dsh-session-persistence-sqlite), where eachSessionEventmaps 1:1 onto a row(session_id, seq, type, time, data)— would run the SAMErunPersistenceContractsuite and so prove the seam is genuinely backend-agnostic (lazy materialization, crash-tail-on-load, contiguous-seq all expressed against a transactional store rather than an append-only file).
Metadata types
Re-exported from dsh-session: SessionHeader (immutable: version, id, createdAt, cwd?, parentSession?), SessionSummary (mutable: updatedAt, title?, firstPrompt?), SessionMeta (their intersection).