@sema-agent/core 7.25.0 → 7.26.0

package/dist/core/governance-codes.js

@@ -35,6 +35,7 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.consolidation_refused",
     "memory.consolidation_withheld",
     "memory.restore_withheld",
+    "memory.project_scope_absent",
     "memory.projection_failed",
     "memory.consolidation_disabled",
     "memory.consolidation_gated",
@@ -152,6 +153,7 @@ export const ENGINE_NOTICE_CODES = [
     "memory.consolidation_refused",
     "memory.consolidation_withheld",
     "memory.restore_withheld",
+    "memory.project_scope_absent",
     "route.fallback_to_primary",
     "route.classifier_unroutable",
     "route.base_url_changed_key_unchanged",
@@ -229,6 +231,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "memory.consolidation_incomplete": "operator",
     "memory.consolidation_refused": "operator",
     "memory.restore_withheld": "operator",
+    "memory.project_scope_absent": "operator",
     "route.fallback_to_primary": "operator",
     "route.classifier_unroutable": "operator",
     "route.base_url_changed_key_unchanged": "operator",

package/dist/core/hooks.d.ts

@@ -1711,6 +1711,9 @@ export interface AskCarry {
     /** #688 C3: the mechanism behind an `origin: "rule_store_unavailable"` (`store` / `call`), persisted on the row
      *  so a durable card says the same thing the synchronous card does. */
     readonly ruleStoreUnreadable?: import("./ask-origin.js").RuleStoreUnreadable;
+    /** The stamped mandate ({@link import("./tool-policy.js").AskRequest.mandated}) — the park site's
+     *  rule-offer facts read it, so a parked mandated ask offers no rule, like the live card. */
+    readonly mandated?: true;
 }
 /** What a durable row persists of an {@link AskCarry}: the fallback member COPIED (the row never aliases
  *  the gate's object; its window is already `0` — the gate's carry mint is the one writer of that

package/dist/core/mcp-probe.d.ts

@@ -0,0 +1,122 @@
+import { type McpFailureKind } from "./mcp-failure.js";
+import type { McpServerSpec, OnElicit } from "./mcp-server-spec.js";
+import type { WiringManifestMcpEntry } from "./wiring-manifest.js";
+/** One server's probe reading, beside its manifest row. `connectMs` is wall time this probe measured
+ *  for THIS server's dial — the spawn/handshake, the initial `tools/list` walk and the intake, ending
+ *  at whichever verdict the server reached (connected, failed, or the clock below) — never a number the
+ *  server reported. `tools` are the namespaced (`mcp__<server>__<tool>`) names that WOULD mount, i.e.
+ *  exactly `McpServerStatus.toolNames` after the schema gate and the per-server allowlist, so
+ *  `tools.length` equals the row's `toolCount`; a server that did not connect carries `[]`.
+ *  `errorCode` is the row's failure class, repeated here so a caller reading only this array need not
+ *  join back. */
+export interface McpProbeServerReading {
+    name: string;
+    connectMs: number;
+    tools: string[];
+    errorCode?: McpFailureKind;
+}
+/**
+ * What {@link probeMcpServers} answers.
+ *
+ * @contract mcp.probe.index_aligned — `entries` and `servers` always have the LENGTH of the `specs`
+ * the caller passed and are ordered by it: `entries[i]` and `servers[i]` both describe `specs[i]`, for
+ * every i, on every resolving call. A server that failed, that timed out, or that was never dialed
+ * keeps its slot (the row carries its `status`/`errorCode`, the reading its measured `connectMs`), so a
+ * consumer pairs its own declaration list with either array by index and never by name matching.
+ */
+export interface McpProbeResult {
+    /** The rows, verbatim as a prepared leg would publish them — same projection, same failure
+     *  vocabulary, same `liveness` snapshot, same neutralized and bounded remote text. */
+    entries: WiringManifestMcpEntry[];
+    /** The probe-only half, index-aligned with `entries` (see the contract above). */
+    servers: McpProbeServerReading[];
+}
+/** The probe's knobs. Every one of them is optional; a value outside its range is REFUSED, never
+ *  folded to the default (a bound the caller asked for and did not get is a bound nobody is keeping). */
+export interface McpProbeOptions {
+    /** The end-user identity a per-task principal header carries, exactly as `TaskSpec.principal` does
+     *  on a real leg — so a server that applies per-user rules answers the probe as it would answer the
+     *  task. */
+    principal?: string;
+    /** Per-server ceiling on the VERDICT, in whole milliseconds within `[1, MCP_ENV_MS_MAX]` (the ceiling
+     *  every env-supplied MCP bound keeps, because a larger delay is silently rewritten to 1 ms). When it
+     *  elapses, THAT server's row reads `failed` with `errorCode: "timeout"` and the walk moves on; nothing
+     *  throws. It does NOT end the dial — nothing here can — so the transport stays open until the dial
+     *  lands on its own; see the residue note on {@link probeMcpServers}.
+     *
+     *  Default: the engine's own startup-phase bound ({@link mcpStartupTimeoutMs}, env `MCP_TIMEOUT`) when a
+     *  deployment set one; absent there, this module runs no clock and the answer for that server is
+     *  whatever the dial's own request budgets produce — which bound the REQUESTS, not the dial. */
+    timeoutMs?: number;
+    /** Abort the whole probe. The call rejects with the signal's own reason (a bare `abort()` gives an
+     *  `AbortError`) AFTER every server it had opened is closed — see the residue contract on
+     *  {@link probeMcpServers}. An already-aborted signal dials nothing. */
+    signal?: AbortSignal;
+    /** The elicitation seat, for a caller that has a human behind it. Default: decline everything. */
+    onElicit?: OnElicit;
+    /** Abort reading, stated once: the call rejects with the signal's own reason when that reason is an
+     *  Error (a bare `abort()` supplies a DOMException named `AbortError`) and with this module's own
+     *  `AbortError` otherwise — a face that throws a string is a face no `catch` can read. A condition
+     *  already held when the abort lands wins: the FIRST thing that ended the walk is what it rejects
+     *  with, so a materialization's refusal is never overwritten by the abort that followed it. */
+    /** How many servers this walk PURSUES A VERDICT for at once, ≥ 1. Default 1 — one at a time, in
+     *  declaration order. Raising it trades what isolation there is for wall time; the rows and the index
+     *  alignment are unaffected.
+     *
+     *  Even at 1, `connectMs` is not a contention-free measurement: a settled dial's CLOSE is started and
+     *  not waited for, so the next dial begins while the previous transport is still shutting down.
+     *
+     *  IT IS NOT A CEILING ON OPEN TRANSPORTS, and the difference is the whole point of `timeoutMs`: a
+     *  dial the clock abandoned keeps running (nothing here can cancel it) while the walk moves on, so
+     *  with a short `timeoutMs` against an unresponsive fleet the transports actually in flight can reach
+     *  one per DECLARATION, not `concurrency`. A caller probing a large fleet through a tight clock is
+     *  choosing that: the alternative — holding the slot until the abandoned dial lands — makes one stuck
+     *  server the walk's pace, which is the thing the clock exists to prevent. */
+    concurrency?: number;
+}
+/**
+ * Connect to each declared MCP server, list its tools and close it again — no task, no run.
+ *
+ * The rows in `entries` are minted by the SAME projection a prepared leg uses, from the SAME
+ * materialization, so they are the rows that leg would publish: `connected` with the mounted tool
+ * count, `failed` with the connect-failure record as closed words (`errorCode` / `delivered` /
+ * `httpStatus`) beside the neutralized, bounded remote text, `skipped` for a declaration this probe
+ * produced no attempt record for. No word is added to the failure vocabulary
+ * ({@link import("./mcp-failure.js").MCP_FAILURE_KINDS}) and none is spelled twice.
+ *
+ * NOTHING IS REGISTERED AND NOTHING IS MOUNTED: no task registry entry, no session, no checkpoint, no
+ * store write, no `TaskEvent`. The materialized tools are dropped unread and never reach a harness, and
+ * the result carries tool NAMES, so a caller holds nothing it could invoke.
+ *
+ * FAILURE IS PER SERVER, REFUSAL IS NOT. A server that cannot be dialed, that answers a status, or that
+ * outlives `timeoutMs` takes its verdict in its own row and the walk continues. What DOES reject is the
+ * declaration set the materialization itself refuses — two names that mount under one namespace prefix
+ * are refused before any transport is touched, by that same function, so the probe answers a colliding
+ * configuration exactly as a task would rather than showing two healthy-looking rows for a pair the
+ * engine would never mount.
+ *
+ * @contract mcp.probe.zero_residue_bound — this call does not settle while a handle it opened is
+ * undisposed: every dial's handle is disposed, a dial abandoned by the clock is disposed WHEN IT LANDS,
+ * and all of them are awaited before the call resolves OR rejects. What that promises is that no
+ * connection is left owned by nobody — NOT that every child process has already exited at the instant of
+ * return, and NOT that the call itself is bounded. What bounds it, stated part by part rather than
+ * summarised into a number that would be wrong:
+ *  · a dial has two REQUEST-BUDGET phases, each carrying the startup-phase bound ({@link
+ *    mcpStartupTimeoutMs}, env `MCP_TIMEOUT`, else the SDK's 60 000 ms default): the handshake, one
+ *    request; and the initial tool listing, a PAGINATED WALK whose whole budget is that same number
+ *    (however many pages it takes — and no request at all when the peer advertises no tools). Two
+ *    budgets, so twice that, not once;
+ *  · the transport's own close ladder then reaps a stdio child that does not exit when its input closes:
+ *    at most 2 000 ms to SIGTERM, 2 000 ms more to SIGKILL;
+ *  · and ONE part is bounded by nothing here: a transport SEND carries no request deadline of its own
+ *    (the post-handshake `notifications/initialized`, an HTTP body read), so a peer that answers the
+ *    handshake and then stalls that send holds the dial — and therefore this call — open. The bound
+ *    belongs to the dial, which owns no cancellation; see `docs/KNOWN-LIMITS.md`.
+ * So, PER DIAL and against a peer that either answers or fails its requests: that dial's residue is gone
+ * within `max(timeoutMs, the handshake budget + the listing budget) + 4 000 ms`, and a server that exits
+ * on its closed input (every well-behaved one) is gone at return. THE CALL is the walk over the
+ * declarations, so its own duration is those per-dial times summed over `ceil(n / concurrency)` rounds —
+ * this is not a whole-call number, and a caller budgeting a health check must do that arithmetic itself.
+ * Against a peer that stalls a send, neither the dial nor this call has a deadline at all.
+ */
+export declare function probeMcpServers(specs: readonly McpServerSpec[], opts?: McpProbeOptions): Promise<McpProbeResult>;

package/dist/core/mcp-probe.js

@@ -0,0 +1,132 @@
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { snapshotMcpEntries } from "./locked-config.js";
+import { classifyMcpFailure, livenessOf } from "./mcp-failure.js";
+import { MCP_ENV_MS_MAX, materializeMcpTools, mcpStartupTimeoutMs } from "./mcp.js";
+import { findNamespacePrefixCollision } from "./protocol-naming.js";
+import { MCP_NAMESPACE } from "./protocol-table.js";
+import { mcpManifestEntries } from "./runner/prepare-wiring-manifest.js";
+const DECLINE_EVERY_ELICITATION = async () => ({ action: "decline" });
+function wholeInRange(name, value, min, max) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === "number" && Number.isInteger(value) && value >= min && value <= max)
+        return value;
+    const shown = typeof value === "number" ? String(value) : `a ${typeof value}`;
+    const e = new Error(`probeMcpServers: \`${name}\` must be a whole number in [${min}, ${max}] — received ${shown}`);
+    e.code = "config.mcp_probe_option";
+    throw e;
+}
+function abortCause(signal) {
+    const reason = signal.reason;
+    if (reason instanceof Error)
+        return reason;
+    const e = new Error("the MCP probe was aborted by its caller's signal");
+    e.name = "AbortError";
+    return e;
+}
+function whenAborted(signal, until) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        signal.addEventListener("abort", () => resolve(), { once: true, signal: until });
+    });
+}
+function afterMs(ms, until) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref();
+        until.addEventListener("abort", () => clearTimeout(timer), { once: true });
+    });
+}
+async function raceDial(dial, ms, signal) {
+    if (ms === undefined && signal === undefined)
+        return { kind: "settled", handle: await dial };
+    const until = new AbortController();
+    const legs = [dial.then((handle) => ({ kind: "settled", handle }))];
+    if (ms !== undefined)
+        legs.push(afterMs(ms, until.signal).then(() => ({ kind: "timeout", afterMs: ms })));
+    if (signal !== undefined)
+        legs.push(whenAborted(signal, until.signal).then(() => ({ kind: "aborted", signal })));
+    try {
+        return await Promise.race(legs);
+    }
+    finally {
+        until.abort();
+    }
+}
+function stoppedWaitingStatus(entry, ms) {
+    const condition = new McpError(ErrorCode.RequestTimeout, `the probe stopped waiting for this server's connect and initial tool listing after ${ms} ms`);
+    const { kind, delivered } = classifyMcpFailure(condition, { phase: "connect", transport: entry.transport.kind });
+    const liveness = livenessOf(kind, Date.now());
+    return { name: entry.name, status: "failed", errorCode: kind, delivered, error: condition.message, ...(liveness !== undefined ? { liveness } : {}) };
+}
+export async function probeMcpServers(specs, opts = {}) {
+    const declared = snapshotMcpEntries(specs);
+    const timeoutMs = wholeInRange("timeoutMs", opts.timeoutMs, 1, MCP_ENV_MS_MAX) ?? mcpStartupTimeoutMs();
+    const concurrency = wholeInRange("concurrency", opts.concurrency, 1, Number.MAX_SAFE_INTEGER) ?? 1;
+    const onElicit = opts.onElicit ?? DECLINE_EVERY_ELICITATION;
+    const signal = opts.signal;
+    if (findNamespacePrefixCollision(MCP_NAMESPACE, declared.map((e) => e.name)) !== undefined) {
+        await materializeMcpTools(declared, opts.principal, onElicit);
+    }
+    const statuses = [];
+    const servers = new Array(declared.length);
+    const teardowns = [];
+    let fatal;
+    const probeOne = async (i) => {
+        const entry = declared[i];
+        const started = performance.now();
+        const elapsed = () => Math.round(performance.now() - started);
+        const dial = materializeMcpTools([entry], opts.principal, onElicit);
+        const verdict = await raceDial(dial, timeoutMs, signal);
+        if (verdict.kind === "settled") {
+            const found = verdict.handle.statuses.find((s) => s.name === entry.name);
+            const status = found === undefined ? undefined : { ...found };
+            teardowns.push(verdict.handle.dispose());
+            if (status !== undefined)
+                statuses.push(status);
+            servers[i] = { name: entry.name, connectMs: elapsed(), tools: status?.toolNames ?? [], ...(status?.errorCode !== undefined ? { errorCode: status.errorCode } : {}) };
+            return;
+        }
+        teardowns.push(dial.then((h) => h.dispose(), () => undefined));
+        if (verdict.kind === "aborted") {
+            fatal ??= { cause: abortCause(verdict.signal) };
+            return;
+        }
+        const status = stoppedWaitingStatus(entry, verdict.afterMs);
+        statuses.push(status);
+        servers[i] = { name: entry.name, connectMs: elapsed(), tools: [], errorCode: status.errorCode };
+    };
+    if (signal?.aborted === true)
+        fatal = { cause: abortCause(signal) };
+    let next = 0;
+    const lane = async () => {
+        for (;;) {
+            if (signal?.aborted === true)
+                fatal ??= { cause: abortCause(signal) };
+            if (fatal !== undefined)
+                return;
+            const i = next++;
+            if (i >= declared.length)
+                return;
+            try {
+                await probeOne(i);
+            }
+            catch (e) {
+                fatal ??= { cause: e };
+                return;
+            }
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.min(concurrency, declared.length) }, lane));
+    }
+    finally {
+        await Promise.allSettled(teardowns);
+    }
+    if (fatal === undefined && signal?.aborted === true)
+        fatal = { cause: abortCause(signal) };
+    if (fatal !== undefined)
+        throw fatal.cause;
+    return { entries: mcpManifestEntries(declared, statuses), servers };
+}

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

@@ -5,7 +5,7 @@ import { type OriginClearanceRow } from "./origin-clearance.js";
 import { type CommittedBinding, type EraseMemoryEntriesInput, type MemoryErasureAttestation, type TransferEvidence } from "./file-backend.js";
 import { type MemoryExportBundle, type MemoryImportReport } from "./export-bundle.js";
 import { type ChallengeAssignment, type ChallengeEvent, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, type MemoryPartitionIncidentSink, type RetrievedAccountRow, type SessionPollutionMarkOutcome, type SessionPollutionRecord, type SessionCaptureOptOutMarkOutcome, type SessionCaptureOptOutRecord, type SessionCaptureRecordStore } from "./layout.js";
-import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemoryEntry, MemoryEntryOrigin, MemoryScopeEnumeration, MemorySessionHandle, ScanFinding, SessionCaptureResidueSweep } from "./types.js";
+import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemoryEntry, MemoryEntryHeader, MemoryEntryOrigin, MemoryScopeEnumeration, MemorySessionHandle, ScanFinding, SessionCaptureResidueSweep } from "./types.js";
 /**
  * The RECALL-FRAMING sentence shared by every arm of the `# Memory` prompt section — the one
  * sentence that tells the model what a recalled memory IS (background context, not an instruction)
@@ -1206,6 +1206,7 @@ export declare class MemoryEngine {
     materialize(scopes: readonly string[], writeScope: string | null, opts?: {
         adoptionRestricted?: boolean;
         sessionId?: string;
+        shadowNames?: ReadonlyMap<string, string>;
     }): Promise<MemorySessionHandle>;
     inject(handle: MemorySessionHandle, opts?: {
         writeToolMounted?: boolean;
@@ -1527,6 +1528,10 @@ export declare class MemoryEngine {
      *  retrieval view (copy-out File), else the backend itself (Pg/TiDB shapes — naturally committed
      *  and side-effect-free per the getByIds contract clause). */
     private committedAuditFace;
+    /** The COMMITTED header listing of `scopes` through the face above: the name source of the
+     *  write-home rule, and the reason an in-session edit of a `name:` field retires nothing before
+     *  the harvest boundary admits it. Side-effect-free (`audit: false`). */
+    listCommittedHeaders(scopes: readonly string[]): Promise<MemoryEntryHeader[]>;
     private static originClearRefusal;
     /** #468② — the most recent COMPLETED clearance of `entryId` in `rows`, or `undefined` when there is none.
      *  Pure over rows the caller ALREADY read (this opens no second read of the account — the not-marked

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

@@ -10,6 +10,7 @@ import { committedDistilledOf, committedOriginOf, computeEntryRev, consolidation
 import { MEMORY_PROVENANCE_RECALL_SENTENCE, memoryExposureIndexRow, parseMemoryExposureIndexRow } from "./provenance-wording.js";
 import { isInstructionEntry } from "./header-hints.js";
 import { ConsolidationRefusedError, CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS, CONSOLIDATION_SEAT_FREEZE_GRACE_MS, consolidationTypeEligible, deriveProductSlug, deriveSupersededSet, isValidConsolidationPlanId, listConsolidationPlanIds, productAddPatch, quarantineCorruptPlan, readConsolidationGateFile, readConsolidationPlan, readIntentCredentials, recordActiveSetBaseline, recordConsolidationSession, sessionsSinceExcludingCurrent, recordIntentCredentials, scanRefusalCeiling, screenConsolidationOptions, supersessionFuseCeiling, updateConsolidationGate, writeConsolidationPlan, } from "./consolidation.js";
+import { deriveShadowedSet } from "./shadowing.js";
 import { classifySessionSettlements, clearHoldResolution, closeSessionAccount, disposeHold, effectiveSettlements, expireOverdueSettlements, foreignDanglingSessionAccounts, markHoldReleased, openInstructionHold, openSessionAccount, readHoldCustody, readHolds, reconcileHolds, replayExternalSettlementEffects, resolveHoldRecord, resolveSessionAccountRecord, resolveSettlementRecord, sessionSettlements, sessionUnattributedSet, emptyUnattributedSet, convertV1SidecarKeys, } from "./delegation-settlement.js";
 import { noReplaceRestore, retireStagingToCustody, stagingPathBeside } from "./delegation-settlement.js";
 import { markOriginClearanceTombstoned, openOriginClearance, readOriginClearances, settleOriginClearance } from "./origin-clearance.js";
@@ -1330,6 +1331,7 @@ export class MemoryEngine {
             repoIndexTargets: new Map(),
             indexBaselineLines: 0,
             indexText: "",
+            ...(opts?.shadowNames !== undefined ? { shadowNames: opts.shadowNames } : {}),
             ...(restricted ? { adoptionRestricted: true } : {}),
             ...(sessionAccountFailed ? { sessionAccountFailed: true } : {}),
         };
@@ -4047,6 +4049,11 @@ export class MemoryEngine {
         const b = this.backend;
         return b.restrictedAdoptionView?.({ audit: false }) ?? b.retrievalView?.() ?? this.backend;
     }
+    async listCommittedHeaders(scopes) {
+        if (scopes.length === 0)
+            return [];
+        return this.committedAuditFace().listHeaders(scopes);
+    }
     static originClearRefusal(code, message, detail) {
         const e = new Error(message);
         e.code = code;
@@ -4341,6 +4348,17 @@ export class MemoryEngine {
         const exposedProjectionTargets = new Set();
         const supersededIds = deriveSupersededSet(headers, { excluded: (id) => excludedIds.has(id) });
         const supersededTargets = new Set();
+        const shadowedIds = deriveShadowedSet(headers, handle.writeScope, {
+            excluded: (id) => excludedIds.has(id) || supersededIds.has(id),
+            ...(handle.shadowNames !== undefined ? { shadowNames: handle.shadowNames } : {}),
+        });
+        const shadowedCounts = new Map();
+        for (const h of headers) {
+            if (excludedIds.has(h.id) || !shadowedIds.has(h.id))
+                continue;
+            shadowedCounts.set(h.scope, (shadowedCounts.get(h.scope) ?? 0) + 1);
+        }
+        const shadowedTargets = new Set();
         for (const h of headers) {
             const repoTarget = handle.repoIndexTargets?.get(h.id);
             const target = repoTarget ?? relative(indexBase, canonicalize(join(scopeDirFor(this.memoryDir, this.controlDir, h.scope), `${h.slug}.md`)));
@@ -4349,8 +4367,9 @@ export class MemoryEngine {
                 continue;
             }
             const superseded = supersededIds.has(h.id);
+            const shadowed = shadowedIds.has(h.id);
             if (carryIndex && h.exposure === "external") {
-                if (!superseded)
+                if (!superseded && !shadowed)
                     exposedById.set(h.id, h);
                 exposedProjectionTargets.add(target);
                 continue;
@@ -4359,8 +4378,13 @@ export class MemoryEngine {
                 supersededTargets.add(target);
                 continue;
             }
+            if (shadowed) {
+                shadowedTargets.add(target);
+                continue;
+            }
             expected.set(target, h);
         }
+        handle.shadowedByScope = shadowedCounts;
         const covered = new Set();
         const handleCovered = new Set();
         const keptByTarget = new Map();
@@ -4376,7 +4400,7 @@ export class MemoryEngine {
             return prev;
         };
         const foldTarget = (t) => foldDots(t.toLowerCase());
-        const knownTargetsFolded = new Set([...expected.keys(), ...excludedTargets, ...exposedProjectionTargets, ...supersededTargets].map(foldTarget));
+        const knownTargetsFolded = new Set([...expected.keys(), ...excludedTargets, ...exposedProjectionTargets, ...supersededTargets, ...shadowedTargets].map(foldTarget));
         const pathTokenAt = (folded, idx, len) => {
             const isPathChar = (ch) => /[a-z0-9._\-/\\]/.test(ch);
             let s = idx;
@@ -4428,6 +4452,10 @@ export class MemoryEngine {
                 warnings?.push(`MEMORY.md index line for ${target} removed: a newer consolidated entry supersedes it (the entry stays readable via memory_get)`);
                 continue;
             }
+            if (shadowedTargets.has(target)) {
+                warnings?.push(`MEMORY.md index line for ${target} removed: a same-named entry in this session's write home shadows it (the entry stays readable via memory_get)`);
+                continue;
+            }
             if (covered.has(target)) {
                 if (line === keptByTarget.get(target))
                     continue;

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

@@ -9,6 +9,7 @@ export { readV2HeaderHints, isInstructionEntry, type V2HeaderHints } from "./hea
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, committedOriginOf, originEquals, ambiguousOriginRepresentation, type ParsedEntryFile } from "./frontmatter.js";
 export { consolidationExposedFrontmatter } from "./frontmatter.js";
 export { committedDistilledOf, distilledEquals } from "./frontmatter.js";
+export { deriveShadowedSet } from "./shadowing.js";
 export { CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, type ConsolidationGateRead, type ConsolidationGateRow, type ConsolidationIntent, type ConsolidationIntentCredentialRow, type ConsolidationLeaseSeat, type ConsolidationProductProposal, type ConsolidationProposal, type MemoryConsolidationOptions, CONSOLIDATION_RUN_STOP_REASONS, type ConsolidationRunStopReason, } from "./consolidation.js";
 export { DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, MEMORY_DISTILLER_PURITY_CONTRACT_V1, detectCleanArmVerbatimLeak, type CleanArmLeakFinding, type CleanArmLeakVerdict, type MemoryDistillerPurityContract, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, type ConsolidationDistillFn, type ConsolidationDriveCycleRow, type ConsolidationDriveEngine, type ConsolidationDriveResult, type ConsolidationFoldState, type DistillerCandidate, type DistillerChatAnswer, type DistillerChatFn, type DistillerChatRequest, type FuseSchedule, type LlmConsolidationPlan, type LlmConsolidationPlanArm, type LlmConsolidationPlanProduct, type LlmDistillerContract, type MintLlmConsolidationPlanResult, type PlanParseRepairs, type SanitizedLlmGroups, } from "./distiller.js";
 export { CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, type ConsolidationDriverEngine, type ConsolidationDriverRunRow, type ConsolidationRunReceipt, type RunMemoryConsolidationOptions, } from "./consolidation-driver.js";

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

@@ -9,6 +9,7 @@ export { readV2HeaderHints, isInstructionEntry } from "./header-hints.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, committedOriginOf, originEquals, ambiguousOriginRepresentation } from "./frontmatter.js";
 export { consolidationExposedFrontmatter } from "./frontmatter.js";
 export { committedDistilledOf, distilledEquals } from "./frontmatter.js";
+export { deriveShadowedSet } from "./shadowing.js";
 export { CONSOLIDATION_DEFAULTS, ConsolidationRefusedError, MEMORY_SEARCH_SUPERSEDED_TAG, consolidationTypeEligible, deriveSupersededSet, memorySupersededNote, readIntentCredentials, supersessionFuseCeiling, CONSOLIDATION_RUN_STOP_REASONS, } from "./consolidation.js";
 export { DISTILLER_DEFAULT_MAX_INPUTS_PER_PRODUCT, LLM_DISTILLER_CONTRACT, LLM_DISTILLER_CONTRACT_DL2, LLM_DISTILLER_CONTRACT_DL3, LLM_DISTILLER_CONTRACTS, MEMORY_DISTILLER_CONTRACT_V1, contractGroupingDiff, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, MEMORY_DISTILLER_PURITY_CONTRACT_V1, detectCleanArmVerbatimLeak, openAiCompatChatSeat, parseJsonAnswer, planParseRepairs, sanitizeLlmGroups, scheduleUnderFuse, } from "./distiller.js";
 export { CONSOLIDATION_DRIVER_PLANS_DIR, CONSOLIDATION_DRIVER_RUNS_FILE, archiveDistillerPlan, readConsolidationDriverRun, runMemoryConsolidationDriver, } from "./consolidation-driver.js";

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

@@ -0,0 +1,58 @@
+/**
+ * The WRITE-HOME NAME rule: one predicate, four existing read seats (index rows, search, listing,
+ * bare-slug resolution). When the session's write home already carries an entry by a given NAME,
+ * the read-only layers' same-named entries leave the DEFAULT read face. Nothing is written, moved
+ * or deleted — the shadowed entry stays fully readable as evidence by id and through the
+ * `includeShadowed` faces, the write home's own entries are never affected, read-only layers never
+ * shadow each other, and a session with no write home derives the empty set (byte-identical
+ * behaviour to a tree without this module).
+ *
+ * It lands at the seats the supersession derivation in `consolidation.ts` lands at, in the same
+ * shape: a second answer to "what is on the default face" would be a drift seam. The two are
+ * orthogonal and compose — supersession is a same-scope data fact carried by consolidation edges,
+ * shadowing a cross-layer session fact that depends on where this session writes — so an entry can
+ * be both, and each is separately disclosed.
+ *
+ * TWO LAWS AUTHORIZE A SHADOW. (1) The NAME SOURCE is a committed header face: an in-session
+ * `name:` edit retires nothing before the harvest boundary admits it. (2) The CARRIER must itself
+ * STAND ON THE SEAT'S OWN DEFAULT FACE — withheld, superseded and undeliverable are not three
+ * conditions but three ways of not standing there, which is how the caller passes them (one
+ * `excluded` predicate, plus a delivery probe for the one part a header listing cannot answer).
+ * Stating it as three independent conditions is what a counterexample punched through: a
+ * write-home entry replaced by a consolidation product is committed, unchallenged and deliverable,
+ * yet it is not on the default face, and letting it shadow took BOTH same-named answers off every
+ * enumeration at once. The write home's answer and the shadowed one never vanish together.
+ */
+import type { MemoryEntryHeader } from "./types.js";
+/** The name an entry is known by on the read faces: its frontmatter `name`, else the last segment
+ *  of its slug — the expression the index row's own title is built from, so "same name" means what
+ *  a reader of the injected index would call the same name. Exact equality: no case folding (the
+ *  frontmatter parse already trimmed), no type or scope participation. */
+export declare function shadowKeyOf(h: Pick<MemoryEntryHeader, "name" | "slug">): string;
+/** The NAMES the session's write home carries, each mapped to the id carrying it (lowest id wins
+ *  when the home holds several under one name — deterministic, never a scan order). A read-only
+ *  layering (`writeScope: null`) carries nothing. */
+export declare function shadowNamesOf(headers: readonly MemoryEntryHeader[], writeScope: string | null, opts?: {
+    excluded?: (id: string) => boolean;
+}): Map<string, string>;
+/**
+ * Derive the SHADOWED set from a header listing: shadowed entry id → the write-home entry id whose
+ * name retires it from the default face.
+ *
+ * `opts.shadowNames`, when given, IS the name map (the caller computed it — across planes, or from
+ * a listing this one does not contain); absent, the map is derived from these same headers through
+ * {@link shadowNamesOf}. One rule either way.
+ *
+ * @contract memory.read_face.write_home_name_wins — a read-only layer's entry whose name the
+ * session's write home already carries leaves the default read face (index row, search hit,
+ * listing row, bare-slug resolution) and stays fully readable as evidence by id; nothing is
+ * written, moved or deleted, and the write home's own entries are never affected.
+ */
+export declare function deriveShadowedSet(headers: readonly MemoryEntryHeader[], writeScope: string | null, opts?: {
+    excluded?: (id: string) => boolean;
+    shadowNames?: ReadonlyMap<string, string>;
+}): Map<string, string>;
+/** memory_get head note for a shadowed entry (delivery proceeds — disclosure, never refusal). */
+export declare function memoryShadowedNote(shadowingId: string): string;
+/** The tag suffixed to a search hit / listing row when a shadowed entry is retrieved explicitly. */
+export declare const MEMORY_SEARCH_SHADOWED_TAG = "[shadowed]";

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

@@ -0,0 +1,40 @@
+export function shadowKeyOf(h) {
+    return h.name ?? h.slug.split("/").pop() ?? h.slug;
+}
+export function shadowNamesOf(headers, writeScope, opts = {}) {
+    const out = new Map();
+    if (writeScope === null)
+        return out;
+    for (const h of headers) {
+        if (h.scope !== writeScope)
+            continue;
+        if (opts.excluded?.(h.id) === true)
+            continue;
+        const key = shadowKeyOf(h);
+        if (key === "")
+            continue;
+        const prior = out.get(key);
+        if (prior === undefined || h.id < prior)
+            out.set(key, h.id);
+    }
+    return out;
+}
+export function deriveShadowedSet(headers, writeScope, opts = {}) {
+    const names = opts.shadowNames ?? shadowNamesOf(headers, writeScope, opts);
+    const out = new Map();
+    if (names.size === 0)
+        return out;
+    for (const h of headers) {
+        if (h.scope === writeScope)
+            continue;
+        const carrier = names.get(shadowKeyOf(h));
+        if (carrier === undefined || carrier === h.id)
+            continue;
+        out.set(h.id, carrier);
+    }
+    return out;
+}
+export function memoryShadowedNote(shadowingId) {
+    return `note: a same-named entry in this session's write home shadows this one — memory entry ${shadowingId} carries the form this session reads by default; this entry remains readable as evidence.`;
+}
+export const MEMORY_SEARCH_SHADOWED_TAG = "[shadowed]";

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

@@ -32,7 +32,7 @@
  * so the engine's abort path stays the abort path.
  */
 import type { ToolSpec } from "../types.js";
-import type { MemoryBackend } from "./types.js";
+import type { MemoryBackend, MemoryEntryHeader } from "./types.js";
 export declare const MEMORY_SEARCH_TOOL_NAME = "memory_search";
 export declare const MEMORY_GET_TOOL_NAME = "memory_get";
 /** #493 件① — the enumeration face. NOT `memory_list`: that wire name (and the `core.memory_list@1`
@@ -108,6 +108,15 @@ export interface MemoryEnginePlane {
      * hosts and tests) and nothing is asserted: the factory's behaviour is byte-identical to before.
      */
     enginePlaneProvenance?: "off" | "carry";
+    /**
+     * The plane's COMMITTED header listing — the name source of the write-home rule
+     * ({@link import("./shadowing.js").deriveShadowedSet}). Wired to
+     * `MemoryEngine.listCommittedHeaders`, it is what makes an in-session edit of a `name:` field
+     * retire nothing before the harvest boundary admits it. ABSENT ⇒ this plane contributes no
+     * write-home names, so nothing on any plane is shadowed and every face below is byte-identical
+     * to a deployment without the rule (engine-direct hosts and tests).
+     */
+    committedHeaders?: () => Promise<MemoryEntryHeader[]>;
 }
 export interface MemoryEngineToolsOptions {
     planes: ReadonlyArray<MemoryEnginePlane>;
@@ -135,6 +144,14 @@ export interface MemoryEngineToolsOptions {
      *   even over a store that carries marked entries (the knob's whole meaning).
      */
     provenance?: "off" | "carry";
+    /**
+     * The session's WRITE HOME scope — the layer every write of this session routes to. The
+     * write-home name rule's one input beside the headers: a read-only layer's entry whose name this
+     * scope already carries leaves the DEFAULT face of all three tools (retrievable through
+     * `includeShadowed` and by id). ABSENT or `null` ⇒ no write home is declared to these faces and
+     * nothing is ever shadowed — the pre-rule bytes.
+     */
+    writeScope?: string | null;
 }
 /**
  * An unmarked search hit — the pre-336 hit shape, `slug` required as before. `exposure` is a
@@ -154,6 +171,9 @@ export interface CleanMemorySearchHit {
     /** design/339 §3.4 — present ⇔ this hit is SUPERSEDED (retrieved via `includeSuperseded`; the
      *  default face filters such hits out) — the value is the standing carrier entry's id. */
     supersededBy?: string;
+    /** Present ⇔ this hit is SHADOWED (retrieved via `includeShadowed`; the default face filters
+     *  such hits out) — the value is the write-home entry id whose name retires it. */
+    shadowedBy?: string;
 }
 /**
  * design/336 §5.2 — a MARKED hit is an OPAQUE HANDLE: id/scope/score/age/size plus the exposure
@@ -175,6 +195,8 @@ export interface ExposedMemorySearchHit {
     description?: never;
     /** design/339 §3.4 — see {@link CleanMemorySearchHit.supersededBy} (same seat on the handle shape). */
     supersededBy?: string;
+    /** See {@link CleanMemorySearchHit.shadowedBy} (same seat on the handle shape). */
+    shadowedBy?: string;
 }
 /**
  * The search hit union (design/336 B5 — a DISCRIMINATED union on `exposure`, deliberately not an
@@ -220,6 +242,10 @@ export interface MemoryGetDetails {
      *  the standing carrier entry's id (the disclosure note's structured half). Delivery proceeds —
      *  supersession is disclosure/ordering, never withholding. */
     supersededBy?: string;
+    /** Present on an `ok` delivery of a SHADOWED entry: the write-home entry id whose name retires
+     *  it from this session's default face (the head note's structured half). Delivery proceeds —
+     *  the rule is disclosure/ordering, never withholding. */
+    shadowedBy?: string;
 }
 /**
  * #493 件① — one row of the memory_index enumeration. The same discriminated shape law as the
@@ -239,6 +265,9 @@ export interface CleanMemoryIndexRow {
     /** Present ⇔ this row is SUPERSEDED (listed via `includeSuperseded`; the default face filters
      *  such rows out) — the value is the standing carrier entry's id. */
     supersededBy?: string;
+    /** Present ⇔ this row is SHADOWED (listed via `includeShadowed`; the default face filters such
+     *  rows out) — the value is the write-home entry id whose name retires it. */
+    shadowedBy?: string;
 }
 /** The opaque marked-row handle (carry mode) — same posture as {@link ExposedMemorySearchHit}. */
 export interface ExposedMemoryIndexRow {
@@ -251,6 +280,7 @@ export interface ExposedMemoryIndexRow {
     name?: never;
     description?: never;
     supersededBy?: string;
+    shadowedBy?: string;
 }
 export type MemoryIndexRow = CleanMemoryIndexRow | ExposedMemoryIndexRow;
 export interface MemoryIndexDetails {
@@ -265,6 +295,8 @@ export interface MemoryIndexDetails {
     total?: number;
     /** Superseded rows the default face hid (absent when zero or when `includeSuperseded` was passed). */
     supersededHidden?: number;
+    /** Shadowed rows the default face hid (absent when zero or when `includeShadowed` was passed). */
+    shadowedHidden?: number;
     /** Present ⇔ more rows follow — pass it as the next call's `offset`. */
     nextOffset?: number;
     /** The listing revision this page was served against (a stateless digest of the ordered id