renor-engine 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/LICENSE +202 -661
  2. package/NOTICE +8 -6
  3. package/README.md +13 -8
  4. package/dist/.tsbuildinfo +1 -0
  5. package/dist/api/server.js +10 -8
  6. package/dist/buildIdentity.js +18 -1
  7. package/dist/callPhases.js +82 -0
  8. package/dist/cli.js +36 -1
  9. package/dist/context/rowStore.js +1 -1
  10. package/dist/conversation/parser.js +40 -36
  11. package/dist/db/client.js +6 -4
  12. package/dist/db/handoffTable.js +31 -0
  13. package/dist/db/indexSalvage.js +24 -4
  14. package/dist/db/migrations.js +30 -2
  15. package/dist/db/sqlite.js +396 -0
  16. package/dist/digests/digestCache.js +6 -2
  17. package/dist/digests/digests.js +3 -3
  18. package/dist/digests/worker.js +3 -1
  19. package/dist/embeddings/caching.js +5 -5
  20. package/dist/embeddings/local.js +5 -3
  21. package/dist/embeddings/openai.js +4 -3
  22. package/dist/embeddings/simdScan.js +3 -1
  23. package/dist/embeddings/vectorIndex.js +0 -1
  24. package/dist/embeddings/vertex.js +123 -13
  25. package/dist/eval/cacheReport.js +7 -0
  26. package/dist/eval/context700-candidate.js +5 -5
  27. package/dist/eval/evalCache.js +46 -3
  28. package/dist/eval/indexSnapshots.js +549 -0
  29. package/dist/eval/pageDump.js +67 -0
  30. package/dist/eval/runManifest.js +6 -0
  31. package/dist/eval/textTokens.js +17 -0
  32. package/dist/evidence/attach.js +0 -3
  33. package/dist/evidence/evidenceCache.js +3 -3
  34. package/dist/evidence/ollamaChat.js +1 -1
  35. package/dist/evidence/options.js +46 -25
  36. package/dist/evidence/secondPass.js +8 -170
  37. package/dist/extraction/factExtractor.js +1 -1
  38. package/dist/extraction/jevDecisionModel.js +307 -0
  39. package/dist/extraction/preferenceExtractor.js +1 -4
  40. package/dist/extraction/secretGuard.js +7 -3
  41. package/dist/extraction/typedFacts.js +1 -1
  42. package/dist/importing/apply.js +42 -14
  43. package/dist/importing/cli.js +9 -8
  44. package/dist/importing/existing.js +2 -0
  45. package/dist/importing/facts.js +0 -2
  46. package/dist/importing/plan.js +0 -5
  47. package/dist/importing/source.js +1 -1
  48. package/dist/indexer/parser.js +4 -1
  49. package/dist/indexer/pipeline.js +99 -279
  50. package/dist/indexer/walker.js +11 -25
  51. package/dist/learning/cli.js +113 -0
  52. package/dist/learning/schema.js +144 -0
  53. package/dist/learning/settings.js +45 -0
  54. package/dist/learning/store.js +267 -0
  55. package/dist/learning/tap.js +401 -0
  56. package/dist/mcp/server.js +36 -6
  57. package/dist/memory/dreamer/adjudicate.js +215 -0
  58. package/dist/memory/dreamer/apply.js +120 -0
  59. package/dist/memory/dreamer/budget.js +64 -0
  60. package/dist/memory/dreamer/candidates.js +149 -0
  61. package/dist/memory/dreamer/collection.js +104 -0
  62. package/dist/memory/dreamer/dreamer.js +352 -0
  63. package/dist/memory/dreamer/review.js +111 -0
  64. package/dist/memory/factConflicts.js +2 -0
  65. package/dist/memory/handoff.js +363 -0
  66. package/dist/memory/lifecycle.js +338 -80
  67. package/dist/memory/sourceName.js +77 -1
  68. package/dist/memory/statusFacts.js +61 -0
  69. package/dist/memory/writer.js +3 -2
  70. package/dist/memorymap/memoryMap.js +39 -13
  71. package/dist/memorymap/replacements.js +8 -3
  72. package/dist/mvp/agentMemory.js +109 -50
  73. package/dist/mvp/answerCheck.js +211 -0
  74. package/dist/mvp/cli.js +14 -1
  75. package/dist/mvp/compileCache.js +3 -10
  76. package/dist/mvp/compileSeed.js +9 -3
  77. package/dist/mvp/config.js +4 -0
  78. package/dist/mvp/contextDistinct.js +53 -0
  79. package/dist/mvp/contextProfile.js +87 -0
  80. package/dist/mvp/directorySurface.js +68 -0
  81. package/dist/mvp/engine.js +39 -26
  82. package/dist/mvp/exportAll.js +36 -2
  83. package/dist/mvp/factMarkers.js +18 -2
  84. package/dist/mvp/history.js +5 -4
  85. package/dist/mvp/log.js +118 -0
  86. package/dist/mvp/server.js +759 -136
  87. package/dist/mvp/serverCard.js +12 -3
  88. package/dist/mvp/telemetry.js +35 -2
  89. package/dist/net/poolFetch.js +174 -0
  90. package/dist/recall/actionRecall.js +282 -0
  91. package/dist/recall/autoRecall.js +447 -0
  92. package/dist/recall/searchRecall.js +189 -0
  93. package/dist/retrieval/entityLookup.js +53 -4
  94. package/dist/retrieval/orchestrator.js +148 -10
  95. package/dist/retrieval/plainWording.js +236 -0
  96. package/dist/retrieval/rankingTrace.js +184 -0
  97. package/dist/retrieval/readerLayout.js +143 -224
  98. package/dist/router/routerCache.js +2 -2
  99. package/dist/sharing/cli.js +181 -0
  100. package/dist/sharing/examples.js +136 -0
  101. package/dist/sharing/fields.js +225 -0
  102. package/dist/sharing/loop.js +80 -0
  103. package/dist/sharing/project.js +327 -0
  104. package/dist/sharing/send.js +466 -0
  105. package/dist/sharing/state.js +222 -0
  106. package/dist/sharing/wording.js +48 -0
  107. package/dist/watcher/watcher.js +5 -3
  108. package/package.json +5 -7
  109. package/dist/BUILD.json +0 -6
  110. package/dist/importing/index.js +0 -29
@@ -3,13 +3,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.LegacyIdentityAmbiguityError = exports.LifecycleInputError = exports.FIELD_LIMITS = exports.DEFAULT_LEDGER_REL = exports.LIFECYCLE_NOTE_PATH = void 0;
6
+ exports.LegacyIdentityAmbiguityError = exports.StaleExpectationError = exports.LifecycleInputError = exports.FIELD_LIMITS = exports.DEFAULT_LEDGER_REL = exports.LIFECYCLE_NOTE_PATH = void 0;
7
7
  exports.resolveLedgerPath = resolveLedgerPath;
8
8
  exports.appendLedgerEvent = appendLedgerEvent;
9
9
  exports.unterminatedFinalEventStart = unterminatedFinalEventStart;
10
10
  exports.parseLedgerEvents = parseLedgerEvents;
11
11
  exports.replayLedger = replayLedger;
12
12
  exports.remember = remember;
13
+ exports.eraseRetiredFact = eraseRetiredFact;
13
14
  exports.factEventId = factEventId;
14
15
  exports.retireFact = retireFact;
15
16
  exports.restoreFact = restoreFact;
@@ -32,8 +33,12 @@ const invisibleText_1 = require("./invisibleText");
32
33
  const sourceName_1 = require("./sourceName");
33
34
  const writerConflicts_1 = require("./writerConflicts");
34
35
  const durableAppend_1 = require("./durableAppend");
36
+ const writer_1 = require("./writer");
35
37
  const secretGuard_1 = require("../extraction/secretGuard");
38
+ const jevDecisionModel_1 = require("../extraction/jevDecisionModel");
36
39
  const toolRefusal_1 = require("../toolRefusal");
40
+ const log_1 = require("../mvp/log");
41
+ const log = (0, log_1.createLogger)('engine');
37
42
  /** Reserved synthetic note path owning lifecycle entities (never a real vault file). */
38
43
  exports.LIFECYCLE_NOTE_PATH = '_mcp_';
39
44
  /** Default relative ledger path inside the vault. */
@@ -44,7 +49,7 @@ const EVENT_HEADER_RE = /^## (mem_[A-Za-z0-9]+) · (.+?)[ \t]*$/i;
44
49
  // `.` otherwise refuses U+2028/U+2029 (and a lone \r), which JavaScript calls line terminators and this
45
50
  // ledger does not: one such character in a value used to make the whole ledger unreadable at startup.
46
51
  const FIELD_RE = /^- ([A-Za-z][\w-]*): (.*)$/s;
47
- const KNOWN_FIELDS = new Set(['kind', 'subject', 'predicate', 'object', 'closed_event', 'source', 'scope', 'statement', 'writer', 'target']);
52
+ const KNOWN_FIELDS = new Set(['kind', 'subject', 'predicate', 'object', 'closed_event', 'source', 'scope', 'statement', 'writer', 'target', 'original_digest', 'closes', 'closed_at']);
48
53
  const REQUIRED_FIELDS = ['subject', 'predicate', 'object'];
49
54
  /**
50
55
  * retire takes one fact out of recall and restore brings it back (retireFact, restoreFact). Each names the fact's own
@@ -53,7 +58,8 @@ const REQUIRED_FIELDS = ['subject', 'predicate', 'object'];
53
58
  * is written.
54
59
  */
55
60
  const RETIREMENT_KINDS = new Set(['retire', 'restore']);
56
- const KNOWN_KINDS = new Set(['store', 'supersede', ...RETIREMENT_KINDS]);
61
+ const ERASE_KIND = 'erase';
62
+ const KNOWN_KINDS = new Set(['store', 'supersede', ...RETIREMENT_KINDS, ERASE_KIND]);
57
63
  const CONTROL_CHARS = /[\u0000-\u001F\u007F]/;
58
64
  exports.FIELD_LIMITS = { subject: 512, predicate: 256, object: 8192, source: 256, scope: 80, statement: limits_1.MAX_STATEMENT_LENGTH, writer: 256 };
59
65
  /**
@@ -127,6 +133,22 @@ class LifecycleInputError extends Error {
127
133
  }
128
134
  }
129
135
  exports.LifecycleInputError = LifecycleInputError;
136
+ /**
137
+ * A write that named the event it expected to close found a different current fact (or none). Nothing was written.
138
+ * Only a caller that asks for the check (`expectCurrentEvent`) can get it: the dreamer, which decides on one reading of
139
+ * the facts and must not overwrite what an agent saved meanwhile.
140
+ */
141
+ class StaleExpectationError extends Error {
142
+ expected;
143
+ found;
144
+ constructor(expected, found) {
145
+ super(`lifecycle write refused without publishing: the current fact is no longer the one the caller judged (expected event ${expected ?? 'none'}, found ${found ?? 'none'}). The ledger was not modified`);
146
+ this.name = 'StaleExpectationError';
147
+ this.expected = expected;
148
+ this.found = found;
149
+ }
150
+ }
151
+ exports.StaleExpectationError = StaleExpectationError;
130
152
  /** The received type, spelled the way JSON Schema spells it, for error messages. */
131
153
  function describeType(value) {
132
154
  if (value === null)
@@ -243,6 +265,24 @@ function validateLedgerEvent(ev) {
243
265
  }
244
266
  if (!KNOWN_KINDS.has(ev.kind))
245
267
  throw new Error(`ledger corruption in event ${ev.id}: unknown kind "${ev.kind}"`);
268
+ if (ev.kind === ERASE_KIND) {
269
+ if (!/^[0-9a-f]{64}$/.test(ev.originalDigest ?? ''))
270
+ throw new Error(`ledger corruption in event ${ev.id}: an erase tombstone needs the original event digest`);
271
+ if (ev.subject || ev.predicate || ev.object || ev.statement !== undefined || ev.writer !== undefined || ev.target !== undefined || ev.closedEvent !== null || ev.source !== 'erased') {
272
+ throw new Error(`ledger corruption in event ${ev.id}: an erase tombstone carries no memory content`);
273
+ }
274
+ // The closing link is ids and a time, both checked, so it cannot carry text either.
275
+ if ((ev.closes === undefined) !== (ev.closedAt === undefined))
276
+ throw new Error(`ledger corruption in event ${ev.id}: an erase tombstone's closes and closed_at go together`);
277
+ if (ev.closes !== undefined) {
278
+ if (ev.closes.length === 0 || ev.closes.some(id => !/^MEM_[A-Z0-9]+$/.test(id)))
279
+ throw new Error(`ledger corruption in event ${ev.id}: an erase tombstone closes event ids only`);
280
+ if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(ev.closedAt) || new Date(ev.closedAt).toISOString() !== ev.closedAt) {
281
+ throw new Error(`ledger corruption in event ${ev.id}: an erase tombstone's closed_at is not an exact UTC ISO time`);
282
+ }
283
+ }
284
+ return;
285
+ }
246
286
  const retirement = RETIREMENT_KINDS.has(ev.kind);
247
287
  validateField('subject', ev.subject, true);
248
288
  validateField('predicate', ev.predicate, true);
@@ -283,6 +323,8 @@ function validateLedgerEvent(ev) {
283
323
  }
284
324
  }
285
325
  function eventDigest(ev) {
326
+ if (ev.kind === ERASE_KIND)
327
+ return ev.originalDigest;
286
328
  const parts = [
287
329
  ev.id, ev.at, ev.kind, ev.subject, ev.predicate, ev.object, ev.closedEvent ?? '', ev.source ?? 'ledger',
288
330
  ];
@@ -357,31 +399,14 @@ function resolveLedgerPath(vaultPath, ledgerRelPath) {
357
399
  }
358
400
  async function appendLedgerEvent(vaultPath, ledgerRelPath, ev) {
359
401
  validateLedgerEvent(ev);
402
+ // An erasure is a rewrite of the whole ledger (eraseRetiredFact), never an append.
403
+ if (ev.kind === ERASE_KIND)
404
+ throw new Error(`ledger event ${ev.id}: an erase tombstone is written only by erasing a retired fact`);
360
405
  const resolved = resolveLedgerPath(vaultPath, ledgerRelPath);
361
- const lines = [
362
- `\n## ${ev.id} · ${ev.at}`,
363
- `- kind: ${ev.kind}`,
364
- `- subject: ${ev.subject}`,
365
- `- predicate: ${ev.predicate}`,
366
- ];
367
- if (ev.target !== undefined)
368
- lines.push(`- target: ${ev.target}`);
369
- else
370
- lines.push(`- object: ${ev.object}`);
371
- if (ev.closedEvent)
372
- lines.push(`- closed_event: ${ev.closedEvent}`);
373
- const scope = (0, scope_1.normalizeScope)(ev.scope);
374
- if (scope !== 'global')
375
- lines.push(`- scope: ${scope}`);
376
- if (ev.statement !== undefined)
377
- lines.push(`- statement: ${encodeStatement(ev.statement)}`);
378
- if (ev.writer !== undefined)
379
- lines.push(`- writer: ${ev.writer}`);
380
- lines.push(`- source: ${ev.source}`, ``);
381
406
  // Confined and durable in one append (confinedWrite.ts): a link, a hard link or a FIFO planted in the vault is refused,
382
407
  // never followed, and a failed write is cut back, so the ledger never keeps a fragment of an event whose save the caller
383
408
  // was told failed. A new ledger starts with its header.
384
- await (0, confinedWrite_1.appendConfined)(vaultPath, path_1.default.relative(path_1.default.resolve(vaultPath), resolved), lines.join('\n'), LEDGER_HEADER);
409
+ await (0, confinedWrite_1.appendConfined)(vaultPath, path_1.default.relative(path_1.default.resolve(vaultPath), resolved), ledgerEventBlock(ev), LEDGER_HEADER);
385
410
  return resolved;
386
411
  }
387
412
  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`;
@@ -475,7 +500,13 @@ async function moveTornTailAside(vaultPath, relFile, ledger, bytes, offset) {
475
500
  }
476
501
  await ledger.truncate(offset);
477
502
  await ledger.sync();
478
- 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.`);
503
+ log.error('ledger_tail_set_aside', {
504
+ ledger: relFile,
505
+ bytes: tornBytes.length,
506
+ movedTo: path_1.default.relative(vaultPath, tornPath),
507
+ detail: 'the final event was cut short (a crash or a full disk); every complete event was kept',
508
+ remedy: 'a hand-written event never replayed: add its `- source:` line and a final newline (if it has none), append its bytes to the ledger and restart; a block still without that line is set aside again',
509
+ });
479
510
  }
480
511
  /**
481
512
  * The ledger's text for replay, and whether its unterminated final event (if any) is one the index already holds. An
@@ -500,6 +531,23 @@ async function readLedgerForReplay(vaultPath, filePath, isProjected, setTornTail
500
531
  return { content: again.subarray(0, now.offset).toString('utf8'), finalEventKnown: false };
501
532
  }));
502
533
  }
534
+ /** Remove private rewrite files left by a process that died before replacing the ledger. */
535
+ async function removeStaleEraseTemps(filePath) {
536
+ const dir = path_1.default.dirname(filePath);
537
+ const prefix = `${path_1.default.basename(filePath)}.erase-`;
538
+ let names;
539
+ try {
540
+ names = await promises_1.default.readdir(dir);
541
+ }
542
+ catch (err) {
543
+ if (err.code === 'ENOENT')
544
+ return;
545
+ throw err;
546
+ }
547
+ await Promise.all(names
548
+ .filter(name => name.startsWith(prefix) && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.tmp$/i.test(name.slice(prefix.length)))
549
+ .map(name => promises_1.default.rm(path_1.default.join(dir, name), { force: true })));
550
+ }
503
551
  /**
504
552
  * Strict line-oriented parser for the ledger format. Returns the events in
505
553
  * append order. Throws (never silently skips) on event-shaped corruption:
@@ -555,6 +603,8 @@ function parseLedgerEvents(content, options = {}) {
555
603
  }
556
604
  const kind = fields.kind ?? 'store';
557
605
  for (const req of REQUIRED_FIELDS) {
606
+ if (kind === ERASE_KIND)
607
+ continue;
558
608
  if (req === 'object' && RETIREMENT_KINDS.has(kind))
559
609
  continue; // a retirement carries no value
560
610
  if (fields[req] === undefined || fields[req] === '') {
@@ -565,6 +615,9 @@ function parseLedgerEvents(content, options = {}) {
565
615
  id, at,
566
616
  ...(fields.statement !== undefined ? { statement: decodeStatement(fields.statement, id) } : {}),
567
617
  ...(fields.target !== undefined ? { target: fields.target } : {}),
618
+ ...(fields.original_digest !== undefined ? { originalDigest: fields.original_digest } : {}),
619
+ ...(fields.closes !== undefined ? { closes: fields.closes.split(',').map(part => part.trim().toUpperCase()) } : {}),
620
+ ...(fields.closed_at !== undefined ? { closedAt: fields.closed_at } : {}),
568
621
  kind,
569
622
  subject: fields.subject,
570
623
  predicate: fields.predicate,
@@ -853,35 +906,11 @@ function requireLedgerPosition(positions, eventId) {
853
906
  }
854
907
  return pos;
855
908
  }
856
- /**
857
- * Canonical stream reconciliation (K12): recompute the current/valid_to chain
858
- * for every event-backed lifecycle fact of (lifecycle entity, predicate) from
859
- * the CANONICAL ledger positions, exactly mirroring what a fresh in-order
860
- * replay produces — the event that appears latest in the ledger is the
861
- * current fact; each earlier event's row is closed at its canonical
862
- * successor's valid_from (never before its own valid_from, so no negative
863
- * intervals). Stale winner flags left behind by earlier candidate reconciliations
864
- * (including migration 6's interim duplicate repair, which cannot read the
865
- * ledger) are repaired here, before readiness. Non-event-backed open rows are
866
- * non-canonical (base vault_store_fact bypassed the ledger): they are closed
867
- * at the start of the canonical record and KEPT in history — never dropped.
868
- * Event-backed rows whose event is absent from the ledger are an
869
- * index-vs-ledger contradiction and fail explicitly. Unrelated (non '_mcp_')
870
- * facts are not touched. Idempotent: re-running produces no further writes.
871
- *
872
- * The stream is the scope's slug (streamCurrentFacts): the rows of every
873
- * spelling are replayed together, in ledger order, as applyEvent applies them.
874
- * Each event closes the current row of its own spelling and the row its
875
- * closed_event names under another spelling (currentFactClosedAcrossSpellings;
876
- * `closedBy` holds each event's closed_event). Without such a link the
877
- * spellings never touch, so each spelling's chain is exactly the per-spelling
878
- * chain this function computed before scopes were one slug.
879
- */
880
- function reconcileStreamCurrent(db, lifecycleId, predicate, positions, scope = 'global', closedBy = new Map()) {
881
- (0, statements_1.transactionOnce)(db, reconcileStreamCurrentBody)(lifecycleId, predicate, positions, scope, closedBy);
909
+ function reconcileStreamCurrent(db, lifecycleId, predicate, positions, scope = 'global', closedBy = new Map(), closers = new Map()) {
910
+ (0, statements_1.transactionOnce)(db, reconcileStreamCurrentBody)(lifecycleId, predicate, positions, scope, closedBy, closers);
882
911
  }
883
912
  /** The body of reconcileStreamCurrent's transaction: a module-level function so replay wraps it once per connection (transactionOnce). */
884
- function reconcileStreamCurrentBody(db, lifecycleId, predicate, positions, scope, closedBy) {
913
+ function reconcileStreamCurrentBody(db, lifecycleId, predicate, positions, scope, closedBy, closers) {
885
914
  const inStream = (0, scope_1.savedScopeSqlPredicate)(scope, 'scope');
886
915
  // A retired fact keeps its place in the stream (retireFact): it is hidden, not undone, so the value it closed stays
887
916
  // closed and the value saved after it closes it, exactly as if it had never been retired.
@@ -906,7 +935,25 @@ function reconcileStreamCurrentBody(db, lifecycleId, predicate, positions, scope
906
935
  // a state a fresh replay could not produce. (Equal timestamps are legal.)
907
936
  const current = new Map();
908
937
  const closeAt = new Map();
909
- for (const row of canonical) {
938
+ // An erased fact has no row any more, but at its place in the ledger it still closes what it closed, at its own time, as a
939
+ // fresh replay of its tombstone does (applyEvent); it never becomes current itself.
940
+ const inChain = new Set(canonical.map(row => row.event_id));
941
+ const links = [...closers]
942
+ .filter(([id, link]) => positions.has(id) && link.closes.some(closed => inChain.has(closed)))
943
+ .map(([id, link]) => ({ pos: positions.get(id), ...link }));
944
+ const steps = [...canonical.map(row => ({ pos: row.pos, row })), ...links.map(link => ({ pos: link.pos, link }))]
945
+ .sort((x, y) => x.pos - y.pos);
946
+ for (const step of steps) {
947
+ if ('link' in step) {
948
+ for (const [spelling, open] of [...current]) {
949
+ if (!step.link.closes.includes(open.event_id))
950
+ continue;
951
+ closeAt.set(open.id, maxInstant(step.link.closedAt, open.valid_from));
952
+ current.delete(spelling);
953
+ }
954
+ continue;
955
+ }
956
+ const row = step.row;
910
957
  const named = closedBy.get(row.event_id);
911
958
  const across = named === undefined ? undefined
912
959
  : [...current.values()].find(r => r.scope !== row.scope && r.event_id === named);
@@ -951,14 +998,14 @@ function reconcileStreamCurrentBody(db, lifecycleId, predicate, positions, scope
951
998
  * The transaction applyEvent runs for an event that is already projected: re-home a fact still attached to a disposable entity,
952
999
  * then reconcile its stream. A module-level function so replay wraps it once per connection (transactionOnce).
953
1000
  */
954
- function reconcileProjectedEvent(db, ev, factId, rehome, positions, lifecycleId, closedBy) {
1001
+ function reconcileProjectedEvent(db, ev, factId, rehome, positions, lifecycleId, closedBy, closers) {
955
1002
  if (rehome) {
956
1003
  rehomeLifecycleFact(db, ev, factId, positions, lifecycleId);
957
1004
  }
958
1005
  // Do not preserve stale winner/valid_to flags merely because the event
959
1006
  // is already projected: recompute the chain from canonical ledger order
960
1007
  // so the upgraded cache is equivalent to a fresh replay of the ledger.
961
- reconcileStreamCurrent(db, lifecycleId, ev.predicate, positions, (0, scope_1.normalizeScope)(ev.scope), closedBy);
1008
+ reconcileStreamCurrent(db, lifecycleId, ev.predicate, positions, (0, scope_1.normalizeScope)(ev.scope), closedBy, closers);
962
1009
  }
963
1010
  /**
964
1011
  * Apply one memory event to SQLite inside a single transaction:
@@ -966,13 +1013,72 @@ function reconcileProjectedEvent(db, ev, factId, rehome, positions, lifecycleId,
966
1013
  * Idempotent by event id + digest; a reused id with a conflicting payload is
967
1014
  * explicit corruption; a failed insert can never leave a partial supersession.
968
1015
  */
969
- function applyEvent(db, ev, positions, index, closedBy) {
1016
+ function applyEvent(db, ev, positions, index, closedBy, closers) {
970
1017
  validateLedgerEvent(ev);
971
1018
  const digest = eventDigest(ev);
972
1019
  const seen = (0, factTerms_1.prepareOnce)(db, 'SELECT digest FROM applied_ledger_events WHERE event_id = ?').get(ev.id);
973
1020
  if (seen && seen.digest !== digest) {
974
1021
  throw new Error(`ledger event id ${ev.id} was reused with a conflicting payload; refusing to apply (corruption)`);
975
1022
  }
1023
+ if (ev.kind === ERASE_KIND) {
1024
+ db.transaction(() => {
1025
+ const entityIds = db.prepare('SELECT subject_entity_id FROM facts WHERE event_id = ? UNION SELECT subject_entity_id FROM retired_facts WHERE event_id = ?')
1026
+ .pluck().all(ev.id, ev.id);
1027
+ const ids = db.prepare('SELECT id FROM facts WHERE event_id = ? UNION SELECT id FROM retired_facts WHERE event_id = ?')
1028
+ .all(ev.id, ev.id);
1029
+ // The erased value can also live on in the writer conflicts (writerConflicts.ts): a later fact that replaced it keeps
1030
+ // it as an open displacement, carried forward by its writer's next saves. Drop those and the erased fact's own row.
1031
+ const gone = db.prepare('SELECT object_text, valid_from, author FROM facts WHERE event_id = ? UNION SELECT object_text, valid_from, author FROM retired_facts WHERE event_id = ?')
1032
+ .get(ev.id, ev.id);
1033
+ if (gone) {
1034
+ const goneWriter = (0, writerConflicts_1.writerOf)(db, ev.id, gone.author).writer;
1035
+ const rows = db.prepare(`SELECT event_id, displaced FROM fact_writers WHERE displaced <> '[]'`).all();
1036
+ for (const row of rows) {
1037
+ const displaced = JSON.parse(row.displaced);
1038
+ const kept = displaced.filter(d => !(d.object === gone.object_text && d.validFrom === gone.valid_from && d.writer === goneWriter));
1039
+ if (kept.length !== displaced.length)
1040
+ db.prepare('UPDATE fact_writers SET displaced = ? WHERE event_id = ?').run(JSON.stringify(kept), row.event_id);
1041
+ }
1042
+ }
1043
+ db.prepare('DELETE FROM fact_writers WHERE event_id = ?').run(ev.id);
1044
+ for (const row of ids)
1045
+ db.prepare('DELETE FROM fact_terms WHERE fact_id = ?').run(row.id);
1046
+ db.prepare('DELETE FROM facts WHERE event_id = ?').run(ev.id);
1047
+ db.prepare('DELETE FROM retired_facts WHERE event_id = ?').run(ev.id);
1048
+ db.prepare('DELETE FROM fact_retirements WHERE target = ?').run(ev.id);
1049
+ db.prepare(`DELETE FROM write_events WHERE note_path = '_memory_ledger_' AND action IN ('retire', 'restore')
1050
+ AND json_valid(summary) AND json_extract(summary, '$.id') = ?`).run(`fact:${ev.id}`);
1051
+ for (const entityId of entityIds) {
1052
+ const used = db.prepare('SELECT 1 FROM facts WHERE subject_entity_id = ? UNION SELECT 1 FROM retired_facts WHERE subject_entity_id = ? LIMIT 1').get(entityId, entityId);
1053
+ if (!used)
1054
+ db.prepare(`DELETE FROM entities WHERE id = ? AND source_note = '_mcp_'`).run(entityId);
1055
+ }
1056
+ // What the erased fact closed stays closed: on a rebuild nothing else in the ledger closes it any more. A fact still open
1057
+ // here (a fresh replay) is closed at the erased fact's own time; one already closed, or gone, is left as it is.
1058
+ if (ev.closes !== undefined) {
1059
+ for (const closed of ev.closes) {
1060
+ for (const table of ['facts', 'retired_facts']) {
1061
+ db.prepare(`UPDATE ${table} SET valid_to = ?, updated_at = ? WHERE event_id = ? AND valid_to IS NULL`).run(ev.closedAt, ev.closedAt, closed);
1062
+ }
1063
+ }
1064
+ }
1065
+ // Store the old digest under the old id: verification still detects a changed pre-erasure event, while no payload remains.
1066
+ db.prepare('INSERT OR REPLACE INTO applied_ledger_events (event_id, digest, applied_at) VALUES (?, ?, ?)')
1067
+ .run(ev.id, ev.originalDigest, ev.at);
1068
+ // A tombstone without a closing link (written before there was one) keeps a link already recorded here.
1069
+ db.prepare(`INSERT INTO erased_facts (event_id, original_digest, erased_at, closes, closed_at) VALUES (?, ?, ?, ?, ?)
1070
+ ON CONFLICT(event_id) DO UPDATE SET original_digest = excluded.original_digest, erased_at = excluded.erased_at,
1071
+ closes = COALESCE(excluded.closes, erased_facts.closes), closed_at = COALESCE(excluded.closed_at, erased_facts.closed_at)`)
1072
+ .run(ev.id, ev.originalDigest, ev.at, ev.closes !== undefined ? ev.closes.join(',') : null, ev.closedAt ?? null);
1073
+ })();
1074
+ return { applied: seen === undefined, factId: null };
1075
+ }
1076
+ // An erased fact's own event, or a retirement of it, that turns up again (a stale copy, a restored fragment): its digest
1077
+ // is the one the tombstone kept, so the check above passes, and the missing-fact repair below would project it again.
1078
+ // Erasure is final: skip it, whichever came first in this ledger.
1079
+ if ((0, factTerms_1.prepareOnce)(db, 'SELECT 1 FROM erased_facts WHERE event_id IN (?, ?)').get(ev.id, ev.target?.toUpperCase() ?? ev.id)) {
1080
+ return { applied: false, factId: null };
1081
+ }
976
1082
  if (RETIREMENT_KINDS.has(ev.kind)) {
977
1083
  applyRetirement(db, ev, digest, seen !== undefined);
978
1084
  return { applied: seen === undefined, factId: null };
@@ -1000,7 +1106,7 @@ function applyEvent(db, ev, positions, index, closedBy) {
1000
1106
  // transactions become savepoints): a rejected ledger (out-of-order chain,
1001
1107
  // absent-from-ledger contradiction) rolls the reconciliation back and
1002
1108
  // leaves the cache exactly as it was held — never partially reconciled.
1003
- (0, statements_1.transactionOnce)(db, reconcileProjectedEvent)(ev, factRow.id, liveRow !== undefined && owner?.source_note !== exports.LIFECYCLE_NOTE_PATH, positions, lifecycleId, closedBy);
1109
+ (0, statements_1.transactionOnce)(db, reconcileProjectedEvent)(ev, factRow.id, liveRow !== undefined && owner?.source_note !== exports.LIFECYCLE_NOTE_PATH, positions, lifecycleId, closedBy, closers);
1004
1110
  // If it predates the digest table (migration 6), backfill the digest so
1005
1111
  // future replays can tell identical dedup from conflicts (the legacy
1006
1112
  // payload itself can no longer be verified).
@@ -1222,12 +1328,15 @@ function settleRetirements(db, events) {
1222
1328
  /** Replay the ledger into facts. Idempotent by event id + digest. Throws on corruption. */
1223
1329
  async function replayLedger(db, vaultPath, ledgerRelPath, options = {}) {
1224
1330
  const filePath = resolveLedgerPath(vaultPath, ledgerRelPath); // shared confinement, before any read
1331
+ if (options.setTornTailAside === true)
1332
+ await removeStaleEraseTemps(filePath);
1225
1333
  let content;
1226
1334
  let finalEventKnown = false;
1227
1335
  try {
1228
1336
  ({ 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));
1229
1337
  }
1230
- catch (err) {
1338
+ catch (caught) {
1339
+ const err = caught;
1231
1340
  if (err?.code === 'ENOENT') {
1232
1341
  // Only an absent ledger means "known-new empty vault: nothing recorded yet".
1233
1342
  // If the index already projects canonical events, the authoritative ledger
@@ -1261,6 +1370,9 @@ async function replayLedger(db, vaultPath, ledgerRelPath, options = {}) {
1261
1370
  const positions = new Map();
1262
1371
  // Each event's closed_event: reconciling a stream replays the facts closed across spellings (reconcileStreamCurrent).
1263
1372
  const closedBy = new Map();
1373
+ // What each erased fact closed (reconcileStreamCurrent): its tombstone's link, or, when a lost rename left its content event
1374
+ // in the ledger, the link the index kept for it.
1375
+ const closers = new Map();
1264
1376
  for (let i = 0; i < events.length; i++) {
1265
1377
  if (positions.has(events[i].id))
1266
1378
  continue;
@@ -1268,15 +1380,21 @@ async function replayLedger(db, vaultPath, ledgerRelPath, options = {}) {
1268
1380
  const closed = events[i].closedEvent;
1269
1381
  if (closed)
1270
1382
  closedBy.set(events[i].id, closed.toUpperCase());
1383
+ if (events[i].kind === ERASE_KIND && events[i].closes !== undefined)
1384
+ closers.set(events[i].id, { closes: events[i].closes, closedAt: events[i].closedAt });
1271
1385
  // A retirement names a fact event written before it.
1272
1386
  const target = events[i].target?.toUpperCase();
1273
1387
  if (target !== undefined) {
1274
1388
  const at = positions.get(target);
1275
- if (at === undefined || RETIREMENT_KINDS.has(events[at].kind)) {
1389
+ if (at === undefined || RETIREMENT_KINDS.has(events[at].kind) || events[at].kind === ERASE_KIND) {
1276
1390
  throw new Error(`ledger corruption in event ${events[i].id}: its target ${target} is no fact event before it in the ledger`);
1277
1391
  }
1278
1392
  }
1279
1393
  }
1394
+ for (const kept of (0, factTerms_1.prepareOnce)(db, 'SELECT event_id, closes, closed_at FROM erased_facts WHERE closes IS NOT NULL AND closed_at IS NOT NULL').all()) {
1395
+ if (positions.has(kept.event_id) && !closers.has(kept.event_id))
1396
+ closers.set(kept.event_id, { closes: kept.closes.split(','), closedAt: kept.closed_at });
1397
+ }
1280
1398
  // GLOBAL preflight (K13): every event-backed canonical projection in the
1281
1399
  // index must be explainable by the COMPLETE parsed ledger — not just the
1282
1400
  // streams this replay happens to touch. The stream-scoped refusal (re-home
@@ -1299,7 +1417,7 @@ async function replayLedger(db, vaultPath, ledgerRelPath, options = {}) {
1299
1417
  }
1300
1418
  const index = replayEntityIndex(db);
1301
1419
  for (const ev of events) {
1302
- if (applyEvent(db, ev, positions, index, closedBy).applied)
1420
+ if (applyEvent(db, ev, positions, index, closedBy, closers).applied)
1303
1421
  applied++;
1304
1422
  }
1305
1423
  settleRetirements(db, events);
@@ -1425,13 +1543,13 @@ async function repeatsCurrentEvent(vaultPath, ledgerRelPath, eventId, args) {
1425
1543
  * because a credential is usually stated across them (predicate wifi_password, object the password) and
1426
1544
  * neither field carries the cue on its own.
1427
1545
  */
1428
- async function refuseSecrets(args) {
1546
+ async function refuseSecrets(args, contentModel = null) {
1429
1547
  try {
1430
1548
  await (0, secretGuard_1.assertStorable)([
1431
1549
  { field: 'statement', text: args.statement },
1432
1550
  { field: 'subject, predicate and object', text: `${args.subject} ${args.predicate}: ${args.object}` },
1433
- { field: 'source', text: args.source },
1434
- ]);
1551
+ { field: 'source', text: args.source, nameOnly: true },
1552
+ ], 'save', contentModel);
1435
1553
  }
1436
1554
  catch (err) {
1437
1555
  // A refusal is the caller's input, like every rejection above it, so it leaves as a LifecycleInputError (4xx).
@@ -1450,8 +1568,9 @@ async function rememberCritical(db, vaultPath, ledgerRelPath, sent) {
1450
1568
  const args = typeof sent.source === 'string' ? { ...sent, source: (0, sourceName_1.savedSource)(sent.source) } : sent;
1451
1569
  validateLifecycleInput(args);
1452
1570
  refuseUnstorableFields(args);
1571
+ // Only a save sends text to the opted-in workspace's second opinion (jevDecisionModel.ts); a restore re-checks text already stored.
1453
1572
  if ((0, secretGuard_1.secretGuardEnabled)())
1454
- await refuseSecrets(args);
1573
+ await refuseSecrets(args, (0, jevDecisionModel_1.saveDecisionModel)());
1455
1574
  const at = new Date().toISOString();
1456
1575
  const scope = (0, scope_1.normalizeScope)(args.scope);
1457
1576
  // The source the event stores, and the writer the save is recorded under: the authenticated identity when the caller
@@ -1465,6 +1584,11 @@ async function rememberCritical(db, vaultPath, ledgerRelPath, sent) {
1465
1584
  const entityId = resolveLifecycleEntity(db, args.subject, at, false, { strict: true });
1466
1585
  // The current value of the scope's stream, whatever spelling of the scope it was saved with (streamCurrentFacts).
1467
1586
  const currents = entityId ? streamCurrentFacts(db, entityId, args.predicate, scope) : [];
1587
+ if (args.expectCurrentEvent !== undefined) {
1588
+ const held = currents.find(c => c.scope === scope) ?? currents[0];
1589
+ if ((held?.event_id ?? null) !== args.expectCurrentEvent)
1590
+ throw new StaleExpectationError(args.expectCurrentEvent, held?.event_id ?? null);
1591
+ }
1468
1592
  // nochange only when nothing the caller said is new: the scope holds this value and no other AND, when they
1469
1593
  // supply the user's words, the same subject spelling and statement as the current event (see repeatsCurrentEvent).
1470
1594
  // A writer that owes a confirmation (its value was replaced) is recorded even when it repeats the current value: that
@@ -1524,6 +1648,153 @@ async function rememberCritical(db, vaultPath, ledgerRelPath, sent) {
1524
1648
  created: { factId, object: args.object, validFrom: at }, ledger,
1525
1649
  };
1526
1650
  }
1651
+ /** One event as the ledger stores it: what an append writes, and what an erasure's rewrite writes for every event it keeps. */
1652
+ function ledgerEventBlock(ev) {
1653
+ const lines = [`\n## ${ev.id} · ${ev.at}`, `- kind: ${ev.kind}`];
1654
+ if (ev.kind === ERASE_KIND) {
1655
+ const closing = ev.closes !== undefined ? [`- closes: ${ev.closes.join(', ')}`, `- closed_at: ${ev.closedAt}`] : [];
1656
+ return [...lines, `- original_digest: ${ev.originalDigest}`, ...closing, '- source: erased', ''].join('\n');
1657
+ }
1658
+ lines.push(`- subject: ${ev.subject}`, `- predicate: ${ev.predicate}`);
1659
+ if (ev.target !== undefined)
1660
+ lines.push(`- target: ${ev.target}`);
1661
+ else
1662
+ lines.push(`- object: ${ev.object}`);
1663
+ if (ev.closedEvent)
1664
+ lines.push(`- closed_event: ${ev.closedEvent}`);
1665
+ const scope = (0, scope_1.normalizeScope)(ev.scope);
1666
+ if (scope !== 'global')
1667
+ lines.push(`- scope: ${scope}`);
1668
+ if (ev.statement !== undefined)
1669
+ lines.push(`- statement: ${encodeStatement(ev.statement)}`);
1670
+ if (ev.writer !== undefined)
1671
+ lines.push(`- writer: ${ev.writer}`);
1672
+ lines.push(`- source: ${ev.source}`, '');
1673
+ return lines.join('\n');
1674
+ }
1675
+ /** Atomically replace a retired fact and its retire/restore events with one content-free, digest-bearing tombstone. */
1676
+ async function eraseRetiredFact(db, vaultPath, ledgerRelPath, id, vectorIndex) {
1677
+ return serializeLifecycleWrite(async () => {
1678
+ const target = factEventId(id);
1679
+ if (target === null)
1680
+ throw new LifecycleInputError('id', 'a live memory is retired first; pass a retired fact id', 'invalid_argument');
1681
+ const row = db.prepare(`SELECT r.subject_entity_id FROM retired_facts r WHERE r.event_id = ?`).get(target);
1682
+ const erased = db.prepare('SELECT original_digest, erased_at, closes FROM erased_facts WHERE event_id = ?').get(target);
1683
+ if (!row && !erased) {
1684
+ if (db.prepare('SELECT 1 FROM facts WHERE event_id = ?').get(target))
1685
+ throw new LifecycleInputError('id', 'that fact is still live; retire it before deleting it permanently', 'invalid_argument');
1686
+ throw new LifecycleInputError('id', 'no retired fact has that id', 'memory_not_found');
1687
+ }
1688
+ const file = resolveLedgerPath(vaultPath, ledgerRelPath);
1689
+ const rel = path_1.default.relative(path_1.default.resolve(vaultPath), file);
1690
+ // The append lock keeps every ledger writer out; the per-file lock the indexer holds for a whole pass (indexFile) keeps
1691
+ // out an index pass that read the ledger before this rewrite and would otherwise commit its chunks after the derived
1692
+ // note is dropped below, putting the erased text back into search. Always in this order: the indexer takes no append lock.
1693
+ return (0, durableAppend_1.withAppendLock)(file, () => (0, writer_1.withDailyFileLock)(file, async () => {
1694
+ const events = parseLedgerEvents(await promises_1.default.readFile(file, 'utf8'));
1695
+ const original = events.find(ev => ev.id === target);
1696
+ if (original?.kind === ERASE_KIND || (!original && erased)) {
1697
+ // The ledger already holds the tombstone (a retry, or a crash after the rename): settle the projection and the audit.
1698
+ const at = original?.at ?? erased.erased_at;
1699
+ const ledgerChunkIds = ledgerChunks(db, file, rel);
1700
+ db.transaction(() => {
1701
+ db.prepare('DELETE FROM notes WHERE path IN (?, ?)').run(file, rel);
1702
+ if (original)
1703
+ applyEvent(db, original);
1704
+ const audit = db.prepare(`SELECT 1 FROM write_events WHERE note_path = '_retired_' AND action = 'delete' AND summary = 'deleted permanently: 1 fact' AND created_at = ?`).get(at);
1705
+ if (!audit)
1706
+ db.prepare(`INSERT INTO write_events (note_path, action, summary, created_at) VALUES ('_retired_', 'delete', 'deleted permanently: 1 fact', ?)`).run(at);
1707
+ })();
1708
+ for (const chunkId of ledgerChunkIds)
1709
+ vectorIndex?.delete(chunkId);
1710
+ return { ok: true, action: 'deleted', ids: [`fact:${target}`], freedBytes: 0, at };
1711
+ }
1712
+ if (!original || RETIREMENT_KINDS.has(original.kind))
1713
+ throw new Error(`ledger corruption: retired fact ${target} has no content-bearing event`);
1714
+ // The index says the fact was erased, yet the ledger still holds it: the rename was lost (a power loss after the index
1715
+ // committed, before the directory reached the disk). Redo the rewrite with the erasure's own digest and time.
1716
+ if (erased && eventDigest(original) !== erased.original_digest) {
1717
+ throw new Error(`ledger corruption: erased fact ${target} is back in the ledger with a different payload`);
1718
+ }
1719
+ const at = erased?.erased_at ?? new Date().toISOString();
1720
+ const subjectEntityId = row?.subject_entity_id ?? resolveLifecycleEntity(db, original.subject, original.at, false);
1721
+ // A redo after a lost rename reuses the link the first erasure recorded: a restart in between replays the old ledger
1722
+ // without the erased fact and may have reopened what it closed, so the facts tables alone no longer show it.
1723
+ const closes = [...new Set([...(erased?.closes ? erased.closes.split(',') : []), ...factsClosedBy(db, original, subjectEntityId)])].sort();
1724
+ const tombstone = {
1725
+ id: target, at, kind: ERASE_KIND, subject: '', predicate: '', object: '', closedEvent: null, source: 'erased',
1726
+ originalDigest: eventDigest(original),
1727
+ ...(closes.length > 0 ? { closes, closedAt: original.at } : {}),
1728
+ };
1729
+ const kept = events.filter(ev => !(RETIREMENT_KINDS.has(ev.kind) && ev.target?.toUpperCase() === target)).map(ev => ev.id === target ? tombstone : ev);
1730
+ // Activity is derived, so scrub it before the canonical commit. A crash here still has the complete retired fact
1731
+ // in its ledger/table; replay does not depend on activity rows. Nothing content-bearing remains after the rename.
1732
+ const erasedEvents = events.filter(ev => ev.id === target || (RETIREMENT_KINDS.has(ev.kind) && ev.target?.toUpperCase() === target));
1733
+ const activityRows = db.prepare(`SELECT id, summary FROM write_events
1734
+ WHERE note_path = '_memory_ledger_' AND action = ? AND created_at = ?
1735
+ AND (author IS NULL OR author = ?) AND (scope IS NULL OR scope = ?)`);
1736
+ const deleteActivity = db.prepare('DELETE FROM write_events WHERE id = ?');
1737
+ db.transaction(() => {
1738
+ for (const ev of erasedEvents) {
1739
+ const expected = ev.target !== undefined
1740
+ ? JSON.stringify({ id: `fact:${ev.target.toUpperCase()}`, title: `${ev.subject} ${ev.predicate}` })
1741
+ : `${ev.subject} ${ev.predicate} → ${ev.object}`;
1742
+ const rows = activityRows.all(ev.kind, ev.at, ev.source, ev.scope ?? 'global');
1743
+ for (const activity of rows) {
1744
+ // The erased event's own line, or that line with the facts it closed: never another line of the same length.
1745
+ const suffix = activity.summary.slice(expected.length);
1746
+ const isWriterSummary = activity.summary === expected
1747
+ || (activity.summary.startsWith(expected) && /^ \(closed facts? [0-9]+(?:, [0-9]+)*\)$/.test(suffix));
1748
+ if (isWriterSummary)
1749
+ deleteActivity.run(activity.id);
1750
+ }
1751
+ }
1752
+ })();
1753
+ const tmp = await (0, confinedWrite_1.createConfined)(vaultPath, `${rel}.erase-${crypto_1.default.randomUUID()}.tmp`, Buffer.from(LEDGER_HEADER + kept.map(ledgerEventBlock).join(''), 'utf8'));
1754
+ try {
1755
+ await promises_1.default.rename(tmp, file);
1756
+ }
1757
+ catch (err) {
1758
+ await promises_1.default.rm(tmp, { force: true });
1759
+ throw err;
1760
+ }
1761
+ // The rename is the commit point, so it reaches the disk before the index records the erasure as done: otherwise a power
1762
+ // loss could leave the old ledger, with the erased content, under an index that says it is gone.
1763
+ await (0, durableAppend_1.syncDirectory)(path_1.default.dirname(file));
1764
+ const ledgerChunkIds = ledgerChunks(db, file, rel);
1765
+ db.transaction(() => {
1766
+ // The Markdown index may have chunked the old ledger bytes. Drop that derived note atomically; the watcher may
1767
+ // index the content-free tombstone later, but no read can serve a stale subject/value chunk meanwhile.
1768
+ db.prepare('DELETE FROM notes WHERE path IN (?, ?)').run(file, rel);
1769
+ applyEvent(db, tombstone);
1770
+ const audit = db.prepare(`SELECT 1 FROM write_events WHERE note_path = '_retired_' AND action = 'delete' AND summary = 'deleted permanently: 1 fact' AND created_at = ?`).get(at);
1771
+ if (!audit)
1772
+ db.prepare(`INSERT INTO write_events (note_path, action, summary, created_at) VALUES ('_retired_', 'delete', 'deleted permanently: 1 fact', ?)`).run(at);
1773
+ })();
1774
+ for (const chunkId of ledgerChunkIds)
1775
+ vectorIndex?.delete(chunkId);
1776
+ return { ok: true, action: 'deleted', ids: [`fact:${target}`], freedBytes: 0, at };
1777
+ }));
1778
+ });
1779
+ }
1780
+ /**
1781
+ * The fact events `ev` closed when it was saved, read from the index: the ones on its subject, predicate and scope whose value
1782
+ * ended at its own time, and the one its closed_event names. Ids only; they go in its erasure tombstone.
1783
+ */
1784
+ function factsClosedBy(db, ev, subjectEntityId) {
1785
+ const query = (table) => `SELECT event_id FROM ${table} WHERE event_id IS NOT NULL AND event_id <> ? AND valid_to = ?
1786
+ AND ((subject_entity_id = ? AND predicate = ? AND scope = ?) OR event_id = ?)`;
1787
+ const args = [ev.id, ev.at, subjectEntityId ?? -1, ev.predicate, (0, scope_1.normalizeScope)(ev.scope), ev.closedEvent?.toUpperCase() ?? ''];
1788
+ const ids = new Set();
1789
+ for (const table of ['facts', 'retired_facts']) {
1790
+ for (const closed of db.prepare(query(table)).pluck().all(...args))
1791
+ ids.add(closed.toUpperCase());
1792
+ }
1793
+ return [...ids].sort();
1794
+ }
1795
+ function ledgerChunks(db, absolute, relative) {
1796
+ return db.prepare('SELECT id FROM chunks WHERE note_path IN (?, ?)').all(absolute, relative).map(chunk => chunk.id);
1797
+ }
1527
1798
  const FACT_ID_RE = /^fact:(mem_[A-Za-z0-9]+)$/i;
1528
1799
  /** The event id in a fact id (`fact:MEM_…`), or null for any other memory id. */
1529
1800
  function factEventId(id) {
@@ -1575,6 +1846,9 @@ async function restoreFact(db, vaultPath, ledgerRelPath, id, source, validateAft
1575
1846
  const target = factEventId(id);
1576
1847
  if (target === null)
1577
1848
  throw new LifecycleInputError('id', `not a fact id: ${JSON.stringify(id)} (a fact's id is fact: and its eventId)`, 'invalid_argument');
1849
+ if ((0, factTerms_1.prepareOnce)(db, 'SELECT 1 FROM erased_facts WHERE event_id = ?').get(target)) {
1850
+ throw new LifecycleInputError('id', 'that fact was permanently erased and cannot be restored', 'memory_not_found');
1851
+ }
1578
1852
  const row = (0, factTerms_1.prepareOnce)(db, `SELECT r.predicate, r.object_text, r.scope, e.canonical_name AS subject
1579
1853
  FROM retired_facts r JOIN entities e ON e.id = r.subject_entity_id WHERE r.event_id = ?`).get(target);
1580
1854
  if (!row) {
@@ -1689,22 +1963,6 @@ function noteReadInstant(db, scope) {
1689
1963
  const DEFAULT_CURRENT_SQL = `((source_path = '${exports.LIFECYCLE_NOTE_PATH}' AND valid_to IS NULL)`
1690
1964
  + ` OR ((source_path IS NULL OR source_path <> '${exports.LIFECYCLE_NOTE_PATH}')`
1691
1965
  + ` AND valid_from <= ? AND (valid_to IS NULL OR valid_to > ?)))`;
1692
- /**
1693
- * Current facts only by default; asOf gives point-in-time; includeHistory gives
1694
- * everything. The default read judges a lifecycle fact by open rows (see
1695
- * DEFAULT_CURRENT_SQL), so a backward clock step cannot hide the current value;
1696
- * a note-derived fact is judged at the wall clock clamped up to the newest
1697
- * workspace observation (workspaceReadInstant), so the same step cannot hide it
1698
- * either; asOf keeps the exact point-in-time window. Lifecycle-owned facts are
1699
- * authoritative: if a lifecycle entity exists for the name, its facts are
1700
- * returned; otherwise the generic (possibly note-derived) entity lookup is used.
1701
- *
1702
- * When a name still matches SEVERAL lifecycle entities (a split a pre-fix write path
1703
- * could create, which nothing reconciles in place), facts from ALL of them are
1704
- * returned. A read must not throw — a startup or dashboard read would become an outage
1705
- * — and it must not hide half the memory behind a silent pick, so the ambiguity is
1706
- * disclosed instead. New writes refuse the same state (LegacyIdentityAmbiguityError).
1707
- */
1708
1966
  function factsFor(db, entityName, opts = {}) {
1709
1967
  let entityIds = [];
1710
1968
  for (const alias of (0, queryHelpers_1.identityNames)(entityName)) {