pi-supernova 0.0.7 → 0.0.11

package/index.js

@@ -3,7 +3,7 @@ import { isString, isFunction, isObject } from "./decode.js";
 import { buildCatalog, searchCatalog, describeTool, mergeNativeToolDefinitions } from "./catalog.js";
 import { loadConfig } from "./config.js";
 import { createHostBridge } from "./host-bridge.js";
-import { runGuestProgram } from "./runtime.js";
+import { runGuestProgram, warmGuestWorker } from "./runtime.js";
 import {
   extractOperationsFromCode,
   renderSupernovaCall,
@@ -30,6 +30,60 @@ try {
 function result(text, details) {
   return { content: [{ type: "text", text }], details };
 }
+
+const PROGRESS_FRAME_MS = 40;
+
+/**
+ * Live trace updates for the card. The first update is immediate (seeds the result slot);
+ * later ones are coalesced to one host re-render per frame so a tight loop of nova.calls
+ * is not throttled by the TUI. A throwing host callback must never break the run.
+ */
+function progressEmitter(onUpdate) {
+  if (!isFunction(onUpdate)) return Object.assign(() => {}, { flush() {} });
+  let pending = null;
+  let timer = null;
+  const send = (trace) => {
+    try {
+      onUpdate({ content: [{ type: "text", text: "" }], details: { trace, running: true } });
+    } catch {}
+  };
+  const flush = () => {
+    timer = null;
+    if (pending === null) return;
+    const trace = pending;
+    pending = null;
+    send(trace);
+  };
+  const emit = (trace) => {
+    if (timer === null && pending === null) {
+      send(trace);
+      timer = setTimeout(flush, PROGRESS_FRAME_MS);
+      return;
+    }
+    pending = trace;
+    if (timer === null) timer = setTimeout(flush, PROGRESS_FRAME_MS);
+  };
+  emit.flush = () => {
+    if (timer !== null) clearTimeout(timer);
+    pending = null;
+    timer = null;
+  };
+  return emit;
+}
+
+function logsBlock(outcome, tail = "") {
+  return outcome.logs?.length ? `\n--- logs\n${outcome.logs.join("\n")}${tail}` : "";
+}
+
+function errorText(outcome) {
+  return `error ${outcome.wallMs}ms: ${outcome.error}${logsBlock(outcome)}`;
+}
+
+function successText(outcome) {
+  const truncated = outcome.returnTruncated ? " [return truncated]" : "";
+  const hint = outcome.undefinedReturn ? " (no return statement — add \`return\` to get a value)" : "";
+  return `ok ${outcome.wallMs}ms${truncated}${logsBlock(outcome, "\n--- result")}\n${outcome.resultText}${hint}`;
+}
 function unwrapStructuredResult(response, operation) {
   if (response?.ok === false) {
     throw new Error(response.value || response.error || `${operation} failed`);
@@ -43,21 +97,17 @@ function unwrapStructuredResult(response, operation) {
   }
 }
 
-const TOOL_DESCRIPTION = `Execute JavaScript that orchestrates host tools in one shot (Code Mode).
-
-Inside the program you get:
-  nova.search(query)           — thin catalog hits (name + one-liner)
-  nova.describe(name)          — full parameter summary on demand
-  nova.call(name, args)        — invoke a host tool (or native adapter)
-  nova.callMany([{name,args}]) — Auto parallel wave (serial if any mutating)
-  nova.snap(query, root?)       — resolve a concept to a source location
-  nova.surface(path)            — structural source outline
-  nova.has(name)                — test host-tool availability
-  parallel(thunks) / pipeline(items, ...stages)
+const TOOL_DESCRIPTION = `Run one JavaScript program that composes host tools. Async body or arrow; \`return\` a small shaped value (compact literal, capped; strings raw; console.log is captured).
 
-Shorthand globals: read, write, edit, patch, exec, snap, surface.
-Prefer search→describe→call. Keep intermediates in the program; return a shaped value.
-Schemas are NOT dumped into the system prompt — discover them inside the runtime.`;
+Globals (async):
+read(path|paths, offset?, limit?) → text | text[]
+write(path, text) · edit(path, oldText, newText) · patch(path, unifiedDiff)
+bash(cmd, {cwd?, timeoutMs?}) → output, throws on non-zero exit · exec(cmd, argv?) quotes argv
+evidence(query, {k?}) → {spans: [{path, lines, name, text}]} top-K spans that answer a question — use before read
+snap(query, root?) → {path, line, signature, context} · surface(path) → {items: [{name, kind, line}]}
+nova.call(name, args) → {ok, value} for any host tool · nova.callMany([{name, args}]) parallel when read-only
+nova.search(query) → [{name, description}] · nova.describe(name) → parameters · nova.has(name) sync
+parallel(thunks) · pipeline(items, ...stages)`;
 
 export default function piSupernova(pi) {
   const config = loadConfig();
@@ -101,16 +151,18 @@ export default function piSupernova(pi) {
       async callMany(calls) {
         return bridge.callMany(calls);
       },
-      async speculate(fn) {
+      speculateBegin() {
         bridge.beginSpeculation();
-        try {
-          const val = await fn();
-          await bridge.commitSpeculation();
-          return { ok: true, committed: true, value: val };
-        } catch (err) {
-          bridge.rollbackSpeculation();
-          return { ok: false, committed: false, error: err instanceof Error ? err.message : String(err) };
-        }
+      },
+      async speculateCommit() {
+        await bridge.commitSpeculation();
+      },
+      speculateRollback() {
+        bridge.rollbackSpeculation();
+      },
+      names() {
+        const cat = catalog.length ? catalog : refreshCatalog();
+        return [...new Set([...cat.map((t) => t.name), ...bridge.executors.keys(), ...Object.keys(bridge.natives)])];
       },
       async surface(filePath) {
         return unwrapStructuredResult(await bridge.call("surface", { path: filePath }), "surface");
@@ -118,9 +170,6 @@ export default function piSupernova(pi) {
       async snap(query, targetPath) {
         return unwrapStructuredResult(await bridge.call("snap", { query, path: targetPath }), "snap");
       },
-      has(name) {
-        return bridge.hasExecutor(name) || catalog.some((t) => t.name === name);
-      },
     };
   }
 
@@ -128,23 +177,13 @@ export default function piSupernova(pi) {
     name: "supernova",
     label: "Supernova",
     description: TOOL_DESCRIPTION,
-    promptSnippet: "Compose multiple host tools in one JavaScript program via supernova",
+    promptSnippet: "Compose host tools in one JavaScript program",
     promptGuidelines: [
-      "Use supernova when a task needs multi-step tool composition, loops, filtering, or parallel reads.",
-      "Discover tools with nova.search / nova.describe inside the program — do not guess full schemas.",
-      "Return a compact shaped value; intermediates stay in the runtime.",
+      "Use supernova for multi-step tool work: loops, filtering, parallel reads, read→edit chains. To understand code, call evidence(question) and read only the returned spans; read whole files only to edit them. Return a compact shaped value; keep raw tool output inside the program.",
     ],
     parameters: Type.Object({
-      code: Type.String({
-        description:
-          "JavaScript async body or arrow. Globals: nova/tools, parallel, pipeline, console.",
-      }),
-      timeoutMs: Type.Optional(
-        Type.Integer({
-          minimum: 1000,
-          description: "Hard timeout in ms (default from supernova.json / package default)",
-        }),
-      ),
+      code: Type.String({ description: "JavaScript program: async body or arrow function." }),
+      timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, description: "Hard timeout in ms." })),
     }),
     // One self-owned result frame is shared by Pi and OMP; renderCall stays empty
     // so separate call/result slots cannot duplicate the lifecycle card.
@@ -163,74 +202,26 @@ export default function piSupernova(pi) {
       bridge.resetCallBudget();
       refreshCatalog();
       bridge.beginSpeculation();
+      const emitProgress = progressEmitter(onUpdate);
+      bridge.setCallListener((_record, allTrace) => emitProgress(allTrace));
+      emitProgress([]);
 
-      bridge.setCallListener((_record, allTrace) => {
-        if (isFunction(onUpdate)) {
-          try {
-            onUpdate({
-              content: [{ type: "text", text: "" }],
-              details: { trace: allTrace, running: true },
-            });
-          } catch {}
-        }
-      });
-
-      if (isFunction(onUpdate)) {
-        try {
-          onUpdate({
-            content: [{ type: "text", text: "" }],
-            details: { trace: [], running: true },
-          });
-        } catch {}
-      }
-
-      const runConfig = {
-        ...config,
-        timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs,
-      };
-
-      const runStartedAt = performance.now();
       let outcome;
       try {
-        outcome = await runGuestProgram({
-          code: String(params?.code || ""),
-          nova: makeNovaApi(),
-          config: runConfig,
-          signal: runController.signal,
-          onTimeout: abortRun,
-        });
-      } catch (error) {
-        outcome = {
-          ok: false,
-          error: error instanceof Error ? error.message : String(error),
-          logs: [],
-          wallMs: Math.round(performance.now() - runStartedAt),
-        };
+        outcome = await runProgram(params, runController.signal, abortRun);
       } finally {
         bridge.setCallListener(null);
+        emitProgress.flush();
         signal?.removeEventListener("abort", abortRun);
       }
 
       const trace = bridge.getTrace();
       if (!outcome.ok) {
         bridge.rollbackSpeculation();
-        let text = `Supernova error (${outcome.wallMs}ms):\n${outcome.error}`;
-        if (outcome.logs?.length) text += `\n\nLogs:\n${outcome.logs.join("\n")}`;
-        return result(text, {
-          ok: false,
-          error: outcome.error,
-          wallMs: outcome.wallMs,
-          logs: outcome.logs,
-          trace,
-        });
+        return result(errorText(outcome), { ok: false, error: outcome.error, wallMs: outcome.wallMs, logs: outcome.logs, trace });
       }
-
       await bridge.commitSpeculation();
-      let text = `Supernova ok (${outcome.wallMs}ms)`;
-      if (outcome.returnTruncated) text += " [return truncated]";
-      if (outcome.logs?.length) text += `\n\nLogs:\n${outcome.logs.join("\n")}`;
-      text += `\n\nResult:\n${outcome.resultText}`;
-      return result(text, {
+      return result(successText(outcome), {
         ok: true,
         wallMs: outcome.wallMs,
         returnTruncated: outcome.returnTruncated,
@@ -242,9 +233,28 @@ export default function piSupernova(pi) {
     },
   });
 
+  async function runProgram(params, signal, onTimeout) {
+    const runStartedAt = performance.now();
+    const runConfig = {
+      ...config,
+      timeoutMs: Number.isInteger(params?.timeoutMs) ? params.timeoutMs : config.timeoutMs,
+    };
+    try {
+      return await runGuestProgram({ code: String(params?.code || ""), nova: makeNovaApi(), config: runConfig, signal, onTimeout });
+    } catch (error) {
+      return {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+        logs: [],
+        wallMs: Math.round(performance.now() - runStartedAt),
+      };
+    }
+  }
+
   pi.on("session_start", (_event, ctx) => {
     if (ctx && isString(ctx.cwd) && ctx.cwd) cwd = ctx.cwd;
     refreshCatalog();
+    warmGuestWorker(config).catch(() => {});
   });
 
   pi.registerCommand("supernova", {
@@ -257,7 +267,7 @@ export default function piSupernova(pi) {
         `pi-supernova catalog: ${catalog.length} tools`,
         `captured executors: ${captured.length ? captured.join(", ") : "(none yet — load this package early)"}`,
         `native adapters: ${natives.join(", ")}`,
-        `timeoutMs=${config.timeoutMs} maxCallResultChars=${config.maxCallResultChars} maxBridgeCalls=${config.maxBridgeCalls}`,
+        `timeoutMs=${config.timeoutMs} maxCallResultChars=${config.maxCallResultChars} maxReturnChars=${config.maxReturnChars} maxBridgeCalls=${config.maxBridgeCalls} maxHeapMb=${config.maxHeapMb}`,
       ];
       ctx.ui.notify(lines.join("\n"), "info");
     },

package/omp-frame.js

@@ -25,10 +25,14 @@ function boxOf(theme) {
 	return DEFAULT_BOX;
 }
 
+const BORDER_BY_STATE = { error: "error", warning: "warning", running: "accent", pending: "accent" };
+
+function borderKeyFor(state) {
+	return BORDER_BY_STATE[state] || "dim";
+}
+
 function borderPaint(theme, state, borderColor) {
-	const key =
-		borderColor ||
-		(state === "error" ? "error" : state === "warning" ? "warning" : state === "running" || state === "pending" ? "accent" : "dim");
+	const key = borderColor || borderKeyFor(state);
 	if (theme && isFunction(theme.fg)) {
 		try {
 			return (text) => theme.fg(key, text);
@@ -39,22 +43,30 @@ function borderPaint(theme, state, borderColor) {
 	return (text) => text;
 }
 
+function resolveStatusIcon({ icon, iconOverride, state }) {
+	if (iconOverride !== undefined) return undefined;
+	if (icon !== undefined) return icon;
+	return state === "error" ? "error" : undefined;
+}
+
+const STATUS_GLYPH = { error: "✗ ", running: "… " };
+const STATUS_COLOR = { error: "error", running: "dim" };
+
+function statusPrefix(theme, resolvedIcon, iconOverride, spinnerFrame) {
+	if (iconOverride) return `${iconOverride} `;
+	const key = resolvedIcon === "error" ? "error" : resolvedIcon === "running" || spinnerFrame ? "running" : undefined;
+	const glyph = STATUS_GLYPH[key];
+	if (!glyph) return "";
+	return theme?.fg ? theme.fg(STATUS_COLOR[key], glyph) : glyph;
+}
+
 function statusHeader(theme, { title, description, state, spinnerFrame, icon, iconOverride }) {
-	const resolvedIcon =
-		iconOverride !== undefined
-			? undefined
-			: icon !== undefined
-				? icon
-				: state === "error"
-					? "error"
-					: undefined;
+	const resolvedIcon = resolveStatusIcon({ icon, iconOverride, state });
 	const titleText = theme?.fg ? theme.fg("accent", title) : title;
 	const descText = description ? (theme?.fg ? theme.fg("muted", description) : description) : "";
-	let prefix = "";
-	if (iconOverride) prefix = `${iconOverride} `;
-	else if (resolvedIcon === "error") prefix = theme?.fg ? theme.fg("error", "✗ ") : "✗ ";
-	else if (resolvedIcon === "running" || spinnerFrame) prefix = theme?.fg ? theme.fg("dim", "… ") : "… ";
-	return descText ? `${prefix}${titleText}: ${descText}` : `${prefix}${titleText}`;
+	const prefix = statusPrefix(theme, resolvedIcon, iconOverride, spinnerFrame);
+	if (!descText) return `${prefix}${titleText}`;
+	return `${prefix}${titleText}: ${descText}`;
 }
 
 function padLine(line, width, bgFn) {
@@ -65,34 +77,55 @@ function padLine(line, width, bgFn) {
 	return bgFn ? bgFn(padded) : padded;
 }
 
+const BG_BY_STATE = { error: "toolErrorBg", pending: "toolPendingBg", running: "toolPendingBg" };
+
+function bgKeyFor(state) {
+	return BG_BY_STATE[state] || "toolSuccessBg";
+}
+
+function wrapBg(paint) {
+	return (text) => {
+		const out = paint(text);
+		return isString(out) ? out : text;
+	};
+}
+
 function bgFnForState(theme, state) {
 	if (!state || !theme) return undefined;
+	const key = bgKeyFor(state);
 	if (isFunction(theme.bg)) {
-		const key =
-			state === "error" ? "toolErrorBg" : state === "pending" || state === "running" ? "toolPendingBg" : "toolSuccessBg";
 		try {
-			const probe = theme.bg(key, "x");
-			if (!isString(probe)) return undefined;
-			return (text) => {
-				const painted = theme.bg(key, text);
-				return isString(painted) ? painted : text;
-			};
+			if (!isString(theme.bg(key, "x"))) return undefined;
 		} catch {
 			return undefined;
 		}
+		return wrapBg((text) => theme.bg(key, text));
 	}
-	if (isFunction(theme.getBgAnsi)) {
-		try {
-			const key =
-				state === "error" ? "toolErrorBg" : state === "pending" || state === "running" ? "toolPendingBg" : "toolSuccessBg";
-			const ansi = theme.getBgAnsi(key);
-			if (!ansi) return undefined;
-			return (text) => `${ansi}${text}\x1b[49m`;
-		} catch {
-			return undefined;
+	if (!isFunction(theme.getBgAnsi)) return undefined;
+	try {
+		const ansi = theme.getBgAnsi(key);
+		if (!ansi) return undefined;
+		return (text) => `${ansi}${text}\x1b[49m`;
+	} catch {
+		return undefined;
+	}
+}
+
+function frameBodyLines(sections, contentWidth, box, border, bgFn, w, paintBar) {
+	const lines = [];
+	const normalized = sections.length > 0 ? sections : [{ lines: [] }];
+	const v = box.vertical;
+	for (const section of normalized) {
+		if (section.label) lines.push(paintBar(box.teeRight || "├", box.teeLeft || "┤", section.label));
+		for (const raw of section.lines || []) {
+			for (const piece of String(raw).split("\n")) {
+				const body = clampLine(piece, contentWidth);
+				const pad = Math.max(0, contentWidth - measureWidth(body));
+				lines.push(padLine(`${border(v)} ${body}${" ".repeat(pad)} ${border(v)}`, w, bgFn));
+			}
 		}
 	}
-	return undefined;
+	return lines;
 }
 
 function renderPortableFrame(theme, { header, sections = [], state = "pending", borderColor, width }) {
@@ -129,22 +162,7 @@ function renderPortableFrame(theme, { header, sections = [], state = "pending",
 	const contentWidth = Math.max(1, w - 2 - 2);
 	const lines = [];
 	lines.push(paintBar(box.topLeft, box.topRight, header));
-
-	const normalized = sections.length > 0 ? sections : [{ lines: [] }];
-	for (const section of normalized) {
-		if (section.label) {
-			lines.push(paintBar(box.teeRight || "├", box.teeLeft || "┤", section.label));
-		}
-		for (const raw of section.lines || []) {
-			for (const piece of String(raw).split("\n")) {
-				const body = clampLine(piece, contentWidth);
-				const pad = Math.max(0, contentWidth - measureWidth(body));
-				const inner = `${body}${" ".repeat(pad)}`;
-				lines.push(padLine(`${border(v)} ${inner} ${border(v)}`, w, bgFn));
-			}
-		}
-	}
-
+	lines.push(...frameBodyLines(sections, contentWidth, box, border, bgFn, w, paintBar));
 	lines.push(paintBar(box.bottomLeft, box.bottomRight, null));
 	return lines;
 }
@@ -180,4 +198,3 @@ export function novaFramedBlock(theme, build) {
 export function novaStatusLine(theme, options) {
 	return statusHeader(theme, options);
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-supernova",
-  "version": "0.0.7",
+  "version": "0.0.11",
   "description": "Dual-host CodeMode for Pi/OMP: progressive tool discovery, result bottleneck, and Amdahl Auto parallel.",
   "type": "module",
   "author": "AdityaVG13",
@@ -29,6 +29,13 @@
     "bottleneck.js",
     "parallel.js",
     "runtime.js",
+    "guest-worker.js",
+    "repo-index.js",
+    "evidence.js",
+    "format.js",
+    "patch.js",
+    "vfs.js",
+    "workspace.js",
     "config.js",
     "config.default.json",
     "README.md",

package/parallel.js

@@ -1,6 +1,5 @@
 
 import { isString } from "./decode.js";
-
 export function isMutatingTool(name, config) {
   const exact = new Set(config.mutatingTools || []);
   if (exact.has(name)) return true;
@@ -10,35 +9,35 @@ export function isMutatingTool(name, config) {
   }
   return false;
 }
-
+async function runSerial(list) {
+  const out = [];
+  for (const thunk of list) out.push(await thunk());
+  return out;
+}
+function shouldParallelize(mode, anyMutating, count) {
+  if (mode === "parallel") return true;
+  if (mode !== "auto") return false;
+  if (anyMutating) return false;
+  return count > 1;
+}
 export async function runParallelWave(thunks, meta, options = {}) {
   const list = Array.isArray(thunks) ? thunks : [];
-  if (list.length === 0) {
-    return { results: [], mode: "serial", reason: "empty" };
-  }
-  const mode = options.mode || "auto";
+  if (list.length === 0) return { results: [], mode: "serial", reason: "empty" };
+  const { mode = "auto", config = {} } = options;
   const names = Array.isArray(meta?.names) ? meta.names : [];
-  const config = options.config || {};
   const anyMutating = names.some((n) => isString(n) && isMutatingTool(n, config));
-  const useParallel = mode === "parallel" || (mode === "auto" && !anyMutating && list.length > 1);
-
-  if (!useParallel) {
-    const out = [];
-    for (const thunk of list) {
-      out.push(await thunk());
-    }
-    return { results: out, mode: "serial", reason: anyMutating ? "mutating" : "single-or-forced" };
+  if (shouldParallelize(mode, anyMutating, list.length)) {
+    const results = await Promise.all(list.map((thunk) => thunk()));
+    return { results, mode: "parallel", reason: "independent-reads" };
   }
-
-  const results = await Promise.all(list.map((thunk) => thunk()));
-  return { results, mode: "parallel", reason: "independent-reads" };
+  const results = await runSerial(list);
+  if (anyMutating) return { results, mode: "serial", reason: "mutating" };
+  return { results, mode: "serial", reason: "single-or-forced" };
 }
-
 export async function parallel(items) {
   const list = Array.isArray(items) ? items : [];
   return Promise.all(list.map((item) => (item instanceof Function ? item() : item)));
 }
-
 export async function pipeline(items, ...stages) {
   let current = Array.isArray(items) ? items.slice() : [];
   for (const stage of stages) {

package/patch.js

@@ -0,0 +1,106 @@
+import { isString } from "./decode.js";
+
+function parseHunkHeader(line) {
+  const match = /^@@\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/.exec(line);
+  if (!match) return null;
+  return {
+    oldStart: parseInt(match[1], 10),
+    oldLength: match[2] !== undefined ? parseInt(match[2], 10) : 1,
+    newStart: parseInt(match[3], 10),
+    newLength: match[4] !== undefined ? parseInt(match[4], 10) : 1,
+    lines: [],
+  };
+}
+
+function isHunkLine(line) {
+  return line.startsWith("+") || line.startsWith("-") || line.startsWith(" ");
+}
+
+export function parsePatchHunks(patchText) {
+  const patchLines = patchText.replace(/\r\n/g, "\n").split("\n");
+  const hunks = [];
+  let current = null;
+
+  for (const line of patchLines) {
+    const header = parseHunkHeader(line);
+    if (header) {
+      if (current) hunks.push(current);
+      current = header;
+    } else if (current && isHunkLine(line)) {
+      current.lines.push(line);
+    }
+  }
+  if (current) hunks.push(current);
+  if (hunks.length === 0) {
+    throw new Error("no valid patch hunks found (expected @@ -old,len +new,len @@)");
+  }
+  return hunks;
+}
+
+function findHunkMatch(fileLines, expectedOld, nominal) {
+  const matchAt = (idx) => {
+    if (idx < 0 || idx + expectedOld.length > fileLines.length) return false;
+    for (let j = 0; j < expectedOld.length; j++) {
+      if (fileLines[idx + j] !== expectedOld[j]) return false;
+    }
+    return true;
+  };
+
+  if (matchAt(nominal)) return nominal;
+  const maxDelta = Math.max(fileLines.length, 100);
+  for (let delta = 1; delta <= maxDelta; delta++) {
+    if (matchAt(nominal + delta)) return nominal + delta;
+    if (matchAt(nominal - delta)) return nominal - delta;
+  }
+  return -1;
+}
+
+function splitHunkLines(hunk) {
+  const expectedOld = [];
+  const newLines = [];
+  for (const hLine of hunk.lines) {
+    if (hLine.startsWith("-")) {
+      expectedOld.push(hLine.slice(1));
+    } else if (hLine.startsWith("+")) {
+      newLines.push(hLine.slice(1));
+    } else {
+      const val = hLine.startsWith(" ") ? hLine.slice(1) : "";
+      expectedOld.push(val);
+      newLines.push(val);
+    }
+  }
+  return { expectedOld, newLines };
+}
+
+export function applyPatchToText(originalText, patchText) {
+  if (!isString(patchText) || !patchText.trim()) {
+    throw new Error("apply_patch requires non-empty patch");
+  }
+
+  const hunks = parsePatchHunks(patchText);
+  let fileLines = originalText.replace(/\r\n/g, "\n").split("\n");
+  const hasTrailingNewline = originalText.endsWith("\n");
+  let offsetShift = 0;
+
+  for (let h = 0; h < hunks.length; h++) {
+    const hunk = hunks[h];
+    const { expectedOld, newLines } = splitHunkLines(hunk);
+
+    if (expectedOld.length !== hunk.oldLength || newLines.length !== hunk.newLength) {
+      throw new Error(`patch hunk ${h + 1} length does not match its header`);
+    }
+
+    const nominal = Math.max(0, hunk.oldStart - 1 + offsetShift);
+    const matchIdx = findHunkMatch(fileLines, expectedOld, nominal);
+    if (matchIdx === -1) {
+      throw new Error(`patch hunk ${h + 1} rejected at line ${hunk.oldStart}: context did not match`);
+    }
+
+    fileLines.splice(matchIdx, expectedOld.length, ...newLines);
+    offsetShift += (matchIdx - nominal) + (newLines.length - expectedOld.length);
+  }
+
+  let resultText = fileLines.join("\n");
+  if (hasTrailingNewline && !resultText.endsWith("\n")) resultText += "\n";
+  return { resultText, hunkCount: hunks.length };
+}