@awebai/oats 0.54.0 → 0.55.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/bin/oats.mjs +5 -5
  2. package/docs/desktop-cli-api.md +15 -4
  3. package/docs/integrations.md +2 -2
  4. package/docs/knowledge.md +14 -2
  5. package/docs/official-catalog.md +4 -4
  6. package/docs/packages.md +10 -10
  7. package/docs/release-notes/v0.55.0.md +158 -0
  8. package/docs/release-notes/v0.55.1.md +45 -0
  9. package/docs/servers.md +13 -3
  10. package/docs/workspaces.md +1 -1
  11. package/lib/servers.mjs +82 -34
  12. package/package-catalog.json +3 -3
  13. package/package.json +1 -1
  14. package/packages/client/cli-locator.mjs +2 -2
  15. package/packages/client/workspace-views.mjs +4 -3
  16. package/packages/record/README.md +58 -13
  17. package/packages/record/bin/capture.mjs +107 -53
  18. package/packages/record/bin/recall.mjs +3 -2
  19. package/packages/record/docs/capture-service.md +193 -0
  20. package/packages/record/docs/capture-status.schema.json +100 -0
  21. package/packages/record/lib/capture-aw.mjs +96 -94
  22. package/packages/record/lib/capture-cc.mjs +109 -187
  23. package/packages/record/lib/capture-db-reader.mjs +39 -0
  24. package/packages/record/lib/capture-issues.mjs +64 -0
  25. package/packages/record/lib/capture-scratch.mjs +111 -0
  26. package/packages/record/lib/capture-state.mjs +105 -0
  27. package/packages/record/lib/derived-state.mjs +60 -0
  28. package/packages/record/lib/formats.mjs +31 -31
  29. package/packages/record/lib/index-db.mjs +74 -34
  30. package/packages/record/lib/receipt-summary.mjs +62 -0
  31. package/packages/record/lib/session-snapshot.mjs +56 -1
  32. package/packages/record/lib/sqlite-rows.mjs +14 -0
  33. package/packages/record/lib/store.mjs +122 -43
  34. package/packages/record/lib/transcript-prefix.mjs +40 -0
  35. package/skills/oats-getting-started/SKILL.md +1 -1
package/lib/servers.mjs CHANGED
@@ -16,7 +16,7 @@
16
16
  * nothing here runs Git against a remote path.
17
17
  */
18
18
 
19
- import { execFileSync, spawnSync } from "node:child_process";
19
+ import { execFile, execFileSync, spawnSync } from "node:child_process";
20
20
  import { createHash } from "node:crypto";
21
21
  import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
22
22
  import { homedir } from "node:os";
@@ -312,28 +312,81 @@ export function parseRemoteEnvelope(stdout) {
312
312
  export function runRemote(target, oatsArgs, io = {}) {
313
313
  const exec = io.execFileSync || execFileSync;
314
314
  const [bin, ...argv] = sshArgv(target, oatsArgs, { cwd: io.cwd, control: controlUsable(target, io) });
315
- let stdout = "";
316
- let stderr = "";
317
- let status = 0;
318
- let started = true;
319
- let timedOut = false;
315
+ const timeoutMs = io.timeoutMs || 300000;
316
+ let call = { stdout: "", stderr: "", status: 0, started: true };
320
317
  try {
321
318
  // `io.input` (a Buffer) streams to the remote command's stdin: the only
322
319
  // way bytes reach a host, as a quoted argument never could.
323
- stdout = exec(bin, argv, { encoding: "utf8", stdio: [io.input === undefined ? "ignore" : "pipe", "pipe", "pipe"], ...(io.input === undefined ? {} : { input: io.input }), maxBuffer: 16 * 1024 * 1024, timeout: io.timeoutMs || 300000 });
320
+ call.stdout = exec(bin, argv, { encoding: "utf8", stdio: [io.input === undefined ? "ignore" : "pipe", "pipe", "pipe"], ...(io.input === undefined ? {} : { input: io.input }), maxBuffer: 16 * 1024 * 1024, timeout: timeoutMs });
324
321
  } catch (e) {
325
- stdout = String(e.stdout || "");
322
+ if (e.code === "ETIMEDOUT") throw remoteTimeout(target, timeoutMs);
323
+ call = failedCall(e);
324
+ }
325
+ return remoteAnswer(target, call);
326
+ }
327
+
328
+ /** `runRemote` for calls that run side by side (the roster's probes): the same ssh argv and the same
329
+ * answer, over an asynchronous transport. `io.execFileAsync(bin, argv, options)` resolves the call's
330
+ * stdout, or rejects as execFileSync throws (with the call's stdout, stderr, status and signal); the
331
+ * default runs execFile. The deadline is this call's own: when it passes, the call is aborted through
332
+ * `options.signal` (execFile then kills ssh) and fails as timed out, whether or not the transport has
333
+ * settled. The remote command's stdin is empty. */
334
+ export async function runRemoteAsync(target, oatsArgs, io = {}) {
335
+ const exec = io.execFileAsync || execFileAsync;
336
+ const [bin, ...argv] = sshArgv(target, oatsArgs, { cwd: io.cwd, control: controlUsable(target, io) });
337
+ const timeoutMs = io.timeoutMs || 300000;
338
+ const abort = new AbortController();
339
+ let timer;
340
+ const deadline = new Promise((_, reject) => { timer = setTimeout(() => { abort.abort(); reject(remoteTimeout(target, timeoutMs)); }, timeoutMs); });
341
+ let call = { stdout: "", stderr: "", status: 0, started: true };
342
+ try {
343
+ call.stdout = await Promise.race([exec(bin, argv, { encoding: "utf8", maxBuffer: 16 * 1024 * 1024, signal: abort.signal }), deadline]);
344
+ } catch (e) {
345
+ // execFile settles an aborted call at once, before the deadline's own rejection lands.
346
+ if (abort.signal.aborted) throw remoteTimeout(target, timeoutMs);
347
+ call = failedCall(e);
348
+ } finally { clearTimeout(timer); }
349
+ return remoteAnswer(target, call);
350
+ }
351
+
352
+ /** child_process.execFile as a promise of stdout that rejects as execFileSync throws: the error carries
353
+ * the call's stdout and stderr, `status` (its exit code, null when it had none) and `signal` (what
354
+ * ended it; SIGTERM when execFile killed it itself, past maxBuffer or on abort). An ssh that never
355
+ * started (spawn failed) has no stderr: its error's message speaks for it. */
356
+ function execFileAsync(bin, argv, options) {
357
+ return new Promise((resolve, reject) => {
358
+ const child = execFile(bin, argv, options, (error, stdout, stderr) => {
359
+ if (!error) return resolve(stdout);
360
+ const ran = !String(error.syscall || "").startsWith("spawn");
361
+ const status = typeof error.code === "number" ? error.code : null;
362
+ reject(Object.assign(error, { stdout, stderr: ran ? stderr : undefined, status, signal: error.signal || (ran && status === null ? "SIGTERM" : null) }));
363
+ });
364
+ child.stdin?.end();
365
+ });
366
+ }
367
+
368
+ /** A call whose own deadline killed ssh: whatever it printed is cut short. Still ssh's failure to the
369
+ * envelope (E_SSH), in words a client reads as a timeout (it says "timed out", as ssh's own does);
370
+ * `timedOut` lets a caller tell it from a broken link. */
371
+ function remoteTimeout(target, timeoutMs) {
372
+ return Object.assign(serverError("E_SSH", `ssh to ${target.sshHost} timed out: no answer within ${Math.round(timeoutMs / 1000)} s`), { timedOut: true });
373
+ }
374
+
375
+ /** What a failed ssh call left: what it printed, its exit status, and whether ssh ever started. */
376
+ function failedCall(e) {
377
+ return {
378
+ stdout: String(e.stdout || ""),
326
379
  // The process's own stderr when it ran (possibly empty); the error's
327
380
  // message only when there was no process to speak (ssh not found).
328
- stderr = String(e.stderr ?? e.message ?? "");
329
- status = typeof e.status === "number" ? e.status : 255;
381
+ stderr: String(e.stderr ?? e.message ?? ""),
382
+ status: typeof e.status === "number" ? e.status : 255,
330
383
  // Neither an exit status nor a signal: ssh never started (not installed, not executable).
331
- started = typeof e.status === "number" || !!e.signal;
332
- timedOut = e.code === "ETIMEDOUT";
333
- }
334
- // The call's own deadline killed ssh: whatever it printed is cut short. Still ssh's failure to the
335
- // envelope (E_SSH); `timedOut` lets a caller with a budget tell it from a broken link.
336
- if (timedOut) throw Object.assign(serverError("E_SSH", `ssh to ${target.sshHost} did not finish within ${Math.round((io.timeoutMs || 300000) / 1000)} s`), { timedOut: true });
384
+ started: typeof e.status === "number" || !!e.signal,
385
+ };
386
+ }
387
+
388
+ /** The envelope of one finished ssh call, or the error it amounts to. */
389
+ function remoteAnswer(target, { stdout, stderr, status, started }) {
337
390
  if (String(stdout).trim()) {
338
391
  const envelope = parseRemoteEnvelope(stdout);
339
392
  // A bare `retire --json` answer with cleanup still owed exits 1 on the
@@ -766,10 +819,10 @@ function routeHostSurface(serverId, cmd, oatsArgs, io) {
766
819
 
767
820
  // ------------------------------------------------------------------- roster
768
821
 
769
- // The roster answers within a budget the Desktop can wait for (its adapter
770
- // allows 60 s): each target gets the smaller of its own allowance and what is
771
- // left, and targets the budget cannot reach are reported as such, never
772
- // dropped and never allowed to sink the healthy groups.
822
+ // The roster probes every target at once, each within its own deadline: the
823
+ // smaller of its per-target allowance and the answer's deadline, which the
824
+ // Desktop can wait for (its adapter allows 60 s). A target that fails or does
825
+ // not answer in time reports its own error; no other group waits for it.
773
826
  export const ROSTER_BUDGET_MS = 45000;
774
827
  export const ROSTER_PER_TARGET_TIMEOUT_MS = 20000;
775
828
 
@@ -780,7 +833,7 @@ function listSnapshotServers() {
780
833
  }
781
834
 
782
835
  /** The remote roster, grouped by server id and saved route target: one
783
- * bounded status pull per group, registrations unioned with saved routes so
836
+ * bounded status pull per group, all of them at once, registrations unioned with saved routes so
784
837
  * a removed or changed registration keeps its group (registrationPresent
785
838
  * false) and its instances from the snapshots (running null when the probe
786
839
  * fails). Remote state is pulled, never cached; the saved route stays the
@@ -820,13 +873,13 @@ export function hostFeatures(result) {
820
873
  return [...list];
821
874
  }
822
875
 
823
- export function rosterGroups({ server, io = {} } = {}) {
876
+ export async function rosterGroups({ server, io = {} } = {}) {
824
877
  const started = Date.now();
825
878
  if (server && !ID_RE.test(server)) throw serverError("E_BAD_ARGS", `server id ${JSON.stringify(server)} is not a valid id`);
826
879
  if (server && !readServers()[server] && !existsSync(join(REMOTE_SNAPSHOT_DIR(), server))) throw serverError("E_SERVER_UNKNOWN", `no server registered as ${JSON.stringify(server)} and no saved routes for it (oats server list)`);
827
880
  const perTargetTimeoutMs = io.perTargetTimeoutMs || ROSTER_PER_TARGET_TIMEOUT_MS;
828
881
  const budgetMs = io.budgetMs || ROSTER_BUDGET_MS;
829
- let skipped = 0;
882
+ const timeoutMs = Math.min(perTargetTimeoutMs, budgetMs);
830
883
  const servers = readServers();
831
884
  const groups = new Map();
832
885
  const add = (serverId, target, registrationPresent, label) => {
@@ -841,16 +894,11 @@ export function rosterGroups({ server, io = {} } = {}) {
841
894
  if (server && serverId !== server) continue;
842
895
  for (const snap of listSnapshots(serverId)) { if (!snap.target) continue; add(serverId, snap.target, false, servers[serverId]?.label)._snapshots.push(snap); }
843
896
  }
844
- for (const g of groups.values()) {
897
+ // Groups keep their registration order in the answer, whatever order their probes finish in.
898
+ await Promise.all([...groups.values()].map(async (g) => {
845
899
  let status;
846
- const remaining = budgetMs - (Date.now() - started);
847
- if (remaining < 1000) {
848
- skipped++;
849
- g.probe = { ok: false, error: { code: "E_ROSTER_BUDGET", message: `not probed: the ${budgetMs} ms roster budget was used up by earlier targets` } };
850
- } else {
851
- try { status = runRemote(g.target, ["status", "--json", "--dir", g.target.workspace], { ...io, serverId: g.server, timeoutMs: Math.min(perTargetTimeoutMs, remaining) }).envelope; }
852
- catch (e) { g.probe = { ok: false, error: { code: e.code || "E_SSH", message: e.message } }; }
853
- }
900
+ try { status = (await runRemoteAsync(g.target, ["status", "--json", "--dir", g.target.workspace], { ...io, serverId: g.server, timeoutMs })).envelope; }
901
+ catch (e) { g.probe = { ok: false, error: { code: e.code || "E_SSH", message: e.message } }; }
854
902
  if (status && !status.ok) g.probe = { ok: false, error: status.error || { code: "E_REMOTE", message: "status failed" } };
855
903
  // A saved route matches a remote row by name AND home: a same-named
856
904
  // twin under another soul on the host is observed only, never given the
@@ -898,8 +946,8 @@ export function rosterGroups({ server, io = {} } = {}) {
898
946
  g.instances.push({ server: g.server, instance: snap.instance, agent: snap.agent, home: snap.home, agentsRoot: snap.agentsRoot, harness: snap.harness || snap.runtime || null, backend: null, running: null, ...rowFacts(), retirePending: false, rollbackIncomplete: false, savedRoute: true, addressable: g.probe?.ok !== true, missingRemotely: g.probe?.ok === true });
899
947
  }
900
948
  delete g._snapshots;
901
- }
902
- return { groups: [...groups.values()], bounds: { budgetMs, perTargetTimeoutMs, elapsedMs: Date.now() - started, skipped } };
949
+ }));
950
+ return { groups: [...groups.values()], bounds: { budgetMs, perTargetTimeoutMs, elapsedMs: Date.now() - started } };
903
951
  }
904
952
 
905
953
  /** argv for an INTERACTIVE remote command (a viewer attach): ssh with a PTY,
@@ -3,12 +3,12 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v5.0.3",
6
+ "ref": "v5.0.5",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.27.1",
11
+ "ref": "v1.27.3",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "oats.engineering": {
30
30
  "url": "https://github.com/awebai/oats-engineering.git",
31
- "ref": "v1.9.1",
31
+ "ref": "v1.10.0",
32
32
  "path": "oats-package"
33
33
  },
34
34
  "oats.cloning": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.54.0",
3
+ "version": "0.55.1",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.25.8 <0.55.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.25.8 <0.56.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -54,7 +54,7 @@ export const DESKTOP_API = 1;
54
54
  // carry a `description` for every kind and `<kind> update <id> --description`
55
55
  // sets one (feature `automation-descriptions`, which gates the Desktop's
56
56
  // summary writes). The Desktop v1 surface is otherwise unchanged.
57
- export const ACCEPT_RANGE = { min: [0, 25, 8], maxExclusive: [0, 55, 0] };
57
+ export const ACCEPT_RANGE = { min: [0, 25, 8], maxExclusive: [0, 56, 0] };
58
58
  /** The band as humans read it — derived, never hand-spelled, so the probe
59
59
  * rejection reason, the backend's /api status and the degradation card can
60
60
  * never disagree with the numbers actually enforced above. */
@@ -60,8 +60,9 @@ const REASONS = {
60
60
  standalone: () => ({ short: 'Local teams only', detail: 'Teams are local only on this host (standalone).', fix: [] }),
61
61
  };
62
62
 
63
- /** True when a failed probe's message is ssh's own timeout: the kernel reports an ssh that timed out
64
- * as E_SSH with ssh's stderr and no code of its own, so ssh's text is the only signal (a documented limit). */
63
+ /** True when a failed probe's message is a timeout: the kernel reports an ssh that timed out as E_SSH,
64
+ * with ssh's own stderr or, when its own deadline ended the call, "timed out: no answer within N s", and
65
+ * no code of its own, so the text is the only signal (a documented limit). */
65
66
  const TIMED_OUT = /timed out|timeout/i;
66
67
 
67
68
  /** The client's own sentence for a deployment whose last read failed and whose last observation is kept. */
@@ -121,7 +122,7 @@ export function deploymentReasonParts(d, terms) {
121
122
  if (d.rosterError) return { short: 'Not reached', detail: `${machine} was not reached: ${d.rosterError}`, fix: [] };
122
123
  if (d.probe && d.probe.ok !== true) {
123
124
  const code = d.probe.error?.code, message = typeof d.probe.error?.message === 'string' ? d.probe.error.message : '';
124
- if (code === 'E_ROSTER_BUDGET' || code === 'E_CLI_TIMEOUT' || TIMED_OUT.test(message)) return { short: 'Timed out', detail: `${machine} timed out; it is tried again on the next read.`, fix: [] };
125
+ if (code === 'E_CLI_TIMEOUT' || TIMED_OUT.test(message)) return { short: 'Timed out', detail: `${machine} timed out; it is tried again on the next read.`, fix: [] };
125
126
  if (code === 'E_SSH') {
126
127
  const host = d.sshHost || machine;
127
128
  return { short: 'ssh needs a prompt', detail: `${machine} needs ssh to connect without a prompt; run \`ssh ${host}\` once in a terminal.`,
@@ -79,6 +79,10 @@ turn-record recall --reindex # full rebuild of the derived in
79
79
 
80
80
  Store root: `--root`, else `$TURN_RECORD_ROOT`, else `~/.turn-record`.
81
81
 
82
+ `recall --show` refuses a turn hidden by its author's tombstone, including a
83
+ session event whose tombstone lives in another stream. It emits no turn payload
84
+ and exits with status 1, as it does for a missing turn.
85
+
82
86
  **The `node` that `setup` writes down.** The hooks and the watcher's unit name
83
87
  a `node` by its path, and only `setup` run again rewrites them. Which path
84
88
  depends on how it is run:
@@ -101,6 +105,32 @@ their shape, quoted or not, and replaces their command; a command it cannot
101
105
  read as its own is left alone and a new hook is added beside it.
102
106
  Stream owner: `--owner`, else `$TURN_RECORD_OWNER`, else the short hostname.
103
107
 
108
+ Transcript capture reads 64 KiB chunks and frames complete native records,
109
+ including UTF-8 characters split across chunks. It appends batches of at most
110
+ 8 MiB of source bytes plus the last record and checkpoints after each batch.
111
+ One very large native record can still require memory proportional to that
112
+ record; capture does not impose a new record-size policy.
113
+ Final, attributed and protected Pi capture stage the descriptor's snapshot on
114
+ private scratch under `<root>/.capture-tmp` before the first append, preserving
115
+ attribution and custody checks without retaining the source in process memory.
116
+ Exact `--file` capture and receipt claims databases use the same record-root
117
+ volume, which may itself be memory-backed. Ordinary success/failure cleans each
118
+ caller's allocation; lock-held cleanup reclaims only proven dead local owners.
119
+ See [scratch ownership and upgrade costs](docs/capture-service.md#resource-model)
120
+ for preserved uncertain leftovers and the unresolved synchronous first-pass cost.
121
+ Explicit final proofs may read the full snapshot; their output inventories
122
+ remain proportional to the issues and sessions the receipt must return.
123
+
124
+ The search index checkpoints byte positions and turn counts in the same
125
+ transaction as its indexed rows, at most 2,000 journal lines or 8 MiB plus
126
+ the last record per transaction. Known journal history is qualified by a
127
+ durable file-version checkpoint (device, inode, size and nanosecond modification
128
+ and change timestamps). Owner appends preserve its epoch after fsync; an
129
+ unknown write, replacement or shrink requires bounded journal validation and
130
+ invalidates dependent index cursors. Interrupted validation and indexing resume
131
+ from their last committed batch. Initial/recovery validation reads historical
132
+ content; unchanged normal passes do not.
133
+
104
134
  ## Ignoring sessions and paths (privacy)
105
135
 
106
136
  `<root>/ignore` is a plain text file of glob patterns, one per line (blank
@@ -249,19 +279,30 @@ into an orphaned inode until it restarts.
249
279
 
250
280
  ## Memory
251
281
 
252
- A capture pass runs in bounded memory, whatever the size of the record.
253
- Journals are streamed, never parsed whole: the first append to a stream
254
- validates its journal one line at a time. Comm logs are read in chunks, and
255
- the aw dedupe looks up only the changed log's own turn ids, in one streamed
256
- read of the journal. A session's new lines are walked, never collected, and
257
- appended in 8 MB batches. A lost offset is rebuilt from the journal's tail.
258
-
259
- So the heap a pass needs grows with one changed comm log's entry count, not
260
- with the record. A host job can keep a small `--max-old-space-size`;
261
- `packages/record/test/capture-bounded-memory.test.mjs` captures a record four
262
- times its 64 MB heap. One cost is not on the heap: the new bytes of one
263
- session are read as one buffer, so resident memory grows with a single
264
- session's backlog.
282
+ Content processing uses fixed read chunks, bounded batches and SQLite caches,
283
+ plus memory proportional to the largest processable native record. Journals,
284
+ transcript tails and comm logs are streamed; persistent ID lookup avoids keeping
285
+ history IDs or a changed log's candidate IDs in memory. Per-input offsets live
286
+ in derived database rows rather than a rewritten global JSON map. Initial
287
+ capture, recovery validation and explicit final proofs may read all applicable
288
+ content; ordinary unchanged and suffix-growth passes use only new content and
289
+ bounded checkpoint probes. The streaming and work-count tests pin these distinct
290
+ paths; the small-heap regression remains supplementary evidence.
291
+
292
+ Filesystem discovery is a separate cost: root/path metadata inventories may grow
293
+ with file and profile counts. Native roots and each directory retain their
294
+ existing `localeCompare` sorting and depth-first traversal, including stable ties.
295
+ Aweb account logs retain code-unit sorted basename order. Public
296
+ list APIs return full arrays. Metadata enumeration, sorting and per-input probes
297
+ still run on unchanged passes; this is not a constant-memory or new-byte-only
298
+ claim for the whole pass. Explicit receipts likewise retain the issue/session
299
+ inventories their public contract returns. Background capture suppresses those
300
+ output inventories without suppressing error counts.
301
+
302
+ Verified snapshots and prefix comparisons use private record-root scratch, which
303
+ can expand with source size; journal and derived-index disk space also grow with
304
+ captured content. Staging is cleaned on success and failure. No new heap, record
305
+ size, elapsed-time or service policy limit is imposed by these algorithms.
265
306
 
266
307
  ## Known costs, accepted for v1
267
308
 
@@ -341,3 +382,7 @@ Anything that binds nothing is an error,
341
382
  | `E_NO_TURNS` | 1 | no records: an empty file, or only blank lines |
342
383
  | `E_FORMAT` | 1 | records, but no session header of the stated format; the message names the format whose header it does carry |
343
384
  | `E_CAPTURE_FAILED` | 1 | the pass failed (`appended: null`: part of the file may be in the record) |
385
+
386
+ See [capture algorithms and recovery](docs/capture-service.md) for the shared
387
+ append-only input assumption, reset/retry commands, bounded status inventory,
388
+ resource accounting and v0.53.0 downgrade/re-upgrade contract.