@holmes-lab/holmes-kit 0.19.6 → 0.20.1

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

@@ -33,13 +33,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRAPH_STALE_MS = void 0;
 exports.specFingerprint = specFingerprint;
 exports.scanDigest = scanDigest;
 exports.openReusableGraph = openReusableGraph;
+exports.publishGraph = publishGraph;
+exports.openPublishedGraph = openPublishedGraph;
+exports.headCommitOf = headCommitOf;
 // @implements A-SPEC-282
+// @implements A-SPEC-631
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const node_crypto_1 = require("node:crypto");
+const node_child_process_1 = require("node:child_process");
 const rtm_graph_1 = require("./rtm-graph");
 const BASIS_FIELDS = [
     'graphSchema', 'extractorVersion', 'sourceCommit', 'specFingerprint', 'scanDigest',
@@ -88,8 +94,10 @@ function readStoredBasis(graph) {
  * to fail: the caller always receives a usable graph, empty when the stored one could not be
  * trusted, so "the cache is broken" degrades to "this call is slower" rather than to an outage.
  */
-function openReusableGraph(dbPath, expected) {
+function openReusableGraph(dbPath, expected, opts = {}) {
     fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    if (opts.publishable)
+        return openPublishable(dbPath, expected);
     let graph;
     let reason = null;
     try {
@@ -126,11 +134,244 @@ function openReusableGraph(dbPath, expected) {
     const commitBasis = () => {
         graph.writeMeta(Object.fromEntries(BASIS_FIELDS.map((f) => [f, expected[f]])));
     };
+    const finish = () => graph.close();
     if (reason) {
         // Not reusable means EMPTY. Handing back a partially-stale graph would be worse than no cache:
         // the caller would build on top of facts whose basis it has just been told it cannot trust.
         graph.clear();
-        return { graph, reusable: false, reason, commitBasis };
+        return { graph, reusable: false, reason, commitBasis, publish: finish, discard: finish };
+    }
+    return { graph, reusable: true, reason: null, commitBasis, publish: finish, discard: finish };
+}
+// ---------------------------------------------------------------------------------------------
+// @implements A-SPEC-631 — publication and inspection of the LIVE graph.
+//
+// Before this, rtm_impact (and therefore every Stop-hook refresh) opened `.ax/rtm.sqlite` through
+// openReusableGraph, which CLEARS the file in place when the basis moved and rebuilds into it. Any
+// reader in that window — an approval computing its impact advisory — saw zero nodes and reported
+// "no impact"; a refresher killed after the clear left the file empty and basis-less for everyone.
+// Reproduced with the built product on 2026-09-13. The live file therefore changes only by rename
+// of a complete, basis-committed temporary database, and readers classify what they find.
+// ---------------------------------------------------------------------------------------------
+/** Age after which a `.tmp-*` / `.bak-*` sibling of the live graph is treated as abandoned by a dead publisher. */
+exports.GRAPH_STALE_MS = 10 * 60_000;
+const removeQuietly = (p) => { try {
+    fs.rmSync(p, { force: true });
+}
+catch { /* best effort */ } };
+const uniqueSibling = (livePath, kind) => `${livePath}.${kind}-${process.pid}-${(0, node_crypto_1.randomBytes)(6).toString('hex')}`;
+/**
+ * Replace the live file with the finished temporary database. One rename is atomic on POSIX and
+ * replaces a closed file on Windows. When the live file is held open elsewhere on Windows the
+ * direct rename is refused (EPERM/EBUSY/EACCES); only then fall back to the rename-aside sequence,
+ * where an ENOENT on the aside step means a sibling publisher already replaced the file and is not
+ * an error — executing that sequence unconditionally was what made one of four concurrent reindexes
+ * fail before.
+ */
+function replaceLive(tempPath, livePath) {
+    try {
+        fs.renameSync(tempPath, livePath);
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES')
+            throw error;
+    }
+    const backup = uniqueSibling(livePath, 'bak');
+    let hadBackup = false;
+    try {
+        fs.renameSync(livePath, backup);
+        hadBackup = true;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    try {
+        fs.renameSync(tempPath, livePath);
+    }
+    catch (error) {
+        if (hadBackup && !fs.existsSync(livePath)) {
+            try {
+                fs.renameSync(backup, livePath);
+            }
+            catch { /* preserve the publication error */ }
+        }
+        throw error;
+    }
+    if (hadBackup)
+        removeQuietly(backup);
+}
+/** Remove `.tmp-*` / `.bak-*` siblings (and their SQLite sidecars) older than the stale bound; younger ones may belong to a live publisher. */
+function sweepAbandoned(livePath) {
+    const dir = path.dirname(livePath), base = path.basename(livePath);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        if (!name.startsWith(`${base}.tmp-`) && !name.startsWith(`${base}.bak-`))
+            continue;
+        const p = path.join(dir, name);
+        try {
+            if (Date.now() - fs.statSync(p).mtimeMs > exports.GRAPH_STALE_MS)
+                fs.rmSync(p, { force: true });
+        }
+        catch { /* raced with its owner or already gone */ }
+    }
+}
+/**
+ * Build a complete graph in a private temporary database, commit `basis`, close it, and replace
+ * the live file atomically. The live file is never opened for writing and never cleared; a build
+ * that throws leaves it untouched and removes the temporary file. Returns the published counts.
+ */
+function publishGraph(livePath, basis, build) {
+    fs.mkdirSync(path.dirname(livePath), { recursive: true });
+    const tempPath = uniqueSibling(livePath, 'tmp');
+    let nodes = 0, edges = 0;
+    try {
+        const graph = new rtm_graph_1.RtmGraph(tempPath);
+        try {
+            build(graph);
+            graph.writeMeta(Object.fromEntries(BASIS_FIELDS.map((f) => [f, basis[f]])));
+            nodes = graph.nodeCount();
+            edges = graph.edgeCount();
+        }
+        finally {
+            graph.close(); // checkpoints WAL and drops the temporary database's sidecars
+        }
+        replaceLive(tempPath, livePath);
+    }
+    catch (error) {
+        for (const suffix of ['', '-wal', '-shm', '-journal'])
+            removeQuietly(tempPath + suffix);
+        throw error;
+    }
+    sweepAbandoned(livePath);
+    return { nodes, edges };
+}
+/**
+ * Open the live graph WITHOUT mutating it and say what it is: absent, unreadable (open or metadata
+ * failed — the file is left for the next publication to replace, never deleted here), empty (a
+ * schema with no nodes — the state an interrupted in-place rebuild used to leave behind), or a
+ * served graph whose basis commit is current / stale against `head`, or unverified when either side
+ * is unknown. Served statuses return an OPEN handle the caller must close.
+ */
+function openPublishedGraph(livePath, head) {
+    let graphAsOf;
+    try {
+        graphAsOf = fs.statSync(livePath).mtime.toISOString();
+    }
+    catch {
+        return { status: 'absent', graph: null };
+    }
+    let graph;
+    try {
+        graph = new rtm_graph_1.RtmGraph(livePath);
+    }
+    catch {
+        return { status: 'unreadable', graph: null, graphAsOf };
+    }
+    let meta, nodes;
+    try {
+        meta = graph.readMeta();
+        nodes = graph.nodeCount();
+    }
+    catch {
+        try {
+            graph.close();
+        }
+        catch { /* preserve the classification */ }
+        return { status: 'unreadable', graph: null, graphAsOf };
+    }
+    if (nodes === 0) {
+        graph.close();
+        return { status: 'empty', graph: null, graphAsOf };
+    }
+    const sourceCommit = typeof meta.sourceCommit === 'string' && meta.sourceCommit !== '' ? meta.sourceCommit : null;
+    const status = sourceCommit === null || head === null ? 'unverified' : sourceCommit === head ? 'current' : 'stale';
+    return { status, graph, sourceCommit, head, graphAsOf };
+}
+/**
+ * The `publishable` mode of openReusableGraph. Reads the live file without mutating it; when it
+ * cannot be reused (absent, unreadable, no basis, a moved field) the returned graph is an empty
+ * private temporary database whose `publish()` replaces the live file atomically. The live file is
+ * never created, cleared or deleted here — an unreadable one is left for publication to replace.
+ */
+function openPublishable(livePath, expected) {
+    const basisMeta = () => Object.fromEntries(BASIS_FIELDS.map((f) => [f, expected[f]]));
+    let live = null;
+    let reason = null;
+    if (!fs.existsSync(livePath))
+        reason = 'no stored graph — nothing to reuse';
+    else {
+        try {
+            live = new rtm_graph_1.RtmGraph(livePath);
+        }
+        catch {
+            reason = 'stored graph was unreadable (left for publication to replace)';
+        }
+        if (live !== null) {
+            const stored = readStoredBasis(live);
+            if (!stored)
+                reason = 'no stored basis — nothing to reuse';
+            else {
+                const moved = BASIS_FIELDS.find((field) => stored[field] !== expected[field]);
+                if (moved)
+                    reason = `${moved} changed since the stored graph was built`;
+            }
+        }
+    }
+    if (reason === null && live !== null) {
+        const handle = live;
+        const finish = () => handle.close();
+        return { graph: handle, reusable: true, reason: null, commitBasis: () => handle.writeMeta(basisMeta()), publish: finish, discard: finish };
+    }
+    if (live !== null) {
+        try {
+            live.close();
+        }
+        catch { /* the handle is not reused */ }
+    }
+    const tempPath = uniqueSibling(livePath, 'tmp');
+    const graph = new rtm_graph_1.RtmGraph(tempPath);
+    const cleanup = () => { for (const suffix of ['', '-wal', '-shm', '-journal'])
+        removeQuietly(tempPath + suffix); };
+    return {
+        graph,
+        reusable: false,
+        reason,
+        commitBasis: () => graph.writeMeta(basisMeta()),
+        publish: () => {
+            try {
+                graph.close();
+                replaceLive(tempPath, livePath);
+            }
+            catch (error) {
+                cleanup();
+                throw error;
+            }
+            sweepAbandoned(livePath);
+        },
+        discard: () => { try {
+            graph.close();
+        }
+        finally {
+            cleanup();
+        } },
+    };
+}
+/** HEAD of the repository at `root`, or null outside Git — the only freshness input a consumer pays for (no scan). */
+function headCommitOf(root, env = process.env) {
+    try {
+        const out = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+        return /^[0-9a-f]{40}$/.test(out) ? out : null;
+    }
+    catch {
+        return null;
     }
-    return { graph, reusable: true, reason: null, commitBasis };
 }

package/dist/holmes/rtm/incremental.d.ts

@@ -59,4 +59,5 @@ export declare function applyIncremental(graph: RtmGraph, changes: ChangeSet, ct
     buildOptions?: BuildRtmOptions;
 }): {
     callEdgesResolved: boolean;
+    importsResolved: boolean;
 };

package/dist/holmes/rtm/incremental.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyIncremental = applyIncremental;
+// @implements A-SPEC-644
 const rtm_builder_1 = require("./rtm-builder");
 /**
  * Reduces every add/modify/delete/rename case to one primitive: replace file
@@ -55,13 +56,21 @@ function applyIncremental(graph, changes, ctx) {
         replaceFile(f);
     }
     if (!ctx.allScanned)
-        return { callEdgesResolved: false };
+        return { callEdgesResolved: false, importsResolved: false };
     // @implements A-SPEC-573.5 — `calls_ambiguous` is rebuilt by the same pass, so it must be cleared
     // by the same pass. Missing it left a stale candidate edge behind when an ambiguity RESOLVED
     // (the second definer was deleted), and incremental stopped converging with a full rebuild —
     // caught by A-SPEC-280's convergence property, which is exactly what it is for.
+    const scanned = ctx.allScanned();
     graph.removeEdgesByRel('calls');
     graph.removeEdgesByRel('calls_ambiguous');
-    (0, rtm_builder_1.addCallEdges)(ctx.allScanned(), graph, ctx.buildOptions);
-    return { callEdgesResolved: true };
+    (0, rtm_builder_1.addCallEdges)(scanned, graph, ctx.buildOptions);
+    // @implements A-SPEC-644 — the same whole-scan rule for imports. FILE nodes and `imports` edges are
+    // written by `addImportEdges` over the whole scan (A-SPEC-289) and never by the per-file subgraph, so
+    // measured 2026-09-14 an update that added an import produced no FILE node and no edge, and one that
+    // deleted the import target left a stale FILE node. Clear the kind and the relation, then re-resolve.
+    graph.removeEdgesByRel('imports');
+    graph.removeNodesByKind('FILE');
+    (0, rtm_builder_1.addImportEdges)(scanned, graph, ctx.buildOptions);
+    return { callEdgesResolved: true, importsResolved: true };
 }

package/dist/holmes/rtm/localize.js

@@ -163,6 +163,10 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
     // be recovered lexically, however many terms it has.
     const citations = citationsIn(issueText, new Set(specs.map((s) => s.id)));
     const citedSet = new Set(citations.cited);
+    // @implements A-SPEC-619 — explicit architecture-contract evidence is a ranking key,
+    // not a bonus that unrelated lexical repetition can dilute out of the result window.
+    const priorityCitations = new Set(specs.filter(s => s.type === 'A-SPEC' && citedSet.has(s.id)).map(s => s.id));
+    const directlyCitedFiles = new Set();
     if (terms.length === 0 && citations.cited.length === 0) {
         return { terms: [], hits: [], matchedSpecs: [], unknownCitations: citations.unknown };
     }
@@ -314,6 +318,8 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
             why.push(`implements matched spec(s) ${viaSpecs.join(', ')} (${viaSpecs.length}/${anchors.length} anchors)`);
         }
         const citedAnchors = anchors.filter((id) => citedSet.has(id));
+        if (anchors.some(id => priorityCitations.has(id)))
+            directlyCitedFiles.add(f.sourcePath);
         if (citedAnchors.length > 0) {
             // Normalized by anchor count for the same reason the lexical spec bonus is (A-SPEC-270):
             // otherwise a hub file would collect this bonus for every citation anyone ever writes.
@@ -361,6 +367,7 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
     // project where the vendored code really is the answer. The score halving stays, so the relative
     // order WITHIN each group is unchanged.
     hits.sort((a, b) => Number(isVendorPath(a.file)) - Number(isVendorPath(b.file)) || // live source before vendored
+        Number(directlyCitedFiles.has(b.file)) - Number(directlyCitedFiles.has(a.file)) ||
         b.score - a.score || // then by evidence strength
         a.file.localeCompare(b.file)); // then deterministic path order
     return { terms, hits: hits.slice(0, topN), matchedSpecs: matchedSpecs.sort(), unknownCitations: citations.unknown };

package/dist/holmes/rtm/rtm-graph.d.ts

@@ -213,6 +213,15 @@ export declare class RtmGraph {
      * re-resolving is the only way an incremental update lands on the full-rebuild answer.
      */
     removeEdgesByRel(rel: string): void;
+    /**
+     * @implements A-SPEC-644
+     * Drop every node of one kind and every edge touching one. FILE nodes exist only as import endpoints
+     * and are owned by whichever file's import first resolved to them, so `removeBySource` cannot reach
+     * the ones another file owns — measured, deleting an import target left a stale FILE node for the
+     * importer. Clearing the kind and re-running the whole-scan import pass is the only way an
+     * incremental update lands on the full-rebuild value, exactly as `removeEdgesByRel` does for calls.
+     */
+    removeNodesByKind(kind: string): void;
     /** @implements A-SPEC-282 — every stored meta key/value. */
     readMeta(): Record<string, string>;
     /** @implements A-SPEC-282 — replace the stored meta wholesale, so a stale key cannot survive. */

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

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RtmGraph = void 0;
 // @implements A-SPEC-293
+// @implements A-SPEC-644
 // @implements A-SPEC-289
 // @implements A-SPEC-288
 // @implements A-SPEC-283
@@ -425,6 +426,18 @@ class RtmGraph {
     removeEdgesByRel(rel) {
         this.db.prepare('DELETE FROM edges WHERE rel = ?').run(rel);
     }
+    /**
+     * @implements A-SPEC-644
+     * Drop every node of one kind and every edge touching one. FILE nodes exist only as import endpoints
+     * and are owned by whichever file's import first resolved to them, so `removeBySource` cannot reach
+     * the ones another file owns — measured, deleting an import target left a stale FILE node for the
+     * importer. Clearing the kind and re-running the whole-scan import pass is the only way an
+     * incremental update lands on the full-rebuild value, exactly as `removeEdgesByRel` does for calls.
+     */
+    removeNodesByKind(kind) {
+        this.db.prepare('DELETE FROM edges WHERE src IN (SELECT id FROM nodes WHERE kind = ?) OR dst IN (SELECT id FROM nodes WHERE kind = ?)').run(kind, kind);
+        this.db.prepare('DELETE FROM nodes WHERE kind = ?').run(kind);
+    }
     /** @implements A-SPEC-282 — every stored meta key/value. */
     readMeta() {
         const rows = this.db.prepare('SELECT key, value FROM meta').all();

package/dist/holmes/rtm/test-scope.js

@@ -172,7 +172,10 @@ const FRAMEWORKS = [
         suiteSkip: /\bdescribe\s*(?:\.\s*skip|\[\s*['"]skip['"]\s*\])|\bxdescribe\b/,
         // Head must be a STANDALONE identifier (not `.test(`/`.it(` method calls) followed directly by
         // `(` or by `.each(...)(`: `it.skip(`/`it.todo(`/`xit(` never match — no subtraction needed.
-        head: /(?<![.\w])(?:it|test|fit)(?:\s*\.\s*each\s*\([^)]*\)\s*)?\s*\(/g,
+        // @implements A-SPEC-653 — the platform helpers of A-SPEC-220.3 (`posixOnly('why')(…)`) are heads too:
+        // a POSIX-only suite written with the REPORTING skip must not read as "no real cases" (measured: that
+        // is why two suites had used a bare early return instead). `.skip` on a helper is still not a head.
+        head: /(?<![.\w])(?:it|test|fit|(?:posixOnly|posixOnlyNonRoot|posixOnlyWithCommand|win32Only)\s*\([^)]*\))(?:\s*\.\s*each\s*\([^)]*\)\s*)?\s*\(/g,
     },
     {
         id: 'pytest',

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

@@ -1,11 +1,26 @@
+/** Segment count at which a flushing writer attempts compaction (A-SPEC-630). */
+export declare const COMPACTION_THRESHOLD = 16;
+/** Age after which a compaction lock or an abandoned `.tmp` is considered orphaned by a dead writer. */
+export declare const STALE_MS: number;
 export declare class VectorCache {
     private readonly file;
+    private readonly dir;
+    private readonly lock;
     private store;
+    private readonly dirty;
     constructor(root: string);
     private load;
     private key;
     get(text: string, modelTag: string, kind: 'query' | 'doc'): number[] | null;
+    /** Stores in memory and marks the key for the next flush. A non-vector (empty or non-finite) is never stored. */
     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. */
+    /**
+     * Publish the entries put since the last flush as one immutable segment (unique tmp + rename), then
+     * compact if the segment count reached the threshold. Nothing dirty → nothing written. Publication
+     * errors propagate as before; compaction errors never do.
+     */
     flush(): void;
+    private acquireLock;
+    /** Merge base + segments FROM DISK into a new base under the lock; any failure leaves the segments in place. */
+    private compactIfNeeded;
 }

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

@@ -33,41 +33,117 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VectorCache = void 0;
+exports.VectorCache = exports.STALE_MS = exports.COMPACTION_THRESHOLD = void 0;
 // @implements A-SPEC-476
+// @implements A-SPEC-630
 /**
  * Content-addressed vector cache: never compute the same embedding twice, never serve a stale
- * vector across a model update.
+ * vector across a model update, and never let one writer erase another.
  *
  * 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).
+ * Persistence (A-SPEC-630) — segments, not snapshots. Every Holmes process that touches a
+ * workspace opens its own instance, and independent clones/worktrees/runs do so at the same time.
+ * The previous layout loaded one private snapshot and wrote it back whole through a fixed `.tmp`,
+ * so two writers erased each other (measured: A puts, B puts, A flushes, B flushes → A is gone)
+ * and simultaneous writers crashed on the shared temporary name. Now:
+ *
+ *   .ax/cpg_cache/semantic-vectors.json                 the base — legacy file, rewritten ONLY by compaction
+ *   .ax/cpg_cache/semantic-vectors.d/<ts>-<pid>-<rnd>.json  one immutable segment per flush, holding only
+ *                                                       the entries THIS instance put since its last flush
+ *   .ax/cpg_cache/semantic-vectors.d/*.tmp              a file still being written — readers never open it
+ *   .ax/cpg_cache/semantic-vectors.d/.compact.lock/     mkdir-owned compaction; stale after STALE_MS
+ *
+ * A reader merges base then segments in ascending name order (later wins), validating every entry:
+ * anything that is not a non-empty array of finite numbers is a miss, a file that does not parse
+ * contributes nothing, and load never throws. Publication is a unique tmp + rename, so a writer
+ * killed at any point leaves committed files untouched. Compaction is opportunistic: once the
+ * segment count reaches COMPACTION_THRESHOLD the flushing writer takes the lock, re-reads base and
+ * segments FROM DISK, writes the merged object over the base and deletes exactly the segments it
+ * merged. Its only failure mode is "not compacted" — never "lost".
+ *
+ * Measured (2026-09-13, macOS arm64, 5,000 × 1,024 floats = 46 MB): one file loads in 139 ms,
+ * 8–256 segments in 132–141 ms, per-entry files in 209 ms (and 407 ms to write vs 153 ms) —
+ * which is why the unit of publication is a flush, not an entry.
+ *
+ * The cache stays LOSABLE: it lives under `.ax/cpg_cache/` (derived, gitignored, protected — no
+ * gate surface moves) and 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');
+const SEGMENT_DIR = path.join('.ax', 'cpg_cache', 'semantic-vectors.d');
+const LOCK_DIR = '.compact.lock';
+/** Segment count at which a flushing writer attempts compaction (A-SPEC-630). */
+exports.COMPACTION_THRESHOLD = 16;
+/** Age after which a compaction lock or an abandoned `.tmp` is considered orphaned by a dead writer. */
+exports.STALE_MS = 10 * 60_000;
+const isVector = (v) => Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === 'number' && Number.isFinite(x));
+/** Parse one cache file into its valid entries; null when the file is unreadable, unparseable or not an object. */
+function readValid(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const out = {};
+    for (const [k, v] of Object.entries(parsed))
+        if (isVector(v))
+            out[k] = v;
+    return out;
+}
+function listSegments(dir) {
+    try {
+        return fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+    }
+    catch {
+        return [];
+    }
+}
+function isStale(p) {
+    try {
+        return Date.now() - fs.statSync(p).mtimeMs > exports.STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+// Segment names sort by (timestamp, pid, random). The timestamp is made strictly increasing within a
+// process so two flushes in the same millisecond keep a deterministic order — "later wins" must mean
+// the later flush, not the luckier random suffix.
+let lastStamp = 0;
+function segmentName() {
+    const now = Date.now();
+    lastStamp = now > lastStamp ? now : lastStamp + 1;
+    return `${String(lastStamp).padStart(15, '0')}-${String(process.pid).padStart(8, '0')}-${(0, node_crypto_1.randomBytes)(4).toString('hex')}.json`;
+}
 class VectorCache {
     file;
+    dir;
+    lock;
     store = null;
+    dirty = new Set();
     constructor(root) {
         this.file = path.join(root, FILE);
+        this.dir = path.join(root, SEGMENT_DIR);
+        this.lock = path.join(this.dir, LOCK_DIR);
     }
     load() {
         if (this.store !== null)
             return this.store;
-        try {
-            this.store = JSON.parse(fs.readFileSync(this.file, 'utf8'));
-        }
-        catch {
-            this.store = {};
-        }
-        return this.store;
+        const merged = readValid(this.file) ?? {};
+        for (const s of listSegments(this.dir))
+            Object.assign(merged, readValid(path.join(this.dir, s)) ?? {});
+        this.store = merged;
+        return merged;
     }
     key(text, modelTag, kind) {
         return `${(0, node_crypto_1.createHash)('sha256').update(text).digest('hex').slice(0, 24)}:${modelTag}:${kind}`;
@@ -75,17 +151,77 @@ class VectorCache {
     get(text, modelTag, kind) {
         return this.load()[this.key(text, modelTag, kind)] ?? null;
     }
+    /** Stores in memory and marks the key for the next flush. A non-vector (empty or non-finite) is never stored. */
     put(text, modelTag, kind, vector) {
-        this.load()[this.key(text, modelTag, kind)] = vector;
+        if (!isVector(vector))
+            return;
+        const k = this.key(text, modelTag, kind);
+        this.load()[k] = vector;
+        this.dirty.add(k);
     }
-    /** Atomic persist: tmp + rename, so a crash mid-write cannot corrupt the previous cache. */
+    /**
+     * Publish the entries put since the last flush as one immutable segment (unique tmp + rename), then
+     * compact if the segment count reached the threshold. Nothing dirty → nothing written. Publication
+     * errors propagate as before; compaction errors never do.
+     */
     flush() {
-        if (this.store === null)
+        if (this.store === null || this.dirty.size === 0)
             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);
+        const entries = {};
+        for (const k of this.dirty)
+            entries[k] = this.store[k];
+        fs.mkdirSync(this.dir, { recursive: true });
+        const name = segmentName();
+        const tmp = path.join(this.dir, `${name}.tmp`);
+        fs.writeFileSync(tmp, JSON.stringify(entries));
+        fs.renameSync(tmp, path.join(this.dir, name));
+        this.dirty.clear();
+        this.compactIfNeeded();
+    }
+    acquireLock() {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                fs.mkdirSync(this.lock);
+                fs.writeFileSync(path.join(this.lock, 'owner.json'), JSON.stringify({ pid: process.pid, ts: new Date().toISOString() }));
+                return true;
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST' || !isStale(this.lock))
+                    return false;
+                fs.rmSync(this.lock, { recursive: true, force: true }); // orphaned by a dead writer — break it once
+            }
+        }
+        return false;
+    }
+    /** Merge base + segments FROM DISK into a new base under the lock; any failure leaves the segments in place. */
+    compactIfNeeded() {
+        try {
+            if (listSegments(this.dir).length < exports.COMPACTION_THRESHOLD)
+                return;
+            if (!this.acquireLock())
+                return;
+            try {
+                const segments = listSegments(this.dir);
+                const merged = readValid(this.file) ?? {};
+                for (const s of segments)
+                    Object.assign(merged, readValid(path.join(this.dir, s)) ?? {});
+                const tmp = path.join(this.dir, `base-${segmentName()}.tmp`);
+                fs.writeFileSync(tmp, JSON.stringify(merged));
+                fs.renameSync(tmp, this.file);
+                for (const s of segments)
+                    fs.rmSync(path.join(this.dir, s), { force: true });
+                for (const f of fs.readdirSync(this.dir)) {
+                    if (f.endsWith('.tmp') && isStale(path.join(this.dir, f)))
+                        fs.rmSync(path.join(this.dir, f), { force: true });
+                }
+            }
+            finally {
+                fs.rmSync(this.lock, { recursive: true, force: true });
+            }
+        }
+        catch {
+            // Not compacted. Every committed segment is still there; a later flush will try again.
+        }
     }
 }
 exports.VectorCache = VectorCache;

package/dist/holmes/spec/approval-status.d.ts

@@ -18,6 +18,16 @@ export interface ApprovalStatus {
     parents: ParentApproval[];
     /** the concrete reasons this spec cannot be approved right now (empty once approved). */
     blockers: string[];
+    /**
+     * @implements A-SPEC-641 — what a RE-SEAL of this document as it stands would be refused on, by the
+     * gate's predicate (`approvalBlockers`): the same list as `blockers` for a draft, and for an approved
+     * document the reasons spec_approve, entity_renumber, entity_integrate and store recovery would refuse
+     * to seal it again. Measured 2026-09-14: a hand-sealed same-kind chain read `blockers: []` here while
+     * every re-seal refused it; 487 of 2,215 approved documents in this repository carry such a duty.
+     * Act-only judgements (duplicate ids, REQ acceptance substance, the OS-content cross-check that
+     * needs a root) are not included.
+     */
+    resealBlockers: string[];
 }
 /**
  * @implements A-SPEC-538.2