@sema-agent/core 5.49.0 → 5.50.0

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

@@ -14,7 +14,7 @@ import { noReplaceRestore } from "./delegation-settlement.js";
 import { markOriginClearanceTombstoned, openOriginClearance, readOriginClearances, settleOriginClearance } from "./origin-clearance.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, canonicalJsonStringify, captureErasureInput, erasureRequestInvalid, erasureSelectHash, scanEntryFiles, } from "./file-backend.js";
 import { assembleMemoryExportBundle, computeMemoryBundleHash, memoryBundleInvalid, } from "./export-bundle.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 export const MEMORY_INSTRUCTION_TEMPLATE = `# Memory
 
@@ -876,6 +876,8 @@ export class MemoryEngine {
                             this.discloseSessionAccountIncident("the committed snapshot was contended/incomplete — the id-bearing residue arm is degraded to id-less for this materialize", undefined);
                         }
                     }
+                    const debtByRel = new Map(readProjectionDebts(this.controlDir).map((r) => [r.relPath, r.entryId]));
+                    const canonicalMemoryDir = canonicalize(this.memoryDir);
                     for (const f of scanEntryFiles(wroot, { maxDepth: this.maxDepth })) {
                         const canonical = canonicalize(f.path);
                         if (canonical !== wroot && !canonical.startsWith(`${wroot}${sep}`))
@@ -883,11 +885,20 @@ export class MemoryEngine {
                         const text = readSafe(canonical);
                         if (text === undefined)
                             continue;
-                        const rel = relative(this.memoryDir, canonical);
+                        const rel = relative(canonicalMemoryDir, canonical);
                         if (rel === MEMORY_INDEX_FILENAME || rel.endsWith(`${sep}${MEMORY_INDEX_FILENAME}`))
                             continue;
                         const parsed = parseEntryFile(text);
-                        const uncommitted = parsed.id === undefined || (committedRevs !== undefined && !committedRevs.has(parsed.id));
+                        const debtEntryId = parsed.id === undefined ? debtByRel.get(relative(canonicalMemoryDir, canonical)) : undefined;
+                        let debtAttributed = false;
+                        if (debtEntryId !== undefined) {
+                            const proj = await this.debtCommittedProjection(debtEntryId);
+                            if (proj.state === "unknown") {
+                                throw new Error(`the committed state for debt-bound file ${rel} could not be read during crash-residue attribution — refusing to classify on a fault`);
+                            }
+                            debtAttributed = proj.state === "valid" && proj.scope === writeScope && proj.slug === f.slug;
+                        }
+                        const uncommitted = (parsed.id === undefined && !debtAttributed) || (parsed.id !== undefined && committedRevs !== undefined && !committedRevs.has(parsed.id));
                         if (uncommitted) {
                             unattributed.push(rel);
                             continue;
@@ -1029,6 +1040,20 @@ export class MemoryEngine {
                 handle.baseIds.set(path, entry.id);
             }
         }
+        {
+            const debts = readProjectionDebts(this.controlDir);
+            if (debts.length > 0) {
+                const projectedIdByRel = new Map(handle.materialized.filter((m) => !m.stub).map((m) => [m.relPath, m.id]));
+                const healed = debts.filter((r) => projectedIdByRel.get(r.relPath) === r.entryId).map((r) => ({ relPath: r.relPath, entryId: r.entryId }));
+                if (healed.length > 0) {
+                    try {
+                        settleProjectionDebts(this.controlDir, healed);
+                    }
+                    catch {
+                    }
+                }
+            }
+        }
         const indexGate = this.gateDerivedIndex(handle);
         if (indexGate !== undefined) {
             if (!indexGate.contained)
@@ -1508,6 +1533,17 @@ export class MemoryEngine {
         for (const [p, id] of idByBasePath)
             if (!handle.fileToScope.get(p) || handle.fileToScope.get(p) === handle.writeScope)
                 basePathById.set(id, p);
+        let projectionDebts;
+        try {
+            projectionDebts = new Map(readProjectionDebts(this.controlDir).map((r) => [r.relPath, { entryId: r.entryId, rev: r.rev }]));
+        }
+        catch (err) {
+            report.ok = false;
+            report.incident = { kind: "sidecar_corrupt", detail: `memory projection-debt ledger unreadable: ${err instanceof Error ? err.message : String(err)}` };
+            return report;
+        }
+        const debtClears = [];
+        const staleReplacedDebts = new Map();
         const patches = [];
         const pendingProjections = [];
         const idsAddedThisHarvest = new Set();
@@ -1528,8 +1564,12 @@ export class MemoryEngine {
                 continue;
             }
             const fastBaseId = idByBasePath.get(f.canonical);
-            if (fastBaseId !== undefined && !stubByPath.has(f.canonical) && revOfText(f.text, fastBaseId) === revByBasePath.get(f.canonical))
+            if (fastBaseId !== undefined && !stubByPath.has(f.canonical) && revOfText(f.text, fastBaseId) === revByBasePath.get(f.canonical)) {
+                const fastDebt = projectionDebts.get(rel);
+                if (fastDebt !== undefined && fastDebt.entryId === fastBaseId)
+                    await this.repairProjectionSeat(rel, f.canonical, fastBaseId, debtClears);
                 continue;
+            }
             processed++;
             if (pollutedReason !== undefined && !carry) {
                 await containPollutedRecord(f);
@@ -1585,8 +1625,35 @@ export class MemoryEngine {
                 continue;
             }
             const parsed = f.parsed;
-            const baseId = idByBasePath.get(f.canonical);
+            let baseId = idByBasePath.get(f.canonical);
             let id = baseId ?? parsed.id;
+            let debtReconciled = false;
+            if (id === undefined && projectionDebts.size > 0) {
+                const debt = projectionDebts.get(rel);
+                if (debt !== undefined) {
+                    const committed = await this.debtCommittedProjection(debt.entryId);
+                    if (committed.state === "unknown") {
+                        report.rejections.push({
+                            path: rel,
+                            code: "deferred",
+                            reason: "memory write deferred: this file's recorded committed id could not be validated (committed state unreadable) — retried next harvest (fail-closed: a fresh mint here could duplicate the committed entry)",
+                        });
+                        continue;
+                    }
+                    if (committed.state === "valid" && committed.scope === writeScope && committed.slug === f.slug) {
+                        baseId = debt.entryId;
+                        id = debt.entryId;
+                        idByBasePath.set(f.canonical, debt.entryId);
+                        revByBasePath.set(f.canonical, debt.rev);
+                        debtReconciled = true;
+                        report.warnings.push(`${rel}: reconciled to its committed entry — a prior harvest committed this file but the id write-back did not land; the projection is repaired through the ordinary update lane, never re-admitted as a duplicate`);
+                    }
+                    else {
+                        debtClears.push({ relPath: rel, entryId: debt.entryId });
+                        staleReplacedDebts.set(rel, debt.entryId);
+                    }
+                }
+            }
             const minted = id === undefined;
             if (id === undefined)
                 id = uuidv7();
@@ -1680,9 +1747,13 @@ export class MemoryEngine {
                 continue;
             }
             if (baseId !== undefined) {
-                if (revOfText(f.text, id) === revByBasePath.get(f.canonical))
+                if (revOfText(f.text, id) === revByBasePath.get(f.canonical)) {
+                    const seatDebt = projectionDebts.get(rel);
+                    if (seatDebt !== undefined && seatDebt.entryId === id)
+                        await this.repairProjectionSeat(rel, f.canonical, id, debtClears);
                     continue;
-                pendingProjections.push({ path: f.canonical, entry, needed: minted || parsed.id !== id || needsCompletion(parsed, fm) });
+                }
+                pendingProjections.push({ path: f.canonical, entry, needed: minted || parsed.id !== id || needsCompletion(parsed, fm), ...(debtReconciled ? { idCompletion: true } : {}) });
                 patches.push({ op: "update", id, entry, ...(revByBasePath.get(f.canonical) !== undefined ? { baseRev: revByBasePath.get(f.canonical) } : {}) });
                 continue;
             }
@@ -1732,7 +1803,7 @@ export class MemoryEngine {
                 entry.rev = computeEntryRev(entry);
                 report.warnings.push(`${rel}: the file's model-written id was not adopted for this external-origin commit — committed under an engine-minted id (a marked entry's index/search handles carry no model-authored bytes)`);
             }
-            pendingProjections.push({ path: f.canonical, entry, needed: minted || reboundId !== undefined || remintedId !== undefined || needsCompletion(parsed, fm) });
+            pendingProjections.push({ path: f.canonical, entry, needed: minted || reboundId !== undefined || remintedId !== undefined || needsCompletion(parsed, fm), ...(minted || reboundId !== undefined || remintedId !== undefined ? { idCompletion: true } : {}) });
             idsAddedThisHarvest.add(entry.id);
             if (parsed.id !== undefined && entry.id === parsed.id)
                 modelIdAdds.add(entry.id);
@@ -1835,6 +1906,7 @@ export class MemoryEngine {
                                 p.entry.id = uuidv7();
                                 p.entry.rev = computeEntryRev(p.entry);
                                 p.id = p.entry.id;
+                                projection.idCompletion = true;
                                 report.warnings.push(`${flipRec.rel}: the file's model-written id was not adopted for this external-origin commit — committed under an engine-minted id (a marked entry's index/search handles carry no model-authored bytes)`);
                             }
                         }
@@ -1869,6 +1941,68 @@ export class MemoryEngine {
                         }
                     }
                 }
+                const debtStage = pendingProjections
+                    .filter((p) => p.idCompletion === true)
+                    .map((p) => {
+                    const relPath = relative(handle.memoryDir, p.path);
+                    const replaces = staleReplacedDebts.get(relPath);
+                    return { relPath, entryId: p.entry.id, rev: p.entry.rev, ...(replaces !== undefined ? { replaces } : {}) };
+                });
+                if (debtStage.length > 0) {
+                    let refusedStage = [];
+                    try {
+                        refusedStage = stageProjectionDebts(this.controlDir, debtStage, this.now).refused;
+                    }
+                    catch (err) {
+                        report.warnings.push(`memory projection-debt staging failed — duplicate-admission protection for this harvest's id write-backs is degraded (a failed write-back could re-admit its file as a duplicate until the next materialize repairs the plane): ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    if (refusedStage.length > 0) {
+                        const refusedIds = new Set(refusedStage.map((r) => r.entryId));
+                        for (let i = patches.length - 1; i >= 0; i--) {
+                            const p = patches[i];
+                            if (p.op !== "delete" && refusedIds.has(p.id))
+                                patches.splice(i, 1);
+                        }
+                        for (let i = pendingProjections.length - 1; i >= 0; i--) {
+                            const proj = pendingProjections[i];
+                            if (refusedIds.has(proj.entry.id)) {
+                                idByBasePath.delete(proj.path);
+                                revByBasePath.delete(proj.path);
+                                pendingProjections.splice(i, 1);
+                            }
+                        }
+                        for (const r of refusedStage) {
+                            report.rejections.push({
+                                path: r.relPath,
+                                code: "deferred",
+                                reason: "memory write deferred: a concurrent writer's projection-debt claim stands at this seat — retried next harvest (committing without a protected id write-back could duplicate the concurrent entry)",
+                            });
+                            report.warnings.push(`${r.relPath}: earlier notes about this file committing under a fresh id are superseded — its commit was WITHDRAWN this harvest (deferred to the next)`);
+                        }
+                        if (lineageArmed) {
+                            const remaining = patches.filter((p) => p.op !== "delete" && p.entry !== undefined).map((p) => ({ entryId: p.id, rev: p.entry.rev, ...(p.entry.frontmatter.origin !== undefined ? { marked: true } : {}) }));
+                            if (remaining.length > 0) {
+                                try {
+                                    stageLineagePending(this.controlDir, txnId, lineageSessionId, remaining, this.now);
+                                }
+                                catch (err) {
+                                    report.ok = false;
+                                    report.incident = { kind: "sidecar_corrupt", detail: `memory lineage restage refused after a withheld projection-debt seat: ${err instanceof Error ? err.message : String(err)}` };
+                                    return report;
+                                }
+                            }
+                            else {
+                                try {
+                                    discardLineagePending(this.controlDir, txnId);
+                                }
+                                catch (err) {
+                                    report.warnings.push(`memory lineage stage for withheld entries could not be discarded — their ids stay latched until the host adjudicates pending transaction ${txnId}: ${err instanceof Error ? err.message : String(err)}`);
+                                }
+                                lineageArmed = false;
+                            }
+                        }
+                    }
+                }
                 try {
                     patchReport = await this.backend.applyPatches(patches);
                 }
@@ -1938,18 +2072,44 @@ export class MemoryEngine {
         }
         const appliedIds = new Set(patchReport.applied.filter((a) => a.op !== "delete").map((a) => a.id));
         for (const p of pendingProjections) {
+            const pRel = relative(handle.memoryDir, p.path);
             if (appliedIds.has(p.entry.id)) {
-                this.writeBackProjection(p.path, p.entry, p.needed);
+                const wrote = this.writeBackProjection(p.path, p.entry, p.needed);
+                if (p.idCompletion === true) {
+                    if (wrote)
+                        debtClears.push({ relPath: pRel, entryId: p.entry.id });
+                    else {
+                        const landed = patchReport.applied.find((a) => a.id === p.entry.id)?.slug;
+                        const suffixNote = landed !== undefined && landed !== p.entry.slug ? ` NOTE: the entry landed at slug ${JSON.stringify(landed)} (collision suffix) — the seat claim will not re-bind; host reconciliation may be needed.` : "";
+                        report.warnings.push(`${pRel}: the entry committed but its id write-back FAILED — the projection-debt row stands, so the file re-binds to its committed id at the next harvest (and the next materialize repairs the plane); it is never re-admitted as a duplicate.${suffixNote}`);
+                    }
+                }
                 continue;
             }
-            const committed = await this.committedContentFor(p.entry.id);
+            const committedRead = await this.committedContentOrFault(p.entry.id);
+            const committed = committedRead.content;
+            let planeHoldsCommitted = false;
             if (committed !== undefined && readNoFollowSafe(p.path) !== committed) {
                 try {
                     writeFileNoFollow(p.path, committed);
+                    planeHoldsCommitted = true;
                 }
                 catch {
                 }
             }
+            else if (committed !== undefined) {
+                planeHoldsCommitted = true;
+            }
+            if (p.idCompletion === true && ((committed === undefined && !committedRead.fault) || planeHoldsCommitted))
+                debtClears.push({ relPath: pRel, entryId: p.entry.id });
+        }
+        if (debtClears.length > 0) {
+            try {
+                settleProjectionDebts(this.controlDir, debtClears);
+            }
+            catch (err) {
+                report.warnings.push(`memory projection-debt settlement failed — settled rows stay on the ledger (harmless: every consumption re-validates a row against the committed state before binding): ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
         try {
             clearScanFuse(this.controlDir, pendingProjections.filter((p) => appliedIds.has(p.entry.id)).map((p) => p.path));
@@ -2074,7 +2234,7 @@ export class MemoryEngine {
             if (committedOrigin !== undefined)
                 fm.origin = committedOrigin;
             else if (opts.valve)
-                fm.origin = { taint: "external", cause: "static", at: this.now() };
+                fm.origin = { taint: "external", cause: "static", at: row.capturedAt };
         }
         if (fm.name === undefined)
             fm.name = row.slug.split("/").pop();
@@ -2140,7 +2300,9 @@ export class MemoryEngine {
             report.warnings.push(`released hold ${row.relPath}: lineage settlement failed after commit — the entry stays latched until a later harvest reconciles: ${err instanceof Error ? err.message : String(err)}`);
         }
         markHoldReleased(this.controlDir, { holdId: row.holdId, now: this.now });
-        const abs = join(this.memoryDir, row.relPath);
+        const landedSlug = patchReport.applied.find((a) => a.id === patch.id)?.slug ?? row.slug;
+        const landedRelPath = landedSlug === row.slug ? row.relPath : join(dirname(row.relPath), `${landedSlug.split("/").pop()}.md`);
+        const abs = join(this.memoryDir, landedRelPath);
         if (existsSync(abs)) {
             const canonical = canonicalize(abs);
             const text = readSafe(canonical);
@@ -2149,7 +2311,7 @@ export class MemoryEngine {
                 handle.baseRevs.set(canonical, computeEntryRev({ id: patch.id, frontmatter: parseEntryFile(text).frontmatter, body: parseEntryFile(text).body }));
                 handle.fileToScope.set(canonical, row.scope);
                 if (!handle.materialized.some((m) => m.path === canonical)) {
-                    handle.materialized.push({ path: canonical, relPath: row.relPath, scope: row.scope, id: patch.id, slug: row.slug, rev: handle.baseRevs.get(canonical), stub: false, readonly: false });
+                    handle.materialized.push({ path: canonical, relPath: landedRelPath, scope: row.scope, id: patch.id, slug: landedSlug, rev: handle.baseRevs.get(canonical), stub: false, readonly: false });
                 }
             }
         }
@@ -2576,20 +2738,28 @@ export class MemoryEngine {
         return text;
     }
     async committedContentFor(id) {
+        return (await this.committedContentOrFault(id)).content;
+    }
+    async committedContentOrFault(id) {
+        let fault = false;
         const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
         if (!zeroCopy) {
             try {
                 const [entry] = await this.backend.getByIds([id]);
                 if (entry !== undefined && entry.id === id)
-                    return serializeEntryFile(entry);
+                    return { content: serializeEntryFile(entry), fault: false };
             }
             catch {
+                fault = true;
             }
         }
         const viaBackend = this.backend.readCommittedShadow?.(id);
         if (viaBackend !== undefined)
-            return viaBackend;
-        return readSafe(join(this.controlDir, "shadow", `${id}.md`));
+            return { content: viaBackend, fault: false };
+        const viaShadow = readSafe(join(this.controlDir, "shadow", `${id}.md`));
+        if (viaShadow !== undefined)
+            return { content: viaShadow, fault: false };
+        return { fault };
     }
     async committedFrontmatterFor(id) {
         const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
@@ -2682,14 +2852,45 @@ export class MemoryEngine {
     }
     writeBackProjection(path, entry, needed) {
         if (!needed)
-            return;
+            return true;
         const text = serializeEntryFile(entry);
         if (readNoFollowSafe(path) === text)
-            return;
+            return true;
         try {
             writeFileNoFollow(path, text);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async repairProjectionSeat(rel, canonical, entryId, debtClears) {
+        const committed = await this.committedContentFor(entryId);
+        if (committed === undefined)
+            return;
+        if (readNoFollowSafe(canonical) !== committed) {
+            try {
+                writeFileNoFollow(canonical, committed);
+            }
+            catch {
+                return;
+            }
+        }
+        debtClears.push({ relPath: rel, entryId });
+    }
+    async debtCommittedProjection(entryId) {
+        const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
+        if (zeroCopy)
+            return { state: "stale" };
+        const face = this.backend.retrievalView?.() ?? this.backend;
+        try {
+            const [entry] = await face.getByIds([entryId]);
+            if (entry !== undefined && entry.id === entryId)
+                return { state: "valid", scope: entry.scope, slug: entry.slug };
+            return { state: "stale" };
         }
         catch {
+            return { state: "unknown" };
         }
     }
     siblingScopeDirNames(dir, scope) {

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

@@ -721,6 +721,49 @@ export declare function recordChallengedHistory(controlDir: string, rows: Readon
 }>, now: () => number): void;
 /** Journal-aware read (observability/tests only — no engine consumer exists, on purpose). */
 export declare function readChallengedHistory(controlDir: string): Record<string, ChallengedHistoryRow>;
+export declare const PROJECTION_DEBTS_FILE = "projection-debts.json";
+/** One standing debt: the plane file at `relPath` (memory-dir-relative, canonical base) belongs to
+ *  committed entry `entryId`, whose id write-back has not landed; `rev` is the rev the projection
+ *  was staged against (the CAS baseline a reconciling harvest hands its update). */
+export interface ProjectionDebtRow {
+    relPath: string;
+    entryId: string;
+    rev: string;
+    at: number;
+}
+/** WRITE-AHEAD staging. Upsert discipline (adversarial round 2): a stage lands only when the seat
+ *  has NO standing row, the standing row is the stager's OWN entry (a rev refresh), or the
+ *  standing row is the entry the stager itself just judged stale (`replaces` — the same-harvest
+ *  stale-then-remint lane). It never blindly replaces ANOTHER writer's protection: a lagging
+ *  process that validated an old row before pausing must not overwrite the row a faster sibling
+ *  staged at the same path (its own commit then CAS-conflicts and its tuple-keyed clear misses
+ *  the survivor — the account converges instead of emptying). Called before the backend
+ *  transaction; the caller degrades LOUDLY (report warning) on a refused stage rather than
+ *  refusing the harvest — the ledger is duplicate-admission protection, not the commit's
+ *  integrity. */
+export declare function stageProjectionDebts(controlDir: string, rows: ReadonlyArray<{
+    relPath: string;
+    entryId: string;
+    rev: string;
+    replaces?: string;
+}>, now: () => number): {
+    refused: Array<{
+        relPath: string;
+        entryId: string;
+    }>;
+};
+/** Settle (remove) rows by ROW IDENTITY — (relPath, entryId), never the bare path: the write-back
+ *  landed, the staged claim turned out stale, or a materialize re-projected the seat. Identity
+ *  matters (adversarial review F1): a stale-clear judged against an OLD row must not delete the
+ *  NEWER row a later staging upserted at the same path (same harvest: stale X cleared while fresh
+ *  Y's write-back failed — a path-keyed drop would erase Y and re-open the duplicate window; same
+ *  shape across processes for a lagging sibling's clear). Missing rows are a no-op (idempotent). */
+export declare function settleProjectionDebts(controlDir: string, rows: ReadonlyArray<{
+    relPath: string;
+    entryId: string;
+}>): void;
+/** Strict read (ENOENT ⇒ empty; corrupt ⇒ throws — the caller's fail-closed arm owns the refusal). */
+export declare function readProjectionDebts(controlDir: string): ProjectionDebtRow[];
 /**
  * REF-C6 — write EVERY byte of `data` to `fd`, looping until the OS has taken all of them.
  *

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

@@ -1504,6 +1504,65 @@ export function recordChallengedHistory(controlDir, rows, now) {
 export function readChallengedHistory(controlDir) {
     return coerceChallengedHistory(readSidecarJson(controlDir, CHALLENGED_HISTORY_FILE));
 }
+export const PROJECTION_DEBTS_FILE = "projection-debts.json";
+function coerceProjectionDebts(raw) {
+    if (raw === undefined)
+        return { version: 1, rows: [] };
+    const rec = raw;
+    if (typeof rec !== "object" || rec === null || rec.version !== 1 || !Array.isArray(rec.rows)) {
+        throw new ControlPlaneCorruptError("memory projection-debt ledger has the wrong shape — refusing (fail-closed; an unreadable debt account must not read as 'no debts')");
+    }
+    for (const r of rec.rows) {
+        const row = r;
+        if (typeof row !== "object" ||
+            row === null ||
+            typeof row.relPath !== "string" ||
+            row.relPath.length === 0 ||
+            row.relPath.startsWith("/") ||
+            row.relPath.split(/[\\/]/).includes("..") ||
+            typeof row.entryId !== "string" ||
+            row.entryId.length === 0 ||
+            typeof row.rev !== "string" ||
+            row.rev.length === 0 ||
+            typeof row.at !== "number" ||
+            !Number.isFinite(row.at)) {
+            throw new ControlPlaneCorruptError("memory projection-debt ledger: a row is malformed — refusing (fail-closed)");
+        }
+    }
+    return rec;
+}
+export function stageProjectionDebts(controlDir, rows, now) {
+    if (rows.length === 0)
+        return { refused: [] };
+    const at = now();
+    return lockedStrictUpdate(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger", coerceProjectionDebts, (rec) => {
+        const byPath = new Map(rec.rows.map((r) => [r.relPath, r]));
+        const refused = [];
+        for (const r of rows) {
+            const existing = byPath.get(r.relPath);
+            if (existing !== undefined && existing.entryId !== r.entryId && existing.entryId !== r.replaces) {
+                refused.push({ relPath: r.relPath, entryId: r.entryId });
+                continue;
+            }
+            byPath.set(r.relPath, { relPath: r.relPath, entryId: r.entryId, rev: r.rev, at });
+        }
+        return { next: { version: 1, rows: [...byPath.values()] }, result: { refused } };
+    });
+}
+export function settleProjectionDebts(controlDir, rows) {
+    if (rows.length === 0)
+        return;
+    const drop = new Set(rows.map((r) => JSON.stringify([r.entryId, r.relPath])));
+    lockedStrictUpdate(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger", coerceProjectionDebts, (rec) => {
+        const kept = rec.rows.filter((r) => !drop.has(JSON.stringify([r.entryId, r.relPath])));
+        if (kept.length === rec.rows.length)
+            return { result: undefined };
+        return { next: { version: 1, rows: kept }, result: undefined };
+    });
+}
+export function readProjectionDebts(controlDir) {
+    return coerceProjectionDebts(readStrictSidecar(controlDir, PROJECTION_DEBTS_FILE, "memory projection-debt ledger")).rows;
+}
 export function writeAllSync(fd, data) {
     const buf = Buffer.from(data, "utf8");
     let written = 0;

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

@@ -426,6 +426,93 @@ export async function memoryBackendContract(hooks) {
         const flat = await b.search("same words", ["s1"], { limit: 3 });
         assert.deepStrictEqual(flat.map((h) => h.id), ["id-band-a-01", "id-band-b-01", "id-band-c-01"]);
     });
+    defer("design/336 §4 hold protocol (update form): mid-hold writes apply plainly (backend is hold-unaware); the release replay at the capture anchor is a reported conflict carrying currentRev; a clean release applies and the snapshot face answers its committed triple", async () => {
+        const b = await hooks.make();
+        const e1v0 = entry("id-hold-upd1", "s1", "held-clean", "committed v0");
+        assert.deepStrictEqual((await b.applyPatches([{ op: "add", id: e1v0.id, entry: e1v0 }])).conflicts, []);
+        const e1rel = entry("id-hold-upd1", "s1", "held-clean", "the released capture");
+        const rep1 = await b.applyPatches([{ op: "update", id: e1v0.id, entry: e1rel, baseRev: e1v0.rev }]);
+        assert.deepStrictEqual(rep1.conflicts, [], "a release onto an untouched anchor applies");
+        const snapFace = b.committedSnapshotOf;
+        if (typeof snapFace === "function") {
+            const snap = await snapFace.call(b, e1v0.id);
+            assert.strictEqual(snap.state, "row");
+            if (snap.state === "row") {
+                assert.strictEqual(snap.rev, e1rel.rev, "the snapshot tracks the UPDATE — not the add-time state");
+                assert.strictEqual(snap.binding.state, "bound");
+                if (snap.binding.state === "bound") {
+                    assert.strictEqual(snap.binding.scope, "s1");
+                    assert.strictEqual(snap.binding.slug, "held-clean");
+                }
+            }
+        }
+        const rep1b = await b.applyPatches([{ op: "update", id: e1v0.id, entry: e1rel, baseRev: e1v0.rev }]);
+        assert.strictEqual(rep1b.applied.length, 0);
+        assert.strictEqual(rep1b.conflicts.length, 1);
+        assert.strictEqual(rep1b.conflicts[0]?.currentRev, e1rel.rev, "currentRev is the retry's idempotency evidence");
+        const e2v0 = entry("id-hold-upd2", "s1", "held-raced", "committed v0");
+        assert.deepStrictEqual((await b.applyPatches([{ op: "add", id: e2v0.id, entry: e2v0 }])).conflicts, []);
+        const mid = entry("id-hold-upd2", "s1", "held-raced", "mid-hold edit by another writer");
+        const repMid = await b.applyPatches([{ op: "update", id: e2v0.id, entry: mid, baseRev: e2v0.rev }]);
+        assert.deepStrictEqual(repMid.conflicts, [], "a mid-hold write applies plainly — the backend is hold-unaware");
+        assert.strictEqual((await b.getByIds([e2v0.id])).length, 1, "the held id keeps serving reads during the pendency window");
+        const e2rel = entry("id-hold-upd2", "s1", "held-raced", "the captured bytes");
+        const rep2 = await b.applyPatches([{ op: "update", id: e2v0.id, entry: e2rel, baseRev: e2v0.rev }]);
+        assert.strictEqual(rep2.applied.length, 0, "the release never blind-writes over a mid-hold winner");
+        assert.strictEqual(rep2.conflicts.length, 1);
+        assert.strictEqual(rep2.conflicts[0]?.baseRev, e2v0.rev);
+        assert.strictEqual(rep2.conflicts[0]?.currentRev, mid.rev, "the conflict names the winner — the dispose('conflict') evidence");
+        assert.strictEqual((await b.getByIds([e2v0.id]))[0]?.body.replace(/\s+$/, ""), "mid-hold edit by another writer", "the winner's content survives");
+    });
+    defer("design/336 §4 hold protocol (add form): a guard-absent release applies onto a free id; the crash retry re-applies idempotently (one row, original slug); a concurrent claim answers the guarded conflict with currentRev and survives", async () => {
+        const b = await hooks.make();
+        const rel = entry("id-hold-add1", "s1", "held-note", "instruction body");
+        assert.deepStrictEqual((await b.applyPatches([{ op: "add", id: rel.id, entry: rel, guard: "absent" }])).conflicts, []);
+        const rep2 = await b.applyPatches([{ op: "add", id: rel.id, entry: rel, guard: "absent" }]);
+        assert.deepStrictEqual(rep2.conflicts, [], "the crash retry of a committed release re-applies idempotently");
+        assert.deepStrictEqual(rep2.applied, [{ op: "add", id: rel.id, slug: "held-note" }]);
+        assert.deepStrictEqual((await b.listHeaders(["s1"])).filter((h) => h.id === rel.id).map((h) => h.slug), ["held-note"], "ONE row at the ORIGINAL slug — never a suffixed duplicate");
+        const claimed = entry("id-hold-add2", "s1", "claimed-note", "the claimant's content");
+        assert.deepStrictEqual((await b.applyPatches([{ op: "add", id: claimed.id, entry: claimed }])).conflicts, []);
+        const rel2 = entry("id-hold-add2", "s1", "claimed-note", "the captured bytes");
+        const rep3 = await b.applyPatches([{ op: "add", id: rel2.id, entry: rel2, guard: "absent" }]);
+        assert.strictEqual(rep3.applied.length, 0);
+        assert.strictEqual(rep3.conflicts.length, 1);
+        assert.match(rep3.conflicts[0]?.reason ?? "", /add_guard_absent_conflict/);
+        assert.strictEqual(rep3.conflicts[0]?.currentRev, claimed.rev, "currentRev distinguishes 'claimed by another writer' from the idempotent retry");
+        assert.strictEqual((await b.getByIds([claimed.id]))[0]?.body.replace(/\s+$/, ""), "the claimant's content", "the claimant survives");
+    });
+    defer("design/336: the whitewash judgment precedes CAS — an origin/trust strip with a STALE baseRev still answers the malformed refusal, never the rev-mismatch conflict", async () => {
+        const b = await hooks.make();
+        const origin = { taint: "external", cause: "observed", at: 1700000000900 };
+        const m0 = { id: "id-prec-0001", scope: "s1", slug: "prec-marked", frontmatter: { name: "prec", origin }, body: "b0", rev: "" };
+        m0.rev = computeEntryRev(m0);
+        assert.deepStrictEqual((await b.applyPatches([{ op: "add", id: m0.id, entry: m0 }])).conflicts, []);
+        const m1 = { ...m0, body: "b1", rev: "" };
+        m1.rev = computeEntryRev(m1);
+        assert.deepStrictEqual((await b.applyPatches([{ op: "update", id: m0.id, entry: m1, baseRev: m0.rev }])).conflicts, []);
+        const stripped = { id: m0.id, scope: "s1", slug: "prec-marked", frontmatter: { name: "prec" }, body: "b2", rev: "" };
+        stripped.rev = computeEntryRev(stripped);
+        const rep = await b.applyPatches([{ op: "update", id: m0.id, entry: stripped, baseRev: m0.rev }]);
+        assert.strictEqual(rep.applied.length, 0);
+        assert.strictEqual(rep.conflicts.length, 1);
+        assert.match(rep.conflicts[0]?.reason ?? "", /malformed patch refused/, "the stronger refusal answers — a CAS conflict here would hide the whitewash");
+        const prov = { kind: "repo_file", path: "AGENTS.md", contentHash: "sha256:cccc3333", ingestedAt: 1700000001000 };
+        const p0 = { id: "id-prec-0002", scope: "s1", slug: "prec-repo", frontmatter: { name: "prec-repo", provenance: prov, trust: "untrusted" }, body: "p0", rev: "" };
+        p0.rev = computeEntryRev(p0);
+        assert.deepStrictEqual((await b.applyPatches([{ op: "add", id: p0.id, entry: p0 }])).conflicts, []);
+        const p1 = { ...p0, body: "p1", rev: "" };
+        p1.rev = computeEntryRev(p1);
+        assert.deepStrictEqual((await b.applyPatches([{ op: "update", id: p0.id, entry: p1, baseRev: p0.rev }])).conflicts, []);
+        const strippedTrust = { id: p0.id, scope: "s1", slug: "prec-repo", frontmatter: { name: "prec-repo", provenance: prov }, body: "p2", rev: "" };
+        strippedTrust.rev = computeEntryRev(strippedTrust);
+        const rep2 = await b.applyPatches([{ op: "update", id: p0.id, entry: strippedTrust, baseRev: p0.rev }]);
+        assert.strictEqual(rep2.applied.length, 0);
+        assert.strictEqual(rep2.conflicts.length, 1);
+        assert.match(rep2.conflicts[0]?.reason ?? "", /malformed patch refused/);
+        assert.deepStrictEqual((await b.getByIds([m0.id]))[0]?.frontmatter.origin, origin);
+        assert.strictEqual((await b.getByIds([p0.id]))[0]?.frontmatter.trust, "untrusted");
+    });
     defer("consolidation cursor round-trips per scope; unset → undefined", async () => {
         const b = await hooks.make();
         assert.strictEqual(await b.getConsolidationCursor("s1"), undefined);

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

@@ -254,6 +254,18 @@ export interface MemoryBackend {
      *   earlier delete in the same batch does not blank the baseline). The one legal exit is the
      *   COMMITTED tombstone: after a delete commits, the marker's life ends with the id (a fresh id —
      *   or the same id in a LATER batch — starts an unmarked life; the engine re-judges its session);
+     * - PRECEDENCE (FAM-1 #5, every whitewash spelling): the malformed judgment answers BEFORE
+     *   guard/CAS arithmetic — a strip riding a stale `baseRev` (or a guard conflict) still answers
+     *   /malformed patch refused/, never the ordinary rev-mismatch conflict (a whitewash is illegal
+     *   at ANY rev, and the weaker conflict would tell the caller's ladder to rebase and retry it);
+     * - design/336 §4 hold protocol: the backend is hold-UNAWARE — instruction holds live on the
+     *   ENGINE's control plane, so a held id keeps serving reads and ordinary add/update patches for
+     *   it apply plainly (no queueing, no refusal). The settlement-period write interaction resolves
+     *   at release time through the clauses above: the release replays the capture-time anchor
+     *   (update+`baseRev` / `guard: "absent"` add), a mid-hold winner surfaces as the REPORTED
+     *   conflict carrying `currentRev` (the engine's conflict-disposition evidence), and the
+     *   crash-idempotent retry reads the optional committed-snapshot face (post-update rev + bound
+     *   projection) — all asserted by the suite's two hold-protocol cases;
      * - conflicts are per-patch and non-fatal: the rest of the batch still applies.
      */
     applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
@@ -338,7 +350,7 @@ export interface MemorySessionHandle {
     adoptionRestricted?: boolean;
 }
 /** Stable rejection codes a harvest gate can produce (model-visible gate events — 镜头 I). */
-export type HarvestRejectionCode = "outside_root" | "symlink" | "secret" | "injection" | "filename" | "too_large" | "file_cap" | "readonly_layer" | "stub_modified" | "nested_too_deep" | "quarantine_failed" | "unreadable" | "polluted" | "restricted_divergence" | "invalid";
+export type HarvestRejectionCode = "outside_root" | "symlink" | "secret" | "injection" | "filename" | "too_large" | "file_cap" | "readonly_layer" | "stub_modified" | "nested_too_deep" | "quarantine_failed" | "unreadable" | "deferred" | "polluted" | "restricted_divergence" | "invalid";
 /** One rejected file: path (relative to the memory dir), stable code, and a model-readable reason. */
 export interface HarvestRejection {
     path: string;