@deepseek-ai/dsh-session-persistence-jsonl 0.1.2-alpha.5 → 0.1.3-alpha.2

package/lib/types/format.d.ts

@@ -8,7 +8,7 @@
  * @module dsh-session-persistence-jsonl/format
  */
 import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/dsh-session';
-import { type SessionStorageMetadata } from '@deepseek-ai/dsh-session-persistence';
+import type { SessionFormatRecovery } from '@deepseek-ai/dsh-session-format';
 /** Physical encoding selected for JSONL session artifacts. */
 export type JsonlCompression = 'zstd' | 'none';
 /**
@@ -18,9 +18,26 @@ export type JsonlCompression = 'zstd' | 'none';
  */
 export declare function logSuffix(compression: JsonlCompression): '.jsonl.zstd' | '.jsonl';
 /**
- * The private version-0 physical header stored as the first JSONL record.
- * Its optional numeric `seedLength` translates to logical lineage metadata
- * plus a separately carried exact inherited cut.
+ * Return the canonical filename for one immutable Session format generation.
+ * Version zero retains the original suffix-only name; every later generation
+ * carries a lowercase numeric `vN` component.
+ * @param version - non-negative safe Session format version.
+ * @param compression - configured JSONL artifact encoding.
+ * @returns the generation filename inside one Session directory.
+ */
+export declare function generationLogFilename(version: number, compression: JsonlCompression): string;
+/**
+ * Parse one canonical generation filename for the selected physical encoding.
+ * Noncanonical, temporary, uppercase, leading-zero, and version-zero-tagged names do
+ * not identify committed generations.
+ * @param filename - one entry from a Session directory.
+ * @param compression - configured JSONL artifact encoding.
+ * @returns its format version, or `undefined` when the name is not canonical.
+ */
+export declare function parseGenerationLogFilename(filename: string, compression: JsonlCompression): number | undefined;
+/**
+ * The current v2 physical header stored as the first JSONL record. The exact
+ * inherited cut lives on the last tagged `session/end-seed` event.
  */
 interface HeaderLine {
     type: 'session';
@@ -29,11 +46,17 @@ interface HeaderLine {
     createdAt: number;
     cwd?: string;
     parentSession?: SessionId;
-    seedLength?: number;
+    isSeeded: boolean;
     origin?: 'subagent';
     delegationDepth: number;
     agentPreset?: string;
 }
+/**
+ * Refuse policy fields that never belong to a released Session header.
+ * @param value - parsed physical header candidate.
+ * @returns nothing after successful validation.
+ */
+export declare function assertNoRetiredHeaderFields(value: unknown): void;
 /**
  * Build the header line object from a {@link SessionHeader}.
  * @param header - the immutable session metadata to serialize.
@@ -82,26 +105,37 @@ export declare function projectDir(root: string, cwd: string | undefined): strin
  */
 export declare function sessionDir(root: string, cwd: string | undefined, id: SessionId): string;
 /**
- * The append-only event-log file path for a session.
+ * Build one immutable Session format generation path.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory (`undefined` → `_no-cwd`).
+ * @param id - the session id, path-encoded via {@link encodeSegment} before filesystem use.
+ * @param version - physical Session format generation.
+ * @param compression - physical artifact encoding and filename suffix.
+ * @returns the selected generation's configured JSONL artifact path.
+ */
+export declare function generationLogPath(root: string, cwd: string | undefined, id: SessionId, version: number, compression: JsonlCompression): string;
+/**
+ * Build the current generation's append target path for a Session.
  * @param root - the backend's session root directory.
  * @param cwd - the session's project directory (`undefined` → `_no-cwd`).
  * @param id - the session id, path-encoded via {@link encodeSegment} before filesystem use.
  * @param compression - physical artifact encoding and filename suffix.
- * @returns the session's configured JSONL artifact path.
+ * @returns the current Session format generation path.
  */
 export declare function logPath(root: string, cwd: string | undefined, id: SessionId, compression: JsonlCompression): string;
 /**
- * Serialize an event batch as JSONL lines (no trailing newline). With
- * `packChunks` on, delta-chunk runs pack into `text-chunks` /
- * `reasoning-chunks` / `tool-call-chunks` storage rows; off writes one event
- * per line. Both modes range-encode provenance at the storage boundary.
- * Reading is layout-blind either way ({@link scanLog} always decodes rows),
- * so the switch changes only newly written bytes.
+ * Serialize a v2 event batch as JSONL lines (no trailing newline). Compact
+ * Assistant streams are nested event data; every event occupies one row.
  * @param events - the batch to serialize, in log order.
- * @param packChunks - whether to pack delta runs into storage rows.
  * @returns the batch's JSONL text; the writer adds the final newline.
  */
-export declare function eventLines(events: readonly SessionEvent[], packChunks: boolean): string;
+export declare function eventLines(events: readonly SessionEvent[]): string;
+/**
+ * Serialize one v2 event as one JSONL record without its trailing newline.
+ * @param event - current event to encode.
+ * @returns one physical JSON record.
+ */
+export declare function eventLine(event: SessionEvent): string;
 interface SessionLogScan {
     meta: SessionHeader;
     inheritedEventCount: SessionLogOffsetType;
@@ -115,9 +149,10 @@ interface SessionLogScan {
  * copied because a decoder may reuse its output buffer after `write()` returns.
  */
 export declare class SessionLogScanner {
+    private readonly recovery;
     private readonly meta;
-    private readonly inheritedEventCount;
-    private readonly events;
+    private readonly restore;
+    private eventCount;
     private fragments;
     private fragmentBytes;
     private inputBytes;
@@ -129,7 +164,7 @@ export declare class SessionLogScanner {
      * Create an event scanner from exactly one newline-terminated header record.
      * @param headerRecord - the complete first JSONL record, including its newline.
      */
-    constructor(headerRecord: Buffer);
+    constructor(headerRecord: Buffer, recovery?: SessionFormatRecovery);
     /**
      * Consume the next raw plaintext chunk, retaining only an incomplete final record.
      * @param chunk - bytes immediately following all previously supplied bytes.
@@ -161,18 +196,5 @@ export declare class SessionLogScanner {
  * @returns the header, preserved event prefix, and byte offset safe to append at.
  */
 export declare function scanLog(buffer: Buffer): SessionLogScan;
-/**
- * Parse just the header line of a log into logical metadata plus its exact
- * inherited cut, or `undefined` if it is missing/not a header.
- * @param firstLine - the first line of a log file (without its trailing newline).
- * @returns parsed storage metadata, or `undefined` for a malformed header.
- */
-export declare function parseHeader(firstLine: string): SessionStorageMetadata | undefined;
-/**
- * Parse only the logical header fields needed by lightweight listing.
- * @param firstLine - first JSONL line without its trailing newline.
- * @returns the logical Session header, or `undefined` for a malformed line.
- */
-export declare function parseHeaderMeta(firstLine: string): SessionHeader | undefined;
 export {};
 //# sourceMappingURL=format.d.ts.map

package/lib/types/generation.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Durable whole-generation publication for JSONL Session artifacts.
+ *
+ * Format packages transform parsed JSON values. This module owns the physical
+ * encoding, exact source identity, immutable generation files, and exclusive
+ * current-generation publication for both configured JSONL suffixes.
+ * @module @deepseek-ai/dsh-session-persistence-jsonl/generation
+ */
+import { type FileHandle } from 'node:fs/promises';
+import type { SessionFormatArtifact, SessionFormatJsonValue, SessionFormatRestore } from '@deepseek-ai/dsh-session-format';
+import type { JsonlCompression } from './format.ts';
+import { publishNewFileWin32 } from './win32.ts';
+/** Pure adapter between backend-owned JSONL framing and the format catalog. */
+export interface JsonlGenerationFormatAdapter {
+    readonly currentVersion: number;
+    /** Create the single-pass codec and migration state for a historical header. */
+    createRestore(header: Record<string, unknown>): SessionFormatRestore;
+    /** Encode one current header record without materializing body rows. */
+    encodeHeader(header: SessionFormatArtifact['header'], inheritedEventCount: number): SessionFormatJsonValue;
+    /** Encode one current event record. */
+    encodeEvent(event: SessionFormatArtifact['events'][number]): SessionFormatJsonValue;
+    /** Classify a supported-version artifact that policy refuses to migrate. */
+    isUnsupportedMigrationError?(error: unknown): error is Error;
+}
+/** Inputs for preparing one historical generation and publishing its current successor later. */
+export interface PrepareJsonlMigrationOptions {
+    /** Immutable generation selected by the backend resolver. */
+    readonly sourcePath: string;
+    /** Version selected from the source filename and independently checked against its header. */
+    readonly sourceVersion: number;
+    /** Canonical filename for `format.currentVersion` in the same Session directory. */
+    readonly currentPath: string;
+    readonly compression: JsonlCompression;
+    readonly format: JsonlGenerationFormatAdapter;
+    /** Validate one selected historical header's identity before any migration write. */
+    readonly validateHistoricalHeader?: (header: Readonly<Record<string, unknown>>) => void | Promise<void>;
+    /** Validate the staged file in an isolated worker before publication. */
+    readonly verifyCurrentFile: (path: string, compression: JsonlCompression, expectedId: string, expectedEventCount: number, expectedPrefix?: JsonlExpectedPrefix, signal?: AbortSignal) => Promise<JsonlVerifiedGeneration>;
+    readonly signal?: AbortSignal;
+}
+/** Small physical identity returned by an isolated generation verifier. */
+export interface JsonlVerifiedGeneration {
+    readonly identity: JsonlPhysicalIdentity;
+    readonly bytes: number;
+    readonly digest: string;
+}
+/** Physical byte prefix already proven to be a valid complete generation. */
+export interface JsonlExpectedPrefix {
+    readonly bytes: number;
+    readonly digest: string;
+}
+/** A historical source changed after its single decode and migration pass. */
+export declare class JsonlGenerationSourceChangedError extends Error {
+    readonly path: string;
+    readonly name = "JsonlGenerationSourceChangedError";
+    /** @param path - historical generation whose revision changed. */
+    constructor(path: string);
+}
+/** Current logical state prepared independently from durable publication. */
+export interface PreparedJsonlMigration {
+    readonly sourceIdentity: JsonlPhysicalIdentity;
+    readonly artifact: SessionFormatArtifact;
+    /** Encode, verify, and exclusively publish once; every call shares the same success or failure. */
+    publish(): Promise<JsonlPhysicalIdentity>;
+}
+/** A historical artifact is intact, but the format edge refuses its contents. */
+export declare class JsonlGenerationUnsupportedMigrationError extends Error {
+    readonly fromVersion: number;
+    readonly reason: Error;
+    readonly name = "JsonlGenerationUnsupportedMigrationError";
+    /**
+     * @param fromVersion - unchanged source generation version.
+     * @param reason - format-edge refusal.
+     */
+    constructor(fromVersion: number, reason: Error);
+}
+/** A current-generation filename already names different or invalid bytes. */
+export declare class JsonlGenerationTargetConflictError extends Error {
+    readonly path: string;
+    readonly reason: Error;
+    readonly name = "JsonlGenerationTargetConflictError";
+    /**
+     * @param path - immutable target that prevented exclusive publication.
+     * @param reason - why the existing target cannot be accepted.
+     */
+    constructor(path: string, reason: Error);
+}
+/** Stat identity captured together with exact generation bytes. */
+export interface JsonlPhysicalIdentity {
+    readonly dev: bigint;
+    readonly ino: bigint;
+    readonly size: bigint;
+    readonly mtimeNs: bigint;
+    readonly ctimeNs: bigint;
+}
+/** Exact bytes of one stable file revision together with the stat identity that proved it stable. */
+export interface StablePhysicalFile {
+    readonly bytes: Buffer;
+    readonly identity: JsonlPhysicalIdentity;
+}
+interface GenerationFileSystem {
+    open(path: string, flags: string, mode?: number): Promise<FileHandle>;
+    readFile(path: string, signal?: AbortSignal): Promise<Buffer>;
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<JsonlPhysicalIdentity>;
+    lstat(path: string): Promise<{
+        isFile(): boolean;
+        isSymbolicLink(): boolean;
+    }>;
+    link(existingPath: string, newPath: string): Promise<void>;
+    rm(path: string): Promise<void>;
+}
+type GenerationBarrierPhase = 'before-source-check' | 'after-publication';
+interface JsonlGenerationInternals {
+    readonly fs: GenerationFileSystem;
+    readonly randomToken: () => string;
+    readonly platform: NodeJS.Platform;
+    readonly publishNewWin32: typeof publishNewFileWin32;
+    readonly barrier: (phase: GenerationBarrierPhase, attempt: number) => void | Promise<void>;
+}
+/** Dependency overrides for an isolated generation runtime. */
+export type JsonlGenerationRuntimeOverrides = Partial<Omit<JsonlGenerationInternals, 'fs'>> & {
+    readonly fs?: Partial<GenerationFileSystem>;
+};
+/** Bound generation operations used by production defaults and deterministic tests. */
+export interface JsonlGenerationRuntime {
+    readStable(path: string, signal?: AbortSignal): Promise<StablePhysicalFile>;
+    prepare(options: PrepareJsonlMigrationOptions): Promise<PreparedJsonlMigration>;
+    verify(path: string, compression: JsonlCompression, expectedId: string, expectedEventCount: number, expectedPrefix?: JsonlExpectedPrefix): Promise<JsonlVerifiedGeneration>;
+}
+/**
+ * Read one stable revision of a JSONL file with a single retry. If an append
+ * overlaps both reads, return the second read's committed pre-read prefix
+ * instead of starving behind a continuous writer.
+ * @param path - the generation file to read.
+ * @param signal - optional cancellation for the stat/read work.
+ * @returns the stable bytes (or the committed prefix) and their stat identity.
+ */
+export declare function readStableJsonlFile(path: string, signal?: AbortSignal): Promise<StablePhysicalFile>;
+/**
+ * Read and validate one complete current generation for an isolated verifier.
+ * @param path - staged or competing current-generation path.
+ * @param compression - configured physical encoding.
+ * @param expectedId - Session identity expected in the header.
+ * @param expectedEventCount - exact logical event count expected after decoding.
+ * @param expectedPrefix - verified migration prefix; an append tail may be present and is not validated.
+ * @returns stable physical identity and digest for publication comparison.
+ */
+export declare function verifyJsonlCurrentGeneration(path: string, compression: JsonlCompression, expectedId: string, expectedEventCount: number, expectedPrefix?: JsonlExpectedPrefix): Promise<JsonlVerifiedGeneration>;
+/**
+ * Decode and migrate one historical generation without writing its successor.
+ * @param options - resolved source, current target, format adapter, and load cancellation.
+ * @returns the current artifact and an idempotent explicit publication operation.
+ */
+export declare function prepareJsonlMigration(options: PrepareJsonlMigrationOptions): Promise<PreparedJsonlMigration>;
+/**
+ * Create one generation runtime with fixed filesystem and publication dependencies.
+ * @param overrides - deterministic filesystem, platform, and race dependencies.
+ * @returns bound generation operations.
+ */
+export declare function createJsonlGenerationRuntime(overrides?: JsonlGenerationRuntimeOverrides): JsonlGenerationRuntime;
+export {};
+//# sourceMappingURL=generation.d.ts.map

package/lib/types/index.d.ts

@@ -1,19 +1,21 @@
 /**
  * JSONL durable session-persistence backend. It stores a header and contiguous
- * events in one append-only file per session, and delegates orchestration to
- * {@link PersistenceCoordinator}. Its side-effect-free locator returns the
- * absolute per-session log target before materialization.
+ * events in immutable generation files under one directory per session and serves the handle-based
+ * `SessionPersistence` API: `create`/`open` return per-session handles, and
+ * every read validates the same fail-closed storage contract.
  * @module @deepseek-ai/dsh-session-persistence-jsonl
  */
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import { SessionPersistence, type BorrowedSessionSource, type PersistenceBackend, type SessionLocation, type SessionPersistenceSnapshot, type SessionEventSuffix, type SessionInspection, type SessionPersistenceRevision as PersistenceRevision, type SessionRawArtifact, type SessionStorageMetadata, type StoredPrefix } from '@deepseek-ai/dsh-session-persistence';
-import type { Session, SessionEvent, SessionId, SessionHeader, SessionLogOffset, SessionPreparation } from '@deepseek-ai/dsh-session';
+import { SessionPersistence, type SessionAccess, type SessionHandle, type SessionHandleReadResult, type SessionPersistenceCreateOptions, type SessionPersistenceListOptions, type SessionPersistenceOpenOptions, type SessionPersistenceSnapshot, type SessionPersistenceStatOptions, type SessionPersistenceRevision as PersistenceRevision } from '@deepseek-ai/dsh-session-persistence';
+import { JsonlSessionHandle } from './storage.ts';
+import { SessionWriteLease } from './lease.ts';
+import type { SessionEvent, SessionId, SessionHeader, SessionLogOffset as SessionLogOffsetType } from '@deepseek-ai/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: where the JSONL backend keeps its session logs, and the packed-row write switch. */
+/** 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
@@ -23,111 +25,185 @@ export interface Config {
      * readable directory; an absent root is created on first materialization.
      */
     root: string;
-    /**
-     * Write runs of consecutive `assistant/chunk` delta events as packed
-     * `text-chunks`/`reasoning-chunks`/`tool-call-chunks` rows (lossless,
-     * ~60% smaller logs measured on a real session). Defaults to true; false
-     * keeps one `SessionEvent` per line for diagnostics. Reading packed rows is
-     * unconditional: a log's layout never depends on this switch.
-     */
-    packChunks?: boolean;
     /** Physical encoding; defaults to checksummed Zstandard frames. */
     compression?: JsonlCompression;
-    /** Maximum cold Session preparations retained for history-to-resume reuse. */
-    preparedSessionCacheSize?: number;
-    /** Fixed live-event coalescing window; not a backend completion deadline. */
-    writeBatchMaxDelayMs?: number;
 }
-/** Opaque coordinator token for replacing bytes recovered from a torn frame. */
-interface JsonlTornMarker {
-    truncateTo: number;
-    recoveredEvents: SessionEvent[];
+/** 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` and (via the coordinator) installs the write-path
- * listeners. Its torn-tail marker carries the byte offset and any events
- * recovered from an incomplete final Zstandard frame.
+ * `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.
  */
-export declare class JsonlSessionPersistence extends SessionPersistence implements PersistenceBackend<JsonlTornMarker> {
+declare class JsonlSessionPersistence extends SessionPersistence {
     config: Config;
-    readonly supportsRawArtifacts = true;
-    static inject: string[];
     static Config: z<Config>;
-    /**
-     * Backend label for coordinator diagnostics and effects. It shadows
-     * `Service.name` without changing the service key captured by the base
-     * constructor.
-     */
+    /** Backend label for diagnostics and effects; shadows `Service.name` without changing the service key. */
     readonly name = "session-persistence-jsonl";
     private root;
-    private packChunks;
     private compression;
-    private coordinator;
     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);
-    /** Resolve the absolute target path without touching the filesystem. */
-    locate(meta: SessionHeader): SessionLocation;
-    create(meta: SessionHeader, inheritedEventCount?: SessionLogOffset): Promise<void>;
-    ensureMaterialized(session: Session): Promise<void>;
-    append(id: SessionId, events: readonly SessionEvent[]): Promise<void>;
-    prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>;
-    load(id: SessionId): Promise<SessionInspection>;
-    inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>;
-    borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>;
-    readFrom(id: SessionId, fromSeq: SessionLogOffset, signal?: AbortSignal): Promise<SessionEventSuffix>;
-    /** Read a stored prefix by id across all project directories when cwd is unknown. */
-    loadStored(id: SessionId, signal?: AbortSignal): Promise<StoredPrefix<JsonlTornMarker> | undefined>;
-    /**
-     * Read one log's stat-derived revision without loading its event bytes.
-     * Resolving an id with unknown cwd still scans the project directories.
-     */
-    readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<PersistenceRevision | undefined>;
-    /**
-     * Read a session's stored artifact text verbatim: the durable file bytes
-     * decoded from this backend's physical encoding (complete zstd frames
-     * concatenated, or UTF-8 plaintext). The content is the exact JSONL text the
-     * backend wrote — never a reconstruction from parsed events — so packed-
-     * chunk rows, key order, and line breaks survive byte-for-byte. A torn
-     * final frame is omitted, matching the committed-prefix semantics of every
-     * other read.
-     * @param id - the persisted session to read.
-     * @param signal - optional cancellation for the stat/read/decode work.
-     * @returns the raw artifact text plus the header parsed from its own first
-     * line, or `undefined` when the session has no stored artifact.
+    /**
+     * 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.
      */
-    readRaw(id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>;
+    private locate;
     /**
-     * Read a file's bytes under a revision-stable loop: a writer appending
-     * between stat and readFile would yield a torn physical file, so retry
-     * while the stat revision changes.
+     * 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>;
+    /**
+     * 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 signal - optional cancellation for the stat/read work.
-     * @returns the stable bytes and the revision that matched both stats.
+     * @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>;
+    /**
+     * 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.
      */
-    private readStableFile;
+    releaseHandle(handle: JsonlSessionHandle, materialized: boolean): void;
     /**
-     * Read a stored prefix and convert torn-tail state to the opaque marker the
-     * coordinator can round-trip without knowing the physical encoding.
+     * 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 readPrefix;
+    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;
-    /** Durably append a batch, lazily materializing the file when not yet present. */
-    appendBatch(storage: SessionStorageMetadata, events: readonly SessionEvent[], isMaterialized: boolean): Promise<void>;
-    /** Materialize a header-only JSONL artifact for an explicitly durable empty session. */
-    materializeHeader(storage: SessionStorageMetadata): Promise<void>;
-    /**
-     * Make a crash repair durable: truncate a torn tail, restore complete events
-     * decoded from it, then append synthetic closers. Two fsync'd steps — the seam
-     * does not require this to be atomic.
-     */
-    commitRepair(storage: SessionStorageMetadata, tornMarker: JsonlTornMarker | undefined, closers: readonly SessionEvent[]): Promise<void>;
-    /** List valid unique stored sessions' metadata (header line only — no full-log parse). */
-    list(signal?: AbortSignal): Promise<SessionHeader[]>;
-    /** List metadata plus a stat-derived identity for each append-only log. */
-    listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>;
     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;
     /** Atomically write the header line + first batch (temp-write, fsync, publish). */
     private materialize;
     private materializePosix;
@@ -157,12 +233,16 @@ export declare class JsonlSessionPersistence extends SessionPersistence implemen
     private readFirstLine;
     /** Read and validate only the independently compressed header frame. */
     private readFirstZstdLine;
-    /** Find the unique physical log for an id across every project directory. */
+    /** 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
@@ -178,11 +258,18 @@ export declare class JsonlSessionPersistence extends SessionPersistence implemen
     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