fraim 2.0.338 → 2.0.339

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

@@ -0,0 +1,261 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEventDir = resolveEventDir;
+exports.resolveMachineId = resolveMachineId;
+exports.appendEvents = appendEvents;
+exports.listEventLogs = listEventLogs;
+exports.readEventsSince = readEventsSince;
+exports.compactEventLogs = compactEventLogs;
+/**
+ * Issue #1752 — the durable half of the usage record.
+ *
+ * The store used to be one mutable JSON document rewritten by every writer with a
+ * plain `writeFileSync`. Measured (spike S1b): eight concurrent processes doing
+ * that on a *plain local disk*, no sync folder involved, lost 1589 of 1600
+ * writes. The four OneDrive conflict copies in issue #1752 are a symptom of the
+ * same defect, not its cause.
+ *
+ * So the durable artifact is an append-only log, one file per machine:
+ *
+ *   OFFER/FIRING event  →  appendFileSync of one whole JSON line
+ *   usage/learning-usage.json  →  a derived snapshot with a byte checkpoint
+ *
+ * Three measurements decided the shape, and each closed off an alternative:
+ *
+ *   S2   16 processes x 1000 lines on the real OneDrive-synced path produced
+ *        16000/16000 complete parseable lines, 0 interleaved, 0 conflict copies.
+ *        That is what removes the need for a same-machine lock. The per-machine
+ *        filename is what removes the cross-machine question, because two
+ *        machines then never write one file.
+ *   S3   `renameSync` over a target any process holds open fails EPERM 100 times
+ *        in 100 on Windows, on a synced path *and* a local one, because Node's
+ *        `openSync(path,'r')` does not request FILE_SHARE_DELETE. The usage store
+ *        is read by concurrent MCP processes by design, so rename-publish is not
+ *        available here. Recorded so it is not re-proposed. See also #820.
+ *   S4b  A full fold is linear: 84 ms at today's volume, 794 ms at ten times it.
+ *        A snapshot plus a tail fold is 2.6 ms at both 9.9 MB and 79 MB. Flat.
+ *
+ * This module owns the log files and nothing else: framing, appending, reading a
+ * tail from a byte offset, and compaction. It knows a line is a JSON object and
+ * knows nothing about what a usage record looks like. That is deliberate — the
+ * record shape lives in `learning-usage-store.ts`, which imports this, so there
+ * is no cycle between them.
+ *
+ * The same primitive is already used by `src/ai-hub/raw-event-log-store.ts`
+ * (append one JSON line, track byte offsets); this is the learning-usage
+ * equivalent rather than a second general mechanism.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+/** Subdirectory of the usage folder holding the per-machine logs. */
+const EVENT_DIR_NAME = 'events';
+const LOG_SUFFIX = '.jsonl';
+/** The log directory that belongs to a snapshot: `<usage>/events/`. */
+function resolveEventDir(snapshotPath) {
+    return (0, path_1.join)((0, path_1.dirname)(snapshotPath), EVENT_DIR_NAME);
+}
+/**
+ * The filename component identifying this machine. Two machines must never write
+ * one file, which is the entire cross-machine safety argument, so anything that
+ * is not a safe filename character is replaced rather than dropped (dropping can
+ * collide two different hostnames onto one name).
+ */
+function resolveMachineId() {
+    const raw = (() => { try {
+        return (0, os_1.hostname)();
+    }
+    catch {
+        return '';
+    } })();
+    const safe = String(raw || 'unknown-machine').trim().replace(/[^A-Za-z0-9._-]/g, '_');
+    return safe || 'unknown-machine';
+}
+function logPathFor(eventDir, machineId) {
+    return (0, path_1.join)(eventDir, `${machineId}${LOG_SUFFIX}`);
+}
+/**
+ * Append one JSON line per record. No read, so there is no lost-update window to
+ * narrow: the window is gone rather than smaller.
+ */
+function appendEvents(eventDir, records, machineId = resolveMachineId()) {
+    if (records.length === 0)
+        return 0;
+    (0, fs_1.mkdirSync)(eventDir, { recursive: true });
+    const logPath = logPathFor(eventDir, machineId);
+    const separator = endsOnARecordBoundary(logPath) ? '' : '\n';
+    const payload = `${separator}${records.map((record) => JSON.stringify(record)).join('\n')}\n`;
+    (0, fs_1.appendFileSync)(logPath, payload, 'utf8');
+    return records.length;
+}
+/**
+ * Does the log already end where a record ends?
+ *
+ * A process killed part-way through an append leaves a line with no terminator.
+ * Appending straight onto it concatenates the torn record and the new one into a
+ * single unparseable line, so one interrupted write costs two events rather than
+ * one. Found in the #1752 bug bash. Closing the boundary first means a torn write
+ * loses only itself.
+ *
+ * One byte read per append, and only when the log already exists.
+ */
+function endsOnARecordBoundary(logPath) {
+    try {
+        const fd = (0, fs_1.openSync)(logPath, 'r');
+        try {
+            const size = (0, fs_1.fstatSync)(fd).size;
+            if (size === 0)
+                return true;
+            const last = Buffer.alloc(1);
+            (0, fs_1.readSync)(fd, last, 0, 1, size - 1);
+            return last[0] === 0x0a;
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        // No log yet, or it cannot be read. A fresh file starts on a boundary, and an
+        // unreadable one is the fold's problem rather than the append's.
+        return true;
+    }
+}
+function listEventLogs(eventDir) {
+    if (!(0, fs_1.existsSync)(eventDir))
+        return [];
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)(eventDir);
+    }
+    catch {
+        return [];
+    }
+    const logs = [];
+    for (const name of names) {
+        if (!name.endsWith(LOG_SUFFIX))
+            continue;
+        const path = (0, path_1.join)(eventDir, name);
+        let size = 0;
+        try {
+            const fd = (0, fs_1.openSync)(path, 'r');
+            try {
+                size = (0, fs_1.fstatSync)(fd).size;
+            }
+            finally {
+                (0, fs_1.closeSync)(fd);
+            }
+        }
+        catch {
+            continue;
+        }
+        logs.push({ machineId: name.slice(0, -LOG_SUFFIX.length), path, size });
+    }
+    return logs.sort((a, b) => a.machineId.localeCompare(b.machineId));
+}
+function readTail(log, from) {
+    const restarted = from > log.size;
+    const start = restarted ? 0 : Math.max(0, from);
+    const length = log.size - start;
+    if (length <= 0) {
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    let text;
+    try {
+        const fd = (0, fs_1.openSync)(log.path, 'r');
+        try {
+            const buffer = Buffer.alloc(length);
+            const read = (0, fs_1.readSync)(fd, buffer, 0, length, start);
+            text = buffer.subarray(0, read).toString('utf8');
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+    }
+    catch {
+        // Unreadable right now (locked, mid-sync). The checkpoint does not advance,
+        // so the next reader picks it up. Degrading to what is readable is the
+        // existing contract for this derived data.
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    // Only complete lines are consumed. A trailing partial is what an interrupted
+    // append leaves behind, and advancing past it would lose the record for good.
+    const lastNewline = text.lastIndexOf('\n');
+    if (lastNewline === -1) {
+        return { ...log, records: [], skippedLines: 0, through: start, restarted };
+    }
+    const complete = text.slice(0, lastNewline);
+    const partialBytes = Buffer.byteLength(text.slice(lastNewline + 1), 'utf8');
+    const records = [];
+    let skippedLines = 0;
+    for (const line of complete.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                records.push(parsed);
+            else
+                skippedLines += 1;
+        }
+        catch {
+            skippedLines += 1;
+        }
+    }
+    return { ...log, records, skippedLines, through: log.size - partialBytes, restarted };
+}
+/**
+ * Read every log's tail past its checkpoint.
+ *
+ * A checkpoint past the end of its log means the log was compacted or replaced
+ * underneath the snapshot. `restarted` says so, and the caller discards the whole
+ * snapshot rather than returning a short count that looks like real data.
+ */
+function readEventsSince(eventDir, checkpoints) {
+    const reads = listEventLogs(eventDir).map((log) => readTail(log, checkpoints[log.machineId] ?? 0));
+    return {
+        reads,
+        skippedLines: reads.reduce((sum, r) => sum + r.skippedLines, 0),
+        restarted: reads.some((r) => r.restarted),
+    };
+}
+/**
+ * Rewrite every log keeping only the records `keep` accepts.
+ *
+ * Required rather than an optimization: S4 measured a cold full fold growing
+ * linearly to 794 ms at ten times today's volume, and the checkpoint only makes a
+ * cold fold rare, not bounded.
+ *
+ * Published by writing a temp file and renaming it. That is safe here and not on
+ * the snapshot (S3), because nothing holds a compacted log open for reading in
+ * the way concurrent MCP processes hold the snapshot: this runs from the CLI, and
+ * a failed rename leaves the original log untouched.
+ */
+function compactEventLogs(eventDir, keep) {
+    const result = { scanned: 0, kept: 0, dropped: 0, skippedLines: 0, logs: [] };
+    for (const log of listEventLogs(eventDir)) {
+        const read = readTail(log, 0);
+        result.scanned += read.records.length;
+        result.skippedLines += read.skippedLines;
+        const retained = read.records.filter(keep);
+        result.kept += retained.length;
+        result.dropped += read.records.length - retained.length;
+        if (retained.length === read.records.length && read.skippedLines === 0)
+            continue;
+        const temp = `${log.path}.compacting`;
+        try {
+            (0, fs_1.writeFileSync)(temp, retained.length ? `${retained.map((r) => JSON.stringify(r)).join('\n')}\n` : '', 'utf8');
+            (0, fs_1.renameSync)(temp, log.path);
+        }
+        catch {
+            // The log is authoritative and the original is still intact, so a failed
+            // compaction costs a slower cold fold and nothing else.
+            try {
+                (0, fs_1.rmSync)(temp, { force: true });
+            }
+            catch { /* best effort */ }
+        }
+    }
+    result.logs = listEventLogs(eventDir);
+    return result;
+}

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

@@ -50,30 +50,34 @@ function buildUsageLookup(store) {
 /**
  * Resolve the usage for one entry from whichever handles it has. Prefers the id,
  * because a title is only a fallback for entries the id migration has not reached.
+ *
+ * Issue #1752 A1: the preference order is `resolveEntryIdentity`'s, not a second
+ * copy of it. The title key is still tried afterwards, because a record written
+ * before the entry was stamped is reachable only by title.
  */
 function lookupUsage(lookup, id, fileType, title) {
-    if (id) {
-        const byId = lookup.get(id);
-        if (byId)
-            return byId;
-    }
-    return lookup.get((0, learning_usage_store_1.titleUsageKey)(fileType, title));
+    const identity = (0, learning_usage_store_1.resolveEntryIdentity)({ id, fileType, title });
+    const resolved = lookup.get(identity.key);
+    if (resolved)
+        return resolved;
+    return identity.source === 'id' ? lookup.get((0, learning_usage_store_1.titleUsageKey)(fileType, title)) : undefined;
 }
 /**
- * The model with the most recent offer. Used as "the current model" for the
- * per-model retirement question, so it follows the agent in use rather than
- * needing to be configured.
+ * Issue #1752 C1 — "the current model" comes from the caller, never from the store.
+ *
+ * This used to return the model of the globally most-recent offer. The store is
+ * shared by concurrent sessions from two machines and two agents, so that reports
+ * whichever agent wrote last. On the sleep-on-learnings run of 2026-09-18 it
+ * answered `gpt-5` while the session was Claude Opus 5, and since retirement
+ * candidacy is computed per model, every per-model conclusion in that run was
+ * computed against a model that was not running.
+ *
+ * Resolution order is the explicit flag, then `FRAIM_ACTIVE_MODEL`, then null.
+ * That follows the existing `FRAIM_ACTIVE_USER_EMAIL` convention, which is
+ * read-only and operator-set, so it introduces no new configuration mechanism.
+ * Null is reported as `unknown` and suppresses every per-model conclusion rather
+ * than being computed against a null bucket.
  */
-function resolveCurrentModel(store) {
-    let bestDate = '';
-    let bestModel = null;
-    for (const record of Object.values(store.entries)) {
-        for (const entry of record.offered.log) {
-            if (entry.model && entry.date >= bestDate) {
-                bestDate = entry.date;
-                bestModel = entry.model;
-            }
-        }
-    }
-    return bestModel;
+function resolveCurrentModel(explicit) {
+    return (0, learning_usage_store_1.normalizeModelName)(explicit) ?? (0, learning_usage_store_1.normalizeModelName)(process.env.FRAIM_ACTIVE_MODEL);
 }