fraim 2.0.346 → 2.0.348

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

@@ -4,28 +4,8 @@ exports.COMPACTION_ADVISORY_BYTES = void 0;
 exports.listUnmergedStoreCopies = listUnmergedStoreCopies;
 exports.findTwinPairs = findTwinPairs;
 exports.buildVerifyReport = buildVerifyReport;
-/**
- * Issue #1752 E2 — the integrity picture for the usage record, in one output.
- *
- * Every defect in issue #1752 was found by a manager reading raw JSON during a
- * `sleep-on-learnings` run, one at a time, over one session. This is the command
- * that answers "can I trust what the record just told me" before acting on a
- * recommendation, and it is the regression guard that makes every defect class
- * visible in one place instead of one at a time.
- *
- * It reports and never blocks. Nothing here treats a finding as a gate: it states
- * what it found, and the manager decides.
- *
- * ## Recovery boundary
- *
- * Rebuild only the snapshot, keeping the event directory intact. The retained
- * events recover the offers and firings they cover; retrospective backfill can
- * supplement older firings but cannot recreate offers. Normal compaction keeps
- * lifetime aggregate totals in the snapshot, so a backup is required before
- * discarding it if history already pruned from events must remain inspectable.
- * Rebuilding cannot invent missing history or fix identities still present in
- * the authoritative events. Verify reports those limitations rather than
- * claiming that deleting the usage directory is a lossless repair.
+/** Explicit historical-store diagnostics. Snapshot/checkpoint/journal provenance must
+ * establish recovery; no diagnostic can reconstruct already discarded observations.
  */
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -134,22 +114,12 @@ function findTwinPairs(entries) {
  * Split out of `buildVerifyReport` so that function reads as what it is: an
  * assembly of independently-computed parts.
  */
-function scanRecordsForIntegrity(records, offersEraStart) {
-    const invariantViolations = [];
+function scanRecordsForIntegrity(records) {
     const caseVariantModelBuckets = [];
     const unknownModelAttribution = [];
     for (const record of records) {
         const title = record.titles[record.titles.length - 1] ?? record.key;
-        const violation = record.integrity ?? (0, learning_usage_store_1.integrityViolation)(record, offersEraStart);
-        if (violation) {
-            invariantViolations.push({
-                key: record.key, title,
-                offered: record.offered.total,
-                firedInEra: record.offered.total + violation.count,
-                detail: violation.detail,
-            });
-        }
-        for (const buckets of [record.offered.byModel, record.fired.byModel]) {
+        for (const buckets of [record.fired.byModel]) {
             const byNormalized = new Map();
             for (const raw of Object.keys(buckets)) {
                 const normalized = (0, learning_usage_store_1.normalizeModelName)(raw) ?? raw;
@@ -161,15 +131,15 @@ function scanRecordsForIntegrity(records, offersEraStart) {
                 }
             }
         }
-        // Only a clock-advancing firing that produced no bucket means the model went
+        // Only a positive outcome that produced no bucket means the model went
         // unrecorded. An entry whose outcomes are all `ignored` has an empty bucket
         // set correctly, and that is information rather than a gap.
-        const clockAdvancing = record.fired.byOutcome.prevented + record.fired.byOutcome.applied;
+        const positiveOutcomes = record.fired.byOutcome.prevented + record.fired.byOutcome.applied;
         if ((0, learning_usage_eligibility_1.modelAttributionIncomplete)(record)) {
-            unknownModelAttribution.push({ key: record.key, title, fired: clockAdvancing });
+            unknownModelAttribution.push({ key: record.key, title, fired: positiveOutcomes });
         }
     }
-    return { invariantViolations, caseVariantModelBuckets, unknownModelAttribution };
+    return { caseVariantModelBuckets, unknownModelAttribution };
 }
 function buildVerifyReport(options) {
     const now = options.now ?? new Date();
@@ -178,7 +148,7 @@ function buildVerifyReport(options) {
     const snapshot = (0, learning_usage_store_1.readUsageSnapshot)(options.snapshotPath);
     const logs = (0, learning_usage_events_1.listEventLogs)(eventDir);
     const records = Object.values(store.entries);
-    const { invariantViolations, caseVariantModelBuckets, unknownModelAttribution } = scanRecordsForIntegrity(records, store.offersEraStart);
+    const { caseVariantModelBuckets, unknownModelAttribution } = scanRecordsForIntegrity(records);
     const twins = findTwinPairs(store.entries);
     const storeCopies = listUnmergedStoreCopies(options.snapshotPath);
     const checkpoints = snapshot.foldedThroughBytes ?? {};
@@ -191,7 +161,6 @@ function buildVerifyReport(options) {
         entries: records.length,
         twinPairs: twins.pairs,
         unmatchedTitleKeys: twins.unmatched,
-        invariantViolations,
         caseVariantModelBuckets,
         unknownModelAttribution,
         storeCopies,

package/dist/src/local-mcp-server/stdio-server.js

@@ -77,7 +77,6 @@ const usage_collector_js_1 = require("./usage-collector.js");
 const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
 const token_adapter_registry_js_1 = require("./token-adapter-registry.js");
 const learning_context_builder_js_1 = require("./learning-context-builder.js");
-const learning_usage_store_js_1 = require("./learning-usage-store.js");
 const learning_domains_js_1 = require("../config/learning-domains.js");
 const skill_include_dedup_js_1 = require("./skill-include-dedup.js");
 const git_utils_1 = require("../core/utils/git-utils");
@@ -1731,7 +1730,6 @@ class FraimLocalMCPServer {
                         responseText += teamContextSection;
                         this.log(`[req:${requestId}] Injected team context from ${workspaceRoot}`);
                     }
-                    this.recordUsageOffers(workspaceRoot, userEmail, false, null, 'session', requestId);
                 }
                 if (this.latestConnectSyncWarning) {
                     responseText += `\n\n## Local Catalog\n${this.latestConnectSyncWarning}`;
@@ -1774,54 +1772,8 @@ class FraimLocalMCPServer {
             text += `\n\n---` + learningSection + teamContextSection;
             this.log(`[req:${requestId}] Injected job-focus learning/team context for ${userEmail} (domain: ${jobDomain ?? 'global'})`);
         }
-        this.recordUsageOffers(workspaceRoot, userEmail, true, jobDomain, String(jobName ?? 'unknown'), requestId);
         return text;
     }
-    /**
-     * Issue #1103 R1, R2 and R3: record what this context injection delivered.
-     *
-     * Written here because this is the only place that knows all of it at once: the
-     * files that were listed, the job, the agent, and the model. Nothing depends on
-     * the agent reading anything, which is R2, and the three auto-loaded rule files
-     * get a record for the first time, which is R3.
-     *
-     * Never throws and never blocks the response. Usage data is derived and optional:
-     * a failure here must not change what the agent is given.
-     */
-    recordUsageOffers(workspaceRoot, userEmail, forJob, domain, job, requestId) {
-        try {
-            const offered = [
-                ...(0, learning_context_builder_js_1.collectOfferedLearningEntries)(workspaceRoot, userEmail, forJob, domain),
-                ...(0, learning_context_builder_js_1.collectOfferedRuleFiles)(workspaceRoot, forJob),
-            ];
-            if (offered.length === 0)
-                return;
-            const collector = this.usageCollector;
-            const date = new Date().toISOString().slice(0, 10);
-            const limits = (0, learning_usage_store_js_1.resolveUsageLimits)(workspaceRoot);
-            const result = (0, learning_usage_store_js_1.recordOffers)(offered.map((entry) => ({
-                key: entry.key,
-                family: entry.family,
-                title: entry.title,
-                fileType: entry.fileType,
-                level: entry.level,
-                aboveThreshold: entry.aboveThreshold,
-                job,
-                date,
-                agent: collector?.getAgentName() ?? null,
-                // Issue #1752 C2: one model, one bucket. `GPT-5` and `gpt-5` were two,
-                // splitting the denominator of every per-model conclusion about it.
-                model: (0, learning_usage_store_js_1.normalizeModelName)(collector?.getAgentModel()),
-            })), { limits });
-            this.log(`[req:${requestId}] Recorded ${result.recorded} usage offers for job ${job} (write mode: append)`);
-        }
-        catch (error) {
-            // Issue #1752: name the log and the write mode. During the migration window
-            // "which path did this write take" is the first question on any report of
-            // missing data, and the answer was not in the logs.
-            this.log(`[req:${requestId}] Usage offer recording skipped (append, log ${(0, learning_usage_store_js_1.resolveEventDir)((0, learning_usage_store_js_1.resolveUsageStorePath)())}): ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
     /**
      * Resolve the learning domain for a `get_fraim_job` request (issue #806) from
      * the job's registry path, so the loader injects global + that domain's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.346",
+  "version": "2.0.348",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {
@@ -13,7 +13,15 @@
     "dist/registry/scripts/learning/entry-format.js",
     "dist/registry/scripts/learning/completion-state.js",
     "dist/registry/scripts/learning/corpus-audit.js",
+    "dist/registry/scripts/learning/entry-authoring.js",
     "dist/registry/scripts/learning/owner-identity.js",
+    "dist/registry/scripts/learning/outcome-types.js",
+    "dist/registry/scripts/learning/outcome-assessment.js",
+    "dist/registry/scripts/learning/proposal-queue.js",
+    "dist/registry/scripts/learning/run-record.js",
+    "dist/registry/scripts/learning/run-application.js",
+    "dist/registry/scripts/learning/run-publication.js",
+    "dist/registry/scripts/learning-usage/learning-source-record.js",
     "dist/src/local-mcp-server/",
     "dist/src/cli/",
     "!dist/src/cli/fraim-hub.js",

package/dist/src/local-mcp-server/learning-firing-parser.js

@@ -1,247 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractLegacyTitle = extractLegacyTitle;
-exports.parseFiringSection = parseFiringSection;
-/**
- * Issue #1103 — reading the firing section a retrospective attests.
- *
- * Pure parsing, no I/O and no store access: it turns the markdown of
- * `## Where Past Learnings Actually Fired` into typed items plus an explicit
- * section state, so silence, an unfilled template, and a genuinely empty section
- * are three different answers rather than one.
- *
- * Extracted from `learning-usage-attestation.ts`, which now owns resolving those
- * items to entries and writing the record. The split is along the boundary the
- * file already had: what a retrospective says, versus what that means for the
- * corpus.
- *
- * Matching is deliberately strict elsewhere; extraction here is deliberately
- * generous. R15 requires exact-title matching, and says nothing about how
- * tolerantly the title is read off the line. A narrow extractor would report most
- * of the corpus as unmatched for a formatting reason dressed up as an identity
- * one.
- */
-const learning_usage_store_1 = require("./learning-usage-store");
-const FIRING_SECTION_HEADING = /^#{1,6}\s+Where Past Learnings Actually Fired\s*$/i;
-const NEXT_SECTION_HEADING = /^#{1,6}\s+\S/;
-/**
- * The structured form R4 requires:
- *   `1. **[L-4f2a91c0de] Entry Title** - outcome: \`prevented\` - one sentence.`
- * The separator may be a hyphen, an en dash, or an em dash, because a human editing
- * a retrospective will not be careful about which.
- */
-// The id pattern matches what the entry reader accepts, not only what the generator
-// emits: a hand-written id in a learning file has to be referenceable from a
-// retrospective, or the two sides disagree about what an id is.
-const STRUCTURED_ITEM = /^\d+\.\s*\*\*\[(L-[0-9A-Za-z]{6,24})\]\s*(.+?)\*\*\s*[-–—:]+\s*outcome:\s*`?([A-Za-z-]+)`?\s*[-–—:]*\s*(.*)$/i;
-/** The same, without an id, for an entry the id migration has not reached. */
-const STRUCTURED_ITEM_NO_ID = /^\d+\.\s*\*\*(.+?)\*\*\s*[-–—:]+\s*outcome:\s*`?([A-Za-z-]+)`?\s*[-–—:]*\s*(.*)$/i;
-/**
- * The legacy form: a numbered item whose leading bold segment names the entry.
- *
- * Measured across the real corpus (346 retrospectives, 828 numbered items in this
- * section, 819 of them with a leading bold segment), the shapes in use are:
- *
- *   1. **Pattern: "Entry Title" (graduated standing rule)** - prose
- *   1. **`[P-HIGH] Entry Title` (score 19.0, PRs #507 and #518)** - prose
- *   1. **Entry Title**: prose
- *   1. **`someIdentifier` gate**: prose
- *
- * Extraction is deliberately generous and matching is deliberately strict. R15
- * requires exact-title matching; it says nothing about how tolerantly the title is
- * read off the line. A narrow extractor would report most of the corpus as
- * unmatched for a formatting reason rather than an identity one, which is a
- * measurement error dressed up as a finding.
- */
-const LEGACY_ITEM = /^\d+\.\s*(.*)$/;
-const LEGACY_BOLD_SEGMENT = /^\*\*(.+?)\*\*\s*(.*)$/;
-/** An explicit statement that nothing fired (R4's second criterion). */
-const DECLARED_NONE = /^[-*]?\s*none\b/i;
-/** Placeholder text from the unfilled template, which must never be read as a firing. */
-const TEMPLATE_PLACEHOLDER = /<[^>]*>|\{[^}]*\}/;
-/** Split a bare `<title><separator><prose>` string on the first colon or spaced dash. */
-function splitTitleAndNote(text) {
-    const split = text.match(/^(.+?)\s*(?::|\s[-–—]\s)\s*(.*)$/);
-    return {
-        title: extractLegacyTitle(split ? split[1] : text),
-        note: split ? split[2].trim() : '',
-    };
-}
-/**
- * Read a legacy numbered item into a title and a one-sentence note.
- *
- * The leading bold segment usually names the entry, but in the oldest form the
- * bold segment is only the template's field label (`**Pattern**:`) and the title
- * follows it. Both are handled, because both are in the corpus.
- */
-/** The old template's field label. Only this justifies reading the title from what follows. */
-const LEGACY_FIELD_LABEL = /^pattern\s*:?\s*$/i;
-function parseLegacyItem(rest) {
-    const bold = rest.match(LEGACY_BOLD_SEGMENT);
-    if (bold) {
-        const remainder = bold[2].replace(/^\s*[-–—:]+\s*/, '').trim();
-        const boldTitle = extractLegacyTitle(bold[1]);
-        if (boldTitle)
-            return { title: boldTitle, note: remainder };
-        // The bold segment reduced to nothing. Read the title from what follows only
-        // when the segment was the template's field label; otherwise the bold text was
-        // something else that stripped away (a bare score parenthetical, say) and
-        // taking the prose after it as a title would attribute a firing to a sentence.
-        if (!LEGACY_FIELD_LABEL.test(bold[1].trim()))
-            return null;
-        const fromRemainder = splitTitleAndNote(remainder);
-        return fromRemainder.title ? { title: fromRemainder.title, note: fromRemainder.note } : null;
-    }
-    const bare = splitTitleAndNote(rest);
-    return bare.title ? { title: bare.title, note: bare.note } : null;
-}
-function extractSection(content) {
-    const lines = content.split(/\r?\n/);
-    const start = lines.findIndex((line) => FIRING_SECTION_HEADING.test(line.trim()));
-    if (start < 0)
-        return null;
-    const body = [];
-    for (let i = start + 1; i < lines.length; i++) {
-        const line = lines[i];
-        if (NEXT_SECTION_HEADING.test(line.trim()) && !FIRING_SECTION_HEADING.test(line.trim()))
-            break;
-        body.push(line);
-    }
-    return body;
-}
-function normalizeOutcome(raw) {
-    const candidate = raw.trim().toLowerCase();
-    return learning_usage_store_1.FIRING_OUTCOMES.includes(candidate) ? candidate : null;
-}
-/**
- * Read the entry title a legacy item is naming, stripping the decoration the
- * corpus actually carries: a `Pattern:` label, backticks, a severity or graduation
- * tag, a trailing score parenthetical, and surrounding quotes.
- *
- * Returns null when nothing usable is left, which is a reportable outcome rather
- * than a guess.
- */
-function extractLegacyTitle(boldSegment) {
-    let title = boldSegment.trim();
-    // A `Pattern:` or `Pattern` label, which is the old template's field name.
-    title = title.replace(/^pattern\s*:?\s*/i, '');
-    title = title.replace(/`/g, '');
-    // Trailing parentheticals: score, recurrence counts, PR references, corpus notes.
-    // Repeated because some items carry more than one.
-    let previous;
-    do {
-        previous = title;
-        title = title.replace(/\s*\([^()]*\)\s*$/, '').trim();
-    } while (title !== previous);
-    // A severity or graduation tag prefix.
-    title = title.replace(/^\[(P-CRITICAL|P-HIGH|P-MED|P-LOW|GRADUATED)\]\s*/i, '');
-    // Surrounding quotes, straight or curly.
-    title = title.replace(/^["'“‘](.*)["'”’]$/, '$1');
-    // A trailing corpus qualifier the corpus writes after a comma or dash, such as
-    // "(engineering corpus)" already removed above, or "- L2 org".
-    title = title.replace(/\s*[-–—]\s*(L2 org|L1|org)\s*$/i, '').trim();
-    return title.length > 0 ? title : null;
-}
-function parseFiringSection(content, options) {
-    const body = extractSection(content);
-    if (body === null) {
-        return { sectionState: 'absent', declaredNone: false, items: [], rejected: [] };
-    }
-    const lines = body.map((l) => l.trim()).filter(Boolean);
-    if (lines.length === 0) {
-        return { sectionState: 'empty', declaredNone: false, items: [], rejected: [] };
-    }
-    const items = [];
-    const rejected = [];
-    let sawDeclaredNone = false;
-    let sawPlaceholderItem = false;
-    let inFence = false;
-    for (const line of lines) {
-        // A fenced block in this section is illustration, not attestation. The template
-        // carries a worked example in one, and copying the template must not create
-        // firings for the entries the example names.
-        if (/^```/.test(line)) {
-            inFence = !inFence;
-            continue;
-        }
-        if (inFence)
-            continue;
-        if (DECLARED_NONE.test(line)) {
-            sawDeclaredNone = true;
-            continue;
-        }
-        // A line still carrying template placeholders is the unfilled template, not an
-        // attestation. Recording it would create a firing for an entry named "<entry
-        // title>", which is exactly the silent-garbage case R4's second criterion
-        // exists to make visible.
-        const isPlaceholder = TEMPLATE_PLACEHOLDER.test(line);
-        const structured = line.match(STRUCTURED_ITEM);
-        if (structured) {
-            if (isPlaceholder) {
-                sawPlaceholderItem = true;
-                continue;
-            }
-            const outcome = normalizeOutcome(structured[3]);
-            if (!outcome) {
-                rejected.push({ raw: line, reason: `Unknown outcome "${structured[3]}". Use one of: ${learning_usage_store_1.FIRING_OUTCOMES.join(', ')}.` });
-                continue;
-            }
-            items.push({ id: structured[1], title: structured[2].trim(), outcome, note: structured[4].trim(), format: 'structured', raw: line });
-            continue;
-        }
-        const noId = line.match(STRUCTURED_ITEM_NO_ID);
-        if (noId) {
-            if (isPlaceholder) {
-                sawPlaceholderItem = true;
-                continue;
-            }
-            // `**Pattern**: …` also matches this shape; keep it in the legacy lane.
-            if (/^pattern$/i.test(noId[1].trim())) {
-                rejected.push({ raw: line, reason: 'Legacy `**Pattern**:` item carrying an outcome is ambiguous. Write it in the structured form.' });
-                continue;
-            }
-            const outcome = normalizeOutcome(noId[2]);
-            if (!outcome) {
-                rejected.push({ raw: line, reason: `Unknown outcome "${noId[2]}". Use one of: ${learning_usage_store_1.FIRING_OUTCOMES.join(', ')}.` });
-                continue;
-            }
-            items.push({ id: null, title: noId[1].trim(), outcome, note: noId[3].trim(), format: 'structured-no-id', raw: line });
-            continue;
-        }
-        const legacy = options.legacy ? line.match(LEGACY_ITEM) : null;
-        if (legacy) {
-            if (isPlaceholder) {
-                sawPlaceholderItem = true;
-                continue;
-            }
-            const parsedLegacy = parseLegacyItem(legacy[1].trim());
-            if (!parsedLegacy) {
-                rejected.push({ raw: line, reason: 'No entry title could be read off this item.' });
-                continue;
-            }
-            const { title, note } = parsedLegacy;
-            // Membership in this section is the attestation that the entry fired and
-            // changed something, which is what the section's own template line says. The
-            // outcome is not inferred from the prose.
-            items.push({ id: null, title, outcome: 'applied', note, format: 'legacy', raw: line });
-            continue;
-        }
-        // A list item still carrying template placeholders is the unfilled template
-        // rather than an attestation, and is what distinguishes it from a genuinely
-        // empty section.
-        if (isPlaceholder && /^(\d+\.|[-*])\s/.test(line))
-            sawPlaceholderItem = true;
-    }
-    // A real item wins over a stray "None" line, because a template that has been
-    // filled in often still carries the guidance line underneath the items.
-    let sectionState;
-    if (items.length > 0 || rejected.length > 0)
-        sectionState = 'filled';
-    else if (sawDeclaredNone)
-        sectionState = 'declared-none';
-    else if (sawPlaceholderItem)
-        sectionState = 'unfilled-template';
-    else
-        sectionState = 'empty';
-    return { sectionState, declaredNone: sectionState === 'declared-none', items, rejected };
-}

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

@@ -1,238 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractLegacyTitle = exports.parseFiringSection = void 0;
-exports.recordAttestationsFromRetrospective = recordAttestationsFromRetrospective;
-exports.readRetrospectiveForAttestation = readRetrospectiveForAttestation;
-exports.runBackfill = runBackfill;
-const artifact_paths_1 = require("../../registry/scripts/artifact-paths");
-/**
- * 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_source_record_1 = require("./learning-source-record");
-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; } });
-const ENTRY_INDEX_READS = [
-    { scope: 'manager', level: 'machine' },
-    { scope: 'manager', level: 'project' },
-    { scope: 'org', level: 'machine' },
-    { scope: 'reverse', level: 'machine' },
-    { scope: 'reverse', level: 'project' },
-];
-function buildEntryIndex(workspaceRoot, userId) {
-    const byId = new Map();
-    const byTitle = new Map();
-    // Keep this list in parity with the preserved-entry levels that the offer
-    // path can surface. Storage resolution stays inside readPreservedLearnings.
-    for (const { scope, level } of ENTRY_INDEX_READS) {
-        let entries = [];
-        try {
-            entries = (0, learning_context_builder_1.readPreservedLearnings)(workspaceRoot, userId, scope, level);
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            const fileType = fileTypeOf(entry);
-            const attestable = {
-                // #1752 A1: one definition of what an entry is, shared with the offer
-                // path. These two disagreeing is defect 4.
-                key: (0, learning_usage_store_1.resolveEntryIdentity)({ id: entry.id, fileType, title: entry.title }).key,
-                family: 'learning',
-                title: entry.title,
-                fileType,
-                level: entry.level,
-            };
-            if (entry.id && !byId.has(entry.id))
-                byId.set(entry.id, attestable);
-            const titleKey = (0, learning_usage_store_1.normalizeEntryTitle)(entry.title);
-            if (!byTitle.has(titleKey))
-                byTitle.set(titleKey, attestable);
-        }
-    }
-    for (const rule of (0, learning_context_builder_1.collectOfferedRuleFiles)(workspaceRoot, true)) {
-        const attestable = {
-            key: rule.key,
-            family: 'rule',
-            title: rule.title,
-            fileType: rule.fileType,
-            level: rule.level,
-        };
-        if (!byId.has(rule.key))
-            byId.set(rule.key, attestable);
-        const titleKey = (0, learning_usage_store_1.normalizeEntryTitle)(rule.title);
-        if (!byTitle.has(titleKey))
-            byTitle.set(titleKey, attestable);
-        if (rule.id && !byId.has(rule.id))
-            byId.set(rule.id, attestable);
-    }
-    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;
-            }
-        }
-        inputs.push({
-            key: entry.key,
-            family: entry.family,
-            title: entry.title,
-            fileType: entry.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, integrityMode: options.integrityMode,
-        });
-        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,
-    };
-}
-// ── R15: backfill ────────────────────────────────────────────────────────────
-/** Resolve live attestation against its recorded home and immutable accounting identity. */
-function readRetrospectiveForAttestation(workspaceRoot, userId, filePath) {
-    let reason = 'Retrospective is outside configured learning homes';
-    for (const home of (0, learning_context_builder_1.getLearningInputHomes)(workspaceRoot)) {
-        const result = (0, learning_context_builder_1.readLearningSourceFile)((0, path_1.resolve)(filePath), home.root, home.contentRoot);
-        if (result.status !== 'valid') {
-            reason = result.reason;
-            continue;
-        }
-        if (result.record.kind !== 'retrospective' || result.record.author !== userId) {
-            throw new Error('Retrospective kind or author does not match this attestation');
-        }
-        return { content: result.content, record: result.record };
-    }
-    throw new Error(`Invalid learning retrospective: ${reason}`);
-}
-/** Read only typed future reflections, including archives, with stable accounting identity. */
-function runBackfill(workspaceRoot, userId, options) {
-    const limits = options.limits ?? (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
-    const report = {
-        filesScanned: 0, filesWithSection: 0, itemsRead: 0, applied: 0,
-        alreadyRecorded: 0, unmatched: [], rejected: [], synthesizedFilesRead: 0, invalidRecords: [],
-    };
-    const seen = new Set();
-    for (const home of (0, learning_context_builder_1.getLearningInputHomes)(workspaceRoot)) {
-        const paths = (0, artifact_paths_1.resolveLearningPaths)(home.root, home.contentRoot);
-        for (const dir of [paths.retrospectives, paths.archiveRetrospectives]) {
-            if (options.retrospectivesDir && (0, learning_source_record_1.normalizeLearningSourcePath)(dir) !== (0, learning_source_record_1.normalizeLearningSourcePath)(options.retrospectivesDir))
-                continue;
-            let files;
-            try {
-                if ((0, fs_1.lstatSync)(dir).isSymbolicLink())
-                    continue;
-                files = (0, fs_1.readdirSync)(dir).filter(f => f.endsWith('.md'));
-            }
-            catch {
-                continue;
-            }
-            for (const file of files) {
-                const filePath = (0, path_1.join)(dir, file);
-                const parsed = (0, learning_context_builder_1.readLearningSourceFile)(filePath, home.root, home.contentRoot);
-                if (parsed.status !== 'valid') {
-                    if (parsed.status === 'invalid')
-                        report.invalidRecords.push({ path: filePath, reason: parsed.reason });
-                    continue;
-                }
-                const { record } = parsed;
-                if (record.kind !== 'retrospective' || record.author !== userId)
-                    continue;
-                if (seen.has(record.usageIdentity))
-                    continue;
-                seen.add(record.usageIdentity);
-                report.filesScanned++;
-                if (record.synthesized)
-                    report.synthesizedFilesRead++;
-                const result = recordAttestationsFromRetrospective(workspaceRoot, userId, {
-                    content: parsed.content, source: record.usageIdentity, job: record.job, date: record.date,
-                    agent: options.agent, model: options.model, legacy: false,
-                    limits, now: options.now, storePath: options.storePath, integrityMode: 'flag',
-                });
-                if (result.sectionState !== 'absent')
-                    report.filesWithSection++;
-                report.itemsRead += result.itemsRead;
-                report.applied += result.applied;
-                report.alreadyRecorded += result.alreadyRecorded;
-                report.unmatched.push(...result.unmatched);
-                report.rejected.push(...result.rejected);
-            }
-        }
-    }
-    return report;
-}