@awebai/oats 0.61.0 → 0.63.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 (90) hide show
  1. package/README.md +1 -1
  2. package/bin/oats.mjs +27 -12
  3. package/docs/capabilities.md +1 -1
  4. package/docs/desktop-cli-api.md +30 -2
  5. package/docs/execution-targets.md +89 -4
  6. package/docs/implementation.md +2 -1
  7. package/docs/named-test-runs.md +382 -0
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-lane.md +13 -0
  11. package/docs/release-notes/v0.62.0.md +223 -0
  12. package/docs/release-notes/v0.63.0.md +135 -0
  13. package/docs/souls-and-instances.md +6 -1
  14. package/docs/upgrading.md +135 -11
  15. package/docs/workspaces.md +1 -1
  16. package/lib/core.mjs +73 -23
  17. package/lib/doctor-capture.mjs +35 -0
  18. package/lib/session-viewer.mjs +86 -7
  19. package/lib/tree-copy.mjs +188 -7
  20. package/package-catalog.json +1 -1
  21. package/package.json +1 -1
  22. package/packages/client/cli-locator.mjs +2 -2
  23. package/packages/record/README.md +87 -13
  24. package/packages/record/bin/capture-hook.mjs +8 -0
  25. package/packages/record/bin/capture.mjs +200 -139
  26. package/packages/record/bin/recall.mjs +8 -3
  27. package/packages/record/bin/setup.mjs +116 -225
  28. package/packages/record/bin/turn-record.mjs +2 -2
  29. package/packages/record/docs/capture-service.md +1527 -28
  30. package/packages/record/docs/capture-status.schema.json +429 -12
  31. package/packages/record/lib/capture-admission.mjs +82 -0
  32. package/packages/record/lib/capture-aw-unit.mjs +137 -0
  33. package/packages/record/lib/capture-aw.mjs +31 -12
  34. package/packages/record/lib/capture-budget.mjs +31 -0
  35. package/packages/record/lib/capture-cc.mjs +39 -6
  36. package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
  37. package/packages/record/lib/capture-cleanup-work.mjs +77 -0
  38. package/packages/record/lib/capture-command-operation.mjs +37 -0
  39. package/packages/record/lib/capture-command-output.mjs +62 -0
  40. package/packages/record/lib/capture-command-worker.mjs +6 -0
  41. package/packages/record/lib/capture-command.mjs +65 -0
  42. package/packages/record/lib/capture-completion.mjs +152 -0
  43. package/packages/record/lib/capture-context.mjs +50 -0
  44. package/packages/record/lib/capture-default-roots.mjs +30 -0
  45. package/packages/record/lib/capture-discovery.mjs +114 -0
  46. package/packages/record/lib/capture-failures.mjs +45 -0
  47. package/packages/record/lib/capture-health-doctor.mjs +13 -0
  48. package/packages/record/lib/capture-health-installation.mjs +117 -0
  49. package/packages/record/lib/capture-health.mjs +116 -0
  50. package/packages/record/lib/capture-hook-ownership.mjs +58 -0
  51. package/packages/record/lib/capture-hook-runner.mjs +17 -0
  52. package/packages/record/lib/capture-hook.mjs +26 -0
  53. package/packages/record/lib/capture-index-inventory.mjs +205 -0
  54. package/packages/record/lib/capture-index-outcomes.mjs +113 -0
  55. package/packages/record/lib/capture-index-reset.mjs +110 -0
  56. package/packages/record/lib/capture-index-work.mjs +77 -0
  57. package/packages/record/lib/capture-issue-preparation.mjs +73 -0
  58. package/packages/record/lib/capture-issues.mjs +15 -2
  59. package/packages/record/lib/capture-lock.mjs +137 -17
  60. package/packages/record/lib/capture-native-unit.mjs +322 -0
  61. package/packages/record/lib/capture-pass.mjs +116 -0
  62. package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
  63. package/packages/record/lib/capture-retained-scratch.mjs +213 -0
  64. package/packages/record/lib/capture-retry.mjs +102 -0
  65. package/packages/record/lib/capture-run.mjs +125 -0
  66. package/packages/record/lib/capture-scratch.mjs +12 -3
  67. package/packages/record/lib/capture-service-definition.mjs +104 -0
  68. package/packages/record/lib/capture-service-install.mjs +362 -0
  69. package/packages/record/lib/capture-service-ownership.mjs +137 -0
  70. package/packages/record/lib/capture-service-runner.mjs +18 -0
  71. package/packages/record/lib/capture-small-snapshot.mjs +85 -0
  72. package/packages/record/lib/capture-source-discovery.mjs +319 -0
  73. package/packages/record/lib/capture-source-queue.mjs +199 -0
  74. package/packages/record/lib/capture-source-work.mjs +85 -0
  75. package/packages/record/lib/capture-state.mjs +16 -71
  76. package/packages/record/lib/capture-status.mjs +171 -0
  77. package/packages/record/lib/capture-supervisor.mjs +136 -0
  78. package/packages/record/lib/capture-watch.mjs +32 -0
  79. package/packages/record/lib/capture-work-session.mjs +241 -0
  80. package/packages/record/lib/capture-worker.mjs +74 -0
  81. package/packages/record/lib/derived-state.mjs +58 -17
  82. package/packages/record/lib/file-lines.mjs +22 -6
  83. package/packages/record/lib/formats.mjs +4 -3
  84. package/packages/record/lib/index-capture.mjs +97 -0
  85. package/packages/record/lib/index-db.mjs +121 -66
  86. package/packages/record/lib/index-reset.mjs +19 -0
  87. package/packages/record/lib/store.mjs +46 -14
  88. package/packages/record/lib/transcript-prefix.mjs +125 -0
  89. package/skills/oats-getting-started/SKILL.md +1 -1
  90. package/docs/macos-test-runs.md +0 -246
@@ -0,0 +1,322 @@
1
+ // Private bounded native command work. Public captureSessions and exact
2
+ // receipts retain their synchronous complete-pass contracts. The scheduler
3
+ // supplies a stream lock/transaction and advances to another input after this
4
+ // unit; a partial result is never a completed sweep.
5
+ import { closeSync, constants, fstatSync, openSync } from "node:fs";
6
+ import { basename } from "node:path";
7
+ import { randomUUID } from "node:crypto";
8
+ import { captureContext } from "./capture-context.mjs";
9
+ import { CAPTURE_POLICY } from "./capture-budget.mjs";
10
+ import { completeNativeLineDigests, completeNativeLines, eventTurnCore } from "./capture-cc.mjs";
11
+ import { finishTurn } from "./canonical.mjs";
12
+ import { SESSION_FORMATS } from "./formats.mjs";
13
+ import { loadIgnore } from "./ignore.mjs";
14
+ import { fileVersion, sameVersion, statVersion } from "./derived-state.mjs";
15
+ import { assertProtectedDescriptor, digest, sourceChunks } from "./session-snapshot.mjs";
16
+ import { guardCapturedPath } from "./native-history.mjs";
17
+ import { RecordSizeError } from "./file-lines.mjs";
18
+ import { advanceRecoverySnapshot } from "./capture-recovery-snapshot.mjs";
19
+ import { advanceTranscriptPrefix } from "./transcript-prefix.mjs";
20
+ import { prepareRetainedCaptureCleanup } from "./capture-retained-scratch.mjs";
21
+ import { smallCommandSnapshot, SMALL_SNAPSHOT_BYTES } from "./capture-small-snapshot.mjs";
22
+
23
+ const nonnegative = n => Number.isSafeInteger(n) && n >= 0;
24
+ const validCursor = (value, size) => value && nonnegative(value.bytes) && value.bytes <= size &&
25
+ nonnegative(value.line) && typeof value.lastTs === "string";
26
+
27
+ export function captureNativeUnit(store, { owner, path, format = "cc", capturedPi, ignore,
28
+ start, maxRecords = 2000, maxBytes = 8388608, maxRecordBytes = CAPTURE_POLICY.maxRecordBytes,
29
+ stopped = () => false, work } = {}) {
30
+ const fmt = SESSION_FORMATS[format];
31
+ if (!fmt) throw new Error("unknown native command format");
32
+ const sessionId = fmt.sessionId(path), stream = `${owner}~${fmt.source}.${sessionId}`, key = `${stream}:${path}`;
33
+ const context = captureContext(store), state = context?.state;
34
+ if (!state?.depth || !context.held.has(stream)) throw new Error("native command unit requires its stream work group");
35
+ if (!Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 2000 ||
36
+ !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > context.batchBytes ||
37
+ !Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 1 || maxRecordBytes > CAPTURE_POLICY.maxRecordBytes) {
38
+ throw new Error("invalid native command unit budget");
39
+ }
40
+ const result = { stream, key, appended: 0, bytesCommitted: 0, complete: false, pending: false };
41
+ if ((ignore ?? loadIgnore(store.root)).ignores(path, [basename(path), sessionId, ...(fmt.ignoreKeys?.(path) ?? [])])) {
42
+ state.delete("set-aside", key);
43
+ // Ignore is evaluated before custody/source access. An extant retained
44
+ // allocation is housekeeping, not authority to reopen an excluded source.
45
+ return { ...result, complete: true, ignored: true };
46
+ }
47
+ const blocked = state.get("set-aside", key);
48
+ if (blocked && !blocked.retry) return { ...result, setAside: blocked };
49
+ if (capturedPi && fmt.source !== "pi") throw new Error("protected capture proof requires pi format");
50
+ guardCapturedPath(path, capturedPi);
51
+ const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | (capturedPi ? constants.O_NOFOLLOW : 0));
52
+ let staged;
53
+ const stagedChunks = function* (from, end) {
54
+ for (const bytes of staged.snapshot.chunks(from, end)) {
55
+ if (work) work.stagedReadBytes = (work.stagedReadBytes ?? 0) + bytes.length;
56
+ yield bytes;
57
+ }
58
+ };
59
+ const stagedWitness = offset => {
60
+ if (work) work.stagedProbeBytes = (work.stagedProbeBytes ?? 0) + Math.min(4096, offset);
61
+ return digest(Buffer.concat([...staged.snapshot.chunks(Math.max(0, offset - 4096), offset)]));
62
+ };
63
+ try {
64
+ const observe = () => {
65
+ assertProtectedDescriptor(fd, path, capturedPi);
66
+ if (!fstatSync(fd).isFile()) throw new Error("native source is not a regular file");
67
+ const value = statVersion(fstatSync(fd, { bigint: true }));
68
+ if (!sameVersion(value, fileVersion(path))) throw new Error("native source descriptor differs from its named file");
69
+ return value;
70
+ };
71
+ const version = observe();
72
+ const chunks = function* (from, end) {
73
+ for (const bytes of sourceChunks(fd, from, end, path, capturedPi)) {
74
+ // Sampling between reads does not turn an incomplete line into a
75
+ // checkpoint. The outer unit stops at a complete-record boundary.
76
+ stopped();
77
+ if (work) work.sourceBytes = (work.sourceBytes ?? 0) + bytes.length;
78
+ yield bytes;
79
+ }
80
+ };
81
+ const witness = (from, read = chunks) => digest(Buffer.concat([...read(Math.max(0, from - 4096), from)]));
82
+ const probe = offset => {
83
+ const read = function* (from, end) {
84
+ for (const bytes of sourceChunks(fd, from, end, path, capturedPi)) {
85
+ if (work) work.sourceProbeBytes = (work.sourceProbeBytes ?? 0) + bytes.length;
86
+ yield bytes;
87
+ }
88
+ };
89
+ return witness(offset, read);
90
+ };
91
+ const generation = JSON.stringify([state.get("reset", `${owner}:${fmt.source}`) ?? "", state.get("source-retry", key) ?? ""]);
92
+ // Ordinary public cursors use the reset value directly. Command cursors
93
+ // retain it too; the private job additionally binds an explicit retry.
94
+ const reset = state.get("reset", `${owner}:${fmt.source}`) ?? "";
95
+ const journalVersion = fileVersion(store.journalPath(stream));
96
+ let cursor = state.get(fmt.source, key);
97
+ const matchesSource = value => value?.version && (sameVersion(value.version, version) ||
98
+ value.version.dev === version.dev && value.version.ino === version.ino && version.size > value.version.size &&
99
+ value.bytes <= version.size && probe(value.bytes) === value.witness);
100
+ let job = state.get("native-unit", key);
101
+ const jobValid = job && job.generation === generation && sameVersion(job.journalVersion, journalVersion) &&
102
+ validCursor(job, version.size) && nonnegative(job.end) && job.bytes <= job.end && job.end <= version.size &&
103
+ matchesSource(job);
104
+ if (!jobValid) { state.delete("native-unit", key); job = null; }
105
+ const cursorValid = validCursor(cursor, version.size) && cursor.generation === reset &&
106
+ sameVersion(cursor.journalVersion, journalVersion) && matchesSource(cursor) && !blocked;
107
+ const recover = !job && !cursorValid && (journalVersion?.size ?? 0) > 0;
108
+ const allocation = state.get("recovery-allocation", key);
109
+ if (allocation?.phase === "deleting") {
110
+ prepareRetainedCaptureCleanup(store, stream, key, start);
111
+ return { ...result, cleanup: true, phase: "cleanup" };
112
+ }
113
+ if (job?.waiting && job.end === version.size && sameVersion(job.version, version)) {
114
+ return { ...result, pending: true, phase: job.scan ? "timestamp" : "capture", reason: job.waiting };
115
+ }
116
+ if (!job && !allocation && cursorValid && cursor.bytes === version.size) {
117
+ return { ...result, complete: true, unchanged: true, phase: "captured" };
118
+ }
119
+ // Journal validation can itself need several units. Never let appendBatch
120
+ // fall back to an unbounded validation inside the first source append.
121
+ const validated = store.validateJournal(stream, state, { maxRecords, maxBytes, stopped, work: work?.journal });
122
+ if (!validated.complete) return { ...result, phase: "journal" };
123
+ const unitWitness = probe(version.size);
124
+ let read = chunks, verify = () => {
125
+ const after = observe();
126
+ if (!sameVersion(version, after) && !(version.dev === after.dev && version.ino === after.ino &&
127
+ after.size > version.size && probe(version.size) === unitWitness)) throw new Error("native source changed during unit");
128
+ };
129
+ if (recover || allocation || job?.snapshot) {
130
+ let small = state.get("small-stage", key);
131
+ if (!small || small.generation !== generation || !sameVersion(small.journalVersion, journalVersion) ||
132
+ !nonnegative(small.size) || small.size > SMALL_SNAPSHOT_BYTES || small.size > version.size ||
133
+ typeof small.id !== "string" || !matchesSource({ ...small, bytes: small.size })) small = null;
134
+ const end = job?.end ?? small?.size ?? version.size;
135
+ // A killed unit has durable admission/retry evidence but cannot have
136
+ // published an in-memory small-copy outcome. Its next due single-stream
137
+ // retry uses retained copying rather than repeating that overhead forever.
138
+ const retain = allocation || state.get("native-retain", key) || context.admission?.retry || end > SMALL_SNAPSHOT_BYTES;
139
+ if (retain) {
140
+ staged = advanceRecoverySnapshot(store, stream, key, path, start, { capturedPi, generation, fixedEnd: end, maxBytes, stopped, work });
141
+ } else {
142
+ // This observation fixes the sweep end even if copying cannot finish.
143
+ // It is NOT a digest/proof checkpoint: reuse below always requires a
144
+ // complete fresh copy/hash before advanceTranscriptPrefix sees its id.
145
+ small ??= { id: randomUUID(), size: end };
146
+ small = { ...small, generation, journalVersion, version, witness: probe(end) };
147
+ state.set("small-stage", key, small);
148
+ staged = smallCommandSnapshot(store.root, fd, path, end, { capturedPi, stopped, work });
149
+ if (staged.complete) {
150
+ // The nonce binds source observation/reset history; digest+size bind
151
+ // bytes. Equal content under a changed identity still restarts proof.
152
+ staged.snapshot.id = `${small.id}:${staged.snapshot.id}`;
153
+ }
154
+ if (!staged.complete || stopped()) {
155
+ state.set("native-retain", key, true);
156
+ state.delete("native-unit", key);
157
+ return { ...result, phase: "snapshot", retainedFallback: true };
158
+ }
159
+ }
160
+ if (!staged.complete) {
161
+ if (staged.cleanup) state.delete("native-unit", key);
162
+ return { ...result, ...staged, phase: staged.phase ?? "snapshot" };
163
+ }
164
+ if (!job || job.snapshot !== staged.snapshot.id) {
165
+ const priorProof = state.get("prefix-proof", key);
166
+ // The captured prefix is proved by streamed per-line digests, so a
167
+ // record captured before the raw-record limit existed is compared, not
168
+ // refused. The limit applies to capture beyond the proven prefix.
169
+ const proof = advanceTranscriptPrefix(store, stream, { key, snapshot: staged.snapshot, maxRecords, maxBytes, stopped,
170
+ work: work?.prefix, lines: from => completeNativeLineDigests(stagedChunks(from), {}) });
171
+ staged.verify();
172
+ if (proof.conflict) {
173
+ // Journals preserve session/line, not the path that first supplied
174
+ // those bytes. A mismatch can also be a rewrite of this same file;
175
+ // neither a cursor nor today's discovery proves a second source.
176
+ const reason = `${proof.conflict.reason}: refused input ${JSON.stringify(path)} conflicts with stream ${JSON.stringify(stream)} at native line ${proof.conflict.line}, source byte ${proof.conflict.offset}; establishing source path unavailable`;
177
+ const row = { owner, source: fmt.source, path, ...proof.conflict, reason, retry: false };
178
+ state.set("set-aside", key, row);
179
+ const cleanup = !staged.small;
180
+ staged.close(); staged = null;
181
+ state.delete("native-unit", key); state.delete("small-stage", key);
182
+ if (cleanup) prepareRetainedCaptureCleanup(store, stream, key, start);
183
+ return { ...result, setAside: row, cleanup };
184
+ }
185
+ if (!proof.complete) {
186
+ // A full restage that leaves no allowance for proof progress must not
187
+ // recur indefinitely. One committed switch selects resumable copying.
188
+ if (staged.small && stopped() && priorProof &&
189
+ ["phase", "journalBytes", "bytes", "line"].every(k => proof[k] === priorProof[k])) {
190
+ state.set("native-retain", key, true);
191
+ }
192
+ return { ...result, phase: "prefix" };
193
+ }
194
+ job = { bytes: proof.bytes, line: proof.line, lastTs: proof.lastTs, end: staged.snapshot.size,
195
+ snapshot: staged.snapshot.id, small: Boolean(staged.small), generation, journalVersion, version, witness: stagedWitness(proof.bytes) };
196
+ state.delete("set-aside", key);
197
+ }
198
+ } else if (!job) {
199
+ cursor = cursorValid ? cursor : { bytes: 0, line: 0, lastTs: "" };
200
+ job = { bytes: cursor.bytes, line: cursor.line, lastTs: cursor.lastTs, end: version.size,
201
+ generation, journalVersion, version, witness: probe(cursor.bytes) };
202
+ }
203
+ if (staged) { read = stagedChunks; verify = staged.verify; }
204
+ // A raw record over the limit is set aside at its exact start, after the
205
+ // complete records before it were committed. Later records wait for an
206
+ // edited source or an ignore of the whole input. A staged job's copy and
207
+ // fixed end retire with it; a retry reproves and returns here.
208
+ const setAsideOversized = offset => {
209
+ state.delete("native-unit", key); state.delete("native-retain", key); state.delete("small-stage", key);
210
+ if (job.snapshot && !job.small) {
211
+ staged.close(); staged = null;
212
+ prepareRetainedCaptureCleanup(store, stream, key, start);
213
+ result.cleanup = true;
214
+ }
215
+ const row = { owner, source: fmt.source, path, offset, reason: "record-too-large", retry: false };
216
+ state.set("set-aside", key, row);
217
+ return { ...result, setAside: row };
218
+ };
219
+ if (job.waiting) {
220
+ if (job.end === version.size) return { ...result, pending: true, phase: job.scan ? "timestamp" : "capture", reason: job.waiting };
221
+ if (job.snapshot) {
222
+ staged.close(); staged = null;
223
+ if (!job.small) prepareRetainedCaptureCleanup(store, stream, key, start);
224
+ state.delete("native-unit", key); state.delete("small-stage", key);
225
+ return { ...result, cleanup: !job.small, phase: "cleanup" };
226
+ }
227
+ // An exhausted fixed end was pending, so the next source growth is a
228
+ // new bounded sweep. Keep its timestamp frontier, not its old EOF.
229
+ job.end = version.size; delete job.waiting;
230
+ }
231
+ const checkpoint = () => {
232
+ verify();
233
+ job.version = staged && !staged.small ? state.get("recovery-stage", key).observedVersion : version;
234
+ job.witness = staged ? stagedWitness(job.bytes) : probe(job.bytes);
235
+ job.journalVersion = fileVersion(store.journalPath(stream));
236
+ state.set("native-unit", key, job);
237
+ state.set(fmt.source, key, { bytes: job.bytes, line: job.line, lastTs: job.lastTs,
238
+ version: job.version, witness: job.witness, generation: reset, journalVersion: job.journalVersion });
239
+ if (job.small) {
240
+ state.set("small-stage", key, { ...state.get("small-stage", key), journalVersion: job.journalVersion });
241
+ } else if (job.snapshot) {
242
+ // Only our successful fsynced append under this stream lock can carry
243
+ // the proven fixed snapshot into the next exact journal generation.
244
+ const stage = state.get("recovery-stage", key);
245
+ if (stage?.allocation !== job.snapshot) throw new Error("native unit lost its staged proof");
246
+ state.set("recovery-stage", key, { ...stage, journalVersion: job.journalVersion });
247
+ }
248
+ };
249
+ let used = 0, records = 0;
250
+ const stop = () => records >= maxRecords || used >= maxBytes || stopped();
251
+ const walk = {};
252
+ const lines = from => completeNativeLines(read(from, job.end), walk, { maxBytes: maxRecordBytes });
253
+ let scanStart = job.bytes;
254
+ try {
255
+ if (!job.lastTs && job.bytes < job.end) {
256
+ const scan = job.scan ?? { bytes: job.bytes, line: job.line };
257
+ if (!validCursor({ ...scan, lastTs: "" }, job.end) || scan.bytes < job.bytes) throw new Error("invalid native timestamp scan");
258
+ scanStart = scan.bytes;
259
+ const iterator = lines(scan.bytes);
260
+ try {
261
+ while (!stop()) {
262
+ const next = iterator.next(); if (next.done) break;
263
+ const line = next.value; scan.bytes += line.bytes; scan.line++; used += line.bytes; records++;
264
+ if (line.ts) { job.lastTs = line.ts; delete job.scan; break; }
265
+ }
266
+ } finally { iterator.return(); }
267
+ if (!job.lastTs) {
268
+ job.scan = scan;
269
+ if (scan.bytes === job.end || walk.reason) job.waiting = walk.reason ?? "unstamped";
270
+ checkpoint();
271
+ // No stamp yet is pending, not a successful empty capture. Preserve
272
+ // the scan frontier so later growth does not rescan this prefix.
273
+ return { ...result, phase: "timestamp", pending: scan.bytes === job.end || !!walk.reason, reason: walk.reason ?? "unstamped" };
274
+ }
275
+ }
276
+ // Timestamp search is work too; it cannot be followed by another full
277
+ // batch after exhausting this unit's allowance.
278
+ const turns = [], from = job.bytes, iterator = lines(from);
279
+ scanStart = from;
280
+ let oversized = null;
281
+ try {
282
+ while (!stop()) {
283
+ const next = iterator.next(); if (next.done) break;
284
+ const line = next.value;
285
+ if (turns.length && used + line.bytes > maxBytes) break;
286
+ if (line.ts) job.lastTs = line.ts;
287
+ job.bytes += line.bytes; job.line++; used += line.bytes; records++;
288
+ turns.push(finishTurn(eventTurnCore({ owner, source: fmt.source, sessionId, line: line.text, lineNo: job.line, ts: job.lastTs })));
289
+ }
290
+ } catch (error) {
291
+ if (!(error instanceof RecordSizeError)) throw error;
292
+ // The raw record was rejected before allocation/projection. Every
293
+ // complete stamped line before it is still processable: append and
294
+ // checkpoint them through the ordinary commit below, then set aside.
295
+ oversized = from + error.offset;
296
+ if (oversized !== job.bytes) throw new Error("native oversized record does not follow the consumed lines");
297
+ } finally { iterator.return(); }
298
+ verify();
299
+ if (turns.length) result.appended = store.appendUniqueBatch(stream, turns);
300
+ result.bytesCommitted = job.bytes - from;
301
+ if (walk.reason) job.waiting = walk.reason;
302
+ checkpoint();
303
+ if (oversized !== null) return setAsideOversized(oversized);
304
+ if (job.small && job.bytes < job.end && !records && stopped()) state.set("native-retain", key, true);
305
+ if (job.bytes === job.end) {
306
+ state.delete("native-unit", key); state.delete("native-retain", key); state.delete("small-stage", key);
307
+ if (job.snapshot && !job.small) {
308
+ staged.close(); staged = null;
309
+ prepareRetainedCaptureCleanup(store, stream, key, start);
310
+ result.cleanup = true;
311
+ }
312
+ return { ...result, complete: true, phase: "captured" };
313
+ }
314
+ return { ...result, phase: "capture", pending: !!walk.reason, reason: walk.reason ?? null };
315
+ } catch (error) {
316
+ if (!(error instanceof RecordSizeError)) throw error;
317
+ // The offending raw record was rejected before allocation/projection
318
+ // while searching for the first timestamp: no turn precedes it here.
319
+ return setAsideOversized(scanStart + error.offset);
320
+ }
321
+ } finally { try { staged?.close?.(); } finally { closeSync(fd); } }
322
+ }
@@ -0,0 +1,116 @@
1
+ // Private continuation transport. Reconciliation, durable fairness, failure
2
+ // attribution and status remain worker responsibilities. The parent never
3
+ // promotes a transient result into journal/checkpoint evidence; it only moves
4
+ // an unreadable status aside, under the lock and before any worker.
5
+ import { randomUUID } from "node:crypto";
6
+ import { CAPTURE_POLICY } from "./capture-budget.mjs";
7
+ import { acquireCaptureLock } from "./capture-lock.mjs";
8
+ import { cleanupCaptureScratch } from "./capture-scratch.mjs";
9
+ import { setAsideInvalidCaptureStatus } from "./capture-status.mjs";
10
+ import { captureMonotonicMs, captureSignalPoll, superviseCapture } from "./capture-supervisor.mjs";
11
+
12
+ // Internal scheduling choices, not public tuning or portable timing promises.
13
+ const ALLOWANCES = Object.freeze({ workMs: 60_000, finalizeMs: 70_000, hardMs: 75_000,
14
+ finalReserveMs: 15_000, finalDrainMs: 10_000, maxStarts: 8 });
15
+
16
+ export async function superviseCapturePass(root, options, {
17
+ policy = CAPTURE_POLICY, clock = captureMonotonicMs, acquire = acquireCaptureLock,
18
+ allowances = ALLOWANCES, drainSeconds = 5, ...transport
19
+ } = {}) {
20
+ const { workMs, finalizeMs, hardMs, finalReserveMs, finalDrainMs, maxStarts } = allowances;
21
+ if (![workMs, finalizeMs, hardMs, finalReserveMs, finalDrainMs].every(n => Number.isFinite(n) && n > 0) ||
22
+ workMs > finalizeMs || finalizeMs > hardMs || finalDrainMs > finalReserveMs ||
23
+ !Number.isSafeInteger(maxStarts) || maxStarts < 2 || maxStarts > 8) throw new Error("invalid internal capture scheduling allowances");
24
+ const started = clock(), deadline = started + policy.deadlineSeconds * 1000;
25
+ const drainAt = Math.max(started, deadline - drainSeconds * 1000), runId = randomUUID();
26
+ // TERM/INT is observed from before acquisition until after release: it ends
27
+ // admission of further workers; the current one is stopped by its supervisor.
28
+ let interrupted = false;
29
+ const onSignal = () => { interrupted = true; };
30
+ process.on("SIGINT", onSignal); process.on("SIGTERM", onSignal);
31
+ try {
32
+ return await superviseAcquiredPass(root, options, { policy, clock, acquire, allowances, transport,
33
+ started, deadline, drainAt, runId, interrupted: () => interrupted });
34
+ } finally { process.off("SIGINT", onSignal); process.off("SIGTERM", onSignal); }
35
+ }
36
+
37
+ async function superviseAcquiredPass(root, options, { policy, clock, acquire, allowances, transport,
38
+ started, deadline, drainAt, runId, interrupted: signalled }) {
39
+ const { workMs, finalizeMs, hardMs, finalReserveMs, finalDrainMs, maxStarts } = allowances;
40
+ const lock = acquire(root);
41
+ if (!lock.release) return { outcome: "overlap", reason: null, exitCode: 0, starts: 0, held: lock.held };
42
+ let starts = 0, registered, publicationFailed = false, interrupted = false, firstFailure = null, failureMessage;
43
+ let previous = null, result = { outcome: "partial", reason: "deadline", exitCode: 0 };
44
+ // A signal pending from synchronous preparation dispatches only at a poll.
45
+ const polled = async () => { await captureSignalPoll(); interrupted ||= signalled(); return interrupted; };
46
+ const attempt = async finalize => {
47
+ const launch = clock();
48
+ starts++;
49
+ const window = finalize
50
+ ? { drainAt: Math.min(drainAt, launch + finalDrainMs), finalizeAt: Math.min(deadline, launch + finalDrainMs), hardAt: Math.min(deadline, launch + finalReserveMs) }
51
+ : { drainAt: Math.min(drainAt, launch + workMs), finalizeAt: Math.min(deadline, launch + finalizeMs), hardAt: Math.min(deadline, launch + hardMs) };
52
+ const response = await superviseCapture(root, options, { ...transport, policy, clock, window,
53
+ pass: { runId, attempt: starts, finalize, reset: !finalize && previous?.resetRequired === true, started, deadline, drainAt,
54
+ failure: firstFailure,
55
+ // Only observed process outcome, never an asserted failed member/frame.
56
+ previous: previous && { outcome: previous.outcome, reason: previous.reason } },
57
+ acquire: () => ({ ...lock,
58
+ registerWorker: worker => {
59
+ try { lock.registerWorker(worker, { previous: registered }); registered = worker; }
60
+ catch (error) { publicationFailed = true; throw error; }
61
+ },
62
+ release: () => ({ released: true }), // outer owner releases once, after all children are reaped
63
+ }),
64
+ });
65
+ previous = response;
66
+ if (response.outcome === "failed" && firstFailure === null) { firstFailure = response.reason; failureMessage = response.message; }
67
+ return response;
68
+ };
69
+ // A worker's private diagnostic accompanies only the first failure it explains.
70
+ // A status moved aside by this pass is reported with whatever it returns.
71
+ let invalidStatus = null;
72
+ const failed = () => ({ outcome: "failed", reason: firstFailure, exitCode: 1, starts,
73
+ ...(failureMessage ? { message: failureMessage } : {}), ...(invalidStatus ? { invalidStatus } : {}) });
74
+ const ended = value => invalidStatus ? { ...value, invalidStatus } : value;
75
+ try {
76
+ // Under the root lock and before this pass starts any child: reclaim
77
+ // per-call scratch whose allocating process is proven dead (killed workers).
78
+ cleanupCaptureScratch(root, lock);
79
+ invalidStatus = setAsideInvalidCaptureStatus(root);
80
+ // Keep one start and time for a worker to reconcile/write final facts.
81
+ // A normal child is admitted only with its full allowance; in particular,
82
+ // atomic reset must not be admitted as a shortened last-minute operation.
83
+ while (!await polled() && starts < maxStarts - 1 && clock() + hardMs + finalReserveMs <= deadline) {
84
+ result = await attempt(false);
85
+ if (publicationFailed || await polled()) break;
86
+ // A worker may finish an honestly failed pass after committing healthy
87
+ // independent work and exhausting ready work. That explicit terminal
88
+ // result needs no idle retries; an unexplained crash still continues.
89
+ if (result.outcome === "complete" || result.outcome === "partial" && !result.continuation ||
90
+ result.outcome === "failed" && result.continuation === false) {
91
+ return firstFailure ? failed() : ended({ ...result, starts });
92
+ }
93
+ // On a crash the next child reconciles durable admission, then selects
94
+ // independent ready work. There is NO same-pass retry/diagnostic class.
95
+ }
96
+ if (!await polled() && !publicationFailed && starts < maxStarts && clock() < deadline) {
97
+ result = await attempt(true);
98
+ // Finalization cannot certify a sweep that this continuation transport
99
+ // stopped early. The worker likewise must not manufacture lastSuccess.
100
+ if (result.outcome === "complete") {
101
+ result = { outcome: "failed", reason: "io", exitCode: 1 }; firstFailure ??= "io";
102
+ }
103
+ }
104
+ // An earlier observed failure cause of this pass is kept, not replaced.
105
+ if (await polled() && !firstFailure) return ended({ outcome: "failed", reason: "interrupted", exitCode: 1, starts });
106
+ if (firstFailure) return failed();
107
+ return ended({ ...result, starts });
108
+ } catch (error) {
109
+ if (invalidStatus) error.invalidStatus ??= invalidStatus;
110
+ throw error;
111
+ } finally {
112
+ const released = lock.release();
113
+ if (!released.released) throw Object.assign(new Error("capture pass could not release its lock"), { release: released,
114
+ ...(invalidStatus ? { invalidStatus } : {}) });
115
+ }
116
+ }
@@ -0,0 +1,182 @@
1
+ // Command-only staged source copying. The fixed source end and committed chunk
2
+ // hashes survive workers; ownership is handled by retained-scratch, never by
3
+ // reopening an allocation by name alone. Explicit receipt snapshots do not use
4
+ // this append-only/bounded-witness path.
5
+ import { closeSync, constants, fstatSync, fsyncSync, ftruncateSync, openSync, readSync, writeSync } from "node:fs";
6
+ import { randomUUID } from "node:crypto";
7
+ import { captureContext } from "./capture-context.mjs";
8
+ import { createRetainedCaptureScratch, openRetainedCaptureScratch } from "./capture-retained-scratch.mjs";
9
+ import { statVersion, fileVersion, sameVersion } from "./derived-state.mjs";
10
+ import { assertProtectedDescriptor, digest } from "./session-snapshot.mjs";
11
+ import { guardCapturedPath } from "./native-history.mjs";
12
+
13
+ const CHUNK = 65536;
14
+ function readExact(fd, position, size) {
15
+ const bytes = Buffer.allocUnsafe(size); let read = 0;
16
+ while (read < size) {
17
+ const n = readSync(fd, bytes, read, size - read, position + read);
18
+ if (!n) throw new Error("short read of recovery snapshot");
19
+ read += n;
20
+ }
21
+ return bytes;
22
+ }
23
+
24
+ export function advanceRecoverySnapshot(store, stream, key, path, start, {
25
+ capturedPi, generation = "", fixedEnd, maxBytes = 8 * 1024 * 1024, stopped = () => false, work,
26
+ } = {}) {
27
+ const context = captureContext(store), state = context?.state;
28
+ if (!state?.depth || !context.held.has(stream)) throw new Error("recovery snapshot requires its stream work group");
29
+ if (typeof generation !== "string" || !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 8 * 1024 * 1024) throw new Error("invalid recovery snapshot budget");
30
+ // The scheduling caller applies ignore before entering this helper. Custody
31
+ // checks still precede every protected source open/read and final verification.
32
+ guardCapturedPath(path, capturedPi);
33
+ const sourceFd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | (capturedPi ? constants.O_NOFOLLOW : 0));
34
+ let allocation, retained = false;
35
+ try {
36
+ assertProtectedDescriptor(sourceFd, path, capturedPi);
37
+ if (!fstatSync(sourceFd).isFile()) throw new Error("recovery source is not a regular file");
38
+ const observe = () => {
39
+ assertProtectedDescriptor(sourceFd, path, capturedPi);
40
+ const version = statVersion(fstatSync(sourceFd, { bigint: true }));
41
+ if (!sameVersion(version, fileVersion(path))) throw new Error("recovery source descriptor differs from its named file");
42
+ return version;
43
+ };
44
+ const version = observe(), journalVersion = fileVersion(store.journalPath(stream)), db = state.db;
45
+ if (fixedEnd !== undefined && (!Number.isSafeInteger(fixedEnd) || fixedEnd < 0 || fixedEnd > version.size)) throw new Error("invalid fixed recovery end");
46
+ if (db.prepare("SELECT 1 AS found FROM sqlite_master WHERE type='table' AND name='recovery_chunks'").get()?.found !== 1) {
47
+ db.exec("CREATE TABLE recovery_chunks (allocation TEXT, offset INTEGER, length INTEGER NOT NULL, hash TEXT NOT NULL, PRIMARY KEY(allocation,offset))");
48
+ state.set("recovery-meta", "epoch", randomUUID());
49
+ }
50
+ let epoch = state.get("recovery-meta", "epoch");
51
+ if (epoch === null) { epoch = randomUUID(); state.set("recovery-meta", "epoch", epoch); }
52
+ if (typeof epoch !== "string" || !epoch) throw new Error("invalid recovery chunk epoch");
53
+ let stage = state.get("recovery-stage", key);
54
+ const existing = state.get("recovery-allocation", key);
55
+ allocation = existing ? openRetainedCaptureScratch(store, stream, key, start) : createRetainedCaptureScratch(store, stream, key, start);
56
+ const invalidate = reason => {
57
+ allocation.close();
58
+ allocation = openRetainedCaptureScratch(store, stream, key, start, { cleanup: true });
59
+ state.set("recovery-stage", key, { allocation: allocation.claim.id, phase: "invalid", reason });
60
+ return { complete: false, invalidated: true, cleanup: true, reason };
61
+ };
62
+ if (allocation.claim.phase === "deleting") return { complete: false, cleanup: true };
63
+ if (!existing) {
64
+ if (typeof stage?.allocation === "string") state.set("recovery-garbage", stage.allocation, true);
65
+ stage = { epoch, generation, journalVersion, allocation: allocation.claim.id, path, sourceVersion: version, observedVersion: version,
66
+ size: fixedEnd ?? version.size, copied: 0, checked: 0,
67
+ witness: digest(Buffer.alloc(0)), payloadVersion: statVersion(fstatSync(allocation.fd, { bigint: true })), phase: "copy" };
68
+ } else if (!stage || stage.epoch !== epoch || stage.allocation !== allocation.claim.id || stage.path !== path) {
69
+ return invalidate("recovery-state-lost");
70
+ }
71
+ if (stage.generation !== generation) return invalidate("recovery-generation-changed");
72
+ // A caller narrowing the end never reuses a copy fixed beyond it. A larger requested end is ordinary later growth: the
73
+ // first observation stays this sweep's fixed end.
74
+ if (fixedEnd !== undefined && fixedEnd < stage.size) return invalidate("recovery-end-changed");
75
+ // A public/outgoing writer may have captured a later source suffix between
76
+ // workers. Comparing that longer journal with this old fixed end would
77
+ // manufacture a missing-prefix conflict. Rebuild the source snapshot first;
78
+ // the append-only source witness never qualifies a changed journal version.
79
+ if (!sameVersion(stage.journalVersion, journalVersion)) return invalidate("recovery-journal-changed");
80
+ if (!["copy", "validate", "ready"].includes(stage.phase) ||
81
+ !["size", "copied", "checked"].every(k => Number.isSafeInteger(stage[k]) && stage[k] >= 0) ||
82
+ stage.copied > stage.size || stage.checked > stage.copied) {
83
+ return invalidate("recovery-state-invalid");
84
+ }
85
+ const witness = end => {
86
+ assertProtectedDescriptor(sourceFd, path, capturedPi);
87
+ const size = Math.min(4096, end), bytes = readExact(sourceFd, end - size, size);
88
+ if (work) work.sourceProbeBytes = (work.sourceProbeBytes ?? 0) + size;
89
+ return digest(bytes);
90
+ };
91
+ const sourceMatches = observed => sameVersion(stage.observedVersion, observed) ||
92
+ observed.dev === stage.sourceVersion.dev && observed.ino === stage.sourceVersion.ino &&
93
+ observed.size > stage.observedVersion.size && observed.size >= stage.size && witness(stage.copied) === stage.witness;
94
+ if (!sourceMatches(version)) return invalidate("recovery-source-changed");
95
+ stage.observedVersion = version;
96
+ allocation.verify();
97
+ let payloadVersion = statVersion(fstatSync(allocation.fd, { bigint: true }));
98
+ if (!sameVersion(payloadVersion, stage.payloadVersion)) {
99
+ if (payloadVersion.size < stage.copied) return invalidate("recovery-payload-shrank");
100
+ // The extra suffix was never committed. Remove it only from this adopted
101
+ // allocation, then verify every committed chunk before extending/using it.
102
+ if (payloadVersion.size > stage.copied) { ftruncateSync(allocation.fd, stage.copied); fsyncSync(allocation.fd); }
103
+ payloadVersion = statVersion(fstatSync(allocation.fd, { bigint: true }));
104
+ stage.phase = "validate"; stage.checked = 0; stage.payloadVersion = payloadVersion;
105
+ }
106
+ let used = 0;
107
+ const stop = () => used >= maxBytes || stopped();
108
+ if (stage.phase === "validate") {
109
+ const get = db.prepare("SELECT length,hash FROM recovery_chunks WHERE allocation=? AND offset=?");
110
+ while (stage.checked < stage.copied && !stop()) {
111
+ const row = get.get(stage.allocation, stage.checked);
112
+ if (!row || !Number.isSafeInteger(row.length) || row.length < 1 || row.length > CHUNK || stage.checked + row.length > stage.copied) return invalidate("recovery-chunk-missing");
113
+ const bytes = readExact(allocation.fd, stage.checked, row.length);
114
+ if (digest(bytes) !== row.hash) return invalidate("recovery-payload-changed");
115
+ stage.checked += row.length; used += row.length;
116
+ if (work) work.stagedReadBytes = (work.stagedReadBytes ?? 0) + row.length;
117
+ }
118
+ if (!sameVersion(stage.payloadVersion, statVersion(fstatSync(allocation.fd, { bigint: true })))) return invalidate("recovery-payload-changed");
119
+ if (stage.checked === stage.copied) stage.phase = stage.copied === stage.size ? "ready" : "copy";
120
+ }
121
+ if (stage.phase === "copy") {
122
+ const put = db.prepare("INSERT INTO recovery_chunks VALUES (?,?,?,?)");
123
+ while (stage.copied < stage.size && !stop()) {
124
+ assertProtectedDescriptor(sourceFd, path, capturedPi); allocation.verify();
125
+ const bytes = readExact(sourceFd, stage.copied, Math.min(CHUNK, maxBytes - used, stage.size - stage.copied));
126
+ if (work) work.sourceBytes = (work.sourceBytes ?? 0) + bytes.length;
127
+ // Copying never joins a line, so a record of any size stages in chunks;
128
+ // the raw-record limit applies to capture beyond the proven prefix.
129
+ for (let written = 0; written < bytes.length;) {
130
+ const n = writeSync(allocation.fd, bytes, written, bytes.length - written, stage.copied + written);
131
+ if (!n) throw new Error("short write of recovery snapshot"); written += n;
132
+ }
133
+ put.run(stage.allocation, stage.copied, bytes.length, digest(bytes));
134
+ stage.copied += bytes.length; used += bytes.length;
135
+ if (work) work.stagedWriteBytes = (work.stagedWriteBytes ?? 0) + bytes.length;
136
+ }
137
+ // File bytes precede the surrounding DB commit; a crash in between leaves
138
+ // a suffix that the next worker truncates/revalidates, never progress.
139
+ fsyncSync(allocation.fd);
140
+ stage.payloadVersion = statVersion(fstatSync(allocation.fd, { bigint: true }));
141
+ const probeBytes = Math.min(4096, stage.copied);
142
+ stage.witness = digest(readExact(allocation.fd, stage.copied - probeBytes, probeBytes));
143
+ if (work) work.stagedProbeBytes = (work.stagedProbeBytes ?? 0) + probeBytes;
144
+ if (stage.copied === stage.size) stage.phase = "ready";
145
+ }
146
+ const after = observe();
147
+ if (!sourceMatches(after)) return invalidate("recovery-source-changed");
148
+ stage.observedVersion = after;
149
+ allocation.verify();
150
+ state.set("recovery-stage", key, stage);
151
+ if (stage.phase !== "ready") return { complete: false, phase: stage.phase, copied: stage.copied, checked: stage.checked };
152
+ const verify = () => {
153
+ allocation.verify();
154
+ if (!sameVersion(stage.payloadVersion, statVersion(fstatSync(allocation.fd, { bigint: true }))) || !sourceMatches(observe())) {
155
+ throw new Error("recovery snapshot changed before use");
156
+ }
157
+ };
158
+ verify(); retained = true; let closed = false;
159
+ return { complete: true, snapshot: { id: stage.allocation, size: stage.size,
160
+ *chunks(from = 0, end = stage.size) {
161
+ if (!Number.isSafeInteger(from) || from < 0 || !Number.isSafeInteger(end) || end < from || end > stage.size) throw new Error("invalid recovery snapshot range");
162
+ for (let position = from; position < end;) {
163
+ verify(); const bytes = readExact(allocation.fd, position, Math.min(CHUNK, end - position));
164
+ position += bytes.length; yield bytes;
165
+ }
166
+ verify();
167
+ } }, verify, close() { if (!closed) { closed = true; try { allocation.close(); } finally { closeSync(sourceFd); } } } };
168
+ } finally { if (!retained) { try { allocation?.close(); } finally { closeSync(sourceFd); } } }
169
+ }
170
+
171
+ // Retired hash rows are derived metadata, not cleanup authority for any path.
172
+ // The worker queues an allocation id after retiring its job and reclaims only a
173
+ // bounded number per unit; payload ownership remains the separate scratch rule.
174
+ export function discardRecoveryChunks(state, allocation, { maxRecords = 2000 } = {}) {
175
+ if (!state.depth || typeof allocation !== "string" || !/^[a-f0-9]{32}$/.test(allocation) ||
176
+ !Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 2000) throw new Error("invalid recovery chunk cleanup");
177
+ const exists = state.db.prepare("SELECT 1 AS found FROM sqlite_master WHERE type='table' AND name='recovery_chunks'").get()?.found === 1;
178
+ const done = !exists || Number(state.db.prepare(`DELETE FROM recovery_chunks WHERE rowid IN
179
+ (SELECT rowid FROM recovery_chunks WHERE allocation=? LIMIT ?)`).run(allocation, maxRecords).changes) < maxRecords;
180
+ if (done) state.delete("recovery-garbage", allocation);
181
+ return done;
182
+ }