@deepseek-ai/dsh-session-persistence 0.1.2-rc.1 → 0.1.3-alpha.2

package/lib/types/errors.d.ts

@@ -1,9 +1,105 @@
-/** Stable failures exposed by the session-persistence service. */
+/**
+ * Stable failures exposed by the session-persistence service and its handles,
+ * including the format refusals shared by every backend: a stored log this
+ * build cannot faithfully interpret is refused, never misread, and the
+ * refusal points at the raw artifact when the backend keeps one per session.
+ * @module @deepseek-ai/dsh-session-persistence/errors
+ */
 import type { SessionId } from '@deepseek-ai/dsh-session';
-/** The requested Session identity has no materialized durable log. */
+/** The requested Session identity has no durable log visible to this caller. */
 export declare class SessionPersistenceNotFoundError extends Error {
     readonly sessionId: SessionId;
     /** @param sessionId - absent durable Session identity. */
     constructor(sessionId: SessionId);
 }
+/** `create` targeted a Session identity that already exists in this backend. */
+export declare class SessionAlreadyExistsError extends Error {
+    readonly sessionId: SessionId;
+    /** @param sessionId - the occupied durable Session identity. */
+    constructor(sessionId: SessionId);
+}
+/** A write open found the session already bound to an active write handle. */
+export declare class SessionAlreadyOwnedError extends Error {
+    readonly sessionId: SessionId;
+    /** @param sessionId - the session whose write ownership is taken. */
+    constructor(sessionId: SessionId);
+}
+/** A mutation (`append`/`flush`) was called on a read handle. */
+export declare class SessionReadOnlyError extends Error {
+    readonly sessionId: SessionId;
+    /**
+     * @param sessionId - the session the read handle observes.
+     * @param operation - the refused mutating operation name.
+     */
+    constructor(sessionId: SessionId, operation: string);
+}
+/**
+ * A write handle's ownership is permanently gone: its lease expired, a renewal
+ * failed, or the durable ownership record no longer names this handle. The
+ * handle never re-acquires ownership — close it and reopen for write.
+ *
+ * Declared for the cross-process lease layer; the shipped in-process backends
+ * never throw it yet.
+ */
+export declare class SessionOwnershipLostError extends Error {
+    readonly sessionId: SessionId;
+    /** @param sessionId - the session whose write ownership this handle lost. */
+    constructor(sessionId: SessionId);
+}
+/** An operation was called on a handle after `close()` was called. */
+export declare class SessionHandleClosedError extends Error {
+    readonly sessionId: SessionId;
+    /**
+     * @param sessionId - the session the closed handle addressed.
+     * @param operation - the refused operation name.
+     */
+    constructor(sessionId: SessionId, operation: string);
+}
+/**
+ * A backend-resolved, per-session local artifact location. Carried only by
+ * refusal diagnostics ({@link SessionFormatUnsupportedError}) so a user can
+ * find the raw log a build refused to interpret; it is not a consumer-facing
+ * query — log access goes through a session handle's `read`.
+ */
+export interface SessionLocation {
+    /** Backend-specific artifact kind, for example `jsonl`. */
+    readonly kind: string;
+    /** Absolute path to this session's backend-owned artifact. */
+    readonly path: string;
+}
+/** Durable session contents failed validation after a successful backend read. */
+export declare class SessionPersistenceCorruptionError extends Error {
+    /**
+     * @param message - stable corruption context.
+     * @param options - original validation failure.
+     */
+    constructor(message: string, options: ErrorOptions);
+}
+/**
+ * The stored log is intact but this runtime cannot faithfully interpret it:
+ * the header carries an unsupported format version, or an event's type is
+ * unknown to this build. Distinct from {@link SessionPersistenceCorruptionError}
+ * — nothing is damaged; the raw log remains readable at {@link location} when
+ * the backend keeps one artifact per session.
+ */
+export declare class SessionFormatUnsupportedError extends Error {
+    readonly location?: SessionLocation | undefined;
+    /**
+     * @param message - stable reason the log cannot be interpreted, already
+     *   including the raw-log path when one exists.
+     * @param location - the backend's artifact location, when one exists.
+     */
+    constructor(message: string, location?: SessionLocation | undefined);
+}
+/**
+ * Direction-aware refusal text for a stored session whose format version this
+ * build does not read. Shared by load-time checks and by backends that must
+ * refuse BEFORE decoding version-dependent structure (a future format may not
+ * satisfy this build's structural checks at all, and the user must see
+ * "upgrade the harness", never "corrupt").
+ * @param id - the stored session id, for message context.
+ * @param version - the stored format version.
+ * @returns the stable refusal text, without a raw-log path suffix.
+ */
+export declare function sessionFormatVersionRefusal(id: string, version: number): string;
 //# sourceMappingURL=errors.d.ts.map

package/lib/types/handle.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The per-session storage handle: one open channel onto a stored session's
+ * append-only event log, returned by `SessionPersistence.create`/`open`.
+ * @module @deepseek-ai/dsh-session-persistence/handle
+ */
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset, SessionSeedEventState } from '@deepseek-ai/dsh-session';
+/**
+ * Log access granted by an open. `write` is read-write: the session's single
+ * mutator, which also reads its own log. `read` only observes — it never
+ * takes ownership and works while another handle or process holds `write`.
+ */
+export type SessionAccess = 'read' | 'write';
+/** Options for {@link SessionHandle.read}. */
+export interface SessionHandleReadOptions {
+    /** Optional cancellation for backend read work. */
+    readonly signal?: AbortSignal;
+}
+/** One persistence event slice returned by {@link SessionHandle.read}. */
+export interface SessionHandleReadResult {
+    /**
+     * Whether event values are exclusively owned or shared only after deep
+     * freezing. Slicing preserves the producer's state even when no events remain.
+     */
+    readonly eventState: SessionSeedEventState;
+    /** Event values in a caller-owned outer array. */
+    readonly events: readonly SessionEvent[];
+}
+/** Options for {@link SessionHandle.append}. */
+export interface SessionHandleAppendOptions {
+    /** Optional cancellation observed before the write starts. */
+    readonly signal?: AbortSignal;
+}
+/** Options for {@link SessionHandle.flush}. */
+export interface SessionHandleFlushOptions {
+    /** Optional cancellation observed before the barrier starts. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * One open channel onto a stored session. A handle is single-owner state, not
+ * a shared service: `read` never backtracks below what this handle already
+ * observed, a `write` handle reads its own successful appends, and `close()`
+ * is the one teardown (idempotent, uncancellable; `Symbol.asyncDispose`
+ * delegates to it). Every operation on a closed handle rejects with
+ * `SessionHandleClosedError`.
+ *
+ * Freshness across handles: once an `append` or `flush` resolves on a write
+ * handle, every read STARTED afterwards on the same backend instance — on any
+ * handle, or through `stat`/`list` — observes at least that prefix.
+ * Reads concurrent with a mutation carry no ordering promise beyond the valid
+ * contiguous prefix.
+ */
+export interface SessionHandle extends AsyncDisposable {
+    /** The stored session this handle addresses. */
+    readonly id: SessionId;
+    /** The immutable stored header, fixed at `create`/`open`. */
+    readonly header: SessionHeader;
+    /**
+     * Exact fork-inherited prefix length stored with the log; `0` when
+     * `header.isSeeded` is false. Storage metadata paired with the header for
+     * every body read, never part of the replayable event log.
+     */
+    readonly inheritedEventCount: SessionLogOffset;
+    /** Whether this handle may mutate the log. */
+    readonly access: SessionAccess;
+    /**
+     * Read a slice of the valid contiguous logical log. The slice is a legal log
+     * prefix segment: a torn physical tail is never returned, and repeated reads
+     * on this handle never observe an older state than a prior read.
+     * @param offset - first logical event seq to include; defaults to `0`.
+     * @param length - maximum number of events to return; defaults to the rest
+     *   of the log. An offset at or past the end returns an empty list.
+     * @param options - optional cancellation.
+     * @returns the caller-owned outer slice plus the ownership state of its event values.
+     */
+    read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<SessionHandleReadResult>;
+    /**
+     * Append a contiguous batch continuing the current logical end. The first
+     * event's `seq` MUST equal the stored next-seq; committed events are never
+     * rewritten. Persistence is best-effort: on resolution the batch is
+     * accepted, ordered, and visible to reads on this backend instance, but
+     * only a resolved {@link flush} promises it survives a crash — a backend
+     * may buffer or batch physical writes behind append. Rejects with
+     * `SessionReadOnlyError` on a read handle and `SessionOwnershipLostError`
+     * when write ownership is gone.
+     * @param events - the contiguous batch, in seq order.
+     * @param options - optional cancellation observed before the write starts.
+     */
+    append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>;
+    /**
+     * The durability barrier — the one operation that promises storage: on
+     * resolution every acknowledged append is durable and the session is
+     * materialized for other processes; an empty created session becomes
+     * durably listable here. Callers that must survive a crash flush; a backend
+     * whose `append` already persists on resolution treats this as
+     * materialize-if-needed. Rejects with `SessionReadOnlyError` on a read
+     * handle.
+     * @param options - optional cancellation observed before the barrier starts.
+     */
+    flush(options?: SessionHandleFlushOptions): Promise<void>;
+    /**
+     * Release the handle: a read handle frees local resources; a write handle
+     * completes pending durability and releases write ownership. Idempotent,
+     * asynchronous, and deliberately not cancellable.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=handle.d.ts.map

package/lib/types/index.d.ts

@@ -1,235 +1,158 @@
 /**
  * Durable session-persistence Service Definition (`ctx.sessionPersistence`). Backends store
  * {@link SessionEvent}s as the event-sourced log and carry non-replayable
- * {@link SessionHeader} metadata separately.
+ * {@link SessionHeader} metadata separately; callers address one stored
+ * session through a {@link SessionHandle} obtained from `create`/`open`.
  * @module @deepseek-ai/dsh-session-persistence
  */
 import { Context, Service } from '@deepseek-ai/cordis';
-import { SessionPreparation, SessionLogOffset } from '@deepseek-ai/dsh-session';
-import type { Session, SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session';
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
+import type { SessionHandle, SessionAccess } from './handle.ts';
 import type { SessionPersistenceRevision } from './revision.ts';
 export type { SessionHeader } from '@deepseek-ai/dsh-session';
 export { SessionPersistenceRevision } from './revision.ts';
-export { SessionPersistenceNotFoundError } from './errors.ts';
-/** Lightweight immutable source identity returned without loading a full log. */
+export type { SessionAccess, SessionHandle, SessionHandleAppendOptions, SessionHandleFlushOptions, SessionHandleReadOptions, SessionHandleReadResult, } from './handle.ts';
+export { SessionAlreadyExistsError, SessionAlreadyOwnedError, SessionFormatUnsupportedError, SessionHandleClosedError, SessionOwnershipLostError, SessionPersistenceCorruptionError, SessionPersistenceNotFoundError, SessionReadOnlyError, sessionFormatVersionRefusal, } from './errors.ts';
+export type { SessionLocation } from './errors.ts';
+export { assertContiguous, assertStoredId, assertVersion, materializeAppendBatch, materializeCreateHeader, validateStoredEvents, } from './storage-contract.ts';
+/**
+ * Lightweight stored-session observation returned by {@link SessionPersistence.stat}
+ * and {@link SessionPersistence.list} without reading the full event log.
+ */
 export interface SessionPersistenceSnapshot {
-    /** Detached metadata for one materialized session. */
-    header: SessionHeader;
-    /** Opaque source-qualified token that changes whenever this stored log changes. */
-    revision: SessionPersistenceRevision;
+    /** Detached metadata for one stored session. */
+    readonly header: SessionHeader;
+    /** Opaque change token; see {@link SessionPersistence.stat}. */
+    readonly revision: SessionPersistenceRevision;
+    /** Logical event count, when the backend can provide it cheaply from metadata; otherwise absent. */
+    readonly eventCount?: number;
+    /** Physical artifact byte size, when the backend can provide it cheaply (JSONL); otherwise absent. */
+    readonly sizeBytes?: number;
 }
-/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
+/** Options for {@link SessionPersistence.create}. */
+export interface SessionPersistenceCreateOptions {
+    /** Optional cancellation observed before backend work starts. */
+    readonly signal?: AbortSignal;
+    /**
+     * Exact fork-inherited prefix length. Required when `header.isSeeded` is
+     * true and must be omitted (or `0`) otherwise; the backend refuses a
+     * mismatch at create.
+     */
+    readonly inheritedEventCount?: SessionLogOffset;
+}
+/**
+ * Logical Session header paired with its exact inherited cut for body-bearing
+ * storage operations. `isSeeded` marks fork lineage on the header; the
+ * numeric cut travels beside it, never inside the replayable event log.
+ */
 export interface SessionStorageMetadata {
     /** Validated immutable Session header. */
     readonly meta: SessionHeader;
     /** Number of leading events inherited from the Session's fork parent. */
     readonly inheritedEventCount: SessionLogOffset;
 }
-/** Immutable logical session prepared from persistence or a live owner. */
+/** Immutable logical session read: storage metadata plus the complete validated event log. */
 export interface SessionInspection extends SessionStorageMetadata {
-    /** Validated contiguous logical event log. */
+    /** Contiguous validated events from seq 0. */
     readonly events: readonly SessionEvent[];
 }
-/** Detached logical suffix returned by one explicit stored-log offset read. */
-export interface SessionEventSuffix extends SessionStorageMetadata {
-    /** First requested log offset; {@link events} contains only seqs at or after it. */
-    readonly fromSeq: SessionLogOffset;
-    /** Valid contiguous stored events at or after {@link fromSeq}; not a complete Session log when the offset is nonzero. */
-    readonly events: readonly SessionEvent[];
+/** Options for {@link SessionPersistence.open}. */
+export interface SessionPersistenceOpenOptions {
+    /** Optional cancellation observed before backend work starts. */
+    readonly signal?: AbortSignal;
 }
-/** A borrowed exact Session source returned from a cold materialization or concurrent live owner. */
-export type BorrowedSessionSource = Disposable & ({
-    /** A reusable unpublished Session is pinned until this observation is disposed. */
-    readonly source: 'prepared';
-    /** Immutable header and logical event prefix observed together. */
-    readonly inspection: SessionInspection;
-    /** Durable revision represented by the prepared source. */
-    readonly revision: SessionPersistenceRevision;
-    /** Exact unpublished Session retained for a later {@link prepare}. */
-    readonly preparedSession: Session;
-} | {
-    /** A live Session won source resolution while the persistence read was starting. */
-    readonly source: 'live';
-    /** Immutable live header and event prefix observed together. */
-    readonly inspection: SessionInspection;
-});
-/** A backend's own raw artifact text for one session, verbatim. */
-export interface SessionRawArtifact extends SessionStorageMetadata {
-    /** The artifact's base filename on disk, without any physical encoding suffix. */
-    readonly filename: string;
-    /** The artifact's full text content, decoded from the backend's physical encoding. */
-    readonly content: string;
+/** Options for {@link SessionPersistence.stat}. */
+export interface SessionPersistenceStatOptions {
+    /** Optional cancellation for backend metadata reads. */
+    readonly signal?: AbortSignal;
+}
+/** Options for {@link SessionPersistence.list}. */
+export interface SessionPersistenceListOptions {
+    /** Optional cancellation for backend listing work. */
+    readonly signal?: AbortSignal;
 }
-export { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, PersistenceCoordinator, SessionFormatUnsupportedError, SessionPersistenceCorruptionError, sessionFormatVersionRefusal, } from './coordinator.ts';
-export type { PersistenceBackend, PersistenceCoordinatorOptions, StoredPrefix, StoredSuffix, } from './coordinator.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         sessionPersistence: SessionPersistence;
     }
 }
 /**
- * A backend-resolved, per-session local artifact location. The path is an
- * absolute target path and can name an artifact that has not materialized yet.
- * Consumers must treat it as a location hint, never as an authorization token.
- */
-export interface SessionLocation {
-    /** Backend-specific artifact kind, for example `jsonl`. */
-    readonly kind: string;
-    /** Absolute path to this session's backend-owned artifact. */
-    readonly path: string;
-}
-/**
- * Durable append-only session storage. Implementations preserve contiguous,
- * losslessly JSON-serializable events; {@link append} resolves only after
- * durability, and {@link load} balances a complete interrupted tail without
- * rewriting committed events.
+ * Durable append-only session storage addressed through per-session handles.
+ *
+ * Storage semantics shared by every backend: events are contiguous from seq 0
+ * and never rewritten; a torn physical tail is never returned to a reader and
+ * is truncated by the write path before its first append; reads validate
+ * current-format records only and refuse unknown vocabulary fail-closed.
+ * `append` persists best-effort; `flush` — per handle or service-wide — is
+ * the durability barrier.
+ *
+ * Visibility: a created session is observable through `stat`/`list`/`open`
+ * in this process from the moment `create` resolves, even while a backend
+ * defers physical materialization (a pure optimization); other processes see
+ * the session only once it materializes, and a session that never
+ * materialized before a crash never existed. `SessionHandle.flush` forces
+ * materialization.
+ *
+ * Freshness: once an `append` or `flush` resolves, reads started afterwards
+ * on this backend instance observe at least that prefix.
  */
 export declare abstract class SessionPersistence extends Service {
     constructor(ctx: Context);
     /**
-     * Resolve this backend's independent local artifact for a session without
-     * reading, creating, flushing, or otherwise materializing it. A backend
-     * that does not own one artifact per Session returns `undefined`.
-     * @param meta - the immutable session header whose artifact is requested.
-     * @returns the backend-specific absolute location, when one exists.
-     */
-    abstract locate(meta: SessionHeader): SessionLocation | undefined;
-    /**
-     * Whether this backend exposes one verbatim raw artifact per session.
-     * A backend that declares `true` must override {@link readRaw}.
+     * Create a new stored session and take its write ownership.
+     * @param header - the immutable header (id, version, cwd, lineage) to store.
+     * @param options - optional cancellation.
+     * @returns a `write` handle owned by the caller; close it to release ownership.
+     * @throws {SessionAlreadyExistsError} when the id already exists.
      */
-    abstract readonly supportsRawArtifacts: boolean;
+    abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>;
     /**
-     * Read a session's backend-owned artifact text verbatim — the exact durable
-     * bytes the backend wrote (decoded from its physical encoding, e.g. a
-     * decompressed JSONL). The returned `content` is the raw text, not a
-     * reconstruction from parsed events, so it preserves backend-specific
-     * serialization (chunk packing, key order, line breaks). Callers first test
-     * {@link supportsRawArtifacts}; `undefined` then means only that the requested
-     * session has no materialized artifact.
-     * @param _id - the persisted session to read (unused by the default: no
-     * per-session artifact).
-     * @param signal - optional cancellation for backend read work.
-     * @returns the raw artifact plus its parsed header, or `undefined` when the
-     * session is absent.
-     * @throws when this backend does not expose per-session raw artifacts.
-     */
-    readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>;
-    /**
-     * Register a new session's metadata. A backend MAY defer the physical write
-     * until the first {@link append} (lazy materialization), in which case a
-     * created-but-never-appended session is absent from {@link list}
-     * — abandoned sessions leave nothing behind.
-     * @param meta - the immutable header (id, version, cwd, lineage) to record.
-     * @param inheritedEventCount - exact fork-inherited prefix length. Required
-     * for a seeded header and omitted only for an unseeded header.
-     */
-    abstract create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>;
-    /**
-     * Ensure a live session has a durable header even when it has no events.
-     * Ordinary sessions remain lazily materialized; lifecycle frontends call
-     * this only when an empty session itself is a durable resumable resource.
-     * @param _session - exact live session whose registered header is materialized.
-     */
-    ensureMaterialized(_session: Session): Promise<void>;
-    /**
-     * Durably persist a batch of events. 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.
-     * A seeded session's first materializing batch must reach its complete
-     * inherited prefix.
-     * @param id - the session the batch belongs to.
-     * @param events - the contiguous batch to persist, in seq order.
-     */
-    abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>;
-    /**
-     * Prepare the exact unpublished Session used by resume. Implementations may
-     * reuse object graphs retained by an earlier {@link inspect} after confirming
-     * their durable revision is still current; disposal releases an unpublished
-     * reservation. Revision retries require the durable log to remain unchanged
-     * for one read/check round trip; continuous external writers may delay completion.
-     * @param id - persisted session to prepare.
-     * @param signal - optional cancellation for preparation work.
-     * @returns one owned unpublished Session preparation.
-     */
-    prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>;
-    /**
-     * Load an immutable balanced logical view and commit any required cold
-     * recovery. 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. Implementations MUST NOT crash-repair an
-     * identity still bound to a live Session: a balanced live log may return as a
-     * durable snapshot, while an open live turn rejects. Returned values may be
-     * shared with immutable live or prepared state and must not be mutated.
-     * Revision-based implementations may wait for one stable read/check round trip.
-     * @param id - the persisted session to reload.
-     * @returns the header and a log ending on a balanced `turn/end`.
-     */
-    abstract load(id: SessionId): Promise<SessionInspection>;
-    /**
-     * Inspect an immutable logical session without committing recovery or
-     * publishing it. A cold complete interrupted turn receives synthetic closers
-     * in memory and a torn physical tail remains untouched. An already-live
-     * Session instead yields its current immutable snapshot, which may contain an
-     * open turn and its `session/end-seed` boundary. Coordinator-backed
-     * implementations retain the exact cold unpublished Session for bounded
-     * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
-     * already committing or reserved for resume remains exclusive, and inspection
-     * may borrow its immutable view. Callers borrow only the immutable header and
-     * log. Continuous external writers may delay revision convergence.
-     * @param id - the persisted session to inspect.
-     * @param signal - optional cancellation for queued and backend read work.
-     * @returns the validated header and current logical event log.
-     */
-    abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>;
-    /**
-     * Borrow one exact inspection while retaining any reusable prepared source.
-     * A cold observation must pin the exact prepared Session that a later
-     * {@link prepare} reserves. Implementations must not degrade this operation
-     * to a detached {@link inspect} result.
-     * @param id - persisted session to observe.
-     * @param signal - optional cancellation for preparation work.
-     * @returns a disposable immutable observation.
+     * Open an existing stored session.
+     *
+     * `read` never takes ownership and works while another handle (or process)
+     * holds write ownership. `write` atomically claims single-writer ownership;
+     * an existing active owner rejects.
+     * @param id - the stored session to open.
+     * @param access - `read` or `write`.
+     * @param options - optional cancellation.
+     * @returns the open handle.
+     * @throws {SessionPersistenceNotFoundError} when the session does not exist.
+     * @throws {SessionAlreadyOwnedError} for `write` when ownership is taken.
      */
-    abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>;
+    abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>;
     /**
-     * Read the stored events from `fromSeq` onward — the read-from-seq
-     * primitive for read models that resume from a watermark (e.g. a persisted
-     * projection cache folding only the tail past its checkpoint). Unlike
-     * {@link inspect}, it is a detached physical suffix read: no preparation
-     * cache, torn-tail truncation, synthetic closers, or coordinator-state
-     * publication. Only events from the valid contiguous stored prefix are
-     * returned, so a torn fragment never reaches the caller. `fromSeq` at or
-     * beyond the stored prefix returns an empty event list (never an error).
-     * A backend whose medium can seek by seq may read only the suffix;
-     * sequential media such as JSONL still parse the whole artifact and skip
-     * forward. The primitive bounds what is returned and refolded, not every
-     * backend's physical read.
-     * @param id - the persisted session to read.
-     * @param fromSeq - first event offset to include.
-     * @param signal - optional cancellation for queued and backend read work.
-     * @returns storage metadata, the requested offset, and stored events with `seq >= fromSeq`.
+     * Flush every active write handle owned by this service instance in one
+     * durability barrier: each handle's routed live events drain durably and
+     * its session materializes, exactly as that handle's own
+     * `SessionHandle.flush` would. Read handles buffer nothing and are
+     * untouched. A handle closed concurrently counts as flushed — close itself
+     * drains durably.
+     * @returns resolution once every write handle active at the call has flushed.
+     * @throws {AggregateError} naming each session whose flush failed; the
+     *   remaining handles still flush.
      */
-    abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>;
+    abstract flush(): Promise<void>;
     /**
-     * Lightweight listing from metadata, without a full-log parse.
-     * @param signal - optional cancellation for backend listing work.
-     * @returns one header per materialized session.
+     * Observe one stored session without reading its event log or taking
+     * ownership.
+     *
+     * The snapshot's `revision` is an opaque change token comparable only
+     * against revisions from the same service instance and session id: equal
+     * revisions may be treated as an unchanged log; unequal revisions promise
+     * nothing. Write-ownership churn does not change a revision. It exists for
+     * derived read-model caches keyed off `stat`/`list`; it plays no part in
+     * open, read, or resume.
+     * @param id - the stored session to observe.
+     * @param options - optional cancellation.
+     * @returns the snapshot, or `undefined` when the session does not exist.
      */
-    abstract list(signal?: AbortSignal): Promise<SessionHeader[]>;
+    abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>;
     /**
-     * List materialized sessions with cheap per-log change tokens.
-     *
-     * Repeated observations of an unchanged log return the same revision. A
-     * successful mutating {@link load} repair changes the next listed revision.
-     * Revisions also distinguish independently backed stores so backend-local
-     * counters cannot compare equal across different persistence sources.
-     * @param signal - optional cancellation for backend snapshot-listing work.
-     * @returns one header and opaque revision per materialized session without loading full logs.
+     * List every stored session visible to this process, in no promised order.
+     * @param options - optional cancellation.
+     * @returns one snapshot per stored session.
      */
-    abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>;
+    abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>;
 }
 export default SessionPersistence;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/storage-contract.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Backend-shared storage validation: the version gate, the fail-closed event
+ * vocabulary, append-batch materialization, and contiguity — one place so
+ * every backend refuses the same inputs identically.
+ * @module @deepseek-ai/dsh-session-persistence/storage-contract
+ */
+import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session';
+import { type SessionLocation } from './errors.ts';
+/**
+ * Refuse stored metadata that is not bound to the requested session id.
+ * @param id - the requested session id.
+ * @param meta - the stored header.
+ */
+export declare function assertStoredId(id: SessionId, meta: SessionHeader): void;
+/**
+ * Refuse a stored header whose format version this build does not read.
+ * @param meta - the stored header.
+ * @param location - the backend's artifact location for the refusal, when one exists.
+ */
+export declare function assertVersion(meta: {
+    readonly id: SessionId;
+    readonly version: number;
+}, location?: SessionLocation): void;
+/**
+ * Validate one exclusively owned stored event array in place: adopt each
+ * record (validating and freezing it) and refuse any event type this build
+ * does not know, unless its writer marked it `ignorable: true` — silently
+ * skipping an unknown required event could reconstruct a wrong session (the
+ * envelope contract on `SessionEvent.ignorable`). Both newer vocabularies and
+ * retired pre-release shapes refuse here; this build ships no migration.
+ * @param meta - the stored header the events belong to.
+ * @param events - exclusively owned decoded events; validated in place.
+ * @param location - the backend's artifact location for refusals, when one exists.
+ * @returns the same array, validated and frozen.
+ * @throws {SessionFormatUnsupportedError} for unknown event types.
+ * @throws {SessionPersistenceCorruptionError} for records that fail validation.
+ */
+export declare function validateStoredEvents(meta: SessionHeader, events: SessionEvent[], location?: SessionLocation): SessionEvent[];
+/**
+ * Validate and deep-snapshot a header passed to `create` in one traversal.
+ * @param header - the caller's header.
+ * @returns the detached lossless-JSON header.
+ * @throws {TypeError} for non-JSON metadata or an invalid `createdAt`.
+ */
+export declare function materializeCreateHeader(header: SessionHeader): SessionHeader;
+/**
+ * Validate and deep-snapshot one append batch in a single traversal, so the
+ * checked value is exactly the value persisted (a check followed by a copy
+ * could reread accessors into a different record).
+ * @param events - the caller's batch.
+ * @returns the detached lossless-JSON batch.
+ * @throws {TypeError} when any event data is not losslessly JSON-serializable.
+ */
+export declare function materializeAppendBatch(events: readonly SessionEvent[]): readonly SessionEvent[];
+/**
+ * Refuse a batch that does not contiguously continue the stored log.
+ * @param id - the session the batch belongs to.
+ * @param events - the batch, in seq order.
+ * @param cursor - the stored next-seq.
+ */
+export declare function assertContiguous(id: SessionId, events: readonly SessionEvent[], cursor: number): void;
+//# sourceMappingURL=storage-contract.d.ts.map