2sagaco48 1.0.0

package/src/lib/research-os.ts

@@ -0,0 +1,306 @@
+/**
+ * ResearchOS v6 — Academic Research & NIH Grant Engine
+ *
+ * Provides:
+ * 1. Claim type taxonomy (OBS/DERIV/ASSUMP/HYP/THEORY/METHOD/RESULT/INTERP/LIMIT/REC/NORM)
+ * 2. NIH mechanism metadata (R01/R03/R15/R21 with page limits, budgets, review factors)
+ * 3. Study-design modules with reporting-standard mappings
+ * 4. Reviewer-vulnerability heuristic scoring
+ * 5. Reporting-standard selector (PRISMA/CONSORT/STROBE/COREQ/APA JARS)
+ * 6. Research gap taxonomy
+ * 7. Manuscript readiness score
+ *
+ * All scoring functions are heuristic engineering estimates, not official NIH formulas.
+ */
+
+// ─── Claim types ────────────────────────────────────────────────────
+export type ClaimType =
+  | "OBS"    // observed fact / literature claim
+  | "DERIV"  // statistical / mathematical derivation
+  | "ASSUMP" // explicit assumption
+  | "HYP"    // hypothesis
+  | "THEORY" // theoretical proposition
+  | "METHOD" // methodological choice
+  | "RESULT" // empirical finding
+  | "INTERP" // interpretation of results
+  | "LIMIT"  // limitation
+  | "REC"    // recommendation
+  | "NORM";  // normative / philosophical claim
+
+export const CLAIM_TYPE_LABELS: Record<ClaimType, string> = {
+  OBS: "Observed fact / literature claim",
+  DERIV: "Statistical / mathematical derivation",
+  ASSUMP: "Explicit assumption",
+  HYP: "Hypothesis",
+  THEORY: "Theoretical proposition",
+  METHOD: "Methodological choice",
+  RESULT: "Empirical finding",
+  INTERP: "Interpretation of results",
+  LIMIT: "Limitation",
+  REC: "Recommendation",
+  NORM: "Normative / philosophical claim",
+};
+
+// ─── NIH Mechanisms ─────────────────────────────────────────────────
+export interface NIHMechanism {
+  code: string;
+  name: string;
+  researchStrategyPages: number;
+  budgetAnchor: string;
+  duration: string;
+  reviewFactors: string[];
+  bestFor: string;
+  fatalFlaws: string[];
+}
+
+export const NIH_MECHANISMS: NIHMechanism[] = [
+  {
+    code: "R01",
+    name: "Research Project Grant",
+    researchStrategyPages: 12,
+    budgetAnchor: "Generally not capped; must reflect actual project needs",
+    duration: "1-5 budget periods",
+    reviewFactors: [
+      "Factor 1: Importance of the Research (Significance + Innovation, scored 1-9)",
+      "Factor 2: Rigor and Feasibility (Approach, scored 1-9)",
+      "Factor 3: Expertise and Resources (Investigator + Environment, sufficient/gaps)",
+    ],
+    bestFor: "Full independent project with strong premise and sustained impact",
+    fatalFlaws: [
+      "No central hypothesis",
+      "No rigorous prior-research assessment",
+      "No power/precision/sample justification",
+      "No alternatives for risky steps",
+      "Aims are dependent dominoes (if Aim 1 fails, whole project collapses)",
+      "Team expertise gap unpatched",
+    ],
+  },
+  {
+    code: "R03",
+    name: "Small Research Grant",
+    researchStrategyPages: 6,
+    budgetAnchor: "Up to $50,000 direct costs/year, up to 2 years, nonrenewable",
+    duration: "Up to 2 years",
+    reviewFactors: [
+      "Factor 1: Importance (smaller scope, tight focus)",
+      "Factor 2: Rigor and Feasibility",
+      "Factor 3: Expertise and Resources",
+    ],
+    bestFor: "Small, self-contained project: pilot/feasibility, secondary analysis, methods development",
+    fatalFlaws: [
+      "Looks like a compressed R01 instead of a self-contained project",
+      "Scope exceeds 2-year / $50K/yr reality",
+      "No clear finish line or next-step logic",
+    ],
+  },
+  {
+    code: "R15",
+    name: "Research Enhancement Award (AREA/REAP)",
+    researchStrategyPages: 12,
+    budgetAnchor: "Modular/R&R thresholds; project period limited to 3 years",
+    duration: "Up to 3 years",
+    reviewFactors: [
+      "Factor 1: Importance of the Research",
+      "Factor 2: Rigor and Feasibility",
+      "Factor 3: Expertise, Resources, AND student involvement + institutional strengthening",
+    ],
+    bestFor: "Meritorious research at eligible institutions; student exposure to research",
+    fatalFlaws: [
+      "Student involvement is decorative rather than operational",
+      "PI eligibility conflicts not addressed",
+      "Institutional eligibility letter missing or weak",
+      "Too ambitious for a 3-year R15",
+      "Student training plan not connected to scientific milestones",
+    ],
+  },
+  {
+    code: "R21",
+    name: "Exploratory / Developmental Grant",
+    researchStrategyPages: 6,
+    budgetAnchor: "Up to $275,000 total direct costs over 2 years; no more than $200,000 in any one year",
+    duration: "Up to 2 years, nonrenewable",
+    reviewFactors: [
+      "Factor 1: Importance and Innovation (must justify uncertainty)",
+      "Factor 2: Rigor and Feasibility",
+      "Factor 3: Expertise and Resources",
+    ],
+    bestFor: "High-risk/high-reward, feasibility, novel direction",
+    fatalFlaws: [
+      "Uncertainty is not scientifically justified (application is simply underdeveloped)",
+      "No clear stopping rules",
+      "No logic connecting R21 output to R01-scale work",
+    ],
+  },
+];
+
+// ─── Study designs + reporting standard mapping ─────────────────────
+export interface StudyDesign {
+  id: string;
+  name: string;
+  category: "quantitative" | "qualitative" | "mixed" | "review" | "theoretical";
+  reportingStandards: string[];
+  reviewerAttacks: string[];
+}
+
+export const STUDY_DESIGNS: StudyDesign[] = [
+  { id: "rct", name: "Randomized Controlled Trial", category: "quantitative",
+    reportingStandards: ["CONSORT 2025"],
+    reviewerAttacks: ["Internal validity is weak", "Manipulation does not isolate mechanism"] },
+  { id: "observational", name: "Observational (Cohort/Case-Control/Cross-Sectional)", category: "quantitative",
+    reportingStandards: ["STROBE"],
+    reviewerAttacks: ["Causal language exceeds design", "Confounders not adequately controlled"] },
+  { id: "quasi-experimental", name: "Quasi-Experimental (DID/RD/ITS/IV)", category: "quantitative",
+    reportingStandards: ["APA JARS-Quant"],
+    reviewerAttacks: ["Identification assumptions are not credible"] },
+  { id: "survey", name: "Survey / Cross-Sectional", category: "quantitative",
+    reportingStandards: ["APA JARS-Quant", "STROBE"],
+    reviewerAttacks: ["Common method variance", "Self-selection bias"] },
+  { id: "sem", name: "Structural Equation Modeling", category: "quantitative",
+    reportingStandards: ["APA JARS-Quant"],
+    reviewerAttacks: ["Model fit acceptable but theory underidentified", "Measurement invariance not tested"] },
+  { id: "grounded-theory", name: "Grounded Theory", category: "qualitative",
+    reportingStandards: ["COREQ", "SRQR"],
+    reviewerAttacks: ["This is thematic analysis mislabeled as grounded theory"] },
+  { id: "thematic-analysis", name: "Reflexive Thematic Analysis", category: "qualitative",
+    reportingStandards: ["COREQ", "SRQR", "APA JARS-Qual"],
+    reviewerAttacks: ["Themes are topic summaries, not analytic themes"] },
+  { id: "phenomenology", name: "Phenomenology / IPA", category: "qualitative",
+    reportingStandards: ["COREQ"],
+    reviewerAttacks: ["Analysis is descriptive but not phenomenological"] },
+  { id: "ethnography", name: "Ethnography", category: "qualitative",
+    reportingStandards: ["COREQ"],
+    reviewerAttacks: ["Field engagement is too thin"] },
+  { id: "case-study", name: "Case Study", category: "qualitative",
+    reportingStandards: ["COREQ"],
+    reviewerAttacks: ["Case is not bounded or theoretically justified"] },
+  { id: "systematic-review", name: "Systematic Review / Meta-Analysis", category: "review",
+    reportingStandards: ["PRISMA 2020"],
+    reviewerAttacks: ["Search strategy is not reproducible", "Risk of bias not assessed"] },
+  { id: "mixed-convergent", name: "Mixed Methods (Convergent Parallel)", category: "mixed",
+    reportingStandards: ["APA JARS-Mixed", "MMAT"],
+    reviewerAttacks: ["Integration is decorative not substantive"] },
+  { id: "mixed-explanatory", name: "Mixed Methods (Explanatory Sequential)", category: "mixed",
+    reportingStandards: ["APA JARS-Mixed"],
+    reviewerAttacks: ["Qual strand does not explain the quant finding"] },
+  { id: "philosophy", name: "Philosophy / Theory Paper", category: "theoretical",
+    reportingStandards: [],
+    reviewerAttacks: ["Argument contains a hidden premise", "Counterexample not addressed"] },
+];
+
+// ─── Reviewer Vulnerability Heuristic ───────────────────────────────
+export interface VulnerabilityInput {
+  importanceGap: number;      // 0-1
+  methodsGap: number;         // 0-1
+  measurementGap: number;     // 0-1
+  theoryGap: number;          // 0-1
+  powerSampleGap: number;     // 0-1
+  reproducibilityGap: number; // 0-1
+  writingClarityGap: number;  // 0-1
+}
+
+export function reviewerVulnerability(input: VulnerabilityInput): { score: number; level: string } {
+  const score =
+    0.25 * input.importanceGap +
+    0.20 * input.methodsGap +
+    0.15 * input.measurementGap +
+    0.15 * input.theoryGap +
+    0.10 * input.powerSampleGap +
+    0.10 * input.reproducibilityGap +
+    0.05 * input.writingClarityGap;
+  const level =
+    score <= 0.20 ? "Low vulnerability" :
+    score <= 0.40 ? "Moderate vulnerability" :
+    score <= 0.60 ? "Serious revision risk" :
+    "Likely rejection / poor grant score";
+  return { score, level };
+}
+
+// ─── NIH Impact Heuristic ───────────────────────────────────────────
+export function nihImpactHeuristic(
+  importance: number,          // 1 exceptional - 9 poor
+  rigorFeasibility: number,    // 1 exceptional - 9 poor
+  resourcesGate: 0 | 1 | 2,   // 0 sufficient, 1 minor gaps, 2 major gaps
+  humanSubjectsRisk = 0,
+  biohazardRisk = 0,
+  budgetConcern = 0,
+): { score: number; label: string } {
+  const resourcePenalty = [0, 0.5, 1.5][resourcesGate];
+  const compliancePenalty = humanSubjectsRisk + biohazardRisk + budgetConcern;
+  const raw = 0.45 * importance + 0.45 * rigorFeasibility + resourcePenalty + compliancePenalty;
+  const score = Math.min(9, Math.max(1, raw));
+  const label =
+    score <= 2 ? "Exceptional" :
+    score <= 3.5 ? "Outstanding" :
+    score <= 5 ? "Good" :
+    score <= 7 ? "Fair" :
+    "Poor";
+  return { score, label };
+}
+
+// ─── Manuscript Readiness Score ──────────────────────────────────────
+export function manuscriptReadiness(i: {
+  contributionStrength: number;  // 0-1
+  methodsRigor: number;         // 0-1
+  theoryFit: number;            // 0-1
+  reportingCompliance: number;  // 0-1
+  reproducibility: number;      // 0-1
+  writingClarity: number;       // 0-1
+  reviewerResilience: number;   // 0-1
+}): { score: number; label: string } {
+  const score =
+    0.20 * i.contributionStrength +
+    0.20 * i.methodsRigor +
+    0.15 * i.theoryFit +
+    0.15 * i.reportingCompliance +
+    0.10 * i.reproducibility +
+    0.10 * i.writingClarity +
+    0.10 * i.reviewerResilience;
+  const label =
+    score >= 0.80 ? "Ready to submit" :
+    score >= 0.60 ? "Needs minor revision" :
+    score >= 0.40 ? "Needs major revision" :
+    "Not ready";
+  return { score, label };
+}
+
+// ─── Research Gap Taxonomy ──────────────────────────────────────────
+export const RESEARCH_GAPS = [
+  { id: "empirical", name: "Empirical Gap", desc: "No data on a population, setting, period, or outcome" },
+  { id: "theoretical", name: "Theoretical Gap", desc: "Existing theories cannot explain a pattern" },
+  { id: "measurement", name: "Measurement Gap", desc: "Construct is poorly operationalized" },
+  { id: "method", name: "Method Gap", desc: "Existing designs cannot support the needed inference" },
+  { id: "mechanism", name: "Mechanism Gap", desc: "Relationship observed but process unknown" },
+  { id: "translational", name: "Translational Gap", desc: "Discovery exists but is not implemented" },
+  { id: "equity", name: "Equity Gap", desc: "Populations or contexts excluded from evidence base" },
+  { id: "replication", name: "Replication Gap", desc: "Claims depend on single, fragile, or underpowered studies" },
+  { id: "synthesis", name: "Synthesis Gap", desc: "Literature exists but has not been integrated" },
+];
+
+// ─── Reporting Standard Selector (deterministic) ────────────────────
+export function selectReportingStandards(design: {
+  reviewType?: string;
+  intervention?: string;
+  designType?: string;
+  qualitative?: boolean;
+  mixedMethods?: boolean;
+  field?: string;
+}): string[] {
+  const standards: string[] = [];
+  if (design.reviewType === "systematic_review" || design.reviewType === "meta_analysis") standards.push("PRISMA 2020");
+  if (design.intervention === "randomized_trial") standards.push("CONSORT 2025");
+  if (["cohort", "case_control", "cross_sectional"].includes(design.designType ?? "")) standards.push("STROBE");
+  if (design.qualitative) standards.push("COREQ", "SRQR");
+  if (design.mixedMethods) standards.push("APA JARS-Mixed", "MMAT");
+  if (["psychology", "behavioral_science", "social_science", "education"].includes(design.field ?? "")) standards.push("APA JARS");
+  return [...new Set(standards)];
+}
+
+// ─── Reviewer Persona Definitions ───────────────────────────────────
+export const REVIEWER_PERSONAS = [
+  { id: "theory", name: "Theory Reviewer", focus: "Conceptual contribution, construct definitions, theory-hypothesis link" },
+  { id: "methods", name: "Methods Reviewer", focus: "Design-inference match, sampling, models, robustness" },
+  { id: "domain", name: "Field/Domain Reviewer", focus: "Literature currency, citation fairness, practical contribution" },
+  { id: "statistician", name: "Skeptical Statistician", focus: "Power, assumptions, multiplicity, null interpretation" },
+  { id: "qualitative", name: "Qualitative Rigor Reviewer", focus: "Epistemology, reflexivity, data grounding, transferability" },
+  { id: "ethics", name: "Ethics/Open Science Reviewer", focus: "IRB/consent, DMS plan, preregistration, COI" },
+];

package/src/lib/resource-estimator.ts

@@ -0,0 +1,114 @@
+import { TIERS } from "./gbse/tiers";
+
+export type DriverId =
+  | "frontier"
+  | "gemma4-31b"
+  | "qwen3.6"
+  | "gemma4-e4b"
+  | "apple-ondevice"
+  | "bonsai-8b";
+
+export interface EstimateInput {
+  query: string;
+  tier: number;
+  driver: DriverId;
+  anchorMode: "required" | "preferred" | "off";
+  webAccess: "on" | "trusted" | "off";
+  verifierAlpha: number;
+  councilWidth: number;
+  workerDepth: number;
+}
+
+export interface Estimate {
+  tier: number;
+  time_s: number;
+  tokens_in: number;
+  tokens_out: number;
+  tools: number;
+  paths: number;
+  states: number;
+  ram_bytes: number;
+  dense_states_avoided: number;
+  dense_bytes_avoided: number;
+  coverage: number;
+}
+
+export interface Actuals {
+  actual_in: number;
+  actual_out: number;
+  actual_tools: number;
+  actual_paths: number;
+  actual_states: number;
+  actual_ram: number;
+  entropy: number;
+  contradictions: number;
+  token_saved: number;
+}
+
+const DRIVER_MULTIPLIER: Record<DriverId, { time: number; tokens: number; coverage: number }> = {
+  frontier: { time: 0.8, tokens: 1.0, coverage: 1.02 },
+  "gemma4-31b": { time: 1.0, tokens: 1.0, coverage: 1.0 },
+  "qwen3.6": { time: 1.25, tokens: 1.12, coverage: 1.0 },
+  "gemma4-e4b": { time: 1.8, tokens: 0.78, coverage: 0.88 },
+  "apple-ondevice": { time: 2.0, tokens: 0.65, coverage: 0.82 },
+  "bonsai-8b": { time: 2.3, tokens: 0.55, coverage: 0.78 },
+};
+
+export function estimateResources(input: EstimateInput): Estimate {
+  const tier = Math.max(0, Math.min(5, input.tier));
+  const spec = TIERS[tier];
+  const words = input.query.trim().split(/\s+/).filter(Boolean).length;
+  const complexity = Math.min(2.0, 0.65 + words / 80 + input.councilWidth / 40 + input.workerDepth / 60);
+  const driver = DRIVER_MULTIPLIER[input.driver];
+  const anchorDiscount = input.anchorMode === "required" ? 0.72 : input.anchorMode === "preferred" ? 0.86 : 1.0;
+  const webMultiplier = input.webAccess === "off" ? 0.35 : input.webAccess === "trusted" ? 0.75 : 1.0;
+  const verifierBoost = 1 + Math.max(0, input.verifierAlpha - 0.2) * 0.9;
+
+  const tokens = spec.maxTokens * 0.32 * complexity * driver.tokens * anchorDiscount * verifierBoost;
+  const tokens_in = Math.round(tokens * 0.68);
+  const tokens_out = Math.round(tokens * 0.32);
+  const tools = Math.max(0, Math.round(spec.evidenceProbes * complexity * webMultiplier + (input.anchorMode === "off" ? 0 : 6)));
+  const paths = Math.max(1, Math.round(input.councilWidth * Math.max(1, input.workerDepth / 3)));
+  const states = Math.max(1, Math.round(paths * (tier + 1) * 1.7));
+  const sparseEdges = Math.max(1, tools + paths * 3 + states);
+  const ram_bytes = sparseEdges * 64;
+  const dense_states_avoided = Math.pow(2, Math.min(20, Math.max(1, states)));
+  const dense_bytes_avoided = dense_states_avoided * 8;
+  const coverage = Math.max(
+    0.15,
+    Math.min(0.98, spec.forecastCoverage * driver.coverage * (input.anchorMode === "required" ? 0.96 : 1) * (input.webAccess === "off" ? 0.78 : 1)),
+  );
+  const time_s = Math.round(spec.maxSeconds * 0.45 * complexity * driver.time * webMultiplier * verifierBoost);
+
+  return { tier, time_s, tokens_in, tokens_out, tools, paths, states, ram_bytes, dense_states_avoided, dense_bytes_avoided, coverage };
+}
+
+/** Honest empty actuals when no run has occurred. No simulation — zeros mean "not measured yet". */
+export function zeroActuals(): Actuals {
+  return {
+    actual_in: 0, actual_out: 0, actual_tools: 0, actual_paths: 0,
+    actual_states: 0, actual_ram: 0, entropy: 0, contradictions: 0, token_saved: 0,
+  };
+}
+
+export function aegisPanel(est: Estimate, actual: Actuals, elapsed: number): string {
+  const d = (a: number, e: number) => `${a >= e ? "+" : ""}${a - e}`;
+  const densePower = Math.floor(Math.log2(Math.max(1, est.dense_states_avoided)));
+  return [
+    "╔════════════════════════════════════════════════════════════════════╗",
+    `║ AEGIS-PHI  ::  T${est.tier} ${TIERS[est.tier].name.padEnd(14)}  ::  live  ${elapsed.toFixed(1).padStart(6)}s      ║`,
+    "╠════════════════════════════════════════════════════════════════════╣",
+    `║ TIME       est ${String(est.time_s).padStart(7)}s act ${elapsed.toFixed(1).padStart(8)}s Δ ${(elapsed - est.time_s).toFixed(0).padStart(7)} ║`,
+    `║ TOK IN     est ${String(est.tokens_in).padStart(8)} act ${String(actual.actual_in).padStart(8)} Δ ${d(actual.actual_in, est.tokens_in).padStart(7)} ║`,
+    `║ TOK OUT    est ${String(est.tokens_out).padStart(8)} act ${String(actual.actual_out).padStart(8)} Δ ${d(actual.actual_out, est.tokens_out).padStart(7)} ║`,
+    `║ TOOLS      est ${String(est.tools).padStart(8)} act ${String(actual.actual_tools).padStart(8)} Δ ${d(actual.actual_tools, est.tools).padStart(7)} ║`,
+    `║ PATHS      est ${String(est.paths).padStart(8)} act ${String(actual.actual_paths).padStart(8)} Δ ${d(actual.actual_paths, est.paths).padStart(7)} ║`,
+    `║ STATES     est ${String(est.states).padStart(8)} act ${String(actual.actual_states).padStart(8)} Δ ${d(actual.actual_states, est.states).padStart(7)} ║`,
+    `║ RAM sparse est ${String(est.ram_bytes).padStart(8)}B act ${String(actual.actual_ram).padStart(8)}B             ║`,
+    `║ DENSE AVOIDED  2^${densePower} mask = ${(est.dense_bytes_avoided / 1024).toFixed(1).padStart(7)} KB                 ║`,
+    `║ TOK SAVED  via collapse vs raw fan-in: ${String(actual.token_saved).padStart(8)}              ║`,
+    `║ PSI-ENTROPY  ${actual.entropy.toFixed(3)}   CONTRADICTIONS  ${String(actual.contradictions).padStart(3)}                 ║`,
+    `║ COVERAGE   forecast ${(est.coverage * 100).toFixed(1).padStart(5)}%                              ║`,
+    "╚════════════════════════════════════════════════════════════════════╝",
+  ].join("\n");
+}

package/src/lib/rpm-governor.ts

@@ -0,0 +1,93 @@
+/**
+ * RPM Governor — serializes and throttles LLM calls so we never exceed the
+ * free-tier requests-per-minute ceiling (typically 5–15 RPM on this key).
+ *
+ * Strategy:
+ *  - A single global queue spaces calls by (60000 / rpm) ms minimum interval.
+ *  - Callers can batch multiple logical sub-prompts into ONE request via
+ *    `batchPrompts()` so the N-Deep engine consumes one RPM slot, not N.
+ */
+
+let lastCallTs = 0;
+let chain: Promise<void> = Promise.resolve();
+
+export interface ThrottleOpts {
+  rpm?: number;
+  onWait?: (ms: number) => void;
+}
+
+/** Run `fn` on a serialized chain, spacing calls to respect the RPM ceiling.
+ *  FIXED: chain cannot deadlock — every link resolves to void regardless of fn outcome. */
+export function throttle<T>(fn: () => Promise<T>, opts?: ThrottleOpts): Promise<T> {
+  const rpm = Math.max(1, opts?.rpm ?? 10);
+  const minInterval = Math.ceil(60_000 / rpm);
+  return new Promise<T>((resolve, reject) => {
+    chain = chain.then(async () => {
+      const now = Date.now();
+      const wait = Math.max(0, lastCallTs + minInterval - now);
+      if (wait > 0) {
+        opts?.onWait?.(wait);
+        await new Promise((r) => setTimeout(r, wait));
+      }
+      lastCallTs = Date.now();
+      try {
+        resolve(await fn());
+      } catch (e) {
+        reject(e);
+      }
+    }, () => {
+      // prior link rejected — still execute this link
+      lastCallTs = Date.now();
+      fn().then(resolve, reject);
+    });
+  });
+}
+
+/** Reset the throttle chain — call between runs to prevent stale state. */
+export function resetThrottle(): void {
+  chain = Promise.resolve();
+  lastCallTs = 0;
+}
+
+export interface BatchSection {
+  key: string;     // stable id the model must echo back
+  prompt: string;  // the sub-task
+}
+
+/**
+ * Compose several sub-tasks into ONE prompt that asks the model to return a
+ * single JSON object keyed by section id. This collapses N requests into 1,
+ * which is the difference between staying under 5 RPM and tripping it.
+ */
+export function batchPrompts(intro: string, sections: BatchSection[]): string {
+  const blocks = sections
+    .map((s, i) => `### TASK ${i + 1} — key "${s.key}"\n${s.prompt}`)
+    .join("\n\n");
+  const keys = sections.map((s) => `"${s.key}"`).join(", ");
+  return `${intro}
+
+You will answer ${sections.length} tasks in ONE reply to conserve rate limit.
+Return a SINGLE raw JSON object whose keys are exactly: ${keys}.
+Each value is a string containing that task's full answer. No prose outside the JSON.
+
+${blocks}`;
+}
+
+/** Parse a batched JSON reply back into a key→answer map (best-effort). */
+export function parseBatchReply(raw: string, keys: string[]): Record<string, string> {
+  const out: Record<string, string> = {};
+  let json: any = null;
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const src = fenced ? fenced[1] : raw;
+  const start = src.indexOf("{");
+  const end = src.lastIndexOf("}");
+  if (start !== -1 && end > start) {
+    try { json = JSON.parse(src.slice(start, end + 1)); } catch { /* */ }
+  }
+  for (const k of keys) {
+    if (json && typeof json[k] === "string") out[k] = json[k];
+    else if (json && json[k] != null) out[k] = JSON.stringify(json[k]);
+    else out[k] = "";
+  }
+  return out;
+}

package/src/lib/runtime-estimator.ts

@@ -0,0 +1,135 @@
+/**
+ * Runtime Estimator — deterministic configuration estimator.
+ *
+ * Two estimators are exposed:
+ *   1. `estimateRuntime(simple)` — legacy minimal estimator (existing API).
+ *   2. `estimateRuntime(advanced)` — when called with the advanced input shape,
+ *      breaks down per-phase wall-clock seconds for Grounding / SLOOP / N-Deep.
+ *
+ * Both are pure functions; no network, no LLM calls. Used by MemoryStressPanel
+ * to give users a time-budget preview before launching a heavy query.
+ */
+
+export interface RuntimeEstimate {
+  estimatedSeconds: number;
+  llmCalls: number;
+  notes: string[];
+  /** Per-phase breakdown when advanced estimator is invoked. */
+  breakdown?: Array<{ step: string; seconds: number }>;
+}
+
+export interface RuntimeEstimateInput {
+  // Simple form (back-compat with prior callers)
+  pages?: number;
+  nDeep?: number;
+  cluster?: number;
+  searchDepth?: number;
+  // Advanced form (new)
+  sources?: number;
+  hypotheses?: number;
+  deepResearch?: boolean;
+  sloopPages?: number;
+  clusterWidth?: number;
+  nDeepPasses?: number;
+  forceSloop?: boolean;
+  modelFamily?: "gemini-fast" | "gemma-31b" | "other";
+}
+
+export function estimateRuntime(opts: RuntimeEstimateInput): RuntimeEstimate {
+  // ── Advanced path: triggered when any advanced field is provided ─────────
+  const isAdvanced =
+    opts.sources !== undefined ||
+    opts.hypotheses !== undefined ||
+    opts.forceSloop !== undefined ||
+    opts.modelFamily !== undefined ||
+    opts.deepResearch !== undefined ||
+    opts.sloopPages !== undefined ||
+    opts.clusterWidth !== undefined ||
+    opts.nDeepPasses !== undefined;
+
+  if (isAdvanced) {
+    const breakdown: Array<{ step: string; seconds: number }> = [];
+    const modelFamily = opts.modelFamily ?? "other";
+    const modelFactor = modelFamily === "gemma-31b" ? 1.8 : modelFamily === "gemini-fast" ? 1.0 : 1.25;
+
+    const sources = opts.sources ?? 18;
+    const hypotheses = opts.hypotheses ?? 4;
+    const sloopPages = opts.sloopPages ?? opts.pages ?? 8;
+    const clusterWidth = opts.clusterWidth ?? opts.cluster ?? 6;
+    const nDeepPasses = opts.nDeepPasses ?? opts.nDeep ?? 4;
+    const deepResearch = opts.deepResearch ?? false;
+    const forceSloop = opts.forceSloop ?? true;
+
+    // Grounding search wave: query + hypotheses. Cluster width batches.
+    const searchCalls = 1 + Math.max(0, hypotheses);
+    const effectiveCluster = Math.max(1, Math.min(clusterWidth, Math.max(1, hypotheses || 1)));
+    const searchSeconds = ((searchCalls * 4.2) / effectiveCluster + sources * 0.5) * modelFactor;
+    breakdown.push({ step: "Grounding", seconds: searchSeconds });
+
+    if (forceSloop) {
+      const sections = Math.max(4, sloopPages * 2);
+      const sloopSeconds = sections * 11.5 * modelFactor;
+      breakdown.push({ step: "SLOOP", seconds: sloopSeconds });
+    } else if (deepResearch) {
+      breakdown.push({ step: "4-Stage", seconds: 22 * modelFactor });
+    } else {
+      breakdown.push({ step: "Direct synthesis", seconds: 10 * modelFactor });
+    }
+
+    if (nDeepPasses > 0) {
+      // Each pass includes critique + section revisions + batched judge.
+      const nDeepSeconds = (nDeepPasses * 17 + 8) * modelFactor;
+      breakdown.push({ step: "N-Deep", seconds: nDeepSeconds });
+    }
+
+    const estimatedSeconds = Math.round(breakdown.reduce((sum, b) => sum + b.seconds, 0));
+    const llmCalls = Math.round(
+      (forceSloop ? Math.max(4, sloopPages * 2) : deepResearch ? 4 : 1) +
+      nDeepPasses * 3 + // critique + revisions + judge per pass
+      Math.max(0, hypotheses) // grounding
+    );
+    return {
+      estimatedSeconds: Math.max(12, estimatedSeconds),
+      llmCalls: Math.max(6, llmCalls),
+      notes: ["advanced", `model=${modelFamily}`, `pages=${sloopPages}`, `cluster=${clusterWidth}`, `nDeep=${nDeepPasses}`],
+      breakdown,
+    };
+  }
+
+  // ── Simple path: legacy estimator (back-compat) ──────────────────────────
+  const p = Math.max(4, Math.min(16, opts.pages ?? 8));
+  const nd = Math.max(1, Math.min(12, opts.nDeep ?? 4));
+  const c = Math.max(2, Math.min(20, opts.cluster ?? 8));
+  const d = Math.max(3, Math.min(12, opts.searchDepth ?? 5));
+
+  const llmCalls = Math.round(p * 1.4 + nd * 1.1 + (c * 0.6) + (d * 0.8));
+  const seconds = Math.round(p * 1.65 + nd * 2.0 + (c * 0.95) + (d * 1.05));
+
+  return {
+    estimatedSeconds: Math.max(12, seconds),
+    llmCalls: Math.max(6, llmCalls),
+    notes: ["heuristic", `pages=${p}`, `nDeep=${nd}`, `cluster=${c}`],
+  };
+}
+
+/**
+ * Smoke test: verifies estimator produces sane output for the user-reported
+ * failing config (8 SLOOP / 4 N-Deep / 8 Cluster / 5 depth, 4-stage on).
+ * Used by MemoryStressPanel for at-load self-check.
+ */
+export function runtimeEstimatorSmoke(): RuntimeEstimate {
+  const target = estimateRuntime({
+    sources: 18,
+    hypotheses: 4,
+    deepResearch: true,
+    forceSloop: true,
+    sloopPages: 8,
+    clusterWidth: 8,
+    nDeepPasses: 4,
+    modelFamily: "gemma-31b",
+  });
+  if (target.estimatedSeconds <= 0) throw new Error("runtime estimate must be positive");
+  if (!target.breakdown?.find(b => b.step === "SLOOP")) throw new Error("expected SLOOP step");
+  if (!target.breakdown?.find(b => b.step === "N-Deep")) throw new Error("expected N-Deep step");
+  return target;
+}