@holmes-lab/holmes-kit 0.19.6 → 0.20.0

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/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

package/dist/holmes/spec/approval-status.js

@@ -18,9 +18,12 @@ function describeApproval(spec, resolve) {
             ? { id: pid, status: parent.status, sealed: !!(0, spec_digest_1.sealOf)(parent).approvedDigest, resolved: true }
             : { id: pid, status: 'missing', sealed: false, resolved: false };
     });
-    // An approved spec has, by definition, cleared every blocker; recomputing would only re-report
-    // the placeholder/parent checks against a document that already passed them.
-    const blockers = spec.status === 'approved' ? [] : (0, approval_blockers_1.approvalBlockers)(spec, resolve);
+    // `blockers` keeps its meaning — what stands between this document and its approval — so an
+    // approved document reports none. The same predicate evaluated on the document AS IT STANDS is
+    // what a re-seal would be refused on; a document sealed by hand never passed it, and the acts
+    // that re-seal (renumber, integration, re-approval) judge exactly this list (A-SPEC-641).
+    const resealBlockers = (0, approval_blockers_1.approvalBlockers)(spec, resolve);
+    const blockers = spec.status === 'approved' ? [] : resealBlockers;
     return {
         id: spec.id,
         type: spec.type,
@@ -29,5 +32,6 @@ function describeApproval(spec, resolve) {
         approvedDigest: seal.approvedDigest,
         parents,
         blockers,
+        resealBlockers,
     };
 }

package/dist/holmes/spec/entity-git-snapshot.d.ts

@@ -0,0 +1,50 @@
+export interface EntityGitSnapshot {
+    schema: 'holmes-entity-git-snapshot/1';
+    commit: string;
+    tree: string;
+    workspacePrefix: string;
+    workspaceId: string;
+    storeId: string;
+    storeLocator: string;
+    /** Names occupied outside the selected store; immutable reads always populate this inventory. */
+    otherStoreDisplayIds?: string[];
+    entities: Array<{
+        entityId: string;
+        displayId: string;
+        documentLocator: string;
+        recordLocator: string;
+        documentBlob: string;
+        recordBlob: string;
+        document: string;
+        record: string;
+    }>;
+    files: Array<{
+        path: string;
+        mode: string;
+        oid: string;
+    }>;
+}
+export interface EntityGitInputs {
+    base: EntityGitSnapshot;
+    left: EntityGitSnapshot;
+    right: EntityGitSnapshot;
+}
+/** Version of the workspace-scoped logical stage inventory, not the on-disk index bytes/stat cache. */
+export declare function readEntityGitIndex(root: string): {
+    version: string;
+    entries: Array<{
+        path: string;
+        mode: string;
+        oid: string;
+        stage: number;
+    }>;
+};
+/** Binary-safe object reads; names, paths and replace refs cannot redirect an OID request. */
+export declare function readEntityGitBlobs(root: string, oids: string[]): Map<string, Buffer>;
+export declare function readEntityGitInputs(root: string, revisions: {
+    base: string;
+    left: string;
+    right: string;
+}, storeLocator: string): EntityGitInputs;
+/** Read immutable objects only; dirty files, local identity and Git replace refs are not input truth. */
+export declare function readEntityGitSnapshot(root: string, revision: string, storeLocator: string): EntityGitSnapshot;

package/dist/holmes/spec/entity-git-snapshot.js

@@ -0,0 +1,276 @@
+"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.readEntityGitIndex = readEntityGitIndex;
+exports.readEntityGitBlobs = readEntityGitBlobs;
+exports.readEntityGitInputs = readEntityGitInputs;
+exports.readEntityGitSnapshot = readEntityGitSnapshot;
+// @implements A-SPEC-629.1, A-SPEC-629
+// @implements A-SPEC-636
+// @implements A-SPEC-637
+const fs = __importStar(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const spec_parser_1 = require("./spec-parser");
+const entity_transaction_1 = require("./entity-transaction");
+/** Version of the workspace-scoped logical stage inventory, not the on-disk index bytes/stat cache. */
+function readEntityGitIndex(root) {
+    const git = gitReader(root);
+    const prefix = utf8(git(['rev-parse', '--show-prefix'])).replace(/\n$/, '');
+    if (prefix && (!prefix.endsWith('/') || !locator(prefix.slice(0, -1))))
+        fail('Unsafe workspace prefix.');
+    const bytes = git(['ls-files', '--stage', '-z', '--full-name']);
+    const entries = [];
+    const seen = new Set();
+    for (const entry of utf8(bytes).split('\0')) {
+        if (!entry)
+            continue;
+        const tab = entry.indexOf('\t'), header = entry.slice(0, tab).split(' '), fullPath = entry.slice(tab + 1);
+        if (tab < 0 || header.length !== 3 || !/^[0-7]{6}$/.test(header[0]) || !OID.test(header[1]) || !/^[0-3]$/.test(header[2]) || !locator(fullPath) || !fullPath.startsWith(prefix))
+            fail('Malformed Git index inventory.');
+        const file = fullPath.slice(prefix.length), key = header[2] + ':' + file;
+        if (!locator(file) || seen.has(key))
+            fail('Unsafe or duplicate Git index entry.');
+        seen.add(key);
+        entries.push({ path: file, mode: header[0], oid: header[1], stage: Number(header[2]) });
+    }
+    return { version: 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(prefix).update('\0').update(bytes).digest('hex'), entries };
+}
+/** Binary-safe object reads; names, paths and replace refs cannot redirect an OID request. */
+function readEntityGitBlobs(root, oids) {
+    if (!Array.isArray(oids) || oids.some(oid => typeof oid !== 'string' || !OID.test(oid)))
+        fail('Git blob reads require immutable object OIDs.');
+    const ids = [...new Set(oids)], blobs = new Map();
+    if (!ids.length)
+        return blobs;
+    const output = gitReader(root)(['cat-file', '--batch'], ids.join('\n') + '\n');
+    let offset = 0;
+    for (const oid of ids) {
+        const end = output.indexOf(10, offset);
+        if (end < 0)
+            fail('Truncated Git blob response.');
+        const header = output.subarray(offset, end).toString('ascii').split(' '), size = Number(header[2]);
+        if (header.length !== 3 || header[0] !== oid || header[1] !== 'blob' || !Number.isSafeInteger(size) || size < 0 || end + 1 + size >= output.length || output[end + 1 + size] !== 10)
+            fail('Invalid or missing Git blob response.');
+        blobs.set(oid, output.subarray(end + 1, end + 1 + size));
+        offset = end + size + 2;
+    }
+    if (offset !== output.length)
+        fail('Unexpected trailing Git blob response.');
+    return blobs;
+}
+function readEntityGitInputs(root, revisions, storeLocator) {
+    if (!revisions || typeof revisions !== 'object' || Object.keys(revisions).length !== 3 || !['base', 'left', 'right'].every(key => Object.prototype.hasOwnProperty.call(revisions, key)))
+        fail('Expected exactly base, left and right revisions.');
+    const git = gitReader(root);
+    // Pin all names before loading any tree; subsequent checks never resolve the names again.
+    const commits = { base: resolveCommit(git, revisions.base), left: resolveCommit(git, revisions.left), right: resolveCommit(git, revisions.right) };
+    for (const side of [commits.left, commits.right])
+        git(['merge-base', '--is-ancestor', commits.base, side], undefined, 'Selected base is not a proven ancestor of both Git inputs.');
+    // @implements A-SPEC-636 — a refusal caused by one input names that side and its commit.
+    const sideSnapshot = (side) => {
+        try {
+            return readEntityGitSnapshot(root, commits[side], storeLocator);
+        }
+        catch (error) {
+            if (error instanceof entity_transaction_1.EntityStoreError && error.code === 'invalid-git-snapshot')
+                throw new entity_transaction_1.EntityStoreError('invalid-git-snapshot', side + ' ' + commits[side] + ': ' + error.message);
+            throw error;
+        }
+    };
+    const inputs = { base: sideSnapshot('base'), left: sideSnapshot('left'), right: sideSnapshot('right') };
+    for (const side of [inputs.left, inputs.right]) {
+        if (side.workspaceId !== inputs.base.workspaceId)
+            fail('Git inputs have different canonical workspace identity.');
+        if (side.storeId !== inputs.base.storeId)
+            fail('Git inputs have different canonical store identity.');
+    }
+    return inputs;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const OID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+function fail(message) { throw new entity_transaction_1.EntityStoreError('invalid-git-snapshot', message); }
+function locator(value) {
+    return typeof value === 'string' && value.length > 0 && !/[\\:\x00]/.test(value) && value.split('/').every(part => part && part !== '.' && part !== '..');
+}
+function uuid(value) { return typeof value === 'string' && UUID.test(value); }
+function object(text, keys) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return fail('Canonical record contains invalid JSON.');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length !== keys.length || keys.some(key => !Object.prototype.hasOwnProperty.call(value, key)))
+        fail('Unsupported canonical record schema or fields.');
+    return value;
+}
+function utf8(bytes) {
+    const text = bytes.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(bytes))
+        fail('Unsupported non-UTF-8 canonical bytes or path.');
+    return text;
+}
+function gitReader(root) {
+    const cwd = fs.realpathSync(root);
+    // A caller's Git environment must not redirect a root-bound read to another repository or index.
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+    env.GIT_NO_REPLACE_OBJECTS = '1';
+    env.GIT_OPTIONAL_LOCKS = '0';
+    return (args, input, failure = 'Git snapshot read failed: unavailable revision/object, unsupported repository or 64 MiB response limit.') => {
+        try {
+            return (0, node_child_process_1.execFileSync)('git', ['-C', cwd, ...args], { env, input, maxBuffer: 64 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] });
+        }
+        catch {
+            return fail(failure);
+        }
+    };
+}
+function resolveCommit(git, revision) {
+    if (typeof revision !== 'string' || !revision || /^-/.test(revision) || /[\x00\r\n]/.test(revision))
+        fail('Unsafe Git revision.');
+    const commit = utf8(git(['rev-parse', '--verify', '--end-of-options', revision + '^{commit}'])).trim();
+    if (!OID.test(commit))
+        fail('Git revision did not resolve to a commit object.');
+    return commit;
+}
+/** Read immutable objects only; dirty files, local identity and Git replace refs are not input truth. */
+function readEntityGitSnapshot(root, revision, storeLocator) {
+    if (!locator(storeLocator))
+        fail('Unsafe store locator.');
+    const git = gitReader(root), commit = resolveCommit(git, revision);
+    const tree = utf8(git(['rev-parse', '--verify', '--end-of-options', commit + '^{tree}'])).trim();
+    if (!OID.test(tree))
+        fail('Git commit has no supported tree object.');
+    const workspacePrefix = utf8(git(['rev-parse', '--show-prefix'])).replace(/\n$/, '');
+    if (workspacePrefix && (!workspacePrefix.endsWith('/') || !locator(workspacePrefix.slice(0, -1))))
+        fail('Unsafe workspace prefix.');
+    const files = [];
+    for (const entry of utf8(git(['ls-tree', '-r', '-z', '--full-tree', commit])).split('\0')) {
+        if (!entry)
+            continue;
+        const tab = entry.indexOf('\t'), header = entry.slice(0, tab).split(' '), fullPath = entry.slice(tab + 1);
+        if (tab < 0 || header.length !== 3 || !OID.test(header[2]) || !locator(fullPath))
+            fail('Malformed Git tree inventory.');
+        if (!fullPath.startsWith(workspacePrefix))
+            continue;
+        const file = fullPath.slice(workspacePrefix.length);
+        if (!locator(file))
+            fail('Unsafe workspace file locator.');
+        // @implements A-SPEC-637 — gitlinks enter the inventory (mode 160000) so the planner can exclude or refuse them.
+        const gitlink = header[1] === 'commit' && header[0] === '160000';
+        if (!gitlink && (header[1] !== 'blob' || !['100644', '100755', '120000'].includes(header[0])))
+            fail('Unsupported Git tree object mode: ' + file);
+        files.push({ path: file, mode: header[0], oid: header[2] });
+    }
+    files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const byPath = new Map(files.map(file => [file.path, file]));
+    if (byPath.size !== files.length)
+        fail('Duplicate Git file inventory.');
+    const regular = (file) => {
+        const entry = byPath.get(file);
+        if (!entry)
+            return fail('Missing canonical document or mapping: ' + file);
+        if (!['100644', '100755'].includes(entry.mode))
+            fail('Canonical document/mapping requires regular mode, not a symlink: ' + file);
+        return entry;
+    };
+    const blobs = new Map();
+    const read = (paths) => {
+        const ids = [...new Set(paths.map(file => regular(file).oid))].filter(oid => !blobs.has(oid));
+        for (const [oid, bytes] of readEntityGitBlobs(root, ids))
+            blobs.set(oid, utf8(bytes));
+    };
+    const text = (file) => {
+        const value = blobs.get(regular(file).oid);
+        if (value === undefined)
+            return fail('Canonical blob was not loaded: ' + file);
+        return value;
+    };
+    const registrations = files.filter(file => /^\.ax\/entities\/stores\/[^/]+\.json$/.test(file.path));
+    const recordFiles = files.filter(file => /^\.ax\/entities\/records\/[^/]+\.json$/.test(file.path));
+    read(['.ax/workspace.json', ...registrations.map(file => file.path), ...recordFiles.map(file => file.path)]);
+    const manifest = object(text('.ax/workspace.json'), ['schema', 'workspaceId']);
+    if (manifest.schema !== 'holmes-workspace/1' || !uuid(manifest.workspaceId))
+        fail('Unsupported canonical workspace identity.');
+    const stores = new Map(), storePaths = new Set();
+    for (const file of registrations) {
+        const registration = object(text(file.path), ['schema', 'workspaceId', 'storeId', 'storeLocator', 'adoptionDigest']);
+        if (registration.schema !== 'holmes-entity-store/1' || registration.workspaceId !== manifest.workspaceId || !uuid(registration.storeId) || file.path !== '.ax/entities/stores/' + registration.storeId + '.json' || !locator(registration.storeLocator) || typeof registration.adoptionDigest !== 'string' || !DIGEST.test(registration.adoptionDigest) || storePaths.has(registration.storeLocator))
+            fail('Invalid or duplicate store registration mapping.');
+        stores.set(registration.storeId, registration.storeLocator);
+        storePaths.add(registration.storeLocator);
+    }
+    const selected = [...stores].find(([, value]) => value === storeLocator);
+    if (!selected)
+        fail('Configured store has no canonical adoption mapping.');
+    const selectedRecords = [];
+    const ids = new Set(), documents = new Set(), otherStoreDisplayIds = new Set();
+    for (const file of recordFiles) {
+        const record = object(text(file.path), ['schema', 'workspaceId', 'storeId', 'entityId', 'displayId', 'documentLocator', 'origin']);
+        const origin = object(JSON.stringify(record.origin), ['kind', 'operationId']);
+        if (record.schema !== 'holmes-entity/1' || record.workspaceId !== manifest.workspaceId || !uuid(record.entityId) || file.path !== '.ax/entities/records/' + record.entityId + '.json' || !uuid(record.storeId) || !stores.has(record.storeId) || typeof record.displayId !== 'string' || !record.displayId || !locator(record.documentLocator) || !record.documentLocator.endsWith('.md') || !['adopted', 'created'].includes(String(origin.kind)) || !uuid(origin.operationId))
+            fail('Invalid entity document mapping.');
+        if (record.storeId !== selected[0]) {
+            otherStoreDisplayIds.add(record.displayId);
+            continue;
+        }
+        if (ids.has(record.displayId) || documents.has(record.documentLocator))
+            fail('Duplicate display ID or document mapping.');
+        ids.add(record.displayId);
+        documents.add(record.documentLocator);
+        selectedRecords.push({ entityId: record.entityId, displayId: record.displayId, documentLocator: record.documentLocator, recordLocator: file.path });
+    }
+    const documentFiles = files.filter(file => file.path.startsWith(storeLocator + '/') && file.path.endsWith('.md'));
+    if (documentFiles.length !== selectedRecords.length || documentFiles.some(file => !documents.has(file.path.slice(storeLocator.length + 1))))
+        fail('Document inventory differs from canonical entity mappings.');
+    read(selectedRecords.map(record => storeLocator + '/' + record.documentLocator));
+    const entities = selectedRecords.map(record => {
+        const documentPath = storeLocator + '/' + record.documentLocator, document = text(documentPath);
+        let parsed;
+        try {
+            parsed = (0, spec_parser_1.parseSpec)(document);
+        }
+        catch {
+            return fail('Unparseable canonical document: ' + documentPath);
+        }
+        if (parsed.id !== record.displayId)
+            fail('Document ID differs from its entity mapping: ' + documentPath);
+        return { ...record, documentBlob: regular(documentPath).oid, recordBlob: regular(record.recordLocator).oid, document, record: text(record.recordLocator) };
+    }).sort((a, b) => a.entityId < b.entityId ? -1 : a.entityId > b.entityId ? 1 : 0);
+    return { schema: 'holmes-entity-git-snapshot/1', commit, tree, workspacePrefix, workspaceId: manifest.workspaceId, storeId: selected[0], storeLocator, entities, files, otherStoreDisplayIds: [...otherStoreDisplayIds].sort() };
+}