@x1a0f3n9/dsh-session-persistence-jsonl 0.1.5-alpha.2

package/lib/types/index.d.ts

@@ -0,0 +1,304 @@
+/**
+ * JSONL durable session-persistence backend. It stores a header and contiguous
+ * events in immutable historical generation files under one directory per session.
+ * Normal writes append to the current generation; explicit destructive deletion
+ * rewrites that current generation's retained prefix. It serves the handle-based
+ * `SessionPersistence` API: `create`/`open` return per-session handles, and
+ * every read validates the same fail-closed storage contract.
+ * @module @x1a0f3n9/dsh-session-persistence-jsonl
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { SessionPersistence, type SessionAccess, type SessionHandle, type SessionHandleReadResult, type SessionPersistenceCreateOptions, type SessionPersistenceListOptions, type SessionPersistenceOpenOptions, type SessionPersistenceSnapshot, type SessionPersistenceStatOptions, type SessionPersistenceRevision as PersistenceRevision, type SessionHistorySuffix, type SessionHistorySuffixOptions } from '@x1a0f3n9/dsh-session-persistence';
+import { JsonlSessionHandle } from './storage.ts';
+import { SessionWriteLease } from './lease.ts';
+import type { SessionEvent, SessionId, SessionHeader, SessionLogOffset as SessionLogOffsetType } from '@x1a0f3n9/dsh-session';
+import { type JsonlCompression } from './format.ts';
+export type { JsonlCompression } from './format.ts';
+/** Loader schema for the JSONL artifact's physical encoding. */
+export declare const JsonlCompressionSchema: z<JsonlCompression>;
+/** Plugin config for the JSONL backend's root and physical encoding. */
+export interface Config {
+    /**
+     * Root directory for all session files. Required (no default): a default of
+     * `process.cwd()` would scatter session files as the process's cwd changes
+     * (bash calls, subprocesses). Sessions group under human-readable project
+     * directories, then per-session directories. An existing root must be a
+     * readable directory; an absent root is created on first materialization.
+     */
+    root: string;
+    /** Physical encoding; defaults to checksummed Zstandard frames. */
+    compression?: JsonlCompression;
+}
+/** One stored event graph whose producer has established immutable sharing. */
+interface FrozenStoredEvents extends SessionHandleReadResult {
+    readonly eventState: 'shared-frozen';
+}
+/** State shared by prepared historical and published current logs. */
+interface StoredLogBase extends FrozenStoredEvents {
+    readonly meta: SessionHeader;
+    readonly tornTruncateTo: number | undefined;
+    /** Complete events recovered from the torn final frame; the write path rewrites them durably. */
+    readonly recoveredTail: SessionEvent[];
+    /** Exact fork-inherited prefix length stored in the header line. */
+    readonly inheritedEventCount: SessionLogOffsetType;
+    readonly revision: PersistenceRevision;
+}
+/** A decoded current generation that is already durable. */
+interface CurrentStoredLog extends StoredLogBase {
+    readonly status: 'current';
+}
+/**
+ * The JSONL persistence backend. Load as a plugin; it registers as
+ * `ctx.sessionPersistence`. Sessions materialize lazily: a created session is
+ * visible to this process immediately, reaches disk on its first append or
+ * flush, and never existed if the process crashes before that.
+ */
+declare class JsonlSessionPersistence extends SessionPersistence {
+    config: Config;
+    static Config: z<Config>;
+    /** Backend label for diagnostics and effects; shadows `Service.name` without changing the service key. */
+    readonly name = "session-persistence-jsonl";
+    private root;
+    private compression;
+    private rootEncodingCheck;
+    private readonly tracker;
+    private readonly generationFormat;
+    /**
+     * Bounded LRU of parsed, validated stored logs keyed by session id and
+     * guarded by the stat-derived revision, so an immediate cold-read handoff
+     * (observation then resume) parses the artifact once. Every local mutation
+     * for an id invalidates its entry; a foreign write misses through the
+     * revision guard.
+     */
+    private readonly coldLogMemo;
+    /** One joinable decode/migration operation per selected historical Session file revision. */
+    private readonly migrationPreparations;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Refusal-diagnostics hook: the absolute target path, without touching the filesystem.
+     * @param meta - the stored header naming the session and its cwd.
+     * @returns the artifact kind and absolute path.
+     */
+    private locate;
+    /**
+     * Create a new stored session and take its write ownership. The session is
+     * visible to this process immediately; the physical artifact appears on the
+     * first append or flush.
+     * @param header - the immutable header to store; must be losslessly
+     *   JSON-serializable with a non-negative safe-integer `createdAt`.
+     * @param options - optional cancellation.
+     * @returns the owned write handle.
+     */
+    create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>;
+    /**
+     * Open an existing stored session for `read` or single-writer `write`.
+     * @param id - the stored session to open.
+     * @param access - `read` (no ownership) or `write` (atomic in-process claim).
+     * @param options - optional cancellation.
+     * @returns the open handle.
+     */
+    open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>;
+    /**
+     * Flush every active write handle in one durability barrier; see the seam
+     * contract.
+     * @returns resolution once every write handle active at the call has flushed.
+     */
+    flush(): Promise<void>;
+    /**
+     * Read a tail page of one current-generation JSONL log without restoring
+     * the whole artifact. Historical generations return `undefined` so the
+     * caller can migrate through a full observation.
+     * @param id - the stored session to read.
+     * @param options - page bounds and cancellation.
+     * @returns the covering suffix, or `undefined` when the selected generation
+     *   is older than this build.
+     */
+    readHistorySuffix(id: SessionId, options: SessionHistorySuffixOptions): Promise<SessionHistorySuffix | undefined>;
+    /**
+     * Observe one stored session without reading its event log.
+     * @param id - the stored session to observe.
+     * @param options - optional cancellation.
+     * @returns the snapshot (`sizeBytes` carries the physical artifact size), or
+     *   `undefined` when the session does not exist.
+     */
+    stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>;
+    /**
+     * List every stored session visible to this process: materialized artifacts
+     * plus this process's created-but-unmaterialized sessions.
+     * @param options - optional cancellation.
+     * @returns one snapshot per session, in no promised order.
+     */
+    list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>;
+    /** Resolve and read one stored log, refusing loudly when the artifact is absent. */
+    private requireStoredLog;
+    /** Probe the memo and otherwise decode one historical generation under backend cancellation. */
+    private loadStoredMigration;
+    /** Await shared preparation for one caller and abort it only after its last waiter leaves. */
+    private waitForPreparation;
+    /** Decode one historical generation without publishing a successor. */
+    private prepareStoredMigration;
+    /** Publish a prepared historical log before granting write access. */
+    private publishStoredMigration;
+    /** Translate generation-layer failures into the persistence seam's error vocabulary. */
+    private generationFailure;
+    /**
+     * Read, parse, and validate one stored log as the current logical prefix.
+     * @param path - the artifact file to read.
+     * @param expectedId - the session identity the artifact must carry.
+     * @param signal - optional cancellation for the stat/read/decode work.
+     * @returns the validated stored log with any torn-tail truncation point.
+     */
+    readStoredLog(path: string, expectedId: SessionId, signal?: AbortSignal): Promise<CurrentStoredLog>;
+    /** Decode and memoize one already-stable current physical snapshot. */
+    private decodeStoredLog;
+    /** Insert one parsed log into the bounded handoff cache. */
+    private memoizeStoredLog;
+    /**
+     * Resolve a session's current-generation log path.
+     * @param id - the stored session to locate.
+     * @param signal - optional cancellation for the directory scans.
+     * @returns the current artifact path, or `undefined` while only a historical generation exists.
+     */
+    resolveCurrentLog(id: SessionId, signal?: AbortSignal): Promise<string | undefined>;
+    /**
+     * Rewrite one active session's current generation with an earlier event prefix.
+     * Historical format generations are left in place.
+     * @param id - the session whose write handle is active in this backend.
+     * @param length - number of events to retain.
+     * @returns resolution after the durable rewrite completes.
+     */
+    truncate(id: SessionId, length: SessionLogOffsetType): Promise<void>;
+    /**
+     * Durably append one validated batch; lazily materializes on the first write.
+     * @param header - the session's stored header.
+     * @param events - the validated contiguous batch, in seq order.
+     * @param isMaterialized - whether the session already has a durable artifact.
+     * @param inheritedEventCount - the exact fork-inherited prefix length written into a materializing header line.
+     */
+    persistBatch(header: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean, inheritedEventCount: SessionLogOffsetType): Promise<void>;
+    /**
+     * Materialize a header-only artifact for an explicitly durable empty session.
+     * @param header - the session's stored header.
+     * @param inheritedEventCount - the exact fork-inherited prefix length written into the header line.
+     */
+    persistHeader(header: SessionHeader, inheritedEventCount: SessionLogOffsetType): Promise<void>;
+    /**
+     * Truncate a torn physical tail durably before this session's first new append.
+     * @param header - the session's stored header.
+     * @param truncateTo - the byte offset the artifact is truncated to.
+     */
+    truncateTornTail(header: SessionHeader, truncateTo: number): Promise<void>;
+    /**
+     * Whether this process still tracks a created-but-unmaterialized session.
+     * @param id - the session to test.
+     * @returns true while the pending entry exists.
+     */
+    hasPendingSession(id: SessionId): boolean;
+    /**
+     * Release one handle's backend bookkeeping on close.
+     * @param handle - the closing handle.
+     * @param materialized - whether the session reached durable storage.
+     */
+    releaseHandle(handle: JsonlSessionHandle, materialized: boolean): void;
+    /**
+     * Acquire the session directory's kernel write lock; the kernel holds it
+     * until the handle's close releases the descriptor, including on process death.
+     * @param id - the session the lock guards.
+     * @param cwd - header cwd used to derive the directory for a fresh session.
+     * @param dir - the resolved directory of an existing artifact, when known.
+     * @returns the held lock.
+     */
+    private acquireLease;
+    /**
+     * Acquire the cross-process write lock for a materializing created session,
+     * called by its handle immediately before the first log bytes publish.
+     * @param header - the session's stored header (its cwd derives the directory).
+     * @returns the held lock.
+     */
+    acquireWriteLease(header: SessionHeader): Promise<SessionWriteLease>;
+    /** Decode complete frames and retain complete JSONL records from a torn final frame. */
+    private readZstdPrefix;
+    private listArtifacts;
+    /** Read and translate one selected generation header without inspecting its body. */
+    private readGenerationHeader;
+    /** Convert format-catalog string identities to current branded Session metadata. */
+    private currentHeader;
+    /**
+     * Rewrite the current generation with a contiguous event prefix.
+     * Predecessor format generations are not moved, overwritten, or deleted.
+     * @param header - immutable session metadata stored in the header line.
+     * @param inheritedEventCount - exact fork-inherited prefix count.
+     * @param events - complete retained event prefix.
+     * @returns resolution after the replacement is durable.
+     */
+    rewrite(header: SessionHeader, inheritedEventCount: SessionLogOffsetType, events: readonly SessionEvent[]): Promise<void>;
+    /** Atomically write the header line + first batch (temp-write, fsync, publish). */
+    private materialize;
+    private materializePosix;
+    private materializeWin32;
+    private rejectExistingLog;
+    private writeSyncedTempFile;
+    /** Encode the header and first batch without combining their frame boundaries. */
+    private encodeMaterialization;
+    /** Encode one durable append batch in the configured physical representation. */
+    private encodeEventBatch;
+    /** fsync a POSIX directory so a just-created/renamed entry is crash-durable. */
+    private syncDirPosix;
+    /**
+     * Append and fsync event lines. On a partial write or sync failure, restore the
+     * previous size before rethrowing because the unchanged cursor will retry the
+     * batch; leaving partial bytes would create duplicate sequence numbers.
+     */
+    private appendLines;
+    private rollbackAppend;
+    /** Truncate the log file to `offset` bytes and fsync (discard the crash tail). */
+    private repair;
+    /**
+     * Read the first newline-terminated line of a file without loading the whole
+     * file. Returns undefined if the file is empty or has no complete first line.
+     * Reads in bounded chunks so a huge log costs only the header read.
+     */
+    private readFirstLine;
+    /** Read and validate only the independently compressed header frame. */
+    private readFirstZstdLine;
+    /** Select the numerically highest canonical generation in one Session directory. */
+    private resolveGenerationInDirectory;
+    /** Find the unique authoritative generation for an id across project directories. */
+    private findLog;
+    /** Require an existing configured root to be a readable directory. */
+    private assertUsableRoot;
+    /** Reject metadata that does not identify the selected physical log. */
+    private assertStoredIdentity;
+    /** Validate a supported historical header against the selected source path. */
+    private validateSourceIdentity;
+    /**
+     * Whether two path spellings resolve to the same physical file. This admits
+     * case aliases on case-insensitive filesystems without weakening identity
+     * checks on case-sensitive stores.
+     */
+    private sameFile;
+    /** The human-readable project directories under the configured root. */
+    private listProjectDirs;
+    /** List session-owned directories and reject the obsolete flat-file layout. */
+    private listSessionDirs;
+    /** Reject a root that already belongs to the other physical encoding. */
+    private ensureRootEncoding;
+    private checkRootEncoding;
+    private rejectLegacyFlatArtifact;
+    private rejectOppositeArtifact;
+    /** Return the highest canonical generation encoded with the other configured suffix. */
+    private findOppositeGenerationInDirectory;
+    private oppositeCompression;
+    private encodingMismatch;
+    private legacyLayout;
+    private exists;
+    private assertLogParentAllowsAbsence;
+}
+/**
+ * One open channel onto a JSONL-stored session: the shared storage-handle
+ * scaffolding over this backend's file primitives. Reads re-scan the artifact
+ * under the stable-read loop.
+ */
+export default JsonlSessionPersistence;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/lease.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cross-process write-ownership lock for one session's artifact directory,
+ * held for the whole life of a write handle. The arbiter is the kernel:
+ * POSIX takes a non-blocking `flock(2)` via native system support on `session.lock`
+ * beside the log, and Windows holds a named kernel semaphore derived from
+ * that path — never a file lock or handle, so readers, searches, and
+ * directory removal proceed freely while the lock is held. Contention maps
+ * to `SessionAlreadyOwnedError`; the kernel releases the lock when the
+ * holder's descriptor or last object handle closes, including on any process
+ * death, so a crashed holder never blocks a successor. A live but wedged
+ * holder keeps the lock until its process exits: there is deliberately no
+ * expiry that could expropriate a stalled writer whose resumed appends would
+ * tear the log.
+ * A POSIX lock names an inode, not a path, so after locking the holder
+ * verifies the locked inode is still the file at the lock path and retries
+ * otherwise: an unlinked-and-recreated lock file carries a fresh inode, and
+ * a lock on the orphaned one proves nothing. Removing a live session's lock
+ * file therefore forfeits exclusion on POSIX (nothing in the harness does
+ * so); Windows has no lock file at all. Readers never touch the lock.
+ * The lock is acquired at write-open of an existing artifact and, for a
+ * created session, only right before its first materializing write — an
+ * unmaterialized session has no filesystem footprint. Release never removes
+ * the POSIX lock file: every acquired lock belongs to a materialized or
+ * materializing session, and the surviving file keeps the stable inode later
+ * lockers verify against. The browser worker stubs the native flock entry to
+ * immediate success: it is single-process, so the in-process write claim
+ * already excludes every writer.
+ * @module @x1a0f3n9/dsh-session-persistence-jsonl/lease
+ */
+import type { SessionId } from '@x1a0f3n9/dsh-session';
+/** Base name of the kernel lock file inside a session's directory. */
+export declare const LEASE_FILENAME = "session.lock";
+/**
+ * One held write lock. Constructed only by {@link SessionWriteLease.acquire};
+ * `release` closes the descriptor or handle, which is what releases the lock.
+ */
+export declare class SessionWriteLease {
+    private readonly held;
+    private released;
+    private constructor();
+    /**
+     * Acquire the session directory's kernel write lock.
+     * @param dir - the session's artifact directory (created if absent).
+     * @param id - the session the lock guards, for error identities.
+     * @returns the held lock.
+     * @throws {SessionAlreadyOwnedError} while another holder keeps the lock.
+     */
+    static acquire(dir: string, id: SessionId): Promise<SessionWriteLease>;
+    /**
+     * Release the kernel lock by closing its descriptor or handle. The POSIX
+     * lock file is never removed: every acquired lock belongs to a
+     * materialized or materializing session, and keeping the file preserves
+     * the stable inode later lockers verify against. Idempotent.
+     */
+    release(): Promise<void>;
+}
+//# sourceMappingURL=lease.d.ts.map

package/lib/types/migration-verifier.d.ts

@@ -0,0 +1,15 @@
+/** Isolated verification for a staged or competing current JSONL generation. */
+import type { JsonlCompression } from './format.ts';
+import type { JsonlExpectedPrefix, JsonlVerifiedGeneration } from './generation.ts';
+/**
+ * Verify one current generation in a fresh Worker Thread.
+ * @param path - staged or competing current-generation path.
+ * @param compression - configured physical encoding.
+ * @param expectedId - Session id expected in the decoded header.
+ * @param expectedEventCount - exact logical event count expected after decoding.
+ * @param expectedPrefix - verified physical prefix; an append tail may be present and is not validated.
+ * @param signal - optional cancellation for scheduler wait and Worker execution.
+ * @returns stable physical identity and digest observed by the worker.
+ */
+export declare function verifyCurrentGenerationInWorker(path: string, compression: JsonlCompression, expectedId: string, expectedEventCount: number, expectedPrefix?: JsonlExpectedPrefix, signal?: AbortSignal): Promise<JsonlVerifiedGeneration>;
+//# sourceMappingURL=migration-verifier.d.ts.map

package/lib/types/storage.d.ts

@@ -0,0 +1,263 @@
+/**
+ * The JSONL provider's session storage runtime: its concrete write/read
+ * handle with a per-handle mutation chain and a routed live write-behind
+ * buffer, the in-process bookkeeping that enforces one active writer per
+ * session id, and the backend's live event routing and teardown. Deliberately
+ * provider-local: the persistence seam exposes only the service and handle
+ * contracts, and the shared contract suites pin equivalent observable
+ * behavior across providers.
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@x1a0f3n9/dsh-session';
+import { SessionPersistenceRevision } from '@x1a0f3n9/dsh-session-persistence';
+import type { SessionAccess, SessionHandle, SessionHandleAppendOptions, SessionHandleFlushOptions, SessionHandleReadOptions, SessionHandleReadResult } from '@x1a0f3n9/dsh-session-persistence';
+import type { SessionWriteLease } from './lease.ts';
+/** Maximum intentional wait before a routed live session batch starts writing. */
+export declare const LIVE_WRITE_BATCH_MAX_DELAY_MS = 200;
+/** The file-storage primitives the handle drives on its owning service. */
+export interface JsonlHandleStorage {
+    /** Append encoded lines; `isMaterialized` selects create-vs-extend publication. */
+    persistBatch(header: SessionHeader, events: readonly SessionEvent[], isMaterialized: boolean, inheritedEventCount: SessionLogOffset): Promise<void>;
+    /** Materialize the header-only artifact for an explicitly flushed empty session. */
+    persistHeader(header: SessionHeader, inheritedEventCount: SessionLogOffset): Promise<void>;
+    /** Truncate a torn physical tail before the first new append lands. */
+    truncateTornTail(header: SessionHeader, truncateTo: number): Promise<void>;
+    /** Rewrite the current generation with an earlier contiguous event prefix. */
+    rewrite(header: SessionHeader, inheritedEventCount: SessionLogOffset, events: readonly SessionEvent[]): Promise<void>;
+    /** Resolve the current-generation artifact path, or `undefined` when absent. */
+    resolveCurrentLog(id: SessionId, signal?: AbortSignal): Promise<string | undefined>;
+    /** Read and validate the stored log at `path`, including its established event aliasing state. */
+    readStoredLog(path: string, expectedId: SessionId, signal?: AbortSignal): Promise<SessionHandleReadResult>;
+    /** Whether the id is still a created-but-unmaterialized session here. */
+    hasPendingSession(id: SessionId): boolean;
+    /** Acquire the session's cross-process write lock in its artifact directory. */
+    acquireWriteLease(header: SessionHeader): Promise<SessionWriteLease>;
+    /** Drop the handle's bookkeeping on close. */
+    releaseHandle(handle: JsonlSessionHandle, materialized: boolean): void;
+}
+/** Mutable per-handle log state; a write handle is its session's single mutator. */
+export interface StorageHandleState {
+    /** The stored next-seq (the logical end this handle knows). */
+    cursor: number;
+    /** Whether the session has a durable artifact yet. */
+    materialized: boolean;
+    /** Torn-tail truncation point, consumed by the first new append. */
+    tornTruncateTo?: number | undefined;
+    /** Complete events recovered from the torn final frame; the first mutation rewrites them durably. */
+    recoveredTail?: SessionEvent[] | undefined;
+    /** Exact fork-inherited prefix length stored with the log; `0` when unseeded. */
+    inheritedEventCount: SessionLogOffset;
+    /** The validated stored prefix from a write open, served to reads until the first append. */
+    primed?: SessionHandleReadResult | undefined;
+}
+/**
+ * The JSONL session handle. Mutations serialize on a per-handle promise
+ * chain; reads re-scan the artifact on demand and never observe a shorter log
+ * than a prior read on this handle. Routed live events buffer in a bounded
+ * window and drain through the same chain as explicit appends.
+ */
+export declare class JsonlSessionHandle implements SessionHandle {
+    private readonly storage;
+    readonly id: SessionId;
+    readonly header: SessionHeader;
+    readonly access: SessionAccess;
+    private readonly state;
+    /** The cross-process write lock; a create handle acquires it lazily at first materialization. */
+    private lease?;
+    private chain;
+    private closing;
+    private observedLength;
+    /** Routed live events awaiting their batching deadline (persistence-owned copies). */
+    private buffered;
+    private batchTimer;
+    /** Set when a drain failed; the automatic timer stays quiet until the next drain. */
+    private drainPaused;
+    private draining;
+    constructor(storage: JsonlHandleStorage, id: SessionId, header: SessionHeader, access: SessionAccess, state: StorageHandleState, 
+    /** The cross-process write lock; a create handle acquires it lazily at first materialization. */
+    lease?: SessionWriteLease | undefined);
+    /** Exact fork-inherited prefix length stored with this session's log. */
+    get inheritedEventCount(): SessionLogOffset;
+    /**
+     * Read a slice of the valid contiguous logical log; see the seam contract.
+     * @param offset - first logical seq to include (default 0).
+     * @param length - maximum events returned (default: the rest).
+     * @param options - optional cancellation.
+     * @returns a slice carrying the aliasing state established by its producer.
+     */
+    read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<SessionHandleReadResult>;
+    /** Read one slice from the prepared historical prefix retained by this handle. */
+    private readPrimed;
+    /** Read one current physical generation and enforce this handle's monotonic view. */
+    private readCurrent;
+    /**
+     * Durably append a contiguous batch; see the seam contract.
+     * @param events - the contiguous batch in seq order.
+     * @param options - optional cancellation observed before the write starts.
+     */
+    append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>;
+    /**
+     * Replace the current generation with an earlier contiguous prefix.
+     * @param length - number of events to retain.
+     * @returns resolution after the rewritten prefix is durable.
+     */
+    truncate(length: SessionLogOffset): Promise<void>;
+    /**
+     * Durability barrier; materializes the artifact when nothing has been
+     * appended yet, so an explicitly flushed empty session survives this process.
+     * @param options - optional cancellation observed before the barrier starts.
+     */
+    flush(options?: SessionHandleFlushOptions): Promise<void>;
+    /**
+     * Release the handle; see the seam contract. Idempotent and uncancellable.
+     * A write handle first drains its routed live buffer through the still-open
+     * storage, so backend teardown loses nothing regardless of which fiber
+     * unwinds first; a drain or lock-release failure still frees the in-process
+     * claim, then rejects — both failures together reject as one
+     * `AggregateError`.
+     * @returns settlement of the release.
+     */
+    close(): Promise<void>;
+    /** `await using` support: delegates to {@link close}. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Buffer one published live session event and arm the bounded batching
+     * window when it is idle. The routing installer is the only caller.
+     * @param event - the live event, retained as a persistence-owned copy.
+     * @param reportBackgroundFailure - observes a deadline-driven drain failure
+     *   (the events stay buffered; the next {@link drainLive} retries loudly).
+     */
+    enqueueLive(event: SessionEvent, reportBackgroundFailure: (error: unknown) => void): void;
+    /**
+     * Durably drain the routed live buffer through the mutation chain;
+     * concurrent callers join one drain, and a failure retains the batch in
+     * order so `session/flush` can retry and reject loudly.
+     */
+    drainLive(): Promise<void>;
+    private drainBuffered;
+    /** The shared durable-append body: contiguity, ownership, torn-tail repair, storage write, state advance. */
+    private persistContiguous;
+    /**
+     * Hold the cross-process write lock before this session's first durable
+     * write. An open write handle holds it from construction; a create handle
+     * acquires it here — immediately before the first log bytes publish — and
+     * keeps it through close even when materialization then fails, so a
+     * materializing session stays exclusively owned across retries.
+     */
+    private ensureLease;
+    /** Serialize one operation onto the chain without the closed-handle refusal (drain-from-close). */
+    private enqueueChain;
+    /** Serialize one public mutating operation onto this handle's chain. */
+    private run;
+    private assertOpen;
+}
+/** One created-but-unmaterialized session tracked in this process only. */
+export interface PendingSession {
+    readonly header: SessionHeader;
+    readonly revision: SessionPersistenceRevision;
+    /** Exact fork-inherited prefix length supplied at create. */
+    readonly inheritedEventCount: SessionLogOffset;
+}
+/**
+ * The JSONL backend's in-process bookkeeping: the single active writer per
+ * session id (doubling as the live event router), the open-handle set the
+ * teardown sweep closes, and the created-but-unmaterialized sessions this
+ * process can already observe.
+ */
+export declare class JsonlBackendTracker {
+    private readonly name;
+    /** Every open handle; teardown closes what remains. */
+    readonly openHandles: Set<SessionHandle>;
+    /** `null` marks a claim whose handle is still being constructed. */
+    private readonly writers;
+    private readonly pending;
+    private counter;
+    /** @param name - backend label used in in-memory revision tokens and teardown errors. */
+    constructor(name: string);
+    /**
+     * Claim write ownership and record the created session as pending, making
+     * it observable to this process before it materializes. Before
+     * materialization this registration is the only guard — session ids do not
+     * collide across processes, and no durable artifact exists for another
+     * process to open; the handle takes the cross-process lock at its first
+     * materializing write.
+     * @param header - the validated detached header.
+     * @param inheritedEventCount - the exact fork-inherited prefix length.
+     * @throws {SessionAlreadyExistsError} when a concurrent create or an open
+     *   write handle holds the id — for create, the duplicate is the fact.
+     */
+    registerCreated(header: SessionHeader, inheritedEventCount: SessionLogOffset): void;
+    /**
+     * Claim write ownership for an existing session.
+     * @param id - the session to claim.
+     * @throws {SessionAlreadyOwnedError} when an active write handle exists.
+     */
+    claimWrite(id: SessionId): void;
+    /**
+     * Roll a failed write open back.
+     * @param id - the session whose claim is dropped.
+     */
+    releaseClaim(id: SessionId): void;
+    /**
+     * The pending entry for a created-but-unmaterialized session, if any.
+     * @param id - the session to look up.
+     * @returns the pending header and in-memory revision.
+     */
+    pendingOf(id: SessionId): PendingSession | undefined;
+    /**
+     * Whether this process still tracks a created-but-unmaterialized session.
+     * @param id - the session to test.
+     * @returns true while the pending entry exists.
+     */
+    hasPending(id: SessionId): boolean;
+    /**
+     * Return the active writer for one session, if this process owns it.
+     * @param id - the session to resolve.
+     * @returns the active writer, or undefined while no writer is open.
+     */
+    writerOf(id: SessionId): JsonlSessionHandle | undefined;
+    /**
+     * Iterate the pending sessions for listing.
+     * @returns the pending entries, keyed by session id.
+     */
+    pendingEntries(): IterableIterator<[SessionId, PendingSession]>;
+    /**
+     * Drop a pending entry once the session materialized durably.
+     * @param id - the session that reached durable storage.
+     */
+    materialized(id: SessionId): void;
+    /**
+     * Track one open handle for teardown and, for a write handle, bind it as
+     * the session's live event route.
+     * @param handle - the just-constructed handle.
+     * @returns the same handle, for construction-site chaining.
+     */
+    adopt(handle: JsonlSessionHandle): JsonlSessionHandle;
+    /**
+     * Release one handle's bookkeeping on close. A write handle drops its
+     * ownership claim; a creator that never materialized leaves nothing behind —
+     * the session never existed.
+     * @param handle - the closing handle.
+     * @param materialized - whether the session reached durable storage.
+     */
+    release(handle: JsonlSessionHandle, materialized: boolean): void;
+    /**
+     * Drain and flush every active write handle — the service-wide durability
+     * barrier behind `SessionPersistence.flush`.
+     * @throws {AggregateError} naming each session whose flush failed; the
+     *   remaining handles still flush.
+     */
+    flushAll(): Promise<void>;
+    /**
+     * Install the backend's live session routing and teardown. Persistence
+     * enforces one active write handle per id, so the listeners route published
+     * sessions' events by id; the teardown effect closes every open handle —
+     * close drains the routed buffer — and aggregates failures. This provider
+     * owns no separate storage connection, so closing handles is the complete
+     * teardown. Registrations are effects of the current fiber.
+     * @param ctx - the backend's context.
+     */
+    install(ctx: Context): void;
+}
+//# sourceMappingURL=storage.d.ts.map

package/lib/types/testing/generation.d.ts

@@ -0,0 +1,8 @@
+import { type JsonlGenerationRuntime, type JsonlGenerationRuntimeOverrides } from '../generation.ts';
+/**
+ * Create generation operations with deterministic I/O and race seams for tests.
+ * @param overrides - deterministic filesystem, platform, and race dependencies.
+ * @returns bound generation operations.
+ */
+export declare function createJsonlGenerationTestRuntime(overrides?: JsonlGenerationRuntimeOverrides): JsonlGenerationRuntime;
+//# sourceMappingURL=generation.d.ts.map