@deepseek-ai/dsh-session-persistence 0.0.1-rc.1

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence`.
+* @module @deepseek-ai/dsh-session-persistence/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-session-persistence";
+/** Cordis companion plugin name. */
+const name = "session-persistence-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: persistence correctness requires backend round-trip and crash-tail tests;
+* this package exposes no continuously observable in-process relation.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/coordinator.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Shared buffering, serialization, adoption, repair, and disposal orchestration
+ * for first-party backends. Third-party backends may implement the public
+ * persistence seam directly.
+ * @module @deepseek-ai/dsh-session-persistence/coordinator
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { SessionPreparation } from '@deepseek-ai/dsh-session';
+import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session';
+import type { SessionInspection } from './index.ts';
+import type { SessionPersistenceRevision } from './revision.ts';
+/** Default number of detached session preparations retained by a coordinator. */
+export declare const DEFAULT_PREPARED_SESSION_CACHE_SIZE = 5;
+/** Default maximum intentional wait before a live session batch starts writing. */
+export declare const DEFAULT_WRITE_BATCH_MAX_DELAY_MS = 200;
+/** Largest write batching delay accepted by Node's timer implementation. */
+export declare const MAX_WRITE_BATCH_DELAY_MS = 2147483647;
+/** 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);
+}
+/** Coordinator policy supplied by a concrete persistence backend. */
+export interface PersistenceCoordinatorOptions {
+    /** Maximum completed unpublished preparations retained for reuse. */
+    readonly preparedSessionCacheSize: number;
+    /** Maximum intentional batching wait after an idle live queue receives work. */
+    readonly writeBatchMaxDelayMs: number;
+}
+/**
+ * A stored session's header, valid contiguous event prefix, source-qualified
+ * revision, and optional opaque torn-tail marker. The revision identifies the
+ * exact detached prefix. The coordinator only checks marker presence and
+ * returns its value to {@link PersistenceBackend.commitRepair}; each backend
+ * owns the marker type.
+ */
+export interface StoredPrefix<TornMarker = unknown> {
+    meta: SessionHeader;
+    events: SessionEvent[];
+    /** Revision observed for exactly this detached prefix. */
+    revision: SessionPersistenceRevision;
+    tornMarker?: TornMarker;
+}
+/**
+ * A stored session's header plus the events at or past a requested seq — the
+ * return shape of the optional seek-capable
+ * {@link PersistenceBackend.loadStoredFrom} hook. Non-mutating reads carry no
+ * torn marker: there is nothing to repair.
+ */
+export interface StoredSuffix {
+    meta: SessionHeader;
+    events: SessionEvent[];
+}
+/**
+ * The storage contract between {@link PersistenceCoordinator} and a concrete
+ * backend: the minimal set of durable primitives the orchestration calls. A
+ * backend implements these (over files, rows, an object store, …); the
+ * coordinator supplies everything else (buffering, serialization, cursors,
+ * adoption, crash repair sequencing, dispose quiescence).
+ *
+ * @typeParam TornMarker - the backend's opaque torn-tail repair token (see
+ * {@link StoredPrefix}). The coordinator treats it as fully opaque.
+ */
+export interface PersistenceBackend<TornMarker = unknown> {
+    /** Human-readable backend name, used in the dispose-failure AggregateError. */
+    readonly name: string;
+    /**
+     * Read a stored prefix by id, scanning every backend storage scope. Returns
+     * `undefined` if no stored artifact exists. Returned metadata must identify
+     * `id` before repair or state publication. Used by resume/load, live adoption,
+     * and — via `!== undefined` — the create-collision probe. The returned
+     * `tornMarker` is present iff there is a torn tail to truncate. Every header
+     * and event graph must be fresh, mutually unaliased, and unretained by the
+     * backend because preparation freezes and publishes them in place. The
+     * returned revision must identify exactly those values and use the same
+     * representation as {@link readStoredRevision}.
+     * @param id - persisted session id to resolve.
+     * @param signal - optional cancellation for backend read work.
+     */
+    loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<TornMarker> | undefined>;
+    /**
+     * Read the current source-qualified revision for one stored session without
+     * loading its event log. Returns `undefined` when the identity is absent.
+     * @param id - persisted session id to observe.
+     * @param signal - optional cancellation for backend read work.
+     */
+    readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<SessionPersistenceRevision | undefined>;
+    /**
+     * Optional seek-capable suffix read behind the service's `readFrom`: return
+     * the header plus the stored events with `seq >= fromSeq` without reading
+     * the whole log. A backend whose medium can address events by seq (SQLite)
+     * implements this so `readFrom` scales with the suffix; sequential backends
+     * omit it and the coordinator falls back to {@link loadStored} plus a
+     * forward skip. Non-mutating (no truncation, no closers). Validation of the
+     * region strictly below `fromSeq` is limited to seq contiguity — the
+     * service contract scopes this read to the suffix — unless that suffix
+     * contains a supported legacy shape whose normalization needs earlier
+     * message-identity facts, in which case the coordinator falls back
+     * to the complete stored prefix.
+     * @param id - persisted session id to resolve.
+     * @param fromSeq - first event seq to include (non-negative safe integer,
+     *   validated by the coordinator before this hook runs).
+     * @param signal - optional cancellation for backend read work.
+     */
+    loadStoredFrom?(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<StoredSuffix | undefined>;
+    /**
+     * Durably append a CONTIGUOUS batch, lazily materializing the session first
+     * when `!isMaterialized`. The materialize-write and the first event batch MUST
+     * commit ATOMICALLY (a crash between them must not leave a materialized-but-
+     * empty session). Returns once the batch is durable.
+     */
+    appendBatch(meta: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>;
+    /**
+     * Make a crash repair durable: truncate the torn tail (iff
+     * `tornMarker !== undefined`) and append `closers` (iff any). NOT required to
+     * be atomic — a file backend may truncate-then-append in two fsync'd steps.
+     * Used by load (truncate + synthetic closers) and by live-adoption (truncate
+     * only, `closers = []`).
+     */
+    commitRepair(meta: SessionHeader, tornMarker: TornMarker | undefined, closers: readonly SessionEvent[]): Promise<void>;
+    /**
+     * List all stored (materialized) sessions' metadata.
+     * @param signal - optional cancellation for backend listing work.
+     */
+    list(signal?: AbortSignal): Promise<SessionHeader[]>;
+    /**
+     * Optional lifecycle teardown (e.g. close a database handle). Awaited by the
+     * coordinator's dispose effect AFTER the quiescence drain. A stateless file
+     * backend omits it.
+     */
+    close?(): Promise<void>;
+}
+/**
+ * Owns the backend-agnostic session write-path orchestration. A backend
+ * constructs one (`new PersistenceCoordinator(ctx, this)`), implements
+ * {@link PersistenceBackend}, and delegates its write/read service methods to
+ * the matching coordinator methods.
+ *
+ * All per-id operations are serialized (a per-id promise chain) so concurrent
+ * flushes / a flush racing a load never interleave storage writes. The
+ * constructor installs the write-path listeners, per-session retirement, and
+ * the backend dispose effect.
+ *
+ * @typeParam TornMarker - the backend's opaque torn-tail repair token.
+ */
+export declare class PersistenceCoordinator<TornMarker = unknown> {
+    private ctx;
+    private backend;
+    /** Backend bookkeeping keyed by session id (NOT the live Session object). */
+    private states;
+    /** Lifecycle and write-behind state keyed by the exact live Session. */
+    private live;
+    /** Exact disposed lifecycles whose buffered tail is still draining. */
+    private retirements;
+    /** Shared cold reads, unpublished reservations, and completed LRU entries. */
+    private readonly preparations;
+    /**
+     * Per-session serialization: every operation chains onto the prior one for the
+     * same id, so writes for one session never interleave. Keyed by session id.
+     */
+    private chains;
+    /** Resolved fixed write-batching window shared by per-session controllers. */
+    private readonly writeBatchMaxDelayMs;
+    constructor(ctx: Context, backend: PersistenceBackend<TornMarker>, options?: PersistenceCoordinatorOptions);
+    /**
+     * Register detached session metadata for lazy creation on the first append.
+     * @param meta - header to snapshot; duplicate tracked or persisted ids reject.
+     */
+    create(meta: SessionHeader): Promise<void>;
+    private createCore;
+    /**
+     * Durably persist a batch of events. Honors the append-only and contiguous-seq
+     * contracts; rejects non-JSON-serializable `event.data`.
+     * @param id - the session the batch belongs to.
+     * @param events - the contiguous batch to persist, in seq order; materialized
+     *   as a detached lossless-JSON snapshot at call time.
+     */
+    append(id: SessionId, events: readonly SessionEvent[]): Promise<void>;
+    private appendCore;
+    /**
+     * Prepare and reserve the exact unpublished Session used by resume.
+     * Revision retries converge once the durable log remains unchanged for one
+     * read/check round trip; continuous external writers may delay completion.
+     * @param id - persisted session to prepare.
+     * @param signal - optional cancellation for reading and repair.
+     * @returns an owned preparation released after publication or rollback.
+     */
+    prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>;
+    /**
+     * Commit recovery and return its immutable logical view without publication.
+     * Revision retries converge once the durable log remains unchanged for one
+     * read/check round trip; continuous external writers may delay completion.
+     * @param id - persisted session to load.
+     * @returns prepared header and balanced events.
+     */
+    load(id: SessionId): Promise<SessionInspection>;
+    /**
+     * Inspect a logical session without publishing it or committing recovery.
+     * A stale ready source is reloaded. A source already committing or reserved
+     * for resume remains exclusive, and inspection may borrow its immutable view.
+     * Revision retries converge once the log is stable for one read/check round
+     * trip; continuous external writers may delay completion.
+     * @param id - persisted session to inspect.
+     * @param signal - optional cancellation for preparation work.
+     * @returns immutable prepared metadata and events; a live view may have an open turn.
+     */
+    inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>;
+    /**
+     * Read the stored events from `fromSeq` onward, detached and non-mutating
+     * (the read-from-seq primitive behind the service's `readFrom`). Runs on
+     * the same per-id chain as writes; a backend with the seek-capable
+     * {@link PersistenceBackend.loadStoredFrom} hook reads only the suffix,
+     * every other backend reads its stored prefix and skips forward here.
+     * @param id - persisted session to read.
+     * @param fromSeq - first event seq to include; a non-negative safe integer.
+     * @param signal - optional cancellation for queued and backend read work.
+     * @returns stored header and the valid stored events with `seq >= fromSeq`.
+     */
+    readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{
+        meta: SessionHeader;
+        events: SessionEvent[];
+    }>;
+    private readFromCore;
+    /** Read one detached physical prefix without logical recovery or caching. */
+    private readStoredPrefix;
+    /** Read, repair in memory, validate, and freeze one cold source once. */
+    private prepareCore;
+    /** Commit one prepared repair and establish its ownerless durable cursor. */
+    private commitPrepared;
+    /** Whether one cached source still names the current durable log revision. */
+    private isPreparedSourceCurrent;
+    /** Return one durable immutable view of an already-live Session. */
+    private loadLiveSnapshot;
+    /** Borrow one immutable view from an already-live Session. */
+    private inspectLive;
+    /** Await one retiring lifecycle with caller cancellation. */
+    private waitForRetirement;
+    /**
+     * Run `op` after any in-flight operation for the same session id, so writes for
+     * one session never interleave. Errors do not poison the chain. NOTE: serialized
+     * public methods must NOT call each other (deadlock); they call the unserialized
+     * `*Core` helpers instead.
+     */
+    private serialize;
+    /** Build a state for a session discovered in storage but not yet in memory. */
+    private adopt;
+    private assertVersion;
+    /** Reject backend metadata that is not bound to the requested session id. */
+    private assertStoredId;
+    private installWritePath;
+    /** Start and observe one disposed session's final drain. */
+    private retire;
+    /** Drain and release state owned by one exact disposed Session lifecycle. */
+    private retireCore;
+    /** Return the one lifecycle controller for a live session, creating it if needed. */
+    private initFor;
+    /** Bind one exact prepared Session and persist only its unpublished suffix. */
+    private attachPrepared;
+    /**
+     * Whether a live session's `seed` reproduces the first `cursor` persisted
+     * events. A `cursor` of 0 (nothing persisted yet) trivially matches. Used when
+     * a live session claims ownerless state left by a prior `load()`/`create()`.
+     */
+    private seedMatchesPersisted;
+    /**
+     * On session/created: sync the backend's in-memory state to a live Session.
+     *
+     * Cases, by whether this backend tracks the id and whether an artifact exists:
+     *   1. Already tracked → no-op (or claim ownerless state if the seed matches,
+     *      or reclaim a truly-abandoned id, else reject as a collision).
+     *   2. Not tracked, an artifact EXISTS at the same cwd and is a seq-aligned
+     *      PREFIX of the live events → ADOPT it, persisting any live suffix.
+     *   3. Not tracked, an artifact EXISTS at another cwd or is NOT a prefix →
+     *      REJECT (collision).
+     *   4. Not tracked and NO artifact → a genuinely new session: register meta
+     *      (lazy) and persist its seed once.
+     */
+    private onCreated;
+    /**
+     * Adopt a stored prefix as a live session's history (HMR/reload): verify the
+     * seed covers the stored prefix, truncate any torn tail (NOT the open turn —
+     * the live Session is still the authority), bind ownership, and persist the
+     * live suffix that was ahead of the stored prefix.
+     */
+    private adoptLivePrefix;
+    private flush;
+    /** Build one package-private write controller around initialization and id serialization. */
+    private createWriteBehind;
+    /** Append one controller-owned prefix after filtering events initialization already stored. */
+    private appendLiveBatch;
+}
+//# sourceMappingURL=coordinator.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 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.
+ * @module @deepseek-ai/dsh-session-persistence
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { SessionPreparation } from '@deepseek-ai/dsh-session';
+import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session';
+import type { SessionPersistenceRevision } from './revision.ts';
+export type { SessionHeader } from '@deepseek-ai/dsh-session';
+export { SessionPersistenceRevision } from './revision.ts';
+/** Lightweight immutable source identity returned without loading a full 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;
+}
+/** Immutable logical session prepared from persistence or a live owner. */
+export interface SessionInspection {
+    /** Validated immutable session metadata. */
+    readonly meta: SessionHeader;
+    /** Validated contiguous logical event log. */
+    readonly events: readonly SessionEvent[];
+}
+export { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, PersistenceCoordinator, SessionPersistenceCorruptionError, } 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.
+ */
+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. Backends such
+     * as SQLite that do not own one artifact per session return `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;
+    /**
+     * 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.
+     */
+    abstract create(meta: SessionHeader): 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.
+     * @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>;
+    /**
+     * 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).
+     * Backends whose medium can seek by seq
+     * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
+     * 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 seq to include; a non-negative safe integer.
+     * @param signal - optional cancellation for queued and backend read work.
+     * @returns the header and the stored events with `seq >= fromSeq`.
+     */
+    abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{
+        meta: SessionHeader;
+        events: SessionEvent[];
+    }>;
+    /**
+     * Lightweight listing from metadata, without a full-log parse.
+     * @param signal - optional cancellation for backend listing work.
+     * @returns one header per materialized session.
+     */
+    abstract list(signal?: AbortSignal): Promise<SessionHeader[]>;
+    /**
+     * 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.
+     */
+    abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>;
+}
+export default SessionPersistence;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence`.
+ * @module @deepseek-ai/dsh-session-persistence/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-persistence-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/preparations.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Bounded sharing and exclusive reservation of unpublished Sessions.
+ * @module @deepseek-ai/dsh-session-persistence/preparations
+ */
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+interface PreparedSource {
+    readonly session: Session;
+}
+type PreparationPhase = 'loading' | 'ready' | 'committing' | 'reserved';
+interface PreparationEntry<Source, CommitState> {
+    readonly id: SessionId;
+    readonly result: Promise<Source>;
+    phase: PreparationPhase;
+    source?: Source;
+    reservation?: SessionPreparationReservation<Source, CommitState>;
+    reservationSettled?: Promise<void>;
+    settleReservation?: () => void;
+}
+/** One exclusively held prepared source and its committed persistence state. */
+export interface SessionPreparationReservation<Source, CommitState> {
+    readonly entry: PreparationEntry<Source, CommitState>;
+    readonly source: Source;
+    readonly state: CommitState;
+}
+/** Per-coordinator cold-read sharing, exclusive reservation, and ready-entry LRU. */
+export declare class SessionPreparations<Source extends PreparedSource, CommitState> {
+    private readonly capacity;
+    private readonly entries;
+    constructor(capacity: number);
+    /**
+     * Whether this pool currently knows about an unpublished identity.
+     * @param id - session identity.
+     * @returns whether an entry exists for the identity.
+     */
+    has(id: SessionId): boolean;
+    /**
+     * Observe one prepared source, sharing an in-flight read for the same id.
+     * @param id - session identity.
+     * @param load - cold loader used when no entry exists.
+     * @param signal - optional cancellation signal while waiting.
+     * @returns the shared prepared source.
+     */
+    inspect(id: SessionId, load: () => Promise<Source>, signal?: AbortSignal): Promise<Source>;
+    /**
+     * Reserve one ready source after committing its pending durable repair.
+     * @param id - session identity.
+     * @param load - cold loader used when no entry exists.
+     * @param commit - durable repair and cursor-state commit.
+     * @param signal - optional cancellation signal while waiting.
+     * @returns the exclusive reservation, or undefined if its entry was invalidated.
+     */
+    reserve(id: SessionId, load: () => Promise<Source>, commit: (source: Source) => Promise<{
+        source: Source;
+        state: CommitState;
+    } | undefined>, signal?: AbortSignal): Promise<SessionPreparationReservation<Source, CommitState> | undefined>;
+    /**
+     * Return the exact reservation for Session publication, rejecting aliases.
+     * @param session - exact Session candidate for publication.
+     * @returns its reservation, or undefined when no preparation exists.
+     */
+    reservationFor(session: Session): SessionPreparationReservation<Source, CommitState> | undefined;
+    /**
+     * Consume a reservation after its exact Session has attached.
+     * @param reservation - reservation to consume.
+     */
+    attach(reservation: SessionPreparationReservation<Source, CommitState>): void;
+    /**
+     * Consume a reservation whose caller only needs the committed inspection.
+     * @param reservation - reservation to consume.
+     */
+    discard(reservation: SessionPreparationReservation<Source, CommitState>): void;
+    /**
+     * Return a reusable unpublished reservation to the ready LRU.
+     * @param reservation - reservation to release.
+     * @param reusable - whether the source remains valid for reuse.
+     */
+    release(reservation: SessionPreparationReservation<Source, CommitState>, reusable: boolean): void;
+    /**
+     * Discard a prepared view after the durable log changes.
+     * @param id - changed session identity.
+     */
+    invalidate(id: SessionId): void;
+    /**
+     * Discard an exact stale ready source without disturbing an exclusive owner.
+     * @param id - changed session identity.
+     * @param expected - exact source observed before its revision check.
+     * @returns whether the source was discarded, retained by a reservation, or is absent.
+     */
+    discardReady(id: SessionId, expected: Source): 'discarded' | 'retained' | 'missing';
+    /**
+     * Reject writes while an unpublished Session exclusively reserves the id.
+     * @param id - session identity to check.
+     */
+    assertWritable(id: SessionId): void;
+    /**
+     * Remove a completed entry for an already-serialized append adoption.
+     * @param id - adopted session identity.
+     * @returns the prepared source, or undefined when no ready entry exists.
+     */
+    takeReady(id: SessionId): Source | undefined;
+    private entryFor;
+    private makeReady;
+    private remove;
+    private touch;
+}
+/**
+ * Give a queued observer a prompt cancellation view without cancelling shared work.
+ * @param operation - shared operation whose settlement remains authoritative.
+ * @param signal - observer-local cancellation signal.
+ * @param started - whether the operation has crossed its cancellation cutoff.
+ * @returns the operation result or the observer's prompt cancellation.
+ */
+export declare function observeQueuedAbort<T>(operation: Promise<T>, signal: AbortSignal, started?: () => boolean): Promise<T>;
+export {};
+//# sourceMappingURL=preparations.d.ts.map

package/lib/types/revision.d.ts

@@ -0,0 +1,14 @@
+/** Opaque revision identity for lightweight persistence observations. */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+/**
+ * Backend-owned token that identifies both one storage source and one revision
+ * of a persisted session log.
+ */
+export type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>;
+/**
+ * Brand a backend revision for the provider-neutral persistence contract.
+ * @param value - backend-owned opaque revision representation.
+ * @returns the same runtime string with persistence-revision identity.
+ */
+export declare function SessionPersistenceRevision(value: string): SessionPersistenceRevision;
+//# sourceMappingURL=revision.d.ts.map