dsh-hashline-edit 0.1.0 → 0.2.0

package/src/apply-patch/tool.ts

@@ -0,0 +1,257 @@
+/**
+ * apply_patch v4 — tool use case.
+ *
+ * The deep module the dsh host adapter calls. One `execute` owns the whole pipeline for one call:
+ *
+ *   grammar.parseApplyPatch → plan.planApplyPatch → commit.commitPlan → render
+ *
+ * and returns the model-facing `{ content, details }` envelope. A rejection carries the rendered
+ * `[E_*]` envelope and is marked `isError`; nothing was written because plan/grammar own every
+ * pre-commit check and commit rolls back or reports its recovery report.
+ *
+ * The orchestration deps are injectable so the transaction lane can test the complete
+ * parse→plan→commit→render path before the grammar/resolve lanes merge into this branch.
+ *
+ * @module dsh-hashline-edit/apply-patch/tool
+ */
+import { parseApplyPatch, type ParsePatchOptions } from "./grammar.js";
+import { planApplyPatch, type PlanApplyPatchOptions } from "./plan.js";
+import { commitPlan, type CommitPlanOptions, type CommitPlanResult } from "./commit.js";
+import { renderFailure, renderSuccess } from "./render.js";
+import type {
+  ApplyPatchContext,
+  ApplyPatchFailure,
+  ApplyPatchSuccess,
+  ApplyPatchToolResult,
+  AppliedFileSummary,
+  PatchPlan,
+  PatchProblem,
+  PlanPatchResult,
+  ServedFileBlock,
+} from "./types.js";
+import { attachEnvelope } from "../error-envelope.js";
+import type { DomainErrorCode } from "../domain-errors.js";
+import { DomainError } from "../domain-errors.js";
+import { decodeNormText } from "../file-content/index.js";
+import { defaultHashIdentity } from "../hashline/hash-identity.js";
+import { loadHashStore } from "../hash-store.js";
+import { reportDiagnostic } from "../diagnostics.js";
+import { createSessionHandle } from "../served-session/session.js";
+import { snapshotHashFor, snapshotIOFor } from "../snapshot-store/index.js";
+
+/** The registered tool name; `apply_patch` is the only mutation entry point. */
+export const APPLY_PATCH_TOOL_NAME = "apply_patch";
+
+/** The use-case seam: one narrow interface over the pipeline. */
+export interface ApplyPatchTool {
+  /**
+   * Execute one apply_patch call.
+   * @param input - the raw patch text.
+   * @param ctx - live cwd, session identity and cancellation.
+   * @returns the model-facing envelope; `isError` marks a rejection (nothing written).
+   */
+  execute(input: string, ctx: ApplyPatchContext): Promise<ApplyPatchToolResult>;
+
+  /**
+   * Parse + plan without writing, for previews and tests.
+   * @param input - the raw patch text.
+   * @param ctx - live cwd, session identity and cancellation.
+   * @returns the plan or every collected problem.
+   */
+  plan(input: string, ctx: ApplyPatchContext): Promise<PlanPatchResult>;
+}
+
+/** The injectable seams of the pipeline; production uses the real modules. */
+export interface ApplyPatchToolDeps {
+  readonly parse?: (
+    input: string,
+    options?: ParsePatchOptions,
+  ) => ReturnType<typeof parseApplyPatch>;
+  readonly plan?: (
+    document: Parameters<typeof planApplyPatch>[0],
+    options: PlanApplyPatchOptions,
+  ) => ReturnType<typeof planApplyPatch>;
+  readonly commit?: (plan: PatchPlan, options: CommitPlanOptions) => Promise<CommitPlanResult>;
+  readonly renderSuccess?: typeof renderSuccess;
+  readonly renderFailure?: typeof renderFailure;
+}
+
+/** Aggregate a pre-commit rejection into the shared failure shape (no served rows at this seam). */
+function failureFromProblems(
+  problems: readonly PatchProblem[],
+  served: readonly ServedFileBlock[] = [],
+): ApplyPatchFailure {
+  const first = problems[0];
+  return {
+    ok: false,
+    code: first?.code ?? "E_PATCH_SYNTAX",
+    message:
+      "nothing changed (" + problems.length + " problem" + (problems.length === 1 ? "" : "s") + ")",
+    problems,
+    served,
+    changedNothing: true,
+  };
+}
+
+/**
+ * Throw the shared rejection envelope: rendered text in the message, code/servedRows/servedBlock
+ * on the error object. This is the exact shape `dsh/tools/errors.ts` reads to build DshToolError —
+ * the host adapter has one failure path (throw), never an in-band isError branch.
+ */
+function throwRejection(failure: ApplyPatchFailure, rendered: ApplyPatchToolResult): never {
+  const text = rendered.content.map((entry) => entry.text).join("\n");
+  const servedRows = failure.served.flatMap((block) => [...block.rows]);
+  const servedBlock = failure.served.map((block) => block.text).join("\n");
+  // WHY: the two apply_patch codes are registered in the shared domain registry, so the tool can
+  // WHY: throw the real DomainError (rendered [MODEL] [E_*] header + envelope fields) exactly like
+  // WHY: every other refusal. Other registry codes fall through to the envelope-only throw below
+  // WHY: because their payload shapes are owned by their producers.
+  if (failure.code === "E_PATCH_SYNTAX") {
+    throw new DomainError("E_PATCH_SYNTAX", {
+      message: text,
+      ...(servedRows.length > 0 ? { servedRows } : {}),
+      ...(servedBlock !== "" ? { servedBlock } : {}),
+    });
+  }
+  if (failure.code === "E_UNIQUE_MATCH") {
+    throw new DomainError("E_UNIQUE_MATCH", {
+      message: text,
+      ...(servedRows.length > 0 ? { servedRows } : {}),
+      ...(servedBlock !== "" ? { servedBlock } : {}),
+    });
+  }
+  if (failure.code === "E_STALE_ANCHOR") {
+    throw new DomainError("E_STALE_ANCHOR", {
+      headline: text,
+      cause: "anchor staleness",
+      ...(servedRows.length > 0 ? { servedRows } : {}),
+      ...(servedBlock !== "" ? { servedBlock } : {}),
+    });
+  }
+  const error = new Error(text);
+  attachEnvelope(error, {
+    code: failure.code as DomainErrorCode,
+    ...(servedRows.length > 0 ? { servedRows } : {}),
+    ...(servedBlock !== "" ? { servedBlock } : {}),
+  });
+  throw error;
+}
+
+/**
+ * Make a rejection's served rows real served rows: materialize the current file snapshot, then
+ * record the rows through the session handle so every returned HASH│content anchor carries a
+ * session+file lease (and the canon evidence derived from it). A retry can then use those anchors
+ * without a read; a failure here never replaces the original rejection.
+ */
+async function recordRejectionServes(
+  blocks: readonly ServedFileBlock[],
+  ctx: ApplyPatchContext,
+): Promise<void> {
+  if (blocks.length === 0) return;
+  let store;
+  try {
+    store = await loadHashStore();
+  } catch (error) {
+    reportDiagnostic("apply-patch", "Failed to open the store for rejection serves:", error);
+    return;
+  }
+  for (const block of blocks) {
+    if (block.rows.length === 0) continue;
+    try {
+      const normalized = await decodeNormText(
+        block.path,
+        ctx.cwd,
+        ctx.signal === undefined ? undefined : { signal: ctx.signal },
+      );
+      const hashes = await defaultHashIdentity.hashesFor(normalized.normalized, {
+        path: normalized.absolutePath,
+        persist: true,
+        snapshotIO: snapshotIOFor(store),
+      });
+      const rows = block.rows.filter((row) => hashes[row.position] === row.hash);
+      if (rows.length === 0) continue;
+      const handle = createSessionHandle(ctx.sessionKey, normalized.absolutePath, store);
+      await handle.recordServeFeedback(
+        [...rows],
+        "live",
+        undefined,
+        snapshotHashFor(normalized.normalized),
+      );
+    } catch (error) {
+      reportDiagnostic("apply-patch", "Failed to record rejection served rows:", error);
+    }
+  }
+}
+
+/** Project the committed facts plus plan stats into the success result the renderer formats. */
+function successFrom(
+  plan: PatchPlan,
+  committed: Extract<CommitPlanResult, { ok: true }>,
+): ApplyPatchSuccess {
+  const files: AppliedFileSummary[] = committed.files.map((file) => ({
+    status: file.status,
+    path: file.path,
+    ...(file.fromPath !== undefined ? { fromPath: file.fromPath } : {}),
+    addedLines: file.addedLines,
+    removedLines: file.removedLines,
+  }));
+  const addedLines = files.reduce((total, file) => total + file.addedLines, 0);
+  const removedLines = files.reduce((total, file) => total + file.removedLines, 0);
+  const hunks = plan.files.reduce((total, file) => total + file.mutations.length, 0);
+  return {
+    ok: true,
+    summary: "Updated " + files.length + " file" + (files.length === 1 ? "" : "s") + ":",
+    diff: committed.diff,
+    files,
+    served: committed.files.flatMap((file) => (file.served !== undefined ? [file.served] : [])),
+    warnings: committed.warnings,
+    metrics: {
+      files: files.length,
+      hunks,
+      addedLines,
+      removedLines,
+    },
+  };
+}
+
+/**
+ * Build the apply_patch use case.
+ * @param deps - optional seam overrides; production binds the real modules.
+ * @returns the tool seam bound to the real hashline engine and store.
+ */
+export function createApplyPatchTool(deps: ApplyPatchToolDeps = {}): ApplyPatchTool {
+  const parse = deps.parse ?? parseApplyPatch;
+  const plan = deps.plan ?? planApplyPatch;
+  const commit = deps.commit ?? commitPlan;
+  const renderOk = deps.renderSuccess ?? renderSuccess;
+  const renderBad = deps.renderFailure ?? renderFailure;
+
+  const planOnly: ApplyPatchTool["plan"] = async (input, ctx) => {
+    const parsed = parse(input);
+    if (!parsed.ok) return { ok: false, problems: parsed.problems, served: [] };
+    return plan(parsed.document, {
+      cwd: ctx.cwd,
+      sessionKey: ctx.sessionKey,
+      ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+    });
+  };
+
+  return {
+    plan: planOnly,
+    async execute(input, ctx) {
+      const planned = await planOnly(input, ctx);
+      if (!planned.ok) {
+        await recordRejectionServes(planned.served ?? [], ctx);
+        const failure = failureFromProblems(planned.problems, planned.served ?? []);
+        throwRejection(failure, renderBad(failure));
+      }
+      const committed = await commit(planned.plan, {
+        cwd: ctx.cwd,
+        sessionKey: ctx.sessionKey,
+        ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+      });
+      if (!committed.ok) throwRejection(committed.failure, renderBad(committed.failure));
+      return renderOk(successFrom(planned.plan, committed));
+    },
+  };
+}

package/src/apply-patch/types.ts

@@ -0,0 +1,387 @@
+/**
+ * apply_patch v4 — shared contract types.
+ *
+ * This module is the frozen vocabulary every apply-patch lane compiles against:
+ *
+ * - the **patch AST** the grammar layer produces (`PatchDocument`),
+ * - the **plan IR** the planner produces and the transaction layer commits
+ *   (`PatchPlan`, `PlannedFile`, `PlannedMutation`),
+ * - the **result / error** types the renderer and the host adapter consume.
+ *
+ * The engine underneath is the existing hashline kernel: content-addressed 4-char
+ * anchors, served leases, MVCC snapshots, correlated multi-file transactions and
+ * the undo store. Nothing here re-declares those primitives; the plan IR only
+ * adds the addressing and lifecycle vocabulary apply_patch needs.
+ *
+ * Vocabulary (see GLOSSARY.md): anchor, served row, lease, fragment hunk,
+ * identity hunk, reference hunk, patch line, plan.
+ *
+ * @module dsh-hashline-edit/apply-patch/types
+ */
+import type { DomainErrorCode, ServedRow } from "../domain-errors.js";
+import type { LineEnding } from "../edit-diff.js";
+import type { HashStore } from "../hash-store.js";
+import type { TransactionRecoveryReport } from "../mutation-engine/types.js";
+
+/** Patch AST (grammar layer output). */
+
+/** A 4-character anchor: `[A-Za-z0-9]{4}` (the hashline alphabet). */
+export type Anchor = string;
+
+/** A 1-based line number in the submitted patch text, used by every diagnostic. */
+export type PatchLineNumber = number;
+
+/** A path exactly as written in the patch: workspace-relative or workspace-absolute. */
+export type PatchPath = string;
+
+/** A closed anchor span; both anchors must have been served for the same file. */
+export interface AnchorSpan {
+  readonly from: Anchor;
+  readonly to: Anchor;
+}
+
+/** One parsed `*** Begin Patch` … `*** End Patch` document. */
+export interface PatchDocument {
+  /** File operations in submission order. */
+  readonly files: readonly PatchFileOp[];
+  /** Total number of lines in the input (1-based diagnostics may point at EOF). */
+  readonly lineCount: number;
+}
+
+export type PatchFileOp = AddFileOp | DeleteFileOp | UpdateFileOp;
+
+/** `*** Add File: <path>` — every following line is a '+' content line. */
+export interface AddFileOp {
+  readonly kind: "add";
+  readonly path: PatchPath;
+  readonly headerLine: PatchLineNumber;
+  /** Content lines WITHOUT the leading '+', in file order. Empty means an empty file. */
+  readonly contentLines: readonly string[];
+}
+
+/** `*** Delete File: <path>` */
+export interface DeleteFileOp {
+  readonly kind: "delete";
+  readonly path: PatchPath;
+  readonly headerLine: PatchLineNumber;
+}
+
+/** `*** Update File: <path>` with its optional `*** Move to:` and zero or more hunks. */
+export interface UpdateFileOp {
+  readonly kind: "update";
+  readonly path: PatchPath;
+  readonly headerLine: PatchLineNumber;
+  /** `*** Move to: <path>`; the parser only accepts it directly after the update header. */
+  readonly moveTo?: MoveDirective;
+  /** Hunks in submission order; each hunk's window starts after the previous hunk's end. */
+  readonly hunks: readonly PatchHunk[];
+}
+
+/** `*** Move to: <path>` */
+export interface MoveDirective {
+  readonly path: PatchPath;
+  readonly line: PatchLineNumber;
+}
+
+export type PatchHunk = FragmentHunk | IdentityHunk | ReferenceHunk;
+
+/**
+ * The addressing a hunk opens with.
+ *
+ * `start` is the bare `@@` (fragment mode, search from the file start);
+ * `context` is `@@ <line>` (fragment mode, search window starts after that
+ * line's unique hit); `anchors` is `@@<a>` / `@@<a>-<b>` (identity mode).
+ */
+export type HunkAddress =
+  | { readonly kind: "start" }
+  | { readonly kind: "context"; readonly text: string }
+  | { readonly kind: "anchors"; readonly span: AnchorSpan };
+
+/** A context/line matcher hunk: `@@` or `@@ <context>` followed by ' '/'+'/'-' lines. */
+export interface FragmentHunk {
+  readonly kind: "fragment";
+  /** Grammar guarantees this is `start` or `context`; `anchors` never appears here. */
+  readonly address: HunkAddress;
+  readonly headerLine: PatchLineNumber;
+  /** Body lines, in submission order; at least one is required. */
+  readonly lines: readonly FragmentLine[];
+  /** `*** End of File` line number when the hunk is tail-pinned, absent otherwise. */
+  readonly endOfFile?: PatchLineNumber;
+}
+
+/** One body line of a fragment hunk. */
+export interface FragmentLine {
+  readonly op: "context" | "remove" | "add";
+  /** Line content without the leading marker (' ', '-', '+'). */
+  readonly text: string;
+  readonly line: PatchLineNumber;
+}
+
+/** An identity hunk: `@@<a>` / `@@<a>-<b>` followed by '+' lines only (empty body = delete). */
+export interface IdentityHunk {
+  readonly kind: "identity";
+  readonly span: AnchorSpan;
+  readonly headerLine: PatchLineNumber;
+  /** '+' lines without the marker; empty means the span is deleted. */
+  readonly addedLines: readonly string[];
+}
+
+/** A copy/cut hunk: the content comes from another file's served span; no body lines allowed. */
+export interface ReferenceHunk {
+  readonly kind: "reference";
+  /**
+   * The hunk's own addressing (`@@`, `@@ <context>`, `@@<a>` or `@@<a>-<b>`),
+   * which determines the destination position (see docs/apply-patch-v4-internals.md §4).
+   */
+  readonly address: HunkAddress;
+  readonly source: ReferenceSource;
+  readonly headerLine: PatchLineNumber;
+}
+
+/** `*** Copy From:` / `*** Cut From:` source span. */
+export interface ReferenceSource {
+  readonly mode: "copy" | "cut";
+  readonly path: PatchPath;
+  readonly span: AnchorSpan;
+  readonly line: PatchLineNumber;
+}
+
+/** Plan IR (planner output / transaction input). */
+
+/**
+ * An inclusive 1-based line range in a file's pre-call baseline.
+ *
+ * A zero-width insertion uses the engine's inverted convention:
+ * `startLine = point + 1` and `endLine = point` (insert after line `point`;
+ * point 0 inserts at the start of the file).
+ */
+export interface LineRange {
+  readonly startLine: number;
+  readonly endLine: number;
+}
+
+/** The file-lifecycle action planned for one target. */
+export type LifecyclePlan =
+  | { readonly kind: "keep" }
+  | { readonly kind: "add" }
+  | { readonly kind: "delete" }
+  | { readonly kind: "move"; readonly to: PatchPath; readonly toAbsolutePath: string };
+
+/** One file's state at call time — the single baseline every mutation resolves against. */
+export interface FileBaseline {
+  /** The path as written in the patch. */
+  readonly path: PatchPath;
+  /** The resolved absolute path the engine reads/writes. */
+  readonly absolutePath: string;
+  /** LF-normalized text; `""` for an Add File target. */
+  readonly text: string;
+  /** 4-char anchors parallel to the file's lines; empty for an Add File target. */
+  readonly hashes: readonly string[];
+  /** Byte-order mark the file carried ("" when none). */
+  readonly bom: string;
+  /** The file's original line ending. */
+  readonly ending: LineEnding;
+  /** False for `*** Add File:` targets, true for every other existing target. */
+  readonly exists: boolean;
+}
+
+/** One resolved content mutation against `FileBaseline.text`, in baseline coordinates. */
+export interface PlannedMutation {
+  readonly kind: "replace" | "insert" | "delete";
+  readonly range: LineRange;
+  /** Replacement lines (LF-joined at commit); empty for `delete` and for an empty insertion. */
+  readonly lines: readonly string[];
+  /** The patch line that produced this mutation (diagnostics and ordering evidence). */
+  readonly patchLine: PatchLineNumber;
+}
+
+/** One Copy/Cut source span materialized from a baseline. */
+export interface PlannedReferenceUse {
+  readonly mode: "copy" | "cut";
+  readonly path: PatchPath;
+  readonly absolutePath: string;
+  readonly range: LineRange;
+  /** The source bytes, line-split and LF-normalized. */
+  readonly lines: readonly string[];
+  readonly patchLine: PatchLineNumber;
+}
+
+/** One file in the plan, with every mutation expressed against its own pre-call baseline. */
+export interface PlannedFile {
+  readonly path: PatchPath;
+  readonly absolutePath: string;
+  readonly lifecycle: LifecyclePlan;
+  readonly baseline: FileBaseline;
+  /** Non-overlapping mutations in baseline coordinates, ordered by `range.startLine`. */
+  readonly mutations: readonly PlannedMutation[];
+  /** Copy/Cut sources this target consumes. */
+  readonly references: readonly PlannedReferenceUse[];
+  /** True when committing this member changes bytes or the namespace. */
+  readonly writes: boolean;
+}
+
+/** The full plan one apply_patch call commits as one correlated transaction. */
+export interface PatchPlan {
+  /** Written members in commit order: the primary file leads, the rest follow deterministically. */
+  readonly files: readonly PlannedFile[];
+  /** Files read only as Copy/Cut sources (never written). */
+  readonly referenceFiles: readonly FileBaseline[];
+  readonly stats: PatchStats;
+}
+
+/** Aggregate line/file counts the success summary reports. */
+export interface PatchStats {
+  readonly filesChanged: number;
+  readonly addedLines: number;
+  readonly removedLines: number;
+}
+
+/** Result and error types. */
+
+/**
+ * The two error codes apply_patch adds to the shared registry.
+ *
+ * `E_STALE_ANCHOR` is NOT new: `src/domain-errors.ts` already registers it with
+ * the served-rows payload this feature reuses. The registry lane must add these
+ * two codes (payload + producer) before the surface lane registers the tool.
+ */
+export type ApplyPatchNewErrorCode = "E_PATCH_SYNTAX" | "E_UNIQUE_MATCH";
+
+/** Every code a patch problem may carry. */
+export type ApplyPatchErrorCode = DomainErrorCode | ApplyPatchNewErrorCode;
+
+/** One candidate row for an ambiguous fragment match, served back to the model. */
+export interface PatchCandidate {
+  /** 1-based line number in the baseline. */
+  readonly line: number;
+  readonly hash: Anchor;
+  readonly text: string;
+}
+
+/** One collectable problem in a rejection; every problem carries its patch line and code. */
+export interface PatchProblem {
+  readonly code: ApplyPatchErrorCode;
+  readonly patchLine: PatchLineNumber;
+  readonly path?: PatchPath;
+  readonly message: string;
+  /** Candidate rows when the failure is an ambiguous fragment match. */
+  readonly candidates?: readonly PatchCandidate[];
+  /** 1-based target line used to center the rejection serve window when known. */
+  readonly line?: number;
+}
+
+/** One file's current rows rendered `HASH│content` for reject-and-serve. */
+export interface ServedFileBlock {
+  readonly path: PatchPath;
+  readonly rows: readonly ServedRow[];
+  /** Rendered block, one `HASH│content` row per line. */
+  readonly text: string;
+}
+
+/** One file's lifecycle status and line counts in the success summary. */
+export interface AppliedFileSummary {
+  /** A = added, M = modified, R = renamed, D = deleted. */
+  readonly status: "A" | "M" | "R" | "D";
+  readonly path: PatchPath;
+  /** Original path for a rename (`R` only). */
+  readonly fromPath?: PatchPath;
+  readonly addedLines: number;
+  readonly removedLines: number;
+}
+
+/** Metrics one committed call reports (mirrors the existing RMetrics intent). */
+export interface PatchMetrics {
+  readonly files: number;
+  readonly hunks: number;
+  readonly addedLines: number;
+  readonly removedLines: number;
+  readonly durationMs?: number;
+}
+
+/** Successful apply_patch outcome. */
+export interface ApplyPatchSuccess {
+  readonly ok: true;
+  /** File-level summary, e.g. `Updated 2 files:\nA src/new.ts\nM src/a.ts`. */
+  readonly summary: string;
+  /** Annotated diff for the UI/details (never the model's primary text). */
+  readonly diff: string;
+  readonly files: readonly AppliedFileSummary[];
+  /** New anchors for every changed line, per file — the second call needs no read. */
+  readonly served: readonly ServedFileBlock[];
+  readonly warnings: readonly string[];
+  readonly metrics: PatchMetrics;
+}
+
+/** Rejected apply_patch outcome: one transaction, zero disk writes. */
+export interface ApplyPatchFailure {
+  readonly ok: false;
+  /** Primary code for the envelope; every problem still carries its own code. */
+  readonly code: ApplyPatchErrorCode;
+  readonly message: string;
+  /** Every independently diagnosable problem, in patch order. */
+  readonly problems: readonly PatchProblem[];
+  /** Current rows for every file named by a problem (reject-and-serve). */
+  readonly served: readonly ServedFileBlock[];
+  /** A rejection is pre-commit: the disk is unchanged by construction. */
+  /**
+   * True when the commit left the disk byte-identical (every written member rolled back). A
+   * mid-commit failure that could not be rolled back sets this false and reports exactly which
+   * members were restored, remain, or are uncertain.
+   */
+  readonly changedNothing: boolean;
+  /** The rollback's three-way outcome, when the failure happened after a member was written. */
+  readonly recovery?: TransactionRecoveryReport;
+}
+
+export type ApplyPatchResult = ApplyPatchSuccess | ApplyPatchFailure;
+
+/** The grammar seam's total result: a document or every syntax problem found. */
+export type ParsePatchResult =
+  | { readonly ok: true; readonly document: PatchDocument }
+  | { readonly ok: false; readonly problems: readonly PatchProblem[] };
+
+/** The planner seam's total result. */
+export type PlanPatchResult =
+  | { readonly ok: true; readonly plan: PatchPlan }
+  | {
+      readonly ok: false;
+      readonly problems: readonly PatchProblem[];
+      /** Current rows for every problem file, so the rejection needs no read to retry. */
+      readonly served: readonly ServedFileBlock[];
+    };
+
+/** The model-facing tool envelope returned by the renderer / tool use case. */
+export interface ApplyPatchToolResult {
+  readonly content: ReadonlyArray<{ readonly type: "text"; readonly text: string }>;
+  readonly details: ApplyPatchDetails;
+  /** True when this envelope renders a rejection (nothing was written). */
+  readonly isError?: boolean;
+}
+
+/** The structured details half of {@link ApplyPatchToolResult}. */
+export interface ApplyPatchDetails {
+  readonly summary: string;
+  readonly diff: string;
+  readonly files: readonly AppliedFileSummary[];
+  readonly servedByPath: readonly ServedFileBlock[];
+  readonly warnings: readonly string[];
+  readonly metrics: PatchMetrics;
+}
+
+/** Execution facts every apply_patch seam shares. */
+export interface ApplyPatchContext {
+  /** Absolute directory relative request paths resolve against (the live session directory). */
+  readonly cwd: string;
+  /** Session identity that keys served anchors and leases; never empty. */
+  readonly sessionKey: string;
+  /** Caller cancellation forwarded into every async file operation. */
+  readonly signal?: AbortSignal;
+}
+
+/** Options for the planner/commit seams over the existing hash store. */
+export interface ApplyPatchEngineOptions extends ApplyPatchContext {
+  /** Hash store override for tests; the default opens the configured store. */
+  readonly store?: HashStore;
+  /** POSIX access-mode bitmask; commit defaults to read+write, plan to read-only. */
+  readonly accessMode?: number;
+}