@untangle-code/storage-local 0.0.0-stage → 0.1.1

package/dist/analysis-cache.js

@@ -0,0 +1,322 @@
+/**
+ * Inhaltsadressierte Caches fuer Parse, Chunk und Komplexitaet (WP-100,
+ * docs/INDEX-SHARING.md §5) — unter `.untangle/cache/analysis/`.
+ *
+ * WARUM ES SIE GIBT: Parsen, Chunken und Messen sind reine Funktionen des
+ * Dateiinhalts. Ohne Cache rechnet jeder Lauf sie neu, obwohl sich zwischen
+ * zwei Laeufen (und zwischen zwei Worktrees desselben Repositoriums)
+ * typischerweise nur wenige Prozent der Dateien unterscheiden. Der
+ * Einbettungs-Cache (spec.md §9.4) ist bereits inhaltsadressiert; diese drei
+ * Caches schliessen die Luecke davor.
+ *
+ * DER SCHLUESSEL IST DIE GANZE SICHERHEIT. Ein Cache, der ein falsches
+ * Ergebnis liefert, ist schlimmer als kein Cache: das falsche Ergebnis ist
+ * nicht sichtbar. Der Schluesselbau steht deshalb in `@untangle-code/domain`
+ * (analysis-cache-key.ts) und traegt jede Eingabe, von der der gespeicherte
+ * Wert abhaengt.
+ *
+ * ABLAGE: ein JSON je Eintrag, zwei Hexzeichen tief geshardet
+ * (`<hash[0:2]>/<hash>.json`), plus ein `index.json` je Cache mit Groesse und
+ * letztem Zugriff — die Buchfuehrung fuer die Verdraengung nach Groesse (LRU).
+ *
+ * UNTERSCHIED ZUM EINBETTUNGS-CACHE: dessen Manifest wird bei JEDER Mutation
+ * geschrieben. Das waere hier falsch: drei Caches mal zwei Zugriffe je Datei
+ * ergaeben sechs Manifest-Schreibvorgaenge je Datei und fraessen genau die
+ * Zeit auf, die der Cache spart. Das Manifest wird deshalb im Speicher
+ * gefuehrt und alle {@link MANIFEST_FLUSH_INTERVAL} Mutationen sowie bei
+ * {@link LocalContentCache.flush} geschrieben. PREIS: bricht der Lauf hart ab,
+ * koennen geschriebene Eintraege im Manifest fehlen. Das kostet Treffer und
+ * laesst Dateien ungezaehlt liegen — es liefert NIE ein falsches Ergebnis,
+ * weil ein Wert ausschliesslich ueber das Manifest gefunden wird.
+ *
+ * Lesen degradiert kontrolliert (architecture.md §12: lokale Caches sind
+ * loeschbar und rekonstruierbar): fehlende Datei, kaputtes JSON, kaputtes
+ * Manifest — alles ist ein Fehlschlag des Nachschlagens, kein geworfener
+ * Fehler.
+ */
+import * as nodePath from "node:path";
+import { sha256Hex } from "@untangle-code/domain";
+import { assertNotAborted } from "./abort.js";
+import { isNotFoundError } from "./fs-errors.js";
+// Der Schluesselbau liegt in `@untangle-code/domain`, weil ihn BEIDE Seiten
+// brauchen: dieses Paket legt ab, `@untangle-code/core` schlaegt nach. Zwei
+// Kopien desselben Schluessels waeren die sicherste Art, den Cache eines Tages
+// an der falschen Stelle treffen zu lassen. Hier nur weitergereicht, damit ein
+// Aufrufer beides aus einem Paket bekommt.
+export { ANALYSIS_CACHE_KINDS, buildChunkCacheKey, buildMetricsCacheKey, buildParseCacheKey, } from "@untangle-code/domain";
+/** 256 MiB je Cache — eine Untangle-Vorgabe, keine Spec-Zahl. */
+export const DEFAULT_ANALYSIS_CACHE_MAX_BYTES = 256 * 1024 * 1024;
+/** Nach so vielen Mutationen wird das Manifest geschrieben. */
+export const MANIFEST_FLUSH_INTERVAL = 64;
+const MANIFEST_FILE_NAME = "index.json";
+function encode(text) {
+    return new TextEncoder().encode(text);
+}
+function signalOptions(options) {
+    return options?.signal ? { signal: options.signal } : undefined;
+}
+function totalBytesOf(manifest) {
+    let total = 0;
+    for (const entry of Object.values(manifest.entries)) {
+        total += entry.sizeBytes;
+    }
+    return total;
+}
+function pickEvictionCandidate(manifest, protectedKey) {
+    const keys = Object.keys(manifest.entries);
+    let best = null;
+    let bestAccess = Number.POSITIVE_INFINITY;
+    for (const key of keys) {
+        if (key === protectedKey && keys.length === 1) {
+            // Der eben geschriebene Eintrag ist der letzte — ihn zu verdraengen
+            // hiesse, `set()` stillschweigend wirkungslos zu machen.
+            continue;
+        }
+        const entry = manifest.entries[key];
+        if (entry !== undefined && entry.lastAccessEpochMs < bestAccess) {
+            bestAccess = entry.lastAccessEpochMs;
+            best = key;
+        }
+    }
+    return best;
+}
+/**
+ * Ein inhaltsadressierter JSON-Cache mit Groessengrenze, Verdraengung und
+ * Trefferquote. Der Schluessel ist eine undurchsichtige Zeichenkette; wer ihn
+ * baut, verantwortet seine Vollstaendigkeit (siehe Kopf dieser Datei).
+ */
+export class LocalContentCache {
+    fs;
+    dir;
+    clock;
+    random;
+    maxBytes;
+    manifest = null;
+    dirty = 0;
+    hits = 0;
+    misses = 0;
+    evictions = 0;
+    constructor(fs, dir, clock, random, options) {
+        this.fs = fs;
+        this.dir = dir;
+        this.clock = clock;
+        this.random = random;
+        this.maxBytes = options?.maxBytes ?? DEFAULT_ANALYSIS_CACHE_MAX_BYTES;
+    }
+    manifestPath() {
+        return nodePath.join(this.dir, MANIFEST_FILE_NAME);
+    }
+    entryFileName(logicalKey) {
+        const hash = sha256Hex(logicalKey);
+        return nodePath.join(hash.slice(0, 2), `${hash}.json`);
+    }
+    entryPath(fileName) {
+        return nodePath.join(this.dir, fileName);
+    }
+    async loadManifest(options) {
+        if (this.manifest !== null) {
+            return this.manifest;
+        }
+        let text;
+        try {
+            text = await this.fs.readTextFile(this.manifestPath(), options);
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                this.manifest = { version: 1, entries: {} };
+                return this.manifest;
+            }
+            throw error;
+        }
+        try {
+            const parsed = JSON.parse(text);
+            this.manifest =
+                parsed.entries === undefined
+                    ? { version: 1, entries: {} }
+                    : { version: 1, entries: parsed.entries };
+        }
+        catch {
+            // Kaputtes Manifest — leerer Cache statt geworfener Fehler.
+            this.manifest = { version: 1, entries: {} };
+        }
+        return this.manifest;
+    }
+    async persistManifest(options) {
+        const manifest = this.manifest;
+        if (manifest === null) {
+            return;
+        }
+        await this.fs.mkdir(this.dir, { recursive: true, ...signalOptions(options) });
+        const tempPath = `${this.manifestPath()}.${this.random.uuid()}.tmp`;
+        await this.fs.writeFile(tempPath, encode(JSON.stringify(manifest)), options);
+        await this.fs.rename(tempPath, this.manifestPath(), options);
+        this.dirty = 0;
+    }
+    async touched(options) {
+        this.dirty++;
+        if (this.dirty >= MANIFEST_FLUSH_INTERVAL) {
+            await this.persistManifest(options);
+        }
+    }
+    /** Schreibt das Manifest, falls Mutationen ausstehen. Am Ende eines Laufs aufrufen. */
+    async flush(options) {
+        if (this.dirty > 0) {
+            await this.persistManifest(options);
+        }
+    }
+    /** Der Wert, oder `null` fuer "nicht im Cache". Wirft nicht fuer kaputte Eintraege. */
+    async get(logicalKey, options) {
+        assertNotAborted(options, "analysis_cache_get");
+        const manifest = await this.loadManifest(options);
+        const entry = manifest.entries[logicalKey];
+        if (entry === undefined) {
+            this.misses++;
+            return null;
+        }
+        let text;
+        try {
+            text = await this.fs.readTextFile(this.entryPath(entry.fileName), options);
+        }
+        catch (error) {
+            if (!isNotFoundError(error)) {
+                throw error;
+            }
+            delete manifest.entries[logicalKey];
+            await this.touched(options);
+            this.misses++;
+            return null;
+        }
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            delete manifest.entries[logicalKey];
+            await this.touched(options);
+            this.misses++;
+            return null;
+        }
+        entry.lastAccessEpochMs = this.clock.nowEpochMs();
+        this.dirty++;
+        this.hits++;
+        return value;
+    }
+    async set(logicalKey, value, options) {
+        assertNotAborted(options, "analysis_cache_set");
+        const fileName = this.entryFileName(logicalKey);
+        const entryPath = this.entryPath(fileName);
+        const bytes = encode(JSON.stringify(value));
+        await this.fs.mkdir(nodePath.dirname(entryPath), {
+            recursive: true,
+            ...signalOptions(options),
+        });
+        const tempPath = `${entryPath}.${this.random.uuid()}.tmp`;
+        await this.fs.writeFile(tempPath, bytes, options);
+        await this.fs.rename(tempPath, entryPath, options);
+        const manifest = await this.loadManifest(options);
+        manifest.entries[logicalKey] = {
+            fileName,
+            sizeBytes: bytes.length,
+            lastAccessEpochMs: this.clock.nowEpochMs(),
+        };
+        await this.evictUntilWithinLimit(manifest, logicalKey, options);
+        await this.touched(options);
+    }
+    async evictUntilWithinLimit(manifest, justWrittenKey, options) {
+        let total = totalBytesOf(manifest);
+        while (total > this.maxBytes) {
+            const victim = pickEvictionCandidate(manifest, justWrittenKey);
+            if (victim === null) {
+                break;
+            }
+            const entry = manifest.entries[victim];
+            delete manifest.entries[victim];
+            if (entry !== undefined) {
+                total -= entry.sizeBytes;
+                this.evictions++;
+                try {
+                    await this.fs.remove(this.entryPath(entry.fileName), options);
+                }
+                catch {
+                    // Der Manifest-Eintrag ist so oder so weg; ein spaeterer `get`
+                    // trifft nicht mehr.
+                }
+            }
+        }
+    }
+    async stats(options) {
+        assertNotAborted(options, "analysis_cache_stats");
+        const manifest = await this.loadManifest(options);
+        const lookups = this.hits + this.misses;
+        return {
+            entryCount: Object.keys(manifest.entries).length,
+            totalBytes: totalBytesOf(manifest),
+            hits: this.hits,
+            misses: this.misses,
+            hitRate: lookups === 0 ? 0 : this.hits / lookups,
+            evictions: this.evictions,
+        };
+    }
+    /** Loescht ausschliesslich das eigene Verzeichnis dieses Caches. */
+    async clear(options) {
+        assertNotAborted(options, "analysis_cache_clear");
+        await this.fs.remove(this.dir, { recursive: true, ...signalOptions(options) });
+        this.manifest = { version: 1, entries: {} };
+        this.dirty = 0;
+    }
+}
+/**
+ * Die drei Caches als ein Gegenstand — genau die Form, die
+ * `@untangle-code/core` als `AnalysisCacheLike` erwartet.
+ */
+export class LocalAnalysisCache {
+    parse;
+    chunk;
+    metrics;
+    constructor(parse, chunk, metrics) {
+        this.parse = parse;
+        this.chunk = chunk;
+        this.metrics = metrics;
+    }
+    of(kind) {
+        if (kind === "parse")
+            return this.parse;
+        if (kind === "chunk")
+            return this.chunk;
+        return this.metrics;
+    }
+    async get(kind, key, options) {
+        return this.of(kind).get(key, options);
+    }
+    async set(kind, key, value, options) {
+        await this.of(kind).set(key, value, options);
+    }
+    /** Schreibt die Manifeste aller drei Caches. */
+    async flush(options) {
+        await this.parse.flush(options);
+        await this.chunk.flush(options);
+        await this.metrics.flush(options);
+    }
+    async stats(options) {
+        const parse = await this.parse.stats(options);
+        const chunk = await this.chunk.stats(options);
+        const metrics = await this.metrics.stats(options);
+        const totalHits = parse.hits + chunk.hits + metrics.hits;
+        const totalMisses = parse.misses + chunk.misses + metrics.misses;
+        const lookups = totalHits + totalMisses;
+        return {
+            parse,
+            chunk,
+            metrics,
+            totalHits,
+            totalMisses,
+            hitRate: lookups === 0 ? 0 : totalHits / lookups,
+        };
+    }
+    async clear(options) {
+        await this.parse.clear(options);
+        await this.chunk.clear(options);
+        await this.metrics.clear(options);
+    }
+}
+//# sourceMappingURL=analysis-cache.js.map

package/dist/analysis-cache.js.map

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

package/dist/checkpoint-store.d.ts

@@ -0,0 +1,22 @@
+import type { CheckpointStorePort, FileSystemPort, IndexCheckpointV1, PortCallOptions, Random } from "@untangle-code/domain";
+/** Local, atomically-mirrored `CheckpointStorePort` under `jobs/`. */
+export declare class LocalCheckpointStore implements CheckpointStorePort {
+    private readonly fs;
+    private readonly jobsDir;
+    private readonly random;
+    constructor(fs: FileSystemPort, jobsDir: string, random: Random);
+    private pathForJob;
+    /**
+     * Both components are variable-length, so a plain concatenation would be
+     * ambiguous (e.g. `repoId="ab"` + `refId="c"` vs. `repoId="a"` +
+     * `refId="bc"`) — joined with the same separator domain's own identity
+     * model uses for exactly this reason (`identity.ts`'s doc comment).
+     */
+    private pointerPathFor;
+    private writeAtomic;
+    save(checkpoint: IndexCheckpointV1, options?: PortCallOptions): Promise<void>;
+    load(jobId: string, options?: PortCallOptions): Promise<IndexCheckpointV1 | null>;
+    loadLatest(repoId: string, refId: string, options?: PortCallOptions): Promise<IndexCheckpointV1 | null>;
+    delete(jobId: string, options?: PortCallOptions): Promise<void>;
+}
+//# sourceMappingURL=checkpoint-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.d.ts","sourceRoot":"","sources":["../src/checkpoint-store.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,MAAM,EACP,MAAM,uBAAuB,CAAC;AAoB/B,sEAAsE;AACtE,qBAAa,oBAAqB,YAAW,mBAAmB;IAE5D,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,EAAE,EAAE,cAAc,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM;IAGjC,OAAO,CAAC,UAAU;IAIlB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;YAKR,WAAW;IAYZ,IAAI,CAAC,UAAU,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAW7E,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IA0BjF,UAAU,CACrB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAsBvB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAI7E"}

package/dist/checkpoint-store.js

@@ -0,0 +1,123 @@
+/**
+ * Local checkpoint mirror (architecture.md §12, §13.3; spec.md §11.2:
+ * "Nach jedem konfigurierten Dateibatch MUSS ein Checkpoint gespeichert
+ * werden" / "Bei Neustart MUSS der Job ab dem letzten bestätigten
+ * Checkpoint fortsetzbar sein").
+ *
+ * Every write is temp-file-then-rename: the checkpoint at `jobs/<jobId>.json`
+ * is only ever created or replaced by a single atomic `rename` onto that
+ * exact path, so a process crash mid-write leaves, at worst, an orphaned
+ * `*.tmp` file next to it — the real path itself is always either the
+ * previous good checkpoint or the new one, never a half-written mix of both
+ * (see README "Entscheidungen" for the crash-simulation test).
+ *
+ * `jobs/latest/<hash>.json` is a small secondary index — "which job is the
+ * latest checkpoint for this repo+ref" — so `loadLatest` does not have to
+ * list and parse every checkpoint file. It is written the same atomic way,
+ * AFTER the checkpoint itself, so a crash between the two writes leaves the
+ * pointer stale (pointing at the previous job) rather than pointing at a
+ * checkpoint that does not exist — `loadLatest` degrades to `null` if the
+ * pointer cannot be trusted at all (spec.md §25.2: reads degrade optional
+ * data in a controlled way), while `load(jobId)` on an actually corrupted
+ * checkpoint body throws instead, because THAT is the resume-critical record
+ * itself, not an accelerator index over it.
+ */
+import * as nodePath from "node:path";
+import { ID_COMPONENT_SEPARATOR, sha256Hex, UntangleError } from "@untangle-code/domain";
+import { assertNotAborted } from "./abort.js";
+import { isNotFoundError } from "./fs-errors.js";
+const POINTER_DIR_NAME = "latest";
+function encode(text) {
+    return new TextEncoder().encode(text);
+}
+function signalOptions(options) {
+    return options?.signal ? { signal: options.signal } : undefined;
+}
+/** Local, atomically-mirrored `CheckpointStorePort` under `jobs/`. */
+export class LocalCheckpointStore {
+    fs;
+    jobsDir;
+    random;
+    constructor(fs, jobsDir, random) {
+        this.fs = fs;
+        this.jobsDir = jobsDir;
+        this.random = random;
+    }
+    pathForJob(jobId) {
+        return nodePath.join(this.jobsDir, `${jobId}.json`);
+    }
+    /**
+     * Both components are variable-length, so a plain concatenation would be
+     * ambiguous (e.g. `repoId="ab"` + `refId="c"` vs. `repoId="a"` +
+     * `refId="bc"`) — joined with the same separator domain's own identity
+     * model uses for exactly this reason (`identity.ts`'s doc comment).
+     */
+    pointerPathFor(repoId, refId) {
+        const hash = sha256Hex(`${repoId}${ID_COMPONENT_SEPARATOR}${refId}`);
+        return nodePath.join(this.jobsDir, POINTER_DIR_NAME, `${hash}.json`);
+    }
+    async writeAtomic(finalPath, content, options) {
+        const dir = nodePath.dirname(finalPath);
+        await this.fs.mkdir(dir, { recursive: true, ...signalOptions(options) });
+        const tempPath = `${finalPath}.${this.random.uuid()}.tmp`;
+        await this.fs.writeFile(tempPath, encode(content), options);
+        await this.fs.rename(tempPath, finalPath, options);
+    }
+    async save(checkpoint, options) {
+        assertNotAborted(options, "checkpoint_save");
+        await this.writeAtomic(this.pathForJob(checkpoint.jobId), JSON.stringify(checkpoint), options);
+        const pointer = { jobId: checkpoint.jobId };
+        await this.writeAtomic(this.pointerPathFor(checkpoint.repoId, checkpoint.refId), JSON.stringify(pointer), options);
+    }
+    async load(jobId, options) {
+        assertNotAborted(options, "checkpoint_load");
+        let text;
+        try {
+            text = await this.fs.readTextFile(this.pathForJob(jobId), options);
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                return null;
+            }
+            throw error;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (parseError) {
+            // Should never happen given atomic temp+rename writes — this is a
+            // defensive, loud failure (fail-closed, spec.md §25.2) for the one
+            // record a resume actually depends on, not a "missing optional data"
+            // case that could silently degrade to "start over".
+            throw new UntangleError("INDEX_INCOMPLETE", `checkpoint "${jobId}" is corrupted and cannot be safely resumed from`, { operation: "checkpoint_load", context: { jobId }, cause: parseError });
+        }
+    }
+    async loadLatest(repoId, refId, options) {
+        assertNotAborted(options, "checkpoint_load_latest");
+        let text;
+        try {
+            text = await this.fs.readTextFile(this.pointerPathFor(repoId, refId), options);
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                return null;
+            }
+            throw error;
+        }
+        let pointer;
+        try {
+            pointer = JSON.parse(text);
+        }
+        catch {
+            // The pointer is an accelerator index, not the resume record itself —
+            // degrade to "no known latest" rather than throwing (spec.md §25.2).
+            return null;
+        }
+        return this.load(pointer.jobId, options);
+    }
+    async delete(jobId, options) {
+        assertNotAborted(options, "checkpoint_delete");
+        await this.fs.remove(this.pathForJob(jobId), options);
+    }
+}
+//# sourceMappingURL=checkpoint-store.js.map

package/dist/checkpoint-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.js","sourceRoot":"","sources":["../src/checkpoint-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,QAAQ,MAAM,WAAW,CAAC;AAStC,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,gBAAgB,GAAG,QAAQ,CAAC;AAMlC,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,aAAa,CAAC,OAAoC;IACzD,OAAO,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED,sEAAsE;AACtE,MAAM,OAAO,oBAAoB;IAEZ;IACA;IACA;IAHnB,YACmB,EAAkB,EAClB,OAAe,EACf,MAAc;QAFd,OAAE,GAAF,EAAE,CAAgB;QAClB,YAAO,GAAP,OAAO,CAAQ;QACf,WAAM,GAAN,MAAM,CAAQ;IAC9B,CAAC;IAEI,UAAU,CAAC,KAAa;QAC9B,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IACtD,CAAC;IAED;;;;;OAKG;IACK,cAAc,CAAC,MAAc,EAAE,KAAa;QAClD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,sBAAsB,GAAG,KAAK,EAAE,CAAC,CAAC;QACrE,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;IACvE,CAAC;IAEO,KAAK,CAAC,WAAW,CACvB,SAAiB,EACjB,OAAe,EACf,OAAoC;QAEpC,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACxC,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,GAAG,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC;QAC1D,MAAM,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QAC5D,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,UAA6B,EAAE,OAAyB;QACxE,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QAC7C,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,CAAC;QAC/F,MAAM,OAAO,GAAoB,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,CAAC;QAC7D,MAAM,IAAI,CAAC,WAAW,CACpB,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,EACxD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EACvB,OAAO,CACR,CAAC;IACJ,CAAC;IAEM,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,OAAyB;QACxD,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;QAC7C,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;QACrE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAsB,CAAC;QAC/C,CAAC;QAAC,OAAO,UAAU,EAAE,CAAC;YACpB,kEAAkE;YAClE,mEAAmE;YACnE,qEAAqE;YACrE,oDAAoD;YACpD,MAAM,IAAI,aAAa,CACrB,kBAAkB,EAClB,eAAe,KAAK,kDAAkD,EACtE,EAAE,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,CACxE,CAAC;QACJ,CAAC;IACH,CAAC;IAEM,KAAK,CAAC,UAAU,CACrB,MAAc,EACd,KAAa,EACb,OAAyB;QAEzB,gBAAgB,CAAC,OAAO,EAAE,wBAAwB,CAAC,CAAC;QACpD,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;QACjF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC3B,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;QACD,IAAI,OAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAoB,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,qEAAqE;YACrE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAEM,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAAyB;QAC1D,gBAAgB,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;QAC/C,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;IACxD,CAAC;CACF"}

package/dist/embedding-cache.d.ts

@@ -0,0 +1,38 @@
+import type { Clock, FileSystemPort, PortCallOptions, Random } from "@untangle-code/domain";
+/** 512 MiB — an Untangle default, not spec-mandated (spec.md §9.4 leaves the
+ * limit open); callers pass their own `maxBytes` where config specifies one. */
+export declare const DEFAULT_EMBEDDING_CACHE_MAX_BYTES: number;
+export interface EmbeddingCacheStatsV1 {
+    entryCount: number;
+    totalBytes: number;
+}
+/**
+ * Cache key exactly per spec.md §9.4: `embedding_profile_id + SHA256(prepared_text)`.
+ * Exported so callers/tests can reason about identity without depending on
+ * this class's internal file sharding.
+ */
+export declare function buildEmbeddingCacheKey(embeddingProfileId: string, preparedText: string): string;
+export declare class LocalEmbeddingCache {
+    private readonly fs;
+    private readonly dir;
+    private readonly clock;
+    private readonly random;
+    private readonly maxBytes;
+    private manifest;
+    constructor(fs: FileSystemPort, dir: string, clock: Clock, random: Random, options?: {
+        maxBytes?: number;
+    });
+    private manifestPath;
+    private entryFileName;
+    private entryPath;
+    private loadManifest;
+    private persistManifest;
+    get(embeddingProfileId: string, preparedText: string, options?: PortCallOptions): Promise<number[] | null>;
+    set(embeddingProfileId: string, preparedText: string, vector: readonly number[], options?: PortCallOptions): Promise<void>;
+    private evictUntilWithinLimit;
+    stats(options?: PortCallOptions): Promise<EmbeddingCacheStatsV1>;
+    /** Explicit, whole-cache removal (the one "clear everything" operation this
+     * class exposes — always naming its exact target: this cache's own directory). */
+    clear(options?: PortCallOptions): Promise<void>;
+}
+//# sourceMappingURL=embedding-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-cache.d.ts","sourceRoot":"","sources":["../src/embedding-cache.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAM5F;gFACgF;AAChF,eAAO,MAAM,iCAAiC,QAAoB,CAAC;AAInE,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAuDD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,kBAAkB,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE/F;AAED,qBAAa,mBAAmB;IAK5B,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAA2B;gBAGxB,EAAE,EAAE,cAAc,EAClB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EAC/B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;IAKjC,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,SAAS;YAIH,YAAY;YA2BZ,eAAe;IAWhB,GAAG,CACd,kBAAkB,EAAE,MAAM,EAC1B,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;IAiCd,GAAG,CACd,kBAAkB,EAAE,MAAM,EAC1B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,IAAI,CAAC;YA0BF,qBAAqB;IAyBtB,KAAK,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAM7E;sFACkF;IACrE,KAAK,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAK7D"}