@ijfw/memory-server 1.4.4 → 1.5.1

package/src/memory-feedback.js

@@ -12,13 +12,32 @@
  * counts, never IDs or full receipt content.
  */
 
-import { readdir, readFile, lstat } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readdir, readFile, lstat, mkdir, appendFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
 
 const RECEIPTS_SUBPATH = join('.ijfw', 'memory', 'gate-receipts');
+const DEVIATIONS_SUBPATH = join('.ijfw', 'memory', 'deviations.jsonl');
 const MAX_FILE_BYTES = 64 * 1024;
+const MAX_DEVIATIONS_FILE_BYTES = 4 * 1024 * 1024; // 4MB JSONL cap
 const FAIL_VERDICTS = new Set(['FAIL', 'FLAG']);
 
+// W12-C N04 — deviation pattern derivation heuristics (ordered: most specific first).
+const DEVIATION_PATTERN_RULES = [
+  { label: 'test-fixture-drift',    rx: /test.*fail|expected.*got/i },
+  { label: 'flaky-infra',           rx: /timeout|EBUSY|ECONNRESET/i },
+  { label: 'missing-dep',           rx: /Cannot find module|MODULE_NOT_FOUND/i },
+  { label: 'fs-permissions',        rx: /permission denied|EACCES/i },
+  { label: 'git-cache-corruption',  rx: /cache-tree|fatal: unable to read/i },
+  { label: 'branch-collision',      rx: /branch.*already exists|cannot create branch/i },
+];
+
+const VALID_DEVIATION_EVENTS = new Set([
+  '3-attempt-cap-hit',
+  'BLOCKED',
+  'cross-ai-divergence',
+]);
+
 /**
  * readRecentReceipts(projectRoot, limit)
  *
@@ -370,3 +389,242 @@ export async function getFeedbackSuggestions(projectRoot, opts = {}) {
     return [];
   }
 }
+
+// ---------------------------------------------------------------------------
+// W12-C N04 — memory-backed deviation patterns (lock-in #48: memory feeds forward)
+// ---------------------------------------------------------------------------
+
+/**
+ * derivePattern(errorText) -> string
+ *
+ * Maps free-form error / failure text to one of seven labels (or 'unclassified').
+ * Rules are tried in order; first match wins so e.g. an "EACCES timeout" string
+ * resolves to 'flaky-infra' only when the test-fixture and timeout patterns
+ * don't match earlier — the rule order encodes priority.
+ *
+ * Pure. Safe to call with any input (null, undefined, non-strings → 'unclassified').
+ *
+ * @param {string} errorText
+ * @returns {string}
+ */
+export function derivePattern(errorText) {
+  if (typeof errorText !== 'string' || errorText.length === 0) return 'unclassified';
+  for (const rule of DEVIATION_PATTERN_RULES) {
+    if (rule.rx.test(errorText)) return rule.label;
+  }
+  return 'unclassified';
+}
+
+/**
+ * Build a short, stable hash of a payload for idempotency keys.
+ * SHA-256 over a sorted-key JSON of {event, payload}, truncated to 12 hex chars.
+ */
+function payloadHash(event, payload) {
+  const stable = stableStringify({ event, payload });
+  return createHash('sha256').update(stable).digest('hex').slice(0, 12);
+}
+
+/** Deterministic JSON: object keys sorted recursively. */
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(stableStringify).join(',') + ']';
+  const keys = Object.keys(value).sort();
+  return '{' + keys.map((k) => JSON.stringify(k) + ':' + stableStringify(value[k])).join(',') + '}';
+}
+
+/** Extract a short task summary from a payload object (best-effort, never throws). */
+function summarizeTask(payload) {
+  if (!payload || typeof payload !== 'object') return 'unknown task';
+  const s = payload.task || payload.task_summary || payload.title || payload.name;
+  if (typeof s === 'string' && s.length > 0) return s.slice(0, 120);
+  return 'unknown task';
+}
+
+/** Extract last_error text from a payload object (best-effort, never throws). */
+function extractError(payload) {
+  if (!payload || typeof payload !== 'object') return '';
+  const e = payload.last_error || payload.error || payload.message || '';
+  if (typeof e === 'string') return e;
+  return '';
+}
+
+/** Build the canonical key for an event. ts is required so repeated calls
+ * with the SAME ts produce the same key (idempotency); different ts ⇒ new key
+ * (but the payload hash guards against duplicate writes regardless of ts).
+ */
+function buildKey(event, payload, ts) {
+  const hash = payloadHash(event, payload);
+  switch (event) {
+    case '3-attempt-cap-hit':
+      return `deviation_${hash}_3attempt_${ts}`;
+    case 'BLOCKED':
+      return `deviation_${hash}_blocked_${ts}`;
+    case 'cross-ai-divergence': {
+      const commit =
+        payload && typeof payload.commit === 'string' && payload.commit.length > 0
+          ? payload.commit.slice(0, 12)
+          : 'nocommit';
+      return `deviation_consensus_${commit}_${ts}`;
+    }
+    default:
+      return `deviation_${hash}_${event}_${ts}`;
+  }
+}
+
+/** Build the human-readable value text for an event. */
+function buildValue(event, payload, pattern) {
+  if (event === 'cross-ai-divergence') {
+    const v = (payload && payload.verdicts) || {};
+    const codex = v.codex || 'n/a';
+    const gemini = v.gemini || 'n/a';
+    const claude = v.claude || 'n/a';
+    return `codex: ${codex}, gemini: ${gemini}, claude: ${claude} — pattern: ${pattern}`;
+  }
+  const task = summarizeTask(payload);
+  const err = extractError(payload);
+  const attempts = (payload && typeof payload.attempts === 'number') ? payload.attempts : 3;
+  if (event === '3-attempt-cap-hit') {
+    return `${task} failed at attempt ${attempts} — last error: ${err}. Pattern: ${pattern}`;
+  }
+  if (event === 'BLOCKED') {
+    return `${task} BLOCKED — last error: ${err}. Pattern: ${pattern}`;
+  }
+  return `${task} (${event}) — ${err}. Pattern: ${pattern}`;
+}
+
+/**
+ * recordDeviation({ event, payload, projectRoot, ts? }) → { key, pattern, written }
+ *
+ * Writes one JSONL entry to <projectRoot>/.ijfw/memory/deviations.jsonl.
+ * Idempotent: if an entry with the same payload_hash already exists in the
+ * file, returns { written: false } without appending.
+ *
+ * @param {{event: string, payload: object, projectRoot: string, ts?: string}} opts
+ * @returns {Promise<{ key: string, pattern: string, written: boolean, type: 'feedback' }>}
+ */
+export async function recordDeviation({ event, payload, projectRoot, ts } = {}) {
+  if (typeof event !== 'string' || !VALID_DEVIATION_EVENTS.has(event)) {
+    throw new Error(`recordDeviation: event must be one of ${Array.from(VALID_DEVIATION_EVENTS).join(', ')}`);
+  }
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new Error('recordDeviation: projectRoot is required');
+  }
+  payload = payload && typeof payload === 'object' ? payload : {};
+  const timestamp = typeof ts === 'string' && ts.length > 0 ? ts : new Date().toISOString();
+
+  const errorText =
+    event === 'cross-ai-divergence'
+      ? (payload && typeof payload.divergence_summary === 'string' ? payload.divergence_summary : '')
+      : extractError(payload);
+  const pattern = derivePattern(errorText);
+  const hash = payloadHash(event, payload);
+  const key = buildKey(event, payload, timestamp);
+  const value = buildValue(event, payload, pattern);
+
+  const entry = {
+    key,
+    value,
+    ts: timestamp,
+    pattern,
+    event,
+    type: 'feedback',
+    payload_hash: hash,
+  };
+
+  const filePath = join(projectRoot, DEVIATIONS_SUBPATH);
+
+  // Idempotency: scan existing entries for matching payload_hash.
+  const existing = await readDeviationsFile(filePath);
+  for (const e of existing) {
+    if (e && e.payload_hash === hash) {
+      return { key: e.key, pattern: e.pattern, written: false, type: 'feedback' };
+    }
+  }
+
+  try {
+    await mkdir(dirname(filePath), { recursive: true });
+    await appendFile(filePath, JSON.stringify(entry) + '\n', 'utf8');
+  } catch (err) {
+    throw new Error(`recordDeviation: failed to write ${filePath}: ${err.message}`);
+  }
+
+  return { key, pattern, written: true, type: 'feedback' };
+}
+
+/**
+ * Read & parse the JSONL deviations file. Skips malformed lines. Never throws.
+ */
+async function readDeviationsFile(filePath) {
+  let info;
+  try {
+    info = await lstat(filePath);
+  } catch {
+    return [];
+  }
+  if (!info.isFile()) return [];
+  if (info.size > MAX_DEVIATIONS_FILE_BYTES) return [];
+
+  let raw;
+  try {
+    raw = await readFile(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const obj = JSON.parse(trimmed);
+      if (obj && typeof obj === 'object' && typeof obj.key === 'string') {
+        out.push(obj);
+      }
+    } catch {
+      // skip malformed line
+    }
+  }
+  return out;
+}
+
+/**
+ * readDeviationPatterns({ patternLabel?, sinceISO?, event?, projectRoot })
+ *   -> Array<{key, value, ts, pattern, event, type, payload_hash}>
+ *
+ * Query function so the planner can ask "all `git-cache-corruption` events
+ * from the last 30 days" and surface the warning in fresh dispatch briefs.
+ *
+ * Returns newest-first.
+ *
+ * @param {{patternLabel?: string, sinceISO?: string, event?: string, projectRoot: string}} opts
+ * @returns {Promise<object[]>}
+ */
+export async function readDeviationPatterns(opts = {}) {
+  const { patternLabel, sinceISO, event, projectRoot } = opts;
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    throw new Error('readDeviationPatterns: projectRoot is required');
+  }
+
+  const filePath = join(projectRoot, DEVIATIONS_SUBPATH);
+  const all = await readDeviationsFile(filePath);
+
+  let sinceMs = null;
+  if (typeof sinceISO === 'string' && sinceISO.length > 0) {
+    const parsed = Date.parse(sinceISO);
+    if (!Number.isNaN(parsed)) sinceMs = parsed;
+  }
+
+  const filtered = all.filter((e) => {
+    if (patternLabel && e.pattern !== patternLabel) return false;
+    if (event && e.event !== event) return false;
+    if (sinceMs !== null) {
+      const eMs = Date.parse(e.ts);
+      if (Number.isNaN(eMs) || eMs < sinceMs) return false;
+    }
+    return true;
+  });
+
+  // Newest first by ts (string ISO compare works for valid ISO timestamps).
+  filtered.sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0));
+  return filtered;
+}

package/src/model-refresh.js

@@ -0,0 +1,292 @@
+// model-refresh.js — 24h-cached latest-model resolver for audit-roster's
+// HTTP API fallback path.
+//
+// Why: CLI dispatch (codex exec, gemini, claude -p) inherits whatever the
+// CLI defaults to, so the model ID is always fresh on the CLI path. But
+// when the CLI is NOT installed and we fall back to direct HTTP, the model
+// name is OURS to pick. Hardcoded strings rot. This module caches the
+// latest non-preview model per provider and refreshes once every 24 hours.
+//
+// Design:
+//   - getLatestModel(family) is SYNCHRONOUS — returns cached value (or
+//     hardcoded fallback) immediately. Never blocks on network.
+//   - When the cache is stale or missing, we kick off a non-blocking
+//     refresh via queueMicrotask. The CURRENT call still returns the
+//     last-known-good value. The fresh value lands by the next call.
+//   - Each provider probe is wrapped in try/catch. Probe failure leaves
+//     the previous cache entry in place.
+//   - Atomic writes: tmp-file + rename. No partial-write corruption.
+//   - Zero new deps. Node 18+ global fetch.
+//
+// Cache file shape:
+//   {
+//     "schema": 1,
+//     "updated_at": "2026-05-18T16:00:00.000Z",
+//     "models": {
+//       "openai":    { "id": "gpt-5.5",                  "checked_at": "..." },
+//       "google":    { "id": "gemini-3.1-pro",           "checked_at": "..." },
+//       "anthropic": { "id": "claude-haiku-4-5-20251001","checked_at": "..." }
+//     }
+//   }
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export const CACHE_SCHEMA = 1;
+export const TTL_MS = 24 * 60 * 60 * 1000;
+
+// Last-known-good defaults, kept in source so offline / no-API-key users
+// get a working answer. Bumped 2026-05-18 to v1.5.0-major flagships.
+export const HARDCODED_FALLBACKS = Object.freeze({
+  openai:    'gpt-5.5',
+  google:    'gemini-3.1-pro',
+  anthropic: 'claude-haiku-4-5-20251001',
+});
+
+// Resolve cache dir lazily so tests can override via env.
+export function cachePath(env = process.env) {
+  const root = env.IJFW_CACHE_DIR || join(homedir(), '.ijfw', 'cache');
+  return join(root, 'model-roster.json');
+}
+
+// Returns true if `tsISO` is within `ttlMs` of `now`.
+export function isCacheFresh(tsISO, now = Date.now(), ttlMs = TTL_MS) {
+  if (!tsISO) return false;
+  const t = Date.parse(tsISO);
+  if (!Number.isFinite(t)) return false;
+  return (now - t) < ttlMs;
+}
+
+// Read the cache file. Returns null on any error (missing / malformed).
+export function readCache(env = process.env) {
+  try {
+    const raw = readFileSync(cachePath(env), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (parsed.schema !== CACHE_SCHEMA) return null;
+    if (!parsed.models || typeof parsed.models !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Atomic write — tmp file + rename. Creates parent dir if needed.
+export function writeCache(payload, env = process.env) {
+  const p = cachePath(env);
+  mkdirSync(dirname(p), { recursive: true });
+  const tmp = `${p}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(payload, null, 2));
+  renameSync(tmp, p);
+}
+
+// Track in-flight refresh so concurrent calls don't fire N probes.
+let inflightRefresh = null;
+
+// Semver-aware comparison for model IDs.
+//
+// Why: Lexical sort breaks once a family hits double-digit majors:
+// `gemini-10.0` sorts BEFORE `gemini-2.0` because "1" < "2" before
+// length is considered. This compares dot-separated segments numerically
+// (highest first when used as a max-picker), falling back to lexical
+// for non-numeric tail segments like `-flash`, `-pro`, `-thinking`.
+//
+// Returns negative if a < b, positive if a > b, 0 if equal.
+// Inputs are full model IDs, e.g. 'gemini-2.5-pro', 'gemini-10.0-pro'.
+export function compareModelIds(a, b) {
+  // Split on hyphens AND dots so 'gemini-2.5-pro' → ['gemini','2','5','pro'].
+  const segs = (s) => String(s).split(/[-.]/);
+  const A = segs(a);
+  const B = segs(b);
+  const n = Math.max(A.length, B.length);
+  for (let i = 0; i < n; i++) {
+    const sa = A[i];
+    const sb = B[i];
+    if (sa === sb) continue;
+    if (sa === undefined) return -1;   // shorter is "less than"
+    if (sb === undefined) return 1;
+    const na = /^\d+$/.test(sa) ? parseInt(sa, 10) : NaN;
+    const nb = /^\d+$/.test(sb) ? parseInt(sb, 10) : NaN;
+    const aIsNum = Number.isFinite(na);
+    const bIsNum = Number.isFinite(nb);
+    if (aIsNum && bIsNum) {
+      if (na !== nb) return na - nb;
+      continue;
+    }
+    // Numeric segments beat non-numeric at the same position (so
+    // 'gemini-2.5-pro' < 'gemini-2.5-pro-thinking' falls out via the
+    // length rule above; here we just need deterministic ordering for
+    // mixed types).
+    if (aIsNum !== bIsNum) return aIsNum ? 1 : -1;
+    // Both non-numeric — lexical fallback.
+    return sa < sb ? -1 : 1;
+  }
+  return 0;
+}
+
+// Synchronous resolver. Returns the cached model id, or the hardcoded
+// fallback, NEVER null. Triggers a background refresh if stale.
+//   family: 'openai' | 'google' | 'anthropic'
+//   opts.now    — inject for tests
+//   opts.env    — inject for tests
+//   opts.fetch  — inject for tests (defaults to globalThis.fetch)
+export function getLatestModel(family, opts = {}) {
+  const env = opts.env || process.env;
+  const now = opts.now || Date.now();
+  const cache = readCache(env);
+  const cached = cache?.models?.[family]?.id;
+  const fresh = isCacheFresh(cache?.updated_at, now);
+
+  if (!fresh && !inflightRefresh) {
+    // Fire-and-forget refresh. Never throw out of the sync call.
+    inflightRefresh = refreshModelCache({ env, now, fetch: opts.fetch })
+      .catch(() => null)
+      .finally(() => { inflightRefresh = null; });
+  }
+
+  return cached || HARDCODED_FALLBACKS[family] || null;
+}
+
+// Per-provider model-list probe. Each returns either { id } on success or
+// null on failure (network / auth / unexpected shape). NEVER throws.
+//
+// All three providers expose a list-models endpoint. We pick the latest
+// non-preview, non-deprecated entry that looks like a current reasoning
+// model. Heuristic, intentionally conservative.
+//
+// v1.5.0 audit-LOW-tok-L2: every probe is wrapped in an AbortController
+// with a hard timeout so a hung TLS handshake / TCP half-open can't keep
+// the event loop alive past process exit. Without this the Node runtime
+// would leak open sockets when getLatestModel() schedules a background
+// refresh and the host process tries to exit before the probes resolve.
+
+const PROBE_TIMEOUT_MS = 5000;
+
+// makeAbortable -> { signal, cancel } pair. Caller MUST call cancel() in
+// a finally{} so we always clear the timer (cancel() is a no-op once the
+// timeout has fired; we use it primarily to release the unref'd timer).
+function makeAbortable(timeoutMs = PROBE_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  // unref so the timer alone never keeps the event loop alive.
+  if (typeof timer.unref === 'function') timer.unref();
+  return { signal: controller.signal, cancel: () => clearTimeout(timer) };
+}
+
+async function probeOpenAI(env, fetchImpl) {
+  const key = env.OPENAI_API_KEY;
+  if (!key) return null;
+  const { signal, cancel } = makeAbortable();
+  try {
+    const r = await fetchImpl('https://api.openai.com/v1/models', {
+      headers: { 'Authorization': `Bearer ${key}` },
+      signal,
+    });
+    if (!r.ok) return null;
+    const json = await r.json();
+    const list = Array.isArray(json.data) ? json.data : [];
+    const candidates = list
+      .filter(m => typeof m.id === 'string')
+      .filter(m => /^gpt-[5-9]/.test(m.id))          // gpt-5+ family
+      .filter(m => !/preview|deprecated|alpha/i.test(m.id))
+      .sort((a, b) => (b.created || 0) - (a.created || 0));
+    return candidates[0] ? { id: candidates[0].id } : null;
+  } catch {
+    return null;
+  } finally {
+    cancel();
+  }
+}
+
+async function probeAnthropic(env, fetchImpl) {
+  const key = env.ANTHROPIC_API_KEY;
+  if (!key) return null;
+  const { signal, cancel } = makeAbortable();
+  try {
+    const r = await fetchImpl('https://api.anthropic.com/v1/models', {
+      headers: {
+        'x-api-key': key,
+        'anthropic-version': '2023-06-01',
+      },
+      signal,
+    });
+    if (!r.ok) return null;
+    const json = await r.json();
+    const list = Array.isArray(json.data) ? json.data : [];
+    // Pick latest haiku (lowest-cost fallback for API path; quality is
+    // bounded by the use case — apiFallback is for short audit JSON).
+    const candidates = list
+      .filter(m => typeof m.id === 'string' && /haiku/i.test(m.id))
+      .sort((a, b) => (b.created_at || '').localeCompare(a.created_at || ''));
+    return candidates[0] ? { id: candidates[0].id } : null;
+  } catch {
+    return null;
+  } finally {
+    cancel();
+  }
+}
+
+async function probeGoogle(env, fetchImpl) {
+  const key = env.GEMINI_API_KEY;
+  if (!key) return null;
+  const { signal, cancel } = makeAbortable();
+  try {
+    const r = await fetchImpl(
+      `https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(key)}`,
+      { signal },
+    );
+    if (!r.ok) return null;
+    const json = await r.json();
+    const list = Array.isArray(json.models) ? json.models : [];
+    const candidates = list
+      .map(m => typeof m.name === 'string' ? m.name.replace(/^models\//, '') : '')
+      .filter(Boolean)
+      .filter(n => n.startsWith('gemini-'))
+      .filter(n => /-pro\b/.test(n))                  // prefer pro tier
+      .filter(n => !/preview|exp|deprecated/i.test(n))
+      .sort(compareModelIds);                         // semver-aware: gemini-10.0 > gemini-2.5
+    const pick = candidates[candidates.length - 1];
+    return pick ? { id: pick } : null;
+  } catch {
+    return null;
+  } finally {
+    cancel();
+  }
+}
+
+// Refresh all three families. Preserves existing entries when a probe
+// fails so a transient outage doesn't wipe a good cache. Returns the
+// updated cache payload.
+export async function refreshModelCache({ env = process.env, now = Date.now(), fetch: fetchImpl } = {}) {
+  const fetcher = fetchImpl || globalThis.fetch;
+  if (typeof fetcher !== 'function') {
+    // Older node without global fetch — keep prior cache intact.
+    return readCache(env);
+  }
+
+  const prior = readCache(env) || { schema: CACHE_SCHEMA, updated_at: null, models: {} };
+  const next  = { schema: CACHE_SCHEMA, updated_at: new Date(now).toISOString(), models: { ...prior.models } };
+  const ts = next.updated_at;
+
+  const probes = await Promise.all([
+    probeOpenAI(env, fetcher).then(r => ({ family: 'openai', r })),
+    probeAnthropic(env, fetcher).then(r => ({ family: 'anthropic', r })),
+    probeGoogle(env, fetcher).then(r => ({ family: 'google', r })),
+  ]);
+
+  for (const { family, r } of probes) {
+    if (r && r.id) {
+      next.models[family] = { id: r.id, checked_at: ts };
+    }
+    // else: leave prior entry in place (or absent — caller falls back to
+    // HARDCODED_FALLBACKS via getLatestModel).
+  }
+
+  writeCache(next, env);
+  return next;
+}
+
+// Test helper — reset the in-flight guard so unit tests can drive refreshes
+// back-to-back without leak.
+export function _resetInflight() { inflightRefresh = null; }