dsh-hashline-edit 0.2.0 → 0.2.2

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, apply-patch, platform) compiles
+ * hashline core in `src/`. Every lane (host, read, edit, platform) compiles
  * against this file; renaming or reshaping an export here is a cross-lane
  * breaking change.
  *
@@ -67,15 +67,6 @@ 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 {
@@ -133,7 +124,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`/`apply_patch` calls never touch the provider's own
+ * existing file. Shadowed `read`/`edit` 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.
  *
@@ -199,7 +190,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/apply-patch.ts` → `buildApplyPatchTool` (tool name `apply_patch`)
+ * - `dsh/tools/edit.ts` → `buildEditTool` (tool name `edit`)
  * - `dsh/tools/undo.ts` → `buildUndoTool` (tool name `undo_last_edit`)
  */
 export type ToolDefinitionFactory = (deps: ToolDependencies) => ToolDefinition;

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

@@ -41,9 +41,6 @@ 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:apply_patch`. */
+    /** Registry section name, e.g. `tool:edit`. */
     readonly name: string;
-    /** Override file name inside a preset directory, e.g. `apply-patch.md`. */
+    /** Override file name inside a preset directory, e.g. `edit.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" | "TOOL_APPLY_PATCH";
+    readonly orderName?: "TOOL_READ" | "TOOL_EDIT";
     /** The compiled default text. */
     renderDefault(): string;
 }
 /**
- * The three sections, in default-order sequence. Read and undo reuse the pi
- * host's prompt sources; apply_patch owns the v4 mutation guidance.
+ * 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.
  */
 export declare const GUIDANCE_SECTIONS: readonly GuidanceSection[];
 /** Render the compiled default text for one section. */

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

@@ -1,11 +1,82 @@
+/** 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;
+}
 /**
- * dsh host shim for the host-neutral utilities the core uses.
+ * Minimal structural stand-in for pi's extension-registry type.
  *
- * 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: `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).
  *
- * @module dsh-hashline-edit/host-compat
+ * 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 * from "../src/host-utils.js";
+export declare function withFileMutationQueue<T>(filePath: string, run: () => Promise<T>): Promise<T>;

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

@@ -1,16 +1,17 @@
 /**
  * dsh-hashline-edit host plugin entry.
  *
- * 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
+ * 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
  * 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.
  *
+ * `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. apply_patch and
- * undo stay local-only (the M5 bridge covers reads; M6 owns mutation).
+ * composition still loads with the local `node:fs` fallback. Edit/undo stay
+ * local-only (the M5 bridge covers reads; M6 owns mutation).
  * @module dsh-hashline-edit
  */
 import type { Context } from "@deepseek-ai/cordis";
@@ -23,17 +24,6 @@ export declare const name = "dsh-hashline-edit";
  * services are resolved with `ctx.get` inside `dsh/sandbox.ts` instead.
  */
 export declare const inject: string[];
-/** The plugin configuration the loader passes as the second `apply` argument. */
-export interface PluginConfig {
-    /**
-     * Hide the native `edit`/`str_replace_editor` tools so every precise text
-     * change goes through `apply_patch`. Defaults to true. `write` is not in
-     * that set on purpose: whole-file replacement has no apply_patch operation.
-     */
-    hideNativeWriteTools?: boolean;
-    /** Extra global tool names to hide alongside the native write set. */
-    hiddenToolNames?: readonly string[];
-}
 /**
  * Install the hashline toolset for one agent inside its own effect, so the
  * registrations are disposed in reverse order when the agent scope unwinds.
@@ -41,6 +31,6 @@ export interface PluginConfig {
  * 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, config?: PluginConfig): void;
+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, config?: PluginConfig): void;
+export declare function apply(rootCtx: Context): 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" | "apply_patch" | "undo_last_edit" | "write" | "shell_view" | (string & {});
+type ToolName = "read" | "edit" | "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`,
- * `apply_patch` and `undo_last_edit` from the tool boundaries, plus `shell_view` from
+ * `edit` 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 `apply_patch`/`undo_last_edit` ask for wider
+ * `@deepseek-ai/dsh-sandbox` pieces) so `edit`/`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 `apply_patch` and `undo_last_edit`
+ * The filesystem escalation controller shared by `edit` 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 `apply_patch` hunk resolves the anchors.
+ * through the read tool's seam so a following `edit` 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/edit.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import type { ToolDependencies } from "../contracts.js";
+/** dsh tool name; the agent-layer registration shadows the preset's built-in `edit`. */
+export declare const EDIT_TOOL_NAME = "edit";
+/**
+ * Build the dsh `edit` tool for one agent install.
+ * @param deps - the host seams this tool may touch; `sandbox` advertises and resolves escalation.
+ * @returns a registry-ready dsh tool definition named `edit`.
+ */
+export declare function buildEditTool(deps: ToolDependencies): 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 `apply_patch` identity hunk can verify the
+ * mode every shown row is recorded as served, so a later `edit` 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 `apply_patch`. */
+    /** The line's 4-character anchor, usable by `edit`. */
     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 `apply_patch` hunk uses.
+ * must be leased to the session the following `edit` uses.
  */
 export declare function serveFileLines(deps: ToolDependencies, request: ServeFileLinesRequest): Promise<ServedFileLine[]>;
 /**

package/lib/types/src/domain-errors.d.ts

@@ -28,13 +28,13 @@
  * See ADR-0047.
  */
 export type Audience = "MODEL" | "USER";
-export type DomainErrorCode = "E_BAD_PAYLOAD" | "E_EMPTY_RANGE" | "E_STALE_ANCHOR" | "E_UNKNOWN_ANCHOR" | "E_FOREIGN_ANCHOR" | "E_STALE_RANGE" | "E_TARGET_LOST" | "E_UNVERIFIED_RANGE" | "E_MALFORMED_ANCHOR" | "E_SUSPICIOUS_TEXT" | "E_BATCH_ABORT" | "E_NOOP_LOOP" | "E_UNSUPPORTED_FILE" | "E_ACCESS" | "E_NOT_FOUND" | "E_UNDO_STALE" | "E_UNDO_UNAVAILABLE" | "E_LOSSY_TEXT" | "E_UNDO_REVERT_FAILED" | "E_UNKNOWN" | "E_LARGE_FILE" | "E_INTERNAL_INVARIANT" | "E_PATCH_SYNTAX" | "E_UNIQUE_MATCH";
+export type DomainErrorCode = "E_BAD_PAYLOAD" | "E_EMPTY_RANGE" | "E_STALE_ANCHOR" | "E_UNKNOWN_ANCHOR" | "E_FOREIGN_ANCHOR" | "E_STALE_RANGE" | "E_TARGET_LOST" | "E_UNVERIFIED_RANGE" | "E_MALFORMED_ANCHOR" | "E_SUSPICIOUS_TEXT" | "E_BATCH_ABORT" | "E_NOOP_LOOP" | "E_UNSUPPORTED_FILE" | "E_ACCESS" | "E_NOT_FOUND" | "E_UNDO_STALE" | "E_UNDO_UNAVAILABLE" | "E_LOSSY_TEXT" | "E_UNDO_REVERT_FAILED" | "E_UNKNOWN" | "E_LARGE_FILE" | "E_INTERNAL_INVARIANT";
 /**
  * The registered tool whose call produced an `E_BAD_PAYLOAD`. WHY the registered name: the model
  * reads the tool list, so `undo_last_edit` names the call it must repair and a short form would
  * name nothing. A tool belongs here only after a live path is measured, never by assumption.
  */
-export type PayloadSubject = "read" | "edit" | "apply_patch" | "undo_last_edit";
+export type PayloadSubject = "read" | "edit" | "undo_last_edit";
 export declare function isPayloadSubject(value: unknown): value is PayloadSubject;
 /**
  * Applied-tier warning codes — the `W_*` namespace (spec
@@ -180,20 +180,6 @@ export interface ErrorPayloadMap {
          */
         subject?: PayloadSubject;
     };
-    E_PATCH_SYNTAX: {
-        message: string;
-        path?: string;
-        patchLine?: number;
-        servedRows?: ServedRow[];
-        servedBlock?: string;
-    };
-    E_UNIQUE_MATCH: {
-        message: string;
-        path?: string;
-        patchLine?: number;
-        servedRows?: ServedRow[];
-        servedBlock?: string;
-    };
 }
 export interface CodeSpec<P> {
     audience: Audience;

package/lib/types/src/edit-tool.d.ts

@@ -0,0 +1,41 @@
+/** SAFETY: EditTool — deep module owning the edit Use Case seam.
+ *
+ * Graded surface: one narrow interface `EditTool { execute, preview }`
+ * hides pipeline delegation, warnings/drift stitching.
+ * Frameworks (pi TUI) never cross this seam — that lives in TuiPresenter.
+ * Clean Architecture: Use Cases depend inward only (mutation-engine),
+ * never outward to Frameworks.
+ *
+ * Typed boundaries: validate once at admission (payload-contract via normReq/assertReq),
+ * trust inside. Immutable state: never mutates caller-owned request.
+ */
+type EditToolContext = {
+    cwd: string;
+    sessionManager?: {
+        getSessionId(): string;
+    };
+};
+export type PreviewContext = {
+    sessionManager?: {
+        getSessionId(): string;
+    };
+};
+type PreviewResult = {
+    diff: string;
+} | {
+    error: string;
+};
+export interface EditTool {
+    /** SAFETY: Execute a validated edit; returns pi tool_result or throws on failure. Admission: params validated by normReq/assertReq. */
+    execute(params: unknown, signal: AbortSignal | undefined, ctx: EditToolContext): Promise<{
+        content: Array<{
+            type: "text";
+            text: string;
+        }>;
+        details: unknown;
+    }>;
+    /** SAFETY: Preview without persisting — mirrors pi's compPreview(request, cwd, ctx). The ctx must carry the session whose serves the anchors came from (#165). */
+    preview(request: unknown, cwd: string, ctx: PreviewContext): Promise<PreviewResult>;
+}
+export declare function createEditTool(): EditTool;
+export {};

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

@@ -1,5 +1,5 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type LineEnding } from "./edit-diff.js";
-import type { UndoLifecycle } from "./undo-store.js";
 export interface UndoEntry {
     content: string;
     bom: string;
@@ -26,16 +26,6 @@ export interface UndoEntry {
     rawPre?: string | null;
     /** The anchor generation the stored hashes were derived under (0 = pre-generation). */
     anchorGeneration?: number | null;
-    /** The lifecycle action this entry reverses; absent/null is an ordinary edit. */
-    lifecycle?: UndoLifecycle | null;
-    /** Move: the absolute pre-transaction path. */
-    fromPath?: string | null;
-    /** Move: the absolute committed path. */
-    toPath?: string | null;
-    /** The raw post-transaction text when the commit wrote non-canonical bytes (pure move). */
-    rawPost?: string | null;
-    /** Add: directories the add created, outermost first. */
-    createdDirs?: readonly string[] | null;
 }
 export declare function saveUndo(path: string, entry: UndoEntry): Promise<{
     persisted: boolean;
@@ -77,3 +67,4 @@ export declare function executeUndoLastEdit(params: {
 }, ctx: UndoLastEditContext, options?: {
     withFileMutationQueue?: UndoMutationQueue;
 }): Promise<UndoLastEditResult>;
+export declare function regEditUndo(pi: ExtensionAPI): void;

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

@@ -12,7 +12,7 @@ import { visLines } from "../utils.js";
 import { type FileStats, type LFile } from "./detection.js";
 import { type ReadWindow, type ShownRange } from "./preview.js";
 import type { ServedRow } from "../served-session/serve-render.js";
-import type { TruncationResult } from "../host-utils.js";
+import type { TruncationResult } from "@earendil-works/pi-coding-agent";
 export type { FileStats, LFile, LoadFileOptions } from "./detection.js";
 export { decodeUtf8Strict, loadFileKindAndText } from "./detection.js";
 export { readNormFile, decodeNormText, fileSnap, snapshotIdFor, statKeyOf, type NormText, type NormFile, type SnapInfo, type StatIdentity, type ReadNormOptions, } from "./loader.js";

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

@@ -1,4 +1,4 @@
-import { type TruncationResult } from "../host-utils.js";
+import { type TruncationResult } from "@earendil-works/pi-coding-agent";
 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/hash-store.d.ts

@@ -14,9 +14,9 @@ export type StoreOpenHook = (db: DatabaseSync, info: {
 }) => void | Promise<void>;
 export declare function onStoreOpen(hook: StoreOpenHook): void;
 /** `file_snapshots` rows whose persisted anchor generation is not the current one. */
-export declare const FOREIGN_GENERATION_SNAPSHOT_SQL = "anchor_generation != 1";
+export declare const FOREIGN_GENERATION_SNAPSHOT_SQL: string;
 /** `served_leases` rows whose served snapshot hash carries a foreign anchor generation. */
-export declare const FOREIGN_GENERATION_LEASE_SQL = "served_snapshot_hash NOT LIKE '%:1:%'";
+export declare const FOREIGN_GENERATION_LEASE_SQL: string;
 /** `line_lineage` rows naming a snapshot that no longer exists. */
 export declare const ORPHAN_LINEAGE_SQL = "snapshot_id NOT IN (SELECT snapshot_id FROM file_snapshots)";
 /**

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

@@ -1,4 +1,19 @@
-export declare const HASH_LEN = 4;
+/**
+ * Anchor width — the single owner of the anchor's length and shape.
+ *
+ * WHY an environment variable rather than a settings-file key: `alphabet.ts` is a zero-import leaf
+ * and every shape, regex, bitset and capacity constant below is derived at module load, so the
+ * width can only be a process-wide, load-time value. Switching it changes every served anchor; the
+ * persisted store stays safe because the anchor generation (`hash-identity.ts`) folds the width in,
+ * so a switch is a hard generation miss (re-read), never a cross-width hit.
+ */
+export declare const ANCHOR_WIDTH_ENV_VAR = "PI_BETTER_EDIT_ANCHOR_WIDTH";
+/**
+ * Resolve the anchor width from an environment map. Pure and dependency-free so the leaf stays a
+ * leaf and the ladder is unit-testable without mutating `process.env`.
+ */
+export declare function resolveAnchorWidth(env: Record<string, string | undefined>): number;
+export declare const HASH_LEN: number;
 export declare const ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 export declare const ALPHA_RE: RegExp;
 export declare const HASH_CLASS: string;

package/lib/types/src/hashline/hash-identity.d.ts

@@ -42,7 +42,7 @@ export interface AnchorWalk {
     /** The anchors this content already has in the store, in line order. */
     cached?: string[];
 }
-export declare const ANCHOR_LEN = 4;
+export declare const ANCHOR_LEN: number;
 export declare const HASH_SEP = "\u2502";
 export declare const HASH_SPACE: number;
 export declare const USABLE_HASH_SPACE: number;
@@ -61,19 +61,25 @@ export declare const HASH_PROBE_STRIDE: number;
  */
 export declare const CANON_VERSION = 3;
 /**
- * ANCHOR_GENERATION 1 (issue #20, ADR-0031): the file-scoped anchor-derivation generation.
+ * The file-scoped anchor-derivation generation (issue #20, ADR-0031; ADR-0020 for the width axis).
  * It covers exactly: (1) the width (`HASH_LEN`, `ALPHA`, `HASH_SPACE`/`USABLE_HASH_SPACE`);
  * (2) the (path, content) seeding (`fileBaseIndex` seeds xxh32 with the canonical absolute path,
  * `contentBaseIndex` is the explicit content-only fallback); (3) the all-digit reservation
  * (`DIGIT_CHARS`/`RESERVED_HASH_SPELLINGS`/`RESERVED_BITS` pre-marked in allocation); (4) the probe
  * stride (`HASH_PROBE_STRIDE`, coprime with both spaces). Bump it whenever any of those change.
  *
- * WHY: single owner of the anchor-generation literal — anchor-bearing artifacts (the undo/snapshot
+ * WHY it is a function of the width now: the width is a runtime switch (default 4, optional 3), so a
+ * width change MUST flip the generation or a store written at one width could be read at another.
+ * Width 4 stays generation 1 — the original persisted generation — so existing stores keep their
+ * anchors across this change; width 3 gets generation 2, and any future width gets `100 + width`.
+ *
+ * WHY: single owner of the anchor-generation value — anchor-bearing artifacts (the undo/snapshot
  * generation gate and the open-time sweep) read this axis only, never `CANON_VERSION`; the snapshot
  * cache key carries both (`${CANON_VERSION}:${ANCHOR_GENERATION}:${checksum}`), so a canon-only change
  * misses the cache without invalidating anchor state while a generation change invalidates both.
  */
-export declare const ANCHOR_GENERATION = 1;
+export declare function anchorGenerationFor(width: number): number;
+export declare const ANCHOR_GENERATION: number;
 export declare function canon(line: string): string;
 /**
  * SAFETY: the canon digest — `String(xxh32(canon(line)))`, the exact value `line_lineage.canon_hash`

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

@@ -0,0 +1,31 @@
+/**
+ * SAFETY: MutationEngine — deep module behind the mutation seam.
+ *
+ * Small interface: `execute` + `preview`. Deep implementation: load → parse
+ * → mutate → finalize → drift → persist → serve hidden inside the pipeline.
+ * Internal seams (validate, verify, mutate, guard, persist, record) stay
+ * private — not exported. The interface is the test surface.
+ *
+ * Typed boundaries: validate once at admission (edit.ts via payload-contract),
+ * trust inside. Errors fail loud with typed `MutationFailure`.
+ */
+import type { PipelineOptions } from "./types.js";
+import type { MutationResult } from "./types.js";
+import type { NormalizedEditRequest } from "../payload-contract.js";
+declare function toFailure(error: unknown): MutationResult;
+/**
+ * SAFETY: Execute a mutation against the file system (persist + undo + serve).
+ * Returns discriminated `MutationResult` — callers must switch on `ok`.
+ *
+ * No `any` threading: input is `NormalizedEditRequest` (validated at
+ * admission), output is typed. Failures are `ok:false` with `code`, not
+ * loose `isError` flags.
+ */
+export declare function execute(request: NormalizedEditRequest, cwd: string, options?: PipelineOptions): Promise<MutationResult>;
+/**
+ * SAFETY: Preview a mutation without persisting (noPersist). Same seam as `execute`,
+ * same `MutationResult` — one interface, N call sites (preview + apply share
+ * the internal path via `runMutations` with `noPersist:true`).
+ */
+export declare function preview(request: NormalizedEditRequest, cwd: string, options?: Omit<PipelineOptions, "noPersist">): Promise<MutationResult>;
+export { toFailure };

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

@@ -1,9 +1,8 @@
-import type { NormalizedEditRequest } from "./edit-request.js";
+import type { NormalizedEditRequest } from "../payload-contract.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>;
-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;
@@ -21,9 +20,3 @@ interface BatchOutcome {
 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 };