2sagaco48 1.0.0

package/src/fiction/continuity.ts

@@ -0,0 +1,372 @@
+/**
+ * CONTINUITY GOVERNOR — deterministic world-state ledger + craft budgets.
+ * ---------------------------------------------------------------------------
+ * Purely local, no model call. Reads the prose the model ACTUALLY returned for
+ * chapters 1..N-1 and compiles a compact, machine-derived state block that is
+ * appended to the chapter-N request. Every line it emits is traceable to an
+ * extracted span, never invented.
+ *
+ * Targets the observed live failure modes:
+ *   FM-02 duplicate opening collision      -> CONTINUE-FROM lock + closing line
+ *   FM-03 procedural deadlock              -> change-vector requirement
+ *   FM-05 wound/motif re-statement         -> motif cooldown from real counts
+ *   FM-06 "The The" title bug              -> normalizeChapterTitle
+ *   FM-07 citation bracket leakage         -> stripHarnessResidue
+ *   FM-08 POV drift                        -> POV lock + measured violations
+ *   FM-09 climax evasion                   -> act ladder obligations
+ *   FM-10 spatial whiplash                 -> place history + transit rule
+ *   FM-11 concept overload                 -> new-concept budget
+ *   FM-12 duplicate relational beat        -> beat ledger
+ *   FM-13 temporal claustrophobia          -> macro clock ledger
+ *   FM-14 instrument fetishism             -> measurement budget
+ *   FM-15 compulsive currency audits       -> currency budget
+ *   FM-16 zero-stakes resets               -> irreversible-commitment ledger
+ */
+import type { SageBlueprint } from '@/lib/sage/engine';
+import type { StorySnapshot, ContinuityToggles } from "./types";
+import { DEFAULT_CONTINUITY_TOGGLES } from "./types";
+
+export type ChapterFacts = {
+  chapter: number;
+  title: string;
+  words: number;
+  places: string[];
+  clocks: string[];
+  dates: string[];
+  irreversible: string[];
+  currency: string[];
+  measurements: string[];
+  concepts: string[];
+  motifHits: Record<string, number>;
+  residue: string[];
+  povViolations: number;
+  dominantVerbs: string[];
+  closingLine: string;
+  openingLine: string;
+  /**
+   * The upstream continuity excerpt, preserved byte-for-byte: the first 420
+   * characters of the chapter with whitespace collapsed. The base compiler is
+   * fed exactly this, unchanged from the original pipeline.
+   */
+  excerpt420: string;
+};
+export type ContinuityLedger = {
+  facts: ChapterFacts[];
+  motifTotals: Record<string, number>;
+  conceptFirstSeen: Record<string, number>;
+  placeHistory: string[];
+  irreversibleAll: string[];
+  lastClock: string | null;
+  lastDate: string | null;
+};
+
+export const EMPTY_LEDGER: ContinuityLedger = {
+  facts: [], motifTotals: {}, conceptFirstSeen: {}, placeHistory: [], irreversibleAll: [], lastClock: null, lastDate: null,
+};
+
+// ── residue / title hygiene (deterministic, reversible-by-inspection) ───────
+export const RESIDUE_PATTERNS: { id: string; re: RegExp }[] = [
+  { id: "source-bracket", re: /\[\s*Sources?\s*:?\s*\d+[^\]]{0,40}\]/gi },
+  { id: "citation-tag", re: /\[\s*(?:S\d+|CTX|SRC|REF)\s*\d*\s*\]/gi },
+  { id: "checksum-tag", re: /\[\s*CHECKSUM[^\]]{0,60}\]/gi },
+  { id: "status-tag", re: /\[\s*(?:UNVERIFIED|VERIFIED|ASSUM|ASSUMPTION|DATA GAP|PROPOSED|POST-CUTOFF|DRAFT GAP|TODO|TBD)[^\]]{0,60}\]/gi },
+  { id: "harness-error", re: /^.*\b(?:GoogleGenerativeAI|fetch failed|ECONNRESET|finish_reason|FinishReason|HTTP \d{3} error)\b.*$/gim },
+  { id: "scratchpad", re: /^\s*(?:<\/?(?:scratchpad|thinking|plan)>|SCRATCHPAD:|PLAN:|INTERNAL NOTES?:).*$/gim },
+  { id: "resumption-notice", re: /^_?Resuming at chapter \d+;?.*finished chapter.*restored.*$/gim },
+  { id: "harness-preamble", re: /^.*(?:chapter\(s\) restored, not regenerated|_SAGE fiction run started:).*$/gim },
+];
+
+/** Removes harness residue. Returns cleaned text plus the ids actually hit. */
+export function stripHarnessResidue(text: string): { text: string; removed: string[] } {
+  let out = text;
+  const removed: string[] = [];
+  for (const { id, re } of RESIDUE_PATTERNS) {
+    re.lastIndex = 0;
+    if (re.test(out)) { removed.push(id); re.lastIndex = 0; out = out.replace(re, ""); }
+  }
+  out = out.replace(/[ \t]{2,}/g, " ").replace(/ +([,.;:!?])/g, "$1").replace(/\n{3,}/g, "\n\n").trim();
+  return { text: out, removed };
+}
+
+/** FM-06: collapses "The The Reckoning" / "A A Gate" produced by naive title templates. */
+export function normalizeChapterTitle(title: string): string {
+  return title
+    .replace(/\b(The)\s+(?:The)\b/gi, (_match, first: string) => first)
+    .replace(/\b(An?)\s+(?:An?)\b/gi, (_match, first: string) => first)
+    .replace(/\s{2,}/g, " ")
+    .replace(/\s+([,.;:])/g, "$1")
+    .trim();
+}
+
+// ── extraction ──────────────────────────────────────────────────────────────
+const CLOCK_RE = /\b([01]?\d|2[0-3]):([0-5]\d)\b/g;
+const DATE_RE = /\b(?:\d{1,2}(?:st|nd|rd|th)?\s+(?:of\s+)?[A-Z][a-z]{2,12}|[A-Z][a-z]{2,12}\s+\d{1,2},?\s*\d{0,4}|day\s+\d{1,3})\b/g;
+const CURRENCY_RE = /\b\d[\d,.]*\s*(?:gold|silver|copper|bronze)?\s*(?:marks?|sovereigns?|crowns?|pieces?|francs?|credits?|coins?|shillings?|dollars?|euros?|pounds?)\b/gi;
+const MEASURE_RE = /\b\d[\d,.]*\s*(?:hertz|hz|decibels?|db|millimet(?:er|re)s?|mm|centimet(?:er|re)s?|cm|met(?:er|re)s?|kilomet(?:er|re)s?|km|gram(?:me)?s?|kilogram(?:me)?s?|kg|milligrams?|mg|degrees?|celsius|fahrenheit|milligauss|millirads?|millibars?|picoseconds?|milliseconds?|percent|%|lumens?|lux|newtons?|pascals?|volts?|amps?|ohms?)\b/gi;
+const IRREVERSIBLE_RE = /[^.!?\n]*\b(?:died|dies|dead|killed|kills|slain|corpse|buried|drowned|destroyed|burned down|burnt|shattered|collapsed|sank|severed|amputated|exiled|banished|forfeited|surrendered|signed away|sold|betrayed|confessed|revealed|arrested|imprisoned|seized|foreclosed|evicted|resigned|abandoned)\b[^.!?\n]*[.!?]/gi;
+const VERB_RE = /\b(measured|inspected|audited|checked|recorded|noted|calibrated|examined|reviewed|filed|signed|walked|entered|descended|climbed|argued|negotiated|waited|counted|logged)\b/gi;
+
+function uniq(list: string[], cap: number): string[] {
+  return [...new Set(list.map((entry) => entry.trim()).filter(Boolean))].slice(0, cap);
+}
+function matches(text: string, re: RegExp, cap = 40): string[] {
+  re.lastIndex = 0;
+  return uniq([...text.matchAll(re)].map((match) => match[0]), cap);
+}
+function firstSentence(text: string): string {
+  const value = text.trim().replace(/\s+/g, " ");
+  return (value.match(/^[^.!?]{0,240}[.!?]/)?.[0] ?? value.slice(0, 200)).trim();
+}
+function lastSentence(text: string): string {
+  const value = text.trim().replace(/\s+/g, " ");
+  const parts = value.match(/[^.!?]{0,240}[.!?]/g);
+  return (parts?.at(-1) ?? value.slice(-200)).trim();
+}
+
+/** Proper-noun-ish worldbuilding concepts: Title Case runs of 2-5 words. */
+function extractConcepts(text: string, known: string[]): string[] {
+  const found = [...text.matchAll(/\b(?:[A-Z][a-z]{2,14})(?:\s+(?:of\s+|the\s+|and\s+)?[A-Z][a-z]{2,14}){1,4}\b/g)].map((match) => match[0].trim());
+  const knownLower = new Set(known.map((entry) => entry.toLowerCase()));
+  return uniq(found.filter((entry) => !knownLower.has(entry.toLowerCase()) && !/^(?:The|And|But|He|She|They|You|It|His|Her|Their)\b/.test(entry)), 24);
+}
+
+/** POV target derived from the frozen blueprint; violations are counted, never silently rewritten. */
+export function povProfile(pov: string): { label: string; forbidden: RegExp | null } {
+  const value = (pov || "").toLowerCase();
+  if (/second/.test(value)) return { label: "second person (you)", forbidden: /\b(?:he|she|him|her|his|hers)\b/gi };
+  if (/first/.test(value)) return { label: "first person (I/we)", forbidden: /\byou\b/gi };
+  return { label: pov || "third person", forbidden: /\byou\b/gi };
+}
+
+/** Static phrases the upstream contract repeats every chapter; these are what FM-05 surfaces verbatim. */
+export function motifPhrases(bp: SageBlueprint): string[] {
+  const raw = [
+    bp.protagonist.wound, bp.protagonist.want, bp.protagonist.need,
+    bp.deuteragonist.wound, bp.antagonist.wound, bp.theme, bp.dramaticQuestion,
+    bp.worldMechanism?.name, bp.beatMechanism?.name, bp.relationshipMechanism?.name,
+  ].filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 8);
+  return uniq(raw.map((entry) => entry.replace(/\s+/g, " ").trim()), 12);
+}
+
+export function extractChapterFacts(args: {
+  chapter: number; title: string; text: string; snapshot: StorySnapshot;
+}): ChapterFacts {
+  const { chapter, title, text, snapshot } = args;
+  const bp = snapshot.blueprint;
+  const placeNames = [
+    bp.primarySetting.name, ...bp.secondarySettings.map((setting) => setting.name),
+    ...snapshot.roll.world.map((place) => place.label),
+  ].filter(Boolean);
+  const castNames = snapshot.roll.cast.cast.map((member) => member.name).filter(Boolean);
+  const motifHits: Record<string, number> = {};
+  const lower = text.toLowerCase();
+  for (const phrase of motifPhrases(bp)) {
+    const needle = phrase.toLowerCase();
+    let count = 0, from = 0;
+    while (needle && from <= lower.length) {
+      const at = lower.indexOf(needle, from);
+      if (at < 0) break;
+      count++; from = at + needle.length;
+    }
+    if (count > 0) motifHits[phrase] = count;
+  }
+  const povRule = povProfile(bp.pov);
+  const povViolations = povRule.forbidden ? (text.match(povRule.forbidden)?.length ?? 0) : 0;
+  const residue: string[] = [];
+  for (const { id, re } of RESIDUE_PATTERNS) { re.lastIndex = 0; if (re.test(text)) residue.push(id); }
+  return {
+    chapter, title, words: (text.trim().match(/\S+/g) ?? []).length,
+    places: uniq(placeNames.filter((name) => lower.includes(name.toLowerCase())), 8),
+    clocks: matches(text, CLOCK_RE, 12),
+    dates: matches(text, DATE_RE, 8),
+    irreversible: matches(text, IRREVERSIBLE_RE, 8).map((line) => line.trim().slice(0, 180)),
+    currency: matches(text, CURRENCY_RE, 20),
+    measurements: matches(text, MEASURE_RE, 30),
+    concepts: extractConcepts(text, [...placeNames, ...castNames]),
+    motifHits, residue, povViolations,
+    dominantVerbs: matches(text, VERB_RE, 8).map((verb) => verb.toLowerCase()),
+    closingLine: lastSentence(text),
+    openingLine: firstSentence(text),
+    excerpt420: text.slice(0, 420).replace(/\s+/g, " "),
+  };
+}
+
+function capRecord(rec: Record<string, number>, cap: number): Record<string, number> {
+  const keys = Object.keys(rec);
+  if (keys.length <= cap) return rec;
+  // Keep highest-count entries: bounded memory at max scale (80 chapters).
+  const sorted = keys.sort((a, b) => rec[b] - rec[a]).slice(0, cap);
+  const out: Record<string, number> = {};
+  for (const k of sorted) out[k] = rec[k];
+  return out;
+}
+
+export function foldFacts(ledger: ContinuityLedger, facts: ChapterFacts): ContinuityLedger {
+  const motifTotals = { ...ledger.motifTotals };
+  for (const [phrase, count] of Object.entries(facts.motifHits)) motifTotals[phrase] = (motifTotals[phrase] ?? 0) + count;
+  const conceptFirstSeen = { ...ledger.conceptFirstSeen };
+  for (const concept of facts.concepts) if (conceptFirstSeen[concept] === undefined) conceptFirstSeen[concept] = facts.chapter;
+  const cappedMotifs = capRecord(motifTotals, 120);
+  const cappedConcepts = capRecord(conceptFirstSeen, 200);
+  return {
+    facts: [...ledger.facts, facts],
+    motifTotals: cappedMotifs, conceptFirstSeen: cappedConcepts,
+    placeHistory: [...ledger.placeHistory, ...facts.places].slice(-60),
+    irreversibleAll: [...ledger.irreversibleAll, ...facts.irreversible].slice(-40),
+    lastClock: facts.clocks.at(-1) ?? ledger.lastClock,
+    lastDate: facts.dates.at(-1) ?? ledger.lastDate,
+  };
+}
+
+/** Rebuilds the ledger from stored chapters after a reload/resume. Pure. */
+export function rebuildLedger(snapshot: StorySnapshot, chapters: { index: number; title: string; text: string }[]): ContinuityLedger {
+  return chapters.reduce<ContinuityLedger>(
+    (ledger, chapter) => foldFacts(ledger, extractChapterFacts({ chapter: chapter.index, title: chapter.title, text: chapter.text, snapshot })),
+    EMPTY_LEDGER,
+  );
+}
+
+// ── act ladder (FM-09 climax evasion, FM-03 stasis) ─────────────────────────
+export function actObligation(chapterIndex: number, total: number): { act: string; duty: string } {
+  const position = total <= 1 ? 1 : chapterIndex / (total - 1);
+  if (position < 0.12) return { act: "ACT I — setup", duty: "End on a concrete disturbance that cannot be undone by paperwork." };
+  if (position < 0.28) return { act: "ACT I — lock-in", duty: "The protagonist must commit to a course with a stated cost they cannot refund." };
+  if (position < 0.48) return { act: "ACT II-A — rising cost", duty: "The opposition must take a coercive action that removes an option permanently." };
+  if (position < 0.56) return { act: "MIDPOINT — reversal", duty: "Reverse the protagonist's understanding or status; something they relied on is gone for good." };
+  if (position < 0.78) return { act: "ACT II-B — escalation", duty: "The opposition wins a round on the page. A named person, place or asset is lost." };
+  if (position < 0.9) return { act: "ACT III — crisis", duty: "Force a choice between two things the protagonist has protected all book; one must be sacrificed." };
+  if (position < 0.97) return { act: "ACT III — climax", duty: "Stage the direct confrontation the book promised, in scene, with the antagonist present and acting. No hearing, memo, audit or petition may substitute for it." };
+  return { act: "ACT III — resolution", duty: "Show the changed state that the climax bought, and pay the dramatic question in dramatized action." };
+}
+
+export type CraftBudgets = { measurements: number; currency: number; newConcepts: number; motifCap: number };
+export const DEFAULT_BUDGETS: CraftBudgets = { measurements: 6, currency: 2, newConcepts: 2, motifCap: 2 };
+
+/** Builds the additive continuity block appended to a chapter request, honoring individual toggles. */
+export function buildContinuityBlock(args: {
+  snapshot: StorySnapshot;
+  chapterIndex: number;
+  ledger: ContinuityLedger;
+  budgets?: CraftBudgets;
+  toggles?: ContinuityToggles;
+}): string {
+  const { snapshot, chapterIndex, ledger } = args;
+  const budgets = args.budgets ?? DEFAULT_BUDGETS;
+  const toggles = args.toggles ?? DEFAULT_CONTINUITY_TOGGLES;
+  const bp = snapshot.blueprint;
+  const total = bp.chapters.length;
+  const previous = ledger.facts.at(-1);
+  const ladder = actObligation(chapterIndex, total);
+  const povRule = povProfile(bp.pov);
+  const recentPlaces = uniq(ledger.placeHistory.slice(-3), 3);
+  const overusedMotifs = Object.entries(ledger.motifTotals)
+    .filter(([, count]) => count >= budgets.motifCap)
+    .map(([phrase]) => phrase).slice(0, 8);
+  const liveConcepts = Object.keys(ledger.conceptFirstSeen).slice(-10);
+  const lines: string[] = [];
+
+  lines.push("CONTINUITY LEDGER — machine-extracted from the chapters already written. These are facts of the book, not suggestions.");
+  if (previous && toggles.enableFM02ContinueFrom) {
+    lines.push(`- Previous chapter written: ${previous.chapter}. "${previous.title}".`);
+    lines.push(`- The last sentence of the book so far is: "${previous.closingLine}"`);
+    lines.push("- THIS CHAPTER CONTINUES FROM THAT EXACT MOMENT. Do not restart the book, do not re-stage the call to adventure, do not write an alternative version of an earlier chapter, and do not re-introduce characters who are already on stage.");
+  }
+  if (ledger.irreversibleAll.length && toggles.enableFM16IrreversibleLedger) {
+    lines.push("- Irreversible events already on the page (they stay true; nothing here may be undone, resurrected, refunded or forgotten):");
+    for (const entry of ledger.irreversibleAll.slice(-8)) lines.push(`    · ${entry}`);
+  }
+  if ((ledger.lastClock || ledger.lastDate) && toggles.enableFM13ClockMonotonicity) {
+    lines.push(`- Story clock reached: ${[ledger.lastDate, ledger.lastClock].filter(Boolean).join(" ")}. This chapter must move the clock FORWARD by an interval appropriate to the travel and work it depicts, and must never occupy a time earlier than that.`);
+  }
+  if (recentPlaces.length && toggles.enableFM10TransitRules) {
+    lines.push(`- Locations already used in the last chapters: ${recentPlaces.join("; ")}. Do not return to any of them unless the return is itself the dramatic event, and never cut to a new location without one concrete line of transit (how long, by what means, at what cost).`);
+  }
+  if (liveConcepts.length && toggles.enableFM11ConceptBudget) {
+    lines.push(`- Worldbuilding concepts already introduced: ${liveConcepts.join("; ")}. Use them; do not re-explain them.`);
+  }
+  lines.push("");
+
+  if (toggles.enableFM09ActLadder) {
+    lines.push(`STRUCTURAL OBLIGATION — ${ladder.act} (chapter ${chapterIndex + 1} of ${total}).`);
+    lines.push(`- ${ladder.duty}`);
+  }
+  if (toggles.enableFM03AntiStasis) {
+    lines.push("- This chapter must change at least TWO of: physical location, who is present, what the protagonist knows, what the protagonist owns or controls, and the protagonist's legal or social standing. Changing none of them is a failed chapter.");
+    if (previous?.dominantVerbs.length) {
+      lines.push(`- The previous chapter's dominant activity was: ${previous.dominantVerbs.slice(0, 4).join(", ")}. This chapter may not repeat that activity as its spine.`);
+    }
+    lines.push("- An inspection, audit, measurement, filing, injunction, deadline or fee may appear only as texture. It may not be the chapter's central action, and it may not be the way the chapter's tension resolves.");
+    lines.push("");
+  }
+
+  lines.push("CRAFT BUDGETS FOR THIS CHAPTER (hard caps; exceeding them is a defect, not a flourish):");
+  if (toggles.enableFM14MeasurementBudget) {
+    lines.push(`- At most ${budgets.measurements} numeric measurements with units in the whole chapter. Concrete specificity means named objects, textures, procedures and consequences, not instrument readings.`);
+  }
+  if (toggles.enableFM15CurrencyBudget) {
+    lines.push(`- At most ${budgets.currency} explicit prices, fines, fees or ledger balances.`);
+  }
+  if (toggles.enableFM11ConceptBudget) {
+    lines.push(`- At most ${budgets.newConcepts} NEW named worldbuilding concepts. Dramatize them; do not let characters lecture each other about them.`);
+  }
+  if (overusedMotifs.length && toggles.enableFM05MotifCooldown) {
+    lines.push("- These exact phrases have already been stated on the page and are now BANNED as literal text. Their content must be shown through behaviour, choice and consequence instead:");
+    for (const phrase of overusedMotifs) lines.push(`    · "${phrase}"`);
+  }
+  if (toggles.enableFM08PovLock) {
+    lines.push(`- Point of view is locked to ${povRule.label}. Do not drift.`);
+    if (previous && previous.povViolations > 0) {
+      lines.push(`    · The previous chapter contained ${previous.povViolations} pronoun(s) outside that point of view. Do not repeat that error.`);
+    }
+  }
+  if (toggles.enableFM07ResidueStripping) {
+    lines.push("- Never emit bracketed metadata of any kind: no [Source 1], no [CHECKSUM], no [UNVERIFIED], no status tags, no scratchpad, no planning notes. Narrative prose only.");
+  }
+  lines.push("- Never quote the story bible back to the reader. Terms such as the dramatic question, the wound, the want and the need are private planning language; if a character says them aloud, the chapter is wrong.");
+  lines.push("");
+  lines.push("Write ONLY the chapter prose now.");
+  return lines.join("\n");
+}
+
+/** Deterministic chapter-level defect report used for logging and warnings. */
+export function auditChapterCraft(facts: ChapterFacts, budgets: CraftBudgets = DEFAULT_BUDGETS): string[] {
+  const defects: string[] = [];
+  if (facts.measurements.length > budgets.measurements) defects.push(`measurement budget exceeded (${facts.measurements.length}/${budgets.measurements})`);
+  if (facts.currency.length > budgets.currency) defects.push(`currency budget exceeded (${facts.currency.length}/${budgets.currency})`);
+  if (facts.residue.length) defects.push(`harness residue removed: ${facts.residue.join(", ")}`);
+  if (facts.povViolations > 0) defects.push(`${facts.povViolations} pronoun(s) outside the locked point of view`);
+  const repeated = Object.entries(facts.motifHits).filter(([, count]) => count > 1).map(([phrase]) => phrase);
+  if (repeated.length) defects.push(`bible phrase repeated verbatim in-chapter: ${repeated.slice(0, 3).join("; ")}`);
+  return defects;
+}
+
+/** FM-04: is the returned chapter truncated or far under its commissioned length? */
+export function truncationVerdict(text: string, targetWords: number): { truncated: boolean; reason: string; words: number } {
+  const words = (text.trim().match(/\S+/g) ?? []).length;
+  const trimmed = text.trim();
+  const unterminated = !!trimmed && !/[.!?"'”’)\]]$/.test(trimmed);
+  if (unterminated) return { truncated: true, reason: "final sentence is unterminated", words };
+  if (targetWords > 0 && words < Math.floor(targetWords * 0.6)) return { truncated: true, reason: `only ${words} words against a ${targetWords}-word commission`, words };
+  return { truncated: false, reason: "", words };
+}
+
+/** Continuation request for a truncated chapter. Additive; never rewrites what already landed. */
+export function buildContinuationPrompt(args: {
+  snapshot: StorySnapshot; chapterIndex: number; title: string; sofar: string; targetWords: number;
+}): string {
+  const words = (args.sofar.trim().match(/\S+/g) ?? []).length;
+  return [
+    "You are continuing ONE chapter of a work of FICTION that was cut off mid-delivery.",
+    "Output ONLY the continuation prose. Do not repeat any sentence that already exists. Do not restate the chapter heading. Do not summarise. Do not start a new chapter.",
+    "",
+    `CHAPTER: "${args.title}" (chapter ${args.chapterIndex + 1} of ${args.snapshot.blueprint.chapters.length}).`,
+    `Commissioned length ~${args.targetWords} words; ${words} words exist so far, so write approximately ${Math.max(200, args.targetWords - words)} more and bring the chapter to a clean, deliberate close.`,
+    `Point of view is locked to ${povProfile(args.snapshot.blueprint.pov).label}.`,
+    "No bracketed metadata, no planning notes, no instrument-reading padding.",
+    "",
+    "THE CHAPTER SO FAR (continue seamlessly from its final words):",
+    args.sofar.slice(-6000),
+    "",
+    "Continue the chapter now.",
+  ].join("\n");
+}

package/src/fiction/crash-protection.ts

@@ -0,0 +1,111 @@
+/**
+ * SAGA OS CRASH PROTECTION & PERSISTENT CHECKPOINT ENGINE
+ * ---------------------------------------------------------------------------
+ * Ensures state survival across browser tab crashes, disconnects, reloads,
+ * and uncaught exceptions.
+ *
+ * Checkpoint invariants:
+ *   - Clean chapter narrative stores (no harness preamble or meta-chatter).
+ *   - Entity state machine serialized to localStorage.
+ *   - Active status ("idle" | "running" | "paused" | "stopped").
+ *   - Seamless resumption from exact checkpoint without prompt corruption.
+ */
+
+import { stripHarnessResidue } from "./continuity";
+
+export type StoryEngineStatus = "idle" | "running" | "paused" | "stopped" | "error" | "complete";
+
+export interface StoryCheckpoint {
+  manuscriptId: string;
+  seed: number;
+  totalChapters: number;
+  completedChapters: number;
+  activeModel: string;
+  status: StoryEngineStatus;
+  timestamp: number;
+  chapters: Array<{
+    index: number;
+    title: string;
+    text: string;
+    wordCount: number;
+  }>;
+  cleanManuscript: string;
+  entityStateJson?: string;
+  ledgerJson?: string;
+}
+
+const CHECKPOINT_KEY = "saga.fiction.checkpoint.v2";
+const ENGINE_STATUS_KEY = "saga.fiction.runtime.status";
+
+export class StoryCrashProtector {
+  public static saveCheckpoint(checkpoint: StoryCheckpoint): void {
+    try {
+      // Clean narrative of any residue before serializing
+      const sanitizedManuscript = stripHarnessResidue(checkpoint.cleanManuscript).text;
+      const payload: StoryCheckpoint = {
+        ...checkpoint,
+        cleanManuscript: sanitizedManuscript,
+        timestamp: Date.now(),
+      };
+      try {
+        // Full checkpoint (manuscript + per-chapter array).
+        localStorage.setItem(CHECKPOINT_KEY, JSON.stringify(payload));
+      } catch (quotaErr) {
+        // Quota fallback at max scale: manuscript-only (chapters re-parseable on load).
+        try {
+          const slim = { ...payload, chapters: [] as StoryCheckpoint["chapters"] };
+          localStorage.setItem(CHECKPOINT_KEY, JSON.stringify(slim));
+          console.warn("[CrashProtector] Quota hit: saved manuscript-only checkpoint.", quotaErr);
+        } catch (e2) {
+          console.warn("[CrashProtector] Failed to persist checkpoint (quota exceeded):", e2);
+          return;
+        }
+      }
+      localStorage.setItem(ENGINE_STATUS_KEY, payload.status);
+      window.dispatchEvent(
+        new CustomEvent("saga:checkpoint-saved", { detail: { completed: payload.completedChapters, status: payload.status } })
+      );
+    } catch (e) {
+      console.warn("[CrashProtector] Failed to persist checkpoint:", e);
+    }
+  }
+
+  public static loadCheckpoint(): StoryCheckpoint | null {
+    try {
+      const raw = localStorage.getItem(CHECKPOINT_KEY);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw) as StoryCheckpoint;
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  public static updateStatus(status: StoryEngineStatus): void {
+    try {
+      localStorage.setItem(ENGINE_STATUS_KEY, status);
+      const cp = this.loadCheckpoint();
+      if (cp) {
+        cp.status = status;
+        localStorage.setItem(CHECKPOINT_KEY, JSON.stringify(cp));
+      }
+      window.dispatchEvent(new CustomEvent("saga:status-changed", { detail: { status } }));
+    } catch {}
+  }
+
+  public static getActiveStatus(): StoryEngineStatus {
+    try {
+      return (localStorage.getItem(ENGINE_STATUS_KEY) as StoryEngineStatus) || "idle";
+    } catch {
+      return "idle";
+    }
+  }
+
+  public static clearCheckpoint(): void {
+    try {
+      localStorage.removeItem(CHECKPOINT_KEY);
+      localStorage.setItem(ENGINE_STATUS_KEY, "idle");
+      window.dispatchEvent(new CustomEvent("saga:checkpoint-cleared"));
+    } catch {}
+  }
+}