fraim 2.0.340 → 2.0.341

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

@@ -27,6 +27,7 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const learning_usage_store_1 = require("./learning-usage-store");
 const learning_usage_projection_1 = require("./learning-usage-projection");
+const learning_usage_eligibility_1 = require("./learning-usage-eligibility");
 function daysBetween(from, to) {
     const a = new Date(from).getTime();
     const b = new Date(to).getTime();
@@ -39,6 +40,7 @@ function firedCount(record) {
 }
 function classifyRecurrence(store, options) {
     const record = store.entries[options.key];
+    const excluded = (0, learning_usage_eligibility_1.usageEvidenceExclusions)(store);
     const base = {
         key: options.key,
         title: record?.titles[record.titles.length - 1] ?? null,
@@ -51,6 +53,14 @@ function classifyRecurrence(store, options) {
             firedTotal: record ? firedCount(record) : 0,
         },
     };
+    if (record && excluded.has(record.key)) {
+        return {
+            ...base, classification: 'undetermined',
+            diagnosis: 'The available usage evidence cannot establish this recurrence.',
+            recommendation: 'Review independent source evidence without attributing this recurrence to usage.',
+            recurrenceBump: false, targetOfFix: 'none',
+        };
+    }
     if (!record) {
         return {
             ...base,
@@ -94,7 +104,7 @@ function classifyRecurrence(store, options) {
     // per entry per session and a plain newest-N bound evicted the job-labelled
     // ones within about a day. Asking about a job the store has never retained an
     // offer for is a gap in the record, not a delivery failure.
-    const jobCoverage = Object.values(store.entries).some((entry) => entry.offered.log.some((offer) => offer.job === options.job && daysBetween(offer.date, options.date) <= options.windowDays));
+    const jobCoverage = Object.values(store.entries).some((entry) => !excluded.has(entry.key) && entry.offered.log.some((offer) => offer.job === options.job && daysBetween(offer.date, options.date) <= options.windowDays));
     if (matchingOffers.length > 0) {
         return {
             ...base,
@@ -231,7 +241,7 @@ function firingsUnderModel(record, model) {
  * unrecorded.
  */
 function modelAttributionUnknown(record) {
-    return firedCount(record) > 0 && Object.keys(record.fired.byModel).length === 0;
+    return (0, learning_usage_eligibility_1.modelAttributionIncomplete)(record);
 }
 function earlierModelFirings(record, currentModel) {
     return Object.entries(record.fired.byModel)
@@ -261,24 +271,22 @@ function findRetirementCandidates(store, options) {
     }
     const candidates = [];
     const notCandidates = [];
+    const excluded = (0, learning_usage_eligibility_1.usageEvidenceExclusions)(store);
     for (const record of Object.values(store.entries)) {
         if (record.family !== 'learning')
             continue;
         const title = latestTitle(record);
+        if (excluded.has(record.key) || modelAttributionUnknown(record)) {
+            notCandidates.push({ key: record.key, title,
+                reason: excluded.get(record.key) ?? 'Model attribution is incomplete; unknown use is not zero use.' });
+            continue;
+        }
         const offered = offersUnderModel(record, currentModel);
         const fired = firingsUnderModel(record, currentModel);
         if (fired > 0) {
             notCandidates.push({ key: record.key, title, reason: `It fired ${fired} time${fired === 1 ? '' : 's'} under the current model, so it is still earning its place.` });
             continue;
         }
-        if (modelAttributionUnknown(record)) {
-            notCandidates.push({
-                key: record.key,
-                title,
-                reason: `Per-model attribution is unknown for this entry: it fired ${firedCount(record)} time${firedCount(record) === 1 ? '' : 's'} and no firing carries a model, so how hard it is working under ${currentModel} cannot be measured. Held back rather than counted as zero.`,
-            });
-            continue;
-        }
         if (offered < threshold) {
             notCandidates.push({
                 key: record.key,
@@ -326,6 +334,10 @@ function deriveStanding(record, options) {
     const offered = record.offered.aboveThreshold;
     const title = latestTitle(record);
     const threshold = options.limits.retirementOfferThreshold;
+    if ((0, learning_usage_eligibility_1.countEvidenceProblem)(record, options.offersEraStart)) {
+        return { key: record.key, title, standing: options.currentStanding?.(record.key) ?? 'standard',
+            reason: 'No usage-based change is supported.', offered: null, fired: null, recommendation: null };
+    }
     let standing;
     let reason;
     if (fired > 0 && daysSince(record.fired.lastFiredAt, now) <= STANDING_RECENT_DAYS) {
@@ -356,10 +368,11 @@ function deriveStanding(record, options) {
  */
 function assessStanding(store, options) {
     const now = options.now ?? new Date();
+    const excluded = (0, learning_usage_eligibility_1.usageEvidenceExclusions)(store);
     const assessments = Object.values(store.entries)
-        .filter((r) => r.family === 'learning')
-        .map((r) => deriveStanding(r, { ...options, now }))
-        .sort((a, b) => b.fired - a.fired || b.offered - a.offered);
+        .filter((r) => r.family === 'learning' && !excluded.has(r.key))
+        .map((r) => deriveStanding(r, { ...options, now, offersEraStart: store.offersEraStart }))
+        .sort((a, b) => (b.fired ?? 0) - (a.fired ?? 0) || (b.offered ?? 0) - (a.offered ?? 0));
     return {
         generatedAt: now.toISOString(),
         assessments,
@@ -374,7 +387,7 @@ function toReportEntry(record) {
         fired: firedCount(record),
         ignored: record.fired.byOutcome.ignored,
         lastFired: record.fired.lastFiredAt,
-        firedUnder: Object.keys(record.fired.byModel),
+        firedUnder: (0, learning_usage_eligibility_1.modelAttributionIncomplete)(record) ? undefined : Object.keys(record.fired.byModel),
         recentLog: record.fired.log,
     };
 }
@@ -388,7 +401,10 @@ function toReportEntry(record) {
 function buildUsageReport(store, options) {
     const now = options.now ?? new Date();
     const limit = options.limit ?? 10;
-    const learningRecords = Object.values(store.entries).filter((r) => r.family === 'learning');
+    const excluded = (0, learning_usage_eligibility_1.usageEvidenceExclusions)(store);
+    const allRecords = Object.values(store.entries).filter((r) => r.family === 'learning');
+    const learningRecords = allRecords.filter(r => !excluded.has(r.key));
+    const complete = excluded.size === 0 && (!store.evidence || store.evidence.status === 'reliable');
     const offered = learningRecords.filter((r) => r.offered.total > 0);
     const fired = learningRecords.filter((r) => firedCount(r) > 0);
     const neverFired = offered.filter((r) => firedCount(r) === 0);
@@ -397,11 +413,11 @@ function buildUsageReport(store, options) {
         generatedAt: now.toISOString(),
         windowDays: options.windowDays,
         currentModel: (0, learning_usage_projection_1.resolveCurrentModel)(options.currentModel),
-        integrityFlagged: learningRecords.filter((r) => Boolean(r.integrity)).length,
+        integrityFlagged: excluded.size,
         totals: {
-            entriesOffered: offered.length,
-            entriesWithFirings: fired.length,
-            entriesNeverFired: neverFired.length,
+            entriesOffered: complete ? offered.length : null,
+            entriesWithFirings: complete ? fired.length : null,
+            entriesNeverFired: complete ? neverFired.length : null,
         },
         workingHardest: fired
             .sort((a, b) => {

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

@@ -277,7 +277,8 @@ const reportCommand = addModelOption(addCommonOptions(new commander_1.Command('r
     });
     emit(report, options.json, () => {
         const lines = [
-            `${report.totals.entriesOffered} entries were offered. ${report.totals.entriesWithFirings} fired. ${report.totals.entriesNeverFired} have never fired.`,
+            report.totals.entriesOffered === null ? 'Corpus totals are unavailable; listed entries have independent usable evidence.'
+                : `${report.totals.entriesOffered} entries were offered. ${report.totals.entriesWithFirings} fired. ${report.totals.entriesNeverFired} have never fired.`,
         ];
         if (report.workingHardest.length) {
             lines.push('', 'Working hardest');
@@ -295,7 +296,7 @@ const reportCommand = addModelOption(addCommonOptions(new commander_1.Command('r
             report.ignoredWhileInContext.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Attested ignored ${e.ignored} time${e.ignored === 1 ? '' : 's'} (fired ${e.fired}). In context and the work went against it, so the entry needs work rather than another recurrence.`));
         }
         if (report.integrityFlagged > 0) {
-            lines.push('', `${report.integrityFlagged} entr${report.integrityFlagged === 1 ? 'y has' : 'ies have'} an integrity flag: more attested firings than recorded offers. Run \`learning-usage verify\` before acting on anything below.`);
+            lines.push('', `${report.integrityFlagged} entries were excluded from usage conclusions. Run \`learning-usage verify\` for diagnostic details.`);
         }
         lines.push('', 'Nothing is retired from this view. Run sleep-on-learnings to decide.');
         return lines.join('\n');
@@ -450,7 +451,8 @@ const pruneCommand = addCommonOptions(new commander_1.Command('prune'))
     const workspaceRoot = resolveWorkspaceRoot(options);
     const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
     const result = (0, learning_usage_store_1.pruneUsageStore)(limits);
-    emit({ ...result, storePath: (0, learning_usage_store_1.resolveUsageStorePath)(), limits }, options.json, () => `Pruned ${result.prunedOfferRecords} offer records and ${result.prunedFiringRecords} firing records across ${result.entries} entries. Aggregates unchanged.`);
+    emit({ ...result, storePath: (0, learning_usage_store_1.resolveUsageStorePath)(), limits }, options.json, () => result.maintenanceStatus === 'deferred' ? `Maintenance deferred; history unchanged. ${result.evidence?.observations.join(', ') ?? ''}`
+        : `Pruned ${result.prunedOfferRecords} offer records and ${result.prunedFiringRecords} firing records across ${result.entries} entries. Aggregates unchanged.`);
 });
 function mb(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
@@ -472,9 +474,11 @@ const verifyCommand = addModelOption(addCommonOptions(new commander_1.Command('v
             '',
         ];
         const finding = (count, singular, plural, remedy) => count === 0 ? `  none: ${singular}` : `  ${count} ${count === 1 ? singular : plural}. ${remedy}`;
+        if (report.evidence)
+            lines.push(`Evidence: ${report.evidence.status}. ${report.evidence.observations.join(', ')}.`, ...(report.evidence.recovery ? [`Recovered from ${report.evidence.recovery}; primary replacement was not persisted by this read.`] : []), '');
         lines.push('Identity', finding(report.twinPairs.length, 'lesson tracked under two keys', 'lessons tracked under two keys', 'Its offers and its firings are on different records, so every count about it is partial.'), report.unmatchedTitleKeys.length
             ? `  ${report.unmatchedTitleKeys.length} title-keyed record${report.unmatchedTitleKeys.length === 1 ? ' has' : 's have'} no id twin. Expected for entries no tier has stamped; run \`stamp-ids\` to reduce it.`
-            : '  every title-keyed record has been matched or has no twin', '', 'Counters', finding(report.invariantViolations.length, 'entry holds more attested firings than recorded offers', 'entries hold more attested firings than recorded offers', 'An entry cannot fire without being offered, so one of the two counters is wrong. History stranded in a store copy nothing reads is the usual cause.'), finding(report.caseVariantModelBuckets.length, 'model bucket differs only by case', 'model buckets differ only by case', 'One model spelled two ways splits its own denominator, so every per-model conclusion about it is computed on a fraction of its traffic.'), finding(report.unknownModelAttribution.length, 'entry fired with no model recorded', 'entries fired with no model recorded', 'Per-model retirement cannot be answered for these, and they are held back rather than counted as zero. These were attested before record-firings carried --agent and --model, so the model was never recorded against them and a rebuild cannot invent it; attestations recorded from now on carry both.'), '', 'Storage');
+            : '  every title-keyed record has been matched or has no twin', '', 'Counters', finding(report.invariantViolations.length, 'entry holds more attested firings than recorded offers', 'entries hold more attested firings than recorded offers', 'The counts are inconsistent. This observation does not establish their cause.'), finding(report.caseVariantModelBuckets.length, 'model bucket differs only by case', 'model buckets differ only by case', 'One model spelled two ways splits its own denominator, so every per-model conclusion about it is computed on a fraction of its traffic.'), finding(report.unknownModelAttribution.length, 'entry has incomplete model attribution', 'entries have incomplete model attribution', 'Affected model conclusions are withheld. The cause is not established; unknown historical attribution cannot be inferred from the current model.'), '', 'Storage');
         if (report.storeCopies.length === 0) {
             lines.push('  one store file, no unmerged copies');
         }

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

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelAttributionIncomplete = modelAttributionIncomplete;
+exports.countEvidenceProblem = countEvidenceProblem;
+exports.usageEvidenceExclusions = usageEvidenceExclusions;
+const learning_usage_store_1 = require("./learning-usage-store");
+const validCount = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+/** Missing attribution is unknown, including a known bucket beside unattributed history. */
+function modelAttributionIncomplete(record) {
+    const buckets = [record.offered.byModel, record.fired.byModel];
+    if (buckets.some(map => !map || Object.entries(map).some(([name, n]) => !validCount(n) || !(0, learning_usage_store_1.normalizeModelName)(name) || (0, learning_usage_store_1.normalizeModelName)(name) !== name)))
+        return true;
+    return Object.values(record.offered.byModel).reduce((a, b) => a + b, 0) !== record.offered.total
+        || Object.values(record.fired.byModel).reduce((a, b) => a + b, 0)
+            !== record.fired.byOutcome.applied + record.fired.byOutcome.prevented;
+}
+/** Validate counts independently of a cached integrity flag. Never alter the record. */
+function countEvidenceProblem(record, offersEraStart) {
+    const counts = [record.offered.total, record.offered.aboveThreshold, record.fired.total,
+        ...Object.values(record.offered.byModel), ...Object.values(record.fired.byModel),
+        ...Object.values(record.fired.byOutcome)];
+    if (counts.some(n => !validCount(n)) || learning_usage_store_1.FIRING_OUTCOMES.some(outcome => !validCount(record.fired.byOutcome[outcome]))
+        || record.offered.aboveThreshold > record.offered.total
+        || Object.values(record.fired.byOutcome).reduce((a, b) => a + b, 0) !== record.fired.total) {
+        return 'Usage counters are inconsistent.';
+    }
+    const violation = record.integrity ?? (0, learning_usage_store_1.integrityViolation)(record, offersEraStart);
+    if (!offersEraStart && record.offered.total > 0 && record.fired.total > record.offered.total) {
+        return 'Excess uses lack provenance establishing the offer-recording era.';
+    }
+    return violation ? violation.detail : null;
+}
+/** Read-time exclusions follow the actual record, never ambient UI or model state. */
+function usageEvidenceExclusions(store) {
+    const excluded = new Map();
+    for (const key of store.evidence?.excludedKeys ?? [])
+        excluded.set(key, 'Unreadable usage record.');
+    const byTitle = new Map();
+    for (const record of Object.values(store.entries)) {
+        const problem = countEvidenceProblem(record, store.offersEraStart);
+        if (store.evidence?.status === 'unavailable')
+            excluded.set(record.key, 'Usage history is unavailable.');
+        else if (problem)
+            excluded.set(record.key, problem);
+        if (!record.fileType)
+            continue;
+        for (const title of record.titles) {
+            const titleKey = (0, learning_usage_store_1.titleUsageKey)(record.fileType, title);
+            byTitle.set(titleKey, [...new Set([...(byTitle.get(titleKey) ?? []), record.key])]);
+        }
+    }
+    for (const keys of byTitle.values()) {
+        if (keys.length > 1 && keys.some(key => key.startsWith('T:'))) {
+            for (const key of keys)
+                excluded.set(key, 'Ambiguous duplicate usage identity.');
+        }
+    }
+    return excluded;
+}

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

@@ -15,6 +15,7 @@ exports.resolveCurrentModel = resolveCurrentModel;
  * Nothing here writes.
  */
 const learning_usage_store_1 = require("./learning-usage-store");
+const learning_usage_eligibility_1 = require("./learning-usage-eligibility");
 function toLookupValue(record) {
     return {
         key: record.key,
@@ -24,7 +25,7 @@ function toLookupValue(record) {
         firedTotalAttestations: record.fired.total,
         lastFired: record.fired.lastFiredAt,
         lastOffered: record.offered.lastOfferedAt,
-        firedUnder: Object.keys(record.fired.byModel),
+        firedUnder: (0, learning_usage_eligibility_1.modelAttributionIncomplete)(record) ? undefined : Object.keys(record.fired.byModel),
         byOutcome: record.fired.byOutcome,
         log: record.fired.log,
     };
@@ -36,7 +37,10 @@ function toLookupValue(record) {
  */
 function buildUsageLookup(store) {
     const lookup = new Map();
+    const excluded = (0, learning_usage_eligibility_1.usageEvidenceExclusions)(store);
     for (const record of Object.values(store.entries)) {
+        if (excluded.has(record.key))
+            continue;
         const value = toLookupValue(record);
         lookup.set(record.key, value);
         if (record.fileType) {

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

@@ -230,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?
  *
@@ -254,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.
@@ -301,15 +315,23 @@ function readCheckpoints(value) {
 }
 /** Read the normal snapshot, recovering a missing or torn copy from its checkpoint. */
 function readUsageSnapshot(storePath = resolveUsageStorePath()) {
-    for (const candidate of [storePath, resolveUsageCheckpointPath(storePath)]) {
-        const snapshot = parseUsageSnapshot(candidate);
-        if (snapshot)
-            return snapshot;
-    }
+    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 emptyStore();
+    return primary ?? emptyStore();
 }
 function resolveUsageCheckpointPath(storePath) {
     return storePath + '.checkpoint';
@@ -324,19 +346,29 @@ function parseUsageSnapshot(storePath) {
         // `entry.offered` throws on it.
         if (!parsed || typeof parsed !== 'object' || !parsed.entries
             || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
-            return null;
+            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 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 null;
+                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,
@@ -346,9 +378,12 @@ function parseUsageSnapshot(storePath) {
                 ? parsed.offersEraStart
                 : deriveOffersEraStart(entries),
         };
+        return excludedKeys.length ? withEvidence(store, {
+            status: 'partial', excludedKeys, observations: ['malformed-records'],
+        }) : store;
     }
     catch {
-        return null;
+        return unavailableStore('unreadable-snapshot');
     }
 }
 /**
@@ -357,9 +392,12 @@ function parseUsageSnapshot(storePath) {
  * 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`, { encoding: 'utf8', flush: true });
+        const { evidence: _evidence, ...snapshot } = store;
+        (0, fs_1.writeFileSync)(storePath, `${JSON.stringify(snapshot, null, 2)}\n`, { encoding: 'utf8', flush: true });
         return true;
     }
     catch {
@@ -385,7 +423,10 @@ function foldUsageEvents(options) {
         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);
 }
@@ -398,12 +439,19 @@ function applyTail(base, tail, limits, now, restarted) {
         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);
@@ -418,17 +466,63 @@ 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 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,
@@ -442,14 +536,20 @@ function readUsageStore(storePath = resolveUsageStorePath(), options = {}) {
     }
     catch (error) {
         const backup = parseUsageSnapshot(resolveUsageCheckpointPath(storePath));
-        if (!backup)
+        if (!backup || backup.evidence)
             throw error;
-        folded = fold(backup);
+        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);
     }
@@ -636,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);
@@ -883,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)) {
@@ -906,7 +1018,10 @@ 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,
+    };
 }
 /** Save totals and source bookmarks in both copies, then clear processed journals.
  * Requires an interval without concurrent writers or sync activity.
@@ -915,6 +1030,14 @@ function compactUsageEvents(options) {
     const now = options.now ?? new Date();
     const store = options.store
         ?? readUsageStore(options.snapshotPath, { limits: options.limits, now, eventDir: options.eventDir });
+    // 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.');
@@ -931,7 +1054,8 @@ function compactUsageEvents(options) {
     const temp = checkpoint + '.tmp';
     try {
         (0, fs_1.mkdirSync)((0, path_1.dirname)(checkpoint), { recursive: true });
-        (0, fs_1.writeFileSync)(temp, JSON.stringify(store, null, 2) + '\n', { encoding: 'utf8', flush: 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 {
@@ -944,7 +1068,7 @@ function compactUsageEvents(options) {
     if (!writeUsageSnapshot(store, options.snapshotPath)) {
         throw new Error('Cannot consolidate usage events: aggregate snapshot could not be saved.');
     }
-    return (0, learning_usage_events_1.compactEventLogs)(options.eventDir, (event) => {
+    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 : '';
@@ -952,4 +1076,5 @@ function compactUsageEvents(options) {
             return true;
         return event.kind === 'firing' && !exports.FIRING_OUTCOMES.includes(event.outcome);
     }, store.foldedThroughBytes ?? {});
+    return { ...compaction, maintenanceStatus: 'completed', evidence: store.evidence };
 }