@ijfw/memory-server 1.5.6 → 1.6.0

package/src/profile/eval/plumbing.test.mjs

@@ -0,0 +1,69 @@
+/**
+ * profile/eval/plumbing.test.mjs — PHASE P5.1.
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────┐
+ * │ THIS IS A PLUMBING / REGRESSION TEST. IT IS *NOT* PROOF THE SYSTEM       │
+ * │ "LEARNS YOU."                                                            │
+ * │                                                                          │
+ * │ It asserts ONE thing: synthetic signals round-trip through the REAL      │
+ * │ derivation pipeline (deriveHeuristic / deriveProfile) into a profile     │
+ * │ delta with the expected shape. That is a wiring check — it proves the    │
+ * │ pipes connect, nothing more.                                             │
+ * │                                                                          │
+ * │ It deliberately TRAINS AND TESTS ON THE SAME SIGNAL (the circular setup  │
+ * │ the slice-1 audit flagged as "the Honcho move" — assert-not-prove). That │
+ * │ circularity is FINE for a plumbing test and FATAL for a proof-of-        │
+ * │ learning claim. Do NOT cite this test as evidence the profile captures   │
+ * │ or changes behavior.                                                     │
+ * │                                                                          │
+ * │ The REAL evidence lives in the two held-out gates:                       │
+ * │   - Gate C (gate-c-capture.mjs): held-out capture, precision AND recall. │
+ * │   - Gate B (gate-b-behavior.mjs): behavioral A/B, paired McNemar.        │
+ * │ The word "prove" is reserved for Gate B passing — never for this file.   │
+ * └─────────────────────────────────────────────────────────────────────────┘
+ *
+ * Cite (why circular-capture eval is not proof): PrefEval [2502.09597].
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { deriveHeuristic } from '../derive-heuristic.js';
+import { deriveProfile } from '../derive.js';
+
+const SIGNALS = {
+  metadata: {
+    avg_msg_chars: 38, emoji_per_msg: 0, code_block_ratio: 0.7,
+    formality_markers: 0.55, turn_cadence_per_min: 6, msg_count: 20,
+  },
+  feedback: [
+    { ts: '2026-06-01T00:00:00.000Z', kind: 'correction', phrase: 'use tabs not spaces', context: '' },
+  ],
+  sessionId: 's0',
+  host: 'claude',
+};
+
+test('[PLUMBING / NOT PROOF] synthetic signals round-trip through the REAL deriveHeuristic into a delta', () => {
+  const delta = deriveHeuristic(SIGNALS);
+  // Shape-only assertions — this is a wiring check, not a learning claim.
+  assert.ok(delta && typeof delta === 'object', 'delta produced');
+  assert.ok(delta.style && delta.style.terseness, 'style axis present');
+  assert.ok(Array.isArray(delta.inferences) && delta.inferences.length === 1, 'one preference inference');
+  assert.equal(delta.inferences[0].kind, 'preference');
+  assert.equal(delta.inferences[0].subject, 'use tabs not spaces');
+});
+
+test('[PLUMBING / NOT PROOF] deriveProfile orchestrator returns the heuristic floor with zero LLM config', async () => {
+  // No local URL, no cloud opt-in -> heuristic-only floor. Round-trip wiring only.
+  const delta = await deriveProfile(SIGNALS, { env: {} });
+  assert.ok(delta && typeof delta === 'object');
+  assert.ok(delta.style && delta.style.terseness, 'heuristic floor style present');
+  assert.ok(Array.isArray(delta.inferences) && delta.inferences.length >= 1, 'heuristic floor inference present');
+});
+
+test('[PLUMBING / NOT PROOF] this file makes NO held-out or behavioral claim (guard)', () => {
+  // A literal guard so a future reader cannot quietly upgrade this plumbing test
+  // into a proof: the only thing asserted here is round-trip wiring. Real proof
+  // is Gate C (held-out capture) + Gate B (behavioral A/B), in their own files.
+  assert.ok(true, 'plumbing only — see gate-c-capture.mjs / gate-b-behavior.mjs for proof');
+});

package/src/profile/eval/prereg.mjs

@@ -0,0 +1,130 @@
+// prereg.mjs — Gate B v2, Task T6. Pre-registration rig. Freezes the analysis plan BEFORE
+// the confirmatory run so nothing can be tuned to pass after seeing results. The hash
+// covers EVERY decision-bearing field (including leakFloor, perTestAlpha, foreignAggregation)
+// so any post-hoc edit is tamper-evident. Split/persona/bootstrap seeds are a pure function
+// of preReg.seed. Per-arm alpha is Bonferroni-split across the verdict-bearing arms.
+
+import crypto from 'node:crypto';
+import { bootstrapCI } from '../../memory/bench-metrics.js';
+
+// Every field here is frozen and hashed. Editing any of them changes the runId hash.
+export const PREREG_DEFAULTS = Object.freeze({
+  primaryEndpoint: 'own-vs-nearest-same-register-foreigner-margin',
+  corpus: 'reddit-single-subreddit',
+  registerDelta: 0.15,
+  familyAlpha: 0.01,        // family-wise; Bonferroni-split across verdictArms
+  alpha: 0.02,              // bootstrap two-sided @0.02 ⇒ one-sided 99% lower bound
+  floorK: 0.25,             // measured-scale floor MULTIPLIER: minMeanMargin = floorK*(betweenMean-withinMean)
+  leakFloor: 0.02,
+  foreignAggregation: 'nearest', // NEVER 'mean'/'centroid'
+  nExemplars: 2,
+  verdictArms: ['derived', 'fewShotOracle'],
+  minSubjects: 60,
+  minDetectableEffect: 0.02,
+  seed: 1,
+});
+
+// perTestAlpha is derived but ALSO hashed, so a manual post-hoc override is tamper-evident.
+const HASHED_FIELDS = [...Object.keys(PREREG_DEFAULTS), 'perTestAlpha'];
+
+// Stable stringify: object keys sorted (key-order independent), array order preserved.
+function stableStringify(o) {
+  if (Array.isArray(o)) return `[${o.map(stableStringify).join(',')}]`;
+  if (o && typeof o === 'object') {
+    return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(o);
+}
+
+export function hashPreReg(preReg) {
+  const picked = {};
+  for (const f of HASHED_FIELDS) picked[f] = preReg[f];
+  return crypto.createHash('sha256').update(stableStringify(picked)).digest('hex');
+}
+
+// Bonferroni per-arm alpha — NOT one reused alpha. Returns { arm: familyAlpha/k }.
+export function bonferroniAlpha(familyAlpha, verdictArms) {
+  const k = verdictArms.length || 1;
+  const per = familyAlpha / k;
+  const out = {};
+  for (const a of verdictArms) out[a] = per;
+  return out;
+}
+
+// Measured-scale floor: the minimum mean margin that counts as a real effect, expressed
+// in the instrument's OWN units = floorK * (betweenMean − withinMean) from validateInstrument.
+// This REPLACES the blind absolute constant (the prior attempt's failure class). Frozen
+// before any cloud spend (floorK is hashed; the derived value is recorded in the run).
+export function deriveMinMeanMargin(validation, floorK) {
+  const sep = validation.betweenMean - validation.withinMean;
+  if (!(Number.isFinite(sep) && sep > 0)) {
+    throw new Error(`cannot derive measured-scale floor: invalid instrument separation (between ${validation.betweenMean}, within ${validation.withinMean})`);
+  }
+  if (!(Number.isFinite(floorK) && floorK > 0)) throw new Error(`invalid floorK ${floorK}`);
+  return floorK * sep;
+}
+
+// Seeds are a pure function of preReg.seed — same seed ⇒ same splits everywhere.
+export function deriveSeeds(seed) {
+  const h = (tag) => parseInt(crypto.createHash('sha256').update(`${seed}:${tag}`).digest('hex').slice(0, 8), 16) >>> 0;
+  return { splitSeed: h('split'), personaSeed: h('persona'), bootstrapSeed: h('bootstrap') };
+}
+
+// buildPreReg(input) → frozen config + derived alpha/seeds + runId hash.
+export function buildPreReg(input = {}) {
+  const cfg = { ...PREREG_DEFAULTS, ...input };
+  const perTestAlpha = bonferroniAlpha(cfg.familyAlpha, cfg.verdictArms);
+  const seeds = deriveSeeds(cfg.seed);
+  const base = { ...cfg, perTestAlpha, seeds };
+  const hash = hashPreReg(base);
+  return Object.freeze({ ...base, hash, runId: input.runId || `gateb-${hash.slice(0, 12)}` });
+}
+
+// assertFrozen(registry, preReg): a runId can be registered ONCE. Re-registering (a re-run
+// after an edit) throws — the rig refuses to silently overwrite a frozen plan.
+export function assertFrozen(registry, preReg) {
+  if (registry.has(preReg.runId)) {
+    throw new Error(`runId ${preReg.runId} already frozen (hash ${registry.get(preReg.runId).slice(0, 12)}); start a new run`);
+  }
+  registry.set(preReg.runId, preReg.hash);
+  return true;
+}
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function rng() {
+    a |= 0; a = (a + 0x6D2B79F5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+// simulatePower: Monte Carlo power under a RIGHT-SKEWED margin distribution (margins are
+// not normal — a few subjects carry most of the signal). For each sim, draw nSubjects
+// margins (mean = trueMeanMargin, right-skewed via exponential), then apply the EXACT
+// decision rule (bootstrap one-sided lower bound > 0 AND mean >= minMeanMargin). Power =
+// fraction of sims that PASS. Deterministic by seed.
+export function simulatePower(preReg, {
+  trueMeanMargin, spread = 0.05, nSubjects, sims = 300, bootIters = 300, minMeanMargin = 0,
+} = {}) {
+  const n = nSubjects || preReg.minSubjects;
+  const rng = mulberry32(preReg.seeds.bootstrapSeed ^ 0x9e3779b9);
+  let pass = 0;
+  for (let s = 0; s < sims; s += 1) {
+    const margins = Array.from({ length: n });
+    for (let i = 0; i < n; i += 1) {
+      // exponential(mean=spread) shifted so the overall mean is trueMeanMargin
+      const exp = -Math.log(1 - rng()) * spread;
+      margins[i] = trueMeanMargin - spread + exp;
+    }
+    const mean = margins.reduce((a, b) => a + b, 0) / n;
+    // measured-scale floor is run-derived (deriveMinMeanMargin); the planner passes a
+    // hypothesized value here. Defaults to 0 so the CI leg dominates the planning estimate.
+    const ci = bootstrapCI(margins, { iters: bootIters, alpha: preReg.alpha, seed: (s * 2654435761) >>> 0 });
+    if (ci.lo > 0 && mean >= minMeanMargin) pass += 1;
+  }
+  return pass / sims;
+}
+
+export const __test = { stableStringify, HASHED_FIELDS };

package/src/profile/eval/prereg.test.mjs

@@ -0,0 +1,78 @@
+// Gate B v2 — Task T6: pre-registration rig. Tamper-evidence (any frozen field changes the
+// hash), freeze-once (no overwrite), seed-pure derivation, per-arm Bonferroni alpha, and a
+// power simulation that responds to the true effect size.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  buildPreReg, hashPreReg, bonferroniAlpha, deriveSeeds, assertFrozen, simulatePower, deriveMinMeanMargin,
+} from './prereg.mjs';
+
+test('deriveMinMeanMargin = floorK*(between-within); throws on invalid instrument scale', () => {
+  assert.ok(Math.abs(deriveMinMeanMargin({ betweenMean: 0.5, withinMean: 0.3 }, 0.25) - 0.05) < 1e-12);
+  assert.throws(() => deriveMinMeanMargin({ betweenMean: 0.3, withinMean: 0.5 }, 0.25), /separation/);
+  assert.throws(() => deriveMinMeanMargin({ betweenMean: 0.5, withinMean: 0.3 }, 0), /floorK/);
+});
+
+test('hashPreReg is stable and key-order independent', () => {
+  const a = buildPreReg({ seed: 7 });
+  const b = buildPreReg({ seed: 7 });
+  assert.equal(a.hash, b.hash);
+  assert.equal(a.runId, b.runId);
+  // key-order independence: same fields, different insertion order ⇒ same hash
+  const o1 = { ...a };
+  const o2 = {};
+  for (const k of Object.keys(o1).reverse()) o2[k] = o1[k];
+  assert.equal(hashPreReg(o1), hashPreReg(o2));
+});
+
+test('TAMPER-EVIDENCE: changing any frozen field changes the hash', () => {
+  const base = buildPreReg({});
+  assert.notEqual(base.hash, buildPreReg({ leakFloor: 0.05 }).hash, 'leakFloor');
+  assert.notEqual(base.hash, buildPreReg({ foreignAggregation: 'mean' }).hash, 'foreignAggregation');
+  assert.notEqual(base.hash, buildPreReg({ familyAlpha: 0.02 }).hash, 'familyAlpha (⇒ perTestAlpha)');
+  assert.notEqual(base.hash, buildPreReg({ registerDelta: 0.2 }).hash, 'registerDelta');
+  assert.notEqual(base.hash, buildPreReg({ floorK: 0.4 }).hash, 'floorK (measured-scale floor multiplier)');
+  // perTestAlpha itself is hashed: a manual override is caught
+  assert.notEqual(hashPreReg(base), hashPreReg({ ...base, perTestAlpha: { derived: 0.001, fewShotOracle: 0.009 } }));
+});
+
+test('FREEZE-ONCE: assertFrozen refuses to overwrite an existing runId', () => {
+  const registry = new Map();
+  const pr = buildPreReg({ seed: 3 });
+  assert.equal(assertFrozen(registry, pr), true);
+  assert.throws(() => assertFrozen(registry, pr), /already frozen/);
+});
+
+test('seeds are a pure function of preReg.seed', () => {
+  assert.deepEqual(deriveSeeds(5), deriveSeeds(5));
+  assert.notDeepEqual(deriveSeeds(5), deriveSeeds(6));
+  const pr = buildPreReg({ seed: 5 });
+  assert.deepEqual(pr.seeds, deriveSeeds(5));
+});
+
+test('per-arm Bonferroni alpha (familyAlpha/k), not one reused alpha', () => {
+  const a = bonferroniAlpha(0.01, ['derived', 'fewShotOracle']);
+  assert.equal(a.derived, 0.005);
+  assert.equal(a.fewShotOracle, 0.005);
+  const pr = buildPreReg({});
+  assert.equal(Object.keys(pr.perTestAlpha).length, 2, 'one alpha entry per verdict arm');
+  assert.ok(pr.perTestAlpha.derived < pr.familyAlpha, 'per-test alpha is stricter than family alpha');
+});
+
+test('buildPreReg returns a frozen object with a runId', () => {
+  const pr = buildPreReg({});
+  assert.ok(Object.isFrozen(pr));
+  assert.match(pr.runId, /^gateb-[0-9a-f]{12}$/);
+});
+
+test('simulatePower is in [0,1] and increases with the true effect', () => {
+  const pr = buildPreReg({ minSubjects: 60 });
+  const opts = { nSubjects: 60, sims: 120, bootIters: 200, spread: 0.05 };
+  const lowEffect = simulatePower(pr, { ...opts, trueMeanMargin: 0.0 });
+  const highEffect = simulatePower(pr, { ...opts, trueMeanMargin: 0.10 });
+  for (const p of [lowEffect, highEffect]) assert.ok(p >= 0 && p <= 1);
+  assert.ok(highEffect > lowEffect, `power rises with effect: ${highEffect} > ${lowEffect}`);
+  // deterministic
+  assert.equal(simulatePower(pr, { ...opts, trueMeanMargin: 0.10 }), highEffect);
+});

package/src/profile/eval/real-corpus.test.mjs

@@ -0,0 +1,103 @@
+/**
+ * real-corpus.test.mjs — offline plumbing tests for the REAL-CORPUS eval scripts
+ * (corpus-from-transcripts + build-real-probes). These do NOT touch the network
+ * or the user's real ~/.claude/projects; they drive a tiny synthetic transcript
+ * tree in a tmp dir so the parser/split/probe logic is exercised deterministically.
+ *
+ * The cloud-driven runner (run-real-corpus.mjs) is intentionally NOT unit-tested
+ * here (it requires a live API key + bounded spend); its scoring pieces are the
+ * already-tested harness functions, and it is exercised by the operator run.
+ */
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { buildCorpus } from './corpus-from-transcripts.mjs';
+import { buildRealEval } from './build-real-probes.mjs';
+
+/** Write a minimal Claude-Code-style transcript .jsonl. */
+function writeTranscript(dir, sid, messages, baseTs) {
+  const lines = messages.map((m, i) => JSON.stringify({
+    type: 'user',
+    sessionId: sid,
+    timestamp: new Date(baseTs + i * 1000).toISOString(),
+    message: { role: 'user', content: m },
+  }));
+  // include a tool_result line (must be skipped) and a meta line (must be skipped)
+  lines.push(JSON.stringify({ type: 'user', sessionId: sid, isMeta: true, timestamp: new Date(baseTs).toISOString(), message: { role: 'user', content: 'meta noise' } }));
+  lines.push(JSON.stringify({ type: 'user', sessionId: sid, timestamp: new Date(baseTs).toISOString(), message: { role: 'user', content: [{ type: 'tool_result', content: 'tool output' }] } }));
+  writeFileSync(join(dir, `${sid}.jsonl`), `${lines.join('\n')}\n`);
+}
+
+function makeTree() {
+  const root = mkdtempSync(join(tmpdir(), 'ijfw-corpus-test-'));
+  const projA = join(root, '-Users-x-projA');
+  mkdirSync(projA, { recursive: true });
+  // 4 sessions, each with >=8 human messages, spread over time. Some carry
+  // feedback-detector-triggering phrases ("don't do that", "I prefer", etc).
+  const t0 = Date.UTC(2026, 0, 1);
+  for (let s = 0; s < 4; s++) {
+    const msgs = [];
+    for (let i = 0; i < 9; i++) {
+      msgs.push(i === 0 ? "No, don't do that. I prefer tabs from now on." : `message ${i} with some content here to count chars and words properly`);
+    }
+    writeTranscript(projA, `sess-${s}`, msgs, t0 + s * 86400000); // one day apart
+  }
+  return root;
+}
+
+test('buildCorpus parses transcripts, skips meta+tool_result, derives metadata+feedback', () => {
+  const root = makeTree();
+  const { sessions, stats } = buildCorpus({ root, minMessages: 8, cap: 100 });
+  assert.equal(sessions.length, 4, 'all 4 sessions kept (>=8 human msgs each)');
+  assert.ok(stats.totalFeedbackRows > 0, 'feedback detected from trigger phrases');
+  for (const s of sessions) {
+    // metadata is the deriveStyle input shape, numbers only (no raw text)
+    assert.ok(Number.isFinite(s.metadata.avg_msg_chars));
+    assert.ok('emoji_per_msg' in s.metadata && 'code_block_ratio' in s.metadata);
+    assert.ok('formality_markers' in s.metadata && 'turn_cadence_per_min' in s.metadata);
+    assert.equal(s.host, 'claude-code');
+    assert.ok(s.ts, 'session carries a timestamp');
+    // msg_count excludes the meta + tool_result lines (9 human msgs only)
+    assert.equal(s.msg_count, 9);
+  }
+});
+
+test('buildCorpus excludes slash-command / system-reminder artifacts from style', () => {
+  const root = mkdtempSync(join(tmpdir(), 'ijfw-corpus-art-'));
+  const proj = join(root, '-Users-x-projB');
+  mkdirSync(proj, { recursive: true });
+  const t0 = Date.UTC(2026, 1, 1);
+  const msgs = [];
+  for (let i = 0; i < 10; i++) msgs.push(`genuine human message number ${i} about code`);
+  msgs.push('<command-name>/foo</command-name>');
+  msgs.push('<system-reminder>noise</system-reminder>');
+  msgs.push('Caveat: The messages below were generated by the user');
+  writeTranscript(proj, 'sx', msgs, t0);
+  const { sessions } = buildCorpus({ root, minMessages: 8, cap: 10 });
+  assert.equal(sessions.length, 1);
+  // 10 genuine + the writeTranscript trailing meta/tool_result skipped; the 3
+  // artifact lines must also be skipped -> exactly 10 counted.
+  assert.equal(sessions[0].msg_count, 10);
+});
+
+test('buildRealEval produces a disjoint LaMP time split + transcript-free probes', async () => {
+  const root = makeTree();
+  const corpus = buildCorpus({ root, minMessages: 8, cap: 100 });
+  const ev = await buildRealEval(corpus, { trainFraction: 0.5, nProbes: 5 });
+  assert.equal(ev.split.disjoint, true, 'train/test session ids are disjoint');
+  assert.ok(ev.train.length >= 1 && ev.test.length >= 1, 'both windows non-empty');
+  // train window strictly precedes test window (time-based)
+  assert.ok(Date.parse(ev.split.trainTsMax) <= Date.parse(ev.split.testTsMin));
+  assert.equal(ev.probes.length, 5);
+  for (const p of ev.probes) {
+    assert.ok(typeof p.prompt === 'string' && p.prompt.length > 0);
+    assert.ok(p.goldStyle && Number.isFinite(p.goldStyle.terseness));
+    // probe prompt must be from the authored generic bank (transcript-free)
+    assert.ok(!p.prompt.includes('message '), 'no raw transcript text in probe prompt');
+  }
+  // negative control carries an inverted target
+  assert.ok(ev.negativeControl && Array.isArray(ev.negativeControl.goldSubjects));
+});

package/src/profile/eval/real-personas.mjs

@@ -0,0 +1,109 @@
+// real-personas.mjs — Gate B v2, Task T3 (real-author half). A "persona" is one real
+// author split into DISJOINT train/test document slices. The brief is derived from TRAIN
+// only; the held-out TEST fingerprint is the scoring target (kills the train/test
+// circularity C1). Real authors carry the confirmatory headline (synthetic-personas.js
+// may only downgrade).
+//
+// SELECTION-BIAS GUARD (audit must-fix): persona selection + ordering depend ONLY on the
+// seed and author identity — NEVER on the mutual fullStyleDistance under test. Choosing
+// "well-separated" authors by the scored metric would inflate every downstream result.
+
+import { tokenizeWords } from './stylometry-features.js';
+import { fullStyleVector } from './stylometry.js';
+
+export const PERSONA_DEFAULTS = Object.freeze({
+  minTrainTokens: 1200, minTestTokens: 600, seed: 1,
+});
+
+// FNV-1a string hash → uint32. Deterministic, content-independent ordering key.
+function fnv1a(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i += 1) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+function tokenCount(text) { return tokenizeWords(text).length; }
+
+// Split one author's docs into disjoint train/test slices. Allocates whole documents to
+// TEST until the test-token floor is met, the remainder to TRAIN; both must clear their
+// floors or it THROWS (abort — do not silently shrink a slice below power).
+export function splitAuthorDocs(author, opts = {}) {
+  const cfg = { ...PERSONA_DEFAULTS, ...opts };
+  const docs = author.docs || [];
+  if (docs.length < 2) throw new Error(`persona ${author.id}: needs >=2 documents for a disjoint split`);
+
+  // deterministic doc order by seeded hash (never by content distance)
+  const order = docs.map((_, i) => i).sort((a, b) => {
+    const ha = fnv1a(`${cfg.seed}:${author.id}:${a}`);
+    const hb = fnv1a(`${cfg.seed}:${author.id}:${b}`);
+    return ha - hb || a - b;
+  });
+
+  const testIdx = [];
+  let testTok = 0;
+  for (const i of order) {
+    if (testTok >= cfg.minTestTokens) break;
+    testIdx.push(i);
+    testTok += tokenCount(docs[i]);
+  }
+  const testSet = new Set(testIdx);
+  const trainIdx = order.filter((i) => !testSet.has(i));
+  const trainDocs = trainIdx.map((i) => docs[i]);
+  const testDocs = testIdx.map((i) => docs[i]);
+  const trainTok = trainDocs.reduce((s, d) => s + tokenCount(d), 0);
+
+  if (testTok < cfg.minTestTokens) throw new Error(`persona ${author.id}: test slice ${testTok} < ${cfg.minTestTokens} tokens`);
+  if (trainTok < cfg.minTrainTokens) throw new Error(`persona ${author.id}: train slice ${trainTok} < ${cfg.minTrainTokens} tokens`);
+  // disjoint by construction (test/train index sets are complementary)
+  return {
+    trainDocs, testDocs, trainTokens: trainTok, testTokens: testTok,
+  };
+}
+
+export function makePersona(author, opts = {}) {
+  const split = splitAuthorDocs(author, opts);
+  return {
+    id: author.id,
+    synthetic: false,
+    headlineEligible: true,
+    trainDocs: split.trainDocs,
+    testDocs: split.testDocs,
+    trainTokens: split.trainTokens,
+    testTokens: split.testTokens,
+    // held-out TEST fingerprint = the scoring target (NOT derived from train).
+    fingerprint: fullStyleVector(split.testDocs.join('\n')),
+  };
+}
+
+// loadRealPersonas(corpus, opts) → up to nAuthors personas. Authors are considered in
+// seed+identity order; too-short authors are SKIPPED (not fatal in selection mode), but
+// if fewer than nAuthors qualify it THROWS — abort-and-ingest-more, never evaluate the
+// downstream gate on an underpowered set.
+export function loadRealPersonas(corpus, opts = {}) {
+  const cfg = { nAuthors: corpus.length, ...PERSONA_DEFAULTS, ...opts };
+  const ordered = [...corpus].sort((a, b) => {
+    const ha = fnv1a(`${cfg.seed}:${a.id}`);
+    const hb = fnv1a(`${cfg.seed}:${b.id}`);
+    return ha - hb || (a.id < b.id ? -1 : 1);
+  });
+
+  const personas = [];
+  const skipped = [];
+  for (const author of ordered) {
+    if (personas.length >= cfg.nAuthors) break;
+    try {
+      personas.push(makePersona(author, cfg));
+    } catch (e) {
+      skipped.push(`${author.id}: ${e.message}`);
+    }
+  }
+  if (personas.length < cfg.nAuthors) {
+    throw new Error(`only ${personas.length} qualifying personas (< ${cfg.nAuthors}); ingest more authors. skipped: ${skipped.length}`);
+  }
+  return personas;
+}
+
+export const __test = { fnv1a, tokenCount };