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

78.7 KB
Raw Blame
/**
 * Pipeline — Foundation-quality judge + fix router (CWQE Phase 11, #2176).
 *
 * The "correct it up-front, not in editor mode" mechanism for autonomous runs.
 * Before Series Autopilot drafts a single issue, it judges the FOUNDATION as a
 * whole — universe canon (worldbuilding) + character records + the series
 * arc/seasons (structure) + declared voice/style (craft) — against a weighted
 * rubric mirroring the Phase 10 craft doctrine (#2175):
 *
 *     worldbuilding 40% · character 30% · structure 20% · craft 10%
 *
 * The judge runs on the writer/judge split resolved by `resolveJudgeForStage()`
 * (#2167) off the `pipeline-arc-overview` writer stage — the model that scores
 * the foundation is deliberately different from the one that generated it. It
 * returns a per-dimension `{ score, gap, fix }` and a weighted composite the
 * autopilot gate spends: proceed once the weighted score clears a configurable
 * threshold AND every dimension clears its floor; otherwise the bounded improve loop (in
 * seriesAutopilot.js `runFoundationGate`) targets the largest weighted deficit, applies
 * the fix through the OWNING service (never a raw write, `force:false`
 * everywhere), and re-judges.
 *
 * Fast-pass / skip: the judged inputs (canon + character records + full
 * synopsis plan + character arcs + series voice) are
 * content-hashed and pinned on the snapshot, so a re-judge of an UNCHANGED
 * foundation returns the cached verdict with no LLM call — an already-clean
 * foundation re-reached after unrelated steps cannot loop (mirrors
 * editorialAnalysis.js / pipelineJudge.js staleness). Snapshots persist at
 * `data/pipeline-foundation-judge/{seriesId}.json`.
 *
 * AI-provider policy: this fires ONLY from the already-consented Series
 * Autopilot (or an explicit user action) — never at boot.
 *
 * Errors bubble (no try/catch) except the single deliberate malformed-JSON retry
 * in `runFoundationJudgeStage` — LLM judges intermittently emit prose-wrapped or
 * truncated JSON, and one stricter retry salvages most of them.
 */

import { join } from 'path';
import { assertValidSeriesId } from '../../lib/pipelineIds.js';
import { SERIES_AUTOPILOT_DEFAULTS } from '../../lib/seriesAutopilotDefaults.js';
import { PATHS, atomicWrite, ensureDir, tryReadFile, safeJSONParse } from '../../lib/fileUtils.js';
import { runStagedLLM, resolveStageContext, resolveJudgeForStage } from '../stageRunner.js';
import { manuscriptContentBudgetChars, estimateTokens } from '../../lib/contextBudget.js';
import { getStage } from '../promptService.js';
import { composeStyleNotes, sanitizeStyleGuide, STYLE_GUIDE_LIMITS } from '../../lib/styleGuide.js';
import { sanitizeCharacterArcList } from '../../lib/seriesCharacterArc.js';
import { BIBLE_KEYS, BIBLE_SOURCE, normalizeBibleName, sanitizeCharacter } from '../../lib/storyBible.js';
import { getUniverse, updateUniverse } from '../universeBuilder.js';
import { isBlankString, isBlankArray } from '../universeCharacterExpand.js';
import { expandWorldTemplate, narrativeRepairTargets } from '../universeBuilderExpand.js';
import { getSeries, updateSeries } from './series.js';
import { listIssues } from './issues.js';
import { getSeriesCanon } from './seriesCanon.js';
import {
  resolveVerifyIssues,
  resolvedEpisodeEdits,
  restoreArcState,
  snapshotArcState,
  verifyArc,
} from './arcPlanner.js';
import { createArcMutationLedger } from './arcMutationLedger.js';
import {
  FRAMEWORK_STRING_FIELDS,
  PROFILE_STRING_FIELDS,
  VISUAL_FOUNDATION_LIST_FIELDS,
  VISUAL_FOUNDATION_STRING_FIELDS,
  buildFoundationContext,
  contentHash,
  countFoundationCharacterBlanks,
  countSeriesCastIntegrityFindings,
  foundationInputs,
  foundationInputsHash,
  pickFrameworkFields,
  pickVisualFoundationFields,
  rankFoundationCharacters,
  renderArc,
  renderCharacterLine,
  renderWorldFoundation,
  repairableSeriesFoundationCharacters,
  seriesFoundationCharacters,
} from './foundationJudgeContext.js';
import { repairOversizedCharacter } from './foundationCharacterOverflow.js';
import { escapeRegExp, trimTo, isNonBlankStr } from '../../lib/textUtils.js';

// Compatibility surface: callers keep importing these projection helpers from
// foundationJudge.js while their implementation lives with the context builder.
export {
  countFoundationCharacterBlanks,
  countSeriesCastIntegrityFindings,
  foundationInputs,
  foundationInputsHash,
  rankFoundationCharacters,
  seriesFoundationCharacters,
};

const STAGE = 'pipeline-judge-foundation';
const REPAIR_STAGE = 'pipeline-foundation-repair';
const CHARACTER_FOUNDATION_STAGE = 'pipeline-character-foundation';
// The writer stage whose judgeProvider/judgeModel pin drives the writer/judge
// split — the arc overview is the foundation's authoring pass. Mirrors
// pipelineJudge.js's WRITER_STAGE_TEMPLATE indirection (kept local + stable).
const WRITER_STAGE = 'pipeline-arc-overview';

// The four rubric dimensions and their weights — the single source of truth for
// the weighted composite, the fix router, sanitize, and client rendering.
// Order is display order. Weights sum to 1.0 (asserted at module load).
export const FOUNDATION_DIMENSIONS = Object.freeze(['worldbuilding', 'character', 'structure', 'craft']);
const MAX_STRUCTURE_CORRECTION_PASSES = 3;
export const FOUNDATION_WEIGHTS = Object.freeze({
  worldbuilding: 0.4,
  character: 0.3,
  structure: 0.2,
  craft: 0.1,
});
// Fail fast if a future edit unbalances the rubric — a weighted score is only
// meaningful when the weights sum to 1.
const WEIGHT_SUM = FOUNDATION_DIMENSIONS.reduce((n, d) => n + FOUNDATION_WEIGHTS[d], 0);
if (Math.abs(WEIGHT_SUM - 1) > 1e-9) {
  throw new Error(`foundationJudge: FOUNDATION_WEIGHTS must sum to 1 (got ${WEIGHT_SUM})`);
}

// Default gate threshold — the weighted [0,10] score the foundation must clear
// before drafting. Mirrors autonovel's 7.5 foundation bar (design record
// Phase 11). Overridable per-run + via the persisted setting.
export const DEFAULT_FOUNDATION_THRESHOLD = SERIES_AUTOPILOT_DEFAULTS.foundationThreshold;
// A strong weighted world score must not hide a critically thin character or
// craft foundation. The floor follows an intentionally lowered run threshold,
// but otherwise keeps every dimension at a publishable planning baseline.
export const DEFAULT_FOUNDATION_DIMENSION_FLOOR = 6;

// Defensive caps on LLM output — never trust raw model JSON.
const GAP_MAX = 600;
const FIX_MAX = 600;
const SUMMARY_MAX = 600;
const JUDGE_OUTPUT_RESERVE_TOKENS = 2_000;

const nowIso = () => new Date().toISOString();

const ARC_BLOCKER_SEVERITIES = Object.freeze(['high', 'medium', 'low']);

function arcBlockerProfile(findings) {
  const list = Array.isArray(findings) ? findings : [];
  const profile = Object.fromEntries(ARC_BLOCKER_SEVERITIES.map((severity) => [severity, 0]));
  for (const finding of list) {
    const severity = ARC_BLOCKER_SEVERITIES.includes(finding?.severity) ? finding.severity : 'medium';
    profile[severity] += 1;
  }
  return { ...profile, total: list.length };
}

// Negative means `left` is the safer checkpoint. A smaller high-severity count
// outranks raw total: six polish findings are preferable to four findings that
// still include a broken authorization or climax. Medium, low, then total break
// ties. This is deliberately lexicographic rather than a weighted sum so no
// number of low findings can conceal one unresolved high blocker.
function compareArcBlockers(left, right) {
  const a = arcBlockerProfile(left);
  const b = arcBlockerProfile(right);
  for (const key of [...ARC_BLOCKER_SEVERITIES, 'total']) {
    if (a[key] !== b[key]) return a[key] - b[key];
  }
  return 0;
}

function formatArcBlockerProfile(findings) {
  const profile = arcBlockerProfile(findings);
  return `${profile.total} blocker(s): ${profile.high} high, ${profile.medium} medium, ${profile.low} low`;
}

const foundationDir = () => join(PATHS.data, 'pipeline-foundation-judge');
const snapshotPath = (seriesId) => join(foundationDir(), `${seriesId}.json`);

// ---------- weighted composite math ----------

const clampScore = (v, fallback = 0) => {
  const n = Number(v);
  if (!Number.isFinite(n)) return fallback;
  return Math.max(0, Math.min(10, Math.round(n * 100) / 100));
};

/**
 * The weighted [0,10] composite — Σ dimension.score × weight. A missing/invalid
 * dimension contributes 0 for its term (never NaN-poisons the score). Pure +
 * unit-tested; the autopilot gate compares this against the threshold.
 */
export function computeWeightedScore(dimensions) {
  const dims = dimensions && typeof dimensions === 'object' ? dimensions : {};
  let total = 0;
  for (const d of FOUNDATION_DIMENSIONS) {
    const score = Number(dims[d]?.score);
    total += (Number.isFinite(score) ? score : 0) * FOUNDATION_WEIGHTS[d];
  }
  return Math.round(total * 100) / 100;
}

/**
 * Largest weighted distance from a perfect rubric score, retained for snapshot
 * diagnostics: `weight × (10 − score)`. Gate repair selection instead uses
 * foundationFixTarget with the requested threshold. Ties break toward the lower raw score, then rubric order.
 * (Fixing a high-weight low-score dimension first is what converges the gate;
 * "weakest" by bare score would waste rounds polishing a 10%-weight craft nit
 * while a thin 40%-weight world drags the composite down.) Pure + unit-tested.
 * Returns `{ dimension, score, deficit }`, or null when no dimension is present.
 */
export function weakestDimension(dimensions) {
  const dims = dimensions && typeof dimensions === 'object' ? dimensions : {};
  let best = null;
  for (const d of FOUNDATION_DIMENSIONS) {
    if (!dims[d]) continue;
    const score = clampScore(dims[d].score);
    const deficit = Math.round(FOUNDATION_WEIGHTS[d] * (10 - score) * 100) / 100;
    if (
      best === null
      || deficit > best.deficit
      || (deficit === best.deficit && score < best.score)
    ) {
      best = { dimension: d, score, deficit };
    }
  }
  return best;
}

export function foundationGateStatus(dimensions, weightedScore, threshold = DEFAULT_FOUNDATION_THRESHOLD) {
  const dimensionFloor = Math.min(
    Number.isFinite(threshold) ? threshold : DEFAULT_FOUNDATION_THRESHOLD,
    DEFAULT_FOUNDATION_DIMENSION_FLOOR,
  );
  const failingDimensions = FOUNDATION_DIMENSIONS
    .filter((dimension) => clampScore(dimensions?.[dimension]?.score) < dimensionFloor);
  return {
    dimensionFloor,
    failingDimensions,
    passes: Number(weightedScore) >= threshold && failingDimensions.length === 0,
  };
}

export function foundationFixTarget(dimensions, threshold = DEFAULT_FOUNDATION_THRESHOLD) {
  const { dimensionFloor, failingDimensions } = foundationGateStatus(dimensions, 0, threshold);
  if (failingDimensions.length === 0) {
    const target = Number.isFinite(threshold) ? threshold : DEFAULT_FOUNDATION_THRESHOLD;
    // Repair the shortfall that keeps this run below its requested bar. Using
    // distance from 10 sent a 7.8/8 foundation back to worldbuilding (already 8)
    // while its only deficient dimension, structure (7), remained untouched.
    const belowTarget = FOUNDATION_DIMENSIONS
      .filter((dimension) => dimensions?.[dimension] && clampScore(dimensions[dimension].score) < target)
      .map((dimension) => ({
        dimension,
        score: clampScore(dimensions[dimension].score),
        deficit: Math.round(FOUNDATION_WEIGHTS[dimension] * (target - clampScore(dimensions[dimension].score)) * 100) / 100,
      }))
      .sort((a, b) => b.deficit - a.deficit || a.score - b.score
        || FOUNDATION_DIMENSIONS.indexOf(a.dimension) - FOUNDATION_DIMENSIONS.indexOf(b.dimension));
    return belowTarget[0] || weakestDimension(dimensions);
  }
  return failingDimensions
    .map((dimension) => ({
      dimension,
      score: clampScore(dimensions?.[dimension]?.score),
      deficit: Math.round((dimensionFloor - clampScore(dimensions?.[dimension]?.score)) * 100) / 100,
    }))
    .sort((a, b) => a.score - b.score
      || FOUNDATION_DIMENSIONS.indexOf(a.dimension) - FOUNDATION_DIMENSIONS.indexOf(b.dimension))[0];
}

// ---------- sanitize LLM output ----------

function sanitizeDimension(raw) {
  const d = raw && typeof raw === 'object' ? raw : {};
  return {
    score: clampScore(d.score),
    gap: trimTo(d.gap, GAP_MAX),
    fix: trimTo(d.fix, FIX_MAX),
  };
}

const PLACEHOLDER_FINDING = /^(?:string|placeholder|todo|tbd|n\/?a|none|null|undefined)$/i;
const isMeaningfulFinding = (value) => (
  typeof value === 'string'
  && value.trim().length > 0
  && !PLACEHOLDER_FINDING.test(value.trim())
);

// A judge response is "valid-shaped" only when every rubric dimension contains
// a usable score plus concrete gap/fix prose. The prompt itself includes a JSON
// shape example whose values are `{ score: 6, gap: "string", fix: "string" }`;
// if a TUI screen scrape ever leaks through, a permissive dimensions-only check
// would mistake that echoed contract for a real verdict and spend a repair round
// on the literal instruction "string". Reject incomplete and placeholder
// rubrics so the deliberate retry (and ultimately the caller) handles them as
// malformed output instead of persisting fabricated editorial evidence.
export function isValidFoundationShape(content) {
  if (!(content && typeof content === 'object'
    && content.dimensions && typeof content.dimensions === 'object')) return false;
  if (!FOUNDATION_DIMENSIONS.every((dimension) => {
    const finding = content.dimensions[dimension];
    const score = Number(finding?.score);
    return finding && typeof finding === 'object'
      && Number.isFinite(score) && score >= 1 && score <= 10
      && isMeaningfulFinding(finding.gap)
      && isMeaningfulFinding(finding.fix);
  })) return false;
  return content.oneLineVerdict === undefined || isMeaningfulFinding(content.oneLineVerdict);
}

export function sanitizeFoundationJudge(parsed) {
  const p = parsed && typeof parsed === 'object' ? parsed : {};
  const rawDims = p.dimensions && typeof p.dimensions === 'object' ? p.dimensions : {};
  const dimensions = {};
  for (const key of FOUNDATION_DIMENSIONS) dimensions[key] = sanitizeDimension(rawDims[key]);
  return {
    dimensions,
    weightedScore: computeWeightedScore(dimensions),
    oneLineVerdict: trimTo(p.oneLineVerdict, SUMMARY_MAX),
  };
}

// The per-dimension findings carried into a pause's `residual` for human review
// — same `{ severity, location, problem, suggestion }` shape the arc/editorial
// gates use, so the existing pause UI renders foundation findings unchanged.
export function residualFindings(dimensions) {
  const dims = dimensions && typeof dimensions === 'object' ? dimensions : {};
  return FOUNDATION_DIMENSIONS
    .filter((d) => dims[d])
    .map((d) => ({
      severity: 'high',
      location: `${d} (weight ${Math.round(FOUNDATION_WEIGHTS[d] * 100)}%, scored ${clampScore(dims[d].score)})`,
      problem: dims[d].gap || `${d} is below the foundation-quality bar`,
      suggestion: dims[d].fix || '',
    }));
}

// ---------- storage ----------

async function loadSnapshot(seriesId) {
  const content = await tryReadFile(snapshotPath(seriesId));
  if (content === null) return null;
  const parsed = safeJSONParse(content, null, { allowArray: false, logError: true, context: snapshotPath(seriesId) });
  // `allowArray: false` only rejects a root array — a bare JSON scalar
  // (corrupted snapshot) still parses, and callers spread this into a
  // response object, so guard for a genuine object here.
  return parsed && typeof parsed === 'object' ? parsed : null;
}

async function saveSnapshot(snapshot) {
  await ensureDir(foundationDir());
  await atomicWrite(snapshotPath(snapshot.seriesId), snapshot);
}

// Staleness: a complete snapshot is stale when the current foundation inputs no
// longer match the pinned hash (mirrors pipelineJudge.js). A legacy snapshot
// with no hash is treated as not-stale (can't tell).
export function isFoundationStale(snap, currentHash) {
  if (!snap || snap.status !== 'complete') return false;
  if (!snap.sourceInputsHash) return false;
  return snap.sourceInputsHash !== currentHash;
}

// ---------- context record reads ----------

/**
 * The two objective, LLM-free measures of a `character` repair's work, read off
 * live records. Pass `charactersOverride` to measure a checkpoint's cast (the
 * pre-repair snapshot) against the same series/issue roster the live read uses,
 * so only the cast CONTENT differs between a before and an after.
 *
 * - `blanks` — named framework/profile/visual fields that are empty across the
 *   repairable roster. Holds every character to one field list.
 * - `integrityFindings` — deterministic cast-integrity gaps (#6415), which
 *   apply a per-character depth (a declared minor role or an author-explained
 *   unknown owes less) and are the only measure that reaches the psychology
 *   profile at all.
 *
 * Both are facts on disk. Neither subsumes the other: a visual-identity pass
 * moves only `blanks`, and authoring a theory of control moves only
 * `integrityFindings`.
 */
export async function readFoundationCharacterProgress(seriesId, charactersOverride = null) {
  assertValidSeriesId(seriesId);
  const series = await getSeries(seriesId);
  const [universe, issues] = await Promise.all([
    series?.universeId ? getUniverse(series.universeId).catch(() => null) : null,
    listIssues({ seriesId }),
  ]);
  const characters = Array.isArray(charactersOverride) ? charactersOverride : universe?.characters;
  return {
    blanks: countFoundationCharacterBlanks(characters, series, issues),
    integrityFindings: countSeriesCastIntegrityFindings(characters, series, issues),
  };
}

// One deliberate malformed-JSON retry (see module doc). Mirrors pipelineJudge.js.
async function runFoundationJudgeStage(ctx, runOptions) {
  let lastError;
  for (let attempt = 0; attempt < 2; attempt += 1) {
    try {
      const result = await runStagedLLM(STAGE, ctx, runOptions);
      if (isValidFoundationShape(result.content)) return result;
      lastError = new Error('foundation judge response parsed but its rubric is incomplete or contains placeholders');
    } catch (err) {
      lastError = err;
    }
  }
  throw lastError;
}

// ---------- judge ----------

/**
 * Judge a series' foundation. Returns the stored snapshot, or a cached snapshot
 * when the inputs are unchanged and `!force` (the fast-pass that stops the gate
 * looping on an already-clean foundation).
 *
 * @param {string} seriesId
 * @param {object} [opts]
 * @param {string} [opts.providerId]  explicit judge provider override
 * @param {string} [opts.model]       explicit judge model override
 * @param {string} [opts.effort]      run-level reasoning effort (soft — a per-stage
 *                                   `effort` pin still wins, #3641)
 * @param {string} [opts.providerDefault] soft run-level judge provider; stage pin wins
 * @param {string} [opts.modelDefault] soft run-level judge model; explicit stage model wins
 * @param {string} [opts.effortDefault] soft run-level judge effort; stage pin wins
 * @param {boolean} [opts.force]      re-judge unchanged inputs
 */
export async function judgeFoundation(seriesId, {
  providerId,
  model,
  effort,
  providerDefault,
  modelDefault,
  effortDefault,
  onRunCreated,
  onRunSettled,
  force = false,
} = {}) {
  assertValidSeriesId(seriesId);
  const series = await getSeries(seriesId);
  const [universe, issues] = await Promise.all([
    series?.universeId ? getUniverse(series.universeId).catch(() => null) : null,
    listIssues({ seriesId }),
  ]);
  const hash = foundationInputsHash(series, universe, issues);

  const existing = await loadSnapshot(seriesId);
  // Cache only a verdict that still satisfies the current rubric contract.
  // This also self-heals snapshots written by an older permissive validator
  // from echoed prompt examples (`gap: "string"`): unchanged story inputs must
  // not make fabricated editorial evidence immortal across restarts/resumes.
  if (!force
    && existing
    && existing.status === 'complete'
    && existing.sourceInputsHash === hash
    && isValidFoundationShape(existing)) {
    return { ...existing, cached: true };
  }

  const canon = await getSeriesCanon(series);

  // Writer/judge split: resolve the judge provider/model from the arc-overview
  // writer stage's config (judgeProvider/judgeModel), honoring a route override.
  const writerStage = getStage(WRITER_STAGE);
  const { provider: judgeProvider, model: judgeModel } = await resolveJudgeForStage(writerStage, {
    providerOverride: providerId,
    modelOverride: model,
    providerDefault,
    modelDefault,
  });

  // Budget content to the judge model's window (#1488).
  const { contextWindow } = await resolveStageContext(STAGE, {
    providerOverride: judgeProvider.id,
    modelOverride: judgeModel,
  });
  const overheadTokens = 2_000 + estimateTokens(composeStyleNotes(series, { proseCraft: true }));
  const contentMax = manuscriptContentBudgetChars({
    contextWindow,
    overheadTokens,
    outputReserveTokens: JUDGE_OUTPUT_RESERVE_TOKENS,
  });

  const ctx = buildFoundationContext({ series, universe, canon, issues, contentMax });
  const result = await runFoundationJudgeStage(ctx, {
    returnsJson: true,
    providerOverride: judgeProvider.id,
    modelOverride: judgeModel,
    effortDefault: effort || effortDefault,
    onRunCreated,
    onRunSettled,
    source: STAGE,
  });

  const judge = sanitizeFoundationJudge(result.content);
  const weak = weakestDimension(judge.dimensions);
  const snapshot = {
    seriesId,
    universeId: series?.universeId || null,
    status: 'complete',
    sourceInputsHash: hash,
    providerId: result.providerId,
    model: result.model,
    judgeProviderId: judgeProvider.id,
    judgeModel: judgeModel || null,
    runId: result.runId,
    createdAt: existing?.createdAt || nowIso(),
    completedAt: nowIso(),
    weakest: weak ? weak.dimension : null,
    ...judge,
  };
  await saveSnapshot(snapshot);
  const actualProviderId = result.providerId || judgeProvider.id;
  const actualModel = result.model || judgeModel || '(default)';
  console.log(`🏛️ foundation judge — series=${seriesId.slice(0, 12)} weighted=${judge.weightedScore} target=${weak?.dimension || '—'}(${weak?.score ?? '—'}) via ${actualProviderId}/${actualModel}`);
  return snapshot;
}

/**
 * Load a series' stored foundation verdict with a `stale` flag. Returns null when
 * never judged.
 */
export async function getFoundationJudge(seriesId) {
  assertValidSeriesId(seriesId);
  const snap = await loadSnapshot(seriesId);
  if (!snap) return null;
  const series = await getSeries(seriesId).catch(() => null);
  const [universe, issues] = await Promise.all([
    series?.universeId ? getUniverse(series.universeId).catch(() => null) : null,
    series ? listIssues({ seriesId }).catch(() => null) : null,
  ]);
  const hash = series && issues ? foundationInputsHash(series, universe, issues) : null;
  return { ...snap, stale: hash ? isFoundationStale(snap, hash) : true };
}

// ---------- fix router (dimension → owning service) ----------

// The thinnest unlocked character to expand for a `character`-dimension fix: the
// one missing the MOST framework fields (most leverage), skipping locked
// records (locked entries are constraints, not fix targets). Pure — takes the
// canon character list, returns the entry id or null.
export function thinnestCharacter(characters) {
  const list = Array.isArray(characters) ? characters : [];
  let best = null;
  for (const c of list) {
    if (!c || c.locked === true) continue;
    const blanks = FRAMEWORK_STRING_FIELDS.filter((f) => isBlankString(c[f])).length
      + PROFILE_STRING_FIELDS.filter((field) => isBlankString(c[field])).length
      + (isBlankArray(c.secrets) ? 1 : 0)
      + VISUAL_FOUNDATION_STRING_FIELDS.filter((field) => isBlankString(c[field])).length
      + VISUAL_FOUNDATION_LIST_FIELDS.filter((field) => isBlankArray(c[field])).length;
    if (blanks === 0) continue;
    if (best === null || blanks > best.blanks) best = { id: c.id, blanks };
  }
  return best ? best.id : null;
}

const REPAIRABLE_CHARACTER_FIELDS = Object.freeze([
  ...FRAMEWORK_STRING_FIELDS,
  ...PROFILE_STRING_FIELDS,
  ...VISUAL_FOUNDATION_STRING_FIELDS,
  ...VISUAL_FOUNDATION_LIST_FIELDS,
  'arcType',
  'secrets',
  // Optional structured psychology (#6414). Allowlisted so a repair proposal
  // that authors one is applied rather than silently dropped; it is NOT part
  // of `hasCompleteFramework` below, so its absence never by itself makes an
  // existing cast read as incomplete and schedule a repair run.
  'psychology',
  'personality',
  'background',
  'relationships',
  'postureNotes',
  'specialTraits',
  'stats',
  'props',
  'expressions',
  'handGestures',
  'wardrobes',
]);

const MAX_FOUNDATION_NEW_CHARACTERS = 3;
// Exhaustive, not restrictive: large casts are split across as many sequential
// calls as necessary so every story-referenced character gets authored without
// asking one response to carry an unbounded amount of JSON. Each batch sees the
// full ensemble map for differentiation and relationship continuity.
const CHARACTER_FOUNDATION_BATCH_SIZE = 6;

// How much of the synopsis-level plan a repair prompt may carry. The judge
// prompt this mirrors has always been budgeted (`buildFoundationContext` caps
// each section at a third of the model's usable input); repair alone sent the
// whole plan raw, so its prompt grew with every episode the series gained. On a
// long-running series that section reached 28KB of a 35KB prompt and BOTH the
// primary and the fallback TUI provider burned their full 10-minute timeout on
// it without emitting a response — which errored the entire autonomous run.
// ~12K chars (~3K tokens) keeps the arc spine plus the early episodes a
// character arc's transitions hang off, and still fits alongside the rest of the
// prompt inside a small local model's window. A fixed cap rather than a
// window-derived one on purpose: the binding constraint here is how much
// material a reasoning model will chew through before the wall clock runs out,
// not how much its context can hold.
const REPAIR_OUTLINE_MAX_CHARS = 12_000;

// The outline cap above only ever bound ONE of the repair prompt's three large
// sections. A real character-foundation run built a 72KB prompt — 35KB of raw
// series seed, 18KB of outline, 15KB of candidate cast — and burned a CLI
// runner's full wall clock without emitting a byte. Each section now carries its
// own budget so the total lands near 40K chars, which the stage demonstrably
// completes within. Same reasoning as the outline cap: fixed rather than
// window-derived, because the binding constraint is how much material a
// reasoning model chews through before the clock runs out, not context size.
const REPAIR_SERIES_MAX_CHARS = 12_000;
const REPAIR_CHARACTERS_MAX_CHARS = 12_000;

// The character-foundation stage reasons over the whole ensemble at once, so it
// is the slowest repair stage by a wide margin. Ten minutes proved short enough
// to kill productive high-effort work, and a fixed two-hour ceiling still cuts
// off a healthy provider solely because the ensemble is large. Match the
// quality-first ceiling used by the pipeline's other long-form editorial calls;
// provider cancellation remains available for a truly hung run.
const CHARACTER_FOUNDATION_TIMEOUT_MS = 43_200_000;

const CRAFT_REPAIR_MAX_ATTEMPTS = 2;

// A repair prompt's JSON sections shed the least load-bearing material first,
// then trim the free-text fields that remain, so the payload stays VALID JSON at
// every tier — a mid-object slice would hand the model a parse error instead of
// a smaller brief. That is the one way these differ from `renderArc`, which is
// plain text and hard-clamps: below the JSON skeleton's own size (a few hundred
// chars of keys and notes) these renderers overshoot the budget rather than
// emitting something unparseable. The real budgets are 12,000.
const JSON_TRUNCATION_MARK = '… [truncated to fit the prompt budget]';
function fitJsonToBudget(payload, trimKeys, maxChars) {
  const shrunk = { ...payload };
  let rendered = JSON.stringify(shrunk, null, 2);
  while (rendered.length > maxChars) {
    const key = trimKeys
      .filter((candidate) => typeof shrunk[candidate] === 'string' && shrunk[candidate].length > 0)
      .sort((a, b) => shrunk[b].length - shrunk[a].length)[0];
    // Nothing left that is safe to trim (structural ids/counts only) — return the
    // smallest valid JSON we can build rather than corrupting it with a slice.
    if (!key) return rendered;
    const keep = Math.max(0, shrunk[key].length - Math.max(rendered.length - maxChars, 1) - JSON_TRUNCATION_MARK.length);
    shrunk[key] = keep > 0 ? `${shrunk[key].slice(0, keep)}${JSON_TRUNCATION_MARK}` : '';
    rendered = JSON.stringify(shrunk, null, 2);
  }
  return rendered;
}

// Drop the style guide's exemplars first — they are craft-dimension material and
// tell a character or world repair nothing — then flatten the authored character
// arcs to their want/need spine, which the outline section already renders in
// full. `premise` / `targetFormat` / `issueCountTarget` / `styleNotes` are the
// brief itself and stay unconditional.
function renderRepairSeriesJson(series, maxChars = REPAIR_SERIES_MAX_CHARS) {
  const base = {
    id: series?.id,
    name: series?.name,
    premise: series?.premise,
    targetFormat: series?.targetFormat,
    issueCountTarget: series?.issueCountTarget,
    styleNotes: series?.styleNotes,
  };
  const arcs = Array.isArray(series?.characterArcs) ? series.characterArcs : [];
  const trimKeys = ['styleNotes', 'premise'];
  const tiers = [
    { ...base, styleGuide: series?.styleGuide, characterArcs: series?.characterArcs },
    {
      ...base,
      characterArcs: series?.characterArcs,
      omitted: 'styleGuide (craft exemplars) omitted to fit the prompt budget',
    },
    {
      ...base,
      characterArcs: arcs.map((arc) => ({
        characterId: arc?.characterId,
        characterName: arc?.characterName,
        want: arc?.want,
        need: arc?.need,
      })),
      omitted: 'styleGuide and character-arc detail omitted to fit the prompt budget; see the outline section',
    },
    // The arcs are named in full in the outline section, so the last structural
    // tier keeps only their count — after this only the brief's own free text is
    // left, which `fitJsonToBudget` can trim.
    {
      ...base,
      characterArcCount: arcs.length,
      omitted: 'styleGuide and every character arc omitted to fit the prompt budget; see the outline section',
    },
  ];
  for (const tier of tiers) {
    const rendered = JSON.stringify(tier, null, 2);
    if (rendered.length <= maxChars) return rendered;
  }
  return fitJsonToBudget(tiers.at(-1), trimKeys, maxChars);
}

// The full-ensemble roster is the unbounded half of the character payload:
// `CHARACTER_FOUNDATION_BATCH_SIZE` bounds `targetCharacters`, but
// `fullSeriesRoster` carries every cast member with every framework field, so it
// grows with the series. Compact the roster to the narrative and visual
// differentiation spine before dropping members — the roster exists so the
// batch can differentiate relationships, motives, and render identities.
const compactRosterCharacter = (character) => ({
  id: character?.id,
  name: character?.name,
  role: character?.role,
  want: character?.want || '',
  need: character?.need || '',
  physicalDescription: character?.physicalDescription || '',
  visualIdentity: character?.visualIdentity || '',
});

// `CHARACTER_FOUNDATION_BATCH_SIZE` bounds how MANY characters a batch carries,
// not how large each one is — six characters with long personality/background/
// relationship prose still run to tens of KB. So the last tier caps every string
// field on the batch itself, halving the cap until the payload fits.
// An explicit ladder rather than a halving loop: a loop guarded on `>= floor`
// steps 1_200 → … → 75 → 37 and exits WITHOUT ever trying the floor itself.
const CHARACTER_FIELD_CAPS = Object.freeze([1_200, 600, 300, 150, 75, 40]);
const truncateField = (value, cap) => {
  if (typeof value !== 'string' || value.length <= cap) return value;
  // Below the marker's own length the marker would be the longer string — slice
  // bare rather than "truncating" a field into a longer one.
  if (cap <= JSON_TRUNCATION_MARK.length) return value.slice(0, Math.max(0, cap));
  return `${value.slice(0, cap - JSON_TRUNCATION_MARK.length)}${JSON_TRUNCATION_MARK}`;
};
// Recursive so a nested shape (an array of objects, an object-valued field)
// cannot smuggle uncapped prose past the budget.
const capValue = (value, cap) => {
  if (Array.isArray(value)) return value.map((entry) => capValue(entry, cap));
  if (value && typeof value === 'object') return capCharacterFields(value, cap);
  return truncateField(value, cap);
};
function capCharacterFields(character, cap) {
  return Object.fromEntries(Object.entries(character || {}).map(([key, value]) => [key, capValue(value, cap)]));
}

function renderRepairCharactersJson(payload, maxChars = REPAIR_CHARACTERS_MAX_CHARS) {
  const render = (value) => JSON.stringify(value, null, 2);
  const full = render(payload);
  if (full.length <= maxChars) return full;

  // The flat array shape (non-character dimensions) is ALL batch — there is no
  // roster to shed — so it trims field text rather than dropping fields, and only
  // falls back to the compact spine when even the tightest cap does not fit.
  if (Array.isArray(payload)) {
    let rendered = full;
    for (const cap of CHARACTER_FIELD_CAPS) {
      rendered = render(payload.map((character) => capCharacterFields(character, cap)));
      if (rendered.length <= maxChars) return rendered;
    }
    // Floor: the compact spine at the tightest cap, shedding trailing members
    // until it fits. The budget is a hard contract, so a cast large enough to
    // overrun even that loses members rather than the bound.
    const spine = payload.map((character) => capCharacterFields(compactRosterCharacter(character), CHARACTER_FIELD_CAPS.at(-1)));
    let kept = spine.length;
    rendered = render(spine);
    while (kept > 0 && rendered.length > maxChars) {
      kept -= 1;
      rendered = render(spine.slice(0, kept));
    }
    return rendered;
  }

  const targets = Array.isArray(payload?.targetCharacters) ? payload.targetCharacters : [];
  const roster = Array.isArray(payload?.fullSeriesRoster) ? payload.fullSeriesRoster : [];
  const compactRoster = roster.map(compactRosterCharacter);
  const rosterNote = (kept) => (kept === compactRoster.length
    ? 'Roster compacted to narrative and visual identity axes to fit the prompt budget.'
    : `Roster compacted and limited to ${kept} of ${compactRoster.length} members to fit the prompt budget.`);
  const buildTargets = (cap, spine) => {
    const shaped = spine ? targets.map(compactRosterCharacter) : targets;
    return cap ? shaped.map((character) => capCharacterFields(character, cap)) : shaped;
  };
  const targetNote = (cap, spine) => {
    if (spine) return `Batch compacted to narrative and visual identity axes and truncated at ${cap} characters to fit the prompt budget.`;
    return cap ? `Character fields over ${cap} characters were truncated to fit the prompt budget.` : undefined;
  };
  const build = (kept, cap, spine = false) => render({
    targetCharacters: buildTargets(cap, spine),
    fullSeriesRoster: compactRoster.slice(0, kept),
    rosterNote: rosterNote(kept),
    ...(targetNote(cap, spine) ? { targetNote: targetNote(cap, spine) } : {}),
  });

  // At a given field cap, keep as many roster members as fit. The batch under
  // repair outranks the roster, so the cap only tightens once even an empty
  // roster cannot make room.
  const bestFit = (cap, spine = false) => {
    let kept = compactRoster.length;
    let rendered = build(kept, cap, spine);
    while (kept > 0 && rendered.length > maxChars) {
      kept -= 1;
      rendered = build(kept, cap, spine);
    }
    return rendered;
  };

  let rendered = bestFit(null);
  for (const cap of CHARACTER_FIELD_CAPS) {
    if (rendered.length <= maxChars) return rendered;
    rendered = bestFit(cap);
  }
  // Floor: compact the batch itself to the spine. Lossy for the characters under
  // repair, which is why it is last, but the budget is a hard contract.
  if (rendered.length > maxChars) rendered = bestFit(CHARACTER_FIELD_CAPS.at(-1), true);
  return rendered;
}

function craftRepairViolations(proposal) {
  const guide = proposal?.styleGuide;
  if (!guide || typeof guide !== 'object') return ['styleGuide is missing'];
  const violations = [];
  const validateEntries = (key, { min, max }) => {
    const entries = guide[key];
    if (!Array.isArray(entries)) {
      violations.push(`${key} must be an array`);
      return;
    }
    if (entries.length < min || entries.length > max) {
      violations.push(`${key} must contain ${min}-${max} entries`);
    }
    for (const [index, entry] of entries.entries()) {
      const passage = typeof entry?.passage === 'string' ? entry.passage.trim() : '';
      const note = typeof entry?.note === 'string' ? entry.note.trim() : '';
      if (!passage) violations.push(`${key}[${index}].passage is required`);
      else if (passage.length > STYLE_GUIDE_LIMITS.EXEMPLAR_PASSAGE_MAX) {
        violations.push(`${key}[${index}].passage exceeds ${STYLE_GUIDE_LIMITS.EXEMPLAR_PASSAGE_MAX} characters`);
      }
      if (!note) violations.push(`${key}[${index}].note is required`);
      else if (note.length > STYLE_GUIDE_LIMITS.EXEMPLAR_NOTE_MAX) {
        violations.push(`${key}[${index}].note exceeds ${STYLE_GUIDE_LIMITS.EXEMPLAR_NOTE_MAX} characters`);
      }
    }
  };
  validateEntries('voiceExemplars', { min: 1, max: 2 });
  validateEntries('voiceAntiExemplars', { min: 1, max: STYLE_GUIDE_LIMITS.EXEMPLARS_MAX });
  return violations;
}

const renderPromptCharacter = (character) => ({
  id: character.id,
  name: character.name,
  role: character.role,
  ...Object.fromEntries(PROFILE_STRING_FIELDS.map((field) => [field, character[field] || ''])),
  ...pickFrameworkFields(character),
  ...pickVisualFoundationFields(character),
  postureNotes: character.postureNotes || '',
  specialTraits: character.specialTraits || '',
  stats: Array.isArray(character.stats) ? character.stats : [],
  props: Array.isArray(character.props) ? character.props : [],
  expressions: Array.isArray(character.expressions) ? character.expressions : [],
  handGestures: Array.isArray(character.handGestures) ? character.handGestures : [],
  wardrobes: Array.isArray(character.wardrobes) ? character.wardrobes : [],
});

async function runFoundationRepair(series, issues, dimension, finding, characters, options) {
  const stage = dimension === 'character' ? CHARACTER_FOUNDATION_STAGE : REPAIR_STAGE;
  const charactersPayload = dimension === 'character'
    ? {
      targetCharacters: characters.map(renderPromptCharacter),
      fullSeriesRoster: (options.ensembleCharacters || characters).map(renderPromptCharacter),
    }
    : characters.map(renderPromptCharacter);
  let violations = [];
  const maxAttempts = dimension === 'craft' ? CRAFT_REPAIR_MAX_ATTEMPTS : 1;
  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const findingPayload = { gap: finding?.gap || '', fix: finding?.fix || '' };
    // The gate may already have reverted an attempt at this dimension — say so,
    // so the next proposal changes strategy instead of re-earning the same
    // rollback. Craft's storage-contract retry below appends to this.
    if (finding?.retryReason) findingPayload.retryReason = finding.retryReason;
    if (dimension === 'craft') {
      findingPayload.hardStorageContract = {
        voiceExemplars: '1-2 entries',
        voiceAntiExemplars: `1-${STYLE_GUIDE_LIMITS.EXEMPLARS_MAX} entries`,
        passageMaxChars: STYLE_GUIDE_LIMITS.EXEMPLAR_PASSAGE_MAX,
        noteMaxChars: STYLE_GUIDE_LIMITS.EXEMPLAR_NOTE_MAX,
        requirement: 'Every passage and note must end as complete prose within these limits; storage never preserves overflow.',
      };
      if (violations.length > 0) {
        findingPayload.retryReason = [
          findingPayload.retryReason,
          `The previous proposal violated the hard storage contract: ${violations.join('; ')}. Rewrite it shorter; do not merely cut it off.`,
        ].filter(Boolean).join(' ');
      }
    }
    const result = await runStagedLLM(stage, {
      dimension,
      phase: options.phase || (dimension === 'character' ? 'post-arc reconciliation' : 'foundation repair'),
      foundationFindingJson: JSON.stringify(findingPayload, null, 2),
      seriesJson: renderRepairSeriesJson(series),
      outline: renderArc(series, issues, { maxChars: REPAIR_OUTLINE_MAX_CHARS }),
      charactersJson: renderRepairCharactersJson(charactersPayload),
    }, {
      returnsJson: true,
      providerDefault: options.providerId,
      modelDefault: options.model,
      effortDefault: options.effort,
      onRunCreated: options.onRunCreated,
      onRunSettled: options.onRunSettled,
      source: stage,
      ...(stage === CHARACTER_FOUNDATION_STAGE ? { timeoutOverride: CHARACTER_FOUNDATION_TIMEOUT_MS } : {}),
    });
    const proposal = result?.content && typeof result.content === 'object' ? result.content : {};
    if (dimension !== 'craft') return proposal;
    violations = craftRepairViolations(proposal);
    if (violations.length === 0) return proposal;
  }
  throw new Error(`foundation craft repair failed its storage contract after ${CRAFT_REPAIR_MAX_ATTEMPTS} attempts: ${violations.join('; ')}`);
}

async function repairCharacters(series, issues, universe, finding, options) {
  const seriesRoster = seriesFoundationCharacters(universe?.characters, series, issues);
  const repairable = seriesRoster.filter((character) => character?.locked !== true);
  const directive = normalizeBibleName(`${finding?.gap || ''} ${finding?.fix || ''}`);
  const namedCast = seriesRoster.filter((character) => [character.name, ...(Array.isArray(character.aliases) ? character.aliases : [])]
    .some((name) => typeof name === 'string' && name.trim()
      && new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegExp(normalizeBibleName(name))}(?![\\p{L}\\p{N}_])`, 'u').test(directive)));
  // A named post-arc finding owns that character's repair. Starting a new
  // foundation or reconciling an ensemble-wide finding still covers the cast.
  const namedRepair = options.phase !== 'pre-arc character foundation' && namedCast.length > 0;
  const targets = namedRepair
    ? namedCast.filter((character) => character.locked !== true)
    : repairable;
  if (namedRepair && targets.length === 0) return { applied: false, reason: 'the named character repair targets are locked' };
  const targetBatches = targets.length > 0
    ? Array.from({ length: Math.ceil(targets.length / CHARACTER_FOUNDATION_BATCH_SIZE) }, (_, index) => (
      targets.slice(index * CHARACTER_FOUNDATION_BATCH_SIZE, (index + 1) * CHARACTER_FOUNDATION_BATCH_SIZE)
    ))
    : [[]];
  const proposals = [];
  const overflowOriginals = new Map();
  let workingRoster = [...seriesRoster];
  const workingNewCharacters = [];
  while (targetBatches.length > 0) {
    const originalBatch = targetBatches.shift();
    const batchIds = new Set(originalBatch.map((character) => character.id));
    const targetBatch = workingRoster.filter((character) => batchIds.has(character.id));
    const ensembleCharacters = [...workingRoster, ...workingNewCharacters];
    const preview = JSON.parse(renderRepairCharactersJson({
      targetCharacters: targetBatch.map(renderPromptCharacter),
      fullSeriesRoster: ensembleCharacters.map(renderPromptCharacter),
    }));
    if (preview.targetNote) {
      // Shrink the batch before shrinking the records it is allowed to edit.
      // A 40-character field cap erased whole designs in a real repair prompt.
      if (originalBatch.length > 1) {
        const midpoint = Math.ceil(originalBatch.length / 2);
        targetBatches.unshift(originalBatch.slice(0, midpoint), originalBatch.slice(midpoint));
        continue;
      }
    }
    const overflow = Boolean(preview.targetNote);
    const proposal = overflow
      ? await repairOversizedCharacter(targetBatch[0], {
        finding,
        phase: options.phase || 'post-arc reconciliation',
        seriesJson: renderRepairSeriesJson(series),
        outline: renderArc(series, issues, { maxChars: REPAIR_OUTLINE_MAX_CHARS }),
        rosterJson: renderRepairCharactersJson(ensembleCharacters.map(compactRosterCharacter), 2_000),
      }, REPAIRABLE_CHARACTER_FIELDS, { ...options, timeoutOverride: CHARACTER_FOUNDATION_TIMEOUT_MS })
      : await runFoundationRepair(series, issues, 'character', finding, targetBatch, {
        ...options,
        // Locked cast members constrain relationships and voices. Later batches
        // also see accepted proposals so they do not invent duplicate identities.
        ensembleCharacters,
      });
    if (overflow) overflowOriginals.set(targetBatch[0].id, targetBatch[0]);
    const boundedProposal = {
      ...proposal,
      characters: (Array.isArray(proposal.characters) ? proposal.characters : [])
        .filter((character) => batchIds.has(character?.id)),
    };
    proposals.push(boundedProposal);

    const proposedById = new Map(boundedProposal.characters
      .filter((character) => typeof character?.id === 'string')
      .map((character) => [character.id, character]));
    workingRoster = workingRoster.map((character) => {
      const raw = proposedById.get(character.id);
      if (!raw) return character;
      if (overflowOriginals.has(character.id)) return { ...character, ...raw };
      return sanitizeCharacter({ ...character, ...raw, id: character.id, name: character.name }) || character;
    });
    const knownNames = new Set([...workingRoster, ...workingNewCharacters]
      .map((character) => String(character?.name || '').trim().toLowerCase())
      .filter(Boolean));
    for (const raw of Array.isArray(proposal.newCharacters) ? proposal.newCharacters : []) {
      if (workingNewCharacters.length >= MAX_FOUNDATION_NEW_CHARACTERS) break;
      const nameKey = String(raw?.name || '').trim().toLowerCase();
      if (!nameKey || knownNames.has(nameKey)) continue;
      workingNewCharacters.push(raw);
      knownNames.add(nameKey);
    }
  }
  const proposedCharacters = proposals.flatMap((proposal) => (
    Array.isArray(proposal.characters) ? proposal.characters : []
  ));
  const proposalById = new Map(proposedCharacters
    .filter((character) => typeof character?.id === 'string')
    .map((character) => [character.id, character]));
  const targetIds = new Set(targets.map((character) => character.id));
  const updatedFields = new Set();
  let charactersApplied = false;
  const addedCharacters = [];
  await updateUniverse(universe.id, (latest) => {
    const latestCharacters = Array.isArray(latest?.characters) ? latest.characters : [];
    for (const [id, original] of overflowOriginals) {
      if (JSON.stringify(latestCharacters.find((character) => character.id === id)) !== JSON.stringify(original)) {
        throw new Error('Character foundation overflow repair source changed during validation; no edits applied.');
      }
    }
    let changed = false;
    const characters = latestCharacters.map((character) => {
      if (!targetIds.has(character.id) || character.locked === true) return character;
      const raw = proposalById.get(character.id);
      if (!raw) return character;
      const sanitized = sanitizeCharacter({ ...character, ...raw, id: character.id, name: character.name });
      if (!sanitized) return character;
      const next = { ...character };
      for (const field of REPAIRABLE_CHARACTER_FIELDS) {
        // Overflow validation covers only the explicit patch. Never rewrite
        // untouched supporting detail through the sanitizer.
        if (overflowOriginals.has(character.id) && !Object.hasOwn(raw, field)) continue;
        const value = sanitized[field];
        // Object-valued fields (`psychology`) are authored when the sanitizer
        // returned one at all — it collapses an empty proposal to null/absent.
        const authored = Array.isArray(value)
          ? value.length > 0
          : (value && typeof value === 'object')
            ? Object.keys(value).length > 0
            : !isBlankString(value);
        if (!authored || JSON.stringify(value) === JSON.stringify(character[field])) continue;
        next[field] = value;
        updatedFields.add(field);
        changed = true;
      }
      return next;
    });
    const knownNames = new Set(characters
      .map((character) => String(character?.name || '').trim().toLowerCase())
      .filter(Boolean));
    const proposedNewCharacters = proposals
      .flatMap((proposal) => (Array.isArray(proposal.newCharacters) ? proposal.newCharacters : []))
      .slice(0, MAX_FOUNDATION_NEW_CHARACTERS);
    for (const raw of proposedNewCharacters) {
      const nameKey = String(raw?.name || '').trim().toLowerCase();
      if (!nameKey || knownNames.has(nameKey)) continue;
      const sanitized = sanitizeCharacter({
        ...raw,
        id: undefined,
        locked: false,
        source: BIBLE_SOURCE.SERIES_EXTRACT,
        sourceSeriesId: series.id,
      }, { preserveTimestamps: false });
      if (!sanitized) continue;
      characters.push(sanitized);
      addedCharacters.push(sanitized);
      knownNames.add(nameKey);
      changed = true;
    }
    if (!changed) return null;
    charactersApplied = true;
    return { characters };
  });

  const characterIdByName = new Map([
    ...(Array.isArray(universe?.characters) ? universe.characters : []),
    ...addedCharacters,
  ].map((character) => [String(character?.name || '').trim().toLowerCase(), character?.id]));
  const proposedArcs = sanitizeCharacterArcList(proposals
    .flatMap((proposal) => (Array.isArray(proposal.characterArcs) ? proposal.characterArcs : []))
    .map((arc) => ({
      ...arc,
      characterId: characterIdByName.get(String(arc?.characterName || '').trim().toLowerCase()) || arc?.characterId,
    })))
    .filter((arc) => !namedRepair || targetIds.has(arc.characterId)
      || addedCharacters.some((character) => character.id === arc.characterId));
  let arcsApplied = false;
  if (proposedArcs.length > 0) {
    const latestSeries = await getSeries(series.id);
    const existingArcByKey = new Map((latestSeries.characterArcs || []).flatMap((arc) => [
      arc?.characterId ? [arc.characterId, arc] : null,
      arc?.characterName ? [`name:${arc.characterName.trim().toLowerCase()}`, arc] : null,
    ].filter(Boolean)));
    // Character repairs after the macro arc may deepen motivation, arc type,
    // and start/end states, but transition beats are plot events. Letting this
    // editor add or move them silently creates an arc-ledger event that no
    // episode synopsis stages; the next judge then (correctly) penalizes the
    // structure for a contradiction the previous repair just invented. Keep
    // existing authored transitions unchanged in post-arc reconciliation and leave
    // missing scene placement to the structure owner (`resolveVerifyIssues`).
    const boundedProposedArcs = options.phase === 'post-arc reconciliation'
      ? proposedArcs.map((arc) => {
        const existing = existingArcByKey.get(arc.characterId)
          || existingArcByKey.get(`name:${String(arc.characterName || '').trim().toLowerCase()}`);
        return existing
          ? { ...arc, transitions: Array.isArray(existing.transitions) ? existing.transitions : [] }
          : arc;
      })
      : proposedArcs;
    // A legacy name-only arc and a newly canon-linked arc otherwise have
    // different sanitizer keys and survive as duplicates. Remove every prior
    // identity the proposal replaces, then rely on last-write-wins within the
    // proposal itself. This preserves untouched arcs while upgrading the
    // authored character to its stable canon id.
    const replacementKeys = new Set(boundedProposedArcs.flatMap((arc) => [
      arc.characterId || '',
      arc.characterName ? `name:${arc.characterName.trim().toLowerCase()}` : '',
    ]).filter(Boolean));
    const untouchedArcs = (latestSeries.characterArcs || []).filter((arc) => (
      !replacementKeys.has(arc?.characterId || '')
      && !replacementKeys.has(arc?.characterName ? `name:${arc.characterName.trim().toLowerCase()}` : '')
    ));
    const mergedArcs = sanitizeCharacterArcList([...untouchedArcs, ...boundedProposedArcs]);
    if (JSON.stringify(mergedArcs) !== JSON.stringify(latestSeries.characterArcs || [])) {
      await updateSeries(series.id, { characterArcs: mergedArcs });
      arcsApplied = true;
    }
  }

  const applied = charactersApplied || arcsApplied;
  return applied
    ? {
      applied: true,
      entryIds: targets.map((character) => character.id),
      updatedFields: [...updatedFields],
      charactersAdded: addedCharacters.length,
      characterArcsUpdated: arcsApplied,
    }
    : { applied: false, reason: 'repair model proposed no usable core-cast or character-arc changes' };
}

function hasCompleteFramework(character) {
  return FRAMEWORK_STRING_FIELDS.every((field) => !isBlankString(character?.[field]))
    && PROFILE_STRING_FIELDS.every((field) => !isBlankString(character?.[field]))
    && !isBlankArray(character?.secrets)
    && !isBlankString(character?.arcType)
    && VISUAL_FOUNDATION_STRING_FIELDS.every((field) => !isBlankString(character?.[field]))
    && VISUAL_FOUNDATION_LIST_FIELDS.every((field) => !isBlankArray(character?.[field]));
}

/**
 * Establish the character engine before the plot spine is generated. This is
 * intentionally distinct from the later whole-foundation judge: the early pass
 * gives the arc planner causal people to build events around, while the later
 * pass reconciles those people with story-specific discoveries.
 */
export async function establishCharacterFoundation(seriesId, {
  providerDefault,
  modelDefault,
  effortDefault,
  onRunCreated,
  onRunSettled,
} = {}) {
  assertValidSeriesId(seriesId);
  const series = await getSeries(seriesId);
  if (!series?.universeId) {
    return { applied: false, skipped: true, ran: false, reason: 'no linked universe' };
  }
  const universe = await getUniverse(series.universeId).catch(() => null);
  if (!universe) {
    return { applied: false, skipped: true, ran: false, reason: 'linked universe not found' };
  }
  const targets = repairableSeriesFoundationCharacters(universe.characters, series, []);
  const authoredArcs = Array.isArray(series.characterArcs) ? series.characterArcs : [];
  const arcKeys = new Set(authoredArcs.flatMap((arc) => [
    arc?.characterId || '',
    `name:${String(arc?.characterName || '').trim().toLowerCase()}`,
  ]).filter(Boolean));
  const needsRepair = targets.length === 0 || targets.some((character) => (
    !hasCompleteFramework(character)
    || (!arcKeys.has(character.id) && !arcKeys.has(`name:${String(character.name || '').trim().toLowerCase()}`))
  ));
  if (!needsRepair) {
    return { applied: false, skipped: true, ran: false, reason: 'core character foundation is already complete' };
  }
  const result = await repairCharacters(series, [], universe, {
    gap: 'The plot spine has not been generated yet, so the core cast must first have specific causal inner engines, relationship tensions, and stable render identities.',
    fix: 'Complete the core ensemble from the premise: Ghost to Wound to Lie to Want to Need, distinct voice and contradictions, active relationships, mutually distinct physical descriptions, silhouettes, visual identities and palettes, and a provisional whole-series change path. Add only a genuinely missing core role.',
  }, {
    providerId: providerDefault,
    model: modelDefault,
    effort: effortDefault,
    onRunCreated,
    onRunSettled,
    phase: 'pre-arc character foundation',
  });
  return { ...result, ran: true };
}

async function repairCraft(series, issues, finding, options) {
  const proposal = await runFoundationRepair(series, issues, 'craft', finding, [], options);
  const latestSeries = await getSeries(series.id);
  const rawGuide = proposal.styleGuide && typeof proposal.styleGuide === 'object'
    ? proposal.styleGuide
    : null;
  const existingGuide = latestSeries.styleGuide || {};
  const mergedGuide = rawGuide
    ? sanitizeStyleGuide({
      ...existingGuide,
      ...rawGuide,
      conventions: rawGuide.conventions && typeof rawGuide.conventions === 'object'
        ? { ...(existingGuide.conventions || {}), ...rawGuide.conventions }
        : existingGuide.conventions,
      voiceExemplars: Array.isArray(rawGuide.voiceExemplars) && rawGuide.voiceExemplars.length > 0
        ? rawGuide.voiceExemplars
        : existingGuide.voiceExemplars,
      voiceAntiExemplars: Array.isArray(rawGuide.voiceAntiExemplars) && rawGuide.voiceAntiExemplars.length > 0
        ? rawGuide.voiceAntiExemplars
        : existingGuide.voiceAntiExemplars,
    })
    : latestSeries.styleGuide;
  const styleNotes = typeof proposal.styleNotes === 'string' && proposal.styleNotes.trim()
    ? proposal.styleNotes.trim()
    : latestSeries.styleNotes;
  const patch = {};
  if (styleNotes !== latestSeries.styleNotes) patch.styleNotes = styleNotes;
  if (JSON.stringify(mergedGuide) !== JSON.stringify(latestSeries.styleGuide)) patch.styleGuide = mergedGuide;
  if (Object.keys(patch).length === 0) {
    return { applied: false, reason: 'repair model proposed no usable series voice changes' };
  }
  await updateSeries(series.id, patch);
  return { applied: true, updatedFields: Object.keys(patch) };
}

// Refine the universe world bible (worldbuilding dimension) through the
// owning service: regenerate logline/premise/styleNotes/influences via
// expandWorldTemplate — which ECHOES locked entries unchanged (force:false /
// no-clobber) — then persist through updateUniverse (serialized write queue).
// Mirrors storyBuilder.js's `universeAesthetic` step. Returns false when there's
// no universe to refine.
async function refineWorld(universeId, { providerId, model, effort, onRunCreated, onRunSettled, finding = {} }) {
  if (!universeId) return { applied: false, reason: 'no linked universe' };
  const universe = await getUniverse(universeId).catch(() => null);
  if (!universe) return { applied: false, reason: 'universe not found' };
  const expanded = await expandWorldTemplate({
    starterPrompt: universe.starterPrompt || universe.name,
    influences: universe.influences,
    logline: universe.logline,
    premise: universe.premise,
    styleNotes: universe.styleNotes,
    locked: universe.locked,
    foundationDirective: [
      [finding.gap, finding.fix].filter(Boolean).join('\nRequested repair: '),
      finding.retryReason ? `Previous attempt: ${finding.retryReason}` : '',
    ].filter(Boolean).join('\n'),
    providerId,
    model,
    effort,
    onRunCreated,
    onRunSettled,
    narrativeOnly: true,
  });
  // Persist through the write-queue mutator against the FRESHEST record, and
  // defensively DROP any field the user has locked — expandWorldTemplate is
  // meant to echo locked fields unchanged, but a bad LLM echo (or a lock set
  // DURING the LLM round-trip) must never overwrite human-locked canon. The
  // gate's whole contract is "locked entries are constraints, not fix targets."
  let wrote = false;
  await updateUniverse(universeId, (latest) => {
    const locked = latest?.locked || {};
    const patch = {};
    // Only write a scalar the LLM actually authored: expandWorldTemplate returns
    // null (or blank) for an OMITTED field, which is "nothing to add" — NOT a
    // clear. Writing it would erase the existing unlocked value (sanitize turns a
    // non-string into ''). Skip locked fields AND absent/blank ones; preserve the
    // current value in both cases (the AGENTS.md absent-vs-empty rule).
    if (locked.logline !== true && isNonBlankStr(expanded.logline)) patch.logline = expanded.logline;
    if (locked.premise !== true && isNonBlankStr(expanded.premise)) patch.premise = expanded.premise;
    if (locked.styleNotes !== true && isNonBlankStr(expanded.styleNotes)) patch.styleNotes = expanded.styleNotes;
    // `influences` is an { embrace, avoid } object and updateUniverse replaces it
    // WHOLESALE — but the lockable keys are the two SUBLISTS
    // (`influencesEmbrace`/`influencesAvoid`, see universeBuilder LOCKABLE_FIELDS),
    // not `influences`. A wholesale write would clobber a locked sublist, so only
    // write influences when NEITHER sublist is locked.
    const influencesLocked = locked.influencesEmbrace === true || locked.influencesAvoid === true;
    if (!influencesLocked && expanded.influences && typeof expanded.influences === 'object') patch.influences = expanded.influences;
    if (!Object.keys(patch).length) return null; // all locked or nothing authored → no-op
    wrote = true;
    return patch;
  });
  // `wrote === false` means every refinable field is locked — report it so the
  // gate pauses 'inapplicable' for human review instead of silently no-op-ing.
  if (!wrote) return { applied: false, reason: 'every refinable world field is locked' };
  // A repair that landed against a field already at its storage ceiling had to
  // consolidate existing prose to make room. Say so on the fix frame: when the
  // gate later pauses on non-convergence, "the premise is full" is the fact that
  // tells a human to prune the bible rather than re-run the same repair.
  const saturated = Object.entries(narrativeRepairTargets(universe))
    .filter(([, budget]) => budget.saturated)
    .map(([field]) => field);
  return saturated.length
    ? { applied: true, reason: `world bible ${saturated.join(' and ')} sat at the storage ceiling; the repair had to consolidate existing canon to fit` }
    : { applied: true };
}

const FOUNDATION_UNIVERSE_SNAPSHOT_FIELDS = Object.freeze([
  'logline', 'premise', 'styleNotes', 'influences', 'characters',
]);

const FOUNDATION_SERIES_SNAPSHOT_FIELDS = Object.freeze([
  'styleNotes', 'styleGuide', 'characterArcs',
]);

const pickFoundationFields = (record, fields) => Object.fromEntries(
  fields.map((field) => [
    field,
    record && Object.hasOwn(record, field) ? structuredClone(record[field]) : undefined,
  ]),
);

// Per-canon-entry fields the universe WRITE PATH owns, which a faithful restore
// therefore does NOT (and must not) bring back to the checkpoint value:
//   - `updatedAt` is re-stamped by `updateUniverse` on every canon entry whose
//     content changed vs the live record — and undoing a repair IS a content
//     change, so a correct revert always comes back with a fresh LWW clock (it
//     has to, or the canon→catalog projection would never carry the revert).
//   - the render/sheet pointers are deliberately preserved FROM the live record
//     (`mergePreservedSheetPointers` / `preserveImageRefsById`) so a sheet or
//     render that completed while the repair ran isn't thrown away by the undo.
// Comparing them made every faithful character rollback report itself as a
// failed restore, which stalled the foundation gate with a checkpoint-corruption
// warning that was never true. Authored content is still compared byte-for-byte.
const CANON_WRITE_PATH_OWNED_FIELDS = Object.freeze([
  'updatedAt', 'referenceSheetImageRef', 'referenceSheets', 'imageRefs',
]);

const comparableCanonEntry = (entry) => {
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return entry;
  const rest = { ...entry };
  for (const field of CANON_WRITE_PATH_OWNED_FIELDS) delete rest[field];
  return rest;
};

// Walk EVERY canon array the bible defines, not just `characters`. The write
// path (`stampChangedCanonEntries` in universeBuilder/crud.js) stamps
// `updatedAt` across all of `BIBLE_KEYS`, so the moment a canon array beyond
// `characters` joins FOUNDATION_UNIVERSE_SNAPSHOT_FIELDS the same false
// "restored foundation fields did not match the checkpoint" pause would return.
const comparableUniverseFields = (universe) => {
  if (!universe || typeof universe !== 'object') return universe ?? null;
  const comparable = { ...universe };
  for (const key of BIBLE_KEYS) {
    if (Array.isArray(comparable[key])) comparable[key] = comparable[key].map(comparableCanonEntry);
  }
  return comparable;
};

// `undefined` (field absent from the record) is NOT the same as `null` — the
// restore skips absent fields, so a repair-added field the checkpoint never had
// is a genuine leftover the verification must still catch. The sentinel keeps
// the two distinguishable through JSON.
const comparablePart = (value) => (value === undefined ? '<absent>' : JSON.stringify(value ?? null));

/**
 * Field-keyed projection of a foundation snapshot for the post-restore check.
 * Keyed (rather than one blob) so a mismatch can NAME what failed to come back —
 * a bare "did not match" pause tells an operator nothing about what to inspect.
 */
const foundationSnapshotParts = (snapshot) => {
  const universe = comparableUniverseFields(snapshot?.universe);
  const parts = { universeId: comparablePart(snapshot?.universeId || null) };
  for (const field of FOUNDATION_UNIVERSE_SNAPSHOT_FIELDS) {
    parts[`universe.${field}`] = comparablePart(universe ? universe[field] : null);
  }
  for (const field of FOUNDATION_SERIES_SNAPSHOT_FIELDS) {
    parts[`series.${field}`] = comparablePart(snapshot?.series ? snapshot.series[field] : null);
  }
  parts.arc = comparablePart(snapshot?.arcState?.arc ?? null);
  parts.seasons = comparablePart(snapshot?.arcState?.seasons || []);
  parts.episodes = comparablePart(snapshot?.arcState?.episodes || []);
  return parts;
};

/** The snapshot fields that did NOT come back — [] when the restore was faithful. */
const mismatchedFoundationFields = (checkpoint, restored) => {
  const before = foundationSnapshotParts(checkpoint);
  const after = foundationSnapshotParts(restored);
  return Object.keys(before).filter((field) => before[field] !== after[field]);
};

/**
 * Capture every field an owned foundation repair may rewrite. Arc planning has
 * its own exact snapshot (including episode ideas); this adds the world,
 * character, and craft-owned records so the conductor can reject a repair that
 * a fresh judge proves did not earn its changes.
 */
export async function snapshotFoundationState(seriesId) {
  assertValidSeriesId(seriesId);
  const series = await getSeries(seriesId);
  const [universe, arcState] = await Promise.all([
    series?.universeId ? getUniverse(series.universeId).catch(() => null) : null,
    snapshotArcState(seriesId),
  ]);
  return {
    seriesId,
    universeId: series?.universeId || null,
    universe: universe ? pickFoundationFields(universe, FOUNDATION_UNIVERSE_SNAPSHOT_FIELDS) : null,
    series: pickFoundationFields(series, FOUNDATION_SERIES_SNAPSHOT_FIELDS),
    arcState,
  };
}

/**
 * Restore a foundation snapshot and verify the tracked fields match exactly.
 *
 * `judge` is the verdict that scored the checkpoint being restored. The cached
 * verdict on disk is keyed by a content hash, so after a rewind it describes
 * content that no longer exists and the next `judgeFoundation` pays a full LLM
 * call to re-derive a score this one already holds. Re-pinning it on a VERIFIED
 * restore puts the cache back in step with the content. Optional: a caller
 * without the pre-rewind verdict simply leaves the stale entry to self-
 * invalidate on its hash.
 */
export async function restoreFoundationState(seriesId, snapshot, { judge } = {}) {
  if (!snapshot || snapshot.seriesId !== seriesId || !snapshot.arcState) {
    return { restored: false, reason: 'invalid foundation snapshot' };
  }
  if (snapshot.universeId && snapshot.universe) {
    await updateUniverse(snapshot.universeId, Object.fromEntries(
      Object.entries(structuredClone(snapshot.universe)).filter(([, value]) => value !== undefined),
    ));
  }
  await updateSeries(seriesId, Object.fromEntries(
    Object.entries(structuredClone(snapshot.series)).filter(([, value]) => value !== undefined),
  ));
  const arcRestore = await restoreArcState(seriesId, snapshot.arcState);
  const restoredSnapshot = await snapshotFoundationState(seriesId);
  const mismatched = mismatchedFoundationFields(snapshot, restoredSnapshot);
  const restored = mismatched.length === 0;
  if (restored && judge?.seriesId === seriesId && judge.sourceInputsHash) {
    const { cached, ...verdict } = judge;
    await saveSnapshot(verdict);
  }
  return {
    restored,
    reason: restored
      ? null
      : `restored foundation fields did not match the checkpoint: ${mismatched.join(', ')}`,
    mismatchedFields: mismatched,
    episodesRestored: arcRestore.episodesRestored || 0,
  };
}

/**
 * Apply a fix for one foundation dimension through its OWNING service (never a
 * raw write; `force:false` everywhere so locked canon is a constraint, not a
 * target). Returns `{ applied, dimension, reason? }`.
 *
 * Routing:
 *   worldbuilding → universe world refine (expandWorldTemplate → updateUniverse)
 *   craft         → series voice/style repair (including concrete exemplars)
 *   character     → judge-directed core-cast framework + character-arc repair
 *   structure     → arc resolve (resolveVerifyIssues) with the judge's finding
 *
 * `finding` is the judge's `{ gap, fix }` for the targeted dimension, threaded
 * into the structure resolve as a synthesized arc finding.
 *
 * A retry after the caller REVERTED an earlier attempt at this same dimension
 * describes that attempt so this one changes strategy instead of re-proposing
 * discarded edits. It arrives on whichever channel the owning route has: the
 * prose `finding.retryReason` for the LLM-payload routes (character/craft's
 * finding JSON, worldbuilding's directive), and `avoidFindings` — the shared
 * "a previous attempt produced these, do not author them again" contract of
 * `resolveVerifyIssues` — for the structure route, so those stay OUT of the
 * work-to-close list a `suggestion` would have put them in.
 */
export async function applyFoundationFix(seriesId, dimension, {
  finding = {},
  avoidFindings,
  providerOverride,
  modelOverride,
  effortOverride,
  judgeProviderDefault,
  judgeModelDefault,
  judgeEffortDefault,
  judgeOnRunCreated,
  judgeOnRunSettled,
  preserveDroppedSeasons = false,
  onRunCreated,
  onRunSettled,
} = {}) {
  assertValidSeriesId(seriesId);
  const series = await getSeries(seriesId);
  const issues = await listIssues({ seriesId });
  const universeId = series?.universeId || null;
  const provider = {
    providerId: providerOverride,
    model: modelOverride,
    effort: effortOverride,
    finding,
    onRunCreated,
    onRunSettled,
  };

  if (dimension === 'worldbuilding') {
    const r = await refineWorld(universeId, provider);
    return { dimension, ...r };
  }

  if (dimension === 'craft') {
    const r = await repairCraft(series, issues, finding, provider);
    return { dimension, ...r };
  }

  if (dimension === 'character') {
    if (!universeId) return { dimension, applied: false, reason: 'no linked universe' };
    const universe = await getUniverse(universeId).catch(() => null);
    if (!universe) return { dimension, applied: false, reason: 'universe not found' };
    const r = await repairCharacters(series, issues, universe, finding, { ...provider, phase: 'post-arc reconciliation' });
    return { dimension, ...r };
  }

  if (dimension === 'structure') {
    // A locked arc is a constraint, not a fix target — resolveVerifyIssues throws
    // on a locked arc, which would error the whole run. Degrade to a graceful
    // "can't apply" so the gate pauses for human review instead (mirrors the
    // no-linked-universe / fully-locked-cast paths above).
    if (series?.locked?.arc === true) {
      return { dimension, applied: false, reason: 'arc is locked (a constraint, not a fix target)' };
    }
    // Synthesize an arc finding from the judge's structure gap/fix and route it
    // through the existing arc-resolve owning service.
    const findings = [{
      severity: 'high',
      location: 'arc',
      problem: finding.gap || 'arc structure is below the foundation-quality bar',
      suggestion: finding.fix || '',
    }];
    // Which episode synopses each rollback below may put back: the ones the
    // resolver reported writing after that checkpoint was taken, and nothing
    // else (see `createArcMutationLedger`). Without it, a repair that runs a
    // resolve plus up to MAX_STRUCTURE_CORRECTION_PASSES correct/verify pairs
    // reverted every episode `idea` that merely DIFFERED from its checkpoint —
    // including a write that landed from elsewhere across that whole window.
    // One ledger for the whole repair, because a checkpoint outlives the pass
    // that took it: rewinding to `bestVerified` has to undo every resolve since.
    const ledger = createArcMutationLedger();
    const takeSnapshot = async () => ledger.hold(await snapshotArcState(seriesId));
    const restoreTo = (checkpoint) => restoreArcState(seriesId, checkpoint, {
      episodeEdits: ledger.since(checkpoint),
    });
    const snapshot = await takeSnapshot();
    const structureRunIds = [];
    const resolveOptions = {
      providerDefault: providerOverride,
      modelDefault: modelOverride,
      // What a reverted earlier attempt at this dimension produced. The resolver
      // renders these in its own "do not author these again" block, apart from
      // the findings it must close (mirrors the arc gate's rollback retry).
      ...(Array.isArray(avoidFindings) && avoidFindings.length > 0 ? { avoid: avoidFindings } : {}),
      // The autopilot's unlock-for-run mode clears both `series.locked.arc`
      // (disarming the short-circuit above) and every per-season lock, so this
      // is the third arc-rewriting path that could otherwise delete a volume.
      // Carry the same non-deletion guarantee the other two do.
      preserveDroppedSeasons,
      effortDefault: effortOverride,
      onRunCreated: (runId) => {
        structureRunIds.push(runId);
        onRunCreated?.(runId);
      },
      onRunSettled,
    };
    const verifyOptions = {
      providerDefault: judgeProviderDefault,
      modelDefault: judgeModelDefault,
      effortDefault: judgeEffortDefault,
      onRunCreated: judgeOnRunCreated,
      onRunSettled: judgeOnRunSettled,
    };
    const trackedResolve = async (resolveFindings) => {
      const before = structureRunIds.length;
      const result = await resolveVerifyIssues(seriesId, { findings: resolveFindings, ...resolveOptions });
      ledger.note(resolvedEpisodeEdits(result));
      return { result, runIds: structureRunIds.slice(before) };
    };
    const runGuardedStructureRepair = async () => {
      const firstAttempt = await trackedResolve(findings);
      const first = firstAttempt.result;
      if (first?.applied === false) {
        return { dimension, applied: false, reason: first?.notes || 'arc resolver applied no change' };
      }

      let verification = await verifyArc(seriesId, verifyOptions);
      let blockers = Array.isArray(verification?.issues) ? verification.issues : [];
      if (blockers.length === 0) {
        return { dimension, applied: true, actions: 2, acceptedRunIds: firstAttempt.runIds };
      }

      const initialBlockers = blockers;
      let retainedRunIds = [...firstAttempt.runIds];
      let rejectedRunIds = [];
      let bestVerified = {
        blockers,
        snapshot: await takeSnapshot(),
        runIds: [...retainedRunIds],
      };

      // A foundation-directed structure rewrite can satisfy its broad judge
      // while accidentally violating a narrower canon/location/timing rule.
      // Keep correcting while the specialized verifier's severity profile improves.
      // A single all-or-nothing pass threw away demonstrated 10 → 3 progress and
      // forced the next run to rebuy all ten fixes. The bounded loop preserves
      // the original rollback guarantee, but spends up to three focused passes
      // when each one is moving monotonically toward a clean plan.
      let actions = 2;
      for (let pass = 0; pass < MAX_STRUCTURE_CORRECTION_PASSES && blockers.length > 0; pass += 1) {
        const before = blockers;
        const correctionAttempt = await trackedResolve(blockers);
        const correction = correctionAttempt.result;
        actions += 1;
        if (correction?.applied === false) break;
        verification = await verifyArc(seriesId, verifyOptions);
        actions += 1;
        const nextBlockers = Array.isArray(verification?.issues) ? verification.issues : [];
        blockers = nextBlockers;
        if (blockers.length === 0) {
          return {
            dimension,
            applied: true,
            actions,
            acceptedRunIds: [...retainedRunIds, ...correctionAttempt.runIds],
            rejectedRunIds,
          };
        }
        if (compareArcBlockers(blockers, before) > 0) {
          rejectedRunIds = [...rejectedRunIds, ...correctionAttempt.runIds];
          break;
        }
        retainedRunIds = [...retainedRunIds, ...correctionAttempt.runIds];
        if (compareArcBlockers(blockers, bestVerified.blockers) <= 0) {
          bestVerified = {
            blockers,
            snapshot: await takeSnapshot(),
            runIds: [...retainedRunIds],
          };
        }
      }

      // Do not throw away a demonstrated monotonic improvement merely because
      // the next correction traded its final residual for a larger set. Keep
      // the best independently verified checkpoint; the foundation judge will
      // still decide whether it improved structure, and the normal full-arc
      // gate remains latched dirty so it must close the residual before beats.
      if (compareArcBlockers(bestVerified.blockers, initialBlockers) < 0) {
        await restoreTo(bestVerified.snapshot);
        return {
          dimension,
          applied: true,
          partial: true,
          actions,
          reason: `structure repair retained its best verified improvement (${formatArcBlockerProfile(initialBlockers)} → ${formatArcBlockerProfile(bestVerified.blockers)}); the full arc gate must close the residual`,
          residual: bestVerified.blockers,
          discarded: blockers,
          acceptedRunIds: bestVerified.runIds,
          rejectedRunIds,
        };
      }

      await restoreTo(snapshot);
      return {
        dimension,
        applied: false,
        reverted: true,
        actions,
        reason: `structure repair left ${blockers.length} arc-verification blocker(s); reverted to the pre-repair plan`,
        // The blockers that condemned the rewrite. Without them the revert is a
        // bare count in prose, and the pause it raises reports dimension-level
        // gaps instead — a different set entirely — so the user is never shown
        // why a plausible rewrite was thrown away.
        discarded: blockers,
        rejectedRunIds: structureRunIds,
      };
    };
    // Any provider/parse failure after the first mutation must not strand the
    // series in the unverified intermediate draft. Restore, then preserve the
    // original error so the conductor pauses with the real provider diagnosis.
    return runGuardedStructureRepair().catch(async (err) => {
      await restoreTo(snapshot);
      throw err;
    });
  }

  return { dimension, applied: false, reason: `unknown dimension: ${dimension}` };
}

export const __testing = {
  sanitizeFoundationJudge,
  foundationInputs,
  contentHash,
  isFoundationStale,
  buildFoundationContext,
  renderArc,
  renderWorldFoundation,
  renderCharacterLine,
  renderRepairSeriesJson,
  renderRepairCharactersJson,
  REPAIR_OUTLINE_MAX_CHARS,
  REPAIR_SERIES_MAX_CHARS,
  REPAIR_CHARACTERS_MAX_CHARS,
  CHARACTER_FOUNDATION_TIMEOUT_MS,
  CHARACTER_FOUNDATION_BATCH_SIZE,
  FRAMEWORK_STRING_FIELDS,
  PROFILE_STRING_FIELDS,
  mismatchedFoundationFields,
  comparableUniverseFields,
  CANON_WRITE_PATH_OWNED_FIELDS,
};