@holmes-lab/holmes-kit 0.19.3 → 0.19.4

package/dist/holmes/rtm/graph-store.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.specFingerprint = specFingerprint;
 exports.scanDigest = scanDigest;
 exports.openReusableGraph = openReusableGraph;
 // @implements A-SPEC-282
@@ -43,6 +44,19 @@ const rtm_graph_1 = require("./rtm-graph");
 const BASIS_FIELDS = [
     'graphSchema', 'extractorVersion', 'sourceCommit', 'specFingerprint', 'scanDigest',
 ];
+/** Deterministic content fingerprint for every spec field consumed by buildRtm. */
+function specFingerprint(specs) {
+    const canonical = (value) => {
+        if (Array.isArray(value))
+            return value.map(canonical);
+        if (value !== null && typeof value === 'object') {
+            return Object.fromEntries(Object.entries(value)
+                .sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, canonical(v)]));
+        }
+        return value;
+    };
+    return `sha256:${(0, node_crypto_1.createHash)('sha256').update(JSON.stringify(specs.map(canonical))).digest('hex')}`;
+}
 /**
  * Content address of a scan: every file's path and its symbols/edges, sorted so the digest depends
  * on the scan's CONTENT and not on the order the scanner happened to walk the tree in.

package/dist/holmes/rtm/rtm-graph.js

@@ -66,16 +66,17 @@ class RtmGraph {
     // full rebuild.
     constructor(dbPath = ':memory:') {
         this.db = new better_sqlite3_1.default(dbPath);
-        // @implements A-SPEC-283
-        // Only a FILE-backed store can be contended. Several MCP servers can be live at once, and the
-        // hook and the CLI can touch the same project, so a reader must not be blocked by a writer and a
-        // busy file must be waited on rather than thrown at. `:memory:` is private to this process and
-        // cannot use WAL at all — setting it there would be a pragma that cannot apply.
-        if (dbPath !== ':memory:') {
-            this.db.pragma('journal_mode = WAL');
-            this.db.pragma('busy_timeout = 5000');
-        }
-        this.db.exec(`CREATE TABLE IF NOT EXISTS nodes (id TEXT PRIMARY KEY, kind TEXT NOT NULL, source_path TEXT, summary TEXT);
+        try {
+            // @implements A-SPEC-283
+            // Only a FILE-backed store can be contended. Several MCP servers can be live at once, and the
+            // hook and the CLI can touch the same project, so a reader must not be blocked by a writer and a
+            // busy file must be waited on rather than thrown at. `:memory:` is private to this process and
+            // cannot use WAL at all — setting it there would be a pragma that cannot apply.
+            if (dbPath !== ':memory:') {
+                this.db.pragma('journal_mode = WAL');
+                this.db.pragma('busy_timeout = 5000');
+            }
+            this.db.exec(`CREATE TABLE IF NOT EXISTS nodes (id TEXT PRIMARY KEY, kind TEXT NOT NULL, source_path TEXT, summary TEXT);
       CREATE TABLE IF NOT EXISTS edges (src TEXT NOT NULL, dst TEXT NOT NULL, rel TEXT NOT NULL, source_path TEXT, PRIMARY KEY (src,dst,rel));
       -- The PK covers src-prefixed lookups; nothing covered dst or source_path, so every reverse
       -- traversal and every removeBySource was a full table scan. Measured on a 240k-node graph:
@@ -86,28 +87,39 @@ class RtmGraph {
       CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst);
       CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_path);
       CREATE INDEX IF NOT EXISTS idx_nodes_source ON nodes(source_path);`);
-        // @implements A-SPEC-281
-        // `CREATE TABLE IF NOT EXISTS` leaves an EXISTING database on its old schema, so a store written
-        // before provenance existed would silently reject every new insert. Add the missing columns in
-        // place; existing rows keep their data and simply report null provenance, which is the honest
-        // record for a fact nobody annotated.
-        // @implements A-SPEC-282 — a small key/value side table so a persisted graph can carry the basis
-        // it was built on. Kept out of `nodes`/`edges` because it describes the WHOLE graph, not a fact.
-        this.db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
-        for (const table of ['nodes', 'edges']) {
-            const present = new Set(this.db.prepare(`PRAGMA table_info(${table})`).all()
-                .map((c) => c.name));
-            for (const column of PROVENANCE_COLUMNS) {
-                if (present.has(column))
-                    continue;
-                const type = column === 'confidence' ? 'REAL' : 'TEXT';
-                this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+            // @implements A-SPEC-281
+            // `CREATE TABLE IF NOT EXISTS` leaves an EXISTING database on its old schema, so a store written
+            // before provenance existed would silently reject every new insert. Add the missing columns in
+            // place; existing rows keep their data and simply report null provenance, which is the honest
+            // record for a fact nobody annotated.
+            // @implements A-SPEC-282 — a small key/value side table so a persisted graph can carry the basis
+            // it was built on. Kept out of `nodes`/`edges` because it describes the WHOLE graph, not a fact.
+            this.db.exec('CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)');
+            for (const table of ['nodes', 'edges']) {
+                const present = new Set(this.db.prepare(`PRAGMA table_info(${table})`).all()
+                    .map((c) => c.name));
+                for (const column of PROVENANCE_COLUMNS) {
+                    if (present.has(column))
+                        continue;
+                    const type = column === 'confidence' ? 'REAL' : 'TEXT';
+                    this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+                }
+                // @implements A-SPEC-568.1 — same in-place migration rule as provenance: an rtm-graph/2 file
+                // must keep OPENING (openReusableGraph decides reuse; an unreadable file would look corrupt).
+                if (table === 'nodes' && !present.has('summary')) {
+                    this.db.exec('ALTER TABLE nodes ADD COLUMN summary TEXT');
+                }
             }
-            // @implements A-SPEC-568.1 — same in-place migration rule as provenance: an rtm-graph/2 file
-            // must keep OPENING (openReusableGraph decides reuse; an unreadable file would look corrupt).
-            if (table === 'nodes' && !present.has('summary')) {
-                this.db.exec('ALTER TABLE nodes ADD COLUMN summary TEXT');
+        }
+        catch (error) {
+            // A corrupt file can fail during pragma/schema setup after better-sqlite3 has opened it.
+            // Release that native handle before propagating the original error so the caller can replace
+            // the file on Windows instead of receiving a second EPERM/SQLITE_NOTADB failure (A-SPEC-588).
+            try {
+                this.db.close();
             }
+            catch { /* preserve the initialization error */ }
+            throw error;
         }
     }
     // @implements A-SPEC-139

package/dist/holmes/semantic/credentials.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveSemanticKey = resolveSemanticKey;
 exports.storeSemanticKey = storeSemanticKey;
 exports.removeSemanticKey = removeSemanticKey;
+// @implements A-SPEC-592
 // @implements A-SPEC-477
 /**
  * The cloud tier's credential: WHERE the consent lives, and in what order it is looked up.
@@ -49,9 +50,9 @@ exports.removeSemanticKey = removeSemanticKey;
  * 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.
+ *   3. macOS keychain           — `security` via injected exec (absent elsewhere).
+ *   4. ~/.holmes/credentials.json — POSIX0600 under0700, or protected current-user-only
+ *                                 Windows DACLs, 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.
@@ -60,11 +61,59 @@ 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 node_crypto_1 = require("node:crypto");
 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;
+// Fixed command: its stdin contains only encoded paths, never credential content. Fresh security
+// descriptors discard both inherited and explicit broad grants; chmod cannot do that on Windows.
+const PRIVATE_WINDOWS_ACL = `
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+$targets = ConvertFrom-Json ([Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([Console]::In.ReadToEnd())))
+$sid = [Security.Principal.WindowsIdentity]::GetCurrent().User
+foreach ($target in $targets) {
+  $item = Get-Item -LiteralPath $target.path -Force
+  if (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) { throw 'Credential path is a reparse point' }
+  if ($target.directory) {
+    $acl = [Security.AccessControl.DirectorySecurity]::new()
+    $rule = [Security.AccessControl.FileSystemAccessRule]::new($sid, 'FullControl', 'ContainerInherit,ObjectInherit', 'None', 'Allow')
+  } else {
+    $acl = [Security.AccessControl.FileSecurity]::new()
+    $rule = [Security.AccessControl.FileSystemAccessRule]::new($sid, 'FullControl', 'Allow')
+  }
+  $acl.SetAccessRuleProtection($true, $false)
+  $acl.AddAccessRule($rule)
+  # Persist only the DACL. Set-Acl can request SACL privileges during a repeated protected update.
+  if ($target.directory) { [IO.Directory]::SetAccessControl($target.path, $acl) }
+  else { [IO.File]::SetAccessControl($target.path, $acl) }
+  $actual = Get-Acl -LiteralPath $target.path
+  $rules = @($actual.GetAccessRules($true, $true, [Security.Principal.SecurityIdentifier]))
+  if (-not $actual.AreAccessRulesProtected -or $rules.Count -ne 1 -or
+      $rules[0].IdentityReference.Value -ne $sid.Value -or $rules[0].IsInherited -or
+      $rules[0].AccessControlType -ne 'Allow' -or
+      $rules[0].FileSystemRights -ne [Security.AccessControl.FileSystemRights]::FullControl) {
+    throw 'Credential ACL verification failed'
+  }
+}
+`;
+function protectWindowsPaths(targets) {
+    try {
+        (0, node_child_process_1.execFileSync)('powershell.exe', [
+            '-NoLogo', '-NoProfile', '-NonInteractive', '-EncodedCommand',
+            Buffer.from(PRIVATE_WINDOWS_ACL, 'utf16le').toString('base64'),
+        ], {
+            input: Buffer.from(JSON.stringify(targets), 'utf8').toString('base64'),
+            encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, timeout: 15000,
+        });
+    }
+    catch {
+        // Native errors may carry command output. Keep the public error stable and free of values.
+        throw new Error('Unable to protect semantic credentials with a private Windows ACL; the new key was not stored.');
+    }
+}
 function resolveSemanticKey(opts = {}) {
     const env = opts.env ?? process.env;
     const home = opts.home ?? os.homedir();
@@ -109,12 +158,40 @@ function storeSemanticKey(key, opts = {}) {
         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);
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    // opts.platform selects a credential source in tests. Permissions must follow the actual host.
+    if (process.platform === 'win32') {
+        protectWindowsPaths([
+            { path: directory, directory: true },
+            ...(fs.existsSync(file) ? [{ path: file, directory: false }] : []),
+        ]);
+    }
+    else {
+        fs.chmodSync(directory, 0o700);
+    }
+    const tmp = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    let fd;
+    let created = false;
+    try {
+        fd = fs.openSync(tmp, 'wx', 0o600);
+        created = true;
+        if (process.platform === 'win32')
+            protectWindowsPaths([{ path: tmp, directory: false }]);
+        else
+            fs.fchmodSync(fd, 0o600);
+        // The empty file is private before the first secret byte, and the descriptor stays owned.
+        fs.writeFileSync(fd, JSON.stringify({ semantic: { provider: 'gemini', key } }));
+        fs.closeSync(fd);
+        fd = undefined;
+        fs.renameSync(tmp, file);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+        if (created)
+            fs.rmSync(tmp, { force: true });
+    }
     return 'file';
 }
 function removeSemanticKey(opts = {}) {

package/dist/holmes/semantic/embedder.js

@@ -1,39 +1,7 @@
 "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-591
 // @implements A-SPEC-478
 /**
  * The tier adapters — the productized form of exactly what the measurement scripts proved:
@@ -54,6 +22,7 @@ exports.makeTierEmbedder = makeTierEmbedder;
  */
 const tier_1 = require("./tier");
 const credentials_1 = require("./credentials");
+const local_model_1 = require("./local-model");
 const CLOUD_BATCH = 25;
 const CLOUD_BACKOFF_MS = 30_000;
 function makeTierEmbedder(tier, cache, opts = {}) {
@@ -61,15 +30,11 @@ function makeTierEmbedder(tier, cache, opts = {}) {
         return null;
     const model = tier.model;
     if (tier.tier === 'local') {
-        const tag = `${model}@q8-${(0, tier_1.POOLING_OF)(model)}`;
+        const tag = `${model}@${local_model_1.LOCAL_REVISION}-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);
+                pipe = (opts.pipelineLoader ?? local_model_1.loadLocalPipeline)(model);
             }
             return pipe;
         };
@@ -79,6 +44,8 @@ function makeTierEmbedder(tier, cache, opts = {}) {
                 return Array.from((await p(text, { pooling: (0, tier_1.POOLING_OF)(model), normalize: true })).data);
             }
             catch {
+                pipe = null;
+                (opts.log ?? ((line) => process.stderr.write(`${line}\n`)))('Local embedding unavailable. Run holmes-kit semantic-setup, then holmes-kit semantic-check.');
                 return null;
             }
         };

package/dist/holmes/semantic/local-model.d.ts

@@ -0,0 +1,30 @@
+import { spawnSync } from 'node:child_process';
+import { modelCacheDir, modelCacheReady } from './model-cache';
+export { modelCacheDir, modelCacheReady };
+export declare const LOCAL_REVISION = "4de13258303883538bd53b696b452bf8099f0858";
+type Pipeline = (text: string, options: {
+    pooling: string;
+    normalize: boolean;
+}) => Promise<{
+    data: Float32Array;
+}>;
+interface Runtime {
+    pipeline(task: string, model: string, options: Record<string, unknown>): Promise<Pipeline>;
+}
+export declare function loadLocalPipeline(model?: string, options?: {
+    download?: boolean;
+    importer?: () => Promise<Runtime>;
+    cacheDir?: string;
+}): Promise<Pipeline>;
+export declare function verifyLocalModel(options?: Parameters<typeof loadLocalPipeline>[1]): Promise<{
+    ready: boolean;
+    dimension?: number;
+    message: string;
+}>;
+/** Isolate setup from the MCP and bound slow downloads/inference; all platforms share this path. */
+export declare function runModelSetup(options?: {
+    automatic?: boolean;
+    offline?: boolean;
+    env?: NodeJS.ProcessEnv;
+    spawn?: typeof spawnSync;
+}): number;

package/dist/holmes/semantic/local-model.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOCAL_REVISION = exports.modelCacheReady = exports.modelCacheDir = void 0;
+exports.loadLocalPipeline = loadLocalPipeline;
+exports.verifyLocalModel = verifyLocalModel;
+exports.runModelSetup = runModelSetup;
+// @implements A-SPEC-591
+const node_child_process_1 = require("node:child_process");
+const tier_1 = require("./tier");
+const model_cache_1 = require("./model-cache");
+Object.defineProperty(exports, "modelCacheDir", { enumerable: true, get: function () { return model_cache_1.modelCacheDir; } });
+Object.defineProperty(exports, "modelCacheReady", { enumerable: true, get: function () { return model_cache_1.modelCacheReady; } });
+exports.LOCAL_REVISION = '4de13258303883538bd53b696b452bf8099f0858';
+// TypeScript's CommonJS transform rewrites import() into require(), which cannot load this ESM
+// dependency on supported Node 20 versions. Preserve native dynamic import without shell code.
+const importRuntime = new Function('return import("@xenova/transformers")');
+const pipelines = new WeakMap();
+async function loadLocalPipeline(model = tier_1.LOCAL_MODEL, options = {}) {
+    const importer = options.importer ?? importRuntime;
+    const cacheDir = options.cacheDir ?? (0, model_cache_1.modelCacheDir)();
+    const key = JSON.stringify([model, cacheDir, !!options.download]);
+    let cache = pipelines.get(importer);
+    if (!cache) {
+        cache = new Map();
+        pipelines.set(importer, cache);
+    }
+    const existing = cache.get(key);
+    if (existing)
+        return existing;
+    const pending = importer().then(runtime => runtime.pipeline('feature-extraction', model, {
+        quantized: true,
+        revision: model === tier_1.LOCAL_MODEL ? exports.LOCAL_REVISION : 'main',
+        cache_dir: cacheDir,
+        local_files_only: !options.download,
+    })).catch(error => { cache.delete(key); throw error; });
+    cache.set(key, pending);
+    return pending;
+}
+async function verifyLocalModel(options = {}) {
+    try {
+        const pipe = await loadLocalPipeline(tier_1.LOCAL_MODEL, options);
+        // Fixed public probe: no repository data is involved in setup.
+        const { data } = await pipe('Holmes-Kit local model verification', { pooling: (0, tier_1.POOLING_OF)(tier_1.LOCAL_MODEL), normalize: true });
+        const norm = Math.hypot(...data);
+        if (data.length !== 1024 || !Array.from(data).every(Number.isFinite) || Math.abs(norm - 1) > 0.001) {
+            return { ready: false, dimension: data.length, message: 'BGE-M3 produced an invalid embedding. Select a clean HOLMES_MODEL_CACHE and run holmes-kit semantic-setup.' };
+        }
+        return { ready: true, dimension: data.length, message: 'BGE-M3 ready: verified 1024-dimensional normalized local embedding.' };
+    }
+    catch (error) {
+        const sharp = String(error instanceof Error ? error.message : '').includes('sharp');
+        return { ready: false, message: sharp
+                ? 'BGE-M3 runtime unavailable: sharp native installation failed. Review npm install-scripts ls and approve the sharp version, rebuild it, then run holmes-kit semantic-setup.'
+                : 'BGE-M3 unavailable: runtime/model load failed. Check network access during setup and cache permissions, then run holmes-kit semantic-setup; use semantic-check to verify offline.' };
+    }
+}
+/** Isolate setup from the MCP and bound slow downloads/inference; all platforms share this path. */
+function runModelSetup(options = {}) {
+    const env = options.env ?? process.env;
+    // @implements A-SPEC-594 — the automatic path does not start a large download the user did not
+    // ask for. An explicit refusal outranks an opt-in: someone who set SKIP meant it, and reading
+    // AUTO as permission to override that would silently reverse their decision. The two skips say
+    // DIFFERENT things, because telling a user "you opted out" when they never did is a lie.
+    if (options.automatic) {
+        if (env.HOLMES_SKIP_MODEL_INSTALL === '1') {
+            process.stderr.write('BGE-M3 automatic setup skipped (HOLMES_SKIP_MODEL_INSTALL=1). Run holmes-kit semantic-setup when ready.\n');
+            return 0;
+        }
+        if (env.HOLMES_AUTO_MODEL_INSTALL !== '1') {
+            process.stderr.write('BGE-M3 is not prepared automatically. Run `holmes-kit semantic-setup` to download the public model once (shared across projects), or set HOLMES_AUTO_MODEL_INSTALL=1 to prepare it during installation. Graph features work without it.\n');
+            return 0;
+        }
+    }
+    process.stderr.write(options.offline ? 'Checking BGE-M3 offline...\n' : 'Preparing BGE-M3 (public model download on first installation)...\n');
+    const result = (options.spawn ?? node_child_process_1.spawnSync)(process.execPath, [__filename, '--worker', ...(options.offline ? ['--offline'] : [])], { env, stdio: 'inherit', timeout: 900_000, windowsHide: true });
+    if (result.error || result.status !== 0) {
+        process.stderr.write('BGE-M3 setup/check failed or timed out. Graph features remain available; run holmes-kit semantic-setup to retry.\n');
+        return options.automatic ? 0 : 1;
+    }
+    return 0;
+}
+if (require.main === module) {
+    if (process.argv.includes('--worker')) {
+        verifyLocalModel({ download: !process.argv.includes('--offline') }).then(result => {
+            process[result.ready ? 'stdout' : 'stderr'].write(`${result.message}\n`);
+            process.exitCode = result.ready ? 0 : 1;
+        }).catch(() => { process.stderr.write('BGE-M3 verification failed. Run holmes-kit semantic-setup.\n'); process.exitCode = 1; });
+    }
+    else {
+        process.exitCode = runModelSetup({ automatic: process.argv.includes('--automatic'), offline: process.argv.includes('--offline') });
+    }
+}

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

@@ -0,0 +1,8 @@
+export declare function modelCacheDir(env?: NodeJS.ProcessEnv, home?: string): string;
+/**
+ * Ready means the cache holds SOMETHING. An interrupted download leaves the directory created
+ * and empty, and reading that as ready is the whole failure mode this predicate exists to stop.
+ * Proof of a working model is `semantic-check`'s actual inference — deliberately not here, because
+ * doctor calls this on every run and must stay cheap and offline.
+ */
+export declare function modelCacheReady(cacheDir?: string): boolean;

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

@@ -0,0 +1,67 @@
+"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.modelCacheDir = modelCacheDir;
+exports.modelCacheReady = modelCacheReady;
+// @implements A-SPEC-594
+/**
+ * Where the local model's assets live, and whether they are actually there.
+ *
+ * A leaf on purpose: `tier.ts` must consult readiness, and `local-model.ts` already imports
+ * `tier.ts`, so putting this in either one closes an import cycle. Nothing here imports
+ * anything of ours.
+ */
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+function modelCacheDir(env = process.env, home = os.homedir()) {
+    return path.resolve(env.HOLMES_MODEL_CACHE || path.join(home, '.holmes', 'models'));
+}
+/**
+ * Ready means the cache holds SOMETHING. An interrupted download leaves the directory created
+ * and empty, and reading that as ready is the whole failure mode this predicate exists to stop.
+ * Proof of a working model is `semantic-check`'s actual inference — deliberately not here, because
+ * doctor calls this on every run and must stay cheap and offline.
+ */
+function modelCacheReady(cacheDir = modelCacheDir()) {
+    if (cacheDir === '')
+        return false;
+    try {
+        return fs.readdirSync(cacheDir).length > 0;
+    }
+    catch {
+        return false;
+    } // absent, unreadable, not a directory — none of them are ready
+}

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

@@ -22,6 +22,12 @@ export interface SemanticTier {
     egress: boolean;
     /** Where the cloud consent came from — shown by doctor/status, never the value itself. */
     keySource?: KeySource;
+    /**
+     * @implements A-SPEC-594 — 'none' only: the local runtime resolves but its model was never
+     * prepared. The distinction exists because the two 'none' states need different advice, and
+     * because reporting this one as 'local' claims a recall the tier cannot deliver.
+     */
+    localRuntimePresent?: boolean;
 }
 /**
  * Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
@@ -33,5 +39,6 @@ export declare function POOLING_OF(model: string): 'cls' | 'mean';
 export declare function resolveSemanticTier(opts?: {
     env?: NodeJS.ProcessEnv;
     hasLocalModule?: boolean;
+    hasLocalModel?: boolean;
     credentials?: CredentialOpts;
 }): SemanticTier;

package/dist/holmes/semantic/tier.js

@@ -17,6 +17,7 @@ exports.CLOUD_MODEL = exports.LOCAL_MODEL = void 0;
 exports.POOLING_OF = POOLING_OF;
 exports.resolveSemanticTier = resolveSemanticTier;
 const credentials_1 = require("./credentials");
+const model_cache_1 = require("./model-cache");
 /** 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). */
@@ -47,8 +48,13 @@ function resolveSemanticTier(opts = {}) {
     if (found !== null) {
         return { tier: 'cloud', model: exports.CLOUD_MODEL, egress: true, keySource: found.source };
     }
-    const hasLocal = opts.hasLocalModule ?? localModulePresent();
-    if (hasLocal)
+    // @implements A-SPEC-594 — availability is a CONJUNCTION. Once @xenova/transformers became a
+    // required dependency, `localModulePresent()` answered true for every install and stopped
+    // discriminating; a resolvable runtime with no model produces no embedding at all. Wiring
+    // presence is not readiness.
+    const hasModule = opts.hasLocalModule ?? localModulePresent();
+    const hasModel = opts.hasLocalModel ?? (0, model_cache_1.modelCacheReady)();
+    if (hasModule && hasModel)
         return { tier: 'local', model: exports.LOCAL_MODEL, egress: false };
-    return { tier: 'none', egress: false };
+    return { tier: 'none', egress: false, ...(hasModule ? { localRuntimePresent: true } : {}) };
 }

package/dist/holmes/spec/renumber.d.ts

@@ -0,0 +1,72 @@
+export interface RenumberPlan {
+    moves: {
+        from: string;
+        to: string;
+        oldId: string;
+        newId: string;
+    }[];
+    dependsOn: {
+        file: string;
+        oldId: string;
+        newId: string;
+    }[];
+    slices: {
+        file: string;
+        from: string;
+        to: string;
+    }[];
+    anchors: {
+        file: string;
+        oldId: string;
+        newId: string;
+        count: number;
+    }[];
+    /** Child-first: T -> A -> H -> REQ. Only what a move actually unseals. */
+    unsealOrder: string[];
+    /** Parent-first: REQ -> H -> A -> T. Only what a move actually breaks. */
+    approveOrder: string[];
+    /** Reported, never rewritten. */
+    proseCandidates: {
+        file: string;
+        line: number;
+        text: string;
+    }[];
+    refusal?: string;
+}
+export interface RenumberSpec {
+    id: string;
+    type: string;
+    file: string;
+    dependsOn: string[];
+    status?: string;
+    frontmatter?: Record<string, unknown>;
+    /** The document text, so prose INSIDE a spec is reported like prose anywhere else. */
+    body?: string;
+}
+export interface RenumberInput {
+    specs: RenumberSpec[];
+    sources: {
+        file: string;
+        text: string;
+    }[];
+    oldBase: string;
+    newBase: string;
+}
+/** Rewrite ONLY `@implements` ids. Everything else in the text is left exactly as it was. */
+export declare function rewriteAnchors(text: string, pairs: {
+    oldId: string;
+    newId: string;
+}[]): string;
+export declare function planRenumber(input: RenumberInput): RenumberPlan;
+/**
+ * Apply the plan's STRUCTURED edits. `proseCandidates` is not read here — that is the whole point.
+ * A half-renumbered store is worse than an unrenumbered one, so a failure returns what it moved.
+ */
+export declare function applyRenumber(root: string, plan: RenumberPlan): number;
+/** Source files an anchor can live in, as `{file, text}` with repo-relative POSIX paths. */
+export declare function readSourcesForRenumber(projectRoot: string): {
+    file: string;
+    text: string;
+}[];
+/** Spec documents as the planner needs them, with store-relative POSIX paths. */
+export declare function readSpecsForRenumber(specsRoot: string): RenumberSpec[];