@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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "title": "Capture status (algorithm phase)",
3
+ "title": "Capture status",
4
4
  "type": "object",
5
5
  "additionalProperties": false,
6
6
  "required": [
@@ -17,24 +17,82 @@
17
17
  "const": 1
18
18
  },
19
19
  "policy": {
20
- "type": "null",
21
- "description": "No policy or run evidence supplied in the algorithm-only phase."
20
+ "anyOf": [
21
+ {
22
+ "type": "null"
23
+ },
24
+ {
25
+ "type": "object",
26
+ "additionalProperties": false,
27
+ "required": [
28
+ "intervalSeconds",
29
+ "heapMiB",
30
+ "rssBytes",
31
+ "deadlineSeconds",
32
+ "maxRecordBytes"
33
+ ],
34
+ "properties": {
35
+ "intervalSeconds": {
36
+ "const": 900
37
+ },
38
+ "heapMiB": {
39
+ "const": 256
40
+ },
41
+ "rssBytes": {
42
+ "const": 2147483648
43
+ },
44
+ "deadlineSeconds": {
45
+ "const": 300
46
+ },
47
+ "maxRecordBytes": {
48
+ "const": 8388608
49
+ }
50
+ }
51
+ }
52
+ ],
53
+ "description": "Null retains algorithm-phase absence of policy evidence. Service workers publish the fixed common policy."
22
54
  },
23
55
  "lastRun": {
24
- "type": "null",
25
- "description": "No policy or run evidence supplied in the algorithm-only phase."
56
+ "anyOf": [
57
+ {
58
+ "type": "null"
59
+ },
60
+ {
61
+ "$ref": "#/$defs/run"
62
+ }
63
+ ]
26
64
  },
27
65
  "lastSuccess": {
28
- "type": "null",
29
- "description": "No policy or run evidence supplied in the algorithm-only phase."
66
+ "anyOf": [
67
+ {
68
+ "type": "null"
69
+ },
70
+ {
71
+ "$ref": "#/$defs/summary"
72
+ }
73
+ ]
30
74
  },
31
75
  "lastFailure": {
32
- "type": "null",
33
- "description": "No policy or run evidence supplied in the algorithm-only phase."
76
+ "anyOf": [
77
+ {
78
+ "type": "null"
79
+ },
80
+ {
81
+ "$ref": "#/$defs/failure"
82
+ }
83
+ ]
34
84
  },
35
85
  "lastProgressAt": {
36
- "type": "null",
37
- "description": "No policy or run evidence supplied in the algorithm-only phase."
86
+ "anyOf": [
87
+ {
88
+ "type": "null"
89
+ },
90
+ {
91
+ "type": "string",
92
+ "format": "date-time"
93
+ }
94
+ ],
95
+ "description": "Advanced only for committed progress; a running process or a sampled RSS value is not progress."
38
96
  },
39
97
  "backlog": {
40
98
  "type": "object",
@@ -93,8 +151,367 @@
93
151
  },
94
152
  "truncated": {
95
153
  "type": "boolean"
154
+ },
155
+ "failedCount": {
156
+ "type": "integer",
157
+ "minimum": 0
158
+ },
159
+ "failedTruncated": {
160
+ "type": "boolean"
161
+ },
162
+ "failed": {
163
+ "type": "array",
164
+ "maxItems": 100,
165
+ "items": {
166
+ "type": "object",
167
+ "additionalProperties": false,
168
+ "required": [
169
+ "stream",
170
+ "offset",
171
+ "reason",
172
+ "attempts",
173
+ "nextRetryAt"
174
+ ],
175
+ "properties": {
176
+ "stream": {
177
+ "type": "string",
178
+ "minLength": 1
179
+ },
180
+ "offset": {
181
+ "type": "integer",
182
+ "minimum": 0,
183
+ "description": "Journal byte offset at the start of the durably admitted failed single-stream unit; not an exact failing-frame location."
184
+ },
185
+ "reason": {
186
+ "enum": [
187
+ "heap",
188
+ "rss",
189
+ "deadline",
190
+ "interrupted",
191
+ "io"
192
+ ]
193
+ },
194
+ "attempts": {
195
+ "type": "integer",
196
+ "minimum": 1
197
+ },
198
+ "nextRetryAt": {
199
+ "type": "string",
200
+ "format": "date-time"
201
+ }
202
+ }
203
+ }
204
+ }
205
+ },
206
+ "description": "Operational failure fields are absent in algorithm-phase snapshots; absence is no recorded evidence, never proof of success. Each category has its own 100-entry sample.",
207
+ "dependentRequired": {
208
+ "failedCount": [
209
+ "failed",
210
+ "failedTruncated"
211
+ ],
212
+ "failed": [
213
+ "failedCount",
214
+ "failedTruncated"
215
+ ],
216
+ "failedTruncated": [
217
+ "failedCount",
218
+ "failed"
219
+ ]
220
+ }
221
+ }
222
+ },
223
+ "$defs": {
224
+ "counts": {
225
+ "type": "object",
226
+ "additionalProperties": false,
227
+ "required": [
228
+ "filesVisited",
229
+ "bytesCommitted",
230
+ "turnsAppended",
231
+ "turnsIndexed",
232
+ "inputsPending",
233
+ "inputsSetAside",
234
+ "inputsFailed",
235
+ "inputsIgnored"
236
+ ],
237
+ "properties": {
238
+ "filesVisited": {
239
+ "type": "integer",
240
+ "minimum": 0,
241
+ "maximum": 9007199254740991
242
+ },
243
+ "bytesCommitted": {
244
+ "type": "integer",
245
+ "minimum": 0,
246
+ "maximum": 9007199254740991
247
+ },
248
+ "turnsAppended": {
249
+ "type": "integer",
250
+ "minimum": 0,
251
+ "maximum": 9007199254740991
252
+ },
253
+ "turnsIndexed": {
254
+ "type": "integer",
255
+ "minimum": 0,
256
+ "maximum": 9007199254740991
257
+ },
258
+ "inputsPending": {
259
+ "type": "integer",
260
+ "minimum": 0,
261
+ "maximum": 9007199254740991
262
+ },
263
+ "inputsSetAside": {
264
+ "type": "integer",
265
+ "minimum": 0,
266
+ "maximum": 9007199254740991
267
+ },
268
+ "inputsFailed": {
269
+ "type": "integer",
270
+ "minimum": 0,
271
+ "maximum": 9007199254740991
272
+ },
273
+ "inputsIgnored": {
274
+ "type": "integer",
275
+ "minimum": 0,
276
+ "maximum": 9007199254740991
277
+ }
278
+ }
279
+ },
280
+ "summary": {
281
+ "type": "object",
282
+ "additionalProperties": false,
283
+ "required": [
284
+ "id",
285
+ "trigger",
286
+ "pid",
287
+ "startedAt",
288
+ "finishedAt",
289
+ "counts",
290
+ "peakRssBytes"
291
+ ],
292
+ "properties": {
293
+ "id": {
294
+ "type": "string",
295
+ "minLength": 1
296
+ },
297
+ "trigger": {
298
+ "enum": [
299
+ "service",
300
+ "hook",
301
+ "setup",
302
+ "manual",
303
+ "watch"
304
+ ]
305
+ },
306
+ "pid": {
307
+ "type": "integer",
308
+ "minimum": 1
309
+ },
310
+ "startedAt": {
311
+ "type": "string",
312
+ "format": "date-time"
313
+ },
314
+ "finishedAt": {
315
+ "type": "string",
316
+ "format": "date-time"
317
+ },
318
+ "counts": {
319
+ "$ref": "#/$defs/counts"
320
+ },
321
+ "peakRssBytes": {
322
+ "type": [
323
+ "integer",
324
+ "null"
325
+ ],
326
+ "minimum": 0
327
+ }
328
+ }
329
+ },
330
+ "failure": {
331
+ "type": "object",
332
+ "additionalProperties": false,
333
+ "required": [
334
+ "id",
335
+ "trigger",
336
+ "pid",
337
+ "startedAt",
338
+ "finishedAt",
339
+ "counts",
340
+ "peakRssBytes",
341
+ "reason",
342
+ "message"
343
+ ],
344
+ "properties": {
345
+ "id": {
346
+ "type": "string",
347
+ "minLength": 1
348
+ },
349
+ "trigger": {
350
+ "enum": [
351
+ "service",
352
+ "hook",
353
+ "setup",
354
+ "manual",
355
+ "watch"
356
+ ]
357
+ },
358
+ "pid": {
359
+ "type": "integer",
360
+ "minimum": 1
361
+ },
362
+ "startedAt": {
363
+ "type": "string",
364
+ "format": "date-time"
365
+ },
366
+ "finishedAt": {
367
+ "type": "string",
368
+ "format": "date-time"
369
+ },
370
+ "counts": {
371
+ "$ref": "#/$defs/counts"
372
+ },
373
+ "peakRssBytes": {
374
+ "type": [
375
+ "integer",
376
+ "null"
377
+ ],
378
+ "minimum": 0
379
+ },
380
+ "reason": {
381
+ "enum": [
382
+ "deadline",
383
+ "rss",
384
+ "heap",
385
+ "interrupted",
386
+ "input",
387
+ "io"
388
+ ]
389
+ },
390
+ "message": {
391
+ "type": "string",
392
+ "minLength": 1,
393
+ "maxLength": 2048
394
+ },
395
+ "path": {
396
+ "type": "string"
397
+ },
398
+ "offset": {
399
+ "type": "integer",
400
+ "minimum": 0,
401
+ "maximum": 9007199254740991
402
+ }
403
+ }
404
+ },
405
+ "run": {
406
+ "type": "object",
407
+ "additionalProperties": false,
408
+ "required": [
409
+ "id",
410
+ "trigger",
411
+ "pid",
412
+ "startedAt",
413
+ "finishedAt",
414
+ "counts",
415
+ "peakRssBytes",
416
+ "outcome",
417
+ "reason",
418
+ "reclaimedLock"
419
+ ],
420
+ "properties": {
421
+ "id": {
422
+ "type": "string",
423
+ "minLength": 1
424
+ },
425
+ "trigger": {
426
+ "enum": [
427
+ "service",
428
+ "hook",
429
+ "setup",
430
+ "manual",
431
+ "watch"
432
+ ]
433
+ },
434
+ "pid": {
435
+ "type": "integer",
436
+ "minimum": 1
437
+ },
438
+ "startedAt": {
439
+ "type": "string",
440
+ "format": "date-time"
441
+ },
442
+ "finishedAt": {
443
+ "anyOf": [
444
+ {
445
+ "type": "string",
446
+ "format": "date-time"
447
+ },
448
+ {
449
+ "type": "null"
450
+ }
451
+ ]
452
+ },
453
+ "counts": {
454
+ "$ref": "#/$defs/counts"
455
+ },
456
+ "peakRssBytes": {
457
+ "type": [
458
+ "integer",
459
+ "null"
460
+ ],
461
+ "minimum": 0
462
+ },
463
+ "outcome": {
464
+ "enum": [
465
+ "running",
466
+ "complete",
467
+ "partial",
468
+ "failed"
469
+ ]
470
+ },
471
+ "reason": {
472
+ "anyOf": [
473
+ {
474
+ "enum": [
475
+ "deadline",
476
+ "rss",
477
+ "heap",
478
+ "interrupted",
479
+ "input",
480
+ "io"
481
+ ]
482
+ },
483
+ {
484
+ "type": "null"
485
+ }
486
+ ]
487
+ },
488
+ "reclaimedLock": {
489
+ "anyOf": [
490
+ {
491
+ "type": "null"
492
+ },
493
+ {
494
+ "type": "object",
495
+ "additionalProperties": false,
496
+ "required": [
497
+ "pid",
498
+ "startedAt"
499
+ ],
500
+ "properties": {
501
+ "pid": {
502
+ "type": "integer",
503
+ "minimum": 1
504
+ },
505
+ "startedAt": {
506
+ "type": "string",
507
+ "format": "date-time"
508
+ }
509
+ }
510
+ }
511
+ ]
96
512
  }
97
513
  }
98
514
  }
99
- }
515
+ },
516
+ "description": "Atomic last-command snapshot. Current issue health is read separately from capture.db. Run times must be ordered and not future-dated; running has null finish/reason, complete has null reason, failed has a nonnull reason. Null policy requires null run/history evidence."
100
517
  }
@@ -0,0 +1,82 @@
1
+ // Private durable admission, separate from processing checkpoints. The command
2
+ // scheduler owns the root lock and chooses bounded work; this module neither
3
+ // schedules retries nor diagnoses a group interruption as member failures.
4
+ import { randomUUID } from "node:crypto";
5
+
6
+ const stages = new Set(["capture", "validation", "index", "prefix", "reset"]);
7
+ const validVersion = value => value === null || value &&
8
+ ["dev", "ino", "mtime", "ctime"].every(key => typeof value[key] === "string" && value[key].length > 0) &&
9
+ Number.isSafeInteger(value.size) && value.size >= 0;
10
+
11
+ export function readCaptureRetry(state, stream) {
12
+ const row = state.get("capture-retry", stream);
13
+ if (row !== null && (!row || row.stream !== stream || !stages.has(row.stage) ||
14
+ !validVersion(row.generation) || !Number.isSafeInteger(row.offset) || row.offset < 0 ||
15
+ row.offset > (row.generation?.size ?? 0) ||
16
+ !["unitId", "attemptedRun"].every(key => typeof row[key] === "string" && row[key]) ||
17
+ typeof row.nextRetryAt !== "string" || !Number.isFinite(Date.parse(row.nextRetryAt)) ||
18
+ new Date(row.nextRetryAt).toISOString() !== row.nextRetryAt)) {
19
+ throw new Error("invalid deferred capture work");
20
+ }
21
+ return row;
22
+ }
23
+
24
+ function validSelection(selection) {
25
+ return selection && typeof selection.runId === "string" && selection.runId.length > 0 &&
26
+ (selection.retry === undefined || typeof selection.retry === "boolean") &&
27
+ stages.has(selection.stage) && selection.next && stages.has(selection.next.stage) &&
28
+ typeof selection.next.after === "string" && Array.isArray(selection.members) &&
29
+ selection.members.length > 0 && selection.members.length <= 128 &&
30
+ new Set(selection.members.map(member => member?.stream)).size === selection.members.length &&
31
+ selection.members.every(member => typeof member?.stream === "string" && member.stream.length > 0 &&
32
+ Number.isSafeInteger(member.offset) && member.offset >= 0 && validVersion(member.generation) &&
33
+ member.offset <= (member.generation?.size ?? 0));
34
+ }
35
+
36
+ export function readCaptureAdmission(state) {
37
+ const row = state.get("capture-admission", "active");
38
+ if (row !== null && (!validSelection(row) || typeof row.id !== "string" || !row.id)) {
39
+ throw new Error("invalid durable capture admission");
40
+ }
41
+ return row;
42
+ }
43
+
44
+ // Called only after ALL member locks are held, before the processing DB
45
+ // transaction. Committing inside the latter would leave only volatile intent.
46
+ export function commitCaptureAdmission(state, selection, held, { now = Date.now() } = {}) {
47
+ if (state.depth) throw new Error("capture admission must precede the processing transaction");
48
+ if (!validSelection(selection) || selection.members.length !== held.size ||
49
+ selection.members.some(member => !held.has(member.stream))) throw new Error("invalid capture admission selection");
50
+ if (!Number.isSafeInteger(now) || now < 0) throw new Error("invalid capture admission time");
51
+ const row = { id: randomUUID(), runId: selection.runId, stage: selection.stage, retry: selection.retry === true,
52
+ next: { stage: selection.next.stage, after: selection.next.after },
53
+ members: selection.members.map(({ stream, offset, generation }) => ({ stream, offset, generation })) };
54
+ state.transaction(() => {
55
+ // The next worker must reconcile this evidence before admitting new work.
56
+ // Overwriting it would lose both crash attribution and queue progress.
57
+ if (readCaptureAdmission(state)) throw new Error("unreconciled capture admission");
58
+ for (const member of row.members) {
59
+ const retry = readCaptureRetry(state, member.stream);
60
+ if (retry) {
61
+ if (!row.retry || row.members.length !== 1 || retry.stage !== row.stage || retry.attemptedRun === row.runId ||
62
+ !Number.isFinite(Date.parse(retry.nextRetryAt)) || now < Date.parse(retry.nextRetryAt)) {
63
+ throw new Error("deferred capture work requires a due single-stream admission");
64
+ }
65
+ state.set("capture-retry", member.stream, { ...retry, attemptedRun: row.runId });
66
+ } else if (row.retry) throw new Error("capture retry no longer exists");
67
+ }
68
+ state.set("capture-admission", "active", row);
69
+ state.set("capture-schedule", "position", row.next);
70
+ state.set("capture-schedule", `position:${row.stage}`, { stage: row.stage, after: row.next.after });
71
+ if (row.retry) state.set("capture-schedule", "retry-after", row.members[0].stream);
72
+ });
73
+ return row;
74
+ }
75
+
76
+ // Clear the admitted work in the SAME commit as its completed checkpoints.
77
+ // On a throw or process death, rollback keeps admission and its fairness
78
+ // position, while journal bytes that were already fsynced remain authoritative.
79
+ export function finishCaptureAdmission(state, id) {
80
+ if (!state.depth || readCaptureAdmission(state)?.id !== id) throw new Error("capture admission changed before completion");
81
+ state.delete("capture-admission", "active");
82
+ }
@@ -0,0 +1,137 @@
1
+ // Private command work, one bounded log batch under the shared stream group.
2
+ // Explicit per-file public APIs keep their full-reprojection defaults.
3
+ import { closeSync, constants, fstatSync, openSync } from "node:fs";
4
+ import { basename } from "node:path";
5
+ import { awBoundaryWitness, awLogLines, awStream } from "./capture-aw.mjs";
6
+ import { captureContext } from "./capture-context.mjs";
7
+ import { CAPTURE_POLICY } from "./capture-budget.mjs";
8
+ import { fileVersion, statVersion, sameVersion } from "./derived-state.mjs";
9
+ import { fileChunks, RecordSizeError } from "./file-lines.mjs";
10
+ import { loadIgnore } from "./ignore.mjs";
11
+ import { projectCommLogEntry, projectInteractionLogEntry } from "./project-aweb.mjs";
12
+
13
+ export function captureAwUnit(store, { owner, path, kind = "comm", selfName, workspace, ignore,
14
+ maxRecords = 2000, maxBytes = 8388608, maxRecordBytes = CAPTURE_POLICY.maxRecordBytes,
15
+ stopped = () => false, work } = {}) {
16
+ const stream = awStream(owner), key = `${stream}:${path}`, account = basename(path, ".jsonl");
17
+ const context = captureContext(store), state = context?.state;
18
+ if (!state?.depth || !context.held.has(stream)) throw new Error("AW command unit requires its stream work group");
19
+ if (!["comm", "interaction"].includes(kind) || !Number.isSafeInteger(maxRecords) || maxRecords < 1 || maxRecords > 2000 ||
20
+ !Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > context.batchBytes ||
21
+ !Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 1 || maxRecordBytes > CAPTURE_POLICY.maxRecordBytes) {
22
+ throw new Error("invalid AW command unit budget");
23
+ }
24
+ const result = { stream, key, entries: 0, skipped: 0, failed: 0, appended: 0, bytesCommitted: 0, complete: false, pending: false };
25
+ if ((ignore ?? loadIgnore(store.root)).ignores(path, [basename(path), account])) {
26
+ state.delete("set-aside", key);
27
+ return { ...result, ignored: true, complete: true };
28
+ }
29
+ const blocked = state.get("set-aside", key);
30
+ if (blocked && !blocked.retry) return { ...result, setAside: blocked };
31
+ const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
32
+ try {
33
+ const observe = () => {
34
+ const stat = fstatSync(fd, { bigint: true });
35
+ if (!stat.isFile()) throw new Error("AW source is not a regular file");
36
+ const version = statVersion(stat);
37
+ if (!sameVersion(version, fileVersion(path))) throw new Error("AW source descriptor differs from its named file");
38
+ return version;
39
+ };
40
+ const version = observe(), generation = state.get("reset", `${owner}:aw`) ?? "",
41
+ retryGeneration = state.get("source-retry", key) ?? "";
42
+ const projection = JSON.stringify(kind === "comm" ? [kind, account] : [kind, selfName ?? null, workspace ?? null]);
43
+ const journal = store.validateJournal(stream, state, { maxRecords, maxBytes, stopped, work: work?.journal });
44
+ if (!journal.complete) return { ...result, phase: "journal" };
45
+ const witness = offset => {
46
+ if (work) work.sourceProbeBytes = (work.sourceProbeBytes ?? 0) + Math.min(4096, offset);
47
+ return awBoundaryWitness(fd, offset);
48
+ };
49
+ const matches = value => value && Number.isSafeInteger(value.bytes) && value.bytes >= 0 && value.bytes <= version.size &&
50
+ value.generation === generation && (value.retryGeneration ?? "") === retryGeneration && value.epoch === journal.epoch && value.version &&
51
+ (value.projection === projection || value.projection === undefined && kind === "comm") &&
52
+ (sameVersion(value.version, version) || value.version.dev === version.dev && value.version.ino === version.ino &&
53
+ version.size > value.version.size && witness(value.bytes) === value.witness);
54
+ let job = state.get("aw-unit", key);
55
+ if (!matches(job) || !Number.isSafeInteger(job.end) || job.end < job.bytes || job.end > version.size) {
56
+ job = null; state.delete("aw-unit", key);
57
+ }
58
+ if (!job) {
59
+ const cursor = state.get("aw", key), qualified = matches(cursor) && !blocked;
60
+ if (qualified && cursor.complete && sameVersion(cursor.version, version)) {
61
+ // The public API's complete flag means the snapshot was scanned; an
62
+ // unconsumed final fragment still prevents command sweep success.
63
+ return { ...result, unchanged: true, complete: cursor.bytes === version.size,
64
+ pending: cursor.bytes < version.size, phase: "captured" };
65
+ }
66
+ // A cursor that no longer qualifies (new epoch, reset, retry, an older
67
+ // release's shape) still proves what it captured from this same file:
68
+ // records before its bytes are rescanned without the record limit. A
69
+ // rescan's cursor also carries the frontier it is still below, so a
70
+ // second invalidation between its units keeps the larger proof.
71
+ const sameFile = cursor?.version?.dev === version.dev && cursor?.version?.ino === version.ino;
72
+ const proof = (bytes, mark) => sameFile && Number.isSafeInteger(bytes) && bytes > 0 && bytes <= version.size &&
73
+ typeof mark === "string" && witness(bytes) === mark ? [bytes, mark] : [0, undefined];
74
+ const [frontier, frontierWitness] = [qualified ? [0, undefined] : proof(cursor?.bytes, cursor?.witness),
75
+ proof(cursor?.frontier, cursor?.frontierWitness)].reduce((a, b) => b[0] > a[0] ? b : a);
76
+ job = { bytes: qualified ? cursor.bytes : 0, end: version.size, version, generation, retryGeneration,
77
+ epoch: journal.epoch, projection, frontier, frontierWitness };
78
+ }
79
+ const unitStart = job.bytes, boundary = witness(version.size);
80
+ const chunks = function* () {
81
+ for (const bytes of fileChunks(fd, { start: unitStart, end: job.end, size: 65536, check: () => { stopped(); } })) {
82
+ if (work) work.sourceBytes = (work.sourceBytes ?? 0) + bytes.length;
83
+ yield bytes;
84
+ }
85
+ };
86
+ const project = kind === "comm" ? entry => projectCommLogEntry(entry, { selfName: account }) :
87
+ entry => projectInteractionLogEntry(entry, { selfName, workspace });
88
+ let bytes = 0, records = 0, scanned = false, oversized = null;
89
+ const turns = [], iterator = awLogLines(chunks(), { start: unitStart, maxBytes: maxRecordBytes, frontier: job.frontier ?? 0 });
90
+ try {
91
+ while (records < maxRecords && bytes < maxBytes && !stopped()) {
92
+ const next = iterator.next();
93
+ if (next.done) { scanned = true; break; }
94
+ const record = next.value;
95
+ if (records && bytes + record.bytes > maxBytes) break;
96
+ records++; bytes += record.bytes; job.bytes = record.end;
97
+ if (work) work.sourceRecords = (work.sourceRecords ?? 0) + 1;
98
+ if (record.skipped) result.skipped++;
99
+ if (record.parsed) {
100
+ result.entries++;
101
+ // Projection refusal is consumed input, not a failed durable append.
102
+ // Reset requests replay; ordinary growth never retries the old line.
103
+ try { turns.push(project(record.entry)); }
104
+ catch { result.failed++; }
105
+ }
106
+ if (record.final) { result.pending = true; scanned = true; break; }
107
+ }
108
+ } catch (error) {
109
+ if (!(error instanceof RecordSizeError)) throw error;
110
+ // The raw record was rejected before allocation. Every complete record
111
+ // before it is still processable: commit them below, then set aside.
112
+ oversized = unitStart + error.offset;
113
+ if (oversized !== job.bytes) throw new Error("AW oversized record does not follow the consumed records");
114
+ } finally { iterator.return(); }
115
+ const after = observe();
116
+ if (!sameVersion(version, after) && !(after.dev === version.dev && after.ino === version.ino &&
117
+ after.size > version.size && witness(version.size) === boundary)) throw new Error("AW source changed during unit");
118
+ if (turns.length) result.appended = store.appendUniqueBatch(stream, turns);
119
+ result.bytesCommitted = job.bytes - unitStart;
120
+ job.version = version; job.witness = witness(job.bytes);
121
+ const atEnd = job.bytes === job.end;
122
+ state.set("aw", key, { bytes: job.bytes, version, witness: job.witness, generation, retryGeneration,
123
+ epoch: journal.epoch, projection, complete: (scanned || atEnd) && job.end === version.size,
124
+ ...(job.frontier > job.bytes && job.frontierWitness ? { frontier: job.frontier, frontierWitness: job.frontierWitness } : {}) });
125
+ if (blocked && (job.bytes > blocked.offset || atEnd)) state.delete("set-aside", key);
126
+ if (scanned || atEnd) state.delete("aw-unit", key);
127
+ else state.set("aw-unit", key, job);
128
+ if (oversized !== null) {
129
+ // Not captured past its exact start. Later records wait for an edited
130
+ // source or an ignore of the whole input.
131
+ const row = { owner, source: "aw", path, offset: oversized, reason: "record-too-large", retry: false };
132
+ state.set("set-aside", key, row);
133
+ return { ...result, setAside: row };
134
+ }
135
+ return { ...result, complete: atEnd, phase: "capture" };
136
+ } finally { closeSync(fd); }
137
+ }