@sema-agent/core 5.46.0 → 5.48.0

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

@@ -900,6 +900,7 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
     /** Lexical floor (design/138 §2.1): `1 - Jaccard` distance over name+description+body, ascending. */
     search(query: string, scopes: readonly string[], opts?: {
         limit?: number;
+        exposureBands?: boolean;
     }): Promise<ScoredMemoryEntry[]>;
     private searchFrom;
     /**

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

@@ -2135,7 +2135,8 @@ export class FileMemoryEngineBackend {
                 scored.push({ ...headerOf(e, join(dir, `${e.slug}.md`)), score: d });
             }
         }
-        scored.sort((a, b) => a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+        const band = opts?.exposureBands === true ? (h) => (h.exposure === "external" ? 1 : 0) : () => 0;
+        scored.sort((a, b) => band(a) - band(b) || a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
         return scored.slice(0, limit);
     }
     async applyPatches(patches) {
@@ -3694,6 +3695,7 @@ function headerOf(e, path) {
         mtimeMs,
         rev: e.rev,
         sizeBytes: Buffer.byteLength(serializeEntryFile(e), "utf8"),
+        ...(committedOriginOf(e.frontmatter) !== undefined ? { exposure: "external" } : {}),
     };
 }
 function readSafe(path) {

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

@@ -27,32 +27,59 @@ export declare function computeEntryRev(entry: Pick<MemoryEntry, "id" | "frontma
 /** True ⇔ `extra` carries origin-form bytes (an invalid/foreign origin block preserved verbatim,
  *  or an origin block a pre-336 vintage folded into `extra`). */
 export declare function hasOriginFormExtra(fm: Pick<MemoryEntryFrontmatter, "extra">): boolean;
+/**
+ * design/336 slice 2 — the ONE serialization-closed tokenization of `extra`'s origin-form bytes
+ * (the adversarial round-3 deep fix; every predicate below reads THROUGH this walk, never through
+ * a private re-implementation). A CARRIER is one independent origin representation:
+ *  - a bare block header (`origin:` — judged on the TRIMMED line, so indented spellings count),
+ *    together with its indented continuation lines: ONE carrier, normalized field-by-field
+ *    (first-wins per key; unknown sub-lines tolerated — an in-block `origin: …` scalar is part of
+ *    THIS carrier, never its own);
+ *  - a scalar `origin: …` line OUTSIDE any block: ONE carrier, always the sentinel (a scalar names
+ *    no fields).
+ * Per-carrier normalization is INDEPENDENT on purpose (adversarial round 2: a cross-carrier
+ * accumulation let two individually-invalid blocks combine into a valid marker, and parse-time
+ * block reordering then changed which fields won): a carrier whose own fields form a valid origin
+ * (taint external, `at` present AND serialization-stable, cause absent-or-known) normalizes to
+ * that value; anything else normalizes to the `{ taint: "external", at: 0 }` sentinel (cause
+ * absent, `at` = 0 — a clock here would make engine and backend normalize to different values and
+ * the engine's own patches would never converge). Marker-form bytes are NEVER dropped and NEVER
+ * read as clean absence.
+ */
+export declare function extraOriginCarriers(extra: readonly string[] | undefined): MemoryEntryOrigin[];
+/**
+ * design/336 §2.2 — the ONE reading of an entry's committed external-origin marker: the typed
+ * field when present, else the first `extra` carrier's deterministic normalization
+ * ({@link extraOriginCarriers}). Returns `undefined` ⇔ the entry carries no marker in any form.
+ * The first-carrier choice is immaterial on every committable shape: a representation whose
+ * carriers DISAGREE is refused at every inbound boundary ({@link ambiguousOriginRepresentation}),
+ * so a committed multi-carrier shape always answers the one agreed value.
+ */
 export declare function committedOriginOf(fm: Pick<MemoryEntryFrontmatter, "origin" | "extra">): MemoryEntryOrigin | undefined;
 /** Deep equality over the origin marker (every member, absence included) — the immutability law's
  *  comparator: a downgraded cause or a rewritten `at` is as refused as a strip. */
 export declare function originEquals(a: MemoryEntryOrigin | undefined, b: MemoryEntryOrigin | undefined): boolean;
 /**
- * design/336 (adversarial rounds 1+2) — the AMBIGUOUS origin-representation predicate, ONE law for
+ * design/336 (adversarial rounds 1-3) — the AMBIGUOUS origin-representation predicate, ONE law for
  * every inbound boundary (backend patch law, sync wire, bundle validation, out-of-band adoption):
- * a frontmatter whose marker has MORE THAN ONE carrier is refused unless it is the one legal
- * legacy shape — a typed origin beside EXACTLY ONE extra-form carrier that normalizes EQUAL.
- * Covered vehicles: typed A + disagreeing extra block B (round 1 — the typed member satisfies the
- * immutability comparator while B rides into storage and a merging reparse answers B); extra-only
- * duplicate blocks (round 2 — cross-block field combination plus the parser's block reordering
- * across a serialize cycle rewrite members with no typed origin at all); typed + multiple extra
- * carriers. Single-carrier shapes and the equal legacy carriage stay legal, so carry-forward of
- * old committed forms never bricks. The model-writable face never reaches this predicate — the
- * harvest strips every origin form and re-judges (§2.3-1).
+ * a representation is refused ⇔ its carriers DISAGREE — any two of {the typed field, each `extra`
+ * carrier's independent normalization ({@link extraOriginCarriers})} differ on any member — or the
+ * typed `at` is not serialization-stable (a value that cannot survive its own serialization is a
+ * representation conflict with the entry's next parse). Covered vehicles: typed A + disagreeing
+ * extra block B (round 1 — the typed member satisfies the immutability comparator while B rides
+ * into storage and a reparse answers B); disagreeing extra-only blocks (round 2 — cross-block
+ * field combination plus parse-time block reordering rewrite members with no typed origin at all).
  *
- * ⚠ KNOWN OPEN (adversarial round 3 — ESCALATED under the three-same-root-rounds rule, no further
- * spelling patch here): the predicate's accepted set is not SERIALIZATION-CLOSED. A scalar
- * `origin: …` sub-line INSIDE an accepted block is not counted as a carrier, yet a serialize →
- * reparse cycle migrates the block to the typed field and drops that sub-line into `extra` — the
- * semantic rev moves, so the committed account diverges from the reparsed bytes (downstream: CAS
- * refusal / quarantine, the FAIL-CLOSED direction — the marker VALUE itself is preserved, no
- * member is rewritten). The registered deep fix is a serialization-closed carrier tokenization
- * with round-trip property tests (carrier count, normalized origin, ambiguity verdict and rev all
- * invariant across serialize/parse at every boundary) — a slice-2 admission item, not a patch.
+ * The refusal boundary keys on DISAGREEMENT, not on carrier count (slice-2 serialization closure,
+ * the round-3 deep fix): agreeing carriers are never a member-rewrite vehicle — refusing them by
+ * count alone made the verdict flip across a serialize/parse cycle (a promotion reseats one
+ * carrier without changing any value). This generalizes the old "typed beside EXACTLY ONE equal
+ * extra form" legacy-carriage exception: N agreeing representations are that same carriage, so
+ * carry-forward of old committed forms never bricks. The model-writable face never reaches this
+ * predicate — the harvest strips every origin form and re-judges (§2.3-1). Together with the
+ * pristine-only typed seating (parse) and the carrier-canonical rev ({@link computeEntryRev}),
+ * the accepted set is SERIALIZATION-CLOSED: carrier count, normalized origin, ambiguity verdict
+ * and rev are all invariant across serialize/parse at every boundary (property-tested).
  */
 export declare function ambiguousOriginRepresentation(fm: Pick<MemoryEntryFrontmatter, "origin" | "extra">): boolean;
 /**

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

@@ -5,6 +5,10 @@ const ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{7,63}$/;
 export function isValidEntryId(value) {
     return ID_RE.test(value);
 }
+const ORIGIN_AT_RE = /^-?\d+(\.\d+)?$/;
+function atSerializationStable(at) {
+    return Number.isFinite(at) && ORIGIN_AT_RE.test(String(at));
+}
 export function parseEntryFile(text) {
     const fm = {};
     if (!text.startsWith(`${FM_FENCE}\n`) && text.trimStart() !== FM_FENCE) {
@@ -31,7 +35,7 @@ export function parseEntryFile(text) {
     const prov = {};
     let inOrigin = false;
     const originRaw = [];
-    const originUnknown = [];
+    let originPristine = true;
     const orig = {};
     for (let i = 1; i < end; i++) {
         const line = lines[i] ?? "";
@@ -83,17 +87,17 @@ export function parseEntryFile(text) {
             const m = /^\s+([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/.exec(line);
             if (m) {
                 const [, k = "", v = ""] = m;
-                if (k === "taint")
+                if (k === "taint" && orig.taint === undefined)
                     orig.taint = v;
-                else if (k === "cause")
+                else if (k === "cause" && orig.cause === undefined)
                     orig.cause = v;
-                else if (k === "at")
-                    orig.at = /^-?\d+(\.\d+)?$/.test(v) ? Number(v) : Number.NaN;
+                else if (k === "at" && orig.at === undefined)
+                    orig.at = ORIGIN_AT_RE.test(v) ? Number(v) : Number.NaN;
                 else
-                    originUnknown.push(line);
+                    originPristine = false;
             }
             else {
-                originUnknown.push(line);
+                originPristine = false;
             }
             continue;
         }
@@ -157,9 +161,12 @@ export function parseEntryFile(text) {
         }
     }
     if (originRaw.length > 0) {
-        if (orig.taint === "external" && typeof orig.at === "number" && Number.isFinite(orig.at) && (orig.cause === undefined || MEMORY_ORIGIN_CAUSES.includes(orig.cause))) {
+        if (originPristine &&
+            orig.taint === "external" &&
+            typeof orig.at === "number" &&
+            atSerializationStable(orig.at) &&
+            (orig.cause === undefined || MEMORY_ORIGIN_CAUSES.includes(orig.cause))) {
             fm.origin = { taint: "external", ...(orig.cause !== undefined ? { cause: orig.cause } : {}), at: orig.at };
-            extra.push(...originUnknown);
         }
         else {
             extra.push(...originRaw);
@@ -188,29 +195,31 @@ export function serializeEntryFile(entry) {
     }
     if (fm.trust !== undefined)
         lines.push(`trust: ${fm.trust}`);
+    if (fm.extra)
+        lines.push(...fm.extra);
     if (fm.origin !== undefined) {
         lines.push("origin:", `  taint: ${fm.origin.taint}`, ...(fm.origin.cause !== undefined ? [`  cause: ${fm.origin.cause}`] : []), `  at: ${fm.origin.at}`);
     }
-    if (fm.extra)
-        lines.push(...fm.extra);
     lines.push(FM_FENCE, "");
     const body = entry.body.replace(/\s+$/, "");
     return `${lines.join("\n")}${body}${body ? "\n" : ""}`;
 }
 export function computeEntryRev(entry) {
     const fm = entry.frontmatter;
+    const hasCarrierExtra = fm.extra !== undefined && fm.extra.some((line) => ORIGIN_FORM_LINE_RE.test(line));
+    const canonicalOrigin = fm.origin !== undefined ? fm.origin : hasCarrierExtra ? committedOriginOf(fm) : undefined;
     const canonical = JSON.stringify([
         entry.id,
         fm.name ?? null,
         fm.description ?? null,
         fm.type ?? null,
         fm.deleted === true,
-        fm.extra ?? [],
+        hasCarrierExtra ? partitionOriginLines(fm.extra).kept : (fm.extra ?? []),
         entry.body.replace(/\s+$/, ""),
         ...(fm.provenance !== undefined || fm.trust !== undefined
             ? [fm.trust ?? null, fm.provenance !== undefined ? [fm.provenance.kind, fm.provenance.path, fm.provenance.contentHash, fm.provenance.ingestedAt] : null]
             : []),
-        ...(fm.origin !== undefined ? [["origin", fm.origin.taint, fm.origin.cause ?? null, fm.origin.at]] : []),
+        ...(canonicalOrigin !== undefined ? [["origin", canonicalOrigin.taint, canonicalOrigin.cause ?? null, canonicalOrigin.at]] : []),
     ]);
     return createHash("sha256").update(canonical, "utf8").digest("hex").slice(0, 16);
 }
@@ -218,55 +227,53 @@ const ORIGIN_FORM_LINE_RE = /^\s*origin\s*:/;
 export function hasOriginFormExtra(fm) {
     return fm.extra !== undefined && fm.extra.some((line) => ORIGIN_FORM_LINE_RE.test(line));
 }
-function walkExtraOrigin(extra) {
+export function extraOriginCarriers(extra) {
     if (extra === undefined)
-        return { carriers: 0, first: undefined };
-    let carriers = 0;
-    let inBlock = false;
-    let blockIndex = 0;
-    let taint;
-    let cause;
-    let at;
+        return [];
+    const carriers = [];
+    let block;
+    const closeBlock = () => {
+        if (block === undefined)
+            return;
+        const { taint, cause, at } = block;
+        block = undefined;
+        if (taint === "external" && typeof at === "number" && atSerializationStable(at) && (cause === undefined || MEMORY_ORIGIN_CAUSES.includes(cause))) {
+            carriers.push({ taint: "external", ...(cause !== undefined ? { cause: cause } : {}), at });
+        }
+        else {
+            carriers.push({ taint: "external", at: 0 });
+        }
+    };
     for (const line of extra) {
-        const trimmed = line.trim();
-        if (/^origin\s*:\s*$/.test(trimmed)) {
-            carriers += 1;
-            inBlock = true;
-            blockIndex += 1;
+        if (/^\s*origin\s*:\s*$/.test(line)) {
+            closeBlock();
+            block = {};
             continue;
         }
-        if (ORIGIN_FORM_LINE_RE.test(line) && !inBlock) {
-            carriers += 1;
+        if (block !== undefined && /^\s/.test(line)) {
+            const m = /^\s+([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/.exec(line);
+            if (m !== null) {
+                const [, k = "", v = ""] = m;
+                if (k === "taint" && block.taint === undefined)
+                    block.taint = v;
+                else if (k === "cause" && block.cause === undefined)
+                    block.cause = v;
+                else if (k === "at" && block.at === undefined)
+                    block.at = ORIGIN_AT_RE.test(v) ? Number(v) : Number.NaN;
+            }
             continue;
         }
-        if (!/^\s/.test(line))
-            inBlock = false;
-        if (!inBlock || blockIndex !== 1)
-            continue;
-        const m = /^\s+([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/.exec(line);
-        if (m === null)
-            continue;
-        const [, k = "", v = ""] = m;
-        if (k === "taint" && taint === undefined)
-            taint = v;
-        else if (k === "cause" && cause === undefined)
-            cause = v;
-        else if (k === "at" && at === undefined)
-            at = /^-?\d+(\.\d+)?$/.test(v) ? Number(v) : Number.NaN;
+        closeBlock();
+        if (ORIGIN_FORM_LINE_RE.test(line))
+            carriers.push({ taint: "external", at: 0 });
     }
-    if (carriers === 0)
-        return { carriers: 0, first: undefined };
-    if (taint === "external" && typeof at === "number" && Number.isFinite(at) && (cause === undefined || MEMORY_ORIGIN_CAUSES.includes(cause))) {
-        return { carriers, first: { taint: "external", ...(cause !== undefined ? { cause: cause } : {}), at } };
-    }
-    return { carriers, first: { taint: "external", at: 0 } };
+    closeBlock();
+    return carriers;
 }
 export function committedOriginOf(fm) {
     if (fm.origin !== undefined)
         return { taint: fm.origin.taint, ...(fm.origin.cause !== undefined ? { cause: fm.origin.cause } : {}), at: fm.origin.at };
-    if (!hasOriginFormExtra(fm))
-        return undefined;
-    return walkExtraOrigin(fm.extra).first ?? { taint: "external", at: 0 };
+    return extraOriginCarriers(fm.extra)[0];
 }
 export function originEquals(a, b) {
     if (a === undefined || b === undefined)
@@ -274,13 +281,31 @@ export function originEquals(a, b) {
     return a.taint === b.taint && a.cause === b.cause && a.at === b.at;
 }
 export function ambiguousOriginRepresentation(fm) {
-    const { carriers, first } = walkExtraOrigin(fm.extra);
-    const total = carriers + (fm.origin !== undefined ? 1 : 0);
-    if (total <= 1)
-        return false;
-    if (total === 2 && fm.origin !== undefined && carriers === 1)
-        return !originEquals(fm.origin, first);
-    return true;
+    if (fm.origin !== undefined && !atSerializationStable(fm.origin.at))
+        return true;
+    const values = extraOriginCarriers(fm.extra);
+    if (fm.origin !== undefined)
+        values.push({ taint: fm.origin.taint, ...(fm.origin.cause !== undefined ? { cause: fm.origin.cause } : {}), at: fm.origin.at });
+    return values.some((v) => !originEquals(v, values[0]));
+}
+function partitionOriginLines(extra) {
+    const kept = [];
+    let removedAny = false;
+    let inBlock = false;
+    for (const line of extra) {
+        if (ORIGIN_FORM_LINE_RE.test(line)) {
+            inBlock = /^\s*origin\s*:\s*$/.test(line);
+            removedAny = true;
+            continue;
+        }
+        if (inBlock && /^\s/.test(line)) {
+            removedAny = true;
+            continue;
+        }
+        inBlock = false;
+        kept.push(line);
+    }
+    return { kept, removedAny };
 }
 export function stripModelWrittenOrigin(fm) {
     let stripped = false;
@@ -288,26 +313,15 @@ export function stripModelWrittenOrigin(fm) {
         delete fm.origin;
         stripped = true;
     }
-    if (fm.extra !== undefined && fm.extra.some((line) => ORIGIN_FORM_LINE_RE.test(line))) {
-        const kept = [];
-        let inBlock = false;
-        for (const line of fm.extra) {
-            if (ORIGIN_FORM_LINE_RE.test(line)) {
-                inBlock = /^\s*origin\s*:\s*$/.test(line);
-                stripped = true;
-                continue;
-            }
-            if (inBlock && /^\s/.test(line)) {
-                stripped = true;
-                continue;
-            }
-            inBlock = false;
-            kept.push(line);
+    if (fm.extra !== undefined) {
+        const { kept, removedAny } = partitionOriginLines(fm.extra);
+        if (removedAny) {
+            stripped = true;
+            if (kept.length > 0)
+                fm.extra = kept;
+            else
+                delete fm.extra;
         }
-        if (kept.length > 0)
-            fm.extra = kept;
-        else
-            delete fm.extra;
     }
     return stripped;
 }

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

@@ -1,11 +1,12 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, } from "./engine.js";
-export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type MemoryGetDetails, } from "./tools.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, memoryRecallDisciplineSegment, entryFileHeadCarriesOrigin, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, type MemoryEngineOptions, type MemoryInjection, type EntryProvenanceAccount, } from "./engine.js";
+export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, type MemorySearchDetails, type MemorySearchHit, type CleanMemorySearchHit, type ExposedMemorySearchHit, type MemoryGetDetails, } from "./tools.js";
+export { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_RECALL_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, memoryExposureIndexRow, parseMemoryExposureIndexRow, } from "./provenance-wording.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile, type TransferEvidence, type CommittedBinding, type CommittedEntrySnapshot, type CommittedScopeSnapshots, type EntryCustodyReport, erasureSelectHash, type EraseMemoryEntriesInput, type ErasureSelect, type ErasedBinding, type MemoryErasureAttestation, type MemoryExportSnapshot, } from "./file-backend.js";
 export { computeBundleSectionHashes, computeMemoryBundleHash, memoryBundleInvalid, type MemoryExportBundle, type MemoryImportReport, type MemoryBundleImportPlan, type BundleChallengeRow, type BundleLineageRow, type BundlePollutedSession, } from "./export-bundle.js";
 export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengeAppendResult, type ChallengeAssignment, type ChallengeEvent, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, } from "./layout.js";
 export { readV2HeaderHints, isInstructionEntry, type V2HeaderHints } from "./header-hints.js";
-export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, committedOriginOf, originEquals, type ParsedEntryFile } from "./frontmatter.js";
+export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, committedOriginOf, originEquals, ambiguousOriginRepresentation, type ParsedEntryFile } from "./frontmatter.js";
 export { MEMORY_ORIGIN_CAUSES } from "./types.js";
 export type { MemoryBackend, MemoryEntry, MemoryEntryFrontmatter, MemoryEntryOrigin, MemoryOriginCause, MemoryEntryHeader, ScoredMemoryEntry, NotePatch, PatchReport, MaterializedFile, MemorySessionHandle, HarvestReport, HarvestRejection, HarvestRejectionCode, MemoryAnnouncement, ScanFinding, } from "./types.js";
 export { memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, } from "./memory-backend-contract.js";

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

@@ -1,11 +1,12 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, memoryRecallDisciplineSegment, entryFileHeadCarriesOrigin, MEMORY_PREFERENCE_DISCIPLINE, MEMORY_READONLY_NOTICE, MEMORY_INDEX_MAX_LINES, MEMORY_INDEX_MAX_BYTES, STUB_ARCHIVED_LINE, DEFAULT_MAX_MEMORY_FILES, DEFAULT_HARVEST_DEADLINE_MS, DEFAULT_HARVEST_FILE_BUDGET, MASS_DELETION_FUSE_RATIO, renderAnnouncements, } from "./engine.js";
 export { MEMORY_SEARCH_TOOL_NAME, MEMORY_GET_TOOL_NAME, MEMORY_ENGINE_TOOL_NAMES, } from "./tools.js";
+export { MEMORY_EXPOSURE_BANNER, MEMORY_EXPOSURE_HANDLE_TAG, MEMORY_PROVENANCE_RECALL_SENTENCE, MEMORY_PROVENANCE_SEARCH_SENTENCE, memoryExposureIndexRow, parseMemoryExposureIndexRow, } from "./provenance-wording.js";
 export { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, erasureSelectHash, } from "./file-backend.js";
 export { computeBundleSectionHashes, computeMemoryBundleHash, memoryBundleInvalid, } from "./export-bundle.js";
 export { ControlPlaneCorruptError, deriveControlPlaneDir, deriveRepoControlPlaneDir, deriveRepoKey, deriveRepoMemoryDir, deriveProjectMemoryDir, deriveProjectControlDir, recordProjectIdHint, lookupProjectIdHint, PROJECT_ID_HINTS_FILE, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, claimRootScope, rootScopeOf, enqueueMemoryAnnouncement, drainMemoryAnnouncements, peekMemoryAnnouncements, bumpScanFuse, scanFuseCount, clearScanFuse, ANNOUNCEMENTS_FILE, MEMORY_ANNOUNCEMENTS_MAX, SCAN_FUSE_FILE, SCAN_FUSE_THRESHOLD, LINEAGE_FILE, CHALLENGES_FILE, CHALLENGED_HISTORY_FILE, CHALLENGE_LEDGER_MAX_EVENTS, rebuildStrictControlPlaneLedger, } from "./layout.js";
 export { readV2HeaderHints, isInstructionEntry } from "./header-hints.js";
-export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, committedOriginOf, originEquals } from "./frontmatter.js";
+export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, committedOriginOf, originEquals, ambiguousOriginRepresentation } from "./frontmatter.js";
 export { MEMORY_ORIGIN_CAUSES } from "./types.js";
 export { memoryBackendContract, assertMemoryBackendSearchEquivalence, } from "./memory-backend-contract.js";
 export { SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, } from "./scope-contract.js";

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

@@ -360,6 +360,20 @@ export declare const LINEAGE_AUDIT_MAX_ROWS = 2048;
 /** The challenged-history account (design/180 B-3: collect-only, fail-open bookkeeping —
  *  the mechanical shadow of "user saw a retrieved entry and corrected it in the same session"). */
 export declare const CHALLENGED_HISTORY_FILE = "usage-challenged-history.json";
+/** The locked, journaled, FAIL-CLOSED sidecar update. `coerce` must throw
+ *  {@link ControlPlaneCorruptError} on any unacceptable shape; only ENOENT reads as the empty
+ *  initial state (`undefined` handed to `coerce`). Exported module-level (not on the root barrel)
+ *  for the strict-account family's siblings (design/336 slice 2: the delegation-settlement /
+ *  session-account / instruction-hold sidecars live in their own module but MUST be this exact
+ *  lock+journal discipline — a second implementation would be a drift seam). */
+export declare function lockedStrictUpdate<S, T>(controlDir: string, fileName: string, what: string, coerce: (raw: unknown) => S, fn: (current: S) => {
+    next?: S;
+    result: T;
+}): T;
+/** Lock-less strict READ (journal-aware): a parseable journal wins (committed next state); an
+ *  unparseable journal, or an unreadable/unparseable file, is corrupt. Exported module-level for
+ *  the strict-account family's siblings (see {@link lockedStrictUpdate}). */
+export declare function readStrictSidecar(controlDir: string, fileName: string, what: string): unknown;
 /** One committed contribution: session → entry, latest rev/at only (the load-bearing invariant is
  *  "which sessions contributed this id", not the per-commit history — that is the audit account). */
 export interface LineageContribution {

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

@@ -894,7 +894,7 @@ function rollForwardStrictSidecar(file, journal) {
     atomicWriteFileSync(file, raw);
     rmSync(journal, { force: true });
 }
-function lockedStrictUpdate(controlDir, fileName, what, coerce, fn) {
+export function lockedStrictUpdate(controlDir, fileName, what, coerce, fn) {
     ensureDirExists(controlDir);
     const file = join(controlDir, fileName);
     const journal = `${file}.journal`;
@@ -934,7 +934,7 @@ function readStrictSidecarRaw(file, what) {
         throw new ControlPlaneCorruptError(`${what} is unparseable: ${file}`);
     }
 }
-function readStrictSidecar(controlDir, fileName, what) {
+export function readStrictSidecar(controlDir, fileName, what) {
     const file = join(controlDir, fileName);
     const journal = `${file}.journal`;
     let journalRaw;

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

@@ -350,6 +350,49 @@ export async function memoryBackendContract(hooks) {
         const hits = await b.search("same words", ["s1"]);
         assert.deepStrictEqual(hits.map((h) => h.id), ["id-tie-a-01", "id-tie-b-01"]);
     });
+    defer("design/336: headers carry the exposure fact on BOTH faces (listHeaders + search), typed and extra-form marker alike; unmarked entries carry none", async () => {
+        const b = await hooks.make();
+        const marked = entry("id-exp-typed-01", "s1", "marked-typed", "same words here");
+        marked.frontmatter.origin = { taint: "external", cause: "observed", at: 1700000000600 };
+        marked.rev = computeEntryRev(marked);
+        const extraForm = entry("id-exp-extra-01", "s1", "marked-extra", "same words here");
+        extraForm.frontmatter.extra = ["origin:", "  taint: external", "  at: 5"];
+        extraForm.rev = computeEntryRev(extraForm);
+        const clean = entry("id-exp-clean-01", "s1", "unmarked", "same words here");
+        const rep = await b.applyPatches([
+            { op: "add", id: marked.id, entry: marked },
+            { op: "add", id: extraForm.id, entry: extraForm },
+            { op: "add", id: clean.id, entry: clean },
+        ]);
+        assert.deepStrictEqual(rep.conflicts, []);
+        const headers = await b.listHeaders(["s1"]);
+        assert.strictEqual(headers.find((h) => h.id === marked.id)?.exposure, "external", "typed marker ⇒ header exposure");
+        assert.strictEqual(headers.find((h) => h.id === extraForm.id)?.exposure, "external", "extra-form marker ⇒ header exposure (one normalization)");
+        assert.strictEqual(headers.find((h) => h.id === clean.id)?.exposure, undefined, "unmarked ⇒ no exposure member");
+        const hits = await b.search("same words", ["s1"]);
+        assert.strictEqual(hits.find((h) => h.id === marked.id)?.exposure, "external", "search hits carry the same fact");
+        assert.strictEqual(hits.find((h) => h.id === clean.id)?.exposure, undefined);
+    });
+    defer("design/336: search exposureBands orders unmarked-first BEFORE truncation (the limit-boundary clean entry is served, never starved); absent flag keeps the single-band contract order", async () => {
+        const b = await hooks.make();
+        const mk = (id, slug, marked) => {
+            const e = entry(id, "s1", slug, "same words here");
+            if (marked) {
+                e.frontmatter.origin = { taint: "external", cause: "observed", at: 1700000000700 };
+                e.rev = computeEntryRev(e);
+            }
+            return e;
+        };
+        const m1 = mk("id-band-a-01", "band-a", true);
+        const m2 = mk("id-band-b-01", "band-b", true);
+        const m3 = mk("id-band-c-01", "band-c", true);
+        const clean = mk("id-band-z-01", "band-z", false);
+        assert.deepStrictEqual((await b.applyPatches([m1, m2, m3, clean].map((e) => ({ op: "add", id: e.id, entry: e })))).conflicts, []);
+        const banded = await b.search("same words", ["s1"], { limit: 3, exposureBands: true });
+        assert.deepStrictEqual(banded.map((h) => h.id), ["id-band-z-01", "id-band-a-01", "id-band-b-01"], "two-band order must apply before the limit truncation (clean first, contract order within the band)");
+        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("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/origin-clearance.d.ts

@@ -0,0 +1,66 @@
+import type { MemoryEntryOrigin } from "./types.js";
+export declare const ORIGIN_CLEARANCES_FILE = "origin-clearances.json";
+/** One clearance's terminal event (appended, never rewritten). */
+export interface OriginClearanceEvent {
+    eventId: string;
+    at: number;
+    to: "done" | "failed";
+    /** The resolver of THIS event (the opener on the normal path; a later resumer on a crash path). */
+    requestId: string;
+    /** Mechanical detail (landing slug, refusal reason) — engine-composed, bounded by the writer. */
+    detail?: string;
+}
+export interface OriginClearanceRow {
+    clearanceId: string;
+    /** The entry whose marker was cleared. The re-record keeps the SAME id (§2.3-2's later-batch
+     *  arm), so this key joins the clearance to the entry across its whole life. */
+    entryId: string;
+    scope: string;
+    slug: string;
+    /** The committed rev the clearance was judged against (the tombstone's CAS anchor). */
+    baseRev: string;
+    /** The cleared marker, verbatim (audit: what the host vouched away). */
+    origin: MemoryEntryOrigin;
+    /** WHO cleared — the mandatory audit attribution (never defaulted). */
+    requestId: string;
+    /** WHY — the host's stated ground (never defaulted). */
+    reason: string;
+    at: number;
+    status: "pending" | "done" | "failed";
+    /** CUSTODY: the full serialized cleared-entry file text. A crash between the tombstone batch and
+     *  the re-record batch leaves this as the only copy — the pending row is the loud recovery seat
+     *  (a later clearEntryOrigin call for the same entry resumes from it). */
+    entryText: string;
+    events: OriginClearanceEvent[];
+}
+/** Lock-free strict read of the whole account (host audit face; journal-aware, corrupt = throw). */
+export declare function readOriginClearances(controlDir: string): OriginClearanceRow[];
+/**
+ * WRITE-AHEAD open: append the pending row (custody included) before any store mutation. Refuses a
+ * second OPEN while a pending row for the same entry stands — the pending row is a resume seat,
+ * not a queue (the caller resumes it instead).
+ */
+export declare function openOriginClearance(controlDir: string, row: Omit<OriginClearanceRow, "status" | "events">): void;
+/**
+ * Terminal event append + status flip. Unknown clearanceId is a corrupt-caller refusal.
+ *
+ * SINGLE-WINNER terminal (codex r1): a row already terminal ignores a late contradictory
+ * settlement — two concurrent resumers race the store legs (the store's own CAS decides those),
+ * and the loser's stale verdict must not overwrite the winner's audit state (a successfully
+ * cleared entry reading `failed` with contradictory events). The loser's own thrown refusal is
+ * its loud channel; a re-call then answers off the CURRENT committed state.
+ *
+ * `keepPending: true` appends the event WITHOUT flipping the status: the resume-seat form for a
+ * refused re-record leg — the tombstone has committed and the custody row is the ONLY copy of the
+ * bytes, so the row must stay resumable (a `failed` flip would strand them: the resume arm only
+ * completes pending rows).
+ */
+export declare function settleOriginClearance(controlDir: string, input: {
+    clearanceId: string;
+    to: "done" | "failed";
+    requestId: string;
+    eventId: string;
+    now: () => number;
+    detail?: string;
+    keepPending?: boolean;
+}): void;