@shrkcrft/compress 0.1.0-alpha.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SharkCraft contributors
+
+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,21 @@
+# @shrkcrft/compress
+
+SharkCraft's deterministic context-compression engine.
+
+Built to honour SharkCraft's hard rule — **no model inside the engine**. Every
+transform is a pure function of its input: content routing, lossless
+columnar/table compaction of homogeneous object arrays, log / search / diff /
+line reduction, and reversible Compress-Cache-Retrieve (CCR).
+
+Part of [SharkCraft](https://github.com/shrkcrft/sharkcraft) — a deterministic,
+local-first toolkit that gives AI coding agents durable project context. See
+[`docs/compression.md`](https://github.com/shrkcrft/sharkcraft/blob/main/docs/compression.md)
+for the full guide, and the main repo for the `shrk` CLI and MCP server.
+
+```ts
+import { compressContent, InMemoryCcrStore } from '@shrkcrft/compress';
+
+const store = new InMemoryCcrStore();
+const result = compressContent(blob, { store, query: 'auth' });
+// result.compressed · result.strategy · result.savings · result.ccrKey
+```

package/dist/cache/align-volatile-tokens.d.ts

@@ -0,0 +1,13 @@
+import type { IAlignmentMap } from './alignment-map.js';
+import type { IAlignmentResult } from './alignment-result.js';
+/**
+ * Replace volatile tokens (UUID/JWT/ISO-8601/hex/epoch) with stable, kind-tagged
+ * placeholders so a provider KV-cache prefix stays steady across turns.
+ * Reversible via `restoreVolatileTokens`. Deterministic and pure: the caller's
+ * `prior` map is never mutated (cloned), ordinals are assigned strictly in scan
+ * order, and the same `(text, prior)` yields byte-identical output. Shares
+ * `clean`/`classify` with `detectVolatileTokens`, so the two never disagree on
+ * what is volatile.
+ */
+export declare function alignVolatileTokens(text: string, prior?: IAlignmentMap): IAlignmentResult;
+//# sourceMappingURL=align-volatile-tokens.d.ts.map

package/dist/cache/align-volatile-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"align-volatile-tokens.d.ts","sourceRoot":"","sources":["../../src/cache/align-volatile-tokens.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAqB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,aAAa,GAAG,gBAAgB,CAsCzF"}

package/dist/cache/align-volatile-tokens.js

@@ -0,0 +1,51 @@
+import { clean, classify, MIN_VOLATILE_LEN } from "./volatile-classify.js";
+import { formatPlaceholder, escapePlaceholders } from "./placeholder.js";
+/**
+ * Replace volatile tokens (UUID/JWT/ISO-8601/hex/epoch) with stable, kind-tagged
+ * placeholders so a provider KV-cache prefix stays steady across turns.
+ * Reversible via `restoreVolatileTokens`. Deterministic and pure: the caller's
+ * `prior` map is never mutated (cloned), ordinals are assigned strictly in scan
+ * order, and the same `(text, prior)` yields byte-identical output. Shares
+ * `clean`/`classify` with `detectVolatileTokens`, so the two never disagree on
+ * what is volatile.
+ */
+export function alignVolatileTokens(text, prior) {
+    const bindings = prior ? prior.bindings.map((b) => ({ ...b })) : [];
+    const byOriginal = new Map();
+    const nextOrdinal = new Map();
+    for (const b of bindings) {
+        byOriginal.set(b.original, b);
+        nextOrdinal.set(b.kind, Math.max(nextOrdinal.get(b.kind) ?? 0, b.ordinal));
+    }
+    let replaced = 0;
+    // Escape any pre-existing `«vk:…»`-shaped literal so a generated placeholder
+    // can never collide with content that was already there (restore stays exact).
+    const safe = escapePlaceholders(text);
+    // Split keeping whitespace runs so they survive verbatim.
+    const aligned = safe
+        .split(/(\s+)/)
+        .map((segment) => {
+        if (segment.length === 0 || /^\s+$/.test(segment))
+            return segment;
+        const cleaned = clean(segment);
+        if (cleaned.length < MIN_VOLATILE_LEN)
+            return segment;
+        const kind = classify(cleaned);
+        if (!kind)
+            return segment;
+        let binding = byOriginal.get(cleaned);
+        if (!binding) {
+            const ordinal = (nextOrdinal.get(kind) ?? 0) + 1;
+            nextOrdinal.set(kind, ordinal);
+            binding = { placeholder: formatPlaceholder(kind, ordinal), original: cleaned, kind, ordinal };
+            bindings.push(binding);
+            byOriginal.set(cleaned, binding);
+        }
+        replaced += 1;
+        // Replace the cleaned span inside the raw segment so wrappers like
+        // `"<uuid>",` keep their surrounding quotes/punctuation.
+        return segment.replace(cleaned, binding.placeholder);
+    })
+        .join('');
+    return { aligned, map: { version: 1, bindings }, replaced };
+}

package/dist/cache/alignment-map.d.ts

@@ -0,0 +1,23 @@
+import type { EVolatileKind } from './volatile-kind.js';
+/** One original-value ↔ placeholder binding. */
+export interface IAlignmentBinding {
+    /** `«vk:uuid:0001»`. */
+    placeholder: string;
+    /** The cleaned original token (no surrounding quotes/punctuation). */
+    original: string;
+    kind: EVolatileKind;
+    /** Per-kind ordinal (first-appearance order). */
+    ordinal: number;
+}
+/**
+ * The reversible alignment map. Append-only, first-appearance order, plain JSON
+ * so it serialises for the CLI and travels in MCP tool I/O. Carry it across
+ * turns so a value keeps its placeholder — that carry-forward is what stabilises
+ * the cache prefix. Per-kind next ordinal is `1 + max(ordinal of that kind)`,
+ * a pure function of `bindings` (no hidden counter).
+ */
+export interface IAlignmentMap {
+    version: 1;
+    bindings: IAlignmentBinding[];
+}
+//# sourceMappingURL=alignment-map.d.ts.map

package/dist/cache/alignment-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment-map.d.ts","sourceRoot":"","sources":["../../src/cache/alignment-map.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,gDAAgD;AAChD,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,aAAa,CAAC;IACpB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B"}

package/dist/cache/alignment-map.js

@@ -0,0 +1 @@
+export {};

package/dist/cache/alignment-result.d.ts

@@ -0,0 +1,11 @@
+import type { IAlignmentMap } from './alignment-map.js';
+/** The outcome of an alignment pass. */
+export interface IAlignmentResult {
+    /** Text with volatile tokens replaced by stable placeholders. */
+    aligned: string;
+    /** The (new) alignment map — pass it back next turn to keep ordinals stable. */
+    map: IAlignmentMap;
+    /** Number of token occurrences replaced. */
+    replaced: number;
+}
+//# sourceMappingURL=alignment-result.d.ts.map

package/dist/cache/alignment-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment-result.d.ts","sourceRoot":"","sources":["../../src/cache/alignment-result.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,GAAG,EAAE,aAAa,CAAC;IACnB,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/cache/alignment-result.js

@@ -0,0 +1 @@
+export {};

package/dist/cache/detect-volatile-tokens.d.ts

@@ -0,0 +1,10 @@
+import type { IVolatileToken } from './volatile-token.js';
+/**
+ * Scan text for volatile tokens that would bust a provider KV-cache prefix.
+ * Deterministic, detection-only (never mutates). Returns one aggregated entry
+ * per kind found, in a stable kind order, with an occurrence count and a
+ * truncated sample. Shares its `clean`/`classify` with `alignVolatileTokens`
+ * so the two never disagree.
+ */
+export declare function detectVolatileTokens(text: string): IVolatileToken[];
+//# sourceMappingURL=detect-volatile-tokens.d.ts.map

package/dist/cache/detect-volatile-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-volatile-tokens.d.ts","sourceRoot":"","sources":["../../src/cache/detect-volatile-tokens.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,EAAE,CA0BnE"}

package/dist/cache/detect-volatile-tokens.js

@@ -0,0 +1,41 @@
+import { EVolatileKind } from "./volatile-kind.js";
+import { clean, classify, MIN_VOLATILE_LEN } from "./volatile-classify.js";
+/**
+ * Scan text for volatile tokens that would bust a provider KV-cache prefix.
+ * Deterministic, detection-only (never mutates). Returns one aggregated entry
+ * per kind found, in a stable kind order, with an occurrence count and a
+ * truncated sample. Shares its `clean`/`classify` with `alignVolatileTokens`
+ * so the two never disagree.
+ */
+export function detectVolatileTokens(text) {
+    const counts = new Map();
+    const samples = new Map();
+    for (const raw of text.split(/\s+/)) {
+        if (raw.length === 0)
+            continue;
+        const token = clean(raw);
+        if (token.length < MIN_VOLATILE_LEN)
+            continue;
+        const kind = classify(token);
+        if (!kind)
+            continue;
+        counts.set(kind, (counts.get(kind) ?? 0) + 1);
+        if (!samples.has(kind))
+            samples.set(kind, token.slice(0, 24));
+    }
+    // Stable kind order so output is deterministic regardless of scan order.
+    const order = [
+        EVolatileKind.Uuid,
+        EVolatileKind.Jwt,
+        EVolatileKind.Iso8601,
+        EVolatileKind.HexHash,
+        EVolatileKind.EpochTimestamp,
+    ];
+    const out = [];
+    for (const kind of order) {
+        const count = counts.get(kind);
+        if (count)
+            out.push({ kind, count, sample: samples.get(kind) ?? '' });
+    }
+    return out;
+}

package/dist/cache/placeholder.d.ts

@@ -0,0 +1,28 @@
+import type { EVolatileKind } from './volatile-kind.js';
+/**
+ * Matches a volatile-token placeholder: `«vk:KIND:NNNN»`. The `«…»` guillemets
+ * essentially never occur in code/logs/JSON, so the placeholder is unambiguous
+ * to scan back out. Global so a restore pass finds every one.
+ */
+export declare const PLACEHOLDER_RE: RegExp;
+/**
+ * Render a stable, self-describing placeholder. The 4-wide zero-padded ordinal
+ * keeps the placeholder a constant length (for the first 9999 of a kind), which
+ * is what keeps surrounding token offsets — and thus a provider KV-cache prefix
+ * — stable across turns.
+ */
+export declare function formatPlaceholder(kind: EVolatileKind, ordinal: number): string;
+/**
+ * The raw placeholder prefix and an escaped form that a NUL breaks so it can
+ * never match `PLACEHOLDER_RE`. Used to escape any pre-existing `«vk:…»`-shaped
+ * literal in the source BEFORE alignment, so a generated placeholder can never
+ * collide with content that was already there (the round-trip stays lossless
+ * even for input that literally contains a placeholder).
+ */
+export declare const PLACEHOLDER_PREFIX = "\u00ABvk:";
+export declare const ESCAPED_PREFIX = "\u00ABvk\0:";
+/** Escape pre-existing placeholder-shaped prefixes in the source. */
+export declare function escapePlaceholders(text: string): string;
+/** Inverse of {@link escapePlaceholders}; applied after restore. */
+export declare function unescapePlaceholders(text: string): string;
+//# sourceMappingURL=placeholder.d.ts.map

package/dist/cache/placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.d.ts","sourceRoot":"","sources":["../../src/cache/placeholder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAgC,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,cAAS,CAAC;AACzC,eAAO,MAAM,cAAc,gBAAU,CAAC;AAEtC,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIzD"}

package/dist/cache/restore-volatile-tokens.d.ts

@@ -0,0 +1,10 @@
+import type { IAlignmentMap } from './alignment-map.js';
+/**
+ * Reverse `alignVolatileTokens`: replace every `«vk:…»` placeholder with its
+ * original value from the map. Unknown placeholders pass through untouched
+ * (total, never throws). Property:
+ * `restoreVolatileTokens(alignVolatileTokens(t).aligned, map) === t` for any `t`
+ * whose volatile tokens were cleanly delimited (lossless-via-restore).
+ */
+export declare function restoreVolatileTokens(text: string, map: IAlignmentMap): string;
+//# sourceMappingURL=restore-volatile-tokens.d.ts.map

package/dist/cache/restore-volatile-tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore-volatile-tokens.d.ts","sourceRoot":"","sources":["../../src/cache/restore-volatile-tokens.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAqB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE3E;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,CAiB9E"}

package/dist/cache/restore-volatile-tokens.js

@@ -0,0 +1,21 @@
+import { PLACEHOLDER_RE, unescapePlaceholders } from "./placeholder.js";
+/**
+ * Reverse `alignVolatileTokens`: replace every `«vk:…»` placeholder with its
+ * original value from the map. Unknown placeholders pass through untouched
+ * (total, never throws). Property:
+ * `restoreVolatileTokens(alignVolatileTokens(t).aligned, map) === t` for any `t`
+ * whose volatile tokens were cleanly delimited (lossless-via-restore).
+ */
+export function restoreVolatileTokens(text, map) {
+    // Defensive: a corrupt/hand-edited map may carry a non-object (or
+    // placeholder-less) element in `bindings[]` that still passes a shallow
+    // `Array.isArray` validation. Skip those so the documented "never throws"
+    // guarantee holds rather than dereferencing `b.placeholder` on `null`.
+    const byPlaceholder = new Map((Array.isArray(map.bindings) ? map.bindings : [])
+        .filter((b) => b != null && typeof b === 'object' && typeof b.placeholder === 'string')
+        .map((b) => [b.placeholder, b.original]));
+    // Revert generated placeholders, then unescape any literal `«vk:…»` that
+    // align escaped — so the round trip is exact even for placeholder-shaped input.
+    const reverted = text.replace(PLACEHOLDER_RE, (match) => byPlaceholder.get(match) ?? match);
+    return unescapePlaceholders(reverted);
+}

package/dist/cache/volatile-classify.d.ts

@@ -0,0 +1,11 @@
+import { EVolatileKind } from './volatile-kind.js';
+/** Minimum cleaned-token length before classification is attempted. */
+export declare const MIN_VOLATILE_LEN = 8;
+/**
+ * Strip surrounding quotes / brackets / punctuation a token tends to carry.
+ * Shared by both detection and active alignment so they never drift.
+ */
+export declare function clean(token: string): string;
+/** Classify a CLEANED token into a volatile kind, or null. */
+export declare function classify(token: string): EVolatileKind | null;
+//# sourceMappingURL=volatile-classify.d.ts.map

package/dist/cache/volatile-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volatile-classify.d.ts","sourceRoot":"","sources":["../../src/cache/volatile-classify.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAenD,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC;;;GAGG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAO5D"}

package/dist/cache/volatile-classify.js

@@ -0,0 +1,35 @@
+import { EVolatileKind } from "./volatile-kind.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// A JWT's first segment is base64url of a `{"alg":...}` header, which always
+// starts with `eyJ` — require it so ordinary dotted identifiers
+// (`config.settings.default`, `lodash.debounce.cancel`) aren't flagged.
+const JWT = /^eyJ[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{4,}$/;
+const ISO8601 = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2})?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+const HEX_HASH = /^(?:[0-9a-f]{32}|[0-9a-f]{40}|[0-9a-f]{64})$/i;
+// Plausible unix epochs only (leading `1`: ~2001–2033 in seconds, ~2001–2286 in
+// millis) so phone numbers / arbitrary IDs (`5551234567`, `9999999999`) don't
+// register as timestamps.
+const EPOCH = /^1\d{9}$|^1\d{12}$/;
+/** Minimum cleaned-token length before classification is attempted. */
+export const MIN_VOLATILE_LEN = 8;
+/**
+ * Strip surrounding quotes / brackets / punctuation a token tends to carry.
+ * Shared by both detection and active alignment so they never drift.
+ */
+export function clean(token) {
+    return token.replace(/^[("'[<{]+/, '').replace(/[)"'\]>}.,;:]+$/, '');
+}
+/** Classify a CLEANED token into a volatile kind, or null. */
+export function classify(token) {
+    if (UUID.test(token))
+        return EVolatileKind.Uuid;
+    if (token.includes('.') && JWT.test(token))
+        return EVolatileKind.Jwt;
+    if (ISO8601.test(token))
+        return EVolatileKind.Iso8601;
+    if (HEX_HASH.test(token))
+        return EVolatileKind.HexHash;
+    if (EPOCH.test(token))
+        return EVolatileKind.EpochTimestamp;
+    return null;
+}

package/dist/cache/volatile-kind.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Classes of volatile token that destabilise a provider's KV-cache prefix.
+ * When these change between otherwise-identical prompts the cache misses, so
+ * surfacing them lets a caller hoist/pin them for cheaper cache hits.
+ */
+export declare enum EVolatileKind {
+    Uuid = "uuid",
+    Jwt = "jwt",
+    Iso8601 = "iso8601",
+    HexHash = "hex-hash",
+    EpochTimestamp = "epoch-timestamp"
+}
+//# sourceMappingURL=volatile-kind.d.ts.map

package/dist/cache/volatile-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volatile-kind.d.ts","sourceRoot":"","sources":["../../src/cache/volatile-kind.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,oBAAY,aAAa;IACvB,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,OAAO,YAAY;IACnB,OAAO,aAAa;IACpB,cAAc,oBAAoB;CACnC"}

package/dist/cache/volatile-kind.js

@@ -0,0 +1,13 @@
+/**
+ * Classes of volatile token that destabilise a provider's KV-cache prefix.
+ * When these change between otherwise-identical prompts the cache misses, so
+ * surfacing them lets a caller hoist/pin them for cheaper cache hits.
+ */
+export var EVolatileKind;
+(function (EVolatileKind) {
+    EVolatileKind["Uuid"] = "uuid";
+    EVolatileKind["Jwt"] = "jwt";
+    EVolatileKind["Iso8601"] = "iso8601";
+    EVolatileKind["HexHash"] = "hex-hash";
+    EVolatileKind["EpochTimestamp"] = "epoch-timestamp";
+})(EVolatileKind || (EVolatileKind = {}));

package/dist/cache/volatile-token.d.ts

@@ -0,0 +1,14 @@
+import type { EVolatileKind } from './volatile-kind.js';
+/**
+ * An aggregated volatile-token finding: how many times a kind of cache-busting
+ * token appears, plus one representative sample (truncated). Detection only —
+ * the prompt is never mutated.
+ */
+export interface IVolatileToken {
+    kind: EVolatileKind;
+    /** Number of occurrences in the scanned text. */
+    count: number;
+    /** A representative occurrence (first seen), truncated to 24 chars. */
+    sample: string;
+}
+//# sourceMappingURL=volatile-token.d.ts.map

package/dist/cache/volatile-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"volatile-token.d.ts","sourceRoot":"","sources":["../../src/cache/volatile-token.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/cache/volatile-token.js

@@ -0,0 +1 @@
+export {};

package/dist/ccr/ccr-entry.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A cached original in the Compress-Cache-Retrieve store. Keyed by a
+ * deterministic content hash so the same bytes always map to the same entry.
+ */
+export interface ICcrEntry {
+    /** Deterministic content key (see {@link ccrKey}). */
+    key: string;
+    /** The original, uncompressed text. */
+    content: string;
+    /** Byte length of {@link content}. */
+    bytes: number;
+}
+//# sourceMappingURL=ccr-entry.d.ts.map

package/dist/ccr/ccr-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ccr-entry.d.ts","sourceRoot":"","sources":["../../src/ccr/ccr-entry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf"}

package/dist/ccr/ccr-entry.js

@@ -0,0 +1 @@
+export {};

package/dist/ccr/ccr-key.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Deterministic content key for the CCR store. A 64-bit FNV-1a hash rendered
+ * as 16 lowercase hex chars — dependency-free, stable across processes and
+ * platforms, and collision-resistant enough for a local content cache. The
+ * same bytes always produce the same key, which is what makes compression
+ * reproducible (same workspace ⇒ same markers).
+ */
+export declare function ccrKey(content: string): string;
+//# sourceMappingURL=ccr-key.d.ts.map

package/dist/ccr/ccr-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ccr-key.d.ts","sourceRoot":"","sources":["../../src/ccr/ccr-key.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ9C"}

package/dist/ccr/ccr-key.js

@@ -0,0 +1,19 @@
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const MASK_64 = 0xffffffffffffffffn;
+/**
+ * Deterministic content key for the CCR store. A 64-bit FNV-1a hash rendered
+ * as 16 lowercase hex chars — dependency-free, stable across processes and
+ * platforms, and collision-resistant enough for a local content cache. The
+ * same bytes always produce the same key, which is what makes compression
+ * reproducible (same workspace ⇒ same markers).
+ */
+export function ccrKey(content) {
+    let hash = FNV_OFFSET;
+    for (let i = 0; i < content.length; i += 1) {
+        const code = content.charCodeAt(i);
+        hash = (hash ^ BigInt(code & 0xff)) * FNV_PRIME & MASK_64;
+        hash = (hash ^ BigInt((code >> 8) & 0xff)) * FNV_PRIME & MASK_64;
+    }
+    return hash.toString(16).padStart(16, '0');
+}

package/dist/ccr/ccr-marker.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Matches a CCR retrieval marker: `<<ccr:KEY>>` or `<<ccr:KEY note text>>`.
+ * The key is the hex content hash; the optional note is a short human hint
+ * (e.g. `42 rows offloaded`). Global + multiline so a scan finds every marker
+ * in a blob.
+ */
+export declare const CCR_MARKER_RE: RegExp;
+/** A parsed CCR marker found inside a compressed blob. */
+export interface ICcrMarkerRef {
+    /** Content key to retrieve. */
+    key: string;
+    /** Optional human hint that accompanied the marker. */
+    note?: string;
+}
+/**
+ * Render a retrieval marker. Callers embed this in compressed output wherever
+ * detail was dropped; an agent that wants the original calls
+ * `retrieve_original` / `shrk expand` with {@link key}.
+ */
+export declare function formatCcrMarker(key: string, note?: string): string;
+/** Extract every CCR marker from a blob, in order of appearance. */
+export declare function parseCcrMarkers(text: string): ICcrMarkerRef[];
+//# sourceMappingURL=ccr-marker.d.ts.map

package/dist/ccr/ccr-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ccr-marker.d.ts","sourceRoot":"","sources":["../../src/ccr/ccr-marker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAA4C,CAAC;AAEvE,0DAA0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAS7D"}

package/dist/ccr/ccr-marker.js

@@ -0,0 +1,30 @@
+/**
+ * Matches a CCR retrieval marker: `<<ccr:KEY>>` or `<<ccr:KEY note text>>`.
+ * The key is the hex content hash; the optional note is a short human hint
+ * (e.g. `42 rows offloaded`). Global + multiline so a scan finds every marker
+ * in a blob.
+ */
+export const CCR_MARKER_RE = /<<ccr:([0-9a-f]{8,})(?:\s+([^>]*?))?>>/g;
+/**
+ * Render a retrieval marker. Callers embed this in compressed output wherever
+ * detail was dropped; an agent that wants the original calls
+ * `retrieve_original` / `shrk expand` with {@link key}.
+ */
+export function formatCcrMarker(key, note) {
+    // Strip `>` from the note so an embedded `>>` can't prematurely close the
+    // marker (format → parse must round-trip for any note the formatter accepts).
+    const trimmed = note?.trim().replace(/>/g, '');
+    return trimmed ? `<<ccr:${key} ${trimmed}>>` : `<<ccr:${key}>>`;
+}
+/** Extract every CCR marker from a blob, in order of appearance. */
+export function parseCcrMarkers(text) {
+    const out = [];
+    for (const match of text.matchAll(CCR_MARKER_RE)) {
+        const key = match[1];
+        if (!key)
+            continue;
+        const note = match[2]?.trim();
+        out.push(note ? { key, note } : { key });
+    }
+    return out;
+}

package/dist/ccr/ccr-store.d.ts

@@ -0,0 +1,18 @@
+import type { ICcrEntry } from './ccr-entry.js';
+/**
+ * Storage contract for cached originals. Implementations may be in-memory
+ * (MCP server lifetime — never touches disk, honouring "MCP never writes")
+ * or filesystem-backed (CLI, under `.sharkcraft/ccr/`). Reads are total;
+ * writes are idempotent on the content key.
+ */
+export interface ICcrStore {
+    /** Cache `content`, returning its deterministic key. Idempotent. */
+    put(content: string): string;
+    /** Fetch a cached original by key, or `undefined` if absent/evicted. */
+    get(key: string): ICcrEntry | undefined;
+    /** Whether `key` is currently cached. */
+    has(key: string): boolean;
+    /** Number of cached entries. */
+    size(): number;
+}
+//# sourceMappingURL=ccr-store.d.ts.map

package/dist/ccr/ccr-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ccr-store.d.ts","sourceRoot":"","sources":["../../src/ccr/ccr-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,wEAAwE;IACxE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACxC,yCAAyC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,gCAAgC;IAChC,IAAI,IAAI,MAAM,CAAC;CAChB"}

package/dist/ccr/ccr-store.js

@@ -0,0 +1 @@
+export {};

package/dist/ccr/file-ccr-store.d.ts

@@ -0,0 +1,19 @@
+import type { ICcrStore } from './ccr-store.js';
+import type { ICcrEntry } from './ccr-entry.js';
+/**
+ * Filesystem-backed CCR store, used by the CLI (the write path). Each cached
+ * original is one content-addressed file under the store directory (typically
+ * `.sharkcraft/ccr/`), so `shrk compress` in one process and `shrk expand` in
+ * a later process share the cache. The MCP server never uses this backend —
+ * it stays in memory to honour the read-only contract.
+ */
+export declare class FileCcrStore implements ICcrStore {
+    private readonly dir;
+    constructor(dir: string);
+    private pathFor;
+    put(content: string): string;
+    get(key: string): ICcrEntry | undefined;
+    has(key: string): boolean;
+    size(): number;
+}
+//# sourceMappingURL=file-ccr-store.d.ts.map

package/dist/ccr/file-ccr-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-ccr-store.d.ts","sourceRoot":"","sources":["../../src/ccr/file-ccr-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQhD;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,SAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,GAAG,EAAE,MAAM;IAKvB,OAAO,CAAC,OAAO;IAIf,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAU5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAQvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKzB,IAAI,IAAI,MAAM;CAIf"}

package/dist/ccr/file-ccr-store.js

@@ -0,0 +1,53 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { Buffer } from 'node:buffer';
+import { ccrKey } from "./ccr-key.js";
+/** CCR keys are content hashes — hex only. Anything else (e.g. a path-traversal
+ *  attempt like `../../etc/passwd`) is rejected so a lookup can never escape the
+ *  store directory or read arbitrary files. */
+const VALID_KEY = /^[0-9a-f]{1,64}$/;
+/**
+ * Filesystem-backed CCR store, used by the CLI (the write path). Each cached
+ * original is one content-addressed file under the store directory (typically
+ * `.sharkcraft/ccr/`), so `shrk compress` in one process and `shrk expand` in
+ * a later process share the cache. The MCP server never uses this backend —
+ * it stays in memory to honour the read-only contract.
+ */
+export class FileCcrStore {
+    dir;
+    constructor(dir) {
+        // Field init only — directory creation is deferred to the first write.
+        this.dir = dir;
+    }
+    pathFor(key) {
+        return nodePath.join(this.dir, `${key}.txt`);
+    }
+    put(content) {
+        const key = ccrKey(content);
+        const file = this.pathFor(key);
+        if (!existsSync(file)) {
+            mkdirSync(this.dir, { recursive: true });
+            writeFileSync(file, content, 'utf8');
+        }
+        return key;
+    }
+    get(key) {
+        if (!VALID_KEY.test(key))
+            return undefined;
+        const file = this.pathFor(key);
+        if (!existsSync(file))
+            return undefined;
+        const content = readFileSync(file, 'utf8');
+        return { key, content, bytes: Buffer.byteLength(content, 'utf8') };
+    }
+    has(key) {
+        if (!VALID_KEY.test(key))
+            return false;
+        return existsSync(this.pathFor(key));
+    }
+    size() {
+        if (!existsSync(this.dir))
+            return 0;
+        return readdirSync(this.dir).filter((f) => f.endsWith('.txt')).length;
+    }
+}