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.js
CHANGED
|
@@ -15,10 +15,50 @@ import { summarizeIssues, validateValue } from "./schema.js";
|
|
|
15
15
|
import { hashDef } from "./defs.js";
|
|
16
16
|
import { localMidnightMs, nowMs, randId } from "./util.js";
|
|
17
17
|
const DEFAULT_REAP_TTL_MS = 2 * 60 * 60 * 1000; // 2h
|
|
18
|
+
/**
|
|
19
|
+
* REL-4: hard cap on `calls:` composition depth (root instance = depth 0), a
|
|
20
|
+
* defense-in-depth bound independent of construction-time cycle validation.
|
|
21
|
+
* Generous — real compositions in this repo are depth 2–3; the bound only trips
|
|
22
|
+
* on a pathological chain (typically a `calls:` cycle that bypassed load-time
|
|
23
|
+
* validation via a hand-wired `Engine` + custom `DefResolver`). See
|
|
24
|
+
* `maintainCalls` (spawn-time refusal) and `tickInternal` (descent guard).
|
|
25
|
+
*/
|
|
26
|
+
const DEFAULT_MAX_CALL_DEPTH = 64;
|
|
27
|
+
/**
|
|
28
|
+
* F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
|
|
29
|
+
* by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
|
|
30
|
+
* `Error` so callers that need to distinguish "this value doesn't fit the
|
|
31
|
+
* schema" from a genuine bug (e.g. `maintainCalls`'s STEP 3/STEP 5, which must
|
|
32
|
+
* turn a CHILD's schema refusal into a debt on the parent rather than crash
|
|
33
|
+
* the parent's tick) can catch narrowly instead of blanket-catching.
|
|
34
|
+
*/
|
|
35
|
+
export class SchemaRefusalError extends Error {
|
|
36
|
+
inputName;
|
|
37
|
+
issues;
|
|
38
|
+
/**
|
|
39
|
+
* B2: the gate fingerprint of the exact parent snapshot the failed validation
|
|
40
|
+
* saw, captured inside the validating transaction and attached before this
|
|
41
|
+
* error is rethrown out to `maintainCalls`. `recordCallsSchemaReject` compares
|
|
42
|
+
* it to the gate fingerprint at recording time so a refusal recorded after a
|
|
43
|
+
* concurrent VALID gate advance is discarded instead of stamped onto (and
|
|
44
|
+
* thereby stalling) the valid update. Mutable and optional: set by the thrower
|
|
45
|
+
* (`provisionCallsChild`) once the snapshot is known; absent means "no snapshot
|
|
46
|
+
* carried" and the recorder falls back to today's stamp-fresh behavior.
|
|
47
|
+
*/
|
|
48
|
+
gateFingerprint;
|
|
49
|
+
constructor(inputName, issues) {
|
|
50
|
+
super(`input '${inputName}' failed schema: ${summarizeIssues(issues)}`);
|
|
51
|
+
this.name = 'SchemaRefusalError';
|
|
52
|
+
this.inputName = inputName;
|
|
53
|
+
this.issues = issues;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
18
56
|
export class Engine {
|
|
19
57
|
store;
|
|
20
58
|
resolveDef;
|
|
21
59
|
reapTtlMs;
|
|
60
|
+
maxLeaseMs;
|
|
61
|
+
maxCallDepth;
|
|
22
62
|
listeners = new Set();
|
|
23
63
|
onListenerError;
|
|
24
64
|
/** M2B: recursion guard — set of parentWf ids currently inside maintainCalls. */
|
|
@@ -27,6 +67,8 @@ export class Engine {
|
|
|
27
67
|
this.store = store;
|
|
28
68
|
this.resolveDef = resolveDef;
|
|
29
69
|
this.reapTtlMs = opts.reapTtlMs ?? DEFAULT_REAP_TTL_MS;
|
|
70
|
+
this.maxLeaseMs = opts.maxLeaseMs;
|
|
71
|
+
this.maxCallDepth = opts.maxCallDepth ?? DEFAULT_MAX_CALL_DEPTH;
|
|
30
72
|
if (opts.onEvent)
|
|
31
73
|
this.listeners.add(opts.onEvent);
|
|
32
74
|
this.onListenerError = opts.onListenerError;
|
|
@@ -49,46 +91,202 @@ export class Engine {
|
|
|
49
91
|
createInstance(defName, opts = {}) {
|
|
50
92
|
const def = this.resolveDef(defName);
|
|
51
93
|
const id = randId('wf');
|
|
52
|
-
this.store.tx(() =>
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
94
|
+
this.store.tx(() => this.createInstanceInTx(defName, def, id, opts));
|
|
95
|
+
this.fire({ type: 'instance', workflow: id, def: defName });
|
|
96
|
+
this.fireSettled(id);
|
|
97
|
+
return id;
|
|
98
|
+
}
|
|
99
|
+
/**
|
|
100
|
+
* The transactional body of instance creation: persist the workflow row, seed
|
|
101
|
+
* its declared inputs (validating any provided values), and settle. MUST run
|
|
102
|
+
* inside a `store.tx()` — callers own the tx and the post-commit event firing.
|
|
103
|
+
* Extracted from {@link createInstance} so the atomic child-provision path
|
|
104
|
+
* ({@link provisionCallsChild}) can find-or-create a child and sync its inputs
|
|
105
|
+
* under a single `BEGIN IMMEDIATE` without nesting transactions.
|
|
106
|
+
*/
|
|
107
|
+
createInstanceInTx(defName, def, id, opts) {
|
|
108
|
+
// §28: pin this instance to the def it was created against — a snapshot
|
|
109
|
+
// of the fully-expanded compiled def plus its content hash. Every new
|
|
110
|
+
// instance is stamped; "no snapshot" is strictly a legacy-row
|
|
111
|
+
// compatibility case (see defFor), never a choice made here.
|
|
112
|
+
const wfData = { def: defName, defSnapshot: def, defHash: hashDef(def) };
|
|
113
|
+
if (opts.title !== undefined)
|
|
114
|
+
wfData.title = opts.title;
|
|
115
|
+
if (opts.params !== undefined)
|
|
116
|
+
wfData.params = opts.params;
|
|
117
|
+
this.store.insertWorkflow(id, wfData, opts.producedBy);
|
|
118
|
+
for (const input of def.inputs) {
|
|
119
|
+
const provided = opts.provide?.[input.name];
|
|
120
|
+
if (provided !== undefined && input.schema !== undefined) {
|
|
121
|
+
const check = validateValue(input.schema, provided);
|
|
122
|
+
if (!check.valid) {
|
|
123
|
+
throw new SchemaRefusalError(input.name, check.issues);
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
const seedGreen = !input.seedOwed || provided !== undefined;
|
|
127
|
+
const a = {
|
|
128
|
+
workflow: id,
|
|
129
|
+
path: input.name,
|
|
130
|
+
producer: input.producer,
|
|
131
|
+
acceptance: seedGreen ? 'green' : 'owed',
|
|
132
|
+
version: seedGreen ? 1 : 0,
|
|
133
|
+
reasons: [],
|
|
134
|
+
judgmentRejects: 0,
|
|
135
|
+
schemaRejects: 0,
|
|
136
|
+
};
|
|
137
|
+
if (provided !== undefined)
|
|
138
|
+
a.value = provided;
|
|
139
|
+
this.store.putArtifact(a);
|
|
140
|
+
}
|
|
141
|
+
this.settle(id, def);
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* C2: atomic fresh-snapshot child provision for a `calls:` step — the
|
|
145
|
+
* creation-side mirror of `publishCallsGreen`'s discipline. Find-or-create the
|
|
146
|
+
* child AND synchronize every mapped child input, all inside ONE
|
|
147
|
+
* `BEGIN IMMEDIATE`, from a parent snapshot RE-READ inside that same tx — never
|
|
148
|
+
* from the caller's (STEP-1) snapshot. Because the write and every read it
|
|
149
|
+
* depends on share one write lock, the committed seed/sync values are by
|
|
150
|
+
* construction current at commit: "never regress a child input" needs no
|
|
151
|
+
* version comparison — the fresh in-tx read IS the guard.
|
|
152
|
+
*
|
|
153
|
+
* This closes two reproduced cross-connection races the STEP-1 snapshot exposed:
|
|
154
|
+
* (a) SPAWN — a child seeded from a stale parent value while a concurrent tick
|
|
155
|
+
* advanced the gate; (b) RE-PROVISION — a stale parent value stamped backward
|
|
156
|
+
* over a newer child input (version bumps, value regresses). `maintainCalls`'
|
|
157
|
+
* pre-reads (gate readiness, `findChildByParent`, F2 fingerprint, depth) are now
|
|
158
|
+
* OPTIMISTIC — they decide only WHETHER to attempt; this helper re-verifies
|
|
159
|
+
* everything the write depends on in-tx.
|
|
160
|
+
*
|
|
161
|
+
* Returns `{ childId, created, provided }` — `created` true only when THIS call
|
|
162
|
+
* inserted the child, `provided` the list of child inputs it actually re-wrote
|
|
163
|
+
* (empty for a plain spawn, since a fresh seed already equals the fresh
|
|
164
|
+
* snapshot). Events (`instance`, `commit`/`provide`, `settled`) and the child
|
|
165
|
+
* cascade are the caller's responsibility, fired post-commit, matching the
|
|
166
|
+
* pre-C2 per-action semantics. Returns `null` on a silent abort: the gate was
|
|
167
|
+
* re-armed, or an F2 schema-reject debt landed, since the pre-read — "not yet"
|
|
168
|
+
* state, next tick redoes the pass (publishCallsGreen discipline; no debt, no
|
|
169
|
+
* events written).
|
|
170
|
+
*
|
|
171
|
+
* A `SchemaRefusalError` (a seed or re-provided parent value illegal per the
|
|
172
|
+
* child's input schema) propagates out with the whole tx rolled back — no
|
|
173
|
+
* orphan child row, no partial input sync — preserving the F2 contract; the
|
|
174
|
+
* caller records it as a debt on the parent calls artifact.
|
|
175
|
+
*/
|
|
176
|
+
provisionCallsChild(parentWf, step, callsStem, gateStems, now) {
|
|
177
|
+
// B2: the gate fingerprint of the exact in-tx snapshot the seed/re-provide
|
|
178
|
+
// validation ran against. Captured fresh inside `run()` so a retry re-reads
|
|
179
|
+
// it; carried out on a `SchemaRefusalError` so `recordCallsSchemaReject` can
|
|
180
|
+
// tell "gate unmoved since the failure" (stamp) from "a concurrent valid
|
|
181
|
+
// gate advance landed" (discard). Pure computation over the already-fetched
|
|
182
|
+
// `parentArts` — no extra in-tx store read (E2 busy_timeout GOTCHA-safe).
|
|
183
|
+
let seenGateFp;
|
|
184
|
+
const run = () => this.store.tx(() => {
|
|
185
|
+
// 1. FRESH parent snapshot — re-read inside the write lock; never trust
|
|
186
|
+
// the caller's STEP-1 map.
|
|
187
|
+
const parentArts = this.artMap(parentWf);
|
|
188
|
+
seenGateFp = computeFingerprint(parentArts, gateStems);
|
|
189
|
+
// 2. Gate readiness against the fresh snapshot: a stem re-armed
|
|
190
|
+
// concurrently must stop provisioning (abort silent — STEP-1 semantics).
|
|
191
|
+
if (!this.callsGateReady(parentArts, step))
|
|
192
|
+
return null;
|
|
193
|
+
// 3. In-tx F2 guard: an F2 schema-reject debt that landed concurrently
|
|
194
|
+
// (rejected + gate fingerprint unmoved) must not be provisioned over — a
|
|
195
|
+
// moved gate falls through and retries (mirrors STEP 2's optimistic guard).
|
|
196
|
+
// Read the calls artifact from the SAME fresh in-tx `parentArts` snapshot
|
|
197
|
+
// (listArtifacts), not a separate `store.getArtifact` — one consistent
|
|
198
|
+
// read, and it avoids adding a parent-calls-artifact read inside the write
|
|
199
|
+
// lock (which STEP-6's cross-connection tests count).
|
|
200
|
+
const parentCallsArt = parentArts.get(callsStem);
|
|
201
|
+
if (parentCallsArt?.acceptance === 'rejected') {
|
|
202
|
+
const fp = computeFingerprint(parentArts, gateStems);
|
|
203
|
+
if (deepEqual(fp, parentCallsArt.fingerprint ?? {}))
|
|
204
|
+
return null;
|
|
205
|
+
}
|
|
206
|
+
// 4. Find-or-create the child (in-tx check-then-insert — absorbs the old
|
|
207
|
+
// spawnChildIfAbsent guarantee, only its home moved).
|
|
208
|
+
let child = this.store.findChildByParent(parentWf, callsStem);
|
|
209
|
+
let created = false;
|
|
210
|
+
let childDef;
|
|
211
|
+
if (!child) {
|
|
212
|
+
const childId = randId('wf');
|
|
213
|
+
childDef = this.resolveDef(step.calls);
|
|
214
|
+
const seedProvide = {};
|
|
215
|
+
for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
|
|
216
|
+
const parentArt = parentArts.get(parentArtifactName);
|
|
217
|
+
if (parentArt?.value !== undefined) {
|
|
218
|
+
seedProvide[childInputName] = parentArt.value;
|
|
69
219
|
}
|
|
70
220
|
}
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
221
|
+
// createInstanceInTx validates the seed against the child input schema
|
|
222
|
+
// and throws SchemaRefusalError (tx rolls back — no orphan child).
|
|
223
|
+
this.createInstanceInTx(step.calls, childDef, childId, {
|
|
224
|
+
producedBy: { parentWf, parentPath: callsStem },
|
|
225
|
+
provide: seedProvide,
|
|
226
|
+
});
|
|
227
|
+
child = this.store.getWorkflow(childId);
|
|
228
|
+
created = true;
|
|
229
|
+
}
|
|
230
|
+
else {
|
|
231
|
+
// §28: read the existing child per its own pinned snapshot.
|
|
232
|
+
childDef = this.defFor(child.id);
|
|
233
|
+
}
|
|
234
|
+
// 5. Synchronize EVERY mapped child input from the SAME fresh snapshot.
|
|
235
|
+
// A freshly-seeded child already equals the snapshot, so its inputs
|
|
236
|
+
// no-op here (no spurious provide for a plain spawn). This is the exact
|
|
237
|
+
// body of `provideInput`, inlined so it shares this tx (store.tx forbids
|
|
238
|
+
// re-entrancy) — behavior identical, all-or-nothing on refusal.
|
|
239
|
+
const childArts = this.artMap(child.id);
|
|
240
|
+
const provided = [];
|
|
241
|
+
for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
|
|
242
|
+
const parentArt = parentArts.get(parentArtifactName);
|
|
243
|
+
if (parentArt?.value === undefined)
|
|
244
|
+
continue; // nothing to provide
|
|
245
|
+
const childArt = childArts.get(childInputName);
|
|
246
|
+
if (!childArt)
|
|
247
|
+
throw new Error(`no such input artifact: ${childInputName}`);
|
|
248
|
+
if (deepEqual(parentArt.value, childArt.value))
|
|
249
|
+
continue; // already current
|
|
250
|
+
const inputDef = childDef.inputs.find((i) => i.name === childInputName);
|
|
251
|
+
if (inputDef?.schema !== undefined) {
|
|
252
|
+
const check = validateValue(inputDef.schema, parentArt.value);
|
|
253
|
+
if (!check.valid)
|
|
254
|
+
throw new SchemaRefusalError(childInputName, check.issues);
|
|
255
|
+
}
|
|
256
|
+
this.store.putArtifact({
|
|
257
|
+
...childArt,
|
|
258
|
+
acceptance: 'green',
|
|
259
|
+
version: childArt.version + 1,
|
|
260
|
+
value: parentArt.value,
|
|
261
|
+
});
|
|
262
|
+
provided.push(childInputName);
|
|
85
263
|
}
|
|
86
|
-
|
|
87
|
-
|
|
264
|
+
// 6. Settle the child if we wrote anything (matches createInstanceInTx /
|
|
265
|
+
// provideInput). A fresh spawn already settled inside createInstanceInTx;
|
|
266
|
+
// re-settling is a cheap fixpoint no-op.
|
|
267
|
+
if (created || provided.length > 0)
|
|
268
|
+
this.settle(child.id, childDef, now);
|
|
269
|
+
return { childId: child.id, created, provided };
|
|
88
270
|
});
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
271
|
+
try {
|
|
272
|
+
return run();
|
|
273
|
+
}
|
|
274
|
+
catch (err) {
|
|
275
|
+
// UNIQUE-index backstop for any future concurrent writer not serialized by
|
|
276
|
+
// BEGIN IMMEDIATE: the whole failed tx rolled back, so a single retry finds
|
|
277
|
+
// the winner in-tx and syncs its inputs. Unreachable under node:sqlite's
|
|
278
|
+
// synchronous, write-lock-serialized connections, but cheap and correct.
|
|
279
|
+
if (err instanceof Error &&
|
|
280
|
+
/UNIQUE constraint failed: workflow\.produced_by_wf/.test(err.message)) {
|
|
281
|
+
return run();
|
|
282
|
+
}
|
|
283
|
+
// B2: tag a child-input schema refusal with the gate fingerprint the failed
|
|
284
|
+
// validation actually saw, so the recorder can discard it if the gate has
|
|
285
|
+
// since moved to a valid value on another connection.
|
|
286
|
+
if (err instanceof SchemaRefusalError)
|
|
287
|
+
err.gateFingerprint = seenGateFp;
|
|
288
|
+
throw err;
|
|
289
|
+
}
|
|
92
290
|
}
|
|
93
291
|
/** A human/external producer supplies (greens) an owed input. */
|
|
94
292
|
provideInput(workflow, name, value) {
|
|
@@ -104,7 +302,7 @@ export class Engine {
|
|
|
104
302
|
if (inputDef?.schema !== undefined) {
|
|
105
303
|
const check = validateValue(inputDef.schema, value);
|
|
106
304
|
if (!check.valid) {
|
|
107
|
-
throw new
|
|
305
|
+
throw new SchemaRefusalError(name, check.issues);
|
|
108
306
|
}
|
|
109
307
|
}
|
|
110
308
|
this.store.putArtifact({
|
|
@@ -153,6 +351,141 @@ export class Engine {
|
|
|
153
351
|
: { workflow, defHash: newHash };
|
|
154
352
|
}
|
|
155
353
|
// ---- Mode 2 calls: child-instance management --------------------------------
|
|
354
|
+
/**
|
|
355
|
+
* F4: the synthetic fingerprint key a `calls:` artifact uses to pin its
|
|
356
|
+
* fingerprint to the child outcome's version. A calls: step declares
|
|
357
|
+
* `consumes: []` (§ M2B), so its produce's fingerprint would otherwise never
|
|
358
|
+
* see the child outcome (which lives in another instance entirely) — this
|
|
359
|
+
* key is how that pin rides inside the same `Fingerprint` map alongside the
|
|
360
|
+
* gate stems, without colliding with any real parent artifact path (gate
|
|
361
|
+
* stems are bare names; this key is namespaced and reserved).
|
|
362
|
+
*/
|
|
363
|
+
static CHILD_OUTCOME_PIN_KEY = '__child_outcome_version__';
|
|
364
|
+
/**
|
|
365
|
+
* F4: the single place that computes "what child-outcome version is this
|
|
366
|
+
* calls: artifact currently resting on" — used both when machine-greening
|
|
367
|
+
* (STEP 6) and when stamping the pin at verdict time (reject propagation,
|
|
368
|
+
* human skip). Returns undefined if no child has ever been spawned (nothing
|
|
369
|
+
* to pin to).
|
|
370
|
+
*/
|
|
371
|
+
childOutcomePin(parentWf, callsPath) {
|
|
372
|
+
const child = this.store.findChildByParent(parentWf, callsPath);
|
|
373
|
+
if (!child)
|
|
374
|
+
return undefined;
|
|
375
|
+
const childDef = this.defFor(child.id);
|
|
376
|
+
const childOutcomeStem = childDef.outputs[0];
|
|
377
|
+
const childArts = this.artMap(child.id);
|
|
378
|
+
const childOutcomeArt = childArts.get(childOutcomeStem);
|
|
379
|
+
return childOutcomeArt?.version ?? -1;
|
|
380
|
+
}
|
|
381
|
+
/**
|
|
382
|
+
* F2: record a child input-schema refusal (from STEP 3 spawn or STEP 5
|
|
383
|
+
* re-provide) as a debt on the PARENT calls artifact — same shape as
|
|
384
|
+
* green()'s schema-reject branch (acceptance: 'rejected', schemaRejects+1,
|
|
385
|
+
* a 'validation' reasons entry naming the child input and the schema
|
|
386
|
+
* issues) — so the tick can proceed instead of throwing, and the parent
|
|
387
|
+
* calls artifact surfaces as a stallable debt (maxSchemaFailures/retry).
|
|
388
|
+
* Stamps the current gate fingerprint on the rejected artifact so the
|
|
389
|
+
* STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
|
|
390
|
+
* worth retrying" on the next tick.
|
|
391
|
+
*
|
|
392
|
+
* B2 (snapshot-consistent recording): `seenGateFp` is the gate fingerprint of
|
|
393
|
+
* the exact snapshot the failed validation saw (carried on the
|
|
394
|
+
* `SchemaRefusalError`). Inside the recording tx we recompute the CURRENT gate
|
|
395
|
+
* fingerprint and compare:
|
|
396
|
+
* - equal → the gate has not moved since the failure: stamp the rejection.
|
|
397
|
+
* - not equal → a concurrent VALID gate advance landed between the validation
|
|
398
|
+
* and here: DISCARD the now-obsolete refusal (write nothing). Stamping it
|
|
399
|
+
* would freeze the valid update as `rejected` because the STEP-2 F2 guard
|
|
400
|
+
* would then read "gate unmoved, don't retry".
|
|
401
|
+
* - `seenGateFp` undefined (defensive; the sole call site always carries one)
|
|
402
|
+
* → legacy stamp-fresh behavior.
|
|
403
|
+
* Returns true only when it actually stamped, so the caller fires the
|
|
404
|
+
* schema-rejected / settled events only on a real write (a discarded refusal
|
|
405
|
+
* is silent — abort discipline, mirroring `publishCallsGreen`).
|
|
406
|
+
*/
|
|
407
|
+
recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, seenGateFp, now) {
|
|
408
|
+
const text = `child input '${err.inputName}' failed schema: ${summarizeIssues(err.issues)}`;
|
|
409
|
+
return this.store.tx(() => {
|
|
410
|
+
const art = this.store.getArtifact(parentWf, callsStem);
|
|
411
|
+
if (!art)
|
|
412
|
+
return false; // not yet materialized by pendingOwed — nothing to stamp
|
|
413
|
+
const gateArts = this.artMap(parentWf);
|
|
414
|
+
const fp = computeFingerprint(gateArts, gateStems);
|
|
415
|
+
// B2: gate moved to a different value since the validation failed → the
|
|
416
|
+
// refusal is stale; discard it and let the concurrent valid update proceed.
|
|
417
|
+
if (seenGateFp !== undefined && !deepEqual(fp, seenGateFp))
|
|
418
|
+
return false;
|
|
419
|
+
this.store.putArtifact({
|
|
420
|
+
...art,
|
|
421
|
+
acceptance: 'rejected',
|
|
422
|
+
schemaRejects: art.schemaRejects + 1,
|
|
423
|
+
fingerprint: fp,
|
|
424
|
+
reasons: [...art.reasons, reason('schema-reject', 'validation', 'engine', text, art.version)],
|
|
425
|
+
});
|
|
426
|
+
this.settle(parentWf, def, now);
|
|
427
|
+
return true;
|
|
428
|
+
});
|
|
429
|
+
}
|
|
430
|
+
/**
|
|
431
|
+
* REL-4: the `calls:` ancestry depth of an instance — how many `producedBy`
|
|
432
|
+
* parent links separate it from the root of its composed tree. A root
|
|
433
|
+
* instance (no `producedBy`) is depth 0; a child spawned by the root is
|
|
434
|
+
* depth 1; and so on. O(depth) — walks the parent chain, which is exactly the
|
|
435
|
+
* tree the spawn bound is protecting, so it only runs on an actual spawn.
|
|
436
|
+
*/
|
|
437
|
+
callsAncestryDepth(workflow) {
|
|
438
|
+
let depth = 0;
|
|
439
|
+
let cur = this.store.getWorkflow(workflow);
|
|
440
|
+
while (cur?.producedBy) {
|
|
441
|
+
depth++;
|
|
442
|
+
cur = this.store.getWorkflow(cur.producedBy.parentWf);
|
|
443
|
+
}
|
|
444
|
+
return depth;
|
|
445
|
+
}
|
|
446
|
+
/**
|
|
447
|
+
* REL-4: record a `calls:` depth-limit refusal as a debt on the PARENT calls
|
|
448
|
+
* artifact — same clean-stop mechanism as `recordCallsSchemaReject` (mark it
|
|
449
|
+
* `rejected`, stamp the current gate fingerprint so the STEP-2 F2 guard skips
|
|
450
|
+
* re-attempts on later ticks), but the reason is a plain structural rejection,
|
|
451
|
+
* NOT a schema failure: it does not touch `schemaRejects` (that counter gates
|
|
452
|
+
* `maxSchemaFailures` and means something specific). The message is actionable
|
|
453
|
+
* — a depth-limit trip almost always means a `calls:` cycle in the def set
|
|
454
|
+
* bypassed load-time validation (a hand-wired resolver construction validation
|
|
455
|
+
* cannot see); raising `maxCallDepth` is only correct when the depth is truly
|
|
456
|
+
* intentional. Stopping here — instead of spawning — is what prevents the
|
|
457
|
+
* unbounded row creation + stack overflow REL-4 describes.
|
|
458
|
+
*
|
|
459
|
+
* B2 asymmetry (deliberate, NOT an oversight): unlike `recordCallsSchemaReject`
|
|
460
|
+
* this recorder is NOT exposed to the wrong-snapshot race, so it needs no
|
|
461
|
+
* carry-and-compare guard. A depth refusal's validity does not depend on the
|
|
462
|
+
* gate snapshot: `callsAncestryDepth` walks the immutable `producedBy` chain and
|
|
463
|
+
* `maxCallDepth` is fixed, so a refusal decided at time T stays valid at
|
|
464
|
+
* recording time regardless of concurrent gate movement — and if a moved-gate
|
|
465
|
+
* re-attempt were somehow blocked, it would deterministically re-trip the same
|
|
466
|
+
* depth refusal anyway (identical outcome, no lost valid update to strand).
|
|
467
|
+
*/
|
|
468
|
+
recordCallsDepthReject(parentWf, def, callsStem, gateStems, childDefName, now) {
|
|
469
|
+
const text = `calls depth limit reached (maxCallDepth=${this.maxCallDepth}) spawning '${childDefName}': `
|
|
470
|
+
+ `this usually means a calls: cycle in the definition set bypassed load-time validation; `
|
|
471
|
+
+ `raise maxCallDepth via Engine opts only if this depth is intentional`;
|
|
472
|
+
this.store.tx(() => {
|
|
473
|
+
const art = this.store.getArtifact(parentWf, callsStem);
|
|
474
|
+
if (!art)
|
|
475
|
+
return; // not yet materialized by pendingOwed — nothing to stamp
|
|
476
|
+
const gateArts = this.artMap(parentWf);
|
|
477
|
+
const fp = computeFingerprint(gateArts, gateStems);
|
|
478
|
+
this.store.putArtifact({
|
|
479
|
+
...art,
|
|
480
|
+
acceptance: 'rejected',
|
|
481
|
+
fingerprint: fp,
|
|
482
|
+
reasons: [...art.reasons, reason('reject', 'structural', 'engine', text, art.version)],
|
|
483
|
+
});
|
|
484
|
+
this.settle(parentWf, def, now);
|
|
485
|
+
});
|
|
486
|
+
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject' });
|
|
487
|
+
this.fireSettled(parentWf);
|
|
488
|
+
}
|
|
156
489
|
/**
|
|
157
490
|
* M2B: Maintain all `calls:` steps for a parent workflow.
|
|
158
491
|
* Called at the top of tick (outside any tx) and as cascade-up prompt.
|
|
@@ -173,27 +506,88 @@ export class Engine {
|
|
|
173
506
|
const callsPath = callsStem;
|
|
174
507
|
const gateStems = Object.values(step.callsInputs ?? {});
|
|
175
508
|
const parentArts = this.artMap(parentWf);
|
|
176
|
-
|
|
177
|
-
if (!gateReady)
|
|
509
|
+
if (!this.callsGateReady(parentArts, step))
|
|
178
510
|
continue;
|
|
179
511
|
// STEP 2 — Look up any existing child via reverse index.
|
|
180
512
|
let existingChild = this.store.findChildByParent(parentWf, callsPath);
|
|
181
|
-
//
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
513
|
+
// F2: if the parent calls artifact is already `rejected` on a schema
|
|
514
|
+
// refusal (see STEP 3/5 below) and the gate stems haven't moved since
|
|
515
|
+
// that refusal was recorded, don't re-attempt — the same value would
|
|
516
|
+
// just refuse again. The gate fingerprint on the rejected artifact is
|
|
517
|
+
// the guard; a moved gate (fingerprint mismatch) means the parent
|
|
518
|
+
// value may have been fixed, so fall through and retry.
|
|
519
|
+
const parentCallsArtPre = this.store.getArtifact(parentWf, callsStem);
|
|
520
|
+
if (!existingChild && parentCallsArtPre?.acceptance === 'rejected') {
|
|
521
|
+
const gateArtsPre = this.artMap(parentWf);
|
|
522
|
+
const currentGateFp = computeFingerprint(gateArtsPre, gateStems);
|
|
523
|
+
if (deepEqual(currentGateFp, parentCallsArtPre.fingerprint ?? {}))
|
|
524
|
+
continue;
|
|
525
|
+
}
|
|
526
|
+
// STEP 3 — SPAWN or RE-PROVISION, atomically against a FRESH snapshot.
|
|
527
|
+
//
|
|
528
|
+
// REL-4 spawn-time depth bound (the guard that prevents row bloat). Only an
|
|
529
|
+
// OPTIMISTIC pre-check, and only when no child exists yet: a self- or
|
|
530
|
+
// cross-calling def whose cycle slipped past load-time validation would
|
|
531
|
+
// otherwise mint a fresh child instance (a new DB row) at every recursion
|
|
532
|
+
// level until the process stack overflows. `callsAncestryDepth` walks the
|
|
533
|
+
// `producedBy` chain, which is immutable after insert, so it cannot race and
|
|
534
|
+
// needs no in-tx recheck. Record a rejection on the parent calls artifact
|
|
535
|
+
// (clean stop; the STEP-2 F2 fingerprint guard then skips re-attempts).
|
|
536
|
+
if (!existingChild && this.callsAncestryDepth(parentWf) >= this.maxCallDepth) {
|
|
537
|
+
this.recordCallsDepthReject(parentWf, def, callsStem, gateStems, step.calls, now);
|
|
538
|
+
continue;
|
|
539
|
+
}
|
|
540
|
+
// The find-or-create AND every mapped input sync happen in ONE
|
|
541
|
+
// BEGIN IMMEDIATE inside the helper, from a parent snapshot RE-READ in that
|
|
542
|
+
// tx — so a child is never CREATED or WRITTEN from a snapshot older than its
|
|
543
|
+
// committing transaction (closes the SPAWN and RE-PROVISION races). The
|
|
544
|
+
// pre-reads above (gate readiness, findChildByParent, F2 fingerprint, depth)
|
|
545
|
+
// are optimistic — they decide only whether to attempt; the helper
|
|
546
|
+
// re-verifies in-tx and aborts (returns null) if the gate re-armed or an F2
|
|
547
|
+
// debt landed since. F2: a child input-schema refusal (seed or re-provide)
|
|
548
|
+
// is not a bug — a parent value legal per the parent's own schema can be
|
|
549
|
+
// illegal per the child's — so it rolls the whole provision tx back and
|
|
550
|
+
// becomes a debt on the PARENT calls artifact (mirroring green()'s
|
|
551
|
+
// schema-reject branch) instead of crash-looping every subsequent tick.
|
|
552
|
+
let provision;
|
|
553
|
+
try {
|
|
554
|
+
provision = this.provisionCallsChild(parentWf, step, callsStem, gateStems, now);
|
|
555
|
+
}
|
|
556
|
+
catch (err) {
|
|
557
|
+
if (err instanceof SchemaRefusalError) {
|
|
558
|
+
// B2: pass the fingerprint the failed validation saw. If the gate has
|
|
559
|
+
// since moved (a concurrent valid update), the recorder discards the
|
|
560
|
+
// refusal and returns false — fire no schema-rejected event, and let
|
|
561
|
+
// the next pass provision against the now-valid gate.
|
|
562
|
+
if (this.recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, err.gateFingerprint, now)) {
|
|
563
|
+
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject', outcome: 'schema-rejected' });
|
|
564
|
+
this.fireSettled(parentWf);
|
|
565
|
+
}
|
|
566
|
+
continue;
|
|
189
567
|
}
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
568
|
+
throw err;
|
|
569
|
+
}
|
|
570
|
+
if (!provision)
|
|
571
|
+
continue; // silent abort (gate re-armed / F2 debt landed) — next tick retries.
|
|
572
|
+
// Post-commit events, matching the pre-C2 per-action semantics exactly:
|
|
573
|
+
// only the creating connection fires `instance`; each re-provided input
|
|
574
|
+
// fires a commit/provide as provideInput did; a settled + one cascade run
|
|
575
|
+
// (idempotent maintenance — once per provision, not once per input) so a
|
|
576
|
+
// grandchild gets re-provided in the same pass.
|
|
577
|
+
if (provision.created) {
|
|
578
|
+
this.fire({ type: 'instance', workflow: provision.childId, def: step.calls });
|
|
579
|
+
this.fireSettled(provision.childId);
|
|
195
580
|
}
|
|
196
|
-
|
|
581
|
+
for (const name of provision.provided) {
|
|
582
|
+
this.fire({ type: 'commit', workflow: provision.childId, path: name, action: 'provide' });
|
|
583
|
+
}
|
|
584
|
+
if (provision.provided.length > 0) {
|
|
585
|
+
this.fireSettled(provision.childId);
|
|
586
|
+
// provideInput's cascade-up, outside the tx (store.tx forbids re-entrancy);
|
|
587
|
+
// the _inMaintainCalls guard keys on parentWf, so this nested call is safe.
|
|
588
|
+
this.maintainCalls(provision.childId, this.defFor(provision.childId), now);
|
|
589
|
+
}
|
|
590
|
+
existingChild = this.store.getWorkflow(provision.childId);
|
|
197
591
|
if (!existingChild)
|
|
198
592
|
continue; // defensive: createInstance returned but getWorkflow failed
|
|
199
593
|
// STEP 4 — Read child's declared outcome artifact.
|
|
@@ -203,41 +597,50 @@ export class Engine {
|
|
|
203
597
|
const childOutcomeStem = childDef.outputs[0]; // validated by Phase-2 check
|
|
204
598
|
let childArts = this.artMap(existingChild.id);
|
|
205
599
|
let childOutcomeArt = childArts.get(childOutcomeStem);
|
|
206
|
-
// STEP 5 — RE-PROVIDE if parent gate source moved (M2B-REPROVIDE).
|
|
207
|
-
for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
|
|
208
|
-
const parentArtNow = parentArts.get(parentArtifactName);
|
|
209
|
-
const childInputArt = childArts.get(childInputName);
|
|
210
|
-
if (parentArtNow?.value !== undefined && !deepEqual(parentArtNow.value, childInputArt?.value)) {
|
|
211
|
-
this.provideInput(existingChild.id, childInputName, parentArtNow.value);
|
|
212
|
-
}
|
|
213
|
-
}
|
|
214
600
|
// STEP 6 — MACHINE-GREEN or STAY OWED (M2B-CASCADEUP).
|
|
601
|
+
//
|
|
602
|
+
// The reads below are an OPTIMISTIC gate ONLY: they decide whether to
|
|
603
|
+
// *attempt* a publish or a re-arm — never what to publish. The write,
|
|
604
|
+
// and a re-read+re-verify of every input it depends on, happen together
|
|
605
|
+
// inside one BEGIN IMMEDIATE in the helper (publishCallsGreen /
|
|
606
|
+
// rearmCallsGreen). Under WAL + BEGIN IMMEDIATE no other connection can
|
|
607
|
+
// commit between that in-tx re-read and the write, so a cross-connection
|
|
608
|
+
// interleave — the parent gate advanced to a newer version, or the child
|
|
609
|
+
// outcome re-armed, between this stale pre-read and the write — is caught
|
|
610
|
+
// in-tx and the pass aborts (helper returns false, nothing written),
|
|
611
|
+
// deferring to the next tick. The published value, the gate fingerprint
|
|
612
|
+
// it claims, and the child-outcome pin therefore always come from ONE
|
|
613
|
+
// atomic snapshot. commit/settled events fire only when the helper wrote,
|
|
614
|
+
// so an aborted pass is silent to listeners.
|
|
615
|
+
//
|
|
215
616
|
// Re-read after potential re-provide.
|
|
216
617
|
childArts = this.artMap(existingChild.id);
|
|
217
618
|
childOutcomeArt = childArts.get(childOutcomeStem);
|
|
218
619
|
const parentCallsArt = this.store.getArtifact(parentWf, callsStem);
|
|
620
|
+
// F2: don't machine-green over a schema-rejected debt — it needs a
|
|
621
|
+
// human `retry` (or a moved gate, handled by the guard above) before
|
|
622
|
+
// this step revisits it.
|
|
623
|
+
if (parentCallsArt?.acceptance === 'rejected')
|
|
624
|
+
continue;
|
|
219
625
|
if (isGreen(childOutcomeArt) && childOutcomeArt?.value !== undefined) {
|
|
220
626
|
const alreadyGreen = isGreen(parentCallsArt);
|
|
221
627
|
const sameValue = alreadyGreen && deepEqual(childOutcomeArt.value, parentCallsArt?.value);
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
this.
|
|
237
|
-
|
|
238
|
-
});
|
|
239
|
-
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'provide' });
|
|
240
|
-
this.fireSettled(parentWf);
|
|
628
|
+
// F4: version-pinning. Only machine-green when the child outcome's
|
|
629
|
+
// version has moved past whatever version is currently pinned on
|
|
630
|
+
// the parent artifact — this is what lets a consumer's reject
|
|
631
|
+
// (propagated down, parent reopened to owed pinned to the rejected
|
|
632
|
+
// child version) or a human skip (pinned at skip time) stand until
|
|
633
|
+
// the child actually rebuilds past that pin, instead of being
|
|
634
|
+
// silently overridden on the very next tick. (Re-checked in-tx by
|
|
635
|
+
// the helper against the snapshot it commits under.)
|
|
636
|
+
const pinnedVersion = parentCallsArt?.fingerprint?.[Engine.CHILD_OUTCOME_PIN_KEY];
|
|
637
|
+
const pastPin = pinnedVersion === undefined || childOutcomeArt.version > pinnedVersion;
|
|
638
|
+
if ((!alreadyGreen || !sameValue) && pastPin && parentCallsArt) {
|
|
639
|
+
// parentCallsArt truthy: not-yet-materialized (pendingOwed) → skip.
|
|
640
|
+
if (this.publishCallsGreen(parentWf, def, step, callsStem, gateStems, existingChild.id, childOutcomeStem, now)) {
|
|
641
|
+
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'provide' });
|
|
642
|
+
this.fireSettled(parentWf);
|
|
643
|
+
}
|
|
241
644
|
}
|
|
242
645
|
}
|
|
243
646
|
else if (!isGreen(childOutcomeArt) && isGreen(parentCallsArt) && parentCallsArt) {
|
|
@@ -245,26 +648,10 @@ export class Engine {
|
|
|
245
648
|
// but the parent calls: artifact is still green. Re-arm it to owed so downstream
|
|
246
649
|
// re-runs when the child completes again. This handles gate re-arm (test f):
|
|
247
650
|
// the cascade can't detect this because deliver step has consumes: [].
|
|
248
|
-
this.
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
this.store.putArtifact({
|
|
253
|
-
...artNow,
|
|
254
|
-
acceptance: 'owed',
|
|
255
|
-
reasons: [...artNow.reasons, {
|
|
256
|
-
at: nowMs(),
|
|
257
|
-
action: 'reopen',
|
|
258
|
-
kind: 'structural',
|
|
259
|
-
by: 'engine',
|
|
260
|
-
text: 'gate input moved: child re-running',
|
|
261
|
-
fromVersion: artNow.version,
|
|
262
|
-
}],
|
|
263
|
-
});
|
|
264
|
-
this.settle(parentWf, def, now);
|
|
265
|
-
});
|
|
266
|
-
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'retry' });
|
|
267
|
-
this.fireSettled(parentWf);
|
|
651
|
+
if (this.rearmCallsGreen(parentWf, def, callsStem, existingChild.id, childOutcomeStem, now)) {
|
|
652
|
+
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'retry' });
|
|
653
|
+
this.fireSettled(parentWf);
|
|
654
|
+
}
|
|
268
655
|
}
|
|
269
656
|
}
|
|
270
657
|
}
|
|
@@ -272,6 +659,120 @@ export class Engine {
|
|
|
272
659
|
this._inMaintainCalls.delete(parentWf);
|
|
273
660
|
}
|
|
274
661
|
}
|
|
662
|
+
/**
|
|
663
|
+
* The seed/consistency invariant for a `calls:` step: every child input wired
|
|
664
|
+
* from a parent gate artifact whose value is defined must currently deepEqual
|
|
665
|
+
* that gate value. STEP 6's in-tx verify calls this; STEP 5's re-provide
|
|
666
|
+
* condition applies the same per-input invariant inline (mirrored, not a call
|
|
667
|
+
* here) — the two encode the same rule and must be kept in step by hand. Both
|
|
668
|
+
* skip when the parent gate value is undefined (nothing to provide). A mismatch
|
|
669
|
+
* means a re-provide is pending against the very gate a fresh fingerprint would
|
|
670
|
+
* claim, so publishing now would stamp a stale child value under a newer gate.
|
|
671
|
+
*/
|
|
672
|
+
childConsistentWithGate(parentArts, childArts, step) {
|
|
673
|
+
for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
|
|
674
|
+
const parentArt = parentArts.get(parentArtifactName);
|
|
675
|
+
if (parentArt?.value === undefined)
|
|
676
|
+
continue;
|
|
677
|
+
const childInputArt = childArts.get(childInputName);
|
|
678
|
+
if (!deepEqual(parentArt.value, childInputArt?.value))
|
|
679
|
+
return false;
|
|
680
|
+
}
|
|
681
|
+
return true;
|
|
682
|
+
}
|
|
683
|
+
/**
|
|
684
|
+
* STEP 6 machine-green as an atomic snapshot-and-commit. maintainCalls'
|
|
685
|
+
* optimistic pre-reads decide only WHETHER to call this; the decision inputs
|
|
686
|
+
* are all re-read and re-verified here INSIDE the same BEGIN IMMEDIATE that
|
|
687
|
+
* performs the write, so the published value, the gate fingerprint it claims,
|
|
688
|
+
* and the child-outcome pin come from ONE snapshot. Any verify failing aborts
|
|
689
|
+
* the publish (returns false; the commit is a no-op — do NOT throw, there is
|
|
690
|
+
* nothing to roll back, and an abort must not record debt/reasons/fingerprint:
|
|
691
|
+
* the state is simply "not yet" and the next tick redoes the pass against
|
|
692
|
+
* fresh state). Returns true only when it actually wrote, so the caller fires
|
|
693
|
+
* commit/settled events only on a real publish.
|
|
694
|
+
*/
|
|
695
|
+
publishCallsGreen(parentWf, def, step, callsStem, gateStems, expectedChildId, childOutcomeStem, now) {
|
|
696
|
+
return this.store.tx(() => {
|
|
697
|
+
const parentArts = this.artMap(parentWf);
|
|
698
|
+
const parentCallsArt = this.store.getArtifact(parentWf, callsStem);
|
|
699
|
+
// Vanished, or an F2 schema-reject debt landed since the pre-read → abort.
|
|
700
|
+
if (!parentCallsArt || parentCallsArt.acceptance === 'rejected')
|
|
701
|
+
return false;
|
|
702
|
+
// Same child the optimistic read saw; a different id means the tree moved.
|
|
703
|
+
const child = this.store.findChildByParent(parentWf, callsStem);
|
|
704
|
+
if (!child || child.id !== expectedChildId)
|
|
705
|
+
return false;
|
|
706
|
+
const childArts = this.artMap(child.id);
|
|
707
|
+
const childOutcomeArt = childArts.get(childOutcomeStem);
|
|
708
|
+
// Child re-armed between the pre-read and here → defer.
|
|
709
|
+
if (!childOutcomeArt || !isGreen(childOutcomeArt) || childOutcomeArt.value === undefined)
|
|
710
|
+
return false;
|
|
711
|
+
// Gate still ready, and the child still consistent with the gate values
|
|
712
|
+
// the fingerprint is about to claim (the heart of the fix).
|
|
713
|
+
if (!this.callsGateReady(parentArts, step))
|
|
714
|
+
return false;
|
|
715
|
+
if (!this.childConsistentWithGate(parentArts, childArts, step))
|
|
716
|
+
return false;
|
|
717
|
+
// Idempotent no-op: another connection already published this exact value.
|
|
718
|
+
const alreadyGreen = isGreen(parentCallsArt);
|
|
719
|
+
if (alreadyGreen && deepEqual(childOutcomeArt.value, parentCallsArt.value))
|
|
720
|
+
return false;
|
|
721
|
+
// F4 version pin, recomputed from the in-tx child outcome version.
|
|
722
|
+
const pinnedVersion = parentCallsArt.fingerprint?.[Engine.CHILD_OUTCOME_PIN_KEY];
|
|
723
|
+
if (pinnedVersion !== undefined && childOutcomeArt.version <= pinnedVersion)
|
|
724
|
+
return false;
|
|
725
|
+
const fp = computeFingerprint(parentArts, gateStems);
|
|
726
|
+
fp[Engine.CHILD_OUTCOME_PIN_KEY] = childOutcomeArt.version;
|
|
727
|
+
// Do NOT set terminal: calls: artifact must be re-armable if gate inputs move.
|
|
728
|
+
this.store.putArtifact({
|
|
729
|
+
...parentCallsArt,
|
|
730
|
+
acceptance: 'green',
|
|
731
|
+
version: parentCallsArt.version + 1,
|
|
732
|
+
value: childOutcomeArt.value,
|
|
733
|
+
fingerprint: fp,
|
|
734
|
+
}, { action: 'provided', actor: 'engine', reason: 'child outcome provided' });
|
|
735
|
+
this.settle(parentWf, def, now);
|
|
736
|
+
return true;
|
|
737
|
+
});
|
|
738
|
+
}
|
|
739
|
+
/**
|
|
740
|
+
* STEP 6 re-arm as the mirror-image atomic guard. maintainCalls' optimistic
|
|
741
|
+
* pre-read decides only WHETHER to call this; the parent artifact AND the
|
|
742
|
+
* child outcome are re-read inside the write lock, and the re-arm happens only
|
|
743
|
+
* if the parent is still green AND the child outcome is still NOT green in-tx.
|
|
744
|
+
* If the child went green between the optimistic read and the tx, this does
|
|
745
|
+
* nothing (returns false) and the next maintainCalls pass publishes normally.
|
|
746
|
+
* Returns true only when it wrote.
|
|
747
|
+
*/
|
|
748
|
+
rearmCallsGreen(parentWf, def, callsStem, expectedChildId, childOutcomeStem, now) {
|
|
749
|
+
return this.store.tx(() => {
|
|
750
|
+
const artNow = this.store.getArtifact(parentWf, callsStem);
|
|
751
|
+
if (!artNow || !isGreen(artNow))
|
|
752
|
+
return false; // already re-armed or gone
|
|
753
|
+
const child = this.store.findChildByParent(parentWf, callsStem);
|
|
754
|
+
if (!child || child.id !== expectedChildId)
|
|
755
|
+
return false;
|
|
756
|
+
const childOutcomeArt = this.artMap(child.id).get(childOutcomeStem);
|
|
757
|
+
// Child went green in-tx → don't re-arm; let the green branch publish next pass.
|
|
758
|
+
if (isGreen(childOutcomeArt))
|
|
759
|
+
return false;
|
|
760
|
+
this.store.putArtifact({
|
|
761
|
+
...artNow,
|
|
762
|
+
acceptance: 'owed',
|
|
763
|
+
reasons: [...artNow.reasons, {
|
|
764
|
+
at: nowMs(),
|
|
765
|
+
action: 'reopen',
|
|
766
|
+
kind: 'structural',
|
|
767
|
+
by: 'engine',
|
|
768
|
+
text: 'gate input moved: child re-running',
|
|
769
|
+
fromVersion: artNow.version,
|
|
770
|
+
}],
|
|
771
|
+
});
|
|
772
|
+
this.settle(parentWf, def, now);
|
|
773
|
+
return true;
|
|
774
|
+
});
|
|
775
|
+
}
|
|
275
776
|
/**
|
|
276
777
|
* M2B cascade-up prompt: if `workflow` has a producedBy link, trigger
|
|
277
778
|
* maintainCalls on its parent so the parent reflects the child's progress promptly.
|
|
@@ -294,19 +795,105 @@ export class Engine {
|
|
|
294
795
|
this.fireSettled(parentWf);
|
|
295
796
|
}
|
|
296
797
|
// ---- the tick (maintain → reap → eligible → cadence/budget → claim) --------
|
|
798
|
+
/**
|
|
799
|
+
* Pull eligible orders for `workflow`. §23.6.8: **deep by default** — after
|
|
800
|
+
* maintaining and ticking this instance, descend into every live `calls:`
|
|
801
|
+
* child (recursively, grandchildren too) and fold their orders / reaps /
|
|
802
|
+
* deferrals / `dueAt` into the returned result so a driver that ticks only
|
|
803
|
+
* the root drives the whole composed tree (a shallow tick would deadlock a
|
|
804
|
+
* `calls:` workflow — the child's eligible steps would never be claimed).
|
|
805
|
+
* Pass `{ deep: false }` (CLI `--shallow`) to restore the pre-deep behavior:
|
|
806
|
+
* only this instance's own orders. See `TickResult` for the fold semantics.
|
|
807
|
+
*/
|
|
297
808
|
tick(workflow, opts = {}) {
|
|
809
|
+
return this.tickInternal(workflow, opts.now ?? nowMs(), opts.deep ?? true, opts.labels ?? [], new Set(), 0);
|
|
810
|
+
}
|
|
811
|
+
/**
|
|
812
|
+
* The recursive tick worker. Runs this instance's own maintain → reap →
|
|
813
|
+
* eligible → claim cycle (its body is byte-for-byte the pre-deep `tick`,
|
|
814
|
+
* kept inside its own `store.tx`), then — when `deep` — descends into each
|
|
815
|
+
* live `calls:` child by calling itself again. The descent MUST run OUTSIDE
|
|
816
|
+
* this frame's `store.tx`: `store.tx` forbids re-entrancy, and every child
|
|
817
|
+
* frame opens its own tx (via its own `maintainCalls` + tick body), so a
|
|
818
|
+
* child is driven by a full nested `tickInternal`, never a child tx opened
|
|
819
|
+
* inside the parent's.
|
|
820
|
+
*
|
|
821
|
+
* REL-4: `visited` (a set of workflow INSTANCE ids) is NOT a sufficient guard
|
|
822
|
+
* against a `calls:` cycle. Each descent level's `maintainCalls` SPAWNS a
|
|
823
|
+
* brand-new child instance, so a self-calling def produces a fresh id at every
|
|
824
|
+
* level — `visited` never trips, and recursion would run unbounded (one DB row
|
|
825
|
+
* per level) until the stack overflows. The real guard is the `maxCallDepth`
|
|
826
|
+
* bound: `maintainCalls` refuses to spawn past it (so a newly-created tree can
|
|
827
|
+
* never get here too deep), and the `depth` check below is the belt-and-braces
|
|
828
|
+
* backstop for a PRE-EXISTING deep tree (e.g. a DB written by an older build
|
|
829
|
+
* before the spawn bound existed) — it throws rather than overflow the stack.
|
|
830
|
+
* `visited` still earns its keep as a re-entrancy guard for a genuinely
|
|
831
|
+
* re-encountered instance within one tick.
|
|
832
|
+
*
|
|
833
|
+
* B1 (in-tx descent claim guard): a deep parent descends into a child by
|
|
834
|
+
* calling this again with `parentEdge` — the calls: edge the child hangs
|
|
835
|
+
* from. Inside the child frame's OWN claim tx, before any child order is
|
|
836
|
+
* issued, we re-verify that the parent gate and the child's synchronized
|
|
837
|
+
* inputs are still mutually consistent with the CURRENTLY-committed parent
|
|
838
|
+
* state (the same predicate `publishCallsGreen` uses on the publish side).
|
|
839
|
+
* `provisionCallsChild` commits child input v1; another connection can advance
|
|
840
|
+
* the parent to v2 before this non-transactional descent claims — without the
|
|
841
|
+
* guard the child claims work against the stale v1. On mismatch the frame
|
|
842
|
+
* issues nothing and its subtree is not descended; the next parent tick
|
|
843
|
+
* re-synchronizes via `maintainCalls`. Absent `parentEdge` = the root frame,
|
|
844
|
+
* unguarded (nothing above it to be inconsistent with). Each frame checks only
|
|
845
|
+
* its IMMEDIATE parent edge; a grandchild gets its own edge from the child
|
|
846
|
+
* frame's descent loop, so every issued order in the tree is guarded by the
|
|
847
|
+
* edge it hangs from. The guard is silent (no debt/reasons/events), mirroring
|
|
848
|
+
* the abort discipline of `publishCallsGreen`/`provisionCallsChild`.
|
|
849
|
+
*/
|
|
850
|
+
tickInternal(workflow, now, deep, labels, visited, depth, parentEdge) {
|
|
851
|
+
if (depth > this.maxCallDepth) {
|
|
852
|
+
throw new Error(`calls depth limit exceeded (maxCallDepth=${this.maxCallDepth}) ticking '${workflow}': `
|
|
853
|
+
+ `a calls: composition is deeper than the bound, which usually means a calls: cycle `
|
|
854
|
+
+ `in the definition set; raise maxCallDepth via Engine opts only if this depth is intentional`);
|
|
855
|
+
}
|
|
856
|
+
if (visited.has(workflow))
|
|
857
|
+
return { workflow, orders: [], reaped: 0, deferred: [] };
|
|
858
|
+
visited.add(workflow);
|
|
298
859
|
const def = this.defFor(workflow);
|
|
299
|
-
const now = opts.now ?? nowMs();
|
|
300
860
|
// M2B: maintain calls: child instances before the normal tick/reap/claim cycle.
|
|
301
861
|
this.maintainCalls(workflow, def, now);
|
|
302
|
-
|
|
862
|
+
// B1: set inside the frame tx when the parent↔child consistency guard fires;
|
|
863
|
+
// read after the tx to suppress this subtree's descent too.
|
|
864
|
+
let staleEdge = false;
|
|
865
|
+
const result = this.store.tx(() => {
|
|
303
866
|
this.settle(workflow, def, now);
|
|
304
867
|
const reaped = this.reap(workflow, now, def);
|
|
305
868
|
const arts = this.artMap(workflow);
|
|
869
|
+
// B1: in-tx descent claim guard. `arts` is THIS (child) frame's snapshot,
|
|
870
|
+
// already read inside the write lock. Re-verify the immediate parent edge
|
|
871
|
+
// against ONE fresh in-tx parent snapshot (`artMap`/`listArtifacts`, NOT a
|
|
872
|
+
// separate `store.getArtifact` for the calls key — E2 busy_timeout GOTCHA)
|
|
873
|
+
// before claiming any order. Reuses the exact descend condition (Fix B3's
|
|
874
|
+
// owed-only) and `publishCallsGreen`'s gate-ready + child-consistency
|
|
875
|
+
// predicates, so claim-side and publish-side never drift. On mismatch the
|
|
876
|
+
// parent advanced since provision: settle/reap already ran and stay (both
|
|
877
|
+
// child-local and useful), but this frame issues no firings/claims and its
|
|
878
|
+
// subtree is skipped below. Next parent tick re-synchronizes.
|
|
879
|
+
if (parentEdge) {
|
|
880
|
+
const pArts = this.artMap(parentEdge.parentWf);
|
|
881
|
+
const callsArt = pArts.get(parentEdge.callsStem);
|
|
882
|
+
if (callsArt?.acceptance !== 'owed'
|
|
883
|
+
|| !this.callsGateReady(pArts, parentEdge.step)
|
|
884
|
+
|| !this.childConsistentWithGate(pArts, arts, parentEdge.step)) {
|
|
885
|
+
staleEdge = true;
|
|
886
|
+
const dueAt = this.computeDueAt(def, workflow, now);
|
|
887
|
+
const r = { workflow, orders: [], reaped, deferred: [] };
|
|
888
|
+
if (dueAt !== null)
|
|
889
|
+
r.dueAt = dueAt;
|
|
890
|
+
return r;
|
|
891
|
+
}
|
|
892
|
+
}
|
|
306
893
|
// Compute time facts for idle eligibility (clock-read boundary).
|
|
307
894
|
const timeFacts = this.computeTimeFacts(def, workflow, arts, now);
|
|
308
895
|
const firings = eligibleFirings(def, arts, timeFacts);
|
|
309
|
-
const { selected, deferred } = this.applySchedule(workflow, def, firings, now);
|
|
896
|
+
const { selected, deferred } = this.applySchedule(workflow, def, firings, now, labels);
|
|
310
897
|
// Clear alarm_at for any idle firing that was selected (consume the alarm).
|
|
311
898
|
for (const f of selected) {
|
|
312
899
|
if (f.cause === 'idle') {
|
|
@@ -316,27 +903,111 @@ export class Engine {
|
|
|
316
903
|
const orders = [];
|
|
317
904
|
const allDeferred = [...deferred];
|
|
318
905
|
for (const f of selected) {
|
|
319
|
-
const
|
|
320
|
-
if (
|
|
906
|
+
const claimed = this.claim(workflow, def, f, arts, now);
|
|
907
|
+
if (claimed === 'in-flight') {
|
|
321
908
|
const d = { step: f.step, key: f.key, inputs: f.inputs, outputs: f.outputs, reason: 'in-flight' };
|
|
322
909
|
if (f.index !== undefined)
|
|
323
910
|
d.index = f.index;
|
|
324
911
|
allDeferred.push(d);
|
|
325
912
|
}
|
|
326
|
-
else if (
|
|
327
|
-
orders.push(
|
|
913
|
+
else if (claimed) {
|
|
914
|
+
orders.push(claimed);
|
|
328
915
|
}
|
|
329
916
|
}
|
|
330
917
|
// E-DUE: compute earliest pending time-trigger for the result.
|
|
331
918
|
const dueAt = this.computeDueAt(def, workflow, now);
|
|
332
|
-
const
|
|
919
|
+
const r = { workflow, orders, reaped, deferred: allDeferred };
|
|
333
920
|
if (dueAt !== null)
|
|
334
|
-
|
|
335
|
-
return
|
|
921
|
+
r.dueAt = dueAt;
|
|
922
|
+
return r;
|
|
336
923
|
});
|
|
924
|
+
// §23.6.8 DESCENT — outside this frame's tx (see method doc). Drive each
|
|
925
|
+
// live calls: child with its own full tickInternal and fold its result up.
|
|
926
|
+
// B1: when this frame's own inputs are disputed (guard fired), skip the whole
|
|
927
|
+
// subtree — do not tick grandchildren off a frame that issued nothing.
|
|
928
|
+
if (deep && !staleEdge) {
|
|
929
|
+
for (const { step, child } of this.callsDescendTargets(workflow, def)) {
|
|
930
|
+
const cr = this.tickInternal(child.id, now, deep, labels, visited, depth + 1, {
|
|
931
|
+
parentWf: workflow,
|
|
932
|
+
step,
|
|
933
|
+
callsStem: step.produces[0].stem,
|
|
934
|
+
});
|
|
935
|
+
// orders: flatten; each Order already carries its own `workflow`.
|
|
936
|
+
result.orders.push(...cr.orders);
|
|
937
|
+
// deferred: stamp child-originated entries with the child id, preserving
|
|
938
|
+
// a grandchild's already-stamped id (absent = ticked root, see type doc).
|
|
939
|
+
for (const d of cr.deferred) {
|
|
940
|
+
result.deferred.push({ ...d, workflow: d.workflow ?? cr.workflow });
|
|
941
|
+
}
|
|
942
|
+
// reaped: sum across the tree (also reaps dead child leases that would
|
|
943
|
+
// otherwise sit until someone ticked the child directly).
|
|
944
|
+
result.reaped += cr.reaped;
|
|
945
|
+
// dueAt: min across the tree; stays absent when neither side has one.
|
|
946
|
+
if (cr.dueAt !== undefined) {
|
|
947
|
+
result.dueAt = result.dueAt === undefined ? cr.dueAt : Math.min(result.dueAt, cr.dueAt);
|
|
948
|
+
}
|
|
949
|
+
}
|
|
950
|
+
}
|
|
951
|
+
return result;
|
|
952
|
+
}
|
|
953
|
+
/**
|
|
954
|
+
* §23.6.8: is a `calls:` step's gate ready — i.e. every parent artifact wired
|
|
955
|
+
* into `callsInputs` is green? Shared by `maintainCalls` STEP 1 and
|
|
956
|
+
* `callsDescendTargets` so the descend condition can never drift from the
|
|
957
|
+
* spawn/re-provide condition. Empty gate (`callsInputs: {}`) is always ready.
|
|
958
|
+
*/
|
|
959
|
+
callsGateReady(parentArts, step) {
|
|
960
|
+
const gateStems = Object.values(step.callsInputs ?? {});
|
|
961
|
+
return gateStems.length === 0 || gateStems.every((s) => isGreen(parentArts.get(s)));
|
|
962
|
+
}
|
|
963
|
+
/**
|
|
964
|
+
* §23.6.8: the live `calls:` children a deep tick should descend into, one
|
|
965
|
+
* per calls: step whose (1) gate is green, (2) child instance exists, and
|
|
966
|
+
* (3) the parent calls artifact is specifically `owed`. Read AFTER
|
|
967
|
+
* `maintainCalls` has run this frame, so a just-spawned child is visible and
|
|
968
|
+
* a just-machine-greened debt is correctly skipped. Consequences that fall
|
|
969
|
+
* out for free: gate re-armed after spawn → not ready → no descend
|
|
970
|
+
* (consistent with maintainCalls bailing at STEP 1, never driving work on
|
|
971
|
+
* disputed inputs); debt already paid → skip.
|
|
972
|
+
*
|
|
973
|
+
* B3: condition (3) descends ONLY on `owed`, never on any non-green state.
|
|
974
|
+
* `owed` is the sole live producer debt: it covers the fresh spawn, the F4
|
|
975
|
+
* propagated-reject reopen (parent reopened to owed pinned at the rejected
|
|
976
|
+
* child version), and `rearmCallsGreen`'s reopen — all of which legitimately
|
|
977
|
+
* want child work driven. `green` is paid; `rejected` (F2 schema / REL-4 depth
|
|
978
|
+
* refusal) needs a human `retry` or a moved gate handled by `maintainCalls`,
|
|
979
|
+
* never child work; `skipped` is a human-declared dead branch; `retracted` is
|
|
980
|
+
* terminal; `submitted` is not a producer debt (a calls artifact is machine
|
|
981
|
+
* -greened and should never be `submitted`) — none of these represent live
|
|
982
|
+
* child work, so descending into them issued orders for dead/refused branches.
|
|
983
|
+
*/
|
|
984
|
+
callsDescendTargets(parentWf, def) {
|
|
985
|
+
const arts = this.artMap(parentWf);
|
|
986
|
+
const out = [];
|
|
987
|
+
for (const step of def.steps) {
|
|
988
|
+
if (!step.calls)
|
|
989
|
+
continue;
|
|
990
|
+
const stem = step.produces[0].stem;
|
|
991
|
+
if (!this.callsGateReady(arts, step))
|
|
992
|
+
continue; // 1. gate green
|
|
993
|
+
const child = this.store.findChildByParent(parentWf, stem);
|
|
994
|
+
if (!child)
|
|
995
|
+
continue; // 2. child exists
|
|
996
|
+
if (arts.get(stem)?.acceptance !== 'owed')
|
|
997
|
+
continue; // 3. descend only on an owed debt
|
|
998
|
+
out.push({ step, child });
|
|
999
|
+
}
|
|
1000
|
+
return out;
|
|
337
1001
|
}
|
|
338
|
-
/**
|
|
339
|
-
|
|
1002
|
+
/**
|
|
1003
|
+
* Per-step cadence + daily budget + parallel cap over the eligible firings.
|
|
1004
|
+
* A2: `labels` is the tick caller's optional claim filter — when non-empty, a
|
|
1005
|
+
* step whose own `labels` are also non-empty is only schedulable when the two
|
|
1006
|
+
* intersect; a disjoint step's firings are deferred as `'label-mismatch'`.
|
|
1007
|
+
* Filtering here (before cadence/budget) means a mismatched firing never
|
|
1008
|
+
* consumes the caller's slots and never perturbs cadence math.
|
|
1009
|
+
*/
|
|
1010
|
+
applySchedule(workflow, def, firings, now, labels) {
|
|
340
1011
|
const midnight = localMidnightMs(now);
|
|
341
1012
|
const selected = [];
|
|
342
1013
|
const deferred = [];
|
|
@@ -350,6 +1021,15 @@ export class Engine {
|
|
|
350
1021
|
const stepFirings = firings.filter((f) => f.step === step.name);
|
|
351
1022
|
if (stepFirings.length === 0)
|
|
352
1023
|
continue;
|
|
1024
|
+
// A2: caller label filter vs. step labels. Both non-empty and disjoint →
|
|
1025
|
+
// this caller must not claim the step; defer every firing and skip it
|
|
1026
|
+
// before it touches cadence/budget/slot math.
|
|
1027
|
+
if (labels.length > 0 && step.labels && step.labels.length > 0 &&
|
|
1028
|
+
!step.labels.some((l) => labels.includes(l))) {
|
|
1029
|
+
for (const f of stepFirings)
|
|
1030
|
+
defer(f, 'label-mismatch');
|
|
1031
|
+
continue;
|
|
1032
|
+
}
|
|
353
1033
|
const latest = this.store.latestRun(workflow, step.name);
|
|
354
1034
|
if (latest && now - latest.createdAt < step.cadenceSecs * 1000) {
|
|
355
1035
|
for (const f of stepFirings)
|
|
@@ -374,15 +1054,53 @@ export class Engine {
|
|
|
374
1054
|
return step?.reapTtlMs ?? this.reapTtlMs;
|
|
375
1055
|
}
|
|
376
1056
|
/**
|
|
377
|
-
*
|
|
378
|
-
*
|
|
379
|
-
*
|
|
1057
|
+
* A3 (REL-8): return the effective max total lease lifetime for a step, or
|
|
1058
|
+
* `undefined` when no cap is configured. Per-step `maxLease` overrides the
|
|
1059
|
+
* engine option; when both are unset there is no cap (heartbeats extend the
|
|
1060
|
+
* lease indefinitely). Uses `??` (not `||`) so an explicit `0` stays a cap.
|
|
380
1061
|
*/
|
|
381
|
-
|
|
1062
|
+
effectiveMaxLease(step) {
|
|
1063
|
+
return step?.maxLeaseMs ?? this.maxLeaseMs;
|
|
1064
|
+
}
|
|
1065
|
+
/**
|
|
1066
|
+
* Classify a claimed task's liveness against the two independent bounds, so a
|
|
1067
|
+
* reap can report WHY a lease was cleared:
|
|
1068
|
+
* - `heartbeat-lost` — the anchor rule lapsed: `now - max(claimedAt,
|
|
1069
|
+
* heartbeatAt) > ttl`. The job went silent (or never beat).
|
|
1070
|
+
* - `max-lease-exceeded` — the anchor rule still holds (a live, beating job)
|
|
1071
|
+
* but a CONFIGURED `maxLease` cap has been exceeded: `now - claimedAt >
|
|
1072
|
+
* maxLease`. Only reachable when `maxLease !== undefined`.
|
|
1073
|
+
* - `fresh` — neither bound violated.
|
|
1074
|
+
*
|
|
1075
|
+
* Precedence: `heartbeat-lost` wins when both bounds lapse — if the job was
|
|
1076
|
+
* not alive under the anchor rule, reporting `max-lease-exceeded` would wrongly
|
|
1077
|
+
* suggest the cap killed a healthy job. The cap reason is reported only for a
|
|
1078
|
+
* still-beating lease. The clamp is measured off the ORIGINAL `claimedAt` of
|
|
1079
|
+
* the current claim; after a reap + re-claim it re-anchors to the new claim.
|
|
1080
|
+
*/
|
|
1081
|
+
staleness(task, now, ttl, maxLease) {
|
|
382
1082
|
const anchor = task.heartbeatAt !== undefined && task.heartbeatAt > (task.claimedAt ?? 0)
|
|
383
1083
|
? task.heartbeatAt
|
|
384
1084
|
: (task.claimedAt ?? 0);
|
|
385
|
-
|
|
1085
|
+
if (now - anchor > ttl)
|
|
1086
|
+
return 'heartbeat-lost';
|
|
1087
|
+
// A3 clamp: total lifetime since the original claim may not exceed a
|
|
1088
|
+
// CONFIGURED maxLease. Unset (undefined) = no cap. `0` is a real (if silly)
|
|
1089
|
+
// cap, so test `!== undefined`, not truthiness.
|
|
1090
|
+
if (maxLease !== undefined && task.claimedAt !== undefined && now - task.claimedAt > maxLease) {
|
|
1091
|
+
return 'max-lease-exceeded';
|
|
1092
|
+
}
|
|
1093
|
+
return 'fresh';
|
|
1094
|
+
}
|
|
1095
|
+
/**
|
|
1096
|
+
* Unified liveness predicate: returns true if the task's claim is still fresh.
|
|
1097
|
+
* Thin wrapper over {@link staleness} — see it for the anchor rule and the
|
|
1098
|
+
* opt-in max-lease clamp. A heartbeating run is never falsely reaped after the
|
|
1099
|
+
* global TTL (anchor rule), and only a configured `maxLease` can reap a
|
|
1100
|
+
* still-beating lease.
|
|
1101
|
+
*/
|
|
1102
|
+
isClaimFresh(task, now, ttl, maxLease) {
|
|
1103
|
+
return this.staleness(task, now, ttl, maxLease) === 'fresh';
|
|
386
1104
|
}
|
|
387
1105
|
/** Claim a firing's lease via CAS, snapshot the fingerprint, open a run. */
|
|
388
1106
|
claim(workflow, def, f, arts, now) {
|
|
@@ -391,16 +1109,26 @@ export class Engine {
|
|
|
391
1109
|
const run = existing.run ? this.store.getRun(existing.run) : undefined;
|
|
392
1110
|
const stepDef = def.steps.find((l) => l.name === f.step);
|
|
393
1111
|
const ttl = this.effectiveTtl(stepDef);
|
|
1112
|
+
const maxLease = this.effectiveMaxLease(stepDef);
|
|
394
1113
|
const fresh = !!run &&
|
|
395
1114
|
run.outcome === undefined &&
|
|
396
|
-
(existing.claimedAt === undefined || this.isClaimFresh(existing, now, ttl));
|
|
1115
|
+
(existing.claimedAt === undefined || this.isClaimFresh(existing, now, ttl, maxLease));
|
|
397
1116
|
if (fresh)
|
|
398
1117
|
return 'in-flight'; // genuinely in flight — don't double-claim
|
|
399
1118
|
}
|
|
400
1119
|
const runId = randId('run');
|
|
401
1120
|
const fp = computeFingerprint(arts, f.inputs);
|
|
1121
|
+
// Build the order BEFORE inserting the run so the flattened packet lands in
|
|
1122
|
+
// the SAME INSERT that creates the run row (§8 / Gap 1). buildOrder is
|
|
1123
|
+
// store-pure — it reads `def`, the in-memory `arts` map, and the firing, and
|
|
1124
|
+
// writes nothing — so reordering it ahead of insertRun changes no semantics.
|
|
1125
|
+
// Artifacts are overwritten in place (UNIQUE(workflow,path), putArtifact ON
|
|
1126
|
+
// CONFLICT DO UPDATE, no history table), so the issued order is unrecoverable
|
|
1127
|
+
// later unless captured here; this persisted packet is the replay/eval/paper
|
|
1128
|
+
// trail record (buildOrder is deterministic modulo run id).
|
|
1129
|
+
const order = this.buildOrder(def, workflow, runId, f, arts);
|
|
402
1130
|
// Stamp the run with the tick's clock so cadence/budget compare on one clock.
|
|
403
|
-
this.store.insertRun(runId, { workflow, step: f.step, key: f.key, fingerprint: fp, ...(f.cause ? { cause: f.cause } : {}) }, now);
|
|
1131
|
+
this.store.insertRun(runId, { workflow, step: f.step, key: f.key, fingerprint: fp, order, ...(f.cause ? { cause: f.cause } : {}) }, now);
|
|
404
1132
|
this.store.putTask({
|
|
405
1133
|
workflow,
|
|
406
1134
|
step: f.step,
|
|
@@ -410,7 +1138,7 @@ export class Engine {
|
|
|
410
1138
|
claimedAt: now,
|
|
411
1139
|
attempts: existing?.attempts ?? 0,
|
|
412
1140
|
});
|
|
413
|
-
return
|
|
1141
|
+
return order;
|
|
414
1142
|
}
|
|
415
1143
|
buildOrder(def, workflow, runId, f, arts) {
|
|
416
1144
|
const step = this.step(def, f.step);
|
|
@@ -459,6 +1187,12 @@ export class Engine {
|
|
|
459
1187
|
order.workdir = step.workdir;
|
|
460
1188
|
if (step.model !== undefined)
|
|
461
1189
|
order.model = step.model;
|
|
1190
|
+
if (step.worker !== undefined)
|
|
1191
|
+
order.worker = step.worker;
|
|
1192
|
+
if (step.command !== undefined)
|
|
1193
|
+
order.command = step.command;
|
|
1194
|
+
if (step.spec !== undefined)
|
|
1195
|
+
order.spec = step.spec;
|
|
462
1196
|
if (step.x !== undefined)
|
|
463
1197
|
order.x = step.x;
|
|
464
1198
|
if (f.cause !== undefined)
|
|
@@ -505,6 +1239,20 @@ export class Engine {
|
|
|
505
1239
|
this.settle(workflow, def);
|
|
506
1240
|
return { path, outcome: 'group-rejected', reason: groupCas.reason };
|
|
507
1241
|
}
|
|
1242
|
+
// §18: a human bypass still lands a value downstream consumers assume
|
|
1243
|
+
// is schema-valid (and which can later crash e.g. maintainCalls child
|
|
1244
|
+
// seeding), so enforce the same produce schema the producer-commit path
|
|
1245
|
+
// enforces (below). Unlike that path, there is no lease/retry loop to
|
|
1246
|
+
// protect here — a schema-invalid human green is a hard refusal (thrown
|
|
1247
|
+
// Error), not a schemaRejects-bumping soft one: no version bump, artifact
|
|
1248
|
+
// left untouched. The judge bypass (§24.6) is untouched by this check.
|
|
1249
|
+
const humanSchema = this.produceSchema(def, art);
|
|
1250
|
+
if (humanSchema !== undefined) {
|
|
1251
|
+
const check = validateValue(humanSchema, value);
|
|
1252
|
+
if (!check.valid) {
|
|
1253
|
+
throw new Error(`human green for '${path}' failed schema: ${summarizeIssues(check.issues)}`);
|
|
1254
|
+
}
|
|
1255
|
+
}
|
|
508
1256
|
const req = requiredInputs(def, arts, art);
|
|
509
1257
|
const next = {
|
|
510
1258
|
...art,
|
|
@@ -517,7 +1265,7 @@ export class Engine {
|
|
|
517
1265
|
const producer = def.steps.find((l) => l.name === art.producer);
|
|
518
1266
|
if (opts.terminal || producer?.terminal)
|
|
519
1267
|
next.terminal = true;
|
|
520
|
-
this.store.putArtifact(next);
|
|
1268
|
+
this.store.putArtifact(next, { action: 'green', actor: 'human', reason: 'human green' });
|
|
521
1269
|
this.settle(workflow, def);
|
|
522
1270
|
return { path, outcome: 'green' };
|
|
523
1271
|
});
|
|
@@ -558,11 +1306,11 @@ export class Engine {
|
|
|
558
1306
|
const next = { ...art, acceptance: 'green', approvals };
|
|
559
1307
|
if (producer?.terminal)
|
|
560
1308
|
next.terminal = true;
|
|
561
|
-
this.store.putArtifact(next);
|
|
1309
|
+
this.store.putArtifact(next, { action: 'judge-approved', actor: jName, reason: 'all judges approved' });
|
|
562
1310
|
this.settle(workflow, def);
|
|
563
1311
|
return { path: judgedStem, outcome: 'green' };
|
|
564
1312
|
}
|
|
565
|
-
this.store.putArtifact({ ...art, approvals });
|
|
1313
|
+
this.store.putArtifact({ ...art, approvals }, { action: 'judge-approved', actor: jName, reason: 'judge approved' });
|
|
566
1314
|
this.settle(workflow, def);
|
|
567
1315
|
return { path: judgedStem, outcome: 'approved' };
|
|
568
1316
|
}
|
|
@@ -633,7 +1381,11 @@ export class Engine {
|
|
|
633
1381
|
const producer = def.steps.find((l) => l.name === art.producer);
|
|
634
1382
|
if (!hasJudges && (opts.terminal || producer?.terminal))
|
|
635
1383
|
next.terminal = true;
|
|
636
|
-
this.store.putArtifact(next
|
|
1384
|
+
this.store.putArtifact(next, {
|
|
1385
|
+
action: hasJudges ? 'submitted' : 'produced',
|
|
1386
|
+
actor: r.step,
|
|
1387
|
+
reason: hasJudges ? 'submitted for judgment' : 'producer green',
|
|
1388
|
+
});
|
|
637
1389
|
this.settle(workflow, def);
|
|
638
1390
|
return { path, outcome: hasJudges ? 'submitted' : 'green' };
|
|
639
1391
|
});
|
|
@@ -672,6 +1424,20 @@ export class Engine {
|
|
|
672
1424
|
this.settle(workflow, def);
|
|
673
1425
|
return { outcome: 'born-rejected', created: [], reason: cas.reason };
|
|
674
1426
|
}
|
|
1427
|
+
// §11.1: once the seal is green the collection is complete — the offer
|
|
1428
|
+
// side never offers collection work again, so a late `emit` on a still
|
|
1429
|
+
// -open lease is refused rather than silently growing a "complete" set.
|
|
1430
|
+
// Check first, don't mutate on refusal (mirrors green()'s group check):
|
|
1431
|
+
// no counters bumped, no artifacts touched, lease stays open so the run
|
|
1432
|
+
// can still close.
|
|
1433
|
+
const sealForGreenCheck = arts.get(sealPath(stem));
|
|
1434
|
+
if (sealForGreenCheck && isGreen(sealForGreenCheck)) {
|
|
1435
|
+
return {
|
|
1436
|
+
outcome: 'sealed-rejected',
|
|
1437
|
+
created: [],
|
|
1438
|
+
reason: `collection ${stem} is sealed: seal green = set complete (§11.1)`,
|
|
1439
|
+
};
|
|
1440
|
+
}
|
|
675
1441
|
// §18: every emitted element must satisfy the collection's declared schema.
|
|
676
1442
|
// The check is atomic — one bad item accretes nothing and bumps the seal's
|
|
677
1443
|
// schema-stall counter — so a producer can't half-fill a collection with
|
|
@@ -716,7 +1482,7 @@ export class Engine {
|
|
|
716
1482
|
reasons: [],
|
|
717
1483
|
judgmentRejects: 0,
|
|
718
1484
|
schemaRejects: 0,
|
|
719
|
-
});
|
|
1485
|
+
}, { action: 'produced', actor: r.step, reason: 'collection item emitted' });
|
|
720
1486
|
created.push(p);
|
|
721
1487
|
}
|
|
722
1488
|
this.settle(workflow, def);
|
|
@@ -757,7 +1523,7 @@ export class Engine {
|
|
|
757
1523
|
version: sealArt.version + 1,
|
|
758
1524
|
value,
|
|
759
1525
|
fingerprint: computeFingerprint(arts, req),
|
|
760
|
-
});
|
|
1526
|
+
}, { action: 'sealed', actor: r.step, reason: 'collection sealed' });
|
|
761
1527
|
this.settle(workflow, def);
|
|
762
1528
|
return { path: sealP, outcome: 'green' };
|
|
763
1529
|
});
|
|
@@ -796,6 +1562,16 @@ export class Engine {
|
|
|
796
1562
|
reject(workflow, path, by, text) {
|
|
797
1563
|
const def = this.defFor(workflow);
|
|
798
1564
|
this.assertAuthority(def, by, path, 'reject');
|
|
1565
|
+
// F4: a reject on an artifact produced by a `calls:` step is a verdict on
|
|
1566
|
+
// the CHILD's work, not the parent's own — forward it. Detection: the
|
|
1567
|
+
// producing step declares `calls:`. The child is resolved via the
|
|
1568
|
+
// parent→child reverse index (store.findChildByParent); if no child was
|
|
1569
|
+
// ever spawned there is nothing to judge, so refuse (consistent with the
|
|
1570
|
+
// verb-guard rule below that a verdict needs a built version).
|
|
1571
|
+
const producingStep = def.steps.find((s) => s.produces.some((p) => p.stem === path));
|
|
1572
|
+
if (producingStep?.calls) {
|
|
1573
|
+
return this.rejectCallsArtifact(workflow, def, producingStep, path, by, text);
|
|
1574
|
+
}
|
|
799
1575
|
const judgeStep = def.steps.find((s) => s.name === by);
|
|
800
1576
|
const judgedStem = judgeStep?.judges;
|
|
801
1577
|
let releasedRun;
|
|
@@ -819,6 +1595,21 @@ export class Engine {
|
|
|
819
1595
|
return { outcome: 'born-rejected', reason: cas.reason };
|
|
820
1596
|
}
|
|
821
1597
|
}
|
|
1598
|
+
// §6: a judgment verdict is about a *produced* version (design §6) — refuse
|
|
1599
|
+
// a reject on anything that isn't currently a build (`green`) or awaiting
|
|
1600
|
+
// verdict (`submitted`). Two concrete wedges this closes: rejecting a
|
|
1601
|
+
// never-built `owed` artifact would burn a judgmentRejects toward the §6
|
|
1602
|
+
// stall cap with zero build attempts (a silent freeze — the producer side
|
|
1603
|
+
// never re-offers past the cap); rejecting a terminal `retracted` collection
|
|
1604
|
+
// member would flip a dead member back to a live `rejected` debt, but no
|
|
1605
|
+
// firing shape can ever rebuild a bare collection element (§11.3: retracted
|
|
1606
|
+
// is terminal, out of the live set), so the instance wedges permanently.
|
|
1607
|
+
// The judge-CAS branch above already guarantees `submitted` for judge
|
|
1608
|
+
// verdicts that reach here (a stale one already returned born-rejected),
|
|
1609
|
+
// so this only bites the plain/human reject path in practice.
|
|
1610
|
+
if (art.acceptance !== 'green' && art.acceptance !== 'submitted') {
|
|
1611
|
+
throw new Error(`cannot reject '${path}' in state '${art.acceptance}': a verdict requires a built version (green|submitted)`);
|
|
1612
|
+
}
|
|
822
1613
|
// §24 §3.1/§4.4: a judge reject (or a human reject on a `submitted`
|
|
823
1614
|
// artifact) is a quality verdict, not a cascade invalidation — it wins
|
|
824
1615
|
// immediately regardless of any other judge's already-recorded approval,
|
|
@@ -849,12 +1640,87 @@ export class Engine {
|
|
|
849
1640
|
this.fireSettled(workflow);
|
|
850
1641
|
return result;
|
|
851
1642
|
}
|
|
1643
|
+
/**
|
|
1644
|
+
* F4: forward a reject on a `calls:`-produced artifact to the CHILD's
|
|
1645
|
+
* outcome artifact, then reopen the parent calls artifact to `owed` pinned
|
|
1646
|
+
* (via `childOutcomePin`) to the just-rejected child outcome version, so
|
|
1647
|
+
* STEP 6's mirror only fires again once the child has actually rebuilt past
|
|
1648
|
+
* this verdict (§ F4 settled design).
|
|
1649
|
+
*
|
|
1650
|
+
* The forward is engine-internal: authority was already checked against the
|
|
1651
|
+
* PARENT def by `assertAuthority` in `reject()` above, so the child's own
|
|
1652
|
+
* `assertAuthority` is not consulted — the author recorded on the child's
|
|
1653
|
+
* reasons entry is `parent:<by>` to make the indirection visible in its
|
|
1654
|
+
* audit thread.
|
|
1655
|
+
*/
|
|
1656
|
+
rejectCallsArtifact(parentWf, def, producingStep, callsStem, by, text) {
|
|
1657
|
+
const child = this.store.findChildByParent(parentWf, callsStem);
|
|
1658
|
+
if (!child) {
|
|
1659
|
+
throw new Error(`cannot reject '${callsStem}': no child instance has been spawned yet (a verdict requires a built version)`);
|
|
1660
|
+
}
|
|
1661
|
+
const childDef = this.defFor(child.id);
|
|
1662
|
+
const childOutcomeStem = childDef.outputs[0];
|
|
1663
|
+
this.store.tx(() => {
|
|
1664
|
+
const parentArt = this.store.getArtifact(parentWf, callsStem);
|
|
1665
|
+
if (!parentArt)
|
|
1666
|
+
throw new Error(`cannot reject unknown artifact: ${callsStem}`);
|
|
1667
|
+
if (parentArt.acceptance !== 'green' && parentArt.acceptance !== 'submitted') {
|
|
1668
|
+
throw new Error(`cannot reject '${callsStem}' in state '${parentArt.acceptance}': a verdict requires a built version (green|submitted)`);
|
|
1669
|
+
}
|
|
1670
|
+
const childArt = this.store.getArtifact(child.id, childOutcomeStem);
|
|
1671
|
+
if (!childArt)
|
|
1672
|
+
throw new Error(`cannot reject '${callsStem}': child outcome artifact missing`);
|
|
1673
|
+
// Child outcome → rejected, judgmentRejects+1, author `parent:<by>`.
|
|
1674
|
+
this.store.putArtifact({
|
|
1675
|
+
...childArt,
|
|
1676
|
+
acceptance: 'rejected',
|
|
1677
|
+
judgmentRejects: childArt.judgmentRejects + 1,
|
|
1678
|
+
approvals: undefined,
|
|
1679
|
+
reasons: [...childArt.reasons, reason('reject', 'judgment', `parent:${by}`, text, childArt.version)],
|
|
1680
|
+
});
|
|
1681
|
+
this.settle(child.id, childDef);
|
|
1682
|
+
// Parent calls artifact → reopened to owed (not left rejected), pinned
|
|
1683
|
+
// to the just-rejected child outcome version.
|
|
1684
|
+
this.store.putArtifact({
|
|
1685
|
+
...parentArt,
|
|
1686
|
+
acceptance: 'owed',
|
|
1687
|
+
fingerprint: { ...(parentArt.fingerprint ?? {}), [Engine.CHILD_OUTCOME_PIN_KEY]: childArt.version },
|
|
1688
|
+
reasons: [
|
|
1689
|
+
...parentArt.reasons,
|
|
1690
|
+
{
|
|
1691
|
+
at: nowMs(),
|
|
1692
|
+
action: 'reopen',
|
|
1693
|
+
kind: 'structural',
|
|
1694
|
+
by: 'engine',
|
|
1695
|
+
text: `reject forwarded to child outcome '${childOutcomeStem}': ${text}`,
|
|
1696
|
+
fromVersion: parentArt.version,
|
|
1697
|
+
},
|
|
1698
|
+
],
|
|
1699
|
+
});
|
|
1700
|
+
this.settle(parentWf, def);
|
|
1701
|
+
});
|
|
1702
|
+
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject' });
|
|
1703
|
+
this.fireSettled(parentWf);
|
|
1704
|
+
// The child's own firings (re-arming its producer with the feedback on
|
|
1705
|
+
// its owes thread) need tick(child) — not driven from here; see docs/design.md
|
|
1706
|
+
// M2/M2B "sweeping" note. Prompt maintainCalls now so the parent's own
|
|
1707
|
+
// state (owed/pin) is visible immediately, mirroring provideInput's cascade.
|
|
1708
|
+
this.maintainCalls(parentWf, def);
|
|
1709
|
+
return { outcome: 'rejected' };
|
|
1710
|
+
}
|
|
852
1711
|
/** Retract a collection member (§11.3): drop it, terminally; abandon the index. */
|
|
853
1712
|
retract(workflow, path, by, text) {
|
|
854
1713
|
const def = this.defFor(workflow);
|
|
855
1714
|
const el = parseElement(path);
|
|
856
1715
|
if (!el || el.suffix !== '')
|
|
857
1716
|
throw new Error(`retract is only valid on a collection member: ${path}`);
|
|
1717
|
+
// §4.1/§11.3: same authority rule as reject — only a consumer of the member's
|
|
1718
|
+
// stem (or human/engine) may drop it. Without this, any string actor name
|
|
1719
|
+
// (even one not in the def) could terminally retract a green member of a
|
|
1720
|
+
// sealed collection. assertAuthority resolves an element path to its stem
|
|
1721
|
+
// via parseElement internally, so `path` (not `el.stem`) is passed straight
|
|
1722
|
+
// through, same as reject().
|
|
1723
|
+
this.assertAuthority(def, by, path, 'retract');
|
|
858
1724
|
this.store.tx(() => {
|
|
859
1725
|
const art = this.store.getArtifact(workflow, path);
|
|
860
1726
|
if (!art)
|
|
@@ -883,10 +1749,22 @@ export class Engine {
|
|
|
883
1749
|
// Fingerprint the inputs this skip rests on, so the level-trigger only
|
|
884
1750
|
// re-arms the branch when those inputs *move* (§16.1), not merely stay green.
|
|
885
1751
|
const req = requiredInputs(def, arts, art);
|
|
1752
|
+
const fp = computeFingerprint(arts, req);
|
|
1753
|
+
// F4: a calls: step declares `consumes: []`, so `req` above never sees
|
|
1754
|
+
// its real input — the child outcome, which lives in another instance.
|
|
1755
|
+
// Capture the same version pin `childOutcomePin` uses elsewhere, so a
|
|
1756
|
+
// skip made on evidence from child version N survives arbitrary ticks
|
|
1757
|
+
// (order A) until the child actually rebuilds past N (order B).
|
|
1758
|
+
const producingStep = def.steps.find((s) => s.name === art.producer);
|
|
1759
|
+
if (producingStep?.calls) {
|
|
1760
|
+
const pin = this.childOutcomePin(workflow, path);
|
|
1761
|
+
if (pin !== undefined)
|
|
1762
|
+
fp[Engine.CHILD_OUTCOME_PIN_KEY] = pin;
|
|
1763
|
+
}
|
|
886
1764
|
this.store.putArtifact({
|
|
887
1765
|
...art,
|
|
888
1766
|
acceptance: 'skipped',
|
|
889
|
-
fingerprint:
|
|
1767
|
+
fingerprint: fp,
|
|
890
1768
|
reasons: [...art.reasons, reason('skip', 'structural', by, text, art.version)],
|
|
891
1769
|
});
|
|
892
1770
|
this.settle(workflow, def);
|
|
@@ -903,10 +1781,21 @@ export class Engine {
|
|
|
903
1781
|
*/
|
|
904
1782
|
retry(workflow, path, by = 'human', text = 'retry: stall cleared') {
|
|
905
1783
|
const def = this.defFor(workflow);
|
|
1784
|
+
// §4.1: same authority rule as reject/retract — only a consumer of the
|
|
1785
|
+
// stem (or human/engine) may re-arm it.
|
|
1786
|
+
this.assertAuthority(def, by, path, 'retry');
|
|
906
1787
|
this.store.tx(() => {
|
|
907
1788
|
const art = this.store.getArtifact(workflow, path);
|
|
908
1789
|
if (!art)
|
|
909
1790
|
throw new Error(`cannot retry unknown artifact: ${path}`);
|
|
1791
|
+
// §11.3: retry re-arms to `owed`, but a bare collection element that has
|
|
1792
|
+
// been retracted has no producer firing that can ever rebuild it — retry
|
|
1793
|
+
// would resurrect a terminally-dropped member into a guaranteed wedge.
|
|
1794
|
+
// `retract` is final by design; every other state (rejected, stalled,
|
|
1795
|
+
// skipped, green) stays a legal retry target.
|
|
1796
|
+
if (art.acceptance === 'retracted') {
|
|
1797
|
+
throw new Error(`cannot retry '${path}': it was retracted, which is terminal (use a fresh collection element instead)`);
|
|
1798
|
+
}
|
|
910
1799
|
this.store.putArtifact({
|
|
911
1800
|
...art,
|
|
912
1801
|
acceptance: 'owed',
|
|
@@ -955,7 +1844,14 @@ export class Engine {
|
|
|
955
1844
|
/**
|
|
956
1845
|
* Touch the liveness timestamp on an open run's task. A run that periodically
|
|
957
1846
|
* calls heartbeat() will never be falsely reaped as long as beats arrive within
|
|
958
|
-
* the effective TTL
|
|
1847
|
+
* the effective TTL — EXCEPT (A3) when a max-lease cap is CONFIGURED and total
|
|
1848
|
+
* lifetime since the original claim exceeds it: past `claimedAt + maxLease` the
|
|
1849
|
+
* read-side freshness predicate (`isClaimFresh`) reports the lease stale no
|
|
1850
|
+
* matter how recent the beat, so a wedged-but-beating run is reaped and
|
|
1851
|
+
* re-claimable. With no cap configured (the default) beats extend the lease
|
|
1852
|
+
* indefinitely. This write stays dumb — it only records `heartbeatAt`; the
|
|
1853
|
+
* clamp is judged on read. Throws (via openRun) if the run no longer holds its
|
|
1854
|
+
* lease.
|
|
959
1855
|
*/
|
|
960
1856
|
heartbeat(workflow, run, now) {
|
|
961
1857
|
const ts = now ?? nowMs();
|
|
@@ -984,10 +1880,30 @@ export class Engine {
|
|
|
984
1880
|
continue;
|
|
985
1881
|
const run = task.run ? this.store.getRun(task.run) : undefined;
|
|
986
1882
|
const stepDef = resolvedDef.steps.find((l) => l.name === task.step);
|
|
987
|
-
const
|
|
988
|
-
const
|
|
989
|
-
|
|
990
|
-
|
|
1883
|
+
const realTtl = this.effectiveTtl(stepDef);
|
|
1884
|
+
const maxLease = this.effectiveMaxLease(stepDef);
|
|
1885
|
+
// Classify why (if at all) this claim is stranded, in the same precedence
|
|
1886
|
+
// order the disjunction has always evaluated: run-missing, then run-closed,
|
|
1887
|
+
// then a liveness failure. The stranding DECISION honors ttlOverride (so
|
|
1888
|
+
// `reap --now` forces even a fresh claim stale), but the reported REASON is
|
|
1889
|
+
// computed under the REAL ttl — a lease that was fresh under real rules and
|
|
1890
|
+
// only cleared by the override reports `forced`, not a misleading liveness
|
|
1891
|
+
// reason (§ CLI reap --now).
|
|
1892
|
+
let reason;
|
|
1893
|
+
if (!run) {
|
|
1894
|
+
reason = 'run-missing';
|
|
1895
|
+
}
|
|
1896
|
+
else if (run.outcome !== undefined) {
|
|
1897
|
+
reason = 'run-closed';
|
|
1898
|
+
}
|
|
1899
|
+
else if (task.claimedAt !== undefined) {
|
|
1900
|
+
const effTtl = opts.ttlOverride ?? realTtl;
|
|
1901
|
+
if (this.staleness(task, now, effTtl, maxLease) !== 'fresh') {
|
|
1902
|
+
const realReason = this.staleness(task, now, realTtl, maxLease);
|
|
1903
|
+
reason = realReason === 'fresh' ? 'forced' : realReason;
|
|
1904
|
+
}
|
|
1905
|
+
}
|
|
1906
|
+
if (reason !== undefined) {
|
|
991
1907
|
this.store.putTask({
|
|
992
1908
|
workflow,
|
|
993
1909
|
step: task.step,
|
|
@@ -997,7 +1913,7 @@ export class Engine {
|
|
|
997
1913
|
...(task.alarmAt !== undefined ? { alarmAt: task.alarmAt } : {}),
|
|
998
1914
|
});
|
|
999
1915
|
n++;
|
|
1000
|
-
const detail = { step: task.step, key: task.key };
|
|
1916
|
+
const detail = { step: task.step, key: task.key, reason };
|
|
1001
1917
|
if (task.run !== undefined)
|
|
1002
1918
|
detail.run = task.run;
|
|
1003
1919
|
details.push(detail);
|
|
@@ -1043,6 +1959,22 @@ export class Engine {
|
|
|
1043
1959
|
if (task && task.attempts > 0)
|
|
1044
1960
|
d.attempts = task.attempts;
|
|
1045
1961
|
}
|
|
1962
|
+
// §23.6.8: surface a `calls:` child on each unpaid calls debt so a stalled
|
|
1963
|
+
// descendant is visible from the root. Walk the debts again: a debt whose
|
|
1964
|
+
// path is a calls: step's produced stem, with a spawned child, gets a
|
|
1965
|
+
// recursive child summary (all instance-crossing logic stays here, in the
|
|
1966
|
+
// engine — the pure workflowStatus never touches another instance).
|
|
1967
|
+
for (const d of st.debts) {
|
|
1968
|
+
const callsStep = def.steps.find((s) => s.calls && s.produces[0].stem === d.path);
|
|
1969
|
+
if (!callsStep)
|
|
1970
|
+
continue;
|
|
1971
|
+
const child = this.store.findChildByParent(workflow, d.path);
|
|
1972
|
+
if (!child)
|
|
1973
|
+
continue;
|
|
1974
|
+
const summary = this.childStatusSummary(child.id, new Set());
|
|
1975
|
+
if (summary !== undefined)
|
|
1976
|
+
d.child = summary;
|
|
1977
|
+
}
|
|
1046
1978
|
// §28: informational drift flag — compare the currently-loaded live def
|
|
1047
1979
|
// for this instance's def NAME against the pinned snapshot's hash. Only
|
|
1048
1980
|
// meaningful when a pin exists; only computable when the live def still
|
|
@@ -1176,9 +2108,10 @@ export class Engine {
|
|
|
1176
2108
|
const run = task.run ? this.store.getRun(task.run) : undefined;
|
|
1177
2109
|
const stepDef = def.steps.find((l) => l.name === task.step);
|
|
1178
2110
|
const ttl = this.effectiveTtl(stepDef);
|
|
2111
|
+
const maxLease = this.effectiveMaxLease(stepDef);
|
|
1179
2112
|
const fresh = !!run &&
|
|
1180
2113
|
run.outcome === undefined &&
|
|
1181
|
-
(task.claimedAt === undefined || this.isClaimFresh(task, now, ttl));
|
|
2114
|
+
(task.claimedAt === undefined || this.isClaimFresh(task, now, ttl, maxLease));
|
|
1182
2115
|
if (fresh)
|
|
1183
2116
|
return true;
|
|
1184
2117
|
}
|
|
@@ -1206,7 +2139,9 @@ export class Engine {
|
|
|
1206
2139
|
let arts = this.artMap(workflow);
|
|
1207
2140
|
const owed = pendingOwed(def, arts);
|
|
1208
2141
|
for (const a of owed)
|
|
1209
|
-
this.store.putArtifact({ ...a, workflow }
|
|
2142
|
+
this.store.putArtifact({ ...a, workflow }, {
|
|
2143
|
+
action: 'owed', actor: 'engine', reason: 'artifact became owed',
|
|
2144
|
+
});
|
|
1210
2145
|
if (owed.length)
|
|
1211
2146
|
arts = this.artMap(workflow);
|
|
1212
2147
|
// Only pass TimeFacts when we have a clock reading (tick path).
|
|
@@ -1296,9 +2231,15 @@ export class Engine {
|
|
|
1296
2231
|
// re-arms when the upstream branch revives (mirrors a producer skip).
|
|
1297
2232
|
// §26: an auto-skip of a losing group sibling tags rejectKind 'exclusive'
|
|
1298
2233
|
// instead of the default 'structural' (op.rejectKind carries this).
|
|
2234
|
+
// §26.2: if the skipped sibling was `submitted` (awaiting judgment), it
|
|
2235
|
+
// may be carrying a partial approvals sign-off — clear it the same way
|
|
2236
|
+
// a cascade reject does (§24 §4.3), so a stale sign-off never leaks onto
|
|
2237
|
+
// a later resubmission if the winner is un-greened and the branch revives.
|
|
2238
|
+
const clearApprovals = art.acceptance === 'submitted' && art.approvals !== undefined;
|
|
1299
2239
|
this.store.putArtifact({
|
|
1300
2240
|
...art,
|
|
1301
2241
|
acceptance: 'skipped',
|
|
2242
|
+
...(clearApprovals ? { approvals: undefined } : {}),
|
|
1302
2243
|
fingerprint: computeFingerprint(arts, requiredInputs(def, arts, art)),
|
|
1303
2244
|
reasons: [...art.reasons, reason('skip', op.rejectKind ?? 'structural', 'engine', op.reason, art.version)],
|
|
1304
2245
|
});
|
|
@@ -1423,6 +2364,48 @@ export class Engine {
|
|
|
1423
2364
|
m.set(a.path, a);
|
|
1424
2365
|
return m;
|
|
1425
2366
|
}
|
|
2367
|
+
/**
|
|
2368
|
+
* §23.6.8: a compact summary of a `calls:` child for parent-status enrichment.
|
|
2369
|
+
* Uses the pure `workflowStatus` for the child's own debts (lighter than a
|
|
2370
|
+
* full recursive `Engine.status` — the `stalled` flag is already set by the
|
|
2371
|
+
* pure layer). `stalled` propagates recursively along the child's OWN unpaid
|
|
2372
|
+
* `calls:` path so a grandchild stall shows as `stalled: true` here. `debts`
|
|
2373
|
+
* is a COUNT — the `workflow` id is the human's inspection handle. `visited`
|
|
2374
|
+
* guards against any accidental instance cycle.
|
|
2375
|
+
*
|
|
2376
|
+
* Returns `undefined` when the child's def is unresolvable (an unpinned row
|
|
2377
|
+
* whose def was deleted/renamed) — practically unreachable since `calls:`
|
|
2378
|
+
* spawns pin (§28), but a summary is enrichment, and enrichment must not
|
|
2379
|
+
* make `status(parent)` throw (same stance as the §28 drift flag).
|
|
2380
|
+
*/
|
|
2381
|
+
childStatusSummary(childWf, visited) {
|
|
2382
|
+
visited.add(childWf);
|
|
2383
|
+
let childDef;
|
|
2384
|
+
try {
|
|
2385
|
+
childDef = this.defFor(childWf);
|
|
2386
|
+
}
|
|
2387
|
+
catch {
|
|
2388
|
+
return undefined;
|
|
2389
|
+
}
|
|
2390
|
+
const childArts = this.artMap(childWf);
|
|
2391
|
+
const cs = workflowStatus(childDef, childArts);
|
|
2392
|
+
let stalled = cs.debts.some((d) => d.stalled);
|
|
2393
|
+
if (!stalled) {
|
|
2394
|
+
for (const d of cs.debts) {
|
|
2395
|
+
const callsStep = childDef.steps.find((s) => s.calls && s.produces[0].stem === d.path);
|
|
2396
|
+
if (!callsStep)
|
|
2397
|
+
continue;
|
|
2398
|
+
const grandchild = this.store.findChildByParent(childWf, d.path);
|
|
2399
|
+
if (!grandchild || visited.has(grandchild.id))
|
|
2400
|
+
continue;
|
|
2401
|
+
if (this.childStatusSummary(grandchild.id, visited)?.stalled) {
|
|
2402
|
+
stalled = true;
|
|
2403
|
+
break;
|
|
2404
|
+
}
|
|
2405
|
+
}
|
|
2406
|
+
}
|
|
2407
|
+
return { workflow: childWf, def: childDef.name, done: cs.done, stalled, debts: cs.debts.length };
|
|
2408
|
+
}
|
|
1426
2409
|
defFor(workflow) {
|
|
1427
2410
|
const wf = this.store.getWorkflow(workflow);
|
|
1428
2411
|
if (!wf)
|