agent-recall-core 3.4.38 → 3.4.40

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 (101) hide show
  1. package/README.md +1 -1
  2. package/dist/helpers/journal-files.d.ts +29 -1
  3. package/dist/helpers/journal-files.d.ts.map +1 -1
  4. package/dist/helpers/journal-files.js +124 -33
  5. package/dist/helpers/journal-files.js.map +1 -1
  6. package/dist/helpers/journal-sig-theme.d.ts.map +1 -1
  7. package/dist/helpers/journal-sig-theme.js +40 -4
  8. package/dist/helpers/journal-sig-theme.js.map +1 -1
  9. package/dist/host-profile.d.ts +69 -0
  10. package/dist/host-profile.d.ts.map +1 -0
  11. package/dist/host-profile.js +107 -0
  12. package/dist/host-profile.js.map +1 -0
  13. package/dist/index.d.ts +9 -2
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +16 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/storage/archive-write.d.ts.map +1 -1
  18. package/dist/storage/archive-write.js +7 -1
  19. package/dist/storage/archive-write.js.map +1 -1
  20. package/dist/storage/blind-spots-store.d.ts +9 -1
  21. package/dist/storage/blind-spots-store.d.ts.map +1 -1
  22. package/dist/storage/blind-spots-store.js +9 -2
  23. package/dist/storage/blind-spots-store.js.map +1 -1
  24. package/dist/storage/corrections.d.ts +175 -3
  25. package/dist/storage/corrections.d.ts.map +1 -1
  26. package/dist/storage/corrections.js +615 -153
  27. package/dist/storage/corrections.js.map +1 -1
  28. package/dist/storage/hygiene.d.ts +111 -0
  29. package/dist/storage/hygiene.d.ts.map +1 -0
  30. package/dist/storage/hygiene.js +422 -0
  31. package/dist/storage/hygiene.js.map +1 -0
  32. package/dist/storage/lifecycle-telemetry.d.ts +56 -0
  33. package/dist/storage/lifecycle-telemetry.d.ts.map +1 -0
  34. package/dist/storage/lifecycle-telemetry.js +134 -0
  35. package/dist/storage/lifecycle-telemetry.js.map +1 -0
  36. package/dist/storage/memory-protocol.d.ts.map +1 -1
  37. package/dist/storage/memory-protocol.js +4 -1
  38. package/dist/storage/memory-protocol.js.map +1 -1
  39. package/dist/storage/sanitize.d.ts +2 -1
  40. package/dist/storage/sanitize.d.ts.map +1 -1
  41. package/dist/storage/sanitize.js +19 -2
  42. package/dist/storage/sanitize.js.map +1 -1
  43. package/dist/storage/session.d.ts +25 -1
  44. package/dist/storage/session.d.ts.map +1 -1
  45. package/dist/storage/session.js +60 -1
  46. package/dist/storage/session.js.map +1 -1
  47. package/dist/storage/store-manifest.d.ts +31 -0
  48. package/dist/storage/store-manifest.d.ts.map +1 -0
  49. package/dist/storage/store-manifest.js +108 -0
  50. package/dist/storage/store-manifest.js.map +1 -0
  51. package/dist/tools-logic/check-action.d.ts.map +1 -1
  52. package/dist/tools-logic/check-action.js +97 -3
  53. package/dist/tools-logic/check-action.js.map +1 -1
  54. package/dist/tools-logic/check.d.ts +22 -0
  55. package/dist/tools-logic/check.d.ts.map +1 -1
  56. package/dist/tools-logic/check.js +31 -1
  57. package/dist/tools-logic/check.js.map +1 -1
  58. package/dist/tools-logic/predict-correction.d.ts +10 -0
  59. package/dist/tools-logic/predict-correction.d.ts.map +1 -1
  60. package/dist/tools-logic/predict-correction.js +6 -2
  61. package/dist/tools-logic/predict-correction.js.map +1 -1
  62. package/dist/tools-logic/recognition-builder.d.ts +9 -0
  63. package/dist/tools-logic/recognition-builder.d.ts.map +1 -1
  64. package/dist/tools-logic/recognition-builder.js +5 -3
  65. package/dist/tools-logic/recognition-builder.js.map +1 -1
  66. package/dist/tools-logic/session-end.d.ts.map +1 -1
  67. package/dist/tools-logic/session-end.js +49 -4
  68. package/dist/tools-logic/session-end.js.map +1 -1
  69. package/dist/tools-logic/session-start.d.ts.map +1 -1
  70. package/dist/tools-logic/session-start.js +64 -10
  71. package/dist/tools-logic/session-start.js.map +1 -1
  72. package/dist/tools-logic/smart-recall.d.ts +93 -1
  73. package/dist/tools-logic/smart-recall.d.ts.map +1 -1
  74. package/dist/tools-logic/smart-recall.js +199 -11
  75. package/dist/tools-logic/smart-recall.js.map +1 -1
  76. package/dist/tools-logic/smart-remember.d.ts.map +1 -1
  77. package/dist/tools-logic/smart-remember.js +12 -0
  78. package/dist/tools-logic/smart-remember.js.map +1 -1
  79. package/dist/tools-logic/store-doctor.d.ts +1 -1
  80. package/dist/tools-logic/store-doctor.d.ts.map +1 -1
  81. package/dist/tools-logic/store-doctor.js +64 -0
  82. package/dist/tools-logic/store-doctor.js.map +1 -1
  83. package/dist/types.d.ts +1 -1
  84. package/dist/types.js +1 -1
  85. package/package.json +4 -3
  86. package/dist/tools-logic/brief.d.ts +0 -84
  87. package/dist/tools-logic/brief.d.ts.map +0 -1
  88. package/dist/tools-logic/brief.js +0 -193
  89. package/dist/tools-logic/brief.js.map +0 -1
  90. package/dist/tools-logic/dashboard-export.d.ts +0 -130
  91. package/dist/tools-logic/dashboard-export.d.ts.map +0 -1
  92. package/dist/tools-logic/dashboard-export.js +0 -485
  93. package/dist/tools-logic/dashboard-export.js.map +0 -1
  94. package/dist/tools-logic/memory-query.d.ts +0 -43
  95. package/dist/tools-logic/memory-query.d.ts.map +0 -1
  96. package/dist/tools-logic/memory-query.js +0 -77
  97. package/dist/tools-logic/memory-query.js.map +0 -1
  98. package/dist/tools-logic/project-status.d.ts +0 -24
  99. package/dist/tools-logic/project-status.d.ts.map +0 -1
  100. package/dist/tools-logic/project-status.js +0 -155
  101. package/dist/tools-logic/project-status.js.map +0 -1
@@ -8,8 +8,9 @@ import * as fs from "node:fs";
8
8
  import * as path from "node:path";
9
9
  import * as crypto from "node:crypto";
10
10
  import { ensureDir } from "./fs-utils.js";
11
- import { sanitizeName } from "./sanitize.js";
11
+ import { byteCap, sanitizeName } from "./sanitize.js";
12
12
  import { journalDir, projectSubPath } from "./paths.js";
13
+ import { withLock } from "./filelock.js";
13
14
  // ---------------------------------------------------------------------------
14
15
  // Internal helpers
15
16
  // ---------------------------------------------------------------------------
@@ -117,6 +118,13 @@ function slugify(text) {
117
118
  * don't dedupe by id — every *.json file is a distinct record). Returns null
118
119
  * when no matching file is found (defensive fallback only; the record was
119
120
  * just read from this same directory by every current caller).
121
+ *
122
+ * KNOWN LIMITATION of the null-fallback recompute at the call sites: it
123
+ * produces the PLAIN `${date}--${slugify(rule)}.json` name and does NOT carry
124
+ * the id-hash suffix a collision-disambiguated record was originally written
125
+ * under (see writeCorrection's brand-new branch). Reachable only if a
126
+ * record's backing file vanishes from disk mid-call, inside the lock —
127
+ * defensive-only today, flagged by review 2026-07-27.
120
128
  */
121
129
  function findExistingCorrectionFile(dir, id) {
122
130
  if (!fs.existsSync(dir))
@@ -551,64 +559,128 @@ export function writeCorrection(project, correction) {
551
559
  // Auto-detect severity if not already set
552
560
  const severity = correction.severity ?? detectSeverity(`${correction.rule} ${correction.context}`);
553
561
  const record = applyCorrectionDefaults({ ...correction, severity }, todayDate());
554
- // ── P1: on-write consolidation (refine-not-overwrite) ─────────────────────
555
- // Borrow Hindsight's consolidation idea, AR-native: instead of accumulating a
556
- // new dated file for a re-stated rule, fold it into the most similar ACTIVE
557
- // correction of the SAME kind and bump that record's proof_count. The matched
558
- // record keeps its id/date (stable document_id) and absorbs the new tags +
559
- // higher severity/authority/weight. High-precision LOCAL gate — no key, no
560
- // network — so this never runs an LLM on the storage hot path.
561
- const normNew = normalizeRule(record.rule);
562
- for (const existing of readActiveCorrections(project)) {
563
- if (existing.id === record.id)
564
- continue; // never merge into self (same-day re-slug)
565
- if ((existing.kind ?? "correction") !== (record.kind ?? "correction"))
566
- continue;
567
- if (normalizeRule(existing.rule) !== normNew)
568
- continue;
569
- const merged = {
570
- ...existing,
571
- proof_count: (existing.proof_count ?? 1) + 1,
572
- merged_from: [...(existing.merged_from ?? []), record.id],
573
- tags: Array.from(new Set([...(existing.tags ?? []), ...(record.tags ?? [])])),
574
- // keep the STRONGER signal on every axis
575
- severity: existing.severity === "p0" || record.severity === "p0" ? "p0" : "p1",
576
- weight: Math.max(existing.weight ?? 0, record.weight ?? 0),
577
- authoritative: Boolean(existing.authoritative || record.authoritative),
578
- last_outcome: new Date().toISOString(),
579
- // RD-1: keep the existing classification; adopt the incoming capture's
580
- // class only when the existing record predates the field AND the
581
- // incoming class is a REAL class. Review fix MEDIUM-1 (2026-07-14):
582
- // writing "other" into a pre-RD-1 file changes nothing at read time
583
- // (absent already reads as other) but permanently forecloses a future
584
- // real classification — stored-wins would keep "other" forever. Note the
585
- // merge gate is rule-text equality while classification runs on the full
586
- // context text, so incoming classes CAN differ across merges; stored
587
- // still wins in that case by design (durable classification).
588
- ...(existing.failure_class
589
- ? { failure_class: existing.failure_class }
590
- : record.failure_class && record.failure_class !== "other"
591
- ? { failure_class: record.failure_class }
592
- : {}),
593
- };
594
- // Rewrite: reuse the EXISTING file's name (never recompute via slugify —
595
- // see findExistingCorrectionFile doc). Falls back to a fresh v2 filename
596
- // only in the defensive case where the file has vanished mid-call.
597
- const mfile = findExistingCorrectionFile(dir, existing.id)
598
- ?? `${merged.date}--${slugify(merged.rule || merged.id)}.json`;
599
- writeRecordAtomic(path.join(dir, mfile), merged);
562
+ // ── LOCKED critical section (P0 data-loss fix, 2026-07-25) ────────────────
563
+ // From here on this is an unlocked read-all→find→mutate→atomic-rewrite→
564
+ // index-regen sequence: the consolidation scan below reads every *.json
565
+ // file, the merge branch rewrites the ONE matched record, and either branch
566
+ // ends by calling regenerateCorrectionsIndex, which re-reads the whole store
567
+ // and rewrites the ONE shared _index.md. Unlocked, two concurrent
568
+ // writeCorrection calls for the same project can (a) both miss each other's
569
+ // match and create duplicate un-merged records instead of consolidating, or
570
+ // (b) race on the shared index rewrite. Locked with `corrections-${project}`
571
+ // — PROJECT-scoped, not per-correction-id, because the index file is shared
572
+ // across every correction in the project (a per-id lock would still let two
573
+ // DIFFERENT corrections' index writes race). Mirrors retractCorrection /
574
+ // recordOutcome below and the existing `palace-index-${project}` /
575
+ // `digest-${project}` lock pattern elsewhere in this codebase.
576
+ return withLock(`corrections-${project}`, () => {
577
+ // ── P1: on-write consolidation (refine-not-overwrite) ─────────────────────
578
+ // Borrow Hindsight's consolidation idea, AR-native: instead of accumulating a
579
+ // new dated file for a re-stated rule, fold it into the most similar ACTIVE
580
+ // correction of the SAME kind and bump that record's proof_count. The matched
581
+ // record keeps its id/date (stable document_id) and absorbs the new tags +
582
+ // higher severity/authority/weight. High-precision LOCAL gate — no key, no
583
+ // network — so this never runs an LLM on the storage hot path.
584
+ const normNew = normalizeRule(record.rule);
585
+ for (const existing of readActiveCorrections(project)) {
586
+ if (existing.id === record.id)
587
+ continue; // never merge into self (same-day re-slug)
588
+ if ((existing.kind ?? "correction") !== (record.kind ?? "correction"))
589
+ continue;
590
+ if (normalizeRule(existing.rule) !== normNew)
591
+ continue;
592
+ const merged = {
593
+ ...existing,
594
+ proof_count: (existing.proof_count ?? 1) + 1,
595
+ merged_from: [...(existing.merged_from ?? []), record.id],
596
+ tags: Array.from(new Set([...(existing.tags ?? []), ...(record.tags ?? [])])),
597
+ // keep the STRONGER signal on every axis
598
+ severity: existing.severity === "p0" || record.severity === "p0" ? "p0" : "p1",
599
+ weight: Math.max(existing.weight ?? 0, record.weight ?? 0),
600
+ authoritative: Boolean(existing.authoritative || record.authoritative),
601
+ last_outcome: new Date().toISOString(),
602
+ // RD-1: keep the existing classification; adopt the incoming capture's
603
+ // class only when the existing record predates the field AND the
604
+ // incoming class is a REAL class. Review fix MEDIUM-1 (2026-07-14):
605
+ // writing "other" into a pre-RD-1 file changes nothing at read time
606
+ // (absent already reads as other) but permanently forecloses a future
607
+ // real classification — stored-wins would keep "other" forever. Note the
608
+ // merge gate is rule-text equality while classification runs on the full
609
+ // context text, so incoming classes CAN differ across merges; stored
610
+ // still wins in that case by design (durable classification).
611
+ ...(existing.failure_class
612
+ ? { failure_class: existing.failure_class }
613
+ : record.failure_class && record.failure_class !== "other"
614
+ ? { failure_class: record.failure_class }
615
+ : {}),
616
+ };
617
+ // Rewrite: reuse the EXISTING file's name (never recompute via slugify —
618
+ // see findExistingCorrectionFile doc). Falls back to a fresh v2 filename
619
+ // only in the defensive case where the file has vanished mid-call.
620
+ const mfile = findExistingCorrectionFile(dir, existing.id)
621
+ ?? `${merged.date}--${slugify(merged.rule || merged.id)}.json`;
622
+ writeRecordAtomic(path.join(dir, mfile), merged);
623
+ // W2-1: regenerate the materialized index on every corrections mutation.
624
+ regenerateCorrectionsIndex(project);
625
+ return { written: true, merged: true, id: merged.id };
626
+ }
627
+ // Brand-new record — no existing file to preserve. v2 delimiter ("--").
628
+ let filename = `${record.date}--${slugify(record.rule || record.id)}.json`;
629
+ let filepath = path.join(dir, filename);
630
+ if (fs.existsSync(filepath)) {
631
+ // Same-day slug collision with a DIFFERENT record: the active-rule merge
632
+ // loop above already claimed every same-rule case, so whatever lives at
633
+ // this path is a distinct rule whose slug happens to coincide (two
634
+ // CJK-heavy rules sharing one surviving Latin word, or a RETRACTED
635
+ // record the active-only merge scan skipped). Overwriting would silently
636
+ // destroy it — both callers would still see { written: true }. See
637
+ // test/cjk-slug-collision.test.mjs. Disambiguate inside the slug field
638
+ // with a short deterministic hash of this record's id: hex + single "-"
639
+ // join keeps the "--" field-delimiter grammar intact, and re-running the
640
+ // same write lands on the same name.
641
+ const idHash = crypto.createHash("sha256").update(record.id).digest("hex").slice(0, 8);
642
+ // 39 = 48 (corrections' slug byte budget) - 1 ("-" join) - 8 (hex hash):
643
+ // the disambiguated slug field stays inside the same 48-byte envelope.
644
+ const baseSlug = byteCap(slugify(record.rule || record.id), 39).replace(/-+$/g, "");
645
+ filename = `${record.date}--${baseSlug}-${idHash}.json`;
646
+ filepath = path.join(dir, filename);
647
+ }
648
+ // Atomic write — tmp + rename, mode 0600
649
+ writeRecordAtomic(filepath, record);
600
650
  // W2-1: regenerate the materialized index on every corrections mutation.
601
651
  regenerateCorrectionsIndex(project);
602
- return { written: true, merged: true, id: merged.id };
603
- }
604
- // Brand-new record — no existing file to preserve. v2 delimiter ("--").
605
- const filename = `${record.date}--${slugify(record.rule || record.id)}.json`;
606
- const filepath = path.join(dir, filename);
607
- // Atomic write — tmp + rename, mode 0600
608
- writeRecordAtomic(filepath, record);
609
- // W2-1: regenerate the materialized index on every corrections mutation.
610
- regenerateCorrectionsIndex(project);
611
- return { written: true, merged: false, id: record.id };
652
+ return { written: true, merged: false, id: record.id };
653
+ });
654
+ }
655
+ /**
656
+ * TEST-ONLY instrumentation log — one entry (the project slug) appended per
657
+ * actual corrections-directory enumeration inside readCorrections() below
658
+ * (i.e., the fs.readdirSync(dir) call that lists corrections/*.json — NOT the
659
+ * derived readActiveCorrections/readP0Corrections/getCorrectionKPIs paths
660
+ * when they are given a `preloaded` array, since those never touch the
661
+ * filesystem). Logged per-project (not a flat counter) because a single
662
+ * session_start call also triggers store-doctor's checkOutcomesDivergence, a
663
+ * deliberate, SEPARATE, cross-project ledger scan that iterates every project
664
+ * in the store (including whichever one a test is targeting) — a flat global
665
+ * counter couldn't distinguish "this project scanned twice" from "two
666
+ * different projects scanned once each," so tests filter this log by slug.
667
+ *
668
+ * Exists so tests can assert "session_start scans a given project's
669
+ * corrections directory exactly once" (PERF fix, 2026-07-27) without
670
+ * depending on monkeypatching Node's `fs` module — verified infeasible:
671
+ * `import * as fs from "node:fs"` produces an ES module-namespace object
672
+ * whose bindings cannot be reassigned at runtime (throws "Cannot assign to
673
+ * read only property", even though `Object.getOwnPropertyDescriptor` reports
674
+ * `writable: true` for compat).
675
+ *
676
+ * Zero behavior/perf impact outside tests — a single array push on the
677
+ * already-taken scan path. Same "test-only export" convention as
678
+ * stripInterjections/dropHardNoise/splitSentences above.
679
+ */
680
+ export const readCorrectionsScanLog = [];
681
+ /** TEST-ONLY — reset the scan log between test cases. */
682
+ export function resetReadCorrectionsScanLog() {
683
+ readCorrectionsScanLog.length = 0;
612
684
  }
613
685
  /**
614
686
  * Read all corrections for a project, sorted newest first.
@@ -617,6 +689,7 @@ export function readCorrections(project) {
617
689
  const dir = correctionsDir(project);
618
690
  if (!fs.existsSync(dir))
619
691
  return [];
692
+ readCorrectionsScanLog.push(project);
620
693
  const files = fs.readdirSync(dir)
621
694
  .filter((f) => f.endsWith(".json"))
622
695
  .sort()
@@ -636,16 +709,27 @@ export function readCorrections(project) {
636
709
  }
637
710
  /**
638
711
  * Read only active corrections, sorted newest first.
712
+ *
713
+ * PERF (2026-07-27, session_start single-scan fix): accepts an optional
714
+ * `preloaded` array of records already returned by a prior `readCorrections()`
715
+ * call. When provided, this is a pure in-memory filter — no directory scan.
716
+ * Order/semantics are byte-identical to the no-arg path: `.filter()` never
717
+ * reorders, so deriving from a `readCorrections(project)` result is
718
+ * indistinguishable from calling `readCorrections(project)` again. Existing
719
+ * callers that omit the second argument are unaffected (source-compatible).
639
720
  */
640
- export function readActiveCorrections(project) {
641
- return readCorrections(project).filter((r) => r.active !== false);
721
+ export function readActiveCorrections(project, preloaded) {
722
+ return (preloaded ?? readCorrections(project)).filter((r) => r.active !== false);
642
723
  }
643
724
  /**
644
725
  * Read only P0 corrections (always-load), sorted newest first.
645
726
  * Respects active field — archived corrections (active:false) are excluded.
727
+ *
728
+ * PERF (2026-07-27): see readActiveCorrections' `preloaded` doc above — same
729
+ * contract, same guarantee.
646
730
  */
647
- export function readP0Corrections(project) {
648
- return readCorrections(project).filter((r) => r.severity === "p0" && r.active !== false);
731
+ export function readP0Corrections(project, preloaded) {
732
+ return (preloaded ?? readCorrections(project)).filter((r) => r.severity === "p0" && r.active !== false);
649
733
  }
650
734
  /**
651
735
  * Retract (soft-delete) a correction by setting active:false.
@@ -654,30 +738,38 @@ export function readP0Corrections(project) {
654
738
  */
655
739
  export function retractCorrection(project, id, reason, supersededBy) {
656
740
  const dir = correctionsDir(project);
657
- // Find the correction record by id
658
- const all = readCorrections(project);
659
- const target = all.find((r) => r.id === id);
660
- if (!target) {
661
- return { success: false, error: `correction not found: ${id}` };
662
- }
663
- const updated = {
664
- ...target,
665
- active: false,
666
- retracted_at: new Date().toISOString(),
667
- ...(reason !== undefined ? { retract_reason: reason } : {}),
668
- // P2: forward pointer to the correction that replaced this one (audit trail).
669
- ...(supersededBy !== undefined ? { superseded_by: supersededBy } : {}),
670
- };
671
- // Rewrite — reuse the EXISTING file's name (see findExistingCorrectionFile
672
- // doc); never recompute via slugify, or a v1-named file would orphan.
673
- const filename = findExistingCorrectionFile(dir, updated.id)
674
- ?? `${updated.date}--${slugify(updated.rule || updated.id)}.json`;
675
- const filepath = path.join(dir, filename);
676
- // Atomic rewrite — tmp + rename, mode 0600
677
- writeRecordAtomic(filepath, updated);
678
- // W2-1: regenerate the materialized index on every corrections mutation.
679
- regenerateCorrectionsIndex(project);
680
- return { success: true, id };
741
+ // ── LOCKED critical section (P0 data-loss fix, 2026-07-25) ────────────────
742
+ // read-all→find→mutate→atomic-rewrite→index-regen, unlocked, is exactly the
743
+ // race class this fix closes — see the matching note in writeCorrection
744
+ // above and recordOutcome below. Locked with `corrections-${project}`
745
+ // (PROJECT-scoped, matching regenerateCorrectionsIndex's one-shared-file-
746
+ // per-project shape; not per-correction-id — see writeCorrection's note).
747
+ return withLock(`corrections-${project}`, () => {
748
+ // Find the correction record by id
749
+ const all = readCorrections(project);
750
+ const target = all.find((r) => r.id === id);
751
+ if (!target) {
752
+ return { success: false, error: `correction not found: ${id}` };
753
+ }
754
+ const updated = {
755
+ ...target,
756
+ active: false,
757
+ retracted_at: new Date().toISOString(),
758
+ ...(reason !== undefined ? { retract_reason: reason } : {}),
759
+ // P2: forward pointer to the correction that replaced this one (audit trail).
760
+ ...(supersededBy !== undefined ? { superseded_by: supersededBy } : {}),
761
+ };
762
+ // Rewrite — reuse the EXISTING file's name (see findExistingCorrectionFile
763
+ // doc); never recompute via slugify, or a v1-named file would orphan.
764
+ const filename = findExistingCorrectionFile(dir, updated.id)
765
+ ?? `${updated.date}--${slugify(updated.rule || updated.id)}.json`;
766
+ const filepath = path.join(dir, filename);
767
+ // Atomic rewrite — tmp + rename, mode 0600
768
+ writeRecordAtomic(filepath, updated);
769
+ // W2-1: regenerate the materialized index on every corrections mutation.
770
+ regenerateCorrectionsIndex(project);
771
+ return { success: true, id };
772
+ });
681
773
  }
682
774
  /**
683
775
  * Record an outcome event for a correction (retrieved / heeded / recurred).
@@ -720,78 +812,443 @@ export function recordOutcome(outcome) {
720
812
  outcome.kind === "unknown") {
721
813
  return;
722
814
  }
723
- // Update the per-correction file's counters.
724
- const target = readCorrections(outcome.project).find((r) => r.id === outcome.correction_id);
725
- if (!target)
726
- return; // outcome can still be replayed later if record is restored
727
- const updated = {
728
- ...target,
729
- retrieved_count: target.retrieved_count ?? 0,
730
- heeded_count: target.heeded_count ?? 0,
731
- recurrence_count: target.recurrence_count ?? 0,
815
+ // ── LOCKED critical section (P0 data-loss fix, 2026-07-25) ────────────────
816
+ // This is the exact read-all→find→mutate→atomic-rewrite→index-regen span the
817
+ // audit reproduced (24 procs × 20 calls losing 66-78% of retrieved_count
818
+ // increments): readCorrections() below re-reads every *.json file, so two
819
+ // concurrent processes can both read the SAME stale counter value, both
820
+ // increment it by one, and the last atomic rewrite to land silently discards
821
+ // the other's increment. Locked with `corrections-${project}` — PROJECT-
822
+ // scoped, not per-correction-id, because regenerateCorrectionsIndex rewrites
823
+ // ONE shared _index.md per project (a per-id lock would still let two
824
+ // DIFFERENT corrections' index writes race). See the matching note in
825
+ // writeCorrection/retractCorrection above; same lock name, same pattern as
826
+ // `palace-index-${project}` / `digest-${project}` elsewhere in this codebase.
827
+ withLock(`corrections-${outcome.project}`, () => {
828
+ // Update the per-correction file's counters.
829
+ const target = readCorrections(outcome.project).find((r) => r.id === outcome.correction_id);
830
+ if (!target)
831
+ return; // outcome can still be replayed later if record is restored
832
+ const updated = {
833
+ ...target,
834
+ retrieved_count: target.retrieved_count ?? 0,
835
+ heeded_count: target.heeded_count ?? 0,
836
+ recurrence_count: target.recurrence_count ?? 0,
837
+ };
838
+ if (outcome.kind === "retrieved") {
839
+ updated.retrieved_count = (updated.retrieved_count ?? 0) + 1;
840
+ updated.last_retrieved = outcome.at;
841
+ }
842
+ else if (outcome.kind === "heeded") {
843
+ updated.heeded_count = (updated.heeded_count ?? 0) + 1;
844
+ updated.last_outcome = outcome.at;
845
+ }
846
+ else if (outcome.kind === "recurred") {
847
+ updated.recurrence_count = (updated.recurrence_count ?? 0) + 1;
848
+ updated.last_outcome = outcome.at;
849
+ }
850
+ else if (outcome.kind === "predicted") {
851
+ // Wave 5: prediction fired — instrument the predict-the-correction loop.
852
+ updated.predicted_count = (updated.predicted_count ?? 0) + 1;
853
+ updated.last_predicted = outcome.at;
854
+ }
855
+ else if (outcome.kind === "predict_hit") {
856
+ updated.predict_hits = (updated.predict_hits ?? 0) + 1;
857
+ }
858
+ const r = updated.retrieved_count ?? 0;
859
+ // Clamp to [0,1]: `retrieved` is guarded 1/day but `heeded` can fire on every
860
+ // session_end, so raw heeded/retrieved can exceed 1.0 ("150% heeded" is
861
+ // nonsense). min(1, …) keeps the metric honest. (Root-cause follow-up: apply
862
+ // the same 1/day guard to heeded as retrieved has, for finer resolution.)
863
+ // NB (Wave 5): `precision` is heeded/retrieved ONLY — predict_* never touch it.
864
+ updated.precision = r > 0 ? Math.min(1, Number(((updated.heeded_count ?? 0) / r).toFixed(3))) : undefined;
865
+ // Wave 5: predict_precision = predict_hits / predicted_count, kept SEPARATE
866
+ // from `precision`. Undefined until at least one prediction has fired.
867
+ // A predict_hit implies a prior prediction. If data is inconsistent (hits
868
+ // recorded without a matching predicted_count — e.g. migrated/corrupt records),
869
+ // floor the denominator at predict_hits so the metric stays VISIBLE and bounded
870
+ // rather than silently undefined while hits exist.
871
+ const pc = updated.predicted_count ?? 0;
872
+ const ph = updated.predict_hits ?? 0;
873
+ const predictDenom = Math.max(pc, ph);
874
+ updated.predict_precision = predictDenom > 0
875
+ ? Math.min(1, Number((ph / predictDenom).toFixed(3)))
876
+ : undefined;
877
+ // P3: evidence-grounded proof_confidence. With NO outcome evidence yet, keep the
878
+ // authority prior (weight); once heeded/recurrence accrue, move to the Beta
879
+ // posterior so a rule that keeps being honored strengthens and one whose bug
880
+ // keeps recurring weakens. Kept SEPARATE from `precision` (heeded/retrieved) and
881
+ // from `weight` (static authority) — this is the evidence axis.
882
+ const heededC = updated.heeded_count ?? 0;
883
+ const recurC = updated.recurrence_count ?? 0;
884
+ updated.proof_confidence = (heededC + recurC) > 0
885
+ ? Number(betaPosterior(heededC, recurC).toFixed(3))
886
+ : (updated.weight ?? defaultWeight(updated.severity));
887
+ // Re-write the JSON file atomically (tmp + rename — prevents truncation on
888
+ // SIGTERM). Reuse the EXISTING filename (see findExistingCorrectionFile
889
+ // doc) — never recompute via slugify, or a v1-named file would orphan.
890
+ const filename = findExistingCorrectionFile(dir, updated.id)
891
+ ?? `${updated.date}--${slugify(updated.rule || updated.id)}.json`;
892
+ const filepath = path.join(dir, filename);
893
+ writeRecordAtomic(filepath, updated);
894
+ // W2-1: regenerate the materialized index on every corrections mutation.
895
+ // (The ledger-only early-returns above for triggered/not_triggered/unknown
896
+ // touch no per-record field the index renders — severity/status/date/rule/
897
+ // failure_class are all unchanged — so they deliberately skip this call,
898
+ // preserving the existing hot-path optimization documented above.)
899
+ regenerateCorrectionsIndex(outcome.project);
900
+ });
901
+ }
902
+ /** Outcome kinds that affect per-correction counters (mirrors recordOutcome's early-return for triggered/not_triggered/unknown — those are ledger-only). */
903
+ const COUNTER_KINDS = new Set([
904
+ "retrieved",
905
+ "heeded",
906
+ "recurred",
907
+ "predicted",
908
+ "predict_hit",
909
+ ]);
910
+ /**
911
+ * Replay-order key for one ledger event.
912
+ *
913
+ * `recorded_at` (forensic, C3b) is the wall-clock instant recordOutcome() was
914
+ * actually CALLED — i.e. it IS the live call order. `at` (semantic) can be
915
+ * backdated by the dream-audit path, so two events can have `at` values out of
916
+ * order relative to when they were really recorded (a nightly dream-audit call
917
+ * backdates `at` to yesterday but is physically called well AFTER today's live
918
+ * calls). recordOutcome has NO "is this newer" guard — every relevant call
919
+ * unconditionally OVERWRITES last_retrieved/last_outcome/last_predicted with
920
+ * `outcome.at`. So the only way a replay reproduces bit-identical results to a
921
+ * lossless LIVE call sequence is to apply events in the order the CALLS
922
+ * happened (recorded_at), each one stamping its own `.at` value — NOT in
923
+ * semantic-day order. Falls back to `at` only for pre-C3b lines that lack
924
+ * `recorded_at` entirely: those lines predate the dream-audit backdating
925
+ * feature (C3b introduced both `recorded_at` AND backdating together), so for
926
+ * them `at` already WAS the wall-clock time — a safe, non-arbitrary fallback.
927
+ */
928
+ function replayOrderKey(evt) {
929
+ const ts = evt.recorded_at ?? evt.at;
930
+ const t = new Date(ts).getTime();
931
+ return Number.isNaN(t) ? 0 : t;
932
+ }
933
+ /**
934
+ * Sort events into live-call order for replay. Array.prototype.sort is stable
935
+ * (guaranteed since ES2019 / all supported Node versions), so ties — identical
936
+ * recorded_at, or both timestamps missing/invalid — keep original ledger line
937
+ * order, the next-best tie-break absent finer-grained sequencing.
938
+ */
939
+ function sortForReplay(events) {
940
+ return [...events]
941
+ .map((evt, idx) => ({ evt, idx }))
942
+ .sort((a, b) => replayOrderKey(a.evt) - replayOrderKey(b.evt) || a.idx - b.idx)
943
+ .map(({ evt }) => evt);
944
+ }
945
+ /**
946
+ * Pure replay of one correction's counter-affecting ledger events, already
947
+ * ordered by `sortForReplay`. Recomputes every field recordOutcome derives,
948
+ * applying the EXACT SAME per-event formulas (see recordOutcome, this file,
949
+ * ~L1032-1084) one event at a time — this is what makes the rebuild produce
950
+ * IDENTICAL results to a lossless live call sequence.
951
+ *
952
+ * `record` supplies ONLY the weight/severity fallback `proof_confidence` needs
953
+ * when no heeded/recurrence evidence exists yet (recordOutcome's own
954
+ * `updated.weight ?? defaultWeight(updated.severity)` fallback, L1084) — its
955
+ * counter fields are never read here; those are recomputed from scratch.
956
+ *
957
+ * Mirrors recordOutcome's asymmetry precisely: retrieved_count/heeded_count/
958
+ * recurrence_count are seeded to 0 as soon as ANY counter-kind event fires
959
+ * (recordOutcome's `{...target, retrieved_count: target.retrieved_count ?? 0, …}`
960
+ * runs unconditionally before the per-kind branch, L1032-1037), while
961
+ * predicted_count/predict_hits stay `undefined` until their OWN specific kind
962
+ * fires at least once (they are only ever seeded inline at their own
963
+ * increment site, L1049/L1052).
964
+ */
965
+ export function recomputeCorrectionCounters(events, record) {
966
+ let retrieved;
967
+ let heeded;
968
+ let recurrence;
969
+ let predicted;
970
+ let predictHits;
971
+ let lastRetrieved;
972
+ let lastOutcome;
973
+ let lastPredicted;
974
+ for (const evt of events) {
975
+ if (!COUNTER_KINDS.has(evt.kind))
976
+ continue; // ledger-only — mirror recordOutcome's early return (L1007-1013)
977
+ // Unconditional baseline seed on EVERY counter-kind event (recordOutcome L1032-1037).
978
+ retrieved = retrieved ?? 0;
979
+ heeded = heeded ?? 0;
980
+ recurrence = recurrence ?? 0;
981
+ if (evt.kind === "retrieved") {
982
+ retrieved = retrieved + 1;
983
+ lastRetrieved = evt.at;
984
+ }
985
+ else if (evt.kind === "heeded") {
986
+ heeded = heeded + 1;
987
+ lastOutcome = evt.at;
988
+ }
989
+ else if (evt.kind === "recurred") {
990
+ recurrence = recurrence + 1;
991
+ lastOutcome = evt.at;
992
+ }
993
+ else if (evt.kind === "predicted") {
994
+ predicted = (predicted ?? 0) + 1;
995
+ lastPredicted = evt.at;
996
+ }
997
+ else if (evt.kind === "predict_hit") {
998
+ predictHits = (predictHits ?? 0) + 1;
999
+ }
1000
+ }
1001
+ // precision — recordOutcome L1054/L1060.
1002
+ const r = retrieved ?? 0;
1003
+ const precision = r > 0 ? Math.min(1, Number(((heeded ?? 0) / r).toFixed(3))) : undefined;
1004
+ // predict_precision — recordOutcome L1068-1073 (denominator floored at
1005
+ // predict_hits when predicted_count is inconsistent/missing).
1006
+ const pc = predicted ?? 0;
1007
+ const ph = predictHits ?? 0;
1008
+ const predictDenom = Math.max(pc, ph);
1009
+ const predictPrecision = predictDenom > 0 ? Math.min(1, Number((ph / predictDenom).toFixed(3))) : undefined;
1010
+ // proof_confidence — recordOutcome L1080-1084.
1011
+ const heededC = heeded ?? 0;
1012
+ const recurC = recurrence ?? 0;
1013
+ const proofConfidence = heededC + recurC > 0
1014
+ ? Number(betaPosterior(heededC, recurC).toFixed(3))
1015
+ : (record.weight ?? defaultWeight(record.severity));
1016
+ return {
1017
+ retrieved_count: retrieved,
1018
+ heeded_count: heeded,
1019
+ recurrence_count: recurrence,
1020
+ predicted_count: predicted,
1021
+ predict_hits: predictHits,
1022
+ last_retrieved: lastRetrieved,
1023
+ last_outcome: lastOutcome,
1024
+ last_predicted: lastPredicted,
1025
+ precision,
1026
+ predict_precision: predictPrecision,
1027
+ proof_confidence: proofConfidence,
732
1028
  };
733
- if (outcome.kind === "retrieved") {
734
- updated.retrieved_count = (updated.retrieved_count ?? 0) + 1;
735
- updated.last_retrieved = outcome.at;
1029
+ }
1030
+ /**
1031
+ * Bulk-read + split _outcomes.jsonl into per-correction event lists, quarantining
1032
+ * malformed/shapeless lines instead of silently dropping them (unlike
1033
+ * bucketOutcomesBy above, whose callers only need coarse kind-presence and
1034
+ * already tolerate silent skips).
1035
+ *
1036
+ * BULK READ, not streamed: this mirrors bucketOutcomesBy's existing pattern in
1037
+ * this exact file (fs.readFileSync + split("\n")) and keeps the doctor check
1038
+ * that shares this function fully synchronous — store-doctor.ts's public API
1039
+ * (runStoreDoctor) is synchronous today and is called from the session_start
1040
+ * hot path; switching to a streaming reader would force it (and every caller)
1041
+ * async, a much wider blast radius than this repair tool's scope. Acceptable
1042
+ * per-project: _outcomes.jsonl is one project's correction-outcome history,
1043
+ * not a global log.
1044
+ */
1045
+ function parseOutcomesLedger(project) {
1046
+ const malformedRows = [];
1047
+ const eventsByCorrectionId = new Map();
1048
+ const p = outcomesPath(project);
1049
+ if (!fs.existsSync(p))
1050
+ return { malformedRows, eventsByCorrectionId };
1051
+ let raw;
1052
+ try {
1053
+ raw = fs.readFileSync(p, "utf-8");
736
1054
  }
737
- else if (outcome.kind === "heeded") {
738
- updated.heeded_count = (updated.heeded_count ?? 0) + 1;
739
- updated.last_outcome = outcome.at;
1055
+ catch (err) {
1056
+ malformedRows.push({
1057
+ line: 0,
1058
+ raw: "",
1059
+ error: `failed to read ledger: ${err instanceof Error ? err.message : String(err)}`,
1060
+ });
1061
+ return { malformedRows, eventsByCorrectionId };
740
1062
  }
741
- else if (outcome.kind === "recurred") {
742
- updated.recurrence_count = (updated.recurrence_count ?? 0) + 1;
743
- updated.last_outcome = outcome.at;
1063
+ const lines = raw.split("\n");
1064
+ for (let i = 0; i < lines.length; i++) {
1065
+ const lineNo = i + 1;
1066
+ const trimmed = lines[i].trim();
1067
+ if (!trimmed)
1068
+ continue; // blank line — not malformed, just skip
1069
+ let evt;
1070
+ try {
1071
+ evt = JSON.parse(trimmed);
1072
+ }
1073
+ catch (err) {
1074
+ malformedRows.push({
1075
+ line: lineNo,
1076
+ raw: lines[i],
1077
+ error: err instanceof Error ? err.message : String(err),
1078
+ });
1079
+ continue;
1080
+ }
1081
+ if (!evt || typeof evt !== "object" || !evt.correction_id || !evt.kind || !evt.at) {
1082
+ malformedRows.push({
1083
+ line: lineNo,
1084
+ raw: lines[i],
1085
+ error: "parsed but missing required field(s): correction_id, kind, at",
1086
+ });
1087
+ continue;
1088
+ }
1089
+ let arr = eventsByCorrectionId.get(evt.correction_id);
1090
+ if (!arr) {
1091
+ arr = [];
1092
+ eventsByCorrectionId.set(evt.correction_id, arr);
1093
+ }
1094
+ arr.push(evt);
744
1095
  }
745
- else if (outcome.kind === "predicted") {
746
- // Wave 5: prediction fired — instrument the predict-the-correction loop.
747
- updated.predicted_count = (updated.predicted_count ?? 0) + 1;
748
- updated.last_predicted = outcome.at;
1096
+ return { malformedRows, eventsByCorrectionId };
1097
+ }
1098
+ /** Snapshot of a correction's CURRENT on-disk counter/derived fields (before any rebuild). */
1099
+ function currentCountersOf(r) {
1100
+ return {
1101
+ retrieved_count: r.retrieved_count,
1102
+ heeded_count: r.heeded_count,
1103
+ recurrence_count: r.recurrence_count,
1104
+ predicted_count: r.predicted_count,
1105
+ predict_hits: r.predict_hits,
1106
+ last_retrieved: r.last_retrieved,
1107
+ last_outcome: r.last_outcome,
1108
+ last_predicted: r.last_predicted,
1109
+ precision: r.precision,
1110
+ predict_precision: r.predict_precision,
1111
+ proof_confidence: r.proof_confidence,
1112
+ };
1113
+ }
1114
+ const COUNTER_FIELD_NAMES = [
1115
+ "retrieved_count",
1116
+ "heeded_count",
1117
+ "recurrence_count",
1118
+ "predicted_count",
1119
+ "predict_hits",
1120
+ "last_retrieved",
1121
+ "last_outcome",
1122
+ "last_predicted",
1123
+ "precision",
1124
+ "predict_precision",
1125
+ "proof_confidence",
1126
+ ];
1127
+ function countersEqual(a, b) {
1128
+ return COUNTER_FIELD_NAMES.every((k) => a[k] === b[k]);
1129
+ }
1130
+ /**
1131
+ * Shared replay-and-compare core for a single project. Read-only — never
1132
+ * mutates, never locks. For every on-disk correction that has at least one
1133
+ * counter-affecting ledger event, replays that event history from scratch
1134
+ * (sortForReplay + recomputeCorrectionCounters) and compares the result
1135
+ * against what's CURRENTLY materialized on disk.
1136
+ *
1137
+ * Corrections with ZERO ledger events for their id are deliberately EXCLUDED
1138
+ * from the result — there is no ledger evidence to rebuild FROM, so "recompute
1139
+ * from scratch" would mean zeroing out counters that might legitimately have
1140
+ * come from a source other than this project's _outcomes.jsonl (e.g. a very
1141
+ * old pre-ledger record). Rebuild only ever touches ids the lossless ledger
1142
+ * can actually vouch for.
1143
+ *
1144
+ * This is the ONE implementation shared by `runOutcomesRebuild` (write-side,
1145
+ * corrections.ts) and store-doctor.ts's `outcomes_ledger_divergence` check
1146
+ * (read-only) — factored here so the two can never disagree.
1147
+ */
1148
+ export function computeLedgerDivergence(project) {
1149
+ const { malformedRows, eventsByCorrectionId } = parseOutcomesLedger(project);
1150
+ const all = readCorrections(project);
1151
+ const entries = [];
1152
+ for (const record of all) {
1153
+ const raw = eventsByCorrectionId.get(record.id);
1154
+ if (!raw || raw.length === 0)
1155
+ continue;
1156
+ const relevant = raw.filter((e) => COUNTER_KINDS.has(e.kind));
1157
+ if (relevant.length === 0)
1158
+ continue;
1159
+ const ordered = sortForReplay(relevant);
1160
+ const after = recomputeCorrectionCounters(ordered, record);
1161
+ const before = currentCountersOf(record);
1162
+ entries.push({ id: record.id, record, before, after, changed: !countersEqual(before, after) });
749
1163
  }
750
- else if (outcome.kind === "predict_hit") {
751
- updated.predict_hits = (updated.predict_hits ?? 0) + 1;
1164
+ return { malformedRows, entries };
1165
+ }
1166
+ function toPublicDiffs(entries) {
1167
+ return entries.map(({ id, before, after, changed }) => ({ id, before, after, changed }));
1168
+ }
1169
+ /**
1170
+ * Rebuild a project's materialized outcome counters from a full replay of the
1171
+ * (lossless) _outcomes.jsonl ledger — the WRITE-side repair for records
1172
+ * corrupted by the pre-05b3699 unlocked read-modify-write in recordOutcome.
1173
+ *
1174
+ * SAFETY INVARIANTS (mirrors store-repair.ts's StoreRepairOptions contract):
1175
+ * 1. DRY-RUN BY DEFAULT. `opts.apply` must be EXPLICITLY true to mutate.
1176
+ * 2. IDEMPOTENT. A second apply run recomputes from the SAME lossless ledger
1177
+ * and disk now matches it, so every entry's `changed` is false and
1178
+ * nothing is rewritten (not even the index).
1179
+ * 3. LOCK SAFETY. The apply pass runs inside `withLock(\`corrections-${project}\`,
1180
+ * …)` — the SAME lock name recordOutcome/retractCorrection/writeCorrection
1181
+ * use (05b3699) — so a rebuild-apply can never race a live recordOutcome
1182
+ * call for the same project.
1183
+ * 4. Only per-correction JSON files that actually differ are rewritten; the
1184
+ * shared _index.md is regenerated ONCE at the end, only if anything wrote.
1185
+ */
1186
+ export function runOutcomesRebuild(project, opts = {}) {
1187
+ const apply = opts.apply === true;
1188
+ if (!apply) {
1189
+ const plan = computeLedgerDivergence(project);
1190
+ const corrections = toPublicDiffs(plan.entries);
1191
+ return {
1192
+ apply: false,
1193
+ malformedRows: plan.malformedRows,
1194
+ corrections,
1195
+ summary: {
1196
+ totalCorrections: corrections.length,
1197
+ changed: corrections.filter((c) => c.changed).length,
1198
+ malformed: plan.malformedRows.length,
1199
+ },
1200
+ };
752
1201
  }
753
- const r = updated.retrieved_count ?? 0;
754
- // Clamp to [0,1]: `retrieved` is guarded 1/day but `heeded` can fire on every
755
- // session_end, so raw heeded/retrieved can exceed 1.0 ("150% heeded" is
756
- // nonsense). min(1, …) keeps the metric honest. (Root-cause follow-up: apply
757
- // the same 1/day guard to heeded as retrieved has, for finer resolution.)
758
- // NB (Wave 5): `precision` is heeded/retrieved ONLY — predict_* never touch it.
759
- updated.precision = r > 0 ? Math.min(1, Number(((updated.heeded_count ?? 0) / r).toFixed(3))) : undefined;
760
- // Wave 5: predict_precision = predict_hits / predicted_count, kept SEPARATE
761
- // from `precision`. Undefined until at least one prediction has fired.
762
- // A predict_hit implies a prior prediction. If data is inconsistent (hits
763
- // recorded without a matching predicted_count — e.g. migrated/corrupt records),
764
- // floor the denominator at predict_hits so the metric stays VISIBLE and bounded
765
- // rather than silently undefined while hits exist.
766
- const pc = updated.predicted_count ?? 0;
767
- const ph = updated.predict_hits ?? 0;
768
- const predictDenom = Math.max(pc, ph);
769
- updated.predict_precision = predictDenom > 0
770
- ? Math.min(1, Number((ph / predictDenom).toFixed(3)))
771
- : undefined;
772
- // P3: evidence-grounded proof_confidence. With NO outcome evidence yet, keep the
773
- // authority prior (weight); once heeded/recurrence accrue, move to the Beta
774
- // posterior so a rule that keeps being honored strengthens and one whose bug
775
- // keeps recurring weakens. Kept SEPARATE from `precision` (heeded/retrieved) and
776
- // from `weight` (static authority) — this is the evidence axis.
777
- const heededC = updated.heeded_count ?? 0;
778
- const recurC = updated.recurrence_count ?? 0;
779
- updated.proof_confidence = (heededC + recurC) > 0
780
- ? Number(betaPosterior(heededC, recurC).toFixed(3))
781
- : (updated.weight ?? defaultWeight(updated.severity));
782
- // Re-write the JSON file atomically (tmp + rename — prevents truncation on
783
- // SIGTERM). Reuse the EXISTING filename (see findExistingCorrectionFile
784
- // doc) — never recompute via slugify, or a v1-named file would orphan.
785
- const filename = findExistingCorrectionFile(dir, updated.id)
786
- ?? `${updated.date}--${slugify(updated.rule || updated.id)}.json`;
787
- const filepath = path.join(dir, filename);
788
- writeRecordAtomic(filepath, updated);
789
- // W2-1: regenerate the materialized index on every corrections mutation.
790
- // (The ledger-only early-returns above for triggered/not_triggered/unknown
791
- // touch no per-record field the index renders — severity/status/date/rule/
792
- // failure_class are all unchanged — so they deliberately skip this call,
793
- // preserving the existing hot-path optimization documented above.)
794
- regenerateCorrectionsIndex(outcome.project);
1202
+ // ── LOCKED apply pass ──────────────────────────────────────────────────────
1203
+ // Re-derive the plan INSIDE the lock: a concurrent live recordOutcome call
1204
+ // could append new ledger lines or rewrite a correction file between any
1205
+ // earlier unlocked plan computation and acquiring this lock. Same lock name
1206
+ // as writeCorrection/retractCorrection/recordOutcome above.
1207
+ return withLock(`corrections-${project}`, () => {
1208
+ const dir = correctionsDir(project);
1209
+ const plan = computeLedgerDivergence(project);
1210
+ let wrote = 0;
1211
+ for (const entry of plan.entries) {
1212
+ if (!entry.changed)
1213
+ continue;
1214
+ const updated = {
1215
+ ...entry.record,
1216
+ retrieved_count: entry.after.retrieved_count,
1217
+ heeded_count: entry.after.heeded_count,
1218
+ recurrence_count: entry.after.recurrence_count,
1219
+ predicted_count: entry.after.predicted_count,
1220
+ predict_hits: entry.after.predict_hits,
1221
+ last_retrieved: entry.after.last_retrieved,
1222
+ last_outcome: entry.after.last_outcome,
1223
+ last_predicted: entry.after.last_predicted,
1224
+ precision: entry.after.precision,
1225
+ predict_precision: entry.after.predict_precision,
1226
+ proof_confidence: entry.after.proof_confidence,
1227
+ };
1228
+ // Reuse the EXISTING file's name (see findExistingCorrectionFile doc) —
1229
+ // never recompute via slugify, matching every other rewrite in this file.
1230
+ const filename = findExistingCorrectionFile(dir, updated.id) ??
1231
+ `${updated.date}--${slugify(updated.rule || updated.id)}.json`;
1232
+ writeRecordAtomic(path.join(dir, filename), updated);
1233
+ wrote++;
1234
+ }
1235
+ // Regenerate the shared index ONCE, only if something actually changed —
1236
+ // keeps a clean second apply-run a true no-op (idempotency invariant #2).
1237
+ if (wrote > 0) {
1238
+ regenerateCorrectionsIndex(project);
1239
+ }
1240
+ const corrections = toPublicDiffs(plan.entries);
1241
+ return {
1242
+ apply: true,
1243
+ malformedRows: plan.malformedRows,
1244
+ corrections,
1245
+ summary: {
1246
+ totalCorrections: corrections.length,
1247
+ changed: wrote,
1248
+ malformed: plan.malformedRows.length,
1249
+ },
1250
+ };
1251
+ });
795
1252
  }
796
1253
  /**
797
1254
  * Best-effort: append one row to corrections/_rejected.jsonl recording a
@@ -1107,9 +1564,14 @@ export function listUnknownVerdicts(project, date) {
1107
1564
  /**
1108
1565
  * Aggregate KPIs over all corrections for a project — the "is this learning loop working?" view.
1109
1566
  * C3 (2026-07-03): adds verdict_coverage, triggered_count, unknown_count, not_triggered_count.
1567
+ *
1568
+ * PERF (2026-07-27): accepts an optional `preloaded` array of records already
1569
+ * returned by a prior `readCorrections()` call, to avoid a redundant directory
1570
+ * scan when the caller (e.g. session_start) already has them in memory. Same
1571
+ * contract as readActiveCorrections/readP0Corrections above.
1110
1572
  */
1111
- export function getCorrectionKPIs(project) {
1112
- const all = readCorrections(project);
1573
+ export function getCorrectionKPIs(project, preloaded) {
1574
+ const all = preloaded ?? readCorrections(project);
1113
1575
  const active = all.filter((r) => r.active !== false);
1114
1576
  let retrieved = 0;
1115
1577
  let heeded = 0;