session-persistence.md 3.5 KB
ctx.sessionPersistence
SessionPersistence (abstract seam) — provided by @deepseek-ai/dsh-session-persistence.
Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
ctx.sessionPersistence.locate(meta)
abstract locate(meta: SessionHeader): SessionLocation | undefined
Resolve this backend's independent local artifact for a session without reading, creating, flushing, or otherwise materializing it. Backends such as SQLite that do not own one artifact per session return undefined.
meta— the immutable session header whose artifact is requested.
Returns the backend-specific absolute location, when one exists.
ctx.sessionPersistence.create(meta)
abstract create(meta: SessionHeader): Promise<void>
Register a new session's metadata. A backend MAY defer the physical write until the first append (lazy materialization), in which case a created-but-never-appended session is absent from list — abandoned sessions leave nothing behind.
meta— the immutable header (id, version, cwd, lineage) to record.
ctx.sessionPersistence.append(id, events)
abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
Durably persist a batch of events (called from the write-behind drain at the session/flush checkpoint). Honors the append-only and contiguous-seq contracts: the first event's seq MUST equal the stored next-seq (after load has durably closed any interrupted turn). Rejects non-JSON- serializable event.data with an error naming the offending event type.
id— the session the batch belongs to.events— the contiguous batch to persist, in seq order.
ctx.sessionPersistence.load(id)
abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
Load a header and balanced contiguous log. A complete interrupted final turn is preserved and durably closed with missing tool errors plus any open step and turn boundaries; only a torn final record is discarded. Unknown versions and corruption in the committed prefix reject.
id— the persisted session to reload.
Returns the header and a log ending on a balanced turn/end.
ctx.sessionPersistence.list()
abstract list(): Promise<SessionHeader[]>
Lightweight listing from metadata, without a full-log parse.
Returns one header per materialized session.