@ijfw/memory-server 1.5.6 → 1.6.0

package/src/profile/eval/gate-b-run.test.mjs

@@ -0,0 +1,204 @@
+// Gate B v2 — PRODUCTION runner wiring. These tests prove the integration seam, not the
+// statistics (those are unit-tested in the module tests). The load-bearing claims:
+//
+//   * makeMeasure produces the EXACT confirmatory shape decideGateB/confirmatoryBooleans
+//     consume — registerEchoPasses + realArmsCarried are COMPUTED booleans, never absent
+//     (the rails THROW on undefined; we prove they don't fire here).
+//   * The register-echo arm is actually run + spliced, so the VOID rail is live.
+//   * A voice-matching fake transport drives toward PASS; a generic fake → NULL.
+//   * INSTRUMENT GATE BEFORE SPEND: when validateInstrument fails, the runner refuses to
+//     spend and the transport is NEVER called (zero calls asserted).
+//   * Fail-closed: missing API key ⇒ BLOCKED, never a silent empty pass.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  makeMeasure, runGateBProduction, buildRegisterEchoBrief, ECHO_ARM,
+} from './gate-b-run.mjs';
+import { buildPreReg } from './prereg.mjs';
+import { fullStyleVector } from './stylometry.js';
+import { generatePersonaText } from './synthetic-personas.js';
+
+// ---- persona fixtures: real human-ish text, formal register (archetype 0) ----
+function persona(id, seed) {
+  const trainDocs = [generatePersonaText(0, seed + 1, 20), generatePersonaText(0, seed + 2, 20)];
+  const testDocs = [generatePersonaText(0, seed + 9001, 16)];
+  return {
+    id,
+    synthetic: false,
+    headlineEligible: true,
+    trainDocs,
+    testDocs,
+    trainTokens: 999,
+    testTokens: 999,
+    fingerprint: fullStyleVector(testDocs.join('\n')),
+  };
+}
+// 8 same-register subjects + 4 same-register foreigners (so every subject is decidable).
+const SUBJECTS = Array.from({ length: 8 }, (_, i) => persona(`s${i}`, 1000 + i * 37));
+const FOREIGNERS = Array.from({ length: 4 }, (_, i) => persona(`f${i}`, 7000 + i * 53));
+
+// A FAITHFUL agent: when the prompt carries fewShotOracle exemplars (""" """), echo them
+// (→ that subject's own train voice). When it carries the register-echo instruction, emit a
+// register-centered generic blob (no idiosyncratic voice). Otherwise a fixed casual default.
+function voiceMatchingTransport(subjectById) {
+  return (prompt) => {
+    const ex = prompt.match(/"""([\s\S]*?)"""/g);
+    if (ex) return ex.map((s) => s.replace(/"""/g, '')).join(' ');
+    if (prompt.includes('REGISTER-ONLY')) return generatePersonaText(0, 424242, 16);
+    // derived/baseline: land near OWN voice if the brief names the subject's id, else generic
+    for (const [id, p] of Object.entries(subjectById)) {
+      if (prompt.includes(`__voice:${id}__`)) return p.trainDocs.join(' ');
+    }
+    return generatePersonaText(0, 424242, 16);
+  };
+}
+// A GENERIC agent: same register-centered blob no matter the brief → no own-voice advantage.
+function genericTransport() {
+  return () => generatePersonaText(0, 424242, 16);
+}
+// A call-counting wrapper so we can assert ZERO spend on the instrument-fail path.
+function counting(fn) {
+  const t = (p) => { t.calls += 1; return fn(p); };
+  t.calls = 0;
+  return t;
+}
+
+const TEST_CFG = {
+  minMeanMargin: 0.0005, // fixture-scaled measured floor (real run derives floorK*(between-within))
+  probes: ['Write a short note about your week.', 'React to a teammate proposal.'],
+  minRealSubjects: 1,
+  // synthetic templated train≈test ⇒ relax the 2nd-tier leak floor (real corpus uses prereg.leakFloor).
+  harnessCfg: { leakFloor: 0.0001 },
+};
+
+test('buildRegisterEchoBrief: a register-ONLY echo, distinct + honestly labeled', () => {
+  const b = buildRegisterEchoBrief(SUBJECTS[0]);
+  assert.ok(b.includes('REGISTER-ONLY'), 'echo brief is explicitly register-only');
+  // must NOT carry any train exemplar prose (it is a register echo, not a voice brief)
+  assert.ok(!SUBJECTS[0].trainDocs.some((d) => b.includes(d)));
+});
+
+test('makeMeasure returns the EXACT confirmatory shape (all rails are computed booleans)', async () => {
+  const measure = makeMeasure({
+    transport: voiceMatchingTransport(Object.fromEntries(SUBJECTS.map((p) => [p.id, p]))),
+    personas: SUBJECTS,
+    foreigners: FOREIGNERS,
+    ...TEST_CFG,
+  });
+  const preReg = buildPreReg({ verdictArms: ['derived', 'fewShotOracle'] });
+  const m = await measure({ seed: 1, phase: 'confirmatory', preReg, minMeanMargin: TEST_CFG.minMeanMargin });
+  for (const k of ['instrumentValid', 'baselinePasses', 'registerEchoPasses', 'derivedPasses', 'oraclePasses', 'realArmsCarried']) {
+    assert.equal(typeof m[k], 'boolean', `${k} must be a computed boolean, got ${typeof m[k]}`);
+  }
+  // the register-echo arm really ran (rail is live, not silent-false)
+  assert.ok(m.control.perArm[ECHO_ARM], 'register-echo arm spliced into the control');
+});
+
+test('the register-echo arm is spliced so confirmatoryBooleans does NOT throw', async () => {
+  // confirmatoryBooleans throws if control.registerEchoPasses === undefined. Prove it is defined.
+  const measure = makeMeasure({
+    transport: genericTransport(), personas: SUBJECTS, foreigners: FOREIGNERS, ...TEST_CFG,
+  });
+  const preReg = buildPreReg({});
+  const m = await measure({ seed: 1, phase: 'confirmatory', preReg, minMeanMargin: TEST_CFG.minMeanMargin });
+  assert.notEqual(m.control.registerEchoPasses, undefined);
+});
+
+test('GENERIC transport ⇒ derived does NOT pass the wrong-target control (honest NULL)', async () => {
+  const measure = makeMeasure({
+    transport: genericTransport(), personas: SUBJECTS, foreigners: FOREIGNERS, ...TEST_CFG,
+  });
+  const preReg = buildPreReg({});
+  const m = await measure({ seed: 1, phase: 'confirmatory', preReg, minMeanMargin: TEST_CFG.minMeanMargin });
+  assert.equal(m.derivedPasses, false, 'generic output is equidistant from same-register targets');
+});
+
+test('VOICE-MATCHING transport ⇒ fewShotOracle margin beats generic (drives toward PASS)', async () => {
+  const measure = makeMeasure({
+    transport: voiceMatchingTransport(Object.fromEntries(SUBJECTS.map((p) => [p.id, p]))),
+    personas: SUBJECTS,
+    foreigners: FOREIGNERS,
+    ...TEST_CFG,
+  });
+  const preReg = buildPreReg({});
+  const m = await measure({ seed: 1, phase: 'confirmatory', preReg, minMeanMargin: TEST_CFG.minMeanMargin });
+  // The oracle arm, echoing OWN train voice, lands closer to OWN test than to the nearest
+  // same-register foreigner → positive mean margin (the structural PASS direction).
+  assert.ok(m.control.perArm.fewShotOracle.meanMargin > m.control.perArm.baseline.meanMargin,
+    'oracle own-voice margin exceeds the no-brief baseline margin');
+});
+
+// ---- the full runner: instrument gate, refuse-to-spend, fail-closed ----
+
+test('INSTRUMENT GATE: validateInstrument fails ⇒ NULL verdict, ZERO transport calls', async () => {
+  const transport = counting(genericTransport());
+  const r = await runGateBProduction({
+    apiKey: 'sk-test-fake',
+    corpus: SUBJECTS.map((p) => ({ id: p.id, docs: [...p.trainDocs, ...p.testDocs] })),
+    foreignersCorpus: FOREIGNERS.map((p) => ({ id: p.id, docs: [...p.trainDocs, ...p.testDocs] })),
+    transport,
+    personaCfg: { minTrainTokens: 50, minTestTokens: 30 }, // fixture-scaled (prod = 1200/600)
+    // force the instrument gate to fail regardless of fixture AUC:
+    validateOverride: () => ({ passes: false, failedChecks: ['forced-fail'], betweenMean: 0.4, withinMean: 0.3 }),
+  });
+  assert.equal(r.spent, false);
+  assert.equal(r.verdict.verdict, 'NULL');
+  assert.equal(transport.calls, 0, 'NO cloud spend when the instrument gate fails');
+});
+
+test('FAIL-CLOSED: missing API key ⇒ BLOCKED, never a silent empty pass', async () => {
+  const r = await runGateBProduction({ apiKey: '', corpus: [], foreignersCorpus: [], transport: genericTransport() });
+  assert.equal(r.status, 'BLOCKED');
+  assert.match(r.reason, /ANTHROPIC_API_KEY|key/i);
+});
+
+test('runner wires validate→prereg→measure and returns a verdict when the gate passes', async () => {
+  const transport = counting(genericTransport());
+  const r = await runGateBProduction({
+    apiKey: 'sk-test-fake',
+    corpus: SUBJECTS.map((p) => ({ id: p.id, docs: [...p.trainDocs, ...p.testDocs] })),
+    foreignersCorpus: FOREIGNERS.map((p) => ({ id: p.id, docs: [...p.trainDocs, ...p.testDocs] })),
+    transport,
+    personaCfg: { minTrainTokens: 50, minTestTokens: 30 }, // fixture-scaled (prod = 1200/600)
+    validateOverride: () => ({ passes: true, betweenMean: 0.5, withinMean: 0.3 }),
+    preRegInput: { minSubjects: 1, floorK: 0.001 },
+    measureCfg: { ...TEST_CFG, minRealSubjects: 1 },
+  });
+  assert.equal(r.spent, true);
+  assert.ok(['PASS', 'PASS_ORACLE', 'CUT', 'NULL', 'VOID'].includes(r.verdict.verdict));
+  assert.ok(typeof r.preRegHash === 'string' && r.preRegHash.length === 64, 'frozen prereg hash surfaced');
+  assert.ok(transport.calls > 0, 'the gate passed, so the transport WAS exercised');
+});
+
+test('END-TO-END: voice-matching transport never VOIDs (baseline + register-echo NULL)', async () => {
+  // The honesty rail: a no-signal arm (baseline / register-echo) must NOT pass the control.
+  // With a faithful agent only the OWN-voice arms move; baseline + echo land on register-center.
+  const transport = voiceMatchingTransport(Object.fromEntries(SUBJECTS.map((p) => [p.id, p])));
+  const r = await runGateBProduction({
+    apiKey: 'sk-test-fake',
+    corpus: SUBJECTS.map((p) => ({ id: p.id, docs: [...p.trainDocs, ...p.testDocs] })),
+    foreignersCorpus: FOREIGNERS.map((p) => ({ id: p.id, docs: [...p.trainDocs, ...p.testDocs] })),
+    transport,
+    personaCfg: { minTrainTokens: 50, minTestTokens: 30 },
+    validateOverride: () => ({ passes: true, betweenMean: 0.5, withinMean: 0.3 }),
+    preRegInput: { minSubjects: 4, floorK: 0.001 },
+    measureCfg: { ...TEST_CFG, minRealSubjects: 1 },
+  });
+  assert.notEqual(r.verdict.verdict, 'VOID', 'no-signal arms did not contaminate the control');
+  const pa = r.confirmatory.control.perArm;
+  assert.equal(pa.baseline.verdict.passes, false, 'baseline NULLs (no own-voice signal)');
+  assert.equal(pa.registerEcho.verdict.passes, false, 'register-echo NULLs (register alone cannot win)');
+});
+
+test('formatVerdict prints a NULL/CUT as cleanly as a PASS (no retry-to-force)', async () => {
+  const { formatVerdict } = await import('./gate-b-run.mjs');
+  const out = formatVerdict({
+    status: 'DONE', spent: true, cloudCalls: 10, budgetMax: 100, nSubjects: 4, nForeigners: 4,
+    runId: 'gateb-x', preRegHash: 'h'.repeat(64),
+    verdict: { verdict: 'NULL', reason: 'real authors did not carry it', ship: 'portability' },
+    confirmatory: { control: { perArm: {} } },
+  });
+  assert.match(out, /Gate B verdict: NULL/);
+  assert.match(out, /ship:\s+portability/);
+});

package/src/profile/eval/gate-c-capture.mjs

@@ -0,0 +1,323 @@
+/**
+ * profile/eval/gate-c-capture.mjs — Cross-system profile bus, PHASE P5 (Gate C).
+ *
+ * GATE C — CAPTURE, HELD-OUT. The honest answer to "does the profile capture the
+ * user?" without the circular train==test leakage the slice-1 hook had. We:
+ *   1. Derive a profile from TRAIN sessions ONLY (sessions 1..k), through the
+ *      REAL pipeline: deriveProfile() -> applyDelta() -> a real UserProfile.
+ *   2. Evaluate on a DISJOINT, surface-varied PROBE set (LaMP time-based split):
+ *      probes live in a later time window with DIFFERENT session ids and
+ *      paraphrased restatements of the same preferences — so recovering them
+ *      tests GENERALIZATION, not memorization of exact train strings.
+ *   3. Report inference PRECISION and RECALL, each with a bootstrap CI from the
+ *      REAL lab-study helper, plus a NEGATIVE-CONTROL persona (the derived
+ *      profile must NOT match an unrelated user's prefs — a precision guard).
+ *
+ * HELD-OUT ENFORCEMENT is not a comment — it is an ASSERTION. Before scoring we
+ * verify train-session-ids ∩ probe-session-ids = ∅ (splitByTime.disjoint). If a
+ * caller hands us a leaky split, runGateC throws rather than reporting an
+ * inflated number. That is the whole point of Gate C vs the slice-1 hook.
+ *
+ * Zero deps. ESM. Wires the REAL derive/merge modules + REAL stats. No stubs.
+ *
+ * Cites: LaMP time-based split [2304.11406].
+ */
+
+import { deriveProfile } from '../derive.js';
+import { applyDelta } from '../merge.js';
+import { makeProfile } from '../schema.js';
+import {
+  splitByTime,
+  precisionRecall,
+  bootstrapCI,
+  makeHeldOutFixture,
+} from './harness.mjs';
+
+/**
+ * Normalize a phrase to the SAME subject slug the heuristic derive uses
+ * (derive-heuristic.js phraseToSubject), so a probe's gold phrase compares
+ * apples-to-apples with a derived inference's `subject`. Re-implemented here
+ * (5 lines, identical rule) to keep this eval module from importing derive
+ * internals — the derive does not export phraseToSubject.
+ */
+function toSubject(phrase) {
+  return String(phrase || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 80);
+}
+
+/**
+ * Push v2 — SEMANTIC preference match (eval-metric fix).
+ *
+ * The exact-slug match (set equality on toSubject) reports recall = 0 on the real
+ * corpus because the user restates the SAME preference cross-time with DIFFERENT
+ * words, so the verbatim sentence-fragment slugs never coincide. That conflates
+ * "captured-but-paraphrased" with "genuinely-not-captured". To separate them we
+ * add a principled LEXICAL-SEMANTIC match: two subjects count as the same
+ * preference if their CONTENT-WORD token sets overlap by Jaccard >= a documented
+ * threshold (default 0.5). No embedder is used — bringing the memory-tier
+ * embedder onto this path would also drag network/LLM modules across the profile
+ * moat — so we use a deterministic, dependency-free lexical-semantic similarity
+ * with a pre-registered threshold instead (the task's sanctioned fallback).
+ *
+ * STOPWORDS are stripped so function words ("the user prefers to") don't inflate
+ * overlap; the match is on the substantive tokens that carry the preference.
+ */
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'to', 'of', 'and', 'or', 'for', 'in', 'on', 'with', 'is',
+  'are', 'be', 'i', 'you', 'user', 'prefer', 'prefers', 'preference', 'like',
+  'likes', 'want', 'wants', 'use', 'uses', 'using', 'should', 'would', 'do',
+  'does', 'my', 'me', 'it', 'this', 'that', 'when', 'always', 'not', 'no',
+]);
+
+/** Content-word token SET for a (already-slugged) subject, stopwords removed. */
+function contentTokens(subject) {
+  const out = new Set();
+  for (const t of String(subject || '').split(/\s+/)) {
+    if (t.length >= 3 && !STOPWORDS.has(t)) out.add(t);
+  }
+  return out;
+}
+
+/** Jaccard similarity between two content-token sets (0 when either is empty). */
+function jaccard(aSet, bSet) {
+  if (!aSet.size || !bSet.size) return 0;
+  let inter = 0;
+  for (const t of aSet) if (bSet.has(t)) inter += 1;
+  return inter / (aSet.size + bSet.size - inter);
+}
+
+/**
+ * SEMANTIC precision/recall over predicted vs gold subjects, in the SAME shape
+ * the REAL precisionRecall helper returns (so the existing bootstrapCI consumes
+ * it unchanged). A predicted subject is "correct" iff it lexical-semantically
+ * matches ANY gold subject at Jaccard >= threshold; a gold subject is
+ * "recovered" iff ANY predicted subject matches it. Bipartite OR-matching (not a
+ * 1:1 assignment) — appropriate for a recovery task where one expressed
+ * preference may be derived as several near-duplicate slugs.
+ */
+export function semanticPrecisionRecall(predicted = [], gold = [], threshold = 0.5) {
+  const predTok = (predicted || []).map((p) => ({ raw: String(p), tok: contentTokens(p) }));
+  const goldTok = (gold || []).map((g) => ({ raw: String(g), tok: contentTokens(g) }));
+  const perPredCorrect = predTok.map((p) => (
+    goldTok.some((g) => jaccard(p.tok, g.tok) >= threshold) ? 1 : 0
+  ));
+  const perGoldHit = goldTok.map((g) => (
+    predTok.some((p) => jaccard(p.tok, g.tok) >= threshold) ? 1 : 0
+  ));
+  const tp = perPredCorrect.reduce((a, b) => a + b, 0);
+  const fp = perPredCorrect.length - tp;
+  const recovered = perGoldHit.reduce((a, b) => a + b, 0);
+  const fn = perGoldHit.length - recovered;
+  const precision = predTok.length ? tp / predTok.length : 0;
+  const recall = goldTok.length ? recovered / goldTok.length : 0;
+  const f1 = precision + recall > 0 ? (2 * precision * recall) / (precision + recall) : 0;
+  return { precision, recall, f1, tp, fp, fn, perGoldHit, perPredCorrect, threshold };
+}
+
+/**
+ * Derive a REAL profile from a list of train sessions. Each session is run
+ * through deriveProfile() (heuristic floor + optional injected dialectic) and the
+ * resulting delta is folded with the REAL applyDelta() CRDT merge — exactly the
+ * SessionEnd path, just driven by the eval instead of the dream runner.
+ *
+ * @param {Array} sessions  train sessions ({ metadata, feedback, outcomes, session_id, host })
+ * @param {object} [opts]   @param {Function} [opts._localTransport] dialectic arm (ablation)
+ *                          @param {object} [opts.env]
+ * @returns {Promise<object>} a UserProfile (schema shape)
+ */
+export async function deriveProfileFromSessions(sessions = [], opts = {}) {
+  let profile = makeProfile();
+  for (const s of sessions) {
+    const signals = {
+      metadata: s.metadata,
+      feedback: s.feedback,
+      outcomes: s.outcomes,
+      sessionId: s.session_id ?? s.sessionId,
+      host: s.host,
+      // dialectic corroborates over the per-session style array when present:
+      style: s.style,
+    };
+    // REAL derivation (heuristic always; dialectic only if a transport is
+    // injected — that is the heuristic-vs-dialectic ablation lever).
+    // eslint-disable-next-line no-await-in-loop
+    const delta = await deriveProfile(signals, {
+      env: opts.env,
+      _localTransport: opts._localTransport,
+    });
+    profile = applyDelta(profile, delta); // REAL CRDT merge
+  }
+  return profile;
+}
+
+/**
+ * Collect the preference subjects a profile ASSERTS — the predicted set Gate C
+ * scores against the held-out gold. We read the REAL profile's global dialectic
+ * (where derived preference inferences live) and keep the EARNED ones: a
+ * subject the profile is confident enough about to surface. We use the brief's
+ * own inclusion floor (confidence > 0.6 AND evidence_count >= 3) so Gate C scores
+ * the SAME signal a host would actually receive — not raw, un-surfaced atoms.
+ */
+export function assertedSubjects(profile, opts = {}) {
+  const minConf = Number.isFinite(opts.minConfidence) ? opts.minConfidence : 0.6;
+  const minEv = Number.isFinite(opts.minEvidence) ? opts.minEvidence : 3;
+  const dialectic = profile && profile.global && Array.isArray(profile.global.dialectic)
+    ? profile.global.dialectic : [];
+  const out = new Set();
+  for (const inf of dialectic) {
+    if (!inf || inf.kind !== 'preference') continue;
+    if (Number(inf.confidence) > minConf && (Number(inf.evidence_count) || 0) >= minEv) {
+      out.add(toSubject(inf.subject));
+    }
+  }
+  return [...out];
+}
+
+/**
+ * runGateC(corpus, opts) -> Gate C report.
+ *
+ * @param {object} [corpus]  { sessions, probes, negativeControl } — defaults to
+ *   the built-in synthetic-but-held-out fixture. A REAL session corpus drops in
+ *   here unchanged (same shape).
+ * @param {object} [opts]
+ *   @param {string|number} [opts.cutoff]        time-split boundary (else fraction)
+ *   @param {number}        [opts.trainFraction] default 0.6
+ *   @param {Function}      [opts._localTransport] dialectic arm (ablation)
+ *   @param {object}        [opts.env]
+ *   @param {number}        [opts.bootstrapSeed] default 42 (reproducible CIs)
+ *
+ * @returns {Promise<{
+ *   heldOut: { disjoint, trainIds, probeIds },
+ *   precision: { point, lo, hi }, recall: { point, lo, hi },
+ *   f1, predicted, gold, negativeControl: { precision, matched },
+ *   nTrain, nProbe }>}
+ *
+ * THROWS if the split is not disjoint (leaky held-out = invalid Gate C).
+ */
+export async function runGateC(corpus, opts = {}) {
+  const data = corpus || makeHeldOutFixture();
+  const allSessions = Array.isArray(data.sessions) ? data.sessions : [];
+  const explicitProbes = Array.isArray(data.probes) ? data.probes : [];
+
+  // TWO held-out modes, both LaMP time-based and both leakage-asserted:
+  //   (a) EXPLICIT probe set: `corpus.probes` is a separate, later-time-window
+  //       set with disjoint ids. TRAIN = all `sessions`; PROBE = `probes`.
+  //   (b) NO explicit probes: split `sessions` chronologically by time/fraction
+  //       (sessions 1..k train, the rest probe).
+  let trainSessions; let probeSessions; let trainIds; let probeIds;
+  if (explicitProbes.length > 0) {
+    trainSessions = allSessions;
+    probeSessions = explicitProbes;
+    trainIds = new Set(allSessions.map((s) => String(s.session_id ?? s.sessionId ?? '')).filter(Boolean));
+    probeIds = new Set(explicitProbes.map((p) => String(p.session_id ?? p.sessionId ?? '')).filter(Boolean));
+  } else {
+    const split = splitByTime(allSessions, {
+      cutoff: opts.cutoff,
+      trainFraction: opts.trainFraction,
+    });
+    trainSessions = split.train;
+    probeSessions = split.probe;
+    trainIds = split.trainIds;
+    probeIds = split.probeIds;
+  }
+
+  // HELD-OUT ENFORCEMENT (assertion, not comment): no probe id may appear in the
+  // train id set. A leaky split is a circular eval — refuse it.
+  let disjoint = true;
+  for (const id of probeIds) {
+    if (trainIds.has(id)) { disjoint = false; break; }
+  }
+  if (!disjoint) {
+    throw new Error(
+      'Gate C held-out violation: a probe session id also appears in the train set '
+      + '(train/test leakage). Refusing to report a circular capture score.',
+    );
+  }
+
+  // DERIVE from train sessions ONLY (the held-out probe sessions never touch
+  // derivation). REAL pipeline.
+  const profile = await deriveProfileFromSessions(trainSessions, {
+    env: opts.env,
+    _localTransport: opts._localTransport,
+  });
+
+  // PREDICTED = what the profile asserts (earned, surfaced subjects).
+  const predicted = assertedSubjects(profile);
+
+  // GOLD = the union of the probe set's surface-varied gold subjects, normalized
+  // to the same slug space. These are paraphrases the profile must GENERALIZE to.
+  const goldSet = new Set();
+  for (const p of probeSessions) {
+    for (const g of (p.goldSubjects || [])) goldSet.add(toSubject(g));
+  }
+  const gold = [...goldSet];
+
+  const pr = precisionRecall(predicted, gold);
+
+  // Bootstrap CIs on precision AND recall using the REAL helper. The per-unit
+  // 0/1 vectors precisionRecall already produced are the bootstrap inputs.
+  const seed = Number.isFinite(opts.bootstrapSeed) ? opts.bootstrapSeed : 42;
+  const precision = bootstrapCI(pr.perPredCorrect, { seed });
+  const recall = bootstrapCI(pr.perGoldHit, { seed: seed + 1 });
+
+  // Push v2 — SEMANTIC metric alongside the exact one. The exact slug match is
+  // kept (it is the honest "do the verbatim slugs coincide" floor); the semantic
+  // match (Jaccard >= threshold on content tokens) tests whether the SAME
+  // preference was captured-but-paraphrased. Same bootstrapCI helper, same
+  // per-unit vectors -> CIs are comparable across the two metrics.
+  const semThreshold = Number.isFinite(opts.semanticThreshold) ? opts.semanticThreshold : 0.5;
+  const semPr = semanticPrecisionRecall(predicted, gold, semThreshold);
+  const semantic = {
+    threshold: semThreshold,
+    precision: bootstrapCI(semPr.perPredCorrect, { seed: seed + 2 }),
+    recall: bootstrapCI(semPr.perGoldHit, { seed: seed + 3 }),
+    f1: semPr.f1,
+    counts: { tp: semPr.tp, fp: semPr.fp, fn: semPr.fn },
+  };
+
+  // NEGATIVE CONTROL — the derived (Ada) profile must NOT match Bo's prefs. We
+  // score precision of the SAME predicted set against the negative persona's
+  // gold; a low match here is the precision guard (it confirms we're not just
+  // emitting universal prefs that match anyone).
+  let negativeControl = { precision: 0, matched: [], semanticPrecision: 0, semanticMatched: [] };
+  if (data.negativeControl && Array.isArray(data.negativeControl.goldSubjects)) {
+    const ncGoldSlugs = data.negativeControl.goldSubjects.map(toSubject);
+    const ncGold = new Set(ncGoldSlugs);
+    const matched = predicted.filter((p) => ncGold.has(p));
+    // SEMANTIC negative control: the SAME Jaccard matcher applied to the inverted
+    // persona's gold. A near-zero here is the proof the semantic metric is not
+    // trivially-always-positive — it must NOT light up on an unrelated user.
+    const ncSem = semanticPrecisionRecall(predicted, ncGoldSlugs, semThreshold);
+    negativeControl = {
+      precision: predicted.length ? matched.length / predicted.length : 0,
+      matched,
+      semanticPrecision: ncSem.precision,
+      semanticMatched: predicted.filter((p, i) => ncSem.perPredCorrect[i] === 1),
+    };
+  }
+
+  return {
+    heldOut: {
+      disjoint: true,
+      trainIds: [...trainIds],
+      probeIds: [...probeIds],
+    },
+    precision,
+    recall,
+    f1: pr.f1,
+    semantic,
+    predicted,
+    gold,
+    counts: { tp: pr.tp, fp: pr.fp, fn: pr.fn },
+    negativeControl,
+    nTrain: trainSessions.length,
+    nProbe: probeIds.size,
+  };
+}
+
+export default {
+  runGateC, deriveProfileFromSessions, assertedSubjects, semanticPrecisionRecall,
+};