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

package/lib/types/format.d.ts

@@ -0,0 +1,209 @@
+/**
+ * On-disk format helpers for the JSONL session-persistence backend: path
+ * sanitization (a {@link SessionId} is an unvalidated branded string, so it
+ * MUST be encoded before use in a path — no traversal, no collision), the
+ * per-project/session directory layout, header-line (de)serialization, and the
+ * truncation-repair offset computation.
+ *
+ * @module dsh-session-persistence-jsonl/format
+ */
+import type { SessionEvent, SessionHeader, SessionId, SessionLogOffset as SessionLogOffsetType } from '@x1a0f3n9/dsh-session';
+import type { SessionFormatRecovery, SessionFormatRestore } from '@x1a0f3n9/dsh-session-format';
+/** Physical encoding selected for JSONL session artifacts. */
+export type JsonlCompression = 'zstd' | 'none';
+/**
+ * Return the artifact suffix for one physical encoding.
+ * @param compression - configured JSONL artifact encoding.
+ * @returns `.jsonl.zstd` for Zstandard or `.jsonl` for plaintext.
+ */
+export declare function logSuffix(compression: JsonlCompression): '.jsonl.zstd' | '.jsonl';
+/**
+ * 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 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';
+    version: number;
+    id: SessionId;
+    createdAt: number;
+    cwd?: string;
+    parentSession?: SessionId;
+    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.
+ * @param inheritedEventCount - exact inherited prefix length; required for a
+ * seeded header and omitted only for an unseeded header.
+ * @returns the `type: 'session'`-tagged line object, absent optional fields omitted (never null).
+ */
+export declare function toHeaderLine(header: SessionHeader, inheritedEventCount?: SessionLogOffsetType): HeaderLine;
+/**
+ * Encode an arbitrary string as a single safe path segment, injectively over ALL JS (UTF-16)
+ * strings — including lone surrogates. A {@link SessionId} is an unvalidated branded string,
+ * so this neutralizes `../`, absolute paths, NUL, and separators before any filesystem use.
+ * Safe code units remain literal; every other unit, including `~`, becomes
+ * `~XXXX`. Operating on code units preserves lone surrogates, while special-
+ * casing `.` and `..` prevents traversal by an otherwise safe whole segment.
+ *
+ * @param raw - the string to encode; must be non-empty (throws on `''`).
+ * @returns the escaped single path segment, decodable back to `raw`.
+ */
+export declare function encodeSegment(raw: string): string;
+/**
+ * Build the readable directory key for a project path.
+ * Filesystem separators and drive separators become `-`; unsafe code units use
+ * the same `~XXXX` escape as session ids. The key is bounded for filesystem
+ * component limits. Separator replacement and truncation are intentionally
+ * lossy, following the common human-navigable project-directory convention.
+ * @param cwd - the session's project directory.
+ * @returns a single filesystem-safe project directory name.
+ */
+export declare function projectKey(cwd: string): string;
+/**
+ * The configured root's human-navigable project directory. A configured root
+ * may be local or shared; this grouping does not prescribe its deployment.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory; `undefined` selects `_no-cwd`.
+ * @returns the project directory path under `root`.
+ */
+export declare function projectDir(root: string, cwd: string | undefined): string;
+/**
+ * The directory owned by one session and available for future session-local
+ * artifacts.
+ * @param root - the backend's session root directory.
+ * @param cwd - the session's project directory.
+ * @param id - the session id, encoded to one safe path segment.
+ * @returns the session directory beneath its project directory.
+ */
+export declare function sessionDir(root: string, cwd: string | undefined, id: SessionId): string;
+/**
+ * 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 current Session format generation path.
+ */
+export declare function logPath(root: string, cwd: string | undefined, id: SessionId, compression: JsonlCompression): string;
+/**
+ * Serialize a current 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.
+ * @returns the batch's JSONL text; the writer adds the final newline.
+ */
+export declare function eventLines(events: readonly SessionEvent[]): string;
+/**
+ * Serialize one current 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;
+    events: SessionEvent[];
+    committedBytes: number;
+}
+/**
+ * Parse one complete header record supplied independently from event rows.
+ * @param record - the complete first JSONL record, including its newline.
+ * @returns logical metadata and a restore stream positioned after the header.
+ */
+export declare function parseHeaderRecord(record: Buffer): {
+    readonly meta: SessionHeader;
+    readonly restore: SessionFormatRestore;
+};
+/**
+ * Incrementally scan complete JSONL event records after an independently
+ * supplied header record. Newline search and byte offsets stay on raw buffers;
+ * only complete records are decoded to UTF-8. A fragment crossing writes is
+ * copied because a decoder may reuse its output buffer after `write()` returns.
+ */
+export declare class SessionLogScanner {
+    private readonly recovery;
+    private readonly meta;
+    private readonly restore;
+    private eventCount;
+    private fragments;
+    private fragmentBytes;
+    private inputBytes;
+    private committedBytes;
+    private eventLine;
+    private issue;
+    private finished;
+    /**
+     * Create an event scanner from exactly one newline-terminated header record.
+     * @param headerRecord - the complete first JSONL record, including its newline.
+     */
+    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.
+     */
+    write(chunk: Buffer): void;
+    /**
+     * Snapshot progress before appending a recoverable torn-frame prefix.
+     * @returns byte, committed-prefix, and expanded-event cursors.
+     */
+    checkpoint(): {
+        inputBytes: number;
+        committedBytes: number;
+        eventCount: SessionLogOffsetType;
+    };
+    /**
+     * Finish scanning, ignoring a final record without a newline as a torn tail.
+     * @returns the header, contiguous event prefix, and safe truncation offset.
+     */
+    finish(): SessionLogScan;
+    /** Decode one complete event row and update the contiguous prefix. */
+    private consumeEventLine;
+}
+/**
+ * Parse a complete or torn JSONL buffer into its preserved event prefix. This
+ * compatibility wrapper supplies the first record separately, then delegates
+ * event rows to {@link SessionLogScanner}.
+ *
+ * @param buffer - the raw bytes of the log file (header line first).
+ * @returns the header, preserved event prefix, and byte offset safe to append at.
+ */
+export declare function scanLog(buffer: Buffer): SessionLogScan;
+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 @x1a0f3n9/dsh-session-persistence-jsonl/generation
+ */
+import { type FileHandle } from 'node:fs/promises';
+import type { SessionFormatArtifact, SessionFormatJsonValue, SessionFormatRestore } from '@x1a0f3n9/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/history-suffix.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tail-page decoder for JSONL session logs. It scans cheap Zstandard frame
+ * boundaries and decompresses only the newest frames that cover one history
+ * page, without constructing a {@link SessionLogScanner} from seq 0.
+ */
+import type { SessionHistorySuffix, SessionHistorySuffixOptions } from '@x1a0f3n9/dsh-session-persistence';
+import { type JsonlCompression } from './format.ts';
+/**
+ * Decode one history-page suffix from a current-generation JSONL artifact.
+ * @param bytes - complete file bytes, possibly with a torn final Zstandard frame.
+ * @param compression - physical encoding of this generation.
+ * @param options - page bounds and cancellation.
+ * @returns header, covering events, and the logical cursor.
+ */
+export declare function readJsonlHistorySuffix(bytes: Buffer, compression: JsonlCompression, options: SessionHistorySuffixOptions): Promise<SessionHistorySuffix>;
+//# sourceMappingURL=history-suffix.d.ts.map