fraim 2.0.270 → 2.0.271

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

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractLegacyTitle = exports.parseFiringSection = void 0;
+exports.recordAttestationsFromRetrospective = recordAttestationsFromRetrospective;
+exports.runBackfill = runBackfill;
+/**
+ * Issue #1103 — turning an attestation into a usage record.
+ *
+ * The retrospective is the durable record of a firing; the usage store is derived
+ * from it (R17). So there is exactly one parser (`learning-firing-parser.ts`) and
+ * one recorder here, used by two entry points: the live attestation at the end of
+ * a job, and the backfill over the retrospectives already on disk (R15).
+ *
+ * Matching is an id or an exact title, and nothing else. R5 forbids resolving a
+ * prose reference to the closest title, and an unmatched item is reported rather
+ * than guessed at: a wrong match writes a firing onto the wrong entry, which is
+ * worse than no firing at all.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const learning_usage_store_1 = require("./learning-usage-store");
+const learning_firing_parser_1 = require("./learning-firing-parser");
+const learning_context_builder_1 = require("./learning-context-builder");
+// Re-exported so callers that only need one of the two halves keep one import.
+var learning_firing_parser_2 = require("./learning-firing-parser");
+Object.defineProperty(exports, "parseFiringSection", { enumerable: true, get: function () { return learning_firing_parser_2.parseFiringSection; } });
+Object.defineProperty(exports, "extractLegacyTitle", { enumerable: true, get: function () { return learning_firing_parser_2.extractLegacyTitle; } });
+function buildEntryIndex(workspaceRoot, userId) {
+    const byId = new Map();
+    const byTitle = new Map();
+    // Every scope a firing could name: the manager's own entries, the org entries
+    // the agent also reads, and the manager-coaching family.
+    for (const scope of ['manager', 'org', 'reverse']) {
+        let entries = [];
+        try {
+            entries = (0, learning_context_builder_1.readPreservedLearnings)(workspaceRoot, userId, scope);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.id && !byId.has(entry.id))
+                byId.set(entry.id, entry);
+            const key = (0, learning_usage_store_1.normalizeEntryTitle)(entry.title);
+            if (!byTitle.has(key))
+                byTitle.set(key, entry);
+        }
+    }
+    return { byId, byTitle };
+}
+function fileTypeOf(entry) {
+    return learning_context_builder_1.CATEGORY_TO_FILETYPE[entry.category] ?? 'mistake-patterns';
+}
+function retrospectiveDate(content, fallback) {
+    const match = content.match(/^date:\s*(\d{4}-\d{2}-\d{2})\s*$/m);
+    return match ? match[1] : fallback;
+}
+/**
+ * Record the firings a retrospective attests. Idempotent per (entry, source), so a
+ * re-run, or a backfill that overlaps a live attestation, cannot inflate a count.
+ */
+function recordAttestationsFromRetrospective(workspaceRoot, userId, options) {
+    const limits = options.limits ?? (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const parsed = (0, learning_firing_parser_1.parseFiringSection)(options.content, { source: options.source, legacy: options.legacy });
+    const date = options.date ?? retrospectiveDate(options.content, new Date().toISOString().slice(0, 10));
+    const index = buildEntryIndex(workspaceRoot, userId);
+    const unmatched = [];
+    const inputs = [];
+    for (const item of parsed.items) {
+        let entry;
+        if (item.id) {
+            entry = index.byId.get(item.id);
+            if (!entry) {
+                unmatched.push({
+                    id: item.id,
+                    title: item.title,
+                    reason: `No entry carries the id ${item.id}. Reported unmatched rather than assigned to the closest title.`,
+                    raw: item.raw,
+                });
+                continue;
+            }
+        }
+        else {
+            entry = index.byTitle.get((0, learning_usage_store_1.normalizeEntryTitle)(item.title));
+            if (!entry) {
+                unmatched.push({
+                    id: null,
+                    title: item.title,
+                    reason: 'No entry has exactly this title. Exact titles match; a paraphrase is reported rather than resolved by similarity.',
+                    raw: item.raw,
+                });
+                continue;
+            }
+        }
+        const fileType = fileTypeOf(entry);
+        inputs.push({
+            key: entry.id ?? (0, learning_usage_store_1.titleUsageKey)(fileType, entry.title),
+            family: 'learning',
+            title: entry.title,
+            fileType,
+            level: entry.level,
+            outcome: item.outcome,
+            note: item.note,
+            job: options.job,
+            date,
+            agent: options.agent,
+            model: options.model,
+            source: item.format === 'legacy' ? 'backfill-legacy' : 'attested',
+            sourceRef: options.source,
+        });
+    }
+    let applied = 0;
+    let alreadyRecorded = 0;
+    if (inputs.length > 0) {
+        const result = (0, learning_usage_store_1.recordFirings)(inputs, { limits, now: options.now, storePath: options.storePath });
+        applied = result.recorded;
+        alreadyRecorded = result.alreadyRecorded;
+    }
+    return {
+        source: options.source,
+        sectionState: parsed.sectionState,
+        itemsRead: parsed.items.length + parsed.rejected.length,
+        applied,
+        alreadyRecorded,
+        unmatched,
+        rejected: parsed.rejected,
+    };
+}
+function jobFromFrontmatter(content) {
+    const match = content.match(/^job:\s*(.+)$/m);
+    return match ? match[1].trim() : 'unknown';
+}
+/**
+ * Read every retrospective and apply the firings it attests.
+ *
+ * Best effort by design (R15): only an id or an exact title resolves, and the
+ * unmatched count is reported rather than resolved by fuzzy matching. A low match
+ * rate is an expected outcome to state, not a failure to hide — only a small
+ * fraction of the existing attestations name a machine-matchable identifier.
+ *
+ * A retrospective already stamped `synthesized` is still read: being synthesized
+ * for learning content is not the same as having contributed usage data.
+ */
+function runBackfill(workspaceRoot, userId, options) {
+    const limits = options.limits ?? (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const dir = options.retrospectivesDir ?? (0, path_1.join)(workspaceRoot, 'docs', 'retrospectives');
+    const report = {
+        filesScanned: 0, filesWithSection: 0, itemsRead: 0, applied: 0,
+        alreadyRecorded: 0, unmatched: [], rejected: [], synthesizedFilesRead: 0,
+    };
+    if (!(0, fs_1.existsSync)(dir))
+        return report;
+    let files;
+    try {
+        files = (0, fs_1.readdirSync)(dir).filter((f) => f.endsWith('.md'));
+    }
+    catch {
+        return report;
+    }
+    for (const file of files) {
+        let content;
+        try {
+            content = (0, fs_1.readFileSync)((0, path_1.join)(dir, file), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        report.filesScanned += 1;
+        if (/^synthesized:\s*\S/m.test(content))
+            report.synthesizedFilesRead += 1;
+        const result = recordAttestationsFromRetrospective(workspaceRoot, userId, {
+            content,
+            source: `docs/retrospectives/${file}`,
+            job: jobFromFrontmatter(content),
+            agent: options.agent,
+            model: options.model,
+            legacy: true,
+            limits,
+            now: options.now,
+            storePath: options.storePath,
+        });
+        if (result.sectionState !== 'absent')
+            report.filesWithSection += 1;
+        report.itemsRead += result.itemsRead;
+        report.applied += result.applied;
+        report.alreadyRecorded += result.alreadyRecorded;
+        report.unmatched.push(...result.unmatched);
+        report.rejected.push(...result.rejected);
+    }
+    return report;
+}

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

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUsageLookup = buildUsageLookup;
+exports.lookupUsage = lookupUsage;
+exports.resolveCurrentModel = resolveCurrentModel;
+/**
+ * Issue #1103 — projecting the usage record into the shapes its readers need.
+ *
+ * The store owns writing and persistence; this owns turning what is stored into
+ * what a scorer, a surface, or a report asks for. Split out because those are two
+ * jobs with different reasons to change: the record's schema changes when the
+ * privacy or retention contract changes, and these projections change when a
+ * consumer needs a different view.
+ *
+ * Nothing here writes.
+ */
+const learning_usage_store_1 = require("./learning-usage-store");
+function toLookupValue(record) {
+    return {
+        key: record.key,
+        offered: record.offered.total,
+        offeredAboveThreshold: record.offered.aboveThreshold,
+        fired: record.fired.byOutcome.prevented + record.fired.byOutcome.applied,
+        firedTotalAttestations: record.fired.total,
+        lastFired: record.fired.lastFiredAt,
+        lastOffered: record.offered.lastOfferedAt,
+        firedUnder: Object.keys(record.fired.byModel),
+        byOutcome: record.fired.byOutcome,
+        log: record.fired.log,
+    };
+}
+/**
+ * A lookup keyed by every identifier that resolves to a record: the entry id, and
+ * every title the entry has been known by. That is what lets a scorer look up an
+ * entry by whichever handle it has.
+ */
+function buildUsageLookup(store) {
+    const lookup = new Map();
+    for (const record of Object.values(store.entries)) {
+        const value = toLookupValue(record);
+        lookup.set(record.key, value);
+        if (record.fileType) {
+            for (const title of record.titles) {
+                lookup.set((0, learning_usage_store_1.titleUsageKey)(record.fileType, title), value);
+            }
+        }
+    }
+    return lookup;
+}
+/**
+ * Resolve the usage for one entry from whichever handles it has. Prefers the id,
+ * because a title is only a fallback for entries the id migration has not reached.
+ */
+function lookupUsage(lookup, id, fileType, title) {
+    if (id) {
+        const byId = lookup.get(id);
+        if (byId)
+            return byId;
+    }
+    return lookup.get((0, learning_usage_store_1.titleUsageKey)(fileType, title));
+}
+/**
+ * The model with the most recent offer. Used as "the current model" for the
+ * per-model retirement question, so it follows the agent in use rather than
+ * needing to be configured.
+ */
+function resolveCurrentModel(store) {
+    let bestDate = '';
+    let bestModel = null;
+    for (const record of Object.values(store.entries)) {
+        for (const entry of record.offered.log) {
+            if (entry.model && entry.date >= bestDate) {
+                bestDate = entry.date;
+                bestModel = entry.model;
+            }
+        }
+    }
+    return bestModel;
+}

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

@@ -0,0 +1,417 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOCK_ADVANCING_OUTCOMES = exports.FIRING_OUTCOMES = void 0;
+exports.resolveUsageStorePath = resolveUsageStorePath;
+exports.resolveUsageLimits = resolveUsageLimits;
+exports.normalizeEntryTitle = normalizeEntryTitle;
+exports.titleUsageKey = titleUsageKey;
+exports.ruleUsageKey = ruleUsageKey;
+exports.readUsageStore = readUsageStore;
+exports.sanitizeNote = sanitizeNote;
+exports.recordOffers = recordOffers;
+exports.recordFirings = recordFirings;
+exports.noteTitleChange = noteTitleChange;
+exports.pruneUsageStore = pruneUsageStore;
+/**
+ * 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.
+ *
+ * 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.
+ */
+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");
+// ── 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.
+ */
+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.
+ */
+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.
+ */
+const DEFAULT_OFFER_LOG_LIMIT = 50;
+/** Open Question 2: configurable and greater than a handful. */
+const DEFAULT_RETIREMENT_OFFER_THRESHOLD = 10;
+/** R16: one line, bounded, no fences. Long enough for a sentence, short enough to be useless as a transcript. */
+const MAX_NOTE_LENGTH = 240;
+// ── Paths and config ─────────────────────────────────────────────────────────
+/**
+ * The store path, inside the manager layer so the existing git-backend guardrail
+ * covers it. `resolvePackHome` never touches the network and never throws.
+ */
+function resolveUsageStorePath() {
+    return (0, path_1.join)((0, pack_home_1.resolvePackHome)('manager').contentRoot, 'usage', STORE_FILE_NAME);
+}
+function readWorkspaceConfig(workspaceRoot) {
+    try {
+        const configPath = (0, project_fraim_paths_1.getWorkspaceConfigPath)(workspaceRoot);
+        if (!(0, fs_1.existsSync)(configPath))
+            return {};
+        return JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function positiveInt(value, fallback) {
+    return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function resolveUsageLimits(workspaceRoot) {
+    const usage = readWorkspaceConfig(workspaceRoot)?.learning?.usage;
+    const block = usage && typeof usage === 'object' && !Array.isArray(usage) ? usage : {};
+    let retentionDays = -1;
+    try {
+        retentionDays = (0, artifact_retention_cleanup_1.resolveArtifactRetentionConfig)(workspaceRoot).values.learning_usage;
+    }
+    catch {
+        // Retention config is advisory here; a malformed config must not stop a write.
+    }
+    return {
+        firingLogLimit: positiveInt(block.firingLogLimit, DEFAULT_FIRING_LOG_LIMIT),
+        offerLogLimit: positiveInt(block.offerLogLimit, DEFAULT_OFFER_LOG_LIMIT),
+        retirementOfferThreshold: positiveInt(block.retirementOfferThreshold, DEFAULT_RETIREMENT_OFFER_THRESHOLD),
+        retentionDays: typeof retentionDays === 'number' ? retentionDays : -1,
+    };
+}
+// ── Keys ─────────────────────────────────────────────────────────────────────
+/** Normalize a title for keying. Case and whitespace only: never a similarity measure (D4). */
+function normalizeEntryTitle(title) {
+    return title.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+/**
+ * The fallback key for an entry that carries no `**Id**` line yet, so the feature
+ * works before the id migration has run. Namespaced by family so the same title
+ * in two families is two entries.
+ */
+function titleUsageKey(fileType, title) {
+    return `T:${fileType}:${normalizeEntryTitle(title)}`;
+}
+/** The key for a rule file, namespaced so it can never collide with a learning id. */
+function ruleUsageKey(displayPath) {
+    return `R:${displayPath.replace(/\\/g, '/')}`;
+}
+// ── Read and write ───────────────────────────────────────────────────────────
+function emptyStore() {
+    return { version: STORE_VERSION, updatedAt: new Date(0).toISOString(), entries: {} };
+}
+/**
+ * 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 `fraim learning-usage
+ * report` and `candidates` 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.
+ */
+function isUsableRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    const offered = record.offered;
+    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);
+}
+/**
+ * A missing or corrupt store reads as empty. It is derived data, so losing it is
+ * recoverable and must never break the loader that reads it.
+ */
+function readUsageStore(storePath = resolveUsageStorePath()) {
+    try {
+        if (!(0, fs_1.existsSync)(storePath))
+            return emptyStore();
+        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();
+        }
+        // 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.
+        const entries = {};
+        for (const [key, value] of Object.entries(parsed.entries)) {
+            if (isUsableRecord(value))
+                entries[key] = value;
+        }
+        return { version: parsed.version ?? STORE_VERSION, updatedAt: parsed.updatedAt ?? emptyStore().updatedAt, entries };
+    }
+    catch {
+        return emptyStore();
+    }
+}
+function writeUsageStore(store, storePath = resolveUsageStorePath()) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(storePath), { recursive: true });
+    (0, fs_1.writeFileSync)(storePath, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+}
+// ── Mutation helpers ─────────────────────────────────────────────────────────
+function emptyOutcomeCounts() {
+    return { prevented: 0, applied: 0, 'not-applicable': 0, ignored: 0, 'not-offered': 0 };
+}
+function ensureRecord(store, key, family, fileType, level) {
+    const existing = store.entries[key];
+    if (existing) {
+        if (fileType && !existing.fileType)
+            existing.fileType = fileType;
+        if (level && !existing.level)
+            existing.level = level;
+        return existing;
+    }
+    const created = {
+        key,
+        family,
+        titles: [],
+        fileType: fileType ?? null,
+        level: level ?? null,
+        offered: { total: 0, aboveThreshold: 0, byModel: {}, lastOfferedAt: null, log: [] },
+        fired: {
+            total: 0, byOutcome: emptyOutcomeCounts(), byModel: {},
+            firstFiredAt: null, lastFiredAt: null, lastAttestedAt: null, log: [], seenSources: [],
+        },
+    };
+    store.entries[key] = created;
+    return created;
+}
+function rememberTitle(record, title) {
+    if (!title)
+        return;
+    const trimmed = title.trim();
+    if (!trimmed)
+        return;
+    const normalized = normalizeEntryTitle(trimmed);
+    const already = record.titles.findIndex((t) => normalizeEntryTitle(t) === normalized);
+    // Already the most recent title: nothing to do. Guard the empty case explicitly,
+    // because findIndex returns -1 and length - 1 is also -1 on an empty list.
+    if (record.titles.length > 0 && already === record.titles.length - 1)
+        return;
+    if (already >= 0)
+        record.titles.splice(already, 1);
+    record.titles.push(trimmed);
+}
+/**
+ * R16: reduce an attested note to a single bounded line. This is the control that
+ * keeps a diff, a prompt, or a transcript out of a behavioural record.
+ */
+function sanitizeNote(note) {
+    const oneLine = String(note ?? '')
+        .replace(/```+/g, ' ')
+        .replace(/[\r\n\t]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return oneLine.length > MAX_NOTE_LENGTH ? `${oneLine.slice(0, MAX_NOTE_LENGTH - 1).trimEnd()}…` : oneLine;
+}
+function maxDate(a, b) {
+    if (!a)
+        return b;
+    return b > a ? b : a;
+}
+function minDate(a, b) {
+    if (!a)
+        return b;
+    return b < a ? b : a;
+}
+function isValidDate(value) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(new Date(value).getTime());
+}
+function withinRetention(date, retentionDays, now) {
+    if (retentionDays < 0)
+        return true;
+    const parsed = new Date(date).getTime();
+    if (Number.isNaN(parsed))
+        return true;
+    return (now.getTime() - parsed) / 86_400_000 <= retentionDays;
+}
+/**
+ * Trim one entry's logs: drop records outside the retention window, then keep the
+ * newest N. Aggregates are never touched, so R16a's second criterion holds.
+ */
+function trimLogs(record, limits, now) {
+    const byDate = (a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0);
+    record.offered.log = record.offered.log
+        .filter((r) => withinRetention(r.date, limits.retentionDays, now))
+        .sort(byDate)
+        .slice(-limits.offerLogLimit);
+    record.fired.log = record.fired.log
+        .filter((r) => withinRetention(r.date, limits.retentionDays, now))
+        .sort(byDate)
+        .slice(-limits.firingLogLimit);
+}
+/**
+ * R1 and R2: write one offer record per listed entry, without any agent
+ * involvement and without depending on the agent reading the file.
+ */
+function recordOffers(offers, options) {
+    const storePath = options.storePath ?? resolveUsageStorePath();
+    const now = options.now ?? new Date();
+    const store = readUsageStore(storePath);
+    let recorded = 0;
+    for (const offer of offers) {
+        if (!offer.key || !isValidDate(offer.date))
+            continue;
+        const record = ensureRecord(store, offer.key, offer.family, offer.fileType, offer.level);
+        rememberTitle(record, offer.title);
+        record.offered.total += 1;
+        if (offer.aboveThreshold)
+            record.offered.aboveThreshold += 1;
+        if (offer.model)
+            record.offered.byModel[offer.model] = (record.offered.byModel[offer.model] ?? 0) + 1;
+        record.offered.lastOfferedAt = maxDate(record.offered.lastOfferedAt, offer.date);
+        record.offered.log.push({
+            date: offer.date,
+            job: offer.job,
+            agent: offer.agent ?? null,
+            model: offer.model ?? null,
+            aboveThreshold: Boolean(offer.aboveThreshold),
+        });
+        trimLogs(record, options.limits, now);
+        recorded += 1;
+    }
+    if (recorded > 0) {
+        store.updatedAt = now.toISOString();
+        writeUsageStore(store, storePath);
+    }
+    return { recorded, entries: Object.keys(store.entries).length };
+}
+/**
+ * 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.
+ */
+function recordFirings(firings, options) {
+    const storePath = options.storePath ?? resolveUsageStorePath();
+    const now = options.now ?? new Date();
+    const store = readUsageStore(storePath);
+    let recorded = 0;
+    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))
+            continue;
+        const record = ensureRecord(store, firing.key, firing.family, firing.fileType, firing.level);
+        if (firing.sourceRef && record.fired.seenSources.includes(firing.sourceRef)) {
+            alreadyRecorded += 1;
+            continue;
+        }
+        rememberTitle(record, firing.title);
+        record.fired.total += 1;
+        record.fired.byOutcome[firing.outcome] += 1;
+        record.fired.lastAttestedAt = maxDate(record.fired.lastAttestedAt, firing.date);
+        if (exports.CLOCK_ADVANCING_OUTCOMES.includes(firing.outcome)) {
+            record.fired.firstFiredAt = minDate(record.fired.firstFiredAt, firing.date);
+            record.fired.lastFiredAt = maxDate(record.fired.lastFiredAt, firing.date);
+            if (firing.model)
+                record.fired.byModel[firing.model] = (record.fired.byModel[firing.model] ?? 0) + 1;
+        }
+        record.fired.log.push({
+            date: firing.date,
+            outcome: firing.outcome,
+            job: firing.job,
+            agent: firing.agent ?? null,
+            model: firing.model ?? null,
+            note: sanitizeNote(firing.note),
+            source: firing.source ?? 'attested',
+        });
+        if (firing.sourceRef)
+            record.fired.seenSources.push(firing.sourceRef);
+        trimLogs(record, options.limits, now);
+        recorded += 1;
+    }
+    if (recorded > 0 || alreadyRecorded > 0) {
+        store.updatedAt = now.toISOString();
+        writeUsageStore(store, storePath);
+    }
+    return { recorded, alreadyRecorded };
+}
+/**
+ * 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) {
+    const storePath = options.storePath ?? resolveUsageStorePath();
+    const store = readUsageStore(storePath);
+    const record = store.entries[key];
+    if (!record)
+        return;
+    rememberTitle(record, newTitle);
+    store.updatedAt = (options.now ?? new Date()).toISOString();
+    writeUsageStore(store, storePath);
+}
+/** Apply retention and log bounds across the whole store. Reports what it dropped. */
+function pruneUsageStore(limits, options = {}) {
+    const storePath = options.storePath ?? resolveUsageStorePath();
+    const now = options.now ?? new Date();
+    const store = readUsageStore(storePath);
+    let prunedOfferRecords = 0;
+    let prunedFiringRecords = 0;
+    for (const record of Object.values(store.entries)) {
+        const offersBefore = record.offered.log.length;
+        const firingsBefore = record.fired.log.length;
+        trimLogs(record, limits, now);
+        prunedOfferRecords += offersBefore - record.offered.log.length;
+        prunedFiringRecords += firingsBefore - record.fired.log.length;
+    }
+    if (prunedOfferRecords > 0 || prunedFiringRecords > 0) {
+        store.updatedAt = now.toISOString();
+        writeUsageStore(store, storePath);
+    }
+    return { prunedOfferRecords, prunedFiringRecords, entries: Object.keys(store.entries).length };
+}