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.d.ts CHANGED
@@ -12,35 +12,31 @@
12
12
  import type { WorkflowStatus } from './model.ts';
13
13
  import type { SchemaIssue } from './schema.ts';
14
14
  import type { Store } from './store.ts';
15
- import type { Author, FiringTrigger, ReasonEntry, WorkflowDef } from './types.ts';
16
- /** A self-contained unit of work emitted by a tick. */
17
- export interface Order {
18
- run: string;
19
- workflow: string;
20
- step: string;
21
- key: string;
22
- index?: number;
23
- inputs: string[];
24
- outputs: string[];
25
- workdir?: string;
26
- model?: string;
27
- /** §27.3: the step's opaque `x:` extension map, carried through untouched
28
- * (same pass-through contract as `model`). The engine never reads it —
29
- * it exists for the external runner/tooling consuming this order. */
30
- x?: Record<string, unknown>;
31
- prompt: string;
32
- /** captured handles of the green inputs this run builds on */
33
- consumes: Record<string, unknown>;
34
- /** the owed outputs and their accumulated reason threads (the feedback channel) */
35
- owes: Array<{
36
- path: string;
37
- acceptance: string;
38
- judgmentRejects: number;
39
- schemaRejects: number;
40
- reasons: ReasonEntry[];
41
- }>;
42
- /** The trigger that woke this firing (§21). Absent = 'inputsGreen'. */
43
- cause?: FiringTrigger;
15
+ import type { Author, Fingerprint, Order, WorkflowDef } from './types.ts';
16
+ export type { Order } from './types.ts';
17
+ /**
18
+ * F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
19
+ * by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
20
+ * `Error` so callers that need to distinguish "this value doesn't fit the
21
+ * schema" from a genuine bug (e.g. `maintainCalls`'s STEP 3/STEP 5, which must
22
+ * turn a CHILD's schema refusal into a debt on the parent rather than crash
23
+ * the parent's tick) can catch narrowly instead of blanket-catching.
24
+ */
25
+ export declare class SchemaRefusalError extends Error {
26
+ readonly inputName: string;
27
+ readonly issues: SchemaIssue[];
28
+ /**
29
+ * B2: the gate fingerprint of the exact parent snapshot the failed validation
30
+ * saw, captured inside the validating transaction and attached before this
31
+ * error is rethrown out to `maintainCalls`. `recordCallsSchemaReject` compares
32
+ * it to the gate fingerprint at recording time so a refusal recorded after a
33
+ * concurrent VALID gate advance is discarded instead of stamped onto (and
34
+ * thereby stalling) the valid update. Mutable and optional: set by the thrower
35
+ * (`provisionCallsChild`) once the snapshot is known; absent means "no snapshot
36
+ * carried" and the recorder falls back to today's stamp-fresh behavior.
37
+ */
38
+ gateFingerprint?: Fingerprint;
39
+ constructor(inputName: string, issues: SchemaIssue[]);
44
40
  }
45
41
  /**
46
42
  * §tick-deferred: an eligible firing the tick did NOT promote to an order, tagged
@@ -49,8 +45,11 @@ export interface Order {
49
45
  * step's daily run allowance is exhausted (binding over parallel); `'parallel-cap'`
50
46
  * — the step's concurrency cap is the binding constraint. Always emitted by
51
47
  * `applySchedule` or `tick`; never alters which firings are selected or claimed.
48
+ * `'label-mismatch'` (A2) — the tick caller passed a label filter that does not
49
+ * intersect the step's declared labels, so a peer orchestrator serving other
50
+ * labels leaves it for the matching caller.
52
51
  */
53
- export type DeferredReason = 'in-flight' | 'cadence' | 'daily-budget' | 'parallel-cap';
52
+ export type DeferredReason = 'in-flight' | 'cadence' | 'daily-budget' | 'parallel-cap' | 'label-mismatch';
54
53
  export interface DeferredFiring {
55
54
  step: string;
56
55
  key: string;
@@ -58,7 +57,29 @@ export interface DeferredFiring {
58
57
  inputs: string[];
59
58
  outputs: string[];
60
59
  reason: DeferredReason;
60
+ /**
61
+ * §23.6.8 deep tick: which instance this deferred firing belongs to.
62
+ * Convention — **absent = the ticked ROOT instance; present = the named
63
+ * descendant.** A deep `tick(root)` folds each live `calls:` child's own
64
+ * `TickResult` up: a child-originated entry is stamped with the child's
65
+ * workflow id (a grandchild's already-stamped id is preserved), while the
66
+ * root frame's own deferrals stay unstamped. Lets a driver tell whose
67
+ * `in-flight`/`cadence`/… deferral it is reading without ambiguity.
68
+ */
69
+ workflow?: string;
61
70
  }
71
+ /**
72
+ * The result of a `tick`. §23.6.8: a deep `tick(root)` (the default) descends
73
+ * into every live `calls:` child and folds the whole subtree's work into this
74
+ * one result — `orders` are flattened (each `Order` carries its own
75
+ * `workflow`, so a driver dispatches/commits by `order.workflow`), `reaped` is
76
+ * summed across the tree, `dueAt` is the min across the tree, and `deferred`
77
+ * entries are stamped with their originating instance (absent = this root; see
78
+ * `DeferredFiring.workflow`). `workflow` below always stays the ROOT (ticked)
79
+ * id — child results are folded, never returned as the root. `tick(wf,
80
+ * { deep: false })` (CLI `--shallow`) restores the pre-deep behavior: only this
81
+ * instance's own orders/reaps/deferrals.
82
+ */
62
83
  export interface TickResult {
63
84
  workflow: string;
64
85
  orders: Order[];
@@ -96,7 +117,7 @@ export interface CommitResult {
96
117
  }
97
118
  /** The outcome of an `emit` (collection accretion) — possibly schema-refused. */
98
119
  export interface EmitResult {
99
- outcome: 'emitted' | 'born-rejected' | 'schema-rejected';
120
+ outcome: 'emitted' | 'born-rejected' | 'schema-rejected' | 'sealed-rejected';
100
121
  /** the element paths created (empty unless `emitted`) */
101
122
  created: string[];
102
123
  reason?: string;
@@ -151,16 +172,51 @@ export type EngineEvent = {
151
172
  };
152
173
  /** A synchronous observer of {@link EngineEvent}s. */
153
174
  export type EngineListener = (event: EngineEvent) => void;
175
+ /**
176
+ * Why the reaper cleared a stranded lease, surfaced per entry in
177
+ * {@link Engine.reapWithDetails} `details` (and printed by the CLI `reap`
178
+ * command). Distinguishes the liveness failures from the bookkeeping ones:
179
+ * - `heartbeat-lost` — no beat within the effective reap TTL (the anchor rule
180
+ * `max(claimedAt, heartbeatAt) + ttl` lapsed): the job went silent.
181
+ * - `max-lease-exceeded` — a *configured* max-lease cap expired the lease even
182
+ * though it was still beating (total lifetime since `claimedAt` passed the
183
+ * cap). Only possible when `maxLeaseMs`/per-step `maxLease` is set.
184
+ * - `run-missing` — the task was claimed but has no run row.
185
+ * - `run-closed` — the owning run already closed (its outcome is set).
186
+ * - `forced` — an admin `reap --now` (`ttlOverride: 0`) cleared a lease that
187
+ * was still fresh under the real TTL rules; reported instead of a misleading
188
+ * liveness reason so the output does not look like the job failed.
189
+ */
190
+ export type ReapReason = 'heartbeat-lost' | 'max-lease-exceeded' | 'run-missing' | 'run-closed' | 'forced';
191
+ /** One cleared-lease entry from {@link Engine.reapWithDetails}. */
192
+ export interface ReapDetail {
193
+ step: string;
194
+ key: string;
195
+ run?: string;
196
+ reason: ReapReason;
197
+ }
154
198
  export declare class Engine {
155
199
  readonly store: Store;
156
200
  private readonly resolveDef;
157
201
  private readonly reapTtlMs;
202
+ private readonly maxLeaseMs;
203
+ private readonly maxCallDepth;
158
204
  private readonly listeners;
159
205
  private readonly onListenerError?;
160
206
  /** M2B: recursion guard — set of parentWf ids currently inside maintainCalls. */
161
207
  private readonly _inMaintainCalls;
162
208
  constructor(store: Store, resolveDef: DefResolver, opts?: {
163
209
  reapTtlMs?: number;
210
+ /** A3 (REL-8): OPT-IN hard cap on total lease lifetime (claimedAt +
211
+ * maxLease), enforced regardless of heartbeats. Unset (the default) means
212
+ * NO cap — a correctly heartbeating job runs as long as it needs, and the
213
+ * anchor rule (reap TTL vs. last beat) is the only liveness bound. Set it
214
+ * only as a runaway backstop; a per-step `maxLeaseMs` overrides it. */
215
+ maxLeaseMs?: number;
216
+ /** REL-4: hard cap on `calls:` composition depth (root = 0). Falls back to
217
+ * DEFAULT_MAX_CALL_DEPTH (64). Defense in depth against a calls: cycle
218
+ * that bypassed load-time validation (e.g. a hand-wired custom resolver). */
219
+ maxCallDepth?: number;
164
220
  /** A listener registered up front, equivalent to a `subscribe` call. */
165
221
  onEvent?: EngineListener;
166
222
  /** Where a throwing listener's error goes (default: swallowed). */
@@ -176,6 +232,49 @@ export declare class Engine {
176
232
  subscribe(listener: EngineListener): () => void;
177
233
  /** Start a workflow instance: persist it, seed its declared inputs, settle. */
178
234
  createInstance(defName: string, opts?: CreateOpts): string;
235
+ /**
236
+ * The transactional body of instance creation: persist the workflow row, seed
237
+ * its declared inputs (validating any provided values), and settle. MUST run
238
+ * inside a `store.tx()` — callers own the tx and the post-commit event firing.
239
+ * Extracted from {@link createInstance} so the atomic child-provision path
240
+ * ({@link provisionCallsChild}) can find-or-create a child and sync its inputs
241
+ * under a single `BEGIN IMMEDIATE` without nesting transactions.
242
+ */
243
+ private createInstanceInTx;
244
+ /**
245
+ * C2: atomic fresh-snapshot child provision for a `calls:` step — the
246
+ * creation-side mirror of `publishCallsGreen`'s discipline. Find-or-create the
247
+ * child AND synchronize every mapped child input, all inside ONE
248
+ * `BEGIN IMMEDIATE`, from a parent snapshot RE-READ inside that same tx — never
249
+ * from the caller's (STEP-1) snapshot. Because the write and every read it
250
+ * depends on share one write lock, the committed seed/sync values are by
251
+ * construction current at commit: "never regress a child input" needs no
252
+ * version comparison — the fresh in-tx read IS the guard.
253
+ *
254
+ * This closes two reproduced cross-connection races the STEP-1 snapshot exposed:
255
+ * (a) SPAWN — a child seeded from a stale parent value while a concurrent tick
256
+ * advanced the gate; (b) RE-PROVISION — a stale parent value stamped backward
257
+ * over a newer child input (version bumps, value regresses). `maintainCalls`'
258
+ * pre-reads (gate readiness, `findChildByParent`, F2 fingerprint, depth) are now
259
+ * OPTIMISTIC — they decide only WHETHER to attempt; this helper re-verifies
260
+ * everything the write depends on in-tx.
261
+ *
262
+ * Returns `{ childId, created, provided }` — `created` true only when THIS call
263
+ * inserted the child, `provided` the list of child inputs it actually re-wrote
264
+ * (empty for a plain spawn, since a fresh seed already equals the fresh
265
+ * snapshot). Events (`instance`, `commit`/`provide`, `settled`) and the child
266
+ * cascade are the caller's responsibility, fired post-commit, matching the
267
+ * pre-C2 per-action semantics. Returns `null` on a silent abort: the gate was
268
+ * re-armed, or an F2 schema-reject debt landed, since the pre-read — "not yet"
269
+ * state, next tick redoes the pass (publishCallsGreen discipline; no debt, no
270
+ * events written).
271
+ *
272
+ * A `SchemaRefusalError` (a seed or re-provided parent value illegal per the
273
+ * child's input schema) propagates out with the whole tx rolled back — no
274
+ * orphan child row, no partial input sync — preserving the F2 contract; the
275
+ * caller records it as a debt on the parent calls artifact.
276
+ */
277
+ private provisionCallsChild;
179
278
  /** A human/external producer supplies (greens) an owed input. */
180
279
  provideInput(workflow: string, name: string, value: Record<string, unknown>): void;
181
280
  /**
@@ -192,6 +291,82 @@ export declare class Engine {
192
291
  defHash: string;
193
292
  previousHash?: string;
194
293
  };
294
+ /**
295
+ * F4: the synthetic fingerprint key a `calls:` artifact uses to pin its
296
+ * fingerprint to the child outcome's version. A calls: step declares
297
+ * `consumes: []` (§ M2B), so its produce's fingerprint would otherwise never
298
+ * see the child outcome (which lives in another instance entirely) — this
299
+ * key is how that pin rides inside the same `Fingerprint` map alongside the
300
+ * gate stems, without colliding with any real parent artifact path (gate
301
+ * stems are bare names; this key is namespaced and reserved).
302
+ */
303
+ private static readonly CHILD_OUTCOME_PIN_KEY;
304
+ /**
305
+ * F4: the single place that computes "what child-outcome version is this
306
+ * calls: artifact currently resting on" — used both when machine-greening
307
+ * (STEP 6) and when stamping the pin at verdict time (reject propagation,
308
+ * human skip). Returns undefined if no child has ever been spawned (nothing
309
+ * to pin to).
310
+ */
311
+ private childOutcomePin;
312
+ /**
313
+ * F2: record a child input-schema refusal (from STEP 3 spawn or STEP 5
314
+ * re-provide) as a debt on the PARENT calls artifact — same shape as
315
+ * green()'s schema-reject branch (acceptance: 'rejected', schemaRejects+1,
316
+ * a 'validation' reasons entry naming the child input and the schema
317
+ * issues) — so the tick can proceed instead of throwing, and the parent
318
+ * calls artifact surfaces as a stallable debt (maxSchemaFailures/retry).
319
+ * Stamps the current gate fingerprint on the rejected artifact so the
320
+ * STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
321
+ * worth retrying" on the next tick.
322
+ *
323
+ * B2 (snapshot-consistent recording): `seenGateFp` is the gate fingerprint of
324
+ * the exact snapshot the failed validation saw (carried on the
325
+ * `SchemaRefusalError`). Inside the recording tx we recompute the CURRENT gate
326
+ * fingerprint and compare:
327
+ * - equal → the gate has not moved since the failure: stamp the rejection.
328
+ * - not equal → a concurrent VALID gate advance landed between the validation
329
+ * and here: DISCARD the now-obsolete refusal (write nothing). Stamping it
330
+ * would freeze the valid update as `rejected` because the STEP-2 F2 guard
331
+ * would then read "gate unmoved, don't retry".
332
+ * - `seenGateFp` undefined (defensive; the sole call site always carries one)
333
+ * → legacy stamp-fresh behavior.
334
+ * Returns true only when it actually stamped, so the caller fires the
335
+ * schema-rejected / settled events only on a real write (a discarded refusal
336
+ * is silent — abort discipline, mirroring `publishCallsGreen`).
337
+ */
338
+ private recordCallsSchemaReject;
339
+ /**
340
+ * REL-4: the `calls:` ancestry depth of an instance — how many `producedBy`
341
+ * parent links separate it from the root of its composed tree. A root
342
+ * instance (no `producedBy`) is depth 0; a child spawned by the root is
343
+ * depth 1; and so on. O(depth) — walks the parent chain, which is exactly the
344
+ * tree the spawn bound is protecting, so it only runs on an actual spawn.
345
+ */
346
+ private callsAncestryDepth;
347
+ /**
348
+ * REL-4: record a `calls:` depth-limit refusal as a debt on the PARENT calls
349
+ * artifact — same clean-stop mechanism as `recordCallsSchemaReject` (mark it
350
+ * `rejected`, stamp the current gate fingerprint so the STEP-2 F2 guard skips
351
+ * re-attempts on later ticks), but the reason is a plain structural rejection,
352
+ * NOT a schema failure: it does not touch `schemaRejects` (that counter gates
353
+ * `maxSchemaFailures` and means something specific). The message is actionable
354
+ * — a depth-limit trip almost always means a `calls:` cycle in the def set
355
+ * bypassed load-time validation (a hand-wired resolver construction validation
356
+ * cannot see); raising `maxCallDepth` is only correct when the depth is truly
357
+ * intentional. Stopping here — instead of spawning — is what prevents the
358
+ * unbounded row creation + stack overflow REL-4 describes.
359
+ *
360
+ * B2 asymmetry (deliberate, NOT an oversight): unlike `recordCallsSchemaReject`
361
+ * this recorder is NOT exposed to the wrong-snapshot race, so it needs no
362
+ * carry-and-compare guard. A depth refusal's validity does not depend on the
363
+ * gate snapshot: `callsAncestryDepth` walks the immutable `producedBy` chain and
364
+ * `maxCallDepth` is fixed, so a refusal decided at time T stays valid at
365
+ * recording time regardless of concurrent gate movement — and if a moved-gate
366
+ * re-attempt were somehow blocked, it would deterministically re-trip the same
367
+ * depth refusal anyway (identical outcome, no lost valid update to strand).
368
+ */
369
+ private recordCallsDepthReject;
195
370
  /**
196
371
  * M2B: Maintain all `calls:` steps for a parent workflow.
197
372
  * Called at the top of tick (outside any tx) and as cascade-up prompt.
@@ -200,23 +375,171 @@ export declare class Engine {
200
375
  * the parent artifact when the child's declared output is green.
201
376
  */
202
377
  private maintainCalls;
378
+ /**
379
+ * The seed/consistency invariant for a `calls:` step: every child input wired
380
+ * from a parent gate artifact whose value is defined must currently deepEqual
381
+ * that gate value. STEP 6's in-tx verify calls this; STEP 5's re-provide
382
+ * condition applies the same per-input invariant inline (mirrored, not a call
383
+ * here) — the two encode the same rule and must be kept in step by hand. Both
384
+ * skip when the parent gate value is undefined (nothing to provide). A mismatch
385
+ * means a re-provide is pending against the very gate a fresh fingerprint would
386
+ * claim, so publishing now would stamp a stale child value under a newer gate.
387
+ */
388
+ private childConsistentWithGate;
389
+ /**
390
+ * STEP 6 machine-green as an atomic snapshot-and-commit. maintainCalls'
391
+ * optimistic pre-reads decide only WHETHER to call this; the decision inputs
392
+ * are all re-read and re-verified here INSIDE the same BEGIN IMMEDIATE that
393
+ * performs the write, so the published value, the gate fingerprint it claims,
394
+ * and the child-outcome pin come from ONE snapshot. Any verify failing aborts
395
+ * the publish (returns false; the commit is a no-op — do NOT throw, there is
396
+ * nothing to roll back, and an abort must not record debt/reasons/fingerprint:
397
+ * the state is simply "not yet" and the next tick redoes the pass against
398
+ * fresh state). Returns true only when it actually wrote, so the caller fires
399
+ * commit/settled events only on a real publish.
400
+ */
401
+ private publishCallsGreen;
402
+ /**
403
+ * STEP 6 re-arm as the mirror-image atomic guard. maintainCalls' optimistic
404
+ * pre-read decides only WHETHER to call this; the parent artifact AND the
405
+ * child outcome are re-read inside the write lock, and the re-arm happens only
406
+ * if the parent is still green AND the child outcome is still NOT green in-tx.
407
+ * If the child went green between the optimistic read and the tx, this does
408
+ * nothing (returns false) and the next maintainCalls pass publishes normally.
409
+ * Returns true only when it wrote.
410
+ */
411
+ private rearmCallsGreen;
203
412
  /**
204
413
  * M2B cascade-up prompt: if `workflow` has a producedBy link, trigger
205
414
  * maintainCalls on its parent so the parent reflects the child's progress promptly.
206
415
  * Called after child commits (green, close) — outside any open tx.
207
416
  */
208
417
  private triggerParentIfChild;
418
+ /**
419
+ * Pull eligible orders for `workflow`. §23.6.8: **deep by default** — after
420
+ * maintaining and ticking this instance, descend into every live `calls:`
421
+ * child (recursively, grandchildren too) and fold their orders / reaps /
422
+ * deferrals / `dueAt` into the returned result so a driver that ticks only
423
+ * the root drives the whole composed tree (a shallow tick would deadlock a
424
+ * `calls:` workflow — the child's eligible steps would never be claimed).
425
+ * Pass `{ deep: false }` (CLI `--shallow`) to restore the pre-deep behavior:
426
+ * only this instance's own orders. See `TickResult` for the fold semantics.
427
+ */
209
428
  tick(workflow: string, opts?: {
210
429
  now?: number;
430
+ deep?: boolean;
431
+ labels?: string[];
211
432
  }): TickResult;
212
- /** Per-step cadence + daily budget + parallel cap over the eligible firings. */
433
+ /**
434
+ * The recursive tick worker. Runs this instance's own maintain → reap →
435
+ * eligible → claim cycle (its body is byte-for-byte the pre-deep `tick`,
436
+ * kept inside its own `store.tx`), then — when `deep` — descends into each
437
+ * live `calls:` child by calling itself again. The descent MUST run OUTSIDE
438
+ * this frame's `store.tx`: `store.tx` forbids re-entrancy, and every child
439
+ * frame opens its own tx (via its own `maintainCalls` + tick body), so a
440
+ * child is driven by a full nested `tickInternal`, never a child tx opened
441
+ * inside the parent's.
442
+ *
443
+ * REL-4: `visited` (a set of workflow INSTANCE ids) is NOT a sufficient guard
444
+ * against a `calls:` cycle. Each descent level's `maintainCalls` SPAWNS a
445
+ * brand-new child instance, so a self-calling def produces a fresh id at every
446
+ * level — `visited` never trips, and recursion would run unbounded (one DB row
447
+ * per level) until the stack overflows. The real guard is the `maxCallDepth`
448
+ * bound: `maintainCalls` refuses to spawn past it (so a newly-created tree can
449
+ * never get here too deep), and the `depth` check below is the belt-and-braces
450
+ * backstop for a PRE-EXISTING deep tree (e.g. a DB written by an older build
451
+ * before the spawn bound existed) — it throws rather than overflow the stack.
452
+ * `visited` still earns its keep as a re-entrancy guard for a genuinely
453
+ * re-encountered instance within one tick.
454
+ *
455
+ * B1 (in-tx descent claim guard): a deep parent descends into a child by
456
+ * calling this again with `parentEdge` — the calls: edge the child hangs
457
+ * from. Inside the child frame's OWN claim tx, before any child order is
458
+ * issued, we re-verify that the parent gate and the child's synchronized
459
+ * inputs are still mutually consistent with the CURRENTLY-committed parent
460
+ * state (the same predicate `publishCallsGreen` uses on the publish side).
461
+ * `provisionCallsChild` commits child input v1; another connection can advance
462
+ * the parent to v2 before this non-transactional descent claims — without the
463
+ * guard the child claims work against the stale v1. On mismatch the frame
464
+ * issues nothing and its subtree is not descended; the next parent tick
465
+ * re-synchronizes via `maintainCalls`. Absent `parentEdge` = the root frame,
466
+ * unguarded (nothing above it to be inconsistent with). Each frame checks only
467
+ * its IMMEDIATE parent edge; a grandchild gets its own edge from the child
468
+ * frame's descent loop, so every issued order in the tree is guarded by the
469
+ * edge it hangs from. The guard is silent (no debt/reasons/events), mirroring
470
+ * the abort discipline of `publishCallsGreen`/`provisionCallsChild`.
471
+ */
472
+ private tickInternal;
473
+ /**
474
+ * §23.6.8: is a `calls:` step's gate ready — i.e. every parent artifact wired
475
+ * into `callsInputs` is green? Shared by `maintainCalls` STEP 1 and
476
+ * `callsDescendTargets` so the descend condition can never drift from the
477
+ * spawn/re-provide condition. Empty gate (`callsInputs: {}`) is always ready.
478
+ */
479
+ private callsGateReady;
480
+ /**
481
+ * §23.6.8: the live `calls:` children a deep tick should descend into, one
482
+ * per calls: step whose (1) gate is green, (2) child instance exists, and
483
+ * (3) the parent calls artifact is specifically `owed`. Read AFTER
484
+ * `maintainCalls` has run this frame, so a just-spawned child is visible and
485
+ * a just-machine-greened debt is correctly skipped. Consequences that fall
486
+ * out for free: gate re-armed after spawn → not ready → no descend
487
+ * (consistent with maintainCalls bailing at STEP 1, never driving work on
488
+ * disputed inputs); debt already paid → skip.
489
+ *
490
+ * B3: condition (3) descends ONLY on `owed`, never on any non-green state.
491
+ * `owed` is the sole live producer debt: it covers the fresh spawn, the F4
492
+ * propagated-reject reopen (parent reopened to owed pinned at the rejected
493
+ * child version), and `rearmCallsGreen`'s reopen — all of which legitimately
494
+ * want child work driven. `green` is paid; `rejected` (F2 schema / REL-4 depth
495
+ * refusal) needs a human `retry` or a moved gate handled by `maintainCalls`,
496
+ * never child work; `skipped` is a human-declared dead branch; `retracted` is
497
+ * terminal; `submitted` is not a producer debt (a calls artifact is machine
498
+ * -greened and should never be `submitted`) — none of these represent live
499
+ * child work, so descending into them issued orders for dead/refused branches.
500
+ */
501
+ private callsDescendTargets;
502
+ /**
503
+ * Per-step cadence + daily budget + parallel cap over the eligible firings.
504
+ * A2: `labels` is the tick caller's optional claim filter — when non-empty, a
505
+ * step whose own `labels` are also non-empty is only schedulable when the two
506
+ * intersect; a disjoint step's firings are deferred as `'label-mismatch'`.
507
+ * Filtering here (before cadence/budget) means a mismatched firing never
508
+ * consumes the caller's slots and never perturbs cadence math.
509
+ */
213
510
  private applySchedule;
214
511
  /** Return the effective reap TTL for a step — per-step override or engine default. */
215
512
  private effectiveTtl;
513
+ /**
514
+ * A3 (REL-8): return the effective max total lease lifetime for a step, or
515
+ * `undefined` when no cap is configured. Per-step `maxLease` overrides the
516
+ * engine option; when both are unset there is no cap (heartbeats extend the
517
+ * lease indefinitely). Uses `??` (not `||`) so an explicit `0` stays a cap.
518
+ */
519
+ private effectiveMaxLease;
520
+ /**
521
+ * Classify a claimed task's liveness against the two independent bounds, so a
522
+ * reap can report WHY a lease was cleared:
523
+ * - `heartbeat-lost` — the anchor rule lapsed: `now - max(claimedAt,
524
+ * heartbeatAt) > ttl`. The job went silent (or never beat).
525
+ * - `max-lease-exceeded` — the anchor rule still holds (a live, beating job)
526
+ * but a CONFIGURED `maxLease` cap has been exceeded: `now - claimedAt >
527
+ * maxLease`. Only reachable when `maxLease !== undefined`.
528
+ * - `fresh` — neither bound violated.
529
+ *
530
+ * Precedence: `heartbeat-lost` wins when both bounds lapse — if the job was
531
+ * not alive under the anchor rule, reporting `max-lease-exceeded` would wrongly
532
+ * suggest the cap killed a healthy job. The cap reason is reported only for a
533
+ * still-beating lease. The clamp is measured off the ORIGINAL `claimedAt` of
534
+ * the current claim; after a reap + re-claim it re-anchors to the new claim.
535
+ */
536
+ private staleness;
216
537
  /**
217
538
  * Unified liveness predicate: returns true if the task's claim is still fresh.
218
- * Uses max(claimedAt, heartbeatAt ?? claimedAt) as the freshness anchor so a
219
- * heartbeating run is never falsely reaped even after the global TTL elapses.
539
+ * Thin wrapper over {@link staleness} — see it for the anchor rule and the
540
+ * opt-in max-lease clamp. A heartbeating run is never falsely reaped after the
541
+ * global TTL (anchor rule), and only a configured `maxLease` can reap a
542
+ * still-beating lease.
220
543
  */
221
544
  private isClaimFresh;
222
545
  /** Claim a firing's lease via CAS, snapshot the fingerprint, open a run. */
@@ -287,6 +610,20 @@ export declare class Engine {
287
610
  outcome: 'rejected' | 'born-rejected';
288
611
  reason?: string;
289
612
  };
613
+ /**
614
+ * F4: forward a reject on a `calls:`-produced artifact to the CHILD's
615
+ * outcome artifact, then reopen the parent calls artifact to `owed` pinned
616
+ * (via `childOutcomePin`) to the just-rejected child outcome version, so
617
+ * STEP 6's mirror only fires again once the child has actually rebuilt past
618
+ * this verdict (§ F4 settled design).
619
+ *
620
+ * The forward is engine-internal: authority was already checked against the
621
+ * PARENT def by `assertAuthority` in `reject()` above, so the child's own
622
+ * `assertAuthority` is not consulted — the author recorded on the child's
623
+ * reasons entry is `parent:<by>` to make the indirection visible in its
624
+ * audit thread.
625
+ */
626
+ private rejectCallsArtifact;
290
627
  /** Retract a collection member (§11.3): drop it, terminally; abandon the index. */
291
628
  retract(workflow: string, path: string, by: Author, text: string): void;
292
629
  /** A producer skips its own owed output on a dead branch (§16.1 routing). */
@@ -304,7 +641,14 @@ export declare class Engine {
304
641
  /**
305
642
  * Touch the liveness timestamp on an open run's task. A run that periodically
306
643
  * calls heartbeat() will never be falsely reaped as long as beats arrive within
307
- * the effective TTL. Throws (via openRun) if the run no longer holds its lease.
644
+ * the effective TTL — EXCEPT (A3) when a max-lease cap is CONFIGURED and total
645
+ * lifetime since the original claim exceeds it: past `claimedAt + maxLease` the
646
+ * read-side freshness predicate (`isClaimFresh`) reports the lease stale no
647
+ * matter how recent the beat, so a wedged-but-beating run is reaped and
648
+ * re-claimable. With no cap configured (the default) beats extend the lease
649
+ * indefinitely. This write stays dumb — it only records `heartbeatAt`; the
650
+ * clamp is judged on read. Throws (via openRun) if the run no longer holds its
651
+ * lease.
308
652
  */
309
653
  heartbeat(workflow: string, run: string, now?: number): void;
310
654
  /** Release stranded leases (claimed by a dead/closed run, or past the TTL). */
@@ -328,11 +672,7 @@ export declare class Engine {
328
672
  ttlOverride?: number;
329
673
  }): {
330
674
  count: number;
331
- details: Array<{
332
- step: string;
333
- key: string;
334
- run?: string;
335
- }>;
675
+ details: ReapDetail[];
336
676
  };
337
677
  status(workflow: string): EngineWorkflowStatus;
338
678
  /** Set a persistent alarm for an idle evaluator step. Survives restart. */
@@ -410,6 +750,21 @@ export declare class Engine {
410
750
  */
411
751
  private groupCasCheck;
412
752
  private artMap;
753
+ /**
754
+ * §23.6.8: a compact summary of a `calls:` child for parent-status enrichment.
755
+ * Uses the pure `workflowStatus` for the child's own debts (lighter than a
756
+ * full recursive `Engine.status` — the `stalled` flag is already set by the
757
+ * pure layer). `stalled` propagates recursively along the child's OWN unpaid
758
+ * `calls:` path so a grandchild stall shows as `stalled: true` here. `debts`
759
+ * is a COUNT — the `workflow` id is the human's inspection handle. `visited`
760
+ * guards against any accidental instance cycle.
761
+ *
762
+ * Returns `undefined` when the child's def is unresolvable (an unpinned row
763
+ * whose def was deleted/renamed) — practically unreachable since `calls:`
764
+ * spawns pin (§28), but a summary is enrichment, and enrichment must not
765
+ * make `status(parent)` throw (same stance as the §28 drift flag).
766
+ */
767
+ private childStatusSummary;
413
768
  private defFor;
414
769
  private step;
415
770
  /**