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

package/lib/types/win32.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Windows durable namespace helpers for the JSONL backend.
+ *
+ * POSIX publishes a newly-created log by creating a directory entry and then
+ * fsyncing the parent directory. Windows does not expose that parent-directory
+ * fsync contract through Node, so the Windows path uses the native durable
+ * namespace primitive instead: create a staging object in the target directory
+ * and publish it with `MoveFileExW(..., MOVEFILE_WRITE_THROUGH)` without
+ * replacement or cross-volume copy fallback.
+ *
+ * @module dsh-session-persistence-jsonl/win32
+ */
+/**
+ * Publish `existing` at `replacement` with Windows write-through rename
+ * semantics. The destination must not already exist; the move must stay within
+ * the volume (no copy fallback flag is set).
+ * @param existing - the synced staging path to move.
+ * @param replacement - the final path, which must not already exist.
+ */
+export declare function publishNewFileWin32(existing: string, replacement: string): Promise<void>;
+/**
+ * Acquire the session write lock as a named kernel semaphore (count 1) whose
+ * name is derived from the canonical lock path. A kernel object never touches
+ * the filesystem, so readers, searches, and directory removal proceed freely
+ * while the lock is held; a second acquirer's zero-timeout wait times out
+ * (`EBUSY`); and when the last handle closes — including on any process
+ * death — the object is destroyed, so a successor's create starts fresh.
+ * @param path - the lock file path the name is derived from (case-folded:
+ *   Windows paths are case-insensitive).
+ * @returns the open semaphore handle, released via {@link releaseLockHandleWin32}.
+ */
+export declare function acquireLockHandleWin32(path: string): Promise<number>;
+/**
+ * Release a lock from {@link acquireLockHandleWin32}: restore the semaphore
+ * count and close the handle (the object dies with its last handle).
+ * @param handle - the open semaphore handle.
+ */
+export declare function releaseLockHandleWin32(handle: number): Promise<void>;
+/**
+ * Create `target` and its missing ancestors with durable Windows namespace
+ * publication. Each missing directory is first created as a random staging
+ * sibling, then moved to its final name with `MOVEFILE_WRITE_THROUGH`; races
+ * with another creator are accepted only after verifying the winner is a
+ * directory.
+ * @param target - the absolute directory path to create durably when absent.
+ */
+export declare function ensureDurableDirectoryWin32(target: string): Promise<void>;
+//# sourceMappingURL=win32.d.ts.map

package/lib/types/worker.d.ts

@@ -0,0 +1,3 @@
+/** Worker entry for current-generation physical and logical verification. */
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/lib/types/zstd-private-decoder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Node-private synchronous Zstandard frame decoder optimization.
+ * @module dsh-session-persistence-jsonl/zstd-private-decoder
+ */
+import type { ZstdFrameDecoder, ZstdFrameRange } from './zstd.ts';
+/**
+ * Synchronous multi-frame decoder backed by one Node Zstd stream handle. Node
+ * exposes synchronous decoding only as a one-shot API, so this adapter uses
+ * the stream's private handle contract to reuse its native context and output
+ * chunks across frames.
+ */
+export declare class NodePrivateZstdFrameDecoder implements ZstdFrameDecoder {
+    private readonly stream;
+    private readonly errorKey;
+    private readonly output;
+    private decoderError?;
+    private started;
+    private closed;
+    private constructor();
+    /**
+     * Create the optimized decoder when this Node release exposes the expected
+     * private stream shape.
+     * @returns a shared decoder, or `undefined` when callers must use the public fallback.
+     */
+    static create(): NodePrivateZstdFrameDecoder | undefined;
+    /** @inheritdoc */
+    decode(source: Buffer, frames: readonly ZstdFrameRange[]): Generator<Buffer, void, void>;
+    /** Decode one frame; its returned scratch view remains valid until the next call. */
+    private decodeFrame;
+    /** @inheritdoc */
+    close(): void;
+}
+//# sourceMappingURL=zstd-private-decoder.d.ts.map

package/lib/types/zstd-public-decoder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public-API synchronous Zstandard frame decoder fallback.
+ * @module dsh-session-persistence-jsonl/zstd-public-decoder
+ */
+import type { ZstdFrameDecoder, ZstdFrameRange } from './zstd.ts';
+/** Multi-frame adapter built exclusively from Node's supported one-shot API. */
+export declare class PublicZstdFrameDecoder implements ZstdFrameDecoder {
+    private started;
+    private closed;
+    /** @inheritdoc */
+    decode(source: Buffer, frames: readonly ZstdFrameRange[]): Generator<Buffer, void, void>;
+    /** @inheritdoc */
+    close(): void;
+}
+//# sourceMappingURL=zstd-public-decoder.d.ts.map

package/lib/types/zstd.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Zstandard frame primitives for the JSONL persistence backend. The backend
+ * owns a concatenated-frame container so it can append and recover batches
+ * without exposing compression mechanics through the persistence seam.
+ * @module dsh-session-persistence-jsonl/zstd
+ */
+/** Byte range occupied by one structurally complete Zstandard frame. */
+export interface ZstdFrameRange {
+    /** Inclusive frame start. */
+    start: number;
+    /** Exclusive frame end. */
+    end: number;
+}
+/** Structural scan result for a concatenated Zstandard stream. */
+export interface ZstdFrameScan {
+    /** Complete frames in file order. */
+    frames: ZstdFrameRange[];
+    /** Start of an incomplete final frame, when EOF interrupts one. */
+    tornStart?: number;
+}
+/**
+ * Locate complete frames without decompressing their blocks. Invalid complete
+ * structure rejects; EOF inside the final frame returns its start for repair.
+ * @param buffer - complete bytes currently present in the session artifact.
+ * @param maxFrames - optional complete-frame limit for metadata-only readers.
+ * @returns complete frame ranges and an optional incomplete-final-frame start.
+ */
+export declare function scanZstdFrames(buffer: Buffer, maxFrames?: number): ZstdFrameScan;
+/**
+ * Compress one independently decodable, checksummed Zstandard frame.
+ * @param input - JSONL bytes for a header or durable event batch.
+ * @returns the complete encoded frame.
+ */
+export declare function compressZstdFrame(input: Buffer | string): Promise<Buffer>;
+/**
+ * Decompress one complete frame and validate its checksum.
+ * @param input - one structurally complete Zstandard frame.
+ * @returns the frame plaintext.
+ */
+export declare function decompressZstdFrame(input: Buffer): Promise<Buffer>;
+/** Common lifecycle for interchangeable synchronous multi-frame decoders. */
+export interface ZstdFrameDecoder {
+    /**
+     * Decode and checksum complete frames in source order. Each yielded buffer
+     * remains valid only until the iterator advances to the next frame.
+     * @param source - concatenated Zstandard frame bytes.
+     * @param frames - structurally complete ranges within `source`.
+     * @returns one plaintext buffer per frame.
+     */
+    decode(source: Buffer, frames: readonly ZstdFrameRange[]): Generator<Buffer, void, void>;
+    /** Release decoder-owned resources; repeated calls are harmless. */
+    close(): void;
+}
+/**
+ * Select the shared private decoder when the running Node 22/24/26 shape is
+ * compatible, otherwise preserve correctness with the public one-shot API.
+ * @returns a synchronous decoder with an implementation-independent lifecycle.
+ */
+export declare function createZstdFrameDecoder(): ZstdFrameDecoder;
+/**
+ * Recover available plaintext from a structurally incomplete final frame.
+ * `ZSTD_e_flush` deliberately suppresses final-frame and checksum completion;
+ * callers must establish the torn frame boundary before using this helper.
+ * @param input - available bytes from a known incomplete Zstandard frame.
+ * @returns plaintext produced from the available input.
+ */
+export declare function decompressZstdPrefix(input: Buffer): Promise<Buffer>;
+//# sourceMappingURL=zstd.d.ts.map