owenloop 0.2.0 → 0.3.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.
package/dist/engine.js CHANGED
@@ -15,10 +15,50 @@ 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;
27
+ /**
28
+ * F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
29
+ * by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
30
+ * `Error` so callers that need to distinguish "this value doesn't fit the
31
+ * schema" from a genuine bug (e.g. `maintainCalls`'s STEP 3/STEP 5, which must
32
+ * turn a CHILD's schema refusal into a debt on the parent rather than crash
33
+ * the parent's tick) can catch narrowly instead of blanket-catching.
34
+ */
35
+ export class SchemaRefusalError extends Error {
36
+ inputName;
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;
49
+ constructor(inputName, issues) {
50
+ super(`input '${inputName}' failed schema: ${summarizeIssues(issues)}`);
51
+ this.name = 'SchemaRefusalError';
52
+ this.inputName = inputName;
53
+ this.issues = issues;
54
+ }
55
+ }
18
56
  export class Engine {
19
57
  store;
20
58
  resolveDef;
21
59
  reapTtlMs;
60
+ maxLeaseMs;
61
+ maxCallDepth;
22
62
  listeners = new Set();
23
63
  onListenerError;
24
64
  /** M2B: recursion guard — set of parentWf ids currently inside maintainCalls. */
@@ -27,6 +67,8 @@ export class Engine {
27
67
  this.store = store;
28
68
  this.resolveDef = resolveDef;
29
69
  this.reapTtlMs = opts.reapTtlMs ?? DEFAULT_REAP_TTL_MS;
70
+ this.maxLeaseMs = opts.maxLeaseMs;
71
+ this.maxCallDepth = opts.maxCallDepth ?? DEFAULT_MAX_CALL_DEPTH;
30
72
  if (opts.onEvent)
31
73
  this.listeners.add(opts.onEvent);
32
74
  this.onListenerError = opts.onListenerError;
@@ -49,46 +91,202 @@ export class Engine {
49
91
  createInstance(defName, opts = {}) {
50
92
  const def = this.resolveDef(defName);
51
93
  const id = randId('wf');
52
- this.store.tx(() => {
53
- // §28: pin this instance to the def it was created against — a snapshot
54
- // of the fully-expanded compiled def plus its content hash. Every new
55
- // instance is stamped; "no snapshot" is strictly a legacy-row
56
- // compatibility case (see defFor), never a choice made here.
57
- const wfData = { def: defName, defSnapshot: def, defHash: hashDef(def) };
58
- if (opts.title !== undefined)
59
- wfData.title = opts.title;
60
- if (opts.params !== undefined)
61
- wfData.params = opts.params;
62
- this.store.insertWorkflow(id, wfData, opts.producedBy);
63
- for (const input of def.inputs) {
64
- const provided = opts.provide?.[input.name];
65
- if (provided !== undefined && input.schema !== undefined) {
66
- const check = validateValue(input.schema, provided);
67
- if (!check.valid) {
68
- throw new Error(`input '${input.name}' failed schema: ${summarizeIssues(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;
69
219
  }
70
220
  }
71
- const seedGreen = !input.seedOwed || provided !== undefined;
72
- const a = {
73
- workflow: id,
74
- path: input.name,
75
- producer: input.producer,
76
- acceptance: seedGreen ? 'green' : 'owed',
77
- version: seedGreen ? 1 : 0,
78
- reasons: [],
79
- judgmentRejects: 0,
80
- schemaRejects: 0,
81
- };
82
- if (provided !== undefined)
83
- a.value = provided;
84
- 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);
85
263
  }
86
- this.settle(id, def);
87
- 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 };
88
270
  });
89
- this.fire({ type: 'instance', workflow: id, def: defName });
90
- this.fireSettled(id);
91
- 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
+ }
92
290
  }
93
291
  /** A human/external producer supplies (greens) an owed input. */
94
292
  provideInput(workflow, name, value) {
@@ -104,7 +302,7 @@ export class Engine {
104
302
  if (inputDef?.schema !== undefined) {
105
303
  const check = validateValue(inputDef.schema, value);
106
304
  if (!check.valid) {
107
- throw new Error(`input '${name}' failed schema: ${summarizeIssues(check.issues)}`);
305
+ throw new SchemaRefusalError(name, check.issues);
108
306
  }
109
307
  }
110
308
  this.store.putArtifact({
@@ -153,6 +351,141 @@ export class Engine {
153
351
  : { workflow, defHash: newHash };
154
352
  }
155
353
  // ---- Mode 2 calls: child-instance management --------------------------------
354
+ /**
355
+ * F4: the synthetic fingerprint key a `calls:` artifact uses to pin its
356
+ * fingerprint to the child outcome's version. A calls: step declares
357
+ * `consumes: []` (§ M2B), so its produce's fingerprint would otherwise never
358
+ * see the child outcome (which lives in another instance entirely) — this
359
+ * key is how that pin rides inside the same `Fingerprint` map alongside the
360
+ * gate stems, without colliding with any real parent artifact path (gate
361
+ * stems are bare names; this key is namespaced and reserved).
362
+ */
363
+ static CHILD_OUTCOME_PIN_KEY = '__child_outcome_version__';
364
+ /**
365
+ * F4: the single place that computes "what child-outcome version is this
366
+ * calls: artifact currently resting on" — used both when machine-greening
367
+ * (STEP 6) and when stamping the pin at verdict time (reject propagation,
368
+ * human skip). Returns undefined if no child has ever been spawned (nothing
369
+ * to pin to).
370
+ */
371
+ childOutcomePin(parentWf, callsPath) {
372
+ const child = this.store.findChildByParent(parentWf, callsPath);
373
+ if (!child)
374
+ return undefined;
375
+ const childDef = this.defFor(child.id);
376
+ const childOutcomeStem = childDef.outputs[0];
377
+ const childArts = this.artMap(child.id);
378
+ const childOutcomeArt = childArts.get(childOutcomeStem);
379
+ return childOutcomeArt?.version ?? -1;
380
+ }
381
+ /**
382
+ * F2: record a child input-schema refusal (from STEP 3 spawn or STEP 5
383
+ * re-provide) as a debt on the PARENT calls artifact — same shape as
384
+ * green()'s schema-reject branch (acceptance: 'rejected', schemaRejects+1,
385
+ * a 'validation' reasons entry naming the child input and the schema
386
+ * issues) — so the tick can proceed instead of throwing, and the parent
387
+ * calls artifact surfaces as a stallable debt (maxSchemaFailures/retry).
388
+ * Stamps the current gate fingerprint on the rejected artifact so the
389
+ * STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
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`).
406
+ */
407
+ recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, seenGateFp, now) {
408
+ const text = `child input '${err.inputName}' failed schema: ${summarizeIssues(err.issues)}`;
409
+ return this.store.tx(() => {
410
+ const art = this.store.getArtifact(parentWf, callsStem);
411
+ if (!art)
412
+ return false; // not yet materialized by pendingOwed — nothing to stamp
413
+ const gateArts = this.artMap(parentWf);
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;
419
+ this.store.putArtifact({
420
+ ...art,
421
+ acceptance: 'rejected',
422
+ schemaRejects: art.schemaRejects + 1,
423
+ fingerprint: fp,
424
+ reasons: [...art.reasons, reason('schema-reject', 'validation', 'engine', text, art.version)],
425
+ });
426
+ this.settle(parentWf, def, now);
427
+ return true;
428
+ });
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' });
487
+ this.fireSettled(parentWf);
488
+ }
156
489
  /**
157
490
  * M2B: Maintain all `calls:` steps for a parent workflow.
158
491
  * Called at the top of tick (outside any tx) and as cascade-up prompt.
@@ -173,27 +506,88 @@ export class Engine {
173
506
  const callsPath = callsStem;
174
507
  const gateStems = Object.values(step.callsInputs ?? {});
175
508
  const parentArts = this.artMap(parentWf);
176
- const gateReady = gateStems.length === 0 || gateStems.every((s) => isGreen(parentArts.get(s)));
177
- if (!gateReady)
509
+ if (!this.callsGateReady(parentArts, step))
178
510
  continue;
179
511
  // STEP 2 — Look up any existing child via reverse index.
180
512
  let existingChild = this.store.findChildByParent(parentWf, callsPath);
181
- // STEP 3 — SPAWN or RE-ATTACH.
182
- if (!existingChild) {
183
- // SPAWN: gate is ready and no child exists yet.
184
- const seedProvide = {};
185
- for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
186
- const parentArt = parentArts.get(parentArtifactName);
187
- if (parentArt?.value !== undefined)
188
- seedProvide[childInputName] = parentArt.value;
513
+ // F2: if the parent calls artifact is already `rejected` on a schema
514
+ // refusal (see STEP 3/5 below) and the gate stems haven't moved since
515
+ // that refusal was recorded, don't re-attempt — the same value would
516
+ // just refuse again. The gate fingerprint on the rejected artifact is
517
+ // the guard; a moved gate (fingerprint mismatch) means the parent
518
+ // value may have been fixed, so fall through and retry.
519
+ const parentCallsArtPre = this.store.getArtifact(parentWf, callsStem);
520
+ if (!existingChild && parentCallsArtPre?.acceptance === 'rejected') {
521
+ const gateArtsPre = this.artMap(parentWf);
522
+ const currentGateFp = computeFingerprint(gateArtsPre, gateStems);
523
+ if (deepEqual(currentGateFp, parentCallsArtPre.fingerprint ?? {}))
524
+ continue;
525
+ }
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);
565
+ }
566
+ continue;
189
567
  }
190
- const childId = this.createInstance(step.calls, {
191
- producedBy: { parentWf, parentPath: callsPath },
192
- provide: seedProvide,
193
- });
194
- 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);
195
580
  }
196
- // 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);
197
591
  if (!existingChild)
198
592
  continue; // defensive: createInstance returned but getWorkflow failed
199
593
  // STEP 4 — Read child's declared outcome artifact.
@@ -203,41 +597,50 @@ export class Engine {
203
597
  const childOutcomeStem = childDef.outputs[0]; // validated by Phase-2 check
204
598
  let childArts = this.artMap(existingChild.id);
205
599
  let childOutcomeArt = childArts.get(childOutcomeStem);
206
- // STEP 5 — RE-PROVIDE if parent gate source moved (M2B-REPROVIDE).
207
- for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
208
- const parentArtNow = parentArts.get(parentArtifactName);
209
- const childInputArt = childArts.get(childInputName);
210
- if (parentArtNow?.value !== undefined && !deepEqual(parentArtNow.value, childInputArt?.value)) {
211
- this.provideInput(existingChild.id, childInputName, parentArtNow.value);
212
- }
213
- }
214
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
+ //
215
616
  // Re-read after potential re-provide.
216
617
  childArts = this.artMap(existingChild.id);
217
618
  childOutcomeArt = childArts.get(childOutcomeStem);
218
619
  const parentCallsArt = this.store.getArtifact(parentWf, callsStem);
620
+ // F2: don't machine-green over a schema-rejected debt — it needs a
621
+ // human `retry` (or a moved gate, handled by the guard above) before
622
+ // this step revisits it.
623
+ if (parentCallsArt?.acceptance === 'rejected')
624
+ continue;
219
625
  if (isGreen(childOutcomeArt) && childOutcomeArt?.value !== undefined) {
220
626
  const alreadyGreen = isGreen(parentCallsArt);
221
627
  const sameValue = alreadyGreen && deepEqual(childOutcomeArt.value, parentCallsArt?.value);
222
- if (!alreadyGreen || !sameValue) {
223
- if (!parentCallsArt)
224
- continue; // not yet materialized by pendingOwed — skip
225
- const gateArts = this.artMap(parentWf);
226
- const fp = computeFingerprint(gateArts, gateStems);
227
- const next = {
228
- ...parentCallsArt,
229
- acceptance: 'green',
230
- version: parentCallsArt.version + 1,
231
- value: childOutcomeArt.value,
232
- fingerprint: fp,
233
- };
234
- // Do NOT set terminal: calls: artifact must be re-armable if gate inputs move.
235
- this.store.tx(() => {
236
- this.store.putArtifact({ ...next, workflow: parentWf });
237
- this.settle(parentWf, def, now);
238
- });
239
- this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'provide' });
240
- this.fireSettled(parentWf);
628
+ // F4: version-pinning. Only machine-green when the child outcome's
629
+ // version has moved past whatever version is currently pinned on
630
+ // the parent artifact — this is what lets a consumer's reject
631
+ // (propagated down, parent reopened to owed pinned to the rejected
632
+ // child version) or a human skip (pinned at skip time) stand until
633
+ // the child actually rebuilds past that pin, instead of being
634
+ // silently overridden on the very next tick. (Re-checked in-tx by
635
+ // the helper against the snapshot it commits under.)
636
+ const pinnedVersion = parentCallsArt?.fingerprint?.[Engine.CHILD_OUTCOME_PIN_KEY];
637
+ const pastPin = pinnedVersion === undefined || childOutcomeArt.version > pinnedVersion;
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
+ }
241
644
  }
242
645
  }
243
646
  else if (!isGreen(childOutcomeArt) && isGreen(parentCallsArt) && parentCallsArt) {
@@ -245,26 +648,10 @@ export class Engine {
245
648
  // but the parent calls: artifact is still green. Re-arm it to owed so downstream
246
649
  // re-runs when the child completes again. This handles gate re-arm (test f):
247
650
  // the cascade can't detect this because deliver step has consumes: [].
248
- this.store.tx(() => {
249
- const artNow = this.store.getArtifact(parentWf, callsStem);
250
- if (!artNow || !isGreen(artNow))
251
- return; // already re-armed or gone
252
- this.store.putArtifact({
253
- ...artNow,
254
- acceptance: 'owed',
255
- reasons: [...artNow.reasons, {
256
- at: nowMs(),
257
- action: 'reopen',
258
- kind: 'structural',
259
- by: 'engine',
260
- text: 'gate input moved: child re-running',
261
- fromVersion: artNow.version,
262
- }],
263
- });
264
- this.settle(parentWf, def, now);
265
- });
266
- this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'retry' });
267
- 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
+ }
268
655
  }
269
656
  }
270
657
  }
@@ -272,6 +659,120 @@ export class Engine {
272
659
  this._inMaintainCalls.delete(parentWf);
273
660
  }
274
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
+ }
275
776
  /**
276
777
  * M2B cascade-up prompt: if `workflow` has a producedBy link, trigger
277
778
  * maintainCalls on its parent so the parent reflects the child's progress promptly.
@@ -294,19 +795,105 @@ export class Engine {
294
795
  this.fireSettled(parentWf);
295
796
  }
296
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
+ */
297
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);
298
859
  const def = this.defFor(workflow);
299
- const now = opts.now ?? nowMs();
300
860
  // M2B: maintain calls: child instances before the normal tick/reap/claim cycle.
301
861
  this.maintainCalls(workflow, def, now);
302
- 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(() => {
303
866
  this.settle(workflow, def, now);
304
867
  const reaped = this.reap(workflow, now, def);
305
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
+ }
306
893
  // Compute time facts for idle eligibility (clock-read boundary).
307
894
  const timeFacts = this.computeTimeFacts(def, workflow, arts, now);
308
895
  const firings = eligibleFirings(def, arts, timeFacts);
309
- const { selected, deferred } = this.applySchedule(workflow, def, firings, now);
896
+ const { selected, deferred } = this.applySchedule(workflow, def, firings, now, labels);
310
897
  // Clear alarm_at for any idle firing that was selected (consume the alarm).
311
898
  for (const f of selected) {
312
899
  if (f.cause === 'idle') {
@@ -316,27 +903,111 @@ export class Engine {
316
903
  const orders = [];
317
904
  const allDeferred = [...deferred];
318
905
  for (const f of selected) {
319
- const result = this.claim(workflow, def, f, arts, now);
320
- if (result === 'in-flight') {
906
+ const claimed = this.claim(workflow, def, f, arts, now);
907
+ if (claimed === 'in-flight') {
321
908
  const d = { step: f.step, key: f.key, inputs: f.inputs, outputs: f.outputs, reason: 'in-flight' };
322
909
  if (f.index !== undefined)
323
910
  d.index = f.index;
324
911
  allDeferred.push(d);
325
912
  }
326
- else if (result) {
327
- orders.push(result);
913
+ else if (claimed) {
914
+ orders.push(claimed);
328
915
  }
329
916
  }
330
917
  // E-DUE: compute earliest pending time-trigger for the result.
331
918
  const dueAt = this.computeDueAt(def, workflow, now);
332
- const result = { workflow, orders, reaped, deferred: allDeferred };
919
+ const r = { workflow, orders, reaped, deferred: allDeferred };
333
920
  if (dueAt !== null)
334
- result.dueAt = dueAt;
335
- return result;
921
+ r.dueAt = dueAt;
922
+ return r;
336
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)));
962
+ }
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;
337
1001
  }
338
- /** Per-step cadence + daily budget + parallel cap over the eligible firings. */
339
- applySchedule(workflow, def, firings, now) {
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) {
340
1011
  const midnight = localMidnightMs(now);
341
1012
  const selected = [];
342
1013
  const deferred = [];
@@ -350,6 +1021,15 @@ export class Engine {
350
1021
  const stepFirings = firings.filter((f) => f.step === step.name);
351
1022
  if (stepFirings.length === 0)
352
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
+ }
353
1033
  const latest = this.store.latestRun(workflow, step.name);
354
1034
  if (latest && now - latest.createdAt < step.cadenceSecs * 1000) {
355
1035
  for (const f of stepFirings)
@@ -374,15 +1054,53 @@ export class Engine {
374
1054
  return step?.reapTtlMs ?? this.reapTtlMs;
375
1055
  }
376
1056
  /**
377
- * Unified liveness predicate: returns true if the task's claim is still fresh.
378
- * Uses max(claimedAt, heartbeatAt ?? claimedAt) as the freshness anchor so a
379
- * 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.
380
1061
  */
381
- 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) {
382
1082
  const anchor = task.heartbeatAt !== undefined && task.heartbeatAt > (task.claimedAt ?? 0)
383
1083
  ? task.heartbeatAt
384
1084
  : (task.claimedAt ?? 0);
385
- 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';
386
1104
  }
387
1105
  /** Claim a firing's lease via CAS, snapshot the fingerprint, open a run. */
388
1106
  claim(workflow, def, f, arts, now) {
@@ -391,16 +1109,26 @@ export class Engine {
391
1109
  const run = existing.run ? this.store.getRun(existing.run) : undefined;
392
1110
  const stepDef = def.steps.find((l) => l.name === f.step);
393
1111
  const ttl = this.effectiveTtl(stepDef);
1112
+ const maxLease = this.effectiveMaxLease(stepDef);
394
1113
  const fresh = !!run &&
395
1114
  run.outcome === undefined &&
396
- (existing.claimedAt === undefined || this.isClaimFresh(existing, now, ttl));
1115
+ (existing.claimedAt === undefined || this.isClaimFresh(existing, now, ttl, maxLease));
397
1116
  if (fresh)
398
1117
  return 'in-flight'; // genuinely in flight — don't double-claim
399
1118
  }
400
1119
  const runId = randId('run');
401
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);
402
1130
  // Stamp the run with the tick's clock so cadence/budget compare on one clock.
403
- 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);
404
1132
  this.store.putTask({
405
1133
  workflow,
406
1134
  step: f.step,
@@ -410,7 +1138,7 @@ export class Engine {
410
1138
  claimedAt: now,
411
1139
  attempts: existing?.attempts ?? 0,
412
1140
  });
413
- return this.buildOrder(def, workflow, runId, f, arts);
1141
+ return order;
414
1142
  }
415
1143
  buildOrder(def, workflow, runId, f, arts) {
416
1144
  const step = this.step(def, f.step);
@@ -459,6 +1187,12 @@ export class Engine {
459
1187
  order.workdir = step.workdir;
460
1188
  if (step.model !== undefined)
461
1189
  order.model = step.model;
1190
+ if (step.worker !== undefined)
1191
+ order.worker = step.worker;
1192
+ if (step.command !== undefined)
1193
+ order.command = step.command;
1194
+ if (step.spec !== undefined)
1195
+ order.spec = step.spec;
462
1196
  if (step.x !== undefined)
463
1197
  order.x = step.x;
464
1198
  if (f.cause !== undefined)
@@ -505,6 +1239,20 @@ export class Engine {
505
1239
  this.settle(workflow, def);
506
1240
  return { path, outcome: 'group-rejected', reason: groupCas.reason };
507
1241
  }
1242
+ // §18: a human bypass still lands a value downstream consumers assume
1243
+ // is schema-valid (and which can later crash e.g. maintainCalls child
1244
+ // seeding), so enforce the same produce schema the producer-commit path
1245
+ // enforces (below). Unlike that path, there is no lease/retry loop to
1246
+ // protect here — a schema-invalid human green is a hard refusal (thrown
1247
+ // Error), not a schemaRejects-bumping soft one: no version bump, artifact
1248
+ // left untouched. The judge bypass (§24.6) is untouched by this check.
1249
+ const humanSchema = this.produceSchema(def, art);
1250
+ if (humanSchema !== undefined) {
1251
+ const check = validateValue(humanSchema, value);
1252
+ if (!check.valid) {
1253
+ throw new Error(`human green for '${path}' failed schema: ${summarizeIssues(check.issues)}`);
1254
+ }
1255
+ }
508
1256
  const req = requiredInputs(def, arts, art);
509
1257
  const next = {
510
1258
  ...art,
@@ -517,7 +1265,7 @@ export class Engine {
517
1265
  const producer = def.steps.find((l) => l.name === art.producer);
518
1266
  if (opts.terminal || producer?.terminal)
519
1267
  next.terminal = true;
520
- this.store.putArtifact(next);
1268
+ this.store.putArtifact(next, { action: 'green', actor: 'human', reason: 'human green' });
521
1269
  this.settle(workflow, def);
522
1270
  return { path, outcome: 'green' };
523
1271
  });
@@ -558,11 +1306,11 @@ export class Engine {
558
1306
  const next = { ...art, acceptance: 'green', approvals };
559
1307
  if (producer?.terminal)
560
1308
  next.terminal = true;
561
- this.store.putArtifact(next);
1309
+ this.store.putArtifact(next, { action: 'judge-approved', actor: jName, reason: 'all judges approved' });
562
1310
  this.settle(workflow, def);
563
1311
  return { path: judgedStem, outcome: 'green' };
564
1312
  }
565
- this.store.putArtifact({ ...art, approvals });
1313
+ this.store.putArtifact({ ...art, approvals }, { action: 'judge-approved', actor: jName, reason: 'judge approved' });
566
1314
  this.settle(workflow, def);
567
1315
  return { path: judgedStem, outcome: 'approved' };
568
1316
  }
@@ -633,7 +1381,11 @@ export class Engine {
633
1381
  const producer = def.steps.find((l) => l.name === art.producer);
634
1382
  if (!hasJudges && (opts.terminal || producer?.terminal))
635
1383
  next.terminal = true;
636
- 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
+ });
637
1389
  this.settle(workflow, def);
638
1390
  return { path, outcome: hasJudges ? 'submitted' : 'green' };
639
1391
  });
@@ -672,6 +1424,20 @@ export class Engine {
672
1424
  this.settle(workflow, def);
673
1425
  return { outcome: 'born-rejected', created: [], reason: cas.reason };
674
1426
  }
1427
+ // §11.1: once the seal is green the collection is complete — the offer
1428
+ // side never offers collection work again, so a late `emit` on a still
1429
+ // -open lease is refused rather than silently growing a "complete" set.
1430
+ // Check first, don't mutate on refusal (mirrors green()'s group check):
1431
+ // no counters bumped, no artifacts touched, lease stays open so the run
1432
+ // can still close.
1433
+ const sealForGreenCheck = arts.get(sealPath(stem));
1434
+ if (sealForGreenCheck && isGreen(sealForGreenCheck)) {
1435
+ return {
1436
+ outcome: 'sealed-rejected',
1437
+ created: [],
1438
+ reason: `collection ${stem} is sealed: seal green = set complete (§11.1)`,
1439
+ };
1440
+ }
675
1441
  // §18: every emitted element must satisfy the collection's declared schema.
676
1442
  // The check is atomic — one bad item accretes nothing and bumps the seal's
677
1443
  // schema-stall counter — so a producer can't half-fill a collection with
@@ -716,7 +1482,7 @@ export class Engine {
716
1482
  reasons: [],
717
1483
  judgmentRejects: 0,
718
1484
  schemaRejects: 0,
719
- });
1485
+ }, { action: 'produced', actor: r.step, reason: 'collection item emitted' });
720
1486
  created.push(p);
721
1487
  }
722
1488
  this.settle(workflow, def);
@@ -757,7 +1523,7 @@ export class Engine {
757
1523
  version: sealArt.version + 1,
758
1524
  value,
759
1525
  fingerprint: computeFingerprint(arts, req),
760
- });
1526
+ }, { action: 'sealed', actor: r.step, reason: 'collection sealed' });
761
1527
  this.settle(workflow, def);
762
1528
  return { path: sealP, outcome: 'green' };
763
1529
  });
@@ -796,6 +1562,16 @@ export class Engine {
796
1562
  reject(workflow, path, by, text) {
797
1563
  const def = this.defFor(workflow);
798
1564
  this.assertAuthority(def, by, path, 'reject');
1565
+ // F4: a reject on an artifact produced by a `calls:` step is a verdict on
1566
+ // the CHILD's work, not the parent's own — forward it. Detection: the
1567
+ // producing step declares `calls:`. The child is resolved via the
1568
+ // parent→child reverse index (store.findChildByParent); if no child was
1569
+ // ever spawned there is nothing to judge, so refuse (consistent with the
1570
+ // verb-guard rule below that a verdict needs a built version).
1571
+ const producingStep = def.steps.find((s) => s.produces.some((p) => p.stem === path));
1572
+ if (producingStep?.calls) {
1573
+ return this.rejectCallsArtifact(workflow, def, producingStep, path, by, text);
1574
+ }
799
1575
  const judgeStep = def.steps.find((s) => s.name === by);
800
1576
  const judgedStem = judgeStep?.judges;
801
1577
  let releasedRun;
@@ -819,6 +1595,21 @@ export class Engine {
819
1595
  return { outcome: 'born-rejected', reason: cas.reason };
820
1596
  }
821
1597
  }
1598
+ // §6: a judgment verdict is about a *produced* version (design §6) — refuse
1599
+ // a reject on anything that isn't currently a build (`green`) or awaiting
1600
+ // verdict (`submitted`). Two concrete wedges this closes: rejecting a
1601
+ // never-built `owed` artifact would burn a judgmentRejects toward the §6
1602
+ // stall cap with zero build attempts (a silent freeze — the producer side
1603
+ // never re-offers past the cap); rejecting a terminal `retracted` collection
1604
+ // member would flip a dead member back to a live `rejected` debt, but no
1605
+ // firing shape can ever rebuild a bare collection element (§11.3: retracted
1606
+ // is terminal, out of the live set), so the instance wedges permanently.
1607
+ // The judge-CAS branch above already guarantees `submitted` for judge
1608
+ // verdicts that reach here (a stale one already returned born-rejected),
1609
+ // so this only bites the plain/human reject path in practice.
1610
+ if (art.acceptance !== 'green' && art.acceptance !== 'submitted') {
1611
+ throw new Error(`cannot reject '${path}' in state '${art.acceptance}': a verdict requires a built version (green|submitted)`);
1612
+ }
822
1613
  // §24 §3.1/§4.4: a judge reject (or a human reject on a `submitted`
823
1614
  // artifact) is a quality verdict, not a cascade invalidation — it wins
824
1615
  // immediately regardless of any other judge's already-recorded approval,
@@ -849,12 +1640,87 @@ export class Engine {
849
1640
  this.fireSettled(workflow);
850
1641
  return result;
851
1642
  }
1643
+ /**
1644
+ * F4: forward a reject on a `calls:`-produced artifact to the CHILD's
1645
+ * outcome artifact, then reopen the parent calls artifact to `owed` pinned
1646
+ * (via `childOutcomePin`) to the just-rejected child outcome version, so
1647
+ * STEP 6's mirror only fires again once the child has actually rebuilt past
1648
+ * this verdict (§ F4 settled design).
1649
+ *
1650
+ * The forward is engine-internal: authority was already checked against the
1651
+ * PARENT def by `assertAuthority` in `reject()` above, so the child's own
1652
+ * `assertAuthority` is not consulted — the author recorded on the child's
1653
+ * reasons entry is `parent:<by>` to make the indirection visible in its
1654
+ * audit thread.
1655
+ */
1656
+ rejectCallsArtifact(parentWf, def, producingStep, callsStem, by, text) {
1657
+ const child = this.store.findChildByParent(parentWf, callsStem);
1658
+ if (!child) {
1659
+ throw new Error(`cannot reject '${callsStem}': no child instance has been spawned yet (a verdict requires a built version)`);
1660
+ }
1661
+ const childDef = this.defFor(child.id);
1662
+ const childOutcomeStem = childDef.outputs[0];
1663
+ this.store.tx(() => {
1664
+ const parentArt = this.store.getArtifact(parentWf, callsStem);
1665
+ if (!parentArt)
1666
+ throw new Error(`cannot reject unknown artifact: ${callsStem}`);
1667
+ if (parentArt.acceptance !== 'green' && parentArt.acceptance !== 'submitted') {
1668
+ throw new Error(`cannot reject '${callsStem}' in state '${parentArt.acceptance}': a verdict requires a built version (green|submitted)`);
1669
+ }
1670
+ const childArt = this.store.getArtifact(child.id, childOutcomeStem);
1671
+ if (!childArt)
1672
+ throw new Error(`cannot reject '${callsStem}': child outcome artifact missing`);
1673
+ // Child outcome → rejected, judgmentRejects+1, author `parent:<by>`.
1674
+ this.store.putArtifact({
1675
+ ...childArt,
1676
+ acceptance: 'rejected',
1677
+ judgmentRejects: childArt.judgmentRejects + 1,
1678
+ approvals: undefined,
1679
+ reasons: [...childArt.reasons, reason('reject', 'judgment', `parent:${by}`, text, childArt.version)],
1680
+ });
1681
+ this.settle(child.id, childDef);
1682
+ // Parent calls artifact → reopened to owed (not left rejected), pinned
1683
+ // to the just-rejected child outcome version.
1684
+ this.store.putArtifact({
1685
+ ...parentArt,
1686
+ acceptance: 'owed',
1687
+ fingerprint: { ...(parentArt.fingerprint ?? {}), [Engine.CHILD_OUTCOME_PIN_KEY]: childArt.version },
1688
+ reasons: [
1689
+ ...parentArt.reasons,
1690
+ {
1691
+ at: nowMs(),
1692
+ action: 'reopen',
1693
+ kind: 'structural',
1694
+ by: 'engine',
1695
+ text: `reject forwarded to child outcome '${childOutcomeStem}': ${text}`,
1696
+ fromVersion: parentArt.version,
1697
+ },
1698
+ ],
1699
+ });
1700
+ this.settle(parentWf, def);
1701
+ });
1702
+ this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject' });
1703
+ this.fireSettled(parentWf);
1704
+ // The child's own firings (re-arming its producer with the feedback on
1705
+ // its owes thread) need tick(child) — not driven from here; see docs/design.md
1706
+ // M2/M2B "sweeping" note. Prompt maintainCalls now so the parent's own
1707
+ // state (owed/pin) is visible immediately, mirroring provideInput's cascade.
1708
+ this.maintainCalls(parentWf, def);
1709
+ return { outcome: 'rejected' };
1710
+ }
852
1711
  /** Retract a collection member (§11.3): drop it, terminally; abandon the index. */
853
1712
  retract(workflow, path, by, text) {
854
1713
  const def = this.defFor(workflow);
855
1714
  const el = parseElement(path);
856
1715
  if (!el || el.suffix !== '')
857
1716
  throw new Error(`retract is only valid on a collection member: ${path}`);
1717
+ // §4.1/§11.3: same authority rule as reject — only a consumer of the member's
1718
+ // stem (or human/engine) may drop it. Without this, any string actor name
1719
+ // (even one not in the def) could terminally retract a green member of a
1720
+ // sealed collection. assertAuthority resolves an element path to its stem
1721
+ // via parseElement internally, so `path` (not `el.stem`) is passed straight
1722
+ // through, same as reject().
1723
+ this.assertAuthority(def, by, path, 'retract');
858
1724
  this.store.tx(() => {
859
1725
  const art = this.store.getArtifact(workflow, path);
860
1726
  if (!art)
@@ -883,10 +1749,22 @@ export class Engine {
883
1749
  // Fingerprint the inputs this skip rests on, so the level-trigger only
884
1750
  // re-arms the branch when those inputs *move* (§16.1), not merely stay green.
885
1751
  const req = requiredInputs(def, arts, art);
1752
+ const fp = computeFingerprint(arts, req);
1753
+ // F4: a calls: step declares `consumes: []`, so `req` above never sees
1754
+ // its real input — the child outcome, which lives in another instance.
1755
+ // Capture the same version pin `childOutcomePin` uses elsewhere, so a
1756
+ // skip made on evidence from child version N survives arbitrary ticks
1757
+ // (order A) until the child actually rebuilds past N (order B).
1758
+ const producingStep = def.steps.find((s) => s.name === art.producer);
1759
+ if (producingStep?.calls) {
1760
+ const pin = this.childOutcomePin(workflow, path);
1761
+ if (pin !== undefined)
1762
+ fp[Engine.CHILD_OUTCOME_PIN_KEY] = pin;
1763
+ }
886
1764
  this.store.putArtifact({
887
1765
  ...art,
888
1766
  acceptance: 'skipped',
889
- fingerprint: computeFingerprint(arts, req),
1767
+ fingerprint: fp,
890
1768
  reasons: [...art.reasons, reason('skip', 'structural', by, text, art.version)],
891
1769
  });
892
1770
  this.settle(workflow, def);
@@ -903,10 +1781,21 @@ export class Engine {
903
1781
  */
904
1782
  retry(workflow, path, by = 'human', text = 'retry: stall cleared') {
905
1783
  const def = this.defFor(workflow);
1784
+ // §4.1: same authority rule as reject/retract — only a consumer of the
1785
+ // stem (or human/engine) may re-arm it.
1786
+ this.assertAuthority(def, by, path, 'retry');
906
1787
  this.store.tx(() => {
907
1788
  const art = this.store.getArtifact(workflow, path);
908
1789
  if (!art)
909
1790
  throw new Error(`cannot retry unknown artifact: ${path}`);
1791
+ // §11.3: retry re-arms to `owed`, but a bare collection element that has
1792
+ // been retracted has no producer firing that can ever rebuild it — retry
1793
+ // would resurrect a terminally-dropped member into a guaranteed wedge.
1794
+ // `retract` is final by design; every other state (rejected, stalled,
1795
+ // skipped, green) stays a legal retry target.
1796
+ if (art.acceptance === 'retracted') {
1797
+ throw new Error(`cannot retry '${path}': it was retracted, which is terminal (use a fresh collection element instead)`);
1798
+ }
910
1799
  this.store.putArtifact({
911
1800
  ...art,
912
1801
  acceptance: 'owed',
@@ -955,7 +1844,14 @@ export class Engine {
955
1844
  /**
956
1845
  * Touch the liveness timestamp on an open run's task. A run that periodically
957
1846
  * calls heartbeat() will never be falsely reaped as long as beats arrive within
958
- * 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.
959
1855
  */
960
1856
  heartbeat(workflow, run, now) {
961
1857
  const ts = now ?? nowMs();
@@ -984,10 +1880,30 @@ export class Engine {
984
1880
  continue;
985
1881
  const run = task.run ? this.store.getRun(task.run) : undefined;
986
1882
  const stepDef = resolvedDef.steps.find((l) => l.name === task.step);
987
- const ttl = opts.ttlOverride ?? this.effectiveTtl(stepDef);
988
- const stale = task.claimedAt !== undefined && !this.isClaimFresh(task, now, ttl);
989
- const stranded = !run || run.outcome !== undefined || stale;
990
- 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) {
991
1907
  this.store.putTask({
992
1908
  workflow,
993
1909
  step: task.step,
@@ -997,7 +1913,7 @@ export class Engine {
997
1913
  ...(task.alarmAt !== undefined ? { alarmAt: task.alarmAt } : {}),
998
1914
  });
999
1915
  n++;
1000
- const detail = { step: task.step, key: task.key };
1916
+ const detail = { step: task.step, key: task.key, reason };
1001
1917
  if (task.run !== undefined)
1002
1918
  detail.run = task.run;
1003
1919
  details.push(detail);
@@ -1043,6 +1959,22 @@ export class Engine {
1043
1959
  if (task && task.attempts > 0)
1044
1960
  d.attempts = task.attempts;
1045
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
+ }
1046
1978
  // §28: informational drift flag — compare the currently-loaded live def
1047
1979
  // for this instance's def NAME against the pinned snapshot's hash. Only
1048
1980
  // meaningful when a pin exists; only computable when the live def still
@@ -1176,9 +2108,10 @@ export class Engine {
1176
2108
  const run = task.run ? this.store.getRun(task.run) : undefined;
1177
2109
  const stepDef = def.steps.find((l) => l.name === task.step);
1178
2110
  const ttl = this.effectiveTtl(stepDef);
2111
+ const maxLease = this.effectiveMaxLease(stepDef);
1179
2112
  const fresh = !!run &&
1180
2113
  run.outcome === undefined &&
1181
- (task.claimedAt === undefined || this.isClaimFresh(task, now, ttl));
2114
+ (task.claimedAt === undefined || this.isClaimFresh(task, now, ttl, maxLease));
1182
2115
  if (fresh)
1183
2116
  return true;
1184
2117
  }
@@ -1206,7 +2139,9 @@ export class Engine {
1206
2139
  let arts = this.artMap(workflow);
1207
2140
  const owed = pendingOwed(def, arts);
1208
2141
  for (const a of owed)
1209
- this.store.putArtifact({ ...a, workflow });
2142
+ this.store.putArtifact({ ...a, workflow }, {
2143
+ action: 'owed', actor: 'engine', reason: 'artifact became owed',
2144
+ });
1210
2145
  if (owed.length)
1211
2146
  arts = this.artMap(workflow);
1212
2147
  // Only pass TimeFacts when we have a clock reading (tick path).
@@ -1296,9 +2231,15 @@ export class Engine {
1296
2231
  // re-arms when the upstream branch revives (mirrors a producer skip).
1297
2232
  // §26: an auto-skip of a losing group sibling tags rejectKind 'exclusive'
1298
2233
  // instead of the default 'structural' (op.rejectKind carries this).
2234
+ // §26.2: if the skipped sibling was `submitted` (awaiting judgment), it
2235
+ // may be carrying a partial approvals sign-off — clear it the same way
2236
+ // a cascade reject does (§24 §4.3), so a stale sign-off never leaks onto
2237
+ // a later resubmission if the winner is un-greened and the branch revives.
2238
+ const clearApprovals = art.acceptance === 'submitted' && art.approvals !== undefined;
1299
2239
  this.store.putArtifact({
1300
2240
  ...art,
1301
2241
  acceptance: 'skipped',
2242
+ ...(clearApprovals ? { approvals: undefined } : {}),
1302
2243
  fingerprint: computeFingerprint(arts, requiredInputs(def, arts, art)),
1303
2244
  reasons: [...art.reasons, reason('skip', op.rejectKind ?? 'structural', 'engine', op.reason, art.version)],
1304
2245
  });
@@ -1423,6 +2364,48 @@ export class Engine {
1423
2364
  m.set(a.path, a);
1424
2365
  return m;
1425
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
+ }
1426
2409
  defFor(workflow) {
1427
2410
  const wf = this.store.getWorkflow(workflow);
1428
2411
  if (!wf)