@ijfw/memory-server 1.5.6 → 1.6.0

package/src/profile/derive.js

@@ -0,0 +1,156 @@
+/**
+ * profile/derive.js — Cross-system profile bus, PHASE P3.2.
+ *
+ * THE FALLBACK LADDER (moat-critical). deriveProfile() composes the two derive
+ * tiers into ONE merged ProfileDelta the merge layer folds at SessionEnd:
+ *
+ *   RUNG 1 (always): deriveHeuristic() — the zero-LLM FLOOR. This is the default
+ *     that carries the profile. It runs unconditionally, with no network, ever.
+ *
+ *   RUNG 2 (only if a LOCAL model is configured): deriveDialectic() — a bounded,
+ *     corroborated local-LLM pass whose inferences ADD ON TOP of the heuristic
+ *     floor (dialectic never overrides heuristic style/expertise; it only
+ *     contributes additional, low-confidence, cross-session-corroborated
+ *     inferences).
+ *
+ * SILENT-CLOUD PREVENTION (the whole point):
+ *   - A LOCAL transport is used iff IJFW_PROFILE_LOCAL_URL (or the reused brain
+ *     local tier endpoint IJFW_BRAIN_LOCAL_URL) is set, OR a test injects one.
+ *   - On local-LLM ABSENT or ERROR -> heuristic-only. We NEVER silently fall
+ *     through to a cloud model.
+ *   - A CLOUD transport runs ONLY when BOTH (a) IJFW_PROFILE_CLOUD_OPT_IN is
+ *     explicitly set AND (b) an explicit cloud transport is injected. This
+ *     module NEVER CONSTRUCTS a cloud transport itself — so even with the opt-in
+ *     flag, absent an injected cloud caller, nothing networks. That makes the
+ *     silent-cloud path STRUCTURALLY impossible, not merely policy-gated.
+ *
+ * The default LOCAL transport here is a self-contained Ollama-compatible fetch
+ * caller (re-implemented locally, NOT imported from brain/tiered-llm.js) so this
+ * module's import graph never reaches the cloud path. serve/render modules must
+ * never import derive.js / derive-dialectic.js — the P4.5 import-graph moat guard
+ * depends on that, and this module keeps itself self-contained to preserve it.
+ *
+ * Zero deps. ESM. Node built-ins only.
+ */
+
+import { deriveHeuristic } from './derive-heuristic.js';
+import { deriveDialectic } from './derive-dialectic.js';
+
+/**
+ * Resolve the LOCAL model endpoint. Prefer the profile-specific override, then
+ * reuse the brain's local tier endpoint (so a user who already runs a local
+ * model for the dream cycle gets profile dialectic for free). NEVER returns a
+ * cloud endpoint.
+ */
+export function resolveLocalUrl(env = process.env) {
+  const e = env || {};
+  const u = e.IJFW_PROFILE_LOCAL_URL || e.IJFW_BRAIN_LOCAL_URL;
+  return typeof u === 'string' && u.trim() ? u.trim() : null;
+}
+
+/**
+ * A self-contained Ollama-compatible local transport. Re-implemented here (NOT
+ * imported from tiered-llm.js) so derive.js's import graph never reaches the
+ * cloud caller. Single-response (stream:false) /api/generate.
+ */
+function makeLocalTransport(url) {
+  return async ({ prompt, maxTokens, model }) => {
+    const res = await fetch(url.replace(/\/$/, '') + '/api/generate', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: model || 'llama3',
+        prompt,
+        stream: false,
+        options: { num_predict: maxTokens },
+      }),
+    });
+    if (!res.ok) throw new Error(`profile local LLM HTTP ${res.status}`);
+    const data = await res.json();
+    return { text: (data && data.response) || '', via: 'local' };
+  };
+}
+
+/**
+ * deriveProfile(signals, opts) -> Promise<ProfileDelta>.
+ *
+ * @param {object} signals  the same bundle deriveHeuristic reads:
+ *   { metadata?, outcomes?, feedback?, style?, sessionId?, host? }
+ *   (`style` is the per-session metadata array the dialectic corroborates over;
+ *   `metadata` is the CURRENT session's style metadata for the heuristic floor.)
+ * @param {object} [opts]
+ *   @param {object}   [opts.env]             defaults to process.env
+ *   @param {Function} [opts._localTransport] test/override local transport
+ *   @param {Function} [opts._cloudTransport] explicit cloud transport (opt-in only)
+ *   @param {Function} [opts.log]             structured logger (degrades are LOGGED)
+ *
+ * ALWAYS returns the heuristic floor; ADDS dialectic inferences when a local (or
+ * explicitly opted-in cloud) transport is available and succeeds. Never throws.
+ */
+export async function deriveProfile(signals = {}, opts = {}) {
+  const env = opts.env || process.env;
+  const log = typeof opts.log === 'function' ? opts.log : () => {};
+
+  // RUNG 1 — the zero-LLM heuristic floor. Always. Pure, no network.
+  const heuristic = deriveHeuristic(signals || {});
+
+  // Decide which transport (if any) may run the dialectic RUNG 2.
+  //   - LOCAL: a configured local URL, OR an injected local transport.
+  //   - CLOUD: ONLY with explicit opt-in AND an explicitly injected cloud
+  //     transport. derive.js never constructs a cloud transport itself.
+  const localUrl = resolveLocalUrl(env);
+  let transport = null;
+  let lane = null;
+  if (typeof opts._localTransport === 'function') {
+    transport = opts._localTransport;
+    lane = 'local';
+  } else if (localUrl) {
+    transport = makeLocalTransport(localUrl);
+    lane = 'local';
+  } else if (env && env.IJFW_PROFILE_CLOUD_OPT_IN && typeof opts._cloudTransport === 'function') {
+    // Explicit two-key gate: the flag AND an injected cloud caller. Without the
+    // injected caller this branch is unreachable -> no silent cloud.
+    transport = opts._cloudTransport;
+    lane = 'cloud';
+  }
+
+  if (!transport) {
+    // Heuristic-only. This is the default and the safe path (no local model
+    // configured, or opt-in set but no cloud transport injected).
+    return heuristic;
+  }
+
+  // RUNG 2 — bounded, corroborated dialectic. ADD ON TOP of the heuristic floor.
+  let dialectic = { inferences: [] };
+  try {
+    dialectic = await deriveDialectic(signals || {}, {
+      transport,
+      host: signals && signals.host,
+      sessionId: signals && signals.sessionId,
+      log: (m) => log(`dialectic (${lane}): ${m}`),
+    });
+  } catch (err) {
+    // Local/cloud error -> heuristic-only. LOGGED, never swallowed (the audit
+    // flagged a swallowed-error class; we surface the degrade explicitly) and
+    // NEVER a silent cloud fallback.
+    log(`profile dialectic (${lane}) degraded to heuristic-only: ${err && err.message ? err.message : err}`);
+    return heuristic;
+  }
+
+  const addInferences = Array.isArray(dialectic && dialectic.inferences)
+    ? dialectic.inferences : [];
+  if (addInferences.length === 0) {
+    // Nothing to add (no corroboration / empty model output) — floor stands.
+    return heuristic;
+  }
+
+  // MERGE: dialectic ADDS, never overrides. Concatenate inferences; the
+  // CRDT merge (applyDelta) dedupes by id and keeps MAX confidence, so even if a
+  // dialectic subject collides with a heuristic preference, the heuristic's
+  // (higher) confidence wins on write — the floor is preserved by construction.
+  const merged = { ...heuristic };
+  merged.inferences = [...(heuristic.inferences || []), ...addInferences];
+  return merged;
+}
+
+export default { deriveProfile, resolveLocalUrl };

package/src/profile/egress.js

@@ -0,0 +1,306 @@
+/**
+ * profile/egress.js — Cross-system profile bus, PHASE P4 (egress ledger).
+ *
+ * The exfiltration AUDIT TRAIL: every time the profile leaves this machine (a
+ * brief rendered for a host, or a `profile.get`), exactly what left is appended
+ * here so the user can answer "what has any agent ever seen about me?" and so
+ * `forget` can expunge the record of a now-deleted inference (design-v2 §7
+ * "exfiltration" + the right-to-be-forgotten contract from P0.7 audit.js).
+ *
+ * FORMAT — JSON-lines at `~/.ijfw/profile/egress.log`, one object per line:
+ *   { ts, host, session, fields:[...] }
+ * `fields[]` carries the leaked field ids: inference ids (e.g.
+ * `preference::tests-pass-before-commit`) and style/expertise tags (e.g.
+ * `style:formality`, `expertise:rust`). The inference ids are what `forget`
+ * matches against on purge.
+ *
+ * PURGE — `purgeEgress(removedIds)` rewrites the log ATOMICALLY (temp file in
+ * the same dir → fsync → rename, symlink-guarded — mirrors store.js discipline),
+ * dropping every entry that referenced ANY removed inference id. Dropping the
+ * whole entry (rather than scrubbing the one field) is the privacy-conservative
+ * choice: if a brief leaked a now-forgotten inference, the record that the leak
+ * happened is itself expunged so the audit trail can't resurrect the deleted id.
+ * A missing log → 0 removed (keeps the P0.7 designed-in hook a clean no-op until
+ * a brief has actually been served).
+ *
+ * Zero deps, Node built-ins only. NO LLM calls.
+ */
+
+import {
+  openSync,
+  writeFileSync,
+  fsyncSync,
+  closeSync,
+  renameSync,
+  unlinkSync,
+  readFileSync,
+  existsSync,
+  mkdirSync,
+  lstatSync,
+  constants as fsConstants,
+} from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { profileDir } from './store.js';
+
+const EGRESS_FILE = 'egress.log';
+
+/**
+ * Max bytes we will read from the egress ledger (audit LOW: read-size cap).
+ * Egress is append-only and purge-compacted, so a file beyond this is a
+ * corrupt/hand-edited artifact; refuse to slurp it whole rather than OOM. 8 MiB
+ * is far above any realistic ledger (one JSON line per brief/get served).
+ */
+const MAX_EGRESS_BYTES = 8 * 1024 * 1024;
+
+/** The egress ledger path — sibling of the profile, under the same dir. */
+export function egressLogPath() {
+  return join(profileDir(), EGRESS_FILE);
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+/** True iff `p` exists AND is a symlink (refuse to read/write through links). */
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * appendEgress(entry) -> { ok, code?, message? }. Appends ONE JSON line:
+ *   { ts, host, session, fields:[...] }
+ * `ts` defaults to now (ISO). Never throws — egress logging must never break
+ * the serve path (a brief that can't be logged still returns; logging failure
+ * is surfaced via the return shape, not an exception).
+ *
+ * @param {{ host?:string, session?:string, fields?:string[], ts?:string }} entry
+ */
+export function appendEgress(entry = {}) {
+  const target = egressLogPath();
+  // The lstat pre-check is advisory only (it is racy against a symlink swap);
+  // the LOAD-BEARING guard is the O_NOFOLLOW open below. We keep the pre-check so
+  // an already-planted symlink returns a clear EEGRESS_SYMLINK rather than the
+  // ELOOP that O_NOFOLLOW raises.
+  if (isSymlink(target)) {
+    return { ok: false, code: 'EEGRESS_SYMLINK', message: `refusing symlinked egress log: ${target}` };
+  }
+  const rec = {
+    ts: typeof entry.ts === 'string' && entry.ts ? entry.ts : new Date().toISOString(),
+    host: typeof entry.host === 'string' ? entry.host : null,
+    session: typeof entry.session === 'string' ? entry.session : null,
+    fields: Array.isArray(entry.fields) ? entry.fields.map((f) => String(f)) : [],
+  };
+  // Optional `cloud` flag — set ONLY when the caller explicitly marks this
+  // disclosure as bound for a CLOUD host (appendExemplarEgress). Back-compat:
+  // omitted entirely for normal local disclosures so the historical
+  // {ts,host,session,fields} line shape is unchanged when the flag is absent.
+  if (entry.cloud === true) rec.cloud = true;
+  // HIGH-1 (symlink-TOCTOU): the previous appendFileSync(target,…) FOLLOWED a
+  // pre-planted `egress.log` symlink (and created+followed it if absent),
+  // letting an attacker redirect this append to an arbitrary file. We now open
+  // the fd ourselves with O_NOFOLLOW so a symlinked target is REFUSED by the
+  // kernel (ELOOP) rather than followed, and write through that fd. O_APPEND
+  // keeps the append atomicity; O_CREAT|0o600 preserves create-if-absent with
+  // owner-only perms. O_NOFOLLOW is a no-op on Windows, where the isSymlink()
+  // lstat above is the portable guard.
+  //
+  // Tamper-evidence: this ledger is ADVISORY (append-only, not hash-chained). A
+  // local attacker with write access to the file can still rewrite prior lines;
+  // the integrity guarantee here is only that WE never write THROUGH a symlink.
+  let fd = null;
+  try {
+    ensureDir(profileDir());
+    fd = openSync(
+      target,
+      fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | fsConstants.O_NOFOLLOW,
+      0o600,
+    );
+    writeFileSync(fd, `${JSON.stringify(rec)}\n`, { encoding: 'utf8' });
+    fsyncSync(fd);
+    return { ok: true, entry: rec };
+  } catch (err) {
+    // ELOOP => the target is (now) a symlink; surface our domain code.
+    if (err && err.code === 'ELOOP') {
+      return { ok: false, code: 'EEGRESS_SYMLINK', message: `refusing symlinked egress log: ${target}` };
+    }
+    return { ok: false, code: err.code || 'EEGRESS_WRITE', message: err.message };
+  } finally {
+    if (fd != null) { try { closeSync(fd); } catch {} }
+  }
+}
+
+/**
+ * readEgress() -> { ok, entries:[...] }. Reads + parses every JSON line. A
+ * missing log -> empty list. Unparseable lines are skipped (the log is an
+ * append-only audit surface; one bad line must not poison the whole read).
+ */
+export function readEgress() {
+  const target = egressLogPath();
+  if (isSymlink(target)) {
+    return { ok: false, code: 'EEGRESS_SYMLINK', entries: [] };
+  }
+  if (!existsSync(target)) return { ok: true, entries: [] };
+  // Read-size cap (audit LOW): refuse to slurp a pathologically large ledger.
+  try {
+    const st = lstatSync(target);
+    if (st.isFile() && st.size > MAX_EGRESS_BYTES) {
+      return { ok: false, code: 'EEGRESS_TOOBIG', message: `egress log exceeds ${MAX_EGRESS_BYTES} bytes`, entries: [] };
+    }
+  } catch {
+    // stat failure falls through to the read, which surfaces its own error.
+  }
+  let raw;
+  try {
+    raw = readFileSync(target, 'utf8');
+  } catch (err) {
+    return { ok: false, code: err.code || 'EEGRESS_READ', message: err.message, entries: [] };
+  }
+  const entries = [];
+  for (const line of raw.split('\n')) {
+    const s = line.trim();
+    if (!s) continue;
+    try {
+      entries.push(JSON.parse(s));
+    } catch {
+      // skip a corrupt line — best-effort audit read.
+    }
+  }
+  return { ok: true, entries };
+}
+
+/**
+ * Atomic write of the full egress contents (used by purge). temp in same dir →
+ * fsync → rename, symlink-guarded both sides. Returns { ok, code?, message? }.
+ */
+function atomicRewrite(target, contents) {
+  if (isSymlink(target)) {
+    return { ok: false, code: 'EEGRESS_SYMLINK', message: `refusing symlinked egress log: ${target}` };
+  }
+  try {
+    ensureDir(profileDir());
+  } catch (err) {
+    return { ok: false, code: err.code || 'EMKDIR', message: err.message };
+  }
+  const tmp = `${target}.tmp.${process.pid}.${randomBytes(4).toString('hex')}`;
+  let fd;
+  try {
+    fd = openSync(
+      tmp,
+      fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
+      0o600,
+    );
+    writeFileSync(fd, contents, 'utf8');
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = null;
+    if (isSymlink(target)) {
+      try { unlinkSync(tmp); } catch {}
+      return { ok: false, code: 'EEGRESS_SYMLINK', message: `target became a symlink: ${target}` };
+    }
+    renameSync(tmp, target);
+    return { ok: true };
+  } catch (err) {
+    if (fd != null) { try { closeSync(fd); } catch {} }
+    try { unlinkSync(tmp); } catch {}
+    return { ok: false, code: err.code || 'EEGRESS_WRITE', message: err.message };
+  }
+}
+
+/**
+ * purgeEgress(removedIds) -> number. Drops every egress entry whose `fields[]`
+ * references ANY id in `removedIds`, rewriting the log atomically. Returns the
+ * count of entries removed. A missing log, an empty removedIds, or zero matches
+ * -> 0 (and no rewrite). Never throws — this is called from `forget`, which must
+ * complete the inference removal even if the egress rewrite fails.
+ *
+ * @param {string[]|Set<string>} removedIds inference ids being forgotten
+ */
+export function purgeEgress(removedIds) {
+  const ids = removedIds instanceof Set ? removedIds : new Set(removedIds || []);
+  if (ids.size === 0) return 0;
+
+  const target = egressLogPath();
+  if (!existsSync(target)) return 0; // nothing served yet -> nothing to purge.
+
+  const r = readEgress();
+  if (!r.ok) return 0;
+
+  const kept = [];
+  let removedCount = 0;
+  for (const entry of r.entries) {
+    const fields = Array.isArray(entry.fields) ? entry.fields : [];
+    const leaked = fields.some((f) => ids.has(String(f)));
+    if (leaked) {
+      removedCount += 1;
+    } else {
+      kept.push(entry);
+    }
+  }
+
+  if (removedCount === 0) return 0; // no entry referenced a removed id.
+
+  const contents = kept.length
+    ? `${kept.map((e) => JSON.stringify(e)).join('\n')}\n`
+    : '';
+  const w = atomicRewrite(target, contents);
+  if (!w.ok) return 0; // rewrite failed -> report nothing purged (forget still removed the inference).
+  return removedCount;
+}
+
+// ---------------------------------------------------------------------------
+// Voice-exemplar disclosure (V4). A voice exemplar is a short raw snippet of the
+// user's OWN writing few-shot into a prompt so the agent can draft in their
+// voice. CAPTURE IS NOT DISCLOSURE: storing an exemplar logs nothing here. This
+// helper is called ONLY when an exemplar is actually INJECTED into a prompt
+// (the injection wiring is a later slice; this slice builds + unit-tests the
+// helper). Encoding it through the SAME `fields[]` channel the inference egress
+// uses means the existing `purgeEgress` (which drops any entry whose fields
+// reference a removed id) expunges these too — `forgetVoiceExemplars` passes the
+// prefixed field strings, so no purge-side change is required.
+// ---------------------------------------------------------------------------
+
+/** Field-prefix that namespaces a disclosed exemplar id in the egress ledger. */
+export const EXEMPLAR_FIELD_PREFIX = 'voice-exemplar::';
+
+/** The exact `fields[]` token for a disclosed exemplar id. */
+export function exemplarField(id) {
+  return `${EXEMPLAR_FIELD_PREFIX}${String(id)}`;
+}
+
+/**
+ * appendExemplarEgress({ ids, host, session, cloudHost }) -> { ok, code?, message?, entry? }.
+ *
+ * Logs ONE JSON line recording that the given voice-exemplar ids were disclosed
+ * (injected) into a prompt. Reuses `appendEgress` (single source of the
+ * symlink-guarded atomic-append discipline) — every exemplar id is encoded as a
+ * `voice-exemplar::<id>` field so `purgeEgress` already matches it on forget.
+ *
+ * CLOUD-HOST FLAG: when `cloudHost` is true the entry is marked TWO ways for an
+ * auditor — a structured `cloud:true` on the record (clean boolean) AND a
+ * sentinel `voice-exemplar::cloud-host` field (so even a fields-only reader, or
+ * a grep of the raw ledger, can see "these writing samples were sent to a CLOUD
+ * host"). Never throws — disclosure logging must not break the serve path.
+ *
+ * An empty/absent `ids` is a no-op success (nothing to disclose, no line
+ * written) — we never write a contentless egress record.
+ *
+ * @param {{ ids?:string[], host?:string, session?:string, cloudHost?:boolean }} arg
+ */
+export function appendExemplarEgress({ ids = [], host, session, cloudHost = false } = {}) {
+  const list = Array.isArray(ids) ? ids.map((x) => String(x)).filter((x) => x) : [];
+  if (list.length === 0) return { ok: true, skipped: true };
+  const fields = list.map((id) => exemplarField(id));
+  if (cloudHost === true) fields.push(`${EXEMPLAR_FIELD_PREFIX}cloud-host`);
+  return appendEgress({
+    host: typeof host === 'string' ? host : undefined,
+    session: typeof session === 'string' ? session : undefined,
+    fields,
+    cloud: cloudHost === true ? true : undefined,
+  });
+}

package/src/profile/eval/build-real-probes.mjs

@@ -0,0 +1,197 @@
+/**
+ * profile/eval/build-real-probes.mjs — turn a REAL transcript corpus into the
+ * { sessions(train), probes, negativeControl } shape Gate B/C consume, with a
+ * LaMP time-based split and HONEST, transcript-free probe construction.
+ *
+ * ── SPLIT ──────────────────────────────────────────────────────────────────
+ * Time-based (LaMP [2304.11406]): sessions sorted by ts; the first `trainFrac`
+ * are TRAIN (the only sessions derivation ever sees), the rest are the held-out
+ * TEST window. Disjoint session ids by construction; the gates re-assert it.
+ *
+ * ── GOLD (the honesty crux) ─────────────────────────────────────────────────
+ * Gate C gold = the preference subjects the user ACTUALLY expressed in the
+ * held-out TEST window, recovered by the SAME heuristic pipeline (so it is the
+ * user's own later-window signal, not a hand-picked target). Recovering a
+ * TRAIN-derived subject in that TEST gold tests cross-time generalization — and
+ * because the heuristic keys on a sentence-fragment slug, exact cross-time
+ * matches are rare; Gate C will report that low recall HONESTLY rather than
+ * rigging exact restatements (the synthetic fixture's 0.75 came from designed
+ * exact restatements that real cross-time data does not contain).
+ *
+ * Gate B goldStyle = the user's held-out OBJECTIVE style target, computed from
+ * the TEST-window per-session metadata (numbers only — terseness/formality/emoji
+ * presence). NO raw transcript text is embedded in a probe. The probe `prompt`
+ * is one of a fixed set of GENERIC, transcript-free engineering tasks the eval
+ * authors — nothing from the user's messages.
+ *
+ * ── PRIVACY ─────────────────────────────────────────────────────────────────
+ * Probes carry only: numeric goldStyle, slugged goldSubjects (already PII/
+ * special-category-scrubbed by the derive pipeline), an authored prompt, and ids.
+ * No raw user prose. The probe set is safe to (and does) drive the cloud agent.
+ *
+ * Zero deps, Node built-ins, no network, no LLM.
+ */
+
+import { deriveProfileFromSessions, assertedSubjects } from './gate-c-capture.mjs';
+import { objectiveStyle } from './harness.mjs';
+
+/**
+ * Map the user's TRAIN-derived style EMA onto an objective-style target the Gate
+ * B `objectiveAdherence` fallback (styleDistance) scores against. We translate
+ * the four derived axes into the objectiveStyle dimension space:
+ *   - terseness   <- derived terseness EMA directly (same 120-char scale)
+ *   - formalityMarkers <- derived formality EMA
+ *   - emoji presence   <- derived emoji_use EMA (> 0.15 => "uses emoji")
+ *   - code presence    <- from the mean code_block_ratio of the window
+ * This keeps the Gate B style target on the user's REAL fingerprint instead of
+ * the synthetic fixture's terse/tabs persona.
+ */
+function styleTargetFromAxes(profile, meanCodeRatio) {
+  const s = profile.global.style;
+  // NOTE on codeBlock: the user's transcripts have a high code_block_ratio, but
+  // that is an artifact of pasting code/diffs INTO Claude, NOT a property of the
+  // assistant-style the brief conveys. The style brief only encodes
+  // terseness/formality/emoji — so the objective target is scoped to the
+  // brief-CONTROLLABLE dimensions. Including codeBlock would penalize an arm for
+  // a facet the brief never asks for (an unfair, non-falsifiable target). We
+  // keep meanCodeRatio in the record for transparency but DO NOT score on it.
+  return {
+    terseness: Number(s.terseness && s.terseness.ema) || 0.5,
+    formalityMarkers: Number(s.formality && s.formality.ema) || 0.5,
+    emojiPerChar: (Number(s.emoji_use && s.emoji_use.ema) || 0) > 0.15 ? 0.001 : 0,
+    codeBlock: 0, // not brief-controllable; excluded from the objective target
+    len: 0,
+    _observed_code_block_ratio: Math.round(meanCodeRatio * 1000) / 1000,
+  };
+}
+
+function meanCode(sessions) {
+  if (!sessions.length) return 0;
+  let sum = 0;
+  for (const s of sessions) sum += Number(s.metadata.code_block_ratio) || 0;
+  return sum / sessions.length;
+}
+
+/**
+ * A fixed set of GENERIC engineering prompts (transcript-free). Gate B asks the
+ * agent to answer each WITH vs WITHOUT the profile brief; adherence is scored on
+ * whether the OUTPUT matches the user's held-out objective style. These prompts
+ * are deliberately open-ended so style (length/formality/emoji) is free to vary.
+ */
+export const GENERIC_PROMPTS = [
+  'Explain what a rate limiter does and when to use one.',
+  'How should I structure a new TypeScript module?',
+  'Review this approach: caching API responses in memory. Any concerns?',
+  'What is the difference between a process and a thread?',
+  'Walk me through setting up CI for a Node project.',
+  'Should I use a monorepo or separate repos for three related services?',
+  'Explain how database indexing improves query performance.',
+  'What are the tradeoffs of server-side vs client-side rendering?',
+  'How do I debug a memory leak in a long-running service?',
+  'Describe a good branching strategy for a small team.',
+  'What is idempotency and why does it matter for APIs?',
+  'How would you design a simple job queue?',
+  'Explain the CAP theorem in practical terms.',
+  'When should I reach for a message broker instead of direct calls?',
+  'How do I make a slow SQL query faster?',
+  'What belongs in a code review checklist?',
+  'Explain dependency injection and when it helps.',
+  'How should secrets be managed in a deployment pipeline?',
+  'What is the point of a feature flag system?',
+  'Describe how you would add observability to a new service.',
+];
+
+/**
+ * buildRealEval(corpus, opts) -> { train, test, probes, negativeControl, split }.
+ *
+ * @param {object} corpus  { sessions } from corpus-from-transcripts.buildCorpus
+ * @param {object} [opts]
+ *   @param {number} [opts.trainFraction] default 0.6
+ *   @param {number} [opts.nProbes]       number of behavior probes (default 30)
+ */
+export async function buildRealEval(corpus, opts = {}) {
+  const all = (corpus.sessions || []).slice().sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts));
+  const frac = Number.isFinite(opts.trainFraction) ? opts.trainFraction : 0.6;
+  const k = Math.max(1, Math.min(all.length - 1, Math.round(all.length * frac)));
+  const train = all.slice(0, k);
+  const test = all.slice(k);
+
+  const trainIds = new Set(train.map((s) => String(s.session_id)));
+  const testIds = new Set(test.map((s) => String(s.session_id)));
+  let disjoint = true;
+  for (const id of testIds) if (trainIds.has(id)) { disjoint = false; break; }
+
+  // Gate C gold = subjects the user expressed in the HELD-OUT test window,
+  // recovered by the SAME pipeline (real later-window signal).
+  const trainProfile = await deriveProfileFromSessions(train, {});
+  const testProfile = await deriveProfileFromSessions(test, {});
+  const testGoldSubjects = assertedSubjects(testProfile);
+
+  // Gate B style target — CIRCULARITY FIX (2026-06-08 cross-audit).
+  // PRIOR BUG: goldStyle was the TRAIN-derived fingerprint — the SAME object the
+  // injected brief encodes. Scoring output against the value we just handed the
+  // model is teaching-to-the-test: any "win" is the model obeying the numbers in
+  // its prompt, not generalizing to the user. Every past Gate B style number
+  // (the 0.617/0.728/0.834 line) was train-target and is SUPERSEDED.
+  // FIX: the brief stays TRAIN-derived (what we actually learned), but the
+  // scoring target is the HELD-OUT TEST fingerprint — a style the model never
+  // saw. Now reducing distance is a real cross-time generalization claim.
+  const styleTargetTrain = styleTargetFromAxes(trainProfile, meanCode(train)); // injected via brief; reported for drift only
+  const styleTargetTest = styleTargetFromAxes(testProfile, meanCode(test));    // SCORING target (held-out)
+  const styleTarget = styleTargetTest;
+
+  // Build N behavior probes from the generic prompt bank. goldSubjects on the
+  // probes is the TEST-window gold (so Gate C, when it consumes probes, scores
+  // the held-out signal); goldStyle is the user's real objective style target.
+  const nProbes = Number.isFinite(opts.nProbes) ? opts.nProbes : 30;
+  const probes = [];
+  for (let i = 0; i < nProbes; i++) {
+    const prompt = GENERIC_PROMPTS[i % GENERIC_PROMPTS.length];
+    probes.push({
+      session_id: `probe-${i}`,
+      sessionId: `probe-${i}`,
+      host: 'claude-code',
+      ts: new Date(Date.parse(all[all.length - 1].ts) + (i + 1) * 60000).toISOString(),
+      // Gate C generalization gold (held-out, real). Empty is honest if the
+      // user expressed no floor-clearing preference in the test window.
+      goldSubjects: testGoldSubjects,
+      // Gate B objective style target (the real fingerprint).
+      goldStyle: styleTarget,
+      prompt,
+    });
+  }
+
+  // NEGATIVE CONTROL — an INVERTED persona whose style target is the opposite of
+  // the user's real fingerprint (terse if user is expansive, etc.). The derived
+  // profile must NOT match this; it is the precision/over-claim guard.
+  const negStyle = objectiveStyle('Terse. No fluff.'); // a deliberately opposite target
+  const negativeControl = {
+    name: 'inverted-persona',
+    goldSubjects: ['use spaces not tabs', 'prefer verbose explanations', 'heavy emoji always'],
+    goldStyle: negStyle,
+  };
+
+  return {
+    train,
+    test,
+    probes,
+    negativeControl,
+    split: {
+      nAll: all.length,
+      nTrain: train.length,
+      nTest: test.length,
+      disjoint,
+      trainTsMin: train.length ? train[0].ts : null,
+      trainTsMax: train.length ? train[train.length - 1].ts : null,
+      testTsMin: test.length ? test[0].ts : null,
+      testTsMax: test.length ? test[test.length - 1].ts : null,
+      testGoldSubjectCount: testGoldSubjects.length,
+      trainProfileSubjectCount: assertedSubjects(trainProfile).length,
+      styleTarget,                 // = held-out TEST fingerprint (scoring target, post circularity-fix)
+      styleTargetTrain,            // what the injected brief encodes — for drift/transparency, NOT scored
+      styleTargetTest,             // explicit alias of the scoring target
+    },
+  };
+}
+
+export default { buildRealEval, GENERIC_PROMPTS };