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.
- package/README.md +1 -1
- package/dist/helpers/journal-files.d.ts +29 -1
- package/dist/helpers/journal-files.d.ts.map +1 -1
- package/dist/helpers/journal-files.js +124 -33
- package/dist/helpers/journal-files.js.map +1 -1
- package/dist/helpers/journal-sig-theme.d.ts.map +1 -1
- package/dist/helpers/journal-sig-theme.js +40 -4
- package/dist/helpers/journal-sig-theme.js.map +1 -1
- package/dist/host-profile.d.ts +69 -0
- package/dist/host-profile.d.ts.map +1 -0
- package/dist/host-profile.js +107 -0
- package/dist/host-profile.js.map +1 -0
- package/dist/index.d.ts +9 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +16 -1
- package/dist/index.js.map +1 -1
- package/dist/storage/archive-write.d.ts.map +1 -1
- package/dist/storage/archive-write.js +7 -1
- package/dist/storage/archive-write.js.map +1 -1
- package/dist/storage/blind-spots-store.d.ts +9 -1
- package/dist/storage/blind-spots-store.d.ts.map +1 -1
- package/dist/storage/blind-spots-store.js +9 -2
- package/dist/storage/blind-spots-store.js.map +1 -1
- package/dist/storage/corrections.d.ts +175 -3
- package/dist/storage/corrections.d.ts.map +1 -1
- package/dist/storage/corrections.js +615 -153
- package/dist/storage/corrections.js.map +1 -1
- package/dist/storage/hygiene.d.ts +111 -0
- package/dist/storage/hygiene.d.ts.map +1 -0
- package/dist/storage/hygiene.js +422 -0
- package/dist/storage/hygiene.js.map +1 -0
- package/dist/storage/lifecycle-telemetry.d.ts +56 -0
- package/dist/storage/lifecycle-telemetry.d.ts.map +1 -0
- package/dist/storage/lifecycle-telemetry.js +134 -0
- package/dist/storage/lifecycle-telemetry.js.map +1 -0
- package/dist/storage/memory-protocol.d.ts.map +1 -1
- package/dist/storage/memory-protocol.js +4 -1
- package/dist/storage/memory-protocol.js.map +1 -1
- package/dist/storage/sanitize.d.ts +2 -1
- package/dist/storage/sanitize.d.ts.map +1 -1
- package/dist/storage/sanitize.js +19 -2
- package/dist/storage/sanitize.js.map +1 -1
- package/dist/storage/session.d.ts +25 -1
- package/dist/storage/session.d.ts.map +1 -1
- package/dist/storage/session.js +60 -1
- package/dist/storage/session.js.map +1 -1
- package/dist/storage/store-manifest.d.ts +31 -0
- package/dist/storage/store-manifest.d.ts.map +1 -0
- package/dist/storage/store-manifest.js +108 -0
- package/dist/storage/store-manifest.js.map +1 -0
- package/dist/tools-logic/check-action.d.ts.map +1 -1
- package/dist/tools-logic/check-action.js +97 -3
- package/dist/tools-logic/check-action.js.map +1 -1
- package/dist/tools-logic/check.d.ts +22 -0
- package/dist/tools-logic/check.d.ts.map +1 -1
- package/dist/tools-logic/check.js +31 -1
- package/dist/tools-logic/check.js.map +1 -1
- package/dist/tools-logic/predict-correction.d.ts +10 -0
- package/dist/tools-logic/predict-correction.d.ts.map +1 -1
- package/dist/tools-logic/predict-correction.js +6 -2
- package/dist/tools-logic/predict-correction.js.map +1 -1
- package/dist/tools-logic/recognition-builder.d.ts +9 -0
- package/dist/tools-logic/recognition-builder.d.ts.map +1 -1
- package/dist/tools-logic/recognition-builder.js +5 -3
- package/dist/tools-logic/recognition-builder.js.map +1 -1
- package/dist/tools-logic/session-end.d.ts.map +1 -1
- package/dist/tools-logic/session-end.js +49 -4
- package/dist/tools-logic/session-end.js.map +1 -1
- package/dist/tools-logic/session-start.d.ts.map +1 -1
- package/dist/tools-logic/session-start.js +64 -10
- package/dist/tools-logic/session-start.js.map +1 -1
- package/dist/tools-logic/smart-recall.d.ts +93 -1
- package/dist/tools-logic/smart-recall.d.ts.map +1 -1
- package/dist/tools-logic/smart-recall.js +199 -11
- package/dist/tools-logic/smart-recall.js.map +1 -1
- package/dist/tools-logic/smart-remember.d.ts.map +1 -1
- package/dist/tools-logic/smart-remember.js +12 -0
- package/dist/tools-logic/smart-remember.js.map +1 -1
- package/dist/tools-logic/store-doctor.d.ts +1 -1
- package/dist/tools-logic/store-doctor.d.ts.map +1 -1
- package/dist/tools-logic/store-doctor.js +64 -0
- package/dist/tools-logic/store-doctor.js.map +1 -1
- package/dist/types.d.ts +1 -1
- package/dist/types.js +1 -1
- package/package.json +4 -3
- package/dist/tools-logic/brief.d.ts +0 -84
- package/dist/tools-logic/brief.d.ts.map +0 -1
- package/dist/tools-logic/brief.js +0 -193
- package/dist/tools-logic/brief.js.map +0 -1
- package/dist/tools-logic/dashboard-export.d.ts +0 -130
- package/dist/tools-logic/dashboard-export.d.ts.map +0 -1
- package/dist/tools-logic/dashboard-export.js +0 -485
- package/dist/tools-logic/dashboard-export.js.map +0 -1
- package/dist/tools-logic/memory-query.d.ts +0 -43
- package/dist/tools-logic/memory-query.d.ts.map +0 -1
- package/dist/tools-logic/memory-query.js +0 -77
- package/dist/tools-logic/memory-query.js.map +0 -1
- package/dist/tools-logic/project-status.d.ts +0 -24
- package/dist/tools-logic/project-status.d.ts.map +0 -1
- package/dist/tools-logic/project-status.js +0 -155
- 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
|
-
// ──
|
|
555
|
-
//
|
|
556
|
-
//
|
|
557
|
-
//
|
|
558
|
-
//
|
|
559
|
-
//
|
|
560
|
-
//
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
:
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
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:
|
|
603
|
-
}
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
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
|
-
//
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
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
|
-
//
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
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
|
-
|
|
734
|
-
|
|
735
|
-
|
|
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
|
-
|
|
738
|
-
|
|
739
|
-
|
|
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
|
-
|
|
742
|
-
|
|
743
|
-
|
|
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
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
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
|
-
|
|
751
|
-
|
|
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
|
-
|
|
754
|
-
//
|
|
755
|
-
//
|
|
756
|
-
//
|
|
757
|
-
//
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
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;
|