@sema-agent/core 5.45.0 → 5.47.0

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

@@ -1,4 +1,4 @@
-import type { MemoryEntry, MemoryEntryFrontmatter } from "./types.js";
+import { type MemoryEntry, type MemoryEntryFrontmatter, type MemoryEntryOrigin } from "./types.js";
 /** A parsed entry file: frontmatter (may be absent — CC allows bare files; harvest mints them) + body. */
 export interface ParsedEntryFile {
     /** The hidden immutable id (`id:` frontmatter line), when present. */
@@ -24,5 +24,73 @@ export declare function serializeEntryFile(entry: Pick<MemoryEntry, "id" | "fron
  * of incidental serialization formatting, or every materialize would see a phantom diff.
  */
 export declare function computeEntryRev(entry: Pick<MemoryEntry, "id" | "frontmatter" | "body">): string;
+/** 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-3) — the AMBIGUOUS origin-representation predicate, ONE law for
+ * every inbound boundary (backend patch law, sync wire, bundle validation, out-of-band adoption):
+ * 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).
+ *
+ * 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;
+/**
+ * design/336 §2.3-1 — the harvest-side STRIP of model-written origin bytes (typed field AND
+ * origin-form `extra` lines, a block header's indented continuation included). The origin seat is
+ * engine-authored in every mode: whatever a file on the model-writable plane says about its own
+ * origin is not evidence — the engine strips it and mints (or carries forward) its own judgment.
+ * Same family as the invalid-id "dropped, fresh one minted" exception to the round-trip law.
+ * MUTATES the given (already-copied) frontmatter; returns true ⇔ anything was stripped (the
+ * caller discloses via a report warning).
+ */
+export declare function stripModelWrittenOrigin(fm: MemoryEntryFrontmatter): boolean;
 /** Parse a file's text directly into a full MemoryEntry (id must already be present/decided). */
 export declare function entryFromFile(text: string, id: string, slug: string, scope: string): MemoryEntry;

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

@@ -1,9 +1,14 @@
 import { createHash } from "node:crypto";
+import { MEMORY_ORIGIN_CAUSES } from "./types.js";
 const FM_FENCE = "---";
 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) {
@@ -28,8 +33,12 @@ export function parseEntryFile(text) {
     const provRaw = [];
     const provUnknown = [];
     const prov = {};
+    let inOrigin = false;
+    const originRaw = [];
+    let originPristine = true;
+    const orig = {};
     for (let i = 1; i < end; i++) {
-        const line = lines[i];
+        const line = lines[i] ?? "";
         const trimmed = line.trim();
         if (trimmed === "")
             continue;
@@ -37,6 +46,7 @@ export function parseEntryFile(text) {
         if (!indented) {
             inMetadata = false;
             inProvenance = false;
+            inOrigin = false;
         }
         if (inMetadata) {
             const m = /^\s+type:\s*(.+?)\s*$/.exec(line);
@@ -72,11 +82,35 @@ export function parseEntryFile(text) {
             inMetadata = true;
             continue;
         }
+        if (inOrigin) {
+            originRaw.push(line);
+            const m = /^\s+([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/.exec(line);
+            if (m) {
+                const [, k = "", v = ""] = m;
+                if (k === "taint" && orig.taint === undefined)
+                    orig.taint = v;
+                else if (k === "cause" && orig.cause === undefined)
+                    orig.cause = v;
+                else if (k === "at" && orig.at === undefined)
+                    orig.at = ORIGIN_AT_RE.test(v) ? Number(v) : Number.NaN;
+                else
+                    originPristine = false;
+            }
+            else {
+                originPristine = false;
+            }
+            continue;
+        }
         if (/^provenance:\s*$/.test(trimmed)) {
             inProvenance = true;
             provRaw.push(line);
             continue;
         }
+        if (/^origin:\s*$/.test(trimmed) && originRaw.length === 0) {
+            inOrigin = true;
+            originRaw.push(line);
+            continue;
+        }
         const kv = /^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*?)\s*$/.exec(trimmed);
         if (!kv || indented) {
             extra.push(line);
@@ -126,6 +160,18 @@ export function parseEntryFile(text) {
             extra.push(...provRaw);
         }
     }
+    if (originRaw.length > 0) {
+        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 };
+        }
+        else {
+            extra.push(...originRaw);
+        }
+    }
     if (extra.length > 0)
         fm.extra = extra;
     let body = lines.slice(end + 1).join("\n");
@@ -151,26 +197,134 @@ export function serializeEntryFile(entry) {
         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}`);
+    }
     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]
             : []),
+        ...(canonicalOrigin !== undefined ? [["origin", canonicalOrigin.taint, canonicalOrigin.cause ?? null, canonicalOrigin.at]] : []),
     ]);
     return createHash("sha256").update(canonical, "utf8").digest("hex").slice(0, 16);
 }
+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));
+}
+export function extraOriginCarriers(extra) {
+    if (extra === undefined)
+        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) {
+        if (/^\s*origin\s*:\s*$/.test(line)) {
+            closeBlock();
+            block = {};
+            continue;
+        }
+        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;
+        }
+        closeBlock();
+        if (ORIGIN_FORM_LINE_RE.test(line))
+            carriers.push({ 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 };
+    return extraOriginCarriers(fm.extra)[0];
+}
+export function originEquals(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.taint === b.taint && a.cause === b.cause && a.at === b.at;
+}
+export function ambiguousOriginRepresentation(fm) {
+    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;
+    if (fm.origin !== undefined) {
+        delete fm.origin;
+        stripped = true;
+    }
+    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;
+        }
+    }
+    return stripped;
+}
 export function entryFromFile(text, id, slug, scope) {
     const parsed = parseEntryFile(text);
     const entry = { id, slug, frontmatter: parsed.frontmatter, body: parsed.body, rev: "", scope };

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

@@ -25,6 +25,23 @@ export interface V2HeaderHints {
     /** `applies-when: <free text>` — non-empty free text, trimmed. */
     appliesWhen?: string;
 }
+/**
+ * design/336 §4.1 — the MECHANICAL instruction-form predicate (deliberately zero semantic judgment:
+ * no model, no content heuristics — SOTA R4's LLM-judge ban). An entry is instruction-form ⇔
+ *  - `metadata.type === "feedback"` (the declared behavior-correction type), OR
+ *  - its v2 header hints declare an injection/trigger privilege: `pinned` / `triggers` /
+ *    `applies-when` (the three hints whose whole purpose is automatic or conditional injection;
+ *    `last-confirmed` is bookkeeping and does not count).
+ * Escape analysis: an entry that declares none of these rides the ordinary-entry row — where the
+ * origin-marker floor governs — so NOT declaring buys no privilege; declaring buys injection
+ * privilege AND walks through the exposure hard gate with it. ONE exported predicate on purpose:
+ * the write side (harvest hard gate) and any read-side consumer must judge through the same
+ * function, never through re-implementations that can drift.
+ */
+export declare function isInstructionEntry(fm: {
+    type?: string;
+    extra?: readonly string[];
+}): boolean;
 /** Read the v2 header hints out of an entry's preserved-verbatim `extra` lines. First well-formed
  *  occurrence of each key wins (duplicate lines are model bookkeeping noise, not a merge input). */
 export declare function readV2HeaderHints(extra: readonly string[] | undefined): V2HeaderHints;

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

@@ -1,5 +1,11 @@
 const LINE_RE = /^\s*([A-Za-z][A-Za-z0-9_-]*):\s*(.*?)\s*$/;
 const ISO_DATE_PREFIX_RE = /^\d{4}-\d{2}-\d{2}(?:$|[T\s])/;
+export function isInstructionEntry(fm) {
+    if (fm.type === "feedback")
+        return true;
+    const hints = readV2HeaderHints(fm.extra);
+    return hints.pinned !== undefined || hints.triggers !== undefined || hints.appliesWhen !== undefined;
+}
 export function readV2HeaderHints(extra) {
     const out = {};
     if (extra === undefined)

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

@@ -1,12 +1,14 @@
-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, type V2HeaderHints } from "./header-hints.js";
-export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile, type ParsedEntryFile } from "./frontmatter.js";
-export type { MemoryBackend, MemoryEntry, MemoryEntryFrontmatter, MemoryEntryHeader, ScoredMemoryEntry, NotePatch, PatchReport, MaterializedFile, MemorySessionHandle, HarvestReport, HarvestRejection, HarvestRejectionCode, MemoryAnnouncement, ScanFinding, } from "./types.js";
+export { readV2HeaderHints, isInstructionEntry, type V2HeaderHints } from "./header-hints.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";
 export { SCOPE_SEGMENT_MAX_ENCODED, PROJECT_MARKER_PATH, encodeScopeSegment, decodeScopeSegment, parseScopeKey, formatUserScope, formatOrgScope, formatProjScope, formatUserProjScope, isPersonalScope, assertScopeContractPlacement, formatProjectMarker, parseProjectMarker, resolveProjectId, PROJECT_ID_REGEX, type ParsedScopeKey, } from "./scope-contract.js";
 export { migrateScope, type MigrateScopeReport } from "./migrate.js";

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

@@ -1,11 +1,13 @@
-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 } from "./header-hints.js";
-export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile } from "./frontmatter.js";
+export { readV2HeaderHints, isInstructionEntry } from "./header-hints.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";
 export { migrateScope } from "./migrate.js";

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

@@ -1,4 +1,4 @@
-import type { MemoryAnnouncement } from "./types.js";
+import { type MemoryAnnouncement } from "./types.js";
 /** Cursor sidecar for the design/84 Seam B pair on the FileBackend (`{ [scope]: cursor }`). B3: control plane. */
 export declare const CURSORS_FILE = "cursors.json";
 /** The control-plane subdir name under a key dir — ONE spelling for every derivation and for the
@@ -285,6 +285,11 @@ export declare const SESSION_POLLUTION_DIR = "session-pollution";
 export interface SessionPollutionRecord {
     at: number;
     reason: string;
+    /** design/336 §2.2 — the structured mechanical cause of the exposure (the value an origin marker
+     *  minted off this record carries). ADDITIVE: records written before the field existed read as
+     *  honestly cause-less (the mint then falls back to `"observed"`); old readers narrow-take the
+     *  two fields they know. */
+    cause?: import("./types.js").MemoryOriginCause;
 }
 /**
  * Mark `sessionId` polluted (idempotent; the FIRST record wins — `wx` create refuses overwrite).
@@ -299,7 +304,7 @@ export interface SessionPollutionRecord {
  * stays polluted for this process either way).
  */
 export type SessionPollutionMarkOutcome = "created" | "existed" | "unpersisted";
-export declare function markSessionPolluted(controlDir: string, sessionId: string, reason: string, now: () => number): SessionPollutionMarkOutcome;
+export declare function markSessionPolluted(controlDir: string, sessionId: string, reason: string, now: () => number, cause?: import("./types.js").MemoryOriginCause): SessionPollutionMarkOutcome;
 /** Read the durable pollution record for `sessionId` (undefined = no marker).
  *  A marker that EXISTS still reads as polluted whether or not its bytes can be read or parsed
  *  (fail-closed: neither corruption nor an unreadable node may launder the state) — a synthesized
@@ -355,11 +360,30 @@ 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 {
     lastRev: string;
     lastAt: number;
+    /** design/336 — carried from the staged row at promotion: the contribution's content (at
+     *  `lastRev`) carries its external-origin marker, so the pollution retroaction sweeps owe it no
+     *  challenge (the account travels with the entry). Absence = unmarked content — the sweeps'
+     *  domain (older vintages read as unmarked, the conservative side). */
+    marked?: true;
 }
 /** One staged (pre-commit) row: an entry this transaction WOULD commit. `kind: "latch-only"` marks
  *  a bundle-import SYNTHETIC latch row (design/178 v2-c §1): it withholds the id on the model-visible
@@ -370,6 +394,12 @@ export interface LineagePendingRow {
     entryId: string;
     rev: string;
     kind?: "latch-only";
+    /** design/336 — set ⇔ the staged content CARRIES its external-origin marker (`frontmatter.origin`
+     *  in the very rev this row names): the exposure account travels WITH the entry, so promotion
+     *  settlement owes it no pollution challenge (challenging it would re-quarantine a tag-admission
+     *  at the read face). Absence = the row's content is unmarked (older vintages included) — the
+     *  conservative side: an unmarked row of a marked session is challenged. */
+    marked?: true;
 }
 /** One staged transaction: rows land BEFORE `applyPatches`; the commit credential lands after it
  *  succeeds; promotion consumes both. A pending txn without a credential is the crash window —
@@ -406,6 +436,10 @@ export interface LineagePromotion {
     entryId: string;
     sessionId: string;
     rev: string;
+    /** design/336 — carried through from {@link LineagePendingRow.marked}: the promoted content
+     *  already carries its external-origin marker, so promotion settlement skips the pollution
+     *  challenge for it. */
+    marked?: true;
 }
 /** Promote a CREDENTIALED pending transaction: rows named by the credential's applied set join the
  *  committed contribution set (deduped by (entryId, sessionId) — a repeat pair refreshes
@@ -473,6 +507,8 @@ export declare function lineageLatchedIds(controlDir: string): Set<string>;
 export declare function lineageContributionsOfSession(controlDir: string, sessionId: string): Array<{
     entryId: string;
     lastRev: string;
+    lastAt: number;
+    marked?: true;
 }>;
 /** design/178 v2-a §1.3 — the BY-ENTRY lineage account, from ONE parse of the ledger (the
  *  by-session read's transpose; the committed set is keyed by entryId, so the index is O(1) after
@@ -538,6 +574,7 @@ export declare function importLineageCommitted(controlDir: string, rows: Readonl
     sessionId: string;
     lastRev: string;
     lastAt: number;
+    marked?: true;
 }>): LineageImportDivergence[];
 /** Full-ledger read (tests / host observability). Throws on corruption. */
 export declare function readLineageRecord(controlDir: string): {

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

@@ -3,6 +3,7 @@ const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { MEMORY_ORIGIN_CAUSES } from "./types.js";
 const SCOPES_FILE = "scopes.json";
 export const CURSORS_FILE = "cursors.json";
 export const CONTROL_PLANE_DIR = ".engine";
@@ -734,11 +735,11 @@ export const SESSION_POLLUTION_DIR = "session-pollution";
 function pollutionPath(controlDir, sessionId) {
     return join(controlDir, SESSION_POLLUTION_DIR, `${encodeURIComponent(sessionId)}.json`);
 }
-export function markSessionPolluted(controlDir, sessionId, reason, now) {
+export function markSessionPolluted(controlDir, sessionId, reason, now, cause) {
     const path = pollutionPath(controlDir, sessionId);
     try {
         ensureDirExists(dirname(path));
-        const record = { at: now(), reason };
+        const record = { at: now(), reason, ...(cause !== undefined ? { cause } : {}) };
         writeFileSync(path, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
         return "created";
     }
@@ -764,8 +765,10 @@ export function readSessionPollution(controlDir, sessionId) {
         if (parsed !== null && typeof parsed === "object") {
             const at = parsed.at;
             const reason = parsed.reason;
+            const cause = parsed.cause;
+            const knownCause = typeof cause === "string" && MEMORY_ORIGIN_CAUSES.includes(cause) ? cause : undefined;
             if (typeof at === "number" && typeof reason === "string")
-                return { at, reason };
+                return { at, reason, ...(knownCause !== undefined ? { cause: knownCause } : {}) };
         }
     }
     catch {
@@ -804,7 +807,7 @@ export function importSessionPollution(controlDir, sessionId, record) {
     const path = pollutionPath(controlDir, sessionId);
     ensureDirExists(dirname(path));
     try {
-        writeFileSync(path, `${JSON.stringify({ at: record.at, reason: record.reason }, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+        writeFileSync(path, `${JSON.stringify({ at: record.at, reason: record.reason, ...(record.cause !== undefined ? { cause: record.cause } : {}) }, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
         return "written";
     }
     catch (err) {
@@ -891,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`;
@@ -931,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;
@@ -976,6 +979,8 @@ function coerceLineage(raw) {
             if (!row || typeof row !== "object" || typeof row.lastRev !== "string" || typeof row.lastAt !== "number") {
                 throw badShape(`committed[${JSON.stringify(entryId)}][${JSON.stringify(sid)}]`);
             }
+            if (row.marked !== undefined && row.marked !== true)
+                throw badShape(`committed[${JSON.stringify(entryId)}][${JSON.stringify(sid)}] marked`);
         }
     }
     for (const [txnId, t] of Object.entries(r.pending)) {
@@ -991,6 +996,8 @@ function coerceLineage(raw) {
                 throw badShape(`pending[${JSON.stringify(txnId)}] row`);
             if (p.kind !== undefined && p.kind !== "latch-only")
                 throw badShape(`pending[${JSON.stringify(txnId)}] row kind`);
+            if (p.marked !== undefined && p.marked !== true)
+                throw badShape(`pending[${JSON.stringify(txnId)}] row marked`);
         }
         if (txn.credential !== undefined) {
             const c = txn.credential;
@@ -1049,8 +1056,8 @@ export function promoteLineagePending(controlDir, txnId, now) {
             if (!applied.has(row.entryId))
                 continue;
             const sessions = (rec.committed[row.entryId] ??= Object.create(null));
-            sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at };
-            promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev });
+            sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}) };
+            promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev, ...(row.marked === true ? { marked: true } : {}) });
         }
         delete rec.pending[txnId];
         return { next: rec, result: promoted };
@@ -1075,8 +1082,8 @@ export function adjudicateLineagePending(controlDir, txnId, action, now) {
             if (applied !== undefined && !applied.has(row.entryId))
                 continue;
             const sessions = (rec.committed[row.entryId] ??= Object.create(null));
-            sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at };
-            promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev });
+            sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}) };
+            promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev, ...(row.marked === true ? { marked: true } : {}) });
         }
         delete rec.pending[txnId];
         return { next: rec, result: promoted };
@@ -1099,8 +1106,8 @@ export function reconcileLineage(controlDir, now) {
                     continue;
                 at ??= now();
                 const sessions = (rec.committed[row.entryId] ??= Object.create(null));
-                sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at };
-                promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev });
+                sessions[txn.sessionId] = { lastRev: row.rev, lastAt: at, ...(row.marked === true ? { marked: true } : {}) };
+                promoted.push({ entryId: row.entryId, sessionId: txn.sessionId, rev: row.rev, ...(row.marked === true ? { marked: true } : {}) });
             }
             delete rec.pending[txnId];
             changed = true;
@@ -1182,7 +1189,7 @@ export function lineageContributionsOfSession(controlDir, sessionId) {
     for (const [entryId, sessions] of Object.entries(rec.committed)) {
         const c = Object.prototype.hasOwnProperty.call(sessions, sessionId) ? sessions[sessionId] : undefined;
         if (c !== undefined)
-            out.push({ entryId, lastRev: c.lastRev });
+            out.push({ entryId, lastRev: c.lastRev, lastAt: c.lastAt, ...(c.marked === true ? { marked: true } : {}) });
     }
     return out;
 }
@@ -1262,12 +1269,18 @@ export function importLineageCommitted(controlDir, rows) {
             const sessions = (rec.committed[row.entryId] ??= Object.create(null));
             const standing = Object.prototype.hasOwnProperty.call(sessions, row.sessionId) ? sessions[row.sessionId] : undefined;
             if (standing === undefined || row.lastAt > standing.lastAt) {
-                sessions[row.sessionId] = { lastRev: row.lastRev, lastAt: row.lastAt };
+                sessions[row.sessionId] = { lastRev: row.lastRev, lastAt: row.lastAt, ...(row.marked === true ? { marked: true } : {}) };
                 changed = true;
                 continue;
             }
             if (row.lastAt === standing.lastAt && row.lastRev !== standing.lastRev) {
                 divergence.push({ entryId: row.entryId, sessionId: row.sessionId, kept: "destination" });
+                continue;
+            }
+            if (row.lastAt === standing.lastAt && row.lastRev === standing.lastRev && row.marked === true && standing.marked !== true) {
+                sessions[row.sessionId] = { ...standing, marked: true };
+                changed = true;
+                continue;
             }
         }
         return { ...(changed ? { next: rec } : {}), result: divergence };