renor-engine 0.0.0-stage → 1.0.0

package/dist/memory/lifecycle.js

@@ -0,0 +1,1756 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LegacyIdentityAmbiguityError = exports.LifecycleInputError = exports.FIELD_LIMITS = exports.DEFAULT_LEDGER_REL = exports.LIFECYCLE_NOTE_PATH = void 0;
+exports.resolveLedgerPath = resolveLedgerPath;
+exports.appendLedgerEvent = appendLedgerEvent;
+exports.unterminatedFinalEventStart = unterminatedFinalEventStart;
+exports.parseLedgerEvents = parseLedgerEvents;
+exports.replayLedger = replayLedger;
+exports.remember = remember;
+exports.factEventId = factEventId;
+exports.retireFact = retireFact;
+exports.restoreFact = restoreFact;
+exports.listRetiredFacts = listRetiredFacts;
+exports.scopeFilterFor = scopeFilterFor;
+exports.listLifecycleSubjects = listLifecycleSubjects;
+exports.factsFor = factsFor;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const entityLookup_1 = require("../retrieval/entityLookup");
+const queryHelpers_1 = require("../retrieval/queryHelpers");
+const scope_1 = require("../mvp/scope");
+const readCache_1 = require("../db/readCache");
+const statements_1 = require("../db/statements");
+const factTerms_1 = require("./factTerms");
+const limits_1 = require("./limits");
+const confinedWrite_1 = require("./confinedWrite");
+const invisibleText_1 = require("./invisibleText");
+const sourceName_1 = require("./sourceName");
+const writerConflicts_1 = require("./writerConflicts");
+const durableAppend_1 = require("./durableAppend");
+const secretGuard_1 = require("../extraction/secretGuard");
+const toolRefusal_1 = require("../toolRefusal");
+/** Reserved synthetic note path owning lifecycle entities (never a real vault file). */
+exports.LIFECYCLE_NOTE_PATH = '_mcp_';
+/** Default relative ledger path inside the vault. */
+exports.DEFAULT_LEDGER_REL = 'System/Memory Events Ledger.md';
+const EVENT_ID_RE = /^mem_[A-Za-z0-9]+$/i;
+const EVENT_HEADER_RE = /^## (mem_[A-Za-z0-9]+) · (.+?)[ \t]*$/i;
+// A field value is the rest of its physical line, and lines are split on '\n' alone. dotAll, because
+// `.` otherwise refuses U+2028/U+2029 (and a lone \r), which JavaScript calls line terminators and this
+// ledger does not: one such character in a value used to make the whole ledger unreadable at startup.
+const FIELD_RE = /^- ([A-Za-z][\w-]*): (.*)$/s;
+const KNOWN_FIELDS = new Set(['kind', 'subject', 'predicate', 'object', 'closed_event', 'source', 'scope', 'statement', 'writer', 'target']);
+const REQUIRED_FIELDS = ['subject', 'predicate', 'object'];
+/**
+ * retire takes one fact out of recall and restore brings it back (retireFact, restoreFact). Each names the fact's own
+ * event as its target and repeats its subject and predicate so the ledger reads on its own, but never its value: the
+ * value is in the target event already, and a second copy would be one more place a value someone asked to forget
+ * is written.
+ */
+const RETIREMENT_KINDS = new Set(['retire', 'restore']);
+const KNOWN_KINDS = new Set(['store', 'supersede', ...RETIREMENT_KINDS]);
+const CONTROL_CHARS = /[\u0000-\u001F\u007F]/;
+exports.FIELD_LIMITS = { subject: 512, predicate: 256, object: 8192, source: 256, scope: 80, statement: limits_1.MAX_STATEMENT_LENGTH, writer: 256 };
+/**
+ * Characters JSON.stringify leaves literal although a line-oriented reader may read them as a line
+ * end or a control: DEL, the C1 controls (U+0085 NEXT LINE among them), U+2028 LINE SEPARATOR and
+ * U+2029 PARAGRAPH SEPARATOR. JSON itself already escapes every C0 control and any unpaired surrogate.
+ */
+const JSON_LEAVES_LITERAL = /[\p{Cc}\p{Zl}\p{Zp}]/gu;
+/**
+ * The user's statement is free text (newlines, '## mem_…', '- key: …' lines), and the ledger is
+ * line-framed, so it is written as ONE JSON string literal and nothing else. The value starts with a
+ * quote, so no statement can open a heading or a field line; between the quotes there is no control
+ * character and no line or paragraph separator, so it is one line to every reader (this parser, an
+ * editor, a script that splits on Unicode line rules). Every escape is plain JSON, so any JSON parser
+ * reads the value back exactly, while text in any script stays readable and searchable as written.
+ */
+function encodeStatement(statement) {
+    return JSON.stringify(statement)
+        .replace(JSON_LEAVES_LITERAL, ch => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+/**
+ * Strict on purpose: anything that is not exactly one JSON string literal is corruption. JSON allows
+ * the separators the encoder now escapes to appear literal inside the quotes, so a ledger written
+ * before they were escaped still reads back exactly.
+ */
+function decodeStatement(raw, id) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        value = undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`ledger corruption in event ${id}: statement is not a JSON string literal`);
+    }
+    return value;
+}
+function newEventId() {
+    const t = Date.now().toString(36);
+    const r = Math.random().toString(36).slice(2, 8);
+    return `mem_${t}${r}`.toUpperCase();
+}
+/**
+ * A lifecycle field value was rejected by validation.
+ *
+ * On the write path every field is validated before the ledger is touched, so this class means
+ * "the request was wrong", never "the process is unhealthy": a caller-side type/length/character
+ * error must be answered 4xx by an HTTP surface, not 500. Reporting it as 500 misclassifies a
+ * client bug as a server fault and pages whoever watches the error budget for a request nobody
+ * can fix. Genuine engine faults — an unreadable ledger, a reused event id, a clock regression,
+ * a ledger path that escapes the vault — keep throwing plain Errors and stay 5xx.
+ *
+ * The message text is unchanged except for naming the received type, so log greps and existing
+ * assertions still match; only the class carries the new distinction.
+ */
+class LifecycleInputError extends Error {
+    field;
+    /**
+     * The refusal code telemetry carries, from the closed set in src/toolRefusal.ts, is recorded out of band
+     * (markErrorReason): the class gains no field, so its class, `name`, `message`, enumerable keys and
+     * `instanceof` are exactly what they were before. The third argument is optional, so an error built
+     * elsewhere keeps its two-argument shape.
+     */
+    constructor(field, message, reason) {
+        super(message);
+        this.name = 'LifecycleInputError';
+        this.field = field;
+        if (reason !== undefined)
+            (0, toolRefusal_1.markErrorReason)(this, reason);
+    }
+}
+exports.LifecycleInputError = LifecycleInputError;
+/** The received type, spelled the way JSON Schema spells it, for error messages. */
+function describeType(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function validateField(field, value, required) {
+    if (typeof value !== 'string')
+        throw new LifecycleInputError(field, `lifecycle ${field} must be a string (received ${describeType(value)})`, 'invalid_argument');
+    if (required && value.trim() === '')
+        throw new LifecycleInputError(field, `lifecycle ${field} must be a non-empty string`, 'invalid_argument');
+    if (CONTROL_CHARS.test(value)) {
+        throw new LifecycleInputError(field, `lifecycle ${field} contains control characters (newlines/tabs are rejected to keep ledger framing strict): ${JSON.stringify(value.slice(0, 40))}`, 'invalid_text');
+    }
+    const limit = exports.FIELD_LIMITS[field];
+    if (limit !== undefined && value.length > limit) {
+        throw new LifecycleInputError(field, `lifecycle ${field} exceeds the maximum length of ${limit} (got ${value.length})`, 'field_too_long');
+    }
+    return value;
+}
+function validateLifecycleInput(args) {
+    validateField('subject', args.subject, true);
+    validateField('predicate', args.predicate, true);
+    validateField('object', args.object, true);
+    if (args.source !== undefined)
+        validateField('source', args.source, false);
+    if (args.statement !== undefined) {
+        // The user's own words are kept as given, so unlike the structured fields they may hold control
+        // characters (the encoding makes them safe); only the type and the size are checked. The encoding
+        // is the reason the control-character rule in memory/controls.ts does not apply here: a statement
+        // is written as ONE JSON string literal, so every C0 control is escaped on disk and no statement
+        // can break the ledger's framing — while the note writer, which stores text raw, does refuse them.
+        if (typeof args.statement !== 'string')
+            throw new LifecycleInputError('statement', `lifecycle statement must be a string (received ${describeType(args.statement)})`, 'invalid_argument');
+        const limit = exports.FIELD_LIMITS.statement;
+        if (args.statement.length > limit)
+            throw new LifecycleInputError('statement', `lifecycle statement exceeds the maximum length of ${limit} (got ${args.statement.length})`, 'field_too_long');
+    }
+    if (args.scope !== undefined) {
+        // Normalize throws on invalid; re-label it as the caller error it is, so every rejection
+        // from this function leaves as a LifecycleInputError and an HTTP surface can answer 4xx.
+        // Also bound via FIELD_LIMITS via validateField on the normalized form.
+        let n;
+        try {
+            n = (0, scope_1.normalizeScope)(args.scope);
+        }
+        catch (err) {
+            // normalizeScope names invalid_scope itself (src/mvp/scope.ts); the re-label keeps that code.
+            throw new LifecycleInputError('scope', err instanceof Error ? err.message : String(err), (0, toolRefusal_1.refusalReason)(err) ?? 'invalid_scope');
+        }
+        validateField('scope', n, false);
+    }
+}
+// Write-only: replay runs validateField over every stored event, so a value written before this check must still load.
+function refuseUnstorableFields(args) {
+    for (const field of ['subject', 'predicate', 'object']) {
+        const value = args[field];
+        if ((0, invisibleText_1.isBlankOrInvisible)(value))
+            throw new LifecycleInputError(field, `lifecycle ${field} must be a non-empty string`, 'invalid_argument');
+        if (/\p{Cs}/u.test(value))
+            throw new LifecycleInputError(field, `lifecycle ${field} contains an unpaired UTF-16 surrogate, which cannot be stored as text`, 'invalid_text');
+    }
+}
+/**
+ * S1 canonical timestamp contract: ONE sortable format everywhere — the exact
+ * UTC-ISO representation the writer emits (new Date().toISOString():
+ * YYYY-MM-DDTHH:mm:ss.sssZ). With this single format, lexicographic string
+ * order == instant order, so the apply/live string comparisons, the
+ * reconciliation's instant comparisons and the SQL textual ordering behind
+ * asOf/current reads all agree without any format migration or digest change
+ * (canonical events keep byte-identical at strings, so digests are unchanged).
+ * Other representations — e.g. '2026-09-08T23:30:00.000-01:00', which is a
+ * LATER instant sorting EARLIER lexically — are an UNSUPPORTED legacy
+ * representation, not a malicious input: the engine writer has never emitted
+ * them, and they are rejected consistently, BEFORE any mutation, with a clear
+ * message naming the event. Recovery is repairing the ledger entry.
+ */
+const CANONICAL_TS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+function isCanonicalTimestamp(at) {
+    if (!CANONICAL_TS_RE.test(at))
+        return false;
+    // Exact writer format: the string IS the canonical serialization of its instant.
+    const d = new Date(at);
+    return !Number.isNaN(d.getTime()) && d.toISOString() === at;
+}
+/** Normalize any parseable ISO instant to the canonical format (query inputs only). */
+// S1.1: datetime input must carry an explicit timezone (trailing Z or a
+// numeric ±HH:MM offset). Timezone-less datetimes such as
+// '2026-09-09T00:30:00' are parsed against the HOST timezone by Date, so the
+// canonicalized instant silently depended on the host's TZ — ambiguous input
+// is rejected clearly instead. Date-only 'YYYY-MM-DD' remains accepted: ISO
+// 8601 defines date-only as UTC midnight, deterministically. Valid zoned
+// instants normalize exactly as before.
+const ZONED_INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?(Z|[+-]\d{2}:\d{2})$/;
+const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;
+function toCanonicalInstant(value) {
+    if (typeof value !== 'string'
+        || (!ZONED_INSTANT_RE.test(value) && !DATE_ONLY_RE.test(value))) {
+        throw new Error(`invalid timestamp ${JSON.stringify(value)}: expected an ISO 8601 instant with an explicit timezone (e.g. 2026-09-09T00:30:00Z or 2026-09-09T00:30:00-03:00, or date-only YYYY-MM-DD which is UTC midnight); timezone-less datetimes are ambiguous and rejected`);
+    }
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) {
+        throw new Error(`invalid timestamp ${JSON.stringify(value)}: expected a parseable ISO 8601 instant`);
+    }
+    return d.toISOString();
+}
+function validateLedgerEvent(ev) {
+    if (!EVENT_ID_RE.test(ev.id))
+        throw new Error(`ledger event id "${ev.id}" is malformed`);
+    if (!isCanonicalTimestamp(ev.at)) {
+        throw new Error(`ledger event ${ev.id} has an unsupported timestamp representation ${JSON.stringify(ev.at)}: the canonical format emitted by the writer is exact UTC ISO (YYYY-MM-DDTHH:mm:ss.sssZ, e.g. 2026-09-09T00:00:00.000Z); repair the ledger entry`);
+    }
+    if (!KNOWN_KINDS.has(ev.kind))
+        throw new Error(`ledger corruption in event ${ev.id}: unknown kind "${ev.kind}"`);
+    const retirement = RETIREMENT_KINDS.has(ev.kind);
+    validateField('subject', ev.subject, true);
+    validateField('predicate', ev.predicate, true);
+    // A retirement carries no value (RETIREMENT_KINDS); a fact event always does.
+    if (retirement) {
+        if (ev.object !== '')
+            throw new Error(`ledger corruption in event ${ev.id}: a ${ev.kind} event carries no object`);
+    }
+    else {
+        validateField('object', ev.object, true);
+    }
+    validateField('source', ev.source, false);
+    if (ev.writer !== undefined)
+        validateField('writer', ev.writer, true);
+    if (retirement) {
+        if (ev.target === undefined || !EVENT_ID_RE.test(ev.target)) {
+            throw new Error(`ledger corruption in event ${ev.id}: a ${ev.kind} event needs the id of the fact event it ${ev.kind}s (target)`);
+        }
+        if (ev.closedEvent != null || ev.statement !== undefined) {
+            throw new Error(`ledger corruption in event ${ev.id}: a ${ev.kind} event closes nothing and keeps no statement`);
+        }
+    }
+    else if (ev.target !== undefined) {
+        throw new Error(`ledger corruption in event ${ev.id}: only a retire or restore event names a target`);
+    }
+    if (ev.statement !== undefined)
+        validateLifecycleInput({ subject: ev.subject, predicate: ev.predicate, object: ev.object, statement: ev.statement });
+    if (ev.scope !== undefined && ev.scope !== null && ev.scope !== '') {
+        const n = (0, scope_1.normalizeScope)(ev.scope);
+        validateField('scope', n, false);
+        ev.scope = n;
+    }
+    else {
+        ev.scope = 'global';
+    }
+    if (ev.closedEvent != null && !EVENT_ID_RE.test(ev.closedEvent)) {
+        throw new Error(`ledger corruption in event ${ev.id}: malformed closed_event id "${ev.closedEvent}"`);
+    }
+}
+function eventDigest(ev) {
+    const parts = [
+        ev.id, ev.at, ev.kind, ev.subject, ev.predicate, ev.object, ev.closedEvent ?? '', ev.source ?? 'ledger',
+    ];
+    // Digest-stable for legacy/global: only append scope when non-global so existing
+    // applied_ledger_events digests keep matching after migration 8.
+    const scope = (0, scope_1.normalizeScope)(ev.scope);
+    if (scope !== 'global')
+        parts.push(scope);
+    // Same rule for the statement: absent => digest identical to pre-statement events.
+    if (ev.statement !== undefined)
+        parts.push(`statement:${ev.statement}`);
+    if (ev.writer !== undefined)
+        parts.push(`writer:${ev.writer}`);
+    if (ev.target !== undefined)
+        parts.push(`target:${ev.target}`);
+    return crypto_1.default.createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+}
+/**
+ * S2 shared ledger path resolver, rooted at the VAULT ROOT and used by BOTH
+ * append and replay (and the remember receipt). The old containment check
+ * rooted its base at dirname(ledgerRelPath), so '../outside/ledger' passed a
+ * check whose base was already outside the vault; replay had no confinement
+ * at all. Confinement is lexical (path.resolve + path.relative) and happens
+ * BEFORE any filesystem access — an escaping path never creates or reads
+ * anything outside the vault. Absolute ledger paths are rejected fail-closed
+ * (previously they silently double-joined through path.join). Normal relative
+ * paths and the '.md'-suffix behavior are unchanged. This is NOT symlink or
+ * concurrent-writer protection — hosted isolation remains Gate 1B scope.
+ *
+ * S2.1: escape detection matches an actual parent component ('..' exactly, or
+ * '..' followed by a path separator) — NOT a mere '../..' string prefix, which
+ * wrongly rejected harmless in-vault names like '..safe/ledger' or
+ * '..ledger.md'. All traversal defenses are preserved: any resolved path
+ * outside the vault root, and any absolute ledger path, still fails closed.
+ */
+function resolveLedgerPath(vaultPath, ledgerRelPath) {
+    const root = path_1.default.resolve(vaultPath);
+    let rel = ledgerRelPath;
+    if (typeof rel !== 'string' || rel.length === 0) {
+        throw new Error(`ledger path escapes the vault root: ${JSON.stringify(ledgerRelPath)}`);
+    }
+    if (path_1.default.isAbsolute(rel)) {
+        // The ledger is addressed RELATIVE to the vault; an absolute path is a
+        // configuration error (previously it silently double-joined through
+        // path.join) and is rejected fail-closed even if it points inside the vault.
+        throw new Error(`absolute ledger path is not vault-relative: ${JSON.stringify(ledgerRelPath)}`);
+    }
+    // S2.1: check the ORIGINAL request before any '.md' suffix mangling — the
+    // vault root itself ('.'/empty resolution) and any REAL parent component
+    // ('..' exactly, or '..' + separator) fail closed here, so '..' can never
+    // be laundered into a literal '..md' name by the suffix rule.
+    const originalRelFromRoot = path_1.default.relative(root, path_1.default.resolve(root, rel));
+    const originalEscapes = originalRelFromRoot === ''
+        || originalRelFromRoot === '..'
+        || originalRelFromRoot.startsWith('..' + path_1.default.sep)
+        || path_1.default.isAbsolute(originalRelFromRoot);
+    if (originalEscapes) {
+        throw new Error(`ledger path escapes the vault root: ${JSON.stringify(ledgerRelPath)}`);
+    }
+    if (!rel.endsWith('.md'))
+        rel += '.md';
+    const resolved = path_1.default.resolve(root, rel);
+    const relFromRoot = path_1.default.relative(root, resolved);
+    const escapes = relFromRoot === ''
+        || relFromRoot === '..'
+        || relFromRoot.startsWith('..' + path_1.default.sep)
+        || path_1.default.isAbsolute(relFromRoot);
+    if (escapes) {
+        throw new Error(`ledger path escapes the vault root: ${JSON.stringify(ledgerRelPath)}`);
+    }
+    return resolved;
+}
+async function appendLedgerEvent(vaultPath, ledgerRelPath, ev) {
+    validateLedgerEvent(ev);
+    const resolved = resolveLedgerPath(vaultPath, ledgerRelPath);
+    const lines = [
+        `\n## ${ev.id} · ${ev.at}`,
+        `- kind: ${ev.kind}`,
+        `- subject: ${ev.subject}`,
+        `- predicate: ${ev.predicate}`,
+    ];
+    if (ev.target !== undefined)
+        lines.push(`- target: ${ev.target}`);
+    else
+        lines.push(`- object: ${ev.object}`);
+    if (ev.closedEvent)
+        lines.push(`- closed_event: ${ev.closedEvent}`);
+    const scope = (0, scope_1.normalizeScope)(ev.scope);
+    if (scope !== 'global')
+        lines.push(`- scope: ${scope}`);
+    if (ev.statement !== undefined)
+        lines.push(`- statement: ${encodeStatement(ev.statement)}`);
+    if (ev.writer !== undefined)
+        lines.push(`- writer: ${ev.writer}`);
+    lines.push(`- source: ${ev.source}`, ``);
+    // Confined and durable in one append (confinedWrite.ts): a link, a hard link or a FIFO planted in the vault is refused,
+    // never followed, and a failed write is cut back, so the ledger never keeps a fragment of an event whose save the caller
+    // was told failed. A new ledger starts with its header.
+    await (0, confinedWrite_1.appendConfined)(vaultPath, path_1.default.relative(path_1.default.resolve(vaultPath), resolved), lines.join('\n'), LEDGER_HEADER);
+    return resolved;
+}
+const LEDGER_HEADER = `---\ntype: memory-ledger\ntitle: Memory Events Ledger\n---\n\n# Memory Events Ledger\n\nAppend-only durable record of memory events. Replayed on rebuild.\n`;
+/** A field line a complete event may carry (writer output): a known key, `- key: value`. */
+function isLedgerFieldLine(line) {
+    const m = FIELD_RE.exec(line.replace(/\r$/, ''));
+    return m !== null && KNOWN_FIELDS.has(m[1]);
+}
+/**
+ * Where the FINAL ledger event starts when a write cut it short, or -1 when the ledger ends in whole events. The writer
+ * emits `- kind:` first and `- source:` last, so a final event that has a kind line but no terminated source line is
+ * unterminated: a crash or a full disk left it short, whether it was cut mid-line (no final newline) or after a line
+ * (missing its source). Such a block is well-formed up to the cut: its complete lines are a header and known fields, and
+ * its partial last line is a header or field prefix. Anything else is not reported here, so the strict parser refuses
+ * it. A final block with no kind line and a final newline (a legacy block replayed as store, or a malformed one) is left
+ * exactly as it was. Ordinary prose after a complete event never matches.
+ */
+function unterminatedFinalEventStart(text) {
+    const headers = [...text.matchAll(/^## mem_/gim)];
+    if (headers.length === 0)
+        return -1;
+    const start = headers[headers.length - 1].index;
+    const block = text.slice(start);
+    if (/^- source: [^\n]*\n/m.test(block))
+        return -1;
+    const lines = block.split('\n');
+    const partial = lines.pop(); // what follows the last newline: '' when the event ends in one
+    const hasKind = lines.some(line => /^- kind: /.test(line.replace(/\r$/, '')));
+    // A header with no field line after it is a cut too: the writer writes kind on the line after the header.
+    if (partial === '' && !hasKind && lines.length > 1)
+        return -1;
+    if (lines.length > 0) {
+        if (!EVENT_HEADER_RE.test(lines[0].replace(/\r$/, '')))
+            return -1;
+        if (!lines.slice(1).every(isLedgerFieldLine))
+            return -1;
+        if (partial !== '' && partial !== '-' && !partial.startsWith('- '))
+            return -1;
+    }
+    return start;
+}
+function finalEventState(bytes, isProjected) {
+    const valid = utf8PrefixLength(bytes);
+    const text = bytes.subarray(0, valid).toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(bytes.subarray(0, valid)))
+        return { kind: 'none' };
+    const start = unterminatedFinalEventStart(text);
+    if (start < 0)
+        return { kind: 'none' };
+    const id = /^## (\S+)/.exec(text.slice(start))?.[1];
+    if (id !== undefined && isProjected(id.toUpperCase()))
+        return { kind: 'known' };
+    return { kind: 'torn', offset: Buffer.byteLength(text.slice(0, start), 'utf8') };
+}
+/** How many leading bytes end on a complete UTF-8 character: a multi-byte character cut at the end is not counted. */
+function utf8PrefixLength(bytes) {
+    for (let back = 1; back <= Math.min(3, bytes.length); back++) {
+        const b = bytes[bytes.length - back];
+        if ((b & 0xc0) === 0x80)
+            continue; // a continuation byte: its lead byte is further back
+        const need = b >= 0xf0 ? 4 : b >= 0xe0 ? 3 : b >= 0xc0 ? 2 : 1;
+        return need > back ? bytes.length - back : bytes.length;
+    }
+    return bytes.length;
+}
+/**
+ * Moves an unterminated final event out of the ledger: its exact bytes go to `<ledger>.torn-<timestamp>` (created and synced
+ * by createConfined), then the ledger is cut back to the last whole event (synced). Only that tail moves; every complete
+ * event stays where it is. Both files are reached through confined handles (confinedWrite.ts), so a link planted at the
+ * ledger, a hard link to it or a link on its directory is refused before anything is copied or cut. Refuses when the ledger
+ * changed since it was read.
+ */
+async function moveTornTailAside(vaultPath, relFile, ledger, bytes, offset) {
+    const tornBytes = bytes.subarray(offset);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    let tornPath = '';
+    for (let n = 0;; n++) {
+        try {
+            tornPath = await (0, confinedWrite_1.createConfined)(vaultPath, `${relFile}.torn-${stamp}${n ? `-${n}` : ''}`, tornBytes);
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST' || n >= 99)
+                throw err;
+        }
+    }
+    // The cut is only right for the bytes it was decided on: a writer that appended since would lose its event.
+    const now = (await ledger.stat()).size;
+    if (now !== bytes.length) {
+        throw new Error(`ledger ${path_1.default.resolve(vaultPath, relFile)} changed while its unterminated tail was being set aside (${bytes.length} -> ${now} bytes); not cut. Restart the engine.`);
+    }
+    await ledger.truncate(offset);
+    await ledger.sync();
+    console.error(`[memory] ledger ${path_1.default.resolve(vaultPath, relFile)}: its final event was cut short (a crash or a full disk); moved its ${tornBytes.length} byte(s) to ${tornPath} and kept every complete event. If that file holds a hand-written event that was never replayed, restore it by adding its \`- source:\` line and a final newline (if it has none), appending its bytes to the ledger, and restarting; a block still without that line is set aside again.`);
+}
+/**
+ * The ledger's text for replay, and whether its unterminated final event (if any) is one the index already holds. An
+ * unterminated final event is set aside only when `setTornTailAside` is set (engine start-up): a live process that is still
+ * appending (an import, a rebuild in another process) must never have its ledger cut from under it, so every other caller
+ * refuses and leaves the bytes alone. The decision is taken again under the append lock and through a confined handle, because
+ * an append may have finished since the first read, and a link planted at the ledger must be refused, not read or cut.
+ */
+async function readLedgerForReplay(vaultPath, filePath, isProjected, setTornTailAside) {
+    const bytes = await promises_1.default.readFile(filePath);
+    const first = finalEventState(bytes, isProjected);
+    if (first.kind !== 'torn' || !setTornTailAside) {
+        return { content: bytes.toString('utf8'), finalEventKnown: first.kind === 'known' };
+    }
+    const relFile = path_1.default.relative(path_1.default.resolve(vaultPath), filePath);
+    return (0, durableAppend_1.withAppendLock)(filePath, () => (0, confinedWrite_1.withConfinedFile)(vaultPath, relFile, async (ledger) => {
+        const again = await ledger.readFile();
+        const now = finalEventState(again, isProjected);
+        if (now.kind !== 'torn')
+            return { content: again.toString('utf8'), finalEventKnown: now.kind === 'known' };
+        await moveTornTailAside(vaultPath, relFile, ledger, again, now.offset);
+        return { content: again.subarray(0, now.offset).toString('utf8'), finalEventKnown: false };
+    }));
+}
+/**
+ * Strict line-oriented parser for the ledger format. Returns the events in
+ * append order. Throws (never silently skips) on event-shaped corruption:
+ * malformed headers, malformed/unknown/duplicate fields, missing required
+ * fields, unknown kinds, invalid timestamps. Ordinary Markdown prose (the
+ * frontmatter header, human sections) outside event blocks is tolerated.
+ */
+function parseLedgerEvents(content, options = {}) {
+    // A cut final event is refused, never read as whole: its last field (the object of a fact) may be a prefix of the value.
+    // Engine start-up sets such a tail aside before it parses (readLedgerForReplay); any other caller refuses.
+    if (options.finalEventKnown !== true && unterminatedFinalEventStart(content) >= 0) {
+        throw new Error('ledger corruption: its final event is unterminated (a write was cut short by a crash or a full disk); the next engine start sets that tail aside');
+    }
+    const events = [];
+    // Line-ending tolerance: a hand-edited CRLF ledger is valid content with a
+    // Windows editor's line endings, not corruption. Normalize \r\n to \n BEFORE
+    // splitting so field values never carry a stray trailing \r. Lone \r inside
+    // a line remains a control character and still fails loudly.
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line.startsWith('## ')) {
+            i++;
+            continue;
+        }
+        const m = EVENT_HEADER_RE.exec(line);
+        if (!m) {
+            if (/^## mem_/i.test(line)) {
+                throw new Error(`ledger corruption at line ${i + 1}: malformed event header: ${JSON.stringify(line)}`);
+            }
+            i++;
+            continue; // ordinary Markdown heading — not a lifecycle event
+        }
+        const id = m[1].toUpperCase();
+        const at = m[2].trim();
+        if (!Number.isFinite(Date.parse(at))) {
+            throw new Error(`ledger corruption in event ${id} (line ${i + 1}): invalid timestamp ${JSON.stringify(at)}`);
+        }
+        i++;
+        const fields = {};
+        while (i < lines.length && lines[i].startsWith('- ')) {
+            const fm = FIELD_RE.exec(lines[i]);
+            if (!fm)
+                throw new Error(`ledger corruption in event ${id} at line ${i + 1}: malformed field line ${JSON.stringify(lines[i])}`);
+            const key = fm[1];
+            if (!KNOWN_FIELDS.has(key))
+                throw new Error(`ledger corruption in event ${id} at line ${i + 1}: unknown field "${key}"`);
+            if (Object.prototype.hasOwnProperty.call(fields, key))
+                throw new Error(`ledger corruption in event ${id} at line ${i + 1}: duplicate field "${key}"`);
+            fields[key] = fm[2];
+            i++;
+        }
+        const kind = fields.kind ?? 'store';
+        for (const req of REQUIRED_FIELDS) {
+            if (req === 'object' && RETIREMENT_KINDS.has(kind))
+                continue; // a retirement carries no value
+            if (fields[req] === undefined || fields[req] === '') {
+                throw new Error(`ledger corruption in event ${id}: missing required field "${req}"`);
+            }
+        }
+        const ev = {
+            id, at,
+            ...(fields.statement !== undefined ? { statement: decodeStatement(fields.statement, id) } : {}),
+            ...(fields.target !== undefined ? { target: fields.target } : {}),
+            kind,
+            subject: fields.subject,
+            predicate: fields.predicate,
+            object: fields.object ?? '',
+            closedEvent: fields.closed_event ?? null,
+            source: fields.source ?? 'ledger',
+            scope: fields.scope ? (0, scope_1.normalizeScope)(fields.scope) : 'global',
+            ...(fields.writer !== undefined ? { writer: fields.writer } : {}),
+        };
+        validateLedgerEvent(ev); // bounds, kind, id/timestamp/closed_event shape
+        events.push(ev);
+    }
+    return events;
+}
+/**
+ * A subject whose identity key matches SEVERAL lifecycle entities and whose open
+ * current facts disagree. Two spellings of one person (`José` and `JOSÉ`, or an NFC
+ * and an NFD form) could be split by a pre-fix write path, and there is no unique
+ * index on `entities` and no merge path, so nothing at the DB level forbids it.
+ *
+ * On the live write path there is no canonical order to consult (row ids are
+ * disposable cache artifacts, never consulted), so picking one entity would silently
+ * decide which of two conflicting values is current. Fail closed instead.
+ *
+ * Recovery is documented, not guessed: replaying the canonical ledger in order into a
+ * fresh index reconciles duplicate identities by event position (the later event
+ * wins), which is exactly the fix's behavior on a rebuild. Stored rows and histories
+ * are never deleted or rewritten by this error.
+ */
+class LegacyIdentityAmbiguityError extends Error {
+    subject;
+    entityIds;
+    canonicalNames;
+    streams;
+    constructor(args) {
+        super(`legacy identity ambiguity for subject ${JSON.stringify(args.subject)}: `
+            + `${args.entities.length} lifecycle entities share one identity `
+            + `(${args.entities.map(e => `#${e.id} ${JSON.stringify(e.canonicalName)}`).join(', ')}) `
+            + `and their current facts disagree on ${args.streams.join(', ')}. `
+            + 'Refusing to guess which value is current; nothing was written. '
+            + 'Recovery: rebuild the index from the canonical ledger (an in-order replay reconciles the duplicate identities by event position).');
+        this.name = 'LegacyIdentityAmbiguityError';
+        this.subject = args.subject;
+        this.entityIds = args.entities.map(e => e.id);
+        this.canonicalNames = args.entities.map(e => e.canonicalName);
+        this.streams = args.streams;
+    }
+}
+exports.LegacyIdentityAmbiguityError = LegacyIdentityAmbiguityError;
+/** One replay-local scan; buckets retain the legacy lowest-row-id ordering. */
+function replayEntityIndex(db) {
+    const index = new Map();
+    const rows = (0, factTerms_1.prepareOnce)(db, `SELECT id, canonical_name FROM entities WHERE source_note = ? ORDER BY id`).all(exports.LIFECYCLE_NOTE_PATH);
+    for (const row of rows)
+        addEntityToIndex(index, row);
+    return index;
+}
+function addEntityToIndex(index, row) {
+    const key = (0, queryHelpers_1.identityKey)(row.canonical_name);
+    const matches = index.get(key) ?? [];
+    matches.push({ id: row.id, canonicalName: row.canonical_name });
+    index.set(key, matches);
+}
+/**
+ * Per database, for the reads and writes outside a replay: the same index, with how many lifecycle entities there
+ * were and the newest one's id when it was read. Lifecycle entity rows are only ever added, under ids that only grow
+ * (AUTOINCREMENT), and never renamed, so those two numbers say whether the table still holds what the index was read
+ * from: rows added since are read and added to it (by id, so each bucket keeps its lowest-id-first order), and any
+ * other change (a row gone) reads the table again. Only committed rows are read into it, so inside a transaction it
+ * is used only while it is current, and the table is scanned instead, as before.
+ */
+const liveEntityIndexes = new WeakMap();
+function liveEntityIndex(db) {
+    const { count, newest } = (0, factTerms_1.prepareOnce)(db, `SELECT COUNT(*) AS count, COALESCE(MAX(id), 0) AS newest FROM entities WHERE source_note = ?`).get(exports.LIFECYCLE_NOTE_PATH);
+    const cached = liveEntityIndexes.get(db);
+    if (cached && cached.count === count && cached.newest === newest)
+        return cached.index;
+    if (db.inTransaction)
+        return null;
+    if (cached && count > cached.count && newest > cached.newest) {
+        const added = (0, factTerms_1.prepareOnce)(db, `SELECT id, canonical_name FROM entities WHERE source_note = ? AND id > ? ORDER BY id`).all(exports.LIFECYCLE_NOTE_PATH, cached.newest);
+        if (cached.count + added.length === count) {
+            for (const row of added)
+                addEntityToIndex(cached.index, row);
+            cached.count = count;
+            cached.newest = newest;
+            return cached.index;
+        }
+    }
+    const index = replayEntityIndex(db);
+    liveEntityIndexes.set(db, { count, newest, index });
+    return index;
+}
+/**
+ * Lifecycle-owned entities whose identity key matches `subject`, ordered by row id.
+ *
+ * `identityKey` is the single subject-identity primitive (NFC + case fold, explicit
+ * aliases unified), so the lifecycle no longer needs SQL `COLLATE NOCASE` — which
+ * folds ASCII A–Z only and therefore split `José`/`JOSÉ`, `Пётр`/`пётр` and every
+ * NFC/NFD pair into two entities with two open currents. The comparison happens in JS
+ * BEFORE the query result is used, so a normalization form can never leak into the
+ * equality test. The fold is not expressible in SQLite without ICU, so the
+ * matches come from an index keyed by identity: replay builds one for itself, and
+ * live reads and writes keep one per database (liveEntityIndex), instead of folding
+ * every `_mcp_` entity's name on every save.
+ */
+function lifecycleEntityMatches(db, subject, index) {
+    const key = (0, queryHelpers_1.identityKey)(subject);
+    if (index)
+        return index.get(key) ?? [];
+    const live = liveEntityIndex(db);
+    if (live)
+        return live.get(key) ?? [];
+    const rows = (0, factTerms_1.prepareOnce)(db, `SELECT id, canonical_name FROM entities WHERE source_note = ? ORDER BY id`).all(exports.LIFECYCLE_NOTE_PATH);
+    return rows
+        .filter(row => (0, queryHelpers_1.identityKey)(row.canonical_name) === key)
+        .map(row => ({ id: row.id, canonicalName: row.canonical_name }));
+}
+/** Streams (`predicate @ scope`) where the matched entities' open currents disagree. */
+function conflictingLegacyStreams(db, entities) {
+    if (entities.length < 2)
+        return [];
+    const placeholders = entities.map(() => '?').join(',');
+    const rows = (0, factTerms_1.prepareOnce)(db, `SELECT predicate, COALESCE(scope, 'global') AS scope, object_text
+       FROM facts WHERE subject_entity_id IN (${placeholders}) AND valid_to IS NULL`).all(...entities.map(e => e.id));
+    const values = new Map();
+    for (const row of rows) {
+        const key = `${row.predicate}\u0000${row.scope}`;
+        const set = values.get(key) ?? new Set();
+        set.add(row.object_text);
+        values.set(key, set);
+    }
+    return [...values.entries()]
+        .filter(([, objects]) => objects.size > 1)
+        .map(([key]) => {
+        const [predicate, scope] = key.split('\u0000');
+        return `${predicate} @ ${scope}`;
+    });
+}
+/**
+ * Resolve the lifecycle-owned entity for a subject (source_note '_mcp_').
+ *
+ * `preferEntityId` is used by the already-projected replay branch: the event's own
+ * projected owner is canonical for that event, so reconciliation targets it instead of
+ * re-deciding identity (which would either re-open the split or refuse a replay the
+ * service needs at startup). `strict` is used by the live write path, which fails
+ * closed on a conflicting legacy split before anything is published.
+ */
+function resolveLifecycleEntity(db, subject, at, create, opts = {}) {
+    const matches = lifecycleEntityMatches(db, subject, opts.index);
+    if (matches.length > 0) {
+        if (opts.preferEntityId !== undefined && matches.some(m => m.id === opts.preferEntityId)) {
+            return opts.preferEntityId;
+        }
+        if (matches.length === 1)
+            return matches[0].id;
+        if (opts.strict) {
+            const streams = conflictingLegacyStreams(db, matches);
+            if (streams.length > 0)
+                throw new LegacyIdentityAmbiguityError({ subject, entities: matches, streams });
+        }
+        // Several entities, no conflicting current value: deterministic lowest id, so a
+        // repeat write/replay never alternates between identities. Nothing is deleted.
+        return matches[0].id;
+    }
+    if (!create)
+        return null;
+    (0, factTerms_1.prepareOnce)(db, `INSERT OR IGNORE INTO notes (path, title, kind, note_hash, modified_at, frontmatter_json) VALUES (?, 'Memory Lifecycle', 'system', ?, ?, '{}')`).run(exports.LIFECYCLE_NOTE_PATH, exports.LIFECYCLE_NOTE_PATH, at);
+    const id = (0, factTerms_1.prepareOnce)(db, `INSERT INTO entities (type, canonical_name, aliases_json, source_note, confidence, updated_at) VALUES ('concept', ?, '[]', ?, 1.0, ?) RETURNING id`).get(subject, exports.LIFECYCLE_NOTE_PATH, at).id;
+    // New rows have increasing ids, and an empty bucket is the only creation
+    // path. On any failed event replay throws and discards this local index;
+    // rolled-back ids can never escape into a later replay/live write.
+    opts.index?.set((0, queryHelpers_1.identityKey)(subject), [{ id, canonicalName: subject }]);
+    return id;
+}
+function currentFact(db, entityId, predicate, scope = 'global') {
+    return (0, factTerms_1.prepareOnce)(db, `SELECT id, object_text, event_id, valid_from, scope, author FROM facts
+     WHERE subject_entity_id = ? AND predicate = ? AND scope = ? AND valid_to IS NULL
+     ORDER BY valid_from DESC, id DESC LIMIT 1`).get(entityId, predicate, scope);
+}
+/**
+ * One lifecycle stream per scope: a named scope is its slug (scopeSpellings), so the stream of (entity, predicate) in
+ * `scope` is its facts under every spelling of the slug, and a write closes the stream's current value whatever
+ * spelling either was saved with. These are that stream's current facts, newest first: one, or two when values were
+ * saved under two spellings before writes closed across them (each spelling holds at most one, idx_facts_current).
+ */
+function streamCurrentFacts(db, entityId, predicate, scope) {
+    return (0, scope_1.scopeSpellings)(scope)
+        .map(spelling => currentFact(db, entityId, predicate, spelling))
+        .filter((row) => row !== undefined)
+        .sort((a, b) => (a.valid_from === b.valid_from ? b.id - a.id : a.valid_from < b.valid_from ? 1 : -1));
+}
+/**
+ * The fact an event closes under the other spelling of its slug: the one its closed_event names, when that is the
+ * current value of the same entity and predicate saved under another spelling of the event's scope. A write closes
+ * across spellings only by naming the fact it closes, and before it did, closed_event only ever named the current
+ * value under the event's own spelling, so a ledger written then replays exactly as it did: values saved under two
+ * spellings stay current, and a read names them as a conflict until a write closes them.
+ */
+function currentFactClosedAcrossSpellings(db, ev, entityId, scope) {
+    if (!ev.closedEvent)
+        return undefined;
+    const named = (0, factTerms_1.prepareOnce)(db, `SELECT id, object_text, event_id, valid_from, scope, author FROM facts
+     WHERE event_id = ? AND subject_entity_id = ? AND predicate = ? AND valid_to IS NULL`).get(ev.closedEvent.toUpperCase(), entityId, ev.predicate);
+    return named && named.scope !== scope && (0, scope_1.savedScopeMatches)(named.scope, scope) ? named : undefined;
+}
+/**
+ * Re-home an already-projected legacy canonical fact from a disposable
+ * note-derived entity onto the stable lifecycle-owned entity (Astra A2 /
+ * Kimi R2, Kimi K9). The row keeps its event_id, timestamps and history —
+ * only ownership moves, and nothing is dropped or duplicated.
+ *
+ * Constraint-safe ordering (K9): idx_facts_current is a PARTIAL unique index
+ * and fires per STATEMENT. The naive move-then-close sequence made the moved
+ * row a second open current for one statement and threw UNIQUE before the
+ * reconciliation close could run, bricking upgrade replay on mixed-owner
+ * states. Instead, the winner is decided BEFORE any move and the statements
+ * are ordered so no intermediate state ever has two open currents:
+ *
+ *   - no competing lifecycle current, or the moving row is historical
+ *       -> plain move (never enters the partial index scope as a second open row);
+ *   - the existing lifecycle current is the canonical winner -> the moving
+ *     row is closed AND moved in ONE statement (valid_to set in the same
+ *     UPDATE, so the index never sees it as an open duplicate);
+ *   - the moving row is the canonical winner -> competing lifecycle currents
+ *     are closed first, then the row moves in as the only open current.
+ *
+ * Winner rule (K12): the CANONICAL LEDGER position of each row's event decides
+ * — the event that appears later in the ledger wins, exactly matching what a
+ * fresh in-order replay would produce. SQLite row ids are disposable cache
+ * artifacts (insertion order of a legacy projection) and are NEVER consulted.
+ * A competing open row with an event_id that is ABSENT from the ledger is an
+ * index-vs-ledger contradiction: it fails explicitly rather than being ordered
+ * by guesswork. A NULL-event row (base vault_store_fact wrote those, bypassing
+ * the ledger) is non-canonical by construction and never wins against a
+ * ledger event. Residual interval flags are canonicalized afterwards by
+ * reconcileStreamCurrent, so this function only has to make the MOVE safe.
+ */
+function rehomeLifecycleFact(db, ev, factId, positions, lifecycleId) {
+    const tx = db.transaction(() => {
+        const moving = (0, factTerms_1.prepareOnce)(db, 'SELECT id, valid_from, valid_to FROM facts WHERE id = ?').get(factId);
+        const existing = currentFact(db, lifecycleId, ev.predicate, (0, scope_1.normalizeScope)(ev.scope));
+        if (existing && moving.valid_to === null) {
+            const movingPos = requireLedgerPosition(positions, ev.id);
+            let movingWins;
+            if (existing.event_id == null) {
+                // Non-event-backed row: never canonical against a ledger event.
+                movingWins = true;
+            }
+            else {
+                const existingPos = requireLedgerPosition(positions, existing.event_id);
+                movingWins = movingPos > existingPos; // later canonical event wins (row ids never consulted)
+            }
+            if (movingWins) {
+                // Close the competing lifecycle current(s) BEFORE the move, so the
+                // moving row is never a second open current. The valid_to value here
+                // is provisional; reconcileStreamCurrent canonicalizes it afterwards.
+                (0, factTerms_1.prepareOnce)(db, `UPDATE facts SET valid_to = ?, updated_at = ? WHERE subject_entity_id = ? AND predicate = ? AND scope = ? AND valid_to IS NULL AND id != ?`).run(moving.valid_from, moving.valid_from, lifecycleId, ev.predicate, (0, scope_1.normalizeScope)(ev.scope), moving.id);
+                (0, factTerms_1.prepareOnce)(db, 'UPDATE facts SET subject_entity_id = ? WHERE id = ?').run(lifecycleId, factId);
+            }
+            else {
+                // The existing lifecycle current wins canonically: close AND move the
+                // row in one statement. With valid_to set in the same UPDATE, the
+                // partial index (valid_to IS NULL) never sees the moved row as open.
+                (0, factTerms_1.prepareOnce)(db, 'UPDATE facts SET subject_entity_id = ?, valid_to = ?, updated_at = ? WHERE id = ?')
+                    .run(lifecycleId, existing.valid_from, existing.valid_from, factId);
+            }
+        }
+        else {
+            // No competing open current, or the moving row is historical: a plain
+            // move cannot violate the partial index.
+            (0, factTerms_1.prepareOnce)(db, 'UPDATE facts SET subject_entity_id = ? WHERE id = ?').run(lifecycleId, factId);
+        }
+    });
+    tx();
+}
+/** Later of two timestamps by instant comparison (raw strings preserved). */
+function maxInstant(a, b) {
+    return Date.parse(a) >= Date.parse(b) ? a : b;
+}
+/** Canonical position of a ledger event, or an explicit refusal to guess. */
+function requireLedgerPosition(positions, eventId) {
+    const pos = positions.get(eventId);
+    if (pos === undefined) {
+        throw new Error(`index holds a lifecycle fact for event ${eventId} which is absent from the ledger; refusing to guess canonical order — restore the ledger or deliberately rebuild the derived index`);
+    }
+    return pos;
+}
+/**
+ * Canonical stream reconciliation (K12): recompute the current/valid_to chain
+ * for every event-backed lifecycle fact of (lifecycle entity, predicate) from
+ * the CANONICAL ledger positions, exactly mirroring what a fresh in-order
+ * replay produces — the event that appears latest in the ledger is the
+ * current fact; each earlier event's row is closed at its canonical
+ * successor's valid_from (never before its own valid_from, so no negative
+ * intervals). Stale winner flags left behind by earlier candidate reconciliations
+ * (including migration 6's interim duplicate repair, which cannot read the
+ * ledger) are repaired here, before readiness. Non-event-backed open rows are
+ * non-canonical (base vault_store_fact bypassed the ledger): they are closed
+ * at the start of the canonical record and KEPT in history — never dropped.
+ * Event-backed rows whose event is absent from the ledger are an
+ * index-vs-ledger contradiction and fail explicitly. Unrelated (non '_mcp_')
+ * facts are not touched. Idempotent: re-running produces no further writes.
+ *
+ * The stream is the scope's slug (streamCurrentFacts): the rows of every
+ * spelling are replayed together, in ledger order, as applyEvent applies them.
+ * Each event closes the current row of its own spelling and the row its
+ * closed_event names under another spelling (currentFactClosedAcrossSpellings;
+ * `closedBy` holds each event's closed_event). Without such a link the
+ * spellings never touch, so each spelling's chain is exactly the per-spelling
+ * chain this function computed before scopes were one slug.
+ */
+function reconcileStreamCurrent(db, lifecycleId, predicate, positions, scope = 'global', closedBy = new Map()) {
+    (0, statements_1.transactionOnce)(db, reconcileStreamCurrentBody)(lifecycleId, predicate, positions, scope, closedBy);
+}
+/** The body of reconcileStreamCurrent's transaction: a module-level function so replay wraps it once per connection (transactionOnce). */
+function reconcileStreamCurrentBody(db, lifecycleId, predicate, positions, scope, closedBy) {
+    const inStream = (0, scope_1.savedScopeSqlPredicate)(scope, 'scope');
+    // A retired fact keeps its place in the stream (retireFact): it is hidden, not undone, so the value it closed stays
+    // closed and the value saved after it closes it, exactly as if it had never been retired.
+    const rows = (0, factTerms_1.prepareOnce)(db, `SELECT id, event_id, valid_from, valid_to, scope, 0 AS retired FROM facts
+     WHERE subject_entity_id = ? AND predicate = ? AND ${inStream.sql} AND source_path = '_mcp_'
+     UNION ALL
+     SELECT id, event_id, valid_from, valid_to, scope, 1 AS retired FROM retired_facts
+     WHERE subject_entity_id = ? AND predicate = ? AND ${inStream.sql}`).all(lifecycleId, predicate, ...inStream.params, lifecycleId, predicate, ...inStream.params);
+    const table = (row) => (row.retired ? 'retired_facts' : 'facts');
+    const canonical = [];
+    for (const r of rows) {
+        if (r.event_id == null)
+            continue;
+        canonical.push({ ...r, event_id: r.event_id, pos: requireLedgerPosition(positions, r.event_id) });
+    }
+    canonical.sort((a, b) => a.pos - b.pos);
+    // The replay, in ledger order: the current row of each spelling, and the valid_to each closed row gets.
+    // Full equivalence with a fresh replay (K12): the fresh-apply path rejects
+    // an event whose time precedes the current fact it would close; the same
+    // rule applies to an already-projected chain, so an invalid ledger is
+    // rejected by BOTH upgrade replay and fresh rebuild, never repaired into
+    // a state a fresh replay could not produce. (Equal timestamps are legal.)
+    const current = new Map();
+    const closeAt = new Map();
+    for (const row of canonical) {
+        const named = closedBy.get(row.event_id);
+        const across = named === undefined ? undefined
+            : [...current.values()].find(r => r.scope !== row.scope && r.event_id === named);
+        for (const closed of [current.get(row.scope), across]) {
+            if (!closed)
+                continue;
+            if (Date.parse(row.valid_from) < Date.parse(closed.valid_from)) {
+                throw new Error(`ledger event ${row.event_id} (${row.valid_from}) is older than the current fact for the same subject+predicate (valid_from ${closed.valid_from}, event ${closed.event_id}); refusing to apply out-of-order`);
+            }
+            closeAt.set(closed.id, maxInstant(row.valid_from, closed.valid_from));
+            current.delete(closed.scope);
+        }
+        current.set(row.scope, row);
+    }
+    // Pass 1 (constraint-safe): apply all NON-NULL valid_to targets first, so
+    // at most one open row per spelling remains before the NULL (current) updates.
+    for (const row of canonical) {
+        const want = closeAt.get(row.id);
+        if (want !== undefined && (row.valid_to ?? null) !== want) {
+            (0, factTerms_1.prepareOnce)(db, `UPDATE ${table(row)} SET valid_to = ?, updated_at = ? WHERE id = ?`).run(want, want, row.id);
+        }
+    }
+    for (const spelling of (0, scope_1.scopeSpellings)(scope)) {
+        const chain = canonical.filter(row => row.scope === spelling);
+        if (chain.length === 0)
+            continue;
+        const last = current.get(spelling);
+        if (last && last.valid_to !== null) {
+            (0, factTerms_1.prepareOnce)(db, `UPDATE ${table(last)} SET valid_to = NULL, updated_at = ? WHERE id = ?`).run(last.valid_from, last.id);
+        }
+        // Non-event-backed open rows never stay current against canonical events.
+        const firstCanonicalFrom = chain[0].valid_from;
+        for (const r of rows) {
+            if (r.scope === spelling && r.event_id == null && r.valid_to === null) {
+                const want = maxInstant(firstCanonicalFrom, r.valid_from);
+                (0, factTerms_1.prepareOnce)(db, 'UPDATE facts SET valid_to = ?, updated_at = ? WHERE id = ?').run(want, want, r.id);
+            }
+        }
+    }
+}
+/**
+ * The transaction applyEvent runs for an event that is already projected: re-home a fact still attached to a disposable entity,
+ * then reconcile its stream. A module-level function so replay wraps it once per connection (transactionOnce).
+ */
+function reconcileProjectedEvent(db, ev, factId, rehome, positions, lifecycleId, closedBy) {
+    if (rehome) {
+        rehomeLifecycleFact(db, ev, factId, positions, lifecycleId);
+    }
+    // Do not preserve stale winner/valid_to flags merely because the event
+    // is already projected: recompute the chain from canonical ledger order
+    // so the upgraded cache is equivalent to a fresh replay of the ledger.
+    reconcileStreamCurrent(db, lifecycleId, ev.predicate, positions, (0, scope_1.normalizeScope)(ev.scope), closedBy);
+}
+/**
+ * Apply one memory event to SQLite inside a single transaction:
+ * dedup check → entity resolution → close current → insert fact → receipt.
+ * Idempotent by event id + digest; a reused id with a conflicting payload is
+ * explicit corruption; a failed insert can never leave a partial supersession.
+ */
+function applyEvent(db, ev, positions, index, closedBy) {
+    validateLedgerEvent(ev);
+    const digest = eventDigest(ev);
+    const seen = (0, factTerms_1.prepareOnce)(db, 'SELECT digest FROM applied_ledger_events WHERE event_id = ?').get(ev.id);
+    if (seen && seen.digest !== digest) {
+        throw new Error(`ledger event id ${ev.id} was reused with a conflicting payload; refusing to apply (corruption)`);
+    }
+    if (RETIREMENT_KINDS.has(ev.kind)) {
+        applyRetirement(db, ev, digest, seen !== undefined);
+        return { applied: seen === undefined, factId: null };
+    }
+    // A retired fact is projected too: its row waits in retired_facts.
+    const liveRow = (0, factTerms_1.prepareOnce)(db, 'SELECT id, subject_entity_id FROM facts WHERE event_id = ?').get(ev.id);
+    const factRow = liveRow
+        ?? (0, factTerms_1.prepareOnce)(db, 'SELECT id, subject_entity_id FROM retired_facts WHERE event_id = ?').get(ev.id);
+    if (factRow) {
+        // Event already projected — but a pre-Gate1A index can hold this canonical
+        // fact attached to a DISPOSABLE note-derived entity (the base engine
+        // resolved subjects via generic lookupEntity). Re-home it onto the stable
+        // lifecycle-owned entity BEFORE readiness and later writes, or note
+        // reindexing would cascade-delete it (Astra A2 / Kimi R2 loss window).
+        // K12: reconciliation of the already-projected stream is CANONICAL — it
+        // needs the ledger event positions and refuses to guess without them
+        // (this branch is unreachable from the live write path, whose event ids
+        // are always fresh).
+        if (!positions) {
+            throw new Error(`canonical ledger order is unavailable while reconciling already-projected event ${ev.id}; refusing to guess — reconciliation requires replay context`);
+        }
+        const lifecycleId = resolveLifecycleEntity(db, ev.subject, ev.at, true, { preferEntityId: factRow.subject_entity_id, index });
+        const owner = (0, factTerms_1.prepareOnce)(db, 'SELECT source_note FROM entities WHERE id = ?').get(factRow.subject_entity_id);
+        // Re-home and stream reconciliation are ONE atomic unit (nested
+        // transactions become savepoints): a rejected ledger (out-of-order chain,
+        // absent-from-ledger contradiction) rolls the reconciliation back and
+        // leaves the cache exactly as it was held — never partially reconciled.
+        (0, statements_1.transactionOnce)(db, reconcileProjectedEvent)(ev, factRow.id, liveRow !== undefined && owner?.source_note !== exports.LIFECYCLE_NOTE_PATH, positions, lifecycleId, closedBy);
+        // If it predates the digest table (migration 6), backfill the digest so
+        // future replays can tell identical dedup from conflicts (the legacy
+        // payload itself can no longer be verified).
+        if (!seen) {
+            (0, factTerms_1.prepareOnce)(db, 'INSERT OR IGNORE INTO applied_ledger_events (event_id, digest, applied_at) VALUES (?, ?, ?)')
+                .run(ev.id, digest, new Date().toISOString());
+        }
+        return { applied: false, factId: null }; // byte-identical event already committed — safe dedup
+    }
+    // If a digest row exists but the fact is missing, the index lost the
+    // projection (e.g. a partial wipe): re-apply — replay repairs the index.
+    const tx = db.transaction(() => {
+        // create=true always resolves or creates — never null here.
+        const entityId = resolveLifecycleEntity(db, ev.subject, ev.at, true, { index });
+        const closedFactIds = [];
+        // The value this write replaces (the newest one it closes): the writer displacements it leaves open are read from it.
+        let replaced = null;
+        // The current fact under the event's own spelling, then the one it names under the other spelling of its slug.
+        const scope = (0, scope_1.normalizeScope)(ev.scope);
+        for (const cur of [currentFact(db, entityId, ev.predicate, scope), currentFactClosedAcrossSpellings(db, ev, entityId, scope)]) {
+            if (!cur)
+                continue;
+            // Monotonicity validation: an event older than the current fact it would
+            // close is arbitrary corrupt ordering — fail loudly, never silently
+            // last-write-wins mask it. (Equal timestamps are legal: base-engine race
+            // chains share millisecond timestamps.)
+            if (ev.at < cur.valid_from) {
+                throw new Error(`ledger event ${ev.id} (${ev.at}) is older than the current fact for the same subject+predicate (valid_from ${cur.valid_from}, fact id ${cur.id}); refusing to apply out-of-order`);
+            }
+            // K12 (replay context only): a current row whose event id is absent from
+            // the ledger is an index-vs-ledger contradiction — closing it silently
+            // would order canonical truth by guesswork. Fail explicitly instead.
+            // (The live write path passes no positions and keeps its existing
+            // behavior; the next replay of the ledger fails closed on the same row.)
+            if (positions && cur.event_id != null && !positions.has(cur.event_id)) {
+                requireLedgerPosition(positions, cur.event_id); // throws the explicit contradiction error
+            }
+            // Explicit reconciliation policy: 'supersede' closes the current fact by
+            // intent. A 'store' finding an open current is NOT normal modern flow —
+            // remember() writes supersede whenever it can see the current value —
+            // so it can only arise from pre-Gate1A legacy chains: base-engine B2
+            // races appended concurrent kind:store events, and the legacy cascade
+            // loss window (Kimi R4) let a user-repair store be appended while the
+            // prior projection was invisible. The prior fact is CLOSED (timestamped
+            // with this event's time) and full history is preserved — nothing is
+            // dropped or duplicated, and the digest/id conflict checks above still
+            // fail loudly on contradictory reuse.
+            (0, factTerms_1.prepareOnce)(db, `UPDATE facts SET valid_to = ?, updated_at = ? WHERE id = ?`).run(ev.at, ev.at, cur.id);
+            closedFactIds.push(cur.id);
+            if (replaced === null || cur.valid_from > replaced.validFrom) {
+                replaced = { eventId: cur.event_id, object: cur.object_text, validFrom: cur.valid_from, source: cur.author };
+            }
+        }
+        // A retired value that was current under this spelling is closed as if it had never been retired
+        // (reconcileStreamCurrent replays it the same way), so restoring it later brings it back as history.
+        // The stream is the scope's slug, not one spelling of it (scopeSpellings): a value retired under scope:alpha is
+        // closed by a save under project:alpha too, or the retired one stays open and a later restore leaves two currents.
+        for (const hidden of streamOpenRetiredFacts(db, entityId, ev.predicate, scope)) {
+            if (ev.at < hidden.valid_from) {
+                throw new Error(`ledger event ${ev.id} (${ev.at}) is older than the retired fact it would close (valid_from ${hidden.valid_from}, event ${hidden.event_id}); refusing to apply out-of-order`);
+            }
+            (0, factTerms_1.prepareOnce)(db, 'UPDATE retired_facts SET valid_to = ?, updated_at = ? WHERE id = ?').run(ev.at, ev.at, hidden.id);
+        }
+        const row = (0, factTerms_1.prepareOnce)(db, `INSERT INTO facts (subject_entity_id, predicate, object_text, source_path, confidence, valid_from, valid_to, updated_at, event_id, scope, author, statement_words)
+       VALUES (?, ?, ?, '_mcp_', 1.0, ?, NULL, ?, ?, ?, ?, ?) RETURNING id`).get(entityId, ev.predicate, ev.object, ev.at, ev.at, ev.id, scope, ev.source, (0, factTerms_1.statementTerms)(ev.statement));
+        // Who saved it, and the writer displacements it leaves open (writerConflicts.ts); a replay writes the same row.
+        const writer = ev.writer ?? ev.source;
+        (0, factTerms_1.prepareOnce)(db, 'INSERT OR REPLACE INTO fact_writers (event_id, writer, displaced) VALUES (?, ?, ?)')
+            .run(ev.id, writer, JSON.stringify((0, writerConflicts_1.displacementsAfter)(db, replaced, { eventId: ev.id, writer, object: ev.object })));
+        // Searchable by its words from the moment it exists: the index row is written by this transaction,
+        // under the subject name a read shows (the entity's, which may be an earlier spelling of ev.subject).
+        (0, factTerms_1.indexFactTerms)(db, row.id, scope, { subject: (0, factTerms_1.canonicalSubject)(db, entityId), predicate: ev.predicate, object: ev.object });
+        (0, factTerms_1.prepareOnce)(db, `INSERT INTO write_events (note_path, action, summary, created_at, author, scope) VALUES ('_memory_ledger_', ?, ?, ?, ?, ?)`)
+            .run(ev.kind, `${ev.subject} ${ev.predicate} → ${ev.object}${closedFactIds.length ? ` (closed fact${closedFactIds.length > 1 ? 's' : ''} ${closedFactIds.join(', ')})` : ''}`, ev.at, ev.source, ev.scope ?? 'global');
+        (0, factTerms_1.prepareOnce)(db, 'INSERT OR REPLACE INTO applied_ledger_events (event_id, digest, applied_at) VALUES (?, ?, ?)')
+            .run(ev.id, digest, ev.at);
+        return row.id;
+    });
+    const factId = tx();
+    return { applied: true, factId };
+}
+/** The retired fact that was the current value of a stream spelling when it was retired, if one still is. */
+function openRetiredFact(db, entityId, predicate, scope) {
+    return (0, factTerms_1.prepareOnce)(db, `SELECT id, event_id, valid_from, object_text, scope FROM retired_facts
+     WHERE subject_entity_id = ? AND predicate = ? AND scope = ? AND valid_to IS NULL
+     ORDER BY valid_from DESC, id DESC LIMIT 1`).get(entityId, predicate, scope);
+}
+/**
+ * The retired facts that were the current value of a stream spelling when they were retired, one per spelling at most,
+ * newest first. The stream is the scope's slug (scopeSpellings): a save closes the retired current whatever spelling it
+ * was retired under, exactly as it closes the live current across spellings (streamCurrentFacts). Closing it at save
+ * time is what lets a later restore bring it back as history instead of as a second current value.
+ */
+function streamOpenRetiredFacts(db, entityId, predicate, scope) {
+    return (0, scope_1.scopeSpellings)(scope)
+        .map(spelling => openRetiredFact(db, entityId, predicate, spelling))
+        .filter((row) => row !== undefined)
+        .sort((a, b) => (a.valid_from === b.valid_from ? b.id - a.id : a.valid_from < b.valid_from ? 1 : -1));
+}
+const FACT_COLUMNS = 'id, subject_entity_id, predicate, object_text, confidence, valid_from, valid_to, updated_at, event_id, scope, author, statement_words';
+/**
+ * Moves a lifecycle fact's row out of `facts`, id and all, into retired_facts: no read of `facts` (current values,
+ * history, as_of, search, the facts lane, memory_map, the subject lists) returns it after this, with nothing to filter.
+ * False when no such row is in `facts` (it is already retired, or no fact has that event).
+ */
+function moveFactOut(db, eventId, retire) {
+    const row = (0, factTerms_1.prepareOnce)(db, `SELECT ${FACT_COLUMNS} FROM facts WHERE event_id = ? AND source_path = ?`)
+        .get(eventId, exports.LIFECYCLE_NOTE_PATH);
+    if (!row)
+        return false;
+    (0, factTerms_1.prepareOnce)(db, `INSERT INTO retired_facts (${FACT_COLUMNS}, retire_event_id, retired_at, retired_by) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.id, row.subject_entity_id, row.predicate, row.object_text, row.confidence, row.valid_from, row.valid_to, row.updated_at, row.event_id, row.scope, row.author, row.statement_words, retire.id, retire.at, retire.source);
+    (0, factTerms_1.unindexFactTerms)(db, row.id, row.scope, { subject: (0, factTerms_1.canonicalSubject)(db, row.subject_entity_id), predicate: row.predicate, object: row.object_text });
+    (0, factTerms_1.prepareOnce)(db, 'DELETE FROM facts WHERE id = ?').run(row.id);
+    return true;
+}
+/**
+ * A restatement can supersede an identical value only because it kept different user words. When that current
+ * restatement is retired, reopen the exact value it directly replaced. Different values remain historical: retiring a
+ * correction is not itself another correction. This projection is derived from the save chain, so replay makes the
+ * same choice without adding a second value to the retire event.
+ */
+function reviveIdenticalPredecessor(db, eventId) {
+    const retired = (0, factTerms_1.prepareOnce)(db, `SELECT ${FACT_COLUMNS} FROM retired_facts WHERE event_id = ?`).get(eventId);
+    if (!retired || retired.valid_to !== null)
+        return; // Retiring history never changes the current value.
+    const inStream = (0, scope_1.savedScopeSqlPredicate)((0, scope_1.normalizeScope)(retired.scope), 'scope');
+    const prior = (0, factTerms_1.prepareOnce)(db, `SELECT ${FACT_COLUMNS} FROM facts
+      WHERE subject_entity_id = ? AND predicate = ? AND object_text = ? AND valid_to = ?
+        AND source_path = ? AND ${inStream.sql}
+      ORDER BY valid_from DESC, id DESC LIMIT 1`).get(retired.subject_entity_id, retired.predicate, retired.object_text, retired.valid_from, exports.LIFECYCLE_NOTE_PATH, ...inStream.params);
+    if (!prior)
+        return;
+    (0, factTerms_1.prepareOnce)(db, 'UPDATE facts SET valid_to = NULL, updated_at = ? WHERE id = ?').run(retired.updated_at, prior.id);
+}
+/** Puts a retired fact's row back into `facts` as it was. False when it is not retired. */
+function moveFactBack(db, eventId) {
+    const row = (0, factTerms_1.prepareOnce)(db, `SELECT ${FACT_COLUMNS}, retired_at FROM retired_facts WHERE event_id = ?`).get(eventId);
+    if (!row)
+        return false;
+    let validTo = row.valid_to;
+    if (validTo === null) {
+        // A later value anywhere in the same stream closes the retired one when it is saved (applyEvent), so this finds one
+        // only in an index written otherwise; it is resolved the same way, the later value staying current. The stream is
+        // the scope's slug, not one spelling of it (scopeSpellings): a value saved under project:alpha replaces a value
+        // retired under scope:alpha, so looking only at the row's own spelling left two current values in one stream.
+        const open = streamCurrentFacts(db, row.subject_entity_id, row.predicate, (0, scope_1.normalizeScope)(row.scope))[0];
+        if (open) {
+            if (open.object_text === row.object_text && open.valid_from < row.valid_from) {
+                // The older identical value was revived when this restatement was retired. Restoring the restatement keeps it
+                // as history instead of manufacturing a second current value or replacing the explicitly revived one.
+                validTo = row.retired_at;
+            }
+            else if (open.valid_from < row.valid_from) {
+                throw new Error(`cannot restore fact event ${eventId}: the current value (event ${open.event_id}) is older than it; rebuild the index from the ledger`);
+            }
+            else
+                validTo = open.valid_from;
+        }
+    }
+    (0, factTerms_1.prepareOnce)(db, `INSERT INTO facts (${FACT_COLUMNS}, source_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.id, row.subject_entity_id, row.predicate, row.object_text, row.confidence, row.valid_from, validTo, validTo === row.valid_to ? row.updated_at : validTo, row.event_id, row.scope, row.author, row.statement_words, exports.LIFECYCLE_NOTE_PATH);
+    (0, factTerms_1.indexFactTerms)(db, row.id, row.scope, { subject: (0, factTerms_1.canonicalSubject)(db, row.subject_entity_id), predicate: row.predicate, object: row.object_text });
+    (0, factTerms_1.prepareOnce)(db, 'DELETE FROM retired_facts WHERE id = ?').run(row.id);
+    return true;
+}
+/**
+ * Applies a retire or restore event. Every one is listed in fact_retirements, so a search never shows its ledger text.
+ * A replay leaves the ones it already applied to settleRetirements, which sets each fact to the state its LAST
+ * retirement event left it in; anything else moves the fact now. Moving a fact that is already where the event puts
+ * it changes nothing (a retry, or a replay over an index that already holds it); a target that is no fact is
+ * corruption.
+ */
+function applyRetirement(db, ev, digest, alreadyApplied) {
+    const target = ev.target.toUpperCase();
+    db.transaction(() => {
+        (0, factTerms_1.prepareOnce)(db, 'INSERT OR IGNORE INTO fact_retirements (event_id, kind, target, at, source) VALUES (?, ?, ?, ?, ?)')
+            .run(ev.id, ev.kind, target, ev.at, ev.source);
+        if (alreadyApplied)
+            return;
+        const moved = ev.kind === 'retire' ? moveFactOut(db, target, ev) : moveFactBack(db, target);
+        if (ev.kind === 'retire')
+            reviveIdenticalPredecessor(db, target);
+        const already = ev.kind === 'retire'
+            ? (0, factTerms_1.prepareOnce)(db, 'SELECT 1 FROM retired_facts WHERE event_id = ?').get(target)
+            : (0, factTerms_1.prepareOnce)(db, 'SELECT 1 FROM facts WHERE event_id = ?').get(target);
+        if (!moved && !already)
+            throw new Error(`ledger corruption in event ${ev.id}: its target ${target} is no saved fact`);
+        // The value stays out of the log, as it stays out of the event: memory_map lists this event.
+        (0, factTerms_1.prepareOnce)(db, 'INSERT INTO write_events (note_path, action, summary, created_at, author, scope) VALUES (?, ?, ?, ?, ?, ?)')
+            .run('_memory_ledger_', ev.kind, JSON.stringify({ id: `fact:${target}`, title: `${ev.subject} ${ev.predicate}` }), ev.at, ev.source, ev.scope ?? 'global');
+        (0, factTerms_1.prepareOnce)(db, 'INSERT OR REPLACE INTO applied_ledger_events (event_id, digest, applied_at) VALUES (?, ?, ?)')
+            .run(ev.id, digest, ev.at);
+    })();
+}
+/**
+ * After a replay: each fact the ledger retired or restored is where its last such event left it, and a fact retired in
+ * the index that the ledger never retired (its event was removed by hand) is back. Facts move whole, so the chain a
+ * replay just reconciled stays as it is.
+ */
+function settleRetirements(db, events) {
+    const last = new Map();
+    for (const ev of events)
+        if (RETIREMENT_KINDS.has(ev.kind))
+            last.set(ev.target.toUpperCase(), ev);
+    const retired = (0, factTerms_1.prepareOnce)(db, 'SELECT event_id FROM retired_facts').all();
+    db.transaction(() => {
+        for (const [target, ev] of last) {
+            if (ev.kind === 'retire') {
+                moveFactOut(db, target, ev);
+                reviveIdenticalPredecessor(db, target);
+            }
+            else
+                moveFactBack(db, target);
+        }
+        for (const { event_id } of retired)
+            if (!last.has(event_id))
+                moveFactBack(db, event_id);
+    })();
+}
+/** Replay the ledger into facts. Idempotent by event id + digest. Throws on corruption. */
+async function replayLedger(db, vaultPath, ledgerRelPath, options = {}) {
+    const filePath = resolveLedgerPath(vaultPath, ledgerRelPath); // shared confinement, before any read
+    let content;
+    let finalEventKnown = false;
+    try {
+        ({ content, finalEventKnown } = await readLedgerForReplay(vaultPath, filePath, eventId => (0, factTerms_1.prepareOnce)(db, 'SELECT 1 FROM applied_ledger_events WHERE event_id = ?').get(eventId) !== undefined, options.setTornTailAside === true));
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT') {
+            // Only an absent ledger means "known-new empty vault: nothing recorded yet".
+            // If the index already projects canonical events, the authoritative ledger
+            // is GONE — silently treating that as an empty vault would let startup go
+            // ready on a stale index whose source of truth no longer exists (and the
+            // next rebuild would wipe every canonical fact). Fail closed instead;
+            // recovery is restoring the ledger or deliberately wiping the derived
+            // index.
+            // ALL reliable evidence of prior canonical projection counts (Kimi K10 /
+            // Astra A3.1): digest rows, event_id-backed facts (a base-v5 DB carries
+            // these with an empty digest table — digests are only backfilled BY a
+            // successful replay, which needs the ledger), and lifecycle write_events.
+            const projected = (0, factTerms_1.prepareOnce)(db, 'SELECT COUNT(*) c FROM applied_ledger_events').get().c
+                + (0, factTerms_1.prepareOnce)(db, 'SELECT COUNT(*) c FROM facts WHERE event_id IS NOT NULL').get().c
+                + (0, factTerms_1.prepareOnce)(db, `SELECT COUNT(*) c FROM write_events WHERE note_path = '_memory_ledger_'`).get().c;
+            if (projected > 0) {
+                throw new Error(`ledger file is missing at ${filePath} but ${projected} canonical event(s) are already projected in the index; refusing to treat this as an empty vault — restore the ledger or deliberately rebuild from scratch`);
+            }
+            return 0;
+        }
+        // EISDIR / EACCES / EIO / anything else is a real I/O failure: block
+        // readiness (B7 fail-closed), never "replayed 0 events".
+        throw new Error(`ledger read failed (${err?.code ?? 'unknown'}) at ${filePath}: ${err?.message ?? err}`);
+    }
+    let applied = 0;
+    const events = parseLedgerEvents(content, { finalEventKnown });
+    // Canonical append order of the ledger (K12): the ONLY ordering input for
+    // reconciliation of already-projected streams. Byte-identical duplicate ids
+    // dedup and conflicting reuse throws in applyEvent; the first occurrence
+    // fixes each event's canonical position.
+    const positions = new Map();
+    // Each event's closed_event: reconciling a stream replays the facts closed across spellings (reconcileStreamCurrent).
+    const closedBy = new Map();
+    for (let i = 0; i < events.length; i++) {
+        if (positions.has(events[i].id))
+            continue;
+        positions.set(events[i].id, i);
+        const closed = events[i].closedEvent;
+        if (closed)
+            closedBy.set(events[i].id, closed.toUpperCase());
+        // A retirement names a fact event written before it.
+        const target = events[i].target?.toUpperCase();
+        if (target !== undefined) {
+            const at = positions.get(target);
+            if (at === undefined || RETIREMENT_KINDS.has(events[at].kind)) {
+                throw new Error(`ledger corruption in event ${events[i].id}: its target ${target} is no fact event before it in the ledger`);
+            }
+        }
+    }
+    // GLOBAL preflight (K13): every event-backed canonical projection in the
+    // index must be explainable by the COMPLETE parsed ledger — not just the
+    // streams this replay happens to touch. The stream-scoped refusal (re-home
+    // competition, per-stream reconcile) cannot see a stream whose ONLY event
+    // was removed from the ledger; such an orphaned row would survive as a
+    // served current fact with false ledger provenance, silently diverging from
+    // a clean rebuild of the identical ledger. Fail closed BEFORE any cache
+    // mutation, with the same explicit contradiction error as the stream-scoped
+    // checks. Unrelated (non '_mcp_') and NULL-event rows are not touched; no
+    // history is dropped or invented — the operator restores the ledger or
+    // deliberately rebuilds the derived index.
+    const projectedIds = (0, factTerms_1.prepareOnce)(db, `SELECT DISTINCT event_id FROM facts WHERE event_id IS NOT NULL AND source_path = '_mcp_'
+     UNION SELECT event_id FROM retired_facts`).all();
+    const orphaned = projectedIds
+        .map(r => r.event_id)
+        .filter(id => !positions.has(id.toUpperCase()));
+    if (orphaned.length > 0) {
+        const shown = orphaned.slice(0, 3).join(', ');
+        throw new Error(`index holds lifecycle facts for ${orphaned.length} event(s) absent from the ledger (${shown}${orphaned.length > 3 ? ', …' : ''}); refusing to guess canonical order — restore the ledger or deliberately rebuild the derived index`);
+    }
+    const index = replayEntityIndex(db);
+    for (const ev of events) {
+        if (applyEvent(db, ev, positions, index, closedBy).applied)
+            applied++;
+    }
+    settleRetirements(db, events);
+    backfillStatementWords(db, events);
+    return applied;
+}
+const STATEMENT_WORDS_BACKFILL = 'statement_words_backfilled';
+/**
+ * Facts saved before migration 25 have no `statement_words`, and replay skips their events (applied_ledger_events holds
+ * them), so the words are derived here once per database from the ledger event that saved each fact. This writes derived
+ * index rows only; the ledger is read, never written. Facts saved without a statement stay null.
+ */
+function backfillStatementWords(db, events) {
+    if ((0, factTerms_1.prepareOnce)(db, 'SELECT 1 FROM index_state WHERE key = ?').get(STATEMENT_WORDS_BACKFILL) !== undefined)
+        return;
+    const live = (0, factTerms_1.prepareOnce)(db, 'UPDATE facts SET statement_words = ? WHERE event_id = ? AND statement_words IS NULL');
+    const retired = (0, factTerms_1.prepareOnce)(db, 'UPDATE retired_facts SET statement_words = ? WHERE event_id = ? AND statement_words IS NULL');
+    for (const ev of events) {
+        const words = (0, factTerms_1.statementTerms)(ev.statement);
+        if (words === null)
+            continue;
+        live.run(words, ev.id);
+        retired.run(words, ev.id);
+    }
+    (0, factTerms_1.prepareOnce)(db, 'INSERT OR REPLACE INTO index_state (key, value) VALUES (?, ?)').run(STATEMENT_WORDS_BACKFILL, '1');
+}
+// In-process single-writer chain: serializes the full lifecycle decision +
+// ledger append + projection so concurrent remember() calls for the same (or
+// any) subject+predicate cannot interleave. Cross-process/crash durability
+// (OS-level writer lock, fsync barriers) is deliberately Gate 1B scope.
+let writeChain = Promise.resolve();
+function serializeLifecycleWrite(fn) {
+    const result = writeChain.then(fn, fn);
+    writeChain = result.then(() => undefined, () => undefined);
+    return result;
+}
+/** The principal write verb. Ledger-first, then SQLite. Idempotent on identical current value. */
+async function remember(db, vaultPath, ledgerRelPath, args) {
+    return serializeLifecycleWrite(() => rememberCritical(db, vaultPath, ledgerRelPath, args));
+}
+// A ledger larger than this is read and parsed whole on every repeat check, and nothing about it is kept.
+const MAX_REPEAT_LEDGER_BYTES = 256 * 1024;
+let repeatIndex;
+const sha256 = (bytes) => crypto_1.default.createHash('sha256').update(bytes).digest('hex');
+/** Keeps `events` as the index of the ledger's bytes, when a later append can be parsed on its own (the bytes end in a line break). */
+function keepRepeatIndex(file, content, events) {
+    const endsInLine = content.byteLength === 0 || content[content.byteLength - 1] === 0x0a;
+    repeatIndex = endsInLine ? { file, length: content.byteLength, digest: sha256(content), events } : undefined;
+}
+/**
+ * The first event with this id, as parseLedgerEvents over the whole ledger would give it. When the ledger still starts with
+ * the bytes it was parsed from, a write has only appended whole events since, so only those are parsed. Any other change,
+ * and any error in the appended part, parses the whole ledger, which raises what it always raised.
+ */
+function ledgerEventNamed(file, content, id) {
+    if (content.byteLength > MAX_REPEAT_LEDGER_BYTES) {
+        repeatIndex = undefined;
+        return parseLedgerEvents(content.toString('utf8')).find(e => e.id === id);
+    }
+    const held = repeatIndex;
+    if (held && held.file === file && held.length <= content.byteLength && sha256(content.subarray(0, held.length)) === held.digest) {
+        if (held.length === content.byteLength)
+            return held.events.get(id);
+        const appended = content.subarray(held.length).toString('utf8');
+        // The appended part must hold an event header, and must not open with a field line, which would belong to the last
+        // event already held. Then it parses exactly as it would at the end of the whole ledger.
+        if (/^## mem_/im.test(appended) && !appended.startsWith('- ')) {
+            try {
+                const events = held.events;
+                for (const e of parseLedgerEvents(appended))
+                    if (!events.has(e.id))
+                        events.set(e.id, e);
+                keepRepeatIndex(file, content, events);
+                return events.get(id);
+            }
+            catch {
+                // Parsed whole below, so the error is the one the whole ledger gives.
+            }
+        }
+    }
+    const events = new Map();
+    for (const e of parseLedgerEvents(content.toString('utf8')))
+        if (!events.has(e.id))
+            events.set(e.id, e);
+    keepRepeatIndex(file, content, events);
+    return events.get(id);
+}
+/**
+ * Does this write repeat the event behind the current fact, in everything the caller supplied?
+ *
+ * A caller that supplies the user's words must repeat them exactly as the current event holds them:
+ * the same statement, and the subject spelled the same. The entity lookup that found the current fact
+ * folds case and Unicode form, so on its own it would take `exactsubject` for a repeat of
+ * `ExactSubject` and the new spelling would never reach the ledger. A different sentence or spelling
+ * for the same value is still the user's own input, so it is written as a new event.
+ *
+ * A write without a statement (save_memory) has no words to keep and dedupes on the value alone.
+ * When the event cannot be read (a legacy fact written without one, an absent ledger) nothing can be
+ * confirmed, so the write goes ahead rather than assuming it is a repeat.
+ */
+async function repeatsCurrentEvent(vaultPath, ledgerRelPath, eventId, args) {
+    if (args.statement === undefined)
+        return true;
+    if (!eventId)
+        return false;
+    const file = resolveLedgerPath(vaultPath, ledgerRelPath);
+    let content;
+    try {
+        content = await promises_1.default.readFile(file);
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    // Always read first: the bytes say whether the events held from the last check are still the ledger's.
+    const event = ledgerEventNamed(file, content, eventId.toUpperCase());
+    return event !== undefined && event.subject === args.subject && event.statement === args.statement;
+}
+/**
+ * RENOR_SECRET_GUARD (default ON): refuse a write whose text looks like a secret, before the ledger or the
+ * index is touched. The subject, predicate and object are scanned as one line, "subject predicate: object",
+ * because a credential is usually stated across them (predicate wifi_password, object the password) and
+ * neither field carries the cue on its own.
+ */
+async function refuseSecrets(args) {
+    try {
+        await (0, secretGuard_1.assertStorable)([
+            { field: 'statement', text: args.statement },
+            { field: 'subject, predicate and object', text: `${args.subject} ${args.predicate}: ${args.object}` },
+            { field: 'source', text: args.source },
+        ]);
+    }
+    catch (err) {
+        // A refusal is the caller's input, like every rejection above it, so it leaves as a LifecycleInputError (4xx).
+        // A guard that could not decide is not: it stays the plain Error it is.
+        if (err instanceof secretGuard_1.SecretRefusedError && err.reason !== 'unavailable')
+            throw new LifecycleInputError(err.field, err.message);
+        throw err;
+    }
+}
+async function rememberCritical(db, vaultPath, ledgerRelPath, sent) {
+    // What is stored is the source's name, not what was sent (sourceName.ts): a path or a URL is cut down to what it ends in,
+    // a long name is cut and control characters are dropped, before anything is judged, so the checks below and the secret
+    // guard see the form that is stored and neither a long path nor a stray newline loses the whole save. A source with no
+    // name left in it (blank, or only separators or controls) is stored as the default, like one that was not sent. A source
+    // that is not a string is left for validateField. The import prefix is an import's alone (savedSource).
+    const args = typeof sent.source === 'string' ? { ...sent, source: (0, sourceName_1.savedSource)(sent.source) } : sent;
+    validateLifecycleInput(args);
+    refuseUnstorableFields(args);
+    if ((0, secretGuard_1.secretGuardEnabled)())
+        await refuseSecrets(args);
+    const at = new Date().toISOString();
+    const scope = (0, scope_1.normalizeScope)(args.scope);
+    // The source the event stores, and the writer the save is recorded under: the authenticated identity when the caller
+    // passed one, else the source itself. The event names the writer only where it differs from the source.
+    const source = args.source || 'agent';
+    const writer = args.writer ?? source;
+    // Current-value decision is made against the lifecycle-owned entity only,
+    // so a same-named disposable note entity can never influence or inherit it.
+    // Strict identity: a legacy split whose open currents disagree fails closed HERE,
+    // before the ledger append below, so the canonical bytes stay untouched.
+    const entityId = resolveLifecycleEntity(db, args.subject, at, false, { strict: true });
+    // The current value of the scope's stream, whatever spelling of the scope it was saved with (streamCurrentFacts).
+    const currents = entityId ? streamCurrentFacts(db, entityId, args.predicate, scope) : [];
+    // nochange only when nothing the caller said is new: the scope holds this value and no other AND, when they
+    // supply the user's words, the same subject spelling and statement as the current event (see repeatsCurrentEvent).
+    // A writer that owes a confirmation (its value was replaced) is recorded even when it repeats the current value: that
+    // save is the confirmation, and only the ledger keeps it.
+    if (currents.length > 0 && currents.every(c => c.object_text === args.object)
+        && !(currents[0].event_id !== null && (0, writerConflicts_1.hasOpenDisplacementBy)(db, currents[0].event_id, writer))
+        && await repeatsCurrentEvent(vaultPath, ledgerRelPath, currents[0].event_id, args)) {
+        return { ok: true, eventId: 'none', action: 'nochange', subject: args.subject, predicate: args.predicate, closed: null,
+            created: { factId: currents[0].id, object: args.object, validFrom: 'existing' }, ledger: resolveLedgerPath(vaultPath, ledgerRelPath) };
+    }
+    // What the write closes, as applyEvent closes it: the current value saved under the write's own spelling, and the
+    // one saved under the other spelling of the slug, which the event names in closed_event (a value with no event,
+    // written before the ledger, cannot be named: it stays current beside the new one, and a read names the conflict).
+    // A retired value keeps its place in the stream, so the write closes the retired current of either spelling too; only
+    // the one under the OTHER spelling is named in closed_event, because reconcileStreamCurrent closes the own-spelling
+    // one by order but cannot close a cross-spelling one without the name. The own-spelling retired value stays unnamed
+    // (the write is a 'store' when no live value was replaced), exactly as it was before scopes became one slug.
+    const own = currents.find(c => c.scope === scope);
+    const across = currents.find(c => c.scope !== scope && c.event_id != null);
+    const hiddens = entityId ? streamOpenRetiredFacts(db, entityId, args.predicate, scope) : [];
+    const named = across ?? hiddens.find(h => h.scope !== scope) ?? own;
+    // Pre-publish monotonicity validation (Kimi K11): the SAME rule the replay
+    // enforces, but checked BEFORE the ledger append. Without this, a transient
+    // backward clock step (NTP correction, manual clock change) made the live
+    // write throw AFTER the append — leaving the self-rejected event in the
+    // ledger and poisoning every future replay/rebuild/startup with the
+    // identical error. A write that would be rejected must never reach the
+    // ledger: the canonical bytes stay byte-identical on rejection.
+    // A retired value that was current under the write's spelling is closed by it too (applyEvent), by the same rule,
+    // and the stream is the scope's slug, so the retired current of either spelling is checked (streamOpenRetiredFacts).
+    // The refusal lasts while the clock stays behind the newest of them, so it names that instant: the wait the user has.
+    const behind = [own, across, ...hiddens].filter((c) => c !== undefined && at < c.valid_from);
+    if (behind.length > 0) {
+        const wait = behind.reduce((latest, c) => (c.valid_from > latest.valid_from ? c : latest));
+        throw new Error(`lifecycle write rejected without publishing: event time ${at} is older than the current fact (valid_from ${wait.valid_from}, fact id ${wait.id}) for the same subject+predicate. Writes are accepted again once the clock reaches ${wait.valid_from}. The ledger was not modified`);
+    }
+    const id = newEventId();
+    const kind = named ? 'supersede' : 'store';
+    const ev = {
+        id, at, kind,
+        subject: args.subject, predicate: args.predicate, object: args.object,
+        closedEvent: named?.event_id ?? null,
+        source,
+        scope,
+        ...(args.statement !== undefined ? { statement: args.statement } : {}),
+        ...(writer !== source ? { writer } : {}),
+    };
+    // Durable first: if the SQLite apply fails, the event is still in the ledger
+    // and the next replay repairs the index. The apply itself is one transaction,
+    // so it either fully lands or leaves no partial supersession behind.
+    const ledger = await appendLedgerEvent(vaultPath, ledgerRelPath, ev);
+    const { factId } = applyEvent(db, ev);
+    return {
+        ok: true, eventId: id, action: kind, subject: args.subject, predicate: args.predicate,
+        closed: named ? { factId: named.id, object: named.object_text, validTo: at } : null,
+        ...(across && own ? { alsoClosed: { factId: own.id, object: own.object_text, validTo: at } } : {}),
+        created: { factId, object: args.object, validFrom: at }, ledger,
+    };
+}
+const FACT_ID_RE = /^fact:(mem_[A-Za-z0-9]+)$/i;
+/** The event id in a fact id (`fact:MEM_…`), or null for any other memory id. */
+function factEventId(id) {
+    return FACT_ID_RE.exec(id)?.[1].toUpperCase() ?? null;
+}
+function factTitle(subject, predicate, object) {
+    return `${subject} ${predicate}: ${object}`;
+}
+/**
+ * Takes one saved fact out of recall, reversibly: a retire event goes into the ledger (who asked, when, and which fact),
+ * then the fact's row leaves `facts` (moveFactOut). The ledger keeps the fact's own event, so its history is never lost
+ * and restoreFact brings it back. Retiring the current value revives only the directly replaced value when its object is
+ * identical (a differently worded restatement); a genuinely different replaced value stays historical.
+ */
+async function retireFact(db, vaultPath, ledgerRelPath, id, source) {
+    return serializeLifecycleWrite(async () => {
+        const target = factEventId(id);
+        if (target === null)
+            throw new LifecycleInputError('id', `not a fact id: ${JSON.stringify(id)} (a fact's id is fact: and its eventId)`, 'invalid_argument');
+        const row = (0, factTerms_1.prepareOnce)(db, `SELECT f.predicate, f.object_text, f.valid_to, f.scope, e.canonical_name AS subject, e.source_note
+         FROM facts f JOIN entities e ON e.id = f.subject_entity_id
+        WHERE f.event_id = ? AND f.source_path = ?`).get(target, exports.LIFECYCLE_NOTE_PATH);
+        if (!row) {
+            if ((0, factTerms_1.prepareOnce)(db, 'SELECT 1 FROM retired_facts WHERE event_id = ?').get(target)) {
+                throw new LifecycleInputError('id', 'that fact is already retired (restore_memory brings it back)', 'memory_already_retired');
+            }
+            throw new LifecycleInputError('id', 'no saved fact has that id', 'memory_not_found');
+        }
+        // A startup replay moves every lifecycle fact onto its lifecycle subject, so this only refuses a fact that has not been.
+        if (row.source_note !== exports.LIFECYCLE_NOTE_PATH)
+            throw new Error(`fact ${target} is not attached to its lifecycle subject yet; restart the engine to replay the ledger first`);
+        const ev = {
+            id: newEventId(), at: new Date().toISOString(), kind: 'retire',
+            subject: row.subject, predicate: row.predicate, object: '', closedEvent: null,
+            source: (source === undefined ? '' : (0, sourceName_1.savedSource)(source)) || 'agent', scope: row.scope, target,
+        };
+        await appendLedgerEvent(vaultPath, ledgerRelPath, ev);
+        applyEvent(db, ev);
+        return { ok: true, id: `fact:${target}`, action: 'retired', title: factTitle(row.subject, row.predicate, row.object_text), at: ev.at, eventId: ev.id, current: row.valid_to === null };
+    });
+}
+/**
+ * Brings a retired fact back exactly as it was: the same row, value and dates. It is the current value again unless a
+ * value saved for the same subject, predicate and scope after it replaced it, as that save would have replaced it had it
+ * never been retired; it is then history. RENOR_SECRET_GUARD (default ON) screens it as a save.
+ */
+async function restoreFact(db, vaultPath, ledgerRelPath, id, source, validateAfterWrite) {
+    return serializeLifecycleWrite(async () => {
+        const target = factEventId(id);
+        if (target === null)
+            throw new LifecycleInputError('id', `not a fact id: ${JSON.stringify(id)} (a fact's id is fact: and its eventId)`, 'invalid_argument');
+        const row = (0, factTerms_1.prepareOnce)(db, `SELECT r.predicate, r.object_text, r.scope, e.canonical_name AS subject
+         FROM retired_facts r JOIN entities e ON e.id = r.subject_entity_id WHERE r.event_id = ?`).get(target);
+        if (!row) {
+            if ((0, factTerms_1.prepareOnce)(db, 'SELECT 1 FROM facts WHERE event_id = ?').get(target))
+                throw new LifecycleInputError('id', 'that fact is not retired', 'memory_not_found');
+            throw new LifecycleInputError('id', 'no retired fact has that id', 'memory_not_found');
+        }
+        if ((0, secretGuard_1.secretGuardEnabled)())
+            await refuseSecrets({ subject: row.subject, predicate: row.predicate, object: row.object_text });
+        const ev = {
+            id: newEventId(), at: new Date().toISOString(), kind: 'restore',
+            subject: row.subject, predicate: row.predicate, object: '', closedEvent: null,
+            source: (source === undefined ? '' : (0, sourceName_1.savedSource)(source)) || 'agent', scope: row.scope, target,
+        };
+        const ledgerPath = resolveLedgerPath(vaultPath, ledgerRelPath);
+        const priorBytes = await promises_1.default.stat(ledgerPath).then((stat) => stat.size, () => 0);
+        await appendLedgerEvent(vaultPath, ledgerRelPath, ev);
+        db.exec('SAVEPOINT restore_storage_limit');
+        try {
+            applyEvent(db, ev);
+            await validateAfterWrite?.();
+            db.exec('RELEASE SAVEPOINT restore_storage_limit');
+        }
+        catch (err) {
+            db.exec('ROLLBACK TO SAVEPOINT restore_storage_limit; RELEASE SAVEPOINT restore_storage_limit');
+            await promises_1.default.truncate(ledgerPath, priorBytes);
+            throw err;
+        }
+        const back = (0, factTerms_1.prepareOnce)(db, 'SELECT valid_to FROM facts WHERE event_id = ?').get(target);
+        return { ok: true, id: `fact:${target}`, action: 'restored', title: factTitle(row.subject, row.predicate, row.object_text), at: ev.at, eventId: ev.id, current: back.valid_to === null };
+    });
+}
+/** Every retired fact, newest retirement first. */
+function listRetiredFacts(db) {
+    const rows = (0, factTerms_1.prepareOnce)(db, `SELECT r.event_id, e.canonical_name AS subject, r.predicate, r.object_text, r.scope, r.valid_from, r.retired_at, r.retired_by
+       FROM retired_facts r JOIN entities e ON e.id = r.subject_entity_id
+      ORDER BY r.retired_at DESC, r.id DESC`).all();
+    return rows.map(r => ({
+        id: `fact:${r.event_id}`, eventId: r.event_id, subject: r.subject, predicate: r.predicate, object: r.object_text,
+        scope: r.scope, title: factTitle(r.subject, r.predicate, r.object_text), validFrom: r.valid_from,
+        retiredAt: r.retired_at, retiredBy: r.retired_by,
+    }));
+}
+/**
+ * The one scope a read is restricted to: the explicit scope, normalized (an empty one means global), or
+ * null for every scope. Every read path derives its filter here, so none can answer for a wider scope than
+ * it was asked about.
+ */
+function scopeFilterFor(scope) {
+    return scope !== undefined ? (0, scope_1.normalizeScope)(scope) : null;
+}
+/**
+ * Names of the subjects that lifecycle facts are about (current or superseded), alphabetical. Given a scope,
+ * only subjects that have a fact in that scope (any spelling of it, savedScopeSqlPredicate): a scoped read must
+ * not learn of subjects that live elsewhere.
+ */
+function listLifecycleSubjects(db, opts = {}) {
+    const scope = scopeFilterFor(opts.scope);
+    const inScope = scope === null ? null : (0, scope_1.savedScopeSqlPredicate)(scope, 'f.scope');
+    const rows = (0, factTerms_1.prepareOnce)(db, `SELECT DISTINCT e.canonical_name AS name FROM entities e
+      WHERE e.source_note = ?
+        AND EXISTS (SELECT 1 FROM facts f WHERE f.subject_entity_id = e.id${inScope ? ` AND ${inScope.sql}` : ''})
+      ORDER BY e.canonical_name COLLATE NOCASE`).all(exports.LIFECYCLE_NOTE_PATH, ...(inScope?.params ?? []));
+    return rows.map(r => r.name);
+}
+// A partial or path match on a lifecycle row names another subject: only the identity match in factsFor may name one.
+const NOT_LIFECYCLE_ENTITY = { sql: 'entities.source_note IS NOT ?', params: [exports.LIFECYCLE_NOTE_PATH] };
+/**
+ * The newest workspace observation in the scope being read. Lifecycle writes keep their stamps in facts and
+ * retired_facts; note indexing keeps its clock in note_index_clock, independently of rows that reindexing or
+ * retirement can delete. Their maximum survives retire/restore and backward-clock reindexing, including a
+ * workspace with no lifecycle writes. Index observations are not content dates: a future-dated note still keeps
+ * its valid_from/valid_to window. The migration seeds existing indexes from the indexer's updated_at stamps.
+ * Read once until the next database write, including a write by another connection (readUntilWrite).
+ */
+function workspaceReadInstant(db, scope) {
+    const cacheKey = `workspace-read-instant${scope === null ? '' : `:${scope}`}`;
+    return (0, readCache_1.readUntilWrite)(db, cacheKey, () => {
+        const inScope = scope === null ? null : (0, scope_1.savedScopeSqlPredicate)(scope, 'scope');
+        // Each observation source carries its own scope predicate and parameter spellings.
+        const scopeSql = inScope ? ` AND ${inScope.sql}` : '';
+        const scopeParams = inScope ? inScope.params : [];
+        return (0, factTerms_1.prepareOnce)(db, `SELECT MAX(newest) AS newest FROM (`
+            + ` SELECT valid_from AS newest FROM facts WHERE source_path = ?${scopeSql}`
+            + ` UNION ALL`
+            + ` SELECT valid_from AS newest FROM retired_facts${inScope ? ` WHERE ${inScope.sql}` : ''}`
+            + ` UNION ALL`
+            + ` SELECT observed_at AS newest FROM note_index_clock${inScope ? ` WHERE ${inScope.sql}` : ''}`
+            + `)`).get(exports.LIFECYCLE_NOTE_PATH, ...scopeParams, ...scopeParams, ...scopeParams)?.newest ?? null;
+    });
+}
+/**
+ * The instant a note-derived fact is judged at by the default read: the wall clock, or the newest workspace observation
+ * when that is newer. The workspace has already observed that instant, so the read judges the content-date window
+ * at the observation rather than losing the note to a regressed machine clock (workspaceReadInstant).
+ */
+function noteReadInstant(db, scope) {
+    const at = new Date().toISOString();
+    const newest = workspaceReadInstant(db, scope);
+    return newest !== null && newest > at ? newest : at;
+}
+/**
+ * The default read's currency rule, keyed on the row's origin. A lifecycle fact
+ * (source_path '_mcp_') is current exactly when it is open — the same rule the
+ * write path uses (streamCurrentFacts), so reads and writes agree after a
+ * backward clock step. A note-derived fact keeps its content-date window: a
+ * date in the future still means "not yet", but the window is bounded below by
+ * the newest workspace observation (workspaceReadInstant), so a machine clock that
+ * stepped backwards cannot hide a note the vault already holds.
+ * Two `?` parameters, the read instant, are the note-derived window bounds.
+ */
+const DEFAULT_CURRENT_SQL = `((source_path = '${exports.LIFECYCLE_NOTE_PATH}' AND valid_to IS NULL)`
+    + ` OR ((source_path IS NULL OR source_path <> '${exports.LIFECYCLE_NOTE_PATH}')`
+    + ` AND valid_from <= ? AND (valid_to IS NULL OR valid_to > ?)))`;
+/**
+ * Current facts only by default; asOf gives point-in-time; includeHistory gives
+ * everything. The default read judges a lifecycle fact by open rows (see
+ * DEFAULT_CURRENT_SQL), so a backward clock step cannot hide the current value;
+ * a note-derived fact is judged at the wall clock clamped up to the newest
+ * workspace observation (workspaceReadInstant), so the same step cannot hide it
+ * either; asOf keeps the exact point-in-time window. Lifecycle-owned facts are
+ * authoritative: if a lifecycle entity exists for the name, its facts are
+ * returned; otherwise the generic (possibly note-derived) entity lookup is used.
+ *
+ * When a name still matches SEVERAL lifecycle entities (a split a pre-fix write path
+ * could create, which nothing reconciles in place), facts from ALL of them are
+ * returned. A read must not throw — a startup or dashboard read would become an outage
+ * — and it must not hide half the memory behind a silent pick, so the ambiguity is
+ * disclosed instead. New writes refuse the same state (LegacyIdentityAmbiguityError).
+ */
+function factsFor(db, entityName, opts = {}) {
+    let entityIds = [];
+    for (const alias of (0, queryHelpers_1.identityNames)(entityName)) {
+        entityIds = lifecycleEntityMatches(db, alias).map(match => match.id);
+        if (entityIds.length > 0)
+            break;
+    }
+    if (entityIds.length === 0) {
+        const entity = (0, entityLookup_1.lookupEntity)(db, entityName, NOT_LIFECYCLE_ENTITY);
+        if (!entity)
+            return [];
+        entityIds = [entity.id];
+    }
+    const placeholders = entityIds.map(() => '?').join(',');
+    // Without scope: return across all scopes (current MVP read behavior).
+    // With scope: filter to that normalized scope, under any spelling of it (savedScopeSqlPredicate).
+    const scopeFilter = scopeFilterFor(opts.scope);
+    const inScope = scopeFilter ? (0, scope_1.savedScopeSqlPredicate)(scopeFilter, 'scope') : null;
+    if (opts.includeHistory) {
+        if (inScope) {
+            return db.prepare(`SELECT * FROM facts WHERE subject_entity_id IN (${placeholders}) AND ${inScope.sql} ORDER BY valid_from DESC, id DESC`).all(...entityIds, ...inScope.params);
+        }
+        return db.prepare(`SELECT * FROM facts WHERE subject_entity_id IN (${placeholders}) ORDER BY valid_from DESC, id DESC`).all(...entityIds);
+    }
+    // S1: asOf is an INSTANT. It is normalized to the canonical format so the
+    // SQL textual comparison is exactly the instant comparison for every
+    // supported input (including offsets); garbage fails with a clear error
+    // instead of a silently wrong answer. An explicit point-in-time read keeps
+    // the window unchanged: it asks what was true AT that instant, not what is
+    // true now.
+    if (opts.asOf !== undefined) {
+        const t = toCanonicalInstant(opts.asOf);
+        if (inScope) {
+            return (0, factTerms_1.prepareOnce)(db, `SELECT * FROM facts WHERE subject_entity_id IN (${placeholders}) AND ${inScope.sql} AND valid_from <= ? AND (valid_to IS NULL OR valid_to > ?) ORDER BY valid_from DESC, id DESC`).all(...entityIds, ...inScope.params, t, t);
+        }
+        return (0, factTerms_1.prepareOnce)(db, `SELECT * FROM facts WHERE subject_entity_id IN (${placeholders}) AND valid_from <= ? AND (valid_to IS NULL OR valid_to > ?) ORDER BY valid_from DESC, id DESC`).all(...entityIds, t, t);
+    }
+    // The default read judges a lifecycle fact (source_path '_mcp_') the way the
+    // write path does (streamCurrentFacts): current exactly when it is open, so a
+    // backward clock step can never hide the value the user already gave — the
+    // repeat-twice failure. Note-derived facts keep their content-date window — a
+    // future date still means "not yet" — bounded below by the newest workspace
+    // observation, so the same step cannot hide a note the vault already holds either.
+    const readInstant = noteReadInstant(db, scopeFilter);
+    if (inScope) {
+        return (0, factTerms_1.prepareOnce)(db, `SELECT * FROM facts WHERE subject_entity_id IN (${placeholders}) AND ${inScope.sql} AND ${DEFAULT_CURRENT_SQL} ORDER BY valid_from DESC, id DESC`).all(...entityIds, ...inScope.params, readInstant, readInstant);
+    }
+    return (0, factTerms_1.prepareOnce)(db, `SELECT * FROM facts WHERE subject_entity_id IN (${placeholders}) AND ${DEFAULT_CURRENT_SQL} ORDER BY valid_from DESC, id DESC`).all(...entityIds, readInstant, readInstant);
+}