dsh-better-edit 0.8.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/CHANGELOG.md +162 -97
  2. package/README.md +2 -2
  3. package/README.zh.md +3 -3
  4. package/cordis.patch.yml +1 -1
  5. package/lib/constants.js +19 -4
  6. package/lib/contract.js +136 -79
  7. package/lib/domain-errors.js +570 -0
  8. package/lib/edit-diff.js +33 -7
  9. package/lib/file-encoding-state.js +27 -7
  10. package/lib/file-view.js +305 -82
  11. package/lib/fs-bridge.js +23 -7
  12. package/lib/hash-store.js +404 -278
  13. package/lib/hashline/anchor-pipeline.js +586 -378
  14. package/lib/hashline/hash-assign.js +21 -22
  15. package/lib/hashline/hash.js +6 -6
  16. package/lib/hashline/index.js +1 -1
  17. package/lib/hashline/resolve.js +1 -1
  18. package/lib/hashline/served-guard.js +181 -0
  19. package/lib/index.js +2 -2
  20. package/lib/mutation/engine.js +392 -96
  21. package/lib/mutation.js +22 -130
  22. package/lib/noop-guard.js +20 -9
  23. package/lib/prompts.js +20 -18
  24. package/lib/read-and-serve.js +44 -20
  25. package/lib/sandbox.js +1 -1
  26. package/lib/session-view.js +57 -43
  27. package/lib/snapshot-store/index.js +97 -0
  28. package/lib/snapshot-store/lineage-store.js +400 -0
  29. package/lib/snapshot-store/migrate.js +80 -0
  30. package/lib/snapshot-store/pairing.js +412 -0
  31. package/lib/snapshot-store/txn.js +63 -0
  32. package/lib/snapshot-store/vacuum.js +243 -0
  33. package/lib/store-lifecycle.js +13 -1
  34. package/lib/store-retry.js +34 -0
  35. package/lib/tool-edit.js +90 -44
  36. package/lib/tool-read.js +29 -1
  37. package/lib/tool-str-replace-editor.js +59 -24
  38. package/lib/tool-undo.js +25 -8
  39. package/lib/types/constants.d.ts +5 -2
  40. package/lib/types/contract.d.ts +76 -71
  41. package/lib/types/domain-errors.d.ts +410 -0
  42. package/lib/types/edit-response.d.ts +1 -1
  43. package/lib/types/file-encoding-state.d.ts +1 -0
  44. package/lib/types/file-view.d.ts +35 -6
  45. package/lib/types/hash-store.d.ts +38 -19
  46. package/lib/types/hashline/anchor-pipeline.d.ts +117 -36
  47. package/lib/types/hashline/hash-assign.d.ts +5 -5
  48. package/lib/types/hashline/hash.d.ts +1 -1
  49. package/lib/types/hashline/index.d.ts +2 -2
  50. package/lib/types/hashline/served-guard.d.ts +100 -0
  51. package/lib/types/index.d.ts +2 -2
  52. package/lib/types/mutation/engine.d.ts +49 -30
  53. package/lib/types/mutation.d.ts +1 -39
  54. package/lib/types/noop-guard.d.ts +4 -4
  55. package/lib/types/prompts.d.ts +1 -1
  56. package/lib/types/read-and-serve.d.ts +6 -0
  57. package/lib/types/sandbox.d.ts +1 -1
  58. package/lib/types/session-view.d.ts +38 -9
  59. package/lib/types/snapshot-store/index.d.ts +28 -0
  60. package/lib/types/snapshot-store/lineage-store.d.ts +96 -0
  61. package/lib/types/snapshot-store/migrate.d.ts +16 -0
  62. package/lib/types/snapshot-store/pairing.d.ts +99 -0
  63. package/lib/types/snapshot-store/txn.d.ts +12 -0
  64. package/lib/types/snapshot-store/vacuum.d.ts +79 -0
  65. package/lib/types/store-lifecycle.d.ts +0 -1
  66. package/lib/types/store-retry.d.ts +6 -0
  67. package/lib/types/tool-edit.d.ts +2 -2
  68. package/lib/types/tool-str-replace-editor.d.ts +10 -4
  69. package/lib/types/utils.d.ts +5 -6
  70. package/lib/types/workspace-context.d.ts +0 -1
  71. package/lib/undo-edit.js +27 -11
  72. package/lib/utils.js +12 -12
  73. package/lib/workspace-context.js +4 -8
  74. package/lib/write-hook.js +13 -4
  75. package/package.json +9 -10
@@ -16,18 +16,23 @@
16
16
  *
17
17
  * @module dsh-better-edit/hashline/anchor-pipeline
18
18
  */
19
- import { abortIf, splitLines, rejectUnknownFields, clipLine, CodedError } from "../utils.js";
20
- import { HASH_CLASS, HL_BARE_PREFIX_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE, HASH_SEP, ANCHOR_LEN, ALPH_RE, canon, lineHashesPure, getCanonForHash, rememberHashCanon, } from "./hash-assign.js";
21
- import { recordServed, servedPositionsOf } from "../session-view.js";
19
+ import { abortIf, splitLines, rejectUnknownFields, clipLine } from "../utils.js";
20
+ import { HASH_CLASS, HL_BARE_PREFIX_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE, HASH_SEP, ANCHOR_LEN, ALPH_RE, canon, lineHashesPure, } from "./hash-assign.js";
21
+ import { servedPositionsOf } from "../session-view.js";
22
22
  import { SERVED_ECHO_CAP } from "../constants.js";
23
- import { NEW_CONTENT_NOT_STRING_MSG } from "../constants.js";
23
+ import { NEW_CONTENT_NOT_STRING_MSG, NEW_CONTENT_BODY } from "../constants.js";
24
+ import { DomainError, formatWarning, numericAnchorNote } from "../domain-errors.js";
25
+ import { buildServedEditPrefixNote, findNeverServedAnchorShapes, findServedPrefixMismatches, } from "./served-guard.js";
24
26
  function diagRef(ref) {
25
27
  const trimmed = ref.trim();
26
28
  if (!trimmed.length) {
27
- return `[MODEL] [E_BAD_ANCHOR] Invalid anchor. Expected a 3-char alphanumeric anchor (e.g. "aB3").`;
29
+ return { rawAnchor: trimmed, reason: 'Expected a 3-char alphanumeric anchor (e.g. "aB3").' };
28
30
  }
29
31
  if (/^\d+/.test(trimmed)) {
30
- return `[MODEL] [E_BAD_ANCHOR] Invalid anchor. Use the hash alone (e.g. "aB3") — no line numbers or trailing content.`;
32
+ return {
33
+ rawAnchor: trimmed,
34
+ reason: 'Use the hash alone (e.g. "aB3") — no line numbers or trailing content.',
35
+ };
31
36
  }
32
37
  if (trimmed.includes("│") && trimmed.includes("\n")) {
33
38
  const lines = trimmed.split("\n");
@@ -39,19 +44,29 @@ function diagRef(ref) {
39
44
  const firstHash = firstMatch?.[0] ?? "wUp";
40
45
  const lastHash = lastMatch?.[0] ?? "AU6";
41
46
  const preview = first.slice(0, 60);
42
- return `[MODEL] [E_BAD_ANCHOR] Invalid anchor — remove_from must be a single bare 3-char hash (e.g. "wUp"), not a block with HASH│. Received ${lines.length} lines starting "${preview}…" — use only the first hash "${firstHash}" as remove_from and "${lastHash}" as remove_to, and put the new content (without HASH│) in replacement_text.`;
47
+ return {
48
+ rawAnchor: trimmed,
49
+ reason: `anchor_from must be a single bare 3-char hash (e.g. "wUp"), not a block with HASH│. Received ${lines.length} lines starting "${preview}…" — use only the first hash "${firstHash}" as anchor_from and "${lastHash}" as anchor_to, and put the new content (without HASH│) in replace_with.`,
50
+ };
43
51
  }
44
52
  if (trimmed.includes("│")) {
45
- return `[MODEL] [E_BAD_ANCHOR] Invalid anchor "${trimmed}". remove_from and remove_to must contain the 3-char hash only — remove everything from "│" onward.`;
53
+ return {
54
+ rawAnchor: trimmed,
55
+ reason: 'anchor_from and anchor_to must contain the 3-char hash only — remove everything from "│" onward.',
56
+ };
46
57
  }
47
- return `[MODEL] [E_BAD_ANCHOR] Invalid anchor "${trimmed}". Expected a 3-char alphanumeric anchor (e.g. "aB3").`;
58
+ return {
59
+ rawAnchor: trimmed,
60
+ reason: 'Expected a 3-char alphanumeric anchor (e.g. "aB3").',
61
+ };
48
62
  }
49
63
  function parseRef(ref) {
50
64
  const trimmed = ref.trim();
51
65
  if (trimmed.length === ANCHOR_LEN && ALPH_RE.test(trimmed)) {
52
66
  return { hash: trimmed };
53
67
  }
54
- throw new CodedError("E_BAD_ANCHOR", diagRef(ref));
68
+ const diag = diagRef(ref);
69
+ throw new DomainError("E_MALFORMED_ANCHOR", { rawAnchor: diag.rawAnchor, reason: diag.reason });
55
70
  }
56
71
  export const parseHashRef = parseRef;
57
72
  export function parseText(edit) {
@@ -85,8 +100,8 @@ function assertAligned(fileLines, fileHashes, ctx) {
85
100
  }
86
101
  }
87
102
  function fmtMismatchWithServes(mismatches, fileLines, fileHashes, filePath) {
88
- assertAligned(fileLines, fileHashes, "fmtMismatch");
89
- const out = [];
103
+ const headlines = [];
104
+ const blocks = [];
90
105
  const servedRows = [];
91
106
  const seen = new Set();
92
107
  const pushRow = (ln) => {
@@ -102,7 +117,11 @@ function fmtMismatchWithServes(mismatches, fileLines, fileHashes, filePath) {
102
117
  const ambiguous = mismatches.filter((m) => m.kind === "ambiguous");
103
118
  const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
104
119
  if (notFound.length > 0) {
105
- out.push(`[MODEL] [E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. Re-read for fresh anchors.`);
120
+ headlines.push(
121
+ // B: a well-formed all-digit anchor that does not resolve lands here;
122
+ // the numeric note steers away from line numbers (T4 deleted the
123
+ // E_UNKNOWN_ANCHOR declaration — this headline is now the note's only home).
124
+ `${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. Re-read for fresh anchors.${numericAnchorNote(notFound.map((m) => m.ref.hash))}`);
106
125
  for (const m of notFound) {
107
126
  const ctx = m.context;
108
127
  if (!ctx)
@@ -114,14 +133,11 @@ function fmtMismatchWithServes(mismatches, fileLines, fileHashes, filePath) {
114
133
  rows.push(` ${ln}: ${fileHashes[ln - 1]}│${clipLine(fileLines[ln - 1] ?? "")}`);
115
134
  pushRow(ln);
116
135
  }
117
- out.push("");
118
- out.push(` Current context around resolved anchor "${ctx.hash}" (line ${ctx.line}):\n${rows.join("\n")}`);
136
+ blocks.push(` Current context around resolved anchor "${ctx.hash}" (line ${ctx.line}):\n${rows.join("\n")}`);
119
137
  }
120
138
  }
121
139
  if (ambiguous.length > 0) {
122
- if (out.length > 0)
123
- out.push("");
124
- out.push(`[MODEL] [E_STALE_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Re-read for fresh anchors.`);
140
+ headlines.push(`${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Re-read for fresh anchors.`);
125
141
  for (const m of ambiguous) {
126
142
  const sample = (m.candidates ?? []).slice(0, 5);
127
143
  const more = (m.candidates?.length ?? 0) > sample.length
@@ -134,28 +150,36 @@ function fmtMismatchWithServes(mismatches, fileLines, fileHashes, filePath) {
134
150
  return ` ${line}: ${fileHashes[line - 1]}│${content}`;
135
151
  })
136
152
  .join("\n");
137
- out.push(` Hash "${m.ref.hash}" matches lines ${sample.join(", ")}${more}.\n${lines}`);
153
+ blocks.push(` Hash "${m.ref.hash}" matches lines ${sample.join(", ")}${more}.\n${lines}`);
138
154
  }
139
155
  }
140
- return { message: out.join("\n"), servedRows };
156
+ return { headline: headlines.join("\n\n"), servedBlock: blocks.join("\n\n"), servedRows };
141
157
  }
142
- const ITEM_KS = new Set(["replacement_text", "remove_from", "remove_to"]);
158
+ const ITEM_KS = new Set(["replace_with", "anchor_from", "anchor_to"]);
143
159
  function assertItem(edit) {
144
- rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { replacement_text, remove_from, remove_to }.");
145
- if ("remove_from" in edit && typeof edit.remove_from !== "string") {
146
- throw new CodedError("E_BAD_PAYLOAD", `[MODEL] [E_BAD_PAYLOAD] Field "remove_from" must be an anchor string (3-char hash).`);
160
+ rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { replace_with, anchor_from, anchor_to }.");
161
+ if ("anchor_from" in edit && typeof edit.anchor_from !== "string") {
162
+ throw new DomainError("E_BAD_PAYLOAD", {
163
+ message: `Field "anchor_from" must be an anchor string (3-char hash).`,
164
+ });
147
165
  }
148
- if ("remove_to" in edit && typeof edit.remove_to !== "string") {
149
- throw new CodedError("E_BAD_PAYLOAD", `[MODEL] [E_BAD_PAYLOAD] Field "remove_to" must be an anchor string (3-char hash).`);
166
+ if ("anchor_to" in edit && typeof edit.anchor_to !== "string") {
167
+ throw new DomainError("E_BAD_PAYLOAD", {
168
+ message: `Field "anchor_to" must be an anchor string (3-char hash).`,
169
+ });
150
170
  }
151
- if (!("replacement_text" in edit)) {
152
- throw new CodedError("E_BAD_PAYLOAD", `[MODEL] [E_BAD_PAYLOAD] The edit requires a "replacement_text" field. Provide the replacement text (use "" to delete).`);
171
+ if (!("replace_with" in edit)) {
172
+ throw new DomainError("E_BAD_PAYLOAD", {
173
+ message: `The edit requires a "replace_with" field. Provide the replacement text (use "" to delete).`,
174
+ });
153
175
  }
154
- if (typeof edit.replacement_text !== "string") {
155
- throw new CodedError("E_BAD_PAYLOAD", NEW_CONTENT_NOT_STRING_MSG);
176
+ if (typeof edit.replace_with !== "string") {
177
+ throw new DomainError("E_BAD_PAYLOAD", { message: NEW_CONTENT_BODY });
156
178
  }
157
- if (typeof edit.remove_from !== "string" || typeof edit.remove_to !== "string") {
158
- throw new CodedError("E_BAD_PAYLOAD", `[MODEL] [E_BAD_PAYLOAD] The edit requires "remove_from" and "remove_to" anchor strings (3-char hashes from read output).`);
179
+ if (typeof edit.anchor_from !== "string" || typeof edit.anchor_to !== "string") {
180
+ throw new DomainError("E_BAD_PAYLOAD", {
181
+ message: `The edit requires "anchor_from" and "anchor_to" anchor strings (3-char hashes from read output).`,
182
+ });
159
183
  }
160
184
  }
161
185
  const ANCHOR_ROW_RE = new RegExp(`^([+-]?)(${HASH_CLASS})│`);
@@ -172,29 +196,33 @@ function firstHashFromBlock(block) {
172
196
  }
173
197
  export function resEdit(edit, _warnings) {
174
198
  assertItem(edit);
175
- const editLines = parseText(edit.replacement_text);
176
- const bounds = [edit.remove_from, edit.remove_to].map((ref) => {
199
+ const editLines = parseText(edit.replace_with);
200
+ const bounds = [edit.anchor_from, edit.anchor_to].map((ref) => {
177
201
  const trimmed = ref.trim();
178
202
  if (trimmed.includes("\n")) {
179
203
  const hash = firstHashFromBlock(trimmed);
180
204
  if (hash) {
181
205
  const lines = trimmed.split("\n").length;
182
- throw new CodedError("E_BAD_ANCHOR", `[MODEL] [E_BAD_ANCHOR] extracted first hash "${hash}" from ${lines}-line block — use bare "${hash}" next time`);
206
+ throw new DomainError("E_MALFORMED_ANCHOR", {
207
+ rawAnchor: trimmed,
208
+ reason: `extracted first hash "${hash}" from ${lines}-line block — use bare "${hash}" next time`,
209
+ });
183
210
  }
184
211
  }
185
212
  const match = trimmed.match(ANCHOR_ROW_RE);
186
213
  if (match) {
187
- let message;
214
+ let reason;
188
215
  if (match[1] === "+") {
189
- message = `[E_BAD_ANCHOR] stripped diff-preview marker from remove_from/remove_to "${trimmed}".`;
216
+ reason = `stripped diff-preview marker from anchor_from/anchor_to — pass the bare anchor.`;
190
217
  }
191
218
  else if (match[1] === "-") {
192
- message = `[E_BAD_ANCHOR] stripped leading "-" marker from remove_from/remove_to "${trimmed}".`;
219
+ reason = `stripped leading "-" marker from anchor_from/anchor_to — pass the bare anchor.`;
193
220
  }
194
221
  else {
195
- message = `[E_BAD_ANCHOR] stripped "HASH│" prefix from remove_from/remove_to "${trimmed}".`;
222
+ reason = `stripped "HASH│" prefix from anchor_from/anchor_to — pass the bare anchor.`;
196
223
  }
197
- throw new CodedError("E_BAD_ANCHOR", `[MODEL] ${message}`);
224
+ // Channel rule: the model must retry with the bare anchor → MODEL audience via the registry.
225
+ throw new DomainError("E_MALFORMED_ANCHOR", { rawAnchor: trimmed, reason });
198
226
  }
199
227
  return ref;
200
228
  });
@@ -204,8 +232,9 @@ export function resEdit(edit, _warnings) {
204
232
  };
205
233
  }
206
234
  function warnUnicodeEsc(edit, warnings) {
207
- if (edit.content_lines.some((line) => /\\uDDDD/i.test(line))) {
208
- warnings.push("Detected literal \\uDDDD in edit content; no autocorrection applied. Verify whether this should be a real Unicode escape or plain text.");
235
+ const index = edit.content_lines.findIndex((line) => /\\uDDDD/i.test(line));
236
+ if (index !== -1) {
237
+ warnings.push(formatWarning("W_UNICODE_LITERAL", { line: index + 1 }));
209
238
  }
210
239
  }
211
240
  /** @internal — private to anchor-pipeline seam; do not import directly, use anchor-pipeline.ts */
@@ -221,15 +250,22 @@ function stripBarePrefixes(edit, fileHashes, _warnings) {
221
250
  });
222
251
  if (stripped.length === 0)
223
252
  return edit;
224
- const locations = stripped.map((s) => `replacement_text line ${s.lineIndex + 1}`).join(", ");
225
253
  const matchedCount = stripped.filter((s) => s.matched).length;
226
- const evidence = matchedCount === 0
227
- ? "0 matched — verify literal 'HASH│' content"
228
- : `${matchedCount}/${stripped.length} matched`;
254
+ // #63 supersedes #24's 0-matched arm: no stripped prefix is a file anchor, so the
255
+ // lines are literal content — pass the edit through UNCHANGED (prefixes intact).
256
+ // Arms with matched >= 1 keep throwing; the call-site echo routing still governs.
257
+ // FU-5: the applied-bytes warn tiers (served-guard.ts) name this write-through.
258
+ if (matchedCount === 0)
259
+ return edit;
260
+ const locations = stripped.map((s) => `replace_with line ${s.lineIndex + 1}`).join(", ");
261
+ const evidence = `${matchedCount}/${stripped.length} matched`;
229
262
  if (matchedCount === stripped.length) {
230
- throw new BadAnchorError(`[MODEL] [E_BAD_ANCHOR] stripped "HASH│" prefix from ${locations} (${evidence}) — use bare content without HASH│ next time.`, { ...edit, content_lines: contentLines });
263
+ throw new BadAnchorError(locations, `stripped "HASH│" prefix from ${locations} (${evidence}) — use bare content without HASH│ next time.`, { ...edit, content_lines: contentLines });
231
264
  }
232
- throw new BadAnchorError(`[MODEL] [E_BAD_ANCHOR] stripped "HASH│" prefix from ${locations} (${evidence}).`, { ...edit, content_lines: contentLines });
265
+ throw new BadAnchorError(locations, `stripped "HASH│" prefix from ${locations} (${evidence}).`, {
266
+ ...edit,
267
+ content_lines: contentLines,
268
+ });
233
269
  }
234
270
  /** @internal — private to anchor-pipeline seam */
235
271
  function stripDiffPrefixes(edit, _warnings) {
@@ -249,8 +285,11 @@ function stripDiffPrefixes(edit, _warnings) {
249
285
  });
250
286
  if (stripped.length === 0)
251
287
  return edit;
252
- const locations = stripped.map((i) => `replacement_text line ${i + 1}`).join(", ");
253
- throw new BadAnchorError(`[MODEL] [E_BAD_ANCHOR] stripped diff-preview marker from ${locations}.`, { ...edit, content_lines: contentLines });
288
+ const locations = stripped.map((i) => `replace_with line ${i + 1}`).join(", ");
289
+ throw new BadAnchorError(locations, `stripped diff-preview marker from ${locations}.`, {
290
+ ...edit,
291
+ content_lines: contentLines,
292
+ });
254
293
  }
255
294
  /** @internal — private to anchor-pipeline seam */
256
295
  function swapReversedRanges(edit, fileHashes, warnings) {
@@ -264,7 +303,7 @@ function swapReversedRanges(edit, fileHashes, warnings) {
264
303
  if (startLine === undefined || endLine === undefined || startLine <= endLine) {
265
304
  return edit;
266
305
  }
267
- warnings.push(`[USER] [E_REVERSED_ANCHORS] reversed remove_from/remove_to (${startRef.hash} after ${endRef.hash}); swapped (healed).`);
306
+ warnings.push(formatWarning("W_REVERSED_ANCHORS", { fromHash: startRef.hash, toHash: endRef.hash }));
268
307
  return { ...edit, hash_bounds: [endRef, startRef] };
269
308
  }
270
309
  /** @internal — private to anchor-pipeline seam */
@@ -302,9 +341,10 @@ function valEdit(edit, fileLines, fileHashes, warnings, signal) {
302
341
  }
303
342
  return { resolved: undefined, mismatches };
304
343
  }
305
- if (startResolved.line > endResolved.line) {
306
- throw new CodedError("E_REVERSED_ANCHORS", `[MODEL] [E_REVERSED_ANCHORS] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.hash_bounds[0].hash} and ${edit.hash_bounds[1].hash}).`);
307
- }
344
+ // Reversal always heals upstream in swapReversedRanges (which runs before
345
+ // valEdit in applyEdit): when both anchors resolve, startLine <= endLine is
346
+ // guaranteed, so no refusal arm exists here. Anchors carry no order — only
347
+ // the resolved lines of the anchor_from/anchor_to slot pair matter.
308
348
  const endLine = endResolved.line;
309
349
  return {
310
350
  resolved: {
@@ -314,42 +354,53 @@ function valEdit(edit, fileLines, fileHashes, warnings, signal) {
314
354
  mismatches,
315
355
  };
316
356
  }
317
- export function findNewEdge() {
318
- return undefined;
319
- }
320
- export { warnUnicodeEsc };
321
- export class ServedRejectionError extends CodedError {
357
+ export class ServedRejectionError extends DomainError {
322
358
  code;
323
359
  unservedKind;
324
- firstOffendingLine;
325
- servedRows;
326
360
  constructor(opts) {
327
- super(opts.code, opts.message);
361
+ if (opts.code === "E_STALE_RANGE") {
362
+ super("E_STALE_RANGE", {
363
+ headline: opts.headline,
364
+ servedRows: opts.servedRows,
365
+ servedBlock: opts.servedBlock,
366
+ ...(opts.cause !== undefined ? { cause: opts.cause } : {}),
367
+ ...(opts.firstOffendingLine !== undefined
368
+ ? { firstOffendingLine: opts.firstOffendingLine }
369
+ : {}),
370
+ });
371
+ }
372
+ else {
373
+ super("E_UNSERVED_RANGE", {
374
+ headline: opts.headline,
375
+ servedRows: opts.servedRows,
376
+ servedBlock: opts.servedBlock,
377
+ unservedKind: opts.unservedKind,
378
+ ...(opts.firstOffendingLine !== undefined
379
+ ? { firstOffendingLine: opts.firstOffendingLine }
380
+ : {}),
381
+ });
382
+ }
328
383
  this.name = "ServedRejectionError";
329
384
  this.code = opts.code;
330
- this.unservedKind = opts.unservedKind;
331
- this.firstOffendingLine = opts.firstOffendingLine;
332
- this.servedRows = opts.servedRows;
385
+ this.unservedKind = opts.code === "E_UNSERVED_RANGE" ? opts.unservedKind : undefined;
333
386
  }
334
387
  }
335
- export function isServedRejection(error) {
336
- return error instanceof ServedRejectionError;
337
- }
338
- export class AnchorMismatchError extends CodedError {
339
- servedRows;
340
- constructor(message, servedRows) {
341
- super("E_STALE_ANCHOR", message);
388
+ // F8: narrowed to the codes the reject-and-serve branches actually handle —
389
+ // the class's meaning is type-enforced instead of carried by convention.
390
+ export class AnchorMismatchError extends DomainError {
391
+ constructor(code, payload) {
392
+ super(code, payload);
342
393
  this.name = "AnchorMismatchError";
343
- this.servedRows = servedRows;
344
394
  }
345
395
  }
346
- /** Thrown when replacement_text carries anchor-syntax garbage (HASH│/diff-preview prefixes).
347
- * Carries the stripped edit so applyEdit can distinguish served-echo (→ E_SERVED_ECHO
348
- * denial downstream) from garbage (→ E_BAD_ANCHOR stands). */
349
- export class BadAnchorError extends CodedError {
396
+ /** Thrown when replace_with carries anchor-syntax garbage (HASH│/diff-preview prefixes).
397
+ * Carries the stripped edit so applyEdit can distinguish served-echo (→ E_SUSPICIOUS_TEXT
398
+ * denial downstream) from garbage (→ E_MALFORMED_ANCHOR stands). @internal — instances
399
+ * cross the seam as DomainError<"E_MALFORMED_ANCHOR">; the symbol has no importer. */
400
+ class BadAnchorError extends DomainError {
350
401
  stripped;
351
- constructor(message, stripped) {
352
- super("E_BAD_ANCHOR", message);
402
+ constructor(rawAnchor, reason, stripped) {
403
+ super("E_MALFORMED_ANCHOR", { rawAnchor, reason });
353
404
  this.name = "BadAnchorError";
354
405
  this.stripped = stripped;
355
406
  }
@@ -368,9 +419,16 @@ export function findEditHashEcho(replacementLines, served, startLine) {
368
419
  }
369
420
  return undefined;
370
421
  }
422
+ /**
423
+ * Served-echo refusal: the replacement reproduces a row actually served for
424
+ * this session, path, and line. A DomainError<"E_SUSPICIOUS_TEXT"> whose
425
+ * code, message header and audience agree — while staying instanceof
426
+ * AnchorMismatchError so the existing reject-and-serve branches (which catch
427
+ * AnchorMismatchError / ServedRejectionError) keep recognising it.
428
+ */
371
429
  export class EditHashEchoError extends AnchorMismatchError {
372
- constructor(message, servedRows = []) {
373
- super(message, servedRows);
430
+ constructor(payload) {
431
+ super("E_SUSPICIOUS_TEXT", payload);
374
432
  this.name = "EditHashEchoError";
375
433
  }
376
434
  }
@@ -386,34 +444,254 @@ export function buildRangeEcho(startLine, endLine, fileHashes) {
386
444
  export function fmtServedRows(rows, fileLines) {
387
445
  return rows.map((row) => `${row.hash}${HASH_SEP}${fileLines[row.position] ?? ""}`).join("\n");
388
446
  }
389
- function retryHint() {
390
- return "Retry with these anchors (no read needed).";
391
- }
392
447
  function paginationHint(nextOffset, more) {
393
448
  return `[... ${more} more — read offset=${nextOffset}]`;
394
449
  }
450
+ function servedEvidenceRoute(leaseSource) {
451
+ return leaseSource === undefined ? { kind: "mirror" } : { kind: "leased", source: leaseSource };
452
+ }
453
+ /**
454
+ * Question 1: does this route owe the never-served interior scan (upstream ADR-0024 decision 2)?
455
+ * On the mirror route the mirror is the only evidence, so an interior hole rejects there.
456
+ * The leased route does not scan: the identity gate owns verification — its two boundary
457
+ * leases pin the span's extent, so an interior `null` carries no identity to verify and
458
+ * `acceptsInteriorHole` admits it (decision 1, adopted; supersedes ADR-0019's decline).
459
+ * Rejecting the hole on the scan would shadow the gate and keep taxing correct edits upstream
460
+ * measured at 8/242 calls.
461
+ */
462
+ function owesInteriorScan(route) {
463
+ return route.kind === "mirror";
464
+ }
465
+ /**
466
+ * Question 2: is slot `k` of a `servedLen`-row gate window an interior hole the leased
467
+ * identity gate accepts? Upstream ADR-0024 decision 1 (adopted; supersedes ADR-0019's
468
+ * decline) narrows informed destruction to the boundaries: an unread interior row has no
469
+ * identity to check, and the two verified boundary leases already fix the span's extent, so
470
+ * refusing it only taxed a correct edit. A `null` boundary is the named anchor itself —
471
+ * unverifiable by construction — so it keeps the fail-closed diagnosis. The mirror route
472
+ * answers uniformly: `owesInteriorScan` has already rejected its holes before the gate can
473
+ * be reached.
474
+ */
475
+ function acceptsInteriorHole(route, k, servedLen) {
476
+ return route.kind === "leased" && k !== 0 && k !== servedLen - 1;
477
+ }
478
+ /**
479
+ * Question 3: does this slot take part in the position comparison? On the leased route a
480
+ * `null` slot carries no evidence to compare and the identity gate has already adjudicated
481
+ * the window (accepting an interior hole per upstream ADR-0024 decision 1); failing the
482
+ * position check on it here would re-shadow the gate. The non-leased route rejects its holes
483
+ * in the interior scan above (decision 2 keeps its interior diagnosis) and compares every
484
+ * slot as before.
485
+ */
486
+ function checksPosition(route, slot) {
487
+ return route.kind !== "leased" || slot !== null;
488
+ }
489
+ /**
490
+ * Refuses anchors the lease seam cannot place: the session holds no lease for them in this file.
491
+ * Deterministic precedence, one condition per code — a lease held for ANOTHER file
492
+ * (`E_FOREIGN_ANCHOR`) wins over holding no lease anywhere (`E_UNKNOWN_ANCHOR`). Neither
493
+ * rejection serves rows: with no lease for this file no range can be identified, so there is
494
+ * nothing trustworthy to retry with (port of upstream b92e0ec:src/hashline/lease-resolve.ts:87-118).
495
+ */
496
+ function throwUnknownOrForeign(args) {
497
+ const path = args.filePath ?? "this file";
498
+ const refused = [...new Set(args.refused)];
499
+ const homes = [...new Set(refused.flatMap((anchor) => args.source.anchorHomes(anchor)))].sort();
500
+ if (homes.length > 0) {
501
+ throw new DomainError("E_FOREIGN_ANCHOR", { path, anchors: refused, homes });
502
+ }
503
+ throw new DomainError("E_UNKNOWN_ANCHOR", { path, anchors: refused });
504
+ }
505
+ /**
506
+ * Per-lease line-identity decision (port of upstream b92e0ec:src/hashline/resolve.ts:95-110):
507
+ * a retired lease, or a live lease whose `line_id` has no coordinate in the buffer being
508
+ * edited, is `stale`; otherwise the decision names the rebased line.
509
+ */
510
+ function lineIdentityDecision(lease, source) {
511
+ if (lease.retiredAt !== null)
512
+ return { kind: "stale" };
513
+ const rebased = source.rebasedLineOf(lease.lineId);
514
+ if (rebased === undefined)
515
+ return { kind: "stale" };
516
+ return { kind: "line", line: rebased };
517
+ }
518
+ /**
519
+ * The leased-route boundary identity interception (port of upstream
520
+ * b92e0ec:src/hashline/lease-resolve.ts:120-200), running before the served-window gates:
521
+ * a boundary anchor with no lease is lost identity — unknown or foreign, never a content
522
+ * question. A stale boundary serves rows ONLY when exactly one bound is stale AND the survivor
523
+ * is live and unshifted (its rebased coordinate equals its served coordinate — evidence no
524
+ * shift occurred): that one case rejects with `E_UNVERIFIED_RANGE`, the named window echoed as
525
+ * a fresh read; every other stale case rejects with `E_TARGET_LOST`, carrying no rows.
526
+ * The named coordinates are lease-derived (`servedLineNumber`) only — content placement never
527
+ * names a window for a retired bound.
528
+ */
529
+ function interceptLeaseBoundaries(args) {
530
+ const { fileHashes, fileLines, leaseSource } = args;
531
+ const fromLease = leaseSource.leaseFor(args.startHash);
532
+ const toLease = leaseSource.leaseFor(args.endHash);
533
+ if (fromLease === undefined || toLease === undefined) {
534
+ throwUnknownOrForeign({
535
+ ...(args.filePath !== undefined ? { filePath: args.filePath } : {}),
536
+ refused: [
537
+ ...(fromLease === undefined ? [args.startHash] : []),
538
+ ...(toLease === undefined ? [args.endHash] : []),
539
+ ],
540
+ source: leaseSource,
541
+ });
542
+ }
543
+ const fromDecision = lineIdentityDecision(fromLease, leaseSource);
544
+ const toDecision = lineIdentityDecision(toLease, leaseSource);
545
+ if (fromDecision.kind === "stale" || toDecision.kind === "stale") {
546
+ const fromLiveUnshifted = fromDecision.kind === "line" && fromDecision.line === fromLease.servedLineNumber;
547
+ const toLiveUnshifted = toDecision.kind === "line" && toDecision.line === toLease.servedLineNumber;
548
+ const staleServedLine = fromDecision.kind === "stale" ? fromLease.servedLineNumber : toLease.servedLineNumber;
549
+ const exactlyOneStale = (fromDecision.kind === "stale") !== (toDecision.kind === "stale");
550
+ const survivorLiveUnshifted = fromDecision.kind === "stale" ? toLiveUnshifted : fromLiveUnshifted;
551
+ if (exactlyOneStale && survivorLiveUnshifted) {
552
+ const rawStart = Math.min(fromLease.servedLineNumber, toLease.servedLineNumber);
553
+ const rawEnd = Math.max(fromLease.servedLineNumber, toLease.servedLineNumber);
554
+ const len = fileHashes.length;
555
+ const startLine = Math.max(1, rawStart);
556
+ const endLine = Math.min(len, rawEnd);
557
+ // Collapsed-window guard: fail closed to `E_TARGET_LOST` when the named window
558
+ // collapses (e.g. served startLine 10 against a 4-line file) or misses the file.
559
+ if (len > 0 && startLine <= endLine && rawEnd >= 1 && rawStart <= len) {
560
+ const servedRows = buildRangeEcho(startLine, endLine, fileHashes);
561
+ const totalLen = endLine - startLine + 1;
562
+ const tail = servedRows.length < totalLen
563
+ ? `\n${paginationHint(startLine + servedRows.length, totalLen - servedRows.length)}`
564
+ : "";
565
+ throw new DomainError("E_UNVERIFIED_RANGE", {
566
+ servedRows,
567
+ servedBlock: fmtServedRows(servedRows, fileLines) + tail,
568
+ cause: "retirement",
569
+ firstOffendingLine: staleServedLine,
570
+ });
571
+ }
572
+ }
573
+ throw new DomainError("E_TARGET_LOST", {
574
+ servedLine: staleServedLine,
575
+ ...(args.filePath !== undefined ? { path: args.filePath } : {}),
576
+ cause: "retirement",
577
+ });
578
+ }
579
+ }
580
+ /**
581
+ * The identity gate for a served span (obligation (c)) — replaces the unconditional position check
582
+ * when a lease source is present.
583
+ *
584
+ * A **benign shift** — the intended line's bytes are unchanged and only its position moved (exterior
585
+ * drift above the served span) — passes: the served anchor's live lease resolves to the rebased
586
+ * coordinate the edit targets, so the edit applies there with no re-read. A **look-alike rebind** —
587
+ * the named line was deleted and a different line now holds the same bytes — rejects: the leased
588
+ * `line_id` no longer lives at the rebased coordinate, or is gone from the buffer's identity map
589
+ * entirely, so the anchor cannot be reconciled with the line it named.
590
+ *
591
+ * Fail-closed arms, all `E_STALE_RANGE` with the echo rows: a window length that changed because
592
+ * an external insert/delete landed strictly inside the span, a truncated mirror slot (no served row
593
+ * left to reconcile), a never-served boundary row (the named anchor itself, unverifiable without a
594
+ * served row), an unleased served row (a serve predating lease granting), a retired lease, or a
595
+ * coordinate no leased identity occupies. An interior mirror row the span never served (`null`) is
596
+ * accepted (upstream ADR-0024 decision 1, adopted; supersedes ADR-0019's decline): it carries no
597
+ * identity to verify and the two boundary leases plus the window-length check pin the span's extent.
598
+ * Throwing happens before any write, so a rejection leaves the file byte-identical.
599
+ */
600
+ export function verifyRebasedSpan(args) {
601
+ const { served, route, echo, echoRows, where } = args;
602
+ const leaseSource = route.source;
603
+ const servedLen = args.servedEnd - args.servedStart + 1;
604
+ const rebasedLen = args.rebasedEnd - args.rebasedStart + 1;
605
+ if (rebasedLen !== servedLen) {
606
+ throw new ServedRejectionError({
607
+ code: "E_STALE_RANGE",
608
+ headline: `served span (${servedLen} lines) no longer matches the rebased range (${rebasedLen} lines)${where}.`,
609
+ servedBlock: echo,
610
+ firstOffendingLine: args.rebasedStart,
611
+ servedRows: echoRows,
612
+ cause: "served-range staleness",
613
+ });
614
+ }
615
+ for (let k = 0; k < servedLen; k++) {
616
+ const servedAnchor = served[args.servedStart - 1 + k];
617
+ const currentLine = args.rebasedStart + k;
618
+ // WHY: the served window can come from the leases' own `servedLineNumber` because a truncated
619
+ // serve dropped the mirror rows it no longer covers: the lease outlives the mirror. An
620
+ // absent slot is that missing record, never "this line was never served", so the span
621
+ // fails closed on the truth (the served record cannot be reconciled) and the current
622
+ // range is served for a fresh read.
623
+ if (servedAnchor === undefined) {
624
+ throw new ServedRejectionError({
625
+ code: "E_STALE_RANGE",
626
+ headline: `line ${currentLine}${where} has no served mirror row left; the served window was truncated.`,
627
+ servedBlock: echo,
628
+ firstOffendingLine: currentLine,
629
+ servedRows: echoRows,
630
+ cause: "served-range staleness",
631
+ });
632
+ }
633
+ if (servedAnchor === null) {
634
+ // WHY: the interior-accept / boundary-reject split is the route's `acceptsInteriorHole`
635
+ // decision (upstream ADR-0024 decision 1, adopted; supersedes ADR-0019's decline) — see
636
+ // its doc for why an unread interior row passes and a `null` boundary keeps the
637
+ // fail-closed diagnosis.
638
+ if (!acceptsInteriorHole(route, k, servedLen)) {
639
+ throw new ServedRejectionError({
640
+ code: "E_STALE_RANGE",
641
+ headline: `line ${currentLine}${where} was never served.`,
642
+ servedBlock: echo,
643
+ firstOffendingLine: currentLine,
644
+ servedRows: echoRows,
645
+ cause: "never-served",
646
+ });
647
+ }
648
+ continue;
649
+ }
650
+ const lease = leaseSource.leaseFor(servedAnchor);
651
+ if (lease === undefined) {
652
+ throw new ServedRejectionError({
653
+ code: "E_STALE_RANGE",
654
+ headline: `line ${currentLine}${where} has no served line identity.`,
655
+ servedBlock: echo,
656
+ firstOffendingLine: currentLine,
657
+ servedRows: echoRows,
658
+ cause: "never-served",
659
+ });
660
+ }
661
+ // WHY: two distinct diagnoses, one per condition: a terminal lease is a `retirement` — the
662
+ // identity is gone and only a re-read revives it — while a live lease whose `lineId` no
663
+ // longer sits at its expected coordinate is drift between the served record and the
664
+ // rebased span.
665
+ if (lease.retiredAt !== null) {
666
+ throw new ServedRejectionError({
667
+ code: "E_STALE_RANGE",
668
+ headline: `line ${currentLine}${where} no longer resolves to the line identity it was served with.`,
669
+ servedBlock: echo,
670
+ firstOffendingLine: currentLine,
671
+ servedRows: echoRows,
672
+ cause: "retirement",
673
+ });
674
+ }
675
+ if (leaseSource.rebasedLineOf(lease.lineId) !== currentLine) {
676
+ throw new ServedRejectionError({
677
+ code: "E_STALE_RANGE",
678
+ headline: `line ${currentLine}${where} no longer resolves to the line identity it was served with.`,
679
+ servedBlock: echo,
680
+ firstOffendingLine: currentLine,
681
+ servedRows: echoRows,
682
+ cause: "served-range staleness",
683
+ });
684
+ }
685
+ }
686
+ }
395
687
  export function verifyServedRange(args) {
396
688
  const { served, startHash, endHash, startLine, endLine, fileHashes, fileLines, filePath } = args;
689
+ // The one route construction (obligation (c)): every leased/mirror decision below consults
690
+ // this value, so the conjunction cannot drift site by site.
691
+ const route = servedEvidenceRoute(args.leaseSource);
397
692
  const where = filePath ? ` in ${filePath}` : "";
398
693
  const retiredSet = args.retired ?? new Set();
399
694
  const servedCanons = args.servedCanons;
400
- const strictPos = args.strictPos ?? false;
401
- const epochSnapshotId = args.epochSnapshotId;
402
- const curSnapshotId = args.curSnapshotId;
403
- let isHealed = false;
404
- for (let i = 0; i < fileHashes.length; i++) {
405
- const h = fileHashes[i];
406
- if (getCanonForHash(h) === undefined)
407
- rememberHashCanon(h, canon(fileLines[i] ?? ""));
408
- }
409
- for (let i = 0; i < served.length; i++) {
410
- const h = served[i];
411
- if (h !== null && getCanonForHash(h) === undefined) {
412
- const pos = fileHashes.indexOf(h);
413
- if (pos >= 0)
414
- rememberHashCanon(h, canon(fileLines[pos] ?? ""));
415
- }
416
- }
417
695
  const echoRows = buildRangeEcho(startLine, endLine, fileHashes);
418
696
  const totalLen = endLine - startLine + 1;
419
697
  const tail = echoRows.length < totalLen
@@ -434,7 +712,8 @@ export function verifyServedRange(args) {
434
712
  if (expected !== undefined && expected !== null && expected !== actual) {
435
713
  throw new ServedRejectionError({
436
714
  code: "E_STALE_RANGE",
437
- message: `[MODEL] [E_STALE_RANGE] anchor "${retiredHash}" was freed since last full read (retired, canon changed from "${expected}" to "${actual}"). Re-read.\nCurrent range:\n${echo}`,
715
+ headline: `anchor "${retiredHash}" was freed since last full read (retired, canon changed from "${expected}" to "${actual}"). Re-read.`,
716
+ servedBlock: echo,
438
717
  firstOffendingLine: pos + 1,
439
718
  servedRows: echoRows,
440
719
  });
@@ -442,307 +721,179 @@ export function verifyServedRange(args) {
442
721
  }
443
722
  }
444
723
  }
724
+ // The leased route resolves boundaries through the lease seam FIRST (upstream
725
+ // b92e0ec:src/hashline/lease-resolve.ts:120-200): a missing or stale boundary lease rejects
726
+ // before content placement can substitute a look-alike for the lost identity. The non-leased
727
+ // route keeps mirror placement alone (upstream's non-leased analogue,
728
+ // served-verification.ts:745, is the zero-position arm below).
729
+ if (route.kind === "leased") {
730
+ interceptLeaseBoundaries({
731
+ startHash,
732
+ endHash,
733
+ fileHashes,
734
+ fileLines,
735
+ ...(filePath !== undefined ? { filePath } : {}),
736
+ leaseSource: route.source,
737
+ });
738
+ }
445
739
  const startPositions = servedPositionsOf(served, startHash);
446
740
  const endPositions = servedPositionsOf(served, endHash);
447
741
  const currentLen = endLine - startLine + 1;
448
742
  let from;
449
743
  let to;
744
+ // Exact-boundary rule (ADR-0018, superseding ADR-0004): each boundary anchor must have
745
+ // EXACTLY one served position. Anything else leaves `from`/`to` undefined and rejects
746
+ // below — there is no candidate-span search that could re-bind onto a look-alike line.
450
747
  if (startPositions.length === 1 && endPositions.length === 1) {
451
748
  from = Math.min(startPositions[0], endPositions[0]);
452
749
  to = Math.max(startPositions[0], endPositions[0]);
453
750
  }
454
- else {
455
- const candidates = [];
456
- for (const s of startPositions) {
457
- for (const e of endPositions) {
458
- const candFrom = Math.min(s, e);
459
- const candTo = Math.max(s, e);
460
- if (candTo - candFrom + 1 !== currentLen)
461
- continue;
462
- let ok = true;
463
- for (let k = 0; k < currentLen; k++) {
464
- if (served[candFrom + k] !== fileHashes[startLine - 1 + k]) {
465
- ok = false;
466
- break;
467
- }
468
- }
469
- if (ok)
470
- candidates.push({ from: candFrom, to: candTo });
471
- }
472
- }
473
- if (candidates.length === 1) {
474
- from = candidates[0].from;
475
- to = candidates[0].to;
476
- }
477
- else if (candidates.length > 1) {
478
- candidates.sort((a, b) => Math.abs(a.from - (startLine - 1)) - Math.abs(b.from - (startLine - 1)));
479
- from = candidates[0].from;
480
- to = candidates[0].to;
481
- }
482
- }
483
751
  if (from === undefined || to === undefined) {
484
- let healed;
485
- if (startPositions.length === 1 && endPositions.length === 1) {
486
- const sPos = startPositions[0];
487
- const ePos = endPositions[0];
488
- const servedFrom = Math.min(sPos, ePos);
489
- const servedTo = Math.max(sPos, ePos);
490
- const servedLen = servedTo - servedFrom + 1;
491
- if (servedLen === currentLen) {
492
- const expectedCanons = [];
493
- let canBuild = true;
494
- for (let k = 0; k < servedLen; k++) {
495
- const h = served[servedFrom + k];
496
- if (h === null) {
497
- canBuild = false;
498
- break;
499
- }
500
- const c = getCanonForHash(h);
501
- if (c === undefined) {
502
- canBuild = false;
503
- break;
504
- }
505
- expectedCanons.push(c);
506
- }
507
- if (canBuild) {
508
- const matches = [];
509
- for (let i = 0; i <= fileLines.length - servedLen; i++) {
510
- let ok = true;
511
- for (let k = 0; k < servedLen; k++) {
512
- if (canon(fileLines[i + k] ?? "") !== expectedCanons[k]) {
513
- ok = false;
514
- break;
515
- }
516
- }
517
- if (ok)
518
- matches.push(i);
519
- if (matches.length > 1)
520
- break;
521
- }
522
- if (matches.length === 1) {
523
- healed = { from: matches[0], to: matches[0] + servedLen - 1 };
524
- }
525
- }
526
- }
527
- }
528
- if (!healed) {
529
- const hasServed = served.some((h) => h !== null);
530
- const startInFile = fileHashes.includes(startHash);
531
- const endInFile = fileHashes.includes(endHash);
532
- if (hasServed && (!startInFile || !endInFile)) {
533
- const startCanon = getCanonForHash(startHash);
534
- const endCanon = getCanonForHash(endHash);
535
- if (startCanon !== undefined && endCanon !== undefined) {
536
- const startMatches = [];
537
- const endMatches = [];
538
- for (let i = 0; i < fileLines.length; i++) {
539
- if (canon(fileLines[i] ?? "") === startCanon)
540
- startMatches.push(i);
541
- if (canon(fileLines[i] ?? "") === endCanon)
542
- endMatches.push(i);
543
- if (startMatches.length > 1 && endMatches.length > 1)
544
- break;
545
- }
546
- if (startMatches.length === 1 && endMatches.length === 1) {
547
- const s = startMatches[0];
548
- const e = endMatches[0];
549
- const healedFrom = Math.min(s, e);
550
- const healedTo = Math.max(s, e);
551
- if (healedTo - healedFrom + 1 === currentLen) {
552
- let interiorOk = true;
553
- if (currentLen > 2) {
554
- const healedCanons = [];
555
- for (let k = 0; k < currentLen; k++)
556
- healedCanons.push(canon(fileLines[healedFrom + k] ?? ""));
557
- let count = 0;
558
- for (let i = 0; i <= fileLines.length - currentLen; i++) {
559
- let ok = true;
560
- for (let k = 0; k < currentLen; k++)
561
- if (canon(fileLines[i + k] ?? "") !== healedCanons[k]) {
562
- ok = false;
563
- break;
564
- }
565
- if (ok)
566
- count++;
567
- if (count > 1)
568
- break;
569
- }
570
- if (count !== 1)
571
- interiorOk = false;
572
- }
573
- if (interiorOk)
574
- healed = { from: healedFrom, to: healedTo };
575
- }
576
- }
577
- }
578
- }
579
- }
580
- if (healed) {
581
- from = healed.from;
582
- to = healed.to;
583
- isHealed = true;
584
- }
585
- else {
586
- const problems = [];
587
- if (startPositions.length === 0) {
588
- problems.push(`remove_from "${startHash}" has no served position`);
589
- }
590
- else if (startPositions.length > 1) {
591
- problems.push(`remove_from "${startHash}" was served at ${startPositions.length} positions`);
592
- }
593
- if (endPositions.length === 0) {
594
- problems.push(`remove_to "${endHash}" has no served position`);
595
- }
596
- else if (endPositions.length > 1) {
597
- problems.push(`remove_to "${endHash}" was served at ${endPositions.length} positions`);
598
- }
599
- throw new ServedRejectionError({
600
- code: "E_UNSERVED_RANGE",
601
- unservedKind: "boundary",
602
- message: `[MODEL] [E_UNSERVED_RANGE] cannot verify range against served state${where}: ${problems.join("; ")}. ` +
603
- `No served span matched the current range (${currentLen} lines). ` +
604
- `A full read will re-sync the served mirror — the echoed range below is current content, ` +
605
- `but retrying without re-reading cannot clear a stale duplicate outside the echoed window.\n` +
606
- `Current range:\n${echo}`,
607
- servedRows: echoRows,
752
+ const missing = [
753
+ ...new Set([
754
+ ...(startPositions.length === 0 ? [startHash] : []),
755
+ ...(endPositions.length === 0 ? [endHash] : []),
756
+ ]),
757
+ ];
758
+ if (missing.length > 0) {
759
+ // A boundary anchor the mirror never placed was never served for this file: the
760
+ // rejection carries no rows — with nothing served there is nothing trustworthy to
761
+ // retry with, only a read restores grounding (port of upstream
762
+ // b92e0ec:src/hashline/served-verification.ts:729-749).
763
+ throw new DomainError("E_UNKNOWN_ANCHOR", {
764
+ path: filePath ?? "this file",
765
+ anchors: missing,
608
766
  });
609
767
  }
610
- }
611
- if (isHealed) {
612
- for (let k = 0; k < currentLen; k++) {
613
- const servedHash = served[from + k];
614
- if (servedHash === null)
615
- continue;
616
- const expectedCanon = getCanonForHash(servedHash);
617
- const actualCanon = canon(fileLines[from + k] ?? "");
618
- if (expectedCanon !== undefined && expectedCanon !== actualCanon) {
619
- const offendingLine = from + k + 1;
620
- throw new ServedRejectionError({
621
- code: "E_STALE_RANGE",
622
- message: `[MODEL] [E_STALE_RANGE] line ${offendingLine}${where} differs from what was served.\nCurrent range:\n${echo}\n${retryHint()}`,
623
- firstOffendingLine: offendingLine,
624
- servedRows: echoRows,
625
- });
626
- }
768
+ const problems = [];
769
+ if (startPositions.length > 1) {
770
+ problems.push(`anchor_from "${startHash}" was served at ${startPositions.length} positions`);
627
771
  }
772
+ if (endPositions.length > 1) {
773
+ problems.push(`anchor_to "${endHash}" was served at ${endPositions.length} positions`);
774
+ }
775
+ throw new ServedRejectionError({
776
+ code: "E_UNSERVED_RANGE",
777
+ unservedKind: "boundary",
778
+ headline: `cannot verify range against served state${where}: ${problems.join("; ")}. ` +
779
+ `Each boundary anchor must have exactly one served position — no served span is searched ` +
780
+ `for a look-alike line. A full read will re-sync the served mirror; the echoed range below ` +
781
+ `is current content.`,
782
+ servedBlock: echo,
783
+ servedRows: echoRows,
784
+ });
628
785
  }
629
- else {
786
+ // The never-served interior scan is the mirror route's evidence rule (upstream ADR-0024
787
+ // decision 2); the leased route skips it because the identity gate owns interior holes
788
+ // there (decision 1) — the full rationale lives on `owesInteriorScan`.
789
+ if (owesInteriorScan(route)) {
630
790
  for (let i = from; i <= to; i++) {
631
791
  if (served[i] === null) {
632
792
  throw new ServedRejectionError({
633
793
  code: "E_UNSERVED_RANGE",
634
794
  unservedKind: "interior",
635
- message: `[MODEL] [E_UNSERVED_RANGE] line ${i + 1}${where} was never served.\nCurrent range:\n${echo}\n${retryHint()}`,
795
+ headline: `line ${i + 1}${where} was never served.`,
796
+ servedBlock: echo,
636
797
  firstOffendingLine: i + 1,
637
798
  servedRows: echoRows,
638
799
  });
639
800
  }
640
801
  }
641
- const servedLen = to - from + 1;
642
- if (servedLen !== currentLen) {
643
- let lenHealed = false;
644
- const expectedCanons = [];
645
- let canBuild = true;
646
- for (let k = 0; k < servedLen; k++) {
647
- const h = served[from + k];
648
- if (h === null) {
649
- canBuild = false;
650
- break;
651
- }
652
- const c = getCanonForHash(h);
653
- if (c === undefined) {
654
- canBuild = false;
655
- break;
656
- }
657
- expectedCanons.push(c);
658
- }
659
- if (canBuild) {
660
- let matches = 0;
661
- for (let i = 0; i <= fileLines.length - servedLen; i++) {
662
- let ok = true;
663
- for (let k = 0; k < servedLen; k++)
664
- if (canon(fileLines[i + k] ?? "") !== expectedCanons[k]) {
665
- ok = false;
666
- break;
667
- }
668
- if (ok)
669
- matches++;
670
- if (matches > 1)
671
- break;
672
- }
673
- if (matches === 1)
674
- lenHealed = true;
675
- }
676
- if (!lenHealed) {
677
- throw new ServedRejectionError({
678
- code: "E_STALE_RANGE",
679
- message: `[MODEL] [E_STALE_RANGE] served span (${servedLen} lines) no longer matches current range (${currentLen} lines)${where}.\nCurrent range:\n${echo}\n${retryHint()}`,
680
- firstOffendingLine: startLine,
681
- servedRows: echoRows,
682
- });
683
- }
684
- }
685
- // Strict pos check for concurrency (pos-free vs strict)
686
- if (strictPos && from !== startLine - 1) {
687
- throw new ServedRejectionError({
688
- code: "E_STALE_RANGE",
689
- message: `[MODEL] [E_STALE_RANGE] anchor was served at line ${from + 1} but now resolves to line ${startLine} (pos-restricted concurrency). Re-read.\nCurrent range:\n${echo}`,
690
- firstOffendingLine: startLine,
691
- servedRows: echoRows,
692
- });
693
- }
694
- // Canon check for same-pos different content (collision)
695
- if (servedCanons) {
696
- for (let k = 0; k < servedLen; k++) {
697
- const expected = servedCanons[from + k];
698
- if (expected !== null && expected !== undefined) {
699
- const actual = canon(fileLines[startLine - 1 + k] ?? "");
700
- if (expected !== actual) {
701
- throw new ServedRejectionError({
702
- code: "E_STALE_RANGE",
703
- message: `[MODEL] [E_STALE_RANGE] line ${startLine + k}${where} canon differs from served (expected "${expected}" vs actual "${actual}").\nCurrent range:\n${echo}`,
704
- firstOffendingLine: startLine + k,
705
- servedRows: echoRows,
706
- });
707
- }
708
- }
709
- }
710
- }
711
- // Tombstone interior check (whole-span) — gated on canon inequality (fail-closed only for different canon)
802
+ }
803
+ const servedLen = to - from + 1;
804
+ if (servedLen !== currentLen) {
805
+ throw new ServedRejectionError({
806
+ code: "E_STALE_RANGE",
807
+ headline: `served span (${servedLen} lines) no longer matches current range (${currentLen} lines)${where}. Re-read.`,
808
+ servedBlock: echo,
809
+ firstOffendingLine: startLine,
810
+ servedRows: echoRows,
811
+ });
812
+ }
813
+ // Position check or identity gate — the seam is opt-in (obligation (c)).
814
+ //
815
+ // With a lease source, identity decides: `verifyRebasedSpan` checks the whole served window by
816
+ // the leases its anchors were served with, so a benign shift (same bytes, moved position —
817
+ // exterior drift above the span) applies at its rebased coordinate with no re-read, while a
818
+ // look-alike rebind (the named line was deleted and another line now holds its bytes) rejects.
819
+ //
820
+ // Without a lease source the unconditional position check below stands: identity only, never a
821
+ // weaker position check. The pos-free route is REACHABLE on a normal session route (a windowed
822
+ // read never pinned the epoch; a preview/no-store edit carries no leases), which is why this
823
+ // fallback cannot be dropped.
824
+ if (route.kind === "leased") {
825
+ verifyRebasedSpan({
826
+ served,
827
+ servedStart: from + 1,
828
+ servedEnd: to + 1,
829
+ rebasedStart: startLine,
830
+ rebasedEnd: endLine,
831
+ route,
832
+ echo,
833
+ echoRows,
834
+ where,
835
+ });
836
+ }
837
+ else if (from !== startLine - 1) {
838
+ throw new ServedRejectionError({
839
+ code: "E_STALE_RANGE",
840
+ headline: `anchor was served at line ${from + 1} but now resolves to line ${startLine}. Re-read.`,
841
+ servedBlock: echo,
842
+ firstOffendingLine: startLine,
843
+ servedRows: echoRows,
844
+ });
845
+ }
846
+ // Canon check for same-pos different content (collision)
847
+ if (servedCanons) {
712
848
  for (let k = 0; k < servedLen; k++) {
713
- const h = fileHashes[startLine - 1 + k];
714
- if (h && retiredSet.has(h)) {
715
- const expectedCanon = servedCanons?.[from + k] ?? undefined;
716
- const actualCanon = canon(fileLines[startLine - 1 + k] ?? "");
717
- if (expectedCanon !== undefined &&
718
- expectedCanon !== null &&
719
- expectedCanon !== actualCanon) {
849
+ const expected = servedCanons[from + k];
850
+ if (expected !== null && expected !== undefined) {
851
+ const actual = canon(fileLines[startLine - 1 + k] ?? "");
852
+ if (expected !== actual) {
720
853
  throw new ServedRejectionError({
721
854
  code: "E_STALE_RANGE",
722
- message: `[MODEL] [E_STALE_RANGE] line ${startLine + k}${where} uses retired anchor "${h}" (freed since last full read, canon changed). Re-read.\nCurrent range:\n${echo}`,
855
+ headline: `line ${startLine + k}${where} canon differs from served (expected "${expected}" vs actual "${actual}").`,
856
+ servedBlock: echo,
723
857
  firstOffendingLine: startLine + k,
724
858
  servedRows: echoRows,
725
859
  });
726
860
  }
727
861
  }
728
862
  }
729
- for (let k = 0; k < servedLen; k++) {
730
- if (served[from + k] !== fileHashes[startLine - 1 + k]) {
731
- const offendingLine = startLine + k;
863
+ }
864
+ // Tombstone interior check (whole-span) — gated on canon inequality (fail-closed only for different canon)
865
+ for (let k = 0; k < servedLen; k++) {
866
+ const h = fileHashes[startLine - 1 + k];
867
+ if (h && retiredSet.has(h)) {
868
+ const expectedCanon = servedCanons?.[from + k] ?? undefined;
869
+ const actualCanon = canon(fileLines[startLine - 1 + k] ?? "");
870
+ if (expectedCanon !== undefined && expectedCanon !== null && expectedCanon !== actualCanon) {
732
871
  throw new ServedRejectionError({
733
872
  code: "E_STALE_RANGE",
734
- message: `[MODEL] [E_STALE_RANGE] line ${offendingLine}${where} differs from what was served.\nCurrent range:\n${echo}\n${retryHint()}`,
735
- firstOffendingLine: offendingLine,
873
+ headline: `line ${startLine + k}${where} uses retired anchor "${h}" (freed since last full read, canon changed). Re-read.`,
874
+ servedBlock: echo,
875
+ firstOffendingLine: startLine + k,
736
876
  servedRows: echoRows,
737
877
  });
738
878
  }
739
879
  }
740
880
  }
741
- }
742
- export async function recordEchoServes(sessionKey, path, rows, policy, lineCount) {
743
- if (policy !== "live")
744
- return;
745
- await recordServed(sessionKey, path, rows, lineCount);
881
+ for (let k = 0; k < servedLen; k++) {
882
+ // The leased route's `null` skip is `checksPosition`'s decision (the identity gate already
883
+ // adjudicated the hole); the mirror route's holes rejected in the scan above.
884
+ if (!checksPosition(route, served[from + k]))
885
+ continue;
886
+ if (served[from + k] !== fileHashes[startLine - 1 + k]) {
887
+ const offendingLine = startLine + k;
888
+ throw new ServedRejectionError({
889
+ code: "E_STALE_RANGE",
890
+ headline: `line ${offendingLine}${where} differs from what was served. Re-read.`,
891
+ servedBlock: echo,
892
+ firstOffendingLine: offendingLine,
893
+ servedRows: echoRows,
894
+ });
895
+ }
896
+ }
746
897
  }
747
898
  export function buildIdx(content) {
748
899
  const fileLines = splitLines(content);
@@ -762,7 +913,7 @@ export function buildIdx(content) {
762
913
  }
763
914
  function assertNotEmpty(originalContent, result) {
764
915
  if (originalContent.length > 0 && result.length === 0) {
765
- throw new Error("[MODEL] [E_EMPTY_RANGE] Cannot empty a non-empty file via edit. Use `write` if you need to clear the file.");
916
+ throw new DomainError("E_EMPTY_RANGE", {});
766
917
  }
767
918
  }
768
919
  function resToSpan(edit, content, lineIndex) {
@@ -824,11 +975,19 @@ function assemble(content, span, signal) {
824
975
  abortIf(signal);
825
976
  return content.slice(0, span.start) + span.replacement + content.slice(span.end);
826
977
  }
827
- export function applyEdit(content, edit, signal, precomputedHashes, filePath, served, servedCanons, retired, epochSnapshotId, curSnapshotId, strictPos) {
978
+ export function applyEdit(content, edit, signal, precomputedHashes, filePath, served, servedCanons, retired, mode, leaseSource) {
828
979
  abortIf(signal);
829
980
  const lineIndex = buildIdx(content);
830
981
  const fileHashes = precomputedHashes ?? lineHashesPure(content);
831
982
  const warnings = [];
983
+ const literal = mode === "literal";
984
+ let bypassNoted = false;
985
+ const noteLiteralBypass = () => {
986
+ if (!bypassNoted) {
987
+ bypassNoted = true;
988
+ warnings.push(formatWarning("W_LITERAL_BYPASS", {}));
989
+ }
990
+ };
832
991
  const rangeFixed = swapReversedRanges(edit, fileHashes, warnings);
833
992
  let prefixFixed;
834
993
  try {
@@ -838,8 +997,8 @@ export function applyEdit(content, edit, signal, precomputedHashes, filePath, se
838
997
  if (!(error instanceof BadAnchorError) || !served)
839
998
  throw error;
840
999
  // Anchor-syntax garbage that is actually served-echo belongs to the
841
- // E_SERVED_ECHO guard below: re-check the stripped + raw lines at the
842
- // resolved start line and throw the echo denial; otherwise E_BAD_ANCHOR stands.
1000
+ // E_SUSPICIOUS_TEXT guard below: re-check the stripped + raw lines at the
1001
+ // resolved start line and throw the echo denial; otherwise E_MALFORMED_ANCHOR stands.
843
1002
  const stripped = error.stripped;
844
1003
  const lineByHash = new Map();
845
1004
  for (let i = 0; i < fileHashes.length; i++)
@@ -852,15 +1011,31 @@ export function applyEdit(content, edit, signal, precomputedHashes, filePath, se
852
1011
  ? findEditHashEcho(stripped.content_lines, served, startLine)
853
1012
  : undefined);
854
1013
  if (echo) {
855
- const msg = `[MODEL] [E_SERVED_ECHO] Refused edit to ${filePath ?? "(unknown file)"}: replacement line ${echo.k} begins with the exact ${echo.hash}${HASH_SEP} anchor served for this session, path, and range-relative line. Remove the copied anchors and retry. Nothing was written.`;
856
- throw new EditHashEchoError(msg, []);
1014
+ if (literal) {
1015
+ // Declared literal bytes are the intent: apply the raw edit verbatim
1016
+ // (prefixes intact), not the stripped form. Non-echo garbage still
1017
+ // throws BadAnchorError below via `throw error`.
1018
+ prefixFixed = rangeFixed;
1019
+ noteLiteralBypass();
1020
+ }
1021
+ else {
1022
+ throw new EditHashEchoError({
1023
+ target: "edit",
1024
+ path: filePath ?? "(unknown file)",
1025
+ line: echo.k,
1026
+ hash: echo.hash,
1027
+ servedLine: startLine + echo.k - 1,
1028
+ });
1029
+ }
1030
+ }
1031
+ else {
1032
+ throw error;
857
1033
  }
858
- throw error;
859
1034
  }
860
1035
  const { resolved: initialResolved, mismatches } = valEdit(prefixFixed, lineIndex.fileLines, fileHashes, warnings, signal);
861
1036
  if (mismatches.length || !initialResolved) {
862
- const { message, servedRows } = fmtMismatchWithServes(mismatches, lineIndex.fileLines, fileHashes, filePath);
863
- throw new AnchorMismatchError(message, servedRows);
1037
+ const { headline, servedBlock, servedRows } = fmtMismatchWithServes(mismatches, lineIndex.fileLines, fileHashes, filePath);
1038
+ throw new AnchorMismatchError("E_STALE_ANCHOR", { headline, servedRows, servedBlock });
864
1039
  }
865
1040
  warnUnicodeEsc(prefixFixed, warnings);
866
1041
  const resolved = initialResolved;
@@ -873,8 +1048,18 @@ export function applyEdit(content, edit, signal, precomputedHashes, filePath, se
873
1048
  if (!echo)
874
1049
  echo = findEditHashEcho(prefixFixed.content_lines, served, startLineEcho);
875
1050
  if (echo) {
876
- const msg = `[MODEL] [E_SERVED_ECHO] Refused edit to ${filePath ?? "(unknown file)"}: replacement line ${echo.k} begins with the exact ${echo.hash}${HASH_SEP} anchor served for this session, path, and range-relative line. Remove the copied anchors and retry. Nothing was written.`;
877
- throw new EditHashEchoError(msg, []);
1051
+ if (literal) {
1052
+ noteLiteralBypass();
1053
+ }
1054
+ else {
1055
+ throw new EditHashEchoError({
1056
+ target: "edit",
1057
+ path: filePath ?? "(unknown file)",
1058
+ line: echo.k,
1059
+ hash: echo.hash,
1060
+ servedLine: startLineEcho + echo.k - 1,
1061
+ });
1062
+ }
878
1063
  }
879
1064
  const startAnchor = resolved.hash_bounds[0];
880
1065
  const endAnchor = resolved.hash_bounds[1];
@@ -889,9 +1074,7 @@ export function applyEdit(content, edit, signal, precomputedHashes, filePath, se
889
1074
  filePath,
890
1075
  servedCanons,
891
1076
  retired,
892
- epochSnapshotId,
893
- curSnapshotId,
894
- strictPos,
1077
+ leaseSource,
895
1078
  });
896
1079
  }
897
1080
  const spanResult = resToSpan(resolved, content, lineIndex);
@@ -911,12 +1094,37 @@ export function applyEdit(content, edit, signal, precomputedHashes, filePath, se
911
1094
  const result = assemble(content, spanResult, signal);
912
1095
  assertNotEmpty(content, result);
913
1096
  const changed = changedRange(content, result);
1097
+ // FU-5 (§4.7 conformance, upstream apply.ts:387-427): the 0-matched literal
1098
+ // write-through (#63/ADR-0025) keeps writing, and these tiers name what was
1099
+ // written. Middle tier stays evidence-gated (`if (served)`): with no served
1100
+ // content it reports nothing by construction. Soft-hint tier is shape-only
1101
+ // and runs against an empty served set when served is absent — it fires
1102
+ // regardless of the literal declaration (the declaration covers served rows,
1103
+ // not never-served shapes). Never blocks, never rewrites, keeps no state.
1104
+ // FU-R (upstream apply.ts:399-401): the offending count travels as structured
1105
+ // data (`neverServedCount`); the engine aggregates across batch items and renders
1106
+ // one counted hint per call — this layer never renders the hint string itself.
1107
+ let neverServedCount = 0;
1108
+ if (served) {
1109
+ for (const mismatch of findServedPrefixMismatches(resolved.content_lines, served, servedCanons ?? [], 1)) {
1110
+ warnings.push(buildServedEditPrefixNote({
1111
+ k: mismatch.k,
1112
+ anchor: mismatch.anchor,
1113
+ servedLine: mismatch.servedLine,
1114
+ }));
1115
+ }
1116
+ }
1117
+ const neverServed = findNeverServedAnchorShapes(resolved.content_lines, served ?? [], 1);
1118
+ if (neverServed.length > 0) {
1119
+ neverServedCount = neverServed.length;
1120
+ }
914
1121
  return {
915
1122
  content: result,
916
1123
  firstChangedLine: changed?.firstChangedLine,
917
1124
  lastChangedLine: changed?.lastChangedLine,
918
1125
  range: resolvedRange(resolved),
919
1126
  ...(warnings.length ? { warnings } : {}),
1127
+ ...(neverServedCount > 0 ? { neverServedCount } : {}),
920
1128
  };
921
1129
  }
922
1130
  function resolvedRange(resolved) {
@@ -976,5 +1184,5 @@ export function changedRange(original, result) {
976
1184
  // by biome noRestrictedImports. Deleting this re-export block would scatter
977
1185
  // the hashline surface again — it concentrates (deep).
978
1186
  // ---------------------------------------------------------------------------
979
- export { HASH_RE, HASH_CLASS, HASH_SEP, ANCHOR_LEN, ALPH_RE, ALPH, HASH_LEN, HASH_SPACE, MAX_HASH_LINES, HASH_PROBE_STRIDE, CANON_VERSION, canon, lineHashesPure, mapStableHashes, initHasher, contentChecksum, getCanonForHash, rememberHashCanon, } from "./hash-assign.js";
1187
+ export { HASH_RE, HASH_CLASS, HASH_SEP, ANCHOR_LEN, ALPH_RE, ALPH, HASH_LEN, HASH_SPACE, MAX_HASH_LINES, HASH_PROBE_STRIDE, CANON_VERSION, canon, lineHashesPure, mapStableHashes, initHasher, contentChecksum, } from "./hash-assign.js";
980
1188
  export { lineHashes } from "./hash.js";