@gtrabanco/agentic-workflow 0.2.0 → 0.4.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 +50 -0
- package/bin/agentic-workflow.mjs +29 -1
- package/package.json +3 -3
- package/src/doc/chunks.mjs +5 -1
- package/src/doc/config.mjs +63 -19
- package/src/doc/query.mjs +57 -9
- package/src/doc/retrieval.mjs +15 -2
- package/src/doc/store.mjs +7 -9
- package/src/doc/sync.mjs +34 -17
- package/src/edit/UnitDoc.mjs +199 -11
- package/src/edit/schema.mjs +45 -1
- package/src/memory/probe.mjs +388 -0
package/README.md
CHANGED
|
@@ -21,3 +21,53 @@ repository's `scripts/` tree (feature 37 ED1). Feature 38's
|
|
|
21
21
|
crate existed, so re-homing it here is a recorded follow-up (feature 37
|
|
22
22
|
ED8.4c) with no unit assigned yet; feature 42 is the next candidate to add the
|
|
23
23
|
first crate subcommand.
|
|
24
|
+
|
|
25
|
+
## `memory probe` — bounded memory-substrate health (feature 66)
|
|
26
|
+
|
|
27
|
+
One command answers "can this session trust the Engram memory layer?" before
|
|
28
|
+
its first memory read. It writes nothing, issues no MCP tool call (only
|
|
29
|
+
`initialize`), and **always exits 0** — a `degraded` verdict is an answer to
|
|
30
|
+
record, never a failure that blocks a unit.
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
agentic-workflow memory probe # human block
|
|
34
|
+
agentic-workflow memory probe --json # memory-probe@1 verdict
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Five checks, fixed order. `ok` requires all five; any failure makes the whole
|
|
38
|
+
verdict `degraded` and names the failing checks:
|
|
39
|
+
|
|
40
|
+
| check | source | bound |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| `http-health` | `GET http://127.0.0.1:7437/health`, body `status` must be `ok` | 4 s |
|
|
43
|
+
| `mcp-runner` | one JSON-RPC `initialize` to `engram mcp --tools=agent` | 4 s |
|
|
44
|
+
| `binary-version` | `engram --version` | 4 s |
|
|
45
|
+
| `sync-staleness` | `engram sync --status`, `Pending import` must be 0 | 10 s |
|
|
46
|
+
| `session-ambiguity` | `engram doctor --json --check` on `ambiguous_active_runtime_sessions` + `sync_target_closed_space`, every non-`ok` answer reported | 10 s |
|
|
47
|
+
|
|
48
|
+
The checks are independent, so they run together: the probe costs the slowest
|
|
49
|
+
bound (10 s), never the sum of five (32 s). Whole-probe ceiling: 30 s, which is
|
|
50
|
+
the backstop for a dependency that ignored its own bound. A bound hit fails that
|
|
51
|
+
check and degrades the verdict — never a hang.
|
|
52
|
+
|
|
53
|
+
Three rules are load-bearing and measured, not assumed:
|
|
54
|
+
|
|
55
|
+
- **Exit code is not a health signal.** `engram doctor` exits 0 while its JSON
|
|
56
|
+
reports `status: "error"`, so every check parses the answer instead of
|
|
57
|
+
trusting the status code.
|
|
58
|
+
- **A responding server that has not synced is not `ok`.** That is why
|
|
59
|
+
`sync-staleness` is a check, and why an unreadable status (e.g. `ambiguous
|
|
60
|
+
project` outside a repo) is a degradation rather than a pass.
|
|
61
|
+
- **One answer never hides another.** The session check asks both scoped
|
|
62
|
+
`--check` ids and reports every non-`ok` finding. Stopping at the first would
|
|
63
|
+
silence the sync-target signal permanently on a machine whose session
|
|
64
|
+
attribution is ambiguous — which is the state this unit's own SPEC records.
|
|
65
|
+
- **`degraded` is reportable, not fatal.** The caller records the verdict in
|
|
66
|
+
the unit's Evidence and keeps working.
|
|
67
|
+
|
|
68
|
+
The full `engram doctor --json` sweep is deliberately excluded: it costs 12–23 s
|
|
69
|
+
at this repository and the two scoped `--check` calls answer the same question
|
|
70
|
+
in under half a second each. `runProbe({ fetchImpl, runImpl, timeoutMs,
|
|
71
|
+
totalTimeoutMs })` takes its side effects by injection, so the suite drives
|
|
72
|
+
every degraded path with fakes and millisecond bounds — no network, no PATH, no
|
|
73
|
+
real engram process.
|
package/bin/agentic-workflow.mjs
CHANGED
|
@@ -9,11 +9,16 @@
|
|
|
9
9
|
* agentic-workflow budgets <op> [args...]
|
|
10
10
|
* agentic-workflow manifest <op> [args...]
|
|
11
11
|
* agentic-workflow doc (--sync | --query <term> | --status | --rebuild) [--json-only]
|
|
12
|
+
* agentic-workflow memory probe [--json]
|
|
12
13
|
*
|
|
13
14
|
* --json prints the operation receipt as JSON.
|
|
14
15
|
* Every operation prints a fixed receipt block to stdout.
|
|
15
16
|
*
|
|
16
17
|
* Refusals exit 2 with "EDIT REFUSAL — <reason>" before writing anything.
|
|
18
|
+
*
|
|
19
|
+
* `memory probe` is a sensor, not an editor: it writes nothing and always
|
|
20
|
+
* exits 0. Its `degraded` verdict is an answer to report, never a failure
|
|
21
|
+
* that blocks the caller (feature 66, AC2).
|
|
17
22
|
*/
|
|
18
23
|
|
|
19
24
|
import { readFileSync } from "node:fs";
|
|
@@ -27,6 +32,7 @@ import { ceilingRebase } from "../src/edit/Budgets.mjs";
|
|
|
27
32
|
import { skillAdd, skillRemove } from "../src/edit/Manifest.mjs";
|
|
28
33
|
import { parseDocArgs } from "../src/doc/grammar.mjs";
|
|
29
34
|
import { runDocOp } from "../src/doc/retrieval.mjs";
|
|
35
|
+
import { runProbe } from "../src/memory/probe.mjs";
|
|
30
36
|
|
|
31
37
|
// ── Helpers ──────────────────────────────────────────────────────────────
|
|
32
38
|
|
|
@@ -66,7 +72,7 @@ function refuse(reason) {
|
|
|
66
72
|
|
|
67
73
|
const command = process.argv[2];
|
|
68
74
|
if (!command) {
|
|
69
|
-
console.error("usage: agentic-workflow <unit-doc|roadmap|changelog|budgets|manifest|doc> ...");
|
|
75
|
+
console.error("usage: agentic-workflow <unit-doc|roadmap|changelog|budgets|manifest|doc|memory> ...");
|
|
70
76
|
process.exit(1);
|
|
71
77
|
}
|
|
72
78
|
|
|
@@ -114,6 +120,28 @@ switch (command) {
|
|
|
114
120
|
break;
|
|
115
121
|
}
|
|
116
122
|
|
|
123
|
+
// ── memory — bounded memory-substrate health probe (unit 66, P1) ────
|
|
124
|
+
case "memory": {
|
|
125
|
+
const op = rawArgs[0];
|
|
126
|
+
if (op !== "probe") refuse(`memory requires the \`probe\` operation, got "${op ?? ""}"`);
|
|
127
|
+
const report = await runProbe();
|
|
128
|
+
if (parsed.json) {
|
|
129
|
+
process.stdout.write(JSON.stringify(report) + "\n");
|
|
130
|
+
} else {
|
|
131
|
+
console.log(`MEMORY PROBE — ${report.verdict}`);
|
|
132
|
+
for (const check of report.checks) {
|
|
133
|
+
const mark = check.status === "ok" ? "ok" : `failed:${check.reason}`;
|
|
134
|
+
console.log(` ${check.id} · ${mark} · ${check.detail}`);
|
|
135
|
+
}
|
|
136
|
+
if (report.degraded.length > 0) {
|
|
137
|
+
console.log(`Degraded: ${report.degraded.join(", ")} — record this in Evidence, keep working`);
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
// A sensor that exits non-zero for a healthy machine's degraded layer
|
|
141
|
+
// would block the very units it exists to protect (AC2 non-goal).
|
|
142
|
+
break;
|
|
143
|
+
}
|
|
144
|
+
|
|
117
145
|
// ── unit-doc ─────────────────────────────────────────────────────────
|
|
118
146
|
case "unit-doc": {
|
|
119
147
|
const slug = rawArgs[0];
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gtrabanco/agentic-workflow",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Deterministic runner for the agentic-workflow lane: file services (agwo edit), sensors, guards and receipts.
|
|
3
|
+
"version": "0.4.0",
|
|
4
|
+
"description": "Deterministic runner for the agentic-workflow lane: file services (agwo edit), sensors, guards and receipts. One pinned pure-JS dependency, no native deps, no build step.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>",
|
|
7
7
|
"repository": {
|
|
@@ -27,6 +27,6 @@
|
|
|
27
27
|
"README.md"
|
|
28
28
|
],
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"typebox": "1.3
|
|
30
|
+
"typebox": "1.4.3"
|
|
31
31
|
}
|
|
32
32
|
}
|
package/src/doc/chunks.mjs
CHANGED
|
@@ -58,7 +58,11 @@ function parseFrontmatter(lines) {
|
|
|
58
58
|
* document order. Deterministic: identical input ⇒ identical output.
|
|
59
59
|
*/
|
|
60
60
|
export function scanChunks(markdown, relativePath) {
|
|
61
|
-
const
|
|
61
|
+
const content = String(markdown);
|
|
62
|
+
const lines = content.split(/\r?\n/);
|
|
63
|
+
// A file ending in a newline splits into one phantom trailing element; it is
|
|
64
|
+
// not a line, and counting it overshoots every last chunk's line_end (F47).
|
|
65
|
+
if (lines.length > 1 && lines[lines.length - 1] === "" && /\r?\n$/.test(content)) lines.pop();
|
|
62
66
|
|
|
63
67
|
// Frontmatter block, only when it opens the file.
|
|
64
68
|
let contentStart = 0;
|
package/src/doc/config.mjs
CHANGED
|
@@ -9,8 +9,8 @@
|
|
|
9
9
|
* an unknown version fails closed — the reader never guesses.
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
|
-
import { existsSync, readFileSync } from "node:fs";
|
|
13
|
-
import { join, resolve, sep } from "node:path";
|
|
12
|
+
import { existsSync, readFileSync, realpathSync } from "node:fs";
|
|
13
|
+
import { dirname, join, resolve, sep } from "node:path";
|
|
14
14
|
|
|
15
15
|
export const CONFIG_VERSION = 1;
|
|
16
16
|
|
|
@@ -27,14 +27,63 @@ export function configPath(root) {
|
|
|
27
27
|
return join(root, ".agentic-workflow", "index.json");
|
|
28
28
|
}
|
|
29
29
|
|
|
30
|
+
/**
|
|
31
|
+
* Realpath of the deepest EXISTING ancestor of `p`, with the not-yet-existing
|
|
32
|
+
* tail re-joined lexically (F36): the configured store leaf usually does not
|
|
33
|
+
* exist yet, but its intermediate directories do — and an intermediate
|
|
34
|
+
* symlink escaping the repository must be caught before any write.
|
|
35
|
+
*/
|
|
36
|
+
function realpathDeepest(p) {
|
|
37
|
+
const tail = [];
|
|
38
|
+
let cur = p;
|
|
39
|
+
while (!existsSync(cur)) {
|
|
40
|
+
const parent = dirname(cur);
|
|
41
|
+
if (parent === cur) return cur; // filesystem root — nothing to resolve
|
|
42
|
+
tail.unshift(cur.slice(parent.length + 1));
|
|
43
|
+
cur = parent;
|
|
44
|
+
}
|
|
45
|
+
return join(realpathSync(cur), ...tail);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Contain a configured `store.path` inside the repository's gitignored
|
|
50
|
+
* `.agentic-workflow/` directory (F36/F37, decision D12):
|
|
51
|
+
* - F37: a store outside `.agentic-workflow/` leaves `git status` dirty
|
|
52
|
+
* after `--sync` (AC7) — the configured store must stay inside the only
|
|
53
|
+
* directory the committed ignore rules cover;
|
|
54
|
+
* - F36: containment is anchored at `realpath(root)` and the candidate is
|
|
55
|
+
* resolved through the realpath of its deepest existing ancestor, so a
|
|
56
|
+
* symlinked intermediate directory (or a symlinked `.agentic-workflow`
|
|
57
|
+
* itself) fails closed — `--rebuild`'s `rmSync` targets this path, so a
|
|
58
|
+
* misconfigured store path is a destructive-write footgun.
|
|
59
|
+
*/
|
|
60
|
+
function containStorePath(root, candidate) {
|
|
61
|
+
const anchoredRoot = realpathDeepest(resolve(root));
|
|
62
|
+
const workflowRoot = join(anchoredRoot, ".agentic-workflow");
|
|
63
|
+
const resolvedCandidate = realpathDeepest(resolve(root, candidate));
|
|
64
|
+
if (!resolvedCandidate.startsWith(workflowRoot + sep)) {
|
|
65
|
+
throw new Error(
|
|
66
|
+
`index.json store.path "${candidate}" must stay inside .agentic-workflow/ (got "${resolvedCandidate}")`,
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
30
71
|
/**
|
|
31
72
|
* Load the config for the project at `root`: defaults merged under the
|
|
32
|
-
* file's overrides. Throws on unparseable JSON (message names the file)
|
|
33
|
-
* on an unknown `version` (fail closed).
|
|
73
|
+
* file's overrides. Throws on unparseable JSON (message names the file),
|
|
74
|
+
* on an unknown `version` (fail closed), and on a `store.path` outside the
|
|
75
|
+
* gitignored `.agentic-workflow/` directory (F36/F37 containment).
|
|
34
76
|
*/
|
|
35
77
|
export function loadConfig(root) {
|
|
36
78
|
const path = configPath(root);
|
|
37
|
-
if (!existsSync(path))
|
|
79
|
+
if (!existsSync(path)) {
|
|
80
|
+
// F50: the absent-config branch is NOT a containment bypass — the merged
|
|
81
|
+
// default store path runs through the same check, so a symlinked
|
|
82
|
+
// `.agentic-workflow` fails closed even with no index.json on disk.
|
|
83
|
+
const merged = structuredClone(DEFAULT_CONFIG);
|
|
84
|
+
containStorePath(root, merged.store.path);
|
|
85
|
+
return merged;
|
|
86
|
+
}
|
|
38
87
|
let parsed;
|
|
39
88
|
try {
|
|
40
89
|
parsed = JSON.parse(readFileSync(path, "utf8"));
|
|
@@ -47,18 +96,13 @@ export function loadConfig(root) {
|
|
|
47
96
|
if (parsed.version !== undefined && parsed.version !== CONFIG_VERSION) {
|
|
48
97
|
throw new Error(`index.json version ${parsed.version} is not supported (expected ${CONFIG_VERSION})`);
|
|
49
98
|
}
|
|
50
|
-
// Contain store
|
|
51
|
-
//
|
|
52
|
-
//
|
|
53
|
-
//
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
`index.json store.path "${candidate}" escapes the repository root (${root})`,
|
|
60
|
-
);
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
|
-
return { ...structuredClone(DEFAULT_CONFIG), ...parsed };
|
|
99
|
+
// Contain the MERGED store path inside the repository's gitignored
|
|
100
|
+
// `.agentic-workflow/` directory (F36/F37/F50, decision D12) — see
|
|
101
|
+
// containStorePath. Runs on every branch: an explicit `store.path`, a
|
|
102
|
+
// config without a `store` key, and the absent-config default alike.
|
|
103
|
+
const merged = { ...structuredClone(DEFAULT_CONFIG), ...parsed };
|
|
104
|
+
// storePath() falls back to the default when `store.path` is falsy —
|
|
105
|
+
// contain exactly the path that will be used.
|
|
106
|
+
containStorePath(root, merged.store?.path || DEFAULT_CONFIG.store.path);
|
|
107
|
+
return merged;
|
|
64
108
|
}
|
package/src/doc/query.mjs
CHANGED
|
@@ -153,11 +153,34 @@ export async function queryIndex(root, term, filters = {}, opts = {}) {
|
|
|
153
153
|
store,
|
|
154
154
|
});
|
|
155
155
|
}
|
|
156
|
+
// F39: the store-wide pin is not enough — a row embedded under a foreign
|
|
157
|
+
// model (or left unmodelled by an older schema) must fail closed too.
|
|
158
|
+
const foreignRows = db
|
|
159
|
+
.prepare(
|
|
160
|
+
"select count(*) as n from chunks where embedding is not null and (emb_model is null or emb_model is not ?)",
|
|
161
|
+
)
|
|
162
|
+
.get(provider.model).n;
|
|
163
|
+
if (foreignRows > 0) {
|
|
164
|
+
db.close();
|
|
165
|
+
return buildEnvelope({
|
|
166
|
+
command: "query",
|
|
167
|
+
results: toResults(keywordRows, hasLogFilters, filters),
|
|
168
|
+
degradations: ["embeddings-model-mismatch"],
|
|
169
|
+
store,
|
|
170
|
+
});
|
|
171
|
+
}
|
|
156
172
|
try {
|
|
157
173
|
const [queryVector] = await provider.embed([term]);
|
|
158
174
|
const vectorRows = vectorTopK(db, queryVector, MATCH_POOL);
|
|
159
|
-
db.close();
|
|
160
175
|
const fused = fuseRrf(keywordRows, vectorRows);
|
|
176
|
+
// F46: chunk bodies are huge (≈9 MB across this repo's corpus) and are
|
|
177
|
+
// needed only for log-entry rows (the AC14 metadata). Fetch them for the
|
|
178
|
+
// fused candidates that can reach a result row — never for the whole scan.
|
|
179
|
+
for (const r of fused) {
|
|
180
|
+
if (r.path === LOGS_PATH && r.body === undefined) {
|
|
181
|
+
r.body = db.prepare("select body from chunks where chunk_id = ?").get(r.chunk_id)?.body ?? "";
|
|
182
|
+
}
|
|
183
|
+
}
|
|
161
184
|
const results = toResults(
|
|
162
185
|
fused.map((r) => ({ ...r, rank: -r.fusedScore })),
|
|
163
186
|
hasLogFilters,
|
|
@@ -165,7 +188,16 @@ export async function queryIndex(root, term, filters = {}, opts = {}) {
|
|
|
165
188
|
);
|
|
166
189
|
return buildEnvelope({ command: "query", results, degradations: [], store });
|
|
167
190
|
} catch (e) {
|
|
168
|
-
|
|
191
|
+
// F40: a stored vector whose dimensionality differs from the query
|
|
192
|
+
// vector is corrupt or foreign-shaped — degrade, never truncate-and-rank.
|
|
193
|
+
if (e instanceof VectorShapeMismatch) {
|
|
194
|
+
return buildEnvelope({
|
|
195
|
+
command: "query",
|
|
196
|
+
results: toResults(keywordRows, hasLogFilters, filters),
|
|
197
|
+
degradations: ["embeddings-model-mismatch"],
|
|
198
|
+
store,
|
|
199
|
+
});
|
|
200
|
+
}
|
|
169
201
|
// AC17: provider down ⇒ declared cause, keyword results survive.
|
|
170
202
|
return buildEnvelope({
|
|
171
203
|
command: "query",
|
|
@@ -173,6 +205,8 @@ export async function queryIndex(root, term, filters = {}, opts = {}) {
|
|
|
173
205
|
degradations: ["unavailable-embeddings-provider-down"],
|
|
174
206
|
store,
|
|
175
207
|
});
|
|
208
|
+
} finally {
|
|
209
|
+
db.close();
|
|
176
210
|
}
|
|
177
211
|
}
|
|
178
212
|
|
|
@@ -191,11 +225,14 @@ function toResults(rows, hasLogFilters, filters) {
|
|
|
191
225
|
meta = {};
|
|
192
226
|
}
|
|
193
227
|
const isLog = r.path === LOGS_PATH;
|
|
194
|
-
if (isLog
|
|
195
|
-
const entry = parseLogEntry(r.body);
|
|
196
|
-
if (
|
|
197
|
-
|
|
198
|
-
|
|
228
|
+
if (isLog) {
|
|
229
|
+
const entry = r.body === undefined ? null : parseLogEntry(r.body); // F46: parsed once per row
|
|
230
|
+
if (hasLogFilters) {
|
|
231
|
+
if (entry === null || !logEntryMatches(entry, filters)) continue;
|
|
232
|
+
meta = entry;
|
|
233
|
+
} else if (entry !== null) {
|
|
234
|
+
meta = entry;
|
|
235
|
+
}
|
|
199
236
|
} else if (hasLogFilters) {
|
|
200
237
|
continue; // structured filters narrow to log entries by definition
|
|
201
238
|
}
|
|
@@ -224,11 +261,19 @@ export async function statusIndex(root) {
|
|
|
224
261
|
|
|
225
262
|
const RRF_K = 60;
|
|
226
263
|
|
|
264
|
+
/** A stored vector's dimensionality differs from the query vector (F40). */
|
|
265
|
+
class VectorShapeMismatch extends Error {}
|
|
266
|
+
|
|
227
267
|
function cosine(a, b) {
|
|
268
|
+
if (a.length !== b.length) {
|
|
269
|
+
// F40: truncating to the shorter vector ranked confidently on garbage;
|
|
270
|
+
// a shape mismatch is a corrupt or foreign-model vector — fail closed.
|
|
271
|
+
throw new VectorShapeMismatch(`vector dimension mismatch: ${a.length} vs ${b.length}`);
|
|
272
|
+
}
|
|
228
273
|
let dot = 0;
|
|
229
274
|
let na = 0;
|
|
230
275
|
let nb = 0;
|
|
231
|
-
const n =
|
|
276
|
+
const n = a.length;
|
|
232
277
|
for (let i = 0; i < n; i++) {
|
|
233
278
|
dot += a[i] * b[i];
|
|
234
279
|
na += a[i] * a[i];
|
|
@@ -240,9 +285,12 @@ function cosine(a, b) {
|
|
|
240
285
|
|
|
241
286
|
/** JS-cosine kNN over D4's float32-LE BLOBs (decision D11 — no second vec0 store). */
|
|
242
287
|
function vectorTopK(db, queryVector, pool) {
|
|
288
|
+
// F46: the scan scores vectors — it must NOT drag every chunk's body
|
|
289
|
+
// (megabytes) out of SQLite per query; bodies are fetched lazily for the
|
|
290
|
+
// few fused candidates that need them.
|
|
243
291
|
const rows = db
|
|
244
292
|
.prepare(
|
|
245
|
-
"select chunk_id, path, section, line_start, line_end, meta,
|
|
293
|
+
"select chunk_id, path, section, line_start, line_end, meta, embedding from chunks where embedding is not null",
|
|
246
294
|
)
|
|
247
295
|
.all();
|
|
248
296
|
const scored = rows.map((r) => ({ ...r, sim: cosine(decodeVector(r.embedding), queryVector) }));
|
package/src/doc/retrieval.mjs
CHANGED
|
@@ -33,13 +33,26 @@ export async function runDocOp(grammar, ctx = {}) {
|
|
|
33
33
|
// same pass; otherwise the store answers keyword-only (AC17's root).
|
|
34
34
|
const cfg = resolveEmbedConfig({ config: loadConfig(root), env: process.env });
|
|
35
35
|
let embedded = null;
|
|
36
|
+
let degradations = [];
|
|
36
37
|
if (cfg.configured) {
|
|
37
|
-
|
|
38
|
+
try {
|
|
39
|
+
embedded = await embedPendingChunks(root, makeOpenAIProvider(cfg));
|
|
40
|
+
if (embedded.skipped === true) {
|
|
41
|
+
// Model mismatch: keep the frozen key and declare the cause.
|
|
42
|
+
// (AC18: embeddings-model-mismatch; D3 frozen key set.)
|
|
43
|
+
degradations = [embedded.reason || "embeddings-model-mismatch"];
|
|
44
|
+
embedded = { embedded: 0 };
|
|
45
|
+
}
|
|
46
|
+
} catch (e) {
|
|
47
|
+
// AC17: provider-down ⇒ declared cause, ok:true, keyword results survive.
|
|
48
|
+
degradations = ["unavailable-embeddings-provider-down"];
|
|
49
|
+
embedded = { embedded: 0 };
|
|
50
|
+
}
|
|
38
51
|
}
|
|
39
52
|
return buildEnvelope({
|
|
40
53
|
command: "sync",
|
|
41
54
|
results: [],
|
|
42
|
-
degradations
|
|
55
|
+
degradations,
|
|
43
56
|
store: {
|
|
44
57
|
path: storePath(root),
|
|
45
58
|
present: true,
|
package/src/doc/store.mjs
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
11
|
import { existsSync } from "node:fs";
|
|
12
|
-
import { join } from "node:path";
|
|
12
|
+
import { dirname, join } from "node:path";
|
|
13
13
|
import { openDatabase } from "./sqlite.mjs";
|
|
14
14
|
import { loadConfig } from "./config.mjs";
|
|
15
15
|
|
|
@@ -18,11 +18,6 @@ export const MANIFEST_EXPORT_NAME = "manifest.json";
|
|
|
18
18
|
/** Default store location: `.agentic-workflow/index/index.db`. */
|
|
19
19
|
const DEFAULT_STORE_DIR = join(".agentic-workflow", "index");
|
|
20
20
|
|
|
21
|
-
/** Resolve the store's parent directory (the gitignored index dir). */
|
|
22
|
-
function storeDir(root) {
|
|
23
|
-
return join(root, DEFAULT_STORE_DIR);
|
|
24
|
-
}
|
|
25
|
-
|
|
26
21
|
/**
|
|
27
22
|
* Resolve the store file path. Honours `config.store.path` when present;
|
|
28
23
|
* falls back to the default (`.agentic-workflow/index/index.db`).
|
|
@@ -34,11 +29,14 @@ export function storePath(root) {
|
|
|
34
29
|
}
|
|
35
30
|
|
|
36
31
|
/**
|
|
37
|
-
* Canonical manifest export: the sidecar
|
|
38
|
-
*
|
|
32
|
+
* Canonical manifest export: the sidecar `manifest.json` beside the resolved
|
|
33
|
+
* store — the configured `store.path`'s directory when set (F18: the sidecar
|
|
34
|
+
* must travel with the store, or a custom store path ENOENTs on sync), else
|
|
35
|
+
* the default gitignored index dir. AC12's byte-for-byte assertion runs over
|
|
36
|
+
* that export, never over SQLite page bytes.
|
|
39
37
|
*/
|
|
40
38
|
export function manifestExportPath(root) {
|
|
41
|
-
return join(
|
|
39
|
+
return join(dirname(storePath(root)), MANIFEST_EXPORT_NAME);
|
|
42
40
|
}
|
|
43
41
|
|
|
44
42
|
export function storePresent(root) {
|
package/src/doc/sync.mjs
CHANGED
|
@@ -89,25 +89,42 @@ export async function syncIndex(root) {
|
|
|
89
89
|
const insert = db.prepare(
|
|
90
90
|
"INSERT INTO chunks (chunk_id, path, section, line_start, line_end, meta, body) VALUES (?, ?, ?, ?, ?, ?, ?)",
|
|
91
91
|
);
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
//
|
|
106
|
-
// (AC11: treat as deletion).
|
|
92
|
+
// F51: one transaction for the whole reap/insert pass. Per-row autocommit
|
|
93
|
+
// paid one fsync per chunk on the cold path (~9.6x measured); a single
|
|
94
|
+
// BEGIN/COMMIT — with rollback on throw so a mid-pass failure leaves the
|
|
95
|
+
// previous store state intact — is the fix, never a weakening of the
|
|
96
|
+
// per-file error semantics (the ENOENT-as-deletion branch still throws
|
|
97
|
+
// non-ENOENT errors out of the pass).
|
|
98
|
+
db.exec("BEGIN");
|
|
99
|
+
try {
|
|
100
|
+
for (const path of deleted) reap.run(path);
|
|
101
|
+
for (const path of changed) {
|
|
102
|
+
const src = join(root, path);
|
|
103
|
+
try {
|
|
104
|
+
// Reap existing chunks for this path before re-inserting (original
|
|
105
|
+
// reap.run(path) before the read — preserved for the non-ENOENT path).
|
|
107
106
|
reap.run(path);
|
|
108
|
-
|
|
109
|
-
|
|
107
|
+
const rows = scanChunks(readFileSync(src, "utf8"), path);
|
|
108
|
+
for (const c of rows) {
|
|
109
|
+
insert.run(c.id, c.path, c.section, c.lines[0], c.lines[1], JSON.stringify(c.meta), c.body);
|
|
110
|
+
}
|
|
111
|
+
} catch (e) {
|
|
112
|
+
if (e.code === "ENOENT") {
|
|
113
|
+
// File deleted in working tree but not yet committed → reap
|
|
114
|
+
// (AC11: treat as deletion).
|
|
115
|
+
reap.run(path);
|
|
116
|
+
deleted.push(path);
|
|
117
|
+
} else throw e;
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
db.exec("COMMIT");
|
|
121
|
+
} catch (e) {
|
|
122
|
+
try {
|
|
123
|
+
db.exec("ROLLBACK");
|
|
124
|
+
} catch {
|
|
125
|
+
// the transaction may already be rolled back by the driver
|
|
110
126
|
}
|
|
127
|
+
throw e;
|
|
111
128
|
}
|
|
112
129
|
|
|
113
130
|
// Persist + export the canonical manifest (AC12's compared artifact).
|
package/src/edit/UnitDoc.mjs
CHANGED
|
@@ -2,9 +2,12 @@
|
|
|
2
2
|
* UnitDoc — create and edit single-unit SPEC documents.
|
|
3
3
|
*
|
|
4
4
|
* The unit doc is a single Markdown file (docs/features/<NN>-<slug>/SPEC.md)
|
|
5
|
-
* containing
|
|
5
|
+
* containing one of two accepted closed section sets in a fixed order (#305
|
|
6
|
+
* added `## Impact`; #308 added the `spec-by-reference` shape). All edits go
|
|
6
7
|
* through typed operations that validate post-state against the file schema
|
|
7
|
-
* before writing
|
|
8
|
+
* before writing, and validation resolves the shape from the headings the
|
|
9
|
+
* document carries — a legacy doc and a migrated one are both valid, never one
|
|
10
|
+
* of them silently upgraded.
|
|
8
11
|
*/
|
|
9
12
|
|
|
10
13
|
import { readFileSync, writeFileSync, renameSync, existsSync, mkdtempSync, rename } from "node:fs";
|
|
@@ -13,11 +16,19 @@ import { tmpdir } from "node:os";
|
|
|
13
16
|
import { createHash } from "node:crypto";
|
|
14
17
|
import {
|
|
15
18
|
UNIT_DOC_SECTIONS,
|
|
19
|
+
UNIT_DOC_SPEC_REF_SECTIONS,
|
|
20
|
+
UNIT_DOC_SECTION_SHAPES,
|
|
16
21
|
EVIDENCE_COLUMNS,
|
|
17
22
|
PROGRESS_ENTRY_REGEX,
|
|
23
|
+
resolveUnitDocShape,
|
|
24
|
+
unitDocSectionsFor,
|
|
18
25
|
} from "./schema.mjs";
|
|
19
26
|
|
|
20
|
-
// ── Canonical
|
|
27
|
+
// ── Canonical skeletons matching docs/{features,fix}/_TEMPLATE/SPEC.md ────
|
|
28
|
+
// The legacy shape is emitted by `create`; the re-cut shape by
|
|
29
|
+
// `createSpecByReference`. Neither is derived from the other: a skeleton is a
|
|
30
|
+
// published template, and generating it from the other shape would make the two
|
|
31
|
+
// drift silently (the #305 defect class).
|
|
21
32
|
const CANONICAL_SKELETON = `# NN — <unit-slug>
|
|
22
33
|
|
|
23
34
|
> One-line: what this unit doc is. Copy to docs/features/NN-<slug>/.
|
|
@@ -40,10 +51,28 @@ Numbered list. Each AC is induced from a concrete user scenario ("I do X and obs
|
|
|
40
51
|
Make each AC command-verified where possible. If the request is too vague to state an AC,
|
|
41
52
|
STOP and ask the user with concrete options — never invent one.
|
|
42
53
|
|
|
54
|
+
## Impact
|
|
55
|
+
|
|
56
|
+
What the change touches beyond its own files: what consumes this unit's
|
|
57
|
+
deliverables, what this unit consumes from others, what stops being true when
|
|
58
|
+
the change lands (comments, docs, declared validators, narrations naming the
|
|
59
|
+
old shape), and what must be asked before touching something live on the other
|
|
60
|
+
side. Cut at plan time — the executor sweeps this surface, it is not
|
|
61
|
+
rediscovered at review.
|
|
62
|
+
|
|
43
63
|
## Non-goals
|
|
44
64
|
|
|
45
65
|
What this unit is NOT. Findings discovered during implementation never expand scope.
|
|
46
66
|
|
|
67
|
+
## Future
|
|
68
|
+
|
|
69
|
+
Ideas the user deferred ("down the road I'd like…"), captured verbatim with a
|
|
70
|
+
date and a status: \`open\`, \`planned\`, or \`discarded <YYYY-MM-DD>\`. This unit
|
|
71
|
+
never implements, specs, or tasks a row here. Write \`none\` when nothing was
|
|
72
|
+
deferred. Reviewed at unit close, on session resume, and whenever later work
|
|
73
|
+
returns to the same area — each open row is then offered as
|
|
74
|
+
plan-now / keep-deferred / discard.
|
|
75
|
+
|
|
47
76
|
## Future cost
|
|
48
77
|
|
|
49
78
|
Standing obligations this unit imposes on future work. Each row: the rule + who it binds.
|
|
@@ -85,6 +114,113 @@ The single next action.
|
|
|
85
114
|
Issues, roadmap rows, related material. The PR closes absorbed issues via \`Closes #N\`. \`none\` if empty.
|
|
86
115
|
`;
|
|
87
116
|
|
|
117
|
+
// The re-cut skeleton (issue #308). Section bodies state what to write, in
|
|
118
|
+
// positive terms: each `S#` quotes the request verbatim, each task links the
|
|
119
|
+
// requirement it implements, and the log is appended to, never rewritten.
|
|
120
|
+
const CANONICAL_SPEC_REF_SKELETON = `# NN — <unit-slug>
|
|
121
|
+
|
|
122
|
+
> One-line: what this unit doc is. Copy to docs/features/NN-<slug>/.
|
|
123
|
+
|
|
124
|
+
## Specs
|
|
125
|
+
|
|
126
|
+
Requirements, each numbered \`S#\` and quoting the requester's own words
|
|
127
|
+
verbatim between the quote markers. Cut one requirement per distinct ask, in the
|
|
128
|
+
order the request states them; a later correction is appended under its own id
|
|
129
|
+
(\`S1a\`, \`S2a\`, …) and never rewrites the id it corrects.
|
|
130
|
+
|
|
131
|
+
**S1 — <short title in your own words>.**
|
|
132
|
+
> <the request's words, verbatim and unedited>
|
|
133
|
+
|
|
134
|
+
## Impact
|
|
135
|
+
|
|
136
|
+
What the change touches beyond its own files: what consumes this unit's
|
|
137
|
+
deliverables, what this unit consumes from others, what stops being true when
|
|
138
|
+
the change lands (comments, docs, declared validators, narrations naming the
|
|
139
|
+
old shape), and what must be asked before touching something live on the other
|
|
140
|
+
side. Cut at plan time — the executor sweeps this surface, it is not
|
|
141
|
+
rediscovered at review.
|
|
142
|
+
|
|
143
|
+
## Non-goals
|
|
144
|
+
|
|
145
|
+
What this unit is NOT. Findings discovered during implementation never expand scope.
|
|
146
|
+
|
|
147
|
+
## Future
|
|
148
|
+
|
|
149
|
+
Ideas the user deferred ("down the road I'd like…"), captured verbatim with a
|
|
150
|
+
date and a status: \`open\`, \`planned\`, or \`discarded <YYYY-MM-DD>\`. This unit
|
|
151
|
+
never implements, specs, or tasks a row here. Write \`none\` when nothing was
|
|
152
|
+
deferred. Reviewed at unit close, on session resume, and whenever later work
|
|
153
|
+
returns to the same area — each open row is then offered as
|
|
154
|
+
plan-now / keep-deferred / discard.
|
|
155
|
+
|
|
156
|
+
## Future cost
|
|
157
|
+
|
|
158
|
+
Standing obligations this unit imposes on future work. Each row: the rule + who it binds.
|
|
159
|
+
|
|
160
|
+
## Applicable tests
|
|
161
|
+
|
|
162
|
+
The tests this unit will run (triage-decided). Write exactly \`n/a — no tests step for this unit\`
|
|
163
|
+
when there is none.
|
|
164
|
+
|
|
165
|
+
## Known pre-existing issues
|
|
166
|
+
|
|
167
|
+
Each: <issue/observation> + explicit \`affects\` or \`does-not-affect\` this unit.
|
|
168
|
+
A red gate is never excused by an unrecorded issue.
|
|
169
|
+
|
|
170
|
+
## Tasks
|
|
171
|
+
|
|
172
|
+
P1…Pn with stable IDs, one line each, smallest first. Final task is verification when the unit has behavior. Each task carries its validator — a backticked command plus its expected outcome — and an \`(Implements: S1, S2)\` line naming the requirements it delivers, plus an optional nested \`Relevant files: <path, path…>\` line naming that task's read set (metadata, never a task).
|
|
173
|
+
|
|
174
|
+
- P1 — <task> (validator: \`node --test scripts/x.test.mjs\` exits 0)
|
|
175
|
+
(Implements: S1)
|
|
176
|
+
Relevant files: <path>
|
|
177
|
+
|
|
178
|
+
### Planning evidence
|
|
179
|
+
|
|
180
|
+
One row per Engineering claim (the closed column order and vocabularies are owned
|
|
181
|
+
by \`skills/pre-execution-review/references/LEDGERS.md\`). Embedded here for XS/S
|
|
182
|
+
units; for M/L the ledger lives in the unit folder's \`planning-evidence.md\` and
|
|
183
|
+
this section names it instead — never both.
|
|
184
|
+
|
|
185
|
+
### Obligations
|
|
186
|
+
|
|
187
|
+
One row per normative behaviour, compatibility invariant, affected use case, and
|
|
188
|
+
required failure state (shape owned by
|
|
189
|
+
\`skills/pre-execution-review/references/LEDGERS.md\`). Embedded here for XS/S
|
|
190
|
+
units; for M/L the ledger lives in the unit folder's \`planning-obligations.md\`
|
|
191
|
+
and this section names it — never both. Before the unit ships, every row is
|
|
192
|
+
\`verified\` (or an evidenced \`n/a\`).
|
|
193
|
+
|
|
194
|
+
## Findings
|
|
195
|
+
|
|
196
|
+
OPEN rows only: a row a review persisted as fix-now work and no fold has closed.
|
|
197
|
+
A folded row leaves this table and becomes a \`## Log\` line. Rows are appended by
|
|
198
|
+
\`review-change\` and \`triage-issue\`.
|
|
199
|
+
|
|
200
|
+
| id | S# / file:line | axis | severity | class | route |
|
|
201
|
+
|---|---|---|---|---|---|
|
|
202
|
+
|
|
203
|
+
## Log
|
|
204
|
+
|
|
205
|
+
Append-only. \`L1\` is the request verbatim; every later line carries one kind
|
|
206
|
+
token — \`L<n>\` request or correction (a verbatim quote), \`E<n>\` evidence run,
|
|
207
|
+
\`G<n>\` gate run, \`F<n>\` folded finding, \`D<n>\` owner decision, \`P<n>\` phase
|
|
208
|
+
progress. A correction never edits an earlier line: it appends.
|
|
209
|
+
|
|
210
|
+
- **L1** — <YYYY-MM-DD>, the request, verbatim:
|
|
211
|
+
\`\`\`
|
|
212
|
+
<the request as it was made>
|
|
213
|
+
\`\`\`
|
|
214
|
+
|
|
215
|
+
## Next
|
|
216
|
+
|
|
217
|
+
The single next action.
|
|
218
|
+
|
|
219
|
+
## References
|
|
220
|
+
|
|
221
|
+
Issues, roadmap rows, related material. The PR closes absorbed issues via \`Closes #N\`. \`none\` if empty.
|
|
222
|
+
`;
|
|
223
|
+
|
|
88
224
|
// ── Helpers ──────────────────────────────────────────────────────────────
|
|
89
225
|
|
|
90
226
|
function sha256(text) {
|
|
@@ -117,7 +253,7 @@ function makeReceipt(service, op, path, schema, before, after, ok) {
|
|
|
117
253
|
// ── Public API ───────────────────────────────────────────────────────────
|
|
118
254
|
|
|
119
255
|
/**
|
|
120
|
-
* create(dir, slug) — write the unit doc with all
|
|
256
|
+
* create(dir, slug) — write the unit doc with all 14 sections from the
|
|
121
257
|
* canonical skeleton. dir is the parent directory (e.g. docs/features);
|
|
122
258
|
* slug is the kebab-case name. The file lands at docs/features/<slug>/SPEC.md.
|
|
123
259
|
*
|
|
@@ -159,8 +295,11 @@ export function create(dir, slug) {
|
|
|
159
295
|
* Returns a receipt. Throws on unknown section.
|
|
160
296
|
*/
|
|
161
297
|
export function setSection(doc, name, body) {
|
|
162
|
-
|
|
163
|
-
|
|
298
|
+
// Both accepted shapes are addressable: a migrated document sets its own
|
|
299
|
+
// sections and a legacy one keeps its own (#308).
|
|
300
|
+
const addressable = [...new Set([...UNIT_DOC_SECTIONS, ...UNIT_DOC_SPEC_REF_SECTIONS])];
|
|
301
|
+
if (!addressable.includes(name)) {
|
|
302
|
+
throw new Error(`Unknown section "${name}"; allowed: ${addressable.join(", ")}`);
|
|
164
303
|
}
|
|
165
304
|
const content = readFileSync(doc, "utf8");
|
|
166
305
|
const beforeHash = sha256(content);
|
|
@@ -185,6 +324,37 @@ export function setSection(doc, name, body) {
|
|
|
185
324
|
);
|
|
186
325
|
}
|
|
187
326
|
|
|
327
|
+
/**
|
|
328
|
+
* createSpecByReference(dir, slug) — write the unit doc in the re-cut
|
|
329
|
+
* (`spec-by-reference`) shape from its own canonical skeleton (#308). Same
|
|
330
|
+
* contract as `create`: dir is the unit directory, the file lands at
|
|
331
|
+
* dir/SPEC.md, and the receipt reports whether the written content validates.
|
|
332
|
+
*
|
|
333
|
+
* Returns { ok: true, receipt } on success.
|
|
334
|
+
*/
|
|
335
|
+
export function createSpecByReference(dir, slug) {
|
|
336
|
+
if (!existsSync(dir)) {
|
|
337
|
+
throw new Error(`Directory does not exist: ${dir}`);
|
|
338
|
+
}
|
|
339
|
+
const target = join(dir, "SPEC.md");
|
|
340
|
+
const content = CANONICAL_SPEC_REF_SKELETON;
|
|
341
|
+
const beforeHash = existsSync(target) ? sha256(readFileSync(target, "utf8")) : "empty";
|
|
342
|
+
atomicWrite(target, content);
|
|
343
|
+
const afterHash = sha256(readFileSync(target, "utf8"));
|
|
344
|
+
|
|
345
|
+
const validation = validate(readFileSync(target, "utf8"));
|
|
346
|
+
const ok = validation.ok && validation.violations.length === 0;
|
|
347
|
+
return makeReceipt(
|
|
348
|
+
"unitDoc",
|
|
349
|
+
"create",
|
|
350
|
+
target,
|
|
351
|
+
"unit-doc-template@1",
|
|
352
|
+
shaPrefix(beforeHash),
|
|
353
|
+
shaPrefix(afterHash),
|
|
354
|
+
ok,
|
|
355
|
+
);
|
|
356
|
+
}
|
|
357
|
+
|
|
188
358
|
/**
|
|
189
359
|
* evidence.addRow(doc, { ac, command, exitDigest, output, verifiedBy })
|
|
190
360
|
* Appends a row to the evidence table in the unit doc.
|
|
@@ -299,8 +469,14 @@ export function validate(text) {
|
|
|
299
469
|
if (m) foundHeadings.push(m[1]);
|
|
300
470
|
}
|
|
301
471
|
|
|
472
|
+
// Which accepted shape the document asserts (#308). A document satisfying
|
|
473
|
+
// neither is reported against the legacy list, which is the shape every unit
|
|
474
|
+
// predating the re-cut carries.
|
|
475
|
+
const shape = resolveUnitDocShape(foundHeadings);
|
|
476
|
+
const required = unitDocSectionsFor(shape);
|
|
477
|
+
|
|
302
478
|
// Check for missing sections
|
|
303
|
-
for (const section of
|
|
479
|
+
for (const section of required) {
|
|
304
480
|
if (!foundHeadings.includes(section)) {
|
|
305
481
|
violations.push(`Missing section: ${section}`);
|
|
306
482
|
}
|
|
@@ -316,13 +492,25 @@ export function validate(text) {
|
|
|
316
492
|
}
|
|
317
493
|
|
|
318
494
|
// Check for misordered sections (only the ones that exist)
|
|
319
|
-
const filtered = UNIT_DOC_SECTIONS.filter((s) => foundHeadings.includes(s));
|
|
320
495
|
let expectedIdx = 0;
|
|
321
496
|
for (const found of foundHeadings) {
|
|
322
|
-
if (found ===
|
|
497
|
+
if (found === required[expectedIdx]) {
|
|
323
498
|
expectedIdx++;
|
|
324
|
-
} else if (
|
|
325
|
-
violations.push(`Misordered section: ${found} (expected after ${
|
|
499
|
+
} else if (required.includes(found)) {
|
|
500
|
+
violations.push(`Misordered section: ${found} (expected after ${required[expectedIdx - 1]} or before ${required[expectedIdx]})`);
|
|
501
|
+
}
|
|
502
|
+
}
|
|
503
|
+
|
|
504
|
+
// A half-migrated document carries a section from the other shape: its
|
|
505
|
+
// Evidence rows and its Log would both claim to be the receipt, so it is
|
|
506
|
+
// refused rather than read two ways (the #308 §Scope 4 migration rule).
|
|
507
|
+
if (shape !== null) {
|
|
508
|
+
const foreign = Object.entries(UNIT_DOC_SECTION_SHAPES)
|
|
509
|
+
.filter(([name]) => name !== shape)
|
|
510
|
+
.flatMap(([, sections]) => sections)
|
|
511
|
+
.filter((section) => !required.includes(section) && foundHeadings.includes(section));
|
|
512
|
+
for (const section of new Set(foreign)) {
|
|
513
|
+
violations.push(`Half-migrated section: ${section} belongs to the other accepted shape`);
|
|
326
514
|
}
|
|
327
515
|
}
|
|
328
516
|
|
package/src/edit/schema.mjs
CHANGED
|
@@ -10,12 +10,13 @@
|
|
|
10
10
|
* package as owner.
|
|
11
11
|
*/
|
|
12
12
|
|
|
13
|
-
// ── Unit doc:
|
|
13
|
+
// ── Unit doc: 14 closed sections (ordered, #305) — the legacy shape ─────
|
|
14
14
|
export const UNIT_DOC_SECTIONS = [
|
|
15
15
|
"Objective",
|
|
16
16
|
"Why",
|
|
17
17
|
"User outcome",
|
|
18
18
|
"Acceptance criteria",
|
|
19
|
+
"Impact",
|
|
19
20
|
"Non-goals",
|
|
20
21
|
"Future cost",
|
|
21
22
|
"Applicable tests",
|
|
@@ -27,6 +28,49 @@ export const UNIT_DOC_SECTIONS = [
|
|
|
27
28
|
"References",
|
|
28
29
|
];
|
|
29
30
|
|
|
31
|
+
// ── Unit doc: the re-cut shape (spec-by-reference, #308) ────────────────
|
|
32
|
+
// `## Specs` numbers the owner's requirements verbatim, `## Findings` holds the
|
|
33
|
+
// OPEN rows `review-findings.md` used to carry, and `## Log` appends every
|
|
34
|
+
// request, correction, evidence run, gate run and folded finding. The re-cut adds
|
|
35
|
+
// three headings and drops the six they replace; the rest is shared, so a migrated
|
|
36
|
+
// doc and a closed one are read by the same code.
|
|
37
|
+
export const UNIT_DOC_SPEC_REF_SECTIONS = [
|
|
38
|
+
"Specs",
|
|
39
|
+
"Impact",
|
|
40
|
+
"Non-goals",
|
|
41
|
+
"Future cost",
|
|
42
|
+
"Applicable tests",
|
|
43
|
+
"Known pre-existing issues",
|
|
44
|
+
"Tasks",
|
|
45
|
+
"Findings",
|
|
46
|
+
"Log",
|
|
47
|
+
"Next",
|
|
48
|
+
"References",
|
|
49
|
+
];
|
|
50
|
+
|
|
51
|
+
// One shape table, resolved by the headings a document actually carries. Kept in
|
|
52
|
+
// parity with `UNIT_DOC_SECTION_SHAPES` in
|
|
53
|
+
// packages/agentic-workflow-schema/src/pre-execution.ts by
|
|
54
|
+
// `scripts/unit-doc-contract.test.mjs`; the duplicate is deliberate — this
|
|
55
|
+
// package ships without a dependency on the schema package.
|
|
56
|
+
export const UNIT_DOC_SECTION_SHAPES = Object.freeze({
|
|
57
|
+
legacy: UNIT_DOC_SECTIONS,
|
|
58
|
+
"spec-by-reference": UNIT_DOC_SPEC_REF_SECTIONS,
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
/** The accepted shape a set of headings satisfies, or `null` when it satisfies neither. */
|
|
62
|
+
export function resolveUnitDocShape(headings) {
|
|
63
|
+
for (const [name, sections] of Object.entries(UNIT_DOC_SECTION_SHAPES)) {
|
|
64
|
+
if (sections.every((section) => headings.includes(section))) return name;
|
|
65
|
+
}
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
/** The section list of a resolved shape, defaulting to the legacy list. */
|
|
70
|
+
export function unitDocSectionsFor(shape) {
|
|
71
|
+
return shape === null ? UNIT_DOC_SECTIONS : UNIT_DOC_SECTION_SHAPES[shape];
|
|
72
|
+
}
|
|
73
|
+
|
|
30
74
|
// ── Unit doc: evidence-table@1 columns ───────────────────────────────────
|
|
31
75
|
export const EVIDENCE_COLUMNS = [
|
|
32
76
|
"AC",
|
|
@@ -0,0 +1,388 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Bounded memory-substrate health probe (feature 66, P1 — AC2).
|
|
3
|
+
*
|
|
4
|
+
* Answers one question before a session's first memory read: is the Engram
|
|
5
|
+
* memory layer healthy enough to trust, and if not, exactly which layer is
|
|
6
|
+
* degraded? Five checks, one verdict:
|
|
7
|
+
*
|
|
8
|
+
* http-health GET :7437/health — the HTTP server pi talks to.
|
|
9
|
+
* mcp-runner one `initialize` round-trip to a spawned
|
|
10
|
+
* `engram mcp --tools=agent` — the stdio transport.
|
|
11
|
+
* binary-version `engram --version` — the CLI both transports ride on.
|
|
12
|
+
* sync-staleness `engram sync --status` — pending import work.
|
|
13
|
+
* session-ambiguity `engram doctor --json --check` on the two findings
|
|
14
|
+
* that make a session id unreliable or a sync target
|
|
15
|
+
* unreachable.
|
|
16
|
+
*
|
|
17
|
+
* Two design rules ride on measured failure modes, not guesses:
|
|
18
|
+
*
|
|
19
|
+
* - **Exit code is not a health signal.** `engram doctor` exits 0 while its
|
|
20
|
+
* JSON says `status: "error"`, so every check parses the answer it gets and
|
|
21
|
+
* never trusts a zero exit.
|
|
22
|
+
* - **A responding server that has not synced is not `ok`** (AC2's staleness
|
|
23
|
+
* signal), which is why `sync-staleness` is a check and not a footnote.
|
|
24
|
+
* - **One answer never hides another.** The session check asks both scoped
|
|
25
|
+
* `doctor --check` ids and reports every non-`ok` finding: the first is
|
|
26
|
+
* non-`ok` permanently on a machine with session-attribution ambiguity, so
|
|
27
|
+
* stopping at it would silence the sync signal there forever.
|
|
28
|
+
*
|
|
29
|
+
* The five checks are independent, so they are launched together and each keeps
|
|
30
|
+
* its own bound: the worst case is the slowest bound, never the sum of five
|
|
31
|
+
* (4+4+4+10+10 = 32 s, which the 30 s ceiling could not fit). The probe never
|
|
32
|
+
* issues an MCP *tool* call — only `initialize` — so running it can never mutate
|
|
33
|
+
* the memory layer. Bounds: 4 s for the HTTP/runner/version calls, 10 s for the
|
|
34
|
+
* two CLI-backed calls, and a 30 s ceiling over the whole probe, which stops any
|
|
35
|
+
* dependency that ignored its own bound. A bound hit fails that check and the
|
|
36
|
+
* verdict becomes `degraded` — never a hang, never a blocked unit (D1).
|
|
37
|
+
*
|
|
38
|
+
* `runProbe` takes its side effects by injection (`fetchImpl`, `runImpl`,
|
|
39
|
+
* `timeoutMs`, `totalTimeoutMs`) — the crate's existing shape
|
|
40
|
+
* (`src/doc/embeddings.mjs`'s `fetchImpl ?? fetch`) — so the suite drives
|
|
41
|
+
* every degraded path with fakes and millisecond bounds: no network, no PATH,
|
|
42
|
+
* no real engram process.
|
|
43
|
+
*/
|
|
44
|
+
|
|
45
|
+
import { spawn } from "node:child_process";
|
|
46
|
+
|
|
47
|
+
export const PROBE_SCHEMA = "memory-probe@1";
|
|
48
|
+
|
|
49
|
+
/** Per-check timeout bounds (ms), and the ceiling over the whole probe. */
|
|
50
|
+
export const PROBE_TIMEOUTS = Object.freeze({
|
|
51
|
+
httpHealth: 4_000,
|
|
52
|
+
mcpRunner: 4_000,
|
|
53
|
+
binaryVersion: 4_000,
|
|
54
|
+
syncStaleness: 10_000,
|
|
55
|
+
sessionAmbiguity: 10_000,
|
|
56
|
+
total: 30_000,
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
const HEALTH_URL = "http://127.0.0.1:7437/health";
|
|
60
|
+
const ENGRAM_BIN = "engram";
|
|
61
|
+
const RUNNER_ARGS = ["mcp", "--tools=agent"];
|
|
62
|
+
const INITIALIZE = {
|
|
63
|
+
jsonrpc: "2.0",
|
|
64
|
+
id: 1,
|
|
65
|
+
method: "initialize",
|
|
66
|
+
params: {
|
|
67
|
+
protocolVersion: "2024-11-05",
|
|
68
|
+
capabilities: {},
|
|
69
|
+
clientInfo: { name: "agentic-workflow-memory-probe", version: "1" },
|
|
70
|
+
},
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
const CHECK_IDS = Object.freeze([
|
|
74
|
+
"http-health",
|
|
75
|
+
"mcp-runner",
|
|
76
|
+
"binary-version",
|
|
77
|
+
"sync-staleness",
|
|
78
|
+
"session-ambiguity",
|
|
79
|
+
]);
|
|
80
|
+
|
|
81
|
+
function pass(id, detail) {
|
|
82
|
+
return { id, status: "ok", detail };
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function fail(id, reason, detail) {
|
|
86
|
+
return { id, status: "failed", reason, detail };
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Run one child process under a bound. Resolves to
|
|
91
|
+
* `{code, stdout, stderr, timedOut, spawnError}` — it never rejects, because
|
|
92
|
+
* every failure mode here is an answer, not an exception.
|
|
93
|
+
*
|
|
94
|
+
* `stdin` is written and the stream closed immediately: the MCP runner would
|
|
95
|
+
* otherwise wait forever for its client, which is the hang this probe exists
|
|
96
|
+
* to avoid.
|
|
97
|
+
*/
|
|
98
|
+
function runBounded(command, args, { timeoutMs, stdin = null } = {}) {
|
|
99
|
+
return new Promise((resolve) => {
|
|
100
|
+
let settled = false;
|
|
101
|
+
let child;
|
|
102
|
+
const done = (result) => {
|
|
103
|
+
if (settled) return;
|
|
104
|
+
settled = true;
|
|
105
|
+
clearTimeout(timer);
|
|
106
|
+
resolve(result);
|
|
107
|
+
};
|
|
108
|
+
const timer = setTimeout(() => {
|
|
109
|
+
if (child) {
|
|
110
|
+
try {
|
|
111
|
+
child.kill("SIGKILL");
|
|
112
|
+
} catch {
|
|
113
|
+
// the process already exited — the settle below is what matters
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
done({ code: null, stdout: "", stderr: "", timedOut: true, spawnError: null });
|
|
117
|
+
}, timeoutMs);
|
|
118
|
+
|
|
119
|
+
try {
|
|
120
|
+
child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
|
|
121
|
+
} catch (error) {
|
|
122
|
+
done({ code: null, stdout: "", stderr: "", timedOut: false, spawnError: error });
|
|
123
|
+
return;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
let stdout = "";
|
|
127
|
+
let stderr = "";
|
|
128
|
+
child.stdout?.on("data", (chunk) => (stdout += chunk));
|
|
129
|
+
child.stderr?.on("data", (chunk) => (stderr += chunk));
|
|
130
|
+
child.on("error", (error) => done({ code: null, stdout, stderr, timedOut: false, spawnError: error }));
|
|
131
|
+
child.on("close", (code) => done({ code, stdout, stderr, timedOut: false, spawnError: null }));
|
|
132
|
+
|
|
133
|
+
if (child.stdin) {
|
|
134
|
+
child.stdin.on("error", () => {
|
|
135
|
+
// the runner died before reading — reported by close/error
|
|
136
|
+
});
|
|
137
|
+
child.stdin.end(stdin ?? "");
|
|
138
|
+
}
|
|
139
|
+
});
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/** First JSON object found in a text stream (doctor/mcp may pad with noise). */
|
|
143
|
+
function firstJsonObject(text) {
|
|
144
|
+
const start = text.indexOf("{");
|
|
145
|
+
if (start === -1) return null;
|
|
146
|
+
let depth = 0;
|
|
147
|
+
let inString = false;
|
|
148
|
+
let escaped = false;
|
|
149
|
+
for (let i = start; i < text.length; i++) {
|
|
150
|
+
const ch = text[i];
|
|
151
|
+
if (inString) {
|
|
152
|
+
if (escaped) escaped = false;
|
|
153
|
+
else if (ch === "\\") escaped = true;
|
|
154
|
+
else if (ch === '"') inString = false;
|
|
155
|
+
continue;
|
|
156
|
+
}
|
|
157
|
+
if (ch === '"') inString = true;
|
|
158
|
+
else if (ch === "{") depth += 1;
|
|
159
|
+
else if (ch === "}") {
|
|
160
|
+
depth -= 1;
|
|
161
|
+
if (depth === 0) {
|
|
162
|
+
try {
|
|
163
|
+
return JSON.parse(text.slice(start, i + 1));
|
|
164
|
+
} catch {
|
|
165
|
+
return null;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
return null;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** `engram sync --status` reports pending work as a fixed text block. */
|
|
174
|
+
export function parseSyncStatus(text) {
|
|
175
|
+
const match = text.match(/Pending import:\s*(\d+)/i);
|
|
176
|
+
if (!match) return { parsed: false, pending: null };
|
|
177
|
+
return { parsed: true, pending: Number(match[1]) };
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
async function checkHttpHealth(fetchImpl, timeoutMs) {
|
|
181
|
+
const id = "http-health";
|
|
182
|
+
const controller = new AbortController();
|
|
183
|
+
const timer = setTimeout(() => controller.abort(), timeoutMs);
|
|
184
|
+
try {
|
|
185
|
+
const response = await fetchImpl(HEALTH_URL, { signal: controller.signal });
|
|
186
|
+
if (!response.ok) return fail(id, "http-status", `HTTP ${response.status}`);
|
|
187
|
+
let body = null;
|
|
188
|
+
try {
|
|
189
|
+
body = JSON.parse(await response.text());
|
|
190
|
+
} catch {
|
|
191
|
+
return fail(id, "http-unparseable", "health body is not JSON");
|
|
192
|
+
}
|
|
193
|
+
if (body?.status !== "ok") return fail(id, "http-unhealthy", `status ${body?.status ?? "missing"}`);
|
|
194
|
+
return pass(id, `engram ${body?.version ?? "unknown"} answering`);
|
|
195
|
+
} catch (error) {
|
|
196
|
+
if (error?.name === "AbortError") return fail(id, "timeout", `no HTTP answer within ${timeoutMs} ms`);
|
|
197
|
+
return fail(id, "http-unreachable", error?.message ?? String(error));
|
|
198
|
+
} finally {
|
|
199
|
+
clearTimeout(timer);
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
async function checkMcpRunner(runImpl, timeoutMs) {
|
|
204
|
+
const id = "mcp-runner";
|
|
205
|
+
const result = await runImpl(ENGRAM_BIN, RUNNER_ARGS, {
|
|
206
|
+
timeoutMs,
|
|
207
|
+
stdin: JSON.stringify(INITIALIZE) + "\n",
|
|
208
|
+
});
|
|
209
|
+
if (result.spawnError) return fail(id, "runner-missing", result.spawnError.message);
|
|
210
|
+
if (result.timedOut) return fail(id, "timeout", `no initialize answer within ${timeoutMs} ms`);
|
|
211
|
+
const reply = firstJsonObject(result.stdout ?? "");
|
|
212
|
+
if (!reply) return fail(id, "runner-silent", `exit ${result.code}, no JSON-RPC reply`);
|
|
213
|
+
if (reply.error) return fail(id, "runner-error", reply.error.message ?? "JSON-RPC error");
|
|
214
|
+
const info = reply.result?.serverInfo;
|
|
215
|
+
if (!info?.name) return fail(id, "runner-silent", "initialize reply carries no serverInfo");
|
|
216
|
+
return pass(id, `${info.name} ${info.version ?? "unknown"} initialized`);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
async function checkBinaryVersion(runImpl, timeoutMs) {
|
|
220
|
+
const id = "binary-version";
|
|
221
|
+
const result = await runImpl(ENGRAM_BIN, ["--version"], { timeoutMs });
|
|
222
|
+
if (result.spawnError) return fail(id, "binary-missing", result.spawnError.message);
|
|
223
|
+
if (result.timedOut) return fail(id, "timeout", `no version answer within ${timeoutMs} ms`);
|
|
224
|
+
const match = (result.stdout ?? "").match(/\d+\.\d+\.\d+\S*/);
|
|
225
|
+
if (!match) return fail(id, "binary-unreadable", `exit ${result.code}, no version string`);
|
|
226
|
+
if (result.code !== 0) return fail(id, "binary-unreadable", `exit ${result.code}`);
|
|
227
|
+
return pass(id, `engram ${match[0]}`);
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
async function checkSyncStaleness(runImpl, timeoutMs) {
|
|
231
|
+
const id = "sync-staleness";
|
|
232
|
+
const result = await runImpl(ENGRAM_BIN, ["sync", "--status"], { timeoutMs });
|
|
233
|
+
if (result.spawnError) return fail(id, "binary-missing", result.spawnError.message);
|
|
234
|
+
if (result.timedOut) return fail(id, "timeout", `no sync answer within ${timeoutMs} ms`);
|
|
235
|
+
// A non-zero exit here is usually "ambiguous project" — the status is
|
|
236
|
+
// unreadable, which is a degradation, not a pass.
|
|
237
|
+
if (result.code !== 0) {
|
|
238
|
+
const detail = (result.stderr ?? "").trim().split("\n").pop() || `exit ${result.code}`;
|
|
239
|
+
return fail(id, "sync-unreadable", detail);
|
|
240
|
+
}
|
|
241
|
+
const parsed = parseSyncStatus(`${result.stdout ?? ""}\n${result.stderr ?? ""}`);
|
|
242
|
+
if (!parsed.parsed) return fail(id, "sync-unreadable", "no pending-import line in the status block");
|
|
243
|
+
if (parsed.pending > 0) return fail(id, "sync-pending", `${parsed.pending} pending import(s)`);
|
|
244
|
+
return pass(id, "no pending import work");
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** One check-scoped `engram doctor --json --check <id>` answer, classified. */
|
|
248
|
+
async function askDoctor(runImpl, checkId, timeoutMs) {
|
|
249
|
+
const result = await runImpl(ENGRAM_BIN, ["doctor", "--json", "--check", checkId], { timeoutMs });
|
|
250
|
+
if (result.spawnError) return { checkId, reason: "binary-missing", detail: result.spawnError.message, structural: true };
|
|
251
|
+
if (result.timedOut) return { checkId, reason: "timeout", detail: `no answer within ${timeoutMs} ms`, structural: true };
|
|
252
|
+
const report = firstJsonObject(result.stdout ?? "");
|
|
253
|
+
if (!report) return { checkId, reason: "doctor-unreadable", detail: "no JSON report", structural: true };
|
|
254
|
+
const entry = (report.checks ?? []).find((c) => c.check_id === checkId) ?? report.checks?.[0];
|
|
255
|
+
if (!entry) return { checkId, reason: "doctor-unreadable", detail: "report carries no check", structural: true };
|
|
256
|
+
if (entry.result !== "ok") {
|
|
257
|
+
return { checkId, reason: `doctor-${entry.result}`, detail: entry.message ?? entry.result, structural: false };
|
|
258
|
+
}
|
|
259
|
+
return { checkId, ok: true };
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Which finding leads the reason code when more than one answer is not `ok`.
|
|
264
|
+
* An `error` outranks a `blocked` target, which outranks a `warning`; a check
|
|
265
|
+
* that could not be answered at all outranks any finding (see the caller).
|
|
266
|
+
*/
|
|
267
|
+
const RESULT_RANK = { error: 3, blocked: 2, warning: 1 };
|
|
268
|
+
|
|
269
|
+
async function checkSessionAmbiguity(runImpl, timeoutMs) {
|
|
270
|
+
const id = "session-ambiguity";
|
|
271
|
+
// Both scoped checks are asked, every time, and in parallel: each is bounded
|
|
272
|
+
// on its own, so pairing them costs no extra wall time, and an answer is
|
|
273
|
+
// never dropped because an earlier finding was already enough to degrade.
|
|
274
|
+
const answers = await Promise.all(DOCTOR_CHECKS.map((checkId) => askDoctor(runImpl, checkId, timeoutMs)));
|
|
275
|
+
const failures = answers.filter((answer) => answer.ok !== true);
|
|
276
|
+
if (failures.length === 0) return pass(id, "no session or sync-target findings");
|
|
277
|
+
// A check that could not be answered at all says more about the layer than a
|
|
278
|
+
// finding does, so a structural failure leads the reason code; otherwise the
|
|
279
|
+
// most severe finding leads, and every finding is listed in the detail.
|
|
280
|
+
const severity = (failure) => (failure.structural ? 4 : RESULT_RANK[failure.reason.replace("doctor-", "")] ?? 0);
|
|
281
|
+
const leading = failures.reduce((best, current) => (severity(current) > severity(best) ? current : best));
|
|
282
|
+
const detail = failures.map((failure) => `${failure.checkId}: ${failure.detail}`).join(" · ");
|
|
283
|
+
return fail(id, leading.reason, detail);
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
/**
|
|
287
|
+
* The two scoped `doctor --json --check <id>` ids the session check asks, named
|
|
288
|
+
* by the plan (P1) and never the full sweep: the first makes a write's session
|
|
289
|
+
* attribution unreliable, the second says a sync target cannot be reached.
|
|
290
|
+
*/
|
|
291
|
+
const DOCTOR_CHECKS = Object.freeze(["ambiguous_active_runtime_sessions", "sync_target_closed_space"]);
|
|
292
|
+
|
|
293
|
+
/** The detail a check carries when the ceiling, not its own bound, stopped it. */
|
|
294
|
+
const CEILING_DETAIL = "probe ceiling reached before this check answered";
|
|
295
|
+
|
|
296
|
+
const CHECKS = [
|
|
297
|
+
{ id: "http-health", timeout: PROBE_TIMEOUTS.httpHealth, run: (deps, ms) => checkHttpHealth(deps.fetchImpl, ms) },
|
|
298
|
+
{ id: "mcp-runner", timeout: PROBE_TIMEOUTS.mcpRunner, run: (deps, ms) => checkMcpRunner(deps.runImpl, ms) },
|
|
299
|
+
{ id: "binary-version", timeout: PROBE_TIMEOUTS.binaryVersion, run: (deps, ms) => checkBinaryVersion(deps.runImpl, ms) },
|
|
300
|
+
{ id: "sync-staleness", timeout: PROBE_TIMEOUTS.syncStaleness, run: (deps, ms) => checkSyncStaleness(deps.runImpl, ms) },
|
|
301
|
+
{ id: "session-ambiguity", timeout: PROBE_TIMEOUTS.sessionAmbiguity, run: (deps, ms) => checkSessionAmbiguity(deps.runImpl, ms) },
|
|
302
|
+
];
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* Run the five checks and return the verdict:
|
|
306
|
+
*
|
|
307
|
+
* {schema, verdict: "ok" | "degraded", checks: [{id, status, reason?, detail}],
|
|
308
|
+
* degraded: [check ids], ceilingHit: boolean}
|
|
309
|
+
*
|
|
310
|
+
* `ok` only when every check passes. The checks are independent, so they run
|
|
311
|
+
* together, each under its own bound; the ceiling is the hard stop over the
|
|
312
|
+
* whole probe and answers for any check whose dependency ignored its bound, so a
|
|
313
|
+
* slow machine can never masquerade as healthy and never hangs.
|
|
314
|
+
*
|
|
315
|
+
* `timeoutMs` overrides every per-check bound (tests use milliseconds);
|
|
316
|
+
* `totalTimeoutMs` overrides the ceiling.
|
|
317
|
+
*/
|
|
318
|
+
export async function runProbe({ fetchImpl, runImpl, timeoutMs, totalTimeoutMs } = {}) {
|
|
319
|
+
const deps = {
|
|
320
|
+
fetchImpl: fetchImpl ?? ((url, init) => fetch(url, init)),
|
|
321
|
+
runImpl: runImpl ?? ((command, args, opts) => runBounded(command, args, opts)),
|
|
322
|
+
};
|
|
323
|
+
const perCheck = timeoutMs ?? null;
|
|
324
|
+
const ceiling = totalTimeoutMs ?? PROBE_TIMEOUTS.total;
|
|
325
|
+
const startedAt = Date.now();
|
|
326
|
+
const remaining = () => ceiling - (Date.now() - startedAt);
|
|
327
|
+
|
|
328
|
+
const answers = new Array(CHECKS.length).fill(null);
|
|
329
|
+
let stopped = false;
|
|
330
|
+
// Set when the ceiling — not a check's own bound — is what ran out. Tracked
|
|
331
|
+
// directly instead of read back out of a detail string, so the wording of a
|
|
332
|
+
// failure can never change what `ceilingHit` reports.
|
|
333
|
+
let ceilingConstrained = false;
|
|
334
|
+
const launched = CHECKS.map(async (check, index) => {
|
|
335
|
+
const budget = perCheck ?? check.timeout;
|
|
336
|
+
const left = remaining();
|
|
337
|
+
if (left <= 0) {
|
|
338
|
+
ceilingConstrained = true;
|
|
339
|
+
answers[index] = fail(check.id, "timeout", CEILING_DETAIL);
|
|
340
|
+
return;
|
|
341
|
+
}
|
|
342
|
+
// The ceiling clamps the bound a check runs under; a timeout that is really
|
|
343
|
+
// the ceiling running out is reported as the ceiling, not as a hung check.
|
|
344
|
+
const bound = Math.min(budget, left);
|
|
345
|
+
const clamped = bound < budget;
|
|
346
|
+
let entry;
|
|
347
|
+
try {
|
|
348
|
+
entry = await check.run(deps, bound);
|
|
349
|
+
} catch (error) {
|
|
350
|
+
entry = fail(check.id, "probe-error", error?.message ?? String(error));
|
|
351
|
+
}
|
|
352
|
+
if (stopped) return;
|
|
353
|
+
if (clamped && entry.status === "failed" && entry.reason === "timeout") {
|
|
354
|
+
ceilingConstrained = true;
|
|
355
|
+
entry = { ...entry, detail: `${CEILING_DETAIL} (bound cut from ${budget} ms to ${bound} ms)` };
|
|
356
|
+
}
|
|
357
|
+
answers[index] = entry;
|
|
358
|
+
});
|
|
359
|
+
|
|
360
|
+
const left = Math.max(remaining(), 0);
|
|
361
|
+
let timer = null;
|
|
362
|
+
const ceilingFired = await new Promise((resolve) => {
|
|
363
|
+
timer = setTimeout(() => {
|
|
364
|
+
stopped = true;
|
|
365
|
+
resolve(true);
|
|
366
|
+
}, left);
|
|
367
|
+
Promise.allSettled(launched).then(() => resolve(false));
|
|
368
|
+
});
|
|
369
|
+
if (timer) clearTimeout(timer);
|
|
370
|
+
|
|
371
|
+
const results = CHECKS.map((check, index) => {
|
|
372
|
+
if (answers[index] !== null) return answers[index];
|
|
373
|
+
// The ceiling fired while this check was still outstanding: its dependency
|
|
374
|
+
// ignored the bound it was given, and the probe answers for it.
|
|
375
|
+
ceilingConstrained = true;
|
|
376
|
+
return fail(check.id, "timeout", CEILING_DETAIL);
|
|
377
|
+
});
|
|
378
|
+
const degraded = results.filter((r) => r.status !== "ok").map((r) => r.id);
|
|
379
|
+
return {
|
|
380
|
+
schema: PROBE_SCHEMA,
|
|
381
|
+
verdict: degraded.length === 0 ? "ok" : "degraded",
|
|
382
|
+
checks: results,
|
|
383
|
+
degraded,
|
|
384
|
+
ceilingHit: ceilingFired === true || ceilingConstrained === true,
|
|
385
|
+
};
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
export { CHECK_IDS, HEALTH_URL, RUNNER_ARGS, ENGRAM_BIN };
|