dsh-hashline-edit 0.1.0 → 0.2.0

package/src/mutation-engine/pipeline.ts

@@ -85,12 +85,16 @@ import { saveCutIntent, dropCutIntent } from "../undo-store.js";
 import { repairCutIntents } from "../cut-repair.js";
 import { withSortedMutationQueues } from "../mutation-queue.js";
 import { resolveTarget, writeAtomic, readBytes } from "../fs-write.js";
+import {
+  missingAncestorDirs,
+  pathKind,
+  pruneEmptyDirs,
+  removeFile,
+  renameFile,
+  assertPathWithinWorkspace,
+} from "../fs-lifecycle.js";
 import { toCwd } from "../paths.js";
-import type {
-  DesiredContent,
-  NormalizedEditItem,
-  NormalizedEditRequest,
-} from "../payload-contract.js";
+import type { DesiredContent, NormalizedEditItem, NormalizedEditRequest } from "./edit-request.js";
 import {
   batchAbortFor,
   batchAbortForMany,
@@ -99,7 +103,13 @@ import {
   wrapParseFailure,
 } from "../edit-response.js";
 import { DEFERRED_STORE_SYNC_WARNING } from "../constants.js";
-import type { PipelineOptions, ProcessedEditFile, ForeignCutRecord } from "./types.js";
+import type {
+  PipelineOptions,
+  ProcessedEditFile,
+  ForeignCutRecord,
+  MemberLifecycle,
+  TransactionRecoveryReport,
+} from "./types.js";
 import {
   loadEditFile,
   loadForeignServedView,
@@ -365,7 +375,11 @@ function replacementTextForPayload(payload: DesiredContent): string {
  */
 type ParsedItem = { edit: HEdit } | { noopInsert: true };
 
-function parseEdits(items: NormalizedEditRequest["edits"], path: string): ParsedItem[] {
+function parseEdits(
+  items: NormalizedEditRequest["edits"],
+  path: string,
+  itemNumbers?: readonly number[],
+): ParsedItem[] {
   const parsed: ParsedItem[] = [];
   // WHY: payload parsing aggregates like the span gate — one malformed item must not mask another,
   // WHY: so the model fixes every malformed item in a single resubmission. Parsing is pure (no
@@ -373,6 +387,9 @@ function parseEdits(items: NormalizedEditRequest["edits"], path: string): Parsed
   const failures: { error: Error; index: number }[] = [];
   for (let index = 0; index < items.length; index++) {
     const item = items[index]!;
+    // WHY: the number the CALLER submitted — a per-file plan keeps its items' global positions,
+    // WHY: so a multi-file refusal still names the item the model sent, not a per-file 0.
+    const number = itemNumbers?.[index] ?? index;
     try {
       const payload = item.payload;
       let text: string;
@@ -388,7 +405,7 @@ function parseEdits(items: NormalizedEditRequest["edits"], path: string): Parsed
           if (payload.text === "") {
             throw new DomainError("E_INTERNAL_INVARIANT", {
               message:
-                `Edit request edits[${index}] "text" must carry at least one line; ` +
+                `Edit request edits[${number}] "text" must carry at least one line; ` +
                 `"text": "" is the deletion payload. Nothing was written.`,
             });
           }
@@ -438,7 +455,10 @@ function parseEdits(items: NormalizedEditRequest["edits"], path: string): Parsed
       });
     } catch (error) {
       if (items.length === 1) throw error;
-      failures.push({ error: error instanceof Error ? error : new Error(String(error)), index });
+      failures.push({
+        error: error instanceof Error ? error : new Error(String(error)),
+        index: number,
+      });
     }
   }
   if (failures.length === 1) {
@@ -716,6 +736,7 @@ async function runMutations(
   request: NormalizedEditRequest,
   cwd: string,
   options?: PipelineOptions,
+  itemNumbers?: readonly number[],
 ): Promise<ProcessedEditFile> {
   // WHY: the file was answered at admission (assertReq); the narrowed type carries it here.
   const path = request.file;
@@ -748,12 +769,19 @@ async function runMutations(
 
   const isPreview = options?.noPersist === true;
 
-  const parsed = parseEdits(items, path);
+  const parsed = parseEdits(items, path, itemNumbers);
   // WHY: (ticket-04 §3.6) noop-insert markers mutate nothing, so they are not part of the batch
   // WHY: span gate — the gate compares regions the call will rewrite.
   const realEdits: HEdit[] = [];
-  for (const one of parsed) {
-    if ("edit" in one) realEdits.push(one.edit);
+  // WHY: the gate reports failures by item number, and a noop-insert marker is not one of its items,
+  // WHY: so the caller-facing numbers are filtered in lockstep with the edits it does compare.
+  const realNumbers: number[] = [];
+  for (let index = 0; index < parsed.length; index++) {
+    const one = parsed[index]!;
+    if ("edit" in one) {
+      realEdits.push(one.edit);
+      realNumbers.push(itemNumbers?.[index] ?? index);
+    }
   }
 
   const {
@@ -788,6 +816,9 @@ async function runMutations(
     // WHY: compares is the `s'_k` the apply path would rewrite — one source for both (spec §3.2.1).
     await assertBatchSpansDisjoint(realEdits, {
       served,
+      // WHY: the caller's own item numbers, parallel to `realEdits` — a per-file plan keeps its
+      // WHY: items' global positions, so a gate refusal names the item the model sent.
+      itemNumbers: realNumbers,
       identity: leaseSpanSource({
         store: hashStore,
         sessionKey,
@@ -864,6 +895,7 @@ async function runMutations(
     abortIf(options?.signal);
     const item = items[index]!;
     const parsedItem = parsed[index]!;
+    const number = itemNumbers?.[index] ?? index;
     if ("noopInsert" in parsedItem) {
       // WHY: (ticket-04 §3.6) an empty "before"/"after" writes nothing by construction: bytes
       // WHY: unchanged, counted as a noop, model channel warned. It skips `applyEdit` AND the
@@ -871,7 +903,7 @@ async function runMutations(
       noopCount += 1;
       warnings.push(
         formatWarning("W_NOOP_INSERT", {
-          ref: `edit[${index}] (${path})`,
+          ref: `edit[${number}] (${path})`,
           removeFrom: item.target.anchor_from,
           removeTo: item.target.anchor_to,
         }),
@@ -899,7 +931,7 @@ async function runMutations(
       ...(isPreview ? {} : { currentIds }),
       onRejected: async (error) => {
         if (items.length === 1) throw error;
-        throw batchAbortFor({ error, index, path });
+        throw batchAbortFor({ error, index: number, path });
       },
     });
 
@@ -932,7 +964,7 @@ async function runMutations(
         removeFrom: item.target.anchor_from,
         removeTo: item.target.anchor_to,
         replacementText: replacementTextForPayload(item.payload),
-        ref: `edit[${index}] (${path})`,
+        ref: `edit[${number}] (${path})`,
         batch: items.length > 1,
         range,
         hashes: currentHashes,
@@ -947,12 +979,12 @@ async function runMutations(
       // WHY: calls keep the direct rejection path.
       if (decision.action === "reject") {
         if (items.length === 1) throw decision.error;
-        throw batchAbortFor({ error: decision.error, index, path });
+        throw batchAbortFor({ error: decision.error, index: number, path });
       }
       if (decision.action === "warn") warnings.push(decision.notice);
       if (items.length > 1) {
         warnings.push(
-          `edit[${index}] (${path}) was a noop: the range already contains the replacement text.`,
+          `edit[${number}] (${path}) was a noop: the range already contains the replacement text.`,
         );
       }
       pushNoopWarnings(outcome.anchorWarnings);
@@ -1260,7 +1292,141 @@ async function runCutTransaction(
     );
   }
 
-  const plans = [file, ...sourcePlans];
+  // WHY: the cut path is the correlated transaction with the source plans derived from this file's
+  // WHY: own `foreignCuts`; the multi-file path derives them from the same records across every
+  // WHY: target. One skeleton owns the pre-images, undo rows, intent, ordered renames, rollback,
+  // WHY: store commit and the single response (ADR-0028).
+  return await runCorrelatedTransaction(
+    [file, ...sourcePlans],
+    [file, ...sourcePlans],
+    options,
+    sessionKey,
+  );
+}
+
+/**
+ * The correlated multi-file commit: the one skeleton both the foreign-cut path and a multi-target
+ * edit run.
+ *
+ * Steps, in order: durable pre-images for every written file → correlated undo rows → the intent
+ * record → ordered renames (primary first) → best-effort rollback on a failed write → the intent
+ * dropped → one store commit per written file → ONE response whose sections cover every file.
+ *
+ * @param writePlans - the plans to write, in commit order. `writePlans[0]` is the primary: it is
+ *   renamed first and its undo row is the intent's target row.
+ * @param sectionPlans - every plan the response reports, including the ones that applied nothing
+ *   (those are reported and never committed).
+ * @returns the batch outcome, anchored on the primary file.
+ */
+function memberLifecycleOf(plan: ProcessedEditFile): MemberLifecycle {
+  return plan.lifecycle ?? { kind: "keep" };
+}
+
+function memberPostBytes(plan: ProcessedEditFile): Buffer {
+  return Buffer.from(plan.bom + restoreEndings(plan.result, plan.originalEnding), "utf-8");
+}
+
+/**
+ * Publish one already-validated member. This is the only place a lifecycle action reaches the
+ * filesystem: content writes keep using writeAtomic (one serializer); add/delete/move use the
+ * fs-lifecycle primitives that writeAtomic deliberately does not express.
+ */
+async function commitMember(
+  plan: ProcessedEditFile,
+  rawPreBytes: ReadonlyMap<string, Buffer>,
+  onPublished: (plan: ProcessedEditFile) => void,
+  workspaceRoot: string | undefined,
+  onAfterMoveRename?: (toAbsolutePath: string) => void | Promise<void>,
+): Promise<void> {
+  const lifecycle = memberLifecycleOf(plan);
+  switch (lifecycle.kind) {
+    case "keep":
+    case "add":
+      if (workspaceRoot !== undefined) {
+        await assertPathWithinWorkspace(workspaceRoot, plan.absolutePath);
+      }
+      await writeAtomic(plan.absolutePath, memberPostBytes(plan));
+      onPublished(plan);
+      return;
+    case "delete":
+      await removeFile(plan.absolutePath);
+      onPublished(plan);
+      return;
+    case "move": {
+      // WHY: rename first, then (only for an edited move) rewrite the destination. A pure move
+      // WHY: must stay a rename: re-serializing would launder the file's raw line endings.
+      await renameFile(
+        lifecycle.fromAbsolutePath,
+        lifecycle.toAbsolutePath,
+        undefined,
+        workspaceRoot,
+      );
+      // WHY: the rename is already a publication: a later content-write failure must roll this
+      // WHY: member back or the source disappears while the failure claims nothing changed.
+      onPublished(plan);
+      if (onAfterMoveRename !== undefined) await onAfterMoveRename(lifecycle.toAbsolutePath);
+      const post = memberPostBytes(plan);
+      // WHY: a pure rename must not re-serialize: the normalized text equals the baseline text,
+      // WHY: so the destination keeps the exact bytes the OS rename carried.
+      if (
+        plan.originalNormalized !== plan.result &&
+        !post.equals(rawPreBytes.get(plan.absolutePath)!)
+      ) {
+        await writeAtomic(lifecycle.toAbsolutePath, post);
+      }
+      return;
+    }
+  }
+}
+
+/**
+ * Restore one member that the commit had already published. A rollback is a BYTE restore, never
+ * a re-serialization: keep/delete write the captured pre-image buffer back; add removes what it
+ * created (and the empty directories it made); move renames back first, then restores the bytes.
+ */
+async function rollbackMember(
+  plan: ProcessedEditFile,
+  rawPreBytes: ReadonlyMap<string, Buffer>,
+  workspaceRoot: string | undefined,
+): Promise<void> {
+  const lifecycle = memberLifecycleOf(plan);
+  const pre = rawPreBytes.get(plan.absolutePath)!;
+  switch (lifecycle.kind) {
+    case "add":
+      if ((await pathKind(plan.absolutePath)) !== "absent") await removeFile(plan.absolutePath);
+      await pruneEmptyDirs(lifecycle.createdDirs);
+      return;
+    case "delete":
+      await writeAtomic(plan.absolutePath, pre);
+      return;
+    case "move": {
+      if ((await pathKind(lifecycle.toAbsolutePath)) !== "absent") {
+        await renameFile(
+          lifecycle.toAbsolutePath,
+          lifecycle.fromAbsolutePath,
+          undefined,
+          workspaceRoot,
+        );
+      }
+      // WHY: the rename carries the pre bytes for a pure move and for a failed content write; only
+      // WHY: rewrite when the destination really holds different bytes (a completed edit rolled back).
+      if (!(await readBytes(lifecycle.fromAbsolutePath)).equals(pre)) {
+        await writeAtomic(lifecycle.fromAbsolutePath, pre);
+      }
+      await pruneEmptyDirs(lifecycle.createdDirs);
+      return;
+    }
+    case "keep":
+      await writeAtomic(plan.absolutePath, pre);
+  }
+}
+async function runCorrelatedTransaction(
+  writePlans: ProcessedEditFile[],
+  sectionPlans: ProcessedEditFile[],
+  options: PipelineOptions | undefined,
+  sessionKey: string,
+): Promise<BatchOutcome> {
+  const primary = writePlans[0]!;
   const txnId = randomUUID();
 
   // WHY: STEP 1 durable pre-images: undo rows for EVERY file (pre bytes + post bytes + the
@@ -1270,21 +1436,63 @@ async function runCutTransaction(
   // WHY: first rename. Byte identity is not promised by this read, it is PROVEN upstream: the
   // WHY: admission round-trip guard refused any file whose decoded text re-encodes differently,
   // WHY: so decode/encode here is lossless by construction, stray line-break spellings included
-  // WHY: (ticket-04b §11: after an abort BOTH files are byte-identical to their pre bytes).
+  // WHY: (ticket-04b §11: after an abort EVERY file is byte-identical to its pre bytes).
   const rawPreBytes = new Map<string, Buffer>();
-  for (const plan of plans) {
+  for (const plan of writePlans) {
+    const lifecycle = plan.lifecycle;
+    if (lifecycle?.kind === "add") {
+      // WHY: an add has no pre-image by construction. A dry buffer keeps every consumer of the
+      // WHY: map total (rollback reads it, undo carries it as NULL through its lifecycle arm).
+      rawPreBytes.set(plan.absolutePath, Buffer.alloc(0));
+      plan.lifecycle = { ...lifecycle, createdDirs: await missingAncestorDirs(plan.absolutePath) };
+      continue;
+    }
+    if (lifecycle?.kind === "move") {
+      rawPreBytes.set(plan.absolutePath, await readBytes(lifecycle.fromAbsolutePath));
+      plan.lifecycle = {
+        ...lifecycle,
+        createdDirs: await missingAncestorDirs(lifecycle.toAbsolutePath),
+      };
+      continue;
+    }
     rawPreBytes.set(plan.absolutePath, await readBytes(plan.absolutePath));
   }
   const saved: { restore: () => Promise<void> }[] = [];
-  for (const plan of plans) {
+  for (const plan of writePlans) {
+    const lifecycle = plan.lifecycle;
+    const isAdd = lifecycle?.kind === "add";
+    const isDelete = lifecycle?.kind === "delete";
+    const isMove = lifecycle?.kind === "move";
+    const rawPost = Buffer.from(
+      plan.bom + restoreEndings(plan.result, plan.originalEnding),
+      "utf-8",
+    );
+    // WHY: a pure move carries the raw pre bytes to the destination; recording the canonical
+    // WHY: fold as its post image would make undo's byte oracle reject a legal mixed-ending file.
+    const storedRawPost =
+      isMove && plan.originalNormalized === plan.result
+        ? rawPreBytes.get(plan.absolutePath)!
+        : rawPost;
     const undo = await saveUndo(plan.absolutePath, {
-      content: plan.originalNormalized,
+      content: isAdd ? "" : plan.originalNormalized,
       bom: plan.bom,
       originalEnding: plan.originalEnding,
       hashes: plan.originalHashes,
-      resultContent: plan.result,
+      resultContent: isDelete ? "" : plan.result,
       transactionId: txnId,
-      rawPre: rawPreBytes.get(plan.absolutePath)!.toString("utf-8"),
+      rawPre: isAdd ? null : rawPreBytes.get(plan.absolutePath)!.toString("utf-8"),
+      ...(isMove
+        ? {
+            lifecycle: "move" as const,
+            fromPath: lifecycle.fromAbsolutePath,
+            toPath: lifecycle.toAbsolutePath,
+            rawPost: storedRawPost.toString("utf-8"),
+          }
+        : isAdd
+          ? { lifecycle: "add" as const, createdDirs: lifecycle.createdDirs }
+          : isDelete
+            ? { lifecycle: "delete" as const }
+            : { lifecycle: "edit" as const }),
     });
     if (!undo.persisted) {
       for (const prior of saved) await prior.restore();
@@ -1293,17 +1501,17 @@ async function runCutTransaction(
     saved.push(undo);
   }
   try {
-    await saveCutIntent(txnId, file.absolutePath);
+    await saveCutIntent(txnId, primary.absolutePath);
   } catch (error) {
     for (const prior of saved) await prior.restore();
     throw error;
   }
 
-  // WHY: STEP 2 ordered commit: the target insert first, then each source retirement, using the
-  // WHY: raw pre-images captured in STEP 1 above. The commit path serializes canonically (one
-  // WHY: convention, no third path); a ROLLBACK is not a commit and must not smuggle in the
-  // WHY: canonical fold as if it were the restore — it writes the captured BUFFERS (ticket-04b
-  // WHY: §11: after an abort BOTH files are byte-identical to the pre-transaction contents).
+  // WHY: STEP 2 ordered commit: the primary file first, then every remaining file in plan order,
+  // WHY: using the raw pre-images captured in STEP 1 above. The commit path serializes canonically
+  // WHY: (one convention, no third path); a ROLLBACK is not a commit and must not smuggle in the
+  // WHY: canonical fold as if it were the restore — it writes the captured BUFFERS (ticket-04b §11:
+  // WHY: after an abort EVERY file is byte-identical to the pre-transaction contents).
   const written: ProcessedEditFile[] = [];
   try {
     if (options?.onBeforeFirstCutWrite) {
@@ -1312,38 +1520,45 @@ async function runCutTransaction(
       await options.onBeforeFirstCutWrite();
     }
     abortIf(options?.signal);
-    await writeAtomic(
-      file.absolutePath,
-      file.bom + restoreEndings(file.result, file.originalEnding),
-    );
-    written.push(file);
-    for (const plan of sourcePlans) {
-      if (options?.onCutBetweenWrites) {
+    for (let index = 0; index < writePlans.length; index++) {
+      const plan = writePlans[index]!;
+      if (index > 0 && options?.onCutBetweenWrites) {
         // WHY: test-only fault-injection seam (ticket-04b §3): fires INSIDE the two-rename
         // WHY: window, after the previous file's rename is durable.
         await options.onCutBetweenWrites(written[written.length - 1]!.absolutePath);
       }
       abortIf(options?.signal);
-      await writeAtomic(
-        plan.absolutePath,
-        plan.bom + restoreEndings(plan.result, plan.originalEnding),
+      const publish = (member: ProcessedEditFile): void => {
+        written.push(member);
+      };
+      await commitMember(
+        plan,
+        rawPreBytes,
+        publish,
+        options?.workspaceRoot,
+        options?.onAfterMoveRename,
       );
-      written.push(plan);
     }
   } catch (error) {
-    let rolledBack = true;
+    // WHY: the recovery report is the honest three-way split the contract requires: restored =
+    // WHY: proven back at its pre-image, remaining = rollback did not run / did not hold,
+    // WHY: uncertain = the rollback attempt itself threw (we cannot claim either state).
+    const report: TransactionRecoveryReport = { restored: [], remaining: [], uncertain: [] };
     for (const plan of written) {
       try {
-        await writeAtomic(plan.absolutePath, rawPreBytes.get(plan.absolutePath)!);
+        await rollbackMember(plan, rawPreBytes, options?.workspaceRoot);
+        report.restored.push(plan.path);
       } catch (rollbackError) {
-        rolledBack = false;
+        report.remaining.push(plan.path);
+        report.uncertain.push(plan.path);
         reportDiagnostic(
           "mutation-engine",
-          "Failed to roll back a cut-transaction file:",
+          "Failed to roll back a transaction member:",
           rollbackError,
         );
       }
     }
+    const rolledBack = report.remaining.length === 0;
     if (rolledBack) {
       for (const prior of saved) await prior.restore();
       try {
@@ -1357,8 +1572,8 @@ async function runCutTransaction(
       }
     }
     // WHY: a rollback that did not hold LEAVES the intent row and the transaction-tagged undo
-    // WHY: rows: next-run repair resolves to complete-the-cut or restore-both from the stored
-    // WHY: pre/post bytes (ADR-0028) — never a silent loss, never a fake atomicity claim.
+    // WHY: rows: next-run repair resolves to complete-the-transaction or restore-from-rows.
+    (error as Error & { recovery?: TransactionRecoveryReport }).recovery = report;
     throw error;
   }
 
@@ -1371,38 +1586,288 @@ async function runCutTransaction(
   }
 
   // WHY: STEP 3 store commit per file — the same `finishCommittedFile` the single-file path
-  // WHY: runs, then ONE response whose sections cover BOTH files (§5).
+  // WHY: runs, then ONE response whose sections cover EVERY file (§5). A plan that applied nothing
+  // WHY: is REPORTED but never committed: its bytes did not move, so it owns no store write.
   const sections = [];
-  for (const plan of plans) {
-    sections.push(toSection(plan, await finishCommittedFile(plan, options, sessionKey)));
+  for (const plan of sectionPlans) {
+    // WHY: a deleted file has no post-image to snapshot or serve; every other member commits its
+    // WHY: new anchors through the same finishCommittedFile the single-file edit uses.
+    const materializes = plan.appliedCount > 0 && memberLifecycleOf(plan).kind !== "delete";
+    sections.push(
+      toSection(
+        plan,
+        materializes ? await finishCommittedFile(plan, options, sessionKey) : undefined,
+      ),
+    );
   }
-  const toolResult = buildBatchResult(sections);
+  return batchOutcome(sectionPlans, buildBatchResult(sections));
+}
+
+/** One group of items sharing a target file, keyed by that file's RESOLVED path. */
+interface TargetGroup {
+  /** Resolved absolute path — the identity two spellings of one file share (§9.4). */
+  readonly key: string;
+  /** The spelling this group's items used, for messages and the response section. */
+  readonly file: string;
+  readonly items: NormalizedEditItem[];
+  /**
+   * The call-relative 0-based number of every item in `items`, parallel to it: a refusal must name
+   * the item the model submitted, not this group's position inside the plan.
+   */
+  readonly numbers: number[];
+}
+
+/** What one plan or committed batch reports: the primary file leads, every section rides the result. */
+interface BatchOutcome {
+  result: string;
+  diff: string;
+  drift: string | undefined;
+  metrics: ReturnType<typeof buildBatchResult>["details"]["metrics"];
+  raw: ProcessedEditFile;
+  toolResult: ReturnType<typeof buildBatchResult>;
+}
+
+/** Shape one batch outcome around its primary plan: the first plan leads, every plan's drift joins. */
+function batchOutcome(
+  plans: ProcessedEditFile[],
+  toolResult: ReturnType<typeof buildBatchResult>,
+): BatchOutcome {
+  const primary = plans[0]!;
   const drift = plans
-    .map((p) => p.driftNotice)
-    .filter((d): d is string => d !== undefined)
+    .map((plan) => plan.driftNotice)
+    .filter((notice): notice is string => notice !== undefined)
     .join("\n\n");
   return {
-    result: file.result,
+    result: primary.result,
     diff: toolResult.details.diff ?? "",
     drift: drift === "" ? undefined : drift,
     metrics: toolResult.details.metrics,
-    raw: file,
+    raw: primary,
     toolResult,
   };
 }
 
+/** True when a request widens its targets past the call's single `file`. */
+function hasItemFiles(request: NormalizedEditRequest): boolean {
+  return request.edits.some((item) => item.file !== undefined);
+}
+
+/** The request one group plans: its items on its own file, under the call's mode. */
+function groupRequest(group: TargetGroup, request: NormalizedEditRequest): NormalizedEditRequest {
+  return {
+    file: group.file,
+    edits: group.items,
+    ...(request.mode !== undefined ? { mode: request.mode } : {}),
+  };
+}
+
+/**
+ * Group one request's items by the file each edits: an item's own `file` when it names one, else the
+ * request's top-level `file`. Groups keep first-appearance order, so the call's FIRST item names the
+ * primary file.
+ *
+ * WHY resolved paths as the key: `./a.ts` and `a.ts` are one file (§9.4), and every per-file
+ * mechanism this plan reuses — lease resolution, the batch-span gate, undo, the served commit —
+ * keys on the resolved identity.
+ */
+async function groupItemsByTarget(
+  request: NormalizedEditRequest,
+  cwd: string,
+): Promise<TargetGroup[]> {
+  const groups: TargetGroup[] = [];
+  const byKey = new Map<string, TargetGroup>();
+  for (let index = 0; index < request.edits.length; index++) {
+    const item = request.edits[index]!;
+    const file = item.file ?? request.file;
+    const key = await resolveTarget(toCwd(file, cwd));
+    let group = byKey.get(key);
+    if (group === undefined) {
+      group = { key, file, items: [], numbers: [] };
+      byKey.set(key, group);
+      groups.push(group);
+    }
+    group.items.push(item);
+    group.numbers.push(index);
+  }
+  return groups;
+}
+
+/**
+ * Fold every foreign `cut`'s retirement into the group of the file it retires.
+ *
+ * WHY: a cut's source may itself be another target of the same call, and one file must be planned —
+ * and written — exactly once. A source the call does not otherwise edit becomes a group of its own:
+ * exactly the source plan the single-target cut path builds, with its own load, lease verification,
+ * batch-span gate and undo row. The retirement is the ordinary deletion payload over the SUBMITTED
+ * anchors, so it goes through the same parse and the same gates as any other item.
+ */
+async function foldCutRetirements(
+  groups: TargetGroup[],
+  request: NormalizedEditRequest,
+  cwd: string,
+): Promise<TargetGroup[]> {
+  const byKey = new Map(groups.map((group) => [group.key, group] as const));
+  // WHY: snapshot the target groups first — a retirement may ADD a group while this loop runs.
+  const targets = [...groups];
+  for (const group of targets) {
+    for (let local = 0; local < group.items.length; local++) {
+      const item = group.items[local]!;
+      const payload = item.payload;
+      if (payload.kind !== "reference" || payload.mode !== "cut") continue;
+      // WHY: the same predicate and the same item target file the planning pre-pass uses, so the
+      // WHY: two halves cannot disagree about which references are foreign.
+      const refFile = await foreignRefFileOf(item, { cwd, file: group.file });
+      if (refFile === undefined) continue;
+      const key = await resolveTarget(toCwd(refFile, cwd));
+      let source = byKey.get(key);
+      if (source === undefined) {
+        source = { key, file: refFile, items: [], numbers: [] };
+        byKey.set(key, source);
+        groups.push(source);
+      }
+      source.items.push({
+        target: {
+          anchor_from: payload.span.anchor_from,
+          anchor_to: payload.span.anchor_to,
+        },
+        at: "in-place",
+        payload: { kind: "empty" },
+      });
+      source.numbers.push(group.numbers[local]!);
+    }
+  }
+  return groups;
+}
+
+/**
+ * Order groups for planning and writing: the primary (the call's first item's file) first, then the
+ * rest by resolved path.
+ *
+ * WHY the primary leads: it is renamed first and its undo row is the transaction's target row, so
+ * next-run repair reads its POST state to decide "complete the rest" — the cut path's own ordering
+ * rule (ADR-0028), generalized from two files to N.
+ */
+function orderGroups(groups: TargetGroup[]): TargetGroup[] {
+  const [primary, ...rest] = groups;
+  if (primary === undefined) return [];
+  rest.sort((left, right) => (left.key < right.key ? -1 : left.key > right.key ? 1 : 0));
+  return [primary, ...rest];
+}
+
+/** Plan every ordered group: one per-file pass through the existing load → gate → buffer path. */
+async function planGroups(
+  groups: TargetGroup[],
+  request: NormalizedEditRequest,
+  cwd: string,
+  options: PipelineOptions | undefined,
+): Promise<ProcessedEditFile[]> {
+  const plans: ProcessedEditFile[] = [];
+  for (const group of groups) {
+    plans.push(await runMutations(groupRequest(group, request), cwd, options, group.numbers));
+  }
+  return plans;
+}
+
+/**
+ * Plan a multi-file request without persisting, for the preview seam.
+ * @returns one plan per target file in commit order, or `undefined` when the call names a single
+ *   file — the caller then keeps its own single-file preview path.
+ */
+export async function planEditTargets(
+  request: NormalizedEditRequest,
+  cwd: string,
+  options?: PipelineOptions,
+): Promise<ProcessedEditFile[] | undefined> {
+  if (!hasItemFiles(request)) return undefined;
+  const groups = orderGroups(
+    await foldCutRetirements(await groupItemsByTarget(request, cwd), request, cwd),
+  );
+  return await planGroups(groups, request, cwd, { ...options, noPersist: true });
+}
+
 export async function apply(
   request: NormalizedEditRequest,
   cwd: string,
   options?: PipelineOptions,
-): Promise<{
-  result: string;
-  diff: string;
-  drift: string | undefined;
-  metrics: ReturnType<typeof buildBatchResult>["details"]["metrics"];
-  raw: ProcessedEditFile;
-  toolResult: ReturnType<typeof buildBatchResult>;
-}> {
+): Promise<BatchOutcome> {
+  // WHY: the fast path — a request without item-level files is the pre-existing single-file edit
+  // WHY: and takes exactly the code it always took: no grouping round-trip, no extra lock, no intent.
+  if (!hasItemFiles(request)) {
+    return await applySingleFile(request, cwd, options);
+  }
+  const groups = orderGroups(
+    await foldCutRetirements(await groupItemsByTarget(request, cwd), request, cwd),
+  );
+  const primaryGroup = groups[0];
+  if (groups.length === 1 && primaryGroup !== undefined) {
+    // WHY: one item-level file for the whole call — the same single-file machinery, run on the file
+    // WHY: the items name. Items that merely repeat the top-level `file` rebuild the same request.
+    return await applySingleFile(groupRequest(primaryGroup, request), cwd, options);
+  }
+  return await applyMultiFile(groups, request, cwd, options);
+}
+
+/**
+ * Plan and commit several target files as ONE correlated transaction: each file gets its own load,
+ * lease verification, batch-span gate and working buffer, and the write set commits with the same
+ * pre-images, undo rows, intent record and rollback the foreign-cut path uses.
+ *
+ * @param groups - every target group in commit order; `groups[0]` is the primary.
+ * @param request - the admitted call, supplying the mode.
+ * @param cwd - the session working directory every request path resolves against.
+ * @param options - the pipeline options; `noPersist` selects the preview half.
+ * @returns the batch outcome, anchored on the primary file.
+ */
+async function applyMultiFile(
+  groups: TargetGroup[],
+  request: NormalizedEditRequest,
+  cwd: string,
+  options: PipelineOptions | undefined,
+): Promise<BatchOutcome> {
+  if (options?.noPersist === true) {
+    // WHY: no queues for a preview: it writes nothing, which is the single-file preview's own rule.
+    const plans = await planGroups(groups, request, cwd, options);
+    return batchOutcome(plans, buildBatchResult(plans.map((plan) => toSection(plan))));
+  }
+
+  // WHY: (ticket-04b §2) repair before work, exactly as the single-file path does: a previous run
+  // WHY: that crashed inside a correlated window left a durable intent this call resolves first.
+  await repairCutIntents(options?.store);
+  const sessionKey = requireSessionKey(options?.sessionKey);
+
+  // WHY: (ticket-04b §2) the transaction serializes EVERY file it will write, in deterministic
+  // WHY: sorted order (`withSortedMutationQueues`): two calls whose file sets overlap in different
+  // WHY: orders can never deadlock.
+  return await withSortedMutationQueues(
+    groups.map((group) => group.key),
+    async () => {
+      abortIf(options?.signal);
+      const plans = await planGroups(groups, request, cwd, {
+        ...options,
+        sessionKey,
+        accessMode: options?.accessMode ?? constants.R_OK | constants.W_OK,
+      });
+      const writePlans = plans.filter((plan) => plan.appliedCount > 0);
+      if (writePlans.length === 0) {
+        // WHY: an all-noop call writes nothing, so it takes no undo row and no intent — the
+        // WHY: single-file noop contract, over every file the call named.
+        return batchOutcome(plans, buildBatchResult(plans.map((plan) => toSection(plan))));
+      }
+      return await runCorrelatedTransaction(writePlans, plans, options, sessionKey);
+    },
+  );
+}
+
+/**
+ * The single-file path: one target, the call's top-level `file`. Unchanged from before multi-file
+ * edit existed — a request with item-level files whose items all name ONE file is funnelled here
+ * with that file's own request, so this path owns every single-target semantic in one place.
+ */
+async function applySingleFile(
+  request: NormalizedEditRequest,
+  cwd: string,
+  options?: PipelineOptions,
+): Promise<BatchOutcome> {
   const isPreview = options?.noPersist === true;
   if (isPreview) {
     const file = await runMutations(request, cwd, options);
@@ -1516,3 +1981,10 @@ export async function execEdits(
 ): Promise<ProcessedEditFile> {
   return runMutations(request, cwd, options);
 }
+
+/**
+ * Visibility-only export of the correlated transaction for apply_patch's commit seam. The
+ * function body is the one the cut path already uses; apply_patch members carry an optional
+ * lifecycle action read by that body. No engine semantics change.
+ */
+export { runCorrelatedTransaction as commitTransaction };