@hasna-internal/kai-session-persistence 0.1.1-rc.2

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-session-persistence`.
+* @module @hasna-internal/kai-session-persistence/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-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,348 @@
+/**
+ * Shared buffering, serialization, adoption, repair, and disposal orchestration
+ * for first-party backends. Third-party backends may implement the public
+ * persistence seam directly.
+ * @module @hasna-internal/kai-session-persistence/coordinator
+ */
+import { Context } from '@deepseek-ai/cordis';
+import { SessionPreparation } from '@hasna-internal/kai-session';
+import type { SessionEvent, SessionId, SessionHeader } from '@hasna-internal/kai-session';
+import type { SessionInspection, SessionLocation } 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 today'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> {
+    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.
+     * 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: 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 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.
+     */
+    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;
+    /**
+     * 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/index.d.ts

@@ -0,0 +1,190 @@
+/**
+ * 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 @hasna-internal/kai-session-persistence
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import { SessionPreparation } from '@hasna-internal/kai-session';
+import type { SessionEvent, SessionId, SessionHeader } from '@hasna-internal/kai-session';
+import type { SessionPersistenceRevision } from './revision.ts';
+export type { SessionHeader } from '@hasna-internal/kai-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[];
+}
+/** A backend's own raw artifact text for one session, verbatim. */
+export interface SessionRawArtifact {
+    /** The session header parsed from the artifact's own first line. */
+    readonly meta: SessionHeader;
+    /** 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. 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;
+    /**
+     * 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.
+     */
+    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 `@hasna-internal/kai-session-persistence`.
+ * @module @hasna-internal/kai-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