2sagaco48 1.0.0

package/src/lib/manuscript-grade-v2.ts

@@ -0,0 +1,298 @@
+/**
+ * MANUSCRIPT GRADE v2 — weighted 100-point editorial rubric (NEW, additive).
+ * ---------------------------------------------------------------------------
+ * Independent of, and non-destructive to, the existing 1-10 x 12-category
+ * `gradeManuscript` (node_modules/src/lib/sage/judge.ts) used by
+ * the in-panel "Grade manuscript" button — that pipeline is untouched.
+ *
+ * This module implements the SEPARATE weighted rubric requested for the
+ * standalone grading report:
+ *   Theme & Conceptual Ambition       15%
+ *   Worldbuilding & Setting Depth     15%
+ *   Prose Style & Syntactic Craft     15%
+ *   Character Voice & Coherence       20%
+ *   Plot Architecture & Pacing        20%
+ *   Cleanliness & Narrative Logic     15%
+ *                                     ----
+ *                                     100%
+ *
+ * HONESTY CONTRACT
+ * - The composite score and letter-grade banding are DETERMINISTIC local
+ *   arithmetic (never the model's own claim of a total).
+ * - The 100 sub-scores and prose commentary are a MODEL JUDGMENT, labelled
+ *   as such everywhere in the UI — never presented as verified fact.
+ * - Rewrite suggestions are quote-grounded: every `originalQuote` is checked
+ *   as a verbatim (whitespace-normalized) substring of the manuscript that
+ *   was actually graded. A suggestion that fails this check is KEPT but
+ *   flagged `verified:false` — never silently dropped, never silently
+ *   trusted (zero-fabrication / quote-grounding discipline).
+ * - On a JSON parse failure the report is NOT fabricated: every category
+ *   gets a neutral 50 and `parseError` is populated so the UI can show the
+ *   raw judge text and flag the run as unreliable.
+ *
+ * NOTE ON THE "ADDITIONAL CRITERIA" SET
+ * No reference image was actually received in this session/tool context, so
+ * the additional-criteria list below is an original, professionally-derived
+ * diagnostic set (NOT reverse-engineered from an unseen attachment). This is
+ * disclosed in the UI to avoid an honesty violation.
+ */
+import { computeProseMetrics, type ProseMetrics } from '@/lib/sage/judge';
+
+export type GradeV2CategoryKey = "theme" | "worldbuilding" | "prose" | "character" | "plot" | "cleanliness";
+
+export interface GradeV2Category {
+  key: GradeV2CategoryKey;
+  label: string;
+  weightPct: number;
+  score: number;
+  weightedScore: number;
+  letterBand: string;
+  descriptor: string;
+  rationale: string;
+}
+
+export interface AdditionalCriterion {
+  key: string;
+  label: string;
+  score: number;
+  note: string;
+}
+
+export interface RewriteSuggestion {
+  id: string;
+  location: string;
+  category: GradeV2CategoryKey | "additional" | "general";
+  originalQuote: string;
+  rewrittenQuote: string;
+  rationale: string;
+  verified: boolean;
+}
+
+export interface ManuscriptGradeReportV2 {
+  generatedAt: number;
+  provider: string;
+  modelId: string;
+  wordCount: number;
+  metrics: ProseMetrics;
+  categories: GradeV2Category[];
+  weightedComposite: number;
+  compositeLetterBand: string;
+  additionalCriteria: AdditionalCriterion[];
+  additionalCriteriaSourceNote: string;
+  rewriteSuggestions: RewriteSuggestion[];
+  tableText: string;
+  rawJudgeText: string;
+  parseError: string | null;
+  truncated: boolean;
+  truncatedFromChars: number;
+}
+
+const GRADE_V2_CATEGORY_DEFS: { key: GradeV2CategoryKey; label: string; weightPct: number }[] = [
+  { key: "theme", label: "Theme & Conceptual Ambition", weightPct: 15 },
+  { key: "worldbuilding", label: "Worldbuilding & Setting Depth", weightPct: 15 },
+  { key: "prose", label: "Prose Style & Syntactic Craft", weightPct: 15 },
+  { key: "character", label: "Character Voice & Coherence", weightPct: 20 },
+  { key: "plot", label: "Plot Architecture & Pacing", weightPct: 20 },
+  { key: "cleanliness", label: "Cleanliness & Narrative Logic", weightPct: 15 },
+];
+
+export const ADDITIONAL_CRITERIA: { key: string; label: string }[] = [
+  { key: "dialogue", label: "Dialogue Authenticity & Subtext" },
+  { key: "imagery", label: "Sensory / Imagery Precision" },
+  { key: "showTell", label: "Show-vs-Tell Ratio" },
+  { key: "continuity", label: "Continuity & Canon Consistency" },
+  { key: "hooks", label: "Chapter-Hook / Cliffhanger Strength" },
+  { key: "exposition", label: "Exposition & Info-Dump Load (higher = leaner)" },
+  { key: "voiceDistinct", label: "Voice Distinctiveness Across POV / Cast" },
+  { key: "genreContract", label: "Genre-Contract Fulfillment (promises paid off)" },
+];
+
+export const ADDITIONAL_CRITERIA_SOURCE_NOTE =
+  "[UNVERIFIED PROVENANCE] No image attachment was received in this session. This diagnostic set is an original, " +
+  "professionally-grounded craft checklist — not derived from an unseen upload. Scores here are supplementary and " +
+  "excluded from the 100% weighted composite above.";
+
+export function letterBand(score: number): string {
+  const s = Math.max(0, Math.min(100, score));
+  if (s >= 97) return "A+";
+  if (s >= 93) return "A";
+  if (s >= 90) return "A-";
+  if (s >= 87) return "B+";
+  if (s >= 83) return "B";
+  if (s >= 80) return "B-";
+  if (s >= 77) return "C+";
+  if (s >= 73) return "C";
+  if (s >= 70) return "C-";
+  if (s >= 67) return "D+";
+  if (s >= 63) return "D";
+  if (s >= 60) return "D-";
+  return "F";
+}
+
+function normalize(s: string): string {
+  return s.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+const MAX_GRADE_CHARS = 200_000;
+
+export function buildGradeV2Prompt(manuscriptText: string): { prompt: string; truncated: boolean; truncatedFromChars: number } {
+  const truncated = manuscriptText.length > MAX_GRADE_CHARS;
+  const body = truncated ? manuscriptText.slice(0, MAX_GRADE_CHARS) : manuscriptText;
+  const catList = GRADE_V2_CATEGORY_DEFS.map((c) => `  - "${c.key}" = "${c.label}" (weight ${c.weightPct}%)`).join("\n");
+  const addList = ADDITIONAL_CRITERIA.map((c) => `  - "${c.key}" = "${c.label}"`).join("\n");
+  const prompt = [
+    "MANUSCRIPT WEIGHTED EDITORIAL RUBRIC",
+    "You are a panel of senior acquisitions editors grading a full manuscript exactly as a real developmental edit / options memo would.",
+    "Score EACH of these six weighted categories from 1 to 100 (use the full range; do not default to a narrow 70-85 band; be a real critic):",
+    catList,
+    "",
+    "Also score these additional diagnostic criteria from 1 to 100 (supplementary craft signals — NOT part of the weighted composite):",
+    addList,
+    "",
+    "Then propose 6 to 14 REWRITE SUGGESTIONS spanning multiple chapters, prioritizing the weakest categories. Each suggestion MUST quote a SHORT VERBATIM excerpt (5-40 words, copied EXACTLY character-for-character from the manuscript — never paraphrase the quote) as \"originalQuote\", plus an exact \"rewrittenQuote\" (the precise replacement text a copy-editor would substitute in) and a one-sentence \"rationale\".",
+    "Respond with STRICT JSON only, no markdown fences, no commentary outside the JSON, matching exactly this shape:",
+    "{\"categories\":{\"theme\":{\"score\":n,\"descriptor\":\"...\",\"rationale\":\"...\"},\"worldbuilding\":{\"score\":n,\"descriptor\":\"...\",\"rationale\":\"...\"},\"prose\":{\"score\":n,\"descriptor\":\"...\",\"rationale\":\"...\"},\"character\":{\"score\":n,\"descriptor\":\"...\",\"rationale\":\"...\"},\"plot\":{\"score\":n,\"descriptor\":\"...\",\"rationale\":\"...\"},\"cleanliness\":{\"score\":n,\"descriptor\":\"...\",\"rationale\":\"...\"}},\"additional\":{\"dialogue\":{\"score\":n,\"note\":\"...\"},\"imagery\":{\"score\":n,\"note\":\"...\"},\"showTell\":{\"score\":n,\"note\":\"...\"},\"continuity\":{\"score\":n,\"note\":\"...\"},\"hooks\":{\"score\":n,\"note\":\"...\"},\"exposition\":{\"score\":n,\"note\":\"...\"},\"voiceDistinct\":{\"score\":n,\"note\":\"...\"},\"genreContract\":{\"score\":n,\"note\":\"...\"}},\"rewriteSuggestions\":[{\"location\":\"Chapter N, ...\",\"category\":\"plot\",\"originalQuote\":\"...\",\"rewrittenQuote\":\"...\",\"rationale\":\"...\"}]}",
+    "",
+    truncated
+      ? `NOTE: the manuscript below was truncated to the first ${MAX_GRADE_CHARS.toLocaleString()} characters for this evaluation; grade only what you can read and do not invent content for the unseen remainder.`
+      : "",
+    "MANUSCRIPT:",
+    body,
+  ]
+    .filter((line) => line !== "")
+    .join("\n");
+  return { prompt, truncated, truncatedFromChars: truncated ? manuscriptText.length : 0 };
+}
+
+function extractJson(raw: string): unknown {
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const candidate = fenced ? fenced[1] : raw;
+  const start = candidate.indexOf("{");
+  const end = candidate.lastIndexOf("}");
+  if (start === -1 || end === -1 || end <= start) throw new Error("no JSON object found in grade v2 response");
+  return JSON.parse(candidate.slice(start, end + 1));
+}
+
+function clampScore(v: unknown): number {
+  const n = Number(v);
+  return Number.isFinite(n) ? Math.max(1, Math.min(100, Math.round(n))) : 50;
+}
+
+function formatGradeTable(categories: GradeV2Category[], composite: number, compositeBand: string): string {
+  const bar = "=".repeat(98);
+  const dash = "-".repeat(98);
+  const header = `${"EVALUATION CRITERIA (WEIGHT)".padEnd(38)}${"SCORE (1-100)".padStart(14)}${"WEIGHTED SCORE".padStart(18)}   QUALITATIVE GRADE`;
+  const rows = categories.map((c) => {
+    const left = `${c.label} (${c.weightPct}%)`.padEnd(38);
+    const score = `${c.score} / 100`.padStart(14);
+    const weighted = c.weightedScore.toFixed(2).padStart(18);
+    return `${left}${score}${weighted}   ${c.letterBand} (${c.descriptor})`;
+  });
+  const total = `${"WEIGHTED COMPOSITE SCORE (100%)".padEnd(38)}${"".padStart(14)}${`${composite.toFixed(2)} / 100`.padStart(18)}   GRADE: ${compositeBand}`;
+  return [bar, header, dash, ...rows, dash, total].join("\n");
+}
+
+function parseGradeV2Response(
+  raw: string,
+  manuscriptText: string,
+): {
+  categories: GradeV2Category[];
+  additionalCriteria: AdditionalCriterion[];
+  rewriteSuggestions: RewriteSuggestion[];
+  parseError: string | null;
+} {
+  try {
+    const parsed = extractJson(raw) as {
+      categories?: Record<string, { score?: unknown; descriptor?: unknown; rationale?: unknown }>;
+      additional?: Record<string, { score?: unknown; note?: unknown }>;
+      rewriteSuggestions?: unknown;
+    };
+    const categories: GradeV2Category[] = GRADE_V2_CATEGORY_DEFS.map((def) => {
+      const c = parsed.categories?.[def.key] ?? {};
+      const score = clampScore(c.score);
+      return {
+        key: def.key,
+        label: def.label,
+        weightPct: def.weightPct,
+        score,
+        weightedScore: Math.round(score * (def.weightPct / 100) * 100) / 100,
+        letterBand: letterBand(score),
+        descriptor: typeof c.descriptor === "string" && c.descriptor ? c.descriptor : "(no descriptor returned)",
+        rationale: typeof c.rationale === "string" ? c.rationale : "",
+      };
+    });
+    const additionalCriteria: AdditionalCriterion[] = ADDITIONAL_CRITERIA.map((def) => {
+      const a = parsed.additional?.[def.key];
+      return { key: def.key, label: def.label, score: clampScore(a?.score), note: typeof a?.note === "string" ? a.note : "" };
+    });
+    const msNorm = normalize(manuscriptText);
+    const rewriteSuggestions: RewriteSuggestion[] = Array.isArray(parsed.rewriteSuggestions)
+      ? (parsed.rewriteSuggestions as unknown[])
+          .filter((t): t is Record<string, unknown> => !!t && typeof t === "object")
+          .map((t, i) => {
+            const originalQuote = String(t.originalQuote ?? "");
+            const verified = originalQuote.trim().length > 0 && msNorm.includes(normalize(originalQuote));
+            const category = String(t.category ?? "general");
+            const validCategory = ["theme", "worldbuilding", "prose", "character", "plot", "cleanliness", "additional", "general"].includes(category)
+              ? (category as RewriteSuggestion["category"])
+              : "general";
+            return {
+              id: `rw-${i}-${Date.now()}`,
+              location: String(t.location ?? "unspecified"),
+              category: validCategory,
+              originalQuote,
+              rewrittenQuote: String(t.rewrittenQuote ?? ""),
+              rationale: String(t.rationale ?? ""),
+              verified,
+            };
+          })
+      : [];
+    return { categories, additionalCriteria, rewriteSuggestions, parseError: null };
+  } catch (e) {
+    const categories = GRADE_V2_CATEGORY_DEFS.map((def) => ({
+      key: def.key,
+      label: def.label,
+      weightPct: def.weightPct,
+      score: 50,
+      weightedScore: Math.round(50 * (def.weightPct / 100) * 100) / 100,
+      letterBand: letterBand(50),
+      descriptor: "(judge response unparsable)",
+      rationale: "",
+    }));
+    const additionalCriteria = ADDITIONAL_CRITERIA.map((def) => ({ key: def.key, label: def.label, score: 50, note: "" }));
+    return { categories, additionalCriteria, rewriteSuggestions: [], parseError: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+export type GenerateFn = (userMessage: string) => Promise<string>;
+
+export async function gradeManuscriptV2(
+  manuscriptText: string,
+  modelMeta: { provider: string; modelId: string },
+  generate: GenerateFn,
+): Promise<ManuscriptGradeReportV2> {
+  const metrics = computeProseMetrics(manuscriptText);
+  const { prompt, truncated, truncatedFromChars } = buildGradeV2Prompt(manuscriptText);
+  const raw = await generate(prompt);
+  const parsed = parseGradeV2Response(raw, manuscriptText);
+  const composite = Math.round(parsed.categories.reduce((a, c) => a + c.weightedScore, 0) * 100) / 100;
+  const compositeBand = letterBand(composite);
+  return {
+    generatedAt: Date.now(),
+    provider: modelMeta.provider,
+    modelId: modelMeta.modelId,
+    wordCount: metrics.wordCount,
+    metrics,
+    categories: parsed.categories,
+    weightedComposite: composite,
+    compositeLetterBand: compositeBand,
+    additionalCriteria: parsed.additionalCriteria,
+    additionalCriteriaSourceNote: ADDITIONAL_CRITERIA_SOURCE_NOTE,
+    rewriteSuggestions: parsed.rewriteSuggestions,
+    tableText: formatGradeTable(parsed.categories, composite, compositeBand),
+    rawJudgeText: raw,
+    parseError: parsed.parseError,
+    truncated,
+    truncatedFromChars,
+  };
+}

package/src/lib/memory-governor.ts

@@ -0,0 +1,173 @@
+/**
+ * Memory Governor — realistic, browser-aware memory pressure signal.
+ * Purpose: prevent OOM crashes during heavy SLOOP/N-Deep/cluster runs by
+ * exposing a single shared signal that callers can consult to:
+ *   - decide whether to start a new heavy step,
+ *   - how many parallel slots to use this wave,
+ *   - whether to skip optional steps (adversarial critique, OCR), and
+ *   - how to size working draft strings.
+ *
+ * The governor is intentionally additive — it never disables features, it
+ * only caps concurrency / sizes when measured pressure crosses a threshold.
+ * All existing code paths still work without it.
+ */
+export type PressureLevel = "ok" | "elevated" | "warn" | "critical";
+
+export interface MemoryReport {
+  /** Used JS heap, MB; 0 if unavailable. */
+  usedMB: number;
+  /** Raw browser heap ceiling, MB. */
+  limitMB: number;
+  /** Effective safe working limit for THIS app, MB. */
+  softLimitMB: number;
+  /** Used / raw limit, 0..1. */
+  pctHeap: number;
+  /** navigator.deviceMemory (GB) when available; null otherwise. */
+  deviceGB: number | null;
+  /** Approximate app-state memory, MB (caller-provided, optional). */
+  approxStateMB: number;
+  /** Composite pressure 0..1 incorporating heap + state + device. */
+  pressure: number;
+  /** Categorical band derived from the composite pressure. */
+  level: PressureLevel;
+  /** Realistic free MB budget we still trust to allocate. */
+  freeBudgetMB: number;
+  /** True when heap telemetry was actually available (Chrome/Edge). */
+  heapAvailable: boolean;
+}
+
+const SAFETY_MARGIN_MB = 80; // leave headroom for GC, fetches, snapshot
+const STATE_TO_HEAP_SCALE = 2.4; // app-state objects pull in retained closures
+const DEFAULT_DEVICE_LIMIT_MB = 1024; // fallback when nothing is exposed
+
+// Synthetic allocation tracker
+const allocations = new Map<string, number>();
+
+export function recordAllocation(label: string, bytes: number): void {
+  if (!Number.isFinite(bytes) || bytes <= 0) {
+    allocations.delete(label);
+  } else {
+    allocations.set(label, Math.round(bytes));
+  }
+}
+
+export function clearAllocation(label: string): void {
+  allocations.delete(label);
+}
+
+export function clearAllocationsByPrefix(prefix: string): void {
+  for (const key of Array.from(allocations.keys())) {
+    if (key.startsWith(prefix)) allocations.delete(key);
+  }
+}
+
+function getSyntheticMB(): number {
+  let total = 0;
+  for (const v of allocations.values()) total += v;
+  return Math.round(total / 1048576);
+}
+
+export async function yieldForGc(ms = 0): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+export async function settleHeap(ms = 25): Promise<void> {
+  await yieldForGc(0);
+  await yieldForGc(ms);
+}
+
+export function readMemoryReport(approxStateMB = 0): MemoryReport {
+  const deviceGB =
+    typeof (navigator as any).deviceMemory === "number"
+      ? ((navigator as any).deviceMemory as number)
+      : null;
+
+  let usedMB = 0;
+  let limitMB = 0;
+  let heapAvailable = false;
+  try {
+    const mem = (performance as any).memory;
+    if (mem) {
+      heapAvailable = true;
+      usedMB = Math.round(mem.usedJSHeapSize / 1048576);
+      limitMB = Math.round(mem.jsHeapSizeLimit / 1048576);
+    }
+  } catch {
+    /* ignore */
+  }
+
+  // Heuristic limit when JS heap telemetry is unavailable (Firefox/Safari).
+  if (limitMB <= 0) {
+    if (deviceGB && deviceGB > 0) limitMB = Math.min(2048, deviceGB * 256);
+    else limitMB = DEFAULT_DEVICE_LIMIT_MB;
+  }
+
+  // Effective safe working limit.
+  const softLimitMB = Math.max(
+    256,
+    Math.min(
+      2048,
+      Math.round(limitMB * 0.4),
+      deviceGB ? Math.round(deviceGB * 1024 * 0.35) : 1024,
+    ),
+  );
+
+  const synthMB = getSyntheticMB();
+  const effectiveUsedMB = Math.max(usedMB, synthMB);
+
+  const pctHeap = limitMB > 0 ? Math.min(1, effectiveUsedMB / limitMB) : 0;
+  const effectiveHeapPressure = softLimitMB > 0 ? Math.min(1, effectiveUsedMB / softLimitMB) : pctHeap;
+  const statePressure = softLimitMB > 0 ? Math.min(1, (approxStateMB * STATE_TO_HEAP_SCALE) / softLimitMB) : 0;
+  // Composite — take the worst signal and round to 2dp.
+  const pressure = Math.min(1, Math.max(effectiveHeapPressure, statePressure));
+  const level: PressureLevel =
+    pressure >= 0.9 ? "critical" : pressure >= 0.75 ? "warn" : pressure >= 0.55 ? "elevated" : "ok";
+
+  const freeBudgetMB = Math.max(0, Math.round(softLimitMB - effectiveUsedMB - SAFETY_MARGIN_MB));
+  return { usedMB: effectiveUsedMB, limitMB, softLimitMB, pctHeap, deviceGB, approxStateMB, pressure, level, freeBudgetMB, heapAvailable };
+}
+
+/**
+ * Reusable safe-cap helpers used by SLOOP / N-Deep / cluster waves.
+ * Design: these are now PERMISSIVE. Because each transient buffer is flattened
+ * and freed between iterations (streaming consolidation + settleHeap), the
+ * marginal heap cost of an extra SLOOP page / N-Deep pass / cluster lane is
+ * small and bounded.
+ */
+export function safeClusterWidth(requested: number, report = readMemoryReport()): number {
+  if (report.level === "critical") return Math.min(requested, 2);
+  if (report.level === "warn") return Math.min(requested, 3);
+  if (report.level === "elevated") return Math.min(requested, 4);
+  // Keep all hypotheses, but run large clusters in safe waves to avoid the
+  // scraper/proxy fan-out that caused browser OOMs.
+  return Math.min(requested, 4);
+}
+export function safeSloopPages(requested: number, report = readMemoryReport()): number {
+  if (report.level === "critical") return Math.min(requested, 6);
+  return requested;
+}
+
+export function safeNDeepPasses(requested: number, _sourceChars = 0, report = readMemoryReport()): number {
+  let cap = requested;
+  if (report.level === "critical") cap = Math.min(cap, 4);
+  if (report.freeBudgetMB < 64) cap = Math.min(cap, 2);
+  return Math.max(1, cap);
+}
+
+export function safeDraftCharCap(report = readMemoryReport()): number {
+  const bytesPerChar = 2;
+  const buffersInFlight = 3;
+  const budgetBytes = Math.max(1, report.freeBudgetMB) * 1024 * 1024;
+  const charBudget = Math.floor(budgetBytes / (bytesPerChar * buffersInFlight));
+  return Math.max(24_000, Math.min(90_000, charBudget));
+}
+
+export function wouldExceedBudget(extraMB: number, report = readMemoryReport()): boolean {
+  return extraMB > report.freeBudgetMB;
+}
+
+export function shouldSkipAdversarial(draftChars: number, report = readMemoryReport()): boolean {
+  if (report.level === "critical") return true;
+  if (report.level === "warn" && draftChars > 20_000) return true;
+  return false;
+}