fraim 2.0.346 → 2.0.348

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

@@ -15,106 +15,40 @@ exports.writeUsageSnapshot = writeUsageSnapshot;
 exports.foldUsageEvents = foldUsageEvents;
 exports.readUsageStore = readUsageStore;
 exports.sanitizeNote = sanitizeNote;
-exports.integrityViolation = integrityViolation;
-exports.recordOffers = recordOffers;
-exports.recordFirings = recordFirings;
-exports.noteTitleChange = noteTitleChange;
+exports.readAssessedOutcomes = readAssessedOutcomes;
+exports.recordAssessedOutcome = recordAssessedOutcome;
 exports.pruneUsageStore = pruneUsageStore;
 exports.compactUsageEvents = compactUsageEvents;
-/**
- * Issue #1103 — the usage record for learnings and rules.
- *
- * Two sides of one boundary, because only one of them is observable:
- *
- *   OFFERED — written by the runtime with no agent involvement. The proxy composes
- *             the injected context block, so it knows which files it listed and,
- *             for the score-gated families, which entries in them were above
- *             threshold. That is what an offer means here.
- *   FIRED   — attested by the agent at retrospective time. FRAIM cannot observe a
- *             file read, and a read is not a use, so influence has to be claimed
- *             rather than inferred.
- *
- * The record is metadata only (R16): entry identity, outcome, date, job, agent,
- * model. Never prompts, diffs, or work content. Notes are reduced to one bounded
- * line so a multi-line diff cannot be smuggled in through the attestation.
- *
- * Aggregate counters are kept in full; the detailed logs are bounded (R16a), on
- * Mem0's precedent of retaining the last 20 accesses rather than an unbounded
- * behavioural history.
- *
- * The store lives inside the manager layer's content root, which is the layer the
- * existing GDPR guardrail blocks from a git backend without an explicit override
- * (`src/ai-hub/server.ts`). That placement is what satisfies R18; there is no
- * second guardrail here.
- *
- * 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:
- *
- *   A1  `resolveEntryIdentity` is the one definition of what an entry is. Four
- *       call sites each built `id ?? titleUsageKey(...)` independently, so one
- *       lesson could be two records.
- *   C2  Model names are lowercased at write. `GPT-5` and `gpt-5` were two buckets
- *       splitting one denominator (measured 6857 against 2652).
- *   D3  Job-labelled offers are reserved against eviction by session traffic.
- *       2067 of 2354 retained offer records were `session` or `__freeform__`, so
- *       "was this in context for that job" had almost no resolution left.
- *   E   A scoped integrity invariant. The literal `fired <= offered` the issue
- *       asks for is unsound, because `runBackfill` legitimately writes firings
- *       for 299 retrospectives that predate offer recording. Scoped to attested
- *       firings dated at or after the store's first recorded offer, it holds: the
- *       CLI throws on a violation, and the injection path only flags, because a
- *       usage failure must never change what the agent is given (R2).
+/** Assessed incidents and recoverable historical outcomes share the durable journal.
+ * Legacy offer/firing records decode only to preserve historical counts and recovery;
+ * their partial validity does not govern independent validated assessments.
  */
 const fs_1 = require("fs");
 const path_1 = require("path");
 const pack_home_1 = require("../cli/utils/pack-home");
 const artifact_retention_cleanup_1 = require("./artifact-retention-cleanup");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const outcome_types_1 = require("../../registry/scripts/learning/outcome-types");
+const proposal_queue_1 = require("../../registry/scripts/learning/proposal-queue");
 const learning_usage_events_1 = require("./learning-usage-events");
 Object.defineProperty(exports, "appendEvents", { enumerable: true, get: function () { return learning_usage_events_1.appendEvents; } });
 Object.defineProperty(exports, "listEventLogs", { enumerable: true, get: function () { return learning_usage_events_1.listEventLogs; } });
 Object.defineProperty(exports, "resolveEventDir", { enumerable: true, get: function () { return learning_usage_events_1.resolveEventDir; } });
 Object.defineProperty(exports, "resolveMachineId", { enumerable: true, get: function () { return learning_usage_events_1.resolveMachineId; } });
 // ── Vocabulary ───────────────────────────────────────────────────────────────
-/**
- * The five outcomes (spec: Outcome vocabulary). `ignored` and `not-offered` are
- * the two that change what the manager should do: the first says fix the entry,
- * the second says fix the delivery.
- */
+/** Outcome vocabulary retained in historical records. */
 exports.FIRING_OUTCOMES = ['prevented', 'applied', 'not-applicable', 'ignored', 'not-offered'];
-/**
- * R8: only these advance the decay clock. An entry that was offered, read, and
- * correctly not relevant has not proved anything about its usefulness.
- */
+/** Positive recorded outcomes; the historical name does not imply a guidance clock. */
 exports.CLOCK_ADVANCING_OUTCOMES = ['prevented', 'applied'];
 const STORE_VERSION = 1;
 const STORE_FILE_NAME = 'learning-usage.json';
 /** Default bounds. The firing bound follows Mem0's published 20-access retention. */
 const DEFAULT_FIRING_LOG_LIMIT = 20;
-/**
- * The offer log is larger than the firing log because R7 has to answer "was this
- * entry in context for that job" across a plausible recurrence window, which
- * needs per-job offer detail rather than a counter.
- */
+/** Bound retained historical offer detail without changing lifetime totals. */
 const DEFAULT_OFFER_LOG_LIMIT = 50;
-/**
- * Issue #1752 D3. Of the offer log's slots, this many are held for records that
- * carry a real job label, so `fraim_connect`'s per-session traffic cannot evict
- * the only records that can answer R7.
- */
+/** Preserve job-specific historical observations when trimming detail. */
 const DEFAULT_JOB_OFFER_RESERVE = 25;
-/** Open Question 2: configurable and greater than a handful. */
-const DEFAULT_RETIREMENT_OFFER_THRESHOLD = 10;
-/**
- * Job labels the runtime writes when no job is selected. An offer carrying one of
- * these says the entry was in a session's context, not that it was in context for
- * any particular job, so it is not what R7 resolves against.
- */
+/** Historical labels without a specific job. */
 exports.AMBIENT_JOB_LABELS = ['session', '__freeform__', 'unknown', ''];
 /** R16: one line, bounded, no fences. Long enough for a sentence, short enough to be useless as a transcript. */
 const MAX_NOTE_LENGTH = 240;
@@ -161,7 +95,6 @@ function resolveUsageLimits(workspaceRoot) {
         firingLogLimit: positiveInt(block.firingLogLimit, DEFAULT_FIRING_LOG_LIMIT),
         offerLogLimit: positiveInt(block.offerLogLimit, DEFAULT_OFFER_LOG_LIMIT),
         jobOfferReserve: positiveInt(block.jobOfferReserve, DEFAULT_JOB_OFFER_RESERVE),
-        retirementOfferThreshold: positiveInt(block.retirementOfferThreshold, DEFAULT_RETIREMENT_OFFER_THRESHOLD),
         retentionDays: typeof retentionDays === 'number' ? retentionDays : -1,
     };
 }
@@ -175,7 +108,6 @@ function defaultUsageLimits() {
         firingLogLimit: DEFAULT_FIRING_LOG_LIMIT,
         offerLogLimit: DEFAULT_OFFER_LOG_LIMIT,
         jobOfferReserve: DEFAULT_JOB_OFFER_RESERVE,
-        retirementOfferThreshold: DEFAULT_RETIREMENT_OFFER_THRESHOLD,
         retentionDays: -1,
     };
 }
@@ -196,39 +128,21 @@ function titleUsageKey(fileType, title) {
 function ruleUsageKey(displayPath) {
     return `R:${displayPath.replace(/\\/g, '/')}`;
 }
-/**
- * Issue #1752 A1: the single definition of what an entry is.
- *
- * `enumerateFileEntries`, `buildEntryIndex`, `lookupUsage` and the `classify` CLI
- * each built `id ?? titleUsageKey(...)` for themselves, which is four definitions
- * that can drift. Defect 4 is what drift looks like: one lesson stamped in one
- * tier and unstamped in another became two records, one collecting every offer
- * and the other every firing, and `standing` then recommended promoting and
- * demoting the same lesson in a single response.
- *
- * The id always wins. A title key is a fallback for a lesson no tier has stamped,
- * never a second identity for one that has been.
- */
+/** A stamped ID wins over a historical title identity. */
 function resolveEntryIdentity(input) {
     const id = typeof input.id === 'string' ? input.id.trim() : '';
     if (id)
         return { key: id, source: 'id' };
     return { key: titleUsageKey(input.fileType ?? 'unknown', input.title ?? ''), source: 'title' };
 }
-/**
- * Issue #1752 C2: one model, one bucket.
- *
- * Measured in the live store: `GPT-5` 6857 against `gpt-5` 2652, and `gpt-6` 1764
- * against `GPT-6` 140. Every per-model calculation, including retirement
- * candidacy, was splitting its own denominator.
- */
+/** Historical model bucket names compare without case or surrounding whitespace. */
 function normalizeModelName(model) {
     const normalized = String(model ?? '').trim().toLowerCase();
     return normalized || null;
 }
 // ── Read and write ───────────────────────────────────────────────────────────
 function emptyStore() {
-    return { version: STORE_VERSION, updatedAt: new Date(0).toISOString(), entries: {}, foldedThroughBytes: {}, offersEraStart: null };
+    return { version: STORE_VERSION, updatedAt: new Date(0).toISOString(), entries: {}, foldedThroughBytes: {} };
 }
 function withEvidence(store, evidence) {
     Object.defineProperty(store, 'evidence', { value: evidence, enumerable: false, configurable: true });
@@ -237,22 +151,7 @@ function withEvidence(store, evidence) {
 function unavailableStore(observation) {
     return withEvidence(emptyStore(), { status: 'unavailable', excludedKeys: [], observations: [observation] });
 }
-/**
- * Is this parsed value a record every consumer can read without crashing?
- *
- * The shallow `record.offered && record.fired` this replaced was not enough. A
- * record whose sub-objects exist but are empty passed it and then threw in
- * `buildUsageReport` (`record.offered.log is not iterable`),
- * `findRetirementCandidates` and `deriveStanding`, so usage reports and
- * candidate analysis failed outright instead of degrading. That state is
- * reachable: the store is a JSON file inside the manager home, which is commonly
- * a synced folder, so an interrupted write or a partial sync produces valid JSON
- * with a hollow record.
- *
- * Checks only what a consumer actually dereferences, so a record carrying an
- * unknown extra field is still accepted and a future field addition does not
- * silently start discarding history.
- */
+/** Validate required historical fields while ignoring optional metadata. */
 function isUsableRecord(value) {
     if (!value || typeof value !== 'object')
         return false;
@@ -277,32 +176,6 @@ function isUsableRecord(value) {
         && 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.
- *
- * Found by validating against a copy of the real store: without this, a store
- * written before the event log existed has no `offersEraStart`, the scoped
- * invariant has no era to scope to, and it reports zero violations on a corpus
- * that has 62 entries holding more attested firings than recorded offers. Silent
- * and wrong, which is the failure class this whole issue is about.
- *
- * Derived from the bounded offer logs, so it is at or later than the true first
- * offer. Later means fewer firings counted as in-era, which under-reports rather
- * than inventing a violation, and that is the right direction for a check whose
- * CLI form refuses a write.
- */
-function deriveOffersEraStart(entries) {
-    let earliest = null;
-    for (const record of Object.values(entries)) {
-        for (const offer of record.offered.log) {
-            if (!offer?.date)
-                continue;
-            if (earliest === null || offer.date < earliest)
-                earliest = offer.date;
-        }
-    }
-    return earliest;
-}
 function readCheckpoints(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return {};
@@ -374,10 +247,17 @@ function parseUsageSnapshot(storePath) {
             updatedAt: parsed.updatedAt ?? emptyStore().updatedAt,
             entries,
             foldedThroughBytes: readCheckpoints(parsed.foldedThroughBytes),
-            offersEraStart: typeof parsed.offersEraStart === 'string'
-                ? parsed.offersEraStart
-                : deriveOffersEraStart(entries),
+            ...(parsed.outcomeAssessments !== undefined ? { outcomeAssessments: parsed.outcomeAssessments } : {}),
         };
+        if (store.outcomeAssessments !== undefined) {
+            if (!store.outcomeAssessments || typeof store.outcomeAssessments !== 'object' || Array.isArray(store.outcomeAssessments))
+                return unavailableStore('malformed-assessments');
+            for (const [digest, assessment] of Object.entries(store.outcomeAssessments)) {
+                (0, outcome_types_1.validateOutcomeAssessmentRecord)(assessment);
+                if (digest !== assessment.digest)
+                    return unavailableStore('malformed-assessments');
+            }
+        }
         return excludedKeys.length ? withEvidence(store, {
             status: 'partial', excludedKeys, observations: ['malformed-records'],
         }) : store;
@@ -437,7 +317,7 @@ function applyTail(base, tail, limits, now, restarted) {
         updatedAt: base.updatedAt,
         entries: base.entries,
         foldedThroughBytes: { ...(base.foldedThroughBytes ?? {}) },
-        offersEraStart: base.offersEraStart ?? null,
+        ...(base.outcomeAssessments ? { outcomeAssessments: { ...base.outcomeAssessments } } : {}),
     };
     if (base.evidence)
         withEvidence(store, base.evidence);
@@ -463,9 +343,6 @@ function applyTail(base, tail, limits, now, restarted) {
         if (record)
             trimLogs(record, limits, now);
     }
-    // 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) {
@@ -518,7 +395,6 @@ function readUsageStore(storePath = resolveUsageStorePath(), options = {}) {
             withEvidence(store, {
                 status: 'unavailable', excludedKeys: store.evidence?.excludedKeys ?? [], observations,
             });
-        flagIntegrity(store);
         return store;
     };
     if (logs.length === 0 || snapshot.evidence?.observations.includes('unsupported-schema'))
@@ -550,7 +426,6 @@ function readUsageStore(storePath = resolveUsageStorePath(), options = {}) {
     // 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);
     }
     return folded.store;
@@ -636,20 +511,7 @@ const byDate = (a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0);
 function isAmbientJob(job) {
     return exports.AMBIENT_JOB_LABELS.includes(job ?? '');
 }
-/**
- * Issue #1752 D3: bound the offer log without letting session traffic evict the
- * only records that can answer R7.
- *
- * Measured cause: `fraim_connect` records one offer per entry per session under
- * the label `session`, and a plain newest-50 rule then evicted every
- * job-labelled record within about a day. 2067 of the 2354 retained offer records
- * in the live store carried `session` or `__freeform__`, and only three real job
- * names appeared at all, which is why `classify --job <real-job>` could almost
- * never find a match.
- *
- * Job-labelled records get the first `jobOfferReserve` slots; the rest of the
- * budget goes to the newest of everything else.
- */
+/** Preserve job-specific historical detail within the configured log bound. */
 function selectRetainedOffers(log, limits) {
     if (log.length <= limits.offerLogLimit)
         return log;
@@ -673,50 +535,21 @@ function trimLogs(record, limits, now) {
         .sort(byDate)
         .slice(-limits.firingLogLimit);
 }
-function offerEvent(offer) {
-    return {
-        kind: 'offer',
-        key: offer.key,
-        family: offer.family,
-        title: offer.title,
-        fileType: offer.fileType,
-        level: offer.level,
-        aboveThreshold: Boolean(offer.aboveThreshold),
-        job: offer.job,
-        date: offer.date,
-        agent: offer.agent ?? null,
-        model: normalizeModelName(offer.model),
-    };
-}
-function firingEvent(firing) {
-    return {
-        kind: 'firing',
-        key: firing.key,
-        family: firing.family,
-        title: firing.title,
-        fileType: firing.fileType,
-        level: firing.level,
-        outcome: firing.outcome,
-        note: sanitizeNote(firing.note),
-        job: firing.job,
-        date: firing.date,
-        agent: firing.agent ?? null,
-        model: normalizeModelName(firing.model),
-        source: firing.source ?? 'attested',
-        sourceRef: firing.sourceRef,
-    };
-}
 /**
  * Apply one logged event to the record set. Returns the key it touched, or null
  * when the event is unusable or already counted.
  *
- * Firing idempotency lives here rather than on the write path, so it holds
- * however many times an event was appended: `(key, sourceRef)` is the complete
- * identity of an attestation, which is the same fact the migration's exact firing
- * recovery rests on.
+ * Historical duplicate suppression remains in the reader: retained `(key, sourceRef)`
+ * identities prevent old journal replays from increasing preserved totals.
  */
 function applyEvent(store, event, limits, now) {
     const kind = event.kind;
+    if (kind === 'assessment') {
+        const assessment = event.assessment;
+        (0, outcome_types_1.validateOutcomeAssessmentRecord)(assessment);
+        (store.outcomeAssessments ??= {})[assessment.digest] = assessment;
+        return null;
+    }
     const key = typeof event.key === 'string' ? event.key : '';
     const date = typeof event.date === 'string' ? event.date : '';
     if (!key || !isValidDate(date))
@@ -737,6 +570,15 @@ function applyEvent(store, event, limits, now) {
     return null;
 }
 function isSupportedUsageEvent(event) {
+    if (event.kind === 'assessment') {
+        try {
+            (0, outcome_types_1.validateOutcomeAssessmentRecord)(event.assessment);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     if (typeof event.key !== 'string' || !event.key || typeof event.date !== 'string' || !isValidDate(event.date))
         return false;
     if (event.family !== 'learning' && event.family !== 'rule')
@@ -768,7 +610,6 @@ function applyOfferEvent(store, event, common) {
     });
     // The era only ever moves earlier, so the scoped invariant's boundary is
     // monotonic and a late-syncing log cannot shrink the window it applies to.
-    store.offersEraStart = minDate(store.offersEraStart, common.date);
     return common.key;
 }
 function applyFiringEvent(store, event, common) {
@@ -776,14 +617,13 @@ function applyFiringEvent(store, event, common) {
     if (!exports.FIRING_OUTCOMES.includes(outcome))
         return null;
     const record = ensureRecord(store, common.key, common.family, common.fileType, common.level);
-    // Idempotency lives here rather than on the write path, so it holds however
-    // many times an event was appended. `(key, sourceRef)` is the complete identity
-    // of an attestation, which is the same fact the migration's exact firing
-    // recovery rests on.
+    // Retained source identities survive detail pruning and suppress duplicate
+    // historical journal rows during recovery.
     const sourceRef = typeof event.sourceRef === 'string' ? event.sourceRef : '';
     if (sourceRef && record.fired.seenSources.includes(sourceRef))
         return null;
     rememberTitle(record, typeof event.title === 'string' ? event.title : undefined);
+    store.updatedAt = maxDate(store.updatedAt, common.date);
     record.fired.total += 1;
     record.fired.byOutcome[outcome] = (record.fired.byOutcome[outcome] ?? 0) + 1;
     record.fired.lastAttestedAt = maxDate(record.fired.lastAttestedAt, common.date);
@@ -806,196 +646,55 @@ function applyFiringEvent(store, event, common) {
         record.fired.seenSources.push(sourceRef);
     return common.key;
 }
-// ── The scoped integrity invariant (issue #1752 E) ──────────────────────────
-/**
- * How many of this entry's attested firings fall inside the offers era.
- *
- * The invariant the issue asks for, `fired <= offered`, is unsound as literally
- * stated: `runBackfill` writes firings attested by 299 retrospectives that
- * predate offer recording entirely, and those have no offer by construction.
- * Scoped to attested firings dated at or after the store's first recorded offer,
- * it holds and means something.
- *
- * Two bases, because the check has two jobs with opposite failure budgets.
- *
- *   'log'        Counts only the firings the bounded log still holds. It cannot
- *                over-count, so it can never refuse a correct write. This is what
- *                the CLI throws on.
- *   'aggregate'  Starts from `fired.total` and subtracts the firings the log
- *                shows are exempt. It sees an entry whose detail has aged out,
- *                which is the shape all 58 violating entries in the live store
- *                have, and it can over-count when the log no longer shows the
- *                exemptions. That is acceptable for a report and not for a
- *                refusal, so this is what the read path flags with and `verify`
- *                lists.
- */
-function attestedFiringsInOffersEra(record, offersEraStart, basis) {
-    if (!offersEraStart)
-        return 0;
-    const inLog = record.fired.log.filter((r) => r.source === 'attested' && r.date >= offersEraStart).length;
-    if (basis === 'log')
-        return inLog;
-    const exemptInLog = record.fired.log.filter((r) => r.source === 'backfill-legacy' || r.date < offersEraStart).length;
-    return Math.max(inLog, record.fired.total - exemptInLog);
-}
-function integrityViolation(record, offersEraStart, basis = 'aggregate') {
-    // An entry with no offer record at all is not an accounting overflow; it is the
-    // question defect 2 is about, and it has several innocent causes: the offers
-    // were recorded under the entry's other key before #1752 A2 merged them, the
-    // entry is a rule or a demoted lesson the offer path does not enumerate, or the
-    // offers are sitting in another machine's event log that has not synced yet.
-    // Throwing on any of those would block a correct attestation on a sync
-    // artefact. The overflow this invariant exists to catch is the one the issue
-    // measured: entries showing `offered: 1, fired: 10`, which all have an offer.
-    if (record.offered.total === 0)
-        return null;
-    const inEra = attestedFiringsInOffersEra(record, offersEraStart, basis);
-    if (inEra <= record.offered.total)
-        return null;
-    return {
-        flag: 'fired-exceeds-offered',
-        count: inEra - record.offered.total,
-        detail: `${inEra} attested firings dated on or after ${offersEraStart} against ${record.offered.total} recorded offers. An entry cannot fire without being offered, so one of the two counters is wrong for this entry.`,
-    };
-}
-function flagIntegrity(store) {
-    for (const record of Object.values(store.entries)) {
-        const violation = integrityViolation(record, store.offersEraStart);
-        if (violation)
-            record.integrity = violation;
-        else if (record.integrity)
-            delete record.integrity;
-    }
-}
-/**
- * Materialize the snapshot when there is none.
- *
- * 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
- * the fold is over a log that has just been created. A failure is swallowed, like
- * every other snapshot write.
- */
-function ensureSnapshotExists(storePath, eventDir, limits, now) {
-    try {
-        if ((0, fs_1.existsSync)(storePath))
-            return;
-        readUsageStore(storePath, { limits, now, eventDir, refreshSnapshot: 'always' });
-    }
-    catch {
-        // Initial cache publication can retry; consolidated history has a separate backup.
-    }
-}
-/**
- * R1 and R2: write one offer record per listed entry, without any agent
- * involvement and without depending on the agent reading the file.
- *
- * Issue #1752 B: this appends and does not read. The read-modify-write it
- * replaces lost 1589 of 1600 writes under eight concurrent processes on a plain
- * local disk (spike S1b), which is the dominant loss path behind both the
- * impossible counters and the four conflict copies. Nothing here can throw on an
- * integrity violation either: R2 requires that a usage failure never changes what
- * the agent is given, so the violation is flagged by the read path instead.
- */
-function recordOffers(offers, options) {
-    const storePath = options.storePath ?? resolveUsageStorePath();
-    const eventDir = options.eventDir ?? (0, learning_usage_events_1.resolveEventDir)(storePath);
-    const usable = offers.filter((offer) => offer.key && isValidDate(offer.date));
-    if (usable.length === 0)
-        return { recorded: 0, entries: 0 };
-    (0, learning_usage_events_1.appendEvents)(eventDir, usable.map(offerEvent), options.machineId);
-    ensureSnapshotExists(storePath, eventDir, options.limits, options.now ?? new Date());
-    return { recorded: usable.length, entries: new Set(usable.map((o) => o.key)).size };
-}
-/**
- * R4 and R6: write the attested firings. Idempotent per (entry, attestation
- * source) so a re-run, or a backfill that overlaps a live attestation, cannot
- * inflate a count.
- *
- * Unlike the offer path this reads first, because it has two questions only the
- * current record can answer: whether this attestation has already contributed,
- * and whether the scoped invariant is about to be violated. It still writes by
- * appending, and the fold applies the same `(key, sourceRef)` idempotency, so a
- * racing duplicate append is folded once rather than counted twice.
- *
- * The invariant throws here. This is a CLI path with an operator watching, and a
- * violation means a real accounting bug rather than a cosmetic one.
- */
-function recordFirings(firings, 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: options.limits, now, eventDir });
-    const events = [];
-    let alreadyRecorded = 0;
-    for (const firing of firings) {
-        if (!exports.FIRING_OUTCOMES.includes(firing.outcome)) {
-            throw new Error(`Unknown firing outcome "${firing.outcome}". Use one of: ${exports.FIRING_OUTCOMES.join(', ')}.`);
-        }
-        if (!firing.key || !isValidDate(firing.date))
+/** Resolve correction chains independent of machine-log order. Conflicting siblings remain unresolved. */
+function currentAssessedOutcomes(store, scope = {}) {
+    const legacyOnlyDamage = store.evidence?.status === 'partial'
+        && store.evidence.observations.length === 1 && store.evidence.observations[0] === 'malformed-records';
+    // Invalid historical totals are excluded independently. They neither erase
+    // validated incident judgments nor authorize replacing the damaged snapshot.
+    if (store.evidence && store.evidence.status !== 'reliable' && !legacyOnlyDamage)
+        throw new Error('assessment-history-unavailable');
+    const groups = new Map();
+    for (const record of Object.values(store.outcomeAssessments ?? {})) {
+        (0, outcome_types_1.validateOutcomeAssessmentRecord)(record);
+        if (!(0, outcome_types_1.matchesOutcomeScope)(record, scope))
             continue;
-        const existing = store.entries[firing.key];
-        if (firing.sourceRef && existing?.fired.seenSources.includes(firing.sourceRef)) {
-            alreadyRecorded += 1;
-            continue;
-        }
-        events.push(firingEvent(firing));
+        const key = (0, outcome_types_1.assessmentKey)(record);
+        groups.set(key, [...(groups.get(key) ?? []), record]);
     }
-    if (events.length > 0) {
-        if ((options.integrityMode ?? 'throw') === 'throw') {
-            assertScopedIntegrity(store, events, options.limits, now);
+    return [...groups.values()].map(records => {
+        const revisions = [...records].sort((a, b) => a.revision - b.revision);
+        let previous;
+        for (const record of revisions) {
+            if (record.revision !== (previous?.revision ?? 0) + 1 || record.expectedPriorDigest !== (previous?.digest ?? null)) {
+                throw new Error('assessment-history-conflict');
+            }
+            previous = record;
         }
-        (0, learning_usage_events_1.appendEvents)(eventDir, events, options.machineId);
-        // Unlike the offer path, this republishes the snapshot. `record-firings` runs
-        // from the CLI once per retrospective, so the fold is cheap, and it makes the
-        // store file current the moment an operator's write returns rather than at
-        // whatever point a later reader happens to refresh it. The offer path stays
-        // append-only, because that is the one that runs on every `fraim_connect`.
-        readUsageStore(storePath, { limits: options.limits, now, eventDir, refreshSnapshot: 'always' });
-    }
-    return { recorded: events.length, alreadyRecorded };
+        return previous;
+    });
 }
-/**
- * E, CLI form: refuse to write a batch that would put an entry into the
- * impossible state the issue reports on 58 of its 223 entries.
- */
-function assertScopedIntegrity(store, events, limits, now) {
-    const projected = {
-        version: store.version,
-        updatedAt: store.updatedAt,
-        entries: JSON.parse(JSON.stringify(store.entries)),
-        foldedThroughBytes: store.foldedThroughBytes,
-        offersEraStart: store.offersEraStart,
-    };
-    for (const event of events)
-        applyEvent(projected, event, limits, now);
-    for (const event of events) {
-        const record = projected.entries[event.key];
-        if (!record)
-            continue;
-        // 'log' basis: a refusal must never rest on a number that can over-count.
-        const violation = integrityViolation(record, projected.offersEraStart, 'log');
-        if (violation) {
-            throw new Error(`Refusing to record firings for ${event.key}: ${violation.detail} Run \`learning-usage verify\` for the full integrity picture before forcing this through.`);
-        }
-    }
+function readAssessedOutcomes(storePath = resolveUsageStorePath(), scope = {}) {
+    return currentAssessedOutcomes(readUsageStore(storePath, { refreshSnapshot: 'never' }), scope);
 }
-/**
- * R5: record that an entry's title changed, so a firing written before the edit
- * still resolves to it. Identity lives on the entry; this keeps the store's title
- * index able to follow a rename.
- */
-function noteTitleChange(key, newTitle, options) {
+/** Sleep commits one validated decision through the existing recoverable usage journal. */
+function recordAssessedOutcome(record, options = {}) {
+    (0, outcome_types_1.validateOutcomeAssessmentRecord)(record);
     const storePath = options.storePath ?? resolveUsageStorePath();
-    const eventDir = options.eventDir ?? (0, learning_usage_events_1.resolveEventDir)(storePath);
-    const store = readUsageStore(storePath, { limits: options.limits, now: options.now, eventDir });
-    const record = store.entries[key];
-    if (!record)
-        return;
-    rememberTitle(record, newTitle);
-    store.updatedAt = (options.now ?? new Date()).toISOString();
-    writeUsageSnapshot(store, storePath);
+    return (0, proposal_queue_1.withFileLock)(storePath, () => {
+        const store = readUsageStore(storePath, { refreshSnapshot: 'never' });
+        const scope = { key: (0, outcome_types_1.assessmentKey)(record) };
+        const current = currentAssessedOutcomes(store, scope)[0];
+        if (store.outcomeAssessments?.[record.digest])
+            return store.outcomeAssessments[record.digest];
+        if (record.expectedPriorDigest !== (current?.digest ?? null) || record.revision !== (current?.revision ?? 0) + 1)
+            throw new Error('assessment-stale-revision');
+        (0, learning_usage_events_1.appendEvents)((0, learning_usage_events_1.resolveEventDir)(storePath), [{ kind: 'assessment', assessment: record }]);
+        const persisted = readAssessedOutcomes(storePath, scope).find(item => item.digest === record.digest);
+        if (!persisted)
+            throw new Error('assessment-write-unverified');
+        return persisted;
+    });
 }
 function pruneUsageStore(limits, options = {}) {
     const storePath = options.storePath ?? resolveUsageStorePath();
@@ -1046,7 +745,6 @@ function compactUsageEvents(options) {
     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.
@@ -1069,6 +767,8 @@ function compactUsageEvents(options) {
         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 === 'assessment')
+            return !isSupportedUsageEvent(event);
         if (event.kind !== 'offer' && event.kind !== 'firing')
             return true;
         const date = typeof event.date === 'string' ? event.date : '';