dsh-hashline-edit 0.2.0 → 0.2.2

package/README.md

@@ -2,9 +2,9 @@
 
 Hash-anchored file editing for [DeepSeek Harness](https://github.com/deepseek-ai) (dsh) on Windows.
 
-`dsh-hashline-edit` is a dsh bundle that shadows the host's built-in `read` with hash-anchored output, registers `apply_patch` as the only file-mutation entry point, and adds `undo_last_edit`. There is no `edit` tool and no pi host support: this package target is DeepSeek Harness only. Every line a served read shows carries a stable 4-character base62 anchor (`A–Z`, `a–z`, `0–9`) derived from the file's canonical path and the line's content. An `apply_patch` hunk either names served anchors or matches file content; the model never re-types existing code. Anchors for unchanged lines stay stable across edits, and every successful `apply_patch` call returns fresh anchors for the changed lines, so chained calls need no re-read.
+`dsh-hashline-edit` is a dsh bundle that shadows the host's built-in `read` and `edit` tools with hashline equivalents and adds `undo_last_edit`. Every line a served read shows carries a stable 3- or 4-character base62 anchor (`A–Z`, `a–z`, `0–9`) derived from the file's canonical path and the line's content (the width is a runtime setting; see [Anchor width](#anchor-width)). An edit names two anchors and new text; it never re-types existing code. Anchors for unchanged lines stay stable across edits, and every successful edit returns fresh anchors for the changed lines, so chained edits need no re-read.
 
-The semantic core is the [pi-better-edit](https://github.com/Rianico/pi-better-edit) v2.16.0 hashline engine (MIT), carried as an internal engine; the pi host integration has been removed. The `dsh/` tree is this repository's DeepSeek Harness host layer: tool registration, filesystem bridge, UTF-8-only admission, prompt guidance, shell integration, write integration and telemetry. See [`dsh/README.md`](dsh/README.md) for the host-layer map.
+The semantic core is the [pi-better-edit](https://github.com/Rianico/pi-better-edit) v2.16.0 hashline engine (MIT). The `dsh/` tree is this repository's DeepSeek Harness host layer: tool registration, filesystem bridge, UTF-8-only admission, prompt guidance, shell integration, write integration and telemetry. See [`dsh/README.md`](dsh/README.md) for the host-layer map.
 
 ## Requirements
 
@@ -13,7 +13,23 @@ The semantic core is the [pi-better-edit](https://github.com/Rianico/pi-better-e
 | OS | Windows — this branch targets Windows only (see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)) |
 | Node.js | ≥ 24.0.0 |
 | pnpm | 12.x |
-| DeepSeek Harness | plugin-capable build; the repository is developed against `@deepseek-ai/dsh-*@0.2.2-alpha.3` |
+| DeepSeek Harness | plugin-capable build; the repository is developed against `@deepseek-ai/dsh-*@0.2.1-rc.2` |
+
+### Anchor width (3 or 4)
+
+The anchor width is baked into the build. Set `PI_BETTER_EDIT_ANCHOR_WIDTH` when you build or pack:
+
+- `PI_BETTER_EDIT_ANCHOR_WIDTH=3 pnpm run build` (or `pnpm pack` / install) produces a fully 3-char artifact.
+- unset or `4` builds the 4-char default.
+
+| Value | Anchor width | Usable space | Anchor generation |
+| --- | --- | --- | --- |
+| unset or `4` (default) | 4 chars | 14,766,336 | 1 |
+| `3` | 3 chars | 237,328 | 2 |
+
+The value is inlined into the bundle at build time (`esbuild define`), so the installed plugin never reads an environment variable at runtime — a 3-char build stays 3-char. The persisted store is keyed by the anchor generation, so changing the build width is a hard cache miss (served rows are simply re-read), never a cross-width hit. Width 4 keeps generation 1, so existing stores keep working unchanged.
+
+Measured on the DeepSeek-V4.1 tokenizer, a 3-char anchor averages ~2.3 tokens and a 4-char anchor ~3.0 tokens per served line, and neither collapses to one token (see [ADR-0020](docs/adr/0020-configurable-anchor-width-3-4.md)). The default stays 4 to preserve the existing persisted contract; build with `PI_BETTER_EDIT_ANCHOR_WIDTH=3` to ship 3-char.
 
 ## Install
 
@@ -36,7 +52,7 @@ For a tarball, pack first and add the archive:
 
 ```sh
 pnpm pack
-dsh plugin add ./dsh-hashline-edit-0.2.0.tgz
+dsh plugin add ./dsh-hashline-edit-0.1.0.tgz
 ```
 
 The bundle ships `lib/index.js` plus `lib/types/**`; `prompts/` must sit next to `lib/` in the installed package (it is in `files`). Guidance override files are materialized under `<DSH_HOME>/plugins/dsh-hashline-edit/guidance/` and are shared between profiles.
@@ -55,7 +71,7 @@ p9rX│  return total;
 a1bX│}
 ```
 
-Copy only the 4 characters before `│` into `anchor_from` / `anchor_to`. An `apply_patch` identity hunk targets an inclusive served range; a successful call returns a diff whose modified and context rows carry fresh anchors:
+Copy only the 4 characters before `│` into `anchor_from` / `anchor_to`. An edit targets an inclusive range and returns a diff whose modified and context rows carry fresh anchors:
 
 ```text
 - szJx│  let total = 0;
@@ -84,58 +100,48 @@ read({
 })
 ```
 
-- **Served mode** returns one `HASH│content` row per line and records every shown row as a lease for this session. A windowed read also includes a `[Lines A-B of N total]` page header. Every row shown is usable by one subsequent `apply_patch`, even when the windows are far apart.
-- **Verbatim mode** returns the same page as plain text with no anchors and serves nothing; an `apply_patch` identity hunk cannot target those lines.
+- **Served mode** returns one `HASH│content` row per line and records every shown row as a lease for this session. A windowed read also includes a `[Lines A-B of N total]` page header. Every row shown is usable by one subsequent edit, even when the windows are far apart.
+- **Verbatim mode** returns the same page as plain text with no anchors and serves nothing; an edit cannot target those lines.
 - A small requested window — up to 61 lines after folding — may widen to its enclosing function, method, class, section or paragraph; a `[widened …]` note names the block that was served. Expansion applies in both modes. Languages: TypeScript/TSX, Python, Go, Rust, Java and Vue through pinned tree-sitter wasm grammars (fetched lazily and verified against a committed SHA-256), plus Bash through the existing `unbash` parser (no wasm). Vue widens a top-level `template`/`script`/`style` block without parsing embedded JS/TS. SQL is not supported: real migrations largely fail to parse and `.tql` is a Java template, not SQL (see [`docs/spec/sql-vue-feasibility-gate.md`](docs/spec/sql-vue-feasibility-gate.md)).
-- `offset`/`limit` and `windows` are page requests, not anchors: only `served` output grants mutation leases.
+- `offset`/`limit` and `windows` are page requests, not anchors: only `served` output grants edit leases.
 
-### `apply_patch`
+### `edit`
 
-The only file-mutation entry point. One call carries one Codex patch document and commits the whole
-batch as one correlated transaction (pre-mirror, undo rows, deterministic member order, all-or-nothing
-rollback, then per-file store commits).
-
-```text
-*** Begin Patch
-*** Update File: src/config.ts
-@@
--  retries: 3,
-+  retries: 5,
-*** Add File: src/new.ts
-+export const x = 1;
-*** End Patch
+```ts
+edit({
+  file: string,                 // default target for items that omit `file`
+  edits: [{
+    file?: string,               // optional per-item target; falls back to the call's `file`
+    anchor_from: string,        // bare 4-char anchor of the first range line (inclusive)
+    anchor_to: string,          // bare 4-char anchor of the last range line (inclusive)
+    text?: string,              // by-value content; "" deletes an in-place range
+    text_ref?: {                // by-reference content from a served span
+      anchor_from: string,
+      anchor_to: string,
+      file?: string,            // another served file (foreign-source copy/cut)
+      mode: "copy" | "cut",     // required: copy keeps the source, cut retires the span
+    },
+    at?: "in-place" | "before" | "after",  // default "in-place"
+  }],
+  mode?: "general" | "literal", // "general" refuses served-row echoes; "literal" declares them intended
+})
 ```
 
-Addressing works in two modes, and one patch may mix them:
-
-- **Fragment hunks** use the official Codex syntax. `@@` starts the search window at the file start;
-  `@@ <one context line>` moves the window after that line's unique match. Body lines are
-  ` ` (context), `-` (remove) and `+` (add). Matching is byte-exact and must be unique: zero or
-  multiple matches reject the whole call and serve the candidate rows back.
-- **Identity hunks** use the `@@<a>` / `@@<a>-<b>` extension: two inclusive 4-char anchors from rows
-  this session served. The body is `+` lines only; an empty body deletes the span. A stale, unknown
-  or foreign anchor is rejected with the file's current rows served.
-- **Reference hunks** `*** Copy From: <path> <a>-<b>` / `*** Cut From: <path> <a>-<b>` take the
-  bytes of another served span; a cut also retires the source span in the same transaction.
-- **Lifecycle** `*** Add File:`, `*** Delete File:` and `*** Move to:` join text edits in the same
-  transaction and the same undo record. `*** End of File` pins a hunk to the file tail.
-
-`@@` followed by a space is Codex's context mode; `@@` immediately followed by four anchor
-characters is identity mode. Any rejection leaves every file byte-identical and reports every
-independent problem with its patch line number and `[E_*`] code. Success returns a file-level summary
-(A/M/R/D) followed by fresh `HASH│content` anchors for every changed line, so the next call can chain
-without a `read`. The host's built-in `write` remains for whole-file rewrites.
+Each item carries exactly one of `text` or `text_ref`; supplying both or neither is refused. An item without `file` targets the call's top-level file; an item that names one may target another served file, so one call may edit several files. The whole call commits as one correlated transaction (pre-mirror, undo rows, ordered renames, all-or-nothing rollback, then per-file store commits) and a refusal leaves every file untouched. `before`/`after` insert at the range boundary and require a single-line resolved target. A foreign-source `cut` writes both files as one correlated transaction; `undo_last_edit` reverts both members. An edit never silently rewrites submitted text — a refused edit writes nothing.
+
+The result is the core's unified diff with fresh anchors for the changed lines, so the next edit can chain from them without a `read`. The host's built-in `write` is not replaced: the plugin guards it against served-row echoes and appends an anchored auto-read so following edits can use its output.
+
 ### `undo_last_edit`
 
 ```ts
 undo_last_edit({ path: string })
 ```
 
-Restores the previous file content, BOM, line endings and original anchors from a snapshot-pinned undo record. The record survives agent restarts. A file changed externally after the patch is refused with `[E_UNDO_STALE]`. A correlated cut's undo restores every member of the transaction, not only the named path.
+Restores the previous file content, BOM, line endings and original anchors from a snapshot-pinned undo record. The record survives agent restarts. A file changed externally after the edit is refused with `[E_UNDO_STALE]`. A correlated cut's undo restores every member of the transaction, not only the named path.
 
 ## Shell view
 
-The plugin installs a `tools/post-execute` listener for the host's `pwsh`, `bash` and built-in `grep` tools. When the command is a whitelisted read-only file view, the captured stdout is replaced with the aligned file's `HASH│content` rows, and those rows are served (leased) exactly like a read — a following `apply_patch` can use them with no re-read. A built-in grep result whose matches are proven against disk is served the same way (see the table below).
+The plugin installs a `tools/post-execute` listener for the host's `pwsh`, `bash` and built-in `grep` tools. When the command is a whitelisted read-only file view, the captured stdout is replaced with the aligned file's `HASH│content` rows, and those rows are served (leased) exactly like a read — a following `edit` can use them with no re-read. A built-in grep result whose matches are proven against disk is served the same way (see the table below).
 
 | Command shape | Served as |
 | --- | --- |
@@ -161,7 +167,7 @@ A file that is not valid UTF-8 is refused with `[E_UNSUPPORTED_FILE]` naming the
 The built-in `write` integration and `undo_last_edit` speak the same contract: they write UTF-8, and every file this plugin serves is UTF-8.
 ## Sandbox behavior
 
-`apply_patch` and `undo_last_edit` carry the host's optional escalation fields `sandbox_permissions` and `justification` only when a confining filesystem backend is mounted. `dsh/sandbox.ts` mirrors the built-in `@deepseek-ai/dsh-tool-fs` controller: it validates the field pairing, repeats the standing mode without approval, and resolves a strictly wider mode through the host's approval channel before touching the filesystem. A provider `FS_SANDBOX_DENIED` error is mapped to the standard model-facing denial marker plus escalation hint; other errors pass through unchanged.
+`edit` and `undo_last_edit` carry the host's optional escalation fields `sandbox_permissions` and `justification` only when a confining filesystem backend is mounted. `dsh/sandbox.ts` mirrors the built-in `@deepseek-ai/dsh-tool-fs` controller: it validates the field pairing, repeats the standing mode without approval, and resolves a strictly wider mode through the host's approval channel before touching the filesystem. A provider `FS_SANDBOX_DENIED` error is mapped to the standard model-facing denial marker plus escalation hint; other errors pass through unchanged.
 
 ### Host-side `0xC0000142` workspace-write finding
 
@@ -182,7 +188,7 @@ The M3/M4 smoke runs therefore used `DSH_PERMISSION_MODE=danger-full-access`; th
 | `pnpm run lint` | `oxlint .` + `knip --max-issues 0` |
 | `pnpm run verify` | lint + format + typecheck + Windows coverage |
 
-The build enforces its own packaging contract: host packages stay external, the bundle must not reference pi (there is no pi host integration), and no bare import outside the allowlist can slip in. See [`dsh/README.md`](dsh/README.md#build-and-packaging).
+The build enforces its own packaging contract: host packages stay external, the pi utility package is aliased to `dsh/host-compat.ts` (the bundle must not reference pi), and no bare import outside the allowlist can slip in. See [`dsh/README.md`](dsh/README.md#build-and-packaging).
 
 ## Error and warning codes
 
@@ -193,7 +199,7 @@ Every refusal carries a bracketed code; `src/domain-errors.ts` is the source of
 | `[E_ACCESS]` | The filesystem denied access to the target path. |
 | `[E_BAD_PAYLOAD]` | Malformed or unknown tool payload; nothing is written. |
 | `[E_BATCH_ABORT]` | A batch item failed; the whole batch was not applied. |
-| `[E_EMPTY_RANGE]` | The patch would empty a non-empty file; use `write`. |
+| `[E_EMPTY_RANGE]` | The edit would empty a non-empty file; use `write`. |
 | `[E_FOREIGN_ANCHOR]` | The anchor belongs to a different file. |
 | `[E_INTERNAL_INVARIANT]` | An internal invariant was violated. |
 | `[E_LARGE_FILE]` | The file exceeds the served line or byte budget. |
@@ -201,23 +207,21 @@ Every refusal carries a bracketed code; `src/domain-errors.ts` is the source of
 | `[E_MALFORMED_ANCHOR]` | The anchor token cannot be parsed. |
 | `[E_NOOP_LOOP]` | Repeated identical no-op edits; refused with the current range served. |
 | `[E_NOT_FOUND]` | The target file does not exist or is unreachable. |
-| `[E_PATCH_SYNTAX]` | The apply_patch text is not valid syntax; nothing is written. |
 | `[E_STALE_ANCHOR]` | A boundary anchor no longer resolves against the file. |
-| `[E_STALE_RANGE]` | The served range changed between serve and patch. |
+| `[E_STALE_RANGE]` | The served range changed between serve and edit. |
 | `[E_SUSPICIOUS_TEXT]` | The replacement reproduces served anchor text (a copied `HASH│` echo). |
 | `[E_TARGET_LOST]` | The target line identity can no longer be resolved. |
 | `[E_UNDO_REVERT_FAILED]` | A correlated revert failed mid-way; a repair run finishes it. |
 | `[E_UNDO_STALE]` | The undo record is stale relative to the file. |
 | `[E_UNDO_UNAVAILABLE]` | There is no undo history for the path. |
-| `[E_UNIQUE_MATCH]` | A fragment hunk matched zero or multiple places; candidates are served back. |
 | `[E_UNKNOWN]` | An unclassified failure; the message carries the cause. |
 | `[E_UNKNOWN_ANCHOR]` | The anchor was never served in this session. |
 | `[E_UNSUPPORTED_FILE]` | Binary, image or directory targets are not editable text; a non-UTF-8 file is refused with its path and an instruction to ask the user how to handle it. |
 | `[E_UNVERIFIED_RANGE]` | The range interior cannot be verified (never served). |
-| `[W_LITERAL_BYPASS]` | Literal `HASH│` bytes were written through `apply_patch` and accepted with a warning. |
-| `[W_NEVER_SERVED_SHAPE]` | A never-served hint was attached to an accepted patch. |
-| `[W_NOOP]` | The patch produced no content change and was accepted as a no-op. |
-| `[W_NOOP_INSERT]` | An insert-shaped hunk produced no change. |
+| `[W_LITERAL_BYPASS]` | Literal `HASH│` bytes were written through `edit` and accepted with a warning. |
+| `[W_NEVER_SERVED_SHAPE]` | A never-served hint was attached to an accepted edit. |
+| `[W_NOOP]` | The edit produced no content change and was accepted as a no-op. |
+| `[W_NOOP_INSERT]` | An insert-shaped edit produced no change. |
 | `[W_REVERSED_ANCHORS]` | Boundaries were reversed and healed. |
 | `[W_SERVED_PREFIX_MISMATCH]` | A served prefix does not match; fresh rows were served. |
 | `[W_UNICODE_LITERAL]` | A Unicode literal in the payload looks like a copied anchor. |
@@ -226,7 +230,7 @@ Range-family rejections render their current-row evidence exactly once: the head
 
 ## Current limitations
 
-- **Mutation stays on the local `node:fs` seam.** The read path consumes a `CoreReadIo` port (local or mounted `ctx.fs`), but `writeAtomic`, the `apply_patch` engine and undo remain local-only. `apply_patch` and `undo_last_edit` fail closed with `E_NOT_FOUND` when the target is reachable only through `ctx.fs`. A full mutation bridge needs target-keyed store state: the host's `ctx.fs` already exposes versioned writes in `0.2.2-alpha.3`, but the snapshot/lease store still keys on absolute paths and local stat identity (M6, see [`dsh/README.md`](dsh/README.md#ctxfs-deferral-m6)).
+- **Mutation stays on the local `node:fs` seam.** The read path consumes a `CoreReadIo` port (local or mounted `ctx.fs`), but `writeAtomic`, the edit engine and undo remain local-only. `edit` and `undo_last_edit` fail closed with `E_NOT_FOUND` when the target is reachable only through `ctx.fs`. A full mutation bridge needs target-keyed store state: the host's `ctx.fs` already exposes versioned `writeText`/`editText` in `0.2.1-rc.2`, but the snapshot/lease store still keys on absolute paths and local stat identity (M6, see [`dsh/README.md`](dsh/README.md#ctxfs-deferral-m6)).
 - **UTF-8 only.** Non-UTF-8 files are refused on read and must be converted with an external tool; the plugin does not decode legacy code pages, does not re-encode on save, and keeps no encoding state.
 - **Windows-only.** The branch targets Windows; POSIX-only suites are excluded in `vitest.config.windows.ts`, and that exclusion list must shrink, never grow (see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)).
 
@@ -234,7 +238,7 @@ Range-family rejections render their current-row evidence exactly once: the head
 
 | Path | Role |
 | --- | --- |
-| `src/` | hashline engine core derived from pi-better-edit (semantic source; upstream fixes are picked selectively, see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)) |
+| `src/` | upstream pi-better-edit core (semantic source; upstream fixes are picked selectively, see [`dsh/UPSTREAM.md`](dsh/UPSTREAM.md)) |
 | `dsh/` | DeepSeek Harness host layer — the only code that differs from upstream; map in [`dsh/README.md`](dsh/README.md) |
 | `dsh/UPSTREAM.md` | upstream sync cursor, policy and Windows adaptation patches |
 | `dsh/baseline/` | milestone measurement baselines (M0–M5) |

package/cordis.patch.yml

@@ -1,7 +1,7 @@
 # dsh-hashline-edit bundle patch: mount the host-plane plugin row.
 # Installed via `dsh plugin --profile <name> add dsh-hashline-edit` (or a
 # profile's bundle list). The plugin hooks agent/created and shadows the
-# built-in read tool and hides its native edit surface on each agent's own scope layer, so no preset
+# built-in read/edit tools on each agent's own scope layer, so no preset
 # editing or user config is needed.
 - insert:
     - id: dsh-hashline-edit