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

41.7 KB
Raw Blame
/**
 * Pipeline — holistic "Review this series" flow (#2664).
 *
 * Composes the existing read-only review passes into ONE structured verdict the
 * user can act on: run the foundation judge + editorial checks + editorial
 * health/readiness + canon readiness, optionally route a free-text user
 * observation into an anchored finding, and return a single
 * `{ verdict: 'ready' | 'issues', foundation, health, canon, findings }` payload.
 *
 * This is a COMPOSITION layer — it reuses the existing runners verbatim and adds
 * no new AI plumbing and no second orchestrator:
 *   - foundation judge   → foundationJudge.judgeFoundation (writes only its own
 *                          snapshot; never touches the manuscript)
 *   - editorial checks   → editorial/checkRunner.runEditorialChecks (seeds the
 *                          shared manuscript-review store with findings — the
 *                          same store the fix path reads; NOT a manuscript write)
 *   - health/readiness   → editorialScore.getSeriesHealth
 *   - canon readiness    → canonReadiness.checkSeriesCanonReadiness (deterministic)
 *   - free-text feedback → routed through runStageScopedInlineLLM to the best
 *                          issue/section and seeded as an anchored finding
 *
 * The foundation judge and canon readiness are kicked off at entry and awaited
 * just before the verdict, so they overlap the editorial-checks pass (#4108).
 * The only hard ordering constraint is the seed→read chain feedback-seed →
 * checks-seed → health/getReview, which stays strictly sequential.
 *
 * The review performs NO manuscript writes, so it is safe to run repeatedly. The
 * FIX path is deliberately NOT here: "Fix these issues" drives the existing
 * Series Autopilot revision cycle (cos-domain gate + budget + SSE) and the
 * per-finding manuscriptFix routes — this service only produces the verdict.
 *
 * Progress streams over SSE via the shared `createSseRunner` (mirrors
 * checkRunner / editorialAnalysisRunner). The last verdict persists at
 * `data/pipeline-series-review/{seriesId}.json` so a (re)mounting client can
 * reload it without re-running.
 *
 * AI-provider policy: this fires ONLY from the explicit user "Review this
 * series" action — never at boot.
 */

import { join } from 'path';
import { unlink } from 'fs/promises';
import { assertValidSeriesId } from '../../lib/pipelineIds.js';
import { PATHS, atomicWrite, ensureDir, tryReadFile, safeJSONParse, sha256Text } from '../../lib/fileUtils.js';
import { canonicalStringify } from '../../lib/objects.js';
import { createSseRunner } from '../../lib/sseUtils.js';
import { runStageScopedInlineLLM } from '../stageRunner.js';
import { CREATIVE_LATITUDE_ADDITION, withCreativeLatitude } from '../../lib/creativeLatitude.js';
import { promptAddition } from '../../lib/modelInput.js';
import { getDomainMode } from '../../lib/domainAutonomy.js';
import { readReadinessGate, mergeSeverityWeights } from '../../lib/editorial/index.js';
import { loadState } from '../cosState.js';
import { getSettings } from '../settings.js';
import { getDomainBudgetStatus, recordDomainUsage } from '../domainUsage.js';
import { getUniverse } from '../universeBuilder.js';
import { getSeries, MANUSCRIPT_TYPES } from './series.js';
import { listIssues } from './issues.js';
import { judgeFoundation, foundationInputs, DEFAULT_FOUNDATION_THRESHOLD } from './foundationJudge.js';
import { runEditorialChecks } from './editorial/checkRunner.js';
import { getSeriesHealth, isOpenFinding, DEFAULT_READINESS_GATE } from './editorialScore.js';
import { checkSeriesCanonReadiness, canonDescriptionInputs } from './canonReadiness.js';
import { pickCanon } from './seriesCanon.js';
import { getReview, seedReviewFromFindings } from './manuscriptReview.js';
import { generateManuscriptFix, acceptManuscriptFix } from './manuscriptFix.js';

// The stage whose provider/model pins the free-text-feedback routing call, so a
// user observation about the manuscript is judged on the SAME provider the arc
// authoring uses (never silently routed elsewhere). Mirrors foundationJudge's
// WRITER_STAGE indirection.
const FEEDBACK_STAGE = 'pipeline-arc-overview';
const FEEDBACK_MAX = 4000;

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

const reviewDir = () => join(PATHS.data, 'pipeline-series-review');
const snapshotPath = (seriesId) => join(reviewDir(), `${seriesId}.json`);

const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };

// ---------------------------------------------------------------------------
// Pure composition helpers (unit-tested in isolation).
// ---------------------------------------------------------------------------

/**
 * The single 'ready' | 'issues' verdict. A series is only "ready to move
 * forward" when the editorial-health readiness gate is clean AND the foundation
 * clears the quality threshold AND every drawn noun is described (canon ready)
 * AND the review actually completed (`incomplete` false — a stage that errored /
 * never ran means the verdict is untrustworthy and must never read 'ready').
 * Any of those failing → 'issues'. Pure.
 */
export function computeReviewVerdict({ health, foundation, canon, threshold = DEFAULT_FOUNDATION_THRESHOLD, incomplete = false } = {}) {
  const healthReady = health?.ready === true;
  const foundationReady = !foundation || !Number.isFinite(foundation.weightedScore)
    ? true
    : foundation.weightedScore >= threshold;
  const canonReady = canon?.ready !== false;
  return healthReady && foundationReady && canonReady && !incomplete ? 'ready' : 'issues';
}

/**
 * Project the manuscript-review store's OPEN comments into the review's flat
 * findings list, each carrying the `commentId` the per-finding fix path needs
 * plus the anchoring fields the UI groups + deep-links by. Sorted high→low
 * severity, then by issue number (series-scoped nulls last). Pure.
 */
export function collectReviewFindings(comments) {
  const open = (Array.isArray(comments) ? comments : []).filter((c) => c && typeof c === 'object' && isOpenFinding(c));
  return open
    .map((c) => ({
      commentId: c.id,
      severity: c.severity in SEVERITY_RANK ? c.severity : 'medium',
      checkId: typeof c.checkId === 'string' ? c.checkId : null,
      issueId: typeof c.issueId === 'string' ? c.issueId : null,
      issueNumber: Number.isInteger(c.issueNumber) ? c.issueNumber : null,
      location: typeof c.location === 'string' ? c.location : '',
      anchorQuote: typeof c.anchorQuote === 'string' ? c.anchorQuote : '',
      summary: typeof c.problem === 'string' ? c.problem : '',
    }))
    .sort((a, b) => {
      const s = (SEVERITY_RANK[a.severity] ?? 1) - (SEVERITY_RANK[b.severity] ?? 1);
      if (s !== 0) return s;
      return (a.issueNumber ?? Infinity) - (b.issueNumber ?? Infinity);
    });
}

// ---------------------------------------------------------------------------
// Reviewed-source fingerprinting (#4111).
//
// The findingIds divergence below only notices findings being accepted/dismissed
// or appearing. It cannot see the manuscript being rewritten, canon being
// edited, or the foundation changing through some other path — so the stored
// verdict's foundation/canon/health dimensions could report old scores as
// current. Mirroring `foundationJudge`'s `sourceInputsHash` / `isFoundationStale`,
// a run pins a hash of everything it reviewed and the GET recomputes it.
// ---------------------------------------------------------------------------

// Separator for concatenated fields inside one fingerprint — a byte that can't
// occur in authored text, so two fields can't blur into each other. Mirrors
// checkRunner's per-finding fingerprinting.
const HASH_SEP = '\u0000';

/**
 * The manuscript text the editorial checks + canon readiness read, as a stable
 * projection: EVERY drafted manuscript stage per issue (not just the highest-
 * precedence one), each stage's input AND output hashed, so any authored edit
 * flips the fingerprint. Sorted by issue id so a listing re-order isn't an edit.
 * Pure.
 */
export function manuscriptInputs(issues) {
  return [...(Array.isArray(issues) ? issues : [])]
    .map((iss) => ({
      id: iss?.id || '',
      stages: Object.fromEntries(MANUSCRIPT_TYPES.map((sid) => {
        const stage = iss?.stages?.[sid];
        // NUL-joined so text moving across the input/output boundary can't hash identically.
        return [sid, sha256Text([stage?.input || '', stage?.output || ''].join(HASH_SEP))];
      })),
    }))
    .sort((a, b) => a.id.localeCompare(b.id));
}

/**
 * Everything this review reads, as a stable projection. Pure.
 *
 * - `foundation` reuses `foundationInputs` verbatim, so the review's staleness
 *   and the foundation judge's can never disagree about what the foundation is.
 * - `manuscript` is the drafted text the editorial checks and canon readiness
 *   grade — absent from the foundation projection (which only carries the `idea`
 *   synopsis), and the single biggest silent-drift source.
 * - `canon` is the descriptive text canon readiness grades. It overlaps the
 *   foundation projection but is NOT covered by it: a character's plain
 *   `description` (the fallback canon readiness grades on) is not a foundation
 *   field, so a description-only edit would otherwise go unnoticed.
 * - `scoring` carries inputs that change how a dimension SCORES rather than what
 *   it reads (the canon source text depends on `targetFormat`; health weights
 *   the open findings by `severityWeights`).
 */
export function seriesReviewInputs({ series, universe, issues } = {}) {
  const list = Array.isArray(issues) ? issues : [];
  return {
    foundation: foundationInputs(series, universe, list),
    manuscript: manuscriptInputs(list),
    canon: canonDescriptionInputs(pickCanon(universe)),
    scoring: {
      targetFormat: series?.targetFormat || '',
      severityWeights: series?.severityWeights ?? null,
    },
  };
}

// Key-sorted so the hash is stable across machines (a synced/imported record can
// re-order keys without being an edit). Mirrors checkRunner's fingerprinting.
export const seriesReviewInputsHash = (parts) => sha256Text(canonicalStringify(seriesReviewInputs(parts)));

/**
 * Whether a stored verdict's reviewed sources have drifted. A snapshot written
 * before this feature carries no hash — it can't be judged, so it is NOT flagged
 * (the findings divergence still applies). A snapshot that HAS a hash we could
 * not recompute (`currentHash` null — the series/universe/issues were unreadable)
 * IS flagged: the verdict is unverifiable, and failing closed matches how the
 * review's own verdict treats a dimension it couldn't evaluate. Pure.
 */
export function isSeriesReviewSourceStale(snapshot, currentHash) {
  if (!snapshot?.sourceInputsHash) return false;
  if (!currentHash) return true;
  return snapshot.sourceInputsHash !== currentHash;
}

/**
 * Whether the live open-finding set has diverged from the one a stored verdict
 * was computed from — findings accepted/dismissed (e.g. via a "Fix here" link)
 * or new findings appearing. Falls back to the snapshot's embedded findings for
 * a snapshot written before `findingIds` existed. Pure.
 */
export function isSeriesReviewFindingsStale(snapshot, liveFindingIds) {
  const live = liveFindingIds instanceof Set ? liveFindingIds : new Set(liveFindingIds || []);
  const snapshotIds = Array.isArray(snapshot?.findingIds)
    ? snapshot.findingIds
    : (snapshot?.findings || []).map((f) => f?.commentId).filter(Boolean);
  return snapshotIds.length !== live.size || snapshotIds.some((id) => !live.has(id));
}

/**
 * Resolve the CURRENT reviewed-source hash for a series. Returns null when the
 * inputs can't be fully read — never a hash computed from a partial read, which
 * would silently report a changed foundation as unchanged.
 *
 * Pass the records the caller already holds to skip the re-read. Each is read
 * here ONLY when the caller omitted it (`undefined`): an explicit `null` is the
 * caller reporting its own read FAILED, and re-reading it here would hash a
 * source the verdict was never computed from.
 */
async function resolveSourceInputsHash(seriesId, { series, issues } = {}) {
  const ser = series === undefined ? await getSeries(seriesId).catch(() => null) : series;
  if (!ser) return null;
  const list = issues === undefined ? await listIssues({ seriesId }).catch(() => null) : issues;
  if (!list) return null;
  // `undefined` = a linked universe we failed to read (distinct from `null` = no
  // linked universe at all). Hashing the failed read as "unlinked" would produce
  // a fresh-looking hash for a world we never saw.
  const universe = ser.universeId ? await getUniverse(ser.universeId).catch(() => undefined) : null;
  if (universe === undefined) return null;
  return seriesReviewInputsHash({ series: ser, universe, issues: list });
}

/**
 * Build the inline prompt that routes a free-text user observation to the best
 * issue + anchor. Given the issue roster (number + title) and the feedback, the
 * model returns a single finding JSON. Pure.
 */
export function buildFeedbackRoutePrompt(feedback, issues) {
  const roster = (Array.isArray(issues) ? issues : [])
    .map((i) => `- #${i.number}: ${i.title || '(untitled)'}`)
    .join('\n') || '(no issues yet)';
  return [
    'You are an editorial triage assistant. A reader has left a free-text note about a series.',
    'Route the note to the single BEST place to patch it, as one JSON object.',
    '',
    'Series issues (number: title):',
    roster,
    '',
    'Reader note:',
    `"""${feedback}"""`,
    '',
    'Return ONLY a JSON object with these keys:',
    '  issueNumber  — the issue number the note is about, or null if it is series-wide',
    '  severity     — "high" | "medium" | "low"',
    '  location     — a short human label for where this applies (e.g. "Volume 1 pacing")',
    '  problem      — a one-to-two sentence restatement of the concern as an editorial finding',
    '  suggestion   — a concrete suggested fix (may be empty)',
    '  anchorQuote  — a short verbatim quote from the manuscript to anchor the fix, or "" if unknown',
    '',
    'Do not invent an issue number that is not in the list above; use null when unsure.',
  ].join('\n');
}

/**
 * Shape the LLM's routed-feedback response into a finding for
 * seedReviewFromFindings, tolerant of malformed/absent output. Falls back to a
 * series-level finding carrying the raw feedback so a user observation ALWAYS
 * lands (never silently dropped). `validNumbers` is the set of real issue
 * numbers — a hallucinated number degrades to a series-level (null) finding.
 * Pure.
 */
export function shapeFeedbackFinding(parsed, { feedback, validNumbers } = {}) {
  const p = parsed && typeof parsed === 'object' ? parsed : {};
  const valid = validNumbers instanceof Set ? validNumbers : new Set(validNumbers || []);
  const issueNumber = Number.isInteger(p.issueNumber) && valid.has(p.issueNumber) ? p.issueNumber : null;
  const severity = p.severity in SEVERITY_RANK ? p.severity : 'medium';
  const problem = (typeof p.problem === 'string' && p.problem.trim())
    ? p.problem.trim()
    : String(feedback || '').trim();
  return {
    issueNumber,
    severity,
    category: 'user-feedback',
    location: typeof p.location === 'string' ? p.location.slice(0, 200) : '',
    problem: problem.slice(0, 2000),
    suggestion: typeof p.suggestion === 'string' ? p.suggestion.slice(0, 8000) : '',
    anchorQuote: typeof p.anchorQuote === 'string' ? p.anchorQuote.slice(0, 400) : '',
    // Marks the finding as a user observation so it groups distinctly from the
    // automated checks and the dedup key can't collide with a real check.
    checkId: 'user-feedback',
  };
}

// ---------------------------------------------------------------------------
// Free-text feedback routing (one inline LLM call, seeded as a finding).
// ---------------------------------------------------------------------------

async function routeFeedbackToFinding(seriesId, feedback, { providerOverride, modelOverride, issues }) {
  const trimmed = String(feedback || '').trim();
  if (!trimmed) return null;
  // Stamped here (idempotent) so the verdict can show the exact text the note
  // went out in, with the routing instructions and policy clause listed (#11317).
  const prompt = withCreativeLatitude(buildFeedbackRoutePrompt(trimmed.slice(0, FEEDBACK_MAX), issues));
  const sentInput = {
    sentPrompt: prompt,
    promptAdditions: [
      CREATIVE_LATITUDE_ADDITION,
      promptAddition('note-routing', 'Note routing instructions', buildFeedbackRoutePrompt('[your note]', issues)),
    ].filter(Boolean),
  };
  // Never fail the whole review on a bad routing call — fall back to a
  // series-level finding carrying the raw note so the observation still lands.
  let parsed = null;
  await runStageScopedInlineLLM(FEEDBACK_STAGE, prompt, {
    returnsJson: true,
    providerOverride,
    modelOverride,
    source: 'series-review-feedback',
  })
    .then((r) => { parsed = r?.content ?? null; })
    .catch((err) => { console.error(`⚠️ series-review feedback routing failed — series=${seriesId.slice(0, 12)} ${err.message}`); });
  const validNumbers = new Set((Array.isArray(issues) ? issues : []).map((i) => i.number).filter(Number.isInteger));
  const finding = shapeFeedbackFinding(parsed, { feedback: trimmed, validNumbers });
  const review = await seedReviewFromFindings(seriesId, [finding], { mode: 'merge', checkId: 'user-feedback' });
  return { finding, review, sentInput };
}

// ---------------------------------------------------------------------------
// Core read-only review.
// ---------------------------------------------------------------------------

/**
 * Run the holistic read-only review. Returns the structured verdict. Emits
 * progress via `onProgress(event)` (each event a `{ type, ... }` frame). No
 * manuscript writes — safe to run repeatedly.
 *
 * @param {string} seriesId
 * @param {object} [opts]
 * @param {string} [opts.feedback]          optional free-text user observation
 * @param {string} [opts.providerOverride]  provider override for the LLM passes
 * @param {string} [opts.modelOverride]     model override for the LLM passes
 * @param {boolean} [opts.force]            re-judge an unchanged foundation
 * @param {string} [opts.readinessGate]     per-run readiness-gate override
 * @param {AbortSignal} [opts.signal]       cancellation
 * @param {(event: object) => void} [opts.onProgress]
 */
export async function runSeriesReview(seriesId, {
  feedback, providerOverride, modelOverride, force = false, readinessGate, signal, onProgress = () => {},
} = {}) {
  assertValidSeriesId(seriesId);
  // Already canceled before we started — bail before spending an LLM round-trip
  // on a run whose verdict would be discarded anyway.
  if (signal?.aborted) return null;
  // Three independent reads — resolve concurrently.
  // `issuesRead` keeps `null` = the read FAILED distinct from `[]` = the series
  // genuinely has no issues: the composition below is happy with an empty list,
  // but the source fingerprint must not pin a hash computed from a failed read.
  const [series, settings, issuesRead] = await Promise.all([
    getSeries(seriesId),
    getSettings().catch(() => null),
    listIssues({ seriesId }).catch(() => null),
  ]);
  const issues = issuesRead || [];
  const gate = readinessGate || readReadinessGate(settings) || DEFAULT_READINESS_GATE;
  const weights = mergeSeverityWeights(series?.severityWeights);

  const aborted = () => signal?.aborted;

  // The ONLY hard ordering constraint in this flow is the seed→read chain:
  // feedback-seed → checks-seed → health/getReview (both of which read the store
  // the first two write). The foundation judge writes only its own snapshot and
  // canon readiness is deterministic + store-independent, so both are kicked off
  // here at entry and awaited just before the verdict — overlapping the full
  // foundation LLM round-trip with the editorial-checks pass instead of running
  // before/after it (#4108).
  //
  // Each background pass owns its own `step:start`/`step:complete` frames and
  // swallows its own failure, so it resolves to `{ value, failed }` and never
  // rejects on the normal path. `kickOff` still attaches a no-op catch the
  // instant the promise exists, so an unexpected throw (e.g. from the caller's
  // `onProgress`) can't surface as an unhandled rejection when an early cancel
  // returns before the `await`.
  const kickOff = (fn) => { const p = fn(); p.catch(() => {}); return p; };

  const foundationTask = kickOff(async () => {
    // Foundation judge (holistic pre-draft quality — catches "looks complete but
    // no development"). A throw is a genuine failure (judgeFoundation otherwise
    // always returns a snapshot), not an absent-but-fine result — record it so
    // the verdict fails closed.
    onProgress({ type: 'step:start', kind: 'foundation' });
    let failed = false;
    const value = await judgeFoundation(seriesId, { providerId: providerOverride, model: modelOverride, force })
      .catch((err) => { console.error(`⚠️ series-review foundation judge failed — series=${seriesId.slice(0, 12)} ${err.message}`); failed = true; return null; });
    onProgress({ type: 'step:complete', kind: 'foundation', weightedScore: value?.weightedScore ?? null, failed });
    return { value, failed };
  });

  const canonTask = kickOff(async () => {
    // Canon readiness (deterministic — no LLM). A throw is a genuine failure —
    // record it so the verdict fails closed rather than treating the missing
    // result as "canon fine".
    onProgress({ type: 'step:start', kind: 'canon' });
    let failed = false;
    const value = await checkSeriesCanonReadiness(seriesId)
      .catch((err) => { console.error(`⚠️ series-review canon readiness failed — series=${seriesId.slice(0, 12)} ${err.message}`); failed = true; return null; });
    // `failed` must gate `ready`: on a throw `value` is null, and a bare
    // `value?.ready !== false` would announce `ready: true` for a pass that never
    // produced a result. Mirrors how the verdict fails closed on the same signal.
    onProgress({ type: 'step:complete', kind: 'canon', ready: !failed && value?.ready !== false, failed });
    return { value, failed };
  });

  // A canceled run still settles the background passes before returning, so their
  // progress frames can never land after the SSE wrapper's `canceled` frame.
  const canceledResult = async () => { await Promise.allSettled([foundationTask, canonTask]); return null; };

  // 1. Optional free-text feedback → anchored finding (before the checks pass so
  //    it merges into the same review the verdict reads).
  let feedbackInput = null;
  if (feedback && String(feedback).trim()) {
    onProgress({ type: 'step:start', kind: 'feedback' });
    await routeFeedbackToFinding(seriesId, feedback, { providerOverride, modelOverride, issues })
      .then((routed) => { feedbackInput = routed?.sentInput ?? null; })
      .catch((err) => { console.error(`⚠️ series-review feedback seed failed — series=${seriesId.slice(0, 12)} ${err.message}`); });
    onProgress({ type: 'step:complete', kind: 'feedback' });
    if (aborted()) return canceledResult();
  }

  // 2. Editorial checks — registry-driven review; seeds the shared review store.
  onProgress({ type: 'step:start', kind: 'editorialChecks' });
  // A runner-level REJECT (e.g. it threw while building shared context, before
  // producing any perCheck entries) is a whole-pass failure — the checks never
  // ran, so mark the review incomplete rather than reporting an empty clean pass.
  let checksRunFailed = false;
  const checks = await runEditorialChecks(seriesId, {
    providerOverride,
    modelOverride,
    signal,
    onProgress,
  }).catch((err) => { console.error(`⚠️ series-review editorial checks failed — series=${seriesId.slice(0, 12)} ${err.message}`); checksRunFailed = true; return { findings: [], perCheck: [], canceled: false }; });
  // A single check that threw (e.g. an unavailable LLM provider) is caught
  // internally by the runner and surfaced in perCheck as `{ checkId, error }` —
  // that dimension was never evaluated, so it too must block a 'ready' verdict.
  const erroredCheckIds = (Array.isArray(checks?.perCheck) ? checks.perCheck : [])
    .filter((p) => p && p.error).map((p) => p.checkId);
  const checksErrored = erroredCheckIds.length;
  onProgress({ type: 'step:complete', kind: 'editorialChecks', findingCount: checks?.findings?.length ?? 0, errored: checksErrored, failed: checksRunFailed });
  if (aborted() || checks?.canceled) return canceledResult();

  // 3. Health + readiness + the seeded findings — both only READ the store the
  //    checks just seeded, so resolve them concurrently.
  onProgress({ type: 'step:start', kind: 'health' });
  const [health, review] = await Promise.all([
    getSeriesHealth(seriesId, { gate, weights }).catch(() => null),
    getReview(seriesId).catch(() => ({ comments: [] })),
  ]);
  onProgress({ type: 'step:complete', kind: 'health', ready: health?.ready === true, score: health?.score ?? null });
  const findings = collectReviewFindings(review?.comments);

  // 4. Join the background passes. Both resolve (never reject) with their own
  //    failure flag, so the failed-stage list is assembled here in ONE place and
  //    keeps a deterministic order regardless of which pass settled first.
  const [foundationRes, canonRes] = await Promise.all([foundationTask, canonTask]);
  const foundation = foundationRes.value;
  const canon = canonRes.value;
  // Stages that errored / never ran this pass — any of these makes the verdict
  // untrustworthy, so it must never read 'ready' (fail closed). Surfaced on the
  // result so the UI can warn the review is incomplete.
  const failedStages = [];
  if (foundationRes.failed) failedStages.push('foundation');
  if (checksRunFailed) failedStages.push('editorialChecks');
  if (canonRes.failed) failedStages.push('canon');
  if (!health) failedStages.push('health');
  const threshold = Number.isFinite(settings?.pipelineEditorialChecks?.foundationThreshold)
    ? settings.pipelineEditorialChecks.foundationThreshold
    : DEFAULT_FOUNDATION_THRESHOLD;
  // The review is incomplete when ANY dimension errored/never-ran OR an
  // individual check errored — the verdict then fails closed (never 'ready').
  const incomplete = failedStages.length > 0 || checksErrored > 0;
  const verdict = computeReviewVerdict({ health, foundation, canon, threshold, incomplete });
  // Pin what this verdict was computed FROM. The review performs no manuscript
  // writes, so the records read at entry are still the ones it reviewed.
  const sourceInputsHash = await resolveSourceInputsHash(seriesId, { series, issues: issuesRead });

  const result = {
    seriesId,
    verdict,
    generatedAt: nowIso(),
    gate,
    foundationThreshold: threshold,
    foundation: foundation
      ? { weightedScore: foundation.weightedScore, dimensions: foundation.dimensions, oneLineVerdict: foundation.oneLineVerdict, weakest: foundation.weakest, stale: foundation.stale === true }
      : null,
    health: health
      ? { score: health.score, ready: health.ready, open: health.open, openBySeverity: health.openBySeverity, gate: health.gate }
      : null,
    canon: canon
      ? { ready: canon.ready, blockingIssues: canon.blockingIssues, undescribed: canon.undescribed }
      : null,
    findings,
    findingCount: findings.length,
    // Whether the review actually completed every dimension. When false, a stage
    // errored / never ran, so the verdict is forced to 'issues' and the UI warns
    // the review is incomplete (P2). `failedStages` names which dimensions failed;
    // `checksErrored`/`erroredCheckIds` detail individual check errors.
    incomplete,
    failedStages,
    checksErrored,
    erroredCheckIds,
    // The open-finding comment ids this verdict was computed from — so a later
    // GET can detect that the review is stale (findings were accepted/dismissed,
    // e.g. via a "Fix here" link) without re-running.
    findingIds: findings.map((f) => f.commentId),
    // A fingerprint of everything this verdict was computed FROM (manuscript,
    // canon, foundation inputs), so a later GET can detect that the reviewed
    // sources changed — not just the findings store (#4111). Null when the
    // inputs couldn't be fully read; a null hash is never flagged stale.
    sourceInputsHash,
    hadFeedback: !!(feedback && String(feedback).trim()),
    // What the note was sent to the AI as, for the panel's chips (#11317).
    ...(feedbackInput ? { feedbackInput } : {}),
  };
  // Don't persist (or return) a verdict for a run the user canceled mid-flight —
  // the SSE wrapper will broadcast `canceled`, and a reload must not restore a
  // verdict from a run that never finished.
  if (aborted()) return null;
  await saveSnapshot(result);
  console.log(`🔎 series review — series=${seriesId.slice(0, 12)} verdict=${verdict} findings=${findings.length} foundation=${foundation?.weightedScore ?? '—'} health=${health?.score ?? '—'}`);
  return result;
}

// ---------------------------------------------------------------------------
// Persistence — last verdict per series.
// ---------------------------------------------------------------------------

async function saveSnapshot(result) {
  await ensureDir(reviewDir());
  await atomicWrite(snapshotPath(result.seriesId), result);
}

// Drop the persisted verdict for a series so a reload/remount doesn't restore a
// now-stale review (e.g. after fixes accepted findings + mutated the manuscript).
// GET /review then returns `{ review: null }` until the user re-reviews.
async function clearSnapshot(seriesId) {
  await unlink(snapshotPath(seriesId)).catch(() => {}); // best-effort; ENOENT is fine
}

/**
 * Read the last stored review verdict for a series (null when never run). Also
 * reports whether the FIX path is currently available (cos-domain autonomy):
 * with the domain `off`, review still works read-only but fixing is disabled.
 *
 * Stamps a `stale` flag when the stored verdict no longer describes the series,
 * from two independent signals, plus a `staleReason` naming which fired:
 *
 *  - `findings` — the live open-finding set no longer matches the snapshot's
 *    `findingIds` (findings accepted/dismissed via a "Fix here" link, or new
 *    ones appeared).
 *  - `sources` — the reviewed sources themselves drifted: the manuscript was
 *    edited, canon changed, or a foundation input moved (#4111). Without this,
 *    the verdict's foundation/canon/health dimensions could keep reporting old
 *    scores as current after a direct manuscript edit.
 *  - `both` — both fired.
 */
export async function getSeriesReview(seriesId) {
  assertValidSeriesId(seriesId);
  const content = await tryReadFile(snapshotPath(seriesId));
  const parsed = content === null
    ? null
    : safeJSONParse(content, null, { allowArray: false, logError: true, context: snapshotPath(seriesId) });
  // `allowArray: false` only rejects a root array — a bare JSON scalar
  // (corrupt snapshot) still parses, so guard for a genuine object before
  // treating it as a verdict.
  const verdict = parsed && typeof parsed === 'object' ? parsed : null;
  const [fix, review, currentHash] = await Promise.all([
    getFixAvailability(),
    // `null` = the findings store couldn't be read (distinct from a store with no
    // open findings). Collapsing the two would read as "every pinned finding was
    // resolved" and falsely flag the verdict stale on a transient read failure.
    verdict ? getReview(seriesId).catch(() => null) : Promise.resolve(null),
    // Only worth the reads when there IS a snapshot to judge, and only when that
    // snapshot carries a hash (a pre-#4111 snapshot can't be judged this way).
    verdict?.sourceInputsHash ? resolveSourceInputsHash(seriesId) : Promise.resolve(null),
  ]);
  if (verdict) {
    const liveOpen = new Set(collectReviewFindings(review?.comments).map((f) => f.commentId));
    const reasons = [
      review && isSeriesReviewFindingsStale(verdict, liveOpen) && 'findings',
      isSeriesReviewSourceStale(verdict, currentHash) && 'sources',
    ].filter(Boolean);
    verdict.stale = reasons.length > 0;
    verdict.staleReason = reasons.length > 1 ? 'both' : (reasons[0] || null);
  }
  return { review: verdict, fix };
}

/**
 * Whether the fix path can run right now, from the cos-domain autonomy mode.
 * Only `execute` applies fixes: `off` disables fixing (review stays read-only),
 * and `dry-run` is a plan-only preview that performs NO writes — so it must NOT
 * report the fix as available (P3), or the UI would claim "fixes complete" after
 * a no-op. The client renders a mode-specific reason for both non-execute cases.
 */
export async function getFixAvailability() {
  const state = await loadState().catch(() => ({ config: {} }));
  const mode = getDomainMode(state?.config, 'cos');
  return { mode, canFix: mode === 'execute' };
}

// ---------------------------------------------------------------------------
// Fix path (P1) — patch findings where best patched via the EXISTING per-finding
// manuscriptFix machinery, in a simple bulk loop.
//
// This deliberately does NOT start Series Autopilot: the autopilot's editorial
// step only auto-resolves manuscript-COMPLETENESS findings, so the editorial-
// CHECK findings this review surfaces stay open, the editorial-health gate
// pauses on them, and the revision cycle is never reached — a full-autopilot run
// can't actually fix the findings the review flagged. Looping
// generateManuscriptFix → acceptManuscriptFix over each open finding patches it
// at its anchor (the finding's `anchorQuote`/issue/stage), which is precisely
// "fix where best patched." It is not a second orchestrator — it reuses the
// per-finding fixers under the same cos-domain gate + budget the autopilot uses.
// ---------------------------------------------------------------------------

/**
 * Bulk-fix a series' open findings through the anchored per-finding fixer. Fails
 * closed on the cos autonomy gate (only `execute` writes) + the daily budget.
 * Findings whose fix can't be anchored are skipped (never mis-applied). Emits
 * progress via `onProgress`. Returns `{ fixed, skipped, total }` or, when gated
 * off, `{ rejected: true, mode | reason }`.
 */
export async function runSeriesFix(seriesId, { commentIds, providerOverride, modelOverride, signal, onProgress = () => {} } = {}) {
  assertValidSeriesId(seriesId);
  // Autonomy gate — mirror the autopilot start route (fail closed).
  const { mode } = await getFixAvailability();
  if (mode !== 'execute') return { rejected: true, mode };
  const budget = await getDomainBudgetStatus('cos');
  if (!budget.withinBudget) return { rejected: true, reason: `daily cos ${budget.exceeded} budget reached` };

  const review = await getReview(seriesId).catch(() => ({ comments: [] }));
  let open = collectReviewFindings(review.comments);
  if (Array.isArray(commentIds) && commentIds.length) {
    const wanted = new Set(commentIds);
    open = open.filter((f) => wanted.has(f.commentId));
  }

  let fixed = 0;
  let skipped = 0;
  let budgetStopped = false;
  for (const f of open) {
    if (signal?.aborted) break;
    // Re-check the budget before each fix (each generate is one cos action).
    const b = await getDomainBudgetStatus('cos');
    if (!b.withinBudget) { budgetStopped = true; break; }
    onProgress({ type: 'fix:start', commentId: f.commentId, severity: f.severity, issueNumber: f.issueNumber });
    const gen = await generateManuscriptFix(seriesId, { commentId: f.commentId, providerOverride, modelOverride })
      .catch((err) => { console.error(`⚠️ series-fix generate failed — comment=${String(f.commentId).slice(0, 12)} ${err.message}`); return null; });
    await recordDomainUsage('cos', { actions: 1 });
    const fix = gen?.fix;
    const hasEdits = fix && ((Array.isArray(fix.edits) && fix.edits.length > 0) || (fix.find && typeof fix.replace === 'string'));
    if (!hasEdits) { skipped += 1; onProgress({ type: 'fix:skip', commentId: f.commentId, reason: 'no anchored fix' }); continue; }
    // acceptManuscriptFix throws when the anchor can't be located — treat as a
    // skip (never a mis-applied edit).
    const applied = await acceptManuscriptFix(seriesId, { commentId: f.commentId, find: fix.find, replace: fix.replace, edits: fix.edits })
      .catch((err) => { console.error(`⚠️ series-fix apply failed — comment=${String(f.commentId).slice(0, 12)} ${err.message}`); return null; });
    if (applied) { fixed += 1; onProgress({ type: 'fix:done', commentId: f.commentId }); }
    else { skipped += 1; onProgress({ type: 'fix:skip', commentId: f.commentId, reason: 'could not anchor' }); }
  }
  // Fixes accepted findings + rewrote manuscript sections, so the persisted
  // verdict is now stale — drop it so a reload can't re-surface (and re-fix) it.
  if (fixed > 0) await clearSnapshot(seriesId);
  console.log(`🔧 series fix — series=${seriesId.slice(0, 12)} fixed=${fixed} skipped=${skipped}/${open.length}${budgetStopped ? ' (budget-stopped)' : ''}`);
  return { fixed, skipped, total: open.length, budgetStopped };
}

// ---------------------------------------------------------------------------
// SSE runner (shared factory — mirrors checkRunner / editorialAnalysisRunner).
// ---------------------------------------------------------------------------

const runner = createSseRunner({ logLabel: 'series review' });

/**
 * Identity of a review kickoff: what the run would actually do. Two starts with
 * the same signature produce the same verdict, so the second can safely attach
 * to the first's in-flight run (a reload/remount re-attaching to its own
 * request). A DIFFERENT signature would review with a different note, provider,
 * or gate — attaching to the running one would silently drop those options and
 * report its verdict as this request's, so the factory reports a `conflict`
 * instead (#4113). Pure.
 *
 * `feedback` is trimmed to match the service's own `feedback && trim()` gate, so
 * a blank note and an absent one are the same work.
 */
export function seriesReviewRequestSig({ feedback, providerOverride, modelOverride, force, readinessGate } = {}) {
  return JSON.stringify({
    feedback: String(feedback ?? '').trim() || null,
    providerOverride: providerOverride ?? null,
    modelOverride: modelOverride ?? null,
    force: !!force,
    readinessGate: readinessGate ?? null,
  });
}

export function startSeriesReviewRun(seriesId, options = {}) {
  // A second start while a review is in flight coalesces ONLY when it would run
  // the same review; a divergent one gets `{ alreadyRunning: true, conflict:
  // true }` so the caller can surface it rather than lose its options.
  const sig = seriesReviewRequestSig(options);
  return runner.start(seriesId, async ({ runId, signal, record, broadcast }) => {
    broadcast({ type: 'start', runId });
    const result = await runSeriesReview(seriesId, {
      feedback: options.feedback,
      providerOverride: options.providerOverride,
      modelOverride: options.modelOverride,
      force: options.force,
      readinessGate: options.readinessGate,
      signal,
      onProgress: (event) => broadcast({ ...event, runId }),
    });
    if (record.cancelRequested || result === null) {
      broadcast({ type: 'canceled', runId, canceledAt: nowIso() });
      return;
    }
    broadcast({
      type: 'complete',
      runId,
      verdict: result.verdict,
      findingCount: result.findingCount,
      completedAt: nowIso(),
    });
  }, { sig });
}

export const attachClient = (seriesId, res) => runner.attachClient(seriesId, res);
export const isSeriesReviewActive = (seriesId) => runner.isActive(seriesId);
export const cancelSeriesReview = (seriesId) => runner.cancel(seriesId);

// Separate runner instance for the fix pass, so a review and a fix are tracked
// independently per series (distinct keys are the same seriesId, but distinct
// runner maps — a review SSE and a fix SSE never collide).
const fixRunner = createSseRunner({ logLabel: 'series fix' });

/**
 * Identity of a fix kickoff. Same contract as `seriesReviewRequestSig`, and the
 * stakes are higher: the fix path WRITES the manuscript, so a start scoped to a
 * different finding set must never bind onto the in-flight run and report its
 * `fixed/skipped` totals as its own. `commentIds` is sorted (and deduped) so the
 * same finding set in a different order is the same work; absent/empty both mean
 * "every open finding", which is what `runSeriesFix` does with either. Pure.
 */
export function seriesFixRequestSig({ commentIds, providerOverride, modelOverride } = {}) {
  const ids = Array.isArray(commentIds) && commentIds.length ? [...new Set(commentIds)].sort() : null;
  return JSON.stringify({
    commentIds: ids,
    providerOverride: providerOverride ?? null,
    modelOverride: modelOverride ?? null,
  });
}

export function startSeriesFixRun(seriesId, options = {}) {
  const sig = seriesFixRequestSig(options);
  return fixRunner.start(seriesId, async ({ runId, signal, record, broadcast }) => {
    broadcast({ type: 'start', runId });
    const result = await runSeriesFix(seriesId, {
      commentIds: options.commentIds,
      providerOverride: options.providerOverride,
      modelOverride: options.modelOverride,
      signal,
      onProgress: (event) => broadcast({ ...event, runId }),
    });
    if (result?.rejected) {
      broadcast({ type: 'rejected', runId, mode: result.mode || null, reason: result.reason || null, rejectedAt: nowIso() });
      return;
    }
    if (record.cancelRequested) {
      broadcast({ type: 'canceled', runId, canceledAt: nowIso() });
      return;
    }
    broadcast({
      type: 'complete',
      runId,
      fixed: result.fixed,
      skipped: result.skipped,
      total: result.total,
      budgetStopped: result.budgetStopped === true,
      completedAt: nowIso(),
    });
  }, { sig });
}

export const attachFixClient = (seriesId, res) => fixRunner.attachClient(seriesId, res);
export const isSeriesFixActive = (seriesId) => fixRunner.isActive(seriesId);
export const cancelSeriesFix = (seriesId) => fixRunner.cancel(seriesId);

export const __testing = { runs: runner.runs, fixRuns: fixRunner.runs };