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

38.4 KB
Raw Blame
/**
 * Pipeline — Editorial Check Runner (#1284).
 *
 * Loads the enabled editorial checks (+ per-check config) from settings, builds
 * the shared `ctx` once (series, issues, universe canon, stitched manuscript),
 * runs each check, and seeds the resulting findings into the existing
 * `manuscriptReview` store — each finding stamped with its `checkId` so the
 * editor groups/filters by check and a dismissal stays suppressed per-check.
 *
 * Deterministic checks run inline; LLM checks reuse the staged-LLM provider
 * plumbing via the `ctx.callStagedLLM` injected here (the registry stays pure).
 *
 * The SSE wrapper at the bottom mirrors manuscriptCompletenessRunner.js: a
 * single in-memory `runs` map keyed by seriesId, terminal-frame replay for
 * late-connecting clients via lib/sseUtils.js.
 */

import { randomUUID } from 'crypto';
import { createSseRunner } from '../../../lib/sseUtils.js';
import { runStagedLLM, runInlineLLM, runStageScopedInlineLLM, resolveStageContext } from '../../stageRunner.js';
import { planManuscriptPass, fitContextToManuscriptFloor, estimateTokens, MANUSCRIPT_FLOOR_TOKENS } from '../../../lib/contextBudget.js';
import { getEnabledChecks, getEnabledCheckRows, getAllChecks, applySeriesCheckConfig, orderChecksByDependencies, buildCustomCheck, CUSTOM_CHECK_ID_PREFIX } from '../../../lib/editorial/index.js';
import { getSettings } from '../../settings.js';
import { getSeries } from '../series.js';
import { listIssuesForSeries } from '../issues.js';
import { getSeriesCanon } from '../seriesCanon.js';
import { collectManuscriptSections, sectionsCorpus, manuscriptSectionHeader } from '../arcPlanner.js';
import { getReverseOutline } from '../reverseOutline.js';
import { getFactsLedger } from '../continuityBible.js';
import { getSeriesEditorial } from '../editorialAnalysis.js';
import { seedReviewFromFindings } from '../manuscriptReview.js';
import { recordTrendSnapshot } from '../editorialScore.js';
import { readReadinessGate, mergeSeverityWeights } from '../../../lib/editorial/index.js';
import {
  buildEditorialSourceProjection,
  checkSources,
  effectiveCheckSources,
  fingerprintForCheck,
} from './reviewStaleness.js';

export { effectiveCheckSources, getReviewWithStaleness } from './reviewStaleness.js';

// Per-check severity breakdown for telemetry (#1578). Bucket a check's findings
// by severity so the autopilot SSE stream can show a per-check high/medium/low
// breakdown mid-run, not just a total count. Mirror manuscriptReview's
// sanitizeComment normalization (unknown/absent → 'medium') so the live frame
// agrees with how the findings ultimately score in the review.
const SEVERITY_BUCKETS = Object.freeze(['high', 'medium', 'low']);
function severityBreakdown(findings) {
  const counts = { high: 0, medium: 0, low: 0 };
  for (const f of Array.isArray(findings) ? findings : []) {
    const sev = SEVERITY_BUCKETS.includes(f?.severity) ? f.severity : 'medium';
    counts[sev] += 1;
  }
  return counts;
}

// Inter-check context sharing (#1627). Build the read-only `ctx.priorFindings` a
// check sees: the stamped findings produced EARLIER this pass by the checks it
// named in `dependsOn`. Scoped to declared deps so a non-declaring check always
// gets the shared EMPTY array (fully order-independent — identical to pre-#1627
// behavior), and a check can only couple to a prior check it explicitly depended
// on. Frozen — the array AND each finding (shallow) — so a check reads but can't
// mutate the shared accumulator or another check's already-seeded finding.
const EMPTY_PRIOR_FINDINGS = Object.freeze([]);
export function buildScopedPriorFindings(findings, dependsOn) {
  const deps = Array.isArray(dependsOn) ? dependsOn : [];
  if (!deps.length || !Array.isArray(findings) || !findings.length) return EMPTY_PRIOR_FINDINGS;
  const want = new Set(deps);
  const scoped = findings.filter((f) => want.has(f?.checkId)).map((f) => Object.freeze({ ...f }));
  return scoped.length ? Object.freeze(scoped) : EMPTY_PRIOR_FINDINGS;
}

// Output room reserved for an editorial check's findings JSON. Sized for the
// editorial output (a bounded findings list — far smaller than the completeness
// pass's full-page rewrites), NOT the 8_000-token contextBudget default: that
// default exceeds the 8_192-token fallback window, so inheriting it would drive
// the usable input budget to 0 on an unknown/small local provider — the exact
// case this chunking targets — and silently feed the model an empty manuscript.
const EDITORIAL_OUTPUT_RESERVE_TOKENS = 2_000;

/**
 * Build the shared `ctx` every editorial check reads (series, stitched
 * manuscript, canon, reverse outline, arcs, comic/storyboard projections, the
 * injected LLM callers + provider-sized manuscript chunker). Extracted from
 * runEditorialChecks so the dry-run preview path (#1607) reuses the IDENTICAL
 * context construction — same per-source I/O gating and provider-sized chunking
 * a real run would use — without persisting anything.
 *
 * Only pays the I/O an enabled check actually consumes: the `needs*` gates read
 * each check's declared `sources`, so a run of a canon-only check skips the
 * manuscript-collection / reverse-outline / issue fetches entirely.
 *
 * @param {string} seriesId
 * @param {Array<{check: object}>} enabled — the enabled (or previewed) checks
 * @param {object} [opts] — providerOverride/Default, modelOverride/Default, effortDefault, signal
 * @returns {Promise<{ series, baseCtx, resolvedSources }>}
 */
export async function buildEditorialContext(seriesId, enabled, { providerOverride, providerDefault, modelOverride, modelDefault, effortDefault, signal, checkById = null } = {}) {
  const series = await getSeries(seriesId);
  // Gate each fetch on EFFECTIVE sources — a check's own sources plus its declared
  // dependencies' (#1627) — so a dependency-consuming check pulls (and fingerprints)
  // its dependency's inputs even when that dependency is disabled this run, keeping
  // the seed-time and read-time hashes symmetric. With no deps this is exactly the
  // check's own sources, so a run with no dependency declarations is unchanged.
  const sourcesOf = (check) => effectiveCheckSources(check, checkById);
  const needsManuscript = enabled.some(({ check }) => check.needsManuscript || sourcesOf(check).includes('manuscript'));
  // Reverse-outline fetch is gated on the declared source (#1296) so a run with no
  // scene-segmentation check pays no extra I/O — mirrors the needsManuscript gate.
  // Either the scenes (`reverseOutline`) OR the plotline list (`reverseOutline.plotlines`,
  // #1310) is served by the same single outline fetch.
  const needsReverseOutline = enabled.some(({ check }) => {
    const sources = sourcesOf(check);
    return sources.includes('reverseOutline') || sources.includes('reverseOutline.plotlines');
  });
  // Editorial-arc fetch is gated on the declared source (#1295) so a run with no
  // POV/arc check pays no extra snapshot I/O — mirrors the needsReverseOutline gate.
  const needsEditorialArcs = enabled.some(({ check }) => sourcesOf(check).includes('editorialArcs'));
  // Continuity-bible ledger fetch is gated on the declared source (#1581) so a run
  // with no contradiction check pays no extra ledger I/O — mirrors the other gates.
  const needsContinuityBible = enabled.some(({ check }) => sourcesOf(check).includes('continuityBible'));
  // Issues are fetched only when an enabled check declares an issue-derived source
  // — storyboard.shots (#1315), comicScript (#1313, served via the comic.lettering
  // check's ctx.issues), or the comic-pacing tokens comicScript.pacing /
  // comicScript.layout (#1314, served via the same ctx.issues projection). All
  // projections feed off the same UNCAPPED per-series scan (#1469): listIssues caps
  // at ISSUES_PER_RESPONSE_MAX (1000), silently skipping every storyboard scene /
  // comic page past the 1000th issue. Mirrors the gate + fetch on the
  // getReviewWithStaleness path below.
  const needsIssues = enabled.some(({ check }) => {
    const sources = sourcesOf(check);
    return sources.includes('storyboard.shots')
      || sources.includes('comicScript')
      || sources.includes('comicScript.pacing')
      || sources.includes('comicScript.layout')
      || sources.includes('prose');
  });
  const [sections, canon, issues, outline, editorial, bible] = await Promise.all([
    needsManuscript ? collectManuscriptSections(seriesId) : Promise.resolve([]),
    getSeriesCanon(series),
    needsIssues ? listIssuesForSeries(seriesId).catch(() => []) : Promise.resolve([]),
    needsReverseOutline ? getReverseOutline(seriesId).catch(() => null) : Promise.resolve(null),
    // Reuse the already-loaded series so the aggregate skips a redundant getSeries.
    // (issues is fetched in this same Promise.all, so it can't be passed here —
    // it's still in the temporal dead zone — and stays an internal fetch.)
    needsEditorialArcs ? getSeriesEditorial(seriesId, { series }).catch(() => null) : Promise.resolve(null),
    needsContinuityBible ? getFactsLedger(seriesId).catch(() => null) : Promise.resolve(null),
  ]);
  const manuscript = sectionsCorpus(sections);
  const {
    continuityBible,
    storyboardScenes,
    reverseOutline,
    reverseOutlinePlotlines,
    editorialArcs,
    editorialArcsComplete,
    resolvedSources,
  } = buildEditorialSourceProjection({
    manuscript,
    canon,
    series,
    issues,
    outline,
    editorial,
    bible,
  });
  const baseCtx = {
    seriesId,
    series,
    issues,
    sections,
    manuscript,
    reverseOutline,
    reverseOutlinePlotlines,
    editorialArcs,
    editorialArcsComplete,
    storyboardScenes,
    canon,
    continuityBible,
    providerOverride,
    providerDefault,
    modelOverride,
    modelDefault,
    effortDefault,
    // The run's AbortSignal, so a multi-chunk LLM check can stop launching
    // further chunk calls mid-run (the runner only checks it before/after each
    // check.run()). Mirrors the per-chunk cancel check in the completeness pass.
    signal,
    // Injected LLM caller — keeps server/lib/editorial pure. Forwards the
    // provider/model overrides so an LLM check honors the autopilot's choice.
    callStagedLLM: (stage, vars, opts = {}) =>
      runStagedLLM(stage, vars, { providerOverride, providerDefault, modelOverride, modelDefault, effortDefault, ...opts }),
    // Injected inline-prompt caller for user-defined checks (#1346) whose prompt
    // body is authored from the UI (no shipped stage template). Same provider/
    // model overrides as callStagedLLM so a custom check honors the run's choice.
    callInlineLLM: (prompt, opts = {}) =>
      runInlineLLM(prompt, { providerOverride, providerDefault, modelOverride, modelDefault, effortDefault, ...opts }),
    // Inline-prompt caller that resolves the provider/model from a NAMED STAGE's
    // pin (#1403). The cross-chunk setup-summary call rides alongside a stage-
    // pinned manuscript check, so it must run on the SAME provider as that stage —
    // routing it through the active provider (plain callInlineLLM) could leak
    // manuscript text to a different (e.g. cloud) provider than the stage chose.
    callStageScopedInlineLLM: (stage, prompt, opts = {}) =>
      runStageScopedInlineLLM(stage, prompt, { providerOverride, providerDefault, modelOverride, modelDefault, effortDefault, ...opts }),
    // Injected manuscript chunker — plans the stitched manuscript into chunks
    // sized to `stage`'s resolved provider context window (reusing the same
    // budgeter as the completeness pass), so a long series is fully reviewed
    // instead of truncated on a small/local provider. Returns the chunk-corpus
    // strings (one for a whole-fits provider) for an LLM check to iterate.
    // Lives here (not the pure registry) because it resolves the provider.
    //
    // Two ways to declare per-chunk overhead:
    //   { overheadTokens }                — legacy: a fixed, non-trimmable overhead
    //                                       (the custom-check prompt wrapper).
    //   { context, fixedOverheadTokens }  — the trimmable re-sent context blocks
    //                                       (scene map, character arcs, …) plus the
    //                                       fixed template/contract overhead. The
    //                                       context is trimmed to GUARANTEE the
    //                                       manuscript a budget floor (#1459) so a
    //                                       large reverse outline on a small window
    //                                       can't starve the manuscript chunk to ''.
    // When `context` is given, the (possibly trimmed) blocks are attached to the
    // returned array as `.context` so the check feeds the trimmed values to the LLM.
    planManuscriptChunks: async (stage, { overheadTokens = 0, context = null, fixedOverheadTokens = 0 } = {}) => {
      if (!sections.length) return [];
      const { contextWindow } = await resolveStageContext(stage, { providerOverride, providerDefault, modelOverride, modelDefault });
      let effectiveOverhead = overheadTokens;
      let fittedContext = null;
      if (context && typeof context === 'object') {
        // Reserve no more than the manuscript actually needs: a short manuscript
        // that fits alongside the full context shouldn't get its context trimmed
        // just to hold open the full floor. Cap the reserved floor at the
        // manuscript's own token cost (the floor only bites a manuscript large
        // enough to want it).
        const floorTokens = Math.min(MANUSCRIPT_FLOOR_TOKENS, estimateTokens(manuscript));
        const fit = fitContextToManuscriptFloor(context, {
          contextWindow,
          fixedOverheadTokens,
          outputReserveTokens: EDITORIAL_OUTPUT_RESERVE_TOKENS,
          floorTokens,
        });
        effectiveOverhead = fit.overheadTokens;
        fittedContext = fit.context;
        if (fit.trimmed) {
          console.warn(`✂️ editorial context trimmed to keep manuscript budget — stage=${stage || 'inline'} window=${contextWindow}`);
        }
      }
      const plan = planManuscriptPass({
        contextWindow,
        // Each section's full contribution = header + body, matching sectionsCorpus.
        sections: sections.map((s) => ({ ...s, text: `${manuscriptSectionHeader(s)}\n\n${s.content || ''}` })),
        overheadTokens: effectiveOverhead,
        outputReserveTokens: EDITORIAL_OUTPUT_RESERVE_TOKENS,
      });
      // One whole chunk or many — the same usable-char budget caps each. Do NOT
      // floor this above plan.usableChars: on a genuinely small configured window
      // that would push the prompt back over the provider's context and get it
      // clipped/rejected. The editorial-sized output reserve above plus the
      // context floor (when context is given) is what keeps usableChars positive
      // on the common unknown/8K-fallback provider.
      const corpora = plan.mode === 'whole'
        ? [manuscript]
        : plan.chunks.map((c) => sectionsCorpus(c.sections));
      const chunks = corpora.map((c) => c.slice(0, plan.usableChars));
      // Expose the per-chunk budget so a cross-chunk-digest check can fit its
      // digest into each chunk's spare room without overflowing the window or
      // displacing manuscript text (see runChunkedManuscriptCheck).
      chunks.usableChars = plan.usableChars;
      // Expose the trimmed context so the check sends the SAME (possibly shrunk)
      // blocks it was budgeted for — sending the untrimmed originals would overflow
      // the window the trim was computed to fit.
      if (fittedContext) chunks.context = fittedContext;
      return chunks;
    },
  };
  return { series, baseCtx, resolvedSources };
}

/**
 * Run the enabled editorial checks for a series and seed their findings into the
 * manuscript review.
 *
 * @param {string} seriesId
 * @param {object} [options]
 *   - checkIds: string[] — run only this subset (default: all enabled)
 *   - settings: object — pre-loaded settings (default: read fresh)
 *   - providerOverride / modelOverride — hard provider/model, forwarded to LLM checks
 *   - providerDefault / modelDefault / effortDefault — soft run-level default
 *     provider/model/reasoning effort (Series Autopilot), forwarded to LLM checks
 *     (each loses to the matching per-stage pin)
 *   - signal: AbortSignal — checked between checks for cancellation
 *   - onProgress: (event) => void — { type: 'check:start'|'check:complete', ... }
 * @returns {Promise<{ runId, findings, perCheck, canceled }>}
 */
export async function runEditorialChecks(seriesId, options = {}) {
  const { checkIds = null, providerOverride, providerDefault, modelOverride, modelDefault, effortDefault, signal, onProgress } = options;
  const settings = options.settings || await getSettings();
  const enabled = getEnabledChecks(settings, checkIds);

  const runId = randomUUID();
  if (enabled.length === 0) {
    return { runId, findings: [], perCheck: [], canceled: false };
  }

  // Every registered check by id (built-ins + custom), so a dependency-consuming
  // check's I/O gates + staleness fingerprint can fold in its declared
  // dependencies' sources (#1627). Resolved against the FULL registry so it matches
  // the read-time map in getReviewWithStaleness even when a dependency is disabled.
  const checkById = new Map(getAllChecks(settings).map((c) => [c.id, c]));
  // Build the shared context once — every check reads from this (extracted to
  // buildEditorialContext so the dry-run preview path reuses the exact same
  // provider-sized chunking + source resolution as a real run, #1607).
  const { series, baseCtx, resolvedSources } = await buildEditorialContext(seriesId, enabled, { providerOverride, providerDefault, modelOverride, modelDefault, effortDefault, signal, checkById });
  // Overlay this series' per-check config overrides (#1591) onto the global
  // resolved config. The `needs*` gates inside the builder read only `check`
  // (config-independent); only the run loop consumes the merged config here.
  const enabledResolved = applySeriesCheckConfig(enabled, series?.editorialCheckConfig);
  // Order the pass so a check's declared dependencies (#1627) run before it — the
  // runner injects each dependency's findings into the dependent's
  // `ctx.priorFindings`, so they must already be in the `findings` accumulator.
  // A pass where nothing declares `dependsOn` keeps the exact registry order.
  const enabledOrdered = orderChecksByDependencies(enabledResolved);

  const findings = [];
  const perCheck = [];
  // Deterministic checks self-heal (see seeding below): track which ones actually
  // RAN to completion this pass (not gated-out, not errored), so we can fresh-mode
  // reconcile each of them — including those that produced zero findings, which
  // must dismiss their now-stale prior open comments.
  const deterministicRanIds = new Set();
  // Every check (any kind) that ran to completion this pass (#1596). The review
  // seed scopes its severity re-grade to this set, so a targeted subset run — or
  // the completeness pass — never rewrites the severity of comments for checks it
  // didn't run (which would silently clear an unrelated check's active pin).
  const ranCheckIds = new Set();
  let canceled = false;
  for (const { check, config, severityOverride } of enabledOrdered) {
    if (signal?.aborted) { canceled = true; break; }
    onProgress?.({ type: 'check:start', checkId: check.id, label: check.label });
    // Run every check with its NATIVE default severity (#1596). A per-check
    // override is applied AUTHORITATIVELY as a post-stamp below rather than via
    // ctx, so escalation / LLM per-finding severities are computed natively and
    // preserved as `nativeSeverity` — which lets a later "reset to Default"
    // restore the true native level on carried findings (even ones that don't
    // re-surface).
    // Inter-check context sharing (#1627): a check that declares `dependsOn` reads
    // the findings its dependencies produced EARLIER this pass via
    // `ctx.priorFindings` (scoped to declared deps only — a check with no
    // `dependsOn` always gets the empty array and stays a pure function of its
    // sources). `orderChecksByDependencies` above guarantees the deps already ran,
    // so their stamped findings are in `findings`.
    const priorFindings = buildScopedPriorFindings(findings, check.dependsOn);
    const ctx = {
      ...baseCtx,
      config,
      severityDefault: check.severityDefault,
      priorFindings,
      // Read a single dependency's findings by id — still scoped, so it returns []
      // for a check NOT named in `dependsOn`, enforcing the explicit contract.
      findingsByCheck: (checkId) => priorFindings.filter((f) => f.checkId === checkId),
    };
    // Boundary try/catch: a check's run() calls into arbitrary logic / LLM
    // providers — one bad check must not abort the whole pass (mirrors the
    // per-comment fix guard in seriesAutopilot.runEditorial).
    try {
      if (typeof check.gate === 'function' && !check.gate(ctx)) {
        perCheck.push({ checkId: check.id, count: 0, skipped: true });
        onProgress?.({ type: 'check:complete', checkId: check.id, label: check.label, count: 0, skipped: true });
        continue;
      }
      const raw = (await check.run(ctx)) || [];
      const sourceContentHash = fingerprintForCheck(check, resolvedSources, checkById);
      // Stamp each finding with its NATIVE severity (the check's own escalated /
      // LLM-emitted level, or the registry default fallback) AND its EFFECTIVE
      // severity: a pin (#1596) is authoritative across every check kind, else
      // the native level stands. Carrying `nativeSeverity` lets the review-seed
      // layer re-grade a carried finding back to native when a pin is cleared.
      const stamped = raw.map((f) => {
        const nativeSeverity = ['high', 'medium', 'low'].includes(f.severity) ? f.severity : check.severityDefault;
        return {
          ...f,
          nativeSeverity,
          severity: severityOverride || nativeSeverity,
          checkId: check.id,
          sourceContentHash,
        };
      });
      findings.push(...stamped);
      // A deterministic check is a pure function of its sources, so a finding it
      // no longer produces is genuinely resolved (not provider variance) — mark it
      // for fresh-mode reconciliation. LLM checks stay merge-only (an absent
      // finding could just be sampling noise).
      ranCheckIds.add(check.id);
      if (check.kind === 'deterministic') deterministicRanIds.add(check.id);
      const bySeverity = severityBreakdown(stamped);
      perCheck.push({ checkId: check.id, count: stamped.length, bySeverity });
      onProgress?.({ type: 'check:complete', checkId: check.id, label: check.label, count: stamped.length, bySeverity });
    } catch (err) {
      const message = (err?.message || String(err)).slice(0, 500);
      console.error(`❌ editorial check ${check.id} failed — series=${String(seriesId).slice(0, 12)} ${message}`);
      perCheck.push({ checkId: check.id, error: message });
      onProgress?.({ type: 'check:complete', checkId: check.id, label: check.label, error: message });
    }
    // Re-check AFTER the (possibly long-running LLM) check so a cancellation
    // during the final check is caught before the seed below — otherwise a
    // cancel mid-run would still persist the partial findings.
    if (signal?.aborted) { canceled = true; break; }
  }

  // Seeding strategy (skip entirely on cancellation — a canceled run emits a
  // `canceled` terminal event and must not mutate the review with partial
  // findings collected before the abort):
  //
  //  - DETERMINISTIC checks self-heal: each that ran is seeded in 'fresh' mode
  //    SCOPED to its own checkId, so a finding the (possibly just-corrected) check
  //    no longer surfaces is auto-dismissed (a sync-safe status flip, never a
  //    deletion — see seedReviewFromFindings). This includes checks that found
  //    nothing this pass: their prior open findings must clear. Scoping by checkId
  //    means one deterministic check's reconciliation can't touch another check's
  //    or the completeness pass's (null-checkId) open comments.
  //  - LLM checks (and everything else) stay 'merge' mode: an absent LLM finding
  //    could be sampling variance, so it must not auto-dismiss a prior open one.
  //
  // accepted/dismissed comments are untouched by either mode.
  if (!canceled) {
    let lastReview = null;
    // Per-check severity overrides active this run (#1596). A pinned check's
    // level is authoritative for ALL its open comments, so the seed re-grades
    // even open comments that didn't re-surface this pass — crucial for LLM
    // checks (merge mode preserves a non-resurfaced open finding) and for a
    // pinned check that produced zero findings this run.
    const severityOverrides = {};
    for (const { check, severityOverride } of enabledResolved) {
      if (severityOverride) severityOverrides[check.id] = severityOverride;
    }
    // Fresh-reconcile each deterministic check that ran, scoped to its checkId —
    // passing only that check's findings so the scoped 'fresh' pass dismisses the
    // stale opens it no longer produces. `regradeCheckIds` scopes the severity
    // re-grade to this check alone.
    for (const checkId of deterministicRanIds) {
      const own = findings.filter((f) => f.checkId === checkId);
      lastReview = await seedReviewFromFindings(seriesId, own, { runId, mode: 'fresh', checkId, severityOverrides, regradeCheckIds: [checkId] });
    }
    // Seed the remaining (non-deterministic) findings in merge mode. Also run
    // when there are active overrides but no merged findings, so a pinned check
    // that produced ZERO findings this pass still re-grades its lingering open
    // comments (#1596) — merge mode never dismisses, so an empty seed is a safe
    // no-op aside from the authoritative severity re-grade. `regradeCheckIds` is
    // the set of non-deterministic checks that actually RAN this pass, so the
    // re-grade never touches comments for a pinned check excluded from a targeted
    // subset run.
    const merged = findings.filter((f) => !deterministicRanIds.has(f.checkId));
    const mergedRanCheckIds = [...ranCheckIds].filter((id) => !deterministicRanIds.has(id));
    if (merged.length || Object.keys(severityOverrides).length) {
      lastReview = await seedReviewFromFindings(seriesId, merged, { runId, mode: 'merge', severityOverrides, regradeCheckIds: mergedRanCheckIds });
    }
    // Record a revision-trend snapshot for EVERY non-canceled run (#1316) — a run
    // is a revision boundary, and a CLEAN run (0 new findings, or a reconciliation
    // that closed prior ones) is exactly the improving point the trend should
    // capture. Reuse the freshest seeded review when we have one; otherwise
    // recordTrendSnapshot reads the current review itself. Best-effort — a ledger
    // write must never fail the check run (it's telemetry).
    const gate = readReadinessGate(settings) || undefined;
    // Series severity-weight override (#1616) so the persisted trend score
    // matches the live computeHealth score the UI shows.
    const weights = mergeSeverityWeights(series?.severityWeights);
    await recordTrendSnapshot(seriesId, { runId, gate, weights, comments: lastReview?.comments }).catch((err) => {
      console.error(`⚠️ editorial trend snapshot failed — series=${String(seriesId).slice(0, 12)} ${err.message}`);
    });
  }
  return { runId, findings, perCheck, canceled };
}

/**
 * Transient preview of a DRAFT custom check (#1607). Synthesizes the unsaved
 * definition into a runnable check, runs it against the live manuscript via the
 * SAME context builder a real run uses, and returns its sample findings —
 * WITHOUT persisting the definition, seeding the manuscript review, or recording
 * a trend snapshot. Lets the author judge a check's noise/scope before committing
 * it to the catalog.
 *
 * The findings are deliberately NOT stamped with `checkId` / `sourceContentHash`
 * (those mark a finding for the review store's seed + staleness machinery, which
 * a preview must never touch). Severity is normalized to the check's native
 * default the same way the run loop does, so the preview's levels match a run.
 *
 * @param {string} seriesId
 * @param {object} def — the draft definition (label, prompt, scope, category, severityDefault)
 * @param {object} [opts] — providerOverride / modelOverride / maxFindings
 * @returns {Promise<{ findings: object[], skipped: boolean, invalid: boolean }>}
 *   - invalid: the draft failed the minimum-viable shape (missing label/prompt/scope/severity)
 *   - skipped: the check's gate declined (e.g. the series has no manuscript yet)
 */
export async function previewCustomCheck(seriesId, def, { providerOverride, modelOverride, maxFindings } = {}) {
  // Stamp a transient custom id so buildCustomCheck accepts the draft — its
  // validator requires the `custom.` prefix; the id is never persisted or seeded.
  const check = buildCustomCheck({ ...def, id: `${CUSTOM_CHECK_ID_PREFIX}preview` });
  if (!check) return { findings: [], skipped: false, invalid: true };

  const { baseCtx } = await buildEditorialContext(seriesId, [{ check }], { providerOverride, modelOverride });
  // Validate the (optional) per-run cap through the check's own config schema so
  // an out-of-range value falls back to the default rather than flooding.
  const config = check.configSchema.parse(Number.isInteger(maxFindings) ? { maxFindings } : {});
  // A preview runs one check in isolation — there are no prior findings, but expose
  // the same ctx shape (#1627) so a draft whose run() references them never crashes.
  const ctx = { ...baseCtx, config, severityDefault: check.severityDefault, priorFindings: EMPTY_PRIOR_FINDINGS, findingsByCheck: () => [] };

  if (typeof check.gate === 'function' && !check.gate(ctx)) {
    return { findings: [], skipped: true, invalid: false };
  }
  const raw = (await check.run(ctx)) || [];
  const findings = raw.map((f) => ({
    ...f,
    severity: ['high', 'medium', 'low'].includes(f.severity) ? f.severity : check.severityDefault,
  }));
  return { findings, skipped: false, invalid: false };
}

/**
 * Dry-run preview: which checks would run for the current settings (+ optional
 * subset), without executing them. Used by the run route's plan response and by
 * callers that want to show the user what's enabled.
 */
export async function buildEditorialCheckPlan(seriesId, { checkIds = null, settings } = {}) {
  const resolved = settings || await getSettings();
  const checks = getEnabledCheckRows(resolved, checkIds)
    // `scope` is the primary scope; `scopes` (#1628) carries the full declared set
    // so a consumer rendering the plan can group a dual-scope check by each of its
    // granularities (the plan itself keeps one entry per check).
    .map((row) => ({ id: row.id, label: row.label, kind: row.kind, scope: row.scope, scopes: row.scopes }));
  return {
    seriesId,
    checks,
    enabledCount: checks.length,
    consumesReverseOutline: enabledChecksConsumeReverseOutline(resolved, checkIds),
  };
}

/**
 * True when any enabled editorial check declares a reverse-outline source — the
 * scenes (`reverseOutline`, #1296) or the plotline list (`reverseOutline.plotlines`,
 * #1310). This is the single signal for "regenerating the reverse outline before
 * the checks is worth the budget" (#1349): it mirrors the `needsReverseOutline`
 * gate inside `runEditorialChecks` exactly, so the autopilot's reverse-outline
 * refresh step and the runner agree on what consumes the outline. Takes resolved
 * settings (sync) so a caller that already loaded them doesn't pay a second read.
 *
 * Gate-aware refinement (#1614): an enabled consumer whose runtime `gate(ctx)`
 * declines won't actually run — so it doesn't justify spending an LLM call to
 * refresh the outline. When the caller supplies a `gateCtx` (the autopilot
 * refresh path, which holds the current — stale — outline), a consumer must ALSO
 * pass its gate to count. The sources-only signal stands when no ctx is given
 * (the dry-run plan + the cheap pre-filter, neither of which builds a ctx) so
 * existing callers are unchanged.
 *
 * Critically, the refresh REGENERATES the outline — so a gate that declines
 * against the stale copy may flip to "passes" once the outline is fresh (e.g. a
 * `pov.justified` gate finds no POV-tagged scenes in a stale outline a refresh
 * would re-tag). We answer the only question that matters — "could a fresh
 * outline let this check run?" — by re-evaluating a declining gate against a
 * permissive synthetic outline while keeping the REAL manuscript/canon/series
 * (which the refresh leaves untouched). If it now passes, the outline was the
 * blocker → consumer; if it still declines, the block is outline-independent (a
 * mixed gate like `endings.pov-switch` that also needs authored cliffhangers, an
 * empty manuscript, a canon-less roster) and a refresh can't help → not a
 * consumer. A gate that already passes against the stale outline always counts.
 */
const PERMISSIVE_GATE_OUTLINE = Object.freeze({
  reverseOutline: Object.freeze([Object.freeze({
    id: 'scene-001', sequence: 0, povCharacter: 'POV', heading: 'Scene', summary: 'Scene.',
    plotlineId: 'p', secondaryPlotlineId: null, issueNumber: 1,
    components: Object.freeze({ narrative: true, action: true, dialogue: true }),
    charactersPresent: Object.freeze(['POV']), setting: 'Setting', anchorQuote: 'q',
  })]),
  reverseOutlinePlotlines: Object.freeze([Object.freeze({ id: 'p', label: 'Plot', kind: 'main' })]),
});

export function enabledChecksConsumeReverseOutline(settings, checkIds = null, gateCtx = null) {
  return getEnabledChecks(settings, checkIds).some(({ check }) => {
    const sources = checkSources(check);
    if (!sources.includes('reverseOutline') && !sources.includes('reverseOutline.plotlines')) return false;
    if (!gateCtx || typeof check.gate !== 'function') return true;
    if (check.gate(gateCtx)) return true;
    return check.gate({ ...gateCtx, ...PERMISSIVE_GATE_OUTLINE });
  });
}

/**
 * Build the minimal context needed to evaluate a reverse-outline consumer's
 * runtime `gate(ctx)` (#1614) — the manuscript corpus, canon, and the current
 * outline's scenes/plotlines. The autopilot's reverse-outline refresh uses this
 * to decide whether any check that would ACTUALLY run consumes the outline
 * before spending an LLM call to regenerate it.
 *
 * Deliberately lighter than buildEditorialContext: no issues / editorial-arc /
 * continuity-bible / comic projections and no injected LLM callers, because the
 * gates of outline-consuming checks read only `manuscript`, `canon`, `series`,
 * and `reverseOutline[.plotlines]`. Pass the already-read `outline` (the
 * autopilot's Gate-2 read) to avoid a redundant outline fetch.
 *
 * The slim field set is a contract: a checkRunner.test.js guard asserts every
 * reverse-outline-consuming check's `gate()` reads only the keys this builder
 * returns, so a future check whose gate reaches for `ctx.issues` (etc.) fails
 * loudly in CI instead of silently mis-evaluating against an absent field.
 */
export async function buildReverseOutlineGateContext(seriesId, { outline } = {}) {
  const series = await getSeries(seriesId);
  const [sections, canon] = await Promise.all([
    collectManuscriptSections(seriesId),
    getSeriesCanon(series),
  ]);
  const resolved = outline || await getReverseOutline(seriesId).catch(() => null);
  return {
    seriesId,
    series,
    manuscript: sectionsCorpus(sections),
    canon,
    reverseOutline: Array.isArray(resolved?.scenes) ? resolved.scenes : [],
    reverseOutlinePlotlines: Array.isArray(resolved?.plotlines) ? resolved.plotlines : [],
  };
}

// ---------------------------------------------------------------------------
// SSE run-tracking — shared lifecycle via createSseRunner (server/lib/sseUtils.js),
// the same factory backing manuscriptCompletenessRunner + editorialAnalysisRunner.
// ---------------------------------------------------------------------------

const runner = createSseRunner({ logLabel: 'editorial checks' });

export function isEditorialChecksActive(seriesId) {
  return runner.isActive(seriesId);
}

export function attachClient(seriesId, res) {
  return runner.attachClient(seriesId, res);
}

export function cancelEditorialChecks(seriesId) {
  return runner.cancel(seriesId);
}

/**
 * Kick off a streamed editorial-checks run. Returns the runId immediately;
 * progress lands via SSE. Re-calling while a run is in flight resolves to the
 * existing runId.
 */
/**
 * Summarize a `perCheck` array (the `{ checkId, count|error|skipped }` entries
 * `runEditorialChecks` returns) into the errored aggregate surfaced on the
 * completion frame and the autopilot run summary — so a check that throws every
 * pass is visible instead of hiding behind a silent "clean" run (#1573). Shared
 * by the standalone run route and `seriesAutopilot.runEditorialChecksPass` so
 * both frames name the fields identically.
 */
export function summarizeCheckErrors(perCheck) {
  const erroredCheckIds = (Array.isArray(perCheck) ? perCheck : [])
    .filter((c) => c?.error)
    .map((c) => c.checkId);
  return { errored: erroredCheckIds.length, erroredCheckIds };
}

export function startEditorialChecksRun(seriesId, options = {}) {
  return runner.start(seriesId, async ({ runId, signal, record, broadcast }) => {
    broadcast({ type: 'start', runId });
    const result = await runEditorialChecks(seriesId, {
      checkIds: options.checkIds,
      providerOverride: options.providerOverride,
      modelOverride: options.modelOverride,
      signal,
      onProgress: (event) => broadcast({ ...event, runId }),
    });
    if (record.cancelRequested || result.canceled) {
      broadcast({ type: 'canceled', runId, canceledAt: new Date().toISOString() });
      console.log(`📝 editorial checks canceled — series=${String(seriesId).slice(0, 12)}`);
      return;
    }
    const { errored, erroredCheckIds } = summarizeCheckErrors(result.perCheck);
    broadcast({
      type: 'complete',
      runId,
      findingCount: result.findings.length,
      perCheck: result.perCheck,
      // #1573 — surface errored checks on the terminal frame so a check that
      // throws every run is visible instead of reporting a silent "clean".
      errored,
      erroredCheckIds,
      completedAt: new Date().toISOString(),
    });
    console.log(`📝 editorial checks complete — series=${String(seriesId).slice(0, 12)} findings=${result.findings.length}${errored ? ` — ⚠️ ${errored} check(s) errored: ${erroredCheckIds.join(', ')}` : ''}`);
  });
}

// Export internals for tests.
export const __testing = { runs: runner.runs, PERMISSIVE_GATE_OUTLINE };