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

54.8 KB
Raw Blame
/**
 * Unified Story Builder — conductor service.
 *
 * The Story Builder is a thin *conductor* over the existing universe / series /
 * issue records. It owns ONE lightweight record (the "session") that tracks
 * per-step status + locks + integrity hashes plus two FKs (`universeId`,
 * `seriesId`). All real content lives in the universe and series records and is
 * mutated through their existing services — this service never duplicates it.
 *
 * Sessions are LOCAL-ONLY BY DEFAULT: they reference peer-syncable records by
 * FK, but the lock/integrity bookkeeping is a private workflow artifact. A
 * session opts into cross-machine resume by flipping `sync: true` (#730). The
 * wire/push integration itself (peer push schema, manifest kind, importer
 * apply) is a later slice; what ships here is the OPT-IN flag plus the
 * sync-safe staleness model that makes enabling it later non-corrupting.
 *
 * Sync-safe staleness (#730). The default (local-only) staleness model
 * live-diffs each locked step's frozen `upstreamHash` against the CURRENT hash
 * recomputed from the live universe/series records — so any out-of-band edit
 * (#731), including a peer's universe edit that arrived via universe sync, flags
 * the locked step stale. That is correct within one install but wrong for a
 * synced session: once the session travels to another machine, that machine's
 * live records legitimately differ, so a live recompute would false-positive
 * EVERY locked step stale. So a `sync: true` session instead keys staleness on a
 * content hash CARRIED IN THE SESSION (`syncedHashes`) — the upstream hashes the
 * session last reconciled with on whatever machine touched it. A peer's record
 * edit moves the live records but NOT `syncedHashes`, so it can't false-positive
 * a synced session; the user re-snapshots the baseline explicitly via reconcile.
 *
 * The tombstone/origin/ephemeral fields are carried only for on-disk shape
 * parity (and forward-compat with the eventual sync wire integration).
 *
 * Storage: one row per session in PostgreSQL (`story_builder_sessions`) as of
 * #1016 (legacy on-disk shape was data/story-builder/{id}/index.json). The
 * storyBuilderStore facade is a drop-in for the collectionStore surface this
 * service calls, so only the `store()` factory below changed.
 */

import { randomUUID } from 'crypto';
import { pickPromptFields, BIBLE_KIND } from '../lib/storyBible.js';
import { sanitizeOrigin } from '../lib/sharingOrigin.js';
import { sanitizeSoftDeleteFields } from '../lib/syncWire.js';
import { runStagedLLM } from './stageRunner.js';
import {
  STEP_IDS, STEP_STATUSES, isValidStepId,
} from '../lib/storyBuilderSteps.js';
import { hashUpstream, computeStaleSteps, computeSyncDrift } from '../lib/storyBuilderIntegrity.js';
import { getStoryBuilderStore } from './storyBuilderStore/store.js';
import { linkIngredientsToSeries, resolveIngredientsByIds } from './catalogDB.js';
import { getActiveCatalogType, payloadSnippet } from '../lib/catalogTypes.js';
import { createUniverse, deleteUniverse, getUniverse, mergeInfluencesWithLocks, updateUniverse } from './universeBuilder.js';
import { expandWorldTemplate } from './universeBuilderExpand.js';
import { extractPreservedFromDraft, mergeExpandIntoDraft } from '../lib/universeExpandMerge.js';
import { refineWorldPrompts } from './universeBuilderRefine.js';
import { refineUniverseCharacter } from './universeCanon.js';
import {
  createSeries, getSeries, updateSeries, setArcFieldLock,
} from './pipeline/series.js';
import {
  generateArcOverview, generateArcFromSource, generateReaderMap, refineReaderMap, refineArc, commitSeasonsWithRemap, mergeArcWithLocks,
  collectIssueSourceText, generateSeasonEpisodes, commitEpisodesToIssues,
  ERR_VALIDATION as ARC_ERR_VALIDATION,
} from './pipeline/arcPlanner.js';
import { isStr, trimTo } from '../lib/textUtils.js';
import { codedError } from '../lib/codedError.js';

// Storage backend dispatcher (#1016): the facade is a drop-in for the
// collectionStore surface this service used to call directly, so every method
// below keeps calling `store().loadAll()`, `store().queueRecordWrite(...)`, etc.
// unchanged — only the backend (PostgreSQL vs the file escape hatch) moved.
const store = () => getStoryBuilderStore(sanitizeSession);
export const storyBuilderStore = () => store();

export const ERR_NOT_FOUND = 'STORY_BUILDER_NOT_FOUND';
export const ERR_VALIDATION = 'STORY_BUILDER_VALIDATION';

const _SESSION_ID_RE = /^stb-[A-Za-z0-9-]+$/;
export const TITLE_MAX = 200;
export const SEED_MAX = 4000;
export const INTAKE_MODES = Object.freeze(['seed', 'import']);

// Group → header label for the composed fallback seed. Prefer the ACTIVE
// registry's canonical label (getActiveCatalogType covers user-defined types
// too, so idea/scene/concept + custom types get proper plurals and match the
// client's prefill), naive-pluralizing an unknown type's id as a fallback.
// Mirrors `seedGroupHeading` in client StoryBuilder.jsx.
function seedGroupHeading(type) {
  const label = getActiveCatalogType(type)?.label;
  const base = label || (isStr(type) && type ? `${type.charAt(0).toUpperCase()}${type.slice(1)}` : 'Other');
  return base.endsWith('s') ? base : `${base}s`;
}

// Compose a fallback seed string from resolved catalog ingredients (#1761),
// used when the user supplies ingredients but no seedIdea so the minted
// universe/series shells aren't empty. Groups by type with a header line per
// group and one `- {name}: {summary}` bullet per ingredient (summary via
// payloadSnippet — the type's snippetFallbackKeys, ~120 chars; omitted, with
// the `: `, when empty). Capped at SEED_MAX with a trailing ellipsis on overflow.
function composeSeedFromIngredients(ingredients) {
  const byType = new Map();
  for (const ing of ingredients) {
    const list = byType.get(ing.type) || [];
    list.push(ing);
    byType.set(ing.type, list);
  }
  const lines = [];
  for (const [type, list] of byType) {
    lines.push(`${seedGroupHeading(type)}:`);
    for (const ing of list) {
      // payloadSnippet follows the type's snippetFallbackKeys (getActiveCatalogType
      // resolves user-defined types too), so a character's body text — under
      // `physicalDescription`, not `description` — is included.
      const summary = payloadSnippet(ing.payload, ing.type, 120, getActiveCatalogType);
      lines.push(summary ? `- ${ing.name}: ${summary}` : `- ${ing.name}`);
    }
  }
  const composed = lines.join('\n');
  if (composed.length <= SEED_MAX) return composed;
  return `${composed.slice(0, SEED_MAX - 1)}…`;
}

// Resolve the selected catalog ingredient ids to live ingredient records
// (de-duped, pick-order-preserving, soft-deleted excluded). Delegates to the
// shared catalogDB resolver (#1808) so Story Builder and Creative Director share
// one implementation instead of each carrying its own copy.
const resolveCatalogIngredients = (ids) => resolveIngredientsByIds(ids);

// Steps the importer actually pre-fills, so they open "ready" for review on an
// import-mode session. `idea` (universe + series exist), `plotArc` (arc +
// seasons), `characters` (extracted canon), and `issues` (the issue split) are
// populated by `analyzeImport` → `commitImport`. Steps NOT listed here —
// `universeAesthetic` (logline/premise/styleNotes/influences are never written
// on import), `readerMap` (no reader-map extraction pass), and `production`
// (the downstream render step) — fall through to the default "pending" status
// so they don't show an empty step under a misleading "Ready" badge (#728).
export const IMPORT_READY_STEPS = Object.freeze(['idea', 'plotArc', 'characters', 'issues']);

// The universe aesthetic step freezes these universe lock keys.
export const AESTHETIC_LOCK_FIELDS = Object.freeze([
  'logline', 'premise', 'styleNotes', 'influencesEmbrace', 'influencesAvoid',
]);

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

function sanitizeStepState(raw) {
  const status = STEP_STATUSES.includes(raw?.status) ? raw.status : 'pending';
  const locked = raw?.locked === true;
  return {
    status: locked ? 'locked' : status,
    locked,
    lockedAt: locked && isStr(raw?.lockedAt) ? raw.lockedAt : null,
    upstreamHash: locked && isStr(raw?.upstreamHash) ? raw.upstreamHash : null,
  };
}

function sanitizeIssueLocks(raw) {
  if (!raw || typeof raw !== 'object') return {};
  const out = {};
  for (const [issueId, state] of Object.entries(raw)) {
    if (!isStr(issueId)) continue;
    if (state?.locked !== true) continue;
    out[issueId] = {
      locked: true,
      lockedAt: isStr(state.lockedAt) ? state.lockedAt : nowIso(),
      upstreamHash: isStr(state.upstreamHash) ? state.upstreamHash : null,
    };
  }
  return out;
}

function sanitizeSteps(raw) {
  const steps = {};
  for (const id of STEP_IDS) {
    steps[id] = sanitizeStepState(raw?.[id]);
  }
  // Per-issue locks ride on the `issues` step.
  const issueLocks = sanitizeIssueLocks(raw?.issues?.issueLocks);
  if (Object.keys(issueLocks).length > 0) steps.issues.issueLocks = issueLocks;
  return steps;
}

// The content-hash baseline a `sync: true` session carries (#730): one
// sha256 hex digest per step id, the upstream hash the session last reconciled
// with. Drops unknown ids and non-hex values so a hand-edited / peer-sourced
// record can't smuggle a bogus baseline that would mis-flag staleness.
const HASH_RE = /^[0-9a-f]{64}$/;
function sanitizeSyncedHashes(raw) {
  if (!raw || typeof raw !== 'object') return {};
  const out = {};
  for (const id of STEP_IDS) {
    const h = raw[id];
    if (isStr(h) && HASH_RE.test(h)) out[id] = h;
  }
  return out;
}

export function sanitizeSession(raw) {
  if (!raw || typeof raw !== 'object') return null;
  if (!isStr(raw.id) || !raw.id) return null;
  const title = trimTo(raw.title, TITLE_MAX);
  if (!title) return null;
  const intakeMode = INTAKE_MODES.includes(raw.intakeMode) ? raw.intakeMode : 'seed';
  const currentStep = isValidStepId(raw.currentStep) ? raw.currentStep : STEP_IDS[0];
  const llm = raw.llm && typeof raw.llm === 'object'
    ? { provider: trimTo(raw.llm.provider, 80) || null, model: trimTo(raw.llm.model, 200) || null }
    : { provider: null, model: null };
  const createdAt = isStr(raw.createdAt) ? raw.createdAt : nowIso();
  const updatedAt = isStr(raw.updatedAt) ? raw.updatedAt : createdAt;
  return {
    id: raw.id,
    title,
    intakeMode,
    seedIdea: trimTo(raw.seedIdea, SEED_MAX),
    universeId: trimTo(raw.universeId, 64) || null,
    seriesId: trimTo(raw.seriesId, 64) || null,
    currentStep,
    steps: sanitizeSteps(raw.steps),
    llm,
    // Cross-machine resume is OPT-IN (#730): local-only is the default. When
    // off, `syncedHashes` is irrelevant (staleness live-diffs against records)
    // so we drop it to keep the record minimal.
    sync: raw.sync === true,
    ...(raw.sync === true ? { syncedHashes: sanitizeSyncedHashes(raw.syncedHashes) } : {}),
    origin: sanitizeOrigin(raw.origin),
    createdAt,
    updatedAt,
    ...sanitizeSoftDeleteFields(raw),
    ...(raw.ephemeral === true ? { ephemeral: true } : {}),
  };
}

// ── CRUD ────────────────────────────────────────────────────────────────

export async function listStorySessions({ includeDeleted = false } = {}) {
  const sessions = await store().loadAll();
  const filtered = includeDeleted ? sessions : sessions.filter((s) => !s.deleted);
  return [...filtered].sort((a, b) => (b.updatedAt || '').localeCompare(a.updatedAt || ''));
}

export async function getStorySession(id, { includeDeleted = false } = {}) {
  const found = await store().loadOne(id);
  if (!found) throw codedError(`Story Builder session not found: ${id}`, ERR_NOT_FOUND);
  if (found.deleted && !includeDeleted) throw codedError(`Story Builder session not found: ${id}`, ERR_NOT_FOUND);
  return found;
}

/**
 * Create a session. Seed mode mints fresh universe + series shells the
 * conductor will fill in step by step. Import mode expects the caller to have
 * already created/linked the universe + series (via the importer) and passes
 * their ids in.
 */
export async function createStorySession(input = {}) {
  const title = trimTo(input.title, TITLE_MAX);
  if (!title) throw codedError(`Title is required (1..${TITLE_MAX} chars)`, ERR_VALIDATION);
  const intakeMode = INTAKE_MODES.includes(input.intakeMode) ? input.intakeMode : 'seed';
  const seedIdea = trimTo(input.seedIdea, SEED_MAX);

  let universeId = trimTo(input.universeId, 64) || null;
  let seriesId = trimTo(input.seriesId, 64) || null;
  // Seed used to mint the shells: the user's seedIdea, or — when they picked
  // Catalog ingredients but typed no seed — a fallback composed from those
  // ingredients (#1761). In the normal (no-ingredients) case this equals
  // seedIdea, so the create path is byte-for-byte unchanged.
  let effectiveSeed = seedIdea;
  // Resolved catalog ingredients (#1761), hoisted to function scope so the
  // series links can be created AFTER the session is saved (best-effort —
  // see below). Stays empty in import mode and the no-ingredients case.
  let remixIngredients = [];

  if (intakeMode === 'seed') {
    // Resolve any selected catalog ingredients up front: they feed both the
    // fallback seed (so the minted shells aren't empty) and the series links
    // created once the session is saved. Missing/deleted ids are skipped.
    remixIngredients = await resolveCatalogIngredients(input.catalogIngredientIds);
    if (!effectiveSeed && remixIngredients.length > 0) {
      effectiveSeed = composeSeedFromIngredients(remixIngredients);
    }

    // Mint the shells the wizard fills in. The universe name doubles as the
    // working title; the seed idea seeds the universe starter prompt.
    //
    // The universe is created first (and on creation fires peer auto-subscribe),
    // then the series. If `createSeries` throws, we'd otherwise leave an orphan
    // universe on disk with no session pointing at it. Track whether *we* minted
    // the universe in this call and tombstone it on a series failure — but never
    // touch a universe the caller passed in (`input.universeId`).
    let mintedUniverseId = null;
    if (!universeId) {
      const universe = await createUniverse({ name: title, starterPrompt: effectiveSeed || '' });
      universeId = universe.id;
      mintedUniverseId = universe.id;
    }
    if (!seriesId) {
      const series = await createSeries({ name: title, universeId, premise: effectiveSeed || '' }).catch(async (err) => {
        if (mintedUniverseId) {
          // Roll back the just-created universe so a failed session create
          // doesn't leave a stray (and already peer-subscribed) shell behind.
          await deleteUniverse(mintedUniverseId).catch((cleanupErr) => {
            console.error(`⚠️ Failed to roll back orphan universe ${mintedUniverseId} after series create failed: ${cleanupErr.message}`);
          });
        }
        throw err;
      });
      seriesId = series.id;
    }
  }

  const now = nowIso();
  const created = sanitizeSession({
    id: `stb-${randomUUID()}`,
    title,
    intakeMode,
    seedIdea,
    universeId,
    seriesId,
    currentStep: STEP_IDS[0],
    steps: {},
    llm: input.llm || null,
    createdAt: now,
    updatedAt: now,
    // Import mode pre-fills SOME content before review — mark only the steps the
    // importer actually populates "ready" so the user reviews + locks those. The
    // importer (`analyzeImport` → `commitImport`) fills: the idea (universe +
    // series exist), the plot arc + seasons, the cast (canon characters), and the
    // issue split. It does NOT extract a universe aesthetic
    // (logline/premise/styleNotes/influences are never written) nor a reader map,
    // and production is the downstream render step. Those start "pending" so the
    // user generates them — leaving them "ready" showed an empty step under a
    // misleading "Ready" badge (issue #728). The default-pending fall-through in
    // sanitizeSteps covers every step omitted here.
    ...(intakeMode === 'import'
      ? { steps: Object.fromEntries(IMPORT_READY_STEPS.map((id) => [id, { status: 'ready' }])) }
      : {}),
  });
  await store().saveOne(created.id, created);

  // Link the selected catalog ingredients to the new series via
  // catalog_ingredient_refs — the convergence contract's single data model.
  // Deliberately AFTER the session is saved and best-effort: the story is the
  // primary artifact, so a transient ref-insert failure must not reject the
  // create and orphan the just-minted universe/series (the link is recoverable
  // by re-picking ingredients). Role maps from type; unknown types → 'mentioned'.
  if (remixIngredients.length > 0) {
    await linkIngredientsToSeries(seriesId, remixIngredients)
      .then((linked) => console.log(`🔗 StoryBuilder: linked ${linked.length} catalog ingredient(s) to series ${seriesId}`))
      .catch((err) => console.error(`⚠️ StoryBuilder: failed to link catalog ingredients to series ${seriesId}: ${err.message}`));
  }
  return created;
}

export async function updateStorySession(id, patch = {}) {
  return store().queueRecordWrite(id, async () => {
    const cur = await store().loadOne(id);
    if (!cur || cur.deleted) throw codedError(`Story Builder session not found: ${id}`, ERR_NOT_FOUND);
    const next = sanitizeSession({
      ...cur,
      ...('title' in patch ? { title: patch.title } : {}),
      ...('seedIdea' in patch ? { seedIdea: patch.seedIdea } : {}),
      ...('currentStep' in patch ? { currentStep: patch.currentStep } : {}),
      ...('llm' in patch ? { llm: { ...(cur.llm || {}), ...(patch.llm || {}) } } : {}),
      updatedAt: nowIso(),
    });
    if (!next) throw codedError('Invalid session payload', ERR_VALIDATION);
    await store().saveOneNow(next.id, next);
    return next;
  });
}

export async function deleteStorySession(id) {
  return store().queueRecordWrite(id, async () => {
    const cur = await store().loadOne(id);
    if (!cur || cur.deleted) throw codedError(`Story Builder session not found: ${id}`, ERR_NOT_FOUND);
    const now = nowIso();
    await store().saveOneNow(id, { ...cur, deleted: true, deletedAt: now, updatedAt: now });
    return { id };
  });
}

// ── Cross-machine sync (#730) ─────────────────────────────────────────────
//
// Sessions are LOCAL-ONLY by default and excluded from peer sync entirely.
// Only a session with `sync: true` participates — it rides the dedicated
// `storyBuilder` snapshot category (dataSync.js), union-merged by id with LWW
// on `updatedAt`. Sessions carry no assets and no child records, so they don't
// need the per-record push pipeline / asset-manifest / reverse-subscribe
// machinery the universe/series kinds use; the 60s snapshot loop's LWW merge
// is the whole transport.
//
// The carried `syncedHashes` baseline is exactly what makes this safe: a peer's
// universe/series edit moves the live records but NOT `syncedHashes`, so a
// session that traveled across machines doesn't false-positive-stale (the whole
// point of the #861 staleness model). The FKs (`universeId`, `seriesId`)
// reference records that sync through their own categories; if the peer hasn't
// received them yet, the session view degrades gracefully (computeCurrentHashes
// reads them best-effort and a missing record just yields empty hashes).

/**
 * Wire-safe projection of a single session for the peer snapshot. Re-runs the
 * sanitizer (canonical key order + field whitelist) and strips the local-only
 * `ephemeral` marker so a synced session can't smuggle a peer-local flag and so
 * the byte-stable checksum matches across machines. Returns null for a session
 * that isn't sync-enabled — local-only sessions must NEVER cross the wire.
 *
 * Tombstones (deleted=true) still cross: a session that was synced, then
 * deleted, needs its tombstone to converge on peers that hold the live copy.
 */
export function sanitizeSessionForWire(raw) {
  const s = sanitizeSession(raw);
  if (!s) return null;
  if (s.sync !== true) return null;
  // `ephemeral` is a peer-local "don't sync" marker analogous to the
  // universe/series flag (and #727's `importDraft`). A live ephemeral session
  // is local-only and never crosses the wire; a tombstone still does so the
  // delete converges on peers that hold the live copy.
  if (s.ephemeral === true && s.deleted !== true) return null;
  // Strip the local-only marker so the wire form is byte-stable against peers
  // that predate the flag (sanitizeSession only adds it when raw.ephemeral).
  const { ephemeral: _ephemeral, ...rest } = s; // eslint-disable-line no-unused-vars
  return rest;
}

/**
 * Every sync-enabled session in wire form, sorted by id for a deterministic
 * (checksum-stable) snapshot. Includes tombstones so deletes propagate.
 */
export async function listSyncableSessionsForWire() {
  const sessions = await store().loadAll();
  return sessions
    .map(sanitizeSessionForWire)
    .filter(Boolean)
    .sort((a, b) => a.id.localeCompare(b.id));
}

/**
 * Merge a peer's sync-enabled sessions into local state. Union by id, LWW on
 * `updatedAt`. Mirrors the bundled-record merge contract:
 *   - sanitize-first: every remote row goes through `sanitizeSession` before it
 *     can touch disk (drops bogus baselines, malformed steps, missing title).
 *   - first-wins dedup: a duplicate id within the same batch keeps the first.
 *   - throw-on-unreadable: a per-record load failure aborts (the store's
 *     queueRecordWrite rejects), surfacing rather than silently dropping.
 *   - local-only guard: a remote session that isn't sync-enabled is refused
 *     (the sender only ships sync:true, but a malformed/hostile payload can't
 *     plant a local-only session as synced).
 *   - sync-flag preservation: a remote payload can't flip a LOCAL session's
 *     `sync` off (or on) — sync mode is a per-machine gesture. We only ever
 *     create/update sessions the remote marked sync:true; a local-only session
 *     of the same id is left untouched (its `sync:false` keeps it out of the
 *     wire on its own machine).
 */
export async function mergeStorySessionsFromSync(remoteSessions) {
  if (!Array.isArray(remoteSessions)) return { applied: false, count: 0 };
  // First-wins dedup within the batch (mirrors the monolithic-reader contract).
  const byId = new Map();
  for (const raw of remoteSessions) {
    const s = sanitizeSessionForWire(raw);
    if (!s || byId.has(s.id)) continue;
    byId.set(s.id, s);
  }
  let changed = 0;
  for (const remote of byId.values()) {
    const applied = await store().queueRecordWrite(remote.id, async () => {
      const local = await store().loadOne(remote.id);
      if (!local) {
        // No local counterpart — adopt the remote session verbatim. It's
        // already sync:true (sanitizeSessionForWire enforced it), so it stays
        // syncable on this machine too.
        await store().saveOneNow(remote.id, remote);
        return true;
      }
      // Don't resurrect / re-sync a session the LOCAL user opted out of. If the
      // local copy is local-only (sync:false), the user explicitly turned sync
      // off here — honor that and leave it alone rather than letting a stale
      // peer push flip it back on.
      if (local.sync !== true) return false;
      const localTs = local.updatedAt || '';
      const remoteTs = remote.updatedAt || '';
      if (remoteTs <= localTs) return false; // local wins (or tie — no churn)
      await store().saveOneNow(remote.id, remote);
      return true;
    });
    if (applied) changed += 1;
  }
  if (changed === 0) return { applied: false, count: 0 };
  console.log(`🔄 StoryBuilder sync: merged ${changed} session(s)`);
  return { applied: true, count: changed };
}

// ── Integrity (staleness) ─────────────────────────────────────────────────

// Project the whitelisted SEMANTIC upstream fields per step. Never include
// `updatedAt` or other churn — only fields whose change should invalidate a
// downstream lock.
function projectAesthetic(universe) {
  const inf = universe?.influences || {};
  return {
    logline: universe?.logline || '',
    premise: universe?.premise || '',
    styleNotes: universe?.styleNotes || '',
    influencesEmbrace: Array.isArray(inf.embrace) ? inf.embrace : [],
    influencesAvoid: Array.isArray(inf.avoid) ? inf.avoid : [],
  };
}
function projectArc(series) {
  const arc = series?.arc || {};
  return {
    logline: arc.logline || '',
    summary: arc.summary || '',
    protagonistArc: arc.protagonistArc || '',
    themes: Array.isArray(arc.themes) ? arc.themes : [],
    shape: arc.shape || null,
    ...(arc.seriesDesign ? { seriesDesign: arc.seriesDesign } : {}),
  };
}
// Project the SEMANTIC content of each canon character — the same prompt-field
// whitelist the bible extractor / evaluator use (`physicalDescription`,
// `personality`, `role`, etc.), which excludes ids/timestamps/source churn by
// construction. A bare `{ name, descriptor }` would only change on add / remove
// / rename — canon characters carry no `descriptor` field, so editing a locked
// character's body fields out-of-band (the #731 case) would never flag stale.
function projectCast(universe) {
  return (Array.isArray(universe?.characters) ? universe.characters : [])
    .map((c) => pickPromptFields(BIBLE_KIND.CHARACTER, c));
}
// The plotArc step generates AND persists the season breakdown, so a locked
// plotArc must fingerprint the seasons' editorial content alongside the arc
// core — editing a season title/logline/synopsis/episode-count out-of-band
// otherwise leaves the lock un-flagged. Excludes render slots (cover/backCover)
// and operational churn (id/status/timestamps) — only the editorial fields the
// step produces and the user reviews.
function projectSeasons(series) {
  return (Array.isArray(series?.seasons) ? series.seasons : []).map((s) => ({
    number: s?.number ?? 0,
    title: s?.title || '',
    logline: s?.logline || '',
    synopsis: s?.synopsis || '',
    episodeCountTarget: s?.episodeCountTarget ?? 0,
    themes: Array.isArray(s?.themes) ? s.themes : [],
    endingHook: s?.endingHook || '',
  }));
}

function buildUpstreamInputs(session, universe, series) {
  const aesthetic = projectAesthetic(universe);
  const arc = projectArc(series);
  const seasons = projectSeasons(series);
  const readerMap = series?.arc?.readerMap || null;
  const cast = projectCast(universe);
  // The idea step expands seedIdea into universe.starterPrompt + series
  // logline/premise. Those are non-deterministic LLM outputs, so seedIdea
  // alone is NOT a sufficient proxy for "idea-step content unchanged" — re-
  // running idea expand can produce a different starterPrompt with the same
  // seed, and downstream steps (aesthetic, plotArc) consume those outputs.
  // Including them in the downstream hashes flags those locked steps stale
  // when idea is regenerated.
  const ideaOutputs = {
    starterPrompt: universe?.starterPrompt || '',
    seriesLogline: series?.logline || '',
    seriesPremise: series?.premise || '',
  };
  // Each step's hash folds in its OWN outputs (`ownOutputs`) alongside its
  // upstream inputs. The session lock only gates the wizard UI — the underlying
  // universe/series records stay editable in Universe Builder, Arc Planner, etc.
  // Fingerprinting a step's own output means an out-of-band edit to that content
  // (e.g. changing universe.logline directly while the aesthetic step is locked)
  // flags the locked step stale, not just edits to an earlier step's inputs
  // (#731). The `issues`/`production` steps carry no `ownOutputs` — their output
  // lives in large child-record collections already covered by their upstream
  // inputs, and hashing every child issue/page would be needless churn.
  return {
    idea: { intakeMode: session.intakeMode, seedIdea: session.seedIdea || '', ownOutputs: ideaOutputs },
    universeAesthetic: { seedIdea: session.seedIdea || '', ideaOutputs, ownOutputs: aesthetic },
    plotArc: { aesthetic, seedIdea: session.seedIdea || '', ideaOutputs, ownOutputs: { arc, seasons } },
    readerMap: { arc, ownOutputs: readerMap },
    characters: { readerMap, arcSummary: arc.summary, aesthetic, ownOutputs: cast },
    issues: { arc, readerMap, cast },
    production: { arc, readerMap, cast },
  };
}

/**
 * Compute the current upstream hash for every step from the live universe +
 * series records. Pure-on-read — does not mutate the session.
 */
export async function computeCurrentHashes(session) {
  const universe = session.universeId ? await getUniverse(session.universeId).catch(() => null) : null;
  const series = session.seriesId ? await getSeries(session.seriesId).catch(() => null) : null;
  const inputs = buildUpstreamInputs(session, universe, series);
  const hashes = {};
  for (const id of STEP_IDS) hashes[id] = hashUpstream(id, inputs[id]);
  return { hashes, universe, series };
}

/**
 * Load a session augmented with the computed `staleSteps` array (the locked
 * steps whose upstream inputs have drifted since lock time). This is the shape
 * the route serves to the client.
 *
 * Staleness baseline depends on the sync mode (#730):
 *  - local-only (default): compare each locked step's frozen `upstreamHash`
 *    against the LIVE recompute, so any out-of-band record edit flags stale
 *    (#731). Correct within one install.
 *  - sync (`session.sync === true`): compare against the session-carried
 *    `syncedHashes` baseline instead of live records. The baseline travels with
 *    the session, so a peer's universe edit that hasn't been reconciled can't
 *    false-positive-stale a session that synced across machines. The user
 *    re-snapshots the baseline to live via `reconcileStorySession`.
 */
export async function getStorySessionView(id) {
  const session = await getStorySession(id);
  const { hashes, universe, series } = await computeCurrentHashes(session);
  const baseline = session.sync === true ? (session.syncedHashes || {}) : hashes;
  const staleSteps = computeStaleSteps(session, baseline);
  // For a synced session, also report whether THIS machine's live records have
  // drifted from the carried baseline — the "reconcile would adopt new state"
  // signal the UI shows next to the reconcile action (#730). Always false for
  // local-only sessions (their staleness already live-diffs).
  const syncDrift = session.sync === true
    ? computeSyncDrift(session, hashes, session.syncedHashes || {})
    : false;
  return { session, staleSteps, syncDrift, universe, series };
}

// Persist sync mode + (when enabled) a fresh live-hash baseline. Both
// reconcile and sync-enable do exactly this — snapshot the current live hashes
// as the carried staleness baseline; disabling drops the baseline entirely.
// `hashes` is computed by the caller (outside the write queue) so disabling
// skips the universe/series read it doesn't need.
async function writeSyncState(id, enabled, hashes) {
  return store().queueRecordWrite(id, async () => {
    const cur = await store().loadOne(id);
    if (!cur || cur.deleted) throw codedError(`Story Builder session not found: ${id}`, ERR_NOT_FOUND);
    const next = sanitizeSession({
      ...cur,
      sync: enabled === true,
      ...(enabled === true ? { syncedHashes: hashes } : {}),
      updatedAt: nowIso(),
    });
    await store().saveOneNow(next.id, next);
    return next;
  });
}

/**
 * Re-snapshot a sync-enabled session's `syncedHashes` baseline to the CURRENT
 * live records. This is the explicit "adopt this machine's universe/series
 * state as the new staleness baseline" gesture — the only thing that moves the
 * carried baseline across steps on a synced session. Rejects a local-only
 * session: reconcile is a re-baseline gesture, NOT a sync-enable one (use
 * `setStorySessionSync` to turn sync on), so calling it on a session with
 * sync off is a no-op-with-surprising-side-effect we'd rather surface loudly.
 */
export async function reconcileStorySession(id) {
  const session = await getStorySession(id);
  if (session.sync !== true) {
    throw codedError('Cross-machine resume is off for this session — enable it before reconciling', ERR_VALIDATION);
  }
  const { hashes } = await computeCurrentHashes(session);
  return writeSyncState(id, true, hashes);
}

/**
 * Toggle cross-machine resume on/off for a session (#730). Turning it ON
 * snapshots the current live hashes as the staleness baseline (so the user
 * doesn't start out "stale against nothing"); turning it OFF drops the baseline
 * and reverts to live-diff staleness.
 */
export async function setStorySessionSync(id, enabled) {
  const on = enabled === true;
  const session = await getStorySession(id);
  const { hashes } = on ? await computeCurrentHashes(session) : { hashes: {} };
  return writeSyncState(id, on, hashes);
}

// ── State machine: lock / unlock ──────────────────────────────────────────

// Apply (or release) the underlying record lock that backs a step, so the
// existing generate guards (locked-arc, locked-readerMap, locked-canon) take
// effect. Best-effort per step; the session lock is the source of truth for
// the wizard gate, the record lock is the enforcement at the generator.
async function applyUnderlyingLock(session, stepId, locked) {
  if (stepId === 'universeAesthetic' && session.universeId) {
    const universe = await getUniverse(session.universeId).catch(() => null);
    if (!universe) return;
    const nextLocked = { ...(universe.locked || {}) };
    for (const f of AESTHETIC_LOCK_FIELDS) {
      if (locked) nextLocked[f] = true;
      else delete nextLocked[f];
    }
    await updateUniverse(session.universeId, { locked: nextLocked });
  } else if (stepId === 'plotArc' && session.seriesId) {
    const series = await getSeries(session.seriesId).catch(() => null);
    if (!series) return;
    const nextLocked = { ...(series.locked || {}) };
    if (locked) nextLocked.arc = true;
    else delete nextLocked.arc;
    await updateSeries(session.seriesId, { locked: nextLocked });
  } else if (stepId === 'readerMap' && session.seriesId) {
    await setArcFieldLock(session.seriesId, 'readerMap', locked);
  }
  // NOTE: the 'characters' step deliberately has NO underlying record lock.
  // Universe canon is shared across series, and per-entry character locks are
  // user-managed (in the Universe Builder / via this step's per-entry Refine).
  // Blanket-toggling locked on every character would clobber those individual
  // locks and mutate a universe other series depend on. The session-level step
  // lock alone gates the wizard; the UI hides the per-character Refine when the
  // step is locked.
}

export async function lockStep(id, stepId) {
  if (!isValidStepId(stepId)) throw codedError(`Unknown step: ${stepId}`, ERR_VALIDATION);
  const session = await getStorySession(id);
  const { hashes } = await computeCurrentHashes(session);
  await applyUnderlyingLock(session, stepId, true);
  return store().queueRecordWrite(id, async () => {
    const cur = await store().loadOne(id);
    if (!cur || cur.deleted) throw codedError(`Story Builder session not found: ${id}`, ERR_NOT_FOUND);
    const steps = { ...cur.steps };
    steps[stepId] = {
      ...steps[stepId],
      status: 'locked',
      locked: true,
      lockedAt: nowIso(),
      upstreamHash: hashes[stepId],
    };
    // A sync-enabled session keys staleness off its carried baseline, not live
    // records — so locking must also move the baseline to live for THIS step
    // (#730). Otherwise the just-locked step would compare its fresh
    // `upstreamHash` against a stale `syncedHashes` entry and report itself
    // stale on the next read. Re-baseline ONLY `stepId`: merging the whole live
    // `hashes` map would move every OTHER locked step's baseline to the current
    // (possibly peer-edited) records, re-introducing the exact false-positive
    // #730 exists to prevent. Cross-step re-baselining is the reconcile gesture.
    const next = sanitizeSession({
      ...cur,
      steps,
      ...(cur.sync === true
        ? { syncedHashes: { ...(cur.syncedHashes || {}), [stepId]: hashes[stepId] } }
        : {}),
      updatedAt: nowIso(),
    });
    await store().saveOneNow(next.id, next);
    return next;
  });
}

export async function unlockStep(id, stepId) {
  if (!isValidStepId(stepId)) throw codedError(`Unknown step: ${stepId}`, ERR_VALIDATION);
  const session = await getStorySession(id);
  await applyUnderlyingLock(session, stepId, false);
  return store().queueRecordWrite(id, async () => {
    const cur = await store().loadOne(id);
    if (!cur || cur.deleted) throw codedError(`Story Builder session not found: ${id}`, ERR_NOT_FOUND);
    const steps = { ...cur.steps };
    steps[stepId] = { status: 'ready', locked: false, lockedAt: null, upstreamHash: null };
    const next = sanitizeSession({ ...cur, steps, updatedAt: nowIso() });
    await store().saveOneNow(next.id, next);
    return next;
  });
}

/**
 * Set the wizard's current step.
 *
 * Advisory, not gated: a user may start from any point and work the steps out
 * of order (e.g. begin from a drafted comic script and backfill the idea / arc
 * afterward). The client surfaces "upstream not locked" / "stale" as warnings
 * (from the `staleSteps` array in the session view) rather than hard blocks.
 * The only enforcement that remains is at the generators themselves — a *locked*
 * underlying record (arc, readerMap, …) still refuses regeneration.
 */
export async function setCurrentStep(id, stepId) {
  if (!isValidStepId(stepId)) throw codedError(`Unknown step: ${stepId}`, ERR_VALIDATION);
  return updateStorySession(id, { currentStep: stepId });
}

// ── Per-issue locks (issues step loop) ────────────────────────────────────

export async function setIssueLock(id, issueId, locked) {
  if (!isStr(issueId) || !issueId) throw codedError('issueId is required', ERR_VALIDATION);
  return store().queueRecordWrite(id, async () => {
    const cur = await store().loadOne(id);
    if (!cur || cur.deleted) throw codedError(`Story Builder session not found: ${id}`, ERR_NOT_FOUND);
    const steps = { ...cur.steps };
    const issueLocks = { ...(steps.issues?.issueLocks || {}) };
    if (locked) issueLocks[issueId] = { locked: true, lockedAt: nowIso(), upstreamHash: null };
    else delete issueLocks[issueId];
    steps.issues = { ...steps.issues, issueLocks };
    const next = sanitizeSession({ ...cur, steps, updatedAt: nowIso() });
    await store().saveOneNow(next.id, next);
    return next;
  });
}

// ── Seed issues from the arc (issues step) ─────────────────────────────────

/**
 * Generate the per-episode breakdown for the linked series' seasons and
 * persist one issue per episode — so the user doesn't have to leave the
 * builder for the Pipeline. Delegates to arcPlanner.generateSeasonEpisodes
 * (per season) + commitEpisodesToIssues, the same path the Pipeline's
 * season-episodes route uses.
 *
 * Provider/model resolution mirrors generateStep: an explicit override wins,
 * else the session's saved picker choice (session.llm).
 *
 * Batch semantics: generateSeasonEpisodes throws on a locked season or one
 * with no synopsis/logline. In a multi-season run one bad season must not
 * abort the rest, so each season is caught independently — the eligible
 * seasons still produce issues. A caught season reports `skipped: true` when
 * it was genuinely ineligible (ARC_ERR_VALIDATION) and `failed: true` for any
 * other (transient provider/LLM) error, so the client never frames an infra
 * failure as a config skip. Successful seasons carry `skipped: false,
 * failed: false`.
 *
 * `options.seasonId` scopes generation to a single season; omit to cover every
 * season on the arc.
 *
 * Deliberately does NOT run the Pipeline route's post-create continuity canon
 * extraction (extractCanonFromProse). In the builder, canon is owned by the
 * dedicated `characters` step where the user curates it against the universe;
 * episode synopses here are thin idea-stage seeds, so auto-extracting canon
 * from them would push low-signal entries the user then has to clean up. Issue
 * creation is the focused job of this action — the characters step handles
 * canon.
 */
export async function generateIssuesFromArc(id, options = {}) {
  const session = await getStorySession(id);
  if (!session.seriesId) throw codedError('No series linked', ERR_VALIDATION);
  const series = await getSeries(session.seriesId);
  const seasons = Array.isArray(series?.seasons) ? series.seasons : [];
  if (seasons.length === 0) {
    throw codedError('No seasons on the arc yet — generate the plot arc first', ERR_VALIDATION);
  }

  const targetSeasons = options.seasonId
    ? seasons.filter((s) => s.id === options.seasonId)
    : seasons;
  if (options.seasonId && targetSeasons.length === 0) {
    throw codedError(`Season not found on series: ${options.seasonId}`, ERR_VALIDATION);
  }

  const reqProviderId = options.providerId || session.llm?.provider || undefined;
  const reqModel = options.model || session.llm?.model || undefined;

  const createdIssues = [];
  const seasonResults = [];
  for (const season of targetSeasons) {
    const label = season.title || `Volume ${season.number ?? '?'}`;
    const res = await generateSeasonEpisodes(session.seriesId, season.id, {
      providerOverride: reqProviderId,
      modelOverride: reqModel,
    }).catch((err) => ({ error: err }));
    if (res.error) {
      // generateSeasonEpisodes throws ARC_ERR_VALIDATION for genuinely
      // ineligible seasons (locked, or no synopsis/logline) — those are
      // `skipped` (expected config state). Any OTHER throw is a transient
      // failure (provider down, timeout, non-JSON) and is reported as
      // `failed` so the client never frames an infra error as "ineligible".
      // We still don't abort the batch — a blip on one season must not
      // discard issues already created for the others.
      const ineligible = res.error?.code === ARC_ERR_VALIDATION;
      const reason = res.error?.message || 'Failed to generate episodes';
      seasonResults.push({
        seasonId: season.id, title: label, created: 0,
        skipped: ineligible, failed: !ineligible, reason,
      });
      continue;
    }
    const issues = await commitEpisodesToIssues(session.seriesId, season.id, res.episodes, { preloadedSeries: series });
    createdIssues.push(...issues);
    seasonResults.push({ seasonId: season.id, title: label, created: issues.length, skipped: false, failed: false, runId: res.runId });
  }

  return { createdIssues, seasons: seasonResults };
}

// ── Backfill (generate upstream from downstream) ───────────────────────────

// ── Generate / refine delegation ──────────────────────────────────────────

// Each step's generate delegates to the existing service that owns its content,
// then persists into the universe/series record. Returns the LLM result so the
// route can surface runId / changes / rationale.
//
// `options.fromDownstream` flips a step from forward-generation to backfill:
// idea / plotArc synthesize themselves from the series' existing issue content
// instead of from their (possibly empty) conventional upstream.
export async function generateStep(id, stepId, options = {}) {
  const session = await getStorySession(id);
  // Provider/model resolution: an explicit per-call override wins, else fall
  // back to the session's saved picker choice (session.llm) so a single
  // selection at the top of the Story Builder drives every operation.
  const reqProviderId = options.providerId || session.llm?.provider || undefined;
  const reqModel = options.model || session.llm?.model || undefined;
  // Best-effort phase emitter for the SSE runner; a no-op on the synchronous
  // path (no onProgress passed) so this call stays byte-for-byte unchanged there.
  const emit = (label, phase) => options.onProgress?.({ label, phase });
  if (stepId === 'idea') {
    // Backfill: reverse-engineer the idea from existing issue content when the
    // user started downstream. Rendered only when present, so the forward path
    // (seed-only) is byte-for-byte unchanged.
    if (options.fromDownstream) emit('Reading existing issues…', 'collect');
    const sourceMaterial = options.fromDownstream ? await collectIssueSourceText(session.seriesId) : '';
    if (options.fromDownstream && !sourceMaterial) {
      throw codedError(
        'No issue content to backfill the idea from — write a comic script, teleplay, or prose on at least one issue first',
        ERR_VALIDATION,
      );
    }
    emit('Expanding the idea…', 'generate');
    const { content, runId, providerId, model } = await runStagedLLM(
      'story-builder-idea-expand',
      { universeName: session.title, seedIdea: session.seedIdea || '', sourceMaterial },
      { providerOverride: reqProviderId, modelOverride: reqModel, returnsJson: true, source: 'story-builder-idea-expand' },
    );
    const expandedIdea = isStr(content?.expandedIdea) ? content.expandedIdea.trim() : '';
    const logline = isStr(content?.logline) ? content.logline.trim() : '';
    emit('Saving…', 'persist');
    // Seed the universe starter + series premise/logline from the expansion.
    // Honor downstream lock keys: locking the universeAesthetic step sets
    // universe.locked.{logline,...} via applyUnderlyingLock, but
    // updateUniverse doesn't enforce those locks on scalar writes — so a
    // re-run of the idea step would otherwise silently clobber a locked
    // logline. Skip any scalar field the user has explicitly locked.
    if (session.universeId && expandedIdea) {
      const universe = await getUniverse(session.universeId);
      const patch = { starterPrompt: expandedIdea };
      if (logline && !universe?.locked?.logline) patch.logline = logline;
      await updateUniverse(session.universeId, patch);
    }
    if (session.seriesId && (logline || expandedIdea)) {
      await updateSeries(session.seriesId, { ...(logline ? { logline } : {}), ...(expandedIdea ? { premise: expandedIdea } : {}) });
    }
    return { result: content, runId, providerId, model };
  }
  if (stepId === 'universeAesthetic') {
    if (!session.universeId) throw codedError('No universe linked', ERR_VALIDATION);
    const universe = await getUniverse(session.universeId);
    emit('Expanding the aesthetic…', 'generate');
    const { preservedVariations, preservedCompositeSheets } = extractPreservedFromDraft(universe);
    const expanded = await expandWorldTemplate({
      starterPrompt: universe.starterPrompt || session.seedIdea || universe.name,
      influences: universe.influences,
      logline: universe.logline,
      premise: universe.premise,
      styleNotes: universe.styleNotes,
      locked: universe.locked,
      preservedVariations,
      preservedCompositeSheets,
      providerId: reqProviderId,
      model: reqModel,
    });
    emit('Saving…', 'persist');
    // Persist the WHOLE expansion (categories, composite sheets, canon) through
    // the same merge the Universe Builder page uses — never a wholesale write:
    // updateUniverse replaces compositeSheets + canon arrays, so a re-run on a
    // curated universe must merge against the LATEST record (the mutator form
    // runs inside the record's write queue, after the multi-minute LLM call)
    // to keep locked fields, pinned variations/sheets, and existing canon.
    const updated = await updateUniverse(session.universeId, (cur) => {
      const { expandedDraft } = mergeExpandIntoDraft(cur, expanded, { mergeInfluences: mergeInfluencesWithLocks });
      return {
        logline: expandedDraft.logline,
        premise: expandedDraft.premise,
        styleNotes: expandedDraft.styleNotes,
        influences: expandedDraft.influences,
        categories: expandedDraft.categories,
        compositeSheets: expandedDraft.compositeSheets,
        characters: expandedDraft.characters,
        places: expandedDraft.places,
        objects: expandedDraft.objects,
      };
    });
    return { result: updated, providerId: expanded.providerId, model: expanded.model };
  }
  if (stepId === 'plotArc') {
    if (!session.seriesId) throw codedError('No series linked', ERR_VALIDATION);
    let arcGenResult;
    if (options.fromDownstream) {
      // Backfill: extract the arc + seasons from the issues that already exist
      // (the user drafted scripts/prose first). Reuses the importer's
      // arc-extraction prompt via arcPlanner.generateArcFromSource.
      emit('Reading existing issues…', 'collect');
      const sourceText = await collectIssueSourceText(session.seriesId);
      if (!sourceText) {
        throw codedError(
          'No issue content to backfill the arc from — write a comic script, teleplay, or prose on at least one issue first',
          ERR_VALIDATION,
        );
      }
      emit('Extracting the plot arc…', 'generate');
      arcGenResult = await generateArcFromSource(session.seriesId, {
        sourceText, providerOverride: reqProviderId, modelOverride: reqModel,
      });
    } else {
      emit('Planning the plot arc…', 'generate');
      arcGenResult = await generateArcOverview(session.seriesId, {
        providerOverride: reqProviderId, modelOverride: reqModel,
      });
    }
    const { arc, seasons, runId, providerId, model } = arcGenResult;
    // A null arc means the LLM returned nothing identifying — refuse rather
    // than wiping a previously-generated arc with `updateSeries({ arc: null })`.
    if (!arc) throw codedError('LLM returned an empty arc — try regenerating', ERR_VALIDATION);
    // Route through commitSeasonsWithRemap so per-field arc locks, per-season
    // locks, and orphaned child issues are all honored — same path the Arc
    // Canvas's regenerate uses. A plain updateSeries({ arc, seasons }) would
    // bypass mergeArcWithLocks / mergeSeasonsWithLocks / buildSeasonRemap and
    // silently wipe locked seasons and orphan their issues.
    emit('Saving seasons…', 'persist');
    const series = await getSeries(session.seriesId);
    const { series: updated } = await commitSeasonsWithRemap(series, { arc, seasons });
    return { result: updated, runId, providerId, model };
  }
  if (stepId === 'readerMap') {
    if (!session.seriesId) throw codedError('No series linked', ERR_VALIDATION);
    emit('Mapping reader emotion…', 'generate');
    const { readerMap, runId, providerId, model } = await generateReaderMap(session.seriesId, {
      providerOverride: reqProviderId, modelOverride: reqModel,
    });
    emit('Saving…', 'persist');
    const series = await getSeries(session.seriesId);
    const updated = await updateSeries(session.seriesId, { arc: { ...(series.arc || {}), readerMap } });
    return { result: updated, runId, providerId, model };
  }
  throw codedError(`Generate is not supported for step "${stepId}"`, ERR_VALIDATION);
}

export async function refineStep(id, stepId, { feedback, entryId, providerId, model, onProgress } = {}) {
  const session = await getStorySession(id);
  // Same fallback as generateStep: explicit override → session picker choice.
  const reqProviderId = providerId || session.llm?.provider || undefined;
  const reqModel = model || session.llm?.model || undefined;
  const emit = (label, phase) => onProgress?.({ label, phase });
  if (stepId === 'universeAesthetic') {
    if (!session.universeId) throw codedError('No universe linked', ERR_VALIDATION);
    const universe = await getUniverse(session.universeId);
    emit('Refining the aesthetic…', 'generate');
    const refined = await refineWorldPrompts({
      starterPrompt: universe.starterPrompt || universe.name,
      logline: universe.logline,
      premise: universe.premise,
      styleNotes: universe.styleNotes,
      influences: universe.influences,
      locked: universe.locked,
      feedback,
      providerId: reqProviderId,
      model: reqModel,
    });
    emit('Saving…', 'persist');
    const updated = await updateUniverse(session.universeId, {
      logline: refined.logline,
      premise: refined.premise,
      styleNotes: refined.styleNotes,
      ...(refined.influences ? { influences: refined.influences } : {}),
    });
    return { result: updated, changes: refined.changes || [], rationale: refined.rationale || '' };
  }
  if (stepId === 'plotArc') {
    if (!session.seriesId) throw codedError('No series linked', ERR_VALIDATION);
    emit('Refining the plot arc…', 'generate');
    const { arc, changes, rationale, runId, providerId: usedProviderId, model: usedModel } = await refineArc(session.seriesId, feedback, { providerId: reqProviderId, model: reqModel });
    emit('Saving…', 'persist');
    // Persist arc-ONLY (never the season breakdown), so we deliberately do NOT
    // route through commitSeasonsWithRemap — passing a stale season snapshot as
    // the "proposed" set there could mis-remap/orphan a season edited during the
    // LLM call. Re-read the latest series, apply per-field arc locks via
    // mergeArcWithLocks (the same guard commitSeasonsWithRemap uses), and write
    // only `arc` — seasons are untouched.
    const latest = await getSeries(session.seriesId);
    // Re-check the whole-arc lock against the LATEST series, not just the
    // pre-LLM snapshot refineArc saw — commitSeasonsWithRemap does the same, and
    // dropping that re-check (this path bypasses it) would let a refine land if
    // the arc was locked while the LLM call was in flight.
    if (latest.locked?.arc === true) {
      throw codedError('Arc is locked — unlock it on the Arc Canvas before refining', ARC_ERR_VALIDATION);
    }
    const mergedArc = mergeArcWithLocks(latest.arc, { ...arc, seriesDesign: latest.arc?.seriesDesign }, latest.locked?.arcFields);
    const updated = await updateSeries(session.seriesId, { arc: mergedArc });
    return { result: updated, changes, rationale, runId, providerId: usedProviderId, model: usedModel };
  }
  if (stepId === 'readerMap') {
    if (!session.seriesId) throw codedError('No series linked', ERR_VALIDATION);
    emit('Refining the reader map…', 'generate');
    const { readerMap, changes, rationale, runId, providerId: usedProviderId, model: usedModel } = await refineReaderMap(session.seriesId, feedback, { providerId: reqProviderId, model: reqModel });
    emit('Saving…', 'persist');
    const series = await getSeries(session.seriesId);
    const updated = await updateSeries(session.seriesId, { arc: { ...(series.arc || {}), readerMap } });
    return { result: updated, changes, rationale, runId, providerId: usedProviderId, model: usedModel };
  }
  if (stepId === 'characters') {
    if (!session.universeId) throw codedError('No universe linked', ERR_VALIDATION);
    if (!isStr(entryId)) throw codedError('entryId is required to refine a character', ERR_VALIDATION);
    emit('Refining the character…', 'generate');
    const out = await refineUniverseCharacter(session.universeId, entryId, { providerId: reqProviderId, model: reqModel });
    return { result: out.universe, changes: out.changes || [], rationale: out.rationale || '' };
  }
  throw codedError(`Refine is not supported for step "${stepId}"`, ERR_VALIDATION);
}