owenloop 0.2.1 → 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,7 +12,8 @@
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';
15
+ import type { Author, Fingerprint, Order, WorkflowDef } from './types.ts';
16
+ export type { Order } from './types.ts';
16
17
  /**
17
18
  * F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
18
19
  * by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
@@ -24,47 +25,19 @@ import type { Author, FiringTrigger, ReasonEntry, WorkflowDef } from './types.ts
24
25
  export declare class SchemaRefusalError extends Error {
25
26
  readonly inputName: string;
26
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;
27
39
  constructor(inputName: string, issues: SchemaIssue[]);
28
40
  }
29
- /** A self-contained unit of work emitted by a tick. */
30
- export interface Order {
31
- run: string;
32
- workflow: string;
33
- step: string;
34
- key: string;
35
- index?: number;
36
- inputs: string[];
37
- outputs: string[];
38
- workdir?: string;
39
- model?: string;
40
- /** Declares which kind of executor this order is for. Absent = 'agent'
41
- * (today's behavior). Opaque to the engine; carried through verbatim from
42
- * the step definition, same pass-through contract as `model`/`x`. */
43
- worker?: string;
44
- /** The command string for a `worker: command` order. Opaque to the engine
45
- * — never parsed, never shelled out. */
46
- command?: string;
47
- /** Opaque config object for a non-agent/non-command worker type (or
48
- * alongside `command`). Carried through untouched, contents never read. */
49
- spec?: Record<string, unknown>;
50
- /** §27.3: the step's opaque `x:` extension map, carried through untouched
51
- * (same pass-through contract as `model`). The engine never reads it —
52
- * it exists for the external runner/tooling consuming this order. */
53
- x?: Record<string, unknown>;
54
- prompt: string;
55
- /** captured handles of the green inputs this run builds on */
56
- consumes: Record<string, unknown>;
57
- /** the owed outputs and their accumulated reason threads (the feedback channel) */
58
- owes: Array<{
59
- path: string;
60
- acceptance: string;
61
- judgmentRejects: number;
62
- schemaRejects: number;
63
- reasons: ReasonEntry[];
64
- }>;
65
- /** The trigger that woke this firing (§21). Absent = 'inputsGreen'. */
66
- cause?: FiringTrigger;
67
- }
68
41
  /**
69
42
  * §tick-deferred: an eligible firing the tick did NOT promote to an order, tagged
70
43
  * with why. `'in-flight'` — the step's task is already claimed by an open run;
@@ -72,8 +45,11 @@ export interface Order {
72
45
  * step's daily run allowance is exhausted (binding over parallel); `'parallel-cap'`
73
46
  * — the step's concurrency cap is the binding constraint. Always emitted by
74
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.
75
51
  */
76
- export type DeferredReason = 'in-flight' | 'cadence' | 'daily-budget' | 'parallel-cap';
52
+ export type DeferredReason = 'in-flight' | 'cadence' | 'daily-budget' | 'parallel-cap' | 'label-mismatch';
77
53
  export interface DeferredFiring {
78
54
  step: string;
79
55
  key: string;
@@ -81,7 +57,29 @@ export interface DeferredFiring {
81
57
  inputs: string[];
82
58
  outputs: string[];
83
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;
84
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
+ */
85
83
  export interface TickResult {
86
84
  workflow: string;
87
85
  orders: Order[];
@@ -174,16 +172,51 @@ export type EngineEvent = {
174
172
  };
175
173
  /** A synchronous observer of {@link EngineEvent}s. */
176
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
+ }
177
198
  export declare class Engine {
178
199
  readonly store: Store;
179
200
  private readonly resolveDef;
180
201
  private readonly reapTtlMs;
202
+ private readonly maxLeaseMs;
203
+ private readonly maxCallDepth;
181
204
  private readonly listeners;
182
205
  private readonly onListenerError?;
183
206
  /** M2B: recursion guard — set of parentWf ids currently inside maintainCalls. */
184
207
  private readonly _inMaintainCalls;
185
208
  constructor(store: Store, resolveDef: DefResolver, opts?: {
186
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;
187
220
  /** A listener registered up front, equivalent to a `subscribe` call. */
188
221
  onEvent?: EngineListener;
189
222
  /** Where a throwing listener's error goes (default: swallowed). */
@@ -199,6 +232,49 @@ export declare class Engine {
199
232
  subscribe(listener: EngineListener): () => void;
200
233
  /** Start a workflow instance: persist it, seed its declared inputs, settle. */
201
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;
202
278
  /** A human/external producer supplies (greens) an owed input. */
203
279
  provideInput(workflow: string, name: string, value: Record<string, unknown>): void;
204
280
  /**
@@ -243,8 +319,54 @@ export declare class Engine {
243
319
  * Stamps the current gate fingerprint on the rejected artifact so the
244
320
  * STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
245
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`).
246
337
  */
247
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;
248
370
  /**
249
371
  * M2B: Maintain all `calls:` steps for a parent workflow.
250
372
  * Called at the top of tick (outside any tx) and as cascade-up prompt.
@@ -253,23 +375,171 @@ export declare class Engine {
253
375
  * the parent artifact when the child's declared output is green.
254
376
  */
255
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;
256
412
  /**
257
413
  * M2B cascade-up prompt: if `workflow` has a producedBy link, trigger
258
414
  * maintainCalls on its parent so the parent reflects the child's progress promptly.
259
415
  * Called after child commits (green, close) — outside any open tx.
260
416
  */
261
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
+ */
262
428
  tick(workflow: string, opts?: {
263
429
  now?: number;
430
+ deep?: boolean;
431
+ labels?: string[];
264
432
  }): TickResult;
265
- /** 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
+ */
266
510
  private applySchedule;
267
511
  /** Return the effective reap TTL for a step — per-step override or engine default. */
268
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;
269
537
  /**
270
538
  * Unified liveness predicate: returns true if the task's claim is still fresh.
271
- * Uses max(claimedAt, heartbeatAt ?? claimedAt) as the freshness anchor so a
272
- * 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.
273
543
  */
274
544
  private isClaimFresh;
275
545
  /** Claim a firing's lease via CAS, snapshot the fingerprint, open a run. */
@@ -371,7 +641,14 @@ export declare class Engine {
371
641
  /**
372
642
  * Touch the liveness timestamp on an open run's task. A run that periodically
373
643
  * calls heartbeat() will never be falsely reaped as long as beats arrive within
374
- * 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.
375
652
  */
376
653
  heartbeat(workflow: string, run: string, now?: number): void;
377
654
  /** Release stranded leases (claimed by a dead/closed run, or past the TTL). */
@@ -395,11 +672,7 @@ export declare class Engine {
395
672
  ttlOverride?: number;
396
673
  }): {
397
674
  count: number;
398
- details: Array<{
399
- step: string;
400
- key: string;
401
- run?: string;
402
- }>;
675
+ details: ReapDetail[];
403
676
  };
404
677
  status(workflow: string): EngineWorkflowStatus;
405
678
  /** Set a persistent alarm for an idle evaluator step. Survives restart. */
@@ -477,6 +750,21 @@ export declare class Engine {
477
750
  */
478
751
  private groupCasCheck;
479
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;
480
768
  private defFor;
481
769
  private step;
482
770
  /**