dsh-hashline-edit 0.2.1 → 0.2.3

package/README.md

@@ -2,7 +2,7 @@
 
 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`. The native `write`/`edit`/`str_replace_editor` surface is hidden; there is no pi host support, because this package targets 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` with hash-anchored output, registers `apply_patch` as the only file-mutation entry point, and adds `undo_last_edit`. The native `write`/`edit`/`str_replace_editor` surface is hidden; there is no pi host support, because this package targets DeepSeek Harness only. Every line a served read shows carries a stable 3- or 4-character base62 anchor (`A–Z`, `a–z`, `0–9`; the width is a build-time setting, see [Anchor width](#anchor-width)) 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.
 
 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.
 
@@ -15,6 +15,22 @@ The semantic core is the [pi-better-edit](https://github.com/Rianico/pi-better-e
 | pnpm | 12.x |
 | DeepSeek Harness | plugin-capable build; the repository is developed against `@deepseek-ai/dsh-*@0.2.2-rc.1` (host packages are declared as peer dependencies) |
 
+### 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` (and `pnpm pack`) 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
 
 Build the plugin first: the dsh loader reads the package through `exports`/`main`, and `lib/` is gitignored.

package/lib/index.js

@@ -45,7 +45,7 @@ import {
 import { dirname as dirname2, join as join4, parse, resolve, sep } from "node:path";
 
 // src/hashline/alphabet.ts
-var HASH_LEN = 4;
+var HASH_LEN = true ? 3 : resolveAnchorWidth(process.env);
 var ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 var ALPHA_SAFE = ALPHA.replace(/-/g, "\\-");
 var ALPHA_RE = new RegExp(`^[${ALPHA_SAFE}]+$`);
@@ -1873,23 +1873,22 @@ import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 
 // src/prompts.ts
 import { readFileSync } from "node:fs";
-function loadP(relativePath2, replacements) {
-  let content = readFileSync(new URL(relativePath2, import.meta.url), "utf-8").trim();
+function applyReplacements(content, replacements) {
+  let out = content;
   if (replacements) {
     for (const [key, value] of Object.entries(replacements)) {
-      content = content.split(`{{${key}}}`).join(value);
+      out = out.split(`{{${key}}}`).join(value);
     }
   }
-  return content;
+  return out.split("{{HASH_LEN}}").join(String(HASH_LEN));
+}
+function loadP(relativePath2, replacements) {
+  const content = readFileSync(new URL(relativePath2, import.meta.url), "utf-8").trim();
+  return applyReplacements(content, replacements);
 }
 function loadGuide(relativePath2, replacements) {
-  let content = readFileSync(new URL(relativePath2, import.meta.url), "utf-8");
-  if (replacements) {
-    for (const [key, value] of Object.entries(replacements)) {
-      content = content.split(`{{${key}}}`).join(value);
-    }
-  }
-  return content.split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => line.slice(2));
+  const content = readFileSync(new URL(relativePath2, import.meta.url), "utf-8");
+  return applyReplacements(content, replacements).split("\n").map((line) => line.trim()).filter((line) => line.startsWith("- ")).map((line) => line.slice(2));
 }
 
 // dsh/guidance.ts
@@ -2612,7 +2611,10 @@ var HASH_SPACE_EXHAUSTED_PAYLOAD = {
 };
 var HASH_PROBE_STRIDE = ALPHA.length ** 2 + ALPHA.length + 1;
 var CANON_VERSION = 3;
-var ANCHOR_GENERATION = 1;
+function anchorGenerationFor(width) {
+  return width === 4 ? 1 : width === 3 ? 2 : 100 + width;
+}
+var ANCHOR_GENERATION = anchorGenerationFor(HASH_LEN);
 var CANON_CODE_POINTS = [
   9,
   10,

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,20 @@
-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. The build bakes it via esbuild `define`
+ * (`__ANCHOR_WIDTH__`), so a shipped bundle carries a literal and never reads the environment; the
+ * anchor generation (`hash-identity.ts`) folds the width in, so a width 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;
@@ -73,7 +73,18 @@ export declare const CANON_VERSION = 3;
  * 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;
+/**
+ * The file-scoped anchor-derivation generation. It covers the width (`HASH_LEN`, `ALPHA`,
+ * `HASH_SPACE`/`USABLE_HASH_SPACE`), the (path, content) seeding, the all-digit reservation and the
+ * probe stride. Bump it whenever any of those change.
+ *
+ * WHY it is a function of the width: the width is a build-time switch (ADR-0020: 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; width 3 gets generation 2, and any future width gets `100 + width`.
+ */
+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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-hashline-edit",
-  "version": "0.2.1",
-  "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.",
+  "version": "0.2.3",
+  "description": "Hash-anchored read/apply_patch tools for DeepSeek Harness (dsh). Every line gets a unique 3- or 4-char hash (A-Za-z0-9, configurable) 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",

package/prompts/apply-patch-guidelines.md

@@ -1,10 +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: the character after `@@` selects the mode. `@@` followed immediately by exactly {{HASH_LEN}} 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 is one `*** Update File:` identity hunk spanning every served line with `+` lines for the new content.
+- apply_patch: paths are workspace-relative or workspace-absolute; `..`, `.git`, and symlink targets reject. Whole-file replacement is one `*** Update File:` identity hunk spanning every served line with `+` lines for the new content.

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 `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.
+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 {{HASH_LEN}}-char alphanumeric hash. That hash is the `apply_patch` identity anchor, so copy only the {{HASH_LEN}} 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: "<anchor>", 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/src/hashline/alphabet.ts

@@ -1,4 +1,45 @@
-export 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. The build bakes it via esbuild `define`
+ * (`__ANCHOR_WIDTH__`), so a shipped bundle carries a literal and never reads the environment; the
+ * anchor generation (`hash-identity.ts`) folds the width in, so a width switch is a hard generation
+ * miss (re-read), never a cross-width hit.
+ */
+export const ANCHOR_WIDTH_ENV_VAR = "PI_BETTER_EDIT_ANCHOR_WIDTH";
+
+/** Supported widths; anything else is rejected at load so a typo cannot silently pick a stale width. */
+const SUPPORTED_WIDTH_TOKENS = ["3", "4"] as const;
+
+/** Default width when the env var is unset/empty — the historical default. */
+const DEFAULT_WIDTH = 4;
+
+/**
+ * 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 function resolveAnchorWidth(env: Record<string, string | undefined>): number {
+  const raw = env[ANCHOR_WIDTH_ENV_VAR];
+  if (raw === undefined || raw.trim() === "") return DEFAULT_WIDTH;
+  const value = raw.trim();
+  if (value === "3") return 3;
+  if (value === "4") return 4;
+  throw new Error(
+    `${ANCHOR_WIDTH_ENV_VAR} must be ${SUPPORTED_WIDTH_TOKENS.join(" or ")} (got ${JSON.stringify(raw)}).`,
+  );
+}
+
+/**
+ * Build-time bake hook. The dsh build passes esbuild `define: __ANCHOR_WIDTH__ = <width>` so the
+ * shipped bundle carries a literal width and NEVER consults the environment at runtime. Without a
+ * define (vitest / an unbundled dev import) the `typeof` guard falls back to the resolver above.
+ */
+declare const __ANCHOR_WIDTH__: number | undefined;
+
+export const HASH_LEN =
+  typeof __ANCHOR_WIDTH__ === "number" ? __ANCHOR_WIDTH__ : resolveAnchorWidth(process.env);
 
 export const ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
 

package/src/hashline/hash-identity.ts

@@ -124,7 +124,21 @@ export const CANON_VERSION = 3;
  * 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 const ANCHOR_GENERATION = 1;
+/**
+ * The file-scoped anchor-derivation generation. It covers the width (`HASH_LEN`, `ALPHA`,
+ * `HASH_SPACE`/`USABLE_HASH_SPACE`), the (path, content) seeding, the all-digit reservation and the
+ * probe stride. Bump it whenever any of those change.
+ *
+ * WHY it is a function of the width: the width is a build-time switch (ADR-0020: 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; width 3 gets generation 2, and any future width gets `100 + width`.
+ */
+export function anchorGenerationFor(width: number): number {
+  return width === 4 ? 1 : width === 3 ? 2 : 100 + width;
+}
+
+export const ANCHOR_GENERATION = anchorGenerationFor(HASH_LEN);
 
 /**
  * WHY: an explicit code-point list, never a Unicode property escape — \p{White_Space} and \p{Cf}

package/src/prompts.ts

@@ -1,23 +1,29 @@
 import { readFileSync } from "node:fs";
+import { HASH_LEN } from "./hashline/alphabet.js";
 
-export function loadP(relativePath: string, replacements?: Record<string, string>): string {
-  let content = readFileSync(new URL(relativePath, import.meta.url), "utf-8").trim();
+/**
+ * Resolve template variables in shipped prompt prose. Beyond caller-supplied replacements, the
+ * anchor-width token is ALWAYS resolved from the live `HASH_LEN`: the width is a build-time setting
+ * (ADR-0020), so any prompt that quotes it must not hardcode a digit.
+ */
+function applyReplacements(content: string, replacements?: Record<string, string>): string {
+  let out = content;
   if (replacements) {
     for (const [key, value] of Object.entries(replacements)) {
-      content = content.split(`{{${key}}}`).join(value);
+      out = out.split(`{{${key}}}`).join(value);
     }
   }
-  return content;
+  return out.split("{{HASH_LEN}}").join(String(HASH_LEN));
+}
+
+export function loadP(relativePath: string, replacements?: Record<string, string>): string {
+  const content = readFileSync(new URL(relativePath, import.meta.url), "utf-8").trim();
+  return applyReplacements(content, replacements);
 }
 
 export function loadGuide(relativePath: string, replacements?: Record<string, string>): string[] {
-  let content = readFileSync(new URL(relativePath, import.meta.url), "utf-8");
-  if (replacements) {
-    for (const [key, value] of Object.entries(replacements)) {
-      content = content.split(`{{${key}}}`).join(value);
-    }
-  }
-  return content
+  const content = readFileSync(new URL(relativePath, import.meta.url), "utf-8");
+  return applyReplacements(content, replacements)
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => line.startsWith("- "))