@visual-z/xeno 0.1.0

package/src/core/derive.ts

@@ -0,0 +1,489 @@
+/**
+ * deriveHandoff: segment events + previous handoff -> next handoff.
+ *
+ * Pure and total. No I/O, no clock, no randomness, no model call. Same inputs
+ * always produce the same object, which is what makes the handoff diffable,
+ * unit-testable and cheap enough that segments can be short (decisions D1, D2).
+ *
+ * Evidence freshness rule: a completion claim must cite an event from the SAME
+ * segment. A gate that passed three segments ago is not proof about code that has
+ * changed since -- that is the stale-evidence problem, so the citation fails.
+ * Verification status, by contrast, carries forward as last-known with its
+ * original timestamp, which is honest about what it is.
+ */
+
+import type {
+  LogEvent, LineRange, NodeRef, EventId, CarryableEvent,
+} from "./events.ts";
+import { CARRYABLE_EVENTS } from "./events.ts";
+import { deriveWorkItems } from "./work-state.ts";
+import { deriveEvidenceLinks } from "./evidence-links.ts";
+import { deriveProgress } from "./progress.ts";
+import { isCommandResult, resolveEvidence, evidenceStale, eligibleProgressChecks } from "./evidence.ts";
+import type { BranchRecord } from "./handoff.ts";
+import {
+  HANDOFF_VERSION,
+  type Handoff, type CompletedItem, type UnverifiedClaim, type InFlightItem,
+  type BlockedItem, type DecisionItem, type PitfallItem, type FileAnchor,
+  type VerificationItem, type UserTurnRecord,
+} from "./handoff.ts";
+
+export interface DeriveConfig {
+  /** Where the agent can grep for anything a cap dropped. */
+  manifestPath: string;
+  maxUserTurns: number;
+  maxUserTurnBytes: number;
+}
+
+/**
+ * Marks the open questions this module generates from branch state, so they
+ * can be rebuilt each derivation instead of accumulating.
+ */
+const UNRESOLVED_BRANCH_PREFIX = "branch ";
+
+export const DEFAULT_DERIVE_CONFIG: DeriveConfig = {
+  manifestPath: "log/manifest.json",
+  maxUserTurns: 200,
+  maxUserTurnBytes: 64_000,
+};
+
+export interface DeriveInput {
+  /** Previous segment's handoff, or null for segment 0. */
+  prev: Handoff | null;
+  /**
+   * Length of the path from the root to this node, inclusive.
+   *
+   * Supplied by the caller rather than derived from a node number, because
+   * allocation order is not an ordering over the tree: a node forked from an
+   * earlier one has a short path and a high number. deriveHandoff is pure and
+   * cannot read the log to count it, but readAncestry already returns
+   * `visited`, so the caller has the length in hand.
+   */
+  depth: number;
+  events: readonly LogEvent[];
+  /** Ref to the segment being closed, recorded as the next segment's predecessor. */
+  self: NodeRef;
+  config?: Partial<DeriveConfig>;
+}
+
+// --- helpers ---------------------------------------------------------------
+
+/** Coalesce overlapping or adjacent ranges into a minimal sorted set. */
+export function mergeRanges(ranges: readonly LineRange[]): LineRange[] {
+  if (ranges.length === 0) return [];
+  const sorted = [...ranges].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+  const out: LineRange[] = [[sorted[0]![0], sorted[0]![1]]];
+  for (let i = 1; i < sorted.length; i++) {
+    const cur = sorted[i]!;
+    const last = out[out.length - 1]!;
+    if (cur[0] <= last[1] + 1) {
+      out[out.length - 1] = [last[0], Math.max(last[1], cur[1])];
+    } else {
+      out.push([cur[0], cur[1]]);
+    }
+  }
+  return out;
+}
+
+/** First occurrence wins, so accumulation across segments is order-stable. */
+function dedupe<T>(items: readonly T[], key: (t: T) => string): T[] {
+  const seen = new Set<string>();
+  const out: T[] = [];
+  for (const it of items) {
+    const k = key(it);
+    if (!seen.has(k)) {
+      seen.add(k);
+      out.push(it);
+    }
+  }
+  return out;
+}
+
+// --- main ------------------------------------------------------------------
+
+export function deriveHandoff(input: DeriveInput): Handoff {
+  const cfg = { ...DEFAULT_DERIVE_CONFIG, ...input.config };
+  const { prev, depth, events } = input;
+
+  // Command results in this segment, in log order. The evidence index and the
+  // verification table are both built from this and nothing else -- exit codes,
+  // never the model's account of them.
+  const commands = events.filter(isCommandResult);
+
+  // -- objective: verbatim, set once, never rewritten -----------------------
+  // Skip user events a later interrupt cancelled: an abandoned prompt is not
+  // what the next segment is doing. If every user event in the segment was
+  // abandoned, keep the last one so EMPTY_OBJECTIVE cannot fire -- the mark
+  // lives on user_turns, not by blanking the field.
+  const abandonedIds = new Set(
+    events.filter((e): e is Extract<LogEvent, { t: "interrupt" }> => e.t === "interrupt")
+      .map((e) => e.user_id),
+  );
+  const users = events.filter((e): e is Extract<LogEvent, { t: "user" }> => e.t === "user");
+  const liveUsers = users.filter((e) => !abandonedIds.has(e.id));
+  const firstUser = liveUsers[0] ?? users.at(-1);
+  const objective = prev?.objective ?? (firstUser !== undefined ? firstUser.text : "");
+
+  // -- user turns: all of them, verbatim, accumulated ----------------------
+  // Abandoned turns stay: deleting them would rewrite history. The interrupt
+  // is a later record, so the mark is derived here rather than written back
+  // onto the user event (D8).
+  const newTurns: UserTurnRecord[] = users.map((e) => ({
+    at: e.at,
+    text: e.text,
+    ...(abandonedIds.has(e.id) ? { abandoned: true as const } : {}),
+  }));
+  const userTurns: UserTurnRecord[] = [...(prev?.user_turns ?? []), ...newTurns];
+
+  let dropped = prev?.user_turns_truncated?.dropped ?? 0;
+  // Drop oldest first: the very first turn survives in `objective` regardless.
+  while (
+    userTurns.length > cfg.maxUserTurns ||
+    (userTurns.length > 1 &&
+      userTurns.reduce((n, t) => n + t.text.length, 0) > cfg.maxUserTurnBytes)
+  ) {
+    userTurns.shift();
+    dropped++;
+  }
+
+  // -- completion claims resolved against the log --------------------------
+  const newCompleted: CompletedItem[] = [];
+  const unverified: UnverifiedClaim[] = [];
+
+  for (let i = 0; i < events.length; i++) {
+    const e = events[i]!;
+    if (e.t !== "claim" || e.work_id !== undefined) continue;
+    // Resolve against the most recent match AT OR BEFORE the claim. A claim is a
+    // statement about evidence available when it was made, so a later run must not
+    // retroactively change it -- that non-locality would mean appending an event
+    // could silently rewrite an earlier conclusion. Whether the gate is red *now*
+    // is separate information, carried by `verification` and repeated inline as
+    // `evidence_superseded` below.
+    const resolved = resolveEvidence(events.slice(0, i), e.evidence);
+    if (resolved.ok) newCompleted.push({ what: e.what, evidence: resolved.evidence });
+    else unverified.push({ what: e.what, claimed: e.evidence, reason: resolved.reason,
+      ...(resolved.exit !== undefined ? { exit: resolved.exit } : {}) });
+  }
+
+  const workItems = deriveWorkItems(prev?.state.work_items ?? [], events);
+  const identifiedCompleted: CompletedItem[] = workItems.flatMap(item => item.status === "completed" && item.evidence
+    ? [{ work_id: item.id, what: item.what, evidence: item.evidence }] : []);
+  const legacyCompleted = dedupe([...(prev?.state.completed ?? []).filter(item => item.work_id === undefined), ...newCompleted], c => c.what);
+  const completed = [...legacyCompleted, ...identifiedCompleted];
+  const completedSet = new Set(legacyCompleted.map(c => c.what));
+
+  // -- in flight: latest note per item wins --------------------------------
+  const inFlightMap = new Map<string, InFlightItem>();
+  for (const i of prev?.state.in_flight ?? []) if (i.work_id === undefined) inFlightMap.set(i.what, i);
+  for (const e of events) {
+    if (e.t === "next_action" && e.work_id === undefined) inFlightMap.set(e.what, { what: e.what, next_action: e.next_action });
+  }
+
+  // -- blocked -------------------------------------------------------------
+  const blockedItems: BlockedItem[] = [
+    ...(prev?.state.blocked ?? []).filter(item => item.work_id === undefined),
+    ...events.filter((e): e is Extract<LogEvent, { t: "blocked" }> => e.t === "blocked" && e.work_id === undefined)
+      .map((e) => ({ what: e.what, reason: e.reason })),
+  ];
+  const legacyBlocked = dedupe(blockedItems, b => b.what).filter(b => !completedSet.has(b.what));
+  const blocked = [...legacyBlocked, ...workItems.filter(item => item.status === "blocked")
+    .map(item => ({ work_id: item.id, what: item.what, reason: item.reason ?? "blocked" }))];
+  const blockedSet = new Set(legacyBlocked.map(b => b.what));
+
+  // Completed beats blocked beats in-flight, so an item never appears twice.
+  const inFlight = [...inFlightMap.values()].filter(
+    (i) => !completedSet.has(i.what) && !blockedSet.has(i.what),
+  ).concat(workItems.filter(item => item.status === "active")
+    .map(item => ({ work_id: item.id, what: item.what, next_action: item.next_action ?? "" })));
+
+  // -- branches: what this node opened, and what became of it --------------
+  //
+  // Spawn creates the record; joined attaches the reference; adopt and
+  // discard resolve it. An unresolved branch stays visible rather than
+  // silently accumulating, which is the whole of D16.
+  const branchMap = new Map<number, BranchRecord>();
+  for (const b of prev?.branches ?? []) branchMap.set(b.node, b);
+  for (const e of events) {
+    if (e.t === "spawn") {
+      branchMap.set(e.branch.node, {
+        node: e.branch.node,
+        spawned_at: e.id,
+        purpose: e.purpose,
+        resolution: null,
+      });
+      continue;
+    }
+    if (e.t !== "joined" && e.t !== "adopt" && e.t !== "discard") continue;
+    // A lifecycle event for a branch this node never spawned still records
+    // the branch: dropping it would hide a branch that exists.
+    const existing = branchMap.get(e.branch.node) ?? {
+      node: e.branch.node,
+      spawned_at: e.id,
+      purpose: "(spawn not recorded in this node)",
+      resolution: null,
+    };
+    if (e.t === "joined") {
+      branchMap.set(e.branch.node, {
+        ...existing,
+        handoff_ref: e.handoff_ref,
+        summary: e.summary,
+        ...(e.outcome ? { outcome: e.outcome } : {}),
+      });
+    } else {
+      branchMap.set(e.branch.node, {
+        ...existing,
+        resolution: e.t === "adopt" ? "merged" : "discarded",
+      });
+    }
+  }
+  const branches = [...branchMap.values()].sort((a, b) => a.node - b.node);
+
+  // -- decisions / pitfalls / questions ------------------------------------
+  const decisions = dedupe<DecisionItem>(
+    [
+      ...(prev?.decisions ?? []),
+      ...events.filter((e): e is Extract<LogEvent, { t: "decision" }> => e.t === "decision")
+        .map((e) => ({
+          chose: e.chose, because: e.because,
+          ...(e.rejected !== undefined ? { rejected: e.rejected } : {}),
+        })),
+    ],
+    (d) => JSON.stringify([d.chose, d.because]),
+  );
+
+  const pitfalls = dedupe<PitfallItem>(
+    [
+      ...(prev?.pitfalls ?? []),
+      ...events.filter((e): e is Extract<LogEvent, { t: "pitfall" }> => e.t === "pitfall")
+        .map((e) => ({ tried: e.tried, failed_because: e.failed_because })),
+    ],
+    (p) => JSON.stringify([p.tried, p.failed_because]),
+  );
+
+  const openQuestions = dedupe(
+    [
+      ...(prev?.open_questions ?? []).filter((q) => !q.startsWith(UNRESOLVED_BRANCH_PREFIX)),
+      ...events.filter((e): e is Extract<LogEvent, { t: "question" }> => e.t === "question")
+        .map((e) => e.text),
+      // Rebuilt from the current branch state each time rather than carried,
+      // so resolving a branch removes its question instead of leaving a stale
+      // one behind. The text names the node and the handoff so the next
+      // context can go read it rather than only learning that it exists.
+      ...branches
+        .filter((b) => b.resolution === null)
+        .map((b) =>
+          `${UNRESOLVED_BRANCH_PREFIX}${b.node} (${b.purpose}) is unresolved` +
+          `${b.handoff_ref ? `; it joined with ${b.handoff_ref}` : "; it has not joined yet"}` +
+          ` -- adopt it or discard it`,
+        ),
+    ],
+    (q) => q,
+  );
+
+  // -- file anchors: reference plus fingerprint, never content -------------
+  const anchors = new Map<string, {
+    path: string; sha256: string; ranges: LineRange[]; touched: Set<"read" | "edit">; stale?: true;
+  }>();
+  for (const a of prev?.file_anchors ?? []) {
+    anchors.set(a.path, {
+      path: a.path, sha256: a.sha256,
+      ranges: [...(a.read_ranges ?? [])], touched: new Set(a.touched),
+      ...(a.stale ? { stale: true } : {}),
+    });
+  }
+  for (const e of events) {
+    if (e.t === "snapshot") {
+      for (const [path, anchor] of anchors) {
+        const now = e.changed[path] ?? e.added[path];
+        if (e.removed.includes(path) || (now !== undefined && now !== anchor.sha256)) anchor.stale = true;
+        else if (now === anchor.sha256) delete anchor.stale;
+      }
+    }
+    if (e.t !== "tool_result" || !e.effect) continue;
+    const eff = e.effect;
+    if (eff.kind === "read") {
+      const cur = anchors.get(eff.path) ?? {
+        path: eff.path, sha256: eff.sha256, ranges: [], touched: new Set<"read" | "edit">(),
+      };
+      cur.sha256 = eff.sha256;
+      delete cur.stale;
+      cur.ranges.push(...(eff.ranges ?? []));
+      cur.touched.add("read");
+      anchors.set(eff.path, cur);
+    } else if (eff.kind === "edit") {
+      const cur = anchors.get(eff.path) ?? {
+        path: eff.path, sha256: eff.sha256_after, ranges: [], touched: new Set<"read" | "edit">(),
+      };
+      cur.sha256 = eff.sha256_after;
+      delete cur.stale;
+      cur.touched.add("edit");
+      anchors.set(eff.path, cur);
+    }
+  }
+  const fileAnchors: FileAnchor[] = [...anchors.values()]
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+    .map((a) => {
+      const merged = mergeRanges(a.ranges);
+      return {
+        path: a.path, sha256: a.sha256,
+        ...(a.stale ? { stale: true } : {}),
+        ...(merged.length > 0 ? { read_ranges: merged } : {}),
+        touched: (["read", "edit"] as const).filter((k) => a.touched.has(k)),
+      };
+    });
+
+  // -- verification: last run per gate; unrun gates stay not_run -----------
+  const gateState = new Map<string, VerificationItem>();
+  for (const item of prev?.verification ?? []) gateState.set(item.gate, { ...item });
+  for (const c of commands) {
+    const gate = c.effect.gate;
+    if (gate === undefined) continue;
+    gateState.set(gate, {
+      gate, status: c.effect.exit === 0 ? "pass" : "fail", at: c.at, exit: c.effect.exit,
+      ...(c.effect.workspace_sha256 ? { workspace_sha256: c.effect.workspace_sha256 } : {}),
+    });
+  }
+  const verification = [...gateState.values()].sort((a, b) =>
+    a.gate < b.gate ? -1 : a.gate > b.gate ? 1 : 0,
+  );
+  for (const item of verification) {
+    const hit = commands.filter((c) => c.effect.gate === item.gate).at(-1);
+    if (evidenceStale(events, { command: hit?.effect.cmd ?? "", event_id: hit?.id ?? "", at: item.at ?? "", exit: item.exit ?? -1,
+      ...(item.workspace_sha256 ? { workspace_sha256: item.workspace_sha256 } : {}),
+    }, item.stale)) item.stale = true;
+    else delete item.stale;
+  }
+
+  // -- mark completions whose gate has since gone red -------------------------
+  const failingGates = new Map(
+    verification.filter((v) => v.status === "fail").map((v) => [v.gate, v]),
+  );
+  const completedMarked: CompletedItem[] = completed.map((original) => {
+    const { evidence_stale: _old, ...base } = original;
+    const item: CompletedItem = evidenceStale(events, original.evidence, original.evidence_stale)
+      ? { ...base, evidence_stale: true } : base;
+    const gate = item.evidence.gate;
+    const failing = gate === undefined ? undefined : failingGates.get(gate);
+    if (!failing) {
+      // Drop any stale marker: the gate went green again.
+      const { evidence_superseded: _drop, ...rest } = item;
+      return rest;
+    }
+    return {
+      ...item,
+      evidence_superseded: {
+        gate: failing.gate,
+        status: "fail" as const,
+        ...(failing.exit !== undefined ? { exit: failing.exit } : {}),
+        ...(failing.at !== undefined ? { at: failing.at } : {}),
+      },
+    };
+  });
+
+  // -- last activity: derived, so it is present even with zero annotations --
+  let lastActivity: string | null = null;
+  for (const e of events) {
+    if (e.t === "tool_result" && e.effect) {
+      const eff = e.effect;
+      lastActivity =
+        eff.kind === "command" ? `ran ${eff.cmd} (exit ${eff.exit})`
+        : eff.kind === "edit" ? `edited ${eff.path}`
+        : `read ${eff.path}`;
+    } else if (e.t === "assistant") {
+      const text = e.blocks.find((b) => b.type === "text");
+      if (text && text.type === "text" && text.text.trim()) {
+        lastActivity = firstLine(text.text);
+      }
+    }
+  }
+  if (lastActivity === null) lastActivity = prev?.state.last_activity ?? null;
+
+  // -- progress (decision D9) ----------------------------------------------
+  const eligibleChecks = eligibleProgressChecks(events, new Set([...newCompleted, ...identifiedCompleted].map(item => item.evidence.event_id)), failingGates);
+  // A bounded view is presentation, not derivation input. Refuse to forget an
+  // omitted ledger, which would make old observations appear new after a cut.
+  if (prev?.history && Object.values(prev.history.sections).some((range) => range.offset > 0)) {
+    throw new Error("deriveHandoff requires full replay state, not a paginated handoff");
+  }
+  const progress = deriveProgress(prev?.progress_evidence ?? [], events, input.self.node, eligibleChecks);
+  const links = deriveEvidenceLinks(prev?.evidence_links ?? [], events);
+
+  const hasRemaining = inFlight.length > 0 || blocked.length > 0 || openQuestions.length > 0;
+  const hasNextAction = inFlight.some((i) => i.next_action.trim().length > 0);
+
+  return {
+    handoff_version: HANDOFF_VERSION,
+    predecessor: input.self,
+    objective,
+    user_turns: userTurns,
+    ...(dropped > 0
+      ? { user_turns_truncated: { dropped, recover_from: [cfg.manifestPath] } }
+      : {}),
+    state: {
+      ...(workItems.length > 0 ? { work_items: workItems } : {}),
+      completed: completedMarked,
+      unverified_claims: dedupe([...(prev?.state.unverified_claims ?? []), ...unverified], (c) => JSON.stringify(c))
+        .filter((c) => !completedSet.has(c.what)),
+      in_flight: inFlight,
+      blocked,
+      last_activity: lastActivity,
+    },
+    decisions,
+    pitfalls,
+    file_anchors: fileAnchors,
+    verification,
+    branches,
+    open_questions: openQuestions,
+    progress_evidence: progress.evidence,
+    ...(links.length > 0 ? { evidence_links: links } : {}),
+    continuation_valid: hasRemaining && hasNextAction,
+    budget: {
+      nodes_on_path: depth,
+      nodes_without_progress: progress.progressed
+        ? 0
+        : (prev?.budget.nodes_without_progress ?? 0) + 1,
+    },
+  };
+}
+
+function firstLine(s: string): string {
+  const line = s.trim().split("\n")[0] ?? "";
+  return line.length > 200 ? line.slice(0, 197) + "..." : line;
+}
+
+/**
+ * Events an adopt carries into the node it opens.
+ *
+ * Adopting a branch replaces the mainline with it, and the branch's ancestry
+ * stops at the fork point -- so everything the parent recorded after forking
+ * is outside it, including the decision that chose the branch. That is the
+ * least disposable record in the log, so it is carried rather than lost.
+ *
+ * Only annotations are carried. Harness events are either already in the
+ * branch's ancestry (before the fork) or are parent actions the branch never
+ * saw and should not inherit. Carrying annotations is free in context terms
+ * because they never replay as messages; only derivation reads them.
+ *
+ * A fork point that is not in `events` carries nothing, rather than falling
+ * back to all of them: an unknown fork point means the caller's picture of
+ * the tree is wrong, and carrying everything would silently duplicate work
+ * the branch already has.
+ */
+export function carryForward(
+  events: readonly LogEvent[],
+  since: EventId,
+  fromNode = 0,
+): CarryableEvent[] {
+  const at = events.findIndex((e) => e.id === since);
+  if (at < 0) return [];
+  const carryable = new Set<string>(CARRYABLE_EVENTS);
+  return events
+    .slice(at + 1)
+    .filter((e): e is CarryableEvent => carryable.has(e.t))
+    .map((e) => ({
+      ...e,
+      // Provenance, so the handoff can tell what this node produced from what
+      // it inherited through an adopt.
+      carried_from: e.carried_from ?? { node: fromNode, event: e.id },
+    }));
+}

package/src/core/edit-plan.ts

@@ -0,0 +1,200 @@
+/**
+ * O.3: exact edits remain exact; a loose match is never silent.
+ *
+ * planEdit is the original single exact replacement and stays as it was.
+ * planEdits is what the tool uses: several edits, matched on the view read
+ * shows (see text-normalize.ts), with a loose fallback that is reported as
+ * such in the result rather than applied quietly.
+ */
+import { editDistance, fromView, normalizeLoose, similarity, toLF, toView } from "./text-normalize.ts";
+
+export function lineDiff(before: string, after: string): { diff: string; firstLine: number } {
+  const a = before.split("\n"), b = after.split("\n");
+  let prefix = 0, suffix = 0;
+  while (prefix < a.length && prefix < b.length && a[prefix] === b[prefix]) prefix++;
+  while (suffix < a.length - prefix && suffix < b.length - prefix && a[a.length - suffix - 1] === b[b.length - suffix - 1]) suffix++;
+  const removed = a.slice(prefix, a.length - suffix), added = b.slice(prefix, b.length - suffix);
+  return { firstLine: prefix + 1,
+    diff: before === after ? "(content unchanged)" : `@@ -${prefix + 1},${removed.length} +${prefix + 1},${added.length} @@\n` +
+      [...removed.map(line => `-${line}`), ...added.map(line => `+${line}`)].join("\n") };
+}
+
+export function planEdit(before: string, oldText: string, newText: string, all: boolean):
+  { ok: true; after: string; replacements: number; diff: string; firstLine: number } |
+  { ok: false; code: "invalid_input" | "not_found" | "ambiguous_edit"; occurrences: number } {
+  if (!oldText) return { ok: false, code: "invalid_input", occurrences: 0 };
+  const occurrences = before.split(oldText).length - 1;
+  if (occurrences === 0) return { ok: false, code: "not_found", occurrences };
+  if (occurrences > 1 && !all) return { ok: false, code: "ambiguous_edit", occurrences };
+  // split/join avoids replacement-string interpolation of literal $&, $` or $'.
+  const at = before.indexOf(oldText);
+  const after = all ? before.split(oldText).join(newText) : before.slice(0, at) + newText + before.slice(at + oldText.length);
+  const a = before.split("\n"), b = after.split("\n");
+  let prefix = 0, suffix = 0;
+  while (prefix < a.length && prefix < b.length && a[prefix] === b[prefix]) prefix++;
+  while (suffix < a.length - prefix && suffix < b.length - prefix && a[a.length - suffix - 1] === b[b.length - suffix - 1]) suffix++;
+  const removed = a.slice(prefix, a.length - suffix), added = b.slice(prefix, b.length - suffix);
+  return { ok: true, after, replacements: all ? occurrences : 1, firstLine: prefix + 1,
+    diff: before === after ? "(content unchanged)" : `@@ -${prefix + 1},${removed.length} +${prefix + 1},${added.length} @@\n` +
+      [...removed.map(line => `-${line}`), ...added.map(line => `+${line}`)].join("\n") };
+}
+
+
+export interface EditSpec { old_string: string; new_string: string; replace_all?: boolean }
+
+export interface ClosestMatch {
+  /** 1-indexed, inclusive, in the view read shows. */
+  startLine: number;
+  endLine: number;
+  score: number;
+  /** First line of old_string that differs from the file, and the file's line there. */
+  expected: string;
+  actual: string;
+}
+
+export type EditsPlan =
+  | { ok: true; after: string; replacements: number; fuzzy: boolean; diff: string; firstLine: number }
+  | { ok: false; code: "invalid_input" | "not_found" | "ambiguous_edit"; edit: number; occurrences: number;
+      message: string; closest?: ClosestMatch };
+
+/** A replacement in view coordinates: [start, end) becomes text. */
+interface Span { start: number; end: number; text: string; edit: number }
+
+function occurrences(haystack: string, needle: string): number[] {
+  const found: number[] = [];
+  for (let at = haystack.indexOf(needle); at !== -1; at = haystack.indexOf(needle, at + needle.length)) found.push(at);
+  return found;
+}
+
+/** Offsets of each line start in `text`, plus a sentinel one past the end. */
+function lineStarts(text: string): number[] {
+  const starts = [0];
+  for (let i = 0; i < text.length; i++) if (text[i] === "\n") starts.push(i + 1);
+  starts.push(text.length + 1);
+  return starts;
+}
+
+const lineOf = (starts: readonly number[], offset: number) => {
+  let lo = 0, hi = starts.length - 2;
+  while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid]! <= offset) lo = mid; else hi = mid - 1; }
+  return lo;
+};
+
+/**
+ * Loose matches mapped back onto whole original lines.
+ *
+ * normalizeLoose keeps the line count, so a match starting on normalized line
+ * i covers original lines i..j. Those lines -- and only those -- are replaced
+ * by their normalized form with the substitution applied. Rewriting the whole
+ * normalized file instead would quietly straighten every quote in it.
+ */
+function looseSpans(text: string, spec: { old: string; next: string; all: boolean }, edit: number):
+  { spans: Span[] } | { count: number } {
+  const loose = normalizeLoose(text);
+  const needle = normalizeLoose(spec.old);
+  if (needle.trim().length === 0) return { count: 0 };
+  const found = occurrences(loose, needle);
+  if (found.length === 0 || (found.length > 1 && !spec.all)) return { count: found.length };
+  const looseStarts = lineStarts(loose), starts = lineStarts(text);
+  const spans: Span[] = [];
+  for (const at of found) {
+    const first = lineOf(looseStarts, at), last = lineOf(looseStarts, at + needle.length - 1);
+    const from = looseStarts[first]!, to = looseStarts[last + 1]! - 1;
+    const segment = loose.slice(from, to);
+    const local = at - from;
+    spans.push({ start: starts[first]!, end: starts[last + 1]! - 1, edit,
+      text: segment.slice(0, local) + spec.next + segment.slice(local + needle.length) });
+  }
+  return { spans };
+}
+
+/**
+ * Where old_string most nearly occurs, for a failure message that lets the
+ * model fix its copy instead of rereading the file (omp reports the same:
+ * `crates/pi-edit/src/fuzzy.rs`). Candidates are anchored on lines of
+ * old_string that occur verbatim (trimmed); failing that, on the most similar
+ * single line, which is only computed for files small enough to afford it.
+ */
+export function closestMatch(text: string, old: string): ClosestMatch | undefined {
+  const lines = text.split("\n");
+  const want = old.split("\n");
+  if (want.length > lines.length) return undefined;
+  const clip = (line: string) => line.trim().slice(0, 200);
+  const starts = new Set<number>();
+  const index = new Map<string, number[]>();
+  lines.forEach((line, i) => { const key = clip(line); if (key.length >= 4) index.set(key, [...(index.get(key) ?? []), i]); });
+  want.forEach((line, k) => {
+    for (const i of index.get(clip(line)) ?? []) if (i - k >= 0 && i - k + want.length <= lines.length) starts.add(i - k);
+  });
+  if (starts.size === 0 && lines.length <= 5_000) {
+    const anchor = want.findIndex((line) => clip(line).length > 0);
+    if (anchor === -1) return undefined;
+    const target = clip(want[anchor]!).slice(0, 80);
+    let best = -1, bestScore = 0;
+    lines.forEach((line, i) => {
+      const candidate = clip(line).slice(0, 80);
+      if (Math.abs(candidate.length - target.length) > target.length / 2) return;
+      const score = similarity(candidate, target);
+      if (score > bestScore && i - anchor >= 0 && i - anchor + want.length <= lines.length) { best = i - anchor; bestScore = score; }
+    });
+    if (best >= 0) starts.add(best);
+  }
+  let result: ClosestMatch | undefined;
+  const block = want.join("\n").slice(0, 2_000);
+  for (const start of [...starts].slice(0, 20)) {
+    const window = lines.slice(start, start + want.length);
+    const score = 1 - editDistance(window.join("\n").slice(0, 2_000), block) / Math.max(1, Math.max(block.length, window.join("\n").slice(0, 2_000).length));
+    if (result !== undefined && score <= result.score) continue;
+    const differs = want.findIndex((line, k) => line !== window[k]);
+    result = { startLine: start + 1, endLine: start + want.length, score,
+      expected: want[Math.max(0, differs)] ?? "", actual: window[Math.max(0, differs)] ?? "" };
+  }
+  return result !== undefined && result.score >= 0.5 ? result : undefined;
+}
+
+/**
+ * Several edits, all located in the original before any is applied, so one
+ * edit can never match text another just wrote. All succeed or none do.
+ */
+export function planEdits(raw: string, edits: readonly EditSpec[]): EditsPlan {
+  const view = toView(raw);
+  const text = view.text;
+  if (edits.length === 0) return { ok: false, code: "invalid_input", edit: 0, occurrences: 0, message: "no edits given" };
+  const spans: Span[] = [];
+  let fuzzy = false;
+  for (let e = 0; e < edits.length; e++) {
+    const spec = { old: toLF(edits[e]!.old_string), next: toLF(edits[e]!.new_string), all: edits[e]!.replace_all === true };
+    const which = edits.length > 1 ? `edit ${e + 1}: ` : "";
+    if (spec.old.length === 0) return { ok: false, code: "invalid_input", edit: e, occurrences: 0, message: `${which}old_string must not be empty` };
+    const exact = occurrences(text, spec.old);
+    if (exact.length > 1 && !spec.all) {
+      return { ok: false, code: "ambiguous_edit", edit: e, occurrences: exact.length,
+        message: `${which}old_string appears ${exact.length} times; add surrounding lines to make it unique or pass replace_all` };
+    }
+    if (exact.length > 0) {
+      for (const at of exact) spans.push({ start: at, end: at + spec.old.length, text: spec.next, edit: e });
+      continue;
+    }
+    const loose = looseSpans(text, spec, e);
+    if ("spans" in loose) { spans.push(...loose.spans); fuzzy = true; continue; }
+    if (loose.count > 1) {
+      return { ok: false, code: "ambiguous_edit", edit: e, occurrences: loose.count,
+        message: `${which}old_string has no exact match and ${loose.count} matches ignoring whitespace and quote style; add surrounding lines to make it unique` };
+    }
+    const closest = closestMatch(text, spec.old);
+    return { ok: false, code: "not_found", edit: e, occurrences: 0,
+      message: `${which}old_string not found` + (closest === undefined ? "; read the current file before retrying" : ""),
+      ...(closest === undefined ? {} : { closest }) };
+  }
+  spans.sort((a, b) => a.start - b.start);
+  for (let i = 1; i < spans.length; i++) {
+    if (spans[i]!.start < spans[i - 1]!.end) {
+      return { ok: false, code: "invalid_input", edit: spans[i]!.edit, occurrences: 0,
+        message: `edits ${spans[i - 1]!.edit + 1} and ${spans[i]!.edit + 1} overlap; merge them into one edit` };
+    }
+  }
+  let after = text;
+  for (let i = spans.length - 1; i >= 0; i--) after = after.slice(0, spans[i]!.start) + spans[i]!.text + after.slice(spans[i]!.end);
+  if (after === text) return { ok: false, code: "invalid_input", edit: 0, occurrences: 0, message: "no change: new_string produces the current content" };
+  return { ok: true, after: fromView(view, after), replacements: spans.length, fuzzy, ...lineDiff(text, after) };
+}