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/CHANGELOG.md +54 -0
- package/README.md +76 -7
- package/bin/owenloop.mjs +2 -2
- package/dist/add.d.ts +412 -0
- package/dist/add.js +999 -0
- package/dist/cli.d.ts +47 -0
- package/dist/cli.js +1809 -19
- package/dist/defs.d.ts +33 -0
- package/dist/defs.js +112 -19
- package/dist/engine.d.ts +338 -50
- package/dist/engine.js +854 -170
- package/dist/factory.d.ts +19 -0
- package/dist/factory.js +41 -5
- package/dist/hub.d.ts +290 -0
- package/dist/hub.js +408 -0
- package/dist/index.d.ts +3 -2
- package/dist/index.js +2 -1
- package/dist/model.d.ts +36 -0
- package/dist/store.d.ts +14 -2
- package/dist/store.js +269 -21
- package/dist/types.d.ts +92 -0
- package/dist/untar.d.ts +47 -0
- package/dist/untar.js +164 -0
- package/dist/util.d.ts +76 -0
- package/dist/util.js +96 -0
- package/docs/authoring.md +48 -1
- package/docs/cli.md +446 -3
- package/docs/design.md +72 -9
- package/docs/embedding.md +53 -7
- package/package.json +1 -1
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,
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
272
|
-
* heartbeating run is never falsely reaped
|
|
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
|
|
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:
|
|
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
|
/**
|