circle-ir-ai 2.27.0 → 2.28.2

package/dist/cache/backends/r2.js

@@ -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,13 @@
  *   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 { S3Client, GetObjectCommand, PutObjectCommand, HeadObjectCommand, DeleteObjectCommand, } from '@aws-sdk/client-s3';
+import { renderObjectPath } from './layout.js';
 export class R2Backend {
     kind = 'r2';
     client;
@@ -33,7 +34,7 @@ export class R2Backend {
     prefix;
     constructor(opts) {
         this.bucket = opts.bucket;
-        this.prefix = (opts.prefix ?? 'v1').replace(/^\/+|\/+$/g, '');
+        this.prefix = (opts.prefix ?? 'v2').replace(/^\/+|\/+$/g, '');
         this.client = new S3Client({
             endpoint: opts.endpoint,
             region: opts.region ?? 'auto',
@@ -46,8 +47,7 @@ export class R2Backend {
         });
     }
     objectKey(key) {
-        const sub = key.substring(0, 2);
-        return `${this.prefix}/${sub}/${key}.json`;
+        return `${this.prefix}/${renderObjectPath(key)}`;
     }
     async get(key) {
         try {
@@ -57,12 +57,10 @@ export class R2Backend {
             }));
             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;

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

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

@@ -2,35 +2,65 @@
  * Classification Cache
  *
  * Caches LLM classification results by composite key
- * (content hash + classifier name + per-phase model fingerprint).
- * Optimized for batch classifier workloads with shorter TTL than FileCache.
+ * (schemaVer + content hash + classifier name + per-phase model fingerprint
+ * + optional coordinate hash-prefix).
  *
- * Key differences from FileCache:
- * - Composite key: SHA-256(content + '\0' + classifierName + '\0' + modelFingerprint)
- * - Shorter default TTL (24h vs 7d)
- * - Cache directory: .cognium/cache/
- * - Hit/miss tracking for observability
+ * Storage is delegated to a `CacheBackend` (cognium-ai#158). Default
+ * = `LocalFSBackend`. Selecting `LLM_CACHE_BACKEND=r2` swaps to Cloudflare
+ * R2 transparently so two runners on different machines share the same
+ * cache.
  *
- * 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.
+ * # Round 2 (2.28.0) key shape
  *
- * Model dimension (cognium-ai#151 P0 spike):
- *   When `modelFingerprint` is supplied (typically via
- *   `getPhaseModelFingerprint()` from `../llm/config.ts`) it becomes part
- *   of the cache key. This prevents a `gemma3:12b` discovery result from
- *   being silently reused when the operator switches to `gpt-4o-mini` for
- *   discovery. The fingerprint is the same identity the persistent cache
- *   (#158) uses, so call-site cache and S3 cache stay in lockstep.
+ *   sha256(
+ *     'cic:v2'           // SCHEMA_VER — bump on breaking key changes
+ *     + '\0' + namespace // 'tree' | 'verify' | 'discovery'
+ *     + '\0' + classifier
+ *     + '\0' + content
+ *     + '\0' + modelFingerprint     // per-phase, see ../llm/config.ts
+ *     + '\0' + coordinateHashPrefix // empty for non-tree, or _unowned
+ *   )
+ *
+ * Why `namespace` is in the hash:
+ *   So a tree-cache entry can never collide with a verify-cache entry
+ *   even if a future caller happens to choose the same classifier name.
+ *
+ * Why `coordinate` is in the hash (when present):
+ *   So `commons-lang3@3.12.0` and `commons-lang3@3.13.0` produce
+ *   different SHAs for the same byte-identical file (we WANT them
+ *   distinct because the surrounding rules / version-conditioned
+ *   profile could differ). The coordinate is also reflected in the
+ *   backend path layout — see `./backends/layout.ts` — so the cache
+ *   is browseable in R2 dashboard by package.
  *
- *   Backward compat: when omitted the key falls through to the prior
- *   2-component shape, so existing callers (and on-disk entries from
- *   ≤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.
+ * Model dimension (cognium-ai#151 P0 spike):
+ *   `modelFingerprint` is the per-phase identity from
+ *   `getDiscoveryModelFingerprint()` / `getVerifyModelFingerprint()` /
+ *   `getComponentModelFingerprint()` in `../llm/config.ts`. Each cache
+ *   instance uses the fingerprint scoped to its phase so swapping the
+ *   discovery model doesn't invalidate verify results and vice versa
+ *   (#158 D2).
+ */
+import type { CacheBackend, CacheNamespace } from './backend.js';
+import type { PackageCoordinate } from './coordinate.js';
+/**
+ * Wire-format version. Bump on every breaking change to the key composition
+ * OR the on-disk envelope shape. Operators rolling back to an older
+ * circle-ir-ai will see misses against newer SCHEMA_VER entries and
+ * re-populate cleanly.
  */
-import type { CacheBackend } from './backend.js';
+export declare const SCHEMA_VER = "cic:v2";
 export interface ClassificationCacheOptions {
+    /**
+     * Logical cache namespace. Determines backend path layout AND whether
+     * the cache participates in the coordinate-aware tree layout.
+     *
+     * Defaults to `'classifier'` for generic LLM classification callers
+     * (batch-classifier, trust passes) that don't care about the namespace
+     * dimension. The three SAST caches (`tree-cache.ts`, `verify-cache.ts`,
+     * `discovery-cache.ts`) always pass their own namespace explicitly.
+     */
+    namespace?: CacheNamespace;
     /** Cache directory (default: .cognium/cache/ in project root). For
      *  non-fs backends this is interpreted as a sub-prefix only. */
     cacheDir?: string;
@@ -39,20 +69,28 @@ export interface ClassificationCacheOptions {
     /** Enable/disable cache (default: true) */
     enabled?: boolean;
     /**
-     * Per-phase model identity for cache namespacing (cognium-ai#151).
-     * Typically the output of `getPhaseModelFingerprint(config)` from
-     * `../llm/config.ts`. Two scans with different discovery / verification
-     * models will produce different cache keys and not poison each other.
-     * Defaults to empty string (legacy 2-component key shape).
+     * Per-phase model identity for cache namespacing (cognium-ai#151 / #158 D2).
+     * Tree-cache passes the discovery+verify joint fingerprint; verify-cache
+     * passes the verify-only fingerprint; discovery-cache passes the
+     * discovery-only fingerprint. See `../llm/config.ts`.
      */
     modelFingerprint?: string;
     /**
      * Override the backend instance (tests). When omitted we build one
-     * via `makeBackend(cacheDir)` based on `LLM_CACHE_BACKEND` env.
+     * via `makeBackend(cacheDir, namespace)` based on `LLM_CACHE_BACKEND` env.
      */
     backend?: CacheBackend;
 }
+/**
+ * Per-get/set call extras. `coordinate` is honored only for the
+ * `tree` namespace; passing it elsewhere is a no-op so callers don't
+ * have to branch.
+ */
+export interface CacheCallOptions {
+    coordinate?: PackageCoordinate;
+}
 export declare class ClassificationCache<T = unknown> {
+    private namespace;
     private cacheDir;
     private maxAge;
     private enabled;
@@ -66,19 +104,23 @@ export declare class ClassificationCache<T = unknown> {
     getModelFingerprint(): string;
     /** Backend kind identifier (`local-fs` | `memory` | `r2`). Observability. */
     getBackendKind(): string;
-    private computeKey;
+    /** Logical namespace (`tree` | `verify` | `discovery`). Observability. */
+    getNamespace(): CacheNamespace;
+    private computeDigest;
+    private toCacheKey;
     private isValid;
-    get(content: string, classifier: string): Promise<T | null>;
-    set(content: string, classifier: string, result: T): Promise<void>;
-    has(content: string, classifier: string): Promise<boolean>;
+    get(content: string, classifier: string, opts?: CacheCallOptions): Promise<T | null>;
+    set(content: string, classifier: string, result: T, opts?: CacheCallOptions): Promise<void>;
+    has(content: string, classifier: string, opts?: CacheCallOptions): Promise<boolean>;
     clear(): Promise<void>;
     stats(): Promise<{
+        namespace: CacheNamespace;
         memoryEntries: number;
         diskEntries: number;
         hitRate: number;
         backend: string;
     }>;
 }
-export declare function getClassificationCache(options?: ClassificationCacheOptions): ClassificationCache;
+export declare function getClassificationCache<T = unknown>(options?: ClassificationCacheOptions): ClassificationCache<T>;
 export declare function resetClassificationCache(): void;
 //# sourceMappingURL=classification-cache.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"classification-cache.d.ts","sourceRoot":"","sources":["../../src/cache/classification-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,WAAW,0BAA0B;IACzC;oEACgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAUD,qBAAa,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC1C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,GAAE,0BAA+B;IAQpD,mEAAmE;IACnE,mBAAmB,IAAI,MAAM;IAI7B,6EAA6E;IAC7E,cAAc,IAAI,MAAM;IAIxB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,OAAO;IAIT,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAoC3D,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAclE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,KAAK,IAAI,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAazG;AASD,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,mBAAmB,CAMhG;AAED,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}
+{"version":3,"file":"classification-cache.d.ts","sourceRoot":"","sources":["../../src/cache/classification-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAY,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,WAAW,CAAC;AAEnC,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B;oEACgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAWD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAED,qBAAa,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC1C,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,WAAW,CAAyC;IAC5D,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,MAAM,CAAK;gBAEP,OAAO,GAAE,0BAA+B;IASpD,mEAAmE;IACnE,mBAAmB,IAAI,MAAM;IAI7B,6EAA6E;IAC7E,cAAc,IAAI,MAAM;IAIxB,0EAA0E;IAC1E,YAAY,IAAI,cAAc;IAI9B,OAAO,CAAC,aAAa;IAqBrB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,OAAO;IAKT,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAqCpF,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB3F,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAInF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,KAAK,IAAI,OAAO,CAAC;QACrB,SAAS,EAAE,cAAc,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CAcH;AASD,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAAE,OAAO,GAAE,0BAA+B,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAUpH;AAED,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/cache/classification-cache.js

@@ -2,38 +2,59 @@
  * Classification Cache
  *
  * Caches LLM classification results by composite key
- * (content hash + classifier name + per-phase model fingerprint).
- * Optimized for batch classifier workloads with shorter TTL than FileCache.
+ * (schemaVer + content hash + classifier name + per-phase model fingerprint
+ * + optional coordinate hash-prefix).
  *
- * Key differences from FileCache:
- * - Composite key: SHA-256(content + '\0' + classifierName + '\0' + modelFingerprint)
- * - Shorter default TTL (24h vs 7d)
- * - Cache directory: .cognium/cache/
- * - Hit/miss tracking for observability
+ * Storage is delegated to a `CacheBackend` (cognium-ai#158). Default
+ * = `LocalFSBackend`. Selecting `LLM_CACHE_BACKEND=r2` swaps to Cloudflare
+ * R2 transparently so two runners on different machines share the same
+ * cache.
  *
- * 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.
+ * # Round 2 (2.28.0) key shape
  *
- * Model dimension (cognium-ai#151 P0 spike):
- *   When `modelFingerprint` is supplied (typically via
- *   `getPhaseModelFingerprint()` from `../llm/config.ts`) it becomes part
- *   of the cache key. This prevents a `gemma3:12b` discovery result from
- *   being silently reused when the operator switches to `gpt-4o-mini` for
- *   discovery. The fingerprint is the same identity the persistent cache
- *   (#158) uses, so call-site cache and S3 cache stay in lockstep.
+ *   sha256(
+ *     'cic:v2'           // SCHEMA_VER — bump on breaking key changes
+ *     + '\0' + namespace // 'tree' | 'verify' | 'discovery'
+ *     + '\0' + classifier
+ *     + '\0' + content
+ *     + '\0' + modelFingerprint     // per-phase, see ../llm/config.ts
+ *     + '\0' + coordinateHashPrefix // empty for non-tree, or _unowned
+ *   )
+ *
+ * Why `namespace` is in the hash:
+ *   So a tree-cache entry can never collide with a verify-cache entry
+ *   even if a future caller happens to choose the same classifier name.
+ *
+ * Why `coordinate` is in the hash (when present):
+ *   So `commons-lang3@3.12.0` and `commons-lang3@3.13.0` produce
+ *   different SHAs for the same byte-identical file (we WANT them
+ *   distinct because the surrounding rules / version-conditioned
+ *   profile could differ). The coordinate is also reflected in the
+ *   backend path layout — see `./backends/layout.ts` — so the cache
+ *   is browseable in R2 dashboard by package.
  *
- *   Backward compat: when omitted the key falls through to the prior
- *   2-component shape, so existing callers (and on-disk entries from
- *   ≤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.
+ * Model dimension (cognium-ai#151 P0 spike):
+ *   `modelFingerprint` is the per-phase identity from
+ *   `getDiscoveryModelFingerprint()` / `getVerifyModelFingerprint()` /
+ *   `getComponentModelFingerprint()` in `../llm/config.ts`. Each cache
+ *   instance uses the fingerprint scoped to its phase so swapping the
+ *   discovery model doesn't invalidate verify results and vice versa
+ *   (#158 D2).
  */
 import * as path from 'path';
 import * as crypto from 'crypto';
 import { makeBackend } from './backends/index.js';
+import { coordinateSegments } from './coordinate.js';
+/**
+ * Wire-format version. Bump on every breaking change to the key composition
+ * OR the on-disk envelope shape. Operators rolling back to an older
+ * circle-ir-ai will see misses against newer SCHEMA_VER entries and
+ * re-populate cleanly.
+ */
+export const SCHEMA_VER = 'cic:v2';
 const DEFAULT_MAX_AGE = 24 * 60 * 60 * 1000; // 24 hours
 export class ClassificationCache {
+    namespace;
     cacheDir;
     maxAge;
     enabled;
@@ -43,11 +64,12 @@ export class ClassificationCache {
     hits = 0;
     misses = 0;
     constructor(options = {}) {
+        this.namespace = options.namespace ?? 'classifier';
         this.cacheDir = options.cacheDir || path.join(process.cwd(), '.cognium', 'cache');
         this.maxAge = options.maxAge ?? DEFAULT_MAX_AGE;
         this.enabled = options.enabled ?? true;
         this.modelFingerprint = options.modelFingerprint ?? '';
-        this.backend = options.backend ?? makeBackend(this.cacheDir);
+        this.backend = options.backend ?? makeBackend(this.cacheDir, this.namespace);
     }
     /** Per-phase model identity used in cache key (cognium-ai#151). */
     getModelFingerprint() {
@@ -57,43 +79,62 @@ export class ClassificationCache {
     getBackendKind() {
         return this.backend.kind;
     }
-    computeKey(content, classifier) {
-        // 3-component key when fingerprint present (cognium-ai#151). When
-        // empty falls through to the prior 2-component shape via the trailing
-        // `'\0' + ''` collapse — bit-identical to ≤2.21.0 only when no
-        // fingerprint is supplied at all, which is the back-compat path.
-        const parts = this.modelFingerprint
-            ? content + '\0' + classifier + '\0' + this.modelFingerprint
-            : content + '\0' + classifier;
+    /** Logical namespace (`tree` | `verify` | `discovery`). Observability. */
+    getNamespace() {
+        return this.namespace;
+    }
+    computeDigest(content, classifier, coordinate) {
+        // Coordinate hash-prefix only applies to the `tree` namespace.
+        // Including it in the digest (not just the path) is what guarantees
+        // a fileSHA collision across packages still produces distinct keys.
+        const coordPart = (this.namespace === 'tree' && coordinate)
+            ? coordinateSegments(coordinate).hashPrefix
+            : '';
+        const parts = SCHEMA_VER
+            + '\0' + this.namespace
+            + '\0' + classifier
+            + '\0' + content
+            + '\0' + this.modelFingerprint
+            + '\0' + coordPart;
         return crypto.createHash('sha256').update(parts).digest('hex');
     }
+    toCacheKey(digest, coordinate) {
+        const key = { namespace: this.namespace, digest };
+        if (this.namespace === 'tree' && coordinate) {
+            key.coordinate = coordinate;
+        }
+        return key;
+    }
     isValid(entry) {
+        if (entry.schemaVer !== SCHEMA_VER)
+            return false;
         return (Date.now() - entry.timestamp) <= this.maxAge;
     }
-    async get(content, classifier) {
+    async get(content, classifier, opts) {
         if (!this.enabled)
             return null;
-        const key = this.computeKey(content, classifier);
+        const digest = this.computeDigest(content, classifier, opts?.coordinate);
+        const cacheKey = this.toCacheKey(digest, opts?.coordinate);
         // Memory cache (process-local hot path)
-        const memEntry = this.memoryCache.get(key);
+        const memEntry = this.memoryCache.get(digest);
         if (memEntry && this.isValid(memEntry)) {
             this.hits++;
             return memEntry.result;
         }
         // Backend (disk / R2 / etc.)
         try {
-            const raw = await this.backend.get(key);
+            const raw = await this.backend.get(cacheKey);
             if (raw !== null) {
                 const entry = JSON.parse(raw);
                 if (this.isValid(entry)) {
-                    this.memoryCache.set(key, entry);
+                    this.memoryCache.set(digest, entry);
                     this.hits++;
                     return entry.result;
                 }
-                // Stale — best-effort drop. We don't await the deletion to
-                // keep the read path fast.
+                // Stale OR schemaVer-mismatch — drop. We don't await the deletion
+                // to keep the read path fast.
                 if (this.backend.delete) {
-                    void this.backend.delete(key);
+                    void this.backend.delete(cacheKey);
                 }
             }
         }
@@ -103,21 +144,27 @@ export class ClassificationCache {
         this.misses++;
         return null;
     }
-    async set(content, classifier, result) {
+    async set(content, classifier, result, opts) {
         if (!this.enabled)
             return;
-        const key = this.computeKey(content, classifier);
-        const entry = { key, timestamp: Date.now(), result };
-        this.memoryCache.set(key, entry);
+        const digest = this.computeDigest(content, classifier, opts?.coordinate);
+        const cacheKey = this.toCacheKey(digest, opts?.coordinate);
+        const entry = {
+            schemaVer: SCHEMA_VER,
+            key: digest,
+            timestamp: Date.now(),
+            result,
+        };
+        this.memoryCache.set(digest, entry);
         try {
-            await this.backend.set(key, JSON.stringify(entry));
+            await this.backend.set(cacheKey, JSON.stringify(entry));
         }
         catch {
             // Cache write is best-effort; never fail the caller.
         }
     }
-    async has(content, classifier) {
-        return (await this.get(content, classifier)) !== null;
+    async has(content, classifier, opts) {
+        return (await this.get(content, classifier, opts)) !== null;
     }
     async clear() {
         this.memoryCache.clear();
@@ -140,6 +187,7 @@ export class ClassificationCache {
         }
         const total = this.hits + this.misses;
         return {
+            namespace: this.namespace,
             memoryEntries: this.memoryCache.size,
             diskEntries,
             hitRate: total > 0 ? this.hits / total : 0,
@@ -147,20 +195,24 @@ export class ClassificationCache {
         };
     }
 }
-// Singleton — keyed on cacheDir + modelFingerprint so two scans with
-// different per-phase models in the same process get distinct caches
-// (cognium-ai#151). Without the fingerprint dimension, switching
-// `LLM_DISCOVERY_MODEL` between scans would silently reuse the first
-// scan's classifier results.
-let classificationCache = null;
-export function getClassificationCache(options) {
-    const wantFingerprint = options?.modelFingerprint ?? '';
-    if (!classificationCache || classificationCache.getModelFingerprint() !== wantFingerprint) {
-        classificationCache = new ClassificationCache(options);
+/**
+ * Singleton table — keyed on (namespace, modelFingerprint) so two scans
+ * with different per-phase models in the same process get distinct
+ * caches (cognium-ai#151).
+ */
+const singletons = new Map();
+export function getClassificationCache(options = {}) {
+    const fp = options.modelFingerprint ?? '';
+    const namespace = options.namespace ?? 'classifier';
+    const slot = `${namespace}\0${fp}`;
+    let existing = singletons.get(slot);
+    if (!existing) {
+        existing = new ClassificationCache(options);
+        singletons.set(slot, existing);
     }
-    return classificationCache;
+    return existing;
 }
 export function resetClassificationCache() {
-    classificationCache = null;
+    singletons.clear();
 }
 //# sourceMappingURL=classification-cache.js.map

package/dist/cache/classification-cache.js.map

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

package/dist/cache/coordinate.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Package coordinate detection for cache path layout.
+ *
+ * The tree-cache backend (R2 / local-fs) uses the coordinate to build a
+ * package-aware key layout:
+ *
+ *   tree/<ecosystem>/<name>@<version>/<4hex>/<sha>.json   (published coords)
+ *   tree/_local/<name>@<version>/<4hex>/<sha>.json        (repo-root manifest)
+ *   tree/_unowned/<4hex>/<sha>.json                       (no coordinate)
+ *
+ * Coordinate is resolved ONCE per scan from the repo root. We deliberately
+ * keep the extractor minimal (only manifest files we can parse with zero
+ * deps) so it can be folded into hot paths without measurable overhead.
+ *
+ * What's intentionally *not* in scope here:
+ * - per-file coordinate from `node_modules/<pkg>/...` paths (deferred until
+ *   we actually scan transitive deps)
+ * - lockfile-derived coordinates
+ * - Maven `<artifactId>` resolution from a multi-module reactor
+ *
+ * For the first-party github sweep use case, every file in a repo shares
+ * the same coordinate (or falls through to `_unowned`), which is exactly
+ * what we want for cross-runner cache sharing.
+ */
+export type Ecosystem = 'npm' | 'maven' | 'pypi' | 'cargo' | 'go' | '_local' | '_unowned';
+export interface PackageCoordinate {
+    ecosystem: Ecosystem;
+    /** Package name in its ecosystem's canonical form (lower-case, normalized). */
+    name: string;
+    /** Resolved version string, or `'HEAD'` for `_local`. */
+    version: string;
+}
+/**
+ * The sentinel coordinate emitted when the repo has no detectable manifest.
+ *
+ * Tree-cache content still gets cached, just under `_unowned/<4hex>/<sha>`.
+ * Re-using the singleton means the path layout is constant for un-coord'd
+ * scans and avoids per-file object allocation.
+ */
+export declare const UNOWNED: PackageCoordinate;
+/**
+ * Render the coordinate as a stable path prefix and a stable hash prefix.
+ *
+ * `pathSegment` is what the backend uses to build the R2 / local-fs key.
+ * `hashPrefix` is what cache-key composers fold into the content hash so
+ * the SHA itself encodes the coordinate (no collision across packages).
+ */
+export declare function coordinateSegments(c: PackageCoordinate): {
+    pathSegment: string;
+    hashPrefix: string;
+};
+/**
+ * Detect a package coordinate from the repo root manifest files.
+ *
+ * Synchronous because it runs once per scan at scanner entry and the
+ * disk reads are tiny (`package.json` / `pom.xml`).
+ */
+export declare function detectCoordinate(repoRoot: string): PackageCoordinate;
+//# sourceMappingURL=coordinate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coordinate.d.ts","sourceRoot":"","sources":["../../src/cache/coordinate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE1F,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,SAAS,CAAC;IACrB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,iBAIpB,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,iBAAiB,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CASpG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAwFpE"}