fraim 2.0.338 → 2.0.340

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -25,6 +25,7 @@ exports.resolveOrgBrandWriteDir = resolveOrgBrandWriteDir;
 exports.countPreservedLearnings = countPreservedLearnings;
 exports.collectBrainLearningDots = collectBrainLearningDots;
 exports.readPreservedLearnings = readPreservedLearnings;
+exports.normalizeLearningDomain = normalizeLearningDomain;
 exports.applyLearningEntryChange = applyLearningEntryChange;
 exports.isTruthyFlag = isTruthyFlag;
 const fs_1 = require("fs");
@@ -496,6 +497,15 @@ function scanMistakePatternFile(filePath, threshold, fileType = 'mistake-pattern
  * behaviour instead of merely equivalent.
  */
 function resolveUsageClock(workspaceRoot) {
+    return resolveUsageViews(workspaceRoot).clock;
+}
+/**
+ * Issue #1755: one store read, two views of it: the clock the scorer needs and
+ * the counters a surface renders. They are resolved together because reading the
+ * store twice for the same pass would let the two disagree, and because the
+ * identity resolution that finds a record is the projection's, not each caller's.
+ */
+function resolveUsageViews(workspaceRoot) {
     try {
         // Required lazily: the store imports the retention config, which imports the
         // workspace path helpers, and a cycle through this module would be fragile.
@@ -503,14 +513,31 @@ function resolveUsageClock(workspaceRoot) {
         const projection = require('./learning-usage-projection');
         const loaded = store.readUsageStore();
         if (Object.keys(loaded.entries).length === 0)
-            return undefined;
+            return {};
         const lookup = projection.buildUsageLookup(loaded);
-        return (id, fileType, title) => projection.lookupUsage(lookup, id, fileType, title)?.lastFired ?? null;
+        return {
+            clock: (id, fileType, title) => projection.lookupUsage(lookup, id, fileType, title)?.lastFired ?? null,
+            stats: (id, fileType, title) => {
+                const found = projection.lookupUsage(lookup, id, fileType, title);
+                if (!found)
+                    return null;
+                return {
+                    offered: found.offered,
+                    offeredAboveThreshold: found.offeredAboveThreshold,
+                    applied: found.byOutcome.applied || 0,
+                    prevented: found.byOutcome.prevented || 0,
+                    ignored: found.byOutcome.ignored || 0,
+                    notApplicable: found.byOutcome['not-applicable'] || 0,
+                    lastOfferedAt: found.lastOffered,
+                    lastFiredAt: found.lastFired,
+                };
+            },
+        };
     }
     catch {
         // Usage data is derived and optional. A failure here must never change what
         // the agent is given.
-        return undefined;
+        return {};
     }
 }
 function readFrontmatter(content) {
@@ -890,8 +917,9 @@ function enumerateFileEntries(file, threshold, usageClock, now) {
         out.push({
             // The store owns key construction. Building the composite key by hand here
             // would be a second definition of what an entry's identity is, and the two
-            // would drift the first time normalization changed.
-            key: current.id ?? (0, learning_usage_store_1.titleUsageKey)(file.fileType, current.title),
+            // would drift the first time normalization changed. Issue #1752 A1 made
+            // that one function rather than four copies of the same expression.
+            key: (0, learning_usage_store_1.resolveEntryIdentity)({ id: current.id, fileType: file.fileType, title: current.title }).key,
             family: 'learning',
             id: current.id,
             title: current.title,
@@ -939,9 +967,27 @@ function enumerateFileEntries(file, threshold, usageClock, now) {
  * listed. `aboveThreshold` is what separates active guidance from the dormant
  * rollup. Nothing here depends on the agent reading anything.
  *
- * Deduplicated by key with the later tier winning, matching how
- * `mergeLearningEntriesAcrossTiers` resolves a title collision across levels, so
- * one lesson is one offer even when two levels hold it.
+ * ## Issue #1752 A2 — one lesson, one offer, stamped or not
+ *
+ * This deduped by usage key, which sounds like the same thing as the context
+ * reader's rule and is not. `resolveOrgLearningFileTiers` deliberately returns
+ * both the org pack copy and the repo-local copy of an org family, because #1002
+ * R4 requires that a promoted entry not hide the rest of its family. The context
+ * reader then merges those tiers with `mergeLearningEntriesAcrossTiers`, keyed on
+ * the normalized title, so the agent sees one lesson. Keying the offer record on
+ * `id ?? titleUsageKey(...)` instead meant that a lesson carrying an `**Id**` line
+ * in one tier and not the other produced two keys, and both were recorded.
+ *
+ * That is defect 4 in #1752, and it is why `standing --changes-only` could
+ * recommend promoting and demoting the same lesson in one response: the
+ * title-keyed twin collected the offers while the id-keyed one collected the
+ * firings (the firing path never split, because `buildEntryIndex` dedups by
+ * identity first-wins). Measured live: five titles emitting two keys each in a
+ * single derived offer batch.
+ *
+ * So group by the same normalized title the context reader groups by, resolve one
+ * identity per group preferring whichever tier carries an id, and let the later
+ * tier win on content exactly as before.
  */
 function collectOfferedLearningEntries(workspaceRoot, userId, forJob, domain) {
     const roots = getLearningRoots(workspaceRoot);
@@ -950,13 +996,35 @@ function collectOfferedLearningEntries(workspaceRoot, userId, forJob, domain) {
     const usageClock = resolveUsageClock(workspaceRoot);
     const now = new Date();
     const resolved = resolveContextLearningFiles(workspaceRoot, resolvedUserId, roots, forJob, domain);
-    const byKey = new Map();
+    // Grouped by family plus normalized title, which is what `titleUsageKey`
+    // already computes. Two families holding the same title are two lessons, and
+    // that is the existing rule rather than a new one.
+    const byLesson = new Map();
     for (const file of [...resolved.l2, ...resolved.l1]) {
         for (const entry of enumerateFileEntries(file, threshold, usageClock, now)) {
-            byKey.set(entry.key, entry);
+            const lessonKey = (0, learning_usage_store_1.titleUsageKey)(entry.fileType, entry.title);
+            const group = byLesson.get(lessonKey);
+            if (group)
+                group.push(entry);
+            else
+                byLesson.set(lessonKey, [entry]);
         }
     }
-    return [...byKey.values()];
+    const out = [];
+    for (const group of byLesson.values()) {
+        // Later tier wins for content, unchanged precedence.
+        const winner = group[group.length - 1];
+        // The id comes from whichever tier carries one, because `stamp-ids` has not
+        // reached the org and manager pack homes for every corpus yet. Latest wins
+        // when more than one tier is stamped.
+        const id = group.reduce((found, entry) => entry.id ?? found, null);
+        out.push({
+            ...winner,
+            id,
+            key: (0, learning_usage_store_1.resolveEntryIdentity)({ id, fileType: winner.fileType, title: winner.title }).key,
+        });
+    }
+    return out;
 }
 /**
  * Issue #1103 R3: the auto-loaded Team Context rule files.
@@ -1175,7 +1243,7 @@ function isTeamContextKey(value) {
  *   user-level `~/.fraim/…` path (where org onboarding writes).
  * - Project scope (projectContext/projectBrief/projectRules/projectQa): repo-local only.
  */
-function resolveTeamContextFile(workspaceRoot, key) {
+function resolveTeamContextFile(workspaceRoot, key, options = {}) {
     const { relativePath, scope } = TEAM_CONTEXT_FILE_MAP[key];
     const repoPath = (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(workspaceRoot), 'personalized-employee', relativePath);
     const repoDisplay = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`personalized-employee/${relativePath}`);
@@ -1204,7 +1272,7 @@ function resolveTeamContextFile(workspaceRoot, key) {
     // destination (R5.1), so writePath stays empty and the caller must route
     // edits through the org backend's propose-and-approve flow.
     if (key === 'org' || key === 'orgRules') {
-        const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, relativePath);
+        const cachePath = (0, path_1.join)((0, pack_home_1.resolvePackHome)('org', options).contentRoot, relativePath);
         if ((0, fs_1.existsSync)(cachePath)) {
             const fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)();
             const orgDisplayPath = cachePath.startsWith(fraimDir)
@@ -1221,7 +1289,7 @@ function resolveTeamContextFile(workspaceRoot, key) {
         }
     }
     if (key === 'manager' || key === 'managerRules') {
-        const managerHome = (0, pack_home_1.resolvePackHome)('manager');
+        const managerHome = (0, pack_home_1.resolvePackHome)('manager', options);
         const managerCachePath = (0, path_1.join)(managerHome.contentRoot, relativePath);
         if ((0, fs_1.existsSync)(managerCachePath)) {
             const fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)();
@@ -1656,7 +1724,7 @@ function listDomainLearningFiles(dir, prefix, fileType) {
 // threshold: entries with score >= threshold (or in a non-gated category) are
 //   marked injected:true. Callers that don't need scoring pass Infinity so
 //   all entries are injected.
-function parseLearningEntries(filePath, displayPath, category, level, domain = 'global', tier, threshold = exports.DEFAULT_THRESHOLD, usageClock) {
+function parseLearningEntries(filePath, displayPath, category, level, domain = 'global', tier, threshold = exports.DEFAULT_THRESHOLD, usageClock, usageStats) {
     if (!(0, fs_1.existsSync)(filePath))
         return [];
     let content;
@@ -1678,6 +1746,10 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
     const flush = () => {
         if (current) {
             current.body = bodyLines.join('\n').replace(/\n{3,}/g, '\n\n').trim();
+            // Issue #1755: resolve usage once per entry, before scoring, so the
+            // counters a surface renders and the clock the score uses come from
+            // the same record rather than two independent lookups.
+            current.usage = usageStats ? usageStats(current.id, fileType, current.title) : null;
             if (isScoreGated) {
                 if (curLastSeen !== null) {
                     const lastFired = usageClock ? usageClock(current.id, fileType, current.title) : null;
@@ -1712,7 +1784,7 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
                 title: header[2].trim(),
                 id: null,
                 body: '', source: displayPath, category, level, domain,
-                score: null, injected: true,
+                score: null, injected: true, usage: null,
             };
             if (tier !== undefined)
                 entry.tier = tier;
@@ -1758,13 +1830,14 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
     const threshold = getScoreThreshold(workspaceRoot);
     // Issue #1103 R8: the Hub's injected flag must agree with the loader's, so both
     // read the same clock. One store read serves the whole call.
-    const usageClock = resolveUsageClock(workspaceRoot);
+    // Issue #1755: the same read also yields the counters the Hub renders.
+    const { clock: usageClock, stats: usageStats } = resolveUsageViews(workspaceRoot);
     const out = [];
     // Helper: parse + merge a list of tier paths for one file family.
     // ResolvedLearningTier uses 'manager' to mean machine-level personal; map it to 'machine'.
     const tierLevel = (t) => t.level === 'manager' ? 'machine' : t.level;
     const parseTiers = (tiers, cat, tierVal, domainVal) => mergeLearningEntriesAcrossTiers(tiers.map((t) => ({
-        entries: parseLearningEntries(t.path, t.displayPath, cat, tierLevel(t), domainVal ?? 'global', tierVal, threshold, usageClock),
+        entries: parseLearningEntries(t.path, t.displayPath, cat, tierLevel(t), domainVal ?? 'global', tierVal, threshold, usageClock, usageStats),
     })));
     if (scope === 'org') {
         for (const cat of ['avoid', 'preference', 'repeat', 'coaching']) {
@@ -1785,7 +1858,7 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
                 seenDomainFile.add(fileName);
                 const domainTiers = resolveOrgLearningFileTiers(roots.repoLearningsBase, fileName);
                 if (domainTiers.length === 0) {
-                    out.push(...parseLearningEntries((0, path_1.join)(base, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'org', domain, undefined, threshold));
+                    out.push(...parseLearningEntries((0, path_1.join)(base, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'org', domain, undefined, threshold, usageClock, usageStats));
                 }
                 else {
                     out.push(...parseTiers(domainTiers, cat, undefined, domain));
@@ -1802,13 +1875,13 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
         for (const cat of cats) {
             const fileType = exports.CATEGORY_TO_FILETYPE[cat];
             const f = `${resolvedUserId}-${fileType}.md`;
-            out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, f), `${REPO_LEARNINGS_REL}/${f}`, cat, 'project', 'global', 'hot', threshold));
+            out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, f), `${REPO_LEARNINGS_REL}/${f}`, cat, 'project', 'global', 'hot', threshold, usageClock, usageStats));
             const coldF = `${resolvedUserId}-${fileType}${COLD_FILE_SUFFIX}.md`;
             if ((0, fs_1.existsSync)((0, path_1.join)(roots.repoLearningsBase, coldF))) {
-                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, coldF), `${REPO_LEARNINGS_REL}/${coldF}`, cat, 'project', 'global', 'cold', threshold));
+                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, coldF), `${REPO_LEARNINGS_REL}/${coldF}`, cat, 'project', 'global', 'cold', threshold, usageClock, usageStats));
             }
             for (const { fileName, domain } of listDomainLearningFiles(roots.repoLearningsBase, resolvedUserId, fileType)) {
-                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'project', domain, 'hot', threshold));
+                out.push(...parseLearningEntries((0, path_1.join)(roots.repoLearningsBase, fileName), `${REPO_LEARNINGS_REL}/${fileName}`, cat, 'project', domain, 'hot', threshold, usageClock, usageStats));
             }
         }
         return out;
@@ -1839,6 +1912,25 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
     }
     return out;
 }
+/** True for a domain value that means "the undecorated global file". */
+function isGlobalDomain(domain) {
+    return !domain || domain === 'global';
+}
+/** Normalize a caller-supplied domain to one of the known domains, or 'global'. */
+function normalizeLearningDomain(domain) {
+    if (isGlobalDomain(domain))
+        return 'global';
+    const found = learning_domains_1.LEARNING_DOMAINS.find((d) => d === domain);
+    return found ?? 'global';
+}
+function learningFileName(userId, fileType, domain) {
+    // Issue #1755 / #754: normalize here rather than trusting the caller. The HTTP
+    // layer already allowlists the domain, but this function builds a path and a
+    // direct caller passing `../../escape` would otherwise write outside the
+    // learnings root. Anything not in the known set resolves to the global file.
+    const safe = normalizeLearningDomain(domain);
+    return safe === 'global' ? `${userId}-${fileType}.md` : `${userId}-${safe}-${fileType}.md`;
+}
 function resolveLearningFilePath(workspaceRoot, userId, ref) {
     const roots = getLearningRoots(workspaceRoot);
     const fileType = exports.CATEGORY_TO_FILETYPE[ref.category];
@@ -1846,12 +1938,12 @@ function resolveLearningFilePath(workspaceRoot, userId, ref) {
         // Write org entries to the org pack home — same location share-with-others uses.
         // The Hub read path already merges pack home + repo-local, so edits land where
         // the agent reads them without needing a repo commit.
-        return (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings', `org-${fileType}.md`);
+        return (0, path_1.join)((0, pack_home_1.resolvePackHome)('org').contentRoot, 'learnings', learningFileName('org', fileType, ref.domain));
     }
     const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
     // Issue #1070: for the 'machine' level use the configured manager home.
     const base = ref.level === 'project' ? roots.repoLearningsBase : roots.managerHomeBase;
-    return (0, path_1.join)(base, `${resolvedUserId}-${fileType}.md`);
+    return (0, path_1.join)(base, learningFileName(resolvedUserId, fileType, ref.domain));
 }
 function titleCaseFromFileType(fileType) {
     return fileType.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
@@ -1875,9 +1967,10 @@ function applyLearningEntryChange(workspaceRoot, userId, ref, action, payload) {
         const body = String(payload.body || '').trim();
         const block = [`#### [${sev}] ${title}`, '', body, '', '---'].join(nl);
         const fileType = exports.CATEGORY_TO_FILETYPE[ref.category];
+        const addDomain = normalizeLearningDomain(ref.domain);
         const preamble = existing.trim()
             ? existing.replace(/\s*$/, '')
-            : `# ${ref.scope === 'org' ? 'Org ' : ''}${titleCaseFromFileType(fileType)}`;
+            : `# ${ref.scope === 'org' ? 'Org ' : ''}${titleCaseFromFileType(fileType)}${addDomain === 'global' ? '' : ` (${addDomain})`}`;
         write(preamble + nl + nl + block);
         return { ok: true, path: filePath };
     }
@@ -1894,8 +1987,12 @@ function applyLearningEntryChange(workspaceRoot, userId, ref, action, payload) {
         write(next.join(nl).replace(/\n{3,}/g, '\n\n'));
         return { ok: true, path: filePath };
     }
-    // edit: keep the entry's metadata lines (Score/Last seen/Recurrences/...) intact,
+    // edit: keep the entry's metadata lines (Id/Score/Last seen/Recurrences/...) intact,
     // replace only the heading (priority + title) and the prose body.
+    //
+    // Issue #1755: `Id` is in this list. It used not to be, so every Hub edit dropped
+    // the entry's stable identifier and the usage record keyed to it (#1752) was
+    // orphaned: silently, and permanently once the title also changed.
     const headerMatch = lines[start].match(headingRe);
     const sev = (payload.severity || headerMatch[1]);
     const title = (payload.title !== undefined ? payload.title : headerMatch[2]).trim();
@@ -1904,11 +2001,32 @@ function applyLearningEntryChange(workspaceRoot, userId, ref, action, payload) {
         const t = l.trim();
         if (t === '---')
             continue;
-        if (/^\*\*(Score|Last seen|Recurrences|Technical trace|Users|First synthesized)\*\*:/i.test(t) || /^(First|Last) synthesized:/i.test(t))
+        if (/^\*\*(Id|Score|Last seen|Recurrences|Technical trace|Users|First synthesized)\*\*:/i.test(t) || /^(First|Last) synthesized:/i.test(t))
             meta.push(l);
     }
     const body = String(payload.body !== undefined ? payload.body : '').trim();
     const rebuilt = [`#### [${sev}] ${title}`, '', ...meta, ...(meta.length ? [''] : []), body, '', '---'];
+    // Issue #1755 R2/R4: a domain change is a move between files, because the domain
+    // IS the filename. Cut the rebuilt block from the source file and append it to the
+    // destination, so the entry keeps its id, score and history rather than being
+    // re-created as a new entry with no past.
+    const targetDomain = payload.targetDomain === undefined ? undefined : normalizeLearningDomain(payload.targetDomain);
+    if (targetDomain !== undefined && targetDomain !== normalizeLearningDomain(ref.domain)) {
+        const destPath = resolveLearningFilePath(workspaceRoot, userId, { ...ref, domain: targetDomain });
+        const destExisting = (0, fs_1.existsSync)(destPath) ? (0, fs_1.readFileSync)(destPath, 'utf8') : '';
+        const destNl = destExisting.includes('\r\n') ? '\r\n' : nl;
+        const fileTypeForHeader = exports.CATEGORY_TO_FILETYPE[ref.category];
+        const destPreamble = destExisting.trim()
+            ? destExisting.replace(/\s*$/, '')
+            : `# ${ref.scope === 'org' ? 'Org ' : ''}${titleCaseFromFileType(fileTypeForHeader)}${targetDomain === 'global' ? '' : ` (${targetDomain})`}`;
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(destPath), { recursive: true });
+        (0, fs_1.writeFileSync)(destPath, (destPreamble + destNl + destNl + rebuilt.join(destNl)).replace(/\s*$/, '') + destNl, 'utf8');
+        // Remove from the source only after the destination write succeeded, so a
+        // failure mid-move duplicates rather than loses the entry.
+        const without = [...lines.slice(0, start), ...lines.slice(end)];
+        write(without.join(nl).replace(/\n{3,}/g, '\n\n'));
+        return { ok: true, path: destPath };
+    }
     const next = [...lines.slice(0, start), ...rebuilt, ...lines.slice(end)];
     write(next.join(nl).replace(/\n{3,}/g, '\n\n'));
     return { ok: true, path: filePath };

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

@@ -81,6 +81,20 @@ function classifyRecurrence(store, options) {
         : null;
     const historyComplete = record.offered.log.length === record.offered.total
         || (oldestRetained !== null && new Date(oldestRetained).getTime() <= windowStartMs);
+    // #1752 D2, the issue's suggested fix 4. `report` selects an entry into
+    // `ignoredWhileInContext` on `byOutcome.ignored > 0`, which asserts the entry
+    // was in context; `classify` was answering `not-offered` for the same entry,
+    // which asserts the opposite, with no hedge. The #1740 postmortem states in
+    // first-hand prose that L-abc958f241 "was above threshold and in context".
+    // When the two halves of one record disagree, neither is evidence.
+    const ignoredInWindow = record.fired.log.filter((firing) => firing.outcome === 'ignored' && daysBetween(firing.date, options.date) <= options.windowDays);
+    // #1752 D1. Absence of an offer for this job is only evidence when the record
+    // can resolve this job at all. Measured: 2067 of 2354 retained offer records
+    // carry `session` or `__freeform__`, because `fraim_connect` writes one offer
+    // per entry per session and a plain newest-N bound evicted the job-labelled
+    // ones within about a day. Asking about a job the store has never retained an
+    // offer for is a gap in the record, not a delivery failure.
+    const jobCoverage = Object.values(store.entries).some((entry) => entry.offered.log.some((offer) => offer.job === options.job && daysBetween(offer.date, options.date) <= options.windowDays));
     if (matchingOffers.length > 0) {
         return {
             ...base,
@@ -91,6 +105,26 @@ function classifyRecurrence(store, options) {
             targetOfFix: 'entry',
         };
     }
+    if (ignoredInWindow.length > 0) {
+        return {
+            ...base,
+            classification: 'undetermined',
+            diagnosis: `The two halves of this entry's record disagree: it carries ${ignoredInWindow.length} attested \`ignored\` outcome${ignoredInWindow.length === 1 ? '' : 's'} inside the window, which says it was in context and the work went against it, while the offer log holds no matching offer for ${options.job}, which says it was never delivered. Both cannot be true.`,
+            recommendation: 'Do not act on either reading. An `ignored` attestation and an empty offer log are contradictory evidence about the same event, so the record cannot say whether the entry or the delivery is at fault. Run `learning-usage verify` to see whether this entry carries an integrity flag, and treat the recurrence on its own terms until the record agrees with itself.',
+            recurrenceBump: true,
+            targetOfFix: 'none',
+        };
+    }
+    if (!jobCoverage) {
+        return {
+            ...base,
+            classification: 'undetermined',
+            diagnosis: `No offer anywhere in the record carries the job label ${options.job} inside this window, so the per-job offer record has no resolution for that job and cannot say whether this entry was in context for it.`,
+            recommendation: 'The offer record cannot answer this question for this job, so absence of a match is not evidence of absence. Do not conclude a delivery problem. Re-ask once the job has run with offer recording in place, or widen the window to one the record covers.',
+            recurrenceBump: true,
+            targetOfFix: 'none',
+        };
+    }
     if (!historyComplete) {
         return {
             ...base,
@@ -179,6 +213,26 @@ function firingsUnderModel(record, model) {
         return 0;
     return record.fired.byModel[model] ?? 0;
 }
+/**
+ * #1752 C4 - is this entry's per-model attribution unknown, as opposed to zero?
+ *
+ * All 781 retained firing records in the live store carry `agent: null,
+ * model: null`, because `attest-learning-firings.md` invoked `record-firings`
+ * with no `--agent` or `--model`. `firedUnderCurrentModel` was therefore
+ * structurally 0 for every entry, which is why `candidates` proposed 31
+ * retirements: every entry clearing the offer threshold became one, however hard
+ * it was working. Fixing the `currentModel` resolution alone would not have
+ * changed a single one of them.
+ *
+ * The predicate is deliberately narrower than "fired at all". An entry whose only
+ * outcomes are `ignored` or `not-applicable` has an empty `byModel` because those
+ * outcomes correctly do not bucket by model; that is information, not a gap. Only
+ * a clock-advancing firing that produced no bucket means the model went
+ * unrecorded.
+ */
+function modelAttributionUnknown(record) {
+    return firedCount(record) > 0 && Object.keys(record.fired.byModel).length === 0;
+}
 function earlierModelFirings(record, currentModel) {
     return Object.entries(record.fired.byModel)
         .filter(([model]) => model !== currentModel)
@@ -189,9 +243,22 @@ 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 currentModel = (0, learning_usage_projection_1.resolveCurrentModel)(options.currentModel);
     const threshold = options.limits.retirementOfferThreshold;
     const probe = options.structuralProbe ?? resolveStructuralProbe(options.structuralSignalPath);
+    // #1752 C1: retirement candidacy is computed per model, so with no model there
+    // is no question to answer. An empty list with the reason stated is the honest
+    // answer; computing against a null bucket is how defect 3 produced 31
+    // proposals nobody could act on.
+    if (!currentModel) {
+        return {
+            currentModel: null,
+            offerThreshold: threshold,
+            candidates: [],
+            notCandidates: [],
+            reason: 'The current model did not resolve, so no per-model conclusion can be drawn. Pass --model <model>, or set FRAIM_ACTIVE_MODEL. The current model is never inferred from the usage record, because the record is shared by concurrent sessions from more than one agent and would report whichever wrote last.',
+        };
+    }
     const candidates = [];
     const notCandidates = [];
     for (const record of Object.values(store.entries)) {
@@ -204,6 +271,14 @@ function findRetirementCandidates(store, options) {
             notCandidates.push({ key: record.key, title, reason: `It fired ${fired} time${fired === 1 ? '' : 's'} under the current model, so it is still earning its place.` });
             continue;
         }
+        if (modelAttributionUnknown(record)) {
+            notCandidates.push({
+                key: record.key,
+                title,
+                reason: `Per-model attribution is unknown for this entry: it fired ${firedCount(record)} time${firedCount(record) === 1 ? '' : 's'} and no firing carries a model, so how hard it is working under ${currentModel} cannot be measured. Held back rather than counted as zero.`,
+            });
+            continue;
+        }
         if (offered < threshold) {
             notCandidates.push({
                 key: record.key,
@@ -297,6 +372,7 @@ function toReportEntry(record) {
         title: latestTitle(record),
         offered: record.offered.total,
         fired: firedCount(record),
+        ignored: record.fired.byOutcome.ignored,
         lastFired: record.fired.lastFiredAt,
         firedUnder: Object.keys(record.fired.byModel),
         recentLog: record.fired.log,
@@ -320,7 +396,8 @@ function buildUsageReport(store, options) {
     return {
         generatedAt: now.toISOString(),
         windowDays: options.windowDays,
-        currentModel: (0, learning_usage_projection_1.resolveCurrentModel)(store),
+        currentModel: (0, learning_usage_projection_1.resolveCurrentModel)(options.currentModel),
+        integrityFlagged: learningRecords.filter((r) => Boolean(r.integrity)).length,
         totals: {
             entriesOffered: offered.length,
             entriesWithFirings: fired.length,

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

@@ -48,7 +48,9 @@ function buildEntryIndex(workspaceRoot, userId) {
         for (const entry of entries) {
             const fileType = fileTypeOf(entry);
             const attestable = {
-                key: entry.id ?? (0, learning_usage_store_1.titleUsageKey)(fileType, entry.title),
+                // #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,
@@ -142,7 +144,9 @@ function recordAttestationsFromRetrospective(workspaceRoot, userId, options) {
     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 });
+        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;
     }
@@ -208,6 +212,9 @@ function runBackfill(workspaceRoot, userId, options) {
             limits,
             now: options.now,
             storePath: options.storePath,
+            // A backfill reconciles hundreds of retrospectives at once, so a single
+            // stranded-offer entry must not refuse the whole run.
+            integrityMode: 'flag',
         });
         if (result.sectionState !== 'absent')
             report.filesWithSection += 1;