dsh-hashline-edit 0.1.0 → 0.2.0

package/lib/types/src/file-content/preview.d.ts

@@ -1,4 +1,4 @@
-import { type TruncationResult } from "@earendil-works/pi-coding-agent";
+import { type TruncationResult } from "../host-utils.js";
 import { type AnchorWalk } from "../hashline/hash-identity.js";
 import type { ServedRow } from "../served-session/serve-render.js";
 /** The lines one page actually rendered, 1-based and inclusive. */

package/lib/types/src/fs-lifecycle.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Filesystem primitives for apply_patch's file lifecycle: classify, create directories, delete a
+ * regular file and rename one. Every entry point resolves through {@link resolveTarget}, the same
+ * symlink-resolving boundary every read/write uses, so a lifecycle action can never escape it.
+ *
+ * These are primitives, not a second write engine: file CONTENTS still go through writeAtomic;
+ * this module only owns namespace operations that writeAtomic deliberately does not express.
+ *
+ * @module dsh-hashline-edit/fs-lifecycle
+ */
+/** The physical kind of a path as the file layer sees it (symlinks resolved first). */
+export type PathKind = "file" | "directory" | "other" | "absent";
+/** Classify one path through the file layer's symlink-resolving boundary. */
+export declare function pathKind(path: string): Promise<PathKind>;
+/**
+ * True when `path` resolves inside `root` once every existing symlink/junction component is
+ * followed. A missing tail is checked against its nearest existing ancestor: an Add File under a
+ * junction ancestor therefore fails before mkdir can create anything outside the workspace.
+ */
+export declare function isPathWithinWorkspace(root: string, path: string): Promise<boolean>;
+/** Throw the E_PATCH_SYNTAX boundary refusal for one escaping lifecycle path. */
+export declare function assertPathWithinWorkspace(root: string, path: string): Promise<void>;
+/** Create one directory (and missing parents), through the symlink-resolving boundary. */
+export declare function mkdirp(path: string, workspaceRoot?: string): Promise<void>;
+/**
+ * Delete one regular file. Deliberately NOT recursive: a lifecycle delete targets a file, and a
+ * directory at the same path is a caller bug that must surface, never be removed wholesale.
+ */
+export declare function removeFile(path: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Rename one regular file, creating the destination parent first. The destination must not exist:
+ * a move never clobbers another file (spec §6: target-exists is a rejection, not an overwrite).
+ */
+export declare function renameFile(from: string, to: string, signal?: AbortSignal, workspaceRoot?: string): Promise<void>;
+/**
+ * The directories on the way to `path` that do not exist yet, OUTERMOST FIRST. Captured before a
+ * lifecycle add writes, so an undo removes exactly the directories the add created and no others.
+ */
+export declare function missingAncestorDirs(path: string): Promise<string[]>;
+/**
+ * Best-effort removal of directories a lifecycle add created, deepest first. Returns the removed
+ * paths. A directory that is no longer empty (an outside writer put something there) is kept.
+ */
+export declare function pruneEmptyDirs(dirs: readonly string[]): Promise<string[]>;

package/lib/types/src/hashline/resolve.d.ts

@@ -128,6 +128,12 @@ export type HTEdit = {
         retire: boolean;
     };
 };
+/**
+ * SAFETY: the rejection summary plus the rows to serve. The message is facts-only: it names the
+ * distinct failing anchors and, for ambiguous ones, the candidate line numbers. Row content travels
+ * only in `servedRows` so a caller renders one evidence block; a message that also echoes the rows
+ * would make the retry read the same lines twice.
+ */
 export declare function fmtMismatchWithServes(mismatches: HMismatch[], snapshot: FileSnapshotContext): {
     message: string;
     servedRows: ServedRow[];

package/lib/types/src/host-utils.d.ts

@@ -0,0 +1,63 @@
+/** 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;
+}
+/**
+ * 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 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.
+ */
+export declare function withFileMutationQueue<T>(filePath: string, run: () => Promise<T>): Promise<T>;

package/lib/types/src/mutation-engine/batch-span-gate.d.ts

@@ -36,6 +36,12 @@ export interface BaselineSpanContext {
     sessionKey: string;
     absolutePath: string;
     isPreview: boolean;
+    /**
+     * WHY: the CALLER's own item numbers, parallel to `edits` — a per-file plan keeps its items'
+     * WHY: global positions, so an aggregated refusal names the item the model sent instead of this
+     * WHY: plan's local index. Absent means `edits` IS the whole call, so local index = caller number.
+     */
+    itemNumbers?: readonly number[];
     path: string;
     originalHashes: string[];
     originalNormalized: string;

package/lib/types/src/mutation-engine/edit-request.d.ts

@@ -0,0 +1,34 @@
+/** The internal payload vocabulary the mutation engine consumes; no wire schema lives here. */
+type SpanRef = {
+    anchor_from: string;
+    anchor_to: string;
+    file?: string;
+    mode: "copy" | "cut";
+};
+type EditMode = "general" | "literal";
+type Placement = "in-place" | "before" | "after";
+export type DesiredContent = {
+    kind: "literal";
+    text: string;
+} | {
+    kind: "reference";
+    span: SpanRef;
+    mode: "copy" | "cut";
+} | {
+    kind: "empty";
+};
+export type NormalizedEditItem = {
+    target: {
+        anchor_from: string;
+        anchor_to: string;
+    };
+    at: Placement;
+    payload: DesiredContent;
+    file?: string;
+};
+export type NormalizedEditRequest = {
+    file: string;
+    edits: NormalizedEditItem[];
+    mode?: EditMode;
+};
+export {};

package/lib/types/src/mutation-engine/pipeline.d.ts

@@ -1,14 +1,29 @@
-import type { NormalizedEditRequest } from "../payload-contract.js";
+import type { NormalizedEditRequest } from "./edit-request.js";
 import { buildBatchResult } from "../edit-response.js";
 import type { PipelineOptions, ProcessedEditFile } from "./types.js";
 export type { PipelineOptions, ProcessedEditFile };
 export declare function previewEdits(request: NormalizedEditRequest, cwd: string, options?: Omit<PipelineOptions, "noPersist">): Promise<ProcessedEditFile>;
-export declare function apply(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<{
+declare function runCorrelatedTransaction(writePlans: ProcessedEditFile[], sectionPlans: ProcessedEditFile[], options: PipelineOptions | undefined, sessionKey: string): Promise<BatchOutcome>;
+/** What one plan or committed batch reports: the primary file leads, every section rides the result. */
+interface BatchOutcome {
     result: string;
     diff: string;
     drift: string | undefined;
     metrics: ReturnType<typeof buildBatchResult>["details"]["metrics"];
     raw: ProcessedEditFile;
     toolResult: ReturnType<typeof buildBatchResult>;
-}>;
+}
+/**
+ * Plan a multi-file request without persisting, for the preview seam.
+ * @returns one plan per target file in commit order, or `undefined` when the call names a single
+ *   file — the caller then keeps its own single-file preview path.
+ */
+export declare function planEditTargets(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<ProcessedEditFile[] | undefined>;
+export declare function apply(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<BatchOutcome>;
 export declare function execEdits(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<ProcessedEditFile>;
+/**
+ * Visibility-only export of the correlated transaction for apply_patch's commit seam. The
+ * function body is the one the cut path already uses; apply_patch members carry an optional
+ * lifecycle action read by that body. No engine semantics change.
+ */
+export { runCorrelatedTransaction as commitTransaction };

package/lib/types/src/mutation-engine/types.d.ts

@@ -7,29 +7,45 @@
 import type { LineEnding } from "../edit-diff.js";
 import type { ResolvedRange } from "../served-session/serve-render.js";
 import type { HashStore } from "../hash-store.js";
-import type { EditDetails, RMetrics } from "../edit-response.js";
-import type { DomainErrorCode, RangeCause } from "../domain-errors.js";
-import type { ServedRow } from "../domain-errors.js";
 export interface PipelineOptions {
+    /** Workspace root used to re-assert lifecycle path boundaries at commit time. */
+    workspaceRoot?: string;
     accessMode?: number;
     signal?: AbortSignal;
     store?: HashStore;
     noPersist?: boolean;
     sessionKey?: string;
     /**
-     * TEST-ONLY fault-injection seam (ticket-04b §3): invoked inside a foreign-source cut transaction
-     * AFTER the target insert is durably committed and BEFORE the source retirement rename. A
-     * throw here lands inside the two-rename window, which is exactly the half-applied state the
-     * intent record and next-run repair must resolve.
+     * TEST-ONLY fault-injection seam (ticket-04b §3): invoked inside a correlated write transaction
+     * AFTER the first file's rename is durably committed and BEFORE the next file's rename. A throw
+     * here lands inside the rename window — the cut path's target-then-sources order, or a multi-file
+     * edit's plan order — which is exactly the half-applied state the intent record and next-run
+     * repair must resolve.
      */
     onCutBetweenWrites?: (committedAbsolutePath: string) => void | Promise<void>;
     /**
-     * TEST-ONLY observation seam (ticket-04b remediation-2 R2): invoked inside a foreign-source cut
-     * transaction BEFORE the first rename, while no byte of the transaction has landed. The rule
-     * under test is write-AHEAD: the intent record must already be durable at the moment of the
-     * first mutation — an existence check taken inside the window cannot show that.
+     * TEST-ONLY observation seam (ticket-04b remediation-2 R2): invoked inside a correlated write
+     * transaction (a foreign-source cut, or a multi-file edit) BEFORE the first rename, while no byte
+     * of the transaction has landed. The rule under test is write-AHEAD: the intent record must
+     * already be durable at the moment of the first mutation — an existence check taken inside the
+     * window cannot show that.
      */
     onBeforeFirstCutWrite?: () => void | Promise<void>;
+    /**
+     * TEST-ONLY mid-member fault seam: called after a move's rename is durable and before its
+     * destination content is rewritten, so the rollback of that in-flight member is exercised.
+     */
+    onAfterMoveRename?: (toAbsolutePath: string) => void | Promise<void>;
+}
+/**
+ * The honest outcome of a failed multi-member commit's rollback attempt. `restored` members are
+ * proven back at their pre-images; `remaining` members were not rolled back; `uncertain` members
+ * are those whose rollback attempt itself threw, so neither state can be claimed for them.
+ */
+export interface TransactionRecoveryReport {
+    restored: string[];
+    remaining: string[];
+    uncertain: string[];
 }
 /**
  * (ticket-04b) One foreign `mode: "cut"` item as seen by the pre-pass: the submitted span anchors
@@ -43,6 +59,26 @@ export interface ForeignCutRecord {
     spanFrom: string;
     spanTo: string;
 }
+/**
+ * The file-lifecycle action one transaction member carries.
+ *
+ * This is the engine-local vocabulary: apply_patch's plan IR maps onto it in
+ * `src/apply-patch/commit.ts` so the mutation engine never imports the apply-patch layer.
+ * Absent is an ordinary in-place edit.
+ */
+export type MemberLifecycle = {
+    kind: "keep";
+} | {
+    kind: "add";
+    createdDirs: readonly string[];
+} | {
+    kind: "delete";
+} | {
+    kind: "move";
+    fromAbsolutePath: string;
+    toAbsolutePath: string;
+    createdDirs: readonly string[];
+};
 export interface ProcessedEditFile {
     path: string;
     absolutePath: string;
@@ -86,53 +122,9 @@ export interface ProcessedEditFile {
      * correlated two-file transaction; the in-memory buffer itself never touches these files.
      */
     foreignCuts: ForeignCutRecord[];
-}
-export interface MutationSuccess {
-    ok: true;
-    /** SAFETY: Normalized result content (LF). */
-    result: string;
-    /** SAFETY: Unified diff (hash-anchored) for model consumption. */
-    diff: string;
-    /** SAFETY: User-facing drift notice, if any (details only, not model content). */
-    drift: string | undefined;
-    /** SAFETY: Metrics for telemetry. */
-    metrics: RMetrics;
-    raw: ProcessedEditFile;
-    /** SAFETY: Full tool result (content + details) for pi's tool_result hook. */
-    toolResult: {
-        content: Array<{
-            type: "text";
-            text: string;
-        }>;
-        details: EditDetails;
-    };
-}
-export interface MutationFailure {
-    ok: false;
-    /**
-     * SAFETY: Machine code — a registry member (`DomainErrorCode`). `toFailure` validates every
-     * caught code through the envelope reader (`src/error-envelope.ts`): non-registry strings
-     * (errno pass-through included) route to `E_UNKNOWN`, so the union is honest.
-     */
-    code: DomainErrorCode;
-    /** SAFETY: Human message — model-facing signal when applicable. */
-    message: string;
-    /** SAFETY: Fresh served block for retry when available (reject-and-serve). */
-    servedBlock?: string;
-    servedRows?: ServedRow[];
     /**
-     * SAFETY: the RAW `E_BAD_PAYLOAD` message behind a rendered refusal, when the route is one, so
-     * SAFETY: the tool seam can name the invoking tool instead of falling back to the neutral
-     * SAFETY: wording. Present only for `code: "E_BAD_PAYLOAD"`.
+     * apply_patch lifecycle action for this member; absent is an ordinary edit. The correlated
+     * transaction reads it for pre-image capture, commit ordering, rollback and undo-row shape.
      */
-    payloadMessage?: string;
-    /** SAFETY: User-facing diagnosis, never a model remedy — a GLOSSARY.md glossary term. */
-    cause?: RangeCause;
-    details?: {
-        code: DomainErrorCode;
-        cause: RangeCause;
-    };
+    lifecycle?: MemberLifecycle;
 }
-export type MutationResult = MutationSuccess | MutationFailure;
-export declare function isMutationSuccess(r: MutationResult): r is MutationSuccess;
-export declare function isMutationFailure(r: MutationResult): r is MutationFailure;

package/lib/types/src/read-expansion/grammar-manifest.d.ts

@@ -17,8 +17,10 @@ export interface GrammarManifestEntry {
 }
 export type GrammarManifest = Readonly<Record<string, GrammarManifestEntry>>;
 /**
- * TypeScript/TSX grammars from the pinned tree-sitter-typescript release. Both are fetched from a
- * versioned URL and verified against the committed digest before they reach the parser.
+ * Pinned grammars: TypeScript/TSX from the tree-sitter-typescript release, Python/Go/Rust from their
+ * own releases, Java from the tree-sitter-java release and Vue from the tree-sitter-vue-wasm npm
+ * package. Every entry is fetched from a versioned URL and verified against the committed digest
+ * before it reaches the parser.
  */
 export declare const GRAMMAR_MANIFEST: GrammarManifest;
 /** The manifest entry for a source path, or undefined when no grammar is supported yet. */

package/lib/types/src/read-expansion/java-decoration.d.ts

@@ -0,0 +1,21 @@
+/** Java vocabulary for the shared scope-decoration walk. */
+import type { DecorationSpec } from "./scope-decoration.js";
+/**
+ * Java declaration nodes and their note kinds. A record is a class-like declaration, so it shares
+ * the `class` label; a constructor is its own protocol kind and is never relabelled as a method.
+ */
+export declare const JAVA_SPAN_KINDS: {
+    readonly class_declaration: "class";
+    readonly record_declaration: "class";
+    readonly interface_declaration: "interface";
+    readonly enum_declaration: "enum";
+    readonly method_declaration: "method";
+    readonly constructor_declaration: "constructor";
+    readonly compact_constructor_declaration: "constructor";
+};
+/**
+ * A Java declaration carries its modifiers (annotations included) inside its own node, so the
+ * span already starts at the first annotation. Only a directly preceding JavaDoc block needs the
+ * leading-sibling walk; ordinary `//` and `/*` comments are not documentation and stay outside.
+ */
+export declare const JAVA_DECORATION: DecorationSpec;

package/lib/types/src/read-expansion/span-expansion.d.ts

@@ -36,9 +36,13 @@ export interface SpanProvider {
 }
 /**
  * Only a folded requested span at or below this size triggers expansion. Folding happens first, so
- * sixteen adjacent 24-line windows are one 384-line span and refuse the trigger.
+ * sixteen adjacent windows are one span and refuse the trigger.
+ *
+ * WHY 61: measured against the working corpus — 25-40 line reads occurred 66 times, 41-60 38 times,
+ * 61-100 38 times and >200 once, with a median refused read of 61 lines. At the previous 24-line
+ * trigger expansion engaged on only 9.6% of reads; the cap, not this trigger, still bounds the cost.
  */
-export declare const TRIGGER_MAX = 24;
+export declare const TRIGGER_MAX = 61;
 /** Code scopes may widen to a function or method; this ceiling is refused, never clamped. */
 export declare const SPAN_CAP_CODE = 80;
 /** Markdown sections clamp to a cap-sized window that still contains the requested window. */

package/lib/types/src/read-expansion/span-kind.d.ts

@@ -5,7 +5,8 @@
  * `SPAN_KIND_TO_LSP` carries the canonical PascalCase name next to it. Six extensions cover
  * concepts the protocol cannot express honestly: `arrow` (an anonymous function assigned to a
  * name), `typeAlias`, `impl` and `trait` (Rust items; mapping them to `Object` would be a lie),
- * and the non-AST prose units `section` and `paragraph`.
+ * and the non-symbol document units `section` (Markdown sections and Vue SFC blocks) and
+ * `paragraph` (plain-text paragraphs).
  *
  * Display stays lowercase because the note is model-facing prose, not a protocol symbol. The two
  * camel-case members `enumMember` and `typeParameter` are rendered as `enum member` and
@@ -31,7 +32,7 @@ export declare function isSpanKind(value: unknown): value is SpanKind;
 /** The model-facing note label; the audit keeps the union spelling. */
 export declare function spanKindLabel(kind: SpanKind): string;
 /** Kinds a current provider table or non-AST emitter can produce; not the whole protocol. */
-export declare const PRODUCED_KINDS: readonly ["function", "method", "class", "interface", "enum", "namespace", "arrow", "impl", "trait", "typeAlias", "section", "paragraph"];
+export declare const PRODUCED_KINDS: readonly ["function", "method", "class", "interface", "enum", "namespace", "arrow", "impl", "trait", "typeAlias", "section", "paragraph", "constructor"];
 /** One language's grammar-node-type to note-kind data table. */
 export type SpanKindTable = Readonly<Record<string, SpanKind>>;
 export {};

package/lib/types/src/read-expansion/vue-decoration.d.ts

@@ -0,0 +1,14 @@
+import type { DecorationSpec } from "./scope-decoration.js";
+/**
+ * A `.vue` file is one component made of top-level document sections. The note vocabulary has no
+ * template/style symbol and `component` is the file root (never a widening target), so the three
+ * SFC block nodes share the existing `section` extension and are distinguished by their names.
+ * Embedded JavaScript/TypeScript is raw text in this grammar, so a script section is never parsed
+ * or widened beyond its own block.
+ */
+export declare const VUE_SPAN_KINDS: {
+    readonly template_element: "section";
+    readonly script_element: "section";
+    readonly style_element: "section";
+};
+export declare const VUE_DECORATION: DecorationSpec;

package/lib/types/src/served-session/serve-render.d.ts

@@ -14,7 +14,13 @@ export interface FileSnapshotContext {
 export declare function buildRangeServeRows(startLine: number, endLine: number, fileHashes: string[]): ServedRow[];
 export declare function denseServeRows(hashes: readonly string[]): ServedRow[];
 export declare function fmtServedRows(rows: ServedRow[], fileLines: string[]): string;
+export declare function paginationHint(nextOffset: number, more: number): string;
 export declare function servedPositionsOf(served: (string | null)[], hash: string): number[];
+/** Builds the reject-and-serve served rows + rendered block for a current on-disk range. */
+export declare function buildRangeServeBlock(startLine: number, endLine: number, fileHashes: string[], fileLines: string[]): {
+    servedRows: ServedRow[];
+    rendered: string;
+};
 /**
  * Builds an `[E_TARGET_LOST]` rejection for a retired leased identity whose range cannot be
  * identified (spec stale-identity-reject-and-serve D1/D6, ADR-0018 decisions 1-2). The payload
@@ -45,9 +51,9 @@ export declare function makeServedRejection(opts: {
 }): DomainError<"E_STALE_RANGE" | "E_UNVERIFIED_RANGE">;
 /**
  * Builds the `[E_STALE_ANCHOR]` reject-and-serve rejection for a boundary anchor the session holds
- * no lease for. It serves the rows under `Current range:` with the retry hint (spec §5.3): the
- * served rows are themselves serves, so the retry needs no `read`. Distinct from the range-family
- * codes, which serve a fresh read with no mandate (issue #149).
+ * no lease for. It serves the rows under `Current range:` as evidence with no retry mandate: the
+ * served rows are themselves serves, so deciding from them needs no `read` (same fresh-read rule as
+ * the range-family codes, issue #149). The registry renders the block at most once.
  */
 export declare function makeStaleAnchorRejection(opts: {
     headline: string;

package/lib/types/src/undo-store.d.ts

@@ -25,7 +25,23 @@ export interface UndoRecord {
      * `null` is a row from before this column, or an ordinary single-file edit.
      */
     rawPre?: string | null;
+    /**
+     * The lifecycle action this row reverses. Absent/null is an ordinary edit (back-compatible).
+     * add = the file did not exist before; delete = the file does not exist after; move = a pure
+     * rename with an optional content edit.
+     */
+    lifecycle?: UndoLifecycle | null;
+    /** Move: the absolute path the file had before the transaction. */
+    fromPath?: string | null;
+    /** Move: the absolute path the file has after the transaction. */
+    toPath?: string | null;
+    /** The RAW post-transaction text when the commit wrote non-canonical bytes (pure move). */
+    rawPost?: string | null;
+    /** Add: the directories the add created, outermost first, JSON-encoded in the column. */
+    createdDirs?: readonly string[] | null;
 }
+/** The lifecycle action one undo row reverses. */
+export type UndoLifecycle = "edit" | "add" | "delete" | "move";
 export type CutIntentDirection = "revert" | null;
 export interface CutIntent {
     txnId: string;
@@ -33,7 +49,7 @@ export interface CutIntent {
     direction: CutIntentDirection;
 }
 export interface UndoStmts {
-    undoUpsert: (path: string, content: string, bom: string, ending: string, hashes: string, resultContent: string, snapshotHash: string | null, transactionId: string | null, rawPre: string | null, anchorGeneration: number, updatedAt: number) => void;
+    undoUpsert: (path: string, content: string, bom: string, ending: string, hashes: string, resultContent: string, snapshotHash: string | null, transactionId: string | null, rawPre: string | null, lifecycle: string | null, fromPath: string | null, toPath: string | null, rawPost: string | null, createdDirs: string | null, anchorGeneration: number, updatedAt: number) => void;
     undoGet: (path: string) => Record<string, unknown> | undefined;
     undoDelete: (path: string) => void;
     undoGetTransaction: (transactionId: string) => Record<string, unknown>[];

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "dsh-hashline-edit",
-  "version": "0.1.0",
-  "description": "Hash-anchored read/edit/undo_last_edit tools for DeepSeek Harness (dsh). Every line gets a unique 4-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
+  "version": "0.2.0",
+  "description": "Hash-anchored read/apply_patch tools for DeepSeek Harness (dsh). Every line gets a unique 4-char hash (A-Za-z0-9) that stays stable across edits; apply_patch is the only file-mutation entry point and commits one patch batch per transaction. Undo persists across restarts.",
   "keywords": [
     "anchors",
+    "apply-patch",
     "coding-agent",
     "deepseek-harness",
     "dsh",
     "dsh-plugin",
-    "edit",
     "file-editing",
     "hash",
     "hash-anchored",
@@ -56,17 +56,8 @@
     "format:fix": "oxfmt .",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.dsh.json",
     "build": "node scripts/build-dsh.mjs",
-    "build:pi": "node scripts/build-dist.mjs",
     "prepublishOnly": "node scripts/build-dsh.mjs && pnpm run typecheck && pnpm run lint && pnpm run test:win",
     "canon:audit": "node scripts/canon-churn-audit.mjs",
-    "prompts:show": "node scripts/served-prompts.mjs",
-    "replay:read-expansion": "node scripts/read-expansion-replay.mjs",
-    "test:runtime": "node scripts/runtime-edge-test.mjs",
-    "verify:dist": "node scripts/verify-dist.mjs",
-    "verify:dist:mutations": "node scripts/verify-dist-mutations.mjs",
-    "measure:import": "node scripts/measure-import.mjs --max-ratio 0.75",
-    "smoke:install": "node scripts/install-smoke.mjs",
-    "prepare": "node scripts/prepare.mjs",
     "prepack": "node scripts/build-dsh.mjs",
     "audit": "pnpm audit --audit-level high --registry https://registry.npmjs.org/",
     "verify": "pnpm run lint && pnpm run format && pnpm run typecheck && pnpm run test:win:coverage"
@@ -74,8 +65,6 @@
   "dependencies": {
     "diff": "^8.0.2",
     "file-type": "^21.3.0",
-    "iconv-lite": "^0.6.3",
-    "typebox": "^1.3.27",
     "unbash": "5.0.0",
     "xxhash-wasm": "^1.1.0"
   },
@@ -83,14 +72,12 @@
     "@babel/parser": "7.29.8",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
-    "@deepseek-ai/cordis": "^4.0.5",
-    "@deepseek-ai/dsh-agent": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-fs": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-home-paths": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-sandbox": "0.2.1-rc.2",
-    "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
-    "@earendil-works/pi-coding-agent": "^0.84.0",
-    "@earendil-works/pi-tui": "*",
+    "@deepseek-ai/cordis": "4.0.6-alpha.2",
+    "@deepseek-ai/dsh-agent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-fs": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-home-paths": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-sandbox": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-tools": "0.2.2-alpha.3",
     "@semantic-release/git": "^11.0.1",
     "@semantic-release/github": "^12.0.9",
     "@semantic-release/npm": "^13.1.5",
@@ -110,6 +97,7 @@
     "web-tree-sitter": "0.27.1"
   },
   "engines": {
+    "dsh": ">=0.2.2-alpha.3 <0.2.3-0",
     "node": ">=24.0.0"
   },
   "packageManager": "pnpm@12.0.0",

package/prompts/apply-patch-guidelines.md

@@ -0,0 +1,10 @@
+- apply_patch: one call = one transaction. Collect every related file change (code, tests, docs, config) into one patch; split only when an earlier RESULT must decide a later edit.
+- apply_patch: two addressing modes. Fragment mode (`@@` or `@@ <context>`) locates by exact content and needs no served state. Identity mode (`@@<a>` / `@@<a>-<b>`) targets rows this session served and never writes the old text back.
+- apply_patch: the character after `@@` selects the mode. `@@` followed immediately by exactly four anchor characters is identity mode; `@@` followed by a space is Codex context mode (`@@ <line>`); a bare `@@` starts the search at the file start. Any other token is a syntax rejection.
+- apply_patch: fragment mode must match exactly once. Zero or several hits reject and serve the candidate rows; add surrounding context to disambiguate, never guess.
+- apply_patch: identity mode accepts only `+` lines; an empty body deletes the span. A `-` or context line in an identity hunk, or body lines in a Copy/Cut hunk, rejects at admission with its patch line number.
+- apply_patch: every hunk resolves against the file as it was before the call; later windows begin after the previous hunk's end. Overlapping target ranges in one file reject the whole batch.
+- apply_patch: lifecycle joins the same transaction and undo. `*** Add File:` content lines all start with `+`; `*** Delete File:` removes the file; `*** Move to:` must immediately follow `*** Update File:` and renames before its hunks apply; an existing move target rejects.
+- apply_patch: a rejection writes nothing. Read the `- patch line N ([E_*], path): ...` lines, then use the immediately following `HASH│content` block — those are the current rows and anchors; retry directly without issuing a separate `read`.
+- apply_patch: a success starts with `Updated N files:` and ends with the changed lines' fresh anchors per file; use those anchors directly in the next identity hunk. `[W_*]` lines are informational.
+- apply_patch: paths are workspace-relative or workspace-absolute; `..`, `.git`, and symlink targets reject. Whole-file replacement stays with `write`.

package/prompts/apply-patch.md

@@ -0,0 +1 @@
+Apply one Codex-format patch to one or more files in a single transaction: `{ input: string }`. `input` is the complete patch text: `*** Begin Patch` ... `*** End Patch`, with `*** Add File:`, `*** Delete File:`, `*** Update File:` (plus optional `*** Move to:`) and hunks addressed either by content (`@@` or `@@ <context>` with ` `/`-`/`+` lines) or by served anchors (`@@<a>` / `@@<a>-<b>` with `+` lines only). `*** Copy From:` / `*** Cut From:` copy or move a served span from another file. Every target validates before anything is written; a rejection changes nothing and returns the current rows with anchors. On success the result lists the changed files and the new anchors for the changed lines, so a follow-up call needs no `read`. `write` stays for whole-file replacement.

package/prompts/read-guidelines.md

@@ -1,6 +1,6 @@
-- read: call it only for information the tool never served you, such as content past the auto-read diff. A bash view or an auto-read already served the file, so edit from those rows.
-- read: when you need several blocks or both boundaries of one replacement, put every range in ONE call. Use `{ file, windows: [{ offset, limit }] }`. Each window is served in that turn, so its anchors work in the same edit. A window can also be `{ around_anchor, radius }` to centre on a line this session already served. An anchor outside this session's served rows is omitted with an inline `[Window warning: ...]`.
-- read: a requested window of 24 lines or fewer can widen to its enclosing block; overlapping or adjacent windows fold before this test. Caps are 80 lines for code and Markdown, 40 for plain text. Widened rows begin with `[widened <requested> -> <served>, <label>]`; above three requested windows the note is `[widened N windows: <ranges>]`. An over-cap Markdown section clamps and names `(section <extent>)`; over-cap code or plain text refuses with no note. `mode: "verbatim"` widens too, with no anchors.
-- read: when you will not edit the file, pass `mode: "verbatim"` for plain content with no anchors. Examples are a config value, docs, a README, or skill content (a SKILL.md or any file in its directory). Omit `mode` when you intend to edit, so the rows carry anchors.
-- read: send one file per call as `{ file, windows?, mode? }`, the same way `edit` does. The single top-level `mode` applies to the file. To read several files, make parallel `read` calls.
+- read: call it only for information the tool never served you, such as content past the auto-read diff. A bash view or an auto-read already served the file, so apply_patch from those rows.
+- read: when you need several blocks or both boundaries of one replacement, put every range in ONE call. Use `{ file, windows: [{ offset, limit }] }`. Each window is served in that turn, so its anchors work in the same apply_patch call. A window can also be `{ around_anchor, radius }` to centre on a line this session already served. An anchor outside this session's served rows is omitted with an inline `[Window warning: ...]`.
+- read: a requested window of 61 lines or fewer can widen to its enclosing block; overlapping or adjacent windows fold before this test. Caps are 80 lines for code and Markdown, 40 for plain text. Widened rows begin with `[widened <requested> -> <served>, <label>]`; above three requested windows the note is `[widened N windows: <ranges>]`. An over-cap Markdown section clamps and names `(section <extent>)`; over-cap code or plain text refuses with no note. `mode: "verbatim"` widens too, with no anchors.
+- read: when you will not apply_patch the file, pass `mode: "verbatim"` for plain content with no anchors. Examples are a config value, docs, a README, or skill content (a SKILL.md or any file in its directory). Omit `mode` when you intend to use the anchors with apply_patch, so the rows carry anchors.
+- read: send one file per call as `{ file, windows?, mode? }`, the same way `apply_patch` does. The single top-level `mode` applies to the file. To read several files, make parallel `read` calls.
 - read: PNG/JPG images return as image attachments for multimodal models. Request one with `file` like any other file.

package/prompts/read.md

@@ -1 +1 @@
-Read one text file via `file`, with optional `windows` and top-level `mode`. To read several files, make parallel `read` calls. Served mode (default) returns each line as HASH│content with a 4-char alphanumeric hash. That hash is the `edit` anchor, so copy only the 4 chars before `│`. Pass `mode: "verbatim"` for plain text with no anchors when you will not edit. `mode: "verbatim"` is not capped by line budget. Name ranges with `windows`: `[{ offset, limit }]` (offset is 1-indexed, limit is a line count, maximum 16 windows) or `[{ around_anchor: "a1b2", radius: 10 }]` for a line this session served. When a page stops short, continue from the next unshown line with `windows: [{ offset, limit }]`. A requested window of 24 lines or fewer can widen to its enclosing block before serving; overlapping or adjacent windows fold before this test. Caps are 80 lines for code and Markdown, 40 for plain text. A widened page begins with `[widened <requested> -> <served>, <label>]`; more than three requested windows collapse to `[widened N windows: <ranges>]`. An over-cap Markdown section clamps to a cap-sized window and names `(section <extent>)`; an over-cap code or plain-text block refuses, serving the requested window. `mode: "verbatim"` widens the same way but adds no anchors. Inline `[...]` notices describe the served result, not file content. Empty files return `HASH│` (edit to insert). PNG/JPG/GIF/WebP return as image attachments for multimodal models. Binary and directory files are rejected. Hashes are file-scoped: an anchor is bound to the file it was served from.
+Read one text file via `file`, with optional `windows` and top-level `mode`. To read several files, make parallel `read` calls. Served mode (default) returns each line as HASH│content with a 4-char alphanumeric hash. That hash is the `apply_patch` identity anchor, so copy only the 4 chars before `│`. Pass `mode: "verbatim"` for plain text with no anchors when you will not apply_patch. `mode: "verbatim"` is not capped by line budget. Name ranges with `windows`: `[{ offset, limit }]` (offset is 1-indexed, limit is a line count, maximum 16 windows) or `[{ around_anchor: "a1b2", radius: 10 }]` for a line this session served. When a page stops short, continue from the next unshown line with `windows: [{ offset, limit }]`. A requested window of 61 lines or fewer can widen to its enclosing block before serving; overlapping or adjacent windows fold before this test. Caps are 80 lines for code and Markdown, 40 for plain text. A widened page begins with `[widened <requested> -> <served>, <label>]`; more than three requested windows collapse to `[widened N windows: <ranges>]`. An over-cap Markdown section clamps to a cap-sized window and names `(section <extent>)`; an over-cap code or plain-text block refuses, serving the requested window. `mode: "verbatim"` widens the same way but adds no anchors. Inline `[...]` notices describe the served result, not file content. Empty files return `HASH│` (use an apply_patch identity hunk to insert). PNG/JPG/GIF/WebP return as image attachments for multimodal models. Binary and directory files are rejected. Hashes are file-scoped: an anchor is bound to the file it was served from.

package/prompts/undo-last-edit-guidelines.md

@@ -1,2 +1,2 @@
-- undo_last_edit: reverts the most recent `edit` call on the file at `path`, and every item of its `edits`. Its scope is the edited file. The exception is an edit that was a foreign `cut`: undo then restores the source file too. The file must still hold the edited bytes. An out-of-band write makes the call fail with `E_UNDO_STALE`, and the file stays byte-identical. Call it as soon as a result is bad.
-- undo_last_edit: a `write` to the file, or a later `edit`, replaces the undo entry. A read, a bash view or an out-of-band write leaves the entry in place. An edit is bad when its post-edit diff shows `-HASH│` rows for lines you meant to keep. Examples are a closing brace, an import, or a declaration.
+- undo_last_edit: reverts the most recent `apply_patch` batch that touched the file at `path`, and every member of that batch: text hunks plus file lifecycle actions (add/delete/move). The exception is a foreign `cut`: undo then restores the source file too. The file must still hold the edited bytes. An out-of-band write makes the call fail with `E_UNDO_STALE`, and the file stays byte-identical. Call it as soon as a result is bad.
+- undo_last_edit: a `write` to the file, or a later `apply_patch` batch, replaces the undo entry. A read, a bash view or an out-of-band write leaves the entry in place. An apply_patch result is bad when its diff shows `-HASH│` rows for lines you meant to keep. Examples are a closing brace, an import, or a declaration.