@sema-agent/core 5.36.0 → 5.38.0

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

@@ -1,7 +1,7 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, } from "./engine.js";
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
-export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile } from "./file-backend.js";
+export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, } from "./file-backend.js";
 export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAppendResult, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, } from "./layout.js";
 export { readV2HeaderHints, type V2HeaderHints } from "./header-hints.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, type ParsedEntryFile } from "./frontmatter.js";

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

@@ -1,7 +1,7 @@
 export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, } from "./engine.js";
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, } from "./tools.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
-export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH } from "./file-backend.js";
+export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, erasureSelectHash, } from "./file-backend.js";
 export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, } from "./layout.js";
 export { readV2HeaderHints } from "./header-hints.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile } from "./frontmatter.js";

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

@@ -380,15 +380,55 @@ export declare function reconcileLineage(controlDir: string, now: () => number):
  *  refuse — "the account is not settled, the content does not go on the table". Throws on a
  *  corrupt ledger (integrity unknown ≠ no latch). */
 export declare function lineageLatchedIds(controlDir: string): Set<string>;
-/** Every committed contribution of `sessionId` (the pollution-retroaction sweep input). Throws on
- *  a corrupt ledger. */
+/** Every committed contribution of `sessionId` (the pollution-retroaction sweep input, and the
+ *  erasure lane's sessionId-selector resolver). Throws on a corrupt ledger. Lookups are
+ *  OWN-property (the twin law {@link lineageAccountOfEntry} states): a prototype-member sessionId
+ *  such as "constructor" indexes truthy on EVERY plain object, so a bare lookup would attribute
+ *  the WHOLE committed set to it — behind the erasure selector that phantom is a whole-store
+ *  delete, the exact shape the selector type forbids. Belt over the null-proto parse rebuild:
+ *  this guard stays honest even against a map minted elsewhere. */
 export declare function lineageContributionsOfSession(controlDir: string, sessionId: string): Array<{
     entryId: string;
     lastRev: string;
 }>;
+/** design/178 v2-a §1.3 — the BY-ENTRY lineage account, from ONE parse of the ledger (the
+ *  by-session read's transpose; the committed set is keyed by entryId, so the index is O(1) after
+ *  the load — the load itself still parses and validates the whole account). BOTH halves come from
+ *  the same read on purpose (adversarial r3): contributors (committed rows; pending rows are NOT
+ *  contributions — the account is unsettled) and the dirty-latch fact (any pending row naming this
+ *  id). Deriving them from two separate reads let a promotion land between them and assemble a
+ *  scene no instant exhibited — empty ancestry AND no latch. Unknown entry ⇒ empty/false. Throws
+ *  {@link ControlPlaneCorruptError} on a corrupt ledger — an audit answer is never assembled over
+ *  an account whose integrity is unknown. Lookups are own-property (a prototype-member entryId
+ *  such as "constructor" must answer the empty account, never a phantom). */
+export declare function lineageAccountOfEntry(controlDir: string, entryId: string): {
+    contributors: Array<{
+        sessionId: string;
+        lastRev: string;
+        lastAt: number;
+    }>;
+    pendingLatched: boolean;
+};
 /** Drop an entry's lineage rows once the entry is DELETED (an applied tombstone) — space hygiene
  *  only, taken at the harvest that saw the applied delete (design/180 §10). */
 export declare function clearLineageForEntries(controlDir: string, entryIds: readonly string[]): void;
+/**
+ * design/178 v2-b §7.2-3 — capture-and-clear an erased id set's lineage in ONE strict-lock write:
+ *  - the COMMITTED contributors of each id are captured (the attestation's testimony) and the rows
+ *    dropped (the organic tombstone's space hygiene, same terminal state);
+ *  - every PENDING txn's staged rows naming these ids are STRUCK in the same write — a promotion
+ *    landing after this lock releases iterates rows the strike already removed, so a late harvest
+ *    can never write a deleted id's lineage row back (the read and the clear being two separate
+ *    lock spans was exactly the interleave that both missed a landing contributor and then erased
+ *    the record of having missed it).
+ * Struck pending rows contribute their txn's sessionId to the returned set — EXCEPT rows carrying
+ * the structural `kind: "latch-only"` seat (an import protocol's synthetic latch is not a
+ * contributing session; the row is still struck). Returns id → contributing session ids
+ * (committed ∪ struck). NON-durable by design: a crash between the caller's journal close and this
+ * call loses the return set — the caller's replay re-runs it idempotently and its attestation
+ * carries the chain's pre-captured set (honest downgrade, never a fabricated rebuild).
+ */
+export declare function captureAndClearLineageForEntries(controlDir: string, entryIds: readonly string[]): Map<string, string[]>;
 /** Full-ledger read (tests / host observability). Throws on corruption. */
 export declare function readLineageRecord(controlDir: string): {
     committed: Record<string, Record<string, LineageContribution>>;

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

@@ -375,7 +375,8 @@ export function claimRootScope(controlDir, scope) {
 }
 export function registerScope(memoryDir, controlDir, scope, opts) {
     return lockedScopesUpdate(controlDir, (rec) => {
-        const dirName = rec.rootScope === scope ? "" : (rec.scopes?.[scope] ?? scopeDirName(scope));
+        const registered = rec.scopes !== undefined && Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : undefined;
+        const dirName = rec.rootScope === scope ? "" : (registered ?? scopeDirName(scope));
         for (const [other, otherDir] of Object.entries(rec.scopes ?? {})) {
             if (other === scope || otherDir === "")
                 continue;
@@ -390,7 +391,7 @@ export function registerScope(memoryDir, controlDir, scope, opts) {
                 }
             }
         }
-        if (rec.scopes?.[scope] === undefined) {
+        if (registered === undefined) {
             return { next: { ...rec, scopes: { ...rec.scopes, [scope]: dirName } }, result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
         }
         return { result: dirName === "" ? memoryDir : join(memoryDir, dirName) };
@@ -403,7 +404,7 @@ export function scopeDirFor(memoryDir, controlDir, scope) {
     const rec = readScopesRecord(controlDir);
     if (rec.rootScope === scope)
         return memoryDir;
-    const registered = rec.scopes?.[scope];
+    const registered = rec.scopes !== undefined && Object.prototype.hasOwnProperty.call(rec.scopes, scope) ? rec.scopes[scope] : undefined;
     if (registered !== undefined)
         return registered === "" ? memoryDir : join(memoryDir, registered);
     return join(memoryDir, scopeDirName(scope));
@@ -769,8 +770,8 @@ export const USAGE_RETRIEVED_FILE = "usage-retrieved.json";
 export const USAGE_RETRIEVED_MAX_IDS = 4096;
 function coerceRetrievedAccount(raw) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
-        return {};
-    const out = {};
+        return Object.create(null);
+    const out = Object.create(null);
     for (const [k, v] of Object.entries(raw)) {
         const row = v;
         if (row && typeof row === "object" && typeof row.count === "number" && Number.isFinite(row.count) && row.count > 0 && typeof row.lastAt === "number" && Number.isFinite(row.lastAt)) {
@@ -903,8 +904,9 @@ function readStrictSidecar(controlDir, fileName, what) {
     return readStrictSidecarRaw(file, what);
 }
 function coerceLineage(raw) {
-    if (raw === undefined)
-        return { version: 1, committed: {}, pending: {} };
+    if (raw === undefined) {
+        return { version: 1, committed: Object.create(null), pending: Object.create(null) };
+    }
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         throw new ControlPlaneCorruptError("memory lineage ledger has the wrong shape");
     const r = raw;
@@ -942,7 +944,17 @@ function coerceLineage(raw) {
             }
         }
     }
-    return raw;
+    const committed = Object.create(null);
+    for (const [entryId, sessions] of Object.entries(r.committed)) {
+        const s = Object.create(null);
+        for (const [sid, c] of Object.entries(sessions))
+            s[sid] = c;
+        committed[entryId] = s;
+    }
+    const pending = Object.create(null);
+    for (const [txnId, t] of Object.entries(r.pending))
+        pending[txnId] = t;
+    return { version: 1, committed, pending };
 }
 export function stageLineagePending(controlDir, txnId, sessionId, rows, now) {
     lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
@@ -981,7 +993,7 @@ export function promoteLineagePending(controlDir, txnId, now) {
         for (const row of txn.rows) {
             if (!applied.has(row.entryId))
                 continue;
-            const sessions = (rec.committed[row.entryId] ??= {});
+            const sessions = (rec.committed[row.entryId] ??= Object.create(null));
             sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at };
             promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev });
         }
@@ -1004,7 +1016,7 @@ export function adjudicateLineagePending(controlDir, txnId, action, now) {
         for (const row of txn.rows) {
             if (applied !== undefined && !applied.has(row.entryId))
                 continue;
-            const sessions = (rec.committed[row.entryId] ??= {});
+            const sessions = (rec.committed[row.entryId] ??= Object.create(null));
             sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at };
             promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev });
         }
@@ -1028,7 +1040,7 @@ export function reconcileLineage(controlDir, now) {
                 if (!applied.has(row.entryId))
                     continue;
                 at ??= now();
-                const sessions = (rec.committed[row.entryId] ??= {});
+                const sessions = (rec.committed[row.entryId] ??= Object.create(null));
                 sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at };
                 promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev });
             }
@@ -1050,12 +1062,25 @@ export function lineageContributionsOfSession(controlDir, sessionId) {
     const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
     const out = [];
     for (const [entryId, sessions] of Object.entries(rec.committed)) {
-        const c = sessions[sessionId];
+        const c = Object.prototype.hasOwnProperty.call(sessions, sessionId) ? sessions[sessionId] : undefined;
         if (c !== undefined)
             out.push({ entryId, lastRev: c.lastRev });
     }
     return out;
 }
+export function lineageAccountOfEntry(controlDir, entryId) {
+    const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
+    const sessions = Object.prototype.hasOwnProperty.call(rec.committed, entryId) ? rec.committed[entryId] : undefined;
+    const contributors = sessions === undefined ? [] : Object.entries(sessions).map(([sessionId, c]) => ({ sessionId, lastRev: c.lastRev, lastAt: c.lastAt }));
+    let pendingLatched = false;
+    for (const txn of Object.values(rec.pending)) {
+        if (txn.rows.some((r) => r.entryId === entryId)) {
+            pendingLatched = true;
+            break;
+        }
+    }
+    return { contributors, pendingLatched };
+}
 export function clearLineageForEntries(controlDir, entryIds) {
     if (entryIds.length === 0)
         return;
@@ -1070,6 +1095,45 @@ export function clearLineageForEntries(controlDir, entryIds) {
         return { ...(changed ? { next: rec } : {}), result: undefined };
     });
 }
+export function captureAndClearLineageForEntries(controlDir, entryIds) {
+    if (entryIds.length === 0)
+        return new Map();
+    return lockedStrictUpdate(controlDir, LINEAGE_FILE, "memory lineage ledger", coerceLineage, (rec) => {
+        const want = new Set(entryIds);
+        const captured = new Map();
+        const add = (id, sessionId) => {
+            const set = captured.get(id) ?? new Set();
+            set.add(sessionId);
+            captured.set(id, set);
+        };
+        let changed = false;
+        for (const id of entryIds) {
+            if (!Object.prototype.hasOwnProperty.call(rec.committed, id))
+                continue;
+            for (const sessionId of Object.keys(rec.committed[id] ?? {}))
+                add(id, sessionId);
+            delete rec.committed[id];
+            changed = true;
+        }
+        for (const txn of Object.values(rec.pending)) {
+            const keep = [];
+            for (const row of txn.rows) {
+                if (!want.has(row.entryId)) {
+                    keep.push(row);
+                    continue;
+                }
+                changed = true;
+                if (row.kind !== "latch-only")
+                    add(row.entryId, txn.sessionId);
+            }
+            txn.rows = keep;
+        }
+        const result = new Map();
+        for (const [id, sessions] of captured)
+            result.set(id, [...sessions].sort());
+        return { ...(changed ? { next: rec } : {}), result };
+    });
+}
 export function readLineageRecord(controlDir) {
     const rec = coerceLineage(readStrictSidecar(controlDir, LINEAGE_FILE, "memory lineage ledger"));
     return { committed: rec.committed, pending: rec.pending };

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

@@ -12,6 +12,19 @@ export interface MemoryBackendContractHooks {
     skipCrossInstanceCas?: string;
     /** Wrap each case (vitest `it`, sequential SQL chaining, …). Default: run sequentially. */
     runAssertion?: (name: string, fn: () => Promise<void>) => void | Promise<void>;
+    /**
+     * design/178 v2-a §1.3 — the OPTIONAL audit-face clauses' report seat (#196
+     * `onOptionalMember` posture: absence is REPORTED, never a silent green — a run without this
+     * hook still passes on an absent face, but a certifying harness that wires it can tell
+     * "verified" from "the store never offered the face"). The three faces are capability probes on
+     * the concrete class (`committedSnapshotOf` / `committedSnapshotsOfScopes` / `custodyOf`); the
+     * `MemoryBackend` interface itself is untouched, so absence is legal — the engine's provenance
+     * assembly answers it as capability-absent.
+     */
+    onOptionalMember?: (report: {
+        member: "committedSnapshotOf" | "committedSnapshotsOfScopes" | "custodyOf" | "eraseWithEvidence";
+        status: "verified" | "absent";
+    }) => void;
 }
 /** Run the full conformance suite. Throws (assert) on the first violated contract clause. */
 export declare function memoryBackendContract(hooks: MemoryBackendContractHooks): Promise<void>;

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

@@ -295,6 +295,95 @@ export async function memoryBackendContract(hooks) {
         assert.strictEqual(await b.getConsolidationCursor("s1"), "c-2");
         assert.strictEqual(await b.getConsolidationCursor("s2"), "c-other");
     });
+    defer("design/178 v2-a optional audit faces: committed snapshot / scope enumeration / custody (absent ⇒ reported)", async () => {
+        const b = await hooks.make();
+        const seats = [
+            ["committedSnapshotOf", b.committedSnapshotOf],
+            ["committedSnapshotsOfScopes", b.committedSnapshotsOfScopes],
+            ["custodyOf", b.custodyOf],
+        ];
+        for (const [member, seat] of seats) {
+            assert.ok(seat === undefined || typeof seat === "function", `${member} must be undefined (absent) or a function — a non-function occupant is a defect, not absence`);
+        }
+        const snapshotOf = typeof seats[0]?.[1] === "function" ? seats[0][1] : undefined;
+        const snapshotsOfScopes = typeof seats[1]?.[1] === "function" ? seats[1][1] : undefined;
+        const custodyOf = typeof seats[2]?.[1] === "function" ? seats[2][1] : undefined;
+        const e = entry("id-audit-0001", "s1", "audited", "audited body", { name: "Audited" });
+        await b.applyPatches([{ op: "add", id: e.id, entry: e }]);
+        if (typeof snapshotOf !== "function") {
+            hooks.onOptionalMember?.({ member: "committedSnapshotOf", status: "absent" });
+        }
+        else {
+            const ghost = await snapshotOf.call(b, "id-ghost-9999");
+            assert.strictEqual(ghost.state, "absent", "an unknown id answers state 'absent' — never a throw, never a guess");
+            const snap = await snapshotOf.call(b, e.id);
+            assert.strictEqual(snap.state, "row");
+            if (snap.state === "row") {
+                assert.strictEqual(snap.rev, e.rev, "the snapshot's rev is the committed rev");
+                assert.strictEqual(snap.binding.state, "bound", "a committed add answers a bound row");
+                if (snap.binding.state === "bound") {
+                    assert.strictEqual(snap.binding.scope, "s1");
+                    assert.strictEqual(snap.binding.slug, "audited");
+                }
+                assert.strictEqual(snap.content.state, "present", "a committed, in-place entry's content is servable");
+                if (snap.content.state === "present")
+                    assert.strictEqual(snap.content.entry.rev, e.rev);
+            }
+            hooks.onOptionalMember?.({ member: "committedSnapshotOf", status: "verified" });
+        }
+        if (typeof snapshotsOfScopes !== "function") {
+            hooks.onOptionalMember?.({ member: "committedSnapshotsOfScopes", status: "absent" });
+        }
+        else {
+            const enumerated = await snapshotsOfScopes.call(b, ["s1"]);
+            if (!enumerated.complete)
+                assert.fail("a quiet store enumerates complete");
+            assert.deepStrictEqual(enumerated.rows.map((r) => r.id), [e.id], "the account-driven enumeration answers the committed row");
+            const foreign = await snapshotsOfScopes.call(b, ["s-elsewhere"]);
+            if (!foreign.complete)
+                assert.fail("a quiet store enumerates complete (foreign scope)");
+            assert.deepStrictEqual(foreign.rows, [], "a foreign scope enumerates empty, not the whole store");
+            hooks.onOptionalMember?.({ member: "committedSnapshotsOfScopes", status: "verified" });
+        }
+        if (typeof custodyOf !== "function") {
+            hooks.onOptionalMember?.({ member: "custodyOf", status: "absent" });
+        }
+        else {
+            const custody = await custodyOf.call(b, e.id);
+            assert.ok(custody.state === "complete" || custody.state === "damaged", "custody state is the two-valued store answer");
+            assert.ok(Array.isArray(custody.events));
+            for (const ev of custody.events) {
+                assert.strictEqual(typeof ev.ev, "string");
+                assert.strictEqual(typeof ev.channel, "string");
+                assert.strictEqual(typeof ev.at, "number");
+            }
+            hooks.onOptionalMember?.({ member: "custodyOf", status: "verified" });
+        }
+    });
+    defer("design/178 v2-b optional erasure face: evidenced delete / replay pinning / selector-swap refusal (absent ⇒ reported)", async () => {
+        const b = await hooks.make();
+        const seat = b.eraseWithEvidence;
+        assert.ok(seat === undefined || typeof seat === "function", "eraseWithEvidence must be undefined (absent) or a function — a non-function occupant is a defect, not absence");
+        if (typeof seat !== "function") {
+            hooks.onOptionalMember?.({ member: "eraseWithEvidence", status: "absent" });
+            return;
+        }
+        const erase = seat;
+        const e = entry("id-erase-0001", "s1", "erasable", "erasable body", { name: "Erasable" });
+        await b.applyPatches([{ op: "add", id: e.id, entry: e }]);
+        const att = await erase.call(b, { requestId: "req-contract-1", select: { ids: [e.id, "id-ghost-8888"] } });
+        assert.strictEqual(att.v, 1, "the attestation rides the v:1 envelope");
+        assert.strictEqual(att.evidenceCapability, "journal", "a face-claiming backend answers the evidenced capability");
+        assert.deepStrictEqual(att.erased.map((r) => r.id), [e.id], "the existing id is erased");
+        assert.ok(typeof att.erased[0]?.evidenceEv === "string" && att.erased[0].evidenceEv.length > 0, "an evidenced erase names its evidence row");
+        assert.deepStrictEqual(att.notFound.map((r) => r.id), ["id-ghost-8888"], "the unknown id answers notFound — never a throw, never a silent drop");
+        assert.deepStrictEqual(await b.getByIds([e.id]), [], "an erased id is gone from the read faces");
+        const replay = await erase.call(b, { requestId: "req-contract-1", select: { ids: [e.id, "id-ghost-8888"] } });
+        assert.deepStrictEqual(replay.resolvedIds, att.resolvedIds, "a replay answers the FIRST resolution's pinned set");
+        assert.deepStrictEqual((replay.erasedPreviously ?? []).map((r) => r.id), [e.id], "a replay claims the prior erase as erasedPreviously, never a second erase");
+        await assert.rejects(async () => erase.call(b, { requestId: "req-contract-1", select: { ids: ["id-other-7777"] } }), (err) => err.code === "memory.erasure_selector_mismatch", "a reused requestId with a different selector refuses loudly");
+        hooks.onOptionalMember?.({ member: "eraseWithEvidence", status: "verified" });
+    });
     if (!hooks.makeSibling) {
         const reason = hooks.skipCrossInstanceCas?.trim();
         if (reason) {

package/dist/core/protocol-table.d.ts

@@ -66,10 +66,10 @@ export declare const MCP_NAMESPACE: ProtocolNamespace<typeof MCP_PREFIX_NAME>;
 /**
  * The A2A tool namespace (roadmap 2026-08-03, appended for the A2A client/server work).
  *
- * NAME LAYER ONLY: this entry decides how an A2A tool name is SPELLED and how it decomposes. Nothing
- * materializes A2A tools yet — until the client leg lands, no name in this namespace can exist at runtime,
- * so appending the entry changes no live behavior. It exists first because every table-driven site
- * (`protocolOf`, the grouped display key, the `ToolOrigin` union) then needs no change when it does.
+ * NAME LAYER ONLY: this entry decides how an A2A tool name is SPELLED and how it decomposes. The
+ * client leg (`a2a.ts`, `materializeA2aTools`) mints live names in this namespace since v5.3.0; the
+ * table entry predates it so that every table-driven site (`protocolOf`, the grouped display key, the
+ * `ToolOrigin` union) needed no change when the leg landed — and needs none for the server-side leg.
  */
 export declare const A2A_NAMESPACE: ProtocolNamespace<typeof A2A_PREFIX_NAME>;
 /** Every protocol namespace the engine knows. APPEND-ONLY: adding a protocol must not change how any

package/dist/core/runner/assemble-result.d.ts

@@ -128,6 +128,11 @@ export interface ResultFlags {
      *  spawner folds it stricter-wins into follow-on legs; every other consumer may ignore it. */
     effectiveReadFace?: TaskResult["effectiveReadFace"];
     effectiveReadDenyPatterns?: TaskResult["effectiveReadDenyPatterns"];
+    /** design/178 v2 §2.3 (件①) — the memory-visibility observation, echoed on
+     *  `TaskResult.effectiveMemoryScopes`. Pure pass-through on every terminal, same law as the
+     *  read-posture seats above: present iff prepare completed (the memory-less states are their own
+     *  values — absence means only "prepare never ran to completion"). */
+    effectiveMemoryScopes?: TaskResult["effectiveMemoryScopes"];
     /** ruled 2026-08-04 — the usage-governance wait hint carried by the platform terminal the run adopted
      *  (`undefined` for every other cause: an expiring environment has no return time to give, and a store
      *  failure is not a window). Passed as data rather than read back off `threw` so the seat has a typed

package/dist/core/runner/assemble-result.js

@@ -162,5 +162,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     void _internalCompaction;
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
-    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), checkpointToken, checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: flags.remoteEnvFailures } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), stats: publicStats };
+    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), checkpointToken, checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: flags.remoteEnvFailures } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), stats: publicStats };
 }

package/dist/core/runner/prepare-config-doors.d.ts

@@ -107,6 +107,10 @@ export interface PrepareConfigDoorsResult {
         exclude: readonly string[] | undefined;
         defer: readonly string[] | undefined;
         alwaysLoad: readonly string[] | undefined;
+        /** design/277 — the model-gate restore selector ({@link TaskSpec.restoreGatedTools}), fourth
+         *  seat of the same frozen task-start snapshot: the gate decision and the delegation carrier
+         *  read THIS, never the live spec. */
+        restoreGated: readonly string[] | true | undefined;
     };
     /** owned — the profile half of the RB-50 single decision point (model-independent by contract). */
     promptProfile: "simple" | "classic";
@@ -127,6 +131,19 @@ export interface PrepareConfigDoorsResult {
     compModel: Model | undefined;
     /** owned — the mitigations half of the RB-50 decision point (model-family fact). */
     fableMitigations: boolean;
+    /** owned, frozen — design/277 model-gate DISCLOSURE data (the application itself already
+     *  happened on {@link spec}: its `tools` is the survivor rebind when anything was removed).
+     *  prepareTask emits the notices from this after the doors return (the onNotice station);
+     *  the doors stay side-effect-free on the announcement axis. */
+    modelGate: {
+        /** gate-class → removed wire names (sorted, unique); empty map = nothing removed. */
+        removedByClass: ReadonlyMap<string, readonly string[]>;
+        /** stamped classes with no merged-table row (inert tags, fail-open — announce material). */
+        unknownClasses: readonly string[];
+        /** a not-in-force `SEMA_TOOL_MODEL_GATE` value outside the closed set (discard-announce
+         *  material; the in-force arm never lands here — it throws at the door). */
+        discardedEnvRaw: string | undefined;
+    };
     /** owned — validated deployment governance windows (undefined = ungoverned). */
     usageWindows: readonly UsageWindow[] | undefined;
     /** owned, out-param cell — created EMPTY here; the brain-call wiring later installs into

package/dist/core/runner/prepare-config-doors.js

@@ -4,6 +4,7 @@ import { resolveCheckpointStore } from "../checkpoint-store.js";
 import { preflightLockedConfig } from "../locked-config.js";
 import { assertRetentionCapability } from "../retention.js";
 import { resolveModel, resolveTaskModel, roleModelIfSet } from "../roles.js";
+import { applyToolModelGate, assertRestoreGatedToolsValue, modelIdTail } from "../tool-model-gate.js";
 import { resolveUsageWindows } from "../usage-window-store.js";
 import { deriveAskEffective, resolveAskSeamForm, resolveQuestionSeam } from "../wiring-manifest.js";
 const TASK_LIMIT_KEY_DICT = {
@@ -73,7 +74,7 @@ export function resolveTaskLimits(limits) {
     return limits;
 }
 export function isFableFamilyModelId(id) {
-    const tail = id.toLowerCase().split("/").pop() ?? "";
+    const tail = modelIdTail(id);
     return /^claude-fable-\d/.test(tail) || /^claude-mythos-5(?!\d)/.test(tail);
 }
 export function resolveModelPromptTraits(model, spec, internals) {
@@ -85,10 +86,16 @@ export function resolveModelPromptTraits(model, spec, internals) {
 export function prepareConfigDoors(input) {
     const { deps, sessions, resume, internals } = input;
     let spec = input.spec;
+    assertRestoreGatedToolsValue(spec.restoreGatedTools);
     const toolFaceSnapshot = {
         exclude: spec.excludeTools ? Object.freeze([...spec.excludeTools]) : undefined,
         defer: spec.deferTools ? Object.freeze([...spec.deferTools]) : undefined,
         alwaysLoad: spec.alwaysLoadTools ? Object.freeze([...spec.alwaysLoadTools]) : undefined,
+        restoreGated: spec.restoreGatedTools === true
+            ? true
+            : spec.restoreGatedTools !== undefined
+                ? Object.freeze([...spec.restoreGatedTools])
+                : undefined,
     };
     const promptProfile = resolveModelPromptTraits({ id: "" }, spec, internals).promptProfile;
     if (spec.resumeAt !== undefined) {
@@ -223,11 +230,34 @@ export function prepareConfigDoors(input) {
             throw e;
         }
         const perTask = spec.agents;
-        spec = { ...spec, tools: pool.map((t) => (typeof t.withAgents === "function" ? t.withAgents(perTask) : t)) };
+        spec = {
+            ...spec,
+            tools: pool.map((t) => {
+                if (typeof t.withAgents !== "function")
+                    return t;
+                const rebuilt = t.withAgents(perTask);
+                return t.modelGate !== undefined && rebuilt.modelGate === undefined ? { ...rebuilt, modelGate: t.modelGate } : rebuilt;
+            }),
+        };
     }
     const resolvedRole = resolveTaskModel(spec, deps);
     const model = resolvedRole.model;
     const fableMitigations = resolveModelPromptTraits(model, spec, internals).fableMitigations;
+    const gateDecision = applyToolModelGate({
+        tools: spec.tools,
+        modelId: model.id,
+        depsSeat: deps.toolModelGate,
+        restoreGated: toolFaceSnapshot.restoreGated,
+        envRaw: process.env.SEMA_TOOL_MODEL_GATE,
+    });
+    if (gateDecision.survivors !== undefined) {
+        spec = { ...spec, tools: gateDecision.survivors };
+    }
+    const modelGate = Object.freeze({
+        removedByClass: gateDecision.removedByClass,
+        unknownClasses: gateDecision.unknownClasses,
+        discardedEnvRaw: gateDecision.discardedEnvRaw,
+    });
     const thinking = spec.thinking ?? resolvedRole.thinking ?? model.defaultThinking;
     const compModel = spec.compactionModel
         ? resolveModel(spec.compactionModel, deps.models)
@@ -243,6 +273,7 @@ export function prepareConfigDoors(input) {
         thinking,
         compModel,
         fableMitigations,
+        modelGate,
         usageWindows,
         brainCallGuardrailRef,
         brainCallGuardrailMs,

package/dist/core/runner/prepare-memory.d.ts

@@ -1,4 +1,4 @@
-import type { BeforeWriteHook, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
+import type { BeforeWriteHook, EffectiveMemoryScopes, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
 import type { Prepared } from "./prepare-task.js";
 export interface PrepareMemoryInput {
     spec: TaskSpec;
@@ -106,5 +106,15 @@ export interface PrepareMemoryResult {
     /** The session's own frozen verdict to persist at suspend — present iff this leg ADJUDICATED an
      *  org plane (including adjudicated-empty); `undefined` for an org-less task. */
     ownOrgVerdict: import("../memory-admission.js").OwnOrgAdmissionVerdict | undefined;
+    /**
+     * design/178 v2 §2.3 (件①) — the memory-visibility OBSERVATION this phase minted for
+     * `TaskResult.effectiveMemoryScopes` (see {@link EffectiveMemoryScopes} for the state law).
+     * ALWAYS present when the phase returns: the memory-less outcomes are their own values
+     * (`none` / `memoryless`), never an absent seat — absence on the RESULT means only "prepare
+     * never completed" (this phase threw). Minted AFTER the materialize outcome (the fail-open arm
+     * sits between the admission verdict and the mount — an earlier stamp would report a mount that
+     * never happened); the deliberate-refusal `config.memory_*` throws produce no value at all.
+     */
+    effectiveMemoryScopes: EffectiveMemoryScopes;
 }
 export declare function prepareMemory(input: PrepareMemoryInput): Promise<PrepareMemoryResult>;