fraim 2.0.338 → 2.0.340

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

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const learning_usage_store_1 = require("./learning-usage-store");
+const learning_usage_events_1 = require("./learning-usage-events");
+const learning_usage_projection_1 = require("./learning-usage-projection");
+const CANONICAL_FILE_NAME = 'learning-usage.json';
+/** `learning-usage.json` plus anything a sync client forked off it. */
+const STORE_COPY_PATTERN = /^learning-usage(-.+)?\.json$/;
+/**
+ * The size past which a cold fold stops fitting the 150 ms context-injection
+ * budget. Spike S4 measured 84 ms at 9.86 MB and 794 ms at 79 MB, so the budget
+ * runs out around here. Compaction is operator-triggered (`learning-usage
+ * prune`), so this is the number that tells the operator when to run it.
+ */
+exports.COMPACTION_ADVISORY_BYTES = 16 * 1024 * 1024;
+/**
+ * Deliberately looser than the store's own `isUsableRecord`.
+ *
+ * That one guards what a consumer will dereference, so it drops anything it
+ * cannot hand out safely. This one decides what `verify` will count, and a record
+ * it rejects is a finding that never gets reported, so it checks only the two
+ * counter objects and the title list.
+ */
+function usableRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return !!record.offered && typeof record.offered === 'object'
+        && !!record.fired && typeof record.fired === 'object'
+        && Array.isArray(record.titles);
+}
+function parseCopy(path) {
+    const summary = { path, readable: false, entries: 0, offers: 0, firings: 0 };
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || !parsed.entries || typeof parsed.entries !== 'object' || Array.isArray(parsed.entries)) {
+            summary.error = 'No readable entries object.';
+            return summary;
+        }
+        const entries = [];
+        for (const value of Object.values(parsed.entries)) {
+            if (usableRecord(value))
+                entries.push(value);
+        }
+        summary.readable = true;
+        summary.entries = entries.length;
+        summary.offers = entries.reduce((sum, r) => sum + (r.offered.total ?? 0), 0);
+        summary.firings = entries.reduce((sum, r) => sum + (r.fired.seenSources?.length ?? 0), 0);
+    }
+    catch (error) {
+        summary.error = error instanceof Error ? error.message : String(error);
+    }
+    return summary;
+}
+/** The store copies beside the canonical snapshot: history nothing reads. */
+function listUnmergedStoreCopies(snapshotPath) {
+    const dir = (0, path_1.dirname)(snapshotPath);
+    if (!(0, fs_1.existsSync)(dir))
+        return [];
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((name) => STORE_COPY_PATTERN.test(name) && name !== CANONICAL_FILE_NAME)
+        .sort()
+        .map((name) => parseCopy((0, path_1.join)(dir, name)));
+}
+/**
+ * Find lessons tracked under both a title-derived key and an id key.
+ *
+ * Matching is the title under the same family and nothing else. #1103 R5 forbids
+ * resolving a reference to the closest title, and reporting a wrong pair here
+ * would tell the manager two unrelated lessons are one.
+ */
+function findTwinPairs(entries) {
+    const idRecordsByTitleKey = new Map();
+    for (const record of Object.values(entries)) {
+        if (record.key.startsWith('T:') || !record.fileType)
+            continue;
+        for (const title of record.titles) {
+            idRecordsByTitleKey.set((0, learning_usage_store_1.titleUsageKey)(record.fileType, title), record.key);
+        }
+    }
+    const pairs = [];
+    const unmatched = [];
+    for (const record of Object.values(entries)) {
+        if (!record.key.startsWith('T:'))
+            continue;
+        const idKey = idRecordsByTitleKey.get(record.key);
+        if (idKey)
+            pairs.push({ titleKey: record.key, idKey, title: record.titles[record.titles.length - 1] ?? record.key });
+        else
+            unmatched.push(record.key);
+    }
+    return { pairs, unmatched };
+}
+/**
+ * The three per-record defect classes, collected in one pass.
+ *
+ * Split out of `buildVerifyReport` so that function reads as what it is: an
+ * assembly of independently-computed parts.
+ */
+function scanRecordsForIntegrity(records, offersEraStart) {
+    const invariantViolations = [];
+    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]) {
+            const byNormalized = new Map();
+            for (const raw of Object.keys(buckets)) {
+                const normalized = (0, learning_usage_store_1.normalizeModelName)(raw) ?? raw;
+                byNormalized.set(normalized, [...(byNormalized.get(normalized) ?? []), raw]);
+            }
+            for (const [normalized, raws] of byNormalized) {
+                if (raws.length > 1 || raws[0] !== normalized) {
+                    caseVariantModelBuckets.push({ key: record.key, title, buckets: raws, normalized });
+                }
+            }
+        }
+        // Only a clock-advancing firing 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;
+        if (clockAdvancing > 0 && Object.keys(record.fired.byModel).length === 0) {
+            unknownModelAttribution.push({ key: record.key, title, fired: clockAdvancing });
+        }
+    }
+    return { invariantViolations, caseVariantModelBuckets, unknownModelAttribution };
+}
+function buildVerifyReport(options) {
+    const now = options.now ?? new Date();
+    const eventDir = options.eventDir ?? (0, learning_usage_events_1.resolveEventDir)(options.snapshotPath);
+    const store = (0, learning_usage_store_1.readUsageStore)(options.snapshotPath, { limits: options.limits, now, eventDir, refreshSnapshot: 'never' });
+    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 twins = findTwinPairs(store.entries);
+    const storeCopies = listUnmergedStoreCopies(options.snapshotPath);
+    const checkpoints = snapshot.foldedThroughBytes ?? {};
+    const totalLogBytes = logs.reduce((sum, log) => sum + log.size, 0);
+    return {
+        snapshotPath: options.snapshotPath,
+        eventDir,
+        currentModel: (0, learning_usage_projection_1.resolveCurrentModel)(options.currentModel),
+        entries: records.length,
+        twinPairs: twins.pairs,
+        unmatchedTitleKeys: twins.unmatched,
+        invariantViolations,
+        caseVariantModelBuckets,
+        unknownModelAttribution,
+        storeCopies,
+        eventLogs: logs.map((log) => ({ machineId: log.machineId, path: log.path, bytes: log.size })),
+        // The one number that makes a stale read visible: a snapshot that stops
+        // advancing while the log grows is a failing snapshot write, which S3 showed
+        // will happen intermittently on a synced folder and is otherwise silent.
+        checkpointLag: Object.fromEntries(logs.map((log) => [log.machineId, Math.max(0, log.baseOffset + log.size - log.headerBytes - (checkpoints[log.machineId] ?? 0))])),
+        skippedLines: 0,
+        totalLogBytes,
+        compactionAdvisoryBytes: exports.COMPACTION_ADVISORY_BYTES,
+        compactionAdvised: totalLogBytes >= exports.COMPACTION_ADVISORY_BYTES,
+        rebuildAdvised: storeCopies.length > 0 || twins.pairs.length > 0,
+    };
+}

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

@@ -1679,12 +1679,17 @@ class FraimLocalMCPServer {
                 job,
                 date,
                 agent: collector?.getAgentName() ?? null,
-                model: collector?.getAgentModel() ?? 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}`);
+            this.log(`[req:${requestId}] Recorded ${result.recorded} usage offers for job ${job} (write mode: append)`);
         }
         catch (error) {
-            this.log(`[req:${requestId}] Usage offer recording skipped: ${error instanceof Error ? error.message : String(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)}`);
         }
     }
     /**
@@ -2423,6 +2428,35 @@ class FraimLocalMCPServer {
         if (request.method === 'tools/call' && typeof toolName === 'string') {
             // 🔍 SMART DISPATCHER: Intercept mentoring and job/workflow tools for local overrides
             if (toolName === 'seekMentoring') {
+                // #1766: report an unrenderable supplied handoff before any mentoring
+                // success response, including when phase-policy enforcement is disabled.
+                // Match the host's direct/evidence/findings precedence and JSON support.
+                const suppliedHandoffs = [args.reviewHandoff, args.evidence?.reviewHandoff, args.findings?.reviewHandoff]
+                    .filter((value) => value !== undefined && value !== null)
+                    .map((value) => {
+                    if (typeof value !== 'string')
+                        return value;
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch {
+                        return value;
+                    }
+                });
+                const suppliedHandoff = suppliedHandoffs.find((value) => value && typeof value === 'object' && !Array.isArray(value) && typeof value.reviewRequired === 'boolean') ?? suppliedHandoffs[0];
+                if (suppliedHandoffs.length > 0) {
+                    const normalizationError = (0, handoff_contracts_1.reviewHandoffNormalizationError)(suppliedHandoff);
+                    if (normalizationError) {
+                        return {
+                            jsonrpc: '2.0',
+                            id: request.id,
+                            result: {
+                                isError: true,
+                                content: [{ type: 'text', text: `Review handoff was not applied: ${normalizationError}. This response does not confirm delivery.` }],
+                            },
+                        };
+                    }
+                }
                 try {
                     const mentor = this.getMentor(requestSessionId);
                     const tutoringResponse = await mentor.handleMentoringRequest(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.338",
+  "version": "2.0.340",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist/registry/scripts/learning/learning-domains.json",
     "dist/registry/scripts/learning/entry-format.js",
+    "dist/registry/scripts/learning/completion-state.js",
     "dist/src/local-mcp-server/",
     "dist/src/cli/",
     "!dist/src/cli/fraim-hub.js",