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
@@ -14,8 +14,9 @@
14
14
  * hash-store persistence delegation (ServedPersistence).
15
15
  *
16
16
  * Ownership: This file OWNS the served-merge invariant
17
- * (_mergeServedRows with orphan healing per ADR-0008), the
18
- * position-reconstruction math, and the drift computation. Deleting
17
+ * (_mergeServedRows — exact-write: a hash written at a new position leaves the
18
+ * old slot intact, and a duplicate is rejected at verification rather than
19
+ * healed), the position-reconstruction math, and the drift computation. Deleting
19
20
  * it would scatter the served+drift invariant across 4 files — it
20
21
  * concentrates (deep).
21
22
  *
@@ -25,14 +26,17 @@ import { HASH_RE, canon } from "./hashline/hash-assign.js";
25
26
  import { loadHashStore, loadServedStore, withStore, } from "./hash-store.js";
26
27
  import { SERVED_ECHO_CAP } from "./constants.js";
27
28
  import { fmtServedRows } from "./hashline/anchor-pipeline.js";
29
+ import { splitLines } from "./utils.js";
28
30
  // --- hash-store re-export (persistence note) ---
29
31
  export { loadHashStore, loadServedStore, shutdownHashStore, withStore } from "./hash-store.js";
30
32
  /**
31
33
  * Merge served rows into a copy of the stored array. This single helper owns
32
34
  * the served-merge invariant shared by recordServed and recordServedTruncated.
33
- * Eagerly heals orphaned serves: if the same hash is written at a new position
34
- * the old position is nulled (O(n) scan, no extra I/O). This prevents a
35
- * partial re-serve from leaving a stale duplicate behind (ADR-0008).
35
+ *
36
+ * Exact-write rule (ADR-0018, superseding ADR-0004): a hash written at a new position
37
+ * leaves the old position INTACT — the old slot is not nulled and no look-alike is
38
+ * rebound. A duplicate is detected at verification time (`verifyServedRange`) and
39
+ * rejects as `E_UNSERVED_RANGE` instead of being healed here.
36
40
  */
37
41
  export function _mergeServedRows(current, rows, options) {
38
42
  const updated = current.slice();
@@ -43,18 +47,6 @@ export function _mergeServedRows(current, rows, options) {
43
47
  for (let i = options.clearFrom; i < updated.length; i++)
44
48
  updated[i] = null;
45
49
  }
46
- // Build index of existing hashes and heal duplicates already in the array
47
- const index = new Map();
48
- for (let i = 0; i < updated.length; i++) {
49
- const h = updated[i];
50
- if (h === null)
51
- continue;
52
- const prev = index.get(h);
53
- if (prev !== undefined) {
54
- updated[prev] = null;
55
- }
56
- index.set(h, i);
57
- }
58
50
  for (const entry of rows) {
59
51
  if (!Number.isInteger(entry.position) || entry.position < 0) {
60
52
  throw new TypeError(`Invalid served position: ${entry.position}`);
@@ -64,23 +56,6 @@ export function _mergeServedRows(current, rows, options) {
64
56
  }
65
57
  while (updated.length <= entry.position)
66
58
  updated.push(null);
67
- if (entry.hash !== null) {
68
- const existing = index.get(entry.hash);
69
- if (existing !== undefined && existing !== entry.position) {
70
- updated[existing] = null;
71
- index.delete(entry.hash);
72
- }
73
- const oldAtPos = updated[entry.position];
74
- if (oldAtPos !== null && oldAtPos !== entry.hash) {
75
- index.delete(oldAtPos);
76
- }
77
- index.set(entry.hash, entry.position);
78
- }
79
- else {
80
- const oldAtPos = updated[entry.position];
81
- if (oldAtPos !== null)
82
- index.delete(oldAtPos);
83
- }
84
59
  updated[entry.position] = entry.hash;
85
60
  }
86
61
  while (updated.length > 0 && updated[updated.length - 1] === null)
@@ -100,10 +75,6 @@ export async function loadServedCanons(sessionKey, path) {
100
75
  const store = await loadServedStore();
101
76
  return store.getServedCanons(sessionKey, path);
102
77
  }
103
- export async function loadEpochSnapshotId(sessionKey, path) {
104
- const store = await loadServedStore();
105
- return store.getEpochSnapshotId(sessionKey, path);
106
- }
107
78
  export async function loadRetiredAnchors(sessionKey, path) {
108
79
  const store = await loadServedStore();
109
80
  return store.getRetiredAnchors(sessionKey, path);
@@ -197,9 +168,36 @@ export async function retireAnchors(sessionKey, path, hashes) {
197
168
  addRetiredAnchors(store, sessionKey, path, additions);
198
169
  });
199
170
  }
171
+ /**
172
+ * Funnel for lease granting: materialize-or-adopt the serve snapshot and grant
173
+ * leases for the served rows as-is. Caller-owned transaction: this must run
174
+ * INSIDE the `withStore` unit that wrote the `served` row it derives from, so a
175
+ * lease fault rolls the pair back instead of splitting it.
176
+ * Fail closed: no content/hashes (or a length mismatch) grants nothing and
177
+ * throws nothing — the served-state write in the same unit still commits.
178
+ */
179
+ function grantServeLeases(store, sessionKey, path, rows, hashes, content) {
180
+ if (content === undefined || hashes === undefined)
181
+ return;
182
+ if (splitLines(content).length !== hashes.length)
183
+ return;
184
+ // SAFETY: loadServedStore returns the makeDomainStore object, which implements
185
+ // InternalHashStore; ServedPersistence is its narrowed public view.
186
+ const internal = store;
187
+ internal.commitSnapshot({ path, content, hashes: [...hashes], leases: { sessionKey, rows } });
188
+ }
189
+ /**
190
+ * Record a serve — the `served` row merge and the lease grant derived from it — as ONE unit, and
191
+ * report whether it landed.
192
+ *
193
+ * `false` means the write rolled back and no lease was granted, so the caller must not advertise
194
+ * the rows' anchors as usable: that is a partial failure of the caller's operation, not a failed
195
+ * operation. The best-effort contract is unchanged — this never throws.
196
+ */
200
197
  export async function recordServed(sessionKey, path, rows, lineCount, full) {
198
+ // Nothing to record, so nothing can fail: vacuously landed.
201
199
  if (rows.length === 0)
202
- return;
200
+ return true;
203
201
  try {
204
202
  const store = await loadServedStore();
205
203
  const isFullRead = full !== undefined &&
@@ -216,8 +214,6 @@ export async function recordServed(sessionKey, path, rows, lineCount, full) {
216
214
  store.clearCards(sessionKey, path);
217
215
  if (full?.canons)
218
216
  store.upsertServedCanons(sessionKey, path, JSON.stringify(full.canons));
219
- if (full?.snapshotId)
220
- store.upsertEpochSnapshotId(sessionKey, path, full.snapshotId);
221
217
  }
222
218
  else {
223
219
  // For partial reads, update canons for the served rows via hash-to-canon map (robust for partial views)
@@ -245,15 +241,29 @@ export async function recordServed(sessionKey, path, rows, lineCount, full) {
245
241
  }
246
242
  sweepAndRetire(store, sessionKey, path, current, updated, rows);
247
243
  }
244
+ // Pair #6: the lease grant and the `served` row it derives from are ONE unit.
245
+ grantServeLeases(store, sessionKey, path, rows, full?.hashes, full?.content);
248
246
  });
247
+ return true;
249
248
  }
250
249
  catch (error) {
251
250
  console.error("Failed to record served rows:", error);
251
+ return false;
252
252
  }
253
253
  }
254
- export async function recordServedTruncated(sessionKey, path, rows, lineCount, clearFrom = 0, fullCanons) {
254
+ /**
255
+ * Record a truncated serve — the `served` row merge and the lease grant derived from it — as ONE
256
+ * unit, and report whether it landed.
257
+ *
258
+ * `false` means the write rolled back and no lease was granted, so the caller must not advertise
259
+ * the rows' anchors as usable: that is a partial failure of the caller's operation, not a failed
260
+ * operation. The best-effort contract is unchanged — this never throws; the callers decide what
261
+ * to advertise.
262
+ */
263
+ export async function recordServedTruncated(sessionKey, path, rows, lineCount, clearFrom = 0, fullCanons, serveSnapshot) {
264
+ // Nothing to record, so nothing can fail: vacuously landed.
255
265
  if (rows.length === 0)
256
- return;
266
+ return true;
257
267
  try {
258
268
  const store = await loadServedStore();
259
269
  withStore(() => {
@@ -282,10 +292,14 @@ export async function recordServedTruncated(sessionKey, path, rows, lineCount, c
282
292
  store.upsertServedCanons(sessionKey, path, JSON.stringify(updatedCanons));
283
293
  }
284
294
  sweepAndRetire(store, sessionKey, path, current, updated, rows);
295
+ // Pair #6: the lease grant and the `served` row it derives from are ONE unit.
296
+ grantServeLeases(store, sessionKey, path, rows, serveSnapshot?.hashes, serveSnapshot?.content);
285
297
  });
298
+ return true;
286
299
  }
287
300
  catch (error) {
288
301
  console.error("Failed to record truncated served rows:", error);
302
+ return false;
289
303
  }
290
304
  }
291
305
  export async function driftReported(sessionKey, path) {
@@ -0,0 +1,97 @@
1
+ /**
2
+ * The `snapshots` table's sole owner: storage detail (SQL, row encoding,
3
+ * hash validation, busy-retry) hides behind a narrow domain interface.
4
+ *
5
+ * Read-order contract: `get` returns hashes in line order (index *i* ↔ line
6
+ * *i* + 1). Storage is a line-ordered JSON array by construction; this module
7
+ * never sorts, reverses or otherwise reorders it — a normalized read must
8
+ * preserve the same contract (e.g. `ORDER BY line_number ASC`).
9
+ * The retention surface (`vacuum.ts`) is re-exported here so consumers never reach into the
10
+ * eviction module directly. See also `./vacuum.js` for the policy constants.
11
+ * @module dsh-better-edit/snapshot-store
12
+ */
13
+ import { DatabaseSync } from "node:sqlite";
14
+ import { contentChecksum, HASH_RE, CANON_VERSION } from "../hashline/hash-assign.js";
15
+ import { splitLines } from "../utils.js";
16
+ import { withBusyRetry } from "../store-retry.js";
17
+ export function isValidHashList(value) {
18
+ if (!Array.isArray(value))
19
+ return false;
20
+ for (const hash of value) {
21
+ if (typeof hash !== "string" || !HASH_RE.test(hash))
22
+ return false;
23
+ }
24
+ return true;
25
+ }
26
+ function cacheKey(checksum) {
27
+ return `${CANON_VERSION}:${checksum}`;
28
+ }
29
+ export function createSnapshotStore(db) {
30
+ const getStmt = db.prepare("SELECT hashes FROM snapshots WHERE path = ? AND checksum = ? AND line_count = ?");
31
+ const allHashesStmt = db.prepare("SELECT path, hashes FROM snapshots");
32
+ const delStmt = db.prepare("DELETE FROM snapshots WHERE path = ?");
33
+ const upsertStmt = db.prepare("INSERT INTO snapshots (path, checksum, line_count, hashes, updated_at) VALUES (?, ?, ?, ?, ?) " +
34
+ "ON CONFLICT(path) DO UPDATE SET checksum = excluded.checksum, line_count = excluded.line_count, hashes = excluded.hashes, updated_at = excluded.updated_at");
35
+ return {
36
+ get(path, content, deleteCorrupt = true) {
37
+ const checksum = cacheKey(contentChecksum(content));
38
+ const lineCount = splitLines(content).length;
39
+ const row = getStmt.get(path, checksum, lineCount);
40
+ if (!row)
41
+ return undefined;
42
+ try {
43
+ const parsed = JSON.parse(row.hashes);
44
+ if (isValidHashList(parsed))
45
+ return parsed;
46
+ if (deleteCorrupt) {
47
+ withBusyRetry(() => {
48
+ delStmt.run(path);
49
+ });
50
+ }
51
+ return undefined;
52
+ }
53
+ catch (error) {
54
+ if (deleteCorrupt) {
55
+ withBusyRetry(() => {
56
+ delStmt.run(path);
57
+ });
58
+ }
59
+ return undefined;
60
+ }
61
+ },
62
+ upsert(path, checksum, lineCount, hashes) {
63
+ withBusyRetry(() => {
64
+ upsertStmt.run(path, cacheKey(checksum), lineCount, JSON.stringify(hashes), Date.now());
65
+ });
66
+ },
67
+ allHashes() {
68
+ return allHashesStmt.all();
69
+ },
70
+ deleteByPath(path) {
71
+ withBusyRetry(() => {
72
+ delStmt.run(path);
73
+ });
74
+ },
75
+ findPathsContaining(hashes) {
76
+ const rows = allHashesStmt.all();
77
+ const matches = [];
78
+ for (const row of rows) {
79
+ try {
80
+ const parsed = JSON.parse(row.hashes);
81
+ if (!isValidHashList(parsed))
82
+ continue;
83
+ if (hashes.every((h) => parsed.includes(h)))
84
+ matches.push(row.path);
85
+ }
86
+ catch (error) {
87
+ console.warn(error); // unparseable row → skip it
88
+ }
89
+ }
90
+ return matches;
91
+ },
92
+ };
93
+ }
94
+ // WHY: the vacuum budgets are the store's retention policy constants, so the module entry keeps
95
+ // them on the public surface; consumers must never reach into the eviction module directly.
96
+ export { reportVacuum, vacuumSnapshots } from "./vacuum.js";
97
+ export { VACUUM_GLOBAL_BUDGET_BYTES, VACUUM_SOFT_OVERFLOW_BYTES, VACUUM_PER_PATH_BUDGET_BYTES, VACUUM_MAX_SNAPSHOTS_PER_PATH, VACUUM_MIN_SNAPSHOTS_PER_PATH, VACUUM_LINEAGE_BYTES_PER_LINE, VACUUM_RETIRED_PIN_MS, REPORT_CONTEXT_CAP, } from "./vacuum.js";