circle-ir-ai 2.27.0 → 2.28.2

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

@@ -1,32 +1,44 @@
 /**
- * Cache backend factory (cognium-ai#158 Acceptance #4).
+ * Cache backend factory (cognium-ai#158).
  *
- * Selects a `CacheBackend` per cache-dir based on `LLM_CACHE_BACKEND`:
- *   `local`  (default) — `LocalFSBackend(cacheDir)`
+ * Selects a `CacheBackend` per namespace based on `LLM_CACHE_BACKEND`:
+ *   `local`  (default) — `LocalFSBackend(<cacheDir>/<namespace>)`
  *   `memory`            — `MemoryBackend()`
- *   `r2`                — `R2Backend({R2_ENDPOINT, R2_BUCKET, …})`
+ *   `r2`                — `R2Backend({prefix: <R2_PREFIX>/<namespace>, …})`
  *
- * 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/`
+ * Each `ClassificationCache` (tree / verify / discovery) constructs ONE
+ * backend, scoped to its own namespace via the `namespace` arg. Inside
+ * the backend, the structured `CacheKey` is rendered to a path via
+ * `renderObjectPath()`:
  *
- * (Phase 2 #158 layout — `<lang>/_tree/<pkg>@<ver>/…` — lands as a
- * separate refactor on top of this.)
+ *   tree+coord   → `<eco>/<name>@<ver>/<4hex>/<sha>.json`
+ *   tree+nocoord → `_unowned/<2hex>/<sha>.json`
+ *   verify       → `<2hex>/<sha>.json`
+ *   discovery    → `<2hex>/<sha>.json`
+ *
+ * `R2_PREFIX` default bumped `v1` → `v2` for the Round 2 layout. Operators
+ * who want the old keys back can pin `R2_PREFIX=v1` (the 2.27.0 layout is
+ * read-only at that prefix; new writes use `v2`).
  */
-import type { CacheBackend } from '../backend.js';
+import type { CacheBackend, CacheNamespace } 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.
+ * Build the backend for a given (cacheDir, namespace).
+ *
+ * `cacheDir` is the local-fs root the caller would have used pre-layout-
+ * reshape. For local-fs, the backend writes to `<cacheDir>` directly (the
+ * caller is expected to already pass the namespace-scoped subdir; this
+ * preserves the 2.27.0 ≤ on-disk shape for operators who care).
+ *
+ * For R2, the backend prefix is `<R2_PREFIX>/<namespace>` so all three
+ * namespaces share one bucket but live in separate keyspaces.
+ *
+ * `namespace` is required so R2 can build the namespace prefix correctly
+ * even when the caller's `cacheDir` basename is something custom.
  */
-export declare function makeBackend(cacheDir: string): CacheBackend;
+export declare function makeBackend(cacheDir: string, namespace: CacheNamespace): CacheBackend;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAClE,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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,YAAY,CAoCrF"}

package/dist/cache/backends/index.js

@@ -1,21 +1,24 @@
 /**
- * Cache backend factory (cognium-ai#158 Acceptance #4).
+ * Cache backend factory (cognium-ai#158).
  *
- * Selects a `CacheBackend` per cache-dir based on `LLM_CACHE_BACKEND`:
- *   `local`  (default) — `LocalFSBackend(cacheDir)`
+ * Selects a `CacheBackend` per namespace based on `LLM_CACHE_BACKEND`:
+ *   `local`  (default) — `LocalFSBackend(<cacheDir>/<namespace>)`
  *   `memory`            — `MemoryBackend()`
- *   `r2`                — `R2Backend({R2_ENDPOINT, R2_BUCKET, …})`
+ *   `r2`                — `R2Backend({prefix: <R2_PREFIX>/<namespace>, …})`
  *
- * 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/`
+ * Each `ClassificationCache` (tree / verify / discovery) constructs ONE
+ * backend, scoped to its own namespace via the `namespace` arg. Inside
+ * the backend, the structured `CacheKey` is rendered to a path via
+ * `renderObjectPath()`:
  *
- * (Phase 2 #158 layout — `<lang>/_tree/<pkg>@<ver>/…` — lands as a
- * separate refactor on top of this.)
+ *   tree+coord   → `<eco>/<name>@<ver>/<4hex>/<sha>.json`
+ *   tree+nocoord → `_unowned/<2hex>/<sha>.json`
+ *   verify       → `<2hex>/<sha>.json`
+ *   discovery    → `<2hex>/<sha>.json`
+ *
+ * `R2_PREFIX` default bumped `v1` → `v2` for the Round 2 layout. Operators
+ * who want the old keys back can pin `R2_PREFIX=v1` (the 2.27.0 layout is
+ * read-only at that prefix; new writes use `v2`).
  */
 import * as path from 'path';
 import { LocalFSBackend } from './local-fs.js';
@@ -31,11 +34,20 @@ export function getBackendKind() {
     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.
+ * Build the backend for a given (cacheDir, namespace).
+ *
+ * `cacheDir` is the local-fs root the caller would have used pre-layout-
+ * reshape. For local-fs, the backend writes to `<cacheDir>` directly (the
+ * caller is expected to already pass the namespace-scoped subdir; this
+ * preserves the 2.27.0 ≤ on-disk shape for operators who care).
+ *
+ * For R2, the backend prefix is `<R2_PREFIX>/<namespace>` so all three
+ * namespaces share one bucket but live in separate keyspaces.
+ *
+ * `namespace` is required so R2 can build the namespace prefix correctly
+ * even when the caller's `cacheDir` basename is something custom.
  */
-export function makeBackend(cacheDir) {
+export function makeBackend(cacheDir, namespace) {
     const kind = getBackendKind();
     if (kind === 'memory')
         return new MemoryBackend();
@@ -45,32 +57,28 @@ export function makeBackend(cacheDir) {
         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.
+            // Misconfigured; degrade to local instead of crashing.
             // 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);
+        const userPrefix = (process.env.R2_PREFIX ?? 'v2').replace(/^\/+|\/+$/g, '');
         return new R2Backend({
             endpoint,
             bucket,
             accessKeyId,
             secretAccessKey,
             region: process.env.R2_REGION ?? 'auto',
-            prefix: `${userPrefix}/${sub}`,
+            prefix: `${userPrefix}/${namespace}`,
         });
     }
-    return new LocalFSBackend({ cacheDir });
-}
-function cacheDirToSubPrefix(cacheDir) {
+    // Local-fs: scope to <cacheDir>/<namespace> unless cacheDir already
+    // ends in that namespace (back-compat with callers passing the
+    // pre-existing per-namespace dir).
     const base = path.basename(cacheDir).toLowerCase();
-    if (base === 'tree' || base === 'verify' || base === 'discovery')
-        return base;
-    return 'misc';
+    const scoped = base === namespace ? cacheDir : path.join(cacheDir, namespace);
+    return new LocalFSBackend({ cacheDir: scoped });
 }
 //# sourceMappingURL=index.js.map

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

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cache/backends/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;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;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,SAAyB;IACrE,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,uDAAuD;YACvD,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,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,SAAS,EAAE;SACrC,CAAC,CAAC;IACL,CAAC;IAED,oEAAoE;IACpE,+DAA+D;IAC/D,mCAAmC;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IACnD,MAAM,MAAM,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC9E,OAAO,IAAI,cAAc,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;AAClD,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * Shared key-to-path renderer used by every backend so R2 / local-fs /
+ * memory all agree on the on-disk layout for a given `CacheKey`.
+ *
+ * Renders the *namespace-relative* suffix. The factory roots each
+ * backend at a `<prefix>/<namespace>/` path, so the resulting full key
+ * is:
+ *
+ *   tree      → `<root>/tree/<eco>/<name>@<ver>/<4hex>/<sha>.json`  (coord)
+ *             → `<root>/tree/_unowned/<4hex>/<sha>.json`            (fallback)
+ *   verify    → `<root>/verify/<4hex>/<sha>.json`
+ *   discovery → `<root>/discovery/<4hex>/<sha>.json`
+ *
+ * All four namespaces use a 4-hex (65 536) shard prefix. Rationale:
+ *
+ * - Uniform shard depth keeps the renderer / backend code symmetric;
+ *   no namespace-specific branching past the coordinate decision.
+ * - 4-hex sizes each shard to a few hundred entries even at the worst
+ *   case we've observed (coord'd `tree` for large packages like the
+ *   aws-sdk-java multi-module reactor or `_unowned` shared across an
+ *   entire CI fleet's anonymous scans).
+ * - The depth cost is negligible: R2 has no directory concept, and
+ *   the local-fs backend just creates one extra cheap directory per
+ *   shard the first time it's touched.
+ *
+ * Always returns forward-slash-separated segments; the local-fs
+ * backend translates to `path.sep` at the filesystem boundary.
+ */
+import type { CacheKey } from '../backend.js';
+export declare function renderObjectPath(key: CacheKey): string;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAM9C,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,CActD"}

package/dist/cache/backends/layout.js

@@ -0,0 +1,46 @@
+/**
+ * Shared key-to-path renderer used by every backend so R2 / local-fs /
+ * memory all agree on the on-disk layout for a given `CacheKey`.
+ *
+ * Renders the *namespace-relative* suffix. The factory roots each
+ * backend at a `<prefix>/<namespace>/` path, so the resulting full key
+ * is:
+ *
+ *   tree      → `<root>/tree/<eco>/<name>@<ver>/<4hex>/<sha>.json`  (coord)
+ *             → `<root>/tree/_unowned/<4hex>/<sha>.json`            (fallback)
+ *   verify    → `<root>/verify/<4hex>/<sha>.json`
+ *   discovery → `<root>/discovery/<4hex>/<sha>.json`
+ *
+ * All four namespaces use a 4-hex (65 536) shard prefix. Rationale:
+ *
+ * - Uniform shard depth keeps the renderer / backend code symmetric;
+ *   no namespace-specific branching past the coordinate decision.
+ * - 4-hex sizes each shard to a few hundred entries even at the worst
+ *   case we've observed (coord'd `tree` for large packages like the
+ *   aws-sdk-java multi-module reactor or `_unowned` shared across an
+ *   entire CI fleet's anonymous scans).
+ * - The depth cost is negligible: R2 has no directory concept, and
+ *   the local-fs backend just creates one extra cheap directory per
+ *   shard the first time it's touched.
+ *
+ * Always returns forward-slash-separated segments; the local-fs
+ * backend translates to `path.sep` at the filesystem boundary.
+ */
+import { coordinateSegments } from '../coordinate.js';
+/** Uniform shard depth across all namespaces. See file header for rationale. */
+const SHARD_HEX_LEN = 4;
+export function renderObjectPath(key) {
+    const sha = key.digest;
+    const shard = sha.substring(0, SHARD_HEX_LEN);
+    if (key.namespace === 'tree') {
+        const coord = key.coordinate;
+        if (coord && coord.ecosystem !== '_unowned') {
+            const { pathSegment } = coordinateSegments(coord);
+            return `${pathSegment}/${shard}/${sha}.json`;
+        }
+        return `_unowned/${shard}/${sha}.json`;
+    }
+    // verify / discovery / classifier — flat with same 4-hex shard.
+    return `${shard}/${sha}.json`;
+}
+//# sourceMappingURL=layout.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.js","sourceRoot":"","sources":["../../../src/cache/backends/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEtD,gFAAgF;AAChF,MAAM,aAAa,GAAG,CAAC,CAAC;AAExB,MAAM,UAAU,gBAAgB,CAAC,GAAa;IAC5C,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;IACvB,MAAM,KAAK,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;IAC9C,IAAI,GAAG,CAAC,SAAS,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;QAC7B,IAAI,KAAK,IAAI,KAAK,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;YAC5C,MAAM,EAAE,WAAW,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;YAClD,OAAO,GAAG,WAAW,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC;QAC/C,CAAC;QACD,OAAO,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC;IACzC,CAAC;IAED,gEAAgE;IAChE,OAAO,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC;AAChC,CAAC"}

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

@@ -1,18 +1,21 @@
 /**
- * Local filesystem cache backend (cognium-ai#158 Acceptance #4).
+ * Local filesystem cache backend (cognium-ai#158).
  *
- * Preserves ≤2.26.0 on-disk shape:
- *   <cacheDir>/<key[0:2]>/<key>.json
+ * Round 2 (2.28.0) layout (translated to platform path-sep):
+ *
+ *   <cacheDir>/tree/<eco>/<name>@<ver>/<4hex>/<sha>.json   (coord)
+ *   <cacheDir>/tree/_unowned/<2hex>/<sha>.json             (fallback)
+ *   <cacheDir>/verify/<2hex>/<sha>.json
+ *   <cacheDir>/discovery/<2hex>/<sha>.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`).
+ * processes don't corrupt each other's entries.
  *
  * Read/write errors are swallowed and surfaced as cache misses.
  */
-import type { CacheBackend } from '../backend.js';
+import type { CacheBackend, CacheKey } from '../backend.js';
 export interface LocalFSBackendOptions {
-    /** Root directory under which `<key[0:2]>/<key>.json` lives. */
+    /** Root directory under which the `<namespace>/.../<sha>.json` tree lives. */
     cacheDir: string;
 }
 export declare class LocalFSBackend implements CacheBackend {
@@ -21,10 +24,10 @@ export declare class LocalFSBackend implements CacheBackend {
     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>;
+    get(key: CacheKey): Promise<string | null>;
+    set(key: CacheKey, value: string): Promise<void>;
+    has(key: CacheKey): Promise<boolean>;
+    delete(key: CacheKey): Promise<void>;
     count(): Promise<number>;
     clear(): Promise<void>;
 }

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

@@ -1 +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"}
+{"version":3,"file":"local-fs.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/local-fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG5D,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,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;IAMX,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAU1C,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAehD,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IASpC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAsBxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ7B"}

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

@@ -1,17 +1,21 @@
 /**
- * Local filesystem cache backend (cognium-ai#158 Acceptance #4).
+ * Local filesystem cache backend (cognium-ai#158).
  *
- * Preserves ≤2.26.0 on-disk shape:
- *   <cacheDir>/<key[0:2]>/<key>.json
+ * Round 2 (2.28.0) layout (translated to platform path-sep):
+ *
+ *   <cacheDir>/tree/<eco>/<name>@<ver>/<4hex>/<sha>.json   (coord)
+ *   <cacheDir>/tree/_unowned/<2hex>/<sha>.json             (fallback)
+ *   <cacheDir>/verify/<2hex>/<sha>.json
+ *   <cacheDir>/discovery/<2hex>/<sha>.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`).
+ * processes don't corrupt each other's entries.
  *
  * Read/write errors are swallowed and surfaced as cache misses.
  */
 import * as fs from 'fs';
 import * as path from 'path';
+import { renderObjectPath } from './layout.js';
 export class LocalFSBackend {
     kind = 'local-fs';
     cacheDir;
@@ -25,8 +29,9 @@ export class LocalFSBackend {
         }
     }
     cachePath(key) {
-        const subdir = key.substring(0, 2);
-        return path.join(this.cacheDir, subdir, `${key}.json`);
+        // layout returns forward-slash segments; translate for windows etc.
+        const rel = renderObjectPath(key).split('/').join(path.sep);
+        return path.join(this.cacheDir, rel);
     }
     async get(key) {
         const p = this.cachePath(key);
@@ -71,21 +76,28 @@ export class LocalFSBackend {
         }
     }
     async count() {
+        // Walk every namespace dir and count regular files. Best-effort —
+        // used by stats() so we don't sweat the cost.
         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 */ }
+        const walk = (dir) => {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
             }
-        }
-        catch { /* ignore */ }
+            catch {
+                return;
+            }
+            for (const ent of entries) {
+                const p = path.join(dir, ent.name);
+                if (ent.isDirectory())
+                    walk(p);
+                else if (ent.isFile() && ent.name.endsWith('.json'))
+                    n++;
+            }
+        };
+        walk(this.cacheDir);
         return n;
     }
     async clear() {

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

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

@@ -1,18 +1,23 @@
 /**
- * In-memory cache backend (cognium-ai#158 Acceptance #4).
+ * In-memory cache backend (cognium-ai#158).
  *
  * Map-backed; used by unit tests to avoid filesystem coupling.
  * Not intended for production — no eviction, no persistence,
  * grows unbounded.
+ *
+ * The internal Map is keyed by the same path string the persistent
+ * backends would render, so memory-backed test fixtures behave
+ * identically to local-fs / R2 wrt layout invariants.
  */
-import type { CacheBackend } from '../backend.js';
+import type { CacheBackend, CacheKey } 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>;
+    private k;
+    get(key: CacheKey): Promise<string | null>;
+    set(key: CacheKey, value: string): Promise<void>;
+    has(key: CacheKey): Promise<boolean>;
+    delete(key: CacheKey): Promise<void>;
     count(): Promise<number>;
     clear(): Promise<void>;
 }

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

@@ -1 +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"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG5D,qBAAa,aAAc,YAAW,YAAY;IAChD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,KAAK,CAAkC;IAE/C,OAAO,CAAC,CAAC;IAIH,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI1C,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAIxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/cache/backends/memory.js

@@ -1,24 +1,32 @@
 /**
- * In-memory cache backend (cognium-ai#158 Acceptance #4).
+ * In-memory cache backend (cognium-ai#158).
  *
  * Map-backed; used by unit tests to avoid filesystem coupling.
  * Not intended for production — no eviction, no persistence,
  * grows unbounded.
+ *
+ * The internal Map is keyed by the same path string the persistent
+ * backends would render, so memory-backed test fixtures behave
+ * identically to local-fs / R2 wrt layout invariants.
  */
+import { renderObjectPath } from './layout.js';
 export class MemoryBackend {
     kind = 'memory';
     store = new Map();
+    k(key) {
+        return renderObjectPath(key);
+    }
     async get(key) {
-        return this.store.get(key) ?? null;
+        return this.store.get(this.k(key)) ?? null;
     }
     async set(key, value) {
-        this.store.set(key, value);
+        this.store.set(this.k(key), value);
     }
     async has(key) {
-        return this.store.has(key);
+        return this.store.has(this.k(key));
     }
     async delete(key) {
-        this.store.delete(key);
+        this.store.delete(this.k(key));
     }
     async count() {
         return this.store.size;

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

@@ -1 +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"}
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/cache/backends/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,QAAQ,CAAC;IACjB,KAAK,GAAwB,IAAI,GAAG,EAAE,CAAC;IAEvC,CAAC,CAAC,GAAa;QACrB,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAa;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAa,EAAE,KAAa;QACpC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAa;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAa;QACxB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACjC,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

@@ -1,15 +1,17 @@
 /**
  * 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.
+ * Round 2 (2.28.0) layout:
  *
- * 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.
+ *   <prefix>/tree/<eco>/<name>@<ver>/<4hex>/<sha>.json   (coord present)
+ *   <prefix>/tree/_unowned/<2hex>/<sha>.json             (no coord)
+ *   <prefix>/verify/<2hex>/<sha>.json                    (flat)
+ *   <prefix>/discovery/<2hex>/<sha>.json                 (flat)
+ *
+ * The coordinate is only consulted for tree-namespace keys; verify and
+ * discovery stay flat because their content already encodes the model
+ * fingerprint + per-batch fingerprint, so a coordinate prefix would
+ * just bloat the path.
  *
  * Configuration (env vars):
  *   LLM_CACHE_BACKEND=r2
@@ -18,14 +20,12 @@
  *   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)
+ *   R2_PREFIX=v2                    (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';
+import type { CacheBackend, CacheKey } from '../backend.js';
 export interface R2BackendOptions {
     endpoint: string;
     bucket: string;
@@ -33,7 +33,7 @@ export interface R2BackendOptions {
     secretAccessKey: string;
     /** R2 ignores region; default `auto`. */
     region?: string;
-    /** Object-key prefix (default `v1`). Used to roll layout versions. */
+    /** Object-key prefix (default `v2`). Used to roll layout versions. */
     prefix?: string;
 }
 export declare class R2Backend implements CacheBackend {
@@ -43,9 +43,9 @@ export declare class R2Backend implements CacheBackend {
     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>;
+    get(key: CacheKey): Promise<string | null>;
+    set(key: CacheKey, value: string): Promise<void>;
+    has(key: CacheKey): Promise<boolean>;
+    delete(key: CacheKey): Promise<void>;
 }
 //# sourceMappingURL=r2.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../../src/cache/backends/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAG5D,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;IAIX,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgB1C,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAahD,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAYpC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAU3C"}