owenloop 0.2.1 → 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/dist/engine.js CHANGED
@@ -15,6 +15,15 @@ import { summarizeIssues, validateValue } from "./schema.js";
15
15
  import { hashDef } from "./defs.js";
16
16
  import { localMidnightMs, nowMs, randId } from "./util.js";
17
17
  const DEFAULT_REAP_TTL_MS = 2 * 60 * 60 * 1000; // 2h
18
+ /**
19
+ * REL-4: hard cap on `calls:` composition depth (root instance = depth 0), a
20
+ * defense-in-depth bound independent of construction-time cycle validation.
21
+ * Generous — real compositions in this repo are depth 2–3; the bound only trips
22
+ * on a pathological chain (typically a `calls:` cycle that bypassed load-time
23
+ * validation via a hand-wired `Engine` + custom `DefResolver`). See
24
+ * `maintainCalls` (spawn-time refusal) and `tickInternal` (descent guard).
25
+ */
26
+ const DEFAULT_MAX_CALL_DEPTH = 64;
18
27
  /**
19
28
  * F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
20
29
  * by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
@@ -26,6 +35,17 @@ const DEFAULT_REAP_TTL_MS = 2 * 60 * 60 * 1000; // 2h
26
35
  export class SchemaRefusalError extends Error {
27
36
  inputName;
28
37
  issues;
38
+ /**
39
+ * B2: the gate fingerprint of the exact parent snapshot the failed validation
40
+ * saw, captured inside the validating transaction and attached before this
41
+ * error is rethrown out to `maintainCalls`. `recordCallsSchemaReject` compares
42
+ * it to the gate fingerprint at recording time so a refusal recorded after a
43
+ * concurrent VALID gate advance is discarded instead of stamped onto (and
44
+ * thereby stalling) the valid update. Mutable and optional: set by the thrower
45
+ * (`provisionCallsChild`) once the snapshot is known; absent means "no snapshot
46
+ * carried" and the recorder falls back to today's stamp-fresh behavior.
47
+ */
48
+ gateFingerprint;
29
49
  constructor(inputName, issues) {
30
50
  super(`input '${inputName}' failed schema: ${summarizeIssues(issues)}`);
31
51
  this.name = 'SchemaRefusalError';
@@ -37,6 +57,8 @@ export class Engine {
37
57
  store;
38
58
  resolveDef;
39
59
  reapTtlMs;
60
+ maxLeaseMs;
61
+ maxCallDepth;
40
62
  listeners = new Set();
41
63
  onListenerError;
42
64
  /** M2B: recursion guard — set of parentWf ids currently inside maintainCalls. */
@@ -45,6 +67,8 @@ export class Engine {
45
67
  this.store = store;
46
68
  this.resolveDef = resolveDef;
47
69
  this.reapTtlMs = opts.reapTtlMs ?? DEFAULT_REAP_TTL_MS;
70
+ this.maxLeaseMs = opts.maxLeaseMs;
71
+ this.maxCallDepth = opts.maxCallDepth ?? DEFAULT_MAX_CALL_DEPTH;
48
72
  if (opts.onEvent)
49
73
  this.listeners.add(opts.onEvent);
50
74
  this.onListenerError = opts.onListenerError;
@@ -67,46 +91,202 @@ export class Engine {
67
91
  createInstance(defName, opts = {}) {
68
92
  const def = this.resolveDef(defName);
69
93
  const id = randId('wf');
70
- this.store.tx(() => {
71
- // §28: pin this instance to the def it was created against — a snapshot
72
- // of the fully-expanded compiled def plus its content hash. Every new
73
- // instance is stamped; "no snapshot" is strictly a legacy-row
74
- // compatibility case (see defFor), never a choice made here.
75
- const wfData = { def: defName, defSnapshot: def, defHash: hashDef(def) };
76
- if (opts.title !== undefined)
77
- wfData.title = opts.title;
78
- if (opts.params !== undefined)
79
- wfData.params = opts.params;
80
- this.store.insertWorkflow(id, wfData, opts.producedBy);
81
- for (const input of def.inputs) {
82
- const provided = opts.provide?.[input.name];
83
- if (provided !== undefined && input.schema !== undefined) {
84
- const check = validateValue(input.schema, provided);
85
- if (!check.valid) {
86
- throw new SchemaRefusalError(input.name, check.issues);
94
+ this.store.tx(() => this.createInstanceInTx(defName, def, id, opts));
95
+ this.fire({ type: 'instance', workflow: id, def: defName });
96
+ this.fireSettled(id);
97
+ return id;
98
+ }
99
+ /**
100
+ * The transactional body of instance creation: persist the workflow row, seed
101
+ * its declared inputs (validating any provided values), and settle. MUST run
102
+ * inside a `store.tx()` — callers own the tx and the post-commit event firing.
103
+ * Extracted from {@link createInstance} so the atomic child-provision path
104
+ * ({@link provisionCallsChild}) can find-or-create a child and sync its inputs
105
+ * under a single `BEGIN IMMEDIATE` without nesting transactions.
106
+ */
107
+ createInstanceInTx(defName, def, id, opts) {
108
+ // §28: pin this instance to the def it was created against — a snapshot
109
+ // of the fully-expanded compiled def plus its content hash. Every new
110
+ // instance is stamped; "no snapshot" is strictly a legacy-row
111
+ // compatibility case (see defFor), never a choice made here.
112
+ const wfData = { def: defName, defSnapshot: def, defHash: hashDef(def) };
113
+ if (opts.title !== undefined)
114
+ wfData.title = opts.title;
115
+ if (opts.params !== undefined)
116
+ wfData.params = opts.params;
117
+ this.store.insertWorkflow(id, wfData, opts.producedBy);
118
+ for (const input of def.inputs) {
119
+ const provided = opts.provide?.[input.name];
120
+ if (provided !== undefined && input.schema !== undefined) {
121
+ const check = validateValue(input.schema, provided);
122
+ if (!check.valid) {
123
+ throw new SchemaRefusalError(input.name, check.issues);
124
+ }
125
+ }
126
+ const seedGreen = !input.seedOwed || provided !== undefined;
127
+ const a = {
128
+ workflow: id,
129
+ path: input.name,
130
+ producer: input.producer,
131
+ acceptance: seedGreen ? 'green' : 'owed',
132
+ version: seedGreen ? 1 : 0,
133
+ reasons: [],
134
+ judgmentRejects: 0,
135
+ schemaRejects: 0,
136
+ };
137
+ if (provided !== undefined)
138
+ a.value = provided;
139
+ this.store.putArtifact(a);
140
+ }
141
+ this.settle(id, def);
142
+ }
143
+ /**
144
+ * C2: atomic fresh-snapshot child provision for a `calls:` step — the
145
+ * creation-side mirror of `publishCallsGreen`'s discipline. Find-or-create the
146
+ * child AND synchronize every mapped child input, all inside ONE
147
+ * `BEGIN IMMEDIATE`, from a parent snapshot RE-READ inside that same tx — never
148
+ * from the caller's (STEP-1) snapshot. Because the write and every read it
149
+ * depends on share one write lock, the committed seed/sync values are by
150
+ * construction current at commit: "never regress a child input" needs no
151
+ * version comparison — the fresh in-tx read IS the guard.
152
+ *
153
+ * This closes two reproduced cross-connection races the STEP-1 snapshot exposed:
154
+ * (a) SPAWN — a child seeded from a stale parent value while a concurrent tick
155
+ * advanced the gate; (b) RE-PROVISION — a stale parent value stamped backward
156
+ * over a newer child input (version bumps, value regresses). `maintainCalls`'
157
+ * pre-reads (gate readiness, `findChildByParent`, F2 fingerprint, depth) are now
158
+ * OPTIMISTIC — they decide only WHETHER to attempt; this helper re-verifies
159
+ * everything the write depends on in-tx.
160
+ *
161
+ * Returns `{ childId, created, provided }` — `created` true only when THIS call
162
+ * inserted the child, `provided` the list of child inputs it actually re-wrote
163
+ * (empty for a plain spawn, since a fresh seed already equals the fresh
164
+ * snapshot). Events (`instance`, `commit`/`provide`, `settled`) and the child
165
+ * cascade are the caller's responsibility, fired post-commit, matching the
166
+ * pre-C2 per-action semantics. Returns `null` on a silent abort: the gate was
167
+ * re-armed, or an F2 schema-reject debt landed, since the pre-read — "not yet"
168
+ * state, next tick redoes the pass (publishCallsGreen discipline; no debt, no
169
+ * events written).
170
+ *
171
+ * A `SchemaRefusalError` (a seed or re-provided parent value illegal per the
172
+ * child's input schema) propagates out with the whole tx rolled back — no
173
+ * orphan child row, no partial input sync — preserving the F2 contract; the
174
+ * caller records it as a debt on the parent calls artifact.
175
+ */
176
+ provisionCallsChild(parentWf, step, callsStem, gateStems, now) {
177
+ // B2: the gate fingerprint of the exact in-tx snapshot the seed/re-provide
178
+ // validation ran against. Captured fresh inside `run()` so a retry re-reads
179
+ // it; carried out on a `SchemaRefusalError` so `recordCallsSchemaReject` can
180
+ // tell "gate unmoved since the failure" (stamp) from "a concurrent valid
181
+ // gate advance landed" (discard). Pure computation over the already-fetched
182
+ // `parentArts` — no extra in-tx store read (E2 busy_timeout GOTCHA-safe).
183
+ let seenGateFp;
184
+ const run = () => this.store.tx(() => {
185
+ // 1. FRESH parent snapshot — re-read inside the write lock; never trust
186
+ // the caller's STEP-1 map.
187
+ const parentArts = this.artMap(parentWf);
188
+ seenGateFp = computeFingerprint(parentArts, gateStems);
189
+ // 2. Gate readiness against the fresh snapshot: a stem re-armed
190
+ // concurrently must stop provisioning (abort silent — STEP-1 semantics).
191
+ if (!this.callsGateReady(parentArts, step))
192
+ return null;
193
+ // 3. In-tx F2 guard: an F2 schema-reject debt that landed concurrently
194
+ // (rejected + gate fingerprint unmoved) must not be provisioned over — a
195
+ // moved gate falls through and retries (mirrors STEP 2's optimistic guard).
196
+ // Read the calls artifact from the SAME fresh in-tx `parentArts` snapshot
197
+ // (listArtifacts), not a separate `store.getArtifact` — one consistent
198
+ // read, and it avoids adding a parent-calls-artifact read inside the write
199
+ // lock (which STEP-6's cross-connection tests count).
200
+ const parentCallsArt = parentArts.get(callsStem);
201
+ if (parentCallsArt?.acceptance === 'rejected') {
202
+ const fp = computeFingerprint(parentArts, gateStems);
203
+ if (deepEqual(fp, parentCallsArt.fingerprint ?? {}))
204
+ return null;
205
+ }
206
+ // 4. Find-or-create the child (in-tx check-then-insert — absorbs the old
207
+ // spawnChildIfAbsent guarantee, only its home moved).
208
+ let child = this.store.findChildByParent(parentWf, callsStem);
209
+ let created = false;
210
+ let childDef;
211
+ if (!child) {
212
+ const childId = randId('wf');
213
+ childDef = this.resolveDef(step.calls);
214
+ const seedProvide = {};
215
+ for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
216
+ const parentArt = parentArts.get(parentArtifactName);
217
+ if (parentArt?.value !== undefined) {
218
+ seedProvide[childInputName] = parentArt.value;
87
219
  }
88
220
  }
89
- const seedGreen = !input.seedOwed || provided !== undefined;
90
- const a = {
91
- workflow: id,
92
- path: input.name,
93
- producer: input.producer,
94
- acceptance: seedGreen ? 'green' : 'owed',
95
- version: seedGreen ? 1 : 0,
96
- reasons: [],
97
- judgmentRejects: 0,
98
- schemaRejects: 0,
99
- };
100
- if (provided !== undefined)
101
- a.value = provided;
102
- this.store.putArtifact(a);
221
+ // createInstanceInTx validates the seed against the child input schema
222
+ // and throws SchemaRefusalError (tx rolls back — no orphan child).
223
+ this.createInstanceInTx(step.calls, childDef, childId, {
224
+ producedBy: { parentWf, parentPath: callsStem },
225
+ provide: seedProvide,
226
+ });
227
+ child = this.store.getWorkflow(childId);
228
+ created = true;
229
+ }
230
+ else {
231
+ // §28: read the existing child per its own pinned snapshot.
232
+ childDef = this.defFor(child.id);
233
+ }
234
+ // 5. Synchronize EVERY mapped child input from the SAME fresh snapshot.
235
+ // A freshly-seeded child already equals the snapshot, so its inputs
236
+ // no-op here (no spurious provide for a plain spawn). This is the exact
237
+ // body of `provideInput`, inlined so it shares this tx (store.tx forbids
238
+ // re-entrancy) — behavior identical, all-or-nothing on refusal.
239
+ const childArts = this.artMap(child.id);
240
+ const provided = [];
241
+ for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
242
+ const parentArt = parentArts.get(parentArtifactName);
243
+ if (parentArt?.value === undefined)
244
+ continue; // nothing to provide
245
+ const childArt = childArts.get(childInputName);
246
+ if (!childArt)
247
+ throw new Error(`no such input artifact: ${childInputName}`);
248
+ if (deepEqual(parentArt.value, childArt.value))
249
+ continue; // already current
250
+ const inputDef = childDef.inputs.find((i) => i.name === childInputName);
251
+ if (inputDef?.schema !== undefined) {
252
+ const check = validateValue(inputDef.schema, parentArt.value);
253
+ if (!check.valid)
254
+ throw new SchemaRefusalError(childInputName, check.issues);
255
+ }
256
+ this.store.putArtifact({
257
+ ...childArt,
258
+ acceptance: 'green',
259
+ version: childArt.version + 1,
260
+ value: parentArt.value,
261
+ });
262
+ provided.push(childInputName);
103
263
  }
104
- this.settle(id, def);
105
- return id;
264
+ // 6. Settle the child if we wrote anything (matches createInstanceInTx /
265
+ // provideInput). A fresh spawn already settled inside createInstanceInTx;
266
+ // re-settling is a cheap fixpoint no-op.
267
+ if (created || provided.length > 0)
268
+ this.settle(child.id, childDef, now);
269
+ return { childId: child.id, created, provided };
106
270
  });
107
- this.fire({ type: 'instance', workflow: id, def: defName });
108
- this.fireSettled(id);
109
- return id;
271
+ try {
272
+ return run();
273
+ }
274
+ catch (err) {
275
+ // UNIQUE-index backstop for any future concurrent writer not serialized by
276
+ // BEGIN IMMEDIATE: the whole failed tx rolled back, so a single retry finds
277
+ // the winner in-tx and syncs its inputs. Unreachable under node:sqlite's
278
+ // synchronous, write-lock-serialized connections, but cheap and correct.
279
+ if (err instanceof Error &&
280
+ /UNIQUE constraint failed: workflow\.produced_by_wf/.test(err.message)) {
281
+ return run();
282
+ }
283
+ // B2: tag a child-input schema refusal with the gate fingerprint the failed
284
+ // validation actually saw, so the recorder can discard it if the gate has
285
+ // since moved to a valid value on another connection.
286
+ if (err instanceof SchemaRefusalError)
287
+ err.gateFingerprint = seenGateFp;
288
+ throw err;
289
+ }
110
290
  }
111
291
  /** A human/external producer supplies (greens) an owed input. */
112
292
  provideInput(workflow, name, value) {
@@ -208,15 +388,34 @@ export class Engine {
208
388
  * Stamps the current gate fingerprint on the rejected artifact so the
209
389
  * STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
210
390
  * worth retrying" on the next tick.
391
+ *
392
+ * B2 (snapshot-consistent recording): `seenGateFp` is the gate fingerprint of
393
+ * the exact snapshot the failed validation saw (carried on the
394
+ * `SchemaRefusalError`). Inside the recording tx we recompute the CURRENT gate
395
+ * fingerprint and compare:
396
+ * - equal → the gate has not moved since the failure: stamp the rejection.
397
+ * - not equal → a concurrent VALID gate advance landed between the validation
398
+ * and here: DISCARD the now-obsolete refusal (write nothing). Stamping it
399
+ * would freeze the valid update as `rejected` because the STEP-2 F2 guard
400
+ * would then read "gate unmoved, don't retry".
401
+ * - `seenGateFp` undefined (defensive; the sole call site always carries one)
402
+ * → legacy stamp-fresh behavior.
403
+ * Returns true only when it actually stamped, so the caller fires the
404
+ * schema-rejected / settled events only on a real write (a discarded refusal
405
+ * is silent — abort discipline, mirroring `publishCallsGreen`).
211
406
  */
212
- recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, now) {
407
+ recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, seenGateFp, now) {
213
408
  const text = `child input '${err.inputName}' failed schema: ${summarizeIssues(err.issues)}`;
214
- this.store.tx(() => {
409
+ return this.store.tx(() => {
215
410
  const art = this.store.getArtifact(parentWf, callsStem);
216
411
  if (!art)
217
- return; // not yet materialized by pendingOwed — nothing to stamp
412
+ return false; // not yet materialized by pendingOwed — nothing to stamp
218
413
  const gateArts = this.artMap(parentWf);
219
414
  const fp = computeFingerprint(gateArts, gateStems);
415
+ // B2: gate moved to a different value since the validation failed → the
416
+ // refusal is stale; discard it and let the concurrent valid update proceed.
417
+ if (seenGateFp !== undefined && !deepEqual(fp, seenGateFp))
418
+ return false;
220
419
  this.store.putArtifact({
221
420
  ...art,
222
421
  acceptance: 'rejected',
@@ -225,8 +424,66 @@ export class Engine {
225
424
  reasons: [...art.reasons, reason('schema-reject', 'validation', 'engine', text, art.version)],
226
425
  });
227
426
  this.settle(parentWf, def, now);
427
+ return true;
228
428
  });
229
- this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject', outcome: 'schema-rejected' });
429
+ }
430
+ /**
431
+ * REL-4: the `calls:` ancestry depth of an instance — how many `producedBy`
432
+ * parent links separate it from the root of its composed tree. A root
433
+ * instance (no `producedBy`) is depth 0; a child spawned by the root is
434
+ * depth 1; and so on. O(depth) — walks the parent chain, which is exactly the
435
+ * tree the spawn bound is protecting, so it only runs on an actual spawn.
436
+ */
437
+ callsAncestryDepth(workflow) {
438
+ let depth = 0;
439
+ let cur = this.store.getWorkflow(workflow);
440
+ while (cur?.producedBy) {
441
+ depth++;
442
+ cur = this.store.getWorkflow(cur.producedBy.parentWf);
443
+ }
444
+ return depth;
445
+ }
446
+ /**
447
+ * REL-4: record a `calls:` depth-limit refusal as a debt on the PARENT calls
448
+ * artifact — same clean-stop mechanism as `recordCallsSchemaReject` (mark it
449
+ * `rejected`, stamp the current gate fingerprint so the STEP-2 F2 guard skips
450
+ * re-attempts on later ticks), but the reason is a plain structural rejection,
451
+ * NOT a schema failure: it does not touch `schemaRejects` (that counter gates
452
+ * `maxSchemaFailures` and means something specific). The message is actionable
453
+ * — a depth-limit trip almost always means a `calls:` cycle in the def set
454
+ * bypassed load-time validation (a hand-wired resolver construction validation
455
+ * cannot see); raising `maxCallDepth` is only correct when the depth is truly
456
+ * intentional. Stopping here — instead of spawning — is what prevents the
457
+ * unbounded row creation + stack overflow REL-4 describes.
458
+ *
459
+ * B2 asymmetry (deliberate, NOT an oversight): unlike `recordCallsSchemaReject`
460
+ * this recorder is NOT exposed to the wrong-snapshot race, so it needs no
461
+ * carry-and-compare guard. A depth refusal's validity does not depend on the
462
+ * gate snapshot: `callsAncestryDepth` walks the immutable `producedBy` chain and
463
+ * `maxCallDepth` is fixed, so a refusal decided at time T stays valid at
464
+ * recording time regardless of concurrent gate movement — and if a moved-gate
465
+ * re-attempt were somehow blocked, it would deterministically re-trip the same
466
+ * depth refusal anyway (identical outcome, no lost valid update to strand).
467
+ */
468
+ recordCallsDepthReject(parentWf, def, callsStem, gateStems, childDefName, now) {
469
+ const text = `calls depth limit reached (maxCallDepth=${this.maxCallDepth}) spawning '${childDefName}': `
470
+ + `this usually means a calls: cycle in the definition set bypassed load-time validation; `
471
+ + `raise maxCallDepth via Engine opts only if this depth is intentional`;
472
+ this.store.tx(() => {
473
+ const art = this.store.getArtifact(parentWf, callsStem);
474
+ if (!art)
475
+ return; // not yet materialized by pendingOwed — nothing to stamp
476
+ const gateArts = this.artMap(parentWf);
477
+ const fp = computeFingerprint(gateArts, gateStems);
478
+ this.store.putArtifact({
479
+ ...art,
480
+ acceptance: 'rejected',
481
+ fingerprint: fp,
482
+ reasons: [...art.reasons, reason('reject', 'structural', 'engine', text, art.version)],
483
+ });
484
+ this.settle(parentWf, def, now);
485
+ });
486
+ this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject' });
230
487
  this.fireSettled(parentWf);
231
488
  }
232
489
  /**
@@ -249,8 +506,7 @@ export class Engine {
249
506
  const callsPath = callsStem;
250
507
  const gateStems = Object.values(step.callsInputs ?? {});
251
508
  const parentArts = this.artMap(parentWf);
252
- const gateReady = gateStems.length === 0 || gateStems.every((s) => isGreen(parentArts.get(s)));
253
- if (!gateReady)
509
+ if (!this.callsGateReady(parentArts, step))
254
510
  continue;
255
511
  // STEP 2 — Look up any existing child via reverse index.
256
512
  let existingChild = this.store.findChildByParent(parentWf, callsPath);
@@ -267,39 +523,71 @@ export class Engine {
267
523
  if (deepEqual(currentGateFp, parentCallsArtPre.fingerprint ?? {}))
268
524
  continue;
269
525
  }
270
- // STEP 3 — SPAWN or RE-ATTACH.
271
- if (!existingChild) {
272
- // SPAWN: gate is ready and no child exists yet.
273
- const seedProvide = {};
274
- for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
275
- const parentArt = parentArts.get(parentArtifactName);
276
- if (parentArt?.value !== undefined)
277
- seedProvide[childInputName] = parentArt.value;
278
- }
279
- // F2: a child input-schema refusal here is not a bug — a parent
280
- // value can be legal per the parent's own schema (looser, or absent)
281
- // yet illegal per the child's declared input schema. Catch narrowly
282
- // (SchemaRefusalError only; anything else is a genuine bug and must
283
- // still throw) and record it as a debt on the PARENT calls artifact,
284
- // mirroring green()'s schema-reject branch, so the tick proceeds
285
- // instead of crash-looping every subsequent tick(parent).
286
- let childId;
287
- try {
288
- childId = this.createInstance(step.calls, {
289
- producedBy: { parentWf, parentPath: callsPath },
290
- provide: seedProvide,
291
- });
292
- }
293
- catch (err) {
294
- if (err instanceof SchemaRefusalError) {
295
- this.recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, now);
296
- continue;
526
+ // STEP 3 — SPAWN or RE-PROVISION, atomically against a FRESH snapshot.
527
+ //
528
+ // REL-4 spawn-time depth bound (the guard that prevents row bloat). Only an
529
+ // OPTIMISTIC pre-check, and only when no child exists yet: a self- or
530
+ // cross-calling def whose cycle slipped past load-time validation would
531
+ // otherwise mint a fresh child instance (a new DB row) at every recursion
532
+ // level until the process stack overflows. `callsAncestryDepth` walks the
533
+ // `producedBy` chain, which is immutable after insert, so it cannot race and
534
+ // needs no in-tx recheck. Record a rejection on the parent calls artifact
535
+ // (clean stop; the STEP-2 F2 fingerprint guard then skips re-attempts).
536
+ if (!existingChild && this.callsAncestryDepth(parentWf) >= this.maxCallDepth) {
537
+ this.recordCallsDepthReject(parentWf, def, callsStem, gateStems, step.calls, now);
538
+ continue;
539
+ }
540
+ // The find-or-create AND every mapped input sync happen in ONE
541
+ // BEGIN IMMEDIATE inside the helper, from a parent snapshot RE-READ in that
542
+ // tx — so a child is never CREATED or WRITTEN from a snapshot older than its
543
+ // committing transaction (closes the SPAWN and RE-PROVISION races). The
544
+ // pre-reads above (gate readiness, findChildByParent, F2 fingerprint, depth)
545
+ // are optimistic — they decide only whether to attempt; the helper
546
+ // re-verifies in-tx and aborts (returns null) if the gate re-armed or an F2
547
+ // debt landed since. F2: a child input-schema refusal (seed or re-provide)
548
+ // is not a bug — a parent value legal per the parent's own schema can be
549
+ // illegal per the child's — so it rolls the whole provision tx back and
550
+ // becomes a debt on the PARENT calls artifact (mirroring green()'s
551
+ // schema-reject branch) instead of crash-looping every subsequent tick.
552
+ let provision;
553
+ try {
554
+ provision = this.provisionCallsChild(parentWf, step, callsStem, gateStems, now);
555
+ }
556
+ catch (err) {
557
+ if (err instanceof SchemaRefusalError) {
558
+ // B2: pass the fingerprint the failed validation saw. If the gate has
559
+ // since moved (a concurrent valid update), the recorder discards the
560
+ // refusal and returns false — fire no schema-rejected event, and let
561
+ // the next pass provision against the now-valid gate.
562
+ if (this.recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, err.gateFingerprint, now)) {
563
+ this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject', outcome: 'schema-rejected' });
564
+ this.fireSettled(parentWf);
297
565
  }
298
- throw err;
566
+ continue;
299
567
  }
300
- existingChild = this.store.getWorkflow(childId);
568
+ throw err;
569
+ }
570
+ if (!provision)
571
+ continue; // silent abort (gate re-armed / F2 debt landed) — next tick retries.
572
+ // Post-commit events, matching the pre-C2 per-action semantics exactly:
573
+ // only the creating connection fires `instance`; each re-provided input
574
+ // fires a commit/provide as provideInput did; a settled + one cascade run
575
+ // (idempotent maintenance — once per provision, not once per input) so a
576
+ // grandchild gets re-provided in the same pass.
577
+ if (provision.created) {
578
+ this.fire({ type: 'instance', workflow: provision.childId, def: step.calls });
579
+ this.fireSettled(provision.childId);
301
580
  }
302
- // else: RE-ATTACH — existingChild is the already-spawned child; no new spawn.
581
+ for (const name of provision.provided) {
582
+ this.fire({ type: 'commit', workflow: provision.childId, path: name, action: 'provide' });
583
+ }
584
+ if (provision.provided.length > 0) {
585
+ this.fireSettled(provision.childId);
586
+ // provideInput's cascade-up, outside the tx (store.tx forbids re-entrancy);
587
+ // the _inMaintainCalls guard keys on parentWf, so this nested call is safe.
588
+ this.maintainCalls(provision.childId, this.defFor(provision.childId), now);
589
+ }
590
+ existingChild = this.store.getWorkflow(provision.childId);
303
591
  if (!existingChild)
304
592
  continue; // defensive: createInstance returned but getWorkflow failed
305
593
  // STEP 4 — Read child's declared outcome artifact.
@@ -309,30 +597,22 @@ export class Engine {
309
597
  const childOutcomeStem = childDef.outputs[0]; // validated by Phase-2 check
310
598
  let childArts = this.artMap(existingChild.id);
311
599
  let childOutcomeArt = childArts.get(childOutcomeStem);
312
- // STEP 5 — RE-PROVIDE if parent gate source moved (M2B-REPROVIDE).
313
- // F2: same typed-refusal handling as STEP 3 — a re-provided parent
314
- // value illegal per the child's input schema becomes a debt on the
315
- // parent calls artifact instead of throwing out of provideInput's
316
- // cascade-up. The human's own provide of the PARENT input still
317
- // commits (that validation happens against the PARENT's schema,
318
- // inside provideInput's own tx, before this cascade ever runs).
319
- for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
320
- const parentArtNow = parentArts.get(parentArtifactName);
321
- const childInputArt = childArts.get(childInputName);
322
- if (parentArtNow?.value !== undefined && !deepEqual(parentArtNow.value, childInputArt?.value)) {
323
- try {
324
- this.provideInput(existingChild.id, childInputName, parentArtNow.value);
325
- }
326
- catch (err) {
327
- if (err instanceof SchemaRefusalError) {
328
- this.recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, now);
329
- continue;
330
- }
331
- throw err;
332
- }
333
- }
334
- }
335
600
  // STEP 6 — MACHINE-GREEN or STAY OWED (M2B-CASCADEUP).
601
+ //
602
+ // The reads below are an OPTIMISTIC gate ONLY: they decide whether to
603
+ // *attempt* a publish or a re-arm — never what to publish. The write,
604
+ // and a re-read+re-verify of every input it depends on, happen together
605
+ // inside one BEGIN IMMEDIATE in the helper (publishCallsGreen /
606
+ // rearmCallsGreen). Under WAL + BEGIN IMMEDIATE no other connection can
607
+ // commit between that in-tx re-read and the write, so a cross-connection
608
+ // interleave — the parent gate advanced to a newer version, or the child
609
+ // outcome re-armed, between this stale pre-read and the write — is caught
610
+ // in-tx and the pass aborts (helper returns false, nothing written),
611
+ // deferring to the next tick. The published value, the gate fingerprint
612
+ // it claims, and the child-outcome pin therefore always come from ONE
613
+ // atomic snapshot. commit/settled events fire only when the helper wrote,
614
+ // so an aborted pass is silent to listeners.
615
+ //
336
616
  // Re-read after potential re-provide.
337
617
  childArts = this.artMap(existingChild.id);
338
618
  childOutcomeArt = childArts.get(childOutcomeStem);
@@ -351,29 +631,16 @@ export class Engine {
351
631
  // (propagated down, parent reopened to owed pinned to the rejected
352
632
  // child version) or a human skip (pinned at skip time) stand until
353
633
  // the child actually rebuilds past that pin, instead of being
354
- // silently overridden on the very next tick.
634
+ // silently overridden on the very next tick. (Re-checked in-tx by
635
+ // the helper against the snapshot it commits under.)
355
636
  const pinnedVersion = parentCallsArt?.fingerprint?.[Engine.CHILD_OUTCOME_PIN_KEY];
356
637
  const pastPin = pinnedVersion === undefined || childOutcomeArt.version > pinnedVersion;
357
- if ((!alreadyGreen || !sameValue) && pastPin) {
358
- if (!parentCallsArt)
359
- continue; // not yet materialized by pendingOwed — skip
360
- const gateArts = this.artMap(parentWf);
361
- const fp = computeFingerprint(gateArts, gateStems);
362
- fp[Engine.CHILD_OUTCOME_PIN_KEY] = childOutcomeArt.version;
363
- const next = {
364
- ...parentCallsArt,
365
- acceptance: 'green',
366
- version: parentCallsArt.version + 1,
367
- value: childOutcomeArt.value,
368
- fingerprint: fp,
369
- };
370
- // Do NOT set terminal: calls: artifact must be re-armable if gate inputs move.
371
- this.store.tx(() => {
372
- this.store.putArtifact({ ...next, workflow: parentWf });
373
- this.settle(parentWf, def, now);
374
- });
375
- this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'provide' });
376
- this.fireSettled(parentWf);
638
+ if ((!alreadyGreen || !sameValue) && pastPin && parentCallsArt) {
639
+ // parentCallsArt truthy: not-yet-materialized (pendingOwed) → skip.
640
+ if (this.publishCallsGreen(parentWf, def, step, callsStem, gateStems, existingChild.id, childOutcomeStem, now)) {
641
+ this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'provide' });
642
+ this.fireSettled(parentWf);
643
+ }
377
644
  }
378
645
  }
379
646
  else if (!isGreen(childOutcomeArt) && isGreen(parentCallsArt) && parentCallsArt) {
@@ -381,26 +648,10 @@ export class Engine {
381
648
  // but the parent calls: artifact is still green. Re-arm it to owed so downstream
382
649
  // re-runs when the child completes again. This handles gate re-arm (test f):
383
650
  // the cascade can't detect this because deliver step has consumes: [].
384
- this.store.tx(() => {
385
- const artNow = this.store.getArtifact(parentWf, callsStem);
386
- if (!artNow || !isGreen(artNow))
387
- return; // already re-armed or gone
388
- this.store.putArtifact({
389
- ...artNow,
390
- acceptance: 'owed',
391
- reasons: [...artNow.reasons, {
392
- at: nowMs(),
393
- action: 'reopen',
394
- kind: 'structural',
395
- by: 'engine',
396
- text: 'gate input moved: child re-running',
397
- fromVersion: artNow.version,
398
- }],
399
- });
400
- this.settle(parentWf, def, now);
401
- });
402
- this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'retry' });
403
- this.fireSettled(parentWf);
651
+ if (this.rearmCallsGreen(parentWf, def, callsStem, existingChild.id, childOutcomeStem, now)) {
652
+ this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'retry' });
653
+ this.fireSettled(parentWf);
654
+ }
404
655
  }
405
656
  }
406
657
  }
@@ -408,6 +659,120 @@ export class Engine {
408
659
  this._inMaintainCalls.delete(parentWf);
409
660
  }
410
661
  }
662
+ /**
663
+ * The seed/consistency invariant for a `calls:` step: every child input wired
664
+ * from a parent gate artifact whose value is defined must currently deepEqual
665
+ * that gate value. STEP 6's in-tx verify calls this; STEP 5's re-provide
666
+ * condition applies the same per-input invariant inline (mirrored, not a call
667
+ * here) — the two encode the same rule and must be kept in step by hand. Both
668
+ * skip when the parent gate value is undefined (nothing to provide). A mismatch
669
+ * means a re-provide is pending against the very gate a fresh fingerprint would
670
+ * claim, so publishing now would stamp a stale child value under a newer gate.
671
+ */
672
+ childConsistentWithGate(parentArts, childArts, step) {
673
+ for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
674
+ const parentArt = parentArts.get(parentArtifactName);
675
+ if (parentArt?.value === undefined)
676
+ continue;
677
+ const childInputArt = childArts.get(childInputName);
678
+ if (!deepEqual(parentArt.value, childInputArt?.value))
679
+ return false;
680
+ }
681
+ return true;
682
+ }
683
+ /**
684
+ * STEP 6 machine-green as an atomic snapshot-and-commit. maintainCalls'
685
+ * optimistic pre-reads decide only WHETHER to call this; the decision inputs
686
+ * are all re-read and re-verified here INSIDE the same BEGIN IMMEDIATE that
687
+ * performs the write, so the published value, the gate fingerprint it claims,
688
+ * and the child-outcome pin come from ONE snapshot. Any verify failing aborts
689
+ * the publish (returns false; the commit is a no-op — do NOT throw, there is
690
+ * nothing to roll back, and an abort must not record debt/reasons/fingerprint:
691
+ * the state is simply "not yet" and the next tick redoes the pass against
692
+ * fresh state). Returns true only when it actually wrote, so the caller fires
693
+ * commit/settled events only on a real publish.
694
+ */
695
+ publishCallsGreen(parentWf, def, step, callsStem, gateStems, expectedChildId, childOutcomeStem, now) {
696
+ return this.store.tx(() => {
697
+ const parentArts = this.artMap(parentWf);
698
+ const parentCallsArt = this.store.getArtifact(parentWf, callsStem);
699
+ // Vanished, or an F2 schema-reject debt landed since the pre-read → abort.
700
+ if (!parentCallsArt || parentCallsArt.acceptance === 'rejected')
701
+ return false;
702
+ // Same child the optimistic read saw; a different id means the tree moved.
703
+ const child = this.store.findChildByParent(parentWf, callsStem);
704
+ if (!child || child.id !== expectedChildId)
705
+ return false;
706
+ const childArts = this.artMap(child.id);
707
+ const childOutcomeArt = childArts.get(childOutcomeStem);
708
+ // Child re-armed between the pre-read and here → defer.
709
+ if (!childOutcomeArt || !isGreen(childOutcomeArt) || childOutcomeArt.value === undefined)
710
+ return false;
711
+ // Gate still ready, and the child still consistent with the gate values
712
+ // the fingerprint is about to claim (the heart of the fix).
713
+ if (!this.callsGateReady(parentArts, step))
714
+ return false;
715
+ if (!this.childConsistentWithGate(parentArts, childArts, step))
716
+ return false;
717
+ // Idempotent no-op: another connection already published this exact value.
718
+ const alreadyGreen = isGreen(parentCallsArt);
719
+ if (alreadyGreen && deepEqual(childOutcomeArt.value, parentCallsArt.value))
720
+ return false;
721
+ // F4 version pin, recomputed from the in-tx child outcome version.
722
+ const pinnedVersion = parentCallsArt.fingerprint?.[Engine.CHILD_OUTCOME_PIN_KEY];
723
+ if (pinnedVersion !== undefined && childOutcomeArt.version <= pinnedVersion)
724
+ return false;
725
+ const fp = computeFingerprint(parentArts, gateStems);
726
+ fp[Engine.CHILD_OUTCOME_PIN_KEY] = childOutcomeArt.version;
727
+ // Do NOT set terminal: calls: artifact must be re-armable if gate inputs move.
728
+ this.store.putArtifact({
729
+ ...parentCallsArt,
730
+ acceptance: 'green',
731
+ version: parentCallsArt.version + 1,
732
+ value: childOutcomeArt.value,
733
+ fingerprint: fp,
734
+ }, { action: 'provided', actor: 'engine', reason: 'child outcome provided' });
735
+ this.settle(parentWf, def, now);
736
+ return true;
737
+ });
738
+ }
739
+ /**
740
+ * STEP 6 re-arm as the mirror-image atomic guard. maintainCalls' optimistic
741
+ * pre-read decides only WHETHER to call this; the parent artifact AND the
742
+ * child outcome are re-read inside the write lock, and the re-arm happens only
743
+ * if the parent is still green AND the child outcome is still NOT green in-tx.
744
+ * If the child went green between the optimistic read and the tx, this does
745
+ * nothing (returns false) and the next maintainCalls pass publishes normally.
746
+ * Returns true only when it wrote.
747
+ */
748
+ rearmCallsGreen(parentWf, def, callsStem, expectedChildId, childOutcomeStem, now) {
749
+ return this.store.tx(() => {
750
+ const artNow = this.store.getArtifact(parentWf, callsStem);
751
+ if (!artNow || !isGreen(artNow))
752
+ return false; // already re-armed or gone
753
+ const child = this.store.findChildByParent(parentWf, callsStem);
754
+ if (!child || child.id !== expectedChildId)
755
+ return false;
756
+ const childOutcomeArt = this.artMap(child.id).get(childOutcomeStem);
757
+ // Child went green in-tx → don't re-arm; let the green branch publish next pass.
758
+ if (isGreen(childOutcomeArt))
759
+ return false;
760
+ this.store.putArtifact({
761
+ ...artNow,
762
+ acceptance: 'owed',
763
+ reasons: [...artNow.reasons, {
764
+ at: nowMs(),
765
+ action: 'reopen',
766
+ kind: 'structural',
767
+ by: 'engine',
768
+ text: 'gate input moved: child re-running',
769
+ fromVersion: artNow.version,
770
+ }],
771
+ });
772
+ this.settle(parentWf, def, now);
773
+ return true;
774
+ });
775
+ }
411
776
  /**
412
777
  * M2B cascade-up prompt: if `workflow` has a producedBy link, trigger
413
778
  * maintainCalls on its parent so the parent reflects the child's progress promptly.
@@ -430,19 +795,105 @@ export class Engine {
430
795
  this.fireSettled(parentWf);
431
796
  }
432
797
  // ---- the tick (maintain → reap → eligible → cadence/budget → claim) --------
798
+ /**
799
+ * Pull eligible orders for `workflow`. §23.6.8: **deep by default** — after
800
+ * maintaining and ticking this instance, descend into every live `calls:`
801
+ * child (recursively, grandchildren too) and fold their orders / reaps /
802
+ * deferrals / `dueAt` into the returned result so a driver that ticks only
803
+ * the root drives the whole composed tree (a shallow tick would deadlock a
804
+ * `calls:` workflow — the child's eligible steps would never be claimed).
805
+ * Pass `{ deep: false }` (CLI `--shallow`) to restore the pre-deep behavior:
806
+ * only this instance's own orders. See `TickResult` for the fold semantics.
807
+ */
433
808
  tick(workflow, opts = {}) {
809
+ return this.tickInternal(workflow, opts.now ?? nowMs(), opts.deep ?? true, opts.labels ?? [], new Set(), 0);
810
+ }
811
+ /**
812
+ * The recursive tick worker. Runs this instance's own maintain → reap →
813
+ * eligible → claim cycle (its body is byte-for-byte the pre-deep `tick`,
814
+ * kept inside its own `store.tx`), then — when `deep` — descends into each
815
+ * live `calls:` child by calling itself again. The descent MUST run OUTSIDE
816
+ * this frame's `store.tx`: `store.tx` forbids re-entrancy, and every child
817
+ * frame opens its own tx (via its own `maintainCalls` + tick body), so a
818
+ * child is driven by a full nested `tickInternal`, never a child tx opened
819
+ * inside the parent's.
820
+ *
821
+ * REL-4: `visited` (a set of workflow INSTANCE ids) is NOT a sufficient guard
822
+ * against a `calls:` cycle. Each descent level's `maintainCalls` SPAWNS a
823
+ * brand-new child instance, so a self-calling def produces a fresh id at every
824
+ * level — `visited` never trips, and recursion would run unbounded (one DB row
825
+ * per level) until the stack overflows. The real guard is the `maxCallDepth`
826
+ * bound: `maintainCalls` refuses to spawn past it (so a newly-created tree can
827
+ * never get here too deep), and the `depth` check below is the belt-and-braces
828
+ * backstop for a PRE-EXISTING deep tree (e.g. a DB written by an older build
829
+ * before the spawn bound existed) — it throws rather than overflow the stack.
830
+ * `visited` still earns its keep as a re-entrancy guard for a genuinely
831
+ * re-encountered instance within one tick.
832
+ *
833
+ * B1 (in-tx descent claim guard): a deep parent descends into a child by
834
+ * calling this again with `parentEdge` — the calls: edge the child hangs
835
+ * from. Inside the child frame's OWN claim tx, before any child order is
836
+ * issued, we re-verify that the parent gate and the child's synchronized
837
+ * inputs are still mutually consistent with the CURRENTLY-committed parent
838
+ * state (the same predicate `publishCallsGreen` uses on the publish side).
839
+ * `provisionCallsChild` commits child input v1; another connection can advance
840
+ * the parent to v2 before this non-transactional descent claims — without the
841
+ * guard the child claims work against the stale v1. On mismatch the frame
842
+ * issues nothing and its subtree is not descended; the next parent tick
843
+ * re-synchronizes via `maintainCalls`. Absent `parentEdge` = the root frame,
844
+ * unguarded (nothing above it to be inconsistent with). Each frame checks only
845
+ * its IMMEDIATE parent edge; a grandchild gets its own edge from the child
846
+ * frame's descent loop, so every issued order in the tree is guarded by the
847
+ * edge it hangs from. The guard is silent (no debt/reasons/events), mirroring
848
+ * the abort discipline of `publishCallsGreen`/`provisionCallsChild`.
849
+ */
850
+ tickInternal(workflow, now, deep, labels, visited, depth, parentEdge) {
851
+ if (depth > this.maxCallDepth) {
852
+ throw new Error(`calls depth limit exceeded (maxCallDepth=${this.maxCallDepth}) ticking '${workflow}': `
853
+ + `a calls: composition is deeper than the bound, which usually means a calls: cycle `
854
+ + `in the definition set; raise maxCallDepth via Engine opts only if this depth is intentional`);
855
+ }
856
+ if (visited.has(workflow))
857
+ return { workflow, orders: [], reaped: 0, deferred: [] };
858
+ visited.add(workflow);
434
859
  const def = this.defFor(workflow);
435
- const now = opts.now ?? nowMs();
436
860
  // M2B: maintain calls: child instances before the normal tick/reap/claim cycle.
437
861
  this.maintainCalls(workflow, def, now);
438
- return this.store.tx(() => {
862
+ // B1: set inside the frame tx when the parent↔child consistency guard fires;
863
+ // read after the tx to suppress this subtree's descent too.
864
+ let staleEdge = false;
865
+ const result = this.store.tx(() => {
439
866
  this.settle(workflow, def, now);
440
867
  const reaped = this.reap(workflow, now, def);
441
868
  const arts = this.artMap(workflow);
869
+ // B1: in-tx descent claim guard. `arts` is THIS (child) frame's snapshot,
870
+ // already read inside the write lock. Re-verify the immediate parent edge
871
+ // against ONE fresh in-tx parent snapshot (`artMap`/`listArtifacts`, NOT a
872
+ // separate `store.getArtifact` for the calls key — E2 busy_timeout GOTCHA)
873
+ // before claiming any order. Reuses the exact descend condition (Fix B3's
874
+ // owed-only) and `publishCallsGreen`'s gate-ready + child-consistency
875
+ // predicates, so claim-side and publish-side never drift. On mismatch the
876
+ // parent advanced since provision: settle/reap already ran and stay (both
877
+ // child-local and useful), but this frame issues no firings/claims and its
878
+ // subtree is skipped below. Next parent tick re-synchronizes.
879
+ if (parentEdge) {
880
+ const pArts = this.artMap(parentEdge.parentWf);
881
+ const callsArt = pArts.get(parentEdge.callsStem);
882
+ if (callsArt?.acceptance !== 'owed'
883
+ || !this.callsGateReady(pArts, parentEdge.step)
884
+ || !this.childConsistentWithGate(pArts, arts, parentEdge.step)) {
885
+ staleEdge = true;
886
+ const dueAt = this.computeDueAt(def, workflow, now);
887
+ const r = { workflow, orders: [], reaped, deferred: [] };
888
+ if (dueAt !== null)
889
+ r.dueAt = dueAt;
890
+ return r;
891
+ }
892
+ }
442
893
  // Compute time facts for idle eligibility (clock-read boundary).
443
894
  const timeFacts = this.computeTimeFacts(def, workflow, arts, now);
444
895
  const firings = eligibleFirings(def, arts, timeFacts);
445
- const { selected, deferred } = this.applySchedule(workflow, def, firings, now);
896
+ const { selected, deferred } = this.applySchedule(workflow, def, firings, now, labels);
446
897
  // Clear alarm_at for any idle firing that was selected (consume the alarm).
447
898
  for (const f of selected) {
448
899
  if (f.cause === 'idle') {
@@ -452,27 +903,111 @@ export class Engine {
452
903
  const orders = [];
453
904
  const allDeferred = [...deferred];
454
905
  for (const f of selected) {
455
- const result = this.claim(workflow, def, f, arts, now);
456
- if (result === 'in-flight') {
906
+ const claimed = this.claim(workflow, def, f, arts, now);
907
+ if (claimed === 'in-flight') {
457
908
  const d = { step: f.step, key: f.key, inputs: f.inputs, outputs: f.outputs, reason: 'in-flight' };
458
909
  if (f.index !== undefined)
459
910
  d.index = f.index;
460
911
  allDeferred.push(d);
461
912
  }
462
- else if (result) {
463
- orders.push(result);
913
+ else if (claimed) {
914
+ orders.push(claimed);
464
915
  }
465
916
  }
466
917
  // E-DUE: compute earliest pending time-trigger for the result.
467
918
  const dueAt = this.computeDueAt(def, workflow, now);
468
- const result = { workflow, orders, reaped, deferred: allDeferred };
919
+ const r = { workflow, orders, reaped, deferred: allDeferred };
469
920
  if (dueAt !== null)
470
- result.dueAt = dueAt;
471
- return result;
921
+ r.dueAt = dueAt;
922
+ return r;
472
923
  });
924
+ // §23.6.8 DESCENT — outside this frame's tx (see method doc). Drive each
925
+ // live calls: child with its own full tickInternal and fold its result up.
926
+ // B1: when this frame's own inputs are disputed (guard fired), skip the whole
927
+ // subtree — do not tick grandchildren off a frame that issued nothing.
928
+ if (deep && !staleEdge) {
929
+ for (const { step, child } of this.callsDescendTargets(workflow, def)) {
930
+ const cr = this.tickInternal(child.id, now, deep, labels, visited, depth + 1, {
931
+ parentWf: workflow,
932
+ step,
933
+ callsStem: step.produces[0].stem,
934
+ });
935
+ // orders: flatten; each Order already carries its own `workflow`.
936
+ result.orders.push(...cr.orders);
937
+ // deferred: stamp child-originated entries with the child id, preserving
938
+ // a grandchild's already-stamped id (absent = ticked root, see type doc).
939
+ for (const d of cr.deferred) {
940
+ result.deferred.push({ ...d, workflow: d.workflow ?? cr.workflow });
941
+ }
942
+ // reaped: sum across the tree (also reaps dead child leases that would
943
+ // otherwise sit until someone ticked the child directly).
944
+ result.reaped += cr.reaped;
945
+ // dueAt: min across the tree; stays absent when neither side has one.
946
+ if (cr.dueAt !== undefined) {
947
+ result.dueAt = result.dueAt === undefined ? cr.dueAt : Math.min(result.dueAt, cr.dueAt);
948
+ }
949
+ }
950
+ }
951
+ return result;
952
+ }
953
+ /**
954
+ * §23.6.8: is a `calls:` step's gate ready — i.e. every parent artifact wired
955
+ * into `callsInputs` is green? Shared by `maintainCalls` STEP 1 and
956
+ * `callsDescendTargets` so the descend condition can never drift from the
957
+ * spawn/re-provide condition. Empty gate (`callsInputs: {}`) is always ready.
958
+ */
959
+ callsGateReady(parentArts, step) {
960
+ const gateStems = Object.values(step.callsInputs ?? {});
961
+ return gateStems.length === 0 || gateStems.every((s) => isGreen(parentArts.get(s)));
473
962
  }
474
- /** Per-step cadence + daily budget + parallel cap over the eligible firings. */
475
- applySchedule(workflow, def, firings, now) {
963
+ /**
964
+ * §23.6.8: the live `calls:` children a deep tick should descend into, one
965
+ * per calls: step whose (1) gate is green, (2) child instance exists, and
966
+ * (3) the parent calls artifact is specifically `owed`. Read AFTER
967
+ * `maintainCalls` has run this frame, so a just-spawned child is visible and
968
+ * a just-machine-greened debt is correctly skipped. Consequences that fall
969
+ * out for free: gate re-armed after spawn → not ready → no descend
970
+ * (consistent with maintainCalls bailing at STEP 1, never driving work on
971
+ * disputed inputs); debt already paid → skip.
972
+ *
973
+ * B3: condition (3) descends ONLY on `owed`, never on any non-green state.
974
+ * `owed` is the sole live producer debt: it covers the fresh spawn, the F4
975
+ * propagated-reject reopen (parent reopened to owed pinned at the rejected
976
+ * child version), and `rearmCallsGreen`'s reopen — all of which legitimately
977
+ * want child work driven. `green` is paid; `rejected` (F2 schema / REL-4 depth
978
+ * refusal) needs a human `retry` or a moved gate handled by `maintainCalls`,
979
+ * never child work; `skipped` is a human-declared dead branch; `retracted` is
980
+ * terminal; `submitted` is not a producer debt (a calls artifact is machine
981
+ * -greened and should never be `submitted`) — none of these represent live
982
+ * child work, so descending into them issued orders for dead/refused branches.
983
+ */
984
+ callsDescendTargets(parentWf, def) {
985
+ const arts = this.artMap(parentWf);
986
+ const out = [];
987
+ for (const step of def.steps) {
988
+ if (!step.calls)
989
+ continue;
990
+ const stem = step.produces[0].stem;
991
+ if (!this.callsGateReady(arts, step))
992
+ continue; // 1. gate green
993
+ const child = this.store.findChildByParent(parentWf, stem);
994
+ if (!child)
995
+ continue; // 2. child exists
996
+ if (arts.get(stem)?.acceptance !== 'owed')
997
+ continue; // 3. descend only on an owed debt
998
+ out.push({ step, child });
999
+ }
1000
+ return out;
1001
+ }
1002
+ /**
1003
+ * Per-step cadence + daily budget + parallel cap over the eligible firings.
1004
+ * A2: `labels` is the tick caller's optional claim filter — when non-empty, a
1005
+ * step whose own `labels` are also non-empty is only schedulable when the two
1006
+ * intersect; a disjoint step's firings are deferred as `'label-mismatch'`.
1007
+ * Filtering here (before cadence/budget) means a mismatched firing never
1008
+ * consumes the caller's slots and never perturbs cadence math.
1009
+ */
1010
+ applySchedule(workflow, def, firings, now, labels) {
476
1011
  const midnight = localMidnightMs(now);
477
1012
  const selected = [];
478
1013
  const deferred = [];
@@ -486,6 +1021,15 @@ export class Engine {
486
1021
  const stepFirings = firings.filter((f) => f.step === step.name);
487
1022
  if (stepFirings.length === 0)
488
1023
  continue;
1024
+ // A2: caller label filter vs. step labels. Both non-empty and disjoint →
1025
+ // this caller must not claim the step; defer every firing and skip it
1026
+ // before it touches cadence/budget/slot math.
1027
+ if (labels.length > 0 && step.labels && step.labels.length > 0 &&
1028
+ !step.labels.some((l) => labels.includes(l))) {
1029
+ for (const f of stepFirings)
1030
+ defer(f, 'label-mismatch');
1031
+ continue;
1032
+ }
489
1033
  const latest = this.store.latestRun(workflow, step.name);
490
1034
  if (latest && now - latest.createdAt < step.cadenceSecs * 1000) {
491
1035
  for (const f of stepFirings)
@@ -510,15 +1054,53 @@ export class Engine {
510
1054
  return step?.reapTtlMs ?? this.reapTtlMs;
511
1055
  }
512
1056
  /**
513
- * Unified liveness predicate: returns true if the task's claim is still fresh.
514
- * Uses max(claimedAt, heartbeatAt ?? claimedAt) as the freshness anchor so a
515
- * heartbeating run is never falsely reaped even after the global TTL elapses.
1057
+ * A3 (REL-8): return the effective max total lease lifetime for a step, or
1058
+ * `undefined` when no cap is configured. Per-step `maxLease` overrides the
1059
+ * engine option; when both are unset there is no cap (heartbeats extend the
1060
+ * lease indefinitely). Uses `??` (not `||`) so an explicit `0` stays a cap.
516
1061
  */
517
- isClaimFresh(task, now, ttl) {
1062
+ effectiveMaxLease(step) {
1063
+ return step?.maxLeaseMs ?? this.maxLeaseMs;
1064
+ }
1065
+ /**
1066
+ * Classify a claimed task's liveness against the two independent bounds, so a
1067
+ * reap can report WHY a lease was cleared:
1068
+ * - `heartbeat-lost` — the anchor rule lapsed: `now - max(claimedAt,
1069
+ * heartbeatAt) > ttl`. The job went silent (or never beat).
1070
+ * - `max-lease-exceeded` — the anchor rule still holds (a live, beating job)
1071
+ * but a CONFIGURED `maxLease` cap has been exceeded: `now - claimedAt >
1072
+ * maxLease`. Only reachable when `maxLease !== undefined`.
1073
+ * - `fresh` — neither bound violated.
1074
+ *
1075
+ * Precedence: `heartbeat-lost` wins when both bounds lapse — if the job was
1076
+ * not alive under the anchor rule, reporting `max-lease-exceeded` would wrongly
1077
+ * suggest the cap killed a healthy job. The cap reason is reported only for a
1078
+ * still-beating lease. The clamp is measured off the ORIGINAL `claimedAt` of
1079
+ * the current claim; after a reap + re-claim it re-anchors to the new claim.
1080
+ */
1081
+ staleness(task, now, ttl, maxLease) {
518
1082
  const anchor = task.heartbeatAt !== undefined && task.heartbeatAt > (task.claimedAt ?? 0)
519
1083
  ? task.heartbeatAt
520
1084
  : (task.claimedAt ?? 0);
521
- return now - anchor <= ttl;
1085
+ if (now - anchor > ttl)
1086
+ return 'heartbeat-lost';
1087
+ // A3 clamp: total lifetime since the original claim may not exceed a
1088
+ // CONFIGURED maxLease. Unset (undefined) = no cap. `0` is a real (if silly)
1089
+ // cap, so test `!== undefined`, not truthiness.
1090
+ if (maxLease !== undefined && task.claimedAt !== undefined && now - task.claimedAt > maxLease) {
1091
+ return 'max-lease-exceeded';
1092
+ }
1093
+ return 'fresh';
1094
+ }
1095
+ /**
1096
+ * Unified liveness predicate: returns true if the task's claim is still fresh.
1097
+ * Thin wrapper over {@link staleness} — see it for the anchor rule and the
1098
+ * opt-in max-lease clamp. A heartbeating run is never falsely reaped after the
1099
+ * global TTL (anchor rule), and only a configured `maxLease` can reap a
1100
+ * still-beating lease.
1101
+ */
1102
+ isClaimFresh(task, now, ttl, maxLease) {
1103
+ return this.staleness(task, now, ttl, maxLease) === 'fresh';
522
1104
  }
523
1105
  /** Claim a firing's lease via CAS, snapshot the fingerprint, open a run. */
524
1106
  claim(workflow, def, f, arts, now) {
@@ -527,16 +1109,26 @@ export class Engine {
527
1109
  const run = existing.run ? this.store.getRun(existing.run) : undefined;
528
1110
  const stepDef = def.steps.find((l) => l.name === f.step);
529
1111
  const ttl = this.effectiveTtl(stepDef);
1112
+ const maxLease = this.effectiveMaxLease(stepDef);
530
1113
  const fresh = !!run &&
531
1114
  run.outcome === undefined &&
532
- (existing.claimedAt === undefined || this.isClaimFresh(existing, now, ttl));
1115
+ (existing.claimedAt === undefined || this.isClaimFresh(existing, now, ttl, maxLease));
533
1116
  if (fresh)
534
1117
  return 'in-flight'; // genuinely in flight — don't double-claim
535
1118
  }
536
1119
  const runId = randId('run');
537
1120
  const fp = computeFingerprint(arts, f.inputs);
1121
+ // Build the order BEFORE inserting the run so the flattened packet lands in
1122
+ // the SAME INSERT that creates the run row (§8 / Gap 1). buildOrder is
1123
+ // store-pure — it reads `def`, the in-memory `arts` map, and the firing, and
1124
+ // writes nothing — so reordering it ahead of insertRun changes no semantics.
1125
+ // Artifacts are overwritten in place (UNIQUE(workflow,path), putArtifact ON
1126
+ // CONFLICT DO UPDATE, no history table), so the issued order is unrecoverable
1127
+ // later unless captured here; this persisted packet is the replay/eval/paper
1128
+ // trail record (buildOrder is deterministic modulo run id).
1129
+ const order = this.buildOrder(def, workflow, runId, f, arts);
538
1130
  // Stamp the run with the tick's clock so cadence/budget compare on one clock.
539
- this.store.insertRun(runId, { workflow, step: f.step, key: f.key, fingerprint: fp, ...(f.cause ? { cause: f.cause } : {}) }, now);
1131
+ this.store.insertRun(runId, { workflow, step: f.step, key: f.key, fingerprint: fp, order, ...(f.cause ? { cause: f.cause } : {}) }, now);
540
1132
  this.store.putTask({
541
1133
  workflow,
542
1134
  step: f.step,
@@ -546,7 +1138,7 @@ export class Engine {
546
1138
  claimedAt: now,
547
1139
  attempts: existing?.attempts ?? 0,
548
1140
  });
549
- return this.buildOrder(def, workflow, runId, f, arts);
1141
+ return order;
550
1142
  }
551
1143
  buildOrder(def, workflow, runId, f, arts) {
552
1144
  const step = this.step(def, f.step);
@@ -673,7 +1265,7 @@ export class Engine {
673
1265
  const producer = def.steps.find((l) => l.name === art.producer);
674
1266
  if (opts.terminal || producer?.terminal)
675
1267
  next.terminal = true;
676
- this.store.putArtifact(next);
1268
+ this.store.putArtifact(next, { action: 'green', actor: 'human', reason: 'human green' });
677
1269
  this.settle(workflow, def);
678
1270
  return { path, outcome: 'green' };
679
1271
  });
@@ -714,11 +1306,11 @@ export class Engine {
714
1306
  const next = { ...art, acceptance: 'green', approvals };
715
1307
  if (producer?.terminal)
716
1308
  next.terminal = true;
717
- this.store.putArtifact(next);
1309
+ this.store.putArtifact(next, { action: 'judge-approved', actor: jName, reason: 'all judges approved' });
718
1310
  this.settle(workflow, def);
719
1311
  return { path: judgedStem, outcome: 'green' };
720
1312
  }
721
- this.store.putArtifact({ ...art, approvals });
1313
+ this.store.putArtifact({ ...art, approvals }, { action: 'judge-approved', actor: jName, reason: 'judge approved' });
722
1314
  this.settle(workflow, def);
723
1315
  return { path: judgedStem, outcome: 'approved' };
724
1316
  }
@@ -789,7 +1381,11 @@ export class Engine {
789
1381
  const producer = def.steps.find((l) => l.name === art.producer);
790
1382
  if (!hasJudges && (opts.terminal || producer?.terminal))
791
1383
  next.terminal = true;
792
- this.store.putArtifact(next);
1384
+ this.store.putArtifact(next, {
1385
+ action: hasJudges ? 'submitted' : 'produced',
1386
+ actor: r.step,
1387
+ reason: hasJudges ? 'submitted for judgment' : 'producer green',
1388
+ });
793
1389
  this.settle(workflow, def);
794
1390
  return { path, outcome: hasJudges ? 'submitted' : 'green' };
795
1391
  });
@@ -886,7 +1482,7 @@ export class Engine {
886
1482
  reasons: [],
887
1483
  judgmentRejects: 0,
888
1484
  schemaRejects: 0,
889
- });
1485
+ }, { action: 'produced', actor: r.step, reason: 'collection item emitted' });
890
1486
  created.push(p);
891
1487
  }
892
1488
  this.settle(workflow, def);
@@ -927,7 +1523,7 @@ export class Engine {
927
1523
  version: sealArt.version + 1,
928
1524
  value,
929
1525
  fingerprint: computeFingerprint(arts, req),
930
- });
1526
+ }, { action: 'sealed', actor: r.step, reason: 'collection sealed' });
931
1527
  this.settle(workflow, def);
932
1528
  return { path: sealP, outcome: 'green' };
933
1529
  });
@@ -1248,7 +1844,14 @@ export class Engine {
1248
1844
  /**
1249
1845
  * Touch the liveness timestamp on an open run's task. A run that periodically
1250
1846
  * calls heartbeat() will never be falsely reaped as long as beats arrive within
1251
- * the effective TTL. Throws (via openRun) if the run no longer holds its lease.
1847
+ * the effective TTL — EXCEPT (A3) when a max-lease cap is CONFIGURED and total
1848
+ * lifetime since the original claim exceeds it: past `claimedAt + maxLease` the
1849
+ * read-side freshness predicate (`isClaimFresh`) reports the lease stale no
1850
+ * matter how recent the beat, so a wedged-but-beating run is reaped and
1851
+ * re-claimable. With no cap configured (the default) beats extend the lease
1852
+ * indefinitely. This write stays dumb — it only records `heartbeatAt`; the
1853
+ * clamp is judged on read. Throws (via openRun) if the run no longer holds its
1854
+ * lease.
1252
1855
  */
1253
1856
  heartbeat(workflow, run, now) {
1254
1857
  const ts = now ?? nowMs();
@@ -1277,10 +1880,30 @@ export class Engine {
1277
1880
  continue;
1278
1881
  const run = task.run ? this.store.getRun(task.run) : undefined;
1279
1882
  const stepDef = resolvedDef.steps.find((l) => l.name === task.step);
1280
- const ttl = opts.ttlOverride ?? this.effectiveTtl(stepDef);
1281
- const stale = task.claimedAt !== undefined && !this.isClaimFresh(task, now, ttl);
1282
- const stranded = !run || run.outcome !== undefined || stale;
1283
- if (stranded) {
1883
+ const realTtl = this.effectiveTtl(stepDef);
1884
+ const maxLease = this.effectiveMaxLease(stepDef);
1885
+ // Classify why (if at all) this claim is stranded, in the same precedence
1886
+ // order the disjunction has always evaluated: run-missing, then run-closed,
1887
+ // then a liveness failure. The stranding DECISION honors ttlOverride (so
1888
+ // `reap --now` forces even a fresh claim stale), but the reported REASON is
1889
+ // computed under the REAL ttl — a lease that was fresh under real rules and
1890
+ // only cleared by the override reports `forced`, not a misleading liveness
1891
+ // reason (§ CLI reap --now).
1892
+ let reason;
1893
+ if (!run) {
1894
+ reason = 'run-missing';
1895
+ }
1896
+ else if (run.outcome !== undefined) {
1897
+ reason = 'run-closed';
1898
+ }
1899
+ else if (task.claimedAt !== undefined) {
1900
+ const effTtl = opts.ttlOverride ?? realTtl;
1901
+ if (this.staleness(task, now, effTtl, maxLease) !== 'fresh') {
1902
+ const realReason = this.staleness(task, now, realTtl, maxLease);
1903
+ reason = realReason === 'fresh' ? 'forced' : realReason;
1904
+ }
1905
+ }
1906
+ if (reason !== undefined) {
1284
1907
  this.store.putTask({
1285
1908
  workflow,
1286
1909
  step: task.step,
@@ -1290,7 +1913,7 @@ export class Engine {
1290
1913
  ...(task.alarmAt !== undefined ? { alarmAt: task.alarmAt } : {}),
1291
1914
  });
1292
1915
  n++;
1293
- const detail = { step: task.step, key: task.key };
1916
+ const detail = { step: task.step, key: task.key, reason };
1294
1917
  if (task.run !== undefined)
1295
1918
  detail.run = task.run;
1296
1919
  details.push(detail);
@@ -1336,6 +1959,22 @@ export class Engine {
1336
1959
  if (task && task.attempts > 0)
1337
1960
  d.attempts = task.attempts;
1338
1961
  }
1962
+ // §23.6.8: surface a `calls:` child on each unpaid calls debt so a stalled
1963
+ // descendant is visible from the root. Walk the debts again: a debt whose
1964
+ // path is a calls: step's produced stem, with a spawned child, gets a
1965
+ // recursive child summary (all instance-crossing logic stays here, in the
1966
+ // engine — the pure workflowStatus never touches another instance).
1967
+ for (const d of st.debts) {
1968
+ const callsStep = def.steps.find((s) => s.calls && s.produces[0].stem === d.path);
1969
+ if (!callsStep)
1970
+ continue;
1971
+ const child = this.store.findChildByParent(workflow, d.path);
1972
+ if (!child)
1973
+ continue;
1974
+ const summary = this.childStatusSummary(child.id, new Set());
1975
+ if (summary !== undefined)
1976
+ d.child = summary;
1977
+ }
1339
1978
  // §28: informational drift flag — compare the currently-loaded live def
1340
1979
  // for this instance's def NAME against the pinned snapshot's hash. Only
1341
1980
  // meaningful when a pin exists; only computable when the live def still
@@ -1469,9 +2108,10 @@ export class Engine {
1469
2108
  const run = task.run ? this.store.getRun(task.run) : undefined;
1470
2109
  const stepDef = def.steps.find((l) => l.name === task.step);
1471
2110
  const ttl = this.effectiveTtl(stepDef);
2111
+ const maxLease = this.effectiveMaxLease(stepDef);
1472
2112
  const fresh = !!run &&
1473
2113
  run.outcome === undefined &&
1474
- (task.claimedAt === undefined || this.isClaimFresh(task, now, ttl));
2114
+ (task.claimedAt === undefined || this.isClaimFresh(task, now, ttl, maxLease));
1475
2115
  if (fresh)
1476
2116
  return true;
1477
2117
  }
@@ -1499,7 +2139,9 @@ export class Engine {
1499
2139
  let arts = this.artMap(workflow);
1500
2140
  const owed = pendingOwed(def, arts);
1501
2141
  for (const a of owed)
1502
- this.store.putArtifact({ ...a, workflow });
2142
+ this.store.putArtifact({ ...a, workflow }, {
2143
+ action: 'owed', actor: 'engine', reason: 'artifact became owed',
2144
+ });
1503
2145
  if (owed.length)
1504
2146
  arts = this.artMap(workflow);
1505
2147
  // Only pass TimeFacts when we have a clock reading (tick path).
@@ -1722,6 +2364,48 @@ export class Engine {
1722
2364
  m.set(a.path, a);
1723
2365
  return m;
1724
2366
  }
2367
+ /**
2368
+ * §23.6.8: a compact summary of a `calls:` child for parent-status enrichment.
2369
+ * Uses the pure `workflowStatus` for the child's own debts (lighter than a
2370
+ * full recursive `Engine.status` — the `stalled` flag is already set by the
2371
+ * pure layer). `stalled` propagates recursively along the child's OWN unpaid
2372
+ * `calls:` path so a grandchild stall shows as `stalled: true` here. `debts`
2373
+ * is a COUNT — the `workflow` id is the human's inspection handle. `visited`
2374
+ * guards against any accidental instance cycle.
2375
+ *
2376
+ * Returns `undefined` when the child's def is unresolvable (an unpinned row
2377
+ * whose def was deleted/renamed) — practically unreachable since `calls:`
2378
+ * spawns pin (§28), but a summary is enrichment, and enrichment must not
2379
+ * make `status(parent)` throw (same stance as the §28 drift flag).
2380
+ */
2381
+ childStatusSummary(childWf, visited) {
2382
+ visited.add(childWf);
2383
+ let childDef;
2384
+ try {
2385
+ childDef = this.defFor(childWf);
2386
+ }
2387
+ catch {
2388
+ return undefined;
2389
+ }
2390
+ const childArts = this.artMap(childWf);
2391
+ const cs = workflowStatus(childDef, childArts);
2392
+ let stalled = cs.debts.some((d) => d.stalled);
2393
+ if (!stalled) {
2394
+ for (const d of cs.debts) {
2395
+ const callsStep = childDef.steps.find((s) => s.calls && s.produces[0].stem === d.path);
2396
+ if (!callsStep)
2397
+ continue;
2398
+ const grandchild = this.store.findChildByParent(childWf, d.path);
2399
+ if (!grandchild || visited.has(grandchild.id))
2400
+ continue;
2401
+ if (this.childStatusSummary(grandchild.id, visited)?.stalled) {
2402
+ stalled = true;
2403
+ break;
2404
+ }
2405
+ }
2406
+ }
2407
+ return { workflow: childWf, def: childDef.name, done: cs.done, stalled, debts: cs.debts.length };
2408
+ }
1725
2409
  defFor(workflow) {
1726
2410
  const wf = this.store.getWorkflow(workflow);
1727
2411
  if (!wf)