@x1a0f3n9/dsh-session-persistence 0.1.2-alpha.6

package/lib/types/coordinator.d.ts

@@ -0,0 +1,378 @@
+/**
+ * Shared buffering, serialization, adoption, repair, and disposal orchestration
+ * for first-party backends. Third-party backends may implement the public
+ * persistence seam directly.
+ * @module @x1a0f3n9/dsh-session-persistence/coordinator
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { SessionPreparation } from '@x1a0f3n9/dsh-session';
+import type { Session, SessionEvent, SessionId, SessionHeader, SessionLogOffset as SessionLogOffsetType } from '@x1a0f3n9/dsh-session';
+import type { BorrowedSessionSource, SessionEventSuffix, SessionInspection, SessionLocation, SessionStorageMetadata } 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);
+}
+/**
+ * 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 and the event is not marked ignorable. 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 the coordinator's load-time check 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;
+/** 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> extends SessionStorageMetadata {
+    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 extends SessionStorageMetadata {
+    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 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.
+     * Unknown-type refusal follows the same suffix scope: a seek-capable
+     * backend's `readFrom` checks only the returned suffix, while the
+     * sequential fallback parses the whole artifact and refuses on an unknown
+     * required event anywhere in it — over-refusal on the sequential side is
+     * accepted rather than widening the seek read.
+     * @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: SessionLogOffsetType, signal?: AbortSignal): Promise<StoredSuffix | undefined>;
+    /** Durably create an empty header-only session artifact. */
+    materializeHeader?(storage: SessionStorageMetadata): Promise<void>;
+    /**
+     * 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.
+     * The coordinator calls this only after a first batch reaches the declared
+     * inherited prefix length.
+     */
+    appendBatch(storage: SessionStorageMetadata, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>;
+    /**
+     * Replace the durable event log with the supplied contiguous prefix. The
+     * replacement must be durable before the coordinator advances its cursor.
+     * Backends that cannot rewrite their medium omit this hook and reject the
+     * public destructive-truncate operation.
+     * @param storage - metadata identifying the existing artifact.
+     * @param events - complete retained event prefix, possibly empty.
+     */
+    rewrite?(storage: SessionStorageMetadata, events: readonly SessionEvent[]): 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(storage: SessionStorageMetadata, 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 side-effect-free artifact locator, used to point refusal
+     * diagnostics ({@link SessionFormatUnsupportedError}) at the raw log.
+     * Backends without one artifact per session omit it or return `undefined`.
+     * @param meta - the header whose artifact is requested.
+     */
+    locate?(meta: SessionHeader): SessionLocation | undefined;
+    /**
+     * 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.
+     * @param inheritedEventCount - exact inherited prefix length; required for
+     * a seeded header and omitted only for an unseeded header.
+     */
+    create(meta: SessionHeader, inheritedEventCount?: SessionLogOffsetType): Promise<void>;
+    /**
+     * Materialize one exact live session without inventing a session event.
+     * @param session - live session already registered through the write path.
+     */
+    ensureMaterialized(session: Session): 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;
+    /**
+     * Durably remove a live Session turn and every later event. The caller keeps
+     * the live Session unchanged until this method resolves, then applies the
+     * same prefix with {@link Session.truncate}.
+     * @param session - exact live Session owned by this coordinator.
+     * @param length - number of events to retain.
+     */
+    truncate(session: Session, length: SessionLogOffsetType): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * Borrow one exact logical view while pinning its reusable prepared Session.
+     * @param id - persisted session to observe.
+     * @param signal - optional cancellation for preparation work.
+     * @returns a disposable observation retaining the prepared source.
+     */
+    borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>;
+    /**
+     * 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 metadata, the requested offset, and valid events with `seq >= fromSeq`.
+     */
+    readFrom(id: SessionId, fromSeq: SessionLogOffsetType, signal?: AbortSignal): Promise<SessionEventSuffix>;
+    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;
+    /**
+     * Refuse a log containing an event type this build does not know, unless the
+     * writer marked the event ignorable: an unrecognized required event may
+     * change how the rest of the log must be interpreted, so silently skipping
+     * it would reconstruct a wrong session (the envelope contract on
+     * `SessionEvent.ignorable`). Runs on NORMALIZED events — after
+     * `snapshotStoredEvents`/`adoptStoredEvents` has upgraded the legacy shapes
+     * this build still reads and rejected the ones it does not, so those keep
+     * their specific diagnostics.
+     */
+    private assertEventsSupported;
+    /** Build a format refusal that points at the raw artifact when the backend has one. */
+    private unsupported;
+    /** 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/errors.d.ts

@@ -0,0 +1,9 @@
+/** Stable failures exposed by the session-persistence service. */
+import type { SessionId } from '@x1a0f3n9/dsh-session';
+/** The requested Session identity has no materialized durable log. */
+export declare class SessionPersistenceNotFoundError extends Error {
+    readonly sessionId: SessionId;
+    /** @param sessionId - absent durable Session identity. */
+    constructor(sessionId: SessionId);
+}
+//# sourceMappingURL=errors.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,243 @@
+/**
+ * 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 @x1a0f3n9/dsh-session-persistence
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { SessionPreparation, SessionLogOffset } from '@x1a0f3n9/dsh-session';
+import type { Session, SessionEvent, SessionId, SessionHeader } from '@x1a0f3n9/dsh-session';
+import type { SessionPersistenceRevision } from './revision.ts';
+export type { SessionHeader } from '@x1a0f3n9/dsh-session';
+export { SessionPersistenceRevision } from './revision.ts';
+export { SessionPersistenceNotFoundError } from './errors.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;
+}
+/** Logical Session header paired with its exact inherited cut for body-bearing storage operations. */
+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. */
+export interface SessionInspection extends SessionStorageMetadata {
+    /** Validated contiguous logical event log. */
+    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[];
+}
+/** 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;
+}
+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.
+ */
+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}.
+     */
+    abstract readonly supportsRawArtifacts: boolean;
+    /**
+     * 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>;
+    /**
+     * Physically replace a live session's durable log with an earlier prefix.
+     * The caller must apply the matching in-memory truncation only after this
+     * promise resolves. Backends without rewrite support fail loudly.
+     * @param session - exact live Session being changed.
+     * @param length - number of events to retain.
+     */
+    truncate(_session: Session, _length: SessionLogOffset): 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.
+     */
+    abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>;
+    /**
+     * 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`.
+     */
+    abstract readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>;
+    /**
+     * 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