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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* 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,
};