dsh-hashline-edit 0.2.0 → 0.2.2

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. 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 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/pi builds pass esbuild `define: __ANCHOR_WIDTH__ = <width>` so the
+ * shipped bundle carries a literal width and NEVER consults the environment at runtime. When there
+ * is no define (vitest / an unbundled dev import), the `typeof` guard falls back to the resolver
+ * below, keeping the zero-import leaf usable in tests without a build step.
+ */
+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

@@ -112,19 +112,28 @@ export const HASH_PROBE_STRIDE = ALPHA.length ** 2 + ALPHA.length + 1;
 export 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 const ANCHOR_GENERATION = 1;
+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}