@holmes-lab/holmes-kit 0.19.5 → 0.20.0

package/dist/holmes/governance/approval-grants.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GRANTS_RELDIR = void 0;
 exports.readGrants = readGrants;
+exports.refusedGrantReasons = refusedGrantReasons;
 exports.pickCoveringGrant = pickCoveringGrant;
 exports.resolveApproval = resolveApproval;
 exports.consumeGrantFile = consumeGrantFile;
@@ -42,6 +43,8 @@ exports.consumeGrantFile = consumeGrantFile;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const risk_gate_1 = require("../guardrail/risk-gate");
+const workspace_identity_1 = require("../project/workspace-identity");
+const approval_queue_1 = require("./approval-queue");
 /**
  * The grant file channel — approval delivery with no file editing and no reconnect.
  *
@@ -102,6 +105,47 @@ function readGrants(root) {
     }
     return { grants, ignored };
 }
+/** The current workspace id, or undefined for a legacy workspace / an unreadable identity. */
+function currentWorkspaceId(root) {
+    try {
+        const id = (0, workspace_identity_1.workspaceIdentity)(root, 'status');
+        return id.state === 'legacy' ? undefined : id.workspaceId;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Why this grant must NOT cover this action here, or null. Measured 2026-09-14 on the shipped dist:
+ * a grant file copied into another workspace with the same request id sealed there, and a grant
+ * read against one spec body sealed a different one. A grant that names a workspace is refused in
+ * any other (or in a workspace with no identity to compare); a grant that names a subject is
+ * refused when the action NAMES a subject and it differs. An action that names no subject is
+ * judged by its consumer at the point where the subject is known: `spec_approve` compares the
+ * grant's subject with the digest of its ONE versioned read (an extra read here to learn the
+ * subject moved the optimistic-write window and let an external edit be sealed — measured by the
+ * A-SPEC-188 TOCTOU pin), and every other decision kind carries a content-addressed target.
+ */
+function bindingRefusal(grant, action, workspace) {
+    if (typeof grant.workspace === 'string' && grant.workspace !== '' && grant.workspace !== workspace)
+        return 'foreign-workspace';
+    if (typeof grant.subject === 'string' && grant.subject !== '' && action.subject !== undefined && grant.subject !== action.subject)
+        return 'stale-subject';
+    return null;
+}
+/** @implements A-SPEC-649 — the grants that WOULD cover this action but are refused by their binding, by name. */
+function refusedGrantReasons(root, action, now) {
+    const workspace = currentWorkspaceId(root);
+    const out = [];
+    for (const g of readGrants(root).grants) {
+        if (!(0, risk_gate_1.approvalCovers)(g, action, now))
+            continue;
+        const reason = bindingRefusal(g, action, workspace);
+        if (reason && typeof g.nonce === 'string')
+            out.push({ nonce: g.nonce, reason });
+    }
+    return out;
+}
 /** First grant that covers the action — judged by `approvalCovers` and nothing else. Pure. */
 function pickCoveringGrant(grants, action, now) {
     for (const g of Array.isArray(grants) ? grants : []) {
@@ -120,7 +164,9 @@ function pickCoveringGrant(grants, action, now) {
 function resolveApproval(root, envApproval, action, now) {
     if ((0, risk_gate_1.approvalCovers)(envApproval, action, now))
         return { approval: envApproval, source: 'env' };
-    const grant = pickCoveringGrant(readGrants(root).grants, action, now);
+    // @implements A-SPEC-649 — a bound grant is a candidate only in its own workspace and for its own subject.
+    const workspace = currentWorkspaceId(root);
+    const grant = pickCoveringGrant(readGrants(root).grants.filter((g) => bindingRefusal(g, action, workspace) === null), action, now);
     return grant ? { approval: grant, source: 'grant' } : undefined;
 }
 /**
@@ -157,6 +203,14 @@ function consumeGrantFile(root, nonce) {
         // No directory, or it cannot be read: there is nothing to spend, which is an ordinary state.
         return;
     }
+    // @implements A-SPEC-649 — the spend is a queue event too, so the decision surface can show the
+    // grant's outcome without reading the provenance ledger. Best-effort, like the removal itself.
+    if (removed > 0) {
+        try {
+            (0, approval_queue_1.appendQueueEvent)(root, { event: 'consumed', id: wanted });
+        }
+        catch { /* fire-and-forget */ }
+    }
     if (removed === 0) {
         // Consumption runs AFTER the act succeeded, so this must never throw — but it must not be silent
         // either: an unspent single-use grant is still spendable, and nobody would know.

package/dist/holmes/governance/approval-queue.d.ts

@@ -1,3 +1,4 @@
+import { ExecutionContext } from '../project/execution-context';
 /**
  * The approval request queue — the review list a human batches decisions over.
  *
@@ -53,6 +54,17 @@ export interface PendingRequest {
      * reads it, so an absent or wrong value can never change a verdict.
      */
     replica?: string;
+    /**
+     * @implements A-SPEC-649
+     * What the FIRST `requested` event of this id said about itself: the execution that asked
+     * (workspace/replica/run — absent for the CLI, hooks and legacy events), the digest of the subject
+     * the human will read (`spec-approve`: `specDigest` of the spec as read), and the risk grade. A
+     * grant minted from this entry copies `subject` so a seal of DIFFERENT content is refused — measured
+     * 2026-09-14: a grant read against "Original title" sealed "CHANGED after the grant".
+     */
+    execution?: ExecutionContext;
+    subject?: string;
+    risk?: string;
 }
 export interface QueueState {
     pending: PendingRequest[];
@@ -75,10 +87,24 @@ export interface QueueState {
      * An invisible decision cannot stop a retry loop.
      */
     decisions: Record<string, {
-        event: 'granted' | 'denied';
+        event: 'granted' | 'denied' | 'revoked';
         reason?: string;
         ts: string;
         covered?: number;
+        execution?: ExecutionContext;
+        consumedTs?: string;
+        expires?: string;
+        actor?: string;
+    }>;
+    /**
+     * @implements A-SPEC-650
+     * kind/target per request id, for EVERY `requested` event the fold saw (first wins) — the decision
+     * surface names what a past decision was about without re-reading the file. Present only when at
+     * least one request was seen, so the empty-state pins (A-SPEC-244) keep their exact shape.
+     */
+    subjects?: Record<string, {
+        kind: string;
+        target: string;
     }>;
     /**
      * @implements A-SPEC-563.2
@@ -89,6 +115,7 @@ export interface QueueState {
     holds: Record<string, {
         question?: string;
         ts: string;
+        execution?: ExecutionContext;
     }>;
 }
 /**
@@ -121,12 +148,17 @@ export declare function foldQueue(lines: string[], opts?: {
  * dead queue could change a verdict, killing the queue becomes a way to manipulate the gate. The
  * caller uses the boolean only to decide whether to print the review hint.
  */
+/** @implements A-SPEC-649 — what a request may say about its subject and risk, beyond kind/target/why. */
+export interface RequestDetails {
+    subject?: string;
+    risk?: string;
+}
 export declare function enqueueApprovalRequest(root: string, req: {
     kind: string;
     target: string;
     why: string;
     reasonBytes?: number;
-}): boolean;
+} & RequestDetails): boolean;
 /**
  * The same act, told in full: what happened and why.
  *
@@ -140,10 +172,17 @@ export declare function enqueueApprovalRequestDetailed(root: string, req: {
     target: string;
     why: string;
     reasonBytes?: number;
-}): {
+} & RequestDetails): {
     written: boolean;
     reason: 'written' | 'duplicate' | 'no-project' | 'unwritable';
 };
+/**
+ * @implements A-SPEC-649
+ * Append a lifecycle event (`consumed`, `revoked`) to the tracked queue: `.ax` must exist, the
+ * queue must be a plain file, the timestamp is this write's, and the active execution (if any) is
+ * attached — the same discipline as the CLI's decision writer. Fire-and-forget: `false` on failure.
+ */
+export declare function appendQueueEvent(root: string, event: Record<string, unknown>): boolean;
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
 export declare function readQueue(root: string, opts?: {
     now?: number;
@@ -160,6 +199,6 @@ export declare function queueHint(root: string, req: {
     kind: string;
     target: string;
     why: string;
-}, opts?: {
+} & RequestDetails, opts?: {
     baseReasonBytes?: number;
 }): string;

package/dist/holmes/governance/approval-queue.js

@@ -41,9 +41,12 @@ exports.approvalRequestId = approvalRequestId;
 exports.foldQueue = foldQueue;
 exports.enqueueApprovalRequest = enqueueApprovalRequest;
 exports.enqueueApprovalRequestDetailed = enqueueApprovalRequestDetailed;
+exports.appendQueueEvent = appendQueueEvent;
 exports.readQueue = readQueue;
 exports.queueHint = queueHint;
-// @implements A-SPEC-244
+// @implements A-SPEC-244, A-SPEC-626
+const execution_context_1 = require("../project/execution-context");
+const root_1 = require("../project/root");
 const node_crypto_1 = require("node:crypto");
 const npx_bin_1 = require("../project/npx-bin");
 const fs = __importStar(require("node:fs"));
@@ -145,6 +148,7 @@ function foldQueue(lines, opts) {
     const pending = new Map();
     const decisions = {};
     const holds = {};
+    const subjects = {};
     let malformedLines = 0;
     for (const raw of Array.isArray(lines) ? lines : []) {
         const line = String(raw ?? '').trim();
@@ -163,6 +167,16 @@ function foldQueue(lines, opts) {
             malformedLines++;
             continue;
         }
+        let execution;
+        if ('execution' in e) {
+            try {
+                execution = (0, execution_context_1.validateExecution)(e.execution);
+            }
+            catch {
+                malformedLines++;
+                continue;
+            }
+        }
         const id = typeof e.id === 'string' ? e.id : undefined;
         switch (e.event) {
             case 'requested': {
@@ -170,6 +184,10 @@ function foldQueue(lines, opts) {
                     malformedLines++;
                     break;
                 }
+                // @implements A-SPEC-650 — remembered for every kind, before the inbox filter: a decided shell
+                // refusal still has a subject to show on the status surface.
+                if (!subjects[id])
+                    subjects[id] = { kind: String(e.kind ?? ''), target: String(e.target ?? '') };
                 // @implements A-SPEC-576.1 — the READER applies the writer's predicate.
                 // REQ-563 routed gate refusals away from the inbox and deliberately did NOT rewrite the
                 // 2,192 lines already written; append-only is the rule this ledger is worth something for.
@@ -198,6 +216,10 @@ function foldQueue(lines, opts) {
                         // @implements A-SPEC-562.2 — events written before attribution existed have no field;
                         // `unknown` names that honestly instead of pretending they came from this machine.
                         replica: typeof e.replica === 'string' && e.replica !== '' ? e.replica : 'unknown',
+                        // @implements A-SPEC-649 — the details ride the first filing; a repeat never rewrites them.
+                        ...(execution ? { execution } : {}),
+                        ...(typeof e.subject === 'string' && e.subject !== '' ? { subject: e.subject } : {}),
+                        ...(typeof e.risk === 'string' && e.risk !== '' ? { risk: e.risk } : {}),
                     });
                 }
                 break;
@@ -212,9 +234,28 @@ function foldQueue(lines, opts) {
                         ...(typeof e.reason === 'string' ? { reason: e.reason } : {}),
                         ts: typeof e.ts === 'string' ? e.ts : '',
                         ...(typeof e.covered === 'number' ? { covered: e.covered } : {}),
+                        ...(execution ? { execution } : {}),
+                        // @implements A-SPEC-650 — when a grant expires and who decided, for the outcome rows.
+                        ...(typeof e.expires === 'string' ? { expires: e.expires } : {}),
+                        ...(typeof e.actor === 'string' ? { actor: e.actor } : {}),
                     };
                 }
                 break;
+            // @implements A-SPEC-649 — the grant's later life, in the same ledger the screen reads.
+            // `consumed`: the act the grant authorized succeeded (written by consumeGrantFile) — the
+            // decision keeps its `granted` shape and gains the consumption time. `revoked`: the operator
+            // withdrew a live grant — a decision like any other (pending cleared, the hold answered).
+            case 'consumed':
+                if (id)
+                    decisions[id] = { ...(decisions[id] ?? { event: 'granted', ts: typeof e.ts === 'string' ? e.ts : '' }), consumedTs: typeof e.ts === 'string' ? e.ts : '' };
+                break;
+            case 'revoked':
+                if (id) {
+                    pending.delete(id);
+                    delete holds[id];
+                    decisions[id] = { event: 'revoked', ...(typeof e.reason === 'string' ? { reason: e.reason } : {}), ts: typeof e.ts === 'string' ? e.ts : '', ...(execution ? { execution } : {}) };
+                }
+                break;
             case 'held': {
                 const entry = id ? pending.get(id) : undefined;
                 if (entry) {
@@ -225,7 +266,7 @@ function foldQueue(lines, opts) {
                 // @implements A-SPEC-563.2 — record the hold by id too: a refusal-log request has no pending
                 // entry to hang the question on, and the question must still reach the retry.
                 if (id)
-                    holds[id] = { ...(typeof e.question === 'string' ? { question: e.question } : {}), ts: typeof e.ts === 'string' ? e.ts : '' };
+                    holds[id] = { ...(typeof e.question === 'string' ? { question: e.question } : {}), ts: typeof e.ts === 'string' ? e.ts : '', ...(execution ? { execution } : {}) };
                 break;
             }
             default:
@@ -236,8 +277,9 @@ function foldQueue(lines, opts) {
     const all = [...pending.values()];
     const ttl = typeof opts?.ttlMs === 'number' && typeof opts?.now === 'number'
         ? { ttlMs: opts.ttlMs, now: opts.now } : null;
+    const withSubjects = Object.keys(subjects).length > 0 ? { subjects } : {};
     if (ttl === null)
-        return { pending: all, expired: [], malformedLines, decisions, holds };
+        return { pending: all, expired: [], malformedLines, decisions, holds, ...withSubjects };
     // @implements A-SPEC-507.1 — strict excess only, and an unparseable lastTs stays ACTIVE: a
     // clockless entry must never be silently hidden by a clock it does not carry.
     const expired = [];
@@ -246,16 +288,8 @@ function foldQueue(lines, opts) {
         const last = Date.parse(p.lastTs);
         (Number.isFinite(last) && last + ttl.ttlMs < ttl.now ? expired : active).push(p);
     }
-    return { pending: active, expired, malformedLines, decisions, holds };
+    return { pending: active, expired, malformedLines, decisions, holds, ...withSubjects };
 }
-/**
- * Append a request event. Fire-and-forget.
- *
- * @implements A-SPEC-244
- * Every failure is swallowed into `false`: this runs INSIDE gate verdict paths, and the moment a
- * dead queue could change a verdict, killing the queue becomes a way to manipulate the gate. The
- * caller uses the boolean only to decide whether to print the review hint.
- */
 function enqueueApprovalRequest(root, req) {
     return enqueueApprovalRequestDetailed(root, req).written;
 }
@@ -298,6 +332,15 @@ function enqueueApprovalRequestDetailed(root, req) {
         catch {
             replica = undefined;
         }
+        // @implements A-SPEC-649 — the requesting execution, when this write happens inside a handler run
+        // (absent for hooks, the CLI and a foreign root — never guessed).
+        let execution;
+        try {
+            execution = (0, execution_context_1.executionForRoot)(root);
+        }
+        catch {
+            execution = undefined;
+        }
         const event = {
             event: 'requested',
             id: approvalRequestId(req.kind, req.target),
@@ -306,6 +349,9 @@ function enqueueApprovalRequestDetailed(root, req) {
             why: req.why,
             ts: new Date().toISOString(),
             ...(replica !== undefined && replica !== '' ? { replica } : {}),
+            ...(execution ? { execution } : {}),
+            ...(typeof req.subject === 'string' && req.subject !== '' ? { subject: req.subject } : {}),
+            ...(typeof req.risk === 'string' && req.risk !== '' ? { risk: req.risk } : {}),
             // @implements A-SPEC-564.2 — only the refusal log carries the feedback cost; inbox kinds have
             // no deny text to measure.
             ...(!exports.DECISION_KINDS.has(req.kind) && typeof req.reasonBytes === 'number' && Number.isFinite(req.reasonBytes)
@@ -362,6 +408,34 @@ function isPlainFile(file) {
         return true;
     }
 }
+/**
+ * @implements A-SPEC-649
+ * Append a lifecycle event (`consumed`, `revoked`) to the tracked queue: `.ax` must exist, the
+ * queue must be a plain file, the timestamp is this write's, and the active execution (if any) is
+ * attached — the same discipline as the CLI's decision writer. Fire-and-forget: `false` on failure.
+ */
+function appendQueueEvent(root, event) {
+    try {
+        let execution;
+        try {
+            execution = (0, execution_context_1.executionForRoot)((0, root_1.resolveProjectRoot)(root).root);
+        }
+        catch {
+            execution = undefined;
+        }
+        const file = path.join(root, exports.QUEUE_RELPATH);
+        if (!fs.existsSync(path.join(root, '.ax')))
+            return false;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        if (!isPlainFile(file))
+            return false;
+        fs.appendFileSync(file, JSON.stringify({ ...event, ts: new Date().toISOString(), ...(execution ? { execution } : {}) }) + '\n');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Read and fold the queue on disk. A missing file is an empty queue, not an error. */
 function readQueue(root, opts) {
     const file = path.join(root, exports.QUEUE_RELPATH);

package/dist/holmes/governance/display-id-aliases.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Display-id history, read from the ledger's rename records.
+ *
+ * The entity model keeps identity immutable and the display id mutable, and every official rename is
+ * already in the ledger: `entity-renumbered` (inputs `entity:<uuid>`, `old-id:<X>`, `new-id:<Y>`), the
+ * legacy `spec-renumbered` (`X->Y`), and `entity-integrated` (same `old-id:`/`new-id:` form for the
+ * mapping steps an integration renumbers). Measured 2026-09-14: evidence consumers keyed by display id
+ * lost a renumbered document's red-first outcomes and timeline entirely. This module is the one place
+ * that turns those records into aliases; it reads only recorded renames and infers nothing.
+ */
+export interface DisplayIdRename {
+    oldId: string;
+    newId: string;
+    ts: string;
+}
+type RenameEvent = {
+    kind: string;
+    ts: string;
+    inputs?: string[];
+};
+/** Every recorded rename as an ordered pair, in ledger order (ts, then input order). */
+export declare function displayIdRenames(events: ReadonlyArray<RenameEvent>): DisplayIdRename[];
+/** The display ids an entity has carried, as the connected component of `id` over recorded renames. */
+export declare function aliasesOf(events: ReadonlyArray<RenameEvent>, id: string): string[];
+/** The display id the entity carries now: recorded renames applied forward from `id`, in ledger order. */
+export declare function currentDisplayId(events: ReadonlyArray<RenameEvent>, id: string): string;
+/** One pass over the renames, then memoized answers — for consumers that canonicalize many ids. */
+export declare function displayIdCanonicalizer(events: ReadonlyArray<RenameEvent>): (id: string) => string;
+export {};

package/dist/holmes/governance/display-id-aliases.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.displayIdRenames = displayIdRenames;
+exports.aliasesOf = aliasesOf;
+exports.currentDisplayId = currentDisplayId;
+exports.displayIdCanonicalizer = displayIdCanonicalizer;
+const RENAME_KINDS = new Set(['entity-renumbered', 'entity-integrated']);
+const ARROW = /^(\S+)->(\S+)$/;
+/** Every recorded rename as an ordered pair, in ledger order (ts, then input order). */
+function displayIdRenames(events) {
+    const indexed = events.map((e, i) => ({ e, i }));
+    indexed.sort((a, b) => (a.e.ts < b.e.ts ? -1 : a.e.ts > b.e.ts ? 1 : a.i - b.i));
+    const out = [];
+    for (const { e } of indexed) {
+        const inputs = e.inputs ?? [];
+        if (RENAME_KINDS.has(e.kind)) {
+            // An `old-id:` is paired with the next `new-id:` that follows it; an unpaired one is ignored.
+            let pending = null;
+            for (const input of inputs) {
+                if (input.startsWith('old-id:')) {
+                    pending = input.slice('old-id:'.length) || null;
+                    continue;
+                }
+                if (input.startsWith('new-id:')) {
+                    const newId = input.slice('new-id:'.length);
+                    if (pending && newId && newId !== pending)
+                        out.push({ oldId: pending, newId, ts: e.ts });
+                    pending = null;
+                }
+            }
+        }
+        else if (e.kind === 'spec-renumbered') {
+            for (const input of inputs) {
+                const m = ARROW.exec(input);
+                if (m && m[1] !== m[2])
+                    out.push({ oldId: m[1], newId: m[2], ts: e.ts });
+            }
+        }
+    }
+    return out;
+}
+/** The display ids an entity has carried, as the connected component of `id` over recorded renames. */
+function aliasesOf(events, id) {
+    const adjacent = new Map();
+    const link = (a, b) => {
+        (adjacent.get(a) ?? adjacent.set(a, new Set()).get(a)).add(b);
+        (adjacent.get(b) ?? adjacent.set(b, new Set()).get(b)).add(a);
+    };
+    for (const r of displayIdRenames(events))
+        link(r.oldId, r.newId);
+    const seen = new Set([id]);
+    const queue = [id];
+    while (queue.length) {
+        const cur = queue.shift();
+        for (const next of adjacent.get(cur) ?? [])
+            if (!seen.has(next)) {
+                seen.add(next);
+                queue.push(next);
+            }
+    }
+    return [...seen].sort();
+}
+/** The display id the entity carries now: recorded renames applied forward from `id`, in ledger order. */
+function currentDisplayId(events, id) {
+    let cur = id;
+    for (const r of displayIdRenames(events))
+        if (r.oldId === cur)
+            cur = r.newId;
+    return cur;
+}
+/** One pass over the renames, then memoized answers — for consumers that canonicalize many ids. */
+function displayIdCanonicalizer(events) {
+    const renames = displayIdRenames(events);
+    const memo = new Map();
+    return (id) => {
+        const hit = memo.get(id);
+        if (hit !== undefined)
+            return hit;
+        let cur = id;
+        for (const r of renames)
+            if (r.oldId === cur)
+                cur = r.newId;
+        memo.set(id, cur);
+        return cur;
+    };
+}

package/dist/holmes/governance/ledger-store.d.ts

@@ -1,5 +1,5 @@
 import { ProvenanceEvent } from './provenance-chain';
-import { LedgerEvent } from './provenance-ledger';
+import { LedgerEvent, DoubleSpend } from './provenance-ledger';
 /**
  * The ledger as a PORT — ADR-001's deferred half, applied to the one store whose shape was derived
  * from real use rather than guessed at.
@@ -24,6 +24,14 @@ import { LedgerEvent } from './provenance-ledger';
  * ADR-001 named speculative port design as the cost of deciding early; this is where that cost is
  * refused.
  */
+/** A-SPEC-642 — one verification failure: a chain break (`kind: 'chain'`) or an unreconciled double-spend. */
+export interface LedgerBroken {
+    replicaId: string | null;
+    detail?: string;
+    kind?: 'chain' | 'double-spend';
+    nonce?: string;
+    events?: DoubleSpend['events'];
+}
 export interface LedgerStore {
     /** This writer's identity — the one used for events this store appends. */
     replicaId(): string;
@@ -34,19 +42,43 @@ export interface LedgerStore {
     }[];
     /** Every event across every chain, deterministically ordered. */
     loadAll(): LedgerEvent[];
-    /** Per-chain verification; one broken chain fails the whole store and is named. */
+    /** Per-chain verification; one broken chain fails the whole store and is named. A-SPEC-642: cross-replica double-spends ride along as `kind: 'double-spend'` entries. */
     verifyAll(): {
         ok: boolean;
-        broken: {
-            replicaId: string | null;
-            detail?: string;
-        }[];
+        broken: LedgerBroken[];
     };
     /** Append to this writer's chain. Never modifies or removes an existing event. */
     append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
     /** Spent on ANY chain — see the interface note. */
     isNonceConsumed(nonce: string): boolean;
+    /** A-SPEC-642 — single-use nonces consumed more than once across chains and not yet reconciled. */
+    doubleSpends(): DoubleSpend[];
+}
+/**
+ * @implements A-SPEC-643
+ * The chain file THIS process writes: `provenance.<replica>.jsonl`, resolved exactly as every other
+ * writer resolves it (the run's execution replica when registered, else the stored or hostname-derived
+ * id). Measured 2026-09-14: the shell gate, `risk_check` and `review_record` handed
+ * `consumeNonceExclusively` the legacy `provenance.jsonl`, so two clones spending the same approval
+ * offline both appended to one file and the origin's merge died with CONFLICT (add/add) before any
+ * double-spend could be seen. Consumptions belong on the writer's chain like every other event.
+ */
+export declare function writerChainFile(ledgerDir: string): string;
+/** A-SPEC-642 — thrown by approval resolution while the merged ledger holds an unreconciled double-spend. */
+export declare class LedgerConflictRefusal extends Error {
+    readonly holmesRefusal = true;
+    readonly code = "ledger-conflict";
+    constructor(message: string);
 }
+/**
+ * @implements A-SPEC-642
+ * The one sentence every authority-spending act refuses with while the merged ledger holds an
+ * unreconciled cross-replica double-spend, or null. Names the nonce, the replicas and the act that
+ * clears it, because a refusal that cannot be acted on is an obstacle rather than a gate. An absent
+ * ledger directory is a clean ledger. Not caught: an unreadable chain file throws here exactly as it
+ * throws in `isNonceConsumed`, and the callers' fail-closed handling applies.
+ */
+export declare function ledgerConflictReason(dir: string): string | null;
 /**
  * Local adapter — DELEGATES to `ProvenanceLedger` rather than re-implementing it.
  *
@@ -77,13 +109,11 @@ export declare class FileLedgerStore implements LedgerStore {
     loadAll(): LedgerEvent[];
     verifyAll(): {
         ok: boolean;
-        broken: {
-            replicaId: string | null;
-            detail?: string;
-        }[];
+        broken: LedgerBroken[];
     };
     append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
     isNonceConsumed(nonce: string): boolean;
+    doubleSpends(): DoubleSpend[];
 }
 /**
  * In-memory adapter — the instrument that makes the contract testable.
@@ -104,13 +134,11 @@ export declare class MemoryLedgerStore implements LedgerStore {
     loadAll(): LedgerEvent[];
     verifyAll(): {
         ok: boolean;
-        broken: {
-            replicaId: string | null;
-            detail?: string;
-        }[];
+        broken: LedgerBroken[];
     };
     append(body: Omit<ProvenanceEvent, 'prevHash' | 'hash' | 'seq'>): ProvenanceEvent;
     isNonceConsumed(nonce: string): boolean;
+    doubleSpends(): DoubleSpend[];
 }
 /**
  * The cross-replica nonce check, bound to one ledger file, ready to hand to