@sema-agent/core 5.21.0 → 5.22.0

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

@@ -6,7 +6,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { formatMemoryAge } from "../memory-recall.js";
 import { computeEntryRev, parseEntryFile, serializeEntryFile } from "./frontmatter.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./file-backend.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, readIndexRevs, writeIndexRevs, bumpScanFuse, canonicalize, claimRootScope, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, isContainedIn, markSessionPolluted, readSessionPollution, recordRetrievedAccount, writeFileNoFollow, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, resolveChallengeEvent, stageLineagePending, } from "./layout.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 export const MEMORY_INSTRUCTION_TEMPLATE = `# Memory
 
@@ -33,6 +33,7 @@ export function buildMemoryInstruction(memoryDir, instructionFileName) {
     return MEMORY_INSTRUCTION_TEMPLATE.replaceAll("{{MEMORY_DIR}}", dir).replaceAll("{{INSTRUCTION_FILE}}", instructionFileName ?? "CLAUDE.md");
 }
 export const MEMORY_RECALL_DISCIPLINE = "Before answering questions about earlier work, decisions, dates, people, or the user's preferences, look them up: `memory_search` finds entries by keyword and `memory_get` reads a full entry — the injected memory index only lists what exists. When a lookup comes up empty, say that you checked memory and found nothing instead of guessing.";
+export const MEMORY_PREFERENCE_DISCIPLINE = "When the user confirms a stored preference or fact still holds, refresh that entry's `last-confirmed: <YYYY-MM-DD>` frontmatter line (add it when absent). When you save a preference, add an `applies-when: <context>` frontmatter line naming when it applies. Both are plain frontmatter lines — write them yourself; nothing fills them in for you.";
 export const MEMORY_INDEX_MAX_LINES = 200;
 export const MEMORY_INDEX_MAX_BYTES = 25 * 1024;
 export const STUB_ARCHIVED_LINE = "[body archived — request hydration by listing the slug in memory/.hydrate]";
@@ -87,6 +88,8 @@ export class MemoryEngine {
         }
     }
     recordRetrieved(ids) {
+        for (const id of ids)
+            this.retrievedThisSession.add(id);
         try {
             recordRetrievedAccount(this.controlDir, ids, this.now);
         }
@@ -124,6 +127,28 @@ export class MemoryEngine {
                 }
             }
         }
+        try {
+            const rec = this.sessionPollution(sessionId) ?? { at: this.now(), reason };
+            const contributions = lineageContributionsOfSession(this.controlDir, sessionId);
+            this.challengeAndAnnounce(contributions.map((c) => ({
+                eventId: `pollution:${sessionId}:${rec.at}:${c.entryId}`,
+                entryId: c.entryId,
+                reason: `challenged: the contributing session was marked polluted`,
+                challengedRev: c.lastRev,
+            })));
+        }
+        catch (err) {
+            const sink = this.onIncident;
+            if (sink !== undefined) {
+                try {
+                    const e = new Error(`memory challenge sweep for a polluted session failed: ${err instanceof Error ? err.message : String(err)}`);
+                    e.code = "memory.challenge_sweep_failed";
+                    sink(e);
+                }
+                catch {
+                }
+            }
+        }
     }
     sessionPollution(sessionId) {
         const inProcess = this.pollutedSessions.get(sessionId);
@@ -136,6 +161,103 @@ export class MemoryEngine {
             return undefined;
         }
     }
+    retrievedThisSession = new Set();
+    readChallengeExclusions() {
+        const out = new Map();
+        for (const id of lineageLatchedIds(this.controlDir))
+            out.set(id, { code: "lineage_pending" });
+        for (const [id, g] of challengedEntryIds(this.controlDir))
+            out.set(id, { code: "challenged", generation: g.generation, at: g.at });
+        return out;
+    }
+    challengeAndAnnounce(events) {
+        if (events.length === 0)
+            return [];
+        const assigned = appendChallengeEvents(this.controlDir, events, this.now);
+        const fresh = assigned.filter((a) => !a.replayed);
+        if (fresh.length > 0) {
+            try {
+                enqueueMemoryAnnouncement(this.controlDir, {
+                    kind: "gate",
+                    at: this.now(),
+                    items: fresh.map((a) => `memory entry challenged: id ${quoteId(a.entryId)} (generation ${a.generation}) — its content is withheld from memory tools and the injected index. If the fact is still needed, verify it with the user, record a fresh entry from their current statement, and tombstone the old one.`),
+                });
+            }
+            catch (err) {
+                this.discloseAnnounceFailure("challenge enqueue", err);
+            }
+        }
+        return assigned;
+    }
+    challengeEntries(ids, reason, requestId) {
+        if (typeof requestId !== "string" || requestId === "") {
+            const e = new Error("challengeEntries: requestId is required (idempotency identity — retries must reuse it; the engine does not mint one)");
+            e.code = "config.memory_challenge_request";
+            throw e;
+        }
+        return this.challengeAndAnnounce(ids.map((entryId) => ({ eventId: `${requestId}:${entryId}`, entryId, reason })));
+    }
+    challengeSession(sessionId, reason, requestId) {
+        if (typeof requestId !== "string" || requestId === "") {
+            const e = new Error("challengeSession: requestId is required (idempotency identity — retries must reuse it; the engine does not mint one)");
+            e.code = "config.memory_challenge_request";
+            throw e;
+        }
+        const contributions = lineageContributionsOfSession(this.controlDir, sessionId);
+        return this.challengeAndAnnounce(contributions.map((c) => ({ eventId: `${requestId}:${c.entryId}`, entryId: c.entryId, reason, challengedRev: c.lastRev })));
+    }
+    resolveChallenge(entryId, generation, reason, requestId) {
+        return resolveChallengeEvent(this.controlDir, entryId, generation, reason, this.now, requestId);
+    }
+    adjudicatePendingLineage(txnId, action) {
+        const promoted = adjudicateLineagePending(this.controlDir, txnId, action, this.now);
+        this.settlePromotions(promoted);
+        return promoted;
+    }
+    listPendingLineage() {
+        return readLineageRecord(this.controlDir).pending;
+    }
+    readChallengeLedger() {
+        return readChallengeEvents(this.controlDir);
+    }
+    readChallengedHistoryAccount() {
+        try {
+            return readChallengedHistory(this.controlDir);
+        }
+        catch {
+            return {};
+        }
+    }
+    settlePromotions(promoted) {
+        if (promoted.length === 0)
+            return;
+        const events = [];
+        for (const p of promoted) {
+            let rec;
+            try {
+                rec = readSessionPollution(this.controlDir, p.sessionId);
+            }
+            catch {
+                rec = undefined;
+            }
+            if (rec === undefined)
+                rec = this.pollutedSessions.get(p.sessionId);
+            if (rec === undefined)
+                continue;
+            events.push({
+                eventId: `pollution:${p.sessionId}:${rec.at}:${p.entryId}`,
+                entryId: p.entryId,
+                reason: `challenged: the contributing session was marked polluted`,
+                challengedRev: p.rev,
+            });
+        }
+        this.challengeAndAnnounce(events);
+        try {
+            appendLineageAudit(this.controlDir, promoted.map((p) => ({ entryId: p.entryId, sessionId: p.sessionId, rev: p.rev, at: this.now() })));
+        }
+        catch {
+        }
+    }
     async materialize(scopes, writeScope) {
         ensureDirExists(this.memoryDir);
         ensureDirExists(this.controlDir);
@@ -316,7 +438,8 @@ export class MemoryEngine {
         return report;
     }
     async harvestCore(handle, opts) {
-        const pollutedReason = opts?.polluted?.reason;
+        let pollutedReason = opts?.polluted?.reason ?? (opts?.sessionId !== undefined ? this.sessionPollution(opts.sessionId)?.reason : undefined);
+        const lineageSessionId = opts?.sessionId;
         const startedAt = this.now();
         const report = {
             ok: true,
@@ -344,6 +467,30 @@ export class MemoryEngine {
             report.incident = { kind: "sidecar_corrupt", detail: `memory control plane refused: ${err instanceof Error ? err.message : String(err)}` };
             return report;
         }
+        try {
+            const rec = reconcileLineage(this.controlDir, this.now);
+            this.settlePromotions(rec.promoted);
+            for (const u of rec.undecidable) {
+                report.warnings.push(`memory lineage transaction ${u.txnId} is unsettled (a crash landed between commit and its durable credential) — ${u.entryIds.length} entr${u.entryIds.length === 1 ? "y is" : "ies are"} latched (memory reads refuse them) until the host adjudicates it (adjudicatePendingLineage)`);
+            }
+            if (pollutedReason !== undefined && lineageSessionId !== undefined) {
+                const rec2 = this.sessionPollution(lineageSessionId);
+                if (rec2 !== undefined) {
+                    const contributions = lineageContributionsOfSession(this.controlDir, lineageSessionId);
+                    this.challengeAndAnnounce(contributions.map((c) => ({
+                        eventId: `pollution:${lineageSessionId}:${rec2.at}:${c.entryId}`,
+                        entryId: c.entryId,
+                        reason: `challenged: the contributing session was marked polluted`,
+                        challengedRev: c.lastRev,
+                    })));
+                }
+            }
+        }
+        catch (err) {
+            report.ok = false;
+            report.incident = { kind: "sidecar_corrupt", detail: `memory lineage/challenge ledger refused: ${err instanceof Error ? err.message : String(err)}` };
+            return report;
+        }
         if (!existsSync(handle.writableRoot)) {
             report.ok = false;
             report.incident = { kind: "dir_missing", detail: `memory writable root is gone: ${handle.writableRoot}` };
@@ -693,13 +840,99 @@ export class MemoryEngine {
             patchReport = { applied: [], conflicts: [] };
         }
         else {
-            try {
-                patchReport = await this.backend.applyPatches(patches);
+            const txnId = uuidv7();
+            const pendingRows = patches.filter((p) => p.op !== "delete" && p.entry !== undefined).map((p) => ({ entryId: p.id, rev: p.entry.rev }));
+            const lineageArmed = lineageSessionId !== undefined && pendingRows.length > 0;
+            if (lineageArmed) {
+                try {
+                    stageLineagePending(this.controlDir, txnId, lineageSessionId, pendingRows, this.now);
+                }
+                catch (err) {
+                    report.ok = false;
+                    report.incident = { kind: "sidecar_corrupt", detail: `memory lineage write-ahead refused: ${err instanceof Error ? err.message : String(err)}` };
+                    return report;
+                }
             }
-            catch (err) {
-                report.ok = false;
-                report.incident = { kind: "sidecar_corrupt", detail: `memory commit refused: ${err instanceof Error ? err.message : String(err)}` };
-                return report;
+            const preCommit = lineageSessionId !== undefined ? this.sessionPollution(lineageSessionId) : undefined;
+            if (preCommit !== undefined) {
+                if (lineageArmed) {
+                    try {
+                        discardLineagePending(this.controlDir, txnId);
+                    }
+                    catch {
+                    }
+                }
+                pollutedReason = preCommit.reason;
+                for (const f of records)
+                    await containPollutedRecord(f);
+                patchReport = { applied: [], conflicts: [] };
+            }
+            else {
+                try {
+                    patchReport = await this.backend.applyPatches(patches);
+                }
+                catch (err) {
+                    if (lineageArmed) {
+                        try {
+                            discardLineagePending(this.controlDir, txnId);
+                        }
+                        catch {
+                        }
+                    }
+                    report.ok = false;
+                    report.incident = { kind: "sidecar_corrupt", detail: `memory commit refused: ${err instanceof Error ? err.message : String(err)}` };
+                    return report;
+                }
+                if (lineageArmed) {
+                    try {
+                        recordLineageCredential(this.controlDir, txnId, patchReport.applied.filter((a) => a.op !== "delete").map((a) => a.id), this.now);
+                        const promoted = promoteLineagePending(this.controlDir, txnId, this.now);
+                        this.settlePromotions(promoted);
+                    }
+                    catch (err) {
+                        const detail = `memory lineage settlement failed after commit — the affected entries stay latched (memory reads refuse them) until a later harvest reconciles or the host adjudicates: ${err instanceof Error ? err.message : String(err)}`;
+                        report.warnings.push(detail);
+                        const sink = this.onIncident;
+                        if (sink !== undefined) {
+                            try {
+                                const e = new Error(detail);
+                                e.code = "memory.lineage_settle_failed";
+                                sink(e);
+                            }
+                            catch {
+                            }
+                        }
+                    }
+                }
+                const deletedIds = patchReport.applied.filter((a) => a.op === "delete").map((a) => a.id);
+                if (deletedIds.length > 0) {
+                    try {
+                        clearLineageForEntries(this.controlDir, deletedIds);
+                    }
+                    catch {
+                    }
+                }
+                try {
+                    recordChallengedHistory(this.controlDir, patchReport.applied
+                        .filter((a) => (a.op === "update" || a.op === "delete") && this.retrievedThisSession.has(a.id))
+                        .map((a) => ({ entryId: a.id, op: a.op === "delete" ? "tombstone" : "update" })), this.now);
+                }
+                catch {
+                }
+                const postCommit = lineageSessionId !== undefined ? this.sessionPollution(lineageSessionId) : undefined;
+                if (postCommit !== undefined) {
+                    const appliedNonDelete = patchReport.applied.filter((a) => a.op !== "delete").map((a) => a.id);
+                    try {
+                        this.challengeAndAnnounce(appliedNonDelete.map((id) => ({
+                            eventId: `pollution:${lineageSessionId}:${postCommit.at}:${id}`,
+                            entryId: id,
+                            reason: `challenged: the contributing session was marked polluted`,
+                        })));
+                    }
+                    catch (err) {
+                        report.warnings.push(`memory challenge of this harvest's commits failed (session polluted post-commit): ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
             }
         }
         const appliedIds = new Set(patchReport.applied.filter((a) => a.op !== "delete").map((a) => a.id));
@@ -798,18 +1031,39 @@ export class MemoryEngine {
     }
     rebuildIndex(handle, headers, opts, warnings) {
         const indexPath = join(handle.writableRoot, MEMORY_INDEX_FILENAME);
+        let excludedIds;
+        try {
+            excludedIds = this.readChallengeExclusions();
+        }
+        catch (err) {
+            const detail = `memory index withheld: the challenge/lineage ledger cannot be trusted (${err instanceof Error ? err.message : String(err)}) — fail-closed, nothing injected`;
+            warnings?.push(detail);
+            handle.indexOnDiskUntrusted = true;
+            const sink = this.onIncident;
+            if (sink !== undefined) {
+                try {
+                    const e = new Error(detail);
+                    e.code = "memory.challenge_ledger_corrupt";
+                    sink(e);
+                }
+                catch {
+                }
+            }
+            return "";
+        }
         const existing = opts.ignoreOnDisk === true ? "" : (readNoFollowSafe(indexPath) ?? "");
         const indexRevs = readIndexRevs(this.controlDir);
         const nextIndexRevs = {};
         const expected = new Map();
+        const excludedTargets = new Set();
         for (const h of headers) {
             const repoTarget = handle.repoIndexTargets?.get(h.id);
-            if (repoTarget !== undefined) {
-                expected.set(repoTarget, h);
+            const target = repoTarget ?? relative(handle.writableRoot, canonicalize(join(scopeDirFor(this.memoryDir, this.controlDir, h.scope), `${h.slug}.md`)));
+            if (excludedIds.has(h.id)) {
+                excludedTargets.add(target);
                 continue;
             }
-            const file = join(scopeDirFor(this.memoryDir, this.controlDir, h.scope), `${h.slug}.md`);
-            expected.set(relative(handle.writableRoot, canonicalize(file)), h);
+            expected.set(target, h);
         }
         const covered = new Set();
         const keptByTarget = new Map();
@@ -821,6 +1075,10 @@ export class MemoryEngine {
                     keptLines.push(line);
                 continue;
             }
+            if (excludedTargets.has(target)) {
+                warnings?.push(`MEMORY.md index line removed: ${target} is withheld (challenged or unsettled) — its content stays off the injected index`);
+                continue;
+            }
             if (covered.has(target)) {
                 if (line === keptByTarget.get(target))
                     continue;

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

@@ -0,0 +1,30 @@
+/**
+ * design/180 裁决 C — the v2 header hints, read-only, over `frontmatter.extra`.
+ *
+ * The v2 header fields (pinned / triggers / last-confirmed / applies-when) are DELIBERATELY not
+ * typed structure positions: the parser's closed grammar keeps unknown lines VERBATIM in `extra`,
+ * `extra` participates in the entry rev, and the sync wire carries it — so a file with these lines
+ * computes the SAME rev on every client vintage (old and new), and no backend/sync twin owes an
+ * upgrade. Promoting them to typed fields would make the same bytes hash to two different revs
+ * across a mixed fleet (the provenance note in frontmatter.ts names that exact incident shape).
+ *
+ * This accessor is the ONLY consumer-side reading: pure, lenient, and closed over bad values —
+ * a malformed line reads as FIELD ABSENT, never an error and never a partial adoption. Nothing in
+ * the engine writes these lines; the model does (the preference-discipline paragraph teaches it),
+ * because an engine-written confirmation would forge the usage evidence it is supposed to record.
+ */
+/** The parsed v2 hints. Every field is absent unless a well-formed line was found. */
+export interface V2HeaderHints {
+    /** `pinned: true` — only the exact literal counts (anything else = absent). */
+    pinned?: boolean;
+    /** `triggers: a, b, c` — comma-split, trimmed, empties dropped; an empty result = absent. */
+    triggers?: string[];
+    /** `last-confirmed: YYYY-MM-DD…` — kept as the raw string when it starts with an ISO-date shape;
+     *  anything else = absent (bad values must not masquerade as confirmations). */
+    lastConfirmedAt?: string;
+    /** `applies-when: <free text>` — non-empty free text, trimmed. */
+    appliesWhen?: string;
+}
+/** 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

@@ -0,0 +1,41 @@
+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 readV2HeaderHints(extra) {
+    const out = {};
+    if (extra === undefined)
+        return out;
+    for (const line of extra) {
+        const m = LINE_RE.exec(line);
+        if (m === null)
+            continue;
+        const [, key, value] = m;
+        switch (key) {
+            case "pinned":
+                if (out.pinned === undefined && value === "true")
+                    out.pinned = true;
+                break;
+            case "triggers": {
+                if (out.triggers !== undefined)
+                    break;
+                const items = value
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter((s) => s !== "");
+                if (items.length > 0)
+                    out.triggers = items;
+                break;
+            }
+            case "last-confirmed":
+                if (out.lastConfirmedAt === undefined && ISO_DATE_PREFIX_RE.test(value))
+                    out.lastConfirmedAt = value;
+                break;
+            case "applies-when":
+                if (out.appliesWhen === undefined && value !== "")
+                    out.appliesWhen = value;
+                break;
+            default:
+                break;
+        }
+    }
+    return out;
+}

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

@@ -1,8 +1,9 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, 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, } from "./engine.js";
+export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, MEMORY_PREFERENCE_DISCIPLINE, 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, } 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 { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH, type ScannedEntryFile } from "./file-backend.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, } from "./layout.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, 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 { memoryBackendContract, assertMemoryBackendSearchEquivalence, type MemoryBackendContractHooks, } from "./memory-backend-contract.js";

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

@@ -1,8 +1,9 @@
-export { MemoryEngine, buildMemoryInstruction, truncateIndex, MEMORY_INSTRUCTION_TEMPLATE, MEMORY_RECALL_DISCIPLINE, 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, MEMORY_PREFERENCE_DISCIPLINE, 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 { scanMemoryWrite, scanMemoryFileName, scanRemediation, MEMORY_FILENAME_SEGMENT_RE } from "./scan.js";
 export { FileMemoryEngineBackend, scanEntryFiles, MEMORY_INDEX_FILENAME, DEFAULT_MAX_ENTRY_DEPTH } from "./file-backend.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, } from "./layout.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, } from "./layout.js";
+export { readV2HeaderHints } from "./header-hints.js";
 export { parseEntryFile, serializeEntryFile, computeEntryRev, entryFromFile } from "./frontmatter.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

@@ -273,6 +273,172 @@ export declare function recordRetrievedAccount(controlDir: string, ids: readonly
 export declare function readRetrievedAccount(controlDir: string): Record<string, RetrievedAccountRow>;
 /** S2-C — clear the fuse for files harvest just ACCEPTED (a committed write resets the strike count). */
 export declare function clearScanFuse(controlDir: string, keys: Iterable<string>): void;
+/** The write-ahead harvest lineage ledger (control plane, fail-closed). */
+export declare const LINEAGE_FILE = "lineage.json";
+/** The challenge generation-event ledger (control plane, fail-closed). */
+export declare const CHALLENGES_FILE = "challenges.json";
+/** Per-commit lineage AUDIT history (bookkeeping, fail-open, bounded rotation) — the load-bearing
+ *  queries never read it; it exists so the deduped contribution set is not the only trace. */
+export declare const LINEAGE_AUDIT_FILE = "lineage-audit.json";
+/** Bound on retained audit rows (oldest rotated out first). */
+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";
+/** 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;
+}
+/** One staged (pre-commit) row: an entry this transaction WOULD commit. */
+export interface LineagePendingRow {
+    entryId: string;
+    rev: string;
+}
+/** 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 —
+ *  it is NEVER auto-discarded (design/180 r5: the applyPatches-success→credential-write gap is
+ *  undecidable on the pinned backend contract; the host adjudicates via the explicit API). */
+export interface LineagePendingTxn {
+    sessionId: string;
+    at: number;
+    rows: LineagePendingRow[];
+    /** Present ⇔ `applyPatches` returned and its applied set was durably recorded. */
+    credential?: {
+        appliedIds: string[];
+        at: number;
+    };
+}
+/** Stage this transaction's would-commit rows BEFORE `applyPatches` (write-ahead). Throws on any
+ *  write/lock/corruption failure — the caller refuses the whole harvest (fail-closed). */
+export declare function stageLineagePending(controlDir: string, txnId: string, sessionId: string, rows: readonly LineagePendingRow[], now: () => number): void;
+/** Discard a staged transaction that never reached `applyPatches` (the pre-commit abort path —
+ *  step ③ of the handshake, or a refused commit). Safe by construction: nothing was committed. */
+export declare function discardLineagePending(controlDir: string, txnId: string): void;
+/** Record the commit credential — `applyPatches` returned, these ids were APPLIED (non-delete ops).
+ *  Written before promotion so a crash between the two converges by credential, never by reading
+ *  the backend's current state back (design/180 r4: later syncs/updates rewrite that scene). */
+export declare function recordLineageCredential(controlDir: string, txnId: string, appliedIds: readonly string[], now: () => number): void;
+/** What one promotion moved into the committed set. */
+export interface LineagePromotion {
+    entryId: string;
+    sessionId: string;
+    rev: string;
+}
+/** 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
+ *  lastRev/lastAt, never grows the set); rows NOT in the applied set (conflicted/refused ops) are
+ *  dropped without ever becoming ancestry. Throws when the txn is unknown or uncredentialed. */
+export declare function promoteLineagePending(controlDir: string, txnId: string, now: () => number): LineagePromotion[];
+/** The host adjudication for the UNDECIDABLE crash window (a pending txn with no credential —
+ *  design/180 r5: never auto-discarded). `"promote"` = the host verified the commit landed (all
+ *  staged rows join the committed set); `"discard"` = the host verified it did not. Idempotent on
+ *  an unknown txn. Also accepts a credentialed txn (then `"promote"` follows the credential). */
+export declare function adjudicateLineagePending(controlDir: string, txnId: string, action: "promote" | "discard", now: () => number): LineagePromotion[];
+/** Reconciliation (harvest-opening / host-triggered): promote every CREDENTIALED orphan pending
+ *  txn; report the uncredentialed ones (their latch stays until the host adjudicates). */
+export declare function reconcileLineage(controlDir: string, now: () => number): {
+    promoted: LineagePromotion[];
+    undecidable: Array<{
+        txnId: string;
+        sessionId: string;
+        entryIds: string[];
+    }>;
+};
+/** The DIRTY-LATCH set: every entry id named by ANY pending row (credentialed or not). While an id
+ *  is latched, its model-visible read faces (index mechanical rows / memory_search / memory_get)
+ *  refuse — "the account is not settled, the content does not go on the table". Throws on a
+ *  corrupt ledger (integrity unknown ≠ no latch). */
+export declare function lineageLatchedIds(controlDir: string): Set<string>;
+/** Every committed contribution of `sessionId` (the pollution-retroaction sweep input). Throws on
+ *  a corrupt ledger. */
+export declare function lineageContributionsOfSession(controlDir: string, sessionId: string): Array<{
+    entryId: string;
+    lastRev: string;
+}>;
+/** Drop an entry's lineage rows once the entry is DELETED (an applied tombstone) — space hygiene
+ *  only, taken at the harvest that saw the applied delete (design/180 §10). */
+export declare function clearLineageForEntries(controlDir: string, entryIds: readonly string[]): void;
+/** Full-ledger read (tests / host observability). Throws on corruption. */
+export declare function readLineageRecord(controlDir: string): {
+    committed: Record<string, Record<string, LineageContribution>>;
+    pending: Record<string, LineagePendingTxn>;
+};
+/** Fail-open per-commit AUDIT history (bounded rotation) — never consulted by the load-bearing
+ *  queries; a broken audit account degrades silently, exactly like the retrieved account. */
+export declare function appendLineageAudit(controlDir: string, rows: ReadonlyArray<{
+    entryId: string;
+    sessionId: string;
+    rev: string;
+    at: number;
+}>): void;
+/** One challenge/resolve event. Append-only; the exclusion predicate is DERIVED ("any unresolved
+ *  challenge generation exists"), never stored as a mutable flag. */
+export interface ChallengeEvent {
+    /** Stable identity for idempotent replay: the automatic arm derives it from the pollution event
+     *  anchor (`pollution:<sessionId>:<markedAt>:<entryId>`); the host arm derives it from the
+     *  caller's requestId (`<requestId>:<entryId>`). Same eventId replayed = same generation (a lost
+     *  ack retried never opens a second generation); a DIFFERENT eventId with the same reason is a
+     *  genuinely new event and opens a new generation (no immunity hole). */
+    eventId: string;
+    entryId: string;
+    kind: "challenge" | "resolve";
+    /** The generation this event opened (challenge) or closed (resolve). */
+    generation: number;
+    at: number;
+    reason: string;
+    /** Evidence grade — v2 mints only "S" (structural) events. */
+    grade?: "S";
+    /** Audit record only (the exclusion predicate keys the entry ID, never the rev). */
+    challengedRev?: string;
+}
+/** One challenge assignment {@link appendChallengeEvents} returns. `replayed` = the eventId already
+ *  existed (idempotent retry — the ORIGINAL generation is returned, no new one opens). */
+export interface ChallengeAssignment {
+    entryId: string;
+    eventId: string;
+    generation: number;
+    at: number;
+    replayed: boolean;
+}
+/** Append S-grade challenge events (idempotent per eventId, generation allocation inside the strict
+ *  lock). Every NEW eventId opens a NEW generation for its entry — a resolve of an earlier
+ *  generation never immunizes the entry against later pollution (design/180 R-8). */
+export declare function appendChallengeEvents(controlDir: string, events: ReadonlyArray<{
+    eventId: string;
+    entryId: string;
+    reason: string;
+    challengedRev?: string;
+}>, now: () => number): ChallengeAssignment[];
+/** The trusted resolve: closes EXACTLY the named generation (a later challenge's generation stays
+ *  open — resolves never blanket-clear). Idempotent: resolving an already-resolved generation is a
+ *  no-op. Returns false ⇔ no such open generation existed. */
+export declare function resolveChallengeEvent(controlDir: string, entryId: string, generation: number, reason: string, now: () => number, requestId?: string): boolean;
+/** The exclusion predicate's input: entry id → its LATEST unresolved challenge generation. An entry
+ *  appears iff at least one challenge generation has no matching resolve. Throws on corruption —
+ *  consumers refuse service (integrity unknown ≠ clean). */
+export declare function challengedEntryIds(controlDir: string): Map<string, {
+    generation: number;
+    at: number;
+}>;
+/** Full event read (host audit / tests). Throws on corruption. */
+export declare function readChallengeEvents(controlDir: string): ChallengeEvent[];
+/** One challenged-history row: how often a retrieved-then-corrected event hit this entry. */
+export interface ChallengedHistoryRow {
+    count: number;
+    lastAt: number;
+    lastOp: "update" | "tombstone";
+}
+/** Record mechanical correction shadows (same-session retrieved → update/tombstone committed).
+ *  Collect-only by contract: NOTHING in the engine reads this back into any decision (v3 candidate
+ *  evidence only — design/178 ③-1 三级账 discipline). Throws propagate; callers treat fail-open. */
+export declare function recordChallengedHistory(controlDir: string, rows: ReadonlyArray<{
+    entryId: string;
+    op: "update" | "tombstone";
+}>, now: () => number): void;
+/** Journal-aware read (observability/tests only — no engine consumer exists, on purpose). */
+export declare function readChallengedHistory(controlDir: string): Record<string, ChallengedHistoryRow>;
 /**
  * REF-C6 — write EVERY byte of `data` to `fd`, looping until the OS has taken all of them.
  *