@sema-agent/core 7.25.0 → 7.26.0

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

@@ -6,6 +6,7 @@ import { formatMemoryAge } from "../memory-recall.js";
 import { committedOriginOf } from "./frontmatter.js";
 import { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_INDEX_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, MEMORY_SEARCH_BAND_ORDER_HEADER } from "./provenance-wording.js";
 import { deriveSupersededSet, memorySupersededNote, MEMORY_SEARCH_SUPERSEDED_TAG } from "./consolidation.js";
+import { deriveShadowedSet, memoryShadowedNote, shadowNamesOf, MEMORY_SEARCH_SHADOWED_TAG } from "./shadowing.js";
 import { toolFace } from "../tool-catalog-entries.js";
 export const MEMORY_SEARCH_TOOL_NAME = "memory_search";
 export const MEMORY_GET_TOOL_NAME = "memory_get";
@@ -69,9 +70,10 @@ const INDEX_DESCRIPTION = [
     "",
     `When to use it: when ${MEMORY_SEARCH_TOOL_NAME} comes up empty but the fact should exist, when the ` +
         `injected memory index says it was truncated, or to survey what is stored at all. The listing is ` +
-        `complete for the ACTIVE set: an entry absent across all pages is either not mounted or superseded ` +
-        `by a newer consolidated entry (superseded rows are hidden by default, their count is always ` +
-        `disclosed, and includeSuperseded lists them too). The order is structural (scope, then name), NOT ` +
+        `complete for the ACTIVE set: an entry absent across all pages is either not mounted, superseded ` +
+        `by a newer consolidated entry, or shadowed by a same-named entry in this session's write home ` +
+        `(both are hidden by default, both counts are always disclosed, and includeSuperseded / ` +
+        `includeShadowed list them too). The order is structural (scope, then name), NOT ` +
         `by relevance — when checking whether something exists, page through to the last page before ` +
         `concluding it does not; the row you need may sit at the end, and early pages full of routine ` +
         `entries say nothing about the later ones. Pages read the live store: on a multi-page pass, send ` +
@@ -173,12 +175,56 @@ export function createMemoryEngineTools(opts) {
         const scopeSet = new Set(plane.scopes);
         return (await plane.backend.getByIds(ids)).filter((e) => scopeSet.has(e.scope) && e.frontmatter.deleted !== true);
     };
-    const supersededOf = async (plane, exclusions) => {
+    const servedHeaders = async (plane) => {
         if (plane.scopes.length === 0)
-            return new Map();
+            return [];
         const face = plane.backend.retrievalView?.() ?? plane.backend;
-        const headers = await face.listHeaders(plane.scopes);
-        return deriveSupersededSet(headers, { excluded: (id) => exclusions?.has(id) === true });
+        return face.listHeaders(plane.scopes);
+    };
+    const supersededOf = async (plane, exclusions) => deriveSupersededSet(await servedHeaders(plane), { excluded: (id) => exclusions?.has(id) === true });
+    const planeFaceOf = async (plane, excluded) => {
+        const headers = await servedHeaders(plane);
+        return { headers, superseded: deriveSupersededSet(headers, { excluded: (id) => excluded?.has(id) === true }) };
+    };
+    const shadowNamesAcross = async (exclusions, faces = []) => {
+        const out = new Map();
+        const writeScope = opts.writeScope;
+        if (writeScope === undefined || writeScope === null)
+            return out;
+        for (let i = 0; i < planes.length; i++) {
+            const plane = planes[i];
+            if (!plane.scopes.includes(writeScope))
+                continue;
+            const committed = await plane.committedHeaders?.();
+            if (committed === undefined)
+                continue;
+            const face = faces[i] ?? (await planeFaceOf(plane, exclusions[i]));
+            const excluded = exclusions[i];
+            const standing = committed.filter((h) => excluded?.has(h.id) !== true && !face.superseded.has(h.id));
+            for (const [name, id] of shadowNamesOf(standing, writeScope)) {
+                const prior = out.get(name);
+                if (prior === undefined || id < prior)
+                    out.set(name, id);
+            }
+        }
+        return out;
+    };
+    const shadowedOf = (headers, names) => names.size === 0 ? new Map() : deriveShadowedSet(headers, opts.writeScope ?? null, { shadowNames: names });
+    const pruneUndeliverableCarriers = async (maps) => {
+        const carriers = new Set();
+        for (const m of maps)
+            for (const id of m.values())
+                carriers.add(id);
+        if (carriers.size === 0)
+            return [...maps];
+        const ids = [...carriers];
+        const live = new Set();
+        for (const plane of planes)
+            for (const e of await getWithinScopes(plane, ids))
+                live.add(e.id);
+        if (live.size === carriers.size)
+            return [...maps];
+        return maps.map((m) => new Map([...m].filter(([, carrier]) => live.has(carrier))));
     };
     const searchTool = {
         name: MEMORY_SEARCH_TOOL_NAME,
@@ -190,9 +236,12 @@ export function createMemoryEngineTools(opts) {
             includeSuperseded: Type.Optional(Type.Boolean({
                 description: "Also return entries a newer consolidated entry has superseded (kept as evidence; hidden from results by default). Superseded hits are tagged, with the superseding entry's id.",
             })),
+            includeShadowed: Type.Optional(Type.Boolean({
+                description: "Also return entries a same-named entry in this session's write home shadows (kept as evidence; hidden from results by default). Shadowed hits are tagged, with the shadowing entry's id.",
+            })),
         }, { additionalProperties: false }),
         execute: async (args, ctx) => {
-            const { query, limit: rawLimit, includeSuperseded } = args;
+            const { query, limit: rawLimit, includeSuperseded, includeShadowed } = args;
             const signal = ctx.signal;
             if (query.trim() === "") {
                 return refusedSearch("empty_query", "query must be non-empty — pass the concrete keywords a past memory entry would contain.");
@@ -208,11 +257,15 @@ export function createMemoryEngineTools(opts) {
                 }
             }
             const supersededMaps = [];
+            const shadowedMaps = [];
             try {
-                for (let i = 0; i < planes.length; i++) {
-                    const plane = planes[i];
-                    supersededMaps.push(plane === undefined ? new Map() : await supersededOf(plane, exclusions[i]));
-                }
+                const faces = [];
+                for (let i = 0; i < planes.length; i++)
+                    faces.push(await planeFaceOf(planes[i], exclusions[i]));
+                for (const face of faces)
+                    supersededMaps.push(face.superseded);
+                const names = await shadowNamesAcross(exclusions, faces);
+                shadowedMaps.push(...(await pruneUndeliverableCarriers(faces.map((f) => shadowedOf(f.headers, names)))));
             }
             catch (err) {
                 if (signal?.aborted === true)
@@ -226,13 +279,16 @@ export function createMemoryEngineTools(opts) {
                     if (plane.scopes.length === 0)
                         continue;
                     const supersededSlots = includeSuperseded === true ? 0 : supersededMaps[i]?.size ?? 0;
-                    const askFor = (carry ? limit + (exclusions[i]?.size ?? 0) : limit) + supersededSlots;
+                    const shadowedSlots = includeShadowed === true ? 0 : shadowedMaps[i]?.size ?? 0;
+                    const askFor = (carry ? limit + (exclusions[i]?.size ?? 0) : limit) + supersededSlots + shadowedSlots;
                     const hits = await plane.backend.search(query, plane.scopes, { limit: askFor, ...(carry ? { exposureBands: true } : {}) });
                     for (const h of hits) {
                         if (exclusions[i]?.has(h.id))
                             continue;
                         if (includeSuperseded !== true && supersededMaps[i]?.has(h.id))
                             continue;
+                        if (includeShadowed !== true && shadowedMaps[i]?.has(h.id))
+                            continue;
                         merged.push({ ...h, planeIndex: i });
                     }
                 }
@@ -292,11 +348,13 @@ export function createMemoryEngineTools(opts) {
                 const h = live[i];
                 const exposed = exposedFlags[i];
                 const supersededBy = supersededMaps[h.planeIndex]?.get(h.id);
-                const supersededSuffix = supersededBy !== undefined ? ` ${MEMORY_SEARCH_SUPERSEDED_TAG}` : "";
+                const shadowedBy = shadowedMaps[h.planeIndex]?.get(h.id);
+                const tags = `${supersededBy !== undefined ? ` ${MEMORY_SEARCH_SUPERSEDED_TAG}` : ""}${shadowedBy !== undefined ? ` ${MEMORY_SEARCH_SHADOWED_TAG}` : ""}`;
+                const offFace = { ...(supersededBy !== undefined ? { supersededBy } : {}), ...(shadowedBy !== undefined ? { shadowedBy } : {}) };
                 if (exposed) {
-                    hits.push({ exposure: "external", id: h.id, scope: h.scope, score: h.score, mtimeMs: h.mtimeMs, sizeBytes: h.sizeBytes, ...(supersededBy !== undefined ? { supersededBy } : {}) });
+                    hits.push({ exposure: "external", id: h.id, scope: h.scope, score: h.score, mtimeMs: h.mtimeMs, sizeBytes: h.sizeBytes, ...offFace });
                     lines.push("");
-                    lines.push(`${i + 1}. [mem:${h.id}] ${MEMORY_EXPOSURE_HANDLE_TAG}${supersededSuffix} (scope ${inlineUntrusted(h.scope, 80)}, score ${h.score.toFixed(3)}, ${ageOf(now, h.mtimeMs)}) — read it with ${MEMORY_GET_TOOL_NAME} id ${h.id}`);
+                    lines.push(`${i + 1}. [mem:${h.id}] ${MEMORY_EXPOSURE_HANDLE_TAG}${tags} (scope ${inlineUntrusted(h.scope, 80)}, score ${h.score.toFixed(3)}, ${ageOf(now, h.mtimeMs)}) — read it with ${MEMORY_GET_TOOL_NAME} id ${h.id}`);
                     continue;
                 }
                 hits.push({
@@ -308,11 +366,11 @@ export function createMemoryEngineTools(opts) {
                     score: h.score,
                     mtimeMs: h.mtimeMs,
                     sizeBytes: h.sizeBytes,
-                    ...(supersededBy !== undefined ? { supersededBy } : {}),
+                    ...offFace,
                 });
                 const hook = h.description ? ` — ${inlineUntrusted(h.description, 200)}` : "";
                 lines.push("");
-                lines.push(`${i + 1}. ${entryPath(h.scope, h.slug)}${supersededSuffix}${hook} (id ${h.id}, score ${h.score.toFixed(3)}, ${ageOf(now, h.mtimeMs)})`);
+                lines.push(`${i + 1}. ${entryPath(h.scope, h.slug)}${tags}${hook} (id ${h.id}, score ${h.score.toFixed(3)}, ${ageOf(now, h.mtimeMs)})`);
                 const body = (entryById.get(h.id)?.body ?? "").trim();
                 if (body !== "")
                     lines.push(delimitUntrusted(`memory entry ${h.slug}`, body, MEMORY_SEARCH_SNIPPET_CAP));
@@ -349,6 +407,7 @@ export function createMemoryEngineTools(opts) {
             const lineCursor = Math.max(0, Math.floor(rawLineCursor ?? 0) || 0);
             let entry;
             let entryPlane;
+            let entryHeader;
             let mtimeMs;
             try {
                 if (id !== undefined) {
@@ -365,7 +424,8 @@ export function createMemoryEngineTools(opts) {
                             `If the id might be misremembered: ${MEMORY_SEARCH_TOOL_NAME} finds entries by keyword, and ` +
                             `${MEMORY_INDEX_TOOL_NAME} lists every mounted entry with its exact id and slug.`, "not_found", { id });
                     }
-                    mtimeMs = (await entryPlane.backend.listHeaders(entryPlane.scopes)).find((h) => h.id === entry.id)?.mtimeMs;
+                    entryHeader = (await entryPlane.backend.listHeaders(entryPlane.scopes)).find((h) => h.id === entry.id);
+                    mtimeMs = entryHeader?.mtimeMs;
                 }
                 else {
                     const matches = [];
@@ -388,6 +448,17 @@ export function createMemoryEngineTools(opts) {
                             `If the slug is misremembered: ${MEMORY_SEARCH_TOOL_NAME} matches keywords; ${MEMORY_INDEX_TOOL_NAME} lists exact slugs.` +
                             pollutionSentence(), "not_found", { slug: slug, ...(scope !== undefined ? { scope } : {}) });
                     }
+                    try {
+                        const names = await shadowNamesAcross(planes.map((plane) => plane.challengeExclusions?.()));
+                        const [shadowed] = await pruneUndeliverableCarriers([shadowedOf(matches.map((m) => m.header), names)]);
+                        const standing = matches.filter((m) => shadowed?.has(m.header.id) !== true);
+                        if (standing.length > 0 && standing.length < matches.length) {
+                            matches.length = 0;
+                            matches.push(...standing);
+                        }
+                    }
+                    catch {
+                    }
                     if (matches.length > 1) {
                         const candidates = matches.map((m) => ({ scope: m.header.scope, slug: m.header.slug, id: m.header.id }));
                         const listing = candidates.map((c) => `- scope ${JSON.stringify(inlineUntrusted(c.scope, 80))}, id ${c.id}`).join("\n");
@@ -400,7 +471,8 @@ export function createMemoryEngineTools(opts) {
                     }
                     entry = found;
                     entryPlane = matches[0].plane;
-                    mtimeMs = matches[0].header.mtimeMs;
+                    entryHeader = matches[0].header;
+                    mtimeMs = entryHeader.mtimeMs;
                 }
             }
             catch (err) {
@@ -436,6 +508,17 @@ export function createMemoryEngineTools(opts) {
                     supersededBy = undefined;
                 }
             }
+            let shadowedBy;
+            if (entryHeader !== undefined) {
+                try {
+                    const names = await shadowNamesAcross(planes.map((plane) => plane.challengeExclusions?.()));
+                    const [pruned] = await pruneUndeliverableCarriers([shadowedOf([entryHeader], names)]);
+                    shadowedBy = pruned?.get(entry.id);
+                }
+                catch {
+                    shadowedBy = undefined;
+                }
+            }
             try {
                 entryPlane?.recordRetrieved([entry.id]);
             }
@@ -450,6 +533,7 @@ export function createMemoryEngineTools(opts) {
                 `Memory entry ${entryPath(entry.scope, entry.slug)} (id ${entry.id}${mtimeMs !== undefined ? `, ${ageOf(now, mtimeMs)}` : ""})`,
                 ...(exposed ? [MEMORY_EXPOSURE_BANNER] : []),
                 ...(supersededBy !== undefined ? [memorySupersededNote(supersededBy)] : []),
+                ...(shadowedBy !== undefined ? [memoryShadowedNote(shadowedBy)] : []),
                 ...(fm.name !== undefined ? [`name: ${inlineUntrusted(fm.name, 120)}`] : []),
                 ...(fm.description !== undefined ? [`description: ${inlineUntrusted(fm.description, 200)}`] : []),
                 ...(fm.type !== undefined ? [`type: ${inlineUntrusted(fm.type, 40)}`] : []),
@@ -494,6 +578,7 @@ export function createMemoryEngineTools(opts) {
                     ...(nextLineCursor !== undefined ? { nextLineCursor } : {}),
                     ...(exposed ? { exposure: "external" } : {}),
                     ...(supersededBy !== undefined ? { supersededBy } : {}),
+                    ...(shadowedBy !== undefined ? { shadowedBy } : {}),
                 };
                 return { content: head.join("\n"), details };
             }
@@ -536,6 +621,7 @@ export function createMemoryEngineTools(opts) {
                 ...(nextLineCursor !== undefined ? { nextLineCursor } : {}),
                 ...(exposed ? { exposure: "external" } : {}),
                 ...(supersededBy !== undefined ? { supersededBy } : {}),
+                ...(shadowedBy !== undefined ? { shadowedBy } : {}),
             };
             return { content: head.join("\n"), details };
         },
@@ -558,9 +644,12 @@ export function createMemoryEngineTools(opts) {
             includeSuperseded: Type.Optional(Type.Boolean({
                 description: "Also list entries a newer consolidated entry has superseded (kept as evidence; hidden from the listing by default). Superseded rows are tagged, with the superseding entry's id.",
             })),
+            includeShadowed: Type.Optional(Type.Boolean({
+                description: "Also list entries a same-named entry in this session's write home shadows (kept as evidence; hidden from the listing by default). Shadowed rows are tagged, with the shadowing entry's id.",
+            })),
         }, { additionalProperties: false }),
         execute: async (args, ctx) => {
-            const { offset: rawOffset, limit: rawLimit, listingRev: givenListingRev, scope, includeSuperseded, } = args;
+            const { offset: rawOffset, limit: rawLimit, listingRev: givenListingRev, scope, includeSuperseded, includeShadowed, } = args;
             const signal = ctx.signal;
             const offset = Math.max(0, Math.floor(rawOffset ?? 0) || 0);
             const limit = Math.max(1, Math.min(MEMORY_INDEX_MAX_PAGE_ROWS, Math.floor(rawLimit ?? MEMORY_INDEX_PAGE_ROWS) || MEMORY_INDEX_PAGE_ROWS));
@@ -583,14 +672,20 @@ export function createMemoryEngineTools(opts) {
             }
             const rows = [];
             let supersededHidden = 0;
+            let shadowedHidden = 0;
             try {
+                const faces = [];
+                for (let i = 0; i < planes.length; i++)
+                    faces.push(await planeFaceOf(planes[i], exclusions[i]));
+                const names = await shadowNamesAcross(exclusions, faces);
+                const shadowedMaps = await pruneUndeliverableCarriers(faces.map((f) => shadowedOf(f.headers, names)));
                 for (let i = 0; i < planes.length; i++) {
                     const plane = planes[i];
                     if (plane.scopes.length === 0)
                         continue;
-                    const face = plane.backend.retrievalView?.() ?? plane.backend;
-                    const headers = await face.listHeaders(plane.scopes);
-                    const superseded = deriveSupersededSet(headers, { excluded: (id) => exclusions[i]?.has(id) === true });
+                    const headers = faces[i].headers;
+                    const superseded = faces[i].superseded;
+                    const shadowed = shadowedMaps[i];
                     const scopeSet = new Set(plane.scopes);
                     for (const h of headers) {
                         if (!scopeSet.has(h.scope))
@@ -604,7 +699,12 @@ export function createMemoryEngineTools(opts) {
                             supersededHidden++;
                             continue;
                         }
-                        rows.push({ planeIndex: i, header: h, ...(supersededBy !== undefined ? { supersededBy } : {}) });
+                        const shadowedBy = shadowed.get(h.id);
+                        if (shadowedBy !== undefined && includeShadowed !== true) {
+                            shadowedHidden++;
+                            continue;
+                        }
+                        rows.push({ planeIndex: i, header: h, ...(supersededBy !== undefined ? { supersededBy } : {}), ...(shadowedBy !== undefined ? { shadowedBy } : {}) });
                     }
                 }
             }
@@ -629,13 +729,16 @@ export function createMemoryEngineTools(opts) {
                 return a.header.id < b.header.id ? -1 : a.header.id > b.header.id ? 1 : 0;
             });
             const total = rows.length;
-            const supersededNote = supersededHidden > 0 && includeSuperseded !== true
+            const supersededNote = (supersededHidden > 0 && includeSuperseded !== true
                 ? ` ${supersededHidden} superseded entr${supersededHidden === 1 ? "y is" : "ies are"} hidden — pass includeSuperseded to list them.`
-                : "";
+                : "") +
+                (shadowedHidden > 0 && includeShadowed !== true
+                    ? ` ${shadowedHidden} shadowed entr${shadowedHidden === 1 ? "y is" : "ies are"} hidden — pass includeShadowed to list them.`
+                    : "");
             if (total === 0) {
                 const where = scope !== undefined ? ` in scope ${inlineUntrusted(scope, 80)}` : "";
-                const details = { outcome: "ok", entries: [], offset: 0, shown: 0, total: 0, ...(supersededHidden > 0 ? { supersededHidden } : {}) };
-                return { content: `No ${supersededHidden > 0 ? "active " : ""}memory entries are mounted${where} in this session.${supersededNote}` + pollutionSentence(), details };
+                const details = { outcome: "ok", entries: [], offset: 0, shown: 0, total: 0, ...(supersededHidden > 0 ? { supersededHidden } : {}), ...(shadowedHidden > 0 ? { shadowedHidden } : {}) };
+                return { content: `No ${supersededHidden > 0 || shadowedHidden > 0 ? "active " : ""}memory entries are mounted${where} in this session.${supersededNote}` + pollutionSentence(), details };
             }
             if (offset >= total) {
                 return refusedIndex("offset_past_end", `offset ${offset} is past the end — the listing has ${total} row${total === 1 ? "" : "s"}.`);
@@ -686,7 +789,7 @@ export function createMemoryEngineTools(opts) {
                 }
                 const h = r.header;
                 const exposed = carry && (h.exposure === "external" || (pageEntryById.has(h.id) && exposedEntry(pageEntryById.get(h.id))));
-                const supersededSuffix = r.supersededBy !== undefined ? ` ${MEMORY_SEARCH_SUPERSEDED_TAG}` : "";
+                const supersededSuffix = `${r.supersededBy !== undefined ? ` ${MEMORY_SEARCH_SUPERSEDED_TAG}` : ""}${r.shadowedBy !== undefined ? ` ${MEMORY_SEARCH_SHADOWED_TAG}` : ""}`;
                 const line = exposed
                     ? `${offset + consumed + 1}. [mem:${h.id}] ${MEMORY_EXPOSURE_HANDLE_TAG}${supersededSuffix} (scope ${inlineUntrusted(h.scope, 80)}, ${ageOf(now, h.mtimeMs)}) — read it with ${MEMORY_GET_TOOL_NAME} id ${h.id}`
                     : `${offset + consumed + 1}. ${entryPath(h.scope, h.slug)}${supersededSuffix}${h.description ? ` — ${inlineUntrusted(h.description, 200)}` : ""} (id ${h.id}, ${ageOf(now, h.mtimeMs)})`;
@@ -699,7 +802,7 @@ export function createMemoryEngineTools(opts) {
                 bytes += lineBytes;
                 consumed++;
                 if (exposed) {
-                    entries.push({ exposure: "external", id: h.id, scope: h.scope, mtimeMs: h.mtimeMs, sizeBytes: h.sizeBytes, ...(r.supersededBy !== undefined ? { supersededBy: r.supersededBy } : {}) });
+                    entries.push({ exposure: "external", id: h.id, scope: h.scope, mtimeMs: h.mtimeMs, sizeBytes: h.sizeBytes, ...(r.supersededBy !== undefined ? { supersededBy: r.supersededBy } : {}), ...(r.shadowedBy !== undefined ? { shadowedBy: r.shadowedBy } : {}) });
                 }
                 else {
                     entries.push({
@@ -711,6 +814,7 @@ export function createMemoryEngineTools(opts) {
                         mtimeMs: h.mtimeMs,
                         sizeBytes: h.sizeBytes,
                         ...(r.supersededBy !== undefined ? { supersededBy: r.supersededBy } : {}),
+                        ...(r.shadowedBy !== undefined ? { shadowedBy: r.shadowedBy } : {}),
                     });
                 }
             }
@@ -728,6 +832,7 @@ export function createMemoryEngineTools(opts) {
                 total,
                 listingRev,
                 ...(supersededHidden > 0 && includeSuperseded !== true ? { supersededHidden } : {}),
+                ...(shadowedHidden > 0 && includeShadowed !== true ? { shadowedHidden } : {}),
                 ...(end < total || capTripped ? { nextOffset: end } : {}),
             };
             return { content: [head, ...lines, ...(footer !== undefined ? [footer] : [])].join("\n"), details };

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

@@ -438,6 +438,16 @@ export interface MemorySessionHandle {
      *  clean-entry mis-labeling). Absent on handles minted by engines predating the field ⇒ consumers
      *  treat as "unknown", which the discipline seat maps to the historic over-teaching side. */
     markedEntriesPresent?: boolean;
+    /** The names the SESSION's write home carries (name → the carrying entry's id), supplied by the
+     *  caller when the write home lives on a DIFFERENT plane than this one (the dual-root read-only
+     *  plane). Absent on a plane holding the write scope itself (the rule reads this plane's own
+     *  headers) and in a session with no write home, where the shadow set is empty. */
+    shadowNames?: ReadonlyMap<string, string>;
+    /** How many entries of each scope this plane's index rebuild retired from the default read face
+     *  by write-home name — the mount-time snapshot the runner reports per scope. Only non-zero
+     *  scopes have a key; the tool faces derive their own LIVE answer per call, so a stale snapshot
+     *  can mis-report a number, never mis-serve an entry. */
+    shadowedByScope?: ReadonlyMap<string, number>;
     /** Lines of the derived MEMORY.md at materialize time (the index-cleared fuse baseline). */
     indexBaselineLines: number;
     /** 评审 M6 — the derived index TEXT as of materialize. `inject` reads THIS when no on-disk

package/dist/core/memory.d.ts

@@ -1,3 +1,4 @@
+import type { EngineNotice } from "./engine-notice.js";
 /**
  * A scored memory candidate returned by {@link MemoryStore.searchScored} (design/41). Carries a
  * **stable id** (for {@link MemoryStore.update}/{@link MemoryStore.delete}) and a similarity `score`.
@@ -525,7 +526,33 @@ export interface NormalizedMemorySpec {
     scopeOrigins?: Readonly<Record<string, "deployment" | "request">>;
     /** See {@link MemorySpecInput.capture} (design/383 §2.1 — the session capture opt-out). */
     capture?: "off";
+    /** See {@link MemorySpecInput.projectKey} — carried verbatim; a normalized spec never invents it. */
+    projectKey?: MemoryProjectKey;
 }
+/**
+ * The closed vocabulary a deployment states a MISSING project key with: the working root is not a
+ * repository, it is a bare repository, or it could not be read. Purely descriptive — the engine
+ * branches on presence (`absent` vs `scope`), never on which word; the word rides the operator
+ * notice so a deployment can tell "no project here" from "I could not look".
+ */
+export declare const MEMORY_PROJECT_KEY_ABSENT_REASONS: readonly ["not_git", "bare", "unreadable"];
+export type MemoryProjectKeyAbsentReason = (typeof MEMORY_PROJECT_KEY_ABSENT_REASONS)[number];
+/**
+ * The assembly point's STATEMENT about this task's project identity — the key it derived for the
+ * working root, or the reason there is none. Exactly one arm is spelled.
+ *
+ * It is a DECLARATION, not a second way to configure memory: the layering is still `scopes` and
+ * `writeScope`, and this key only lets the engine refuse the one misconfiguration those two cannot
+ * express — an assembler that derived a project key and then left `writeScope` to its default, so
+ * every entry the session writes lands in the shared layer instead of the project's.
+ */
+export type MemoryProjectKey = {
+    scope: string;
+    absent?: never;
+} | {
+    absent: MemoryProjectKeyAbsentReason;
+    scope?: never;
+};
 /** The memory spec accepted on `TaskSpec.memory`. RB-479-B② (ruled 2026-08-02): ONE form —
  *  the legacy singular `scope` field is REMOVED; `scopes` (ordered read layers) is the only spelling.
  *  An input still carrying an own `scope` property is REFUSED by {@link normalizeMemorySpec}
@@ -573,6 +600,24 @@ export type MemorySpecInput = {
      * prepare, strictly BEFORE any record lands (a denied declaration leaves zero record residue).
      */
     capture?: "off";
+    /**
+     * The assembly point's statement about this task's PROJECT IDENTITY ({@link MemoryProjectKey}).
+     * Two things happen to it and nothing else: a `{ scope }` arm must EQUAL `writeScope` (a
+     * read-only layering excepted), or the task refuses to start with
+     * `config.memory_write_scope_mismatch`; an `{ absent }` arm mints one operator notice
+     * (`memory.project_scope_absent`) naming the reason, and the layering is used as written.
+     *
+     * Why this rather than "derive writeScope from it": the layering is the deployment's to compose,
+     * and a key that quietly re-pointed the write face would be a second configuration channel. What
+     * it closes is the SILENT direction — an omitted `writeScope` defaults to the LAST scope, so an
+     * assembler that derived a project key and forgot to pin the write face writes every entry of
+     * every project into the shared layer, and nothing says so. Absent ⇒ the spec reads as before.
+     *
+     * Any other shape — both arms, neither, an empty `scope`, a reason outside
+     * {@link MEMORY_PROJECT_KEY_ABSENT_REASONS} — is REFUSED loudly
+     * (`config.memory_project_key_spelling`), never folded to "no key stated".
+     */
+    projectKey?: MemoryProjectKey;
 };
 /**
  * Normalize {@link import("./types.js").TaskSpec.memory} into ONE canonical
@@ -592,6 +637,21 @@ export type MemorySpecInput = {
  *
  */
 export declare function normalizeMemorySpec(input: MemorySpecInput | undefined): NormalizedMemorySpec | undefined;
+/**
+ * The operator disclosure for a declared-absent project key (`memory.project_scope_absent`,
+ * audience `operator`): the deployment stated it could derive no project identity for this working
+ * root, so the layering it sent is used exactly as written — typically writing into a layer shared
+ * with every other project. The notice states the deployment's own reason word and the root it was
+ * about; whether that reading is correct is a question about how the deployment resolves working
+ * roots, which is why nobody is judged here. One per prepared leg, at the declaration — not at the
+ * mount, because the declaration is already the fact.
+ */
+export declare function memoryProjectScopeAbsentNotice(input: {
+    reason: MemoryProjectKeyAbsentReason;
+    taskRoot: string;
+    sessionId: string;
+    writeScope: string | null;
+}): EngineNotice;
 /** Max bytes of memory injected into the prompt; larger is truncated with a marker. (CodeWhale: 100 KiB)
  *  Exported so the inject-all de-dup seeding (prepare-task.ts) can detect truncation and NOT seed dropped
  *  (truncated-out) note ids as "already surfaced" — see the MINOR-1 audit fix there. */

package/dist/core/memory.js

@@ -363,6 +363,7 @@ export function parseNoteTimestamp(ts) {
     const ms = Date.parse(`${ts.replace(" ", "T")}:00Z`);
     return Number.isFinite(ms) ? { mtimeMs: ms } : { mtimeMs: 0, timestampMissing: true };
 }
+export const MEMORY_PROJECT_KEY_ABSENT_REASONS = ["not_git", "bare", "unreadable"];
 export function normalizeMemorySpec(input) {
     if (!input)
         return undefined;
@@ -385,6 +386,7 @@ export function normalizeMemorySpec(input) {
         e.code = "config.memory_capture_spelling";
         throw e;
     }
+    const projectKey = readProjectKey(input);
     const raw = input.scopes ?? [];
     const scopes = [];
     const seen = new Set();
@@ -421,13 +423,56 @@ export function normalizeMemorySpec(input) {
         ...(input.execIsExternalContent === true ? { execIsExternalContent: true } : {}),
     };
     const origins = input.scopeOrigins !== undefined ? { scopeOrigins: input.scopeOrigins } : {};
+    if (projectKey?.scope !== undefined && writeScope !== null && writeScope !== projectKey.scope) {
+        const e = new Error(`TaskSpec.memory.projectKey declares project scope ${JSON.stringify(projectKey.scope)} while writeScope is ${JSON.stringify(writeScope)} — ` +
+            `every entry this session writes would land in ${JSON.stringify(writeScope)} instead of the project's own layer. ` +
+            `Pin writeScope to the project scope (or drop projectKey if the layering is deliberate). Refusing to start mis-addressed.`);
+        e.code = "config.memory_write_scope_mismatch";
+        throw e;
+    }
     const capture = input.capture === "off" ? { capture: "off" } : {};
+    const project = projectKey !== undefined ? { projectKey } : {};
     if (input.scopeContract === "v2") {
         for (const key of writeScope !== null ? [...scopes, writeScope] : scopes)
             parseScopeKey(key);
-        return { scopes, writeScope, enabled: input.enabled !== false, scopeContract: "v2", ...contentSafety, ...origins, ...capture };
+        return { scopes, writeScope, enabled: input.enabled !== false, scopeContract: "v2", ...contentSafety, ...origins, ...capture, ...project };
+    }
+    return { scopes, writeScope, enabled: input.enabled !== false, ...contentSafety, ...origins, ...capture, ...project };
+}
+function readProjectKey(input) {
+    const raw = input.projectKey;
+    if (raw === undefined)
+        return undefined;
+    const refuse = (why) => {
+        const e = new Error(`TaskSpec.memory.projectKey must be exactly { scope: "<non-empty>" } or { absent: ${MEMORY_PROJECT_KEY_ABSENT_REASONS.map((r) => JSON.stringify(r)).join(" | ")} } — ${why}. ` +
+            `Refusing to guess whether this deployment has a project identity.`);
+        e.code = "config.memory_project_key_spelling";
+        throw e;
+    };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return refuse(`got ${raw === null ? "null" : Array.isArray(raw) ? "an array" : typeof raw}`);
+    const scope = raw.scope;
+    const absent = raw.absent;
+    if ((scope === undefined) === (absent === undefined))
+        return refuse(absent === undefined ? "neither arm was spelled" : "both arms were spelled");
+    if (absent !== undefined) {
+        if (typeof absent !== "string" || !MEMORY_PROJECT_KEY_ABSENT_REASONS.includes(absent)) {
+            return refuse(`the absence reason ${typeof absent === "string" ? JSON.stringify(absent.slice(0, 64)) : typeof absent} is not one of the stated words`);
+        }
+        return { absent: absent };
     }
-    return { scopes, writeScope, enabled: input.enabled !== false, ...contentSafety, ...origins, ...capture };
+    if (typeof scope !== "string" || scope.trim() === "")
+        return refuse(typeof scope === "string" ? "the project scope is blank" : `the project scope is ${typeof scope}`);
+    return { scope: scope.trim() };
+}
+export function memoryProjectScopeAbsentNotice(input) {
+    return {
+        code: "memory.project_scope_absent",
+        message: `No project identity was derived for this session's working root (${input.reason}), so its memory layering is used as declared: ` +
+            `${input.writeScope === null ? "the session writes nothing (read-only layering)" : `entries this session writes go to the shared layer ${JSON.stringify(input.writeScope)}`}. ` +
+            `If this root should have its own project memory, fix how the deployment resolves it — nothing here retries.`,
+        detail: { reason: input.reason, taskRoot: input.taskRoot, sessionId: input.sessionId, ...(input.writeScope !== null ? { writeScope: input.writeScope } : {}) },
+    };
 }
 export const MAX_MEMORY_BYTES = 100 * 1024;
 export const MEMORY_WRAPPER_TAGS = ["user_memory"];

package/dist/core/permission-rule-store.d.ts

@@ -221,6 +221,19 @@ export interface RuleSyncJoinDelta {
  * calling layer, and closes identically for every caller.
  */
 export type RuleWriteDelta = RuleAddDelta | RuleTightenAddDelta | RuleDeleteDelta | RuleSyncJoinDelta;
+/**
+ * The refusal every backend owes a delta whose `kind` is outside {@link RuleWriteDelta} — minted here so
+ * the two bundled backends (and an out-of-repo twin) answer an unnamed operation with ONE sentence
+ * instead of each guessing.
+ *
+ * The parameter is `never` on purpose: the only way to reach it is from a `default` arm the type system
+ * has already proved unreachable, so the factory doubles as the compile-time fence (a fifth arm added to
+ * the union stops satisfying `never` and reds at every backend's switch, naming the missing word). The
+ * runtime half is not decoration — a delta arrives as DATA (a foreign caller, a replayed record, a
+ * deserialized join), and the alternative to throwing is folding an unnamed kind as whichever arm
+ * an if/else chain happens to end with: a write nobody defined, landed under a name nobody checked.
+ */
+export declare function unknownRuleWriteDeltaError(delta: never): Error;
 /**
  * The backend write face. Exported as part of the BACKEND CONTRACT (ruled 2026-08-10) so an
  * out-of-repo store implementation hangs the same face the file backend does, instead of mirroring the
@@ -531,6 +544,22 @@ export declare function ruleStoreChecksum(payload: unknown): Promise<string>;
  */
 export declare const REMOVAL_LIVENESS_WORDS: readonly ["yes", "no", "unknown"];
 export type RemovalLiveness = (typeof REMOVAL_LIVENESS_WORDS)[number];
+/**
+ * What a terminal write FAILURE may claim about the bytes — the failure half of the honesty
+ * {@link RemovalLiveness} keeps on the success half, spelled ONCE and read by every write entry here.
+ *
+ * `"no"` = the store ITSELF answered: a face that cannot write at all, a target the type face refuses,
+ * a read that failed before any write, a refused preflight, an epoch seal, a compare-and-set that lost
+ * every attempt. Each of those is the store saying nothing landed, so saying it is a fact.
+ * `"unknown"` = the apply THREW, which proves nothing either way (a backend can commit and then lose
+ * its acknowledgement), or the read-back that would have settled it could not be taken.
+ *
+ * The word exists because the caller's two branches — retry, or reconcile with `list()` — are not
+ * derivable from the failure PROSE. A consumer reading the strength out of the sentence is parsing a
+ * message written for a person, and every such reader has to be updated by hand when the sentence is.
+ */
+export declare const RULE_WRITE_COMMITTED_WORDS: readonly ["no", "unknown"];
+export type RuleWriteCommitted = (typeof RULE_WRITE_COMMITTED_WORDS)[number];
 /**
  * The result of a removal.
  *
@@ -548,21 +577,32 @@ export type RemoveResult =
     rev: number;
     stillLive: RemovalLiveness;
 }
-/** Nothing to remove — including a repeated delete. No empty tombstone is minted. */
+/** Nothing to remove — including a repeated delete. No empty tombstone is minted. `stillLive` is the
+ *  SAME read-back the `removed` arm reports, taken at the same point in the call ({@link
+ *  readRuleLiveness}): "there was nothing to remove" is a statement about the snapshot this call read,
+ *  and an approval landing after it leaves the rule standing. Both 200-shaped arms therefore carry the
+ *  word, from one source. It is a LATER OBSERVATION, not an atomic absence: `rev` is the revision the
+ *  decision was taken at, the word is what a second look saw, and the store may change again right
+ *  after — `yes` beside a `no-op` is the honest pair, not a contradiction. */
  | {
     status: "no-op";
     rev: number;
+    stillLive: RemovalLiveness;
 }
-/** Terminal failure, in one of two strengths the `error` text distinguishes — word for word the dual of
- *  {@link AddResult}'s. When the STORE answered every attempt (the compare-and-set simply lost), the
- *  read-back confirms nothing was written and the text says so plainly. When the apply THREW, a missing
+/** Terminal failure, in one of two strengths — word for word the dual of {@link AddResult}'s, and
+ *  `committed` is the word for it ({@link RuleWriteCommitted}), so the strength is READ, not parsed out
+ *  of the sentence. When the STORE answered every attempt (the compare-and-set simply lost), nothing
+ *  landed: `committed: "no"`, and the read-back confirms it in the text. When the apply THREW, a missing
  *  tombstone cannot tell a write that never landed from one whose evidence a paired collection erased
  *  (`collectBelowFrontier` recycles a tombstone together with the adds it covered), so that outcome is
- *  reported INDETERMINATE and the caller reconciles with `list()` rather than retrying blind. When the
- *  read-back itself failed, `error` says so and the caller reconciles with `list()` too. */
+ *  `committed: "unknown"`, reported INDETERMINATE, and the caller reconciles with `list()` rather than
+ *  retrying blind. When the read-back itself failed, the word is the one the apply earned — a throw
+ *  leaves it `unknown`, an answered compare-and-set stays `no`, because an unreadable store cannot
+ *  un-answer what the store already said. */
  | {
     status: "failed";
     error: string;
+    committed: RuleWriteCommitted;
 };
 /**
  * Remove a persisted rule.
@@ -602,7 +642,7 @@ export type RuleAddLanding = {
  | {
     landed: false;
     reason: string;
-    committed: "no" | "unknown";
+    committed: RuleWriteCommitted;
 };
 /**
  * Land ONE add — the terminal write both doors take (the consent protocol's redemption and the
@@ -652,10 +692,13 @@ export type AddResult =
  *  survives the tombstone a concurrent removal laid on it — but a sync collection can erase even
  *  that, so a dot it cannot find is reported INDETERMINATE rather than as a confirmed nothing, and
  *  the caller reconciles with `list()` instead of retrying blind (a blind retry mints a fresh dot and
- *  can reinstate a restriction somebody had just removed). */
+ *  can reinstate a restriction somebody had just removed). `committed` ({@link RuleWriteCommitted}) is
+ *  which of the two this is, as a WORD — the landing's own answer, passed through rather than re-derived,
+ *  so this entry and the consent protocol's door cannot disagree about a write they both took. */
  | {
     status: "failed";
     error: string;
+    committed: RuleWriteCommitted;
 };
 /**
  * Add a persisted rule in ONE step, with no approval record.