fraim 2.0.339 → 2.0.341

package/dist/src/local-mcp-server/learning-usage-store.js

@@ -10,6 +10,7 @@ exports.ruleUsageKey = ruleUsageKey;
 exports.resolveEntryIdentity = resolveEntryIdentity;
 exports.normalizeModelName = normalizeModelName;
 exports.readUsageSnapshot = readUsageSnapshot;
+exports.resolveUsageCheckpointPath = resolveUsageCheckpointPath;
 exports.writeUsageSnapshot = writeUsageSnapshot;
 exports.foldUsageEvents = foldUsageEvents;
 exports.readUsageStore = readUsageStore;
@@ -46,18 +47,10 @@ exports.compactUsageEvents = compactUsageEvents;
  * (`src/ai-hub/server.ts`). That placement is what satisfies R18; there is no
  * second guardrail here.
  *
- * It is derived data (R17): deleting it loses no lesson, because every firing is
- * still written in the retrospective that attested it and every offer is
- * re-recorded the next time the entry is delivered.
- *
- * ## Issue #1752 — what changed and why
- *
- * The durable artifact is now the append-only event log in
- * `learning-usage-events.ts`; `usage/learning-usage.json` is a derived snapshot
- * carrying a `foldedThroughBytes` checkpoint into it. The old read-modify-write
- * lost 1589 of 1600 writes from eight concurrent processes on a plain local disk
- * (spike S1b), which is the real cause of both the impossible `fired > offered`
- * counts and the four OneDrive conflict copies.
+ * Sleep consolidates the append-only journal into learning-usage.json and its
+ * recoverable .checkpoint copy before clearing processed events. Those snapshots
+ * preserve lifetime aggregates and source bookmarks after journal cleanup.
+ * Raw retrospectives preserve lessons and attestations, not every runtime offer.
  *
  * Four smaller corrections ride with it, each removing a place where the record
  * gave a confident answer it could not prove:
@@ -237,6 +230,13 @@ function normalizeModelName(model) {
 function emptyStore() {
     return { version: STORE_VERSION, updatedAt: new Date(0).toISOString(), entries: {}, foldedThroughBytes: {}, offersEraStart: null };
 }
+function withEvidence(store, evidence) {
+    Object.defineProperty(store, 'evidence', { value: evidence, enumerable: false, configurable: true });
+    return store;
+}
+function unavailableStore(observation) {
+    return withEvidence(emptyStore(), { status: 'unavailable', excludedKeys: [], observations: [observation] });
+}
 /**
  * Is this parsed value a record every consumer can read without crashing?
  *
@@ -261,14 +261,21 @@ function isUsableRecord(value) {
     const fired = record.fired;
     if (!offered || typeof offered !== 'object' || !fired || typeof fired !== 'object')
         return false;
-    return Array.isArray(offered.log)
-        && typeof offered.total === 'number'
-        && typeof offered.aboveThreshold === 'number'
-        && !!offered.byModel && typeof offered.byModel === 'object'
-        && Array.isArray(fired.log)
-        && typeof fired.total === 'number'
-        && !!fired.byOutcome && typeof fired.byOutcome === 'object'
-        && Array.isArray(record.titles);
+    const count = (v) => Number.isSafeInteger(v) && v >= 0;
+    const counts = (v) => !!v && typeof v === 'object' && !Array.isArray(v)
+        && Object.values(v).every(count);
+    const nullableString = (v) => v === null || typeof v === 'string';
+    return typeof record.key === 'string' && (record.family === 'learning' || record.family === 'rule')
+        && Array.isArray(offered.log) && offered.log.every(r => r && isValidDate(r.date)
+        && typeof r.job === 'string' && nullableString(r.model))
+        && count(offered.total) && count(offered.aboveThreshold)
+        && counts(offered.byModel)
+        && Array.isArray(fired.log) && fired.log.every(r => r && isValidDate(r.date)
+        && typeof r.job === 'string' && nullableString(r.model) && exports.FIRING_OUTCOMES.includes(r.outcome))
+        && count(fired.total) && counts(fired.byOutcome) && counts(fired.byModel)
+        && exports.FIRING_OUTCOMES.every(outcome => count(fired.byOutcome[outcome]))
+        && Array.isArray(fired.seenSources) && fired.seenSources.every(s => typeof s === 'string')
+        && Array.isArray(record.titles) && record.titles.every(t => typeof t === 'string');
 }
 /**
  * The earliest offer date a pre-#1752 snapshot can evidence.
@@ -306,32 +313,63 @@ function readCheckpoints(value) {
     }
     return out;
 }
-/**
- * Parse the snapshot alone, with no event folding. A missing or corrupt snapshot
- * reads as empty: it is derived data, so losing it is recoverable and must never
- * break the loader that reads it.
- */
+/** Read the normal snapshot, recovering a missing or torn copy from its checkpoint. */
 function readUsageSnapshot(storePath = resolveUsageStorePath()) {
+    const primary = parseUsageSnapshot(storePath);
+    if (primary && primary.evidence?.status !== 'unavailable')
+        return primary;
+    // An unknown schema is not evidence that an older checkpoint can replace it.
+    if (primary?.evidence?.observations.includes('unsupported-schema'))
+        return primary;
+    const backup = parseUsageSnapshot(resolveUsageCheckpointPath(storePath));
+    if (backup && !backup.evidence)
+        return withEvidence(backup, {
+            status: 'reliable', excludedKeys: [],
+            observations: [(0, fs_1.existsSync)(storePath) ? 'primary-unreadable' : 'primary-missing'],
+            recovery: 'checkpoint', persisted: false,
+        });
+    if ((0, fs_1.existsSync)(resolveUsageCheckpointPath(storePath))) {
+        throw new Error('Usage snapshot and checkpoint backup are unreadable. Restore a matching backup; do not delete the usage directory.');
+    }
+    return primary ?? emptyStore();
+}
+function resolveUsageCheckpointPath(storePath) {
+    return storePath + '.checkpoint';
+}
+function parseUsageSnapshot(storePath) {
     try {
         if (!(0, fs_1.existsSync)(storePath))
-            return emptyStore();
+            return null;
         const parsed = JSON.parse((0, fs_1.readFileSync)(storePath, 'utf8'));
         // `typeof [] === 'object'`, so an array has to be rejected explicitly: otherwise
         // Object.values yields whatever the array held and every consumer that reads
         // `entry.offered` throws on it.
         if (!parsed || typeof parsed !== 'object' || !parsed.entries
             || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
-            return emptyStore();
+            return unavailableStore('malformed-snapshot');
+        }
+        if (parsed.version !== undefined && parsed.version !== STORE_VERSION)
+            return unavailableStore('unsupported-schema');
+        if (parsed.foldedThroughBytes !== undefined && (!parsed.foldedThroughBytes
+            || typeof parsed.foldedThroughBytes !== 'object' || Array.isArray(parsed.foldedThroughBytes)
+            || Object.values(parsed.foldedThroughBytes).some(v => !Number.isSafeInteger(v) || v < 0))) {
+            return unavailableStore('malformed-checkpoints');
         }
         // Drop any value that is not a usable record rather than handing a caller
         // something it will crash on. A partially corrupt store degrades to the records
-        // that are still readable, which is the right behaviour for derived data.
+        // that are still readable before consolidation. Consolidated snapshots must be complete.
         const entries = {};
+        const excludedKeys = [];
         for (const [key, value] of Object.entries(parsed.entries)) {
-            if (isUsableRecord(value))
+            if (isUsableRecord(value) && value.key === key)
                 entries[key] = value;
+            else if (parsed.consolidated)
+                return unavailableStore('malformed-consolidated-snapshot');
+            else
+                excludedKeys.push(key);
         }
-        return {
+        const store = {
+            consolidated: parsed.consolidated === true,
             version: parsed.version ?? STORE_VERSION,
             updatedAt: parsed.updatedAt ?? emptyStore().updatedAt,
             entries,
@@ -340,30 +378,26 @@ function readUsageSnapshot(storePath = resolveUsageStorePath()) {
                 ? parsed.offersEraStart
                 : deriveOffersEraStart(entries),
         };
+        return excludedKeys.length ? withEvidence(store, {
+            status: 'partial', excludedKeys, observations: ['malformed-records'],
+        }) : store;
     }
     catch {
-        return emptyStore();
+        return unavailableStore('unreadable-snapshot');
     }
 }
 /**
- * Publish the derived snapshot.
- *
- * In place, with a plain `writeFileSync`, and never by rename. S3 measured a
- * rename over a target any process holds open failing EPERM 100 times in 100, on
- * both a synced and a local path, because that is Windows file-sharing semantics
- * rather than a OneDrive artefact. The usage store is read by concurrent MCP
- * processes by design, so a rename-published snapshot would fail essentially
- * always in production. This is safe precisely because the snapshot is derived: a
- * torn one is rejected by `readUsageSnapshot` and rebuilt from the log.
- *
- * Returns whether it landed. A failure is never thrown: the log is authoritative
- * and the next reader either uses the older snapshot with a longer tail, or folds
- * cold.
+ * Refresh the normal snapshot in place (Windows readers can prevent rename).
+ * Sleep alone publishes the separate flushed checkpoint backup before clearing
+ * journals, so a torn ordinary refresh can recover without replaying old history.
  */
 function writeUsageSnapshot(store, storePath = resolveUsageStorePath()) {
+    if (store.evidence && store.evidence.status !== 'reliable')
+        return false;
     try {
         (0, fs_1.mkdirSync)((0, path_1.dirname)(storePath), { recursive: true });
-        (0, fs_1.writeFileSync)(storePath, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+        const { evidence: _evidence, ...snapshot } = store;
+        (0, fs_1.writeFileSync)(storePath, `${JSON.stringify(snapshot, null, 2)}\n`, { encoding: 'utf8', flush: true });
         return true;
     }
     catch {
@@ -385,26 +419,39 @@ function foldUsageEvents(options) {
     // A checkpoint past the end of its log means the log was compacted or replaced
     // under this snapshot, so the snapshot may already count events the log no
     // longer holds. Re-folding onto it would double count. Discard and fold cold.
+    if (tail.restarted && base.consolidated)
+        throw new Error('Usage journal no longer matches its consolidated snapshot. Restore matching checkpoint files before continuing.');
     if (tail.restarted) {
         const cold = (0, learning_usage_events_1.readEventsSince)(options.eventDir, {});
-        return applyTail(emptyStore(), cold, limits, now, true);
+        return applyTail(withEvidence(emptyStore(), {
+            status: 'unavailable', excludedKeys: base.evidence?.excludedKeys ?? [],
+            observations: [...(base.evidence?.observations ?? []), 'journal-restarted'],
+        }), cold, limits, now, true);
     }
     return applyTail(base, tail, limits, now, false);
 }
 function applyTail(base, tail, limits, now, restarted) {
     const store = {
+        consolidated: base.consolidated,
         version: base.version,
         updatedAt: base.updatedAt,
         entries: base.entries,
         foldedThroughBytes: { ...(base.foldedThroughBytes ?? {}) },
         offersEraStart: base.offersEraStart ?? null,
     };
+    if (base.evidence)
+        withEvidence(store, base.evidence);
     let tailBytes = 0;
+    let unsupportedEvents = false;
     const touched = new Set();
     for (const read of tail.reads) {
         const from = restarted ? 0 : (store.foldedThroughBytes[read.machineId] ?? 0);
         tailBytes += Math.max(0, read.through - from);
         for (const event of read.records) {
+            if (!isSupportedUsageEvent(event)) {
+                unsupportedEvents = true;
+                continue;
+            }
             const key = applyEvent(store, event, limits, now);
             if (key)
                 touched.add(key);
@@ -419,28 +466,90 @@ function applyTail(base, tail, limits, now, restarted) {
     // E: the invariant is evaluated on the read path, where it is always current
     // and costs the write path nothing.
     flagIntegrity(store);
+    const incompleteJournal = tail.skippedLines > 0
+        || tail.reads.some(read => read.through < read.baseOffset + read.size - read.headerBytes);
+    if (incompleteJournal || unsupportedEvents) {
+        withEvidence(store, {
+            status: 'unavailable', excludedKeys: store.evidence?.excludedKeys ?? [],
+            observations: [...(store.evidence?.observations ?? []),
+                ...(incompleteJournal ? ['incomplete-journal'] : []),
+                ...(unsupportedEvents ? ['unsupported-journal-events'] : [])],
+        });
+    }
     return { store, skippedLines: tail.skippedLines, restarted, tailBytes, logs: tail.reads };
 }
 /**
  * The checkpointed read every consumer uses. Snapshot plus the bytes appended
  * past it, republished once the tail is worth re-checkpointing.
  */
+/** Metadata detects observed writes/sync during a read; it is not a writer lock. */
+function usageReadState(storePath, eventDir) {
+    const dir = (0, path_1.dirname)(storePath);
+    const copies = (0, fs_1.existsSync)(dir) ? (0, fs_1.readdirSync)(dir)
+        .filter(name => /^learning-usage(-.+)?\.json$/.test(name) && name !== STORE_FILE_NAME).sort() : [];
+    const paths = [storePath, resolveUsageCheckpointPath(storePath),
+        ...(0, learning_usage_events_1.listEventLogs)(eventDir).map(log => log.path), ...copies.map(name => (0, path_1.join)(dir, name))];
+    const fingerprint = JSON.stringify(paths.map(file => {
+        try {
+            const stat = (0, fs_1.statSync)(file);
+            return [file, stat.size, stat.mtimeMs, stat.ctimeMs, stat.ino];
+        }
+        catch {
+            return [file, 'missing'];
+        }
+    }));
+    return { fingerprint, copies };
+}
 function readUsageStore(storePath = resolveUsageStorePath(), options = {}) {
-    const snapshot = readUsageSnapshot(storePath);
     const eventDir = options.eventDir ?? (0, learning_usage_events_1.resolveEventDir)(storePath);
-    if ((0, learning_usage_events_1.listEventLogs)(eventDir).length === 0)
-        return snapshot;
-    const folded = foldUsageEvents({
+    const before = usageReadState(storePath, eventDir);
+    const snapshot = readUsageSnapshot(storePath);
+    const logs = (0, learning_usage_events_1.listEventLogs)(eventDir);
+    const finish = (store) => {
+        const after = usageReadState(storePath, eventDir);
+        const observations = [...(store.evidence?.observations ?? [])];
+        if (before.fingerprint !== after.fingerprint)
+            observations.push('inputs-changed-during-read');
+        if (after.copies.length)
+            observations.push('unmerged-store-copies');
+        if (store.consolidated && Object.keys(store.foldedThroughBytes ?? {}).some(machineId => !logs.some(log => log.machineId === machineId)))
+            observations.push('consolidated-journal-missing');
+        if (observations.length > (store.evidence?.observations.length ?? 0))
+            withEvidence(store, {
+                status: 'unavailable', excludedKeys: store.evidence?.excludedKeys ?? [], observations,
+            });
+        flagIntegrity(store);
+        return store;
+    };
+    if (logs.length === 0 || snapshot.evidence?.observations.includes('unsupported-schema'))
+        return finish(snapshot);
+    const fold = (base) => foldUsageEvents({
         eventDir,
         limits: options.limits,
         now: options.now,
-        base: snapshot,
-        checkpoints: snapshot.foldedThroughBytes ?? {},
+        base,
+        checkpoints: base.foldedThroughBytes ?? {},
     });
+    let folded;
+    try {
+        folded = fold(snapshot);
+    }
+    catch (error) {
+        const backup = parseUsageSnapshot(resolveUsageCheckpointPath(storePath));
+        if (!backup || backup.evidence)
+            throw error;
+        folded = fold(withEvidence(backup, {
+            status: 'reliable', excludedKeys: [], observations: ['primary-journal-mismatch'],
+            recovery: 'checkpoint', persisted: false,
+        }));
+    }
+    finish(folded.store);
     const mode = options.refreshSnapshot ?? 'auto';
     const shouldRefresh = mode === 'always'
         || (mode === 'auto' && (folded.tailBytes >= SNAPSHOT_REFRESH_BYTES || !(0, fs_1.existsSync)(storePath) || folded.restarted));
-    if (shouldRefresh) {
+    // Recovery is usable in memory. Persisting a primary replacement requires the
+    // explicit maintenance interval; an ordinary reader never establishes it.
+    if (shouldRefresh && !folded.store.evidence) {
         folded.store.updatedAt = (options.now ?? new Date()).toISOString();
         writeUsageSnapshot(folded.store, storePath);
     }
@@ -627,6 +736,20 @@ function applyEvent(store, event, limits, now) {
     void now;
     return null;
 }
+function isSupportedUsageEvent(event) {
+    if (typeof event.key !== 'string' || !event.key || typeof event.date !== 'string' || !isValidDate(event.date))
+        return false;
+    if (event.family !== 'learning' && event.family !== 'rule')
+        return false;
+    if (typeof event.job !== 'string' || (event.model !== null && typeof event.model !== 'string'))
+        return false;
+    if (event.kind === 'offer')
+        return typeof event.aboveThreshold === 'boolean';
+    if (event.kind === 'firing')
+        return exports.FIRING_OUTCOMES.includes(event.outcome)
+            && (event.source === undefined || event.source === 'attested' || event.source === 'backfill-legacy');
+    return false;
+}
 function applyOfferEvent(store, event, common) {
     const record = ensureRecord(store, common.key, common.family, common.fileType, common.level);
     rememberTitle(record, typeof event.title === 'string' ? event.title : undefined);
@@ -747,7 +870,7 @@ function flagIntegrity(store) {
 /**
  * Materialize the snapshot when there is none.
  *
- * The snapshot is derived and normally published by readers, but a workspace that
+ * Before the first consolidation, readers publish snapshots, but a workspace that
  * has only ever been written to would have no snapshot at all, so every reader
  * would pay a cold fold and anything inspecting the store as a file would find
  * nothing there. Bounded: it only runs when the file is absent, and at that point
@@ -761,7 +884,7 @@ function ensureSnapshotExists(storePath, eventDir, limits, now) {
         readUsageStore(storePath, { limits, now, eventDir, refreshSnapshot: 'always' });
     }
     catch {
-        // The log is authoritative. A missing snapshot costs a cold fold, nothing else.
+        // Initial cache publication can retry; consolidated history has a separate backup.
     }
 }
 /**
@@ -874,19 +997,17 @@ function noteTitleChange(key, newTitle, options) {
     store.updatedAt = (options.now ?? new Date()).toISOString();
     writeUsageSnapshot(store, storePath);
 }
-/**
- * Apply retention and log bounds across the whole store, and compact the event
- * log behind it.
- *
- * Compaction is a requirement rather than an optimization: S4 measured a cold
- * full fold at 84 ms on today's volume but 794 ms at ten times it, and the
- * checkpoint only makes a cold fold rare, not bounded.
- */
 function pruneUsageStore(limits, options = {}) {
     const storePath = options.storePath ?? resolveUsageStorePath();
     const eventDir = options.eventDir ?? (0, learning_usage_events_1.resolveEventDir)(storePath);
     const now = options.now ?? new Date();
     const store = readUsageStore(storePath, { limits, now, eventDir });
+    if (store.evidence && store.evidence.status !== 'reliable')
+        return {
+            maintenanceStatus: 'deferred', evidence: store.evidence,
+            prunedOfferRecords: 0, prunedFiringRecords: 0, entries: Object.keys(store.entries).length,
+            compaction: compactUsageEvents({ eventDir, snapshotPath: storePath, limits, now, store }),
+        };
     let prunedOfferRecords = 0;
     let prunedFiringRecords = 0;
     for (const record of Object.values(store.entries)) {
@@ -897,28 +1018,63 @@ function pruneUsageStore(limits, options = {}) {
         prunedFiringRecords += firingsBefore - record.fired.log.length;
     }
     const compaction = compactUsageEvents({ eventDir, snapshotPath: storePath, limits, now, store });
-    return { prunedOfferRecords, prunedFiringRecords, entries: Object.keys(store.entries).length, compaction };
+    return {
+        maintenanceStatus: compaction.maintenanceStatus, evidence: compaction.evidence,
+        prunedOfferRecords, prunedFiringRecords, entries: Object.keys(store.entries).length, compaction,
+    };
 }
-/**
- * Rewrite the event logs to the configured retention window and re-base the
- * snapshot's checkpoint onto the rewritten logs.
- *
- * Re-basing is not optional: leaving a checkpoint pointing into the old log would
- * make the next reader either re-count events the snapshot already holds, or skip
- * ones it does not.
+/** Save totals and source bookmarks in both copies, then clear processed journals.
+ * Requires an interval without concurrent writers or sync activity.
  */
 function compactUsageEvents(options) {
     const now = options.now ?? new Date();
     const store = options.store
         ?? readUsageStore(options.snapshotPath, { limits: options.limits, now, eventDir: options.eventDir });
-    const result = (0, learning_usage_events_1.compactEventLogs)(options.eventDir, (event) => {
+    // Do not turn a partial read into a durable replacement or advance bookmarks
+    // over evidence this reader could not understand. Independent review can run.
+    if (store.evidence && store.evidence.status !== 'reliable')
+        return {
+            maintenanceStatus: 'deferred', evidence: store.evidence,
+            scanned: 0, kept: 0, dropped: 0, skippedLines: 0, logs: [],
+            checkpoints: { ...(store.foldedThroughBytes ?? {}) },
+        };
+    for (const log of (0, learning_usage_events_1.listEventLogs)(options.eventDir)) {
+        if ((store.foldedThroughBytes?.[log.machineId] ?? 0) < log.baseOffset) {
+            throw new Error('Cannot consolidate from a snapshot older than the journal checkpoint.');
+        }
+    }
+    for (const entry of Object.values(store.entries))
+        trimLogs(entry, options.limits, now);
+    store.consolidated = true;
+    store.updatedAt = now.toISOString();
+    // Publish the recoverable checkpoint first, then the normal snapshot. No
+    // journal is cleared unless both writes succeed. The backup is never written
+    // by ordinary readers, so a torn cache refresh cannot destroy both copies.
+    const checkpoint = resolveUsageCheckpointPath(options.snapshotPath);
+    const temp = checkpoint + '.tmp';
+    try {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(checkpoint), { recursive: true });
+        const { evidence: _evidence, ...snapshot } = store;
+        (0, fs_1.writeFileSync)(temp, JSON.stringify(snapshot, null, 2) + '\n', { encoding: 'utf8', flush: true });
+        (0, fs_1.renameSync)(temp, checkpoint);
+    }
+    catch {
+        try {
+            (0, fs_1.rmSync)(temp, { force: true });
+        }
+        catch { /* Best effort. */ }
+        throw new Error('Cannot consolidate usage events: checkpoint backup could not be saved.');
+    }
+    if (!writeUsageSnapshot(store, options.snapshotPath)) {
+        throw new Error('Cannot consolidate usage events: aggregate snapshot could not be saved.');
+    }
+    const compaction = (0, learning_usage_events_1.compactEventLogs)(options.eventDir, (event) => {
+        if (event.kind !== 'offer' && event.kind !== 'firing')
+            return true;
         const date = typeof event.date === 'string' ? event.date : '';
-        if (!isValidDate(date))
+        if (typeof event.key !== 'string' || !event.key || !isValidDate(date))
             return true;
-        return withinRetention(date, options.limits.retentionDays, now);
-    });
-    store.foldedThroughBytes = Object.fromEntries(result.logs.map((log) => [log.machineId, log.size]));
-    store.updatedAt = now.toISOString();
-    writeUsageSnapshot(store, options.snapshotPath);
-    return result;
+        return event.kind === 'firing' && !exports.FIRING_OUTCOMES.includes(event.outcome);
+    }, store.foldedThroughBytes ?? {});
+    return { ...compaction, maintenanceStatus: 'completed', evidence: store.evidence };
 }

package/dist/src/local-mcp-server/learning-usage-verify.js

@@ -16,37 +16,23 @@ exports.buildVerifyReport = buildVerifyReport;
  * It reports and never blocks. Nothing here treats a finding as a gate: it states
  * what it found, and the manager decides.
  *
- * ## Why there is no repair command here
+ * ## Recovery boundary
  *
- * The usage record is derived data (#1103 R17): every firing is also written in
- * the retrospective that attested it, and every offer is re-recorded the next
- * time the entry is delivered. So the repair for a store that has gone wrong is
- * to delete it and rebuild, not to reconcile it in place.
- *
- * That is not a preference, it is what the numbers say. Measured on a 733-file
- * retrospective corpus with four unmerged store copies beside the canonical one:
- *
- *   delete `usage/` then `learning-usage backfill`  ->  149 entries, 2874 firings,
- *                                                       0 split identities,
- *                                                       1 clean model bucket
- *
- * A rebuild lands with zero split identities and one model bucket for free,
- * because the identity resolution and the model normalization fix the causes and
- * a rebuilt store carries no legacy shape. The only thing an in-place
- * reconciliation recovers beyond that is old firings whose retrospectives
- * retention has already deleted, and a decay clock reads the most recent firing
- * rather than the count. What a rebuild does cost is the offer history, which
- * rebuilds itself from live traffic and degrades toward `undetermined` and
- * hold-back in the meantime, which is this module's posture anyway.
- *
- * So `verify` names the rebuild when it finds a stale shape, and the destructive
- * step stays the manager's.
+ * Rebuild only the snapshot, keeping the event directory intact. The retained
+ * events recover the offers and firings they cover; retrospective backfill can
+ * supplement older firings but cannot recreate offers. Normal compaction keeps
+ * lifetime aggregate totals in the snapshot, so a backup is required before
+ * discarding it if history already pruned from events must remain inspectable.
+ * Rebuilding cannot invent missing history or fix identities still present in
+ * the authoritative events. Verify reports those limitations rather than
+ * claiming that deleting the usage directory is a lossless repair.
  */
 const fs_1 = require("fs");
 const path_1 = require("path");
 const learning_usage_store_1 = require("./learning-usage-store");
 const learning_usage_events_1 = require("./learning-usage-events");
 const learning_usage_projection_1 = require("./learning-usage-projection");
+const learning_usage_eligibility_1 = require("./learning-usage-eligibility");
 const CANONICAL_FILE_NAME = 'learning-usage.json';
 /** `learning-usage.json` plus anything a sync client forked off it. */
 const STORE_COPY_PATTERN = /^learning-usage(-.+)?\.json$/;
@@ -179,7 +165,7 @@ function scanRecordsForIntegrity(records, offersEraStart) {
         // unrecorded. An entry whose outcomes are all `ignored` has an empty bucket
         // set correctly, and that is information rather than a gap.
         const clockAdvancing = record.fired.byOutcome.prevented + record.fired.byOutcome.applied;
-        if (clockAdvancing > 0 && Object.keys(record.fired.byModel).length === 0) {
+        if ((0, learning_usage_eligibility_1.modelAttributionIncomplete)(record)) {
             unknownModelAttribution.push({ key: record.key, title, fired: clockAdvancing });
         }
     }
@@ -198,6 +184,7 @@ function buildVerifyReport(options) {
     const checkpoints = snapshot.foldedThroughBytes ?? {};
     const totalLogBytes = logs.reduce((sum, log) => sum + log.size, 0);
     return {
+        evidence: store.evidence,
         snapshotPath: options.snapshotPath,
         eventDir,
         currentModel: (0, learning_usage_projection_1.resolveCurrentModel)(options.currentModel),
@@ -212,7 +199,7 @@ function buildVerifyReport(options) {
         // The one number that makes a stale read visible: a snapshot that stops
         // advancing while the log grows is a failing snapshot write, which S3 showed
         // will happen intermittently on a synced folder and is otherwise silent.
-        checkpointLag: Object.fromEntries(logs.map((log) => [log.machineId, Math.max(0, log.size - (checkpoints[log.machineId] ?? 0))])),
+        checkpointLag: Object.fromEntries(logs.map((log) => [log.machineId, Math.max(0, log.baseOffset + log.size - log.headerBytes - (checkpoints[log.machineId] ?? 0))])),
         skippedLines: 0,
         totalLogBytes,
         compactionAdvisoryBytes: exports.COMPACTION_ADVISORY_BYTES,