@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/semantic/credentials.js

@@ -0,0 +1,134 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSemanticKey = resolveSemanticKey;
+exports.storeSemanticKey = storeSemanticKey;
+exports.removeSemanticKey = removeSemanticKey;
+// @implements A-SPEC-477
+/**
+ * The cloud tier's credential: WHERE the consent lives, and in what order it is looked up.
+ *
+ * Consent model: the key IS the opt-in for egress, so only a human may mint it. The gate blocks
+ * an agent assigning the env names (self-granted egress, the HOLMES_ROLE class); this module owns
+ * the storage the human's CLI act writes to. A project-tree file is NEVER a source — a tree file
+ * is a commit-accident surface and readable by every in-session tool, which is exactly what the
+ * owner's ".env 는 임시 조치" call-out named.
+ *
+ * Resolution chain, the order being the contract:
+ *   1. HOLMES_SEMANTIC_API_KEY  — dedicated name, CI/headless.
+ *   2. GEMINI_API_KEY           — ecosystem-compatible name.
+ *   3. macOS keychain           — `security` via injected exec (absent elsewhere; win32 is a
+ *                                 recorded Windows-agent follow-up).
+ *   4. ~/.holmes/credentials.json — 0600 under 0700, the everywhere-fallback.
+ *
+ * The VALUE never appears in argv (ps/history surfaces), logs, reports, or error messages.
+ * Keychain writes feed the secret over STDIN (`security -i`) for the same reason.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const node_child_process_1 = require("node:child_process");
+const SERVICE = 'holmes-kit';
+const ACCOUNT = 'semantic';
+const defaultExec = (cmd, args, stdin) => (0, node_child_process_1.execFileSync)(cmd, args, { encoding: 'utf8', input: stdin, stdio: ['pipe', 'pipe', 'pipe'] });
+const credFile = (home) => path.join(home, '.holmes', 'credentials.json');
+const nonBlank = (v) => typeof v === 'string' && v.trim() !== '' ? v.trim() : null;
+function resolveSemanticKey(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? os.homedir();
+    const platform = opts.platform ?? process.platform;
+    const exec = opts.exec ?? defaultExec;
+    const dedicated = nonBlank(env.HOLMES_SEMANTIC_API_KEY);
+    if (dedicated !== null)
+        return { key: dedicated, source: 'env' };
+    // GOOGLE_API_KEY is Google's own SDK-compatible spelling; both count as the same consent.
+    const compat = nonBlank(env.GEMINI_API_KEY) ?? nonBlank(env.GOOGLE_API_KEY);
+    if (compat !== null)
+        return { key: compat, source: 'env-compat' };
+    if (platform === 'darwin') {
+        try {
+            const out = nonBlank(exec('security', ['find-generic-password', '-s', SERVICE, '-a', ACCOUNT, '-w']));
+            if (out !== null)
+                return { key: out, source: 'keychain' };
+        }
+        catch { /* no keychain entry, or no keychain — the chain continues */ }
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(credFile(home), 'utf8'));
+        const k = nonBlank(parsed.semantic?.key);
+        if (k !== null)
+            return { key: k, source: 'file' };
+    }
+    catch { /* absent or corrupted — a broken store must not take the tier down */ }
+    return null;
+}
+/** Store via the human's CLI act. Returns where it landed. */
+function storeSemanticKey(key, opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const platform = opts.platform ?? process.platform;
+    const exec = opts.exec ?? defaultExec;
+    if (platform === 'darwin') {
+        try {
+            // `security -i` reads commands from stdin, so the secret never rides argv where ps and
+            // shell history could see it. -U updates an existing entry in place.
+            exec('security', ['-i'], `add-generic-password -U -s ${SERVICE} -a ${ACCOUNT} -w "${key.replace(/"/g, '\\"')}"\n`);
+            return 'keychain';
+        }
+        catch { /* fall through to the file */ }
+    }
+    const file = credFile(home);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    fs.chmodSync(path.dirname(file), 0o700);
+    const tmp = file + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify({ semantic: { provider: 'gemini', key } }), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    fs.chmodSync(file, 0o600);
+    return 'file';
+}
+function removeSemanticKey(opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const platform = opts.platform ?? process.platform;
+    const exec = opts.exec ?? defaultExec;
+    if (platform === 'darwin') {
+        try {
+            exec('security', ['delete-generic-password', '-s', SERVICE, '-a', ACCOUNT]);
+        }
+        catch { /* absent is fine */ }
+    }
+    try {
+        fs.rmSync(credFile(home));
+    }
+    catch { /* absent is fine */ }
+}

package/dist/holmes/semantic/embedder.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The tier adapters — the productized form of exactly what the measurement scripts proved:
+ *
+ *   local  = @xenova/transformers with the FROZEN pooling table (bge-m3 → CLS; mean-pooling it
+ *            was the S-491 instrument accident), quantized, lazy pipeline.
+ *   cloud  = gemini batchEmbedContents with the MEASURED pacing (≤25 per batch, backoff on 429 —
+ *            the free-tier and TPM ceilings were both hit live). The key never appears in any
+ *            log or error string.
+ *
+ * Both flow through the VectorCache (content hash + model tag), which is what makes warming
+ * idempotent, replays offline-reproducible, and cloud model drift a cache miss instead of a
+ * silent corruption.
+ *
+ * Division of labor with the HOT PATH: `warm()` is the only bulk computation and belongs to
+ * explicit heavy operations (rtm_reindex). The ranking path only calls `cachedDocVector`
+ * (a lookup) and `embedQuery` (one text, awaited by the HANDLER before the sync ranking runs).
+ */
+import { type SemanticTier } from './tier';
+import { VectorCache } from './vector-cache';
+export interface SemanticRuntime {
+    label: string;
+    /** One text, awaited by the handler BEFORE the sync ranking; null on any failure. */
+    embedQuery(text: string): Promise<number[] | null>;
+    /** Cache lookup only — the hot path never computes a document embedding. */
+    cachedDocVector(text: string): number[] | null;
+    /** The bulk path, for explicit heavy operations. Idempotent through the cache. */
+    warm(texts: string[]): Promise<{
+        computed: number;
+        cached: number;
+    }>;
+}
+export interface EmbedderOpts {
+    pipelineLoader?: (model: string) => Promise<(text: string, o: {
+        pooling: string;
+        normalize: boolean;
+    }) => Promise<{
+        data: Float32Array;
+    }>>;
+    fetchImpl?: typeof fetch;
+    key?: string;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (line: string) => void;
+}
+export declare function makeTierEmbedder(tier: SemanticTier, cache: VectorCache, opts?: EmbedderOpts): SemanticRuntime | null;

package/dist/holmes/semantic/embedder.js

@@ -0,0 +1,185 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeTierEmbedder = makeTierEmbedder;
+// @implements A-SPEC-478
+/**
+ * The tier adapters — the productized form of exactly what the measurement scripts proved:
+ *
+ *   local  = @xenova/transformers with the FROZEN pooling table (bge-m3 → CLS; mean-pooling it
+ *            was the S-491 instrument accident), quantized, lazy pipeline.
+ *   cloud  = gemini batchEmbedContents with the MEASURED pacing (≤25 per batch, backoff on 429 —
+ *            the free-tier and TPM ceilings were both hit live). The key never appears in any
+ *            log or error string.
+ *
+ * Both flow through the VectorCache (content hash + model tag), which is what makes warming
+ * idempotent, replays offline-reproducible, and cloud model drift a cache miss instead of a
+ * silent corruption.
+ *
+ * Division of labor with the HOT PATH: `warm()` is the only bulk computation and belongs to
+ * explicit heavy operations (rtm_reindex). The ranking path only calls `cachedDocVector`
+ * (a lookup) and `embedQuery` (one text, awaited by the HANDLER before the sync ranking runs).
+ */
+const tier_1 = require("./tier");
+const credentials_1 = require("./credentials");
+const CLOUD_BATCH = 25;
+const CLOUD_BACKOFF_MS = 30_000;
+function makeTierEmbedder(tier, cache, opts = {}) {
+    if (tier.tier === 'none' || tier.model === undefined)
+        return null;
+    const model = tier.model;
+    if (tier.tier === 'local') {
+        const tag = `${model}@q8-${(0, tier_1.POOLING_OF)(model)}`;
+        let pipe = null;
+        const load = () => {
+            if (pipe === null) {
+                pipe = (opts.pipelineLoader ?? (async (m) => {
+                    const specifier = '@xenova/transformers';
+                    const mod = await Promise.resolve(`${specifier}`).then(s => __importStar(require(s)));
+                    return mod.pipeline('feature-extraction', m, { quantized: true });
+                }))(model);
+            }
+            return pipe;
+        };
+        const embed = async (text) => {
+            try {
+                const p = await load();
+                return Array.from((await p(text, { pooling: (0, tier_1.POOLING_OF)(model), normalize: true })).data);
+            }
+            catch {
+                return null;
+            }
+        };
+        return {
+            label: `local:${model}`,
+            embedQuery: async (text) => {
+                const hit = cache.get(text, tag, 'query');
+                if (hit)
+                    return hit;
+                const v = await embed(text);
+                // In-memory only: maintenance analysis is READ-ONLY (a pinned contract — a cold project
+                // must stay cache-free), so the hot path never flushes. Disk persistence belongs to
+                // warm(), which only runs inside explicit write-path operations (rtm_reindex).
+                if (v)
+                    cache.put(text, tag, 'query', v);
+                return v;
+            },
+            cachedDocVector: (text) => cache.get(text, tag, 'doc'),
+            warm: async (texts) => {
+                let computed = 0, cached = 0;
+                for (const t of texts) {
+                    if (cache.get(t, tag, 'doc')) {
+                        cached++;
+                        continue;
+                    }
+                    const v = await embed(t);
+                    if (v) {
+                        cache.put(t, tag, 'doc', v);
+                        computed++;
+                    }
+                }
+                cache.flush();
+                return { computed, cached };
+            },
+        };
+    }
+    // cloud
+    const tag = `${model}@v1`;
+    const key = opts.key ?? (0, credentials_1.resolveSemanticKey)()?.key ?? null;
+    if (key === null)
+        return null;
+    const f = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const callBatch = async (texts, taskType) => {
+        const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:batchEmbedContents?key=${key}`;
+        const body = JSON.stringify({ requests: texts.map((t) => ({ model: `models/${model}`, content: { parts: [{ text: t }] }, taskType })) });
+        for (let attempt = 0; attempt < 5; attempt++) {
+            try {
+                const res = await f(url, { method: 'POST', headers: { 'content-type': 'application/json' }, body });
+                if (res.status === 429 || res.status >= 500) {
+                    opts.log?.(`cloud embed backoff (HTTP ${res.status})`);
+                    await sleep(CLOUD_BACKOFF_MS);
+                    continue;
+                }
+                if (!res.ok) {
+                    opts.log?.(`cloud embed failed (HTTP ${res.status})`);
+                    return null;
+                } // never the key, never the body
+                const j = await res.json();
+                return j.embeddings.map((e) => e.values);
+            }
+            catch {
+                opts.log?.('cloud embed network error');
+                return null;
+            }
+        }
+        opts.log?.('cloud embed rate-limited after retries');
+        return null;
+    };
+    return {
+        label: `cloud:${model}`,
+        embedQuery: async (text) => {
+            const hit = cache.get(text, tag, 'query');
+            if (hit)
+                return hit;
+            const vs = await callBatch([text], 'RETRIEVAL_QUERY');
+            if (vs === null)
+                return null;
+            cache.put(text, tag, 'query', vs[0]); // in-memory only — see the local adapter's note
+            return vs[0];
+        },
+        cachedDocVector: (text) => cache.get(text, tag, 'doc'),
+        warm: async (texts) => {
+            let computed = 0, cached = 0;
+            const missing = [];
+            for (const t of texts) {
+                if (cache.get(t, tag, 'doc'))
+                    cached++;
+                else
+                    missing.push(t);
+            }
+            for (let i = 0; i < missing.length; i += CLOUD_BATCH) {
+                const slice = missing.slice(i, i + CLOUD_BATCH);
+                const vs = await callBatch(slice, 'RETRIEVAL_DOCUMENT');
+                if (vs === null)
+                    break; // partial warm is fine — the cache keeps what landed
+                slice.forEach((t, n) => cache.put(t, tag, 'doc', vs[n]));
+                computed += slice.length;
+                cache.flush();
+            }
+            return { computed, cached };
+        },
+    };
+}

package/dist/holmes/semantic/hit-rerank.d.ts

@@ -0,0 +1,4 @@
+export declare function rerankHitsBySemantic(hits: Array<{
+    file: string;
+    why: string[];
+}>, queryVec: readonly number[] | null, docVecOf: (file: string) => readonly number[] | null, label: string): void;

package/dist/holmes/semantic/hit-rerank.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rerankHitsBySemantic = rerankHitsBySemantic;
+// @implements A-SPEC-496
+/**
+ * The uncited semantic head rerank, extracted PURE — exactly the A-SPEC-478 math that ships in
+ * maintenance_analyze, so the direct localization path (issue_localize) provably applies the
+ * same policy: only hits with a CACHED vector move (stable order otherwise), the set never
+ * changes, coverage lands as a why-line, and any missing signal is a complete no-op.
+ *
+ * The gate (the request cited no spec) stays with the CALLER — it needs the spec store, and
+ * keeping it there mirrors how A-SPEC-478 divides the same responsibility.
+ */
+const dense_retrieval_1 = require("../review/dense-retrieval");
+function rerankHitsBySemantic(hits, queryVec, docVecOf, label) {
+    if (queryVec === null || hits.length <= 1)
+        return;
+    const sim = new Map();
+    let covered = 0;
+    for (const h of hits) {
+        const dv = docVecOf(h.file);
+        if (dv !== null) {
+            sim.set(h.file, (0, dense_retrieval_1.cosine)(queryVec, dv));
+            covered++;
+        }
+    }
+    if (covered === 0)
+        return;
+    hits.sort((a, b) => {
+        const sa = sim.get(a.file) ?? -Infinity;
+        const sb = sim.get(b.file) ?? -Infinity;
+        return sb === sa ? 0 : sb - sa;
+    });
+    for (const h of hits) {
+        if (sim.has(h.file))
+            h.why.push(`semantic-rerank(${label}, coverage ${covered}/${hits.length})`);
+    }
+}

package/dist/holmes/semantic/tier.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The semantic layer's tier structure — the owner's two-lever design made a contract:
+ * maximize what the harness can do WITHOUT egress (a local model), and let an explicit opt-in
+ * maximize further (a cloud model). The default ships NEITHER: tier 'none', zero egress.
+ *
+ * The measured parameters this encodes (S-491, four-arm traceability, 305 cases):
+ *   lexical 0.486  <  local bge-m3 (CLS) 0.667  <  cloud gemini-embedding-001 0.887 recall,
+ *   and on the lexical-zero segment (16.4%, growing): 0.000 / 0.517 / 0.920.
+ *
+ * Consent model: setting GEMINI_API_KEY IS the opt-in. The tier resolver never probes the
+ * network; presence signals only, so doctor can call it offline.
+ */
+import { type CredentialOpts, type KeySource } from './credentials';
+/** The local tier's model. CLS-pooled — see POOLING_OF. */
+export declare const LOCAL_MODEL = "Xenova/bge-m3";
+/** The opt-in cloud tier's model (S-491 four-arm winner). */
+export declare const CLOUD_MODEL = "gemini-embedding-001";
+export interface SemanticTier {
+    tier: 'cloud' | 'local' | 'none';
+    model?: string;
+    /** Whether using this tier sends repository-derived text off the machine. */
+    egress: boolean;
+    /** Where the cloud consent came from — shown by doctor/status, never the value itself. */
+    keySource?: KeySource;
+}
+/**
+ * Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
+ * S-491 instrument accident — a 4.4x quality collapse (0.150 vs 0.667 recall) that read as a
+ * verdict until the "a stronger model losing to a weaker one means the instrument is broken"
+ * heuristic caught it. The table exists so that lesson is code, not tribal knowledge.
+ */
+export declare function POOLING_OF(model: string): 'cls' | 'mean';
+export declare function resolveSemanticTier(opts?: {
+    env?: NodeJS.ProcessEnv;
+    hasLocalModule?: boolean;
+    credentials?: CredentialOpts;
+}): SemanticTier;

package/dist/holmes/semantic/tier.js

@@ -0,0 +1,54 @@
+"use strict";
+// @implements A-SPEC-476
+/**
+ * The semantic layer's tier structure — the owner's two-lever design made a contract:
+ * maximize what the harness can do WITHOUT egress (a local model), and let an explicit opt-in
+ * maximize further (a cloud model). The default ships NEITHER: tier 'none', zero egress.
+ *
+ * The measured parameters this encodes (S-491, four-arm traceability, 305 cases):
+ *   lexical 0.486  <  local bge-m3 (CLS) 0.667  <  cloud gemini-embedding-001 0.887 recall,
+ *   and on the lexical-zero segment (16.4%, growing): 0.000 / 0.517 / 0.920.
+ *
+ * Consent model: setting GEMINI_API_KEY IS the opt-in. The tier resolver never probes the
+ * network; presence signals only, so doctor can call it offline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOUD_MODEL = exports.LOCAL_MODEL = void 0;
+exports.POOLING_OF = POOLING_OF;
+exports.resolveSemanticTier = resolveSemanticTier;
+const credentials_1 = require("./credentials");
+/** The local tier's model. CLS-pooled — see POOLING_OF. */
+exports.LOCAL_MODEL = 'Xenova/bge-m3';
+/** The opt-in cloud tier's model (S-491 four-arm winner). */
+exports.CLOUD_MODEL = 'gemini-embedding-001';
+/**
+ * Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
+ * S-491 instrument accident — a 4.4x quality collapse (0.150 vs 0.667 recall) that read as a
+ * verdict until the "a stronger model losing to a weaker one means the instrument is broken"
+ * heuristic caught it. The table exists so that lesson is code, not tribal knowledge.
+ */
+function POOLING_OF(model) {
+    return model.includes('bge-m3') ? 'cls' : 'mean';
+}
+function localModulePresent() {
+    try {
+        // Same optional-dependency discipline as dense-retrieval: resolved, never imported here.
+        require.resolve('@xenova/transformers');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveSemanticTier(opts = {}) {
+    // @implements A-SPEC-477 — the cloud consent is resolved through the credential CHAIN
+    // (dedicated env → compat env → keychain → 0600 user file), never a project-tree file.
+    const found = (0, credentials_1.resolveSemanticKey)({ env: opts.env ?? process.env, ...opts.credentials });
+    if (found !== null) {
+        return { tier: 'cloud', model: exports.CLOUD_MODEL, egress: true, keySource: found.source };
+    }
+    const hasLocal = opts.hasLocalModule ?? localModulePresent();
+    if (hasLocal)
+        return { tier: 'local', model: exports.LOCAL_MODEL, egress: false };
+    return { tier: 'none', egress: false };
+}

package/dist/holmes/semantic/vector-cache.d.ts

@@ -0,0 +1,11 @@
+export declare class VectorCache {
+    private readonly file;
+    private store;
+    constructor(root: string);
+    private load;
+    private key;
+    get(text: string, modelTag: string, kind: 'query' | 'doc'): number[] | null;
+    put(text: string, modelTag: string, kind: 'query' | 'doc', vector: number[]): void;
+    /** Atomic persist: tmp + rename, so a crash mid-write cannot corrupt the previous cache. */
+    flush(): void;
+}

package/dist/holmes/semantic/vector-cache.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VectorCache = void 0;
+// @implements A-SPEC-476
+/**
+ * Content-addressed vector cache: never compute the same embedding twice, never serve a stale
+ * vector across a model update.
+ *
+ * The key is `hash(text) : modelTag : kind`. The model TAG (id plus a caller-supplied version
+ * label) is load-bearing for the cloud tier — an API model can be re-deployed silently, and
+ * "same text, different vector" across that boundary would corrupt every similarity the product
+ * computes. A tag change is a cache miss by construction.
+ *
+ * The file lives under `.ax/cpg_cache/` — an existing protected directory, so no gate surface
+ * moves. A cache must be LOSABLE: a corrupted file restarts empty instead of throwing (measured
+ * economics: 37MB for a three-corpus measurement day; recomputing is cost, not damage).
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const FILE = path.join('.ax', 'cpg_cache', 'semantic-vectors.json');
+class VectorCache {
+    file;
+    store = null;
+    constructor(root) {
+        this.file = path.join(root, FILE);
+    }
+    load() {
+        if (this.store !== null)
+            return this.store;
+        try {
+            this.store = JSON.parse(fs.readFileSync(this.file, 'utf8'));
+        }
+        catch {
+            this.store = {};
+        }
+        return this.store;
+    }
+    key(text, modelTag, kind) {
+        return `${(0, node_crypto_1.createHash)('sha256').update(text).digest('hex').slice(0, 24)}:${modelTag}:${kind}`;
+    }
+    get(text, modelTag, kind) {
+        return this.load()[this.key(text, modelTag, kind)] ?? null;
+    }
+    put(text, modelTag, kind, vector) {
+        this.load()[this.key(text, modelTag, kind)] = vector;
+    }
+    /** Atomic persist: tmp + rename, so a crash mid-write cannot corrupt the previous cache. */
+    flush() {
+        if (this.store === null)
+            return;
+        const tmp = this.file + '.tmp';
+        fs.mkdirSync(path.dirname(this.file), { recursive: true });
+        fs.writeFileSync(tmp, JSON.stringify(this.store));
+        fs.renameSync(tmp, this.file);
+    }
+}
+exports.VectorCache = VectorCache;