@sema-agent/core 5.44.0 → 5.46.0

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

@@ -4,7 +4,7 @@ import { dirname, join, relative } from "node:path";
 import { jaccardDistance, termSet } from "../memory-vector.js";
 import { MAX_MEMORY_BYTES } from "../memory.js";
 import { inlineUntrusted } from "../untrusted-text.js";
-import { computeEntryRev, entryFromFile, isValidEntryId, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
+import { ambiguousOriginRepresentation, committedOriginOf, computeEntryRev, entryFromFile, isValidEntryId, originEquals, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
 import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, claimRootScope, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, stageImportLatch, writeAllSync, } from "./layout.js";
 import { screenInboundEntries } from "./data-plane.js";
 import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
@@ -540,6 +540,8 @@ export class FileMemoryEngineBackend {
     unboundRowsKnown = false;
     adoptionNoticeKeys = new Set();
     transfersAppendFault;
+    recoveryCommitProbe;
+    chainHealProbe;
     exportFaceProbe;
     deletedIdsDigest;
     inboundFindings = [];
@@ -735,11 +737,18 @@ export class FileMemoryEngineBackend {
         const tryMkdir = () => {
             try {
                 mkdirSync(this.controlPlaneRoot, { recursive: true });
+            }
+            catch (err) {
+                throw new ControlPlaneCorruptError(`memory control-plane root could not be created (${err.code ?? "io error"}) at ${this.controlPlaneRoot} — a lock-acquisition fault is not contention; deferring recovery/migration on it would be silent (fail-closed)`, { cause: err });
+            }
+            try {
                 mkdirSync(lockDir);
                 return true;
             }
-            catch {
-                return false;
+            catch (err) {
+                if (err.code === "EEXIST")
+                    return false;
+                throw new ControlPlaneCorruptError(`memory txn lock could not be created (${err.code ?? "io error"}) at ${lockDir} — a lock-acquisition fault is not contention; deferring recovery/migration on it would be silent (fail-closed)`, { cause: err });
             }
         };
         let acquired = tryMkdir();
@@ -748,7 +757,22 @@ export class FileMemoryEngineBackend {
             try {
                 mtimeMs = statSync(lockDir).mtimeMs;
             }
-            catch {
+            catch (err) {
+                if (err.code !== "ENOENT") {
+                    throw new ControlPlaneCorruptError(`memory txn lock state could not be probed (${err.code ?? "io error"}) at ${lockDir} — a probe failure is not contention (fail-closed)`, { cause: err });
+                }
+                let occupant;
+                try {
+                    occupant = lstatSync(lockDir);
+                }
+                catch (lerr) {
+                    if (lerr.code !== "ENOENT") {
+                        throw new ControlPlaneCorruptError(`memory txn lock re-probe failed (${lerr.code ?? "io error"}) at ${lockDir} — a probe failure is not contention (fail-closed)`, { cause: lerr });
+                    }
+                }
+                if (occupant !== undefined && !occupant.isDirectory()) {
+                    throw new ControlPlaneCorruptError(`memory txn lock path is occupied by an invalid node (a dangling symlink?) at ${lockDir} — not contention and not a release race; remove the occupant (fail-closed)`, { cause: err });
+                }
                 mtimeMs = undefined;
             }
             if (mtimeMs !== undefined && this.now() - mtimeMs > TXN_LOCK_STALE_MS) {
@@ -757,7 +781,10 @@ export class FileMemoryEngineBackend {
                     statSync(ownerPath);
                     tokenPresent = true;
                 }
-                catch {
+                catch (err) {
+                    if (err.code !== "ENOENT") {
+                        throw new ControlPlaneCorruptError(`memory txn lock owner token could not be probed (${err.code ?? "io error"}) at ${ownerPath} — a probe failure is not a mid-acquisition (fail-closed)`, { cause: err });
+                    }
                 }
                 if (tokenPresent) {
                     const tomb = join(this.controlPlaneRoot, `txn.lock.stale-${randomUUID()}`);
@@ -766,7 +793,10 @@ export class FileMemoryEngineBackend {
                         renameSync(lockDir, tomb);
                         stolen = true;
                     }
-                    catch {
+                    catch (err) {
+                        if (err.code !== "ENOENT") {
+                            throw new ControlPlaneCorruptError(`memory txn lock stale-steal rename failed (${err.code ?? "io error"}) at ${lockDir} — a rename fault is not a lost race (fail-closed)`, { cause: err });
+                        }
                     }
                     if (stolen) {
                         rmSync(tomb, { recursive: true, force: true });
@@ -819,7 +849,7 @@ export class FileMemoryEngineBackend {
         if (lock === undefined)
             return;
         try {
-            this.recoverJournal();
+            this.recoverJournal({ token: lock.token });
             this.migrateLockedIfNeeded(lock.token);
         }
         finally {
@@ -892,8 +922,10 @@ export class FileMemoryEngineBackend {
             fd = openSync(path, "wx", 0o600);
         }
         catch (err) {
-            if (err.code === "EEXIST")
+            if (err.code === "EEXIST") {
+                this.fsyncControlPlaneDir();
                 return;
+            }
             throw new ControlPlaneCorruptError(`evidence-chain degradation marker could not be created at ${path} (${err.code ?? "io error"}) — heal aborted, the chain is unchanged (fail-closed)`);
         }
         try {
@@ -903,11 +935,32 @@ export class FileMemoryEngineBackend {
         finally {
             closeSync(fd);
         }
+        this.fsyncControlPlaneDir();
         if (readControlFileOrAbsent(path, "evidence-chain degradation marker") === undefined) {
             throw new ControlPlaneCorruptError(`evidence-chain degradation marker vanished after its write at ${path} — heal aborted, the chain is unchanged (fail-closed)`);
         }
     }
-    readTransferChain() {
+    fsyncControlPlaneDir() {
+        if (process.platform === "win32")
+            return;
+        let dfd;
+        try {
+            dfd = openSync(this.controlPlaneRoot, "r");
+        }
+        catch (err) {
+            throw new ControlPlaneCorruptError(`evidence-chain degradation marker's directory could not be opened for fsync (${err.code ?? "io error"}) at ${this.controlPlaneRoot} — heal aborted, the chain is unchanged (fail-closed: an unproven marker must not authorize a truncation)`, { cause: err });
+        }
+        try {
+            fsyncSync(dfd);
+        }
+        catch (err) {
+            throw new ControlPlaneCorruptError(`evidence-chain degradation marker's directory entry could not be fsynced (${err.code ?? "io error"}) at ${this.controlPlaneRoot} — heal aborted, the chain is unchanged (fail-closed: an unproven marker must not authorize a truncation)`, { cause: err });
+        }
+        finally {
+            closeSync(dfd);
+        }
+    }
+    readTransferChain(fenceToken) {
         const path = join(this.controlPlaneRoot, TRANSFERS_FILE);
         const raw = readControlFileOrAbsent(path, "transfer evidence log");
         const out = [];
@@ -940,6 +993,8 @@ export class FileMemoryEngineBackend {
                     }
                 }
                 const outOfBand = !journalHasPendingEvidence;
+                if (fenceToken !== undefined)
+                    this.assertTxnLockOwnership(fenceToken);
                 let fragmentPath;
                 try {
                     ensureDirExists(join(this.controlPlaneRoot, QUARANTINE_DIR));
@@ -951,6 +1006,9 @@ export class FileMemoryEngineBackend {
                 }
                 if (outOfBand)
                     this.mintChainDegradedMarker(fragmentPath);
+                this.chainHealProbe?.();
+                if (fenceToken !== undefined)
+                    this.assertTxnLockOwnership(fenceToken);
                 try {
                     atomicWriteFileSync(path, lines.slice(0, i).join("\n") + (i > 0 ? "\n" : ""));
                 }
@@ -1110,21 +1168,22 @@ export class FileMemoryEngineBackend {
             closeSync(fd);
         }
     }
-    recoverJournal(opts = {}) {
-        if (opts.unlocked) {
+    recoverJournal(fence) {
+        if (fence.token === undefined) {
             if (this.txnInFlight())
                 return;
             const lock = this.tryAcquireTxnLockSync();
             if (lock === undefined)
                 return;
             try {
-                this.recoverJournal();
+                this.recoverJournal({ token: lock.token });
             }
             finally {
                 lock.release();
             }
             return;
         }
+        const fenceToken = fence.token;
         const jp = join(this.controlPlaneRoot, JOURNAL_FILE);
         const raw = readControlFileOrAbsent(jp, "transaction journal");
         if (raw !== undefined) {
@@ -1205,7 +1264,7 @@ export class FileMemoryEngineBackend {
                 if (hasV1)
                     throw new ControlPlaneCorruptError(`transaction journal carries transfers with a v1 snapshot (impossible form): ${jp}`);
                 if (journalEvs.size > 0) {
-                    for (const row of this.readTransferChain()) {
+                    for (const row of this.readTransferChain(fenceToken)) {
                         const j = journalEvs.get(row.ev);
                         if (j !== undefined && j !== row.canonical) {
                             throw new ControlPlaneCorruptError(`transaction journal event id ${JSON.stringify(row.ev)} collides with a DIFFERENT payload already on the evidence chain (fail-closed before redo): ${jp}`);
@@ -1242,7 +1301,7 @@ export class FileMemoryEngineBackend {
                         }
                     }
                     if (e.req !== undefined && !anchorRows.some((a) => a.req === e.req)) {
-                        chainAnchors ??= this.readTransferChain()
+                        chainAnchors ??= this.readTransferChain(fenceToken)
                             .map((r) => r.parsed)
                             .filter((p) => p.channel === "erasure-anchor" && p.origin === undefined);
                         const matching = chainAnchors.filter((p) => p.req === e.req);
@@ -1254,7 +1313,7 @@ export class FileMemoryEngineBackend {
                 }
                 const chainAnchorEvsByReq = new Map();
                 if (anchorRows.length > 0) {
-                    for (const p of (chainAnchors ??= this.readTransferChain()
+                    for (const p of (chainAnchors ??= this.readTransferChain(fenceToken)
                         .map((r) => r.parsed)
                         .filter((p) => p.channel === "erasure-anchor" && p.origin === undefined))) {
                         const set = chainAnchorEvsByReq.get(p.req) ?? new Set();
@@ -1332,6 +1391,7 @@ export class FileMemoryEngineBackend {
                     }
                 }
             }
+            this.assertTxnLockOwnership(fenceToken);
             for (const op of journal.ops) {
                 try {
                     if (op.kind === "write" && op.content !== undefined) {
@@ -1354,6 +1414,8 @@ export class FileMemoryEngineBackend {
                     throw new ControlPlaneCorruptError(`transaction journal replay failed on op kind=${op.kind} target=${JSON.stringify(op.target)} (${code ?? (err instanceof Error ? err.message : String(err))}) — the journal is kept at ${jp}; an I/O failure retries at the next construction, a persistent fault needs the explicit control-plane rebuild path`);
                 }
             }
+            this.recoveryCommitProbe?.();
+            this.assertTxnLockOwnership(fenceToken);
             if (hasV2) {
                 this.ledger = snapshotRows;
                 this.envelopeExtras = snapshotExtras;
@@ -1366,8 +1428,15 @@ export class FileMemoryEngineBackend {
                 this.persistedSchemaVersion = "v1";
                 this.persistLedgerV1(snapshotRows);
             }
-            rmSync(jp, { force: true });
+            if (typeof journal.txn === "string") {
+                this.closeJournalIfOurs(journal.txn);
+            }
+            else {
+                this.assertTxnLockOwnership(fenceToken);
+                rmSync(jp, { force: true });
+            }
         }
+        this.assertTxnLockOwnership(fenceToken);
         this.sweepStagedFiles();
     }
     txnInFlight() {
@@ -1452,6 +1521,9 @@ export class FileMemoryEngineBackend {
         if (first !== undefined) {
             return { path: relPath, code: first.code, reason: `inbound memory change blocked: ${first.reason} (quarantined)` };
         }
+        if (ambiguousOriginRepresentation(parseEntryFile(text).frontmatter)) {
+            return { path: relPath, code: "invalid", reason: `inbound memory change blocked: conflicting or duplicated origin representations (ambiguous external-origin marker; quarantined)` };
+        }
         return undefined;
     }
     readScope(scope, sync, probeOnly, lockToken) {
@@ -1628,17 +1700,28 @@ export class FileMemoryEngineBackend {
     whitewashInboundFinding(relPath, entry, containment) {
         const committedShadow = this.readCommittedShadow(entry.id);
         const committedFm = committedShadow !== undefined ? parseEntryFile(committedShadow).frontmatter : undefined;
-        if (committedFm?.provenance?.kind !== "repo_file")
+        if (committedFm === undefined)
             return undefined;
-        const stripsProvenance = entry.frontmatter.provenance === undefined;
-        const stripsTrust = committedFm.trust !== undefined && entry.frontmatter.trust === undefined;
-        if (!stripsProvenance && !stripsTrust)
-            return undefined;
-        return {
-            path: relPath,
-            code: "invalid",
-            reason: `inbound memory change blocked: repo_file provenance whitewash refused — the on-disk change drops ${stripsProvenance ? "provenance" : "trust"} from a repo-ingested entry ${containment === "restored" ? "(quarantined; committed content restored)" : "(quarantined)"}`,
-        };
+        if (committedFm.provenance?.kind === "repo_file") {
+            const stripsProvenance = entry.frontmatter.provenance === undefined;
+            const stripsTrust = committedFm.trust !== undefined && entry.frontmatter.trust === undefined;
+            if (stripsProvenance || stripsTrust) {
+                return {
+                    path: relPath,
+                    code: "invalid",
+                    reason: `inbound memory change blocked: repo_file provenance whitewash refused — the on-disk change drops ${stripsProvenance ? "provenance" : "trust"} from a repo-ingested entry ${containment === "restored" ? "(quarantined; committed content restored)" : "(quarantined)"}`,
+                };
+            }
+        }
+        const committedOrigin = committedOriginOf(committedFm);
+        if (committedOrigin !== undefined && !originEquals(committedOrigin, committedOriginOf(entry.frontmatter))) {
+            return {
+                path: relPath,
+                code: "invalid",
+                reason: `inbound memory change blocked: external-origin marker whitewash refused — the on-disk change strips or rewrites the origin marker of a marked entry ${containment === "restored" ? "(quarantined; committed content restored)" : "(quarantined)"}`,
+            };
+        }
+        return undefined;
     }
     adoptMoveCandidateLocked(rows, entry, absPath, slug, scope, relPath, text, committedRev, from, moveEvents, moveAnnouncements, adoptedExternal) {
         const census = this.censusProjectionsLocked();
@@ -1685,7 +1768,7 @@ export class FileMemoryEngineBackend {
         try {
             this.assertTxnLockOwnership(lock.token);
             this.ledger = undefined;
-            this.recoverJournal();
+            this.recoverJournal({ token: lock.token });
             this.migrateLockedIfNeeded(lock.token);
             return this.readScope(scope, true, false, lock.token);
         }
@@ -2177,7 +2260,7 @@ export class FileMemoryEngineBackend {
     async applyPatchesLocked(patches, lockToken) {
         this.assertTxnLockOwnership(lockToken);
         this.ledger = undefined;
-        this.recoverJournal();
+        this.recoverJournal({ token: lockToken });
         this.migrateLockedIfNeeded(lockToken);
         const rows = cloneRows(this.loadLedger());
         const report = { applied: [], conflicts: [] };
@@ -2291,6 +2374,14 @@ export class FileMemoryEngineBackend {
             report.conflicts.push({ op: patch.op, id: patch.id, reason: `invalid_slug_shape (slug ${JSON.stringify(patch.entry.slug)} is empty, absolute, or path-escaping — a projection must stay inside its scope dir)` });
             return;
         }
+        if (patch.op !== "delete" && patch.entry !== undefined && ambiguousOriginRepresentation(patch.entry.frontmatter)) {
+            report.conflicts.push({
+                op: patch.op,
+                id: patch.id,
+                reason: `external-origin marker representation conflict: the entry carries conflicting or duplicated origin representations (malformed patch refused)`,
+            });
+            return;
+        }
         if (patch.op === "add") {
             const entry = patch.entry;
             if (!entry) {
@@ -2299,6 +2390,19 @@ export class FileMemoryEngineBackend {
             }
             const locatedAnywhere = this.locateById(patch.id);
             const existingAnywhere = locatedAnywhere !== undefined && plannedDeletes.has(patch.id) ? undefined : locatedAnywhere;
+            if (locatedAnywhere !== undefined) {
+                const shadowText = this.readCommittedShadow(patch.id);
+                const committedFm = shadowText !== undefined ? parseEntryFile(shadowText).frontmatter : locatedAnywhere.entry.frontmatter;
+                const committedOrigin = committedOriginOf(committedFm);
+                if (committedOrigin !== undefined && !originEquals(committedOrigin, committedOriginOf(entry.frontmatter))) {
+                    report.conflicts.push({
+                        op: "add",
+                        id: patch.id,
+                        reason: `external-origin marker whitewash refused: the add strips or rewrites the origin marker of a marked entry (malformed patch refused)`,
+                    });
+                    return;
+                }
+            }
             if (patch.guard === "absent") {
                 if (existingAnywhere) {
                     const currentRev = rowsRev(rows, patch.id) ?? existingAnywhere.entry.rev;
@@ -2376,6 +2480,15 @@ export class FileMemoryEngineBackend {
                     return;
                 }
             }
+            const committedOrigin = committedOriginOf(committedFm);
+            if (committedOrigin !== undefined && !originEquals(committedOrigin, committedOriginOf(patch.entry.frontmatter))) {
+                report.conflicts.push({
+                    op: "update",
+                    id: patch.id,
+                    reason: `external-origin marker whitewash refused: the update strips or rewrites the origin marker of a marked entry (malformed patch refused)`,
+                });
+                return;
+            }
         }
         const currentRev = rowsRev(rows, patch.id) ?? found.entry.rev;
         if (patch.baseRev !== undefined && patch.baseRev !== currentRev) {
@@ -2447,10 +2560,10 @@ export class FileMemoryEngineBackend {
         try {
             this.assertTxnLockOwnership(lock.token);
             this.ledger = undefined;
-            this.recoverJournal();
+            this.recoverJournal({ token: lock.token });
             this.migrateLockedIfNeeded(lock.token);
             const rows = cloneRows(this.loadLedger());
-            const chain = this.readTransferChain();
+            const chain = this.readTransferChain(lock.token);
             const degraded = this.chainDegradedMarkerPresent();
             const custodyState = degraded ? "damaged" : "complete";
             const selectHash = erasureSelectHash(select);
@@ -3141,7 +3254,7 @@ export class FileMemoryEngineBackend {
         try {
             this.assertTxnLockOwnership(lock.token);
             this.ledger = undefined;
-            this.recoverJournal();
+            this.recoverJournal({ token: lock.token });
             const rows = this.loadLedger();
             if (this.persistedSchemaVersion !== "v2") {
                 throw erasureCodedError("memory export refused: the committed-rev ledger is still schema v1 (pre-binding) — the store migrates itself at its next write/read entry or checkControlPlane; an export never triggers the migration", FileMemoryEngineBackend.EXPORT_INCOMPLETE);
@@ -3187,9 +3300,9 @@ export class FileMemoryEngineBackend {
                 const lineage = [];
                 for (const [entryId, sessions] of Object.entries(lineageRec.committed)) {
                     for (const [sessionId, c] of Object.entries(sessions))
-                        lineage.push({ entryId, sessionId, lastRev: c.lastRev, lastAt: c.lastAt });
+                        lineage.push({ entryId, sessionId, lastRev: c.lastRev, lastAt: c.lastAt, ...(c.marked === true ? { marked: true } : {}) });
                 }
-                const pollutedSessions = Object.entries(polluted).map(([sessionId, r]) => ({ sessionId, at: r.at, reason: r.reason }));
+                const pollutedSessions = Object.entries(polluted).map(([sessionId, r]) => ({ sessionId, at: r.at, reason: r.reason, ...(r.cause !== undefined ? { cause: r.cause } : {}) }));
                 try {
                     this.assertTxnLockOwnership(lock.token);
                 }
@@ -3224,7 +3337,7 @@ export class FileMemoryEngineBackend {
         try {
             this.assertTxnLockOwnership(lock.token);
             this.ledger = undefined;
-            this.recoverJournal();
+            this.recoverJournal({ token: lock.token });
             const rows = this.loadLedger();
             if (this.persistedSchemaVersion !== "v2")
                 return { custody: [], unbound: [], complete: false, unsliceableCustody: 0, reason: "the committed-rev ledger is still schema v1 (migrate first)" };
@@ -3259,7 +3372,7 @@ export class FileMemoryEngineBackend {
         const lock = await this.acquireTxnLock(timings);
         try {
             this.assertTxnLockOwnership(lock.token);
-            this.recoverJournal();
+            this.recoverJournal({ token: lock.token });
             return this.custodyImportLocked(rows, opts);
         }
         finally {
@@ -3328,7 +3441,7 @@ export class FileMemoryEngineBackend {
         try {
             this.assertTxnLockOwnership(lock.token);
             this.ledger = undefined;
-            this.recoverJournal();
+            this.recoverJournal({ token: lock.token });
             this.migrateLockedIfNeeded(lock.token);
             const ctl = this.controlPlaneRoot;
             const txnId = importLatchTxnId(bundleHash);
@@ -3450,8 +3563,21 @@ export class FileMemoryEngineBackend {
             const orphanIds = new Set();
             const lineageToApply = [];
             for (const row of plan.lineage) {
-                if (eligible.has(row.entryId))
+                if (eligible.has(row.entryId)) {
+                    if (row.marked === true) {
+                        const shadow = this.readCommittedShadow(row.entryId);
+                        let committedFm = shadow !== undefined ? parseEntryFile(shadow).frontmatter : undefined;
+                        if (committedFm === undefined)
+                            committedFm = this.locateById(row.entryId)?.entry.frontmatter;
+                        if (committedFm !== undefined && committedOriginOf(committedFm) === undefined) {
+                            const { marked: _dropped, ...unmarked } = row;
+                            lineageToApply.push(unmarked);
+                            report.conflicts.push({ id: row.entryId, reason: `lineage row claims marked:true but the committed content carries no origin marker — the bit was dropped (the pollution sweep judges the contribution)` });
+                            continue;
+                        }
+                    }
                     lineageToApply.push(row);
+                }
                 else if (destKnown(row.entryId) || entryById.has(row.entryId))
                     withheldIds.add(row.entryId);
                 else
@@ -3476,14 +3602,14 @@ export class FileMemoryEngineBackend {
                 ...(c.challengedRev !== undefined ? { challengedRev: c.challengedRev } : {}),
             })));
             for (const p of [...plan.pollutedSessions].sort((a, b) => (a.sessionId < b.sessionId ? -1 : 1))) {
-                const contributions = lineageContributionsOfSession(ctl, p.sessionId);
+                const contributions = lineageContributionsOfSession(ctl, p.sessionId).filter((c) => c.marked !== true);
                 this.appendImportChallengesVerified(contributions.map((c) => ({
                     eventId: `imp-sweep:${bundleHash}:pollution:${p.sessionId}:${p.at}:${c.entryId}`,
                     entryId: c.entryId,
                     reason: `challenged: the contributing session was marked polluted`,
                     challengedRev: c.lastRev,
                 })));
-                const outcome = importSessionPollution(ctl, p.sessionId, { at: p.at, reason: p.reason });
+                const outcome = importSessionPollution(ctl, p.sessionId, { at: p.at, reason: p.reason, ...(p.cause !== undefined ? { cause: p.cause } : {}) });
                 if (outcome === "divergent")
                     report.pollutionDivergence.push({ sessionId: p.sessionId, kept: "destination" });
             }

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,46 @@ 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;
+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
+ * 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).
+ *
+ * ⚠ 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.
+ */
+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;