2sagaco48 1.0.0

package/src/lib/ai-revision.ts

@@ -0,0 +1,623 @@
+/**
+ * AI REVISION v3 — Pareto-Superior Targeted Recursive Revision Loop.
+ * ---------------------------------------------------------------------------
+ * Solves the core pathology where scores previously fell or stagnated:
+ * 1. WEIGHTED-DEFICIT TARGETING:
+ *    Plot (20%) + Character (20%) + Cleanliness (15%) = 55% of the rubric and
+ *    CANNOT move under word-level cosmetic substitutions. We compute exact
+ *    weighted deficits per category: Deficit_k = (Target - Score_k) * Weight_k.
+ * 2. L0 -> L1 -> L2 ESCALATION WITH INSERTS & ROTATING MECHANISMS:
+ *    - L0 (Micro-edit): Line-level prose polish and cosmetic tuning.
+ *    - L1 (Scene-level insert): Missing dramatic confrontation, character agency,
+ *      and direct dialogue subtext inserts.
+ *    - L2 (Macro-structural reversal insert): Irreversible sacrifice, antagonist
+ *      active intervention, true climax staging, and elimination of administrative
+ *      anti-climaxes.
+ * 3. TWO-MODEL NOISE CALIBRATION (Promotion Margin):
+ *    Judge LLMs have inherent stochastic variance (~1.0 pt). We enforce a
+ *    calibrated promotion threshold (+0.5 pt margin) so stochastic noise does
+ *    not promote degenerate or disguised regressions.
+ * 4. PER-CRITERION REGRESSION GUARD:
+ *    If an iteration gains on Prose Style but regresses on Plot Architecture or
+ *    Character Voice by more than the tolerance, it is rejected and rolled back.
+ * 5. DIAGNOSE STAGNATION (Plateau vs Decline):
+ *    Detects plateau (score delta within +/- 0.5 for 2 turns) vs decline (score drop),
+ *    surfaces exact diagnostic explanations, and triggers immediate escalation to
+ *    higher-level insertion mechanisms.
+ * 6. 15 NEGATIVE-SPACE SHAPES & 6-MECHANISM PORTFOLIO:
+ *    Explicitly embedded into the prompt, forcing the LLM to verify and avoid all
+ *    15 failure modes (FM-02 to FM-16) while executing distinct micro-architectures.
+ */
+import { gradeManuscriptV2, type ManuscriptGradeReportV2 } from "./manuscript-grade-v2";
+
+export interface RevisionModel {
+  provider: string;
+  modelId: string;
+}
+
+export type EscalationLevel = "L0-micro" | "L1-scene-insert" | "L2-macro-reversal";
+
+export type RevisionProgressEvent =
+  | { phase: "grading-initial" }
+  | { phase: "grading-initial-done"; report: ManuscriptGradeReportV2 }
+  | { phase: "revising"; iteration: number; model: RevisionModel; escalation: EscalationLevel; targetCategory: string }
+  | { phase: "revising-done"; iteration: number; changedRatioPct: number; anomaly?: string; stagnationDiagnosis?: string }
+  | { phase: "grading"; iteration: number; model: RevisionModel }
+  | { phase: "grading-done"; iteration: number; report: ManuscriptGradeReportV2; accepted: boolean; rejectionReason?: string }
+  | { phase: "error"; message: string }
+  | { phase: "done"; result: RevisionLoopResult };
+
+export interface RevisionIteration {
+  iteration: number;
+  beforeScore: number;
+  afterScore: number;
+  reviseModel: RevisionModel;
+  gradeModel: RevisionModel;
+  changedRatioPct: number;
+  escalation: EscalationLevel;
+  accepted: boolean;
+  rejectionReason?: string;
+  anomaly?: string;
+  stagnationDiagnosis?: string;
+  unitCounts?: UnitCounts;
+  budgetUsedPct?: number;
+}
+
+export interface RevisionLoopResult {
+  status: "target-met" | "budget-exhausted" | "error";
+  initialReport: ManuscriptGradeReportV2 | null;
+  finalReport: ManuscriptGradeReportV2 | null;
+  iterations: RevisionIteration[];
+  finalText: string;
+  error?: string;
+  plateauDetected?: boolean;
+}
+
+/** Approximate changed ratio via common prefix/suffix. */
+export function changedRatioPct(a: string, b: string): number {
+  if (a === b) return 0;
+  const maxLen = Math.max(a.length, b.length, 1);
+  let prefix = 0;
+  const minLen = Math.min(a.length, b.length);
+  while (prefix < minLen && a.charCodeAt(prefix) === b.charCodeAt(prefix)) prefix++;
+  let suffix = 0;
+  while (
+    suffix < minLen - prefix &&
+    a.charCodeAt(a.length - 1 - suffix) === b.charCodeAt(b.length - 1 - suffix)
+  )
+    suffix++;
+  const unchanged = prefix + suffix;
+  return Math.round(Math.min(100, Math.max(0, (1 - unchanged / maxLen) * 100)));
+}
+
+function extractChapterHeadings(text: string): string[] {
+  const heads: string[] = [];
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (/^(#{1,3}\s+|chapter\s+\d+|part\s+\d+)/i.test(t) && t.length < 120) heads.push(t.slice(0, 100));
+    if (heads.length >= 40) break;
+  }
+  return heads;
+}
+
+export interface CategoryDeficit {
+  key: string;
+  label: string;
+  weightPct: number;
+  currentScore: number;
+  weightedDeficit: number;
+}
+
+export function computeCategoryDeficits(report: ManuscriptGradeReportV2, targetScore: number): CategoryDeficit[] {
+  return report.categories
+    .map((c) => {
+      const deficit = Math.max(0, targetScore - c.score);
+      const weightedDeficit = Math.round(deficit * (c.weightPct / 100) * 100) / 100;
+      return {
+        key: c.key,
+        label: c.label,
+        weightPct: c.weightPct,
+        currentScore: c.score,
+        weightedDeficit,
+      };
+    })
+    .sort((a, b) => b.weightedDeficit - a.weightedDeficit);
+}
+
+/** Determine escalation level based on iteration history and largest deficit category. */
+export function determineEscalation(
+  iteration: number,
+  consecutivePlateaus: number,
+  topDeficit: CategoryDeficit,
+): EscalationLevel {
+  // If the top deficit is Plot or Character and we have stagnated, or iteration >= 2, escalate to inserts
+  if (["plot", "character", "cleanliness"].includes(topDeficit.key)) {
+    if (iteration >= 3 || consecutivePlateaus >= 1) return "L2-macro-reversal";
+    if (iteration >= 2) return "L1-scene-insert";
+  }
+  if (consecutivePlateaus >= 2) return "L2-macro-reversal";
+  if (consecutivePlateaus >= 1 || iteration >= 2) return "L1-scene-insert";
+  return "L0-micro";
+}
+
+/** Diagnosis of stagnation separating plateau from decline. */
+export function diagnoseStagnation(history: RevisionIteration[]): { isStagnant: boolean; isDecline: boolean; diagnosis: string } {
+  if (history.length < 2) return { isStagnant: false, isDecline: false, diagnosis: "Initial trajectory establishing." };
+  const last = history[history.length - 1];
+  const prev = history[history.length - 2];
+  const delta = last.afterScore - prev.afterScore;
+
+  if (delta < -1.5) {
+    return {
+      isStagnant: true,
+      isDecline: true,
+      diagnosis: `Score dropped by ${Math.abs(delta).toFixed(2)} pts. Cause: cosmetic edits disturbed rhythm or caused pronoun/POV drift without adding narrative substance.`,
+    };
+  }
+  if (Math.abs(delta) <= 0.6) {
+    return {
+      isStagnant: true,
+      isDecline: false,
+      diagnosis: `Score plateaued (Δ ${delta > 0 ? "+" : ""}${delta.toFixed(2)} pts). Cause: Plot & Character deficits cannot move via word-level substitution. Escalation to scene/reversal insertion required.`,
+    };
+  }
+  return { isStagnant: false, isDecline: false, diagnosis: `Active progress: +${delta.toFixed(2)} pts.` };
+}
+
+/** 15 Negative-space shapes to avoid (derived from FM-02 through FM-16). */
+export const FIFTEEN_NEGATIVE_PATTERNS = [
+  "1. Re-staging the opening (FM-02): Do not rewrite Chapter 1's Call to Adventure when revising later chapters.",
+  "2. Procedural Deadlock (FM-03): Do not have characters enter a room, take measurements, and cancel threats with a form.",
+  "3. Severe Truncation (FM-04): Do not truncate chapters into brief 300-word summaries; preserve fully fleshed-out scenes.",
+  "4. Wound Tag Fatigue (FM-05): Do not repeat literal story-bible wound tags ('survivor guilt was a cloak', 'love's trap'); show them via actions.",
+  "5. Double Article Glitch (FM-06): Do not output 'The The' or 'A A' in chapter titles.",
+  "6. Citation Leakage (FM-07): Never emit bracketed metadata ([Source 1], [CHECKSUM], [VERIFIED]).",
+  "7. POV Slippage (FM-08): Do not flip second-person ('You') to third-person ('He/Him') during line-edits.",
+  "8. Climax Evasion (FM-09): Do not resolve the central confrontation via an administrative decree, petition, or audit filing.",
+  "9. Spatial Whiplash (FM-10): Do not jump characters between distant incompatible locations without transit logistics.",
+  "10. Epistemic Concept Overload (FM-11): Do not dump 5 theoretical doctrines into dialogue in one scene.",
+  "11. Handoff Duplication (FM-12): Do not duplicate the exact same cognitive transfer/revelation in multiple chapters.",
+  "12. Temporal Claustrophobia (FM-13): Do not compress an epic journey into a 3-hour morning commute.",
+  "13. Instrument/Sensor Fetishism (FM-14): Do not pad prose with lists of hertz, decibels, millibars, and picoseconds.",
+  "14. Currency Bookkeeping (FM-15): Do not reduce character interactions to ledgers, coin debits, and fines.",
+  "15. Consequence Annihilation (FM-16): When a character makes a sacrifice, do not undo or ignore it in the next chapter.",
+];
+
+/** 6 Mechanism Portfolio for targeted resolution. */
+export const SIX_MECHANISM_PORTFOLIO = [
+  "M1 (Irreversible Choice): Protagonist must destroy an asset or sever an alliance to escape, permanently closing an exit.",
+  "M2 (Antagonist Coercion): Antagonist physically enforces their deadline or seizes territory on the page, forcing real stakes.",
+  "M3 (Subtext Dialogue): Replace exposition with dialogue where characters talk about one thing while meaning another.",
+  "M4 (Active Transit): Bridge any location shift with sensory transit (distance, mode, physical fatigue, cost of passage).",
+  "M5 (Dramatized Climax): Stage the final confrontation face-to-face with dialogue and high-stakes choice, not a legal memo.",
+  "M6 (Physicalized Consequence): Show character wounds through bodily reflexes, hesitation, and tactical mistakes rather than internal monologue.",
+];
+
+// ── v4: rewrite budget, edit units, exponential decay ────────────────────────
+export type EditUnit = "word" | "phrase" | "sentence" | "paragraph" | "page" | "chapter";
+export const EDIT_UNIT_ORDER: EditUnit[] = ["word", "phrase", "sentence", "paragraph", "page", "chapter"];
+
+export interface RevisionBudgetOptions {
+  /** Max fraction of the manuscript that may change, % (1-50). Default 25. */
+  maxRewritePct: number;
+  /** Max contiguous replacement length in paragraphs (1-30). Default 10. */
+  maxReplacementParagraphs: number;
+  /** When true, one full-chapter replacement is permitted as the absolute max. Default false. */
+  allowChapterReplacement: boolean;
+}
+
+export const DEFAULT_REVISION_BUDGET: RevisionBudgetOptions = {
+  maxRewritePct: 25,
+  maxReplacementParagraphs: 10,
+  allowChapterReplacement: false,
+};
+
+export function normalizeBudget(b?: Partial<RevisionBudgetOptions>): RevisionBudgetOptions {
+  const n = (v: unknown, lo: number, hi: number, fb: number) => {
+    const x = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(x) ? Math.min(hi, Math.max(lo, Math.round(x))) : fb;
+  };
+  return {
+    maxRewritePct: n(b?.maxRewritePct, 1, 50, DEFAULT_REVISION_BUDGET.maxRewritePct),
+    maxReplacementParagraphs: n(b?.maxReplacementParagraphs, 1, 30, DEFAULT_REVISION_BUDGET.maxReplacementParagraphs),
+    allowChapterReplacement: b?.allowChapterReplacement === true,
+  };
+}
+
+export interface UnitBudget { unit: EditUnit; sharePct: number; maxEdits: number }
+
+/**
+ * Exponential-decay edit budget: smallest units get the most edits.
+ * weight(level) = exp(-0.9 * level); shares normalized to 100%.
+ * A "page" = 3 consecutive paragraphs; "chapter" is only budgeted when allowed.
+ */
+export function decayEditBudget(totalEdits: number, allowChapter: boolean): UnitBudget[] {
+  const levels = allowChapter ? EDIT_UNIT_ORDER : EDIT_UNIT_ORDER.slice(0, 5);
+  const weights = levels.map((_, i) => Math.exp(-0.9 * i));
+  const sum = weights.reduce((a, b) => a + b, 0);
+  return levels.map((unit, i) => ({
+    unit,
+    sharePct: Math.round((weights[i] / sum) * 100),
+    maxEdits: Math.max(unit === "word" ? 1 : 0, Math.round((totalEdits * weights[i]) / sum)),
+  }));
+}
+
+export type UnitCounts = Record<EditUnit, number>;
+
+/**
+ * Honest heuristic classification of what changed between drafts.
+ * word: isolated single-word substitution; phrase: a changed run of 2-3 words
+ * (a word change recurring 2x within 3 words is a phrase, per spec);
+ * sentence/paragraph: changed sentences/paragraphs; page: 3+ consecutive
+ * changed paragraphs; chapter: >60% of paragraphs changed.
+ */
+export function classifyRevisionUnits(before: string, after: string): UnitCounts {
+  const counts: UnitCounts = { word: 0, phrase: 0, sentence: 0, paragraph: 0, page: 0, chapter: 0 };
+  if (before === after) return counts;
+  const bParas = before.split(/\n{2,}/);
+  const aParas = after.split(/\n{2,}/);
+  const maxLen = Math.max(bParas.length, aParas.length, 1);
+  let changedParas = 0;
+  let run = 0;
+  const n = Math.max(bParas.length, aParas.length);
+  for (let i = 0; i < n; i++) {
+    const b = (bParas[i] ?? "").trim();
+    const a = (aParas[i] ?? "").trim();
+    if (b === a) {
+      if (run >= 3) counts.page += Math.floor(run / 3);
+      run = 0;
+      continue;
+    }
+    changedParas++;
+    run++;
+    counts.paragraph++;
+    // sentence-level diff within the paragraph
+    const bS = b.split(/(?<=[.!?])\s+/).filter(Boolean);
+    const aS = a.split(/(?<=[.!?])\s+/).filter(Boolean);
+    const m = Math.max(bS.length, aS.length);
+    for (let s = 0; s < m; s++) {
+      const bs = (bS[s] ?? "").trim();
+      const as = (aS[s] ?? "").trim();
+      if (bs === as || !bs || !as) continue;
+      counts.sentence++;
+      // word-run analysis: changed runs of 1 word = word edit, 2-3 = phrase, longer = sentence-level (already counted)
+      const bw = bs.split(/\s+/);
+      const aw = as.split(/\s+/);
+      let runLen = 0;
+      const flush = () => {
+        if (runLen === 1) counts.word++;
+        else if (runLen >= 2 && runLen <= 3) counts.phrase++;
+        runLen = 0;
+      };
+      const wmax = Math.max(bw.length, aw.length);
+      for (let w = 0; w < wmax; w++) {
+        if ((bw[w] ?? "") === (aw[w] ?? "")) flush();
+        else runLen++;
+      }
+      flush();
+    }
+  }
+  if (run >= 3) counts.page += Math.floor(run / 3);
+  if (changedParas / maxLen > 0.6) counts.chapter = 1;
+  return counts;
+}
+
+/** Per-category delta directives: NEW instructions targeting THIS draft's movement. */
+export function buildDynamicDirectives(
+  prevReport: ManuscriptGradeReportV2 | null,
+  currentReport: ManuscriptGradeReportV2,
+  stallCounts: Record<string, number>,
+): string[] {
+  const out: string[] = [];
+  for (const c of currentReport.categories) {
+    const prev = prevReport?.categories.find((p) => p.key === c.key)?.score;
+    const delta = prev == null ? null : Math.round((c.score - prev) * 100) / 100;
+    const stalls = stallCounts[c.key] ?? 0;
+    if (delta == null) {
+      out.push(`NEW INSTRUCTION [${c.label} ${c.score}/100]: first scored draft — attack its weakest quoted evidence first (see rewrite pairs).`);
+    } else if (delta <= -1) {
+      out.push(`NEW INSTRUCTION [${c.label} ${prev}→${c.score} REGRESSED]: revert the approach that caused this drop; make ZERO ${c.label.toLowerCase()} edits except one minimal repair to the single worst passage quoted in the latest report.`);
+    } else if (stalls >= 2 || (Math.abs(delta) < 0.6 && stalls >= 1)) {
+      out.push(`NEW INSTRUCTION [${c.label} STALLED ${stalls + 1} rounds at ~${c.score}]: escalate one unit level (word→sentence→paragraph) and change tactic entirely — use a different mechanism from the portfolio than prior rounds.`);
+    } else if (delta > 0) {
+      out.push(`NEW INSTRUCTION [${c.label} improving +${delta}]: continue the same tactic on the NEXT-weakest passage only; do not revisit already-fixed text.`);
+    } else {
+      out.push(`NEW INSTRUCTION [${c.label} flat at ${c.score}]: apply exactly one focused edit to its weakest quoted passage; leave the rest byte-identical.`);
+    }
+  }
+  return out;
+}
+
+export function buildTargetedRevisionPrompt(args: {
+  originalText: string;
+  currentText: string;
+  currentReport: ManuscriptGradeReportV2;
+  priorReports: ManuscriptGradeReportV2[];
+  targetScore: number;
+  iteration: number;
+  maxIterations: number;
+  escalation: EscalationLevel;
+  topDeficits: CategoryDeficit[];
+  budget?: RevisionBudgetOptions;
+  stallCounts?: Record<string, number>;
+  dynamicDirectives?: string[];
+}): string {
+  const { originalText, currentText, currentReport, priorReports, targetScore, iteration, maxIterations, escalation, topDeficits } = args;
+  const budget = normalizeBudget(args.budget);
+  const prevReport = priorReports.length ? priorReports[priorReports.length - 1] : null;
+  const directives = args.dynamicDirectives ?? buildDynamicDirectives(prevReport, currentReport, args.stallCounts ?? {});
+
+  const deficitList = topDeficits
+    .slice(0, 3)
+    .map((d) => `- ${d.label} (${d.weightPct}% weight): current score ${d.currentScore}/100 -> weighted deficit ${d.weightedDeficit.toFixed(2)} pts`)
+    .join("\n");
+  const unitTable = decayEditBudget(20, budget.allowChapterReplacement)
+    .map((u) => `- ${u.unit}: up to ${u.maxEdits} edits (${u.sharePct}% of edit budget)`)
+    .join("\n");
+
+  const escalationInstructions: Record<EscalationLevel, string> = {
+    "L0-micro": "LEVEL: L0 (Micro Line-Level Polish). Target stylistic flow, word choice, and dialogue cadence. Fix typos and eliminate repetitive words without altering scenes.",
+    "L1-scene-insert": "LEVEL: L1 (Scene-Level Dynamic Insertion). Add 1-2 new high-tension beats or dialogue exchanges into the weakest chapters. Deepen character agency, force an unscripted choice, and reveal subtext.",
+    "L2-macro-reversal": "LEVEL: L2 (Macro-Structural Resolution Insertion). Replace any administrative/anti-climactic resolution with a DRAMATIZED face-to-face confrontation with the antagonist. Introduce an irreversible sacrifice (asset lost, alliance broken, wound paid for) so the climax is real and earned.",
+  };
+
+  const rewrites = currentReport.rewriteSuggestions.slice(0, Math.min(12, 4 + iteration * 2));
+  const history = priorReports
+    .map((r, i) => `  Draft #${i}: Composite ${r.weightedComposite.toFixed(2)} (${r.compositeLetterBand}) [Plot: ${r.categories.find(c => c.key === "plot")?.score ?? "—"}, Char: ${r.categories.find(c => c.key === "character")?.score ?? "—"}, Prose: ${r.categories.find(c => c.key === "prose")?.score ?? "—"}]`)
+    .join("\n");
+  const anchors = extractChapterHeadings(originalText).slice(0, 24).join(" | ") || "(no chapter headings detected)";
+
+  return [
+    "MINIMAL SURGICAL REVISION PASS — PARETO-SUPERIOR TARGETED REVISION",
+    `Target composite: ${targetScore}/100. Current composite: ${currentReport.weightedComposite.toFixed(2)}/100 (${currentReport.compositeLetterBand}). Iteration ${iteration} of ${maxIterations}.`,
+    "",
+    "=== TARGETED DEFICIT DIRECTIVE ===",
+    `You are tasked with closing the score gap by focusing primarily on these highest-deficit categories:`,
+    deficitList,
+    "",
+    `=== ESCALATION OPERATING MODE ===`,
+    escalationInstructions[escalation],
+    "",
+    "=== MANDATORY 15 NEGATIVE PATTERNS (AVOID ALL 15) ===",
+    FIFTEEN_NEGATIVE_PATTERNS.join("\n"),
+    "",
+    "=== 6-MECHANISM PORTFOLIO (EXECUTE APPLICABLE SUBSET) ===",
+    SIX_MECHANISM_PORTFOLIO.join("\n"),
+    "",
+    "=== REVISION RULES ===",
+    "1. Keep all existing chapters in order. Do not drop chapters.",
+    "2. If an edit does not improve narrative tension or structural logic, do not make it.",
+    "3. Never output commentary, JSON, or code fences. Output ONLY the complete revised story text.",
+    "",
+    `=== DYNAMIC DIRECTIVES FOR THIS DRAFT (iteration ${iteration} — these are NEW, follow them over any prior-round habit) ===`,
+    ...directives,
+    "",
+    `=== REWRITE BUDGET (hard limits for this pass) ===`,
+    `- Total changed text must not exceed ${budget.maxRewritePct}% of the manuscript.`,
+    `- No single contiguous replacement may exceed ${budget.maxReplacementParagraphs} paragraph(s)${budget.allowChapterReplacement ? "; ONE full-chapter replacement is permitted as the absolute max" : " (full-chapter replacement FORBIDDEN this pass)"}.`,
+    "- Prefer the SMALLEST unit that fixes the defect. Edit budget follows exponential decay (most edits at word level, fewest at page/chapter):",
+    unitTable,
+    "- Unit honesty rule: an isolated 1-word substitution = word edit; a changed run of 2-3 words = phrase edit; anything longer counts at sentence level or above.",
+    "",
+    "VERIFIED LINE-LEVEL REWRITE PAIRS:",
+    rewrites.length
+      ? rewrites.map((r) => `- [${r.category}] "${r.originalQuote.slice(0, 140)}" => "${r.rewrittenQuote.slice(0, 140)}"${r.verified ? "" : " (verify before using)"}`).join("\n")
+      : "- (none available)",
+    "",
+    "GRADING HISTORY & TRAJECTORY:",
+    history || "  (initial grade only)",
+    "",
+    "ORIGINAL-STORY ANCHORS:",
+    `  Chapters: ${anchors}`,
+    "",
+    "CURRENT MANUSCRIPT TO REVISE:",
+    "<<<BEGIN_MANUSCRIPT>>>",
+    currentText,
+    "<<<END_MANUSCRIPT>>>",
+  ].join("\n");
+}
+
+function detectAnomaly(source: string, revised: string, beforeScore: number, afterScore: number, ratio: number, maxRewritePct = 50): string | undefined {
+  const flags: string[] = [];
+  if (revised.length < source.length * 0.45) flags.push("severe truncation (output <45% of input length)");
+  if (ratio > maxRewritePct) flags.push(`rewrite budget exceeded (${ratio}% > ${maxRewritePct}% cap)`);
+  if (afterScore < beforeScore - 1.5) flags.push(`score regression ${beforeScore.toFixed(1)} -> ${afterScore.toFixed(1)}`);
+  const srcCh = (source.match(/chapter|##\s+/gi) || []).length;
+  const revCh = (revised.match(/chapter|##\s+/gi) || []).length;
+  if (srcCh >= 2 && revCh < Math.floor(srcCh * 0.6)) flags.push("chapter omission (chapter markers lost)");
+  if (!revised.trim()) flags.push("empty revision output");
+  return flags.length ? flags.join("; ") : undefined;
+}
+
+export async function runRecursiveRevisionLoop(args: {
+  manuscriptText: string;
+  targetScore: number;
+  maxIterations: number;
+  pickModel: (exclude: string[]) => RevisionModel | null;
+  generate: (userMessage: string, choice: RevisionModel) => Promise<string>;
+  onProgress?: (e: RevisionProgressEvent) => void;
+  promotionMargin?: number;
+  budget?: Partial<RevisionBudgetOptions>;
+}): Promise<RevisionLoopResult> {
+  const { manuscriptText, targetScore, maxIterations, pickModel, generate, onProgress, promotionMargin = 0.5 } = args;
+  const budget = normalizeBudget(args.budget);
+  const stallCounts: Record<string, number> = {};
+  const emit = (e: RevisionProgressEvent) => {
+    try {
+      onProgress?.(e);
+    } catch {
+      /* fail-open */
+    }
+  };
+
+  const iterations: RevisionIteration[] = [];
+  const priorReports: ManuscriptGradeReportV2[] = [];
+  let consecutivePlateaus = 0;
+
+  try {
+    emit({ phase: "grading-initial" });
+    const g0choice = pickModel([]);
+    if (!g0choice) throw new Error("No model with a configured API key is available.");
+    const initialReport = await gradeManuscriptV2(manuscriptText, { provider: g0choice.provider, modelId: g0choice.modelId }, (msg) =>
+      generate(msg, g0choice),
+    );
+    emit({ phase: "grading-initial-done", report: initialReport });
+    priorReports.push(initialReport);
+
+    let bestText = manuscriptText;
+    let bestReport: ManuscriptGradeReportV2 = initialReport;
+    let lastModelId = g0choice.modelId;
+
+    if (initialReport.weightedComposite >= targetScore) {
+      const result: RevisionLoopResult = { status: "target-met", initialReport, finalReport: initialReport, iterations, finalText: bestText };
+      emit({ phase: "done", result });
+      return result;
+    }
+
+    const maxLoops = Math.max(1, Math.min(8, maxIterations));
+    for (let i = 1; i <= maxLoops; i++) {
+      const deficits = computeCategoryDeficits(bestReport, targetScore);
+      const topDeficit = deficits[0] ?? { key: "plot", label: "Plot", weightPct: 20, currentScore: 50, weightedDeficit: 8 };
+      const escalation = determineEscalation(i, consecutivePlateaus, topDeficit);
+
+      const reviseChoice = pickModel([lastModelId]);
+      if (!reviseChoice) throw new Error("No model available for revision step.");
+      emit({ phase: "revising", iteration: i, model: reviseChoice, escalation, targetCategory: topDeficit.label });
+
+      const prompt = buildTargetedRevisionPrompt({
+        originalText: manuscriptText,
+        currentText: bestText,
+        currentReport: bestReport,
+        priorReports: priorReports.slice(),
+        targetScore,
+        iteration: i,
+        maxIterations: maxLoops,
+        escalation,
+        topDeficits: deficits,
+        budget,
+        stallCounts,
+      });
+
+      const revised = (await generate(prompt, reviseChoice)).trim();
+      lastModelId = reviseChoice.modelId;
+      const ratio = changedRatioPct(bestText, revised);
+      const unitCounts = classifyRevisionUnits(bestText, revised);
+      const beforeScore = bestReport.weightedComposite;
+
+      // Grade with fresh random model
+      const gradeChoice = pickModel([reviseChoice.modelId]);
+      if (!gradeChoice) throw new Error("No model available for grading step.");
+      emit({ phase: "grading", iteration: i, model: gradeChoice });
+      const afterReport = await gradeManuscriptV2(revised, { provider: gradeChoice.provider, modelId: gradeChoice.modelId }, (msg) =>
+        generate(msg, gradeChoice),
+      );
+      lastModelId = gradeChoice.modelId;
+
+      // Update per-category stall counters from THIS draft's movement (drives next round's dynamic directives).
+      for (const c of afterReport.categories) {
+        const prev = bestReport.categories.find((p) => p.key === c.key)?.score ?? c.score;
+        const moved = Math.abs(c.score - prev) >= 0.6;
+        stallCounts[c.key] = moved ? 0 : (stallCounts[c.key] ?? 0) + 1;
+      }
+
+      const anomaly = detectAnomaly(bestText, revised, beforeScore, afterReport.weightedComposite, ratio, budget.maxRewritePct);
+
+      // Noise calibration & per-criterion regression guard + rewrite-budget enforcement.
+      const scoreDelta = afterReport.weightedComposite - beforeScore;
+      const plotBefore = bestReport.categories.find((c) => c.key === "plot")?.score ?? 50;
+      const plotAfter = afterReport.categories.find((c) => c.key === "plot")?.score ?? 50;
+      const charBefore = bestReport.categories.find((c) => c.key === "character")?.score ?? 50;
+      const charAfter = afterReport.categories.find((c) => c.key === "character")?.score ?? 50;
+
+      let accepted = false;
+      let rejectionReason: string | undefined;
+
+      // Hard reject: empty / catastrophic truncation / chapter loss / over-budget rewrite.
+      // Budget reject is honest power: a 90% rewrite claiming to be "minimal" is not promoted.
+      const hardReject =
+        !revised.trim() ||
+        revised.length < bestText.length * 0.45 ||
+        ratio > budget.maxRewritePct + 0.5 ||
+        (anomaly || "").includes("chapter omission");
+
+      if (hardReject) {
+        accepted = false;
+        rejectionReason = anomaly
+          ? `Hard reject: ${anomaly}. Prior best retained.`
+          : `Hard reject: empty/truncated/over-budget revision. Prior best retained.`;
+        consecutivePlateaus++;
+      } else if (scoreDelta >= promotionMargin) {
+        if (plotAfter < plotBefore - 4 || charAfter < charBefore - 4) {
+          accepted = false;
+          rejectionReason = `Score increased (+${scoreDelta.toFixed(2)}) but core plot/character regressed (plot: ${plotBefore}->${plotAfter}, char: ${charBefore}->${charAfter}). Retaining prior best.`;
+          consecutivePlateaus++;
+        } else {
+          accepted = true;
+          bestText = revised;
+          bestReport = afterReport;
+          consecutivePlateaus = 0;
+        }
+      } else {
+        accepted = false;
+        rejectionReason = scoreDelta < 0
+          ? `Score declined (${beforeScore.toFixed(2)} -> ${afterReport.weightedComposite.toFixed(2)}). Best-kept rule preserved prior best draft.`
+          : `Improvement (+${scoreDelta.toFixed(2)}) below calibrated noise margin (+${promotionMargin}). Prior best retained.`;
+        consecutivePlateaus++;
+      }
+
+      emit({ phase: "grading-done", iteration: i, report: afterReport, accepted, rejectionReason });
+
+      const currentIterationRecord: RevisionIteration = {
+        iteration: i,
+        beforeScore,
+        afterScore: afterReport.weightedComposite,
+        reviseModel: reviseChoice,
+        gradeModel: gradeChoice,
+        changedRatioPct: ratio,
+        escalation,
+        accepted,
+        rejectionReason,
+        anomaly,
+        unitCounts,
+        budgetUsedPct: ratio,
+      };
+
+      const stag = diagnoseStagnation([...iterations, currentIterationRecord]);
+      currentIterationRecord.stagnationDiagnosis = stag.diagnosis;
+
+      emit({ phase: "revising-done", iteration: i, changedRatioPct: ratio, anomaly, stagnationDiagnosis: stag.diagnosis });
+      iterations.push(currentIterationRecord);
+      priorReports.push(afterReport);
+
+      if (bestReport.weightedComposite >= targetScore) {
+        const result: RevisionLoopResult = { status: "target-met", initialReport, finalReport: bestReport, iterations, finalText: bestText };
+        emit({ phase: "done", result });
+        return result;
+      }
+    }
+
+    const result: RevisionLoopResult = {
+      status: "budget-exhausted",
+      initialReport,
+      finalReport: bestReport,
+      iterations,
+      finalText: bestText,
+      plateauDetected: consecutivePlateaus >= 2,
+    };
+    emit({ phase: "done", result });
+    return result;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    emit({ phase: "error", message });
+    const result: RevisionLoopResult = {
+      status: "error",
+      initialReport: priorReports[0] ?? null,
+      finalReport: priorReports[priorReports.length - 1] ?? null,
+      iterations,
+      finalText: manuscriptText,
+      error: message,
+    };
+    emit({ phase: "done", result });
+    return result;
+  }
+}