owenloop 0.2.1 → 0.4.0
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 +67 -0
- package/README.md +82 -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 +43 -0
- package/dist/cli.js +1865 -19
- package/dist/defs.d.ts +33 -0
- package/dist/defs.js +112 -19
- package/dist/engine.d.ts +338 -50
- package/dist/engine.js +854 -170
- package/dist/factory.d.ts +19 -0
- package/dist/factory.js +41 -5
- package/dist/hub.d.ts +514 -0
- package/dist/hub.js +783 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.js +2 -1
- package/dist/model.d.ts +36 -0
- package/dist/store.d.ts +14 -2
- package/dist/store.js +269 -21
- package/dist/types.d.ts +92 -0
- package/dist/untar.d.ts +47 -0
- package/dist/untar.js +164 -0
- package/dist/util.d.ts +76 -0
- package/dist/util.js +96 -0
- package/docs/authoring.md +48 -1
- package/docs/cli.md +509 -3
- package/docs/design.md +72 -9
- package/docs/embedding.md +87 -7
- package/package.json +1 -1
package/dist/engine.js
CHANGED
|
@@ -15,6 +15,15 @@ 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;
|
|
18
27
|
/**
|
|
19
28
|
* F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
|
|
20
29
|
* by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
|
|
@@ -26,6 +35,17 @@ const DEFAULT_REAP_TTL_MS = 2 * 60 * 60 * 1000; // 2h
|
|
|
26
35
|
export class SchemaRefusalError extends Error {
|
|
27
36
|
inputName;
|
|
28
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;
|
|
29
49
|
constructor(inputName, issues) {
|
|
30
50
|
super(`input '${inputName}' failed schema: ${summarizeIssues(issues)}`);
|
|
31
51
|
this.name = 'SchemaRefusalError';
|
|
@@ -37,6 +57,8 @@ export class Engine {
|
|
|
37
57
|
store;
|
|
38
58
|
resolveDef;
|
|
39
59
|
reapTtlMs;
|
|
60
|
+
maxLeaseMs;
|
|
61
|
+
maxCallDepth;
|
|
40
62
|
listeners = new Set();
|
|
41
63
|
onListenerError;
|
|
42
64
|
/** M2B: recursion guard — set of parentWf ids currently inside maintainCalls. */
|
|
@@ -45,6 +67,8 @@ export class Engine {
|
|
|
45
67
|
this.store = store;
|
|
46
68
|
this.resolveDef = resolveDef;
|
|
47
69
|
this.reapTtlMs = opts.reapTtlMs ?? DEFAULT_REAP_TTL_MS;
|
|
70
|
+
this.maxLeaseMs = opts.maxLeaseMs;
|
|
71
|
+
this.maxCallDepth = opts.maxCallDepth ?? DEFAULT_MAX_CALL_DEPTH;
|
|
48
72
|
if (opts.onEvent)
|
|
49
73
|
this.listeners.add(opts.onEvent);
|
|
50
74
|
this.onListenerError = opts.onListenerError;
|
|
@@ -67,46 +91,202 @@ export class Engine {
|
|
|
67
91
|
createInstance(defName, opts = {}) {
|
|
68
92
|
const def = this.resolveDef(defName);
|
|
69
93
|
const id = randId('wf');
|
|
70
|
-
this.store.tx(() =>
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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;
|
|
87
219
|
}
|
|
88
220
|
}
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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);
|
|
103
263
|
}
|
|
104
|
-
|
|
105
|
-
|
|
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 };
|
|
106
270
|
});
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
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
|
+
}
|
|
110
290
|
}
|
|
111
291
|
/** A human/external producer supplies (greens) an owed input. */
|
|
112
292
|
provideInput(workflow, name, value) {
|
|
@@ -208,15 +388,34 @@ export class Engine {
|
|
|
208
388
|
* Stamps the current gate fingerprint on the rejected artifact so the
|
|
209
389
|
* STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
|
|
210
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`).
|
|
211
406
|
*/
|
|
212
|
-
recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, now) {
|
|
407
|
+
recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, seenGateFp, now) {
|
|
213
408
|
const text = `child input '${err.inputName}' failed schema: ${summarizeIssues(err.issues)}`;
|
|
214
|
-
this.store.tx(() => {
|
|
409
|
+
return this.store.tx(() => {
|
|
215
410
|
const art = this.store.getArtifact(parentWf, callsStem);
|
|
216
411
|
if (!art)
|
|
217
|
-
return; // not yet materialized by pendingOwed — nothing to stamp
|
|
412
|
+
return false; // not yet materialized by pendingOwed — nothing to stamp
|
|
218
413
|
const gateArts = this.artMap(parentWf);
|
|
219
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;
|
|
220
419
|
this.store.putArtifact({
|
|
221
420
|
...art,
|
|
222
421
|
acceptance: 'rejected',
|
|
@@ -225,8 +424,66 @@ export class Engine {
|
|
|
225
424
|
reasons: [...art.reasons, reason('schema-reject', 'validation', 'engine', text, art.version)],
|
|
226
425
|
});
|
|
227
426
|
this.settle(parentWf, def, now);
|
|
427
|
+
return true;
|
|
228
428
|
});
|
|
229
|
-
|
|
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' });
|
|
230
487
|
this.fireSettled(parentWf);
|
|
231
488
|
}
|
|
232
489
|
/**
|
|
@@ -249,8 +506,7 @@ export class Engine {
|
|
|
249
506
|
const callsPath = callsStem;
|
|
250
507
|
const gateStems = Object.values(step.callsInputs ?? {});
|
|
251
508
|
const parentArts = this.artMap(parentWf);
|
|
252
|
-
|
|
253
|
-
if (!gateReady)
|
|
509
|
+
if (!this.callsGateReady(parentArts, step))
|
|
254
510
|
continue;
|
|
255
511
|
// STEP 2 — Look up any existing child via reverse index.
|
|
256
512
|
let existingChild = this.store.findChildByParent(parentWf, callsPath);
|
|
@@ -267,39 +523,71 @@ export class Engine {
|
|
|
267
523
|
if (deepEqual(currentGateFp, parentCallsArtPre.fingerprint ?? {}))
|
|
268
524
|
continue;
|
|
269
525
|
}
|
|
270
|
-
// STEP 3 — SPAWN or RE-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
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);
|
|
297
565
|
}
|
|
298
|
-
|
|
566
|
+
continue;
|
|
299
567
|
}
|
|
300
|
-
|
|
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);
|
|
301
580
|
}
|
|
302
|
-
|
|
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);
|
|
303
591
|
if (!existingChild)
|
|
304
592
|
continue; // defensive: createInstance returned but getWorkflow failed
|
|
305
593
|
// STEP 4 — Read child's declared outcome artifact.
|
|
@@ -309,30 +597,22 @@ export class Engine {
|
|
|
309
597
|
const childOutcomeStem = childDef.outputs[0]; // validated by Phase-2 check
|
|
310
598
|
let childArts = this.artMap(existingChild.id);
|
|
311
599
|
let childOutcomeArt = childArts.get(childOutcomeStem);
|
|
312
|
-
// STEP 5 — RE-PROVIDE if parent gate source moved (M2B-REPROVIDE).
|
|
313
|
-
// F2: same typed-refusal handling as STEP 3 — a re-provided parent
|
|
314
|
-
// value illegal per the child's input schema becomes a debt on the
|
|
315
|
-
// parent calls artifact instead of throwing out of provideInput's
|
|
316
|
-
// cascade-up. The human's own provide of the PARENT input still
|
|
317
|
-
// commits (that validation happens against the PARENT's schema,
|
|
318
|
-
// inside provideInput's own tx, before this cascade ever runs).
|
|
319
|
-
for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
|
|
320
|
-
const parentArtNow = parentArts.get(parentArtifactName);
|
|
321
|
-
const childInputArt = childArts.get(childInputName);
|
|
322
|
-
if (parentArtNow?.value !== undefined && !deepEqual(parentArtNow.value, childInputArt?.value)) {
|
|
323
|
-
try {
|
|
324
|
-
this.provideInput(existingChild.id, childInputName, parentArtNow.value);
|
|
325
|
-
}
|
|
326
|
-
catch (err) {
|
|
327
|
-
if (err instanceof SchemaRefusalError) {
|
|
328
|
-
this.recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, now);
|
|
329
|
-
continue;
|
|
330
|
-
}
|
|
331
|
-
throw err;
|
|
332
|
-
}
|
|
333
|
-
}
|
|
334
|
-
}
|
|
335
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
|
+
//
|
|
336
616
|
// Re-read after potential re-provide.
|
|
337
617
|
childArts = this.artMap(existingChild.id);
|
|
338
618
|
childOutcomeArt = childArts.get(childOutcomeStem);
|
|
@@ -351,29 +631,16 @@ export class Engine {
|
|
|
351
631
|
// (propagated down, parent reopened to owed pinned to the rejected
|
|
352
632
|
// child version) or a human skip (pinned at skip time) stand until
|
|
353
633
|
// the child actually rebuilds past that pin, instead of being
|
|
354
|
-
// silently overridden on the very next tick.
|
|
634
|
+
// silently overridden on the very next tick. (Re-checked in-tx by
|
|
635
|
+
// the helper against the snapshot it commits under.)
|
|
355
636
|
const pinnedVersion = parentCallsArt?.fingerprint?.[Engine.CHILD_OUTCOME_PIN_KEY];
|
|
356
637
|
const pastPin = pinnedVersion === undefined || childOutcomeArt.version > pinnedVersion;
|
|
357
|
-
if ((!alreadyGreen || !sameValue) && pastPin) {
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
const next = {
|
|
364
|
-
...parentCallsArt,
|
|
365
|
-
acceptance: 'green',
|
|
366
|
-
version: parentCallsArt.version + 1,
|
|
367
|
-
value: childOutcomeArt.value,
|
|
368
|
-
fingerprint: fp,
|
|
369
|
-
};
|
|
370
|
-
// Do NOT set terminal: calls: artifact must be re-armable if gate inputs move.
|
|
371
|
-
this.store.tx(() => {
|
|
372
|
-
this.store.putArtifact({ ...next, workflow: parentWf });
|
|
373
|
-
this.settle(parentWf, def, now);
|
|
374
|
-
});
|
|
375
|
-
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'provide' });
|
|
376
|
-
this.fireSettled(parentWf);
|
|
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
|
+
}
|
|
377
644
|
}
|
|
378
645
|
}
|
|
379
646
|
else if (!isGreen(childOutcomeArt) && isGreen(parentCallsArt) && parentCallsArt) {
|
|
@@ -381,26 +648,10 @@ export class Engine {
|
|
|
381
648
|
// but the parent calls: artifact is still green. Re-arm it to owed so downstream
|
|
382
649
|
// re-runs when the child completes again. This handles gate re-arm (test f):
|
|
383
650
|
// the cascade can't detect this because deliver step has consumes: [].
|
|
384
|
-
this.
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
this.store.putArtifact({
|
|
389
|
-
...artNow,
|
|
390
|
-
acceptance: 'owed',
|
|
391
|
-
reasons: [...artNow.reasons, {
|
|
392
|
-
at: nowMs(),
|
|
393
|
-
action: 'reopen',
|
|
394
|
-
kind: 'structural',
|
|
395
|
-
by: 'engine',
|
|
396
|
-
text: 'gate input moved: child re-running',
|
|
397
|
-
fromVersion: artNow.version,
|
|
398
|
-
}],
|
|
399
|
-
});
|
|
400
|
-
this.settle(parentWf, def, now);
|
|
401
|
-
});
|
|
402
|
-
this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'retry' });
|
|
403
|
-
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
|
+
}
|
|
404
655
|
}
|
|
405
656
|
}
|
|
406
657
|
}
|
|
@@ -408,6 +659,120 @@ export class Engine {
|
|
|
408
659
|
this._inMaintainCalls.delete(parentWf);
|
|
409
660
|
}
|
|
410
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
|
+
}
|
|
411
776
|
/**
|
|
412
777
|
* M2B cascade-up prompt: if `workflow` has a producedBy link, trigger
|
|
413
778
|
* maintainCalls on its parent so the parent reflects the child's progress promptly.
|
|
@@ -430,19 +795,105 @@ export class Engine {
|
|
|
430
795
|
this.fireSettled(parentWf);
|
|
431
796
|
}
|
|
432
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
|
+
*/
|
|
433
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);
|
|
434
859
|
const def = this.defFor(workflow);
|
|
435
|
-
const now = opts.now ?? nowMs();
|
|
436
860
|
// M2B: maintain calls: child instances before the normal tick/reap/claim cycle.
|
|
437
861
|
this.maintainCalls(workflow, def, now);
|
|
438
|
-
|
|
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(() => {
|
|
439
866
|
this.settle(workflow, def, now);
|
|
440
867
|
const reaped = this.reap(workflow, now, def);
|
|
441
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
|
+
}
|
|
442
893
|
// Compute time facts for idle eligibility (clock-read boundary).
|
|
443
894
|
const timeFacts = this.computeTimeFacts(def, workflow, arts, now);
|
|
444
895
|
const firings = eligibleFirings(def, arts, timeFacts);
|
|
445
|
-
const { selected, deferred } = this.applySchedule(workflow, def, firings, now);
|
|
896
|
+
const { selected, deferred } = this.applySchedule(workflow, def, firings, now, labels);
|
|
446
897
|
// Clear alarm_at for any idle firing that was selected (consume the alarm).
|
|
447
898
|
for (const f of selected) {
|
|
448
899
|
if (f.cause === 'idle') {
|
|
@@ -452,27 +903,111 @@ export class Engine {
|
|
|
452
903
|
const orders = [];
|
|
453
904
|
const allDeferred = [...deferred];
|
|
454
905
|
for (const f of selected) {
|
|
455
|
-
const
|
|
456
|
-
if (
|
|
906
|
+
const claimed = this.claim(workflow, def, f, arts, now);
|
|
907
|
+
if (claimed === 'in-flight') {
|
|
457
908
|
const d = { step: f.step, key: f.key, inputs: f.inputs, outputs: f.outputs, reason: 'in-flight' };
|
|
458
909
|
if (f.index !== undefined)
|
|
459
910
|
d.index = f.index;
|
|
460
911
|
allDeferred.push(d);
|
|
461
912
|
}
|
|
462
|
-
else if (
|
|
463
|
-
orders.push(
|
|
913
|
+
else if (claimed) {
|
|
914
|
+
orders.push(claimed);
|
|
464
915
|
}
|
|
465
916
|
}
|
|
466
917
|
// E-DUE: compute earliest pending time-trigger for the result.
|
|
467
918
|
const dueAt = this.computeDueAt(def, workflow, now);
|
|
468
|
-
const
|
|
919
|
+
const r = { workflow, orders, reaped, deferred: allDeferred };
|
|
469
920
|
if (dueAt !== null)
|
|
470
|
-
|
|
471
|
-
return
|
|
921
|
+
r.dueAt = dueAt;
|
|
922
|
+
return r;
|
|
472
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)));
|
|
473
962
|
}
|
|
474
|
-
/**
|
|
475
|
-
|
|
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;
|
|
1001
|
+
}
|
|
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) {
|
|
476
1011
|
const midnight = localMidnightMs(now);
|
|
477
1012
|
const selected = [];
|
|
478
1013
|
const deferred = [];
|
|
@@ -486,6 +1021,15 @@ export class Engine {
|
|
|
486
1021
|
const stepFirings = firings.filter((f) => f.step === step.name);
|
|
487
1022
|
if (stepFirings.length === 0)
|
|
488
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
|
+
}
|
|
489
1033
|
const latest = this.store.latestRun(workflow, step.name);
|
|
490
1034
|
if (latest && now - latest.createdAt < step.cadenceSecs * 1000) {
|
|
491
1035
|
for (const f of stepFirings)
|
|
@@ -510,15 +1054,53 @@ export class Engine {
|
|
|
510
1054
|
return step?.reapTtlMs ?? this.reapTtlMs;
|
|
511
1055
|
}
|
|
512
1056
|
/**
|
|
513
|
-
*
|
|
514
|
-
*
|
|
515
|
-
*
|
|
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.
|
|
516
1061
|
*/
|
|
517
|
-
|
|
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) {
|
|
518
1082
|
const anchor = task.heartbeatAt !== undefined && task.heartbeatAt > (task.claimedAt ?? 0)
|
|
519
1083
|
? task.heartbeatAt
|
|
520
1084
|
: (task.claimedAt ?? 0);
|
|
521
|
-
|
|
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';
|
|
522
1104
|
}
|
|
523
1105
|
/** Claim a firing's lease via CAS, snapshot the fingerprint, open a run. */
|
|
524
1106
|
claim(workflow, def, f, arts, now) {
|
|
@@ -527,16 +1109,26 @@ export class Engine {
|
|
|
527
1109
|
const run = existing.run ? this.store.getRun(existing.run) : undefined;
|
|
528
1110
|
const stepDef = def.steps.find((l) => l.name === f.step);
|
|
529
1111
|
const ttl = this.effectiveTtl(stepDef);
|
|
1112
|
+
const maxLease = this.effectiveMaxLease(stepDef);
|
|
530
1113
|
const fresh = !!run &&
|
|
531
1114
|
run.outcome === undefined &&
|
|
532
|
-
(existing.claimedAt === undefined || this.isClaimFresh(existing, now, ttl));
|
|
1115
|
+
(existing.claimedAt === undefined || this.isClaimFresh(existing, now, ttl, maxLease));
|
|
533
1116
|
if (fresh)
|
|
534
1117
|
return 'in-flight'; // genuinely in flight — don't double-claim
|
|
535
1118
|
}
|
|
536
1119
|
const runId = randId('run');
|
|
537
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);
|
|
538
1130
|
// Stamp the run with the tick's clock so cadence/budget compare on one clock.
|
|
539
|
-
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);
|
|
540
1132
|
this.store.putTask({
|
|
541
1133
|
workflow,
|
|
542
1134
|
step: f.step,
|
|
@@ -546,7 +1138,7 @@ export class Engine {
|
|
|
546
1138
|
claimedAt: now,
|
|
547
1139
|
attempts: existing?.attempts ?? 0,
|
|
548
1140
|
});
|
|
549
|
-
return
|
|
1141
|
+
return order;
|
|
550
1142
|
}
|
|
551
1143
|
buildOrder(def, workflow, runId, f, arts) {
|
|
552
1144
|
const step = this.step(def, f.step);
|
|
@@ -673,7 +1265,7 @@ export class Engine {
|
|
|
673
1265
|
const producer = def.steps.find((l) => l.name === art.producer);
|
|
674
1266
|
if (opts.terminal || producer?.terminal)
|
|
675
1267
|
next.terminal = true;
|
|
676
|
-
this.store.putArtifact(next);
|
|
1268
|
+
this.store.putArtifact(next, { action: 'green', actor: 'human', reason: 'human green' });
|
|
677
1269
|
this.settle(workflow, def);
|
|
678
1270
|
return { path, outcome: 'green' };
|
|
679
1271
|
});
|
|
@@ -714,11 +1306,11 @@ export class Engine {
|
|
|
714
1306
|
const next = { ...art, acceptance: 'green', approvals };
|
|
715
1307
|
if (producer?.terminal)
|
|
716
1308
|
next.terminal = true;
|
|
717
|
-
this.store.putArtifact(next);
|
|
1309
|
+
this.store.putArtifact(next, { action: 'judge-approved', actor: jName, reason: 'all judges approved' });
|
|
718
1310
|
this.settle(workflow, def);
|
|
719
1311
|
return { path: judgedStem, outcome: 'green' };
|
|
720
1312
|
}
|
|
721
|
-
this.store.putArtifact({ ...art, approvals });
|
|
1313
|
+
this.store.putArtifact({ ...art, approvals }, { action: 'judge-approved', actor: jName, reason: 'judge approved' });
|
|
722
1314
|
this.settle(workflow, def);
|
|
723
1315
|
return { path: judgedStem, outcome: 'approved' };
|
|
724
1316
|
}
|
|
@@ -789,7 +1381,11 @@ export class Engine {
|
|
|
789
1381
|
const producer = def.steps.find((l) => l.name === art.producer);
|
|
790
1382
|
if (!hasJudges && (opts.terminal || producer?.terminal))
|
|
791
1383
|
next.terminal = true;
|
|
792
|
-
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
|
+
});
|
|
793
1389
|
this.settle(workflow, def);
|
|
794
1390
|
return { path, outcome: hasJudges ? 'submitted' : 'green' };
|
|
795
1391
|
});
|
|
@@ -886,7 +1482,7 @@ export class Engine {
|
|
|
886
1482
|
reasons: [],
|
|
887
1483
|
judgmentRejects: 0,
|
|
888
1484
|
schemaRejects: 0,
|
|
889
|
-
});
|
|
1485
|
+
}, { action: 'produced', actor: r.step, reason: 'collection item emitted' });
|
|
890
1486
|
created.push(p);
|
|
891
1487
|
}
|
|
892
1488
|
this.settle(workflow, def);
|
|
@@ -927,7 +1523,7 @@ export class Engine {
|
|
|
927
1523
|
version: sealArt.version + 1,
|
|
928
1524
|
value,
|
|
929
1525
|
fingerprint: computeFingerprint(arts, req),
|
|
930
|
-
});
|
|
1526
|
+
}, { action: 'sealed', actor: r.step, reason: 'collection sealed' });
|
|
931
1527
|
this.settle(workflow, def);
|
|
932
1528
|
return { path: sealP, outcome: 'green' };
|
|
933
1529
|
});
|
|
@@ -1248,7 +1844,14 @@ export class Engine {
|
|
|
1248
1844
|
/**
|
|
1249
1845
|
* Touch the liveness timestamp on an open run's task. A run that periodically
|
|
1250
1846
|
* calls heartbeat() will never be falsely reaped as long as beats arrive within
|
|
1251
|
-
* 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.
|
|
1252
1855
|
*/
|
|
1253
1856
|
heartbeat(workflow, run, now) {
|
|
1254
1857
|
const ts = now ?? nowMs();
|
|
@@ -1277,10 +1880,30 @@ export class Engine {
|
|
|
1277
1880
|
continue;
|
|
1278
1881
|
const run = task.run ? this.store.getRun(task.run) : undefined;
|
|
1279
1882
|
const stepDef = resolvedDef.steps.find((l) => l.name === task.step);
|
|
1280
|
-
const
|
|
1281
|
-
const
|
|
1282
|
-
|
|
1283
|
-
|
|
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) {
|
|
1284
1907
|
this.store.putTask({
|
|
1285
1908
|
workflow,
|
|
1286
1909
|
step: task.step,
|
|
@@ -1290,7 +1913,7 @@ export class Engine {
|
|
|
1290
1913
|
...(task.alarmAt !== undefined ? { alarmAt: task.alarmAt } : {}),
|
|
1291
1914
|
});
|
|
1292
1915
|
n++;
|
|
1293
|
-
const detail = { step: task.step, key: task.key };
|
|
1916
|
+
const detail = { step: task.step, key: task.key, reason };
|
|
1294
1917
|
if (task.run !== undefined)
|
|
1295
1918
|
detail.run = task.run;
|
|
1296
1919
|
details.push(detail);
|
|
@@ -1336,6 +1959,22 @@ export class Engine {
|
|
|
1336
1959
|
if (task && task.attempts > 0)
|
|
1337
1960
|
d.attempts = task.attempts;
|
|
1338
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
|
+
}
|
|
1339
1978
|
// §28: informational drift flag — compare the currently-loaded live def
|
|
1340
1979
|
// for this instance's def NAME against the pinned snapshot's hash. Only
|
|
1341
1980
|
// meaningful when a pin exists; only computable when the live def still
|
|
@@ -1469,9 +2108,10 @@ export class Engine {
|
|
|
1469
2108
|
const run = task.run ? this.store.getRun(task.run) : undefined;
|
|
1470
2109
|
const stepDef = def.steps.find((l) => l.name === task.step);
|
|
1471
2110
|
const ttl = this.effectiveTtl(stepDef);
|
|
2111
|
+
const maxLease = this.effectiveMaxLease(stepDef);
|
|
1472
2112
|
const fresh = !!run &&
|
|
1473
2113
|
run.outcome === undefined &&
|
|
1474
|
-
(task.claimedAt === undefined || this.isClaimFresh(task, now, ttl));
|
|
2114
|
+
(task.claimedAt === undefined || this.isClaimFresh(task, now, ttl, maxLease));
|
|
1475
2115
|
if (fresh)
|
|
1476
2116
|
return true;
|
|
1477
2117
|
}
|
|
@@ -1499,7 +2139,9 @@ export class Engine {
|
|
|
1499
2139
|
let arts = this.artMap(workflow);
|
|
1500
2140
|
const owed = pendingOwed(def, arts);
|
|
1501
2141
|
for (const a of owed)
|
|
1502
|
-
this.store.putArtifact({ ...a, workflow }
|
|
2142
|
+
this.store.putArtifact({ ...a, workflow }, {
|
|
2143
|
+
action: 'owed', actor: 'engine', reason: 'artifact became owed',
|
|
2144
|
+
});
|
|
1503
2145
|
if (owed.length)
|
|
1504
2146
|
arts = this.artMap(workflow);
|
|
1505
2147
|
// Only pass TimeFacts when we have a clock reading (tick path).
|
|
@@ -1722,6 +2364,48 @@ export class Engine {
|
|
|
1722
2364
|
m.set(a.path, a);
|
|
1723
2365
|
return m;
|
|
1724
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
|
+
}
|
|
1725
2409
|
defFor(workflow) {
|
|
1726
2410
|
const wf = this.store.getWorkflow(workflow);
|
|
1727
2411
|
if (!wf)
|