fraim 2.0.270 → 2.0.271

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

@@ -0,0 +1,247 @@
+"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-analysis.js

@@ -0,0 +1,347 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyRecurrence = classifyRecurrence;
+exports.resolveStructuralProbe = resolveStructuralProbe;
+exports.findRetirementCandidates = findRetirementCandidates;
+exports.deriveStanding = deriveStanding;
+exports.assessStanding = assessStanding;
+exports.buildUsageReport = buildUsageReport;
+/**
+ * Issue #1103 — what the usage record lets you conclude.
+ *
+ * Three questions, each with an answer the record can prove:
+ *
+ *   R7  Why did this recur? `ignored` means the entry was in context and did not
+ *       change the outcome, so the fix is the entry. `not-offered` means it never
+ *       reached the agent, so the fix is the delivery. Today a recurrence cannot
+ *       tell those apart, which is why the same lesson gets rewritten when the
+ *       real bug is in the loader.
+ *   R9  Which entries have stopped earning their place under the current model?
+ *   R20 And is there a second, independent signal agreeing before anything is
+ *       recommended for retirement?
+ *
+ * Everything here is read-only. R10 and R19: usage data produces recommendations,
+ * and every change to an entry still passes the existing review gate.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const learning_usage_store_1 = require("./learning-usage-store");
+const learning_usage_projection_1 = require("./learning-usage-projection");
+function daysBetween(from, to) {
+    const a = new Date(from).getTime();
+    const b = new Date(to).getTime();
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return Number.POSITIVE_INFINITY;
+    return Math.abs(b - a) / 86_400_000;
+}
+function firedCount(record) {
+    return learning_usage_store_1.CLOCK_ADVANCING_OUTCOMES.reduce((sum, outcome) => sum + record.fired.byOutcome[outcome], 0);
+}
+function classifyRecurrence(store, options) {
+    const record = store.entries[options.key];
+    const base = {
+        key: options.key,
+        title: record?.titles[record.titles.length - 1] ?? null,
+        evidence: {
+            recurrenceDate: options.date,
+            recurrenceJob: options.job,
+            windowDays: options.windowDays,
+            matchingOffers: [],
+            offeredTotal: record?.offered.total ?? 0,
+            firedTotal: record ? firedCount(record) : 0,
+        },
+    };
+    if (!record) {
+        return {
+            ...base,
+            classification: 'undetermined',
+            diagnosis: 'There is no usage record for this entry, so whether it was in context for that job cannot be determined.',
+            recommendation: 'No usage record exists for this entry yet. Treat this recurrence the way you would have before usage attribution, and re-check after the entry has been offered a few times.',
+            recurrenceBump: true,
+            targetOfFix: 'none',
+        };
+    }
+    // "In context for that job" means an offer for the same job inside the window.
+    // A different job's offer is not evidence: domain filtering is exactly the
+    // mechanism that can deliver an entry to one job and withhold it from another.
+    const matchingOffers = record.offered.log.filter((offer) => offer.job === options.job
+        && offer.aboveThreshold
+        && daysBetween(offer.date, options.date) <= options.windowDays);
+    base.evidence.matchingOffers = matchingOffers;
+    // Absence of a matching offer record is only evidence of absence when the offer
+    // log actually reaches back over the window. The log is bounded (R16a), so an
+    // entry offered many times can have had every relevant record trimmed away.
+    // Reporting `not-offered` there would tell the manager to fix the loader for an
+    // entry that was in fact delivered, which is the wrong-fix failure R7 exists to
+    // prevent. The history is complete when nothing has been trimmed, or when the
+    // oldest retained record predates the window.
+    const windowStartMs = new Date(options.date).getTime() - options.windowDays * 86_400_000;
+    const oldestRetained = record.offered.log.length
+        ? record.offered.log.reduce((min, o) => (o.date < min ? o.date : min), record.offered.log[0].date)
+        : null;
+    const historyComplete = record.offered.log.length === record.offered.total
+        || (oldestRetained !== null && new Date(oldestRetained).getTime() <= windowStartMs);
+    if (matchingOffers.length > 0) {
+        return {
+            ...base,
+            classification: 'ignored',
+            diagnosis: `This entry was in context for ${options.job} when the mistake recurred, and being in context did not change what happened.`,
+            recommendation: 'The entry reached the agent and did not change the outcome, so the entry itself is what needs work. Fix its wording so the required action is unambiguous, or fix its placement so it is read at the moment the decision is made. Do not record another recurrence as if the lesson were simply not learned yet.',
+            recurrenceBump: true,
+            targetOfFix: 'entry',
+        };
+    }
+    if (!historyComplete) {
+        return {
+            ...base,
+            classification: 'undetermined',
+            diagnosis: `Whether this entry was in context for ${options.job} cannot be determined: it has been offered ${record.offered.total} times, but the retained offer log no longer reaches back over the window being asked about.`,
+            recommendation: 'The offer history for this window has been pruned, so absence of a record is not evidence that the entry was not delivered. Do not conclude a delivery problem from this. Either widen the retained offer log for this corpus, or ask again about a more recent recurrence.',
+            recurrenceBump: true,
+            targetOfFix: 'none',
+        };
+    }
+    return {
+        ...base,
+        classification: 'not-offered',
+        diagnosis: `This entry was never in context for ${options.job}, so it had no opportunity to change what happened.`,
+        recommendation: 'The entry never reached the agent, so the delivery is what is wrong and the entry text is fine. Check the entry\'s domain and its threshold in the loader: widen the domain if the lesson applies beyond the jobs it is currently scoped to. Do not raise the recurrence count, because the count measures how often the lesson failed to stick and this is not an instance of that.',
+        recurrenceBump: false,
+        targetOfFix: 'delivery',
+    };
+}
+const UNDETERMINED = {
+    signal: 'undetermined',
+    detail: 'The structural signal could not be determined: the corpus hygiene detector is not available in this workspace, so whether the thing this entry guards still exists is unknown.',
+};
+/**
+ * R20's structural half comes from issue #1100's inert and orphan detection, which
+ * answers a different question from usage: is the thing this entry guards still
+ * there? The two specs meet at exactly this point, and #1103 reads that detector
+ * rather than re-deriving it.
+ *
+ * When the detector is absent the probe says so plainly. That is not a fallback
+ * for convenience: R20's third acceptance criterion requires the undetermined case
+ * to be stated rather than presented as if both signals agreed.
+ */
+/**
+ * The only module this integration loads. Naming it exactly, rather than accepting
+ * any path, keeps `require` of a caller-supplied string from becoming a general
+ * arbitrary-module loader: a mistyped or hostile `--detector` value fails closed to
+ * the undetermined signal instead of executing.
+ */
+const STRUCTURAL_DETECTOR_FILENAME = 'instruction-hygiene.js';
+function resolveStructuralProbe(detectorPath) {
+    if (!detectorPath || !(0, fs_1.existsSync)(detectorPath)) {
+        return () => UNDETERMINED;
+    }
+    if ((0, path_1.basename)(detectorPath) !== STRUCTURAL_DETECTOR_FILENAME) {
+        return () => ({
+            signal: 'undetermined',
+            detail: `The structural signal could not be determined: the detector path must end in ${STRUCTURAL_DETECTOR_FILENAME}, and this one does not.`,
+        });
+    }
+    let detector;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        detector = require(detectorPath);
+    }
+    catch {
+        return () => UNDETERMINED;
+    }
+    if (!detector || typeof detector.analyzeInstructionHygiene !== 'function') {
+        return () => UNDETERMINED;
+    }
+    return (key, title) => {
+        try {
+            const report = detector.analyzeInstructionHygiene({ root: process.cwd() });
+            const findings = report?.findings ?? [];
+            const needle = (title ?? key).toLowerCase();
+            const inert = findings.find((f) => (f.type === 'inert' || f.type === 'orphan')
+                && `${f.file ?? ''} ${f.message ?? ''}`.toLowerCase().includes(needle));
+            if (inert) {
+                return { signal: 'guard-absent', detail: `The corpus hygiene detector reports this as ${inert.type}: ${inert.message ?? 'no consumer found'}.` };
+            }
+            return { signal: 'still-referenced', detail: 'The corpus hygiene detector finds the surface this entry guards is still referenced.' };
+        }
+        catch {
+            return UNDETERMINED;
+        }
+    };
+}
+function offersUnderModel(record, model) {
+    if (!model)
+        return 0;
+    return record.offered.byModel[model] ?? 0;
+}
+function firingsUnderModel(record, model) {
+    if (!model)
+        return 0;
+    return record.fired.byModel[model] ?? 0;
+}
+function earlierModelFirings(record, currentModel) {
+    return Object.entries(record.fired.byModel)
+        .filter(([model]) => model !== currentModel)
+        .map(([model, count]) => ({ model, count }))
+        .sort((a, b) => b.count - a.count);
+}
+function latestTitle(record) {
+    return record.titles[record.titles.length - 1] ?? record.key;
+}
+function findRetirementCandidates(store, options) {
+    const currentModel = options.currentModel ?? (0, learning_usage_projection_1.resolveCurrentModel)(store);
+    const threshold = options.limits.retirementOfferThreshold;
+    const probe = options.structuralProbe ?? resolveStructuralProbe(options.structuralSignalPath);
+    const candidates = [];
+    const notCandidates = [];
+    for (const record of Object.values(store.entries)) {
+        if (record.family !== 'learning')
+            continue;
+        const title = latestTitle(record);
+        const offered = offersUnderModel(record, currentModel);
+        const fired = firingsUnderModel(record, currentModel);
+        if (fired > 0) {
+            notCandidates.push({ key: record.key, title, reason: `It fired ${fired} time${fired === 1 ? '' : 's'} under the current model, so it is still earning its place.` });
+            continue;
+        }
+        if (offered < threshold) {
+            notCandidates.push({
+                key: record.key,
+                title,
+                reason: `Only ${offered} offer${offered === 1 ? '' : 's'} under the current model, which is below the threshold of ${threshold}. That is more likely to mean the work that triggers it has not come up than that it is no longer needed.`,
+            });
+            continue;
+        }
+        const structural = probe(record.key, title);
+        // R20: two independent signals before recommending removal. Usage alone says
+        // "unused"; only usage plus an absent guard says "obsolete".
+        const recommendation = structural.signal === 'guard-absent' ? 'retire' : 'keep-and-reword';
+        candidates.push({
+            key: record.key,
+            title,
+            offeredUnderCurrentModel: offered,
+            firedUnderCurrentModel: fired,
+            firedUnderEarlierModels: earlierModelFirings(record, currentModel),
+            currentModel,
+            structural: structural.signal,
+            structuralDetail: structural.detail,
+            recommendation,
+        });
+    }
+    candidates.sort((a, b) => b.offeredUnderCurrentModel - a.offeredUnderCurrentModel);
+    return { currentModel, offerThreshold: threshold, candidates, notCandidates };
+}
+/**
+ * The window in which a firing still counts as recent for standing purposes.
+ * Longer than the Brain's 30-day "fired recently" glance signal, because standing
+ * is a slower-moving decision than a dot colour.
+ */
+const STANDING_RECENT_DAYS = 90;
+function daysSince(date, now) {
+    if (!date)
+        return Number.POSITIVE_INFINITY;
+    const parsed = new Date(date).getTime();
+    if (Number.isNaN(parsed))
+        return Number.POSITIVE_INFINITY;
+    return (now.getTime() - parsed) / 86_400_000;
+}
+function deriveStanding(record, options) {
+    const now = options.now ?? new Date();
+    const fired = firedCount(record);
+    const offered = record.offered.aboveThreshold;
+    const title = latestTitle(record);
+    const threshold = options.limits.retirementOfferThreshold;
+    let standing;
+    let reason;
+    if (fired > 0 && daysSince(record.fired.lastFiredAt, now) <= STANDING_RECENT_DAYS) {
+        standing = 'promoted';
+        reason = `Fired ${fired} time${fired === 1 ? '' : 's'}, most recently ${record.fired.lastFiredAt}. It is changing outcomes, so it stays fully in context.`;
+    }
+    else if (offered >= threshold && fired === 0) {
+        standing = 'demoted';
+        reason = `Offered ${offered} times as active guidance and never changed an outcome. Demoted rather than removed: it stays readable and can earn its way back the first time it fires.`;
+    }
+    else if (fired > 0) {
+        standing = 'standard';
+        reason = `Fired ${fired} time${fired === 1 ? '' : 's'}, but not within the last ${STANDING_RECENT_DAYS} days. Held at standard while it is neither proving itself nor failing to.`;
+    }
+    else {
+        standing = 'standard';
+        reason = offered === 0
+            ? 'No usage record yet. An entry FRAIM has not measured is held at standard rather than judged.'
+            : `Offered ${offered} times, which is below the ${threshold} needed to conclude anything from silence.`;
+    }
+    const current = options.currentStanding ? options.currentStanding(record.key) : 'standard';
+    const recommendation = standing === current ? null : standing === 'promoted' ? 'promote' : standing === 'demoted' ? 'demote' : null;
+    return { key: record.key, title, standing, reason, offered, fired, recommendation };
+}
+/**
+ * Assess every entry with a usage record. Read-only: this recommends, and
+ * `sleep-on-learnings` applies under the existing approval gate (R10, R19).
+ */
+function assessStanding(store, options) {
+    const now = options.now ?? new Date();
+    const assessments = Object.values(store.entries)
+        .filter((r) => r.family === 'learning')
+        .map((r) => deriveStanding(r, { ...options, now }))
+        .sort((a, b) => b.fired - a.fired || b.offered - a.offered);
+    return {
+        generatedAt: now.toISOString(),
+        assessments,
+        changes: assessments.filter((a) => a.recommendation !== null),
+    };
+}
+function toReportEntry(record) {
+    return {
+        key: record.key,
+        title: latestTitle(record),
+        offered: record.offered.total,
+        fired: firedCount(record),
+        lastFired: record.fired.lastFiredAt,
+        firedUnder: Object.keys(record.fired.byModel),
+        recentLog: record.fired.log,
+    };
+}
+/**
+ * The answer to "which of my learnings are still earning their place?".
+ *
+ * Only entries with a usage record appear. An entry FRAIM has never measured is
+ * absent rather than listed with zeroes, because a fabricated zero reads as
+ * evidence of disuse when it is only evidence of no data.
+ */
+function buildUsageReport(store, options) {
+    const now = options.now ?? new Date();
+    const limit = options.limit ?? 10;
+    const learningRecords = Object.values(store.entries).filter((r) => r.family === 'learning');
+    const offered = learningRecords.filter((r) => r.offered.total > 0);
+    const fired = learningRecords.filter((r) => firedCount(r) > 0);
+    const neverFired = offered.filter((r) => firedCount(r) === 0);
+    const ignored = learningRecords.filter((r) => r.fired.byOutcome.ignored > 0);
+    return {
+        generatedAt: now.toISOString(),
+        windowDays: options.windowDays,
+        currentModel: (0, learning_usage_projection_1.resolveCurrentModel)(store),
+        totals: {
+            entriesOffered: offered.length,
+            entriesWithFirings: fired.length,
+            entriesNeverFired: neverFired.length,
+        },
+        workingHardest: fired
+            .sort((a, b) => {
+            const byCount = firedCount(b) - firedCount(a);
+            if (byCount !== 0)
+                return byCount;
+            return (b.fired.lastFiredAt ?? '').localeCompare(a.fired.lastFiredAt ?? '');
+        })
+            .slice(0, limit)
+            .map(toReportEntry),
+        neverFired: neverFired
+            .sort((a, b) => b.offered.total - a.offered.total)
+            .slice(0, limit)
+            .map(toReportEntry),
+        ignoredWhileInContext: ignored
+            .sort((a, b) => b.fired.byOutcome.ignored - a.fired.byOutcome.ignored)
+            .slice(0, limit)
+            .map(toReportEntry),
+    };
+}