circle-ir-ai 2.22.0 → 2.27.0

package/dist/cache/backend.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cache backend abstraction (cognium-ai#158 Acceptance #4).
+ *
+ * Defines the storage interface used by `ClassificationCache` so the
+ * three caches (tree / verify / discovery) can be persisted to any of:
+ *   - local filesystem (default; preserves ≤2.26.0 behavior)
+ *   - in-memory map (unit tests)
+ *   - S3-compatible object store (Cloudflare R2, AWS S3, MinIO)
+ *
+ * The interface is byte-oriented and async — backends serialize raw
+ * UTF-8 JSON strings under opaque keys. TTL / hit-counter / fingerprint
+ * key composition stays in `ClassificationCache` so a backend swap
+ * doesn't change observable cache semantics.
+ *
+ * Selection: `LLM_CACHE_BACKEND` env (`local` | `memory` | `r2`).
+ * Default = `local` (back-compat). See `./backends/index.ts` factory.
+ */
+export interface CacheBackend {
+    /**
+     * Fetch the serialized payload for `key`, or null if absent.
+     * Backends MUST NOT treat "not found" as an error.
+     * Read errors (I/O, decode) MUST be swallowed and returned as null
+     * so the cache layer falls through to a miss instead of crashing
+     * the scan.
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Persist `value` under `key`. Backends MUST be safe under
+     * concurrent writers — local-fs uses tmp + rename, S3 backends
+     * rely on the object store's last-writer-wins semantics.
+     * Write errors MUST be swallowed (the cache is an optimization,
+     * not a correctness boundary).
+     */
+    set(key: string, value: string): Promise<void>;
+    /** Optional: cheap existence check. Default impl is `get(...) !== null`. */
+    has?(key: string): Promise<boolean>;
+    /** Optional: delete a single entry. Used by TTL eviction. */
+    delete?(key: string): Promise<void>;
+    /**
+     * Optional: count / list entries. Used by `ClassificationCache.stats()`.
+     * S3 backends MAY be slow here; callers should treat as best-effort.
+     */
+    count?(): Promise<number>;
+    /**
+     * Optional: drop everything. Used by tests; production callers
+     * should never hit this.
+     */
+    clear?(): Promise<void>;
+    /** Human-readable backend identifier for logs (`local-fs`, `r2`, etc.). */
+    readonly kind: string;
+}
+//# sourceMappingURL=backend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/cache/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEzC;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C,4EAA4E;IAC5E,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEpC,6DAA6D;IAC7D,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;;OAGG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAE1B;;;OAGG;IACH,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB"}

package/dist/cache/backend.js

@@ -0,0 +1,19 @@
+/**
+ * Cache backend abstraction (cognium-ai#158 Acceptance #4).
+ *
+ * Defines the storage interface used by `ClassificationCache` so the
+ * three caches (tree / verify / discovery) can be persisted to any of:
+ *   - local filesystem (default; preserves ≤2.26.0 behavior)
+ *   - in-memory map (unit tests)
+ *   - S3-compatible object store (Cloudflare R2, AWS S3, MinIO)
+ *
+ * The interface is byte-oriented and async — backends serialize raw
+ * UTF-8 JSON strings under opaque keys. TTL / hit-counter / fingerprint
+ * key composition stays in `ClassificationCache` so a backend swap
+ * doesn't change observable cache semantics.
+ *
+ * Selection: `LLM_CACHE_BACKEND` env (`local` | `memory` | `r2`).
+ * Default = `local` (back-compat). See `./backends/index.ts` factory.
+ */
+export {};
+//# sourceMappingURL=backend.js.map

package/dist/cache/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/cache/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/cache/backends/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cache backend factory (cognium-ai#158 Acceptance #4).
+ *
+ * Selects a `CacheBackend` per cache-dir based on `LLM_CACHE_BACKEND`:
+ *   `local`  (default) — `LocalFSBackend(cacheDir)`
+ *   `memory`            — `MemoryBackend()`
+ *   `r2`                — `R2Backend({R2_ENDPOINT, R2_BUCKET, …})`
+ *
+ * For R2, the `cacheDir` is mapped to a stable sub-prefix so the three
+ * caches (tree / verify / discovery) live under separate keyspaces in
+ * a single bucket:
+ *   tree      → `<R2_PREFIX>/tree/`
+ *   verify    → `<R2_PREFIX>/verify/`
+ *   discovery → `<R2_PREFIX>/discovery/`
+ *   <other>   → `<R2_PREFIX>/misc/`
+ *
+ * (Phase 2 #158 layout — `<lang>/_tree/<pkg>@<ver>/…` — lands as a
+ * separate refactor on top of this.)
+ */
+import type { CacheBackend } from '../backend.js';
+import { LocalFSBackend } from './local-fs.js';
+import { MemoryBackend } from './memory.js';
+import { R2Backend } from './r2.js';
+export { LocalFSBackend, MemoryBackend, R2Backend };
+export declare function getBackendKind(): 'local' | 'memory' | 'r2';
+/**
+ * Build the backend for a given cacheDir. `cacheDir` is the local-fs
+ * path the caller would have used pre-abstraction; for non-fs backends
+ * we use only its basename as a sub-prefix.
+ */
+export declare function makeBackend(cacheDir: string): CacheBackend;
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/backends/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC;AAEpD,wBAAgB,cAAc,IAAI,OAAO,GAAG,QAAQ,GAAG,IAAI,CAK1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAkC1D"}

package/dist/cache/backends/index.js

@@ -0,0 +1,76 @@
+/**
+ * Cache backend factory (cognium-ai#158 Acceptance #4).
+ *
+ * Selects a `CacheBackend` per cache-dir based on `LLM_CACHE_BACKEND`:
+ *   `local`  (default) — `LocalFSBackend(cacheDir)`
+ *   `memory`            — `MemoryBackend()`
+ *   `r2`                — `R2Backend({R2_ENDPOINT, R2_BUCKET, …})`
+ *
+ * For R2, the `cacheDir` is mapped to a stable sub-prefix so the three
+ * caches (tree / verify / discovery) live under separate keyspaces in
+ * a single bucket:
+ *   tree      → `<R2_PREFIX>/tree/`
+ *   verify    → `<R2_PREFIX>/verify/`
+ *   discovery → `<R2_PREFIX>/discovery/`
+ *   <other>   → `<R2_PREFIX>/misc/`
+ *
+ * (Phase 2 #158 layout — `<lang>/_tree/<pkg>@<ver>/…` — lands as a
+ * separate refactor on top of this.)
+ */
+import * as path from 'path';
+import { LocalFSBackend } from './local-fs.js';
+import { MemoryBackend } from './memory.js';
+import { R2Backend } from './r2.js';
+export { LocalFSBackend, MemoryBackend, R2Backend };
+export function getBackendKind() {
+    const raw = (process.env.LLM_CACHE_BACKEND ?? '').toLowerCase().trim();
+    if (raw === 'r2')
+        return 'r2';
+    if (raw === 'memory')
+        return 'memory';
+    return 'local';
+}
+/**
+ * Build the backend for a given cacheDir. `cacheDir` is the local-fs
+ * path the caller would have used pre-abstraction; for non-fs backends
+ * we use only its basename as a sub-prefix.
+ */
+export function makeBackend(cacheDir) {
+    const kind = getBackendKind();
+    if (kind === 'memory')
+        return new MemoryBackend();
+    if (kind === 'r2') {
+        const endpoint = process.env.R2_ENDPOINT;
+        const bucket = process.env.R2_BUCKET;
+        const accessKeyId = process.env.R2_ACCESS_KEY_ID;
+        const secretAccessKey = process.env.R2_SECRET_ACCESS_KEY;
+        if (!endpoint || !bucket || !accessKeyId || !secretAccessKey) {
+            // Misconfigured; degrade to local instead of crashing. The
+            // operator will see no cross-runner sharing but the scan
+            // still works.
+            // eslint-disable-next-line no-console
+            console.warn('[cache] LLM_CACHE_BACKEND=r2 but R2_ENDPOINT / R2_BUCKET / ' +
+                'R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY not all set — ' +
+                'falling back to local filesystem cache.');
+            return new LocalFSBackend({ cacheDir });
+        }
+        const userPrefix = (process.env.R2_PREFIX ?? 'v1').replace(/^\/+|\/+$/g, '');
+        const sub = cacheDirToSubPrefix(cacheDir);
+        return new R2Backend({
+            endpoint,
+            bucket,
+            accessKeyId,
+            secretAccessKey,
+            region: process.env.R2_REGION ?? 'auto',
+            prefix: `${userPrefix}/${sub}`,
+        });
+    }
+    return new LocalFSBackend({ cacheDir });
+}
+function cacheDirToSubPrefix(cacheDir) {
+    const base = path.basename(cacheDir).toLowerCase();
+    if (base === 'tree' || base === 'verify' || base === 'discovery')
+        return base;
+    return 'misc';
+}
+//# sourceMappingURL=index.js.map

package/dist/cache/backends/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cache/backends/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,CAAC;AAEpD,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;IACvE,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,GAAG,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACtC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,aAAa,EAAE,CAAC;IAElD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;QACzC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;QACrC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;QACjD,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACzD,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW,IAAI,CAAC,eAAe,EAAE,CAAC;YAC7D,2DAA2D;YAC3D,yDAAyD;YACzD,eAAe;YACf,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACV,6DAA6D;gBAC7D,wDAAwD;gBACxD,yCAAyC,CAC1C,CAAC;YACF,OAAO,IAAI,cAAc,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,UAAU,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QAC7E,MAAM,GAAG,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAC;QAC1C,OAAO,IAAI,SAAS,CAAC;YACnB,QAAQ;YACR,MAAM;YACN,WAAW;YACX,eAAe;YACf,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,MAAM;YACvC,MAAM,EAAE,GAAG,UAAU,IAAI,GAAG,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;IAED,OAAO,IAAI,cAAc,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAgB;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IACnD,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cache/backends/local-fs.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Local filesystem cache backend (cognium-ai#158 Acceptance #4).
+ *
+ * Preserves ≤2.26.0 on-disk shape:
+ *   <cacheDir>/<key[0:2]>/<key>.json
+ *
+ * Atomic write via tmp + rename so concurrent `cognium-ai scan`
+ * processes don't corrupt each other's entries (same pattern as
+ * the previous inline implementation in `classification-cache.ts`).
+ *
+ * Read/write errors are swallowed and surfaced as cache misses.
+ */
+import type { CacheBackend } from '../backend.js';
+export interface LocalFSBackendOptions {
+    /** Root directory under which `<key[0:2]>/<key>.json` lives. */
+    cacheDir: string;
+}
+export declare class LocalFSBackend implements CacheBackend {
+    readonly kind = "local-fs";
+    private cacheDir;
+    constructor(opts: LocalFSBackendOptions);
+    private ensureCacheDir;
+    private cachePath;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    count(): Promise<number>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=local-fs.d.ts.map

package/dist/cache/backends/local-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-fs.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/local-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,cAAc;IAC3B,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,qBAAqB;IAKvC,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,SAAS;IAKX,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAgBxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B"}

package/dist/cache/backends/local-fs.js

@@ -0,0 +1,101 @@
+/**
+ * Local filesystem cache backend (cognium-ai#158 Acceptance #4).
+ *
+ * Preserves ≤2.26.0 on-disk shape:
+ *   <cacheDir>/<key[0:2]>/<key>.json
+ *
+ * Atomic write via tmp + rename so concurrent `cognium-ai scan`
+ * processes don't corrupt each other's entries (same pattern as
+ * the previous inline implementation in `classification-cache.ts`).
+ *
+ * Read/write errors are swallowed and surfaced as cache misses.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export class LocalFSBackend {
+    kind = 'local-fs';
+    cacheDir;
+    constructor(opts) {
+        this.cacheDir = opts.cacheDir;
+        this.ensureCacheDir();
+    }
+    ensureCacheDir() {
+        if (!fs.existsSync(this.cacheDir)) {
+            fs.mkdirSync(this.cacheDir, { recursive: true });
+        }
+    }
+    cachePath(key) {
+        const subdir = key.substring(0, 2);
+        return path.join(this.cacheDir, subdir, `${key}.json`);
+    }
+    async get(key) {
+        const p = this.cachePath(key);
+        try {
+            if (!fs.existsSync(p))
+                return null;
+            return fs.readFileSync(p, 'utf-8');
+        }
+        catch {
+            return null;
+        }
+    }
+    async set(key, value) {
+        const p = this.cachePath(key);
+        const subdir = path.dirname(p);
+        const tmp = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 8)}`;
+        try {
+            if (!fs.existsSync(subdir)) {
+                fs.mkdirSync(subdir, { recursive: true });
+            }
+            fs.writeFileSync(tmp, value);
+            fs.renameSync(tmp, p);
+        }
+        catch {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    async has(key) {
+        return fs.existsSync(this.cachePath(key));
+    }
+    async delete(key) {
+        const p = this.cachePath(key);
+        try {
+            if (fs.existsSync(p))
+                fs.unlinkSync(p);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    async count() {
+        let n = 0;
+        if (!fs.existsSync(this.cacheDir))
+            return 0;
+        try {
+            for (const sub of fs.readdirSync(this.cacheDir)) {
+                const subPath = path.join(this.cacheDir, sub);
+                try {
+                    if (fs.statSync(subPath).isDirectory()) {
+                        n += fs.readdirSync(subPath).length;
+                    }
+                }
+                catch { /* skip */ }
+            }
+        }
+        catch { /* ignore */ }
+        return n;
+    }
+    async clear() {
+        try {
+            if (fs.existsSync(this.cacheDir)) {
+                fs.rmSync(this.cacheDir, { recursive: true, force: true });
+            }
+            this.ensureCacheDir();
+        }
+        catch { /* ignore */ }
+    }
+}
+//# sourceMappingURL=local-fs.js.map

package/dist/cache/backends/local-fs.js.map

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

package/dist/cache/backends/memory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * In-memory cache backend (cognium-ai#158 Acceptance #4).
+ *
+ * Map-backed; used by unit tests to avoid filesystem coupling.
+ * Not intended for production — no eviction, no persistence,
+ * grows unbounded.
+ */
+import type { CacheBackend } from '../backend.js';
+export declare class MemoryBackend implements CacheBackend {
+    readonly kind = "memory";
+    private store;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    count(): Promise<number>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/cache/backends/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,qBAAa,aAAc,YAAW,YAAY;IAChD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,KAAK,CAAkC;IAEzC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAIxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/cache/backends/memory.js

@@ -0,0 +1,30 @@
+/**
+ * In-memory cache backend (cognium-ai#158 Acceptance #4).
+ *
+ * Map-backed; used by unit tests to avoid filesystem coupling.
+ * Not intended for production — no eviction, no persistence,
+ * grows unbounded.
+ */
+export class MemoryBackend {
+    kind = 'memory';
+    store = new Map();
+    async get(key) {
+        return this.store.get(key) ?? null;
+    }
+    async set(key, value) {
+        this.store.set(key, value);
+    }
+    async has(key) {
+        return this.store.has(key);
+    }
+    async delete(key) {
+        this.store.delete(key);
+    }
+    async count() {
+        return this.store.size;
+    }
+    async clear() {
+        this.store.clear();
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/cache/backends/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/cache/backends/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,QAAQ,CAAC;IACjB,KAAK,GAAwB,IAAI,GAAG,EAAE,CAAC;IAE/C,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,KAAa;QAClC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}

package/dist/cache/backends/r2.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cloudflare R2 (S3-compatible) cache backend (cognium-ai#158).
+ *
+ * Phase 1 scope: drop-in object-store mirror of the local-fs key shape.
+ * The R2 object key is `<prefix>/<key[0:2]>/<key>.json` — same sharding
+ * as `LocalFSBackend` so the existing 3-component `ClassificationCache`
+ * keys (content + classifier + modelFingerprint hash) just work.
+ *
+ * Phase 2 (#158 layout reshape — separate follow-up): swap the opaque
+ * 64-hex key for the structured `<lang>/_tree/<pkg>@<ver>/<fileSHA>.json`
+ * style and reuse the `pkg-coord` + `model-registry` normalization
+ * helpers. Phase 1 only proves wire-up + cross-runner sharing.
+ *
+ * Configuration (env vars):
+ *   LLM_CACHE_BACKEND=r2
+ *   R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+ *   R2_BUCKET=cognium-cache
+ *   R2_ACCESS_KEY_ID=<S3-compat access key>
+ *   R2_SECRET_ACCESS_KEY=<S3-compat secret>
+ *   R2_REGION=auto                  (default; R2 ignores region)
+ *   R2_PREFIX=v1                    (default; namespaces the bucket)
+ *
+ * Failure mode: R2 errors are swallowed and surfaced as misses so a
+ * network blip during scan degrades to local behavior, not a crash.
+ * This matches `LocalFSBackend` and the cache-as-optimization contract
+ * spelled out in `backend.ts`.
+ */
+import type { CacheBackend } from '../backend.js';
+export interface R2BackendOptions {
+    endpoint: string;
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** R2 ignores region; default `auto`. */
+    region?: string;
+    /** Object-key prefix (default `v1`). Used to roll layout versions. */
+    prefix?: string;
+}
+export declare class R2Backend implements CacheBackend {
+    readonly kind = "r2";
+    private client;
+    private bucket;
+    private prefix;
+    constructor(opts: R2BackendOptions);
+    private objectKey;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=r2.d.ts.map

package/dist/cache/backends/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,SAAU,YAAW,YAAY;IAC5C,QAAQ,CAAC,IAAI,QAAQ;IACrB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;gBAEX,IAAI,EAAE,gBAAgB;IAelC,OAAO,CAAC,SAAS;IAKX,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkBxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAUzC"}

package/dist/cache/backends/r2.js

@@ -0,0 +1,116 @@
+/**
+ * Cloudflare R2 (S3-compatible) cache backend (cognium-ai#158).
+ *
+ * Phase 1 scope: drop-in object-store mirror of the local-fs key shape.
+ * The R2 object key is `<prefix>/<key[0:2]>/<key>.json` — same sharding
+ * as `LocalFSBackend` so the existing 3-component `ClassificationCache`
+ * keys (content + classifier + modelFingerprint hash) just work.
+ *
+ * Phase 2 (#158 layout reshape — separate follow-up): swap the opaque
+ * 64-hex key for the structured `<lang>/_tree/<pkg>@<ver>/<fileSHA>.json`
+ * style and reuse the `pkg-coord` + `model-registry` normalization
+ * helpers. Phase 1 only proves wire-up + cross-runner sharing.
+ *
+ * Configuration (env vars):
+ *   LLM_CACHE_BACKEND=r2
+ *   R2_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
+ *   R2_BUCKET=cognium-cache
+ *   R2_ACCESS_KEY_ID=<S3-compat access key>
+ *   R2_SECRET_ACCESS_KEY=<S3-compat secret>
+ *   R2_REGION=auto                  (default; R2 ignores region)
+ *   R2_PREFIX=v1                    (default; namespaces the bucket)
+ *
+ * Failure mode: R2 errors are swallowed and surfaced as misses so a
+ * network blip during scan degrades to local behavior, not a crash.
+ * This matches `LocalFSBackend` and the cache-as-optimization contract
+ * spelled out in `backend.ts`.
+ */
+import { S3Client, GetObjectCommand, PutObjectCommand, HeadObjectCommand, DeleteObjectCommand, } from '@aws-sdk/client-s3';
+export class R2Backend {
+    kind = 'r2';
+    client;
+    bucket;
+    prefix;
+    constructor(opts) {
+        this.bucket = opts.bucket;
+        this.prefix = (opts.prefix ?? 'v1').replace(/^\/+|\/+$/g, '');
+        this.client = new S3Client({
+            endpoint: opts.endpoint,
+            region: opts.region ?? 'auto',
+            credentials: {
+                accessKeyId: opts.accessKeyId,
+                secretAccessKey: opts.secretAccessKey,
+            },
+            // R2 requires path-style addressing for the S3-compat endpoint.
+            forcePathStyle: true,
+        });
+    }
+    objectKey(key) {
+        const sub = key.substring(0, 2);
+        return `${this.prefix}/${sub}/${key}.json`;
+    }
+    async get(key) {
+        try {
+            const out = await this.client.send(new GetObjectCommand({
+                Bucket: this.bucket,
+                Key: this.objectKey(key),
+            }));
+            if (!out.Body)
+                return null;
+            // SDK v3 returns a stream; collect to string.
+            const stream = out.Body;
+            return await streamToString(stream);
+        }
+        catch (err) {
+            // 404 → miss. Other errors swallowed (cache is best-effort).
+            const name = err?.name;
+            if (name === 'NoSuchKey' || name === 'NotFound')
+                return null;
+            return null;
+        }
+    }
+    async set(key, value) {
+        try {
+            await this.client.send(new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: this.objectKey(key),
+                Body: value,
+                ContentType: 'application/json',
+            }));
+        }
+        catch {
+            /* swallow: cache write failure is non-fatal */
+        }
+    }
+    async has(key) {
+        try {
+            await this.client.send(new HeadObjectCommand({
+                Bucket: this.bucket,
+                Key: this.objectKey(key),
+            }));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async delete(key) {
+        try {
+            await this.client.send(new DeleteObjectCommand({
+                Bucket: this.bucket,
+                Key: this.objectKey(key),
+            }));
+        }
+        catch {
+            /* swallow */
+        }
+    }
+}
+async function streamToString(stream) {
+    const chunks = [];
+    for await (const chunk of stream) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString('utf-8');
+}
+//# sourceMappingURL=r2.js.map

package/dist/cache/backends/r2.js.map

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

package/dist/cache/classification-cache.d.ts

@@ -11,6 +11,11 @@
  * - Cache directory: .cognium/cache/
  * - Hit/miss tracking for observability
  *
+ * Storage is delegated to a `CacheBackend` (cognium-ai#158 Acceptance #4).
+ * Default = `LocalFSBackend` (preserves ≤2.26.0 on-disk shape). Selecting
+ * `LLM_CACHE_BACKEND=r2` swaps to Cloudflare R2 transparently so two
+ * runners on different machines share the same cache.
+ *
  * Model dimension (cognium-ai#151 P0 spike):
  *   When `modelFingerprint` is supplied (typically via
  *   `getPhaseModelFingerprint()` from `../llm/config.ts`) it becomes part
@@ -24,8 +29,10 @@
  *   ≤2.21.0) keep working — the first run after wire-through is a cache
  *   miss only for the call sites that opt into the fingerprint.
  */
+import type { CacheBackend } from './backend.js';
 export interface ClassificationCacheOptions {
-    /** Cache directory (default: .cognium/cache/ in project root) */
+    /** Cache directory (default: .cognium/cache/ in project root). For
+     *  non-fs backends this is interpreted as a sub-prefix only. */
     cacheDir?: string;
     /** Maximum age of entries in ms (default: 24h) */
     maxAge?: number;
@@ -39,31 +46,38 @@ export interface ClassificationCacheOptions {
      * Defaults to empty string (legacy 2-component key shape).
      */
     modelFingerprint?: string;
+    /**
+     * Override the backend instance (tests). When omitted we build one
+     * via `makeBackend(cacheDir)` based on `LLM_CACHE_BACKEND` env.
+     */
+    backend?: CacheBackend;
 }
 export declare class ClassificationCache<T = unknown> {
     private cacheDir;
     private maxAge;
     private enabled;
     private modelFingerprint;
+    private backend;
     private memoryCache;
     private hits;
     private misses;
     constructor(options?: ClassificationCacheOptions);
     /** Per-phase model identity used in cache key (cognium-ai#151). */
     getModelFingerprint(): string;
+    /** Backend kind identifier (`local-fs` | `memory` | `r2`). Observability. */
+    getBackendKind(): string;
     private computeKey;
-    private getCachePath;
-    private ensureCacheDir;
     private isValid;
-    get(content: string, classifier: string): T | null;
-    set(content: string, classifier: string, result: T): void;
-    has(content: string, classifier: string): boolean;
-    clear(): void;
-    stats(): {
+    get(content: string, classifier: string): Promise<T | null>;
+    set(content: string, classifier: string, result: T): Promise<void>;
+    has(content: string, classifier: string): Promise<boolean>;
+    clear(): Promise<void>;
+    stats(): Promise<{
         memoryEntries: number;
         diskEntries: number;
         hitRate: number;
-    };
+        backend: string;
+    }>;
 }
 export declare function getClassificationCache(options?: ClassificationCacheOptions): ClassificationCache;
 export declare function resetClassificationCache(): void;