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

88.3 KB
Raw Blame
/**
 * arcPlanner/arcCore.js — the arc overview / reader-map / refine / verify /
 * resolve / commit cluster.
 *
 * These passes are mutually recursive (overview ↔ resolve ↔ commit, verify ↔
 * volume-verify) and can't be cleanly separated, so they share one module.
 * Built on the leaf helpers in ./context.js.
 */

import { runStagedLLM } from '../../stageRunner.js';
import { ServerError } from '../../../lib/errorHandler.js';
import { stripAnsi } from '../../../lib/ansiStrip.js';
import { ARC_LOCKABLE_FIELDS, MANUSCRIPT_TYPES, getSeries, updateSeries } from '../series.js';
import { listIssues, listIssuesForSeries, recomputeIssueNumbersForSeries, updateIssue, updateStageWithLatest, updateStagesWithLatest } from '../issues.js';
import { emitRecordUpdated, withReexportSuppressed } from '../../sharing/recordEvents.js';
import { getSeason } from '../seasons.js';
import { ARC_LIMITS, READER_MAP_BEAT_KINDS, TICKING_CLOCK_LIMITS, buildSeason, cleanThemes, renderArcShapeGuidance, renderArcShapePositionSummary, sanitizeArc, sanitizeReaderMap, sanitizeSeason, sanitizeSeasonList, sanitizeTickingClock } from '../../../lib/storyArc.js';
import { sanitizeCharacterArcList } from '../../../lib/seriesCharacterArc.js';
import { runPromptRefineRaw, trimChanges } from '../refineHelpers.js';
import { ERR_VALIDATION, SHAPE_GUIDANCE_NONE, appendTickingClock, buildArcBaseContext, buildArcOverviewContext, buildNeighborVolumes, buildReaderMapContext, buildResolveContext, buildVerifyContext, compareIssuesByPosition, findingIdSet, matchIssueForEpisodeEdit, matchResolvedFindings, renderVolumeFields, renderVolumeIssue, resolveWorldContext, seasonIdByNumberOf, shapeEpisodeResolutions, shapeFindings, shapeSeasonOutlines, shapeVerifyIssues } from './context.js';
import { codedError } from '../../../lib/codedError.js';

export async function generateArcOverview(seriesId, options = {}) {
  const series = await getSeries(seriesId);
  if (series.locked?.arc === true) {
    throw codedError(
      'Arc is locked — unlock it on the Arc Canvas before regenerating',
      ERR_VALIDATION,
    );
  }
  const ctx = await buildArcOverviewContext(series);
  const { content, runId, providerId, model } = await runStagedLLM(
    'pipeline-arc-overview',
    ctx,
    {
      providerOverride: options.providerOverride,
      providerDefault: options.providerDefault,
      modelOverride: options.modelOverride,
      modelDefault: options.modelDefault,
      effortDefault: options.effortDefault,
      onRunCreated: options.onRunCreated,
      onRunSettled: options.onRunSettled,
      returnsJson: true,
      source: 'pipeline-arc-overview',
    },
  );
  // Build the canonical arc + seasons shape from the LLM payload. We send
  // both back to the caller so the route can persist in one updateSeries
  // call (or hand the user a preview before committing).
  // `shape` is the user's Vonnegut pick — the overview prompt doesn't ask
  // the LLM for it, so without this fallback a regenerate would wipe the
  // pick. Mirrors `resolveVerifyIssues` further down.
  const arc = sanitizeArc({
    logline: content?.logline || '',
    summary: content?.summary || '',
    themes: content?.themes,
    protagonistArc: content?.protagonistArc || '',
    shape: content?.shape ?? series.arc?.shape ?? null,
    // The arc-overview prompt doesn't author the reader map — preserve any
    // existing one (like `shape`) so regenerating the arc never silently wipes
    // a reader map the user already built on the next step.
    seriesDesign: series.arc?.seriesDesign,
    readerMap: series.arc?.readerMap ?? null,
    // Same for the ticking clock — the overview prompt doesn't author it, so
    // preserve any existing countdown across a regenerate.
    tickingClock: series.arc?.tickingClock ?? null,
    // The arc-overview prompt DOES author the foreshadowing ledger (#2172) —
    // take the LLM's if present, else preserve any existing one so a regenerate
    // that omits it doesn't silently wipe the seeds.
    foreshadowing: content?.foreshadowing ?? series.arc?.foreshadowing ?? null,
    status: 'draft',
  });
  const seasons = shapeSeasonOutlines(content?.seasonOutlines);
  return {
    arc,
    seasons,
    raw: content,
    runId,
    providerId,
    model,
  };
}

// The reader map is authored AFTER the plot arc is approved, so a frozen arc
// (`locked.arc`, which protects the core arc fields from the arc-overview
// regenerator) must NOT block reader-map work — only the reader-map field lock
// (`locked.arcFields.readerMap`) does. The locked arc is read as INPUT here.
export function assertReaderMapUnlocked(series) {
  if (series.locked?.arcFields?.readerMap === true) {
    throw codedError('Reader map is locked — unlock it before regenerating', ERR_VALIDATION);
  }
}

/**
 * Generate the reader map (audience experience roadmap) from the series arc.
 * Extraction-only like generateArcOverview — returns the sanitized readerMap;
 * the caller persists it by merging into `series.arc` (preserving the other
 * arc fields) via updateSeries.
 */
export async function generateReaderMap(seriesId, options = {}) {
  const series = await getSeries(seriesId);
  assertReaderMapUnlocked(series);
  const ctx = await buildReaderMapContext(series);
  const { content, runId, providerId, model } = await runStagedLLM(
    'story-builder-reader-map',
    ctx,
    {
      providerOverride: options.providerOverride,
      providerDefault: options.providerDefault,
      modelOverride: options.modelOverride,
      modelDefault: options.modelDefault,
      effortDefault: options.effortDefault,
      onRunCreated: options.onRunCreated,
      onRunSettled: options.onRunSettled,
      returnsJson: true,
      source: 'story-builder-reader-map',
    },
  );
  const readerMap = sanitizeReaderMap({
    hooks: content?.hooks,
    payoffs: content?.payoffs,
    beats: content?.beats,
    cliffhangers: content?.cliffhangers,
    status: 'draft',
  });
  // A null sanitize means the LLM returned nothing usable — surface an error
  // rather than letting the caller persist `readerMap: null` over an existing
  // map (silent data loss).
  if (!readerMap) {
    throw codedError('LLM returned an empty reader map — try regenerating', ERR_VALIDATION);
  }
  return { readerMap, raw: content, runId, providerId, model };
}

/**
 * Refine an existing reader map against free-text feedback (the same AI-
 * feedback affordance as image-prompt refine). Returns the regenerated
 * readerMap plus `changes` (a short bullet list) and `rationale`.
 */
export async function refineReaderMap(seriesId, feedback, options = {}) {
  const series = await getSeries(seriesId);
  assertReaderMapUnlocked(series);
  const arc = series.arc || {};
  const { content, rationale, runId, providerId, model } = await runPromptRefineRaw({
    templateName: 'story-builder-reader-map-refine',
    variables: {
      currentReaderMapJson: arc.readerMap ? JSON.stringify(arc.readerMap, null, 2) : '{}',
      feedback: typeof feedback === 'string' ? feedback.trim().slice(0, 4000) : '',
      arcSummary: arc.summary || '',
      protagonistArc: arc.protagonistArc || '',
      shapeGuidance: appendTickingClock(renderArcShapeGuidance(arc.shape) || SHAPE_GUIDANCE_NONE, arc),
      beatKindsCsv: READER_MAP_BEAT_KINDS.join(', '),
    },
    options,
    source: 'story-builder-reader-map-refine',
    logTag: `Story Builder reader-map refine series=${seriesId.slice(0, 8)}`,
  });
  const readerMap = sanitizeReaderMap({ ...content, status: 'draft' });
  // Refine is meant to PRESERVE — never let an empty LLM payload null out the
  // existing map. Fall back to the current reader map when the refine produced
  // nothing usable (mirrors the AGENTS.md absent-vs-empty rule).
  const safeReaderMap = readerMap || arc.readerMap || null;
  if (!safeReaderMap) {
    throw codedError('LLM returned an empty reader map and there is none to preserve', ERR_VALIDATION);
  }
  // When the refine produced nothing usable and we fell back to the existing
  // map, the LLM's `changes`/`rationale` describe an attempt that was DISCARDED
  // — surfacing them would tell the user we applied edits we threw away. Only
  // report changes/rationale when the refined map is the one we're returning.
  const usedRefinedMap = readerMap != null;
  return {
    readerMap: safeReaderMap,
    changes: usedRefinedMap ? trimChanges(content.changes) : [],
    rationale: usedRefinedMap ? rationale : '',
    runId,
    providerId,
    model,
  };
}

/**
 * Refine an existing plot arc's NARRATIVE fields (logline / summary /
 * protagonist arc / themes) against free-text feedback — the AI-feedback
 * affordance the arc step lacked (it only had full regenerate). Deliberately
 * does NOT re-plan seasons or change the Vonnegut shape: the refine prompt
 * authors only the narrative fields, and `shape`/`readerMap` are carried over
 * from the current arc. Returns the merged arc plus `changes` + `rationale`.
 *
 * Honors the absent-vs-intentionally-empty rule: a field the LLM omits or
 * returns empty falls back to the current value (refine PRESERVES; it must
 * never null out an arc the user already has). The same `locked.arc` guard the
 * arc-overview regenerator uses applies.
 */
export async function refineArc(seriesId, feedback, options = {}) {
  const series = await getSeries(seriesId);
  if (series.locked?.arc === true) {
    throw codedError('Arc is locked — unlock it on the Arc Canvas before refining', ERR_VALIDATION);
  }
  const arc = series.arc || {};
  const { content, rationale, runId, providerId, model } = await runPromptRefineRaw({
    templateName: 'story-builder-arc-refine',
    variables: {
      currentLogline: arc.logline || '',
      currentSummary: arc.summary || '',
      currentProtagonistArc: arc.protagonistArc || '',
      currentThemesCsv: Array.isArray(arc.themes) ? arc.themes.join(', ') : '',
      shapeGuidance: appendTickingClock(renderArcShapeGuidance(arc.shape) || SHAPE_GUIDANCE_NONE, arc),
      series: { name: series.name, premise: series.premise },
      feedback: typeof feedback === 'string' ? feedback.trim().slice(0, 4000) : '',
    },
    options,
    source: 'story-builder-arc-refine',
    logTag: `Story Builder arc refine series=${seriesId.slice(0, 8)}`,
  });
  // Merge the refined narrative fields over the current arc, preserving any the
  // LLM omitted (absent) or returned empty (a refine should never blank a field
  // the user already had). `shape`, `readerMap`, and status pass through from
  // the current arc — this pass is narrative-only. sanitizeArc trims/cleans the
  // fields (incl. themes) on the way in, so pass raw values and only choose
  // between the refined value and the current one here.
  const refinedStr = (next, current) => {
    const trimmed = typeof next === 'string' ? next.trim() : '';
    return trimmed || current || '';
  };
  // Clean the candidate themes BEFORE deciding to keep them: an LLM array of
  // only blanks/nulls (`['  ']`, `[null]`) is non-empty but sanitizes to [],
  // which would wipe the existing themes. Fall back to current when the cleaned
  // candidate is empty (preserve, per the absent-vs-empty rule).
  const cleanedCandidateThemes = cleanThemes(content.themes);
  const refinedThemes = cleanedCandidateThemes.length > 0
    ? cleanedCandidateThemes
    : (arc.themes || []);
  const refinedArc = sanitizeArc({
    logline: refinedStr(content.logline, arc.logline),
    summary: refinedStr(content.summary, arc.summary),
    protagonistArc: refinedStr(content.protagonistArc, arc.protagonistArc),
    themes: refinedThemes,
    shape: arc.shape ?? null,
    seriesDesign: arc.seriesDesign,
    readerMap: arc.readerMap ?? null,
    // The arc-refine prompt edits the narrative fields only — preserve the
    // ticking clock (like readerMap/shape) so a refine never wipes it.
    tickingClock: arc.tickingClock ?? null,
    // Same for the foreshadowing ledger — a narrative refine must not wipe it.
    foreshadowing: arc.foreshadowing ?? null,
    status: 'draft',
  });
  // sanitizeArc returns null only when every identifying field is empty — which,
  // because every field above falls back to the current arc, means the current
  // arc was ALSO empty and the LLM added nothing. Nothing to preserve, so error.
  if (!refinedArc) {
    throw codedError('LLM returned an empty arc and there is none to preserve', ERR_VALIDATION);
  }
  return { arc: refinedArc, changes: trimChanges(content.changes), rationale, runId, providerId, model };
}

export async function verifyArc(seriesId, options = {}) {
  const series = await getSeries(seriesId);
  if (!series.arc) {
    throw new ServerError(
      'Series has no arc to verify — run /arc/generate first',
      { status: 400, code: 'PIPELINE_NO_ARC' },
    );
  }
  const ctx = await buildVerifyContext(series, options.preloadedWorld, { spineOnly: options.spineOnly === true });
  const { content, runId, providerId, model } = await runStagedLLM(
    'pipeline-arc-verify',
    ctx,
    {
      providerOverride: options.providerOverride,
      providerDefault: options.providerDefault,
      modelOverride: options.modelOverride,
      modelDefault: options.modelDefault,
      effortDefault: options.effortDefault,
      onRunCreated: options.onRunCreated,
      onRunSettled: options.onRunSettled,
      returnsJson: true,
      source: 'pipeline-arc-verify',
    },
  );
  const issues = shapeVerifyIssues(content?.issues);
  return { issues, raw: content, runId, providerId, model };
}

export async function buildVolumeVerifyContext(series, season, preloadedWorld, { synopsisOnly = false } = {}) {
  const [allIssues, base] = await Promise.all([
    listIssues({ seriesId: series.id }),
    buildArcBaseContext(series, preloadedWorld),
  ]);
  const volumeIssues = allIssues
    .filter((iss) => iss.seasonId === season.id)
    .sort(compareIssuesByPosition)
    .map((issue) => renderVolumeIssue(issue, { synopsisOnly }));
  // Volume-specific curve placement layered on top of base's arc-wide
  // shapeGuidance so the verifier can flag "this volume inverts the expected
  // fortune at its position."
  const totalSeasons = (series.seasons || []).length || 1;
  const volumeShapePosition = renderArcShapePositionSummary(series.arc?.shape, season.number, totalSeasons)
    || '(no story shape selected — do not flag shape adherence for this volume)';
  return {
    ...base,
    volume: renderVolumeFields(season),
    volumeShapePosition,
    neighborsJson: JSON.stringify(buildNeighborVolumes(series.seasons, season.id), null, 2),
    volumeIssuesJson: JSON.stringify(volumeIssues, null, 2),
  };
}

// Verify a single volume / season — the deeper, narrower counterpart to
// verifyArc. The cross-volume pass operates at synopsis depth across the
// whole arc; this pass operates at beat depth (when beats exist) across one
// volume. Issues without beats are checked at synopsis depth — the prompt
// is explicitly aware of which depth each issue is at, so a partially-
// expanded volume can still be validated mid-workflow.
export async function verifyVolume(seriesId, seasonId, options = {}) {
  const series = await getSeries(seriesId);
  if (!series.arc) {
    throw new ServerError(
      'Series has no arc — run /arc/generate first before verifying a volume',
      { status: 400, code: 'PIPELINE_NO_ARC' },
    );
  }
  const season = await getSeason(seriesId, seasonId);
  const ctx = await buildVolumeVerifyContext(series, season, options.preloadedWorld, {
    synopsisOnly: options.synopsisOnly === true,
  });
  const { content, runId, providerId, model } = await runStagedLLM(
    'pipeline-volume-verify',
    ctx,
    {
      providerOverride: options.providerOverride,
      providerDefault: options.providerDefault,
      modelOverride: options.modelOverride,
      modelDefault: options.modelDefault,
      effortDefault: options.effortDefault,
      onRunCreated: options.onRunCreated,
      onRunSettled: options.onRunSettled,
      returnsJson: true,
      source: 'pipeline-volume-verify',
    },
  );
  const issues = shapeVerifyIssues(content?.issues);
  return { issues, raw: content, runId, providerId, model, seasonId };
}

/**
 * Split one auto-resolve response into the edits that actually name a finding
 * the round was handed, and the ones to drop (#3724). Pure.
 *
 * Every entry in `arc` / `characterArcs[]` / `seasons[]` / `episodes[]` has to carry
 * `resolves: ["f2", …]` naming at least one input finding — an edit that names
 * none can't be closing anything, so applying it is all blast radius and no
 * benefit. Returns `{ legacy, arc, arcDropped, characterArcs,
 * characterArcsDropped, seasons, seasonsDropped, episodes, episodesDropped,
 * episodesOutOfScope }`.
 *
 * `spineOnly` drops every episode edit regardless of what it names (#3789): a
 * spine round is judged against an episode-empty plan, so an episode rewrite
 * cannot close the finding it declares — it only mutates records the gate never
 * read. Counted separately from `episodesDropped` because the two are different
 * diagnoses (wrong scope vs. named no finding), and enforced here rather than
 * trusting the prompt alone so a customized/stale installed template can't
 * re-open the blast radius.
 *
 * `legacy` is the escape hatch for an install whose `pipeline-arc-resolve.md`
 * was customized before #3724 and therefore never got the migration: when NOT
 * ONE entry in the whole response declares a `resolves` array, the model is
 * plainly running the old contract, and dropping everything would silently turn
 * auto-resolve into a no-op that burns a round per pass. Those responses are
 * applied unkeyed (still as a sparse patch, which is strictly safer than the
 * old full-list rewrite) and logged. A response that keys SOME of its edits is
 * on the new contract, so its unkeyed entries are genuine drops.
 */
export function selectFindingKeyedEdits(content, findings, { spineOnly = false } = {}) {
  const validIds = findingIdSet(findings);
  const isEdit = (e) => !!e && typeof e === 'object';
  const arcEdit = isEdit(content?.arc) ? content.arc : null;
  const characterArcsRaw = (Array.isArray(content?.characterArcs) ? content.characterArcs : []).filter(isEdit);
  const seasonsRaw = (Array.isArray(content?.seasons) ? content.seasons : []).filter(isEdit);
  const episodesRaw = (Array.isArray(content?.episodes) ? content.episodes : []).filter(isEdit);
  const legacy = ![arcEdit, ...characterArcsRaw, ...seasonsRaw, ...episodesRaw]
    .some((e) => e && matchResolvedFindings(e, validIds).declared);
  const targeted = (raw) => legacy || matchResolvedFindings(raw, validIds).matched.length > 0;
  const characterArcs = characterArcsRaw.filter(targeted);
  const seasons = seasonsRaw.filter(targeted);
  const episodes = spineOnly ? [] : episodesRaw.filter(targeted);
  return {
    legacy,
    arc: arcEdit && targeted(arcEdit) ? arcEdit : null,
    arcDropped: !!arcEdit && !targeted(arcEdit),
    characterArcs,
    characterArcsDropped: characterArcsRaw.length - characterArcs.length,
    seasons,
    seasonsDropped: seasonsRaw.length - seasons.length,
    episodes,
    episodesDropped: spineOnly ? 0 : episodesRaw.length - episodes.length,
    episodesOutOfScope: spineOnly ? episodesRaw.length : 0,
  };
}

const characterArcKey = (arc) => {
  const characterId = typeof arc?.characterId === 'string' ? arc.characterId.trim() : '';
  if (characterId) return `id:${characterId}`;
  const characterName = typeof arc?.characterName === 'string' ? arc.characterName.trim().toLowerCase() : '';
  return characterName ? `name:${characterName}` : '';
};

const CHARACTER_ARC_PATCH_FIELDS = Object.freeze([
  'want', 'need', 'startState', 'endState', 'status',
]);
const TRANSITION_PATCH_FIELDS = Object.freeze([
  'kind', 'label', 'atIssue', 'atSceneAnchor', 'note',
]);

/**
 * Apply finding-keyed per-character arc edits as sparse patches. Existing
 * character and transition identifiers are required and preserved: an arc
 * verifier finding must never mint a new cast arc or replace every transition
 * merely because the model corrected one milestone.
 */
export function mergeCharacterArcPatches(existingArcs, patches) {
  const current = sanitizeCharacterArcList(existingArcs);
  if (!Array.isArray(patches) || patches.length === 0) return current;
  const patchByKey = new Map(patches.map((patch) => [characterArcKey(patch), patch]).filter(([key]) => key));
  const merged = current.map((arc) => {
    const patch = patchByKey.get(characterArcKey(arc));
    if (!patch) return arc;
    const next = { ...arc };
    for (const field of CHARACTER_ARC_PATCH_FIELDS) {
      if (field in patch) next[field] = patch[field];
    }
    if (Array.isArray(patch.transitions)) {
      const transitionPatches = new Map(patch.transitions
        .filter((transition) => transition && typeof transition === 'object' && typeof transition.id === 'string')
        .map((transition) => [transition.id, transition]));
      next.transitions = arc.transitions.flatMap((transition) => {
        const transitionPatch = transitionPatches.get(transition.id);
        if (!transitionPatch) return [transition];
        if (transitionPatch.delete === true) return [];
        const updated = { ...transition };
        for (const field of TRANSITION_PATCH_FIELDS) {
          if (field in transitionPatch) updated[field] = transitionPatch[field];
        }
        return [updated];
      });
    }
    return next;
  });
  return sanitizeCharacterArcList(merged);
}

const EXACT_TEXT_PATCH_MODE = 'exact-text-v1';
const EXACT_TEXT_EDITS_MAX = 12;

/**
 * Apply bounded exact-match replacements to one persisted long-form field.
 *
 * Arc verification findings are usually sentence-local, but `synopsis` and
 * `summary` are monolithic strings. Asking the resolver to return either field
 * wholesale gave a one-sentence repair thousands of unrelated words of blast
 * radius, and an over-limit rewrite could then be truncated mid-sentence by the
 * canonical sanitizer. Exact replacements keep the untouched text byte-for-byte
 * stable. Ambiguous/missing anchors are skipped rather than guessed at. Check
 * capacity after all replacements: an early expansion may rely on a later
 * compression. If the final field exceeds its limit, preserve the original
 * field instead of persisting a partial version of the proposed change.
 */
export function applyExactTextEdits(current, rawEdits, maxLength) {
  const original = typeof current === 'string' ? current : '';
  if (!Array.isArray(rawEdits) || rawEdits.length === 0) {
    return { value: original, applied: 0, rejected: 0 };
  }
  let value = original;
  let applied = 0;
  let rejected = 0;
  for (const raw of rawEdits.slice(0, EXACT_TEXT_EDITS_MAX)) {
    const find = typeof raw?.find === 'string' ? raw.find : '';
    const replacement = typeof raw?.replace === 'string' ? raw.replace : null;
    const first = find ? value.indexOf(find) : -1;
    const duplicate = first >= 0 && value.indexOf(find, first + find.length) >= 0;
    const replacesWholeLongField = find.length === value.length
      && maxLength > ARC_LIMITS.SEASON_ENDING_HOOK_MAX;
    if (!find || replacement == null || first < 0 || duplicate || replacesWholeLongField) {
      rejected += 1;
      continue;
    }
    value = `${value.slice(0, first)}${replacement}${value.slice(first + find.length)}`;
    applied += 1;
  }
  rejected += Math.max(0, rawEdits.length - EXACT_TEXT_EDITS_MAX);
  if (value.length > maxLength) {
    return { value: original, applied: 0, rejected: rejected + applied };
  }
  return { value, applied, rejected };
}

// Two stored values are the same edit-wise. `undefined` and `null` are one
// value here: an omitted field and an explicit null both mean "no change I can
// count", and the appliers treat them identically.
const sameStored = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);

// Countdown repairs follow the same sparse, existing-ID contract as character
// transitions. A finding cannot delete the clock or replace its reminder list.
const CLOCK_PATCH_FIELDS = ['label', 'stakes', 'plantedAtArcPosition', 'dueAtArcPosition'];
function mergeTickingClockPatch(current, patch) {
  if (!current || !patch || typeof patch !== 'object' || Array.isArray(patch)) {
    return { value: current, changes: 0 };
  }
  const next = { ...current };
  for (const [field, max] of [['label', TICKING_CLOCK_LIMITS.LABEL_MAX], ['stakes', TICKING_CLOCK_LIMITS.STAKES_MAX]]) {
    if (typeof patch[field] === 'string' && patch[field].length <= max) next[field] = patch[field];
  }
  for (const field of ['plantedAtArcPosition', 'dueAtArcPosition']) {
    if (patch[field] === null || Number.isFinite(patch[field])) next[field] = patch[field];
  }
  const byId = new Map((Array.isArray(patch.reminders) ? patch.reminders : [])
    .filter((r) => r && typeof r.id === 'string').map((r) => [r.id, r]));
  next.reminders = (current.reminders || []).map((reminder) => {
    const edit = byId.get(reminder.id);
    if (!edit) return reminder;
    const updated = { ...reminder };
    if (edit.atIssue === null || Number.isFinite(edit.atIssue)) updated.atIssue = edit.atIssue;
    if (typeof edit.note === 'string' && edit.note.length <= TICKING_CLOCK_LIMITS.REMINDER_NOTE_MAX) updated.note = edit.note;
    // Clearing both fields would make the canonical sanitizer delete the row.
    return updated.atIssue == null && !updated.note.trim() ? reminder : updated;
  });
  const value = sanitizeTickingClock(next) || current;
  const changes = CLOCK_PATCH_FIELDS.filter((field) => !sameStored(value[field], current[field])).length
    + value.reminders.filter((reminder, index) => !sameStored(reminder, current.reminders[index])).length;
  return { value, changes };
}

// The fields a resolve response can change on the arc / on a volume — the same
// surface the two appliers below spread (`sanitizeArc` at the arc, the season
// patch inside `resolveVerifyIssues`), restated here because those do per-field
// coercion rather than list iteration. THEY MOVE TOGETHER: a newly patchable
// field the appliers accept but this list omits is a change the isolated bound
// cannot see. Long prose is paired `[direct, editsKey, limit]` because under
// `exact-text-v1` it lands ONLY through the `*Edits` array and a
// directly-returned string is ignored (and vice versa) — counting the ignored
// spelling would reject a candidate over an edit that was never going to be
// persisted.
const ARC_SHORT_FIELDS = Object.freeze(['logline', 'themes', 'shape', 'foreshadowing']);
const ARC_LONG_FIELDS = Object.freeze([
  ['summary', 'summaryEdits', ARC_LIMITS.SUMMARY_MAX],
  ['protagonistArc', 'protagonistArcEdits', ARC_LIMITS.PROTAGONIST_ARC_MAX],
]);
const SEASON_SHORT_FIELDS = Object.freeze(['title', 'number', 'logline', 'episodeCountTarget', 'themes']);
const SEASON_LONG_FIELDS = Object.freeze([
  ['synopsis', 'synopsisEdits', ARC_LIMITS.SEASON_SYNOPSIS_MAX],
  ['endingHook', 'endingHookEdits', ARC_LIMITS.SEASON_ENDING_HOOK_MAX],
]);

// ---------------------------------------------------------------------------
// Resolve-outcome accounting (#3843). `applied` says a pass wrote SOMETHING; it
// never said what, and the gate's telemetry reported only `episodesEdited` — a
// count the arc-SPINE resolver can never move, because that altitude may not
// touch episodes at all. A spine round that rewrote the arc and two volumes and
// took the blocking set from 5 to 2 therefore reported `episodesEdited: 0`,
// indistinguishable from a round that wrote nothing. These supply the missing
// halves: per-record counts of what landed, and a categorical reason when
// nothing did. Numbers and enum values only — it rides into the retained
// diagnosis log, which must never carry manuscript text or resolver prose.
// ---------------------------------------------------------------------------

// The arc surface a resolve pass can rewrite — derived from the two lists the
// isolated-candidate bound already keeps in step with the appliers, so a newly
// patchable field is counted the moment it is accepted rather than after
// someone remembers a third list. Countdown patches have their own sparse
// applier; readerMap and status are not resolver-authored fields.
const RESOLVE_ARC_FIELDS = Object.freeze([...ARC_SHORT_FIELDS, ...ARC_LONG_FIELDS.map(([direct]) => direct), 'tickingClock']);

const changedFieldCount = (next, prev, fields) => fields
  .filter((field) => !sameStored(next?.[field], prev?.[field])).length;

// Entries in `next` that match no entry in `prev` — i.e. minted or rewritten.
// Deletion is not reachable on either list this counts (volumes ride through as
// a sparse patch, character arcs merge in place), so added/changed is a complete
// account of the pass's writes.
const changedEntryCount = (next, prev) => {
  const before = new Set((prev || []).map((entry) => JSON.stringify(entry)));
  return (next || []).filter((entry) => !before.has(JSON.stringify(entry))).length;
};

const NO_MUTATIONS = Object.freeze({
  arcFieldsEdited: 0, volumesEdited: 0, characterArcsEdited: 0, episodesEdited: 0,
});

/**
 * Why a resolve pass wrote nothing, as ONE of these values. Categorical so the
 * stall diagnosis can separate the cases it kept conflating: the resolver
 * answered but its anchors no longer matched (`exact-edits-rejected`), it
 * answered at an altitude this gate forbids (`edits-out-of-scope`), or it
 * declined to propose anything at all (`no-edits-returned`) — a content-level
 * refusal no amount of extra rounds will fix. Exported because the diagnosis
 * prompts have to explain every value they can be handed; the contract test in
 * `arcPlanner.test.js` fails when a value is missing from that legend.
 */
export const RESOLVE_NO_CHANGE_REASONS = Object.freeze([
  'no-findings',
  'isolated-candidate-rejected',
  'exact-edits-rejected',
  'edits-matched-existing',
  'edits-out-of-scope',
  'edits-named-no-finding',
  'no-edits-returned',
]);

const noChangeReasonFor = (edits, rejectedExactEdits) => {
  if (rejectedExactEdits > 0) return 'exact-edits-rejected';
  const proposed = (edits.arc ? 1 : 0) + edits.characterArcs.length + edits.seasons.length + edits.episodes.length;
  // Something survived selection and was applied, yet the store did not move:
  // the resolver re-authored text the plan already held.
  if (proposed > 0) return 'edits-matched-existing';
  if (edits.episodesOutOfScope > 0) return 'edits-out-of-scope';
  const dropped = (edits.arcDropped ? 1 : 0) + edits.characterArcsDropped + edits.seasonsDropped + edits.episodesDropped;
  if (dropped > 0) return 'edits-named-no-finding';
  return 'no-edits-returned';
};

// How many stored values a patch would actually change. Echoed fields that
// already match the record do not count: the resolve prompt asks for `id` and
// `number` to be repeated, so "field present" is not "field changed". Exact-text
// replacements are counted by running the real applier — one `{find, replace}`
// pair is one causal change, and an anchor `applyExactTextEdits` would reject
// (missing, ambiguous, over-limit) is none, so the count is the patch's
// persisted effect rather than the size of what the model asked for.
function countFieldChanges(patch, current, { shortFields, longFields = [], exactTextMode = false }) {
  let changes = 0;
  for (const field of shortFields) {
    if (patch?.[field] === undefined) continue;
    if (!sameStored(patch[field], current?.[field])) changes += 1;
  }
  for (const [direct, editsKey, limit] of longFields) {
    if (exactTextMode) {
      changes += applyExactTextEdits(current?.[direct] || '', patch?.[editsKey], limit).applied;
    } else if (typeof patch?.[direct] === 'string' && !sameStored(patch[direct], current?.[direct] ?? '')) {
      changes += 1;
    }
  }
  return changes;
}

// Same accounting one altitude down, for a per-character arc patch: changed
// top-level fields plus ONE per patched existing transition (a transition is the
// causal unit — correcting its label and its issue anchor together is one
// milestone repair). Transitions the merge would discard anyway (no `id`, or an
// id no stored transition carries) are not changes.
function countCharacterArcChanges(patch, current) {
  let changes = countFieldChanges(patch, current, { shortFields: CHARACTER_ARC_PATCH_FIELDS });
  const byId = new Map((current?.transitions || []).map((t) => [t.id, t]));
  for (const raw of (Array.isArray(patch?.transitions) ? patch.transitions : [])) {
    if (!raw || typeof raw !== 'object' || typeof raw.id !== 'string') continue;
    const existing = byId.get(raw.id);
    if (!existing) continue;
    if (raw.delete === true) { changes += 1; continue; }
    if (TRANSITION_PATCH_FIELDS.some((f) => raw[f] !== undefined && !sameStored(raw[f], existing[f]))) changes += 1;
  }
  return changes;
}

/**
 * Decide whether an isolated (single-finding) resolve candidate is bounded
 * enough to persist. Pure. Returns a short rejection reason, or null when the
 * candidate is exactly ONE causal patch: one owner record, one changed field on
 * it — one exact-text replacement, one short scalar, or one existing
 * character-transition patch.
 *
 * This is what makes the arc gate's per-finding fallback (#3780) bounded.
 * Isolating the FINDING never isolated the EDIT: every entry in a single-finding
 * response trivially names that finding, so `selectFindingKeyedEdits` passed
 * whole-arc rewrites and each "isolated" attempt regressed the blocking set
 * exactly like the whole-set pass it escalated from.
 *
 * Checked BEFORE anything is written, so an over-reaching candidate costs its
 * own resolve call and nothing else: no rewrite to undo, and no verification
 * round billed to discover that the rewrite was worse. The post-apply verifier
 * and rollback in the gate stay exactly as they are — this is a narrower net in
 * front of them, not a replacement for them.
 *
 * Counting is against the STORED record, not the response's shape: an echoed
 * `id`/`number`/title is not a change, and an edit the appliers would discard
 * (an unmatched character arc, a transition with no id, an unanchored exact-text
 * replacement, the ignored spelling of a long prose field) is not one either —
 * rejecting on those would fail candidates that were already going to be no-ops.
 */
export function isolatedCandidateRejection(edits, { exactTextMode = false, series = {}, matchedSeasons, issues = [] } = {}) {
  const touched = [];
  if (edits.arc) {
    const changes = countFieldChanges(edits.arc, series.arc || {}, {
      shortFields: ARC_SHORT_FIELDS, longFields: ARC_LONG_FIELDS, exactTextMode,
    }) + mergeTickingClockPatch(series.arc?.tickingClock, edits.arc.tickingClock).changes;
    if (changes) touched.push({ label: 'the arc', changes });
  }
  if (edits.characterArcs.length) {
    const arcByKey = new Map(sanitizeCharacterArcList(series.characterArcs).map((a) => [characterArcKey(a), a]));
    for (const patch of edits.characterArcs) {
      // An unmatched key mints nothing (mergeCharacterArcPatches drops it), so
      // it is not a record this candidate touches.
      const existing = arcByKey.get(characterArcKey(patch));
      if (!existing) continue;
      const changes = countCharacterArcChanges(patch, existing);
      if (changes) touched.push({ label: `character arc ${existing.characterId || 'unkeyed'}`, changes });
    }
  }
  const matched = matchedSeasons || matchProposedSeasons(series.seasons, edits.seasons);
  for (let idx = 0; idx < edits.seasons.length; idx += 1) {
    const existing = matched[idx];
    // An unmatched volume proposal MINTS one. A new volume is never the minimal
    // causal patch for a single finding, and it is the one edit here that can't
    // be undone by putting a field back.
    if (!existing) return 'it would add a new volume instead of patching one';
    const changes = countFieldChanges(edits.seasons[idx], existing, {
      shortFields: SEASON_SHORT_FIELDS, longFields: SEASON_LONG_FIELDS, exactTextMode,
    });
    if (changes) touched.push({ label: `volume ${existing.number ?? '?'}`, changes });
  }
  // Shaped by the applier's own admission rule, so an entry `applyEpisodeResolutions`
  // would drop (no integer episode number, past its cap) is not counted as a
  // record this candidate touches.
  for (const episode of shapeEpisodeResolutions(edits.episodes)) {
    // A custom profile and its two targets are one indivisible length choice.
    const existing = matchIssueForEpisodeEdit(issues, seasonIdByNumberOf(series), episode);
    const changes = Number(Boolean(episode.synopsis) && (!existing || episode.synopsis !== existing.stages?.idea?.input))
      + Number('arcRole' in episode && (!existing || episode.arcRole !== existing.arcRole))
      + Number('lengthProfile' in episode && (!existing || EPISODE_METADATA_FIELDS.slice(1)
        .some((field) => Object.hasOwn(episode, field) && episode[field] !== existing[field])));
    if (!changes) continue;
    touched.push({ label: `episode ${episode.episodeNumber}`, changes });
  }
  if (touched.length === 0) return 'it changed nothing this gate would persist';
  if (touched.length > 1) {
    return `it edits ${touched.length} records (${touched.map((t) => t.label).join(', ')}) — an isolated repair may change only one`;
  }
  const [only] = touched;
  if (only.changes > 1) {
    return `it changes ${only.changes} fields on ${only.label} — an isolated repair may change only one`;
  }
  return null;
}


// Character arcs are patched in place by existing IDs; episode (issue) records
// are never CREATED or DELETED here, and their drafted scripts are never
// clobbered — a full-arc round may rewrite an episode's planning synopsis or
// an unproduced issue's role/length (see `applyEpisodeResolutions`). If a
// finding's only actionable resolution would require deleting issues, the LLM
// is told to flag that in the response's `notes` field rather than executing it.
// `options.findings` empty / omitted = re-run verify first and resolve
// everything it returns. `options.avoid` is the optional "a previous attempt at
// these same findings authored THESE and was reverted" list (see
// buildResolveContext) — set only by a corrective pass.
// `options.spineOnly` mirrors verifyArc's pre-episode arc-spine mode: the
// resolver sees the same episode-empty editable tree and may only patch the series arc,
// per-character arcs, and volumes (#3789). It is a PAIRING constraint, not an independent knob — it
// must match the verify that produced `options.findings`, or the resolver
// answers at an altitude the gate never judged. Episode-synopsis corrections
// stay available for the later full arc gate. Existing episode plans are
// read-only references here so a summary repair preserves their established
// events; their presence does not expand this checkpoint's write scope.
export async function resolveVerifyIssues(seriesId, options = {}) {
  const spineOnly = options.spineOnly === true;
  const isolated = options.isolated === true;
  const series = await getSeries(seriesId);
  if (!series.arc) {
    throw new ServerError(
      'Series has no arc to resolve — run /arc/generate first',
      { status: 400, code: 'PIPELINE_NO_ARC' },
    );
  }
  // Resolve rewrites arc + seasons in place, so the lock gates this too.
  // Verify (read-only) stays enabled — the user can act on findings manually.
  if (series.locked?.arc === true) {
    throw new ServerError(
      'Arc is locked — unlock it before rewriting the arc',
      { status: 400, code: ERR_VALIDATION },
    );
  }

  // Load the world once and thread it through verify + resolve so the
  // refresh-then-resolve path doesn't hit the filesystem twice for the same
  // world.
  const world = await resolveWorldContext(series);

  let findings = shapeFindings(options.findings);
  if (!findings.length) {
    // The spread is load-bearing: it carries `spineOnly` into the refresh, which
    // is the one path where the verify and the resolve it feeds are the same
    // call and so must not drift apart in altitude.
    const fresh = await verifyArc(seriesId, { ...options, preloadedWorld: world });
    findings = fresh.issues || [];
    if (!findings.length) {
      return {
        series,
        applied: false,
        notes: 'No findings to resolve',
        findings: [],
        mutations: NO_MUTATIONS,
        noChangeReason: 'no-findings',
      };
    }
  }

  // `options.avoid` carries the findings a reverted earlier attempt at these
  // same findings authored, so a corrective pass is told what NOT to re-create
  // instead of re-running the identical prompt and regressing identically.
  const ctx = await buildResolveContext(series, findings, world, { avoid: options.avoid, spineOnly, isolated });
  const { content, runId, providerId, model } = await runStagedLLM(
    'pipeline-arc-resolve',
    ctx,
    {
      providerOverride: options.providerOverride,
      providerDefault: options.providerDefault,
      modelOverride: options.modelOverride,
      modelDefault: options.modelDefault,
      effortDefault: options.effortDefault,
      onRunCreated: options.onRunCreated,
      onRunSettled: options.onRunSettled,
      returnsJson: true,
      source: 'pipeline-arc-resolve',
    },
  );

  // Keep only the edits that name a finding this round was handed (#3724). An
  // untargeted rewrite is pure blast radius: it can't close anything, and every
  // volume it touches is a chance to author the contradiction the next verify
  // files as a brand-new blocker.
  const edits = selectFindingKeyedEdits(content, findings, { spineOnly });
  const exactTextMode = content?.patchMode === EXACT_TEXT_PATCH_MODE;
  // Only worth saying when there is actually something to apply unkeyed — a
  // response that proposed NO edits reads as legacy too, and warning about a
  // stale prompt there would be a lie.
  if (edits.legacy && (edits.arc || edits.characterArcs.length || edits.seasons.length || edits.episodes.length)) {
    console.log(`⚠️ arc-resolve: response carries no resolves[] — applying it unkeyed (installed pipeline-arc-resolve.md predates #3724)`);
  }
  if (edits.arcDropped) {
    console.log(`⚠️ arc-resolve: dropped the arc-level edit — it named no input finding`);
  }
  if (edits.characterArcsDropped || edits.seasonsDropped || edits.episodesDropped) {
    console.log(`⚠️ arc-resolve: dropped ${edits.characterArcsDropped} character arc + ${edits.seasonsDropped} volume + ${edits.episodesDropped} episode edit(s) naming no input finding`);
  }
  if (edits.episodesOutOfScope) {
    console.log(`⚠️ arc-resolve: discarded ${edits.episodesOutOfScope} episode edit(s) — the arc-spine gate resolves at arc/volume scope only`);
  }

  // What every return below carries regardless of whether the candidate landed.
  const runMeta = {
    notes: typeof content?.notes === 'string' ? content.notes.trim().slice(0, 2000) : '',
    findings,
    runId,
    providerId,
    model,
  };

  // Which existing volume each proposal rewrites. Resolved once: the isolated
  // check needs it to tell a patch from a mint, and the season merge below needs
  // the same answer.
  const matchedExisting = matchProposedSeasons(series.seasons, edits.seasons);

  // The isolated fallback's candidate is judged BEFORE anything is written: a
  // candidate that spans records or fields is discarded whole, so it costs its
  // own resolve call and neither a rewrite to undo nor a verification round to
  // discover the damage. Reported as a plain unapplied result — the shape the
  // gate already reads for "nothing was written" — with the bound it broke as
  // the reason. The post-apply verifier and rollback still judge everything that
  // DOES get through.
  const isolationRejected = isolated
    ? isolatedCandidateRejection(edits, {
      exactTextMode, series, matchedSeasons: matchedExisting,
      issues: edits.episodes.length ? await listIssues({ seriesId }) : [],
    })
    : null;
  if (isolationRejected) {
    console.log(`⚠️ arc-resolve: discarded an isolated repair candidate — ${isolationRejected}`);
    return {
      series,
      applied: false,
      reason: isolationRejected,
      patchMode: exactTextMode ? 'exact-text-v1' : null,
      rejectedExactEdits: 0,
      episodesResolved: [],
      mutations: NO_MUTATIONS,
      noChangeReason: 'isolated-candidate-rejected',
      ...runMeta,
    };
  }


  const arcSummary = exactTextMode
    ? applyExactTextEdits(series.arc.summary || '', edits.arc?.summaryEdits, ARC_LIMITS.SUMMARY_MAX)
    : { value: edits.arc?.summary || series.arc.summary || '', applied: 0, rejected: 0 };
  const protagonistArc = exactTextMode
    ? applyExactTextEdits(series.arc.protagonistArc || '', edits.arc?.protagonistArcEdits, ARC_LIMITS.PROTAGONIST_ARC_MAX)
    : { value: edits.arc?.protagonistArc ?? series.arc.protagonistArc ?? '', applied: 0, rejected: 0 };
  let rejectedExactEdits = arcSummary.rejected + protagonistArc.rejected;
  const arc = sanitizeArc({
    logline: edits.arc?.logline || series.arc.logline || '',
    summary: arcSummary.value,
    themes: edits.arc?.themes ?? series.arc.themes,
    protagonistArc: protagonistArc.value,
    shape: edits.arc?.shape ?? series.arc.shape ?? null,
    // The resolve prompt doesn't author the reader map — preserve any existing
    // one so auto-resolve never silently wipes a reader map the user already
    // built on the next step. Mirrors `generateArcOverview` above.
    seriesDesign: series.arc?.seriesDesign,
    readerMap: series.arc?.readerMap ?? null,
    // A sparse repair can move existing countdown beats without replacing them.
    tickingClock: mergeTickingClockPatch(series.arc?.tickingClock, edits.arc?.tickingClock).value ?? null,
    // The resolve prompt doesn't author the foreshadowing ledger — take it if
    // present, else preserve any existing one so auto-resolve never wipes it.
    foreshadowing: edits.arc?.foreshadowing ?? series.arc?.foreshadowing ?? null,
    status: 'draft',
  });

  // Round-trip the LLM's seasons through `buildSeason` if they include a
  // brand-new entry (no `id`), otherwise preserve the existing `id` so child
  // issues still join their season cleanly. The sanitizer enforces the
  // canonical shape regardless.
  //
  // `seasons[]` is a SPARSE PATCH LIST (#3724), not the full volume lineup: the
  // response carries only the volumes the resolver actually edited, and every
  // existing volume it left out rides through untouched below. That removes the
  // old "omit a volume and it is deleted" footgun — deletion is now an explicit
  // `notes` recommendation, matching how episode deletion already worked.
  const proposedSeasons = edits.seasons;
  // `matchedExisting` (resolved above) pairs each proposal with the existing
  // record it rewrites BEFORE minting. The resolve prompt frequently returns a
  // rewritten volume WITHOUT echoing its `id`; matching on id alone read that as
  // a brand-new season and minted one. With `preserveDroppedSeasons` on (the
  // autopilot's unlock-for-run mode) the original was then re-inserted alongside
  // the mint — so every auto-resolve round ADDED a duplicate "Volume 1" instead
  // of clearing a finding, and arc-verify could never converge. See the
  // divergence pause on 2026-08-09.
  // Patched rewrites keyed by the record they land on, plus the genuinely-new
  // volumes to append. Untouched existing volumes are carried through verbatim.
  const patchedById = new Map();
  const mintedSeasons = [];
  proposedSeasons.forEach((raw, idx) => {
    const existing = matchedExisting[idx];
    if (existing) {
      const synopsis = exactTextMode
        ? applyExactTextEdits(existing.synopsis || '', raw.synopsisEdits, ARC_LIMITS.SEASON_SYNOPSIS_MAX)
        : { value: typeof raw.synopsis === 'string' ? raw.synopsis : existing.synopsis, applied: 0, rejected: 0 };
      const endingHook = exactTextMode
        ? applyExactTextEdits(existing.endingHook || '', raw.endingHookEdits, ARC_LIMITS.SEASON_ENDING_HOOK_MAX)
        : { value: typeof raw.endingHook === 'string' ? raw.endingHook : existing.endingHook, applied: 0, rejected: 0 };
      if (synopsis.rejected || endingHook.rejected) {
        console.log(`⚠️ arc-resolve: skipped ${synopsis.rejected + endingHook.rejected} ambiguous or over-limit exact text edit(s) for volume ${existing.number}`);
      }
      rejectedExactEdits += synopsis.rejected + endingHook.rejected;
      patchedById.set(existing.id, sanitizeSeason({
        ...existing,
        title: typeof raw.title === 'string' ? raw.title : existing.title,
        number: Number.isFinite(raw.number) ? raw.number : existing.number,
        logline: typeof raw.logline === 'string' ? raw.logline : existing.logline,
        synopsis: synopsis.value,
        endingHook: endingHook.value,
        episodeCountTarget: Number.isFinite(raw.episodeCountTarget)
          ? raw.episodeCountTarget
          : existing.episodeCountTarget,
        themes: Array.isArray(raw.themes) ? raw.themes : existing.themes,
      }));
      return;
    }
    const minted = buildSeason({
      number: raw?.number,
      title: raw?.title,
      logline: raw?.logline,
      synopsis: raw?.synopsis,
      endingHook: raw?.endingHook,
      episodeCountTarget: raw?.episodeCountTarget,
    });
    if (minted) mintedSeasons.push(minted);
  });

  const seasons = sanitizeSeasonList([
    ...(series.seasons || []).map((s) => patchedById.get(s.id) || s),
    ...mintedSeasons,
  ]);

  // `preserveDroppedSeasons` (autopilot unlock-for-run) rides through so an
  // auto-resolve can rewrite a volume but never delete one — see the option's
  // contract on commitSeasonsWithRemap.
  const arcOrSeasonsChanged = JSON.stringify(arc) !== JSON.stringify(series.arc)
    || JSON.stringify(seasons) !== JSON.stringify(series.seasons || []);
  const { series: updated } = arcOrSeasonsChanged
    ? await commitSeasonsWithRemap(
      series,
      { arc, seasons },
      { preserveDroppedSeasons: options.preserveDroppedSeasons === true },
    )
    : { series };

  const characterArcs = mergeCharacterArcPatches(updated.characterArcs, edits.characterArcs);
  const characterArcsChanged = !sameStored(characterArcs, updated.characterArcs || []);
  const resolvedSeries = characterArcsChanged
    ? await updateSeries(seriesId, { characterArcs })
    : updated;

  // Apply any episode-level synopsis corrections the resolver returned. This is
  // the heal capability that lets episode-scoped findings converge: when a
  // contradiction originates inside one episode's planning synopsis (e.g. it
  // stages an event a later volume reserves as its own "first"), the only fix is
  // to rewrite that episode — the volume/arc layer can't make it go away. Done
  // here (after the arc+season commit) against the freshest issue set.
  const episodesResolved = await applyEpisodeResolutions(
    seriesId,
    resolvedSeries,
    shapeEpisodeResolutions(edits.episodes),
  );

  const episodesChanged = episodesResolved.some((entry) => !entry.skipped);
  const applied = arcOrSeasonsChanged || characterArcsChanged || episodesChanged;
  if (!applied && rejectedExactEdits) {
    console.log(`⚠️ arc-resolve: response made no applicable change after ${rejectedExactEdits} exact text edit(s) were rejected`);
  }

  // What this pass actually wrote, per record kind — the whole account in one
  // place, so a fifth record kind is added here and nowhere else. `series.*` is
  // the state as it stood BEFORE the commit above, so these describe this call's
  // writes and nothing else, and the two `*Changed` flags gate the counting: a
  // pass that moved nothing needs no per-record comparison to prove it.
  // Episodes ride the same manifest the rollback is driven by, so an edit that
  // was skipped or failed is never counted as written.
  const mutations = {
    arcFieldsEdited: arcOrSeasonsChanged ? changedFieldCount(arc, series.arc, RESOLVE_ARC_FIELDS) : 0,
    volumesEdited: arcOrSeasonsChanged ? changedEntryCount(seasons, series.seasons) : 0,
    characterArcsEdited: characterArcsChanged ? changedEntryCount(characterArcs, updated.characterArcs) : 0,
    episodesEdited: resolvedEpisodeEdits({ episodesResolved }).length,
  };

  return {
    series: resolvedSeries,
    applied,
    patchMode: exactTextMode ? 'exact-text-v1' : null,
    rejectedExactEdits,
    episodesResolved,
    mutations,
    noChangeReason: applied ? null : noChangeReasonFor(edits, rejectedExactEdits),
    ...runMeta,
  };
}

const EPISODE_METADATA_FIELDS = ['arcRole', 'lengthProfile', 'pageTarget', 'minutesTarget'];
const episodeMetadataOf = (issue) => Object.fromEntries(EPISODE_METADATA_FIELDS.map((field) => [field, issue[field] ?? null]));

/**
 * Apply the auto-resolve pass's episode planning corrections to the canonical
 * issue records. Each correction targets one issue by its series-global episode
 * number (with `seasonNumber` as a disambiguating cross-check). Writes the new
 * synopsis to the issue's `idea.input` seed. If that issue already has expanded
 * beats (`idea.output`) — only possible on a resume where beats ran in a prior
 * pass — they are cleared and the stage reset to `empty` so the beat-sheet step
 * regenerates them from the corrected synopsis instead of leaving stale beats
 * that still encode the contradiction.
 *
 * Role/length changes are limited to unproduced issues and clear expanded beats.
 * Metadata and beat invalidation share one owning-service write.
 * A locked `idea` stage is left untouched (the user froze it) and reported as
 * skipped. Returns entries with the written `idea` and/or sparse `metadata`, plus
 * identity, `clearedBeats`, and an optional `skipped` reason
 * for the conductor to surface; never throws — a bad match is dropped, not fatal.
 *
 * `idea` is the stage AS THIS CALL LEFT IT, and it is what makes the entry a
 * mutation manifest rather than a report: rollback restores an episode only when
 * the resolver is on record as having written it AND the value it wrote is still
 * standing (see `restoreArcState`). A write that failed is reported skipped —
 * counting it as an applied edit told the gate a synopsis had changed when the
 * store still held the old one.
 */
export async function applyEpisodeResolutions(seriesId, series, episodes) {
  if (!Array.isArray(episodes) || episodes.length === 0) return [];
  const issues = await listIssues({ seriesId });
  const seasonIdByNumber = seasonIdByNumberOf(series);
  const applied = [];
  for (const edit of shapeEpisodeResolutions(episodes)) {
    // Season match required when the named season resolves, else series-global
    // number; fail-safe to no-match on a numbering-scheme mismatch (see
    // matchIssueForEpisodeEdit). A bad match is logged below, never fatal.
    const issue = matchIssueForEpisodeEdit(issues, seasonIdByNumber, edit);
    if (!issue) {
      // A correction we can't land is a silent path to non-convergence — log it
      // so a number-scheme mismatch (per-season vs series-global) is diagnosable.
      console.log(`⚠️ arc-resolve: no issue matched episode correction (season ${edit.seasonNumber}, episode ${edit.episodeNumber})`);
      applied.push({ seasonNumber: edit.seasonNumber, episodeNumber: edit.episodeNumber, skipped: 'no-match' });
      continue;
    }
    if (issue.stages?.idea?.locked === true) {
      applied.push({ issueId: issue.id, number: issue.number, seasonNumber: edit.seasonNumber, skipped: 'locked' });
      continue;
    }
    const metadata = Object.fromEntries(EPISODE_METADATA_FIELDS
      .filter((field) => Object.hasOwn(edit, field) && edit[field] !== issue[field])
      .map((field) => [field, edit[field]]));
    const metadataChanged = Object.keys(metadata).length > 0;
    const hasSynopsis = typeof edit.synopsis === 'string' && edit.synopsis.trim().length > 0;
    if (!metadataChanged && !hasSynopsis) {
      applied.push({ issueId: issue.id, number: issue.number, seasonNumber: edit.seasonNumber, skipped: 'unchanged' });
      continue;
    }
    // This repair owns the plan, not regeneration of an existing manuscript or
    // page layout. A length/role change after production needs explicit review.
    const pages = issue.stages?.comicPages;
    if (metadataChanged && (MANUSCRIPT_TYPES.some((stage) => {
      const value = issue.stages?.[stage];
      return value?.output?.trim() || value?.input?.trim();
    }) || pages?.pages?.length || ['cover', 'backCover'].some((slot) => pages?.[slot]?.proofImage || pages?.[slot]?.finalImage))) {
      applied.push({ issueId: issue.id, number: issue.number, seasonNumber: edit.seasonNumber, skipped: 'existing-production' });
      continue;
    }
    const hadBeats = Boolean(issue.stages?.idea?.output?.trim());
    const ideaPatch = {
      ...(hasSynopsis ? { input: edit.synopsis } : {}),
      ...(hadBeats ? { output: '', status: 'empty', errorMessage: '' } : {}),
    };
    const writesIdea = Object.keys(ideaPatch).length > 0;
    // Metadata and any resulting beat invalidation belong to one stored write.
    const write = metadataChanged
      ? updateIssue(issue.id, { ...metadata, ...(writesIdea ? { stages: { idea: ideaPatch } } : {}) })
      : updateStageWithLatest(issue.id, 'idea', () => ideaPatch).then((result) => result.issue);
    const written = await write.catch((err) => {
      console.log(`⚠️ arc-resolve: episode ${edit.episodeNumber} planning edit failed: ${err.message}`);
      return null;
    });
    applied.push({
      issueId: issue.id,
      number: issue.number,
      seasonNumber: edit.seasonNumber,
      clearedBeats: hadBeats,
      ...(written ? {
        ...(writesIdea ? { idea: ideaSnapshotOf(written.stages?.idea) } : {}),
        ...(metadataChanged ? {
          metadata: Object.fromEntries(Object.keys(metadata).map((field) => [field, written[field]])),
          metadataGuard: episodeMetadataOf(written),
        } : {}),
      } : { skipped: 'write-failed' }),
    });
  }
  if (applied.length) {
    const fixed = applied.filter((a) => !a.skipped).length;
    console.log(`📝 arc-resolve: corrected ${fixed} episode synopsis(es) for series ${seriesId.slice(0, 12)}`);
  }
  return applied;
}

// The three `idea`-stage fields an auto-resolve round can rewrite, normalized so
// the snapshot and the restore's dirty-check read the record the same way — a
// fourth field would otherwise have to be added to two hand-rolled default lists
// kept in lockstep.
const ideaSnapshotOf = (stage) => ({
  input: stage?.input ?? '',
  output: stage?.output ?? '',
  status: stage?.status ?? 'empty',
});

const sameIdea = (a, b) => a.input === b.input && a.output === b.output && a.status === b.status;

/**
 * The episode-synopsis writes ONE resolve pass actually landed, as
 * `[{ issueId, idea?, metadata?, metadataGuard? }]` — the exact-mutation manifest a rollback needs so it can
 * tell its own round's edits from a write that arrived from somewhere else while
 * the verification was running. Derived from the applier's own report — an entry
 * carries `idea` only when the write went through, never when it was skipped or
 * failed — so the manifest cannot claim an edit that never happened.
 *
 * Empty for an arc-spine round: that gate's resolver may not touch episodes at
 * all (`selectFindingKeyedEdits` discards them), which is exactly why a
 * spine-scope rollback must leave every episode `idea` field alone.
 */
export const resolvedEpisodeEdits = (resolved) => (Array.isArray(resolved?.episodesResolved)
  ? resolved.episodesResolved
    .filter((entry) => entry?.issueId && (entry.idea || entry.metadata))
    .map((entry) => ({
      issueId: entry.issueId,
      ...(entry.idea ? { idea: entry.idea } : {}),
      ...(entry.metadata ? { metadata: entry.metadata, metadataGuard: entry.metadataGuard } : {}),
    }))
  : []);

// Every issue in the series, without per-stage run history: `listIssues` caps at
// 1000 (a longer series would lose its tail from the snapshot, making those
// episodes unrestorable) and carries history payloads this projection throws
// away. Shared by the snapshot and the restore.
const listEpisodesForSnapshot = (seriesId) => listIssuesForSeries(seriesId, { withHistory: false });

/**
 * Capture everything ONE auto-resolve round can rewrite — the series arc,
 * per-character arcs, volume records, and each episode's planning synopsis and role/length metadata
 * (plus which volume it sits under) — so a round that leaves verification WORSE
 * can be reverted instead of committed. Read-only; the caller holds the snapshot
 * for the duration of the round (see `runArcVerify`'s regression guard).
 *
 * Deep-cloned: `getSeries` hands back the store record un-cloned, and a snapshot
 * that aliases the record it is meant to restore is no snapshot at all.
 */
export async function snapshotArcState(seriesId) {
  const [series, issues] = await Promise.all([getSeries(seriesId), listEpisodesForSnapshot(seriesId)]);
  return {
    seriesId,
    arc: structuredClone(series.arc ?? null),
    characterArcs: structuredClone(series.characterArcs || []),
    seasons: structuredClone(series.seasons || []),
    episodes: issues.map((iss) => ({
      id: iss.id,
      seasonId: iss.seasonId ?? null,
      idea: ideaSnapshotOf(iss.stages?.idea),
      metadata: episodeMetadataOf(iss),
    })),
  };
}

/**
 * Put a `snapshotArcState` capture back, restoring only what actually differs:
 * the series arc, per-character arcs, volume list, any episode whose volume the
 * round re-pointed, and any episode synopsis the round rewrote. Returns what it
 * touched.
 *
 * Deliberately NOT routed through `commitSeasonsWithRemap`: that path merges,
 * preserves and re-mints, which is right for applying a rewrite and wrong for
 * undoing one — a rollback wants the exact prior record back, and it restores
 * the child issues' `seasonId` itself so a volume the round minted can't strand
 * the episodes it took. For the same reason it doesn't re-check `locked.arc`:
 * the arc was writable when the round ran, and refusing to undo that round's
 * damage because a lock flipped mid-run would strand the user with the damage.
 * A locked `idea` stage IS skipped — the resolve pass never touched it.
 *
 * `options.episodeEdits` is the round's exact mutation manifest (see
 * `resolvedEpisodeEdits`): pass it and only those episodes' recorded idea and
 * metadata changes are eligible, and only while the value the resolver wrote is still the one
 * standing — "differs from the snapshot" was never proof the round owned the
 * difference. Two deliberate limits on that:
 *   - Volume reassignment is never manifest-gated. The volume list is being
 *     restored wholesale, so an episode left pointing at a volume that is about
 *     to disappear would be stranded.
 *   - Neither are the arc, character arcs and volume records themselves. Nothing
 *     records what the resolver wrote at that altitude, and a non-spine round is
 *     expected to rewrite all three, so the false-revert exposure is small — but
 *     it is the same reasoning, and closing it needs a manifest one level up.
 *
 * Omit `episodeEdits` and every differing episode is restored. The one caller
 * that still wants that is `restoreFoundationState`, which verifies its own
 * restore fidelity by diffing episodes wholesale. Both rollback loops that judge
 * a round by re-verifying it — the arc gate and the foundation gate's structure
 * repair — pass a manifest.
 *
 * Callers must re-verify after every resolve so they can distinguish a
 * regressive round from a good one. The arc convergence loop uses this to keep
 * its best verified checkpoint; foundation structure repair uses it to restore
 * the pre-repair plan when its bounded verify/correct pass is still blocked.
 * The manual `/arc/resolve` route remains an explicit unguarded user edit.
 */
export async function restoreArcState(seriesId, snapshot, { episodeEdits = null } = {}) {
  if (!snapshot || snapshot.seriesId !== seriesId || !Array.isArray(snapshot.episodes)) {
    return { restored: false, episodesRestored: 0, reassignedIssueCount: 0 };
  }
  const issues = await listEpisodesForSnapshot(seriesId);
  const byId = new Map(issues.map((iss) => [iss.id, iss]));
  // What the round is on record as having written to each episode, or null when
  // the caller kept the pre-manifest "restore every difference" contract.
  const ownedEdits = Array.isArray(episodeEdits) ? new Map() : null;
  for (const edit of Array.isArray(episodeEdits) ? episodeEdits : []) {
    const prior = ownedEdits.get(edit.issueId) || {};
    const metadata = edit.metadata || {};
    const lengthChanged = EPISODE_METADATA_FIELDS.slice(1).some((field) => Object.hasOwn(metadata, field));
    ownedEdits.set(edit.issueId, {
      ...prior, ...edit,
      metadata: { ...prior.metadata, ...metadata },
      // A role-only repair records a fresh full metadata guard, but it does not
      // take ownership of the length choice. Keep the guard from the last edit
      // that actually changed length fields so a later authored target remains
      // outside this round's rollback scope.
      metadataGuard: lengthChanged
        ? (edit.metadataGuard || metadata)
        : (prior.metadataGuard || prior.metadata),
    });
  }
  const stageUpdates = [];
  const metadataUpdates = [];
  const reassign = [];
  for (const snap of snapshot.episodes) {
    const cur = byId.get(snap.id);
    // Gone since the snapshot — nothing to restore onto (auto-resolve never
    // deletes issues, so this is a concurrent user edit, not the round).
    if (!cur) continue;
    if ((cur.seasonId ?? null) !== snap.seasonId) reassign.push(snap);
    if (cur.stages?.idea?.locked === true) continue;
    const idea = ideaSnapshotOf(cur.stages?.idea);
    const owned = ownedEdits?.get(snap.id);
    let metadataPatch = {};
    // Legacy snapshots do not own metadata. For current snapshots, restore only
    // fields this round changed and only while its result still stands. Length
    // is one choice: a later page-count edit must not have its profile reset.
    if (snap.metadata) {
      const lengthFields = EPISODE_METADATA_FIELDS.slice(1);
      const lengthStillOwned = !ownedEdits || (owned?.metadata && lengthFields.every((field) => {
        const guard = owned.metadataGuard || owned.metadata;
        return !Object.hasOwn(guard, field) || (cur[field] ?? null) === guard[field];
      }));
      metadataPatch = Object.fromEntries(EPISODE_METADATA_FIELDS.filter((field) => (
        Object.hasOwn(snap.metadata, field) && (cur[field] ?? null) !== snap.metadata[field]
        && (!ownedEdits || (Object.hasOwn(owned?.metadata || {}, field)
          && (cur[field] ?? null) === owned.metadata[field]
          && (field === 'arcRole' || lengthStillOwned)))
      )).map((field) => [field, snap.metadata[field]]));
      if (Object.keys(metadataPatch).length) metadataUpdates.push({ issueId: snap.id, patch: metadataPatch });
    }
    if (!sameIdea(idea, snap.idea) && (!ownedEdits || (owned?.idea && sameIdea(idea, owned.idea)))) {
      const restoredMetadata = { ...episodeMetadataOf(cur), ...metadataPatch };
      const metadataStillChanged = snap.metadata && EPISODE_METADATA_FIELDS
        .some((field) => restoredMetadata[field] !== snap.metadata[field]);
      // A later author choice can keep a new length or role. Restore our old
      // synopsis, but never resurrect beats sized for the superseded plan.
      const restoredIdea = metadataStillChanged && snap.idea.output
        ? { ...snap.idea, output: '', status: 'empty' }
        : snap.idea;
      stageUpdates.push({ issueId: snap.id, stageId: 'idea', computeFn: () => ({ ...restoredIdea, errorMessage: '' }) });
    }
  }
  // Same write ordering as `commitSeasonsWithRemap`: seasons first, so a crash
  // between writes can't leave an issue pointing at a volume that isn't in
  // `series.seasons[]`.
  await withReexportSuppressed('series', seriesId, async () => {
    await updateSeries(seriesId, {
      arc: { ...snapshot.arc, seriesDesign: (await getSeries(seriesId)).arc?.seriesDesign },
      seasons: snapshot.seasons,
      ...(Array.isArray(snapshot.characterArcs) ? { characterArcs: snapshot.characterArcs } : {}),
    });
    for (const snap of reassign) {
      await updateIssue(snap.id, { seasonId: snap.seasonId }, { skipRenumber: true });
    }
    if (reassign.length) await recomputeIssueNumbersForSeries(seriesId);
    for (const { issueId, patch } of metadataUpdates) await updateIssue(issueId, patch);
    await updateStagesWithLatest(seriesId, stageUpdates);
  });
  emitRecordUpdated('series', seriesId);
  console.log(`↩️ arc-resolve: reverted a regressive round for series ${seriesId.slice(0, 12)} — ${stageUpdates.length} episode synopsis(es), ${reassign.length} reassignment(s)`);
  const episodesRestored = new Set([...stageUpdates, ...metadataUpdates].map((entry) => entry.issueId)).size;
  return { restored: true, episodesRestored, reassignedIssueCount: reassign.length };
}

// Preserve per-field arc locks. When `currentSeries.locked.arcFields[k]` is
// true, the incoming arc's value for `k` is replaced with the existing one so
// auto-resolve / regenerate flows can rewrite unlocked fields without
// clobbering user-frozen ones. `null` next-arc (no incoming arc) is passed
// through unchanged — the persist layer's sanitizer drops it.
export function mergeArcWithLocks(currentArc, nextArc, lockedFields) {
  if (!nextArc || !lockedFields || typeof lockedFields !== 'object') return nextArc;
  if (!currentArc) return nextArc;
  const merged = { ...nextArc };
  for (const field of ARC_LOCKABLE_FIELDS) {
    if (lockedFields[field] === true) merged[field] = currentArc[field];
  }
  return merged;
}

// Preserve per-season locks. For every locked season in `currentSeasons`:
//   - if the LLM proposed an entry with the same id, replace it with the
//     existing locked record field-for-field (LLM's title/logline/etc. are
//     discarded);
//   - if the LLM dropped it entirely, re-insert it so it survives the resolve.
// Unlocked seasons (and brand-new entries the LLM minted) pass through. The
// caller still funnels the result through `sanitizeSeasonList`, which re-sorts
// by `number` ascending and dedups by id.
//
// Mirrors `mergeArcWithLocks`'s contract: locks are an *enforcement* gate, not
// a workflow signal — the arc-level `series.locked.arc` check up the stack
// remains the all-or-nothing block; this lets users freeze individual seasons
// while still letting auto-resolve rewrite the rest of the arc.
export function mergeSeasonsWithLocks(currentSeasons, nextSeasons) {
  if (!Array.isArray(nextSeasons)) return nextSeasons;
  if (!Array.isArray(currentSeasons)) return nextSeasons;
  const lockedById = new Map();
  for (const s of currentSeasons) {
    if (s?.locked === true && s.id) lockedById.set(s.id, s);
  }
  if (lockedById.size === 0) return nextSeasons;
  const seen = new Set();
  const merged = [];
  for (const next of nextSeasons) {
    const locked = next?.id ? lockedById.get(next.id) : null;
    if (locked) {
      merged.push(locked);
      seen.add(locked.id);
    } else {
      merged.push(next);
    }
  }
  for (const [id, locked] of lockedById) {
    if (!seen.has(id)) merged.push(locked);
  }
  return merged;
}

// Re-insert every EXISTING season the rewrite dropped, without freezing the
// ones it kept. Distinct from `mergeSeasonsWithLocks`: that one restores a
// locked season's CONTENT verbatim (the user froze it); this one only
// guarantees the record survives, so a same-id rewrite still applies in full.
//
// Used by the autopilot's `unlockForRun` mode — once that pass clears the
// per-season locks, nothing else stops an LLM-proposed arc from silently
// deleting a volume, and unlocking for EDITING must not become a licence to
// DELETE (see seriesAutopilot/unlockPass.js).
//
// The preserved records go FIRST, and that ordering is load-bearing rather than
// cosmetic: `sanitizeSeasonList` caps the list at SEASONS_PER_SERIES_MAX by
// keeping the first N it sees. Appending them would mean an LLM that returned a
// full cap's worth of brand-new volumes silently pushed every existing volume
// past the cap — the sanitizer would drop them and `commitSeasonsWithRemap`
// would then treat them as deleted and reassign their issues, which is exactly
// the deletion this helper exists to refuse. Existing records therefore win the
// cap; the rewrite's surplus new volumes are what gets trimmed. Final display
// order is unaffected — `sanitizeSeasonList` sorts by `number` at the end.
export function preserveDroppedSeasonRecords(currentSeasons, nextSeasons) {
  if (!Array.isArray(nextSeasons)) return nextSeasons;
  if (!Array.isArray(currentSeasons)) return nextSeasons;
  const keptIds = new Set(nextSeasons.map((s) => s?.id).filter(Boolean));
  const dropped = currentSeasons.filter((s) => s?.id && !keptIds.has(s.id));
  return dropped.length === 0 ? nextSeasons : [...dropped, ...nextSeasons];
}

// Normalized title comparison, shared by the two season matchers below.
const normTitle = (s) => (typeof s === 'string' ? s.trim().toLowerCase() : '');

/**
 * Resolve each LLM-proposed season to the EXISTING season record it is a
 * rewrite of, so a rewrite lands on that record instead of minting a sibling.
 * Returns an array parallel to `proposedSeasons` holding the matched existing
 * season (or `null` when the proposal is genuinely new).
 *
 * Match priority mirrors `buildSeasonRemap`, and runs as three ordered passes
 * rather than one greedy sweep so a proposal that DOES carry an `id` always
 * wins its own record: a same-titled sibling processed earlier must not claim
 * it and push the id-carrying proposal into minting a duplicate.
 *   1. explicit `id`
 *   2. normalized title (the resolve prompt is told to preserve titles)
 *   3. `number`, only when exactly one unclaimed existing season has it
 *
 * Deliberately NOT a positional fallback — unlike `buildSeasonRemap`'s 1↔1
 * pass, a wrong guess here doesn't just misfile child issues, it overwrites a
 * volume's prose with another volume's rewrite. Unmatched proposals mint, which
 * is the recoverable outcome.
 */
export function matchProposedSeasons(existingSeasons, proposedSeasons) {
  const existing = Array.isArray(existingSeasons) ? existingSeasons.filter((s) => s?.id) : [];
  const proposed = Array.isArray(proposedSeasons) ? proposedSeasons : [];
  const matched = new Array(proposed.length).fill(null);
  if (existing.length === 0) return matched;
  const byId = new Map(existing.map((s) => [s.id, s]));
  const claimed = new Set();

  const claim = (idx, season) => {
    matched[idx] = season;
    claimed.add(season.id);
  };

  // Pass 1 — explicit id.
  proposed.forEach((raw, idx) => {
    const hit = raw?.id ? byId.get(raw.id) : null;
    if (hit && !claimed.has(hit.id)) claim(idx, hit);
  });

  // Pass 2 — normalized title.
  proposed.forEach((raw, idx) => {
    if (matched[idx]) return;
    const title = normTitle(raw?.title);
    if (!title) return;
    const hit = existing.find((s) => normTitle(s.title) === title && !claimed.has(s.id));
    if (hit) claim(idx, hit);
  });

  // Pass 3 — unambiguous `number`.
  proposed.forEach((raw, idx) => {
    if (matched[idx]) return;
    if (!Number.isFinite(raw?.number)) return;
    const hits = existing.filter((s) => s.number === raw.number && !claimed.has(s.id));
    if (hits.length === 1) claim(idx, hits[0]);
  });

  return matched;
}

// Prose fields a collapse may back-fill onto the surviving record. Only ever
// used to fill a field that is EMPTY on the survivor — never to overwrite.
const SEASON_FILLABLE_FIELDS = ['logline', 'synopsis', 'endingHook'];

// Rescue content that only exists on the records being absorbed, so collapsing
// a duplicate can't silently delete the one revision that had a synopsis.
function backfillSeasonGaps(survivor, group) {
  // Newest first — if several duplicates could fill a gap, the latest rewrite
  // is the one the user last saw.
  const donors = group
    .filter((s) => s.id !== survivor.id)
    .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
  let next = survivor;
  for (const key of SEASON_FILLABLE_FIELDS) {
    if (next[key]) continue;
    const donor = donors.find((d) => d[key]);
    if (donor) next = { ...next, [key]: donor[key] };
  }
  if (!next.themes?.length) {
    const donor = donors.find((d) => d.themes?.length);
    if (donor) next = { ...next, themes: donor.themes };
  }
  if (!next.episodeCountTarget) {
    const donor = donors.find((d) => d.episodeCountTarget);
    if (donor) next = { ...next, episodeCountTarget: donor.episodeCountTarget };
  }
  return next;
}

/** True when two or more seasons in the list share a `number`. Pure. */
export function hasDuplicateSeasonNumbers(seasons) {
  if (!Array.isArray(seasons)) return false;
  const seen = new Set();
  for (const s of seasons) {
    if (!s) continue;
    if (seen.has(s.number)) return true;
    seen.add(s.number);
  }
  return false;
}

/**
 * Collapse seasons that share a `number` down to one record per number, and
 * report which ids were absorbed so the caller can re-point their child issues.
 * Returns `{ seasons, absorbed: Map<absorbedId, survivorId> }`.
 *
 * Two volumes numbered the same is never a state a user can act on — the Arc
 * Canvas renders both, a volume export can't tell which is canonical, and
 * arc-verify files it as a blocking finding every round. Before
 * `matchProposedSeasons` existed, auto-resolve manufactured exactly this shape,
 * so the collapse doubles as the self-heal for installs that already diverged:
 * the next arc write repairs the record without a migration (the file-migration
 * runner executes before the Postgres pool, and series are db-primary).
 *
 * Survivor preference — the record with the strongest claim to the child
 * issues, so a collapse never strands episodes:
 *   1. `locked` (the user froze it)
 *   2. most child issues
 *   3. oldest `createdAt` (the original, not the bug's mint)
 *
 * A group holding TWO OR MORE locked records is left intact: silently deleting
 * a user-frozen volume is worse than the duplicate, and only a human can say
 * which freeze was intended. Those groups keep warning every write, which is
 * the correct nag.
 */
export function collapseDuplicateSeasonNumbers(seasons, issueCountBySeasonId = new Map(), { log = true } = {}) {
  const absorbed = new Map();
  if (!Array.isArray(seasons)) return { seasons, absorbed };
  const byNumber = new Map();
  for (const s of seasons) {
    if (!s) continue;
    const group = byNumber.get(s.number);
    if (group) group.push(s);
    else byNumber.set(s.number, [s]);
  }

  const survivors = [];
  for (const [number, group] of byNumber) {
    if (group.length === 1) {
      survivors.push(group[0]);
      continue;
    }
    const lockedCount = group.filter((s) => s.locked === true).length;
    if (lockedCount > 1) {
      if (log) {
        console.warn(
          `⚠️ collapseDuplicateSeasonNumbers: volume ${number} has ${group.length} records including ${lockedCount} locked — left intact, unlock all but one to collapse`,
        );
      }
      survivors.push(...group);
      continue;
    }
    const episodes = (s) => issueCountBySeasonId.get(s.id) || 0;
    const [survivor] = [...group].sort((a, b) => (
      (b.locked === true ? 1 : 0) - (a.locked === true ? 1 : 0)
      || episodes(b) - episodes(a)
      || String(a.createdAt || '').localeCompare(String(b.createdAt || ''))
    ));
    survivors.push(backfillSeasonGaps(survivor, group));
    for (const s of group) {
      if (s.id !== survivor.id) absorbed.set(s.id, survivor.id);
    }
    if (log) {
      console.warn(
        `⚠️ collapseDuplicateSeasonNumbers: volume ${number} had ${group.length} records — kept ${survivor.id} (${episodes(survivor)} episode(s)), absorbed ${group.length - 1} into it`,
      );
    }
  }
  // Re-sort: `sanitizeSeasonList`'s number ordering is the contract consumers
  // render straight from, and the group walk above emits in first-seen order.
  return { seasons: survivors.sort((a, b) => (a.number || 0) - (b.number || 0)), absorbed };
}

/**
 * Persist a new `arc` + `seasons[]` onto a series, migrating any child issues
 * whose `seasonId` referenced a season that the new shape dropped or renamed.
 * Shared by `resolveVerifyIssues` (auto-resolve) and `/arc/generate` — both
 * paths can rewrite season ids, and without this migration the orphans land
 * behind keys the Arc Canvas never iterates back.
 *
 * Match priority (via `buildSeasonRemap`): normalized title → unique number →
 * positional 1:1 fallback. Unmatched orphans get `seasonId: null` so they fall
 * into the visible "Un-grouped" bucket instead of vanishing.
 *
 * Per-field arc locks (`series.locked.arcFields`) are honored: locked fields
 * are restored from `currentSeries.arc` before the persist, so an auto-resolve
 * that proposes a new logline can preserve the user-frozen themes verbatim.
 *
 * `currentSeries` identifies the target series. The helper refreshes the
 * latest snapshot before writing so locks toggled while an LLM run is in
 * flight are honored at commit time.
 *
 * `options.preserveDroppedSeasons` additionally re-inserts any existing season
 * the new shape omitted, whether or not it was locked — the non-destructive
 * guarantee the autopilot's `unlockForRun` mode relies on (it clears the very
 * per-season locks that would otherwise have preserved them). Content rewrites
 * to surviving seasons still apply; only deletion is refused.
 */
export async function commitSeasonsWithRemap(currentSeries, { arc, seasons }, options = {}) {
  const seriesId = currentSeries.id;
  const latestSeries = await getSeries(seriesId);
  if (latestSeries.locked?.arc === true) {
    throw new ServerError(
      'Arc is locked — unlock it before rewriting the arc',
      { status: 400, code: ERR_VALIDATION },
    );
  }
  const mergedArc = mergeArcWithLocks(latestSeries.arc, { ...arc, seriesDesign: latestSeries.arc?.seriesDesign }, latestSeries.locked?.arcFields);
  // Per-season locks: restore any locked existing seasons over LLM-proposed
  // rewrites, and re-insert any locked seasons the LLM dropped. Re-sanitize
  // so the locked records merge with the new shape (sort by number, dedup).
  const lockMerged = mergeSeasonsWithLocks(latestSeries.seasons, seasons);
  let mergedSeasons = sanitizeSeasonList(
    options.preserveDroppedSeasons === true
      ? preserveDroppedSeasonRecords(latestSeries.seasons, lockMerged)
      : lockMerged,
  );

  // One `listIssues` for the whole commit — the collapse below needs per-season
  // episode counts and the reassign sweep needs the same list.
  let allIssues = null;
  const loadIssues = async () => {
    if (allIssues === null) allIssues = await listIssues({ seriesId });
    return allIssues;
  };

  // Self-heal duplicate volume numbers on the way through. `sanitizeSeasonList`
  // dedupes by `id` only, so two records both numbered 1 survive it happily —
  // and that shape is a blocking arc-verify finding no amount of LLM rewriting
  // can clear. Absorbed ids are threaded into the remap below so their episodes
  // follow the survivor instead of falling into the ungrouped bucket.
  let absorbed = new Map();
  if (hasDuplicateSeasonNumbers(mergedSeasons)) {
    const counts = new Map();
    for (const iss of await loadIssues()) {
      if (iss.seasonId) counts.set(iss.seasonId, (counts.get(iss.seasonId) || 0) + 1);
    }
    ({ seasons: mergedSeasons, absorbed } = collapseDuplicateSeasonNumbers(mergedSeasons, counts));
  }

  const newIds = new Set(mergedSeasons.map((s) => s.id));
  const droppedOldSeasons = (latestSeries.seasons || []).filter((s) => !newIds.has(s.id));
  const oldIds = new Set((latestSeries.seasons || []).map((s) => s.id));
  const newlyMintedSeasons = mergedSeasons.filter((s) => !oldIds.has(s.id));
  const remap = buildSeasonRemap(droppedOldSeasons, newlyMintedSeasons);
  // An absorbed duplicate has a KNOWN survivor, which beats buildSeasonRemap's
  // title/number inference — that pass only considers freshly-minted seasons as
  // targets, so a duplicate absorbed into an existing record would otherwise
  // map to null and orphan every episode under it.
  for (const [absorbedId, survivorId] of absorbed) remap.set(absorbedId, survivorId);
  const droppedIdSet = new Set(droppedOldSeasons.map((s) => s.id));
  const reassignList = droppedIdSet.size
    ? (await loadIssues()).filter((iss) => droppedIdSet.has(iss.seasonId))
    : [];

  // Mirrors `deleteSeason`'s bulk-reassign idiom — `skipRenumber` per call +
  // one `recomputeIssueNumbers` after, wrapped in `withReexportSuppressed` so
  // we don't fan out N socket events + N debounced re-exports of the same
  // series.
  //
  // Persist the new seasons FIRST so that a crash between writes leaves
  // issues attached to ids that still exist in `series.seasons[]`. If we
  // wrote issues first and crashed before `updateSeries`, every reassigned
  // issue would point at a `seasonId` that's not in the persisted series —
  // the exact orphan state this helper was written to prevent.
  let updated;
  await withReexportSuppressed('series', seriesId, async () => {
    updated = await updateSeries(seriesId, { arc: mergedArc, seasons: mergedSeasons });
    for (const iss of reassignList) {
      const target = remap.get(iss.seasonId) ?? null;
      await updateIssue(iss.id, { seasonId: target }, { skipRenumber: true });
    }
    if (reassignList.length) await recomputeIssueNumbersForSeries(seriesId);
  });
  if (reassignList.length) emitRecordUpdated('series', seriesId);
  return { series: updated, reassignedIssueCount: reassignList.length };
}

// Build a Map<oldSeasonId, newSeasonId|null> from the set of removed seasons
// and the freshly-minted ones in the same resolve. Matching priority:
//   1. normalized title equality (LLM was told to preserve titles when it can)
//   2. `number` equality (only when the target number is unique among new ones)
//   3. positional fallback — only fires when exactly ONE unmatched on each
//      side. With a single pair the mapping is forced and unambiguous; with
//      2+ unmatched the LLM may have reshuffled/renamed everything and
//      positional guessing silently invents wrong mappings (the bug that
//      motivated this guard). Skipped runs log a warning and let those
//      orphans fall through to the ungrouped bucket below.
// Anything that can't be matched maps to null so the issue lands in the
// ungrouped bucket instead of staying stranded behind a defunct id.
export function buildSeasonRemap(droppedOldSeasons, newlyMintedSeasons) {
  const remap = new Map();
  const claimed = new Set();
  const norm = (s) => (typeof s === 'string' ? s.trim().toLowerCase() : '');

  // Pass 1: normalized title
  for (const old of droppedOldSeasons) {
    const oldTitle = norm(old.title);
    if (!oldTitle) continue;
    const hit = newlyMintedSeasons.find(
      (n) => norm(n.title) === oldTitle && !claimed.has(n.id),
    );
    if (hit) {
      claimed.add(hit.id);
      remap.set(old.id, hit.id);
    }
  }

  // Pass 2: unique `number` match
  for (const old of droppedOldSeasons) {
    if (remap.has(old.id)) continue;
    if (!Number.isFinite(old.number)) continue;
    const matches = newlyMintedSeasons.filter(
      (n) => n.number === old.number && !claimed.has(n.id),
    );
    if (matches.length === 1) {
      claimed.add(matches[0].id);
      remap.set(old.id, matches[0].id);
    }
  }

  // Pass 3: positional fallback — only when the unmatched sets are exactly
  // 1↔1, where the pairing is forced.
  const oldRemaining = droppedOldSeasons.filter((s) => !remap.has(s.id));
  const newRemaining = newlyMintedSeasons.filter((n) => !claimed.has(n.id));
  if (oldRemaining.length === 1 && newRemaining.length === 1) {
    // Sanitize titles before logging — LLM-generated text can carry newlines,
    // C0/C1 control chars, or ANSI escapes that would break the project's
    // single-line logging convention or corrupt terminal output; fall back to
    // the stable id when the title is empty after sanitization.
    const safeLabel = (s) => {
      const raw = typeof s.title === 'string' ? s.title : '';
      // stripAnsi removes full ESC + CSI sequences (so "[31m" payload tails
      // don't leak through). Note: OSC sequence bodies do leak
      // through stripAnsi today — extremely unlikely in LLM-generated season
      // titles, but called out here so a future fix to ANSI_PATTERN naturally
      // tightens this path. The trailing control-char sweep catches any bare
      // C0/C1 bytes the regex doesn't match.
      const t = stripAnsi(raw)
        .replace(/[\u0000-\u001F\u007F-\u009F]+/g, ' ')
        .replace(/\s+/g, ' ')
        .trim()
        .slice(0, 60);
      return t || s.id;
    };
    console.warn(
      `⚠️ buildSeasonRemap Pass 3 fired: forced 1↔1 pairing "${safeLabel(oldRemaining[0])}" → "${safeLabel(newRemaining[0])}"`,
    );
    remap.set(oldRemaining[0].id, newRemaining[0].id);
    claimed.add(newRemaining[0].id);
  } else if (
    oldRemaining.length === newRemaining.length
    && oldRemaining.length > 1
  ) {
    // Suppression warn ONLY for the cases where the previous behavior would
    // have fired the positional fallback (equal counts ≥ 2). Unequal counts
    // were never positional-fallback candidates, so they don't deserve a
    // "skipped" message.
    console.warn(
      `⚠️ buildSeasonRemap skipped positional fallback (${oldRemaining.length} old × ${newRemaining.length} new unmatched) — orphan issues route to ungrouped`,
    );
  }

  // Anything still unmapped → null (ungrouped bucket).
  for (const old of droppedOldSeasons) {
    if (!remap.has(old.id)) remap.set(old.id, null);
  }
  return remap;
}