@hy-sde-org/dsh-zstd-frame 0.1.1-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hy-sde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @hy-sde-org/dsh-zstd-frame
+
+Zstandard frame primitives shared by the DeepSeek Harness session
+persistence backend (`session.jsonl.zstd`) and the project memory bank
+(`bank.jsonl.zstd`). Both store append-only, checksummed, per-batch zstd
+frames; this package owns the structural scan, the one-shot compress /
+decompress API with checksum, torn-frame recovery, and the interchangeable
+multi-frame decoders, so consumers never reimplement frame layout or
+Node-private decoder lifecycle.
+
+Published standalone as `@hy-sde-org/dsh-zstd-frame`; it mirrors
+`@deepseek-ai/dsh-zstd-frame` in the [hy-sde deepseek-harness fork](https://github.com/hy-sde/deepseek-harness).
+
+Backed entirely by `node:zlib` — no native module, works in-process.
+
+## API
+
+```ts
+import {
+  compressZstdFrame,
+  decompressZstdFrame,
+  decompressZstdFrameSync,
+  decompressZstdPrefix,
+  scanZstdFrames,
+  createZstdFrameDecoder,
+} from '@hy-sde-org/dsh-zstd-frame'
+```
+
+- `scanZstdFrames(buffer, maxFrames?)` → `{ frames: ZstdFrameRange[], tornStart? }` —
+  locate complete frames without decompressing their blocks; EOF inside the
+  final frame returns its start for repair.
+- `compressZstdFrame(input)` — one independently decodable, checksummed frame.
+- `decompressZstdFrame(input, maxOutput?)` / `decompressZstdFrameSync(...)` —
+  one-frame decompression with optional plaintext bound.
+- `decompressZstdPrefix(input)` — recover available plaintext from a
+  structurally incomplete final frame.
+- `createZstdFrameDecoder()` — `NodePrivateZstdFrameDecoder` when the running
+  Node shape is compatible, else `PublicZstdFrameDecoder`; both implement the
+  common `ZstdFrameDecoder` interface (`decode(source, frames)` generator +
+  `close()`).
+
+## Known Limitations and Deferred Work
+
+- The private-handle decoder (`NodePrivateZstdFrameDecoder`) depends on the
+  private `zlib._handle.writeSync` shape, which the public Node API does not
+  document; the decoder feature-probes at load and falls back to the
+  one-shot-based `PublicZstdFrameDecoder` when the shape is incompatible, so
+  correctness never depends on private internals.
+- No streaming incremental compressor; frames are written whole per batch.
+- Only *checksummed* frames are produced by `compressZstdFrame`
+  (`ZSTD_c_checksumFlag`), and `decompressZstdPrefix` deliberately suppresses
+  final-frame/checksum completion — callers must establish the torn boundary
+  themselves before using it.
+
+The optional `./invariant` entry registers the package into a Cordis host's
+`ctx.invariants` service (no-op) and needs `@deepseek-ai/cordis` +
+`@deepseek-ai/dsh-invariants` peers only when you use that entry.
+
+## License
+
+MIT. Derived from the DeepSeek Harness codebase; see
+`THIRD-PARTY-NOTICES.md` for provenance.

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Zstandard frame primitives shared by the JSONL session persistence backend
+ * and the project memory bank. Both store append-only, checksummed, per-batch
+ * zstd frames; this package owns the structural scan, the one-shot compress /
+ * decompress API, torn-frame recovery, and the interchangeable multi-frame
+ * decoders, so consumers never reimplement frame layout or Node-private
+ * decoder lifecycle.
+ *
+ * Backed entirely by `node:zlib` — no native module, works in-process.
+ * @module @hy-sde-org/dsh-zstd-frame
+ */
+export { NodePrivateZstdFrameDecoder } from './zstd-private-decoder.ts';
+export { PublicZstdFrameDecoder } from './zstd-public-decoder.ts';
+/** 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.
+ * @param maxOutput - optional plaintext bound; oversized frames reject with the Node error.
+ * @returns the frame plaintext.
+ */
+export declare function decompressZstdFrame(input: Buffer, maxOutput?: number): Promise<Buffer>;
+/**
+ * Synchronous one-frame decompression with an optional plaintext bound — for
+ * sync-only readers (the `memory:project` prompt section reads bank files with
+ * `readFileSync`). Keeps checksum validation identical to the async path.
+ * @param input - one structurally complete Zstandard frame.
+ * @param maxOutput - optional plaintext bound; oversized frames reject.
+ * @returns the frame plaintext.
+ */
+export declare function decompressZstdFrameSync(input: Buffer, maxOutput?: number): 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=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAA;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AAYjE,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAA2B,GAAG,aAAa,CAwDlG;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE/E;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5F;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;IACxF,oEAAoE;IACpE,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEzE"}

package/dist/index.js

@@ -0,0 +1,143 @@
+/**
+ * Zstandard frame primitives shared by the JSONL session persistence backend
+ * and the project memory bank. Both store append-only, checksummed, per-batch
+ * zstd frames; this package owns the structural scan, the one-shot compress /
+ * decompress API, torn-frame recovery, and the interchangeable multi-frame
+ * decoders, so consumers never reimplement frame layout or Node-private
+ * decoder lifecycle.
+ *
+ * Backed entirely by `node:zlib` — no native module, works in-process.
+ * @module @hy-sde-org/dsh-zstd-frame
+ */
+import { constants, zstdCompress, zstdDecompress, zstdDecompressSync, } from 'node:zlib';
+import { promisify } from 'node:util';
+import { NodePrivateZstdFrameDecoder } from "./zstd-private-decoder.js";
+import { PublicZstdFrameDecoder } from "./zstd-public-decoder.js";
+export { NodePrivateZstdFrameDecoder } from "./zstd-private-decoder.js";
+export { PublicZstdFrameDecoder } from "./zstd-public-decoder.js";
+const ZSTD_MAGIC = 0xFD2FB528;
+const zstdCompressAsync = promisify(zstdCompress);
+const zstdDecompressAsync = promisify(zstdDecompress);
+const CHECKSUM_OPTIONS = {
+    params: { [constants.ZSTD_c_checksumFlag]: 1 },
+};
+const INCOMPLETE_FRAME_OPTIONS = {
+    finishFlush: constants.ZSTD_e_flush,
+};
+/**
+ * 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 function scanZstdFrames(buffer, maxFrames = Number.POSITIVE_INFINITY) {
+    const frames = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        const start = offset;
+        if (buffer.length - offset < 4)
+            return { frames, tornStart: start };
+        if (buffer.readUInt32LE(offset) !== ZSTD_MAGIC) {
+            throw new Error(`corrupt Zstandard stream: invalid frame magic at byte ${offset}`);
+        }
+        offset += 4;
+        if (offset === buffer.length)
+            return { frames, tornStart: start };
+        const descriptor = buffer.readUInt8(offset);
+        offset += 1;
+        if ((descriptor & 0x18) !== 0) {
+            throw new Error(`corrupt Zstandard stream: reserved frame-header bit at byte ${offset - 1}`);
+        }
+        const contentSizeFlag = descriptor >>> 6;
+        const singleSegment = (descriptor & 0x20) !== 0;
+        const checksum = (descriptor & 0x04) !== 0;
+        const dictionaryFlag = descriptor & 0x03;
+        const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+        const contentSizeBytes = contentSizeFlag === 0
+            ? (singleSegment ? 1 : 0)
+            : 1 << contentSizeFlag;
+        const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+        if (buffer.length - offset < remainingHeaderBytes)
+            return { frames, tornStart: start };
+        offset += remainingHeaderBytes;
+        for (;;) {
+            if (buffer.length - offset < 3)
+                return { frames, tornStart: start };
+            const blockHeader = buffer.readUIntLE(offset, 3);
+            offset += 3;
+            const lastBlock = (blockHeader & 1) !== 0;
+            const blockType = (blockHeader >>> 1) & 0x03;
+            const blockSize = blockHeader >>> 3;
+            if (blockType === 0x03) {
+                throw new Error(`corrupt Zstandard stream: reserved block type at byte ${offset - 3}`);
+            }
+            const payloadBytes = blockType === 0x01 ? 1 : blockSize;
+            if (buffer.length - offset < payloadBytes)
+                return { frames, tornStart: start };
+            offset += payloadBytes;
+            if (lastBlock)
+                break;
+        }
+        if (checksum) {
+            if (buffer.length - offset < 4)
+                return { frames, tornStart: start };
+            offset += 4;
+        }
+        frames.push({ start, end: offset });
+        if (frames.length === maxFrames)
+            return { frames };
+    }
+    return { frames };
+}
+/**
+ * Compress one independently decodable, checksummed Zstandard frame.
+ * @param input - JSONL bytes for a header or durable event batch.
+ * @returns the complete encoded frame.
+ */
+export async function compressZstdFrame(input) {
+    return zstdCompressAsync(input, CHECKSUM_OPTIONS);
+}
+/**
+ * Decompress one complete frame and validate its checksum.
+ * @param input - one structurally complete Zstandard frame.
+ * @param maxOutput - optional plaintext bound; oversized frames reject with the Node error.
+ * @returns the frame plaintext.
+ */
+export async function decompressZstdFrame(input, maxOutput) {
+    if (maxOutput === undefined)
+        return zstdDecompressAsync(input);
+    return zstdDecompressAsync(input, { maxOutputLength: Math.max(1, maxOutput) });
+}
+/**
+ * Synchronous one-frame decompression with an optional plaintext bound — for
+ * sync-only readers (the `memory:project` prompt section reads bank files with
+ * `readFileSync`). Keeps checksum validation identical to the async path.
+ * @param input - one structurally complete Zstandard frame.
+ * @param maxOutput - optional plaintext bound; oversized frames reject.
+ * @returns the frame plaintext.
+ */
+export function decompressZstdFrameSync(input, maxOutput) {
+    if (maxOutput === undefined)
+        return zstdDecompressSync(input);
+    return zstdDecompressSync(input, { maxOutputLength: Math.max(1, maxOutput) });
+}
+/**
+ * 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 function createZstdFrameDecoder() {
+    return NodePrivateZstdFrameDecoder.create() ?? new PublicZstdFrameDecoder();
+}
+/**
+ * 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 async function decompressZstdPrefix(input) {
+    return zstdDecompressAsync(input, INCOMPLETE_FRAME_OPTIONS);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hy-sde-org/dsh-zstd-frame`.
+ * @module @hy-sde-org/dsh-zstd-frame/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "zstd-frame-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/dist/invariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,yBAAyB,CAAA;AAC1C,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAQpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/dist/invariant.js

@@ -0,0 +1,22 @@
+/**
+ * Package-owned invariant companion for `@hy-sde-org/dsh-zstd-frame`.
+ * @module @hy-sde-org/dsh-zstd-frame/invariant
+ */
+const PACKAGE_NAME = '@hy-sde-org/dsh-zstd-frame';
+/** Cordis companion plugin name. */
+export const name = 'zstd-frame-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: the frame layout algebra is enforced by the test suite
+ * and the structural scan rejects corrupt input at runtime.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/dist/invariant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invariant.js","sourceRoot":"","sources":["../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,YAAY,GAAG,4BAA4B,CAAA;AAEjD,oCAAoC;AACpC,MAAM,CAAC,MAAM,IAAI,GAAG,sBAAsB,CAAA;AAC1C,2EAA2E;AAC3E,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,YAAY,CAAC,CAAA;AAEpC;;;GAGG;AACH,MAAM,OAAO,GAAuB,GAAG,EAAE,GAAE,CAAC,CAAA;AAE5C;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAY,EAAuB,EAAE,CACzD,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAA;AACjE,sBAAsB"}

package/dist/zstd-private-decoder.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Node-private synchronous Zstandard frame decoder optimization.
+ * @module @hy-sde-org/dsh-zstd-frame/zstd-private-decoder
+ */
+import type { ZstdFrameDecoder, ZstdFrameRange } from './index.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/dist/zstd-private-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-private-decoder.d.ts","sourceRoot":"","sources":["../src/zstd-private-decoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAiDlE;;;;;GAKG;AACH,qBAAa,2BAA4B,YAAW,gBAAgB;IAOhE,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAP3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,YAAY,CAAC,CAAO;IAC5B,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,MAAM,CAAQ;IAEtB,OAAO;IASP;;;;OAIG;IACH,MAAM,CAAC,MAAM,IAAI,2BAA2B,GAAG,SAAS;IAaxD,kBAAkB;IACV,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;IAmBhG,qFAAqF;IACrF,OAAO,CAAC,WAAW;IAuDnB,kBAAkB;IAClB,KAAK,IAAI,IAAI;CAKd"}

package/dist/zstd-private-decoder.js

@@ -0,0 +1,142 @@
+/**
+ * Node-private synchronous Zstandard frame decoder optimization.
+ * @module @hy-sde-org/dsh-zstd-frame/zstd-private-decoder
+ */
+import { constants as bufferConstants } from 'node:buffer';
+import { createZstdDecompress } from 'node:zlib';
+const DECODE_CHUNK_SIZE = 1024 * 1024;
+/** Return the stream with its observed private Node contract, or reject that optimization. */
+function privateZstdStream(stream) {
+    const candidate = stream;
+    const handle = candidate._handle;
+    const errorKey = Reflect.ownKeys(stream).find((key) => (typeof key === 'symbol' && key.description === 'kError'));
+    /* v8 ignore next -- one test runtime exposes one Node-private shape; the Node 22/24/26 matrix checks compatibility. */
+    if (typeof handle !== 'object' || handle === null
+        || typeof handle.writeSync !== 'function'
+        || !(candidate._writeState instanceof Uint32Array)
+        || candidate._writeState.length < 2
+        || typeof candidate._defaultFlushFlag !== 'number'
+        || errorKey === undefined
+        || candidate[errorKey] !== null)
+        return undefined;
+    return { stream: stream, errorKey };
+}
+/**
+ * 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 class NodePrivateZstdFrameDecoder {
+    stream;
+    errorKey;
+    output = Buffer.allocUnsafe(DECODE_CHUNK_SIZE);
+    decoderError;
+    started = false;
+    closed = false;
+    constructor(stream, errorKey) {
+        this.stream = stream;
+        this.errorKey = errorKey;
+        this.stream.on('error', (error) => {
+            this.decoderError ??= error;
+        });
+    }
+    /**
+     * 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() {
+        const stream = createZstdDecompress({ chunkSize: DECODE_CHUNK_SIZE });
+        const privateAccess = privateZstdStream(stream);
+        /* v8 ignore next -- reached only when a supported Node release changes its private stream shape. */
+        if (privateAccess !== undefined) {
+            return new NodePrivateZstdFrameDecoder(privateAccess.stream, privateAccess.errorKey);
+        }
+        /* v8 ignore next -- the active Node runtime passed the private-shape probe above. */
+        stream.close();
+        /* v8 ignore next -- the active Node runtime passed the private-shape probe above. */
+        return undefined;
+    }
+    /** @inheritdoc */
+    *decode(source, frames) {
+        if (this.started)
+            throw new Error('Zstandard frame decoder was already started');
+        if (this.closed)
+            throw new Error('cannot start a closed Zstandard frame decoder');
+        this.started = true;
+        try {
+            for (const frame of frames) {
+                try {
+                    yield this.decodeFrame(source.subarray(frame.start, frame.end));
+                }
+                catch (error) {
+                    throw new Error(`corrupt Zstandard stream: frame at byte ${frame.start} failed validation`, {
+                        cause: error,
+                    });
+                }
+            }
+        }
+        finally {
+            this.close();
+        }
+    }
+    /** Decode one frame; its returned scratch view remains valid until the next call. */
+    decodeFrame(input) {
+        const handle = this.stream._handle;
+        /* v8 ignore next -- decode() rejects closed instances before entering this private frame operation. */
+        if (this.closed || handle === null)
+            throw new Error('cannot decode with a closed Zstandard frame decoder');
+        let inputOffset = 0;
+        let inputRemaining = input.length;
+        let outputBytes = 0;
+        const fullChunks = [];
+        for (;;) {
+            handle.writeSync(this.stream._defaultFlushFlag, input, inputOffset, inputRemaining, this.output, 0, this.output.length);
+            if (this.decoderError !== undefined)
+                throw this.decoderError;
+            const internalError = this.stream[this.errorKey];
+            if (internalError !== null) {
+                if (internalError instanceof Error)
+                    throw internalError;
+                throw new Error('Zstandard decoder exposed a non-Error internal failure');
+            }
+            const outputAfter = this.stream._writeState[0];
+            const inputAfter = this.stream._writeState[1];
+            const consumed = inputRemaining - inputAfter;
+            const produced = this.output.length - outputAfter;
+            if (produced > 0) {
+                outputBytes += produced;
+                /* v8 ignore next -- Buffer cannot materialize a frame beyond its own process-wide maximum length. */
+                if (outputBytes > bufferConstants.MAX_LENGTH) {
+                    throw new Error(`Zstandard frame output exceeds ${bufferConstants.MAX_LENGTH} bytes`);
+                }
+            }
+            if (outputAfter !== 0) {
+                /* v8 ignore next -- structurally scanned ranges contain exactly one complete frame and no trailing bytes. */
+                if (inputAfter !== 0)
+                    throw new Error('Zstandard frame decoder left trailing input');
+                const finalChunk = this.output.subarray(0, produced);
+                if (fullChunks.length === 0)
+                    return finalChunk;
+                if (produced > 0)
+                    fullChunks.push(Buffer.from(finalChunk));
+                const onlyChunk = fullChunks[0];
+                return fullChunks.length === 1
+                    ? onlyChunk
+                    : Buffer.concat(fullChunks, outputBytes);
+            }
+            fullChunks.push(Buffer.from(this.output));
+            inputOffset += consumed;
+            inputRemaining = inputAfter;
+        }
+    }
+    /** @inheritdoc */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.stream.close();
+    }
+}
+//# sourceMappingURL=zstd-private-decoder.js.map

package/dist/zstd-private-decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-private-decoder.js","sourceRoot":"","sources":["../src/zstd-private-decoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,SAAS,IAAI,eAAe,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAGhD,MAAM,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAA;AAyBrC,8FAA8F;AAC9F,SAAS,iBAAiB,CACxB,MAA+C;IAE/C,MAAM,SAAS,GAAG,MAAkD,CAAA;IACpE,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAA;IAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,CACpE,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,WAAW,KAAK,QAAQ,CACxD,CAAC,CAAA;IACF,uHAAuH;IACvH,IACE,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;WAC1C,OAAQ,MAAkC,CAAC,SAAS,KAAK,UAAU;WACnE,CAAC,CAAC,SAAS,CAAC,WAAW,YAAY,WAAW,CAAC;WAC/C,SAAS,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC;WAChC,OAAO,SAAS,CAAC,iBAAiB,KAAK,QAAQ;WAC/C,QAAQ,KAAK,SAAS;WACtB,SAAS,CAAC,QAAQ,CAAC,KAAK,IAAI;QAC/B,OAAO,SAAS,CAAA;IAClB,OAAO,EAAE,MAAM,EAAE,MAA+B,EAAE,QAAQ,EAAE,CAAA;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,2BAA2B;IAOnB;IACA;IAPF,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,iBAAiB,CAAC,CAAA;IACvD,YAAY,CAAQ;IACpB,OAAO,GAAG,KAAK,CAAA;IACf,MAAM,GAAG,KAAK,CAAA;IAEtB,YACmB,MAA6B,EAC7B,QAAgB;QADhB,WAAM,GAAN,MAAM,CAAuB;QAC7B,aAAQ,GAAR,QAAQ,CAAQ;QAEjC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;YACvC,IAAI,CAAC,YAAY,KAAK,KAAK,CAAA;QAC7B,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,MAAM;QACX,MAAM,MAAM,GAAG,oBAAoB,CAAC,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC,CAAA;QACrE,MAAM,aAAa,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAA;QAC/C,oGAAoG;QACpG,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAChC,OAAO,IAAI,2BAA2B,CAAC,aAAa,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;QACtF,CAAC;QACD,qFAAqF;QACrF,MAAM,CAAC,KAAK,EAAE,CAAA;QACd,qFAAqF;QACrF,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,kBAAkB;IACX,CAAC,MAAM,CAAC,MAAc,EAAE,MAAiC;QAC9D,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;QAChF,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;QACjF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACnB,IAAI,CAAC;YACH,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;gBACjE,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,IAAI,KAAK,CAAC,2CAA2C,KAAK,CAAC,KAAK,oBAAoB,EAAE;wBAC1F,KAAK,EAAE,KAAK;qBACb,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;IACH,CAAC;IAED,qFAAqF;IAC7E,WAAW,CAAC,KAAa;QAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAA;QAClC,uGAAuG;QACvG,IAAI,IAAI,CAAC,MAAM,IAAI,MAAM,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAA;QAE1G,IAAI,WAAW,GAAG,CAAC,CAAA;QACnB,IAAI,cAAc,GAAG,KAAK,CAAC,MAAM,CAAA;QACjC,IAAI,WAAW,GAAG,CAAC,CAAA;QACnB,MAAM,UAAU,GAAa,EAAE,CAAA;QAC/B,SAAS,CAAC;YACR,MAAM,CAAC,SAAS,CACd,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAC7B,KAAK,EACL,WAAW,EACX,cAAc,EACd,IAAI,CAAC,MAAM,EACX,CAAC,EACD,IAAI,CAAC,MAAM,CAAC,MAAM,CACnB,CAAA;YACD,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS;gBAAE,MAAM,IAAI,CAAC,YAAY,CAAA;YAC5D,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;YAChD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;gBAC3B,IAAI,aAAa,YAAY,KAAK;oBAAE,MAAM,aAAa,CAAA;gBACvD,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAA;YAC3E,CAAC;YAED,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAA;YAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAA;YAC7C,MAAM,QAAQ,GAAG,cAAc,GAAG,UAAU,CAAA;YAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,WAAW,CAAA;YACjD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;gBACjB,WAAW,IAAI,QAAQ,CAAA;gBACvB,qGAAqG;gBACrG,IAAI,WAAW,GAAG,eAAe,CAAC,UAAU,EAAE,CAAC;oBAC7C,MAAM,IAAI,KAAK,CAAC,kCAAkC,eAAe,CAAC,UAAU,QAAQ,CAAC,CAAA;gBACvF,CAAC;YACH,CAAC;YAED,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;gBACtB,6GAA6G;gBAC7G,IAAI,UAAU,KAAK,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;gBACpF,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;gBACpD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;oBAAE,OAAO,UAAU,CAAA;gBAC9C,IAAI,QAAQ,GAAG,CAAC;oBAAE,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAA;gBAC1D,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAW,CAAA;gBACzC,OAAO,UAAU,CAAC,MAAM,KAAK,CAAC;oBAC5B,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,WAAW,CAAC,CAAA;YAC5C,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAA;YACzC,WAAW,IAAI,QAAQ,CAAA;YACvB,cAAc,GAAG,UAAU,CAAA;QAC7B,CAAC;IACH,CAAC;IAED,kBAAkB;IAClB,KAAK;QACH,IAAI,IAAI,CAAC,MAAM;YAAE,OAAM;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAA;IACrB,CAAC;CACF"}

package/dist/zstd-public-decoder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public-API synchronous Zstandard frame decoder fallback.
+ * @module @hy-sde-org/dsh-zstd-frame/zstd-public-decoder
+ */
+import type { ZstdFrameDecoder, ZstdFrameRange } from './index.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/dist/zstd-public-decoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-public-decoder.d.ts","sourceRoot":"","sources":["../src/zstd-public-decoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAElE,gFAAgF;AAChF,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,MAAM,CAAQ;IAEtB,kBAAkB;IACV,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC;IAqBhG,kBAAkB;IAClB,KAAK,IAAI,IAAI;CAGd"}

package/dist/zstd-public-decoder.js

@@ -0,0 +1,40 @@
+/**
+ * Public-API synchronous Zstandard frame decoder fallback.
+ * @module @hy-sde-org/dsh-zstd-frame/zstd-public-decoder
+ */
+import { zstdDecompressSync } from 'node:zlib';
+/** Multi-frame adapter built exclusively from Node's supported one-shot API. */
+export class PublicZstdFrameDecoder {
+    started = false;
+    closed = false;
+    /** @inheritdoc */
+    *decode(source, frames) {
+        if (this.started)
+            throw new Error('Zstandard frame decoder was already started');
+        if (this.closed)
+            throw new Error('cannot start a closed Zstandard frame decoder');
+        this.started = true;
+        try {
+            for (const { start, end } of frames) {
+                let decoded;
+                try {
+                    decoded = zstdDecompressSync(source.subarray(start, end));
+                }
+                catch (error) {
+                    throw new Error(`corrupt Zstandard stream: frame at byte ${start} failed validation`, {
+                        cause: error,
+                    });
+                }
+                yield decoded;
+            }
+        }
+        finally {
+            this.close();
+        }
+    }
+    /** @inheritdoc */
+    close() {
+        this.closed = true;
+    }
+}
+//# sourceMappingURL=zstd-public-decoder.js.map

package/dist/zstd-public-decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-public-decoder.js","sourceRoot":"","sources":["../src/zstd-public-decoder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAG9C,gFAAgF;AAChF,MAAM,OAAO,sBAAsB;IACzB,OAAO,GAAG,KAAK,CAAA;IACf,MAAM,GAAG,KAAK,CAAA;IAEtB,kBAAkB;IACX,CAAC,MAAM,CAAC,MAAc,EAAE,MAAiC;QAC9D,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAA;QAChF,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAA;QACjF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACnB,IAAI,CAAC;YACH,KAAK,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,MAAM,EAAE,CAAC;gBACpC,IAAI,OAAe,CAAA;gBACnB,IAAI,CAAC;oBACH,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAA;gBAC3D,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,IAAI,KAAK,CAAC,2CAA2C,KAAK,oBAAoB,EAAE;wBACpF,KAAK,EAAE,KAAK;qBACb,CAAC,CAAA;gBACJ,CAAC;gBACD,MAAM,OAAO,CAAA;YACf,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;IACH,CAAC;IAED,kBAAkB;IAClB,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;IACpB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@hy-sde-org/dsh-zstd-frame",
+  "version": "0.1.1-rc.2",
+  "description": "Zstandard frame primitives (scan / compress / decompress / multi-frame decoder) shared by the DeepSeek Harness session persistence backend and project memory bank, as a standalone npm package.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./invariant": {
+      "types": "./dist/invariant.d.ts",
+      "default": "./dist/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hy-sde/dsh-zstd-frame.git"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  },
+  "keywords": [
+    "deepseek",
+    "agent",
+    "harness",
+    "dsh-plugin",
+    "zstd",
+    "zstandard",
+    "frame",
+    "checksum",
+    "torn-frame"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}