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/CHANGELOG.md +65 -0
- package/README.md +94 -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 +171 -21
- package/dist/engine.d.ts +395 -40
- package/dist/engine.js +1118 -135
- 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/model.js +20 -9
- package/dist/store.d.ts +14 -2
- package/dist/store.js +285 -35
- package/dist/types.d.ts +120 -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 +118 -1
- package/docs/cli.md +446 -3
- package/docs/design.md +259 -32
- package/docs/embedding.md +81 -10
- package/examples/workflows/command-worker.yaml +56 -0
- package/package.json +1 -1
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,
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
*
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
219
|
-
* 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.
|
|
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
|
|
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:
|
|
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
|
/**
|