@sema-agent/core 5.36.0 → 5.38.0

package/dist/core/hooks.js

@@ -78,6 +78,18 @@ export function createHookEnvCapabilities(env) {
     }
     return Object.freeze(face);
 }
+const IDENTITY_AGENT_NAME_MAX = 80;
+export function mintHookInvocationIdentity(facts) {
+    return Object.freeze(Object.assign(Object.create(null), {
+        sessionId: facts.sessionId,
+        taskId: facts.taskId,
+        legKind: facts.legKind,
+        isDelegatedChild: facts.isDelegatedChild,
+        ...(facts.insideFork === true ? { insideFork: true } : {}),
+        ...(facts.agentName !== undefined ? { agentName: inlineUntrusted(facts.agentName.slice(0, 320), IDENTITY_AGENT_NAME_MAX) } : {}),
+        ...(facts.parentToolCallId !== undefined ? { parentToolCallId: facts.parentToolCallId } : {}),
+    }));
+}
 export function formatHookFeedback(text) {
     return `<system-reminder>\n${text}\n</system-reminder>`;
 }
@@ -270,7 +282,12 @@ export function persistedRuleMandateOf(marks) {
 export async function runToolGate(input) {
     const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
-    const hookCtx = () => ({ toolCallId, toolName, ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}) });
+    const hookCtx = () => ({
+        toolCallId,
+        toolName,
+        ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}),
+        ...(input.identity !== undefined ? { identity: input.identity } : {}),
+    });
     let currentInput = event.input;
     const preToolContext = [];
     let hookAsk;
@@ -285,7 +302,7 @@ export async function runToolGate(input) {
             const reason = preToolUseCrashReason(`this call to "${toolName}"`, err);
             traceHookCrash(input, err, notifier);
             if (input.permissionDenied) {
-                await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook" }), "toolGate.permissionDenied");
+                await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook", ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
             }
             return { block: true, reason: formatHookFeedback(reason), preToolContext };
         }
@@ -741,7 +758,7 @@ export async function runToolGate(input) {
             currentInput = decision.updatedInput;
         }
         if (input.permissionDenied) {
-            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource }), "toolGate.permissionDenied");
+            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource, ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
         }
         const denySettledBy = decision.settledBy;
         const denyApprover = denySettledBy !== undefined ? resolvedApprover : undefined;

package/dist/core/memory-engine/engine.d.ts

@@ -1,3 +1,4 @@
+import { type CommittedBinding, type EraseMemoryEntriesInput, type MemoryErasureAttestation, type TransferEvidence } from "./file-backend.js";
 import { type ChallengeAssignment, type ChallengeEvent, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, type MemoryPartitionIncidentSink, type RetrievedAccountRow, type SessionPollutionRecord } from "./layout.js";
 import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemorySessionHandle, ScanFinding } from "./types.js";
 /**
@@ -187,6 +188,72 @@ export interface MemoryInjection {
         content: string;
     };
 }
+/**
+ * design/178 v2-a §1.3 — one entry's ASSEMBLED provenance account: the machine-readable answer to
+ * "who wrote this in, what state is it in, has it been moved" for an auditor holding an entry id.
+ * ASSEMBLY, not a second account: every field is read from an authority that already exists
+ * (lineage/challenge/pollution = the engine's control plane; binding/content/custody = the
+ * backend's committed account + evidence chain) — a "provenance store" would be a drift surface.
+ *
+ * Field law:
+ *  - `v` — version envelope: a consumer reading `v > 1` must refuse, never reinterpret.
+ *  - `binding` — the committed-account row state, FOUR states without collapse: `bound`/`unbound`
+ *    ({@link CommittedBinding}, shared tagged form) / `absent` (no row) / `unknown` (the backend
+ *    has no audit-snapshot capability — "cannot judge" is never folded into "does not exist").
+ *  - `contributors` — the committed lineage BY-ENTRY projection, each row joined with its
+ *    session's pollution record where one exists. Pending (unsettled) lineage rows are never
+ *    contributions; they surface as the `lineage_pending` exclusion instead.
+ *  - `exclusion` — the model-visible read faces' withholding state for this id, when any.
+ *  - `contentState` — the content half, LINKED to `binding` by construction: `absent` ⇔ binding
+ *    `absent`; `capability-absent` ⇔ binding `unknown`; a row answers `present` (committed content
+ *    servable; only then may `ingest` ride) or `unavailable` (row facts answered, no committed
+ *    carrier — "cannot read it" stays distinct from "does not exist").
+ *  - `ingest` — the typed repo-file ingest provenance carried by the committed content's
+ *    frontmatter (`provenance` + the un-whitewashable `trust` marker), present only with
+ *    `contentState: "present"`.
+ *  - `custody` — the per-id evidence-chain read (`transfers.jsonl`), `damaged` = the chain's
+ *    integrity is impeached while a sound reading still answers (torn tail / evidence loss /
+ *    ev-identity contradiction — `reason` carries the detail when one is known; see
+ *    {@link EntryCustodyReport}), `capability-absent` = the backend has no custody face (events
+ *    then empty — never fabricated).
+ */
+export interface EntryProvenanceAccount {
+    v: 1;
+    id: string;
+    binding: CommittedBinding | {
+        state: "absent";
+    } | {
+        state: "unknown";
+        reason: "audit-snapshot-capability-absent";
+    };
+    contributors: Array<{
+        sessionId: string;
+        lastRev: string;
+        lastAt?: number;
+        polluted?: {
+            at: number;
+            reason: string;
+        };
+    }>;
+    exclusion?: {
+        code: "challenged" | "lineage_pending";
+        generation?: number;
+        at?: number;
+    };
+    contentState: "present" | "unavailable" | "capability-absent" | "absent";
+    ingest?: {
+        kind: "repo_file";
+        path: string;
+        contentHash: string;
+        ingestedAt: number;
+        trust?: "untrusted";
+    };
+    custody: {
+        state: "complete" | "damaged" | "capability-absent";
+        events: TransferEvidence[];
+        reason?: string;
+    };
+}
 export declare class MemoryEngine {
     private readonly backend;
     private readonly memoryDir;
@@ -296,6 +363,81 @@ export declare class MemoryEngine {
      * so one batched request stays per-entry attributable.
      */
     challengeEntries(ids: readonly string[], reason: string, requestId: string): ChallengeAssignment[];
+    /**
+     * design/178 v2-b §3.3(b) — the HOST erasure API: explicit, named, evidenced, loud. This is a
+     * host-plane DECLARED deletion, not a second deletion throat: it executes through the same
+     * `op:"delete"` lane every deletion takes, and the model-visible rule is untouched (a missing
+     * file is still never a delete; the frontmatter tombstone is still the only model-side channel).
+     * The mass-deletion fuse guards the ACCIDENT shape (files silently missing at harvest) and does
+     * not apply here — an explicitly authorized erasure self-discloses by enumerating every id in
+     * its attestation, and each selector form is bounded (there is no whole-store selector).
+     *
+     * Thin membrane by design (§7.4 r1): with the backend's evidence capability present
+     * (`eraseWithEvidence` — File implements it), validation is the ONLY thing that happens outside
+     * the store's transaction lock; resolution, lineage capture, planning, and evidence all run
+     * inside it. Capability ABSENT ⇒ loud refusal (`memory.erasure_evidence_unavailable`) unless
+     * `allowUnevidenced: true` opts into the DEGRADED lane, whose contract is deliberately weaker
+     * and stated (§5): same requestId = a NEW request (re-resolved — replay convergence is not
+     * promised), selector reuse is undetectable (no anchor to compare), `erasedPreviously` and
+     * `evidenceEv` never appear, every notFound row carries `historyUnknown` ("never existed" vs
+     * "deleted without evidence" is not decidable), resolution is the contract read faces'
+     * best-effort set (shadow-only rows invisible), execution is per-id CAS'd delete patches
+     * (conflicts reported, replay converges), and the attestation carries
+     * `evidenceCapability: "none"` + `custodyState: "capability-absent"` throughout — a silent
+     * downgrade is the forbidden shape. Residual enumeration is unavailable on the degraded lane
+     * (no quarantine face): its `quarantineHits`/`quarantineOpaque` answer empty/zero as
+     * "unenumerable", never as a verified absence. Applied deletes close their lineage rows (the
+     * same space hygiene the organic tombstone path takes).
+     *
+     * BOTH lanes finish with the derived-index sweep ({@link sweepErasedIndexLines}): the erased
+     * entries' MEMORY.md pointer lines — name + description, the model-visible distillation — are
+     * cleared from disk in the same call, and a sweep failure is disclosed on
+     * `residuals.indexUncleared`, never silently absorbed into a clean residual set.
+     */
+    eraseMemoryEntries(input: EraseMemoryEntriesInput): Promise<MemoryErasureAttestation>;
+    /**
+     * design/178 v2-b (rescan hardening) — the erase-time DERIVED-INDEX sweep, both lanes. MEMORY.md
+     * is the engine's model-visible distillation of entry frontmatter (name + description — routinely
+     * a restatement of exactly what an erasure request targets), and it is a derived projection the
+     * BACKEND knows nothing about: the store lane deletes rows/projections/shadows while the index
+     * line survives on disk (git working tree included) and rides the next injection that prefers the
+     * live on-disk index. The only other cleaner is the next materialize's rebuild — which a one-off
+     * compliance erasure cannot count on — so the erase itself clears the pointer lines.
+     *
+     * LINE-TARGETED, never a full rebuild (no session handle exists here; prose/headers and every
+     * unrelated line stay verbatim): a line is dropped iff its link target resolves to an erased
+     * row's BOUND projection path. Failures are DISCLOSED on the attestation's
+     * `residuals.indexUncleared` seat, never silent (坏值响亮度): a non-file at the index path, a
+     * non-ENOENT read failure, or a refused write leaves the path listed — the caller archiving the
+     * attestation knows the model-visible index may still name the erased entry. Honest bounds,
+     * stated: an UNBOUND erased row has no projection address to match (its dangling line — if a
+     * model ever wrote one — falls to the rebuild's orphan clearing); a session handle minted
+     * BEFORE the erase still carries its materialize-time index text (a handle is a snapshot; the
+     * next materialize re-derives); a REPO-INGESTED entry's index line targets the repo source file
+     * (recorded at materialize), which is not derivable from the deleted row — that line is a
+     * pointer to a still-existing user-owned file (L8 keeps it; the repo bytes were never the
+     * store's to erase — `propagation: "local-store-only"`); and the write is the same unlocked
+     * read-filter-write every writer performs on this MODEL-EDITABLE plane file (a concurrent
+     * session's line landing inside the window is last-writer-wins — the plane's standing posture,
+     * not a channel this sweep adds).
+     */
+    private sweepErasedIndexLines;
+    /**
+     * design/178 v2-a §1.3 — the per-entry provenance ANSWER (host audit API; see
+     * {@link EntryProvenanceAccount} for the field law). The read is held to the three audit axes:
+     * SIDE-EFFECT-FREE (no adoption, no healing, no migration trigger — the backend half goes through
+     * the audit-snapshot capability faces, never the adopting/serving read paths), COMMITTED (the
+     * account answers, never uncommitted plane bytes), and ACCOUNT-COMPLETE (the backend half is
+     * ledger-driven, so a row whose projection vanished out-of-band still answers).
+     *
+     * Failure posture is the control plane's existing fail-closed law: a corrupt lineage or challenge
+     * ledger THROWS (`ControlPlaneCorruptError` — an answer is never assembled over an account whose
+     * integrity is unknown), and the backend's own refusals (v1-compat store, contended snapshot
+     * fence) propagate. CAPABILITY ABSENCE is not failure: a backend without the audit faces answers
+     * `binding: "unknown"` / `contentState: "capability-absent"` / `custody: "capability-absent"` —
+     * reported honestly, never fabricated and never a throw (#196 absence-reports-not-silent-green).
+     */
+    provenanceOf(entryId: string): Promise<EntryProvenanceAccount>;
     /** Host API: challenge every entry the lineage ledger attributes to `sessionId` (post-hoc source
      *  falsification — trustedTools misconfigured, a tool re-classified, late delegation evidence).
      *  Same requestId contract as {@link challengeEntries}. */

package/dist/core/memory-engine/engine.js

@@ -5,8 +5,8 @@ import { MAX_MEMORY_BYTES, composeMemoryBlock, firstSentence } from "../memory.j
 import { inlineUntrusted } from "../untrusted-text.js";
 import { formatMemoryAge } from "../memory-recall.js";
 import { computeEntryRev, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
-import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./file-backend.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
+import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, canonicalJsonStringify, captureErasureInput, erasureRequestInvalid, erasureSelectHash, scanEntryFiles, } from "./file-backend.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 export const MEMORY_INSTRUCTION_TEMPLATE = `# Memory
 
@@ -259,6 +259,268 @@ export class MemoryEngine {
         }
         return this.challengeAndAnnounce(ids.map((entryId) => ({ eventId: `${requestId}:${entryId}`, entryId, reason })));
     }
+    async eraseMemoryEntries(input) {
+        const captured = captureErasureInput(input);
+        const bad = erasureRequestInvalid(captured);
+        if (bad !== undefined) {
+            const e = new Error(`eraseMemoryEntries: ${bad}`);
+            e.code = "config.memory_erasure_request";
+            throw e;
+        }
+        const requestId = captured.requestId;
+        const face = this.backend.eraseWithEvidence;
+        if (typeof face === "function") {
+            const att = await face.call(this.backend, captured);
+            this.sweepErasedIndexLines(att);
+            return att;
+        }
+        if (captured.allowUnevidenced !== true) {
+            const e = new Error("eraseMemoryEntries: this backend has no erasure-evidence capability (eraseWithEvidence) — an unevidenced erasure is refused by default. " +
+                "Pass allowUnevidenced: true to run the documented degraded lane (no replay convergence, no selector-reuse detection, no erasure history, best-effort resolution).");
+            e.code = "memory.erasure_evidence_unavailable";
+            throw e;
+        }
+        const at = this.now();
+        const select = captured.select;
+        let resolvedIds;
+        if ("ids" in select) {
+            resolvedIds = [...select.ids];
+        }
+        else if ("scope" in select) {
+            const headers = await this.backend.listHeaders([select.scope]);
+            resolvedIds = [...new Set(headers.map((h) => h.id))].sort();
+        }
+        else {
+            resolvedIds = lineageContributionsOfSession(this.controlDir, select.sessionId)
+                .map((c) => c.entryId)
+                .sort();
+        }
+        const present = await this.backend.getByIds(resolvedIds);
+        const byId = new Map(present.map((e) => [e.id, e]));
+        const patches = [...byId.values()].map((e) => ({ op: "delete", id: e.id, baseRev: e.rev }));
+        const report = patches.length > 0 ? await this.backend.applyPatches(patches) : { applied: [], conflicts: [] };
+        const appliedDeletes = new Set(report.applied.filter((a) => a.op === "delete").map((a) => a.id));
+        if (appliedDeletes.size > 0)
+            clearLineageForEntries(this.controlDir, [...appliedDeletes]);
+        const erased = [...appliedDeletes].map((id) => {
+            const e = byId.get(id);
+            return {
+                id,
+                rev: e?.rev ?? "",
+                binding: e !== undefined ? { state: "bound", scope: e.scope, slug: e.slug } : { state: "unbound" },
+                projectionsRemoved: 1,
+                sessions: [],
+            };
+        });
+        const notFound = resolvedIds.filter((id) => !byId.has(id)).map((id) => ({ id, historyUnknown: true }));
+        const conflicts = report.conflicts.map((c) => ({ id: c.id, reason: c.reason }));
+        const status = conflicts.length === 0 && resolvedIds.every((id) => appliedDeletes.has(id)) ? "complete" : "partial";
+        const att = {
+            v: 1,
+            requestId,
+            at,
+            status,
+            evidenceCapability: "none",
+            custodyState: "capability-absent",
+            select,
+            selectHash: erasureSelectHash(select),
+            resolvedIds,
+            erased,
+            notFound,
+            conflicts,
+            residuals: { quarantineHits: [], quarantineOpaque: 0, propagation: "local-store-only" },
+        };
+        this.sweepErasedIndexLines(att);
+        return att;
+    }
+    sweepErasedIndexLines(att) {
+        const uncleared = [];
+        try {
+            const erasedPaths = new Set();
+            const boundScopes = new Set();
+            for (const row of att.erased) {
+                if (row.binding.state !== "bound")
+                    continue;
+                boundScopes.add(row.binding.scope);
+                erasedPaths.add(canonicalize(join(scopeDirFor(this.memoryDir, this.controlDir, row.binding.scope), `${row.binding.slug}.md`)));
+            }
+            for (const row of att.erasedPreviously ?? []) {
+                if (row.from === undefined)
+                    continue;
+                boundScopes.add(row.from.scope);
+                erasedPaths.add(canonicalize(join(scopeDirFor(this.memoryDir, this.controlDir, row.from.scope), `${row.from.slug}.md`)));
+            }
+            if (erasedPaths.size === 0)
+                return;
+            const dirs = new Set([this.memoryDir]);
+            for (const scope of Object.keys(registeredScopes(this.controlDir)))
+                dirs.add(scopeDirFor(this.memoryDir, this.controlDir, scope));
+            for (const scope of boundScopes)
+                dirs.add(scopeDirFor(this.memoryDir, this.controlDir, scope));
+            const seen = new Set();
+            for (const dir of dirs) {
+                const indexPath = join(dir, MEMORY_INDEX_FILENAME);
+                const canon = canonicalize(indexPath);
+                if (seen.has(canon))
+                    continue;
+                seen.add(canon);
+                let isFile;
+                try {
+                    isFile = lstatSync(indexPath).isFile();
+                }
+                catch (err) {
+                    if (err.code === "ENOENT")
+                        continue;
+                    uncleared.push(indexPath);
+                    continue;
+                }
+                if (!isFile) {
+                    uncleared.push(indexPath);
+                    continue;
+                }
+                const text = readNoFollowSafe(indexPath);
+                if (text === undefined) {
+                    uncleared.push(indexPath);
+                    continue;
+                }
+                const lines = text.split("\n");
+                const kept = lines.filter((line) => {
+                    const target = indexLineTarget(line);
+                    if (target === undefined)
+                        return true;
+                    return !erasedPaths.has(canonicalize(join(dir, target)));
+                });
+                if (kept.length === lines.length)
+                    continue;
+                try {
+                    writeFileNoFollow(indexPath, kept.join("\n"));
+                }
+                catch {
+                    uncleared.push(indexPath);
+                }
+            }
+        }
+        catch (err) {
+            uncleared.push(`${join(this.memoryDir, MEMORY_INDEX_FILENAME)} (index sweep failed: ${err instanceof Error ? err.message : String(err)})`);
+        }
+        if (uncleared.length > 0) {
+            try {
+                att.residuals.indexUncleared = [...new Set(uncleared)].sort();
+            }
+            catch (err) {
+                try {
+                    const detail = `memory erasure: the attestation could not carry its index-residue disclosure ` +
+                        `(${inlineUntrusted(String(err instanceof Error ? err.message : err), 200)}) — MEMORY.md files that may still name erased entries: ` +
+                        `${uncleared.map((p) => inlineUntrusted(String(p), 300)).join(", ")}`;
+                    try {
+                        enqueueMemoryAnnouncement(this.controlDir, { kind: "external", at: this.now(), items: [detail] });
+                    }
+                    catch (enqueueErr) {
+                        this.discloseAnnounceFailure("erasure index-residue enqueue", enqueueErr);
+                    }
+                    const sink = this.onIncident;
+                    if (sink !== undefined) {
+                        try {
+                            const e = new Error(detail);
+                            e.code = "memory.erasure_index_residue";
+                            sink(e);
+                        }
+                        catch {
+                        }
+                    }
+                }
+                catch {
+                }
+            }
+        }
+    }
+    async provenanceOf(entryId) {
+        const snapshotFn = this.backend.committedSnapshotOf;
+        const custodyFn = this.backend.custodyOf;
+        const readEnginePlane = () => {
+            const challenged = challengedEntryIds(this.controlDir).get(entryId);
+            const lineage = lineageAccountOfEntry(this.controlDir, entryId);
+            return {
+                contributors: lineage.contributors.map((c) => {
+                    const polluted = this.sessionPollution(c.sessionId);
+                    return {
+                        sessionId: c.sessionId,
+                        lastRev: c.lastRev,
+                        lastAt: c.lastAt,
+                        ...(polluted !== undefined ? { polluted: { at: polluted.at, reason: polluted.reason } } : {}),
+                    };
+                }),
+                exclusion: challenged !== undefined
+                    ? { code: "challenged", generation: challenged.generation, at: challenged.at }
+                    : lineage.pendingLatched
+                        ? { code: "lineage_pending" }
+                        : undefined,
+            };
+        };
+        {
+            let snap;
+            let custody;
+            if (typeof snapshotFn !== "function") {
+                custody = typeof custodyFn !== "function" ? { state: "capability-absent", events: [] } : await custodyFn.call(this.backend, entryId);
+            }
+            else if (typeof custodyFn !== "function") {
+                snap = await snapshotFn.call(this.backend, entryId);
+                custody = { state: "capability-absent", events: [] };
+            }
+            else {
+                const accountKey = (s) => JSON.stringify(s.state === "row" ? { state: s.state, rev: s.rev, binding: s.binding } : { state: s.state });
+                const chainKey = (c) => canonicalJsonStringify(JSON.parse(JSON.stringify([c.state, c.reason ?? null, c.events])));
+                snap = await snapshotFn.call(this.backend, entryId);
+                custody = await custodyFn.call(this.backend, entryId);
+                let stable = false;
+                for (let bracket = 0; bracket < 4; bracket++) {
+                    const snapAgain = await snapshotFn.call(this.backend, entryId);
+                    if (accountKey(snapAgain) !== accountKey(snap)) {
+                        snap = snapAgain;
+                        custody = await custodyFn.call(this.backend, entryId);
+                        continue;
+                    }
+                    const custodyAgain = await custodyFn.call(this.backend, entryId);
+                    if (chainKey(custodyAgain) !== chainKey(custody)) {
+                        custody = custodyAgain;
+                        snap = await snapshotFn.call(this.backend, entryId);
+                        continue;
+                    }
+                    stable = true;
+                    break;
+                }
+                if (!stable) {
+                    throw new Error(`memory provenance read refused: the committed account for ${JSON.stringify(entryId)} kept moving across ` +
+                        `every snapshot/custody bracket — the two faces cannot be joined without tearing while the store is this hot; retry later.`);
+                }
+            }
+            const plane = readEnginePlane();
+            let binding;
+            let contentState;
+            let ingest;
+            if (snap === undefined) {
+                binding = { state: "unknown", reason: "audit-snapshot-capability-absent" };
+                contentState = "capability-absent";
+            }
+            else if (snap.state === "absent") {
+                binding = { state: "absent" };
+                contentState = "absent";
+            }
+            else {
+                binding = snap.binding;
+                if (snap.content.state === "present") {
+                    contentState = "present";
+                    const fm = snap.content.entry.frontmatter;
+                    if (fm.provenance !== undefined)
+                        ingest = { ...fm.provenance, ...(fm.trust !== undefined ? { trust: fm.trust } : {}) };
+                }
+                else {
+                    contentState = "unavailable";
+                }
+            }
+            return { v: 1, id: entryId, binding, contributors: plane.contributors, ...(plane.exclusion !== undefined ? { exclusion: plane.exclusion } : {}), contentState, ...(ingest !== undefined ? { ingest } : {}), custody };
+        }
+    }
     challengeSession(sessionId, reason, requestId) {
         if (typeof requestId !== "string" || requestId === "") {
             const e = new Error("challengeSession: requestId is required (idempotency identity — retries must reuse it; the engine does not mint one)");