dsh-hashline-edit 0.1.1 → 0.2.0

package/lib/types/dsh/shell-view.d.ts

@@ -95,3 +95,55 @@ export declare function align(stdoutLines: readonly string[], fileLines: readonl
  * @returns the plan, or `undefined` when the host must pass the output through.
  */
 export declare function plan(deps: ToolDependencies, request: ShellViewRequest): Promise<ShellViewPlan | undefined>;
+/** The host tool whose canonical value is `{ matches: [{ path, lineNumber, line }] }`. */
+export declare const GREP_TOOL_NAME = "grep";
+/** The host `grepMaxMatches` default (`@deepseek-ai/dsh-tool-fs-search` `Config`). */
+export declare const GREP_INLINE_MAX_MATCHES = 250;
+/**
+ * WHY: the host spill policy's own budget is `maxInlineTokens: 12500`
+ * (`dsh-base/cordis.patch.yml`, `@deepseek-ai/dsh-spill-policy`), and grep is not
+ * on its exemption list — only `read` is. A `post-execute` accept decision that
+ * carries a `value` bypasses that policy (`Object.hasOwn(decision, "value")`), so
+ * this seam must hold the same line itself, using the host's own price for one
+ * text block: `ceil(chars / 4) + 4` (`@deepseek-ai/dsh-token-meter/estimate`).
+ */
+export declare const GREP_VIEW_MAX_INLINE_TOKENS = 12500;
+/** The host estimator's price for one text block, so a self-check matches the policy's. */
+export declare function estimateTextTokens(text: string): number;
+/** One match of the host `grep` value. */
+export interface GrepViewMatch {
+    readonly path: string;
+    readonly lineNumber: number;
+    readonly line: string;
+}
+/** The matches plus the session to serve them to. */
+export interface GrepViewRequest {
+    readonly matches: readonly GrepViewMatch[];
+    readonly cwd: string;
+    readonly sessionKey: string;
+    readonly signal: AbortSignal | undefined;
+}
+/** The rewritten model-facing grep result. */
+export interface GrepViewPlan {
+    /** The shared search banner, one count header per file, and anchored `HASH│content` rows. */
+    readonly text: string;
+    /** Total rows served (and leased) by this plan. */
+    readonly servedLines: number;
+    /** The served files, in first-seen match order. */
+    readonly paths: readonly string[];
+}
+/**
+ * Turn one built-in `grep` result into anchored rows for the files it matched,
+ * serving (and leasing) exactly those lines.
+ *
+ * Fail-closed discipline mirrors the shell view: a result that is empty, over the
+ * host's inline match cap, over the host's inline token budget, non-ascending per
+ * file, or whose matched text does not byte-equal the file's governed decode leaves
+ * the original result untouched and records no lease. The budget is checked BEFORE
+ * the first serve, so an oversized view can never leave partial leases behind.
+ *
+ * @param deps - host seams; `deps.io` is the only filesystem access used.
+ * @param request - the matches, working directory, session and cancellation signal.
+ * @returns the plan, or `undefined` when the host must pass the result through.
+ */
+export declare function planGrepView(deps: ToolDependencies, request: GrepViewRequest): Promise<GrepViewPlan | undefined>;

package/lib/types/dsh/tools/apply-patch.d.ts

@@ -0,0 +1,38 @@
+import type { FileDiff, ToolDefinition } from "@deepseek-ai/dsh-tools";
+import { APPLY_PATCH_TOOL_NAME } from "../../src/apply-patch/tool.js";
+import type { ApplyPatchTool } from "../../src/apply-patch/tool.js";
+/** Public tool name re-exported for host registration and surface tests. */
+export { APPLY_PATCH_TOOL_NAME };
+import type { ToolDependencies } from "../contracts.js";
+/** One call's intended file diffs, parsed from the patch headers for the pending card. */
+interface PatchPreview {
+    readonly diffs: FileDiff[];
+    readonly locations: string[];
+}
+/**
+ * Scan the patch headers for the pending card. This is a presentation-only
+ * projection: it never decides whether the patch is valid (the grammar and
+ * planner do), and it never throws on malformed text.
+ * @param input - the raw patch text.
+ * @returns the intended additions and every path the patch names.
+ */
+export declare function previewPatch(input: string): PatchPreview;
+/** Every path this patch writes, including a Cut From source; Copy From sources are read-only. */
+export declare function writtenPatchPaths(input: string): string[];
+/** Options for {@link buildApplyPatchTool}; the factory seam is for tests. */
+export interface ApplyPatchToolOptions {
+    /** Test seam: build the use case without touching the real engine/store. */
+    readonly create?: () => ApplyPatchTool;
+}
+/**
+ * Build the dsh 'apply_patch' tool for one agent install.
+ *
+ * The use case is created lazily: building a tool definition must not touch the
+ * engine or the store, and a composition where 'apply_patch' is skipped must
+ * still install the rest of the toolset.
+ *
+ * @param deps - the host seams this tool may touch; 'sandbox' advertises and resolves escalation.
+ * @param options - test seam for the use case.
+ * @returns a registry-ready dsh tool definition named 'apply_patch'.
+ */
+export declare function buildApplyPatchTool(deps: ToolDependencies, options?: ApplyPatchToolOptions): ToolDefinition;

package/lib/types/dsh/tools/context.d.ts

@@ -14,7 +14,7 @@
  * @module dsh-hashline-edit/tools/context
  */
 import type { ToolRunContext } from "@deepseek-ai/dsh-tools";
-import type { ToolContext } from "../contracts.js";
+import type { ToolContext, ToolDependencies } from "../contracts.js";
 /** The pi-shaped context the upstream use cases consume. */
 export interface UpstreamContext {
     cwd: string;
@@ -35,3 +35,21 @@ export interface UpstreamContext {
 export declare function resolveToolContext(exec: ToolRunContext): ToolContext;
 /** Translate the dsh facts into the pi-shaped context the upstream seams still take. */
 export declare function upstreamContext(ctx: ToolContext): UpstreamContext;
+/**
+ * Announce, before the core writes them, every request path one mutating call
+ * owns.
+ *
+ * WHY announce and not enforce: these mutations go to `node:fs` and bypass the
+ * provider whose guarded write is where an intent would be applied, so the
+ * dispatch exists for host bookkeeping. The channel is present only when
+ * `ctx.fs` is mounted; without one there is nothing to announce.
+ */
+export declare function announcePluginWrites(deps: ToolDependencies, requestPaths: readonly string[], ctx: ToolContext, exec: object): Promise<void>;
+/**
+ * Publish what a successful write left on disk for each path it touched.
+ *
+ * WHY `fresh`: the version this call saw before writing is stale once the bytes
+ * changed, so the channel must re-stat for the version the host's guard is later
+ * compared against.
+ */
+export declare function publishPluginWrites(deps: ToolDependencies, requestPaths: readonly string[], ctx: ToolContext, exec: object): Promise<void>;

package/lib/types/dsh/tools/output.d.ts

@@ -9,12 +9,19 @@
  * - the canonical value IS `{ content, details }`, so no projection loses fields;
  * - `render` is the identity on `content`, which keeps the model-facing text byte-identical to the
  *   upstream tool result;
- * - `details` stays available to nested (`run_code`) callers as structured data; a UI projection
- *   can be added through `presentationMeta` without reshaping the canonical value.
+ * - `details` stays available to nested (`run_code`) callers as structured data; the UI projection
+ *   rides `presentationMeta`, which is persisted beside the result and never reshapes the value.
+ *
+ * The presentation projection exists because the two consumers read different things: a host-local
+ * presenter consumes `presentCall`/`presentResult` directly, while the built-in Web Client derives
+ * its card props from persisted metadata — the same split the preset's own `write`/`edit` declare
+ * in their `output.presentationMeta`, which projects the applied hunks. Ours projects the annotated
+ * diff the tool already rendered, because that is the only before/after artifact the upstream
+ * envelope carries at this seam.
  *
  * @module dsh-hashline-edit/tools/output
  */
-import type { InferValue } from "@deepseek-ai/dsh-tools";
+import type { DiffResultView, FileDiff, InferValue, ToolOutputDefinition } from "@deepseek-ai/dsh-tools";
 /** One model-facing text block; the upstream tools emit nothing else today. */
 export interface TextContentBlock {
     type: "text";
@@ -46,8 +53,17 @@ declare const TOOL_RESULT_SCHEMA: {
 };
 /** The inferred canonical value type of {@link TOOL_RESULT_SCHEMA}. */
 export type ToolResultOutput = InferValue<typeof TOOL_RESULT_SCHEMA>;
+/**
+ * The durable presentation payload both mutation tools project: the applied hunks a diff card
+ * renders. `path` is the model-facing path the call named (a UI bridge relativizes it); a hunk
+ * carries `oldText: null` for a pure insertion, exactly like the preset's own `computeHunkDiffs`.
+ */
+export interface HashlineResultMeta {
+    path?: string;
+    diffs: FileDiff[];
+}
 /** Registry-ready output declaration shared by `edit` and `undo_last_edit`. */
-export declare const TOOL_RESULT_OUTPUT: {
+export declare const HASHLINE_RESULT_OUTPUT: {
     readonly schema: {
         readonly type: "object";
         readonly additionalProperties: false;
@@ -66,7 +82,19 @@ export declare const TOOL_RESULT_OUTPUT: {
         };
     };
     readonly render: (_args: unknown, value: ToolResultOutput) => TextContentBlock[];
+    readonly presentationMeta: NonNullable<ToolOutputDefinition["presentationMeta"]>;
 };
+/**
+ * The completed state of a mutation call as one diff card, or `undefined` when the call failed or
+ * applied nothing — the presenter then keeps the pending card, exactly like the preset's `edit`.
+ * @param title - the card header, e.g. `Edit src/a.ts`.
+ * @param result - the completed outcome handed to `presentResult`.
+ * @returns the diff result view, or `undefined` for the generic path.
+ */
+export declare function diffResultView(title: string, result: {
+    readonly isError: boolean;
+    readonly meta?: unknown;
+}): DiffResultView | undefined;
 /**
  * Present the upstream envelope as the declared canonical value.
  *

package/lib/types/dsh/tools/read.d.ts

@@ -1,7 +1,7 @@
 /**
  * The dsh `read` tool: hash-anchored reads (`HASH│content` rows) that shadow
  * the built-in `read` on the agent's own scope layer. In the default `served`
- * mode every shown row is recorded as served, so a later `edit` can verify the
+ * mode every shown row is recorded as served, so a later `apply_patch` identity hunk can verify the
  * model was actually shown the lines it targets; `verbatim` mode is a plain
  * reference read that grants no anchor and leaves served state untouched.
  *
@@ -17,11 +17,14 @@
  * - `around_anchor` windows are admitted and resolved against this session's
  *   active lineage, for both modes (spec §4.3 carries no mode qualifier); only
  *   a served read leases the rows it renders.
- * - Read expansion mirrors `src/read.ts`: the host entry injects the composed
- *   provider (`createDefaultReadSpanProvider`), the `read.expansion` mode and
- *   every attempt's audit record come from the core seams, and a missing
- *   provider or unavailable grammar degrades to the exact requested window —
- *   expansion never fails a read.
+ * - Read expansion mirrors `src/read.ts` — every attempt's audit record comes from
+ *   the core seams, and a missing provider or unavailable grammar degrades to the
+ *   exact requested window: expansion never fails a read.
+ * - `encoding` — the word, and the parameter itself, is gone. This host reads and
+ *   writes UTF-8 only: a target whose bytes are not valid UTF-8 is refused with
+ *   `E_UNSUPPORTED_FILE` naming the path and telling the model to ask the user how
+ *   to handle the file. The bytes still round-trip verbatim — only admission is
+ *   narrowed.
  * - ADR-0043 stat-identity adoption mirrors the core: on the default decode path
  *   the loader's stat identity (ino/size/mtime/ctime) is passed through, so an
  *   unchanged file adopts its committed snapshot and reuses its anchors; a moved
@@ -51,22 +54,16 @@ export declare function createDefaultReadSpanProvider(io?: CoreReadIo): SpanProv
 export interface ServedFileLine {
     /** 1-based line number the anchor addresses. */
     readonly line: number;
-    /** The line's 4-character anchor, usable by `edit`. */
+    /** The line's 4-character anchor, usable by `apply_patch`. */
     readonly hash: string;
     /** The line's decoded text, without the anchor prefix. */
     readonly text: string;
 }
-/** The facts one line-set serve needs; `autoGuess` admits a probabilistic decode. */
+/** The facts one line-set serve needs. */
 export interface ServeFileLinesOptions {
     readonly path: string;
     readonly cwd: string;
     readonly signal: AbortSignal | undefined;
-    /**
-     * Admit a probabilistic decode. WHY off for the read tool: only a caller with
-     * independent evidence of the text (a shell view's own stdout, aligned line by
-     * line) may accept a guessed code page.
-     */
-    readonly autoGuess?: boolean;
 }
 /** A line-set serve: the file plus the lines to materialize and lease. */
 export interface ServeFileLinesRequest extends ServeFileLinesOptions {
@@ -87,7 +84,7 @@ export declare function decodeFileLines(deps: ToolDependencies, request: ServeFi
  *
  * WHY a separate seam: the shell view must turn already-aligned disk lines into
  * editable anchors without re-implementing the read pipeline, and those anchors
- * must be leased to the session the following `edit` uses.
+ * must be leased to the session the following `apply_patch` hunk uses.
  */
 export declare function serveFileLines(deps: ToolDependencies, request: ServeFileLinesRequest): Promise<ServedFileLine[]>;
 /**

package/lib/types/dsh/tools/undo.d.ts

@@ -2,6 +2,11 @@ import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
 import type { ToolDependencies } from "../contracts.js";
 /** dsh tool name; `undo_last_edit` is plugin-owned (no preset shadow). */
 export declare const UNDO_TOOL_NAME = "undo_last_edit";
+/**
+ * The core's prompt text, kept in sync with `prompts/undo-last-edit.md`. Exported only so the drift
+ * test can pin it to the file the guidance section loads; the tool itself uses the inlined copy.
+ */
+export declare const UNDO_DESCRIPTION: string;
 /**
  * Build the dsh `undo_last_edit` tool for one agent install.
  * @param deps - the host seams this tool may touch; `sandbox` advertises and resolves escalation.

package/lib/types/dsh/write-hook.d.ts

@@ -33,8 +33,7 @@
  */
 import type { Context } from "@deepseek-ai/cordis";
 import type { PostToolDecision, PreToolDecision, ToolExecution, ToolExecutionResult } from "@deepseek-ai/dsh-tools";
-import type { FileIO } from "./contracts.js";
-import { type EncodingState } from "./encoding.js";
+import type { FileIO, FsObservationChannel } from "./contracts.js";
 /** The heading the post-write auto-read appends to the write result. */
 export declare const AUTO_READ_HEADING = "--- Auto-read (hashline anchors) ---";
 /** The served evidence the guard compares a submitted write against. */
@@ -44,11 +43,6 @@ export interface ServedSnapshot {
     /** Canon digests parallel to `served` (null = no evidence for that position). */
     readonly canonDigests: readonly (string | null)[];
 }
-/** A write's captured encoding state: the restore target taken before the tool wrote. */
-interface CapturedEncodingState {
-    readonly absolutePath: string;
-    readonly state: EncodingState;
-}
 /** Everything the hook needs from the host, injectable for tests. */
 export interface WriteHookDeps {
     /** Resolve a model-supplied path against the session cwd; must match the read/edit path keys. */
@@ -58,17 +52,11 @@ export interface WriteHookDeps {
     /** Read + serve the just-written file, returning the model-facing anchored text. */
     autoRead(rawPath: string, cwd: string, sessionKey: string, signal?: AbortSignal): Promise<string>;
     /**
-     * Optional pre-write capture of the encoding state this write must restore.
-     * WHY before the write: the write changes the file version the state is gated
-     * on, so a capture taken afterwards could never match what the read recorded.
-     */
-    captureEncodingState?(rawPath: string, cwd: string, signal?: AbortSignal): Promise<CapturedEncodingState | undefined>;
-    /**
-     * Optional host step between the committed write and the auto-read: re-encode
-     * the built-in tool's UTF-8 bytes to the captured encoding. Returns a
-     * model-facing warning when the bytes had to stay UTF-8.
+     * Optional host observation channel. The built-in write's own dispatch is what
+     * observes the write itself, so the hook only publishes the auto-read's re-observation
+     * here; a composition without the channel silently skips the announcement.
      */
-    finalizeWrite?(captured: CapturedEncodingState | undefined, rawPath: string, cwd: string, signal?: AbortSignal): Promise<string | undefined>;
+    readonly observations?: FsObservationChannel;
     /** Host diagnostic sink; the hook must never throw through this. */
     warn(message: string): void;
 }
@@ -84,16 +72,14 @@ export interface WriteHooks {
  */
 export declare function createWriteHooks(deps: WriteHookDeps): WriteHooks;
 /** The production dependency set: the byte seam plus core served state, core read pipeline, local paths. */
-export declare function defaultWriteHookDeps(warn: (message: string) => void, io: FileIO): WriteHookDeps;
+export declare function defaultWriteHookDeps(warn: (message: string) => void, io: FileIO, observations?: FsObservationChannel): WriteHookDeps;
 /**
  * Register the write integration for one agent on its own scope layer.
  *
  * @param rootCtx - host context, used only for diagnostics.
  * @param agentCtx - the agent's scoped context; the listeners see only that
  *   agent's tool calls.
- * @param io - the host byte seam: the auto-read decodes through it and the
- *   post-write step inverts the recorded encoding with it.
+ * @param io - the host byte seam: the auto-read decodes the written bytes through it.
  * @returns the exact disposer that unregisters both listeners.
  */
-export declare function registerWriteHook(rootCtx: Context, agentCtx: Context, io: FileIO): () => void;
-export {};
+export declare function registerWriteHook(rootCtx: Context, agentCtx: Context, io: FileIO, observations?: FsObservationChannel): () => void;

package/lib/types/src/apply-patch/commit.d.ts

@@ -0,0 +1,49 @@
+import type { HashStore } from "../hash-store.js";
+import type { ApplyPatchFailure, PatchPlan, ServedFileBlock } from "./types.js";
+/** Options for {@link commitPlan}. */
+export interface CommitPlanOptions {
+    readonly cwd: string;
+    readonly sessionKey: string;
+    readonly signal?: AbortSignal;
+    readonly store?: HashStore;
+    /** POSIX access-mode bitmask; defaults to read+write. */
+    readonly accessMode?: number;
+    /** TEST-ONLY: fires before the first rename, while the pre-images/undo rows are durable. */
+    readonly onBeforeFirstWrite?: () => void | Promise<void>;
+    /** TEST-ONLY: fires between two member renames, after the earlier one is durable. */
+    readonly onBetweenWrites?: (committedAbsolutePath: string) => void | Promise<void>;
+    /** TEST-ONLY: fires after a move rename and before the destination rewrite (mid-member failure). */
+    readonly onAfterMoveRename?: (toAbsolutePath: string) => void | Promise<void>;
+}
+/** One committed file's lifecycle status and line accounting. */
+export interface CommittedFile {
+    readonly path: string;
+    readonly status: "A" | "M" | "R" | "D";
+    /** Original path for a rename (`R` only). */
+    readonly fromPath?: string;
+    readonly addedLines: number;
+    readonly removedLines: number;
+    /** New anchors for the changed lines; absent when the member wrote no content. */
+    readonly served?: ServedFileBlock;
+}
+/** Commit outcome: the per-file facts on success, the whole failure on rejection. */
+export type CommitPlanResult = {
+    readonly ok: true;
+    readonly files: readonly CommittedFile[];
+    readonly diff: string;
+    readonly warnings: readonly string[];
+} | {
+    readonly ok: false;
+    readonly failure: ApplyPatchFailure;
+};
+/**
+ * Commit one plan atomically (one correlated transaction, one undo record set).
+ *
+ * The implementation reuses `commitTransaction` — the existing correlated skeleton — and extends
+ * its member shape with the plan's lifecycle action; the undo schema gains the matching action.
+ *
+ * @param plan - the fully resolved plan.
+ * @param options - cwd/session/store, cancellation and the test fault seams.
+ * @returns the committed facts, or a failure whose `changedNothing` reflects the rollback.
+ */
+export declare function commitPlan(plan: PatchPlan, options: CommitPlanOptions): Promise<CommitPlanResult>;

package/lib/types/src/apply-patch/grammar.d.ts

@@ -0,0 +1,29 @@
+import type { AnchorSpan, ParsePatchResult } from "./types.js";
+/** Hard cap on one patch input (bytes), mirroring the host request budget. */
+export declare const PATCH_MAX_BYTES: number;
+/** Options for {@link parseApplyPatch}. */
+export interface ParsePatchOptions {
+    /** Maximum accepted input size in bytes; defaults to {@link PATCH_MAX_BYTES}. */
+    readonly maxBytes?: number;
+}
+/**
+ * Parse one patch document.
+ *
+ * Success returns the AST defined in `types.ts`; failure returns every syntax
+ * problem the parser could diagnose in one pass (never a throw for malformed
+ * user input). Rejections use `E_PATCH_SYNTAX` with the offending patch line.
+ *
+ * @param input - the raw `*** Begin Patch` … `*** End Patch` text.
+ * @param options - size guard knobs.
+ * @returns the parsed document or the collected problems.
+ */
+export declare function parseApplyPatch(input: string, options?: ParsePatchOptions): ParsePatchResult;
+/**
+ * Parse an anchor token: `<a>` (single line) or `<a>-<b>` (closed span).
+ * Returns `undefined` when the token is not a valid four-character anchor pair; the
+ * grammar layer turns that into an `E_PATCH_SYNTAX` problem at the patch line.
+ *
+ * @param token - the text after `@@` (no leading space).
+ * @returns the closed span, or undefined for a malformed token.
+ */
+export declare function parseAnchorSpan(token: string): AnchorSpan | undefined;

package/lib/types/src/apply-patch/lifecycle.d.ts

@@ -0,0 +1,32 @@
+import { type HashStore } from "../hash-store.js";
+import type { ProcessedEditFile } from "../mutation-engine/types.js";
+import type { PatchPath, PlannedFile } from "./types.js";
+/**
+ * apply_patch lifecycle materialization — the plan-to-engine adapter.
+ *
+ * The planner resolves every mutation against a pre-call baseline; this module turns that plan
+ * into the mutation engine's `ProcessedEditFile` member shape (plus the engine-local lifecycle
+ * action). It never writes: the correlated transaction in `mutation-engine/pipeline.ts` owns the
+ * one commit path. Pure text application (splice at baseline coordinates) is the only work here,
+ * and the resulting anchors are always derived under the member's COMMITTED path.
+ *
+ * @module dsh-hashline-edit/apply-patch/lifecycle
+ */
+/** One materialized member: the plan facts plus the engine member the commit consumes. */
+export interface MaterializedMember {
+    readonly planned: PlannedFile;
+    readonly member: ProcessedEditFile;
+    readonly status: "A" | "M" | "R" | "D";
+    /** The committed display path (destination for a move; the pre path otherwise). */
+    readonly committedPath: PatchPath;
+    /** The pre-transaction display path (move only). */
+    readonly fromPath?: PatchPath;
+}
+/**
+ * Materialize one planned file into the engine's member shape.
+ *
+ * The result text is produced by applying the plan's baseline-coordinate mutations; the anchors
+ * are then derived under the committed path. No file is read or written here — the plan already
+ * carries every baseline byte the commit needs.
+ */
+export declare function materializeMember(planned: PlannedFile, store?: HashStore): Promise<MaterializedMember>;

package/lib/types/src/apply-patch/plan.d.ts

@@ -0,0 +1,50 @@
+import type { LeaseSpanSource } from "../hashline/resolve.js";
+import { type HashStore } from "../hash-store.js";
+import { type ServedAnchors } from "./resolve.js";
+import type { ApplyPatchEngineOptions, FileBaseline, PatchDocument, PatchPath, PlannedMutation, PlanPatchResult } from "./types.js";
+/**
+ * The baseline/served loader port.
+ *
+ * Production wires `readBaseline` to the file-content decode path,
+ * `readServed` to `createSessionHandle(...).load()` and `readLeaseSource` to
+ * the read-only lease identity source. Tests inject a pure in-memory
+ * implementation, which is what makes the planner testable without a store.
+ */
+export interface PlanFileLoader {
+    /** Load one file's baseline (LF-normalized text + anchors + BOM + ending). */
+    readBaseline(path: PatchPath, absolutePath: string, signal?: AbortSignal): Promise<FileBaseline>;
+    /** Load this session's served anchors for one file, parallel to its lines. */
+    readServed(absolutePath: string, sessionKey: string, store?: HashStore): Promise<ServedAnchors>;
+    /** Session-wide anchor homes, for foreign-anchor diagnosis (optional legacy port). */
+    anchorHomes?(anchor: string, sessionKey: string, store?: HashStore): readonly PatchPath[];
+    /** Build the read-only lease identity source for one file's baseline content. */
+    readLeaseSource?(absolutePath: string, sessionKey: string, content: string, store?: HashStore): Promise<LeaseSpanSource>;
+}
+/** Options for {@link planApplyPatch}; `loader` is the test seam. */
+export interface PlanApplyPatchOptions extends ApplyPatchEngineOptions {
+    readonly loader?: PlanFileLoader;
+}
+/** A baseline for a file that does not exist yet (Add File / missing target). */
+export declare function absentBaseline(path: PatchPath, absolutePath: string): FileBaseline;
+/** The production loader over node:fs, the file-content decoder and the hash store. */
+export declare function createDefaultPlanFileLoader(): PlanFileLoader;
+/** Apply resolved baseline-coordinate mutations to a line array (descending, so coordinates stay valid). */
+export declare function applyPlannedMutations(lines: readonly string[], mutations: readonly PlannedMutation[]): string[];
+export declare function mutationDelta(baselineLines: readonly string[], mutation: PlannedMutation): {
+    added: number;
+    removed: number;
+};
+/**
+ * Plan one apply_patch call without writing anything.
+ *
+ * All hunks resolve against the pre-call baseline (never chained application);
+ * a later hunk's fragment window begins after the previous hunk's end. Any
+ * problem aborts the whole call: the returned list is every independently
+ * diagnosable problem, not just the first, together with the current rows of
+ * every named file (reject-and-serve).
+ *
+ * @param document - the parsed patch AST.
+ * @param options - cwd/session/store plus the optional baseline loader.
+ * @returns the plan, or every problem found plus the rows to serve.
+ */
+export declare function planApplyPatch(document: PatchDocument, options: PlanApplyPatchOptions): Promise<PlanPatchResult>;

package/lib/types/src/apply-patch/render.d.ts

@@ -0,0 +1,51 @@
+/**
+ * apply_patch v4 — renderer.
+ *
+ * One renderer owns both surfaces:
+ *
+ * - success: file-level summary lines first (`A`/`M`/`R`/`D`), then the
+ *   changed-line anchor rows (`HASH│content`) per file, so a second call needs
+ *   no `read`;
+ * - rejection: every problem as `- patch line N ([E_*], path): message`,
+ *   followed by each problem file's current rows.
+ *
+ * @module dsh-hashline-edit/apply-patch/render
+ */
+import type { ApplyPatchFailure, ApplyPatchResult, ApplyPatchSuccess, ApplyPatchToolResult, AppliedFileSummary, PatchProblem, ServedFileBlock } from "./types.js";
+/**
+ * Render one apply_patch outcome into the model-facing tool envelope.
+ * @param result - the committed success or the collected rejection.
+ * @returns `{ content, details }` ready for the dsh tool registry.
+ */
+export declare function renderApplyPatchResult(result: ApplyPatchResult): ApplyPatchToolResult;
+/**
+ * Render a successful outcome.
+ * @param success - committed file facts plus new anchor rows.
+ * @returns the model-facing envelope.
+ */
+export declare function renderSuccess(success: ApplyPatchSuccess): ApplyPatchToolResult;
+/**
+ * Render a rejected outcome: all problems first, then the served rows.
+ * @param failure - the collected problems and current rows.
+ * @returns the model-facing envelope (as an `isError` tool result at the host seam).
+ */
+export declare function renderFailure(failure: ApplyPatchFailure): ApplyPatchToolResult;
+/**
+ * Render the file-level summary block: `Updated N files:` then one status line
+ * per file (`R src/old.ts -> src/new.ts` for a rename).
+ * @param files - the committed file summaries.
+ * @returns the summary text.
+ */
+export declare function renderFileSummary(files: readonly AppliedFileSummary[]): string;
+/**
+ * Render the new-anchor blocks for every changed file.
+ * @param blocks - per-file served rows.
+ * @returns one `<path>\nHASH│content` section per block.
+ */
+export declare function renderServedBlocks(blocks: readonly ServedFileBlock[]): string;
+/**
+ * Render one problem line: `- patch line N ([E_*], path): message`.
+ * @param problem - one collected problem.
+ * @returns the single-line rendering, without a trailing newline.
+ */
+export declare function formatPatchProblem(problem: PatchProblem): string;