Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

33.0 KB
Raw Blame
/**
 * Statistical voice fingerprint (#2166 — CWQE Phase 2) for the editorial check
 * registry. Pure and dependency-free (no side-effecting imports — only the
 * sibling editorial primitives) so it stays unit-testable in isolation, mirroring
 * ./slopScore.js / ./repetition.js / ./proseTics.js.
 *
 * This is the cheap DETERMINISTIC complement to the LLM `style.voice-consistency`
 * check (checks/proseStyle.js — subjective narrator tone). Where that check ASKS a
 * model whether the tone wobbled, this one MEASURES a fixed metric vector per issue
 * (sentence rhythm, fragment/long-sentence rates, paragraph shape, dialogue ratio,
 * em-dash rate, abstract-noun/simile density, dominant opener, optional vocabulary
 * "wells"), computes the series-wide mean/σ per metric, and names exactly which
 * issue drifted, on which metric, and in which direction. autonovel used this to
 * catch chapters whose sentence rhythm or vocabulary register silently diverged
 * from the established series voice.
 *
 * Reuses (never re-implements) the shared tokenizers: `tokenizeWords` /
 * `splitSentences` from ./proseTics.js and `splitParagraphs` /
 * `emDashDensityPer1000` from ./slopScore.js — so a fingerprint counts words and
 * segments sentences/paragraphs exactly the way every other deterministic check
 * does.
 */

import { tokenizeWords, splitSentences } from './proseTics.js';
import { splitParagraphs, emDashDensityPer1000 } from './slopScore.js';

// Word suffixes that mark an abstract / nominalized noun. Overusing them ("the
// realization of the situation") is the register signal a drifting issue shifts
// on. A coarse suffix heuristic (no POS tagger) — advisory, like every editorial
// deterministic check. Guarded by a minimum stem length below so short words
// (e.g. "ship", "dom", "ity") don't false-match.
const ABSTRACT_NOUN_SUFFIXES = Object.freeze([
  'tion', 'sion', 'ment', 'ness', 'ity', 'ance', 'ence', 'ism',
  'ship', 'hood', 'dom', 'acy', 'ude', 'ology',
]);
// A stem must have at least this many letters BEFORE the suffix, so "action" and
// "nation" count (real abstract nouns) but "dom"/"ship"/"tion" as whole short
// words don't.
const ABSTRACT_MIN_STEM = 2;

// Simile markers: an explicit "like a/an/the …" comparison, or an "as ADJ as …"
// frame. Deliberately narrow — bare "like" (a filler/verb) and bare "as" (a
// conjunction) are NOT counted, only these two comparison frames — so the density
// tracks figurative reach, not filler.
const SIMILE_LIKE_RE = /\blike\s+(?:a|an|the)\b/gi;
const SIMILE_AS_AS_RE = /\bas\s+[A-Za-z]+\s+as\b/gi;
// Any run of characters inside straight or curly double-quotes — the dialogue
// span. Non-greedy so adjacent quoted lines stay separate.
const DIALOGUE_SPAN_RE = /[“"]([^“”"]*)[”"]/g;

const round2 = (n) => Math.round(n * 100) / 100;
const round1 = (n) => Math.round(n * 10) / 10;

// Population mean / std (divide by N, not N−1): the issues ARE the whole series
// population, not a sample of a larger one, so σ is the population deviation.
function meanOf(values) {
  if (!values.length) return 0;
  return values.reduce((a, b) => a + b, 0) / values.length;
}
function stdOf(values, mean) {
  if (values.length < 2) return 0;
  const m = typeof mean === 'number' ? mean : meanOf(values);
  const variance = values.reduce((a, b) => a + (b - m) ** 2, 0) / values.length;
  return Math.sqrt(variance);
}

/**
 * The fixed metric vector every issue is fingerprinted on. Order here IS the
 * column order of `voiceFingerprintMatrix`. Each descriptor carries a `label`
 * (human name), a `unit` suffix for rendered values, and a `higher` phrase
 * describing what a high value MEANS (its opposite is auto-derived), so a drift
 * finding can read "prose has gone metronomic" instead of "cv is low".
 *
 * `wells` metrics are appended dynamically at compute time (one `well:<name>` per
 * configured vocabulary well) — they are not part of this static list.
 */
export const VOICE_METRICS = Object.freeze([
  { key: 'sentenceLenMean', label: 'sentence-length mean', unit: ' words', higher: 'longer sentences', lower: 'shorter sentences' },
  { key: 'sentenceLenStd', label: 'sentence-length spread (σ)', unit: ' words', higher: 'more varied sentence lengths', lower: 'more uniform sentence lengths' },
  { key: 'sentenceLenCV', label: 'sentence-length variation (CV)', unit: '', higher: 'more rhythmic variety', lower: 'metronomic, same-length prose' },
  { key: 'fragmentPct', label: 'fragment rate (< 5 words)', unit: '%', higher: 'more sentence fragments', lower: 'fewer sentence fragments' },
  { key: 'longSentencePct', label: 'long-sentence rate (> 30 words)', unit: '%', higher: 'more long, winding sentences', lower: 'fewer long sentences' },
  { key: 'paragraphLenMean', label: 'paragraph-length mean', unit: ' words', higher: 'longer paragraphs', lower: 'shorter paragraphs' },
  { key: 'paragraphLenStd', label: 'paragraph-length spread (σ)', unit: ' words', higher: 'more varied paragraph lengths', lower: 'more uniform paragraph lengths' },
  { key: 'dialogueRatio', label: 'dialogue ratio', unit: '%', higher: 'more dialogue-driven prose', lower: 'more narration-driven prose' },
  { key: 'emDashRate', label: 'em-dash rate (per 1k words)', unit: '', higher: 'heavier em-dash use', lower: 'lighter em-dash use' },
  { key: 'abstractNounDensity', label: 'abstract-noun density (per 1k words)', unit: '', higher: 'a more abstract, nominal register', lower: 'a more concrete register' },
  { key: 'simileDensity', label: 'simile density (per 1k words)', unit: '', higher: 'more figurative comparison', lower: 'less figurative comparison' },
  { key: 'dominantOpenerPct', label: 'dominant sentence-opener share', unit: '%', higher: 'sentences that mostly open the same way', lower: 'more varied sentence openings' },
]);

const STATIC_METRIC_KEYS = Object.freeze(VOICE_METRICS.map((m) => m.key));

/**
 * Parse a vocabulary-wells spec into `[{ name, words: Set<string> }]`. The spec
 * is a per-check-config string (series-configurable via the per-series check
 * override) declaring register categories a series wants coverage tracked for:
 *
 *   `trade: forge, anvil, temper; body: pulse, sinew, marrow`
 *
 * Categories are `;`-separated, `name: words` split on the first `:`, words
 * `,`-separated (whitespace tolerated). Empty/malformed fragments are skipped
 * (never throws) so a hand-typed spec can't break the check. Returns [] for a
 * blank/absent spec.
 *
 * @param {string} spec
 * @returns {Array<{ name: string, words: Set<string> }>}
 */
export function parseVoiceWells(spec) {
  if (typeof spec !== 'string' || !spec.trim()) return [];
  const out = [];
  const seen = new Set();
  for (const chunk of spec.split(';')) {
    const colon = chunk.indexOf(':');
    if (colon === -1) continue;
    const name = chunk.slice(0, colon).trim().toLowerCase();
    if (!name || seen.has(name)) continue;
    const words = chunk
      .slice(colon + 1)
      .split(',')
      .map((w) => w.trim().toLowerCase())
      .filter(Boolean);
    if (!words.length) continue;
    seen.add(name);
    out.push({ name, words: new Set(words) });
  }
  return out;
}

// Count of tokens (word objects from tokenizeWords) whose lowercase form is in
// the well's set — the raw hit count, turned into a per-1k density below.
function wellHits(tokens, well) {
  let n = 0;
  for (const t of tokens) if (well.words.has(t.lower)) n += 1;
  return n;
}

/**
 * The prose fingerprint of a single block of text — the metric vector for one
 * issue. Pure. Returns `{ words, sentences, paragraphs, metrics: { key: number } }`
 * where `metrics` carries every `VOICE_METRICS` key plus one `well:<name>` per
 * configured well. An empty/near-empty block yields a fingerprint whose metrics
 * are all 0 (never NaN), so a matrix row is always numeric.
 *
 * @param {string} text
 * @param {{ wells?: Array<{ name: string, words: Set<string> }> }} [opts]
 */
export function computeFingerprint(text, opts = {}) {
  const src = typeof text === 'string' ? text : '';
  const wells = Array.isArray(opts.wells) ? opts.wells : [];
  const tokens = tokenizeWords(src);
  const totalWords = tokens.length;
  const sentences = splitSentences(src);
  const paragraphs = splitParagraphs(src);

  // Sentence-length metrics (words per sentence via the shared word tokenizer, so
  // "the cat's" counts identically to every other check). Tokenize each sentence
  // ONCE — both the length pass and the dominant-opener pass below read this.
  const sentenceTokenLists = sentences.map((s) => tokenizeWords(s.text));
  const sentenceLengths = sentenceTokenLists.map((toks) => toks.length);
  const sMean = meanOf(sentenceLengths);
  const sStd = stdOf(sentenceLengths, sMean);
  const sCount = sentenceLengths.length;
  const fragmentPct = sCount ? (sentenceLengths.filter((n) => n > 0 && n < 5).length / sCount) * 100 : 0;
  const longPct = sCount ? (sentenceLengths.filter((n) => n > 30).length / sCount) * 100 : 0;

  // Paragraph-length metrics (words per paragraph).
  const paragraphLengths = paragraphs.map((p) => tokenizeWords(p.text).length);
  const pMean = meanOf(paragraphLengths);
  const pStd = stdOf(paragraphLengths, pMean);

  // Dialogue ratio: fraction of words that fall inside double-quoted spans.
  let dialogueWords = 0;
  let m;
  DIALOGUE_SPAN_RE.lastIndex = 0;
  while ((m = DIALOGUE_SPAN_RE.exec(src)) !== null) {
    dialogueWords += tokenizeWords(m[1]).length;
  }
  const dialogueRatio = totalWords ? (dialogueWords / totalWords) * 100 : 0;

  const emDashRate = emDashDensityPer1000(src).rate;

  // Abstract-noun density per 1k words (suffix heuristic + min-stem guard).
  let abstractHits = 0;
  for (const t of tokens) {
    const w = t.lower;
    for (const suf of ABSTRACT_NOUN_SUFFIXES) {
      if (w.length >= suf.length + ABSTRACT_MIN_STEM && w.endsWith(suf)) { abstractHits += 1; break; }
    }
  }
  const abstractNounDensity = totalWords ? round1((abstractHits / totalWords) * 1000) : 0;

  // Simile density per 1k words (the two comparison frames).
  const simileHits = (src.match(SIMILE_LIKE_RE) || []).length + (src.match(SIMILE_AS_AS_RE) || []).length;
  const simileDensity = totalWords ? round1((simileHits / totalWords) * 1000) : 0;

  // Dominant sentence-opener share: the most common sentence-initial word, as a
  // fraction of sentences. High = every sentence opens the same way ("He … He …").
  const openerCounts = new Map();
  for (const toks of sentenceTokenLists) {
    const first = toks[0];
    if (!first) continue;
    openerCounts.set(first.lower, (openerCounts.get(first.lower) || 0) + 1);
  }
  let dominantOpener = 0;
  for (const c of openerCounts.values()) if (c > dominantOpener) dominantOpener = c;
  const dominantOpenerPct = sCount ? (dominantOpener / sCount) * 100 : 0;

  const metrics = {
    sentenceLenMean: round2(sMean),
    sentenceLenStd: round2(sStd),
    sentenceLenCV: sMean > 0 ? round2(sStd / sMean) : 0,
    fragmentPct: round1(fragmentPct),
    longSentencePct: round1(longPct),
    paragraphLenMean: round2(pMean),
    paragraphLenStd: round2(pStd),
    dialogueRatio: round1(dialogueRatio),
    emDashRate,
    abstractNounDensity,
    simileDensity,
    dominantOpenerPct: round1(dominantOpenerPct),
  };

  // Optional vocabulary wells — coverage per 1k words per configured category.
  for (const well of wells) {
    metrics[`well:${well.name}`] = totalWords ? round1((wellHits(tokens, well) / totalWords) * 1000) : 0;
  }

  return { words: totalWords, sentences: sCount, paragraphs: paragraphLengths.length, metrics };
}

// Split the stitched manuscript into per-issue text blocks on the `# Issue N`
// headers the manuscript stitcher emits. The header pattern intentionally mirrors
// `conflictIntensityTally` in checkInfra.js (its own local `headerRe`) — kept as a
// parallel literal here rather than a shared `/g` constant on purpose: a single
// exported `/g` regex instance carries mutable `lastIndex` state, so two `.exec`
// callers in different modules would corrupt each other's scan. If the stitcher's
// header shape ever changes, update both. Duplicate issue numbers (a
// chunk boundary that repeats a header) accumulate into ONE block so an issue
// isn't split into two thin, noisy fingerprints. Returns [] when there are no
// headers (the drift check then gates off — a single unlabelled blob can't drift
// against itself).
const ISSUE_HEADER_RE = /^#+\s*Issue\s+(\d+)\b[^\n]*$/gim;
export function splitManuscriptByIssue(manuscript) {
  const text = typeof manuscript === 'string' ? manuscript : '';
  if (!text.trim()) return [];
  const marks = [];
  let match;
  ISSUE_HEADER_RE.lastIndex = 0;
  while ((match = ISSUE_HEADER_RE.exec(text)) !== null) {
    // `headerStart` = where the `# Issue N` line begins (so the PREVIOUS issue's
    // body ends before it); `bodyStart` = just after the header line.
    marks.push({ issue: Number(match[1]), headerStart: match.index, bodyStart: ISSUE_HEADER_RE.lastIndex });
  }
  if (!marks.length) return [];
  const byIssue = new Map();
  for (let i = 0; i < marks.length; i += 1) {
    const bodyEnd = i + 1 < marks.length ? marks[i + 1].headerStart : text.length;
    const body = text.slice(marks[i].bodyStart, bodyEnd);
    byIssue.set(marks[i].issue, (byIssue.get(marks[i].issue) || '') + body);
  }
  return [...byIssue.entries()]
    .sort((a, b) => a[0] - b[0])
    .map(([issue, body]) => ({ issue, text: body }));
}

/**
 * Fingerprint every issue in a stitched manuscript. Returns
 * `{ issues: [{ issue, words, sentences, metrics }], metricKeys, wells }` sorted
 * by issue number. `metricKeys` is the full ordered key list (static metrics then
 * `well:*`), so the UI/table renders a stable column order. Pure.
 *
 * @param {string} manuscript
 * @param {{ wells?: Array<{ name: string, words: Set<string> }> }} [opts]
 */
export function voiceFingerprintMatrix(manuscript, opts = {}) {
  const wells = Array.isArray(opts.wells) ? opts.wells : [];
  const blocks = splitManuscriptByIssue(manuscript);
  const issues = blocks.map(({ issue, text }) => {
    const fp = computeFingerprint(text, { wells });
    return { issue, words: fp.words, sentences: fp.sentences, metrics: fp.metrics };
  });
  const metricKeys = [...STATIC_METRIC_KEYS, ...wells.map((w) => `well:${w.name}`)];
  return { issues, metricKeys, wells: wells.map((w) => w.name) };
}

// The three drift-baseline modes (#2179, CWQE Phase 14). Which per-metric CENTER
// each drafted issue's z-score is measured against:
//   'drafted'   — the mean of the drafted issues (default; the original behavior).
//   'exemplars' — the style guide's voice EXEMPLARS' combined fingerprint (the
//                 CHOSEN voice), so an issue is flagged for drifting from the
//                 voice the author picked, not from the average of what got
//                 drafted (which itself may all have drifted the same way).
//   'blended'   — the midpoint of the two, splitting the difference.
// The spread (σ) is ALWAYS the drafted-issue σ regardless of mode — 1–3 short
// exemplar passages can't yield a meaningful population σ, and "how much this
// series naturally varies per metric" is a property of the drafted corpus. So an
// exemplar/blended run re-centers the target, keeping the drafted spread.
export const VOICE_BASELINE_MODES = Object.freeze(['drafted', 'exemplars', 'blended']);

// A combined exemplar fingerprint needs at least this many words to be a stable
// baseline — a one-line "exemplar" is too thin to center against, so below this
// the baseline is treated as absent (the run falls back to 'drafted').
const MIN_EXEMPLAR_WORDS = 40;

// Default relative-distance threshold for the SERIES-level "uniformly off the
// chosen voice" finding (#2248): the whole drafted corpus sits at ~one value on a
// metric (σ≈0) while the exemplar/blended center sits far away. Because the metric
// vector mixes wildly different scales (dialogueRatio 0–100, sentence-length CV
// ~0.4, em-dash rate per-1k), a single ABSOLUTE gap threshold is meaningless — so
// the finding gates on a SCALE-FREE relative distance `|center − mean| /
// max(|center|, |mean|)` in [0, 1]. 0.5 means "the corpus and the chosen voice are
// at least half apart on this metric's own scale" — the dialogue-free-series-vs-
// dialogue-heavy-voice example (mean 0 vs center 30) has distance 1.0 and flags
// hard, while a small uniform offset stays quiet.
const SERIES_DRIFT_DISTANCE = 0.5;
// Absolute floor so a metric where BOTH the corpus mean and the chosen-voice
// center round to ~0 can't manufacture a large relative distance from rounding
// noise (e.g. 0.0 vs 0.1 → relative 1.0). Below this |center − mean| gap the
// series-level finding is suppressed regardless of relative distance.
const SERIES_DRIFT_MIN_GAP = 1e-6;

/**
 * Combine a style guide's voice exemplar passages into ONE fingerprint — the
 * statistical profile of the series' CHOSEN voice, used as the drift baseline in
 * `exemplars` / `blended` mode (#2179). Concatenates the passages (they are the
 * same register by construction) and fingerprints the whole, so the metric
 * profile reflects the exemplars' aggregate rhythm/diction. Pure.
 *
 * Returns `null` when there are no usable passages or the combined text is below
 * `MIN_EXEMPLAR_WORDS` (too thin to center against) — callers then fall back to
 * the drafted-mean baseline.
 *
 * @param {Array<{ passage?: string }>} voiceExemplars
 * @param {{ wells?: Array<{ name: string, words: Set<string> }> }} [opts]
 * @returns {{ metrics: Record<string, number>, words: number, passages: number } | null}
 */
export function computeExemplarBaseline(voiceExemplars, opts = {}) {
  const wells = Array.isArray(opts.wells) ? opts.wells : [];
  const passages = (Array.isArray(voiceExemplars) ? voiceExemplars : [])
    .map((e) => (typeof e?.passage === 'string' ? e.passage.trim() : ''))
    .filter(Boolean);
  if (!passages.length) return null;
  const combined = passages.join('\n\n');
  const fp = computeFingerprint(combined, { wells });
  if (fp.words < MIN_EXEMPLAR_WORDS) return null;
  return { metrics: fp.metrics, words: fp.words, passages: passages.length };
}

// Human label for a metric key (static descriptor label, or the well name).
export function metricLabel(key) {
  if (typeof key === 'string' && key.startsWith('well:')) {
    return `"${key.slice(5)}" vocabulary (per 1k words)`;
  }
  const desc = VOICE_METRICS.find((mm) => mm.key === key);
  return desc ? desc.label : key;
}

// The rendered unit suffix for a metric key (static descriptor unit, or '' for a
// well). Single source of truth so the drift outlier's `unit`, the finding text,
// and the matrix column header all agree.
export function metricUnit(key) {
  if (typeof key === 'string' && key.startsWith('well:')) return '';
  const desc = VOICE_METRICS.find((mm) => mm.key === key);
  return desc ? desc.unit : '';
}

// Directional phrase for a drift: what a value ABOVE / BELOW the series mean means
// for this metric. Wells share a generic phrasing (no static descriptor).
function directionPhrase(key, direction) {
  if (typeof key === 'string' && key.startsWith('well:')) {
    return direction === 'high'
      ? `leans harder on the "${key.slice(5)}" register`
      : `uses the "${key.slice(5)}" register less`;
  }
  const desc = VOICE_METRICS.find((mm) => mm.key === key);
  if (!desc) return direction === 'high' ? 'runs high' : 'runs low';
  return direction === 'high' ? desc.higher : desc.lower;
}

/**
 * Self-describing column descriptor for a metric key — the label, unit, and the
 * plain-language phrasing for a value that runs high vs low against the series
 * mean, plus whether it's a vocabulary well. The single source of truth for
 * rendering a fingerprint-matrix column header (server and client), built on the
 * same `metricLabel` / `directionPhrase` / `metricUnit` primitives the finding
 * text (`describeDrift`) uses — so header tooltips can't silently diverge from the
 * finding cards.
 *
 * @param {string} key
 * @returns {{ key: string, label: string, unit: string, higher: string, lower: string, isWell: boolean }}
 */
export function describeMetricColumn(key) {
  return {
    key,
    label: metricLabel(key),
    unit: metricUnit(key),
    higher: directionPhrase(key, 'high'),
    lower: directionPhrase(key, 'low'),
    isWell: typeof key === 'string' && key.startsWith('well:'),
  };
}

// One-sentence finding text for a drift outlier — names the issue, the metric,
// the issue value vs the baseline center, the σ distance, and the plain-language
// direction ("prose has gone metronomic"). The baseline label reflects which
// center the outlier was measured against (#2179): the drafted-issue mean, the
// style guide's chosen-voice exemplars, or a blend of the two — so an
// exemplar-baseline finding reads "vs the style guide's chosen voice" instead of
// implying it drifted from the average of what got drafted.
export function describeDrift(o) {
  const label = metricLabel(o.metricKey);
  const dir = directionPhrase(o.metricKey, o.direction);
  const val = `${o.value}${o.unit || ''}`;
  // `center` is the baseline value; older callers/tests that pass only `mean`
  // still work (center falls back to mean).
  const centerVal = Number.isFinite(o.center) ? o.center : o.mean;
  const center = `${round2(centerVal)}${o.unit || ''}`;
  const baselineNoun = o.baselineMode === 'exemplars'
    ? "the style guide's chosen voice"
    : (o.baselineMode === 'blended' ? "the blend of the series mean and the chosen voice" : 'the series mean');
  return `Issue ${o.issue}'s ${label} is ${val} vs ${baselineNoun} of ${center} `
    + `(${Math.abs(o.z).toFixed(1)}σ ${o.direction === 'high' ? 'above' : 'below'}) — ${dir}. `
    + 'A statistical outlier against the series voice; confirm it is an earned modulation, not drift.';
}

// One-sentence finding text for a SERIES-LEVEL drift (#2248) — the whole drafted
// corpus sits uniformly at one value on a metric (σ≈0) that is far from the CHOSEN
// voice's center, so there is no per-issue outlier to name. Reads "the whole
// series sits at X vs the chosen voice's Y — <direction phrase>", explicitly a
// corpus-wide observation, not an issue outlier. Only meaningful under an
// exemplar/blended baseline (in drafted mode center===mean, so nothing flags).
export function describeSeriesDrift(o) {
  const label = metricLabel(o.metricKey);
  const dir = directionPhrase(o.metricKey, o.direction);
  const unit = o.unit || '';
  const val = `${round2(o.mean)}${unit}`;
  const center = `${round2(o.center)}${unit}`;
  const baselineNoun = o.baselineMode === 'blended'
    ? 'the blend of the series mean and the chosen voice'
    : "the style guide's chosen voice";
  return `The whole series sits at ${val} on ${label} vs ${baselineNoun} of ${center} `
    + `— the corpus is uniformly ${o.direction === 'high' ? 'above' : 'below'} the chosen voice here (${dir}). `
    + 'Not a per-issue outlier but a series-wide register mismatch; revise toward the chosen voice across the run, '
    + 'or update the voice exemplars if this IS the voice you want.';
}

/**
 * Compute the voice-drift outliers for a stitched manuscript. Pure — returns
 * structured results the `style.voice-drift` check maps to editorial findings (so
 * the severity/config policy lives in the check, not here).
 *
 * Small-N gate: with fewer than `minIssues` issues drafted, σ is too small to be
 * meaningful, so the check gates OFF and emits nothing — `{ gatedOff: true,
 * issueCount, outliers: [] }`. The default `minIssues` is 4, not 3, because the
 * LARGEST possible population z-score for N points is √(N−1) (one issue vs the
 * rest identical): at N=3 that ceiling is √2 ≈ 1.41 — below the default 1.5σ
 * threshold, so a 3-issue series could NEVER flag drift and the check would
 * silently be a no-op. At N=4 the ceiling is √3 ≈ 1.73, so drift is reachable. An
 * explicit `minIssues: 3` is still honored (it only matters with a lower
 * `threshold` — e.g. 1.0, where √2 clears it).
 *
 * For each metric, a series mean/σ is computed across issues; a metric whose σ is
 * ~0 (every issue identical) is skipped — no drift is possible. An issue is an
 * outlier on a metric when its value is more than `threshold`·σ from the CENTER.
 * Outliers are sorted by |z| descending so the most significant drift survives a
 * downstream `maxFindings` cap.
 *
 * `opts.baselineMode` (#2179) selects what CENTER each issue is measured against:
 * `'drafted'` (default — the drafted-issue mean), `'exemplars'` (the style
 * guide's chosen-voice exemplar profile), or `'blended'` (the midpoint). In the
 * exemplar/blended modes the σ is STILL the drafted-issue σ (see
 * `VOICE_BASELINE_MODES`) — only the center shifts — so an issue is flagged for
 * drifting from the *chosen* voice rather than from the average of what got
 * drafted. When the mode asks for exemplars but `opts.voiceExemplars` yields no
 * usable baseline, the run silently falls back to `'drafted'` and reports the
 * effective mode in `baselineMode` + `exemplarBaselineUsed: false`.
 *
 * `seriesFindings` (#2248) covers the boundary the per-issue z-score model can't:
 * under an exemplar/blended baseline, when EVERY drafted issue shares the same
 * value on a metric (σ≈0) but that shared value sits far from the chosen-voice
 * center, there is no per-issue outlier — the whole corpus is uniformly
 * off-register. Each such metric emits ONE series-level finding (no `issue`),
 * gated on a scale-free relative distance ≥ `opts.seriesDistanceThreshold`.
 *
 * @param {string} manuscript
 * @param {{ threshold?: number, minIssues?: number, wells?: Array<{ name: string, words: Set<string> }>,
 *   baselineMode?: 'drafted'|'exemplars'|'blended',
 *   seriesDistanceThreshold?: number,
 *   voiceExemplars?: Array<{ passage?: string }> }} [opts]
 * @returns {{ gatedOff: boolean, issueCount: number, threshold: number,
 *   baselineMode: string, exemplarBaselineUsed: boolean,
 *   matrix: object, series: Record<string, {mean:number, std:number, center:number}>,
 *   outliers: Array<{ issue:number, metricKey:string, label:string, value:number,
 *     mean:number, center:number, std:number, z:number, direction:'high'|'low',
 *     unit:string, baselineMode:string }>,
 *   seriesFindings: Array<{ metricKey:string, label:string, mean:number, center:number,
 *     distance:number, direction:'high'|'low', unit:string, baselineMode:string }> }}
 */
export function computeVoiceDrift(manuscript, opts = {}) {
  const threshold = Number.isFinite(opts.threshold) && opts.threshold > 0 ? opts.threshold : 1.5;
  const minIssues = Number.isInteger(opts.minIssues) && opts.minIssues >= 3 ? opts.minIssues : 4;
  const seriesDistanceThreshold = Number.isFinite(opts.seriesDistanceThreshold) && opts.seriesDistanceThreshold > 0
    ? opts.seriesDistanceThreshold
    : SERIES_DRIFT_DISTANCE;
  const wells = opts.wells;
  const requestedMode = VOICE_BASELINE_MODES.includes(opts.baselineMode) ? opts.baselineMode : 'drafted';
  // Compute the exemplar baseline once (only when a non-drafted mode asked for
  // it). A thin/absent exemplar set → null → fall back to the drafted mean.
  const exemplarBaseline = requestedMode === 'drafted'
    ? null
    : computeExemplarBaseline(opts.voiceExemplars, { wells });
  const effectiveMode = exemplarBaseline ? requestedMode : 'drafted';

  const fullMatrix = voiceFingerprintMatrix(manuscript, { wells });
  // Drop empty / not-yet-drafted issue sections (a `# Issue N` header with no
  // prose behind it). Counting them would let a stub satisfy `minIssues` and
  // inject an all-zero row that pulls the series mean and flags the unwritten
  // issue as a wild outlier on every metric. Drift is computed over the drafted
  // issues only; the matrix returned is likewise restricted so renderFingerprintTable
  // agrees with the stats.
  const issues = fullMatrix.issues.filter((it) => it.words > 0 && it.sentences > 0);
  const matrix = { ...fullMatrix, issues };
  const { metricKeys } = matrix;

  const base = {
    issueCount: issues.length,
    threshold,
    baselineMode: effectiveMode,
    exemplarBaselineUsed: effectiveMode !== 'drafted',
  };

  if (issues.length < minIssues) {
    return { ...base, gatedOff: true, matrix, series: {}, outliers: [], seriesFindings: [] };
  }

  const series = {};
  const outliers = [];
  // #2248 — series-level "uniformly off the chosen voice" findings (only ever
  // populated under an active exemplar/blended baseline; see the skip-site branch).
  const seriesFindings = [];

  for (const key of metricKeys) {
    const values = issues.map((it) => it.metrics[key] ?? 0);
    const mean = meanOf(values);
    const std = stdOf(values, mean);
    // The CENTER each issue's z-score is measured against. Drafted mode centers on
    // the drafted mean; exemplars mode on the chosen-voice profile; blended on the
    // midpoint. The exemplar value for a metric the exemplars don't carry falls
    // back to the drafted mean (never NaN). The σ is always the drafted spread.
    let center = mean;
    if (exemplarBaseline) {
      const exemplarVal = exemplarBaseline.metrics[key];
      const target = Number.isFinite(exemplarVal) ? exemplarVal : mean;
      center = effectiveMode === 'blended' ? (mean + target) / 2 : target;
    }
    series[key] = { mean: round2(mean), std: round2(std), center: round2(center) };
    // A metric with no drafted spread can't have a per-issue OUTLIER — and dividing
    // by ~0 σ would manufacture infinite z-scores — so skip the per-issue pass.
    // But (#2248) under an exemplar/blended baseline this σ≈0 case is exactly the
    // "uniformly off the chosen voice" boundary: every drafted issue shares the
    // SAME value on a metric, yet that shared value can sit far from the
    // chosen-voice center (e.g. a dialogue-free series vs a dialogue-heavy voice).
    // There's no per-issue outlier, but the whole corpus is off-register — so emit
    // ONE series-level finding (a different shape: no `issue`), gated on a
    // scale-free relative distance so it works across the metric vector's very
    // different scales. Drafted mode never trips this (center === mean → gap 0).
    // The common case the #2179 feature targets is untouched: issues that drifted
    // the same DIRECTION still have natural per-metric variance (σ>0), so they flag
    // per-issue below against the chosen-voice center.
    if (std < 1e-9) {
      if (exemplarBaseline) {
        const gap = Math.abs(center - mean);
        const denom = Math.max(Math.abs(center), Math.abs(mean));
        const distance = denom > 0 ? gap / denom : 0;
        if (gap >= SERIES_DRIFT_MIN_GAP && distance >= seriesDistanceThreshold) {
          seriesFindings.push({
            metricKey: key,
            label: metricLabel(key),
            mean,
            center,
            distance,
            direction: mean > center ? 'high' : 'low',
            unit: metricUnit(key),
            baselineMode: effectiveMode,
          });
        }
      }
      continue;
    }
    for (const it of issues) {
      const value = it.metrics[key] ?? 0;
      const z = (value - center) / std;
      if (Math.abs(z) <= threshold) continue;
      outliers.push({
        issue: it.issue,
        metricKey: key,
        label: metricLabel(key),
        value,
        mean,
        center,
        std,
        z,
        direction: z > 0 ? 'high' : 'low',
        unit: metricUnit(key),
        baselineMode: effectiveMode,
      });
    }
  }

  outliers.sort((a, b) => Math.abs(b.z) - Math.abs(a.z));
  // Most-off-register first, so a downstream cap keeps the worst mismatches.
  seriesFindings.sort((a, b) => b.distance - a.distance);
  return { ...base, gatedOff: false, matrix, series, outliers, seriesFindings };
}

/**
 * Render a fingerprint matrix as a plain-text aligned table (issues as rows,
 * metrics as columns, outlier cells marked with `*`). Used for debug/logging and
 * covered by tests; the interactive UI table is a separate surface. Returns '' for
 * an empty matrix.
 *
 * @param {ReturnType<typeof computeVoiceDrift>} drift
 */
export function renderFingerprintTable(drift) {
  if (!drift || !drift.matrix || !drift.matrix.issues.length) return '';
  const { matrix, series } = drift;
  const keys = matrix.metricKeys;
  const outlierSet = new Set((drift.outliers || []).map((o) => `${o.issue}:${o.metricKey}`));
  const header = ['issue', ...keys.map(metricLabel)];
  const rows = matrix.issues.map((it) => [
    `#${it.issue}`,
    ...keys.map((k) => {
      const v = it.metrics[k] ?? 0;
      return outlierSet.has(`${it.issue}:${k}`) ? `${v}*` : `${v}`;
    }),
  ]);
  if (series && Object.keys(series).length) {
    rows.push(['mean', ...keys.map((k) => `${series[k]?.mean ?? 0}`)]);
    rows.push(['σ', ...keys.map((k) => `${series[k]?.std ?? 0}`)]);
    // When drift was measured against a non-drafted baseline (exemplars/blended),
    // the flagged cells sit against `center`, not `mean` — surface it as its own
    // row so the starred outliers are readable against the actual baseline.
    if (drift.exemplarBaselineUsed) {
      const label = drift.baselineMode === 'blended' ? 'blend' : 'voice';
      rows.push([label, ...keys.map((k) => `${series[k]?.center ?? series[k]?.mean ?? 0}`)]);
    }
  }
  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i]).length)));
  const fmt = (cells) => cells.map((c, i) => String(c).padEnd(widths[i])).join('  ').trimEnd();
  return [fmt(header), ...rows.map(fmt)].join('\n');
}