dsh-better-edit 1.2.4 → 1.2.5

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 (97) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/lib/domain-errors.js +11 -9
  3. package/lib/edit-mode.js +11 -0
  4. package/lib/encoding.js +2 -0
  5. package/lib/file-encoding-state.js +42 -25
  6. package/lib/file-view.js +26 -205
  7. package/lib/fs-bridge.js +14 -49
  8. package/lib/hashline/anchor-pipeline.js +8 -499
  9. package/lib/hashline/hash-assign.js +55 -4
  10. package/lib/hashline/index.js +5 -2
  11. package/lib/hashline/served-evidence.js +531 -0
  12. package/lib/index.js +176 -47
  13. package/lib/mutation/engine.js +10 -13
  14. package/lib/mutation.js +36 -100
  15. package/lib/noop-guard.js +24 -39
  16. package/lib/paths.js +9 -5
  17. package/lib/read-and-serve.js +51 -53
  18. package/lib/reclaim.js +65 -0
  19. package/lib/self-heal.js +6 -10
  20. package/lib/session-view.js +61 -21
  21. package/lib/store/index.js +14 -14
  22. package/lib/store-config.js +4 -5
  23. package/lib/store-lifecycle.js +1 -1
  24. package/lib/tool-edit.js +0 -3
  25. package/lib/tool-read.js +2 -8
  26. package/lib/tool-str-replace-editor.js +3 -10
  27. package/lib/tool-undo.js +5 -13
  28. package/lib/types/contract.d.ts +2 -1
  29. package/lib/types/domain-errors.d.ts +8 -9
  30. package/lib/types/edit-mode.d.ts +11 -0
  31. package/lib/types/encoding.d.ts +1 -0
  32. package/lib/types/file-encoding-state.d.ts +10 -10
  33. package/lib/types/file-view.d.ts +18 -56
  34. package/lib/types/hashline/anchor-pipeline.d.ts +6 -128
  35. package/lib/types/hashline/hash-assign.d.ts +40 -0
  36. package/lib/types/hashline/index.d.ts +6 -4
  37. package/lib/types/hashline/served-evidence.d.ts +152 -0
  38. package/lib/types/mutation/engine.d.ts +4 -2
  39. package/lib/types/mutation.d.ts +9 -57
  40. package/lib/types/noop-guard.d.ts +2 -33
  41. package/lib/types/paths.d.ts +0 -1
  42. package/lib/types/reclaim.d.ts +36 -0
  43. package/lib/types/session-view.d.ts +28 -8
  44. package/lib/types/store/index.d.ts +12 -11
  45. package/lib/types/store-config.d.ts +1 -1
  46. package/lib/types/store-lifecycle.d.ts +12 -2
  47. package/lib/types/tool-edit.d.ts +0 -2
  48. package/lib/types/tool-read.d.ts +0 -5
  49. package/lib/types/tool-str-replace-editor.d.ts +0 -6
  50. package/lib/types/tool-undo.d.ts +0 -5
  51. package/package.json +3 -2
  52. package/lib/drift.js +0 -5
  53. package/lib/dsh-context.js +0 -5
  54. package/lib/edit-engine.js +0 -7
  55. package/lib/edit-normalize.js +0 -9
  56. package/lib/edit-pipeline.js +0 -6
  57. package/lib/file-kind.js +0 -6
  58. package/lib/file-reader.js +0 -6
  59. package/lib/guidance/index.js +0 -8
  60. package/lib/hashline/alphabet.js +0 -2
  61. package/lib/hashline/apply.js +0 -2
  62. package/lib/hashline/hasher.js +0 -2
  63. package/lib/hashline/parse.js +0 -2
  64. package/lib/hashline/pure.js +0 -2
  65. package/lib/hashline/resolve.js +0 -3
  66. package/lib/hashline/served.js +0 -2
  67. package/lib/preview-controller.js +0 -65
  68. package/lib/read-render.js +0 -6
  69. package/lib/schema.js +0 -24
  70. package/lib/served-store.js +0 -5
  71. package/lib/tool-batch-edit.js +0 -190
  72. package/lib/truncate.js +0 -6
  73. package/lib/types/drift.d.ts +0 -5
  74. package/lib/types/dsh-context.d.ts +0 -5
  75. package/lib/types/edit-engine.d.ts +0 -7
  76. package/lib/types/edit-normalize.d.ts +0 -1
  77. package/lib/types/edit-pipeline.d.ts +0 -6
  78. package/lib/types/file-kind.d.ts +0 -6
  79. package/lib/types/file-reader.d.ts +0 -6
  80. package/lib/types/guidance/index.d.ts +0 -8
  81. package/lib/types/hashline/alphabet.d.ts +0 -1
  82. package/lib/types/hashline/apply.d.ts +0 -1
  83. package/lib/types/hashline/hasher.d.ts +0 -1
  84. package/lib/types/hashline/parse.d.ts +0 -1
  85. package/lib/types/hashline/pure.d.ts +0 -1
  86. package/lib/types/hashline/resolve.d.ts +0 -1
  87. package/lib/types/hashline/served.d.ts +0 -1
  88. package/lib/types/preview-controller.d.ts +0 -33
  89. package/lib/types/read-render.d.ts +0 -6
  90. package/lib/types/schema.d.ts +0 -25
  91. package/lib/types/served-store.d.ts +0 -5
  92. package/lib/types/tool-batch-edit.d.ts +0 -25
  93. package/lib/types/truncate.d.ts +0 -6
  94. package/lib/types/validation.d.ts +0 -6
  95. package/lib/types/workspace.d.ts +0 -5
  96. package/lib/validation.js +0 -6
  97. package/lib/workspace.js +0 -5
@@ -166,11 +166,6 @@ export interface ErrorPayloadMap {
166
166
  count: number;
167
167
  batch: boolean;
168
168
  servedBlock: string;
169
- /**
170
- * Present on engine single rejects: the display path ("in <path>" flavor).
171
- * The batch ref already names the item, so no index is needed.
172
- */
173
- path?: string;
174
169
  };
175
170
  E_UNSUPPORTED_FILE: {
176
171
  path: string;
@@ -382,10 +377,14 @@ export declare const DECLARATION_ONLY_FIELDS: Readonly<Record<string, AllowlistE
382
377
  *
383
378
  * | ported upstream diagnostic | upstream producer (pi-better-edit@b92e0ec) | local producer |
384
379
  * |---|---|---|
385
- * | `E_FOREIGN_ANCHOR` | `lease-resolve.ts:116` | `anchor-pipeline.ts` (`throwUnknownOrForeign`, boundary placement) |
386
- * | `E_UNKNOWN_ANCHOR` | `lease-resolve.ts:118`, `served-verification.ts:745` | `anchor-pipeline.ts` (boundary placement, pre-gate) |
387
- * | `E_UNVERIFIED_RANGE` | `lease-resolve.ts:186`, `served-verification.ts:187` | `anchor-pipeline.ts` (pre-gate stale-boundary arm) |
388
- * | `E_TARGET_LOST` | `served-verification.ts:170`, `lease-resolve.ts:196` | `anchor-pipeline.ts` (pre-gate stale-boundary arm) |
380
+ * | `E_FOREIGN_ANCHOR` | `lease-resolve.ts:116` | `served-evidence.ts` (`throwUnknownOrForeign`, boundary placement) |
381
+ * | `E_UNKNOWN_ANCHOR` | `lease-resolve.ts:118`, `served-verification.ts:745` | `served-evidence.ts` (boundary placement, pre-gate) |
382
+ * | `E_UNVERIFIED_RANGE` | `lease-resolve.ts:186`, `served-verification.ts:187` | `served-evidence.ts` (pre-gate stale-boundary arm) |
383
+ * | `E_TARGET_LOST` | `served-verification.ts:170`, `lease-resolve.ts:196` | `served-evidence.ts` (pre-gate stale-boundary arm) |
384
+ *
385
+ * The upstream column is scoped to the upstream tree (`pi-better-edit@b92e0ec`): its
386
+ * `served-verification.ts` never existed downstream, so those cites never named a local
387
+ * file. The local column did move — the four arms live in `served-evidence.ts` (ADR-0037).
389
388
  *
390
389
  * Their owner is `"upstream absorb"` and their trigger is the absorb that
391
390
  * ports the corresponding producer. When that happens, reintroduce the code
@@ -0,0 +1,11 @@
1
+ /**
2
+ * EditMode — the one member of the request contract the write pipeline names.
3
+ *
4
+ * WHY a module of its own (ADR-0037): `EditMode` is the only edge from
5
+ * anchor-pipeline back into contract.ts, and contract.ts reaches the read side
6
+ * through `ReadWindow`. Left there, the type re-closed the import ring; as a leaf
7
+ * it closes nothing — both ends import this file and never each other.
8
+ *
9
+ * @module dsh-better-edit/edit-mode
10
+ */
11
+ export type EditMode = "general" | "literal";
@@ -5,6 +5,7 @@
5
5
  */
6
6
  export declare const SUPPORTED_ENCODINGS: readonly ["gbk", "big5", "shift_jis", "euc-kr", "windows-1251", "iso-8859-1"];
7
7
  export type SupportedEncoding = (typeof SUPPORTED_ENCODINGS)[number];
8
+ export declare const SUPPORTED_ENCODINGS_LABEL: string;
8
9
  /** Canonicalize case-insensitive encoding param, strip -_ . */
9
10
  export declare function normalizeEncoding(input: string): string | undefined;
10
11
  export declare function isSupportedEncoding(enc: string): boolean;
@@ -32,21 +32,21 @@ import { type LineEnding } from "./edit-diff.js";
32
32
  * A drifted memo is dropped first, so a changed file is re-detected instead of
33
33
  * having the old encoding laundered onto its new bytes.
34
34
  */
35
- export declare function encodingHintAtVersion(targetKey: string, currentVersion: string | undefined): string | undefined;
35
+ export declare function encodingHintAtVersion(filePath: string, currentVersion: string | undefined): string | undefined;
36
36
  export interface FileEncodingState {
37
37
  encoding: string;
38
38
  hasBOM: boolean;
39
39
  lineEnding?: LineEnding;
40
40
  version: string | undefined;
41
41
  }
42
- export declare function getEncodingState(targetKey: string): FileEncodingState | undefined;
43
- export declare function setEncodingState(targetKey: string, state: FileEncodingState): void;
44
- export declare function clearEncodingState(targetKey?: string): void;
45
- export declare function getAutoGuessFooter(targetKey: string): string | undefined;
46
- export declare function setAutoGuessFooter(targetKey: string, footer: string): void;
47
- export declare function clearAutoGuessFooter(targetKey?: string): void;
42
+ export declare function getEncodingState(filePath: string): FileEncodingState | undefined;
43
+ export declare function setEncodingState(filePath: string, state: FileEncodingState): void;
44
+ export declare function clearEncodingState(filePath?: string): void;
45
+ export declare function getAutoGuessFooter(filePath: string): string | undefined;
46
+ export declare function setAutoGuessFooter(filePath: string, footer: string): void;
47
+ export declare function clearAutoGuessFooter(filePath?: string): void;
48
48
  /** Invalidate memo when FsVersion drifted (ADR-0012). */
49
- export declare function invalidateIfStale(targetKey: string, currentVersion: string | undefined): void;
49
+ export declare function invalidateIfStale(filePath: string, currentVersion: string | undefined): void;
50
50
  export declare function buildTop3Description(candidates: CandidatePreview[]): string;
51
51
  export declare function buildTop3ErrorMessage(displayPath: string, candidates: CandidatePreview[]): string;
52
52
  export interface DecodeAdmissionConfig {
@@ -75,8 +75,8 @@ export interface DecodeForOpenOptions {
75
75
  * `autoGuessEncoding`, but Top-3 is always computed for the error/ footer.
76
76
  */
77
77
  export declare function decodeForOpen(bytes: Uint8Array, config: DecodeAdmissionConfig, opts?: DecodeForOpenOptions): Promise<DecodeForOpenResult>;
78
- export declare function recordOpenState(targetKey: string, text: string, encoding: string, hasBOM: boolean, version: string | undefined): FileEncodingState;
79
- export declare function recordFooter(targetKey: string, footer: string | undefined): void;
78
+ export declare function recordOpenState(filePath: string, text: string, encoding: string, hasBOM: boolean, version: string | undefined): FileEncodingState;
79
+ export declare function recordFooter(filePath: string, footer: string | undefined): void;
80
80
  export interface EncodeForSaveOptions {
81
81
  encodingHint?: string;
82
82
  normalizeToUtf8?: boolean;
@@ -2,17 +2,15 @@
2
2
  * FileView — deep module owning "what the model sees".
3
3
  *
4
4
  * Single seam for normalize → hash → render → truncate → served-row
5
- * selection. Previously split across file-reader, read-render, truncate,
6
- * file-kind, validation — each shallow (interface≈implementation). Now one
7
- * file owns the invariant; deleting it would scatter complexity (deep).
5
+ * selection. Previously split across five shallow modules
6
+ * (interface≈implementation). Now one file owns the invariant; deleting it
7
+ * would scatter complexity (deep).
8
8
  *
9
- * Private helpers inlined from file-reader (normFromText/fileSnap),
10
- * read-render (fmtReadPreview), truncate (truncateHead), file-kind
11
- * (loadFileKindAndText), validation (valKind/valAccess).
12
- * Old files are shims re-exporting from this seam for compat.
9
+ * Private helpers inlined from the retired reader, renderer and truncate
10
+ * modules: normFromText/fileSnap, fmtReadPreview, truncateHead.
13
11
  *
14
12
  * Two surfaces:
15
- * - `preview` (pure, no IO) — tested without filesystem
13
+ * - `fmtReadPreview` (pure, no IO) — tested without filesystem
16
14
  * - `readView` (IO) — read + normalize + render + truncate + hashes
17
15
  *
18
16
  * @module dsh-better-edit/file-view
@@ -50,32 +48,6 @@ export interface FileStats {
50
48
  mtimeMs: number;
51
49
  ctimeMs: number;
52
50
  }
53
- export interface LFileText {
54
- kind: "text";
55
- text: string;
56
- stats?: FileStats;
57
- hadUtf8DecodeErrors?: true;
58
- }
59
- export type LFile = {
60
- kind: "directory";
61
- } | {
62
- kind: "image";
63
- mimeType: string;
64
- } | LFileText | {
65
- kind: "binary";
66
- description: string;
67
- };
68
- export interface LoadFileOptions {
69
- maxLines?: number;
70
- displayPath?: string;
71
- }
72
- export declare function loadFileKindAndText(filePath: string, options?: LoadFileOptions): Promise<LFile>;
73
- export declare function valAccess(absolutePath: string, path: string, accessMode?: number): Promise<void>;
74
- export declare function valKind(file: LFile, path: string): asserts file is {
75
- kind: "text";
76
- text: string;
77
- hadUtf8DecodeErrors?: true;
78
- };
79
51
  export interface NormFile {
80
52
  absolutePath: string;
81
53
  normalized: string;
@@ -92,21 +64,6 @@ export type SnapInfo = {
92
64
  size: number;
93
65
  };
94
66
  export declare function fileSnap(absolutePath: string, preloadedStats?: FileStats): Promise<SnapInfo>;
95
- export interface ReadNormOptions {
96
- signal?: AbortSignal;
97
- accessMode?: number;
98
- preloadedFile?: LFile;
99
- maxLines?: number;
100
- store?: HashStore;
101
- noPersist?: boolean;
102
- reservedHashes?: ReadonlySet<string>;
103
- retiredHashes?: ReadonlySet<string>;
104
- previous?: {
105
- content: string;
106
- hashes: string[];
107
- removedHashes?: Set<string>;
108
- };
109
- }
110
67
  export declare function normFromText(input: {
111
68
  absolutePath: string;
112
69
  rawText: string;
@@ -124,7 +81,6 @@ export declare function normFromText(input: {
124
81
  removedHashes?: Set<string>;
125
82
  };
126
83
  }): Promise<NormFile>;
127
- export declare function readNormFile(path: string, cwd: string, options?: ReadNormOptions): Promise<NormFile>;
128
84
  /** One requested line range of a multi-window read (FU-6, port of pi-better-edit@2334352). */
129
85
  export interface ReadWindow {
130
86
  offset: number;
@@ -159,6 +115,18 @@ export interface FileView {
159
115
  absolutePath: string;
160
116
  truncation?: TruncationResult;
161
117
  nextOffset?: number;
118
+ /**
119
+ * The full-read verdict — computed HERE and nowhere else (ADR-0035).
120
+ *
121
+ * True only for an untruncated whole-file read: no `offset`, no `limit` and no requested windows
122
+ * (`undefined`/`[]` both mean none, per `hasRequestedWindows`), and nothing cut by the render.
123
+ * A page that happens to cover every line is still a page.
124
+ *
125
+ * WHY here: the request shape lives in this seam — the consumers of the verdict (session-view's
126
+ * `recordServed`, read-and-serve's drift clear) see only rows, and any verdict re-derived from
127
+ * rows says "full" for a page whose rows turn out dense.
128
+ */
129
+ fullRead: boolean;
162
130
  hadUtf8DecodeErrors: boolean;
163
131
  bom: string;
164
132
  originalEnding: LineEnding;
@@ -181,10 +149,4 @@ export interface ReadViewOpts extends PreviewOpts {
181
149
  removedHashes?: Set<string>;
182
150
  };
183
151
  }
184
- export declare function preview(content: string, hashes: string[], opts?: PreviewOpts, absolutePath?: string): Promise<{
185
- text: string;
186
- served: ServedRow[];
187
- truncation?: TruncationResult;
188
- nextOffset?: number;
189
- }>;
190
152
  export declare function readView(io: FileIO, path: string, cwd: string, opts?: ReadViewOpts): Promise<FileView>;
@@ -14,11 +14,15 @@
14
14
  * for backwards compat but are marked @internal and should be imported via this
15
15
  * module only.
16
16
  *
17
+ * The served-evidence verdict lives in served-evidence.ts (ADR-0037): this seam
18
+ * calls `verifyServedRange` and owns nothing it decides.
19
+ *
17
20
  * @module dsh-better-edit/hashline/anchor-pipeline
18
21
  */
19
22
  import { DomainError } from "../domain-errors.js";
20
- import type { ErrorPayloadMap, ServedRow, DomainErrorCode, RangeCause } from "../domain-errors.js";
21
- import type { EditMode } from "../contract.js";
23
+ import type { ErrorPayloadMap, DomainErrorCode } from "../domain-errors.js";
24
+ import type { LeaseSpanSource, ResolvedRange } from "./served-evidence.js";
25
+ import type { EditMode } from "../edit-mode.js";
22
26
  export type Anchor = {
23
27
  hash: string;
24
28
  };
@@ -48,27 +52,7 @@ export type HTEdit = {
48
52
  anchor_to: string;
49
53
  };
50
54
  export declare function resEdit(edit: HTEdit, _warnings?: string[]): HEdit;
51
- export type ServedCode = "E_STALE_RANGE" | "E_UNSERVED_RANGE";
52
55
  export type { ServedRow, RangeCause } from "../domain-errors.js";
53
- export declare class ServedRejectionError extends DomainError<DomainErrorCode> {
54
- readonly code: ServedCode;
55
- readonly unservedKind: "boundary" | "interior" | undefined;
56
- constructor(opts: {
57
- code: "E_STALE_RANGE";
58
- headline: string;
59
- servedRows: ServedRow[];
60
- servedBlock: string;
61
- cause?: RangeCause;
62
- firstOffendingLine?: number;
63
- } | {
64
- code: "E_UNSERVED_RANGE";
65
- headline: string;
66
- servedRows: ServedRow[];
67
- servedBlock: string;
68
- unservedKind: "boundary" | "interior";
69
- firstOffendingLine?: number;
70
- });
71
- }
72
56
  export declare class AnchorMismatchError extends DomainError<DomainErrorCode> {
73
57
  constructor(code: "E_STALE_ANCHOR" | "E_SUSPICIOUS_TEXT", payload: ErrorPayloadMap[typeof code]);
74
58
  }
@@ -87,112 +71,6 @@ export declare function findEditHashEcho(replacementLines: string[], served: rea
87
71
  export declare class EditHashEchoError extends AnchorMismatchError {
88
72
  constructor(payload: ErrorPayloadMap["E_SUSPICIOUS_TEXT"]);
89
73
  }
90
- export declare function buildRangeEcho(startLine: number, endLine: number, fileHashes: string[]): ServedRow[];
91
- export declare function fmtServedRows(rows: ServedRow[], fileLines: string[]): string;
92
- /**
93
- * SAFETY: the read-only identity seam the edit path resolves a served anchor through (CP2-r1,
94
- * obligation (c)). Production wires it to `served_leases` + `line_lineage`; tests inject plain
95
- * maps. Nothing here writes: the authoritative `retired_at` writer is materialization.
96
- */
97
- export interface LeaseIdentityView {
98
- lineId: number;
99
- servedLineNumber: number;
100
- servedSnapshotHash: string;
101
- retiredAt: number | null;
102
- }
103
- /**
104
- * The lease source a served span is verified against when identity is available.
105
- * `leaseFor` is a per-anchor lookup; `rebasedLineOf` answers where a leased `line_id` lives in the
106
- * buffer being edited (the store's `positionsByIdentity`).
107
- */
108
- export interface LeaseSpanSource {
109
- leaseFor(anchor: string): LeaseIdentityView | undefined;
110
- rebasedLineOf(lineId: number): number | undefined;
111
- /**
112
- * Other files this session served one anchor for, excluding the file being edited.
113
- * Backed by the store's `(session_id, anchor)` lookup; it runs on the failure path only,
114
- * so the happy path pays nothing (upstream b92e0ec:src/hashline/resolve.ts:41-49).
115
- */
116
- anchorHomes(anchor: string): string[];
117
- }
118
- /**
119
- * The served-evidence route: which evidence owns verification of a served span. Constructed
120
- * EXACTLY ONCE per `verifyServedRange` call from the opt-in `leaseSource` seam, so the
121
- * leased/mirror conjunction — boundary interception, never-served interior scan, identity-gate
122
- * route, position-check null handling, and the gate's interior-hole rule — is one value's
123
- * decisions instead of five comment-enforced presence-tests.
124
- *
125
- * The union answers exactly three questions (below): `owesInteriorScan`, `acceptsInteriorHole`
126
- * and `checksPosition`. The `kind` discriminator itself routes the boundary interception and
127
- * the identity gate (obligation (c)).
128
- */
129
- export type ServedEvidenceRoute = {
130
- kind: "leased";
131
- source: LeaseSpanSource;
132
- } | {
133
- kind: "mirror";
134
- };
135
- /**
136
- * The identity gate for a served span (obligation (c)) — replaces the unconditional position check
137
- * when a lease source is present.
138
- *
139
- * A **benign shift** — the intended line's bytes are unchanged and only its position moved (exterior
140
- * drift above the served span) — passes: the served anchor's live lease resolves to the rebased
141
- * coordinate the edit targets, so the edit applies there with no re-read. A **look-alike rebind** —
142
- * the named line was deleted and a different line now holds the same bytes — rejects: the leased
143
- * `line_id` no longer lives at the rebased coordinate, or is gone from the buffer's identity map
144
- * entirely, so the anchor cannot be reconciled with the line it named.
145
- *
146
- * Fail-closed arms, all `E_STALE_RANGE` with the echo rows: a window length that changed because
147
- * an external insert/delete landed strictly inside the span, a truncated mirror slot (no served row
148
- * left to reconcile), a never-served boundary row (the named anchor itself, unverifiable without a
149
- * served row), an unleased served row (a serve predating lease granting), a retired lease, or a
150
- * coordinate no leased identity occupies. An interior mirror row the span never served (`null`) is
151
- * accepted (upstream ADR-0024 decision 1, adopted; supersedes ADR-0019's decline): it carries no
152
- * identity to verify and the two boundary leases plus the window-length check pin the span's extent.
153
- * Throwing happens before any write, so a rejection leaves the file byte-identical.
154
- */
155
- export declare function verifyRebasedSpan(args: {
156
- served: (string | null)[];
157
- servedStart: number;
158
- servedEnd: number;
159
- rebasedStart: number;
160
- rebasedEnd: number;
161
- /** The leased evidence route — this gate is what the leased kind owns. */
162
- route: Extract<ServedEvidenceRoute, {
163
- kind: "leased";
164
- }>;
165
- echo: string;
166
- echoRows: ServedRow[];
167
- where: string;
168
- }): void;
169
- export declare function verifyServedRange(args: {
170
- served: (string | null)[];
171
- startHash: string;
172
- endHash: string;
173
- startLine: number;
174
- endLine: number;
175
- fileHashes: string[];
176
- fileLines: string[];
177
- filePath?: string;
178
- servedCanons?: (string | null)[];
179
- retired?: ReadonlySet<string>;
180
- /**
181
- * Present => the leased evidence route (identity gate `verifyRebasedSpan` replaces the position
182
- * check below, obligation (c)); absent => the mirror route with its unconditional position
183
- * check. Identity only, never a weaker position check. Turns into the single
184
- * `ServedEvidenceRoute` value at the top of the body — the rest of the function never
185
- * presence-tests this argument.
186
- */
187
- leaseSource?: LeaseSpanSource;
188
- }): void;
189
- export interface ResolvedRange {
190
- startLine: number;
191
- endLine: number;
192
- startHash: string;
193
- endHash: string;
194
- delta: number;
195
- }
196
74
  type LIdx = {
197
75
  fileLines: string[];
198
76
  lineStarts: number[];
@@ -22,6 +22,46 @@ export declare class AnchorSpaceExhaustedError extends DomainError<"E_LARGE_FILE
22
22
  readonly servedCount: number;
23
23
  constructor(retiredCount: number, servedCount: number);
24
24
  }
25
+ /**
26
+ * The ONE anchor-space-exhaustion test, owned by the error's own module: "is this
27
+ * exhaustion?" (a typing question).
28
+ *
29
+ * WHY single: the classification lives beside the error it classifies, and no site keeps a private
30
+ * copy — the two translate blocks below ask exactly this question, and the promotion sites ask its
31
+ * strict subset (`isPromotableAnchorSpaceExhaustion`). Each of the five sites used to carry its own
32
+ * copy (or an inline variant) of the test; a rewording of the allocator's probe message in one copy
33
+ * would silently change a decision at the others, and the failure mode is a raw `Error` reaching
34
+ * the model instead of the typed refusal.
35
+ *
36
+ * Members: the typed `AnchorSpaceExhaustedError` (already translated), the allocator wording
37
+ * `nextZeroBit` raises when the probe wraps the whole space ("probing failed over"), and that
38
+ * same refusal's formatted headline ("Cannot allocate a unique hash anchor", which survives a
39
+ * re-wrap that costs the error its class).
40
+ */
41
+ export declare function isAnchorSpaceExhaustion(e: unknown): boolean;
42
+ /**
43
+ * Promotion's narrower question: is this an exhaustion that clearing retired anchors and
44
+ * retrying could actually cure?
45
+ *
46
+ * WHY a second predicate, not the one above: `isAnchorSpaceExhaustion` answers "is this
47
+ * exhaustion" — a typing question, asked by the two translate blocks that must turn any
48
+ * allocator wording into the typed `E_LARGE_FILE`. Promotion asks a different question, and the
49
+ * two answers differ on every refusal whose subject is the file's line count rather than the
50
+ * anchor space: exhaustion and the line cap are the same diagnosis (a file too long to hash),
51
+ * but promotion cannot out-grow the line cap, because the retry re-reads the same oversized file
52
+ * and throws the identical error — with this `(session, path)`'s retired anchors now cleared, so
53
+ * the failed read has also degraded its own stale-anchor checks. "Can promotion help?" is
54
+ * therefore the strict subset: the probe wrapping the whole space.
55
+ *
56
+ * The line cap is a capacity refusal, never an identity one, and its wording is not the hash-space
57
+ * one: `eLargeFileMsg` formats with `limitKind: "lines"` ("<path> has N lines, exceeding the
58
+ * N-line limit"), so `isAnchorSpaceExhaustion` already declines it; "Cannot allocate a unique hash
59
+ * anchor" is `AnchorSpaceExhaustedError`'s own headline, reachable as message-only text on a
60
+ * re-wrap. Declining both keeps promotion off every refusal a retry cannot out-grow, and leaves
61
+ * the line cap free to be re-formatted through the hash-space wording without promotion silently
62
+ * becoming a hazard-clear.
63
+ */
64
+ export declare function isPromotableAnchorSpaceExhaustion(e: unknown): boolean;
25
65
  export declare function idxToHash(idx: number): string;
26
66
  export declare function hashAt(idx: number): string;
27
67
  export declare const HL_PREFIX_PLUS_RE: RegExp;
@@ -5,9 +5,11 @@
5
5
  */
6
6
  export { CANON_VERSION, ANCHOR_LEN, HASH_SEP, HASH_SPACE, HASH_PROBE_STRIDE, MAX_HASH_LINES, HASH_LEN, HASH_CLASS, HASH_RE, ALPH_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE, HL_BARE_PREFIX_RE, canon, lineHashesPure, mapStableHashes, initHasher, contentChecksum, } from "./hash-assign.js";
7
7
  export { lineHashes } from "./hash.js";
8
- export { parseHashRef, parseText } from "./parse.js";
9
- export type { Anchor } from "./parse.js";
8
+ export { parseHashRef, parseText } from "./anchor-pipeline.js";
9
+ export type { Anchor } from "./anchor-pipeline.js";
10
10
  export { resEdit } from "./anchor-pipeline.js";
11
11
  export type { HEdit, HTEdit, NEdit } from "./anchor-pipeline.js";
12
- export { applyEdit, fmtRegion, changedRange, buildIdx, ServedRejectionError, AnchorMismatchError, EditHashEchoError, findEditHashEcho, isAnchorMismatch, verifyServedRange, verifyRebasedSpan, buildRangeEcho, fmtServedRows, } from "./anchor-pipeline.js";
13
- export type { ServedRow, ResolvedRange, LeaseSpanSource, LeaseIdentityView, } from "./anchor-pipeline.js";
12
+ export { applyEdit, fmtRegion, changedRange, buildIdx, AnchorMismatchError, EditHashEchoError, findEditHashEcho, isAnchorMismatch, } from "./anchor-pipeline.js";
13
+ export type { ServedRow } from "./anchor-pipeline.js";
14
+ export { ServedRejectionError, verifyServedRange, verifyRebasedSpan, buildRangeEcho, fmtServedRows, moreRowsHint, } from "./served-evidence.js";
15
+ export type { ResolvedRange, LeaseSpanSource, LeaseIdentityView } from "./served-evidence.js";
@@ -0,0 +1,152 @@
1
+ /**
2
+ * ServedEvidence — deep module owning what a served range can still prove.
3
+ *
4
+ * One entry point: `verifyServedRange` decides whether the anchor pair an edit
5
+ * names is still grounded in the evidence this session was served, and rejects
6
+ * with the echoed window when it is not. Every other decision here is private to
7
+ * that call — the `ServedEvidenceRoute` union answers its three route questions
8
+ * (`owesInteriorScan`, `acceptsInteriorHole`, `checksPosition`), the leased
9
+ * route's boundary interception loses identity before any content question is
10
+ * asked, and `throwUnknownOrForeign` refuses anchors the lease seam cannot place.
11
+ *
12
+ * `verifyRebasedSpan` is exported because two cells pin the leased route directly;
13
+ * it is not a second entry point. `buildRangeEcho`/`fmtServedRows`/`moreRowsHint`
14
+ * render the echo, and `ResolvedRange` is the shape both sides of the edit path
15
+ * carry, so neither side has to import the other.
16
+ *
17
+ * WHY here: the verifier is read-side evidence, but the write path calls it. Kept
18
+ * in anchor-pipeline it closed a cycle through the served mirror and the request
19
+ * contract; as a leaf (domain registry, hash-assign, constants) it closes none.
20
+ *
21
+ * @module dsh-better-edit/hashline/served-evidence
22
+ */
23
+ import { DomainError } from "../domain-errors.js";
24
+ import type { DomainErrorCode, RangeCause, ServedRow } from "../domain-errors.js";
25
+ export type ServedCode = "E_STALE_RANGE" | "E_UNSERVED_RANGE";
26
+ export declare class ServedRejectionError extends DomainError<DomainErrorCode> {
27
+ readonly code: ServedCode;
28
+ readonly unservedKind: "boundary" | "interior" | undefined;
29
+ constructor(opts: {
30
+ code: "E_STALE_RANGE";
31
+ headline: string;
32
+ servedRows: ServedRow[];
33
+ servedBlock: string;
34
+ cause?: RangeCause;
35
+ firstOffendingLine?: number;
36
+ } | {
37
+ code: "E_UNSERVED_RANGE";
38
+ headline: string;
39
+ servedRows: ServedRow[];
40
+ servedBlock: string;
41
+ unservedKind: "boundary" | "interior";
42
+ firstOffendingLine?: number;
43
+ });
44
+ }
45
+ export declare function servedPositionsOf(served: (string | null)[], hash: string): number[];
46
+ export declare function buildRangeEcho(startLine: number, endLine: number, fileHashes: string[]): ServedRow[];
47
+ export declare function fmtServedRows(rows: ServedRow[], fileLines: string[]): string;
48
+ export declare function moreRowsHint(count: number, tail: string): string;
49
+ /**
50
+ * SAFETY: the read-only identity seam the edit path resolves a served anchor through (CP2-r1,
51
+ * obligation (c)). Production wires it to `served_leases` + `line_lineage`; tests inject plain
52
+ * maps. Nothing here writes: the authoritative `retired_at` writer is materialization.
53
+ */
54
+ export interface LeaseIdentityView {
55
+ lineId: number;
56
+ servedLineNumber: number;
57
+ servedSnapshotHash: string;
58
+ retiredAt: number | null;
59
+ }
60
+ /**
61
+ * The lease source a served span is verified against when identity is available.
62
+ * `leaseFor` is a per-anchor lookup; `rebasedLineOf` answers where a leased `line_id` lives in the
63
+ * buffer being edited (the store's `positionsByIdentity`).
64
+ */
65
+ export interface LeaseSpanSource {
66
+ leaseFor(anchor: string): LeaseIdentityView | undefined;
67
+ rebasedLineOf(lineId: number): number | undefined;
68
+ /**
69
+ * Other files this session served one anchor for, excluding the file being edited.
70
+ * Backed by the store's `(session_id, anchor)` lookup; it runs on the failure path only,
71
+ * so the happy path pays nothing (upstream b92e0ec:src/hashline/resolve.ts:41-49).
72
+ */
73
+ anchorHomes(anchor: string): string[];
74
+ }
75
+ /**
76
+ * The served-evidence route: which evidence owns verification of a served span. Constructed
77
+ * EXACTLY ONCE per `verifyServedRange` call from the opt-in `leaseSource` seam, so the
78
+ * leased/mirror conjunction — boundary interception, never-served interior scan, identity-gate
79
+ * route, position-check null handling, and the gate's interior-hole rule — is one value's
80
+ * decisions instead of five comment-enforced presence-tests.
81
+ *
82
+ * The union answers exactly three questions (below): `owesInteriorScan`, `acceptsInteriorHole`
83
+ * and `checksPosition`. The `kind` discriminator itself routes the boundary interception and
84
+ * the identity gate (obligation (c)).
85
+ */
86
+ export type ServedEvidenceRoute = {
87
+ kind: "leased";
88
+ source: LeaseSpanSource;
89
+ } | {
90
+ kind: "mirror";
91
+ };
92
+ /**
93
+ * The identity gate for a served span (obligation (c)) — replaces the unconditional position check
94
+ * when a lease source is present.
95
+ *
96
+ * A **benign shift** — the intended line's bytes are unchanged and only its position moved (exterior
97
+ * drift above the served span) — passes: the served anchor's live lease resolves to the rebased
98
+ * coordinate the edit targets, so the edit applies there with no re-read. A **look-alike rebind** —
99
+ * the named line was deleted and a different line now holds the same bytes — rejects: the leased
100
+ * `line_id` no longer lives at the rebased coordinate, or is gone from the buffer's identity map
101
+ * entirely, so the anchor cannot be reconciled with the line it named.
102
+ *
103
+ * Fail-closed arms, all `E_STALE_RANGE` with the echo rows: a window length that changed because
104
+ * an external insert/delete landed strictly inside the span, a truncated mirror slot (no served row
105
+ * left to reconcile), a never-served boundary row (the named anchor itself, unverifiable without a
106
+ * served row), an unleased served row (a serve predating lease granting), a retired lease, or a
107
+ * coordinate no leased identity occupies. An interior mirror row the span never served (`null`) is
108
+ * accepted (upstream ADR-0024 decision 1, adopted; supersedes ADR-0019's decline): it carries no
109
+ * identity to verify and the two boundary leases plus the window-length check pin the span's extent.
110
+ * Throwing happens before any write, so a rejection leaves the file byte-identical.
111
+ */
112
+ export declare function verifyRebasedSpan(args: {
113
+ served: (string | null)[];
114
+ servedStart: number;
115
+ servedEnd: number;
116
+ rebasedStart: number;
117
+ rebasedEnd: number;
118
+ /** The leased evidence route — this gate is what the leased kind owns. */
119
+ route: Extract<ServedEvidenceRoute, {
120
+ kind: "leased";
121
+ }>;
122
+ echo: string;
123
+ echoRows: ServedRow[];
124
+ where: string;
125
+ }): void;
126
+ export declare function verifyServedRange(args: {
127
+ served: (string | null)[];
128
+ startHash: string;
129
+ endHash: string;
130
+ startLine: number;
131
+ endLine: number;
132
+ fileHashes: string[];
133
+ fileLines: string[];
134
+ filePath?: string;
135
+ servedCanons?: (string | null)[];
136
+ retired?: ReadonlySet<string>;
137
+ /**
138
+ * Present => the leased evidence route (identity gate `verifyRebasedSpan` replaces the position
139
+ * check below, obligation (c)); absent => the mirror route with its unconditional position
140
+ * check. Identity only, never a weaker position check. Turns into the single
141
+ * `ServedEvidenceRoute` value at the top of the body — the rest of the function never
142
+ * presence-tests this argument.
143
+ */
144
+ leaseSource?: LeaseSpanSource;
145
+ }): void;
146
+ export interface ResolvedRange {
147
+ startLine: number;
148
+ endLine: number;
149
+ startHash: string;
150
+ endHash: string;
151
+ delta: number;
152
+ }
@@ -14,8 +14,10 @@
14
14
  import type { FileIO } from "../fs-bridge.js";
15
15
  import { type HashStore } from "../hash-store.js";
16
16
  import type { LineEnding } from "../edit-diff.js";
17
- import { type HEdit, type NEdit, type LeaseSpanSource } from "../hashline/anchor-pipeline.js";
18
- import { type ResolvedRange, type ServedRow } from "../hashline/anchor-pipeline.js";
17
+ import { type HEdit, type NEdit } from "../hashline/anchor-pipeline.js";
18
+ import type { LeaseSpanSource } from "../hashline/served-evidence.js";
19
+ import type { ResolvedRange } from "../hashline/served-evidence.js";
20
+ import type { ServedRow } from "../hashline/anchor-pipeline.js";
19
21
  import type { EditMode } from "../contract.js";
20
22
  export interface PreparedItem {
21
23
  index: number;