@ijfw/memory-server 1.4.4 → 1.5.0

package/src/receipts.js

@@ -9,6 +9,9 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+// v1.5.0 N4.obs M1: tag every receipt with the orchestrator's trace_id so the
+// dashboard can roll up sessions->traces->observations like Langfuse / Helicone.
+import { getTraceId } from './observability/trace-id.js';
 
 export function RECEIPTS_FILE(projectDir) {
   return path.join(projectDir, '.ijfw', 'receipts', 'cross-runs.jsonl');
@@ -24,7 +27,13 @@ export function writeReceipt(projectDir, record) {
   const dest = RECEIPTS_FILE(projectDir);
   const dir = path.dirname(dest);
   fs.mkdirSync(dir, { recursive: true });
-  fs.appendFileSync(dest, JSON.stringify(record) + '\n');
+  // v1.5.0 N4.obs M1: tag with trace_id if one is set + caller hasn't supplied
+  // one. Never overwrite an explicit caller-supplied trace_id.
+  const traceId = getTraceId();
+  const enriched = (traceId && record && typeof record === 'object' && !record.trace_id)
+    ? { ...record, trace_id: traceId }
+    : record;
+  fs.appendFileSync(dest, JSON.stringify(enriched) + '\n');
   _pruneReceipts(dest);
 }
 
@@ -46,8 +55,27 @@ export function purgeReceipts(projectDir) {
   return count;
 }
 
-// Anthropic cache-read savings rate (mirrors hero-line.js constant).
-const CACHE_SAVINGS_PER_TOKEN = 2.70 / 1_000_000;
+// v1.5.0 audit-LOW-obs-L2: per-tier cache-read savings rate.
+//
+// Anthropic prompt caching: a cached read costs ~10% of an uncached input
+// token. Savings are computed as (uncached_input_rate - cached_read_rate),
+// which collapses to (0.9 * input_rate) per cached-read token. Values are
+// derived from the canonical pricing table (mcp-server/src/cost/pricing.js).
+//
+// Default tier remains sonnet (matches the prior single-constant behaviour
+// and is the dominant model on the hero-line surface), but cache_stats
+// records that carry a `model` field now dispatch to the right rate.
+const SONNET_CACHE_SAVINGS_PER_TOKEN = 2.70 / 1_000_000;
+const OPUS_CACHE_SAVINGS_PER_TOKEN   = 13.50 / 1_000_000;
+const HAIKU_CACHE_SAVINGS_PER_TOKEN  = 0.72 / 1_000_000;
+
+function cacheSavingsPerTokenFor(model) {
+  if (typeof model !== 'string' || !model) return SONNET_CACHE_SAVINGS_PER_TOKEN;
+  const m = model.toLowerCase();
+  if (m.includes('opus'))  return OPUS_CACHE_SAVINGS_PER_TOKEN;
+  if (m.includes('haiku')) return HAIKU_CACHE_SAVINGS_PER_TOKEN;
+  return SONNET_CACHE_SAVINGS_PER_TOKEN;
+}
 
 // renderReceipt(record, phaseWave?, stepNum?)
 //   phaseWave -- caller-supplied label for the narration header. Default is
@@ -101,7 +129,11 @@ export function renderReceipt(record, phaseWave = 'Trident', stepNum = 1) {
         lines.push(`Step ${stepNum}.4 -- cache created: ${cs.cache_creation_input_tokens} tokens`);
       }
       if (typeof cs.cache_read_input_tokens === 'number') {
-        const saved = cs.cache_read_input_tokens * CACHE_SAVINGS_PER_TOKEN;
+        // v1.5.0 audit-LOW-obs-L2: dispatch on cache_stats.model when set;
+        // fall back to receipt-level model; finally fall back to sonnet.
+        const modelForRate = cs.model || record.model || null;
+        const rate = cacheSavingsPerTokenFor(modelForRate);
+        const saved = cs.cache_read_input_tokens * rate;
         const savedStr = saved >= 0.01 ? ` (~$${saved.toFixed(2)} saved)` : '';
         lines.push(`Step ${stepNum}.5 -- cache read: ${cs.cache_read_input_tokens} tokens${savedStr}`);
       }

package/src/recovery/checkpoint.js

@@ -4,10 +4,15 @@
 // not a replacement for IJFW memory, but they make recovery possible when chat
 // context or a generated memory summary goes missing.
 
-import { existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, join, resolve } from 'node:path';
 import { writeAtomic } from '../lib/atomic-io.js';
-import { appendBlackboardEvent, blackboardStatus, readBlackboard } from '../blackboard.js';
+import {
+  appendBlackboardEvent,
+  blackboardPaths,
+  blackboardStatus,
+  readBlackboard,
+} from '../blackboard.js';
 import { readTeamAssembly } from '../team/generator.js';
 import { buildSwarmPlan } from '../swarm/planner.js';
 
@@ -89,13 +94,43 @@ export function listCheckpoints(projectRoot = process.cwd()) {
     .map((file) => join(paths.dir, file));
 }
 
+// v1.5.0 audit-LOW-work-L2: memoise buildSnapshot per (projectRoot, ms).
+// Snapshot construction reads team + plan + blackboard, which are themselves
+// I/O-heavy reads. The bb mtime cache already shortcuts the inner reads, but
+// when a caller does back-to-back createCheckpoint() calls (e.g. on a wave
+// boundary) we still re-build the wrapper N times. Memo is keyed on the
+// project root + blackboard mtimes + ts so any state change invalidates;
+// hot-path cache size is capped at 8 entries to stay tiny.
+const SNAPSHOT_CACHE = new Map();
+const SNAPSHOT_CACHE_MAX = 8;
+
+function snapshotCacheKey(projectRoot, ts) {
+  const paths = blackboardPaths(projectRoot);
+  let tasksMtime = 0, claimsMtime = 0;
+  try { tasksMtime = statSync(paths.tasks).mtimeMs; } catch { /* default 0 */ }
+  try { claimsMtime = statSync(paths.claims).mtimeMs; } catch { /* default 0 */ }
+  return `${paths.root}::${ts}::${tasksMtime}::${claimsMtime}`;
+}
+
 function buildSnapshot(projectRoot, meta) {
+  const cacheKey = snapshotCacheKey(projectRoot, meta.ts);
+  const cached = SNAPSHOT_CACHE.get(cacheKey);
+  if (cached) {
+    // Cached body is independent of meta.id / meta.label / meta.message;
+    // those are reapplied from the current call.
+    return {
+      ...cached,
+      id: meta.id,
+      label: meta.label,
+      message: meta.message || null,
+    };
+  }
   const blackboard = readBlackboard(projectRoot);
   const team = readTeamAssembly(projectRoot);
   const plan = buildSwarmPlan(projectRoot);
   const status = blackboardStatus(projectRoot);
   const tasks = blackboard.tasks.data.tasks || [];
-  return {
+  const snapshot = {
     schema_version: 'ijfw-checkpoint/v1',
     id: meta.id,
     label: meta.label,
@@ -122,6 +157,24 @@ function buildSnapshot(projectRoot, meta) {
     recent: blackboard.recent,
     next: recommendedNext(team, plan, tasks),
   };
+  // Stash a meta-agnostic copy in the cache (id/label/message reapplied on hit).
+  SNAPSHOT_CACHE.set(cacheKey, {
+    ...snapshot,
+    id: null,
+    label: null,
+    message: null,
+  });
+  // Narrow LRU: cap the cache size and drop the oldest insertion when over.
+  if (SNAPSHOT_CACHE.size > SNAPSHOT_CACHE_MAX) {
+    const firstKey = SNAPSHOT_CACHE.keys().next().value;
+    if (firstKey !== undefined) SNAPSHOT_CACHE.delete(firstKey);
+  }
+  return snapshot;
+}
+
+// Exposed for tests / cache invalidation hooks.
+export function _resetSnapshotCache() {
+  SNAPSHOT_CACHE.clear();
 }
 
 function renderCheckpoint(snapshot) {