dsh-hashline-edit 0.2.2 → 0.3.0

package/lib/types/dsh/contracts.d.ts

@@ -2,7 +2,7 @@
  * Shared host contracts for the dsh adapter.
  *
  * The `dsh/` tree is the DeepSeek Harness host layer over the host-agnostic
- * hashline core in `src/`. Every lane (host, read, edit, platform) compiles
+ * hashline core in `src/`. Every lane (host, read, apply-patch, platform) compiles
  * against this file; renaming or reshaping an export here is a cross-lane
  * breaking change.
  *
@@ -67,6 +67,15 @@ export interface FileIO {
     stat(path: string, signal?: AbortSignal): Promise<FileStat | undefined>;
     /** Direct child names of a directory, sorted lexicographically. */
     readdir(path: string, signal?: AbortSignal): Promise<string[]>;
+    /**
+     * Delete one regular file. A lifecycle delete targets a file; a directory at the same path is
+     * a caller bug that must surface (never a recursive removal).
+     */
+    remove?(path: string, signal?: AbortSignal): Promise<void>;
+    /** Rename one regular file. The destination must not exist and its parent is created first. */
+    rename?(from: string, to: string, signal?: AbortSignal): Promise<void>;
+    /** Create one directory and missing parents. */
+    mkdir?(path: string, signal?: AbortSignal): Promise<void>;
 }
 /** The two sandbox-escalation arguments a mutating tool may carry. */
 export interface SandboxArgs {
@@ -124,7 +133,7 @@ export interface SandboxController {
  *
  * The host's observation policy fills its per-session state exclusively from
  * `fs/observed`, and that state is what lets a built-in `write` replace an
- * existing file. Shadowed `read`/`edit` calls never touch the provider's own
+ * existing file. Shadowed `read`/`apply_patch` calls never touch the provider's own
  * write path, so without this channel a file this plugin served stays
  * "unobserved" and the built-in overwrite is refused forever.
  *
@@ -190,7 +199,7 @@ export interface ToolDependencies {
  * factories at registration time. The fixed names are part of the lane
  * contract:
  * - `dsh/tools/read.ts` → `buildReadTool` (tool name `read`)
- * - `dsh/tools/edit.ts` → `buildEditTool` (tool name `edit`)
+ * - `dsh/tools/apply-patch.ts` → `buildApplyPatchTool` (tool name `apply_patch`)
  * - `dsh/tools/undo.ts` → `buildUndoTool` (tool name `undo_last_edit`)
  */
 export type ToolDefinitionFactory = (deps: ToolDependencies) => ToolDefinition;

package/lib/types/dsh/fs.d.ts

@@ -41,6 +41,9 @@ export declare class LocalFileIO implements FileIO {
     write(path: string, data: Uint8Array | string, signal?: AbortSignal): Promise<void>;
     stat(path: string, signal?: AbortSignal): Promise<FileStat | undefined>;
     readdir(path: string, signal?: AbortSignal): Promise<string[]>;
+    remove(path: string, signal?: AbortSignal): Promise<void>;
+    rename(from: string, to: string, signal?: AbortSignal): Promise<void>;
+    mkdir(path: string, signal?: AbortSignal): Promise<void>;
 }
 /** Create the M1 local filesystem seam. */
 export declare function createLocalFileIO(): FileIO;

package/lib/types/dsh/guidance.d.ts

@@ -26,20 +26,20 @@ export declare function parseSectionFile(content: string): ParsedSection;
 export declare function isBlankOverride(content: string): boolean;
 /** One overridable tool section. */
 export interface GuidanceSection {
-    /** Registry section name, e.g. `tool:edit`. */
+    /** Registry section name, e.g. `tool:apply_patch`. */
     readonly name: string;
-    /** Override file name inside a preset directory, e.g. `edit.md`. */
+    /** Override file name inside a preset directory, e.g. `apply-patch.md`. */
     readonly file: string;
     /** Order used when the harness registry names no slot for this section. */
     readonly defaultOrder: number;
     /** The `systemPrompt.getSectionOrder` slot this section shadows, when one exists. */
-    readonly orderName?: "TOOL_READ" | "TOOL_EDIT";
+    readonly orderName?: "TOOL_READ" | "TOOL_EDIT" | "TOOL_APPLY_PATCH";
     /** The compiled default text. */
     renderDefault(): string;
 }
 /**
- * The three sections, in default-order sequence. Defaults are byte-identical to
- * the pi host's guidance because they come from the same prompt sources.
+ * The three sections, in default-order sequence. Read and undo reuse the pi
+ * host's prompt sources; apply_patch owns the v4 mutation guidance.
  */
 export declare const GUIDANCE_SECTIONS: readonly GuidanceSection[];
 /** Render the compiled default text for one section. */
@@ -116,4 +116,10 @@ export declare function guidanceHomeDir(env?: Record<string, string | undefined>
  * come from the shared prompt sources, so the plugin package must ship
  * `prompts/` for them to load.
  */
-export declare function registerGuidanceSections(rootCtx: Context, agentCtx: Context): () => void;
+/** Which feature tools are enabled, so a disabled tool's guidance section is not registered. */
+export interface GuidanceToggles {
+    readonly read: boolean;
+    readonly applyPatch: boolean;
+    readonly undo: boolean;
+}
+export declare function registerGuidanceSections(rootCtx: Context, agentCtx: Context, enabled?: GuidanceToggles): () => void;

package/lib/types/dsh/hide.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Hide the native file-mutation tools so every text change goes through
+ * `apply_patch` — the one mutation entry point of the v4 surface.
+ *
+ * DSH 0.2.2-rc.1 owns tool declarations in the tool registry, not in the
+ * `system-prompt/assemble` waterfall: the waterfall receives sections, contexts
+ * and variables only. The authoritative schema filter is therefore the
+ * per-agent registry restriction (`tools.restrict({ deny })`), which removes a
+ * global tool from both the native schema list and the PTC `tools:sdk` section
+ * because both are rendered from `tools.definitions(scope, toolSet)`.
+ *
+ * Three seams still back that up, because a restriction only governs the
+ * registry view and a stale session or a hand-rolled section could carry a
+ * residual binding:
+ *
+ * 1. `tools.restrict({ deny })` drops the hidden schemas for this agent;
+ * 2. `system-prompt/assemble` empties the `tool:edit` guidance section (its
+ *    text is prose, never a tool mention) and deletes the hidden tools' member
+ *    blocks from any rendered PTC `tools:sdk` section;
+ * 3. `tools.guard` is the monotonic execution backstop for a stale schema or
+ *    any residual binding.
+ *
+ * `write` is hidden with `edit`/`str_replace_editor`. A whole-file replacement
+ * is one `*** Update File:` identity hunk spanning every served line with `+`
+ * lines for the new content, so no native mutation tool has to stay visible.
+ * The native `apply_patch` name is also denied in the inherited/preset layer
+ * when it exists; the plugin's own scoped registration shadows it otherwise.
+ *
+ * The layer is installed only when `apply_patch` actually registered: hiding
+ * the native mutation tools while owning no replacement would leave the
+ * profile with no way to change a file.
+ *
+ * @module dsh-hashline-edit/hide
+ */
+/** A boolean config value, or a live getter (used when a host exposes volatile config). */
+type BooleanSource = boolean | (() => boolean);
+/** The hide-layer configuration after the plugin-level defaults are applied. */
+export interface NativeHideConfig {
+    /** The registered replacement tool name, protected from `hiddenToolNames`. */
+    readonly toolName: string;
+    /** Hide `write`/`edit`/`str_replace_editor`; defaults to true. */
+    readonly hideNativeWriteTools?: BooleanSource;
+    /** Extra global tool names to hide alongside the native set. */
+    readonly hiddenToolNames?: readonly string[];
+    /** The Agent scope key used for the agent-view probe; absent keeps the global probe. */
+    readonly scope?: unknown;
+}
+/**
+ * Delete the hidden tools' member blocks from one rendered `tools:sdk` text.
+ *
+ * Structural, renderer-specific parsing — never a mention match:
+ * - TypeScript: a member starts at `  name: type` (2-space indent) inside
+ *   `ToolArgsMap`/`ToolOutputMap`, may open braces on the same line, and ends
+ *   at the first line that closes every opened brace and ends with `;`. Its
+ *   optional single-line JSDoc comment directly above goes with it.
+ * - Python: a `Tools` protocol member starts at an indented `async def` line
+ *   and spans until the next line at that member indent or shallower.
+ * @param text - the rendered SDK section text.
+ * @param hidden - the tool names to remove.
+ * @returns the text with every hidden member block removed.
+ */
+export declare function stripSdkMembers(text: string, hidden: ReadonlySet<string>): string;
+interface LoggerLike {
+    warn?(message: string): void;
+}
+declare function warn(rootCtx: {
+    logger?: LoggerLike;
+}, message: string): void;
+/**
+ * Install the hide layer for one agent. Only call this after `apply_patch`
+ * registered successfully.
+ *
+ * @param rootCtx - the plugin/root scope, used for the global-name probe and warnings.
+ * @param agentCtx - the agent scope whose tool view is restricted.
+ * @param config - the resolved hide configuration.
+ * @returns the exact disposer; disposing lifts the restriction and every listener.
+ */
+export declare function registerNativeToolHiding(rootCtx: Parameters<typeof warn>[0], agentCtx: unknown, config: NativeHideConfig): () => void;
+export {};

package/lib/types/dsh/host-compat.d.ts

@@ -1,82 +1,11 @@
-/** Retained line budget, matching pi's `DEFAULT_MAX_LINES`. */
-export declare const DEFAULT_MAX_LINES = 2000;
-/** Retained byte budget, matching pi's `DEFAULT_MAX_BYTES` (50KB). */
-export declare const DEFAULT_MAX_BYTES: number;
-/** The truncation report the core's read page renders. */
-export interface TruncationResult {
-    /** The truncated content. */
-    content: string;
-    /** Whether truncation occurred. */
-    truncated: boolean;
-    /** Which limit was hit: `"lines"`, `"bytes"`, or `null` when nothing was cut. */
-    truncatedBy: "lines" | "bytes" | null;
-    /** Total number of lines in the original content. */
-    totalLines: number;
-    /** Total number of bytes in the original content. */
-    totalBytes: number;
-    /** Number of complete lines in the truncated output. */
-    outputLines: number;
-    /** Number of bytes in the truncated output. */
-    outputBytes: number;
-    /** Whether the last line was partially truncated (tail truncation only). */
-    lastLinePartial: boolean;
-    /** Whether the first line exceeded the byte limit (head truncation only). */
-    firstLineExceedsLimit: boolean;
-    /** The line limit that was applied. */
-    maxLines: number;
-    /** The byte limit that was applied. */
-    maxBytes: number;
-}
-/** The two independent limits a truncation call applies. */
-export interface TruncationOptions {
-    /** Maximum number of lines; defaults to {@link DEFAULT_MAX_LINES}. */
-    maxLines?: number;
-    /** Maximum number of bytes; defaults to {@link DEFAULT_MAX_BYTES}. */
-    maxBytes?: number;
-}
 /**
- * Minimal structural stand-in for pi's extension-registry type.
+ * dsh host shim for the host-neutral utilities the core uses.
  *
- * WHY: `src/edit-undo.ts` keeps the pi registration (and its `ExtensionAPI` type) next to the
- * host-agnostic use case the dsh undo tool calls. The dsh build resolves the pi package to this
- * shim and never invokes that registration, so the build typecheck needs only the single method
- * the registration calls; the root tsconfig still checks the registration against the real pi API.
- */
-export interface ExtensionAPI {
-    /**
-     * Register one pi tool definition. The argument is intentionally structural and loose: the dsh
-     * program only needs the registration to compile, never to execute, and the loose `execute`
-     * signature keeps the pi adapter's untyped callback out of the dsh build's implicit-any checks.
-     */
-    registerTool(definition: {
-        execute: (...args: any[]) => unknown;
-        [key: string]: unknown;
-    }): void;
-}
-/**
- * Format bytes as a human-readable size (`512B`, `1.5KB`, `2.0MB`).
- * @param bytes - the byte count to render.
- * @returns the pi-compatible size label.
- */
-export declare function formatSize(bytes: number): string;
-/**
- * Truncate content from the head (keep the first N lines / bytes).
+ * WHY: the dsh bundle must not ship the pi agent package. The core's utility
+ * surface lives in `src/host-utils.ts`; this module keeps the historical
+ * `dsh/host-compat` import path (and the `@earendil-works/pi-coding-agent`
+ * esbuild/tsconfig alias) working for the dsh build.
  *
- * WHY: the read page's oversize and truncation warnings must agree with the pi
- * implementation the rest of the contract was written against, so this is a
- * faithful port including its two edge rules: complete lines only, and an
- * over-long first line yields empty content with `firstLineExceedsLimit`.
- * @param content - the text to truncate.
- * @param options - the line and byte limits.
- * @returns the truncation report.
- */
-export declare function truncateHead(content: string, options?: TruncationOptions): TruncationResult;
-/**
- * Serialize file mutation operations that target the same file; different files still run
- * in parallel. A faithful port of pi's queue so the core's cut transaction keeps its
- * lock ordering guarantees under the dsh host.
- * @param filePath - the file the mutation targets.
- * @param run - the critical section to run once the path is free.
- * @returns the critical section's result.
+ * @module dsh-hashline-edit/host-compat
  */
-export declare function withFileMutationQueue<T>(filePath: string, run: () => Promise<T>): Promise<T>;
+export * from "../src/host-utils.js";

package/lib/types/dsh/index.d.ts

@@ -1,21 +1,23 @@
 /**
  * dsh-hashline-edit host plugin entry.
  *
- * On every `agent/created`, install the three hashline tools on the AGENT's
- * own scope layer so they shadow the preset's built-in `read`/`edit` for that
+ * On every `agent/created`, install the hashline tools on the AGENT's
+ * own scope layer so they shadow the preset's built-in `read` for that
  * agent (nearest layer wins in dsh's tool registry) and unwind automatically
- * when the agent is disposed. The built-in `write` stays in place; the
- * platform lane's write hook integrates with it.
+ * when the agent is disposed. The native `write`, `edit` and
+ * `str_replace_editor` schemas are hidden on the same scope so `apply_patch`
+ * is the only file-mutation entry point; the write hook still integrates a
+ * built-in `write` when a profile chooses to keep it visible.
  *
- * `inject` deliberately lists only `tools` and `systemPrompt`: M1 has no
  * `inject` deliberately lists only `tools` and `systemPrompt`: the read-path
  * `ctx.fs` bridge is optional and resolved with `ctx.get`, so a minimal
- * composition still loads with the local `node:fs` fallback. Edit/undo stay
- * local-only (the M5 bridge covers reads; M6 owns mutation).
+ * composition still loads with the local `node:fs` fallback. apply_patch and
+ * undo stay local-only (the M5 bridge covers reads; M6 owns mutation).
  * @module dsh-hashline-edit
  */
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
+import Schema from "@deepseek-ai/schemastery";
 import { type ToolMetrics } from "./metrics/instrument.js";
 /** Cordis plugin name used by loader diagnostics. */
 export declare const name = "dsh-hashline-edit";
@@ -24,6 +26,47 @@ export declare const name = "dsh-hashline-edit";
  * services are resolved with `ctx.get` inside `dsh/sandbox.ts` instead.
  */
 export declare const inject: string[];
+/**
+ * The row's editable config schema. Exporting `Config` is what makes the host
+ * expose `dsh-hashline-edit#dsh-hashline-edit` as a writable settings namespace,
+ * so the Plugins-page card can render its three switches and write them back.
+ */
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    read: Schema<boolean, boolean, "volatile-defined">;
+    applyPatch: Schema<boolean, boolean, "volatile-defined">;
+    undo: Schema<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    read: Schema<boolean, boolean, "volatile-defined">;
+    applyPatch: Schema<boolean, boolean, "volatile-defined">;
+    undo: Schema<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
+/** The plugin configuration the loader passes as the second `apply` argument. */
+export interface PluginConfig {
+    /**
+     * Expose the hashline `read` tool, shadowing the host's native `read`.
+     * Defaults to true; off leaves the native `read` in place.
+     */
+    read?: boolean;
+    /**
+     * Expose the hashline `apply_patch` tool and hide the native
+     * `edit`/`write`/`apply_patch`/`str_replace_editor` tools. Defaults to true;
+     * off keeps every native mutation tool.
+     */
+    applyPatch?: boolean;
+    /**
+     * Expose the `undo_last_edit` tool. Defaults to false. The undo snapshot row is
+     * still written on every commit; only the model-facing tool is opt-in.
+     */
+    undo?: boolean;
+}
+/** The three feature switches after the shipped defaults are applied. */
+export interface ResolvedSwitches {
+    readonly read: boolean;
+    readonly applyPatch: boolean;
+    readonly undo: boolean;
+}
+/** Resolve the plugin's three switches with the shipped defaults: read and apply_patch on, undo off. */
+export declare function resolveSwitches(config?: PluginConfig): ResolvedSwitches;
 /**
  * Install the hashline toolset for one agent inside its own effect, so the
  * registrations are disposed in reverse order when the agent scope unwinds.
@@ -31,6 +74,6 @@ export declare const inject: string[];
  * Exported separately from {@link apply} so the host test can drive one fake
  * agent directly and integration probes can reuse the exact install path.
  */
-export declare function installAgentTools(rootCtx: Context, agent: Agent, metrics?: ToolMetrics): void;
-/** Mount the plugin: install the hashline toolset on every new agent. */
-export declare function apply(rootCtx: Context): void;
+export declare function installAgentTools(rootCtx: Context, agent: Agent, metrics?: ToolMetrics, config?: PluginConfig): () => void;
+/** Mount the plugin and reconcile live agents on every (re)apply. */
+export declare function apply(rootCtx: Context, config?: PluginConfig): void;

package/lib/types/dsh/metrics/events.d.ts

@@ -5,7 +5,7 @@
  * lets the global observer record any other host tool — the built-in `write`,
  * `pwsh`, `grep`, … — without widening this union once per tool.
  */
-type ToolName = "read" | "edit" | "undo_last_edit" | "write" | "shell_view" | (string & {});
+type ToolName = "read" | "apply_patch" | "undo_last_edit" | "write" | "shell_view" | (string & {});
 /** One tool call, as written to the JSONL file. Character counts are exact; the
  *  token estimate belongs to the summarizer so the ratio stays a reporting
  *  choice instead of being frozen into the event stream. */

package/lib/types/dsh/metrics/observer.d.ts

@@ -2,7 +2,7 @@
  * Global tool-call telemetry for the dsh host layer.
  *
  * Before this observer the adapter measured only its own surface: `read`,
- * `edit` and `undo_last_edit` from the tool boundaries, plus `shell_view` from
+ * `apply_patch` and `undo_last_edit` from the tool boundaries, plus `shell_view` from
  * the shell hook when it rewrites a result. Every other call the host
  * dispatched — the built-in `write` that sits next to this plugin's shadowed
  * tools, `pwsh`, `grep`, … — left no event at all, so no baseline could say

package/lib/types/dsh/sandbox.d.ts

@@ -3,7 +3,7 @@
  *
  * Mirrors the built-in `@deepseek-ai/dsh-tool-fs` controller (same
  * vocabulary, same fail-closed approval sequence, shared
- * `@deepseek-ai/dsh-sandbox` pieces) so `edit`/`undo_last_edit` ask for wider
+ * `@deepseek-ai/dsh-sandbox` pieces) so `apply_patch`/`undo_last_edit` ask for wider
  * access exactly like the built-in `write`/`edit`. The differences are
  * deliberate M1 facts:
  *
@@ -21,7 +21,7 @@ import type { ToolExecution } from "@deepseek-ai/dsh-tools";
 import type { SandboxMode } from "@deepseek-ai/dsh-sandbox";
 import type { SandboxArgs, SandboxController, SandboxDecision } from "./contracts.js";
 /**
- * The filesystem escalation controller shared by `edit` and `undo_last_edit`
+ * The filesystem escalation controller shared by `apply_patch` and `undo_last_edit`
  * for one agent install.
  */
 export declare class FsSandboxController implements SandboxController {

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

@@ -7,7 +7,7 @@
  * foreground stdout channel, or a shell view that refuses (not whitelisted /
  * ambiguous alignment) all pass the decision through untouched. Only a
  * successful, uniquely aligned view is rewritten, and its rows are served
- * through the read tool's seam so a following `edit` resolves the anchors.
+ * through the read tool's seam so a following `apply_patch` hunk resolves the anchors.
  *
  * Both foreground value shapes the host may project are understood:
  * `{ kind: "foreground", stdout: { text, truncated } }` (the canonical

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/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.
  *
@@ -54,7 +54,7 @@ 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 served anchor, usable by `apply_patch`. */
     readonly hash: string;
     /** The line's decoded text, without the anchor prefix. */
     readonly text: string;
@@ -84,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/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 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>;