@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.
- package/README.md +1 -1
- package/bin/oats.mjs +27 -12
- package/docs/capabilities.md +1 -1
- package/docs/desktop-cli-api.md +30 -2
- package/docs/execution-targets.md +89 -4
- package/docs/implementation.md +2 -1
- package/docs/named-test-runs.md +382 -0
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-lane.md +13 -0
- package/docs/release-notes/v0.62.0.md +223 -0
- package/docs/release-notes/v0.63.0.md +135 -0
- package/docs/souls-and-instances.md +6 -1
- package/docs/upgrading.md +135 -11
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +73 -23
- package/lib/doctor-capture.mjs +35 -0
- package/lib/session-viewer.mjs +86 -7
- package/lib/tree-copy.mjs +188 -7
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/record/README.md +87 -13
- package/packages/record/bin/capture-hook.mjs +8 -0
- package/packages/record/bin/capture.mjs +200 -139
- package/packages/record/bin/recall.mjs +8 -3
- package/packages/record/bin/setup.mjs +116 -225
- package/packages/record/bin/turn-record.mjs +2 -2
- package/packages/record/docs/capture-service.md +1527 -28
- package/packages/record/docs/capture-status.schema.json +429 -12
- package/packages/record/lib/capture-admission.mjs +82 -0
- package/packages/record/lib/capture-aw-unit.mjs +137 -0
- package/packages/record/lib/capture-aw.mjs +31 -12
- package/packages/record/lib/capture-budget.mjs +31 -0
- package/packages/record/lib/capture-cc.mjs +39 -6
- package/packages/record/lib/capture-cleanup-queue.mjs +135 -0
- package/packages/record/lib/capture-cleanup-work.mjs +77 -0
- package/packages/record/lib/capture-command-operation.mjs +37 -0
- package/packages/record/lib/capture-command-output.mjs +62 -0
- package/packages/record/lib/capture-command-worker.mjs +6 -0
- package/packages/record/lib/capture-command.mjs +65 -0
- package/packages/record/lib/capture-completion.mjs +152 -0
- package/packages/record/lib/capture-context.mjs +50 -0
- package/packages/record/lib/capture-default-roots.mjs +30 -0
- package/packages/record/lib/capture-discovery.mjs +114 -0
- package/packages/record/lib/capture-failures.mjs +45 -0
- package/packages/record/lib/capture-health-doctor.mjs +13 -0
- package/packages/record/lib/capture-health-installation.mjs +117 -0
- package/packages/record/lib/capture-health.mjs +116 -0
- package/packages/record/lib/capture-hook-ownership.mjs +58 -0
- package/packages/record/lib/capture-hook-runner.mjs +17 -0
- package/packages/record/lib/capture-hook.mjs +26 -0
- package/packages/record/lib/capture-index-inventory.mjs +205 -0
- package/packages/record/lib/capture-index-outcomes.mjs +113 -0
- package/packages/record/lib/capture-index-reset.mjs +110 -0
- package/packages/record/lib/capture-index-work.mjs +77 -0
- package/packages/record/lib/capture-issue-preparation.mjs +73 -0
- package/packages/record/lib/capture-issues.mjs +15 -2
- package/packages/record/lib/capture-lock.mjs +137 -17
- package/packages/record/lib/capture-native-unit.mjs +322 -0
- package/packages/record/lib/capture-pass.mjs +116 -0
- package/packages/record/lib/capture-recovery-snapshot.mjs +182 -0
- package/packages/record/lib/capture-retained-scratch.mjs +213 -0
- package/packages/record/lib/capture-retry.mjs +102 -0
- package/packages/record/lib/capture-run.mjs +125 -0
- package/packages/record/lib/capture-scratch.mjs +12 -3
- package/packages/record/lib/capture-service-definition.mjs +104 -0
- package/packages/record/lib/capture-service-install.mjs +362 -0
- package/packages/record/lib/capture-service-ownership.mjs +137 -0
- package/packages/record/lib/capture-service-runner.mjs +18 -0
- package/packages/record/lib/capture-small-snapshot.mjs +85 -0
- package/packages/record/lib/capture-source-discovery.mjs +319 -0
- package/packages/record/lib/capture-source-queue.mjs +199 -0
- package/packages/record/lib/capture-source-work.mjs +85 -0
- package/packages/record/lib/capture-state.mjs +16 -71
- package/packages/record/lib/capture-status.mjs +171 -0
- package/packages/record/lib/capture-supervisor.mjs +136 -0
- package/packages/record/lib/capture-watch.mjs +32 -0
- package/packages/record/lib/capture-work-session.mjs +241 -0
- package/packages/record/lib/capture-worker.mjs +74 -0
- package/packages/record/lib/derived-state.mjs +58 -17
- package/packages/record/lib/file-lines.mjs +22 -6
- package/packages/record/lib/formats.mjs +4 -3
- package/packages/record/lib/index-capture.mjs +97 -0
- package/packages/record/lib/index-db.mjs +121 -66
- package/packages/record/lib/index-reset.mjs +19 -0
- package/packages/record/lib/store.mjs +46 -14
- package/packages/record/lib/transcript-prefix.mjs +125 -0
- package/skills/oats-getting-started/SKILL.md +1 -1
- package/docs/macos-test-runs.md +0 -246
|
@@ -1,13 +1,12 @@
|
|
|
1
|
-
// Shared capture status and operator recovery.
|
|
2
|
-
//
|
|
1
|
+
// Shared capture status and operator recovery. Null policy/run fields retain
|
|
2
|
+
// their algorithm-phase meaning: no such evidence has been supplied.
|
|
3
3
|
import { randomUUID } from "node:crypto";
|
|
4
|
-
import { closeSync, constants, fstatSync, fsyncSync, openSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
|
|
5
|
-
import { join } from "node:path";
|
|
6
4
|
import { DerivedState, invalidateLegacyMaps } from "./derived-state.mjs";
|
|
7
|
-
import {
|
|
5
|
+
import { readIssueBacklog } from "./capture-issues.mjs";
|
|
6
|
+
import { emptyCaptureStatus, readCaptureStatus, persistCaptureStatus } from "./capture-status.mjs";
|
|
8
7
|
|
|
9
8
|
export const CAPTURE_SOURCES = ["aw", "cc", "pi", "codex"];
|
|
10
|
-
export
|
|
9
|
+
export { captureHealth, SET_ASIDE_REMEDY } from "./capture-health.mjs";
|
|
11
10
|
|
|
12
11
|
// Caller owns the root capture lock. One transaction persists every selected
|
|
13
12
|
// generation; a missing source cursor cannot erase this rescan request.
|
|
@@ -26,7 +25,13 @@ export function retrySetAside(root) {
|
|
|
26
25
|
const state = new DerivedState(root);
|
|
27
26
|
try {
|
|
28
27
|
state.transaction(() => {
|
|
29
|
-
for (const { key, value } of state.entries("set-aside"))
|
|
28
|
+
for (const { key, value } of state.entries("set-aside")) {
|
|
29
|
+
// A command's explicit retry invalidates an older staged proof once.
|
|
30
|
+
// Keep this private generation after the issue resolves, so subsequent
|
|
31
|
+
// workers do not restart merely because the active row was removed.
|
|
32
|
+
state.set("source-retry", key, randomUUID());
|
|
33
|
+
state.set("set-aside", key, { ...value, retry: true });
|
|
34
|
+
}
|
|
30
35
|
});
|
|
31
36
|
} finally { state.close(); }
|
|
32
37
|
}
|
|
@@ -37,69 +42,9 @@ export function writeCaptureStatus(root, { pending = false } = {}) {
|
|
|
37
42
|
try {
|
|
38
43
|
backlog = readIssueBacklog(state.db, { pending });
|
|
39
44
|
} finally { state.close(); }
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
fd = openSync(temp, "wx", 0o600);
|
|
45
|
-
writeFileSync(fd, JSON.stringify(status) + "\n"); fsyncSync(fd); closeSync(fd); fd = undefined;
|
|
46
|
-
renameSync(temp, path);
|
|
47
|
-
} finally {
|
|
48
|
-
if (fd !== undefined) closeSync(fd);
|
|
49
|
-
try { unlinkSync(temp); } catch (err) { if (err.code !== "ENOENT") throw err; }
|
|
50
|
-
}
|
|
51
|
-
return status;
|
|
45
|
+
// Exact receipt callers update issue evidence, never erase prior worker run
|
|
46
|
+
// facts or turn their unbounded operation into a bounded-service success.
|
|
47
|
+
const prior = readCaptureStatus(root) ?? emptyCaptureStatus(backlog);
|
|
48
|
+
return persistCaptureStatus(root, { ...prior, backlog });
|
|
52
49
|
}
|
|
53
50
|
|
|
54
|
-
function validStatus(status) {
|
|
55
|
-
const b = status?.backlog;
|
|
56
|
-
return status?.schemaVersion === 1 && status.policy === null && status.lastRun === null && status.lastSuccess === null &&
|
|
57
|
-
status.lastFailure === null && status.lastProgressAt === null && typeof b?.pending === "boolean" &&
|
|
58
|
-
Number.isSafeInteger(b.setAsideCount) && b.setAsideCount >= 0 && Array.isArray(b.setAside) && b.setAside.length <= 100 &&
|
|
59
|
-
b.setAside.length === Math.min(b.setAsideCount, 100) && b.truncated === (b.setAsideCount > 100) &&
|
|
60
|
-
b.setAside.every(e => CAPTURE_SOURCES.includes(e.source) && typeof e.path === "string" && typeof e.reason === "string" &&
|
|
61
|
-
Number.isSafeInteger(e.offset) && e.offset >= 0 && (e.line === undefined || Number.isSafeInteger(e.line) && e.line > 0));
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
// Read-only, including a never-installed/absent root: no writable DB construction,
|
|
65
|
-
// directory creation, manager query, index rebuild or capture.
|
|
66
|
-
export function captureHealth(root) {
|
|
67
|
-
const path = join(root, "capture-status.json");
|
|
68
|
-
let status = { lastRun: null, lastSuccess: null, lastFailure: null,
|
|
69
|
-
backlog: { pending: false, setAsideCount: 0, setAside: [], truncated: false } };
|
|
70
|
-
const rows = [];
|
|
71
|
-
try {
|
|
72
|
-
const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
|
|
73
|
-
let text;
|
|
74
|
-
try {
|
|
75
|
-
const stat = fstatSync(fd);
|
|
76
|
-
if (!stat.isFile()) throw new Error("status is not a regular file");
|
|
77
|
-
const limit = 1024 * 1024;
|
|
78
|
-
if (stat.size > limit) throw new Error("status exceeds 1 MiB");
|
|
79
|
-
const bytes = Buffer.alloc(limit + 1);
|
|
80
|
-
let size = 0;
|
|
81
|
-
while (size < bytes.length) {
|
|
82
|
-
const count = readSync(fd, bytes, size, bytes.length - size, size);
|
|
83
|
-
if (!count) break;
|
|
84
|
-
size += count;
|
|
85
|
-
}
|
|
86
|
-
if (size > limit) throw new Error("status exceeds 1 MiB");
|
|
87
|
-
text = bytes.toString("utf8", 0, size);
|
|
88
|
-
} finally { closeSync(fd); }
|
|
89
|
-
const parsed = JSON.parse(text);
|
|
90
|
-
if (!validStatus(parsed)) throw new Error("unsupported or malformed status");
|
|
91
|
-
status = parsed;
|
|
92
|
-
} catch (err) {
|
|
93
|
-
if (err.code !== "ENOENT") rows.push({ code: "capture-status-invalid", message: `Cannot read capture status at ${path}: ${err.message}` });
|
|
94
|
-
}
|
|
95
|
-
let backlog;
|
|
96
|
-
try {
|
|
97
|
-
backlog = readCurrentIssueBacklog(root);
|
|
98
|
-
if (!backlog && status.backlog.setAsideCount) throw new Error("capture.db is missing but the last command reported active set-aside inputs");
|
|
99
|
-
} catch (err) { throw new Error(`Cannot read current capture issues at ${join(root, "index", "capture.db")}: ${err.message}`, { cause: err }); }
|
|
100
|
-
backlog ??= { pending: false, setAsideCount: 0, setAside: [], truncated: false };
|
|
101
|
-
if (backlog.setAsideCount) rows.push({ code: "capture-input-set-aside", message:
|
|
102
|
-
`${backlog.setAsideCount} capture inputs set aside. ${SET_ASIDE_REMEDY.replace("<root>", root)}` });
|
|
103
|
-
return { schemaVersion: 1, status: rows.length ? "warning" : "ok", rows,
|
|
104
|
-
lastRun: status.lastRun, lastSuccess: status.lastSuccess, lastFailure: status.lastFailure, backlog };
|
|
105
|
-
}
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
// Shared status format and atomic file I/O. This module neither creates a run
|
|
2
|
+
// nor infers success from counters. Only admitted command workers publish run
|
|
3
|
+
// facts; exact receipt commands may refresh backlog while retaining history.
|
|
4
|
+
import { randomUUID } from "node:crypto";
|
|
5
|
+
import { closeSync, constants, fstatSync, fsyncSync, openSync, readdirSync, readSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
|
|
6
|
+
import { join } from "node:path";
|
|
7
|
+
import { CAPTURE_POLICY } from "./capture-budget.mjs";
|
|
8
|
+
import { validFailureBacklog } from "./capture-failures.mjs";
|
|
9
|
+
|
|
10
|
+
export const CAPTURE_COUNT_FIELDS = Object.freeze(["filesVisited", "bytesCommitted", "turnsAppended", "turnsIndexed",
|
|
11
|
+
"inputsPending", "inputsSetAside", "inputsFailed", "inputsIgnored"]);
|
|
12
|
+
export const emptyCaptureCounts = () => Object.fromEntries(CAPTURE_COUNT_FIELDS.map(key => [key, 0]));
|
|
13
|
+
const triggers = new Set(["service", "hook", "setup", "manual", "watch"]);
|
|
14
|
+
const reasons = new Set(["deadline", "rss", "heap", "interrupted", "input", "io"]);
|
|
15
|
+
const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
16
|
+
const integer = value => Number.isSafeInteger(value) && value >= 0;
|
|
17
|
+
const exact = (value, required, optional = []) => object(value) && required.every(key => Object.hasOwn(value, key)) &&
|
|
18
|
+
Object.keys(value).every(key => required.includes(key) || optional.includes(key));
|
|
19
|
+
const stamp = (value, now) => typeof value === "string" && Number.isFinite(Date.parse(value)) &&
|
|
20
|
+
new Date(value).toISOString() === value && Date.parse(value) <= now;
|
|
21
|
+
const peak = value => value === null || integer(value);
|
|
22
|
+
const counts = value => exact(value, CAPTURE_COUNT_FIELDS) && CAPTURE_COUNT_FIELDS.every(key => integer(value[key]));
|
|
23
|
+
const reclaimed = (value, now) => exact(value, ["pid", "startedAt"]) && Number.isSafeInteger(value.pid) && value.pid > 0 &&
|
|
24
|
+
stamp(value.startedAt, now);
|
|
25
|
+
const identityKeys = ["id", "trigger", "pid", "startedAt"];
|
|
26
|
+
const summaryKeys = [...identityKeys, "finishedAt", "counts", "peakRssBytes"];
|
|
27
|
+
function identity(value, now) {
|
|
28
|
+
return object(value) && typeof value.id === "string" && value.id.length > 0 && triggers.has(value.trigger) &&
|
|
29
|
+
Number.isSafeInteger(value.pid) && value.pid > 0 && stamp(value.startedAt, now);
|
|
30
|
+
}
|
|
31
|
+
function summary(value, now, failure = false) {
|
|
32
|
+
return exact(value, [...summaryKeys, ...(failure ? ["reason", "message"] : [])], failure ? ["path", "offset"] : []) &&
|
|
33
|
+
identity(value, now) && stamp(value.finishedAt, now) && value.startedAt <= value.finishedAt && counts(value.counts) && peak(value.peakRssBytes) &&
|
|
34
|
+
(!failure || reasons.has(value.reason) && typeof value.message === "string" && value.message.length > 0 && value.message.length <= 2048 &&
|
|
35
|
+
(value.path === undefined || typeof value.path === "string") && (value.offset === undefined || integer(value.offset)));
|
|
36
|
+
}
|
|
37
|
+
function run(value, now) {
|
|
38
|
+
if (!exact(value, [...summaryKeys, "outcome", "reason", "reclaimedLock"]) || !identity(value, now) ||
|
|
39
|
+
!counts(value.counts) || !peak(value.peakRssBytes) ||
|
|
40
|
+
!["running", "complete", "partial", "failed"].includes(value.outcome) || value.reason !== null && !reasons.has(value.reason)) return false;
|
|
41
|
+
if (value.reclaimedLock !== null && !reclaimed(value.reclaimedLock, now)) return false;
|
|
42
|
+
if (value.outcome === "running") return value.finishedAt === null && value.reason === null;
|
|
43
|
+
return stamp(value.finishedAt, now) && value.startedAt <= value.finishedAt &&
|
|
44
|
+
(value.outcome !== "complete" || value.reason === null) && (value.outcome !== "failed" || value.reason !== null);
|
|
45
|
+
}
|
|
46
|
+
function backlog(value) {
|
|
47
|
+
return exact(value, ["pending", "setAsideCount", "setAside", "truncated"], ["failedCount", "failed", "failedTruncated"]) &&
|
|
48
|
+
typeof value.pending === "boolean" && integer(value.setAsideCount) && Array.isArray(value.setAside) &&
|
|
49
|
+
value.setAside.length === Math.min(value.setAsideCount, 100) && value.truncated === (value.setAsideCount > 100) &&
|
|
50
|
+
validFailureBacklog(value, { legacy: true }) &&
|
|
51
|
+
(value.failed === undefined || value.failed.every(row => exact(row, ["stream", "offset", "reason", "attempts", "nextRetryAt"]))) &&
|
|
52
|
+
value.setAside.every(row =>
|
|
53
|
+
exact(row, ["source", "path", "offset", "reason"], ["line"]) && ["aw", "cc", "pi", "codex"].includes(row.source) &&
|
|
54
|
+
typeof row.path === "string" && typeof row.reason === "string" && integer(row.offset) &&
|
|
55
|
+
(row.line === undefined || Number.isSafeInteger(row.line) && row.line > 0));
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export function validCaptureStatus(status, { now = Date.now() } = {}) {
|
|
59
|
+
if (!exact(status, ["schemaVersion", "policy", "lastRun", "lastSuccess", "lastFailure", "lastProgressAt", "backlog"]) ||
|
|
60
|
+
status.schemaVersion !== 1 || !backlog(status.backlog)) return false;
|
|
61
|
+
if (status.policy !== null && !(exact(status.policy, Object.keys(CAPTURE_POLICY)) &&
|
|
62
|
+
Object.keys(CAPTURE_POLICY).every(key => status.policy[key] === CAPTURE_POLICY[key]))) return false;
|
|
63
|
+
if (status.lastRun !== null && !run(status.lastRun, now) || status.lastSuccess !== null && !summary(status.lastSuccess, now) ||
|
|
64
|
+
status.lastFailure !== null && !summary(status.lastFailure, now, true) ||
|
|
65
|
+
status.lastProgressAt !== null && !stamp(status.lastProgressAt, now)) return false;
|
|
66
|
+
// Algorithm-phase nulls are valid absence of evidence; service facts cannot
|
|
67
|
+
// be published as an unqualified null-policy algorithm snapshot.
|
|
68
|
+
return status.policy !== null || [status.lastRun, status.lastSuccess, status.lastFailure, status.lastProgressAt].every(value => value === null);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// Reclaim evidence is optional. A dead owner record with a missing,
|
|
72
|
+
// nonstandard or future start (clock step, skewed shared home) is published
|
|
73
|
+
// as null rather than refusing this run's receipt.
|
|
74
|
+
export function captureReclaimedLock(value, { now = Date.now() } = {}) {
|
|
75
|
+
const evidence = value ? { pid: value.pid, startedAt: value.startedAt } : null;
|
|
76
|
+
return evidence && reclaimed(evidence, now) ? evidence : null;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export function emptyCaptureStatus(backlog) {
|
|
80
|
+
return { schemaVersion: 1, policy: null, lastRun: null, lastSuccess: null, lastFailure: null, lastProgressAt: null, backlog };
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
// The health transport carries the same nullable receipt/backlog components,
|
|
84
|
+
// without a policy/progress snapshot. Reuse their validators here; consumers
|
|
85
|
+
// validate this envelope, never read status or reinterpret diagnosis rules.
|
|
86
|
+
export function validCaptureHealthEnvelope(value, { now = Date.now() } = {}) {
|
|
87
|
+
return exact(value, ["schemaVersion", "status", "rows", "lastRun", "lastSuccess", "lastFailure", "backlog"]) &&
|
|
88
|
+
value.schemaVersion === 1 && Array.isArray(value.rows) &&
|
|
89
|
+
value.status === (value.rows.length ? "warning" : "ok") &&
|
|
90
|
+
value.rows.every(row => exact(row, ["code", "message"]) &&
|
|
91
|
+
typeof row.code === "string" && /^capture-[a-z]+(?:-[a-z]+)*$/.test(row.code) &&
|
|
92
|
+
typeof row.message === "string" && row.message.length > 0) &&
|
|
93
|
+
(value.lastRun === null || run(value.lastRun, now)) &&
|
|
94
|
+
(value.lastSuccess === null || summary(value.lastSuccess, now)) &&
|
|
95
|
+
(value.lastFailure === null || summary(value.lastFailure, now, true)) && backlog(value.backlog);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
export function readCaptureStatus(root, options) {
|
|
99
|
+
const path = join(root, "capture-status.json");
|
|
100
|
+
let fd;
|
|
101
|
+
try { fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK); }
|
|
102
|
+
catch (error) { if (error.code === "ENOENT") return null; throw error; }
|
|
103
|
+
let text;
|
|
104
|
+
try {
|
|
105
|
+
const stat = fstatSync(fd), limit = 1024 * 1024;
|
|
106
|
+
if (!stat.isFile() || stat.size > limit) throw new Error("capture status is not a regular file within 1 MiB");
|
|
107
|
+
const bytes = Buffer.alloc(limit + 1); let size = 0;
|
|
108
|
+
while (size < bytes.length) {
|
|
109
|
+
const count = readSync(fd, bytes, size, bytes.length - size, size);
|
|
110
|
+
if (!count) break; size += count;
|
|
111
|
+
}
|
|
112
|
+
if (size > limit) throw new Error("capture status exceeds 1 MiB");
|
|
113
|
+
text = bytes.toString("utf8", 0, size);
|
|
114
|
+
} finally { closeSync(fd); }
|
|
115
|
+
let parsed;
|
|
116
|
+
try { parsed = JSON.parse(text); } catch { throw new Error("malformed capture status JSON"); }
|
|
117
|
+
if (!validCaptureStatus(parsed, options)) throw new Error("unsupported, malformed or future-dated capture status");
|
|
118
|
+
return parsed;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const INVALID_PREFIX = "capture-status.json.invalid-";
|
|
122
|
+
function syncDirectory(path) {
|
|
123
|
+
const fd = openSync(path, constants.O_RDONLY);
|
|
124
|
+
try { fsyncSync(fd); } finally { closeSync(fd); }
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** A malformed, oversized, non-regular or future-dated status is no evidence
|
|
128
|
+
* and would stop every pass that reads it. It is moved aside, never
|
|
129
|
+
* overwritten, to `capture-status.json.invalid-<UTC stamp>` (the root
|
|
130
|
+
* directory synced after the rename), so the next publication starts from an
|
|
131
|
+
* empty status with no history; one moved-aside copy is kept. A system error
|
|
132
|
+
* reading it (permission, I/O, descriptors) says nothing about its content
|
|
133
|
+
* and is thrown, as is a failed rename: the original stays in place.
|
|
134
|
+
* → { path, reason, stale? } of the moved-aside copy (`stale` lists older
|
|
135
|
+
* copies that could not be removed), or null when the status is absent or
|
|
136
|
+
* readable. */
|
|
137
|
+
export function setAsideInvalidCaptureStatus(root, { now = Date.now() } = {}) {
|
|
138
|
+
let reason;
|
|
139
|
+
try { readCaptureStatus(root, { now }); return null; }
|
|
140
|
+
catch (error) { if (error.code) throw error; reason = error.message; }
|
|
141
|
+
const path = join(root, "capture-status.json");
|
|
142
|
+
const aside = join(root, INVALID_PREFIX + new Date(now).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z"));
|
|
143
|
+
const older = readdirSync(root).filter(name => name.startsWith(INVALID_PREFIX)).map(name => join(root, name)).filter(name => name !== aside);
|
|
144
|
+
try { renameSync(path, aside); }
|
|
145
|
+
catch (error) { throw new Error(`capture status ${path} is unreadable (${reason}) and could not be moved aside: ${error.message}; it was left in place`); }
|
|
146
|
+
// Moved but not confirmed durable: the error says where the status now is.
|
|
147
|
+
try { syncDirectory(root); }
|
|
148
|
+
catch (error) {
|
|
149
|
+
throw Object.assign(new Error(`capture status ${path} is unreadable (${reason}); it was moved aside to ${aside}, but syncing ${root} failed (${error.message}), so the move may not be durable`),
|
|
150
|
+
{ invalidStatus: { path: aside, reason } });
|
|
151
|
+
}
|
|
152
|
+
// The new copy is already safe: an older one that cannot go stays, reported.
|
|
153
|
+
const stale = older.filter(name => { try { unlinkSync(name); return false; } catch (error) { return error.code !== "ENOENT"; } });
|
|
154
|
+
if (older.length > stale.length) try { syncDirectory(root); } catch { /* the removals are diagnostics housekeeping */ }
|
|
155
|
+
return { path: aside, reason, ...(stale.length ? { stale } : {}) };
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
export function persistCaptureStatus(root, status, options) {
|
|
159
|
+
if (!validCaptureStatus(status, options)) throw new Error("refusing invalid capture status publication");
|
|
160
|
+
const path = join(root, "capture-status.json"), temp = `${path}.${randomUUID()}.tmp`;
|
|
161
|
+
let fd;
|
|
162
|
+
try {
|
|
163
|
+
fd = openSync(temp, "wx", 0o600);
|
|
164
|
+
writeFileSync(fd, JSON.stringify(status) + "\n"); fsyncSync(fd); closeSync(fd); fd = undefined;
|
|
165
|
+
renameSync(temp, path);
|
|
166
|
+
} finally {
|
|
167
|
+
if (fd !== undefined) closeSync(fd);
|
|
168
|
+
try { unlinkSync(temp); } catch (error) { if (error.code !== "ENOENT") throw error; }
|
|
169
|
+
}
|
|
170
|
+
return status;
|
|
171
|
+
}
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
// Private process transport, separate from reconciliation and status writing.
|
|
2
|
+
// The caller supplies the package worker entry; no shell, inherited execArgv,
|
|
3
|
+
// or caller-controlled NODE_OPTIONS can override its fixed heap policy.
|
|
4
|
+
import { spawn } from "node:child_process";
|
|
5
|
+
import { CAPTURE_POLICY } from "./capture-budget.mjs";
|
|
6
|
+
import { acquireCaptureLock } from "./capture-lock.mjs";
|
|
7
|
+
|
|
8
|
+
// hrtime uses the same monotonic origin in both local processes. Startup and
|
|
9
|
+
// lock publication consume this budget; the child never starts a new 300s clock.
|
|
10
|
+
export const captureMonotonicMs = () => Number(process.hrtime.bigint() / 1000000n);
|
|
11
|
+
// A signal received during synchronous work stays pending until a poll phase.
|
|
12
|
+
// One setImmediate can resume before that phase; two hops allow one between.
|
|
13
|
+
export const captureSignalPoll = () => new Promise(resolve => setImmediate(() => setImmediate(resolve)));
|
|
14
|
+
export function captureWorkerEnvironment(env = process.env) {
|
|
15
|
+
const out = {};
|
|
16
|
+
for (const key of ["HOME", "PATH", "TMPDIR", "TMP", "TEMP", "XDG_CACHE_HOME", "XDG_CONFIG_HOME", "LANG", "LC_ALL", "TZ", "USERPROFILE", "SYSTEMROOT"])
|
|
17
|
+
if (env[key] !== undefined) out[key] = env[key];
|
|
18
|
+
return out;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
const outcomes = new Set(["complete", "partial", "failed"]);
|
|
22
|
+
const reasons = new Set([null, "deadline", "rss", "heap", "interrupted", "input", "io"]);
|
|
23
|
+
const MESSAGE_LENGTH = 512, CONTROL = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
|
|
24
|
+
// A failed worker's private one-line diagnostic for the supervising command's
|
|
25
|
+
// stderr, never published status. Parser messages can quote input bytes, so a
|
|
26
|
+
// SyntaxError is reduced to its class name.
|
|
27
|
+
export function captureWorkerMessage(error) {
|
|
28
|
+
const text = error instanceof SyntaxError ? "SyntaxError" : error instanceof Error ? String(error.message) : "non-Error exception";
|
|
29
|
+
const message = text.replace(new RegExp(CONTROL.source + "+", "g"), " ").trim().slice(0, MESSAGE_LENGTH).replace(/[\ud800-\udbff]$/, "").trim();
|
|
30
|
+
return message || "unexplained operational failure";
|
|
31
|
+
}
|
|
32
|
+
export function validWorkerResult(value) {
|
|
33
|
+
return value && outcomes.has(value.outcome) && reasons.has(value.reason) &&
|
|
34
|
+
(value.outcome !== "complete" || value.reason === null) &&
|
|
35
|
+
(value.outcome !== "failed" || value.reason !== null) &&
|
|
36
|
+
(value.message === undefined || value.outcome === "failed" && typeof value.message === "string" &&
|
|
37
|
+
value.message.length > 0 && value.message.length <= MESSAGE_LENGTH && !CONTROL.test(value.message)) &&
|
|
38
|
+
(value.continuation === undefined || typeof value.continuation === "boolean") &&
|
|
39
|
+
(value.resetRequired === undefined || value.resetRequired === true && value.outcome === "partial" && value.continuation === true) &&
|
|
40
|
+
!(value.outcome === "complete" && value.continuation);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** Internal seams are for isolated tests, not public tuning. Only the worker
|
|
44
|
+
* writes run/status facts. The supervisor owns admission, process lifetime and
|
|
45
|
+
* its command result; a forced death leaves an unfinished worker receipt.
|
|
46
|
+
*
|
|
47
|
+
* TERM/INT is a cooperative stop: a started worker is asked, through its own
|
|
48
|
+
* owner record, to stop at its next bounded check and write its interrupted
|
|
49
|
+
* receipt. The first signal starts one grace (`graceMs`, capped by the
|
|
50
|
+
* absolute deadline) after which the exact child is killed; later signals
|
|
51
|
+
* neither shorten nor extend it. A child not yet started is killed at once. */
|
|
52
|
+
export async function superviseCapture(root, options, {
|
|
53
|
+
workerPath, policy = CAPTURE_POLICY, drainSeconds = 5, graceMs = 5000,
|
|
54
|
+
executable = process.execPath, env = process.env, clock = captureMonotonicMs,
|
|
55
|
+
acquire = acquireCaptureLock, spawnChild = spawn,
|
|
56
|
+
window, pass,
|
|
57
|
+
} = {}) {
|
|
58
|
+
if (typeof workerPath !== "string" || !workerPath) throw new Error("capture worker entry is required");
|
|
59
|
+
if (window && (![window.drainAt, window.finalizeAt, window.hardAt].every(Number.isFinite) ||
|
|
60
|
+
window.drainAt > window.finalizeAt || window.finalizeAt > window.hardAt)) throw new Error("invalid capture child time window");
|
|
61
|
+
const started = clock(), deadline = Math.min(started + policy.deadlineSeconds * 1000, window?.hardAt ?? Infinity);
|
|
62
|
+
const drainAt = Math.min(deadline, window?.drainAt ?? Math.max(started, deadline - drainSeconds * 1000));
|
|
63
|
+
const finalizeAt = Math.min(deadline, window?.finalizeAt ?? deadline);
|
|
64
|
+
const lock = acquire(root);
|
|
65
|
+
if (!lock.release) return { outcome: "overlap", reason: null, exitCode: 0, held: lock.held };
|
|
66
|
+
let child, timer, grace, finish, forced, result, admitted = false, ready = false, diagnostics = "", outputBytes = 0;
|
|
67
|
+
const stop = reason => {
|
|
68
|
+
forced ??= reason;
|
|
69
|
+
// ChildProcess owns this exact child until exit/reaping. Never derive a
|
|
70
|
+
// process group, or signal a PID recovered from a persisted lock record.
|
|
71
|
+
if (child?.pid > 0 && child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
|
|
72
|
+
};
|
|
73
|
+
const interrupted = () => {
|
|
74
|
+
if (grace !== undefined || forced) return;
|
|
75
|
+
if (!admitted) { stop("interrupted"); return; }
|
|
76
|
+
// A worker that already sent its result keeps it; it still must exit
|
|
77
|
+
// within the same grace.
|
|
78
|
+
if (!result) {
|
|
79
|
+
try { lock.requestStop(); } catch { stop("interrupted"); return; }
|
|
80
|
+
}
|
|
81
|
+
grace = setTimeout(() => stop("interrupted"), Math.max(0, Math.min(deadline, clock() + graceMs) - clock()));
|
|
82
|
+
};
|
|
83
|
+
try {
|
|
84
|
+
process.on("SIGTERM", interrupted); process.on("SIGINT", interrupted);
|
|
85
|
+
child = spawnChild(executable, [`--max-old-space-size=${policy.heapMiB}`, "--no-warnings",
|
|
86
|
+
// Node 22.5–22.12 need this flag. It does not import SQLite or alter the
|
|
87
|
+
// heap, and unlike execArgv it cannot forward arbitrary preload code.
|
|
88
|
+
...(Number(process.versions.node.split(".")[0]) === 22 && Number(process.versions.node.split(".")[1]) < 13 ? ["--experimental-sqlite"] : []),
|
|
89
|
+
workerPath], { env: captureWorkerEnvironment(env), stdio: ["ignore", "ignore", "pipe", "ipc"], serialization: "json" });
|
|
90
|
+
finish = new Promise(resolve => {
|
|
91
|
+
let spawnError;
|
|
92
|
+
child.once("error", () => { spawnError = true; stop("io"); });
|
|
93
|
+
child.once("close", (code, signal) => resolve({ code, signal, spawnError }));
|
|
94
|
+
});
|
|
95
|
+
child.stderr?.on("data", chunk => {
|
|
96
|
+
outputBytes += chunk.length;
|
|
97
|
+
if (outputBytes > 64 * 1024) { stop("io"); return; }
|
|
98
|
+
diagnostics += chunk.toString("utf8");
|
|
99
|
+
});
|
|
100
|
+
child.on("message", message => {
|
|
101
|
+
if (forced) return;
|
|
102
|
+
if (!ready && message?.type === "ready" && message.pid === child.pid &&
|
|
103
|
+
typeof message.nonce === "string" && /^[a-f0-9]{32}$/.test(message.nonce) &&
|
|
104
|
+
typeof message.startedAt === "string" && Number.isFinite(Date.parse(message.startedAt))) {
|
|
105
|
+
ready = true;
|
|
106
|
+
try {
|
|
107
|
+
lock.registerWorker(message);
|
|
108
|
+
if (clock() >= deadline) { stop("deadline"); return; }
|
|
109
|
+
admitted = true;
|
|
110
|
+
child.send({ type: "start", root, options, policy, parent: { pid: process.pid, nonce: lock.nonce },
|
|
111
|
+
workerNonce: message.nonce, drainAt, finalizeAt, hardAt: deadline, pass,
|
|
112
|
+
reclaimedLock: lock.reclaimed ?? null }, error => { if (error) stop("io"); });
|
|
113
|
+
} catch { stop("io"); }
|
|
114
|
+
} else if (ready && !result && message?.type === "result" && validWorkerResult(message.result)) {
|
|
115
|
+
result = message.result;
|
|
116
|
+
} else stop("io");
|
|
117
|
+
});
|
|
118
|
+
timer = setTimeout(() => stop("deadline"), Math.max(0, deadline - clock()));
|
|
119
|
+
const ended = await finish;
|
|
120
|
+
if (forced || ended.spawnError || ended.signal || !result || ended.code !== (result.outcome === "failed" ? 1 : 0)) {
|
|
121
|
+
const heap = /heap out of memory|allocation failed.*heap/i.test(diagnostics);
|
|
122
|
+
return { outcome: "failed", reason: heap ? "heap" : forced ?? (ended.signal ? "interrupted" : "io"), exitCode: 1 };
|
|
123
|
+
}
|
|
124
|
+
return { ...result, exitCode: result.outcome === "failed" ? 1 : 0 };
|
|
125
|
+
} catch {
|
|
126
|
+
stop("io");
|
|
127
|
+
if (finish) await finish;
|
|
128
|
+
return { outcome: "failed", reason: "io", exitCode: 1 };
|
|
129
|
+
} finally {
|
|
130
|
+
clearTimeout(timer); clearTimeout(grace);
|
|
131
|
+
process.off("SIGTERM", interrupted); process.off("SIGINT", interrupted);
|
|
132
|
+
const released = lock.release();
|
|
133
|
+
// Cleanup failure is an operational error even after a successful worker.
|
|
134
|
+
if (!released.released) throw Object.assign(new Error("capture supervisor could not release its lock"), { release: released });
|
|
135
|
+
}
|
|
136
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
// Foreground notification scheduling only. A queued event never authorizes
|
|
2
|
+
// capture, selects roots or certifies progress; each pass owns those decisions.
|
|
3
|
+
export function captureWatchQueue(run, { onError = error => console.error(error), delay = 2000, setTimer = setTimeout, clearTimer = clearTimeout } = {}) {
|
|
4
|
+
let timer = null, active = null, pending = false, closed = false;
|
|
5
|
+
const drain = async () => {
|
|
6
|
+
while (pending && !closed) {
|
|
7
|
+
pending = false;
|
|
8
|
+
try { await run(); } catch (error) {
|
|
9
|
+
// A broken diagnostic sink must not strand the queue or turn a timer
|
|
10
|
+
// callback into an unhandled rejection. It supplies no run evidence.
|
|
11
|
+
try { onError(error); } catch { /* best-effort diagnostics */ }
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
};
|
|
15
|
+
const ready = () => {
|
|
16
|
+
timer = null;
|
|
17
|
+
if (closed) return;
|
|
18
|
+
pending = true;
|
|
19
|
+
if (!active) active = drain().finally(() => { active = null; });
|
|
20
|
+
};
|
|
21
|
+
return {
|
|
22
|
+
schedule() {
|
|
23
|
+
if (closed) return;
|
|
24
|
+
if (timer !== null) clearTimer(timer);
|
|
25
|
+
timer = setTimer(ready, delay);
|
|
26
|
+
},
|
|
27
|
+
// Do not abandon an admitted child. Its supervisor handles signals and
|
|
28
|
+
// reaps it; closing only cancels future notification-driven passes.
|
|
29
|
+
close() { closed = true; pending = false; if (timer !== null) clearTimer(timer); timer = null; },
|
|
30
|
+
async settled() { await active; },
|
|
31
|
+
};
|
|
32
|
+
}
|