@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 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.
@@ -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.2.0",
4
- "description": "Deterministic runner for the agentic-workflow lane: file services (agwo edit), sensors, guards and receipts. No dependencies.",
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.7"
30
+ "typebox": "1.4.3"
31
31
  }
32
32
  }
@@ -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 lines = String(markdown).split(/\r?\n/);
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;
@@ -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) and
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)) return structuredClone(DEFAULT_CONFIG);
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.path inside the repository root (AC7: gitignored cache must not
51
- // escape). An absolute path that is outside the root, or a relative path that
52
- // resolves outside (contains `..`), is rejected — the `rmSync` in --rebuild
53
- // targets this path, so a misconfigured store path is a destructive-write
54
- // footgun.
55
- if (parsed.store?.path) {
56
- const candidate = parsed.store.path;
57
- if (!resolve(root, candidate).startsWith(resolve(root) + sep)) {
58
- throw new Error(
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
- db.close();
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 && (hasLogFilters || parseLogEntry(r.body) !== null)) {
195
- const entry = parseLogEntry(r.body);
196
- if (entry === null) continue;
197
- if (hasLogFilters && !logEntryMatches(entry, filters)) continue;
198
- meta = entry;
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 = Math.min(a.length, b.length);
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, body, embedding from chunks where embedding is not null",
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) }));
@@ -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
- embedded = await embedPendingChunks(root, makeOpenAIProvider(cfg));
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 `.agentic-workflow/index/manifest.json`
38
- * in the same gitignored directory as the store (AC12).
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(storeDir(root), MANIFEST_EXPORT_NAME);
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
- for (const path of deleted) reap.run(path);
93
- for (const path of changed) {
94
- const src = join(root, path);
95
- try {
96
- // Reap existing chunks for this path before re-inserting (original
97
- // reap.run(path) before the read — preserved for the non-ENOENT path).
98
- reap.run(path);
99
- const rows = scanChunks(readFileSync(src, "utf8"), path);
100
- for (const c of rows) {
101
- insert.run(c.id, c.path, c.section, c.lines[0], c.lines[1], JSON.stringify(c.meta), c.body);
102
- }
103
- } catch (e) {
104
- if (e.code === "ENOENT") {
105
- // File deleted in working tree but not yet committed → reap
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
- deleted.push(path);
109
- } else throw e;
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).
@@ -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 exactly 13 closed sections in a fixed order. All edits go
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 skeleton matching docs/features/_TEMPLATE/SPEC.md ──────────
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 13 sections from the
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
- if (!UNIT_DOC_SECTIONS.includes(name)) {
163
- throw new Error(`Unknown section "${name}"; allowed: ${UNIT_DOC_SECTIONS.join(", ")}`);
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 UNIT_DOC_SECTIONS) {
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 === UNIT_DOC_SECTIONS[expectedIdx]) {
497
+ if (found === required[expectedIdx]) {
323
498
  expectedIdx++;
324
- } else if (UNIT_DOC_SECTIONS.includes(found)) {
325
- violations.push(`Misordered section: ${found} (expected after ${UNIT_DOC_SECTIONS[expectedIdx - 1]} or before ${UNIT_DOC_SECTIONS[expectedIdx]})`);
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
 
@@ -10,12 +10,13 @@
10
10
  * package as owner.
11
11
  */
12
12
 
13
- // ── Unit doc: 13 closed sections (ordered) ───────────────────────────────
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 };