owenloop 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/engine.js CHANGED
@@ -15,6 +15,24 @@ 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
+ * F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
20
+ * by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
21
+ * `Error` so callers that need to distinguish "this value doesn't fit the
22
+ * schema" from a genuine bug (e.g. `maintainCalls`'s STEP 3/STEP 5, which must
23
+ * turn a CHILD's schema refusal into a debt on the parent rather than crash
24
+ * the parent's tick) can catch narrowly instead of blanket-catching.
25
+ */
26
+ export class SchemaRefusalError extends Error {
27
+ inputName;
28
+ issues;
29
+ constructor(inputName, issues) {
30
+ super(`input '${inputName}' failed schema: ${summarizeIssues(issues)}`);
31
+ this.name = 'SchemaRefusalError';
32
+ this.inputName = inputName;
33
+ this.issues = issues;
34
+ }
35
+ }
18
36
  export class Engine {
19
37
  store;
20
38
  resolveDef;
@@ -65,7 +83,7 @@ export class Engine {
65
83
  if (provided !== undefined && input.schema !== undefined) {
66
84
  const check = validateValue(input.schema, provided);
67
85
  if (!check.valid) {
68
- throw new Error(`input '${input.name}' failed schema: ${summarizeIssues(check.issues)}`);
86
+ throw new SchemaRefusalError(input.name, check.issues);
69
87
  }
70
88
  }
71
89
  const seedGreen = !input.seedOwed || provided !== undefined;
@@ -104,7 +122,7 @@ export class Engine {
104
122
  if (inputDef?.schema !== undefined) {
105
123
  const check = validateValue(inputDef.schema, value);
106
124
  if (!check.valid) {
107
- throw new Error(`input '${name}' failed schema: ${summarizeIssues(check.issues)}`);
125
+ throw new SchemaRefusalError(name, check.issues);
108
126
  }
109
127
  }
110
128
  this.store.putArtifact({
@@ -153,6 +171,64 @@ export class Engine {
153
171
  : { workflow, defHash: newHash };
154
172
  }
155
173
  // ---- Mode 2 calls: child-instance management --------------------------------
174
+ /**
175
+ * F4: the synthetic fingerprint key a `calls:` artifact uses to pin its
176
+ * fingerprint to the child outcome's version. A calls: step declares
177
+ * `consumes: []` (§ M2B), so its produce's fingerprint would otherwise never
178
+ * see the child outcome (which lives in another instance entirely) — this
179
+ * key is how that pin rides inside the same `Fingerprint` map alongside the
180
+ * gate stems, without colliding with any real parent artifact path (gate
181
+ * stems are bare names; this key is namespaced and reserved).
182
+ */
183
+ static CHILD_OUTCOME_PIN_KEY = '__child_outcome_version__';
184
+ /**
185
+ * F4: the single place that computes "what child-outcome version is this
186
+ * calls: artifact currently resting on" — used both when machine-greening
187
+ * (STEP 6) and when stamping the pin at verdict time (reject propagation,
188
+ * human skip). Returns undefined if no child has ever been spawned (nothing
189
+ * to pin to).
190
+ */
191
+ childOutcomePin(parentWf, callsPath) {
192
+ const child = this.store.findChildByParent(parentWf, callsPath);
193
+ if (!child)
194
+ return undefined;
195
+ const childDef = this.defFor(child.id);
196
+ const childOutcomeStem = childDef.outputs[0];
197
+ const childArts = this.artMap(child.id);
198
+ const childOutcomeArt = childArts.get(childOutcomeStem);
199
+ return childOutcomeArt?.version ?? -1;
200
+ }
201
+ /**
202
+ * F2: record a child input-schema refusal (from STEP 3 spawn or STEP 5
203
+ * re-provide) as a debt on the PARENT calls artifact — same shape as
204
+ * green()'s schema-reject branch (acceptance: 'rejected', schemaRejects+1,
205
+ * a 'validation' reasons entry naming the child input and the schema
206
+ * issues) — so the tick can proceed instead of throwing, and the parent
207
+ * calls artifact surfaces as a stallable debt (maxSchemaFailures/retry).
208
+ * Stamps the current gate fingerprint on the rejected artifact so the
209
+ * STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
210
+ * worth retrying" on the next tick.
211
+ */
212
+ recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, now) {
213
+ const text = `child input '${err.inputName}' failed schema: ${summarizeIssues(err.issues)}`;
214
+ this.store.tx(() => {
215
+ const art = this.store.getArtifact(parentWf, callsStem);
216
+ if (!art)
217
+ return; // not yet materialized by pendingOwed — nothing to stamp
218
+ const gateArts = this.artMap(parentWf);
219
+ const fp = computeFingerprint(gateArts, gateStems);
220
+ this.store.putArtifact({
221
+ ...art,
222
+ acceptance: 'rejected',
223
+ schemaRejects: art.schemaRejects + 1,
224
+ fingerprint: fp,
225
+ reasons: [...art.reasons, reason('schema-reject', 'validation', 'engine', text, art.version)],
226
+ });
227
+ this.settle(parentWf, def, now);
228
+ });
229
+ this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject', outcome: 'schema-rejected' });
230
+ this.fireSettled(parentWf);
231
+ }
156
232
  /**
157
233
  * M2B: Maintain all `calls:` steps for a parent workflow.
158
234
  * Called at the top of tick (outside any tx) and as cascade-up prompt.
@@ -178,6 +254,19 @@ export class Engine {
178
254
  continue;
179
255
  // STEP 2 — Look up any existing child via reverse index.
180
256
  let existingChild = this.store.findChildByParent(parentWf, callsPath);
257
+ // F2: if the parent calls artifact is already `rejected` on a schema
258
+ // refusal (see STEP 3/5 below) and the gate stems haven't moved since
259
+ // that refusal was recorded, don't re-attempt — the same value would
260
+ // just refuse again. The gate fingerprint on the rejected artifact is
261
+ // the guard; a moved gate (fingerprint mismatch) means the parent
262
+ // value may have been fixed, so fall through and retry.
263
+ const parentCallsArtPre = this.store.getArtifact(parentWf, callsStem);
264
+ if (!existingChild && parentCallsArtPre?.acceptance === 'rejected') {
265
+ const gateArtsPre = this.artMap(parentWf);
266
+ const currentGateFp = computeFingerprint(gateArtsPre, gateStems);
267
+ if (deepEqual(currentGateFp, parentCallsArtPre.fingerprint ?? {}))
268
+ continue;
269
+ }
181
270
  // STEP 3 — SPAWN or RE-ATTACH.
182
271
  if (!existingChild) {
183
272
  // SPAWN: gate is ready and no child exists yet.
@@ -187,10 +276,27 @@ export class Engine {
187
276
  if (parentArt?.value !== undefined)
188
277
  seedProvide[childInputName] = parentArt.value;
189
278
  }
190
- const childId = this.createInstance(step.calls, {
191
- producedBy: { parentWf, parentPath: callsPath },
192
- provide: seedProvide,
193
- });
279
+ // F2: a child input-schema refusal here is not a bug — a parent
280
+ // value can be legal per the parent's own schema (looser, or absent)
281
+ // yet illegal per the child's declared input schema. Catch narrowly
282
+ // (SchemaRefusalError only; anything else is a genuine bug and must
283
+ // still throw) and record it as a debt on the PARENT calls artifact,
284
+ // mirroring green()'s schema-reject branch, so the tick proceeds
285
+ // instead of crash-looping every subsequent tick(parent).
286
+ let childId;
287
+ try {
288
+ childId = this.createInstance(step.calls, {
289
+ producedBy: { parentWf, parentPath: callsPath },
290
+ provide: seedProvide,
291
+ });
292
+ }
293
+ catch (err) {
294
+ if (err instanceof SchemaRefusalError) {
295
+ this.recordCallsSchemaReject(parentWf, def, callsStem, gateStems, err, now);
296
+ continue;
297
+ }
298
+ throw err;
299
+ }
194
300
  existingChild = this.store.getWorkflow(childId);
195
301
  }
196
302
  // else: RE-ATTACH — existingChild is the already-spawned child; no new spawn.
@@ -204,11 +310,26 @@ export class Engine {
204
310
  let childArts = this.artMap(existingChild.id);
205
311
  let childOutcomeArt = childArts.get(childOutcomeStem);
206
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).
207
319
  for (const [childInputName, parentArtifactName] of Object.entries(step.callsInputs ?? {})) {
208
320
  const parentArtNow = parentArts.get(parentArtifactName);
209
321
  const childInputArt = childArts.get(childInputName);
210
322
  if (parentArtNow?.value !== undefined && !deepEqual(parentArtNow.value, childInputArt?.value)) {
211
- this.provideInput(existingChild.id, childInputName, parentArtNow.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
+ }
212
333
  }
213
334
  }
214
335
  // STEP 6 — MACHINE-GREEN or STAY OWED (M2B-CASCADEUP).
@@ -216,14 +337,29 @@ export class Engine {
216
337
  childArts = this.artMap(existingChild.id);
217
338
  childOutcomeArt = childArts.get(childOutcomeStem);
218
339
  const parentCallsArt = this.store.getArtifact(parentWf, callsStem);
340
+ // F2: don't machine-green over a schema-rejected debt — it needs a
341
+ // human `retry` (or a moved gate, handled by the guard above) before
342
+ // this step revisits it.
343
+ if (parentCallsArt?.acceptance === 'rejected')
344
+ continue;
219
345
  if (isGreen(childOutcomeArt) && childOutcomeArt?.value !== undefined) {
220
346
  const alreadyGreen = isGreen(parentCallsArt);
221
347
  const sameValue = alreadyGreen && deepEqual(childOutcomeArt.value, parentCallsArt?.value);
222
- if (!alreadyGreen || !sameValue) {
348
+ // F4: version-pinning. Only machine-green when the child outcome's
349
+ // version has moved past whatever version is currently pinned on
350
+ // the parent artifact — this is what lets a consumer's reject
351
+ // (propagated down, parent reopened to owed pinned to the rejected
352
+ // child version) or a human skip (pinned at skip time) stand until
353
+ // the child actually rebuilds past that pin, instead of being
354
+ // silently overridden on the very next tick.
355
+ const pinnedVersion = parentCallsArt?.fingerprint?.[Engine.CHILD_OUTCOME_PIN_KEY];
356
+ const pastPin = pinnedVersion === undefined || childOutcomeArt.version > pinnedVersion;
357
+ if ((!alreadyGreen || !sameValue) && pastPin) {
223
358
  if (!parentCallsArt)
224
359
  continue; // not yet materialized by pendingOwed — skip
225
360
  const gateArts = this.artMap(parentWf);
226
361
  const fp = computeFingerprint(gateArts, gateStems);
362
+ fp[Engine.CHILD_OUTCOME_PIN_KEY] = childOutcomeArt.version;
227
363
  const next = {
228
364
  ...parentCallsArt,
229
365
  acceptance: 'green',
@@ -459,6 +595,12 @@ export class Engine {
459
595
  order.workdir = step.workdir;
460
596
  if (step.model !== undefined)
461
597
  order.model = step.model;
598
+ if (step.worker !== undefined)
599
+ order.worker = step.worker;
600
+ if (step.command !== undefined)
601
+ order.command = step.command;
602
+ if (step.spec !== undefined)
603
+ order.spec = step.spec;
462
604
  if (step.x !== undefined)
463
605
  order.x = step.x;
464
606
  if (f.cause !== undefined)
@@ -505,6 +647,20 @@ export class Engine {
505
647
  this.settle(workflow, def);
506
648
  return { path, outcome: 'group-rejected', reason: groupCas.reason };
507
649
  }
650
+ // §18: a human bypass still lands a value downstream consumers assume
651
+ // is schema-valid (and which can later crash e.g. maintainCalls child
652
+ // seeding), so enforce the same produce schema the producer-commit path
653
+ // enforces (below). Unlike that path, there is no lease/retry loop to
654
+ // protect here — a schema-invalid human green is a hard refusal (thrown
655
+ // Error), not a schemaRejects-bumping soft one: no version bump, artifact
656
+ // left untouched. The judge bypass (§24.6) is untouched by this check.
657
+ const humanSchema = this.produceSchema(def, art);
658
+ if (humanSchema !== undefined) {
659
+ const check = validateValue(humanSchema, value);
660
+ if (!check.valid) {
661
+ throw new Error(`human green for '${path}' failed schema: ${summarizeIssues(check.issues)}`);
662
+ }
663
+ }
508
664
  const req = requiredInputs(def, arts, art);
509
665
  const next = {
510
666
  ...art,
@@ -672,6 +828,20 @@ export class Engine {
672
828
  this.settle(workflow, def);
673
829
  return { outcome: 'born-rejected', created: [], reason: cas.reason };
674
830
  }
831
+ // §11.1: once the seal is green the collection is complete — the offer
832
+ // side never offers collection work again, so a late `emit` on a still
833
+ // -open lease is refused rather than silently growing a "complete" set.
834
+ // Check first, don't mutate on refusal (mirrors green()'s group check):
835
+ // no counters bumped, no artifacts touched, lease stays open so the run
836
+ // can still close.
837
+ const sealForGreenCheck = arts.get(sealPath(stem));
838
+ if (sealForGreenCheck && isGreen(sealForGreenCheck)) {
839
+ return {
840
+ outcome: 'sealed-rejected',
841
+ created: [],
842
+ reason: `collection ${stem} is sealed: seal green = set complete (§11.1)`,
843
+ };
844
+ }
675
845
  // §18: every emitted element must satisfy the collection's declared schema.
676
846
  // The check is atomic — one bad item accretes nothing and bumps the seal's
677
847
  // schema-stall counter — so a producer can't half-fill a collection with
@@ -796,6 +966,16 @@ export class Engine {
796
966
  reject(workflow, path, by, text) {
797
967
  const def = this.defFor(workflow);
798
968
  this.assertAuthority(def, by, path, 'reject');
969
+ // F4: a reject on an artifact produced by a `calls:` step is a verdict on
970
+ // the CHILD's work, not the parent's own — forward it. Detection: the
971
+ // producing step declares `calls:`. The child is resolved via the
972
+ // parent→child reverse index (store.findChildByParent); if no child was
973
+ // ever spawned there is nothing to judge, so refuse (consistent with the
974
+ // verb-guard rule below that a verdict needs a built version).
975
+ const producingStep = def.steps.find((s) => s.produces.some((p) => p.stem === path));
976
+ if (producingStep?.calls) {
977
+ return this.rejectCallsArtifact(workflow, def, producingStep, path, by, text);
978
+ }
799
979
  const judgeStep = def.steps.find((s) => s.name === by);
800
980
  const judgedStem = judgeStep?.judges;
801
981
  let releasedRun;
@@ -819,6 +999,21 @@ export class Engine {
819
999
  return { outcome: 'born-rejected', reason: cas.reason };
820
1000
  }
821
1001
  }
1002
+ // §6: a judgment verdict is about a *produced* version (design §6) — refuse
1003
+ // a reject on anything that isn't currently a build (`green`) or awaiting
1004
+ // verdict (`submitted`). Two concrete wedges this closes: rejecting a
1005
+ // never-built `owed` artifact would burn a judgmentRejects toward the §6
1006
+ // stall cap with zero build attempts (a silent freeze — the producer side
1007
+ // never re-offers past the cap); rejecting a terminal `retracted` collection
1008
+ // member would flip a dead member back to a live `rejected` debt, but no
1009
+ // firing shape can ever rebuild a bare collection element (§11.3: retracted
1010
+ // is terminal, out of the live set), so the instance wedges permanently.
1011
+ // The judge-CAS branch above already guarantees `submitted` for judge
1012
+ // verdicts that reach here (a stale one already returned born-rejected),
1013
+ // so this only bites the plain/human reject path in practice.
1014
+ if (art.acceptance !== 'green' && art.acceptance !== 'submitted') {
1015
+ throw new Error(`cannot reject '${path}' in state '${art.acceptance}': a verdict requires a built version (green|submitted)`);
1016
+ }
822
1017
  // §24 §3.1/§4.4: a judge reject (or a human reject on a `submitted`
823
1018
  // artifact) is a quality verdict, not a cascade invalidation — it wins
824
1019
  // immediately regardless of any other judge's already-recorded approval,
@@ -849,12 +1044,87 @@ export class Engine {
849
1044
  this.fireSettled(workflow);
850
1045
  return result;
851
1046
  }
1047
+ /**
1048
+ * F4: forward a reject on a `calls:`-produced artifact to the CHILD's
1049
+ * outcome artifact, then reopen the parent calls artifact to `owed` pinned
1050
+ * (via `childOutcomePin`) to the just-rejected child outcome version, so
1051
+ * STEP 6's mirror only fires again once the child has actually rebuilt past
1052
+ * this verdict (§ F4 settled design).
1053
+ *
1054
+ * The forward is engine-internal: authority was already checked against the
1055
+ * PARENT def by `assertAuthority` in `reject()` above, so the child's own
1056
+ * `assertAuthority` is not consulted — the author recorded on the child's
1057
+ * reasons entry is `parent:<by>` to make the indirection visible in its
1058
+ * audit thread.
1059
+ */
1060
+ rejectCallsArtifact(parentWf, def, producingStep, callsStem, by, text) {
1061
+ const child = this.store.findChildByParent(parentWf, callsStem);
1062
+ if (!child) {
1063
+ throw new Error(`cannot reject '${callsStem}': no child instance has been spawned yet (a verdict requires a built version)`);
1064
+ }
1065
+ const childDef = this.defFor(child.id);
1066
+ const childOutcomeStem = childDef.outputs[0];
1067
+ this.store.tx(() => {
1068
+ const parentArt = this.store.getArtifact(parentWf, callsStem);
1069
+ if (!parentArt)
1070
+ throw new Error(`cannot reject unknown artifact: ${callsStem}`);
1071
+ if (parentArt.acceptance !== 'green' && parentArt.acceptance !== 'submitted') {
1072
+ throw new Error(`cannot reject '${callsStem}' in state '${parentArt.acceptance}': a verdict requires a built version (green|submitted)`);
1073
+ }
1074
+ const childArt = this.store.getArtifact(child.id, childOutcomeStem);
1075
+ if (!childArt)
1076
+ throw new Error(`cannot reject '${callsStem}': child outcome artifact missing`);
1077
+ // Child outcome → rejected, judgmentRejects+1, author `parent:<by>`.
1078
+ this.store.putArtifact({
1079
+ ...childArt,
1080
+ acceptance: 'rejected',
1081
+ judgmentRejects: childArt.judgmentRejects + 1,
1082
+ approvals: undefined,
1083
+ reasons: [...childArt.reasons, reason('reject', 'judgment', `parent:${by}`, text, childArt.version)],
1084
+ });
1085
+ this.settle(child.id, childDef);
1086
+ // Parent calls artifact → reopened to owed (not left rejected), pinned
1087
+ // to the just-rejected child outcome version.
1088
+ this.store.putArtifact({
1089
+ ...parentArt,
1090
+ acceptance: 'owed',
1091
+ fingerprint: { ...(parentArt.fingerprint ?? {}), [Engine.CHILD_OUTCOME_PIN_KEY]: childArt.version },
1092
+ reasons: [
1093
+ ...parentArt.reasons,
1094
+ {
1095
+ at: nowMs(),
1096
+ action: 'reopen',
1097
+ kind: 'structural',
1098
+ by: 'engine',
1099
+ text: `reject forwarded to child outcome '${childOutcomeStem}': ${text}`,
1100
+ fromVersion: parentArt.version,
1101
+ },
1102
+ ],
1103
+ });
1104
+ this.settle(parentWf, def);
1105
+ });
1106
+ this.fire({ type: 'commit', workflow: parentWf, path: callsStem, action: 'reject' });
1107
+ this.fireSettled(parentWf);
1108
+ // The child's own firings (re-arming its producer with the feedback on
1109
+ // its owes thread) need tick(child) — not driven from here; see docs/design.md
1110
+ // M2/M2B "sweeping" note. Prompt maintainCalls now so the parent's own
1111
+ // state (owed/pin) is visible immediately, mirroring provideInput's cascade.
1112
+ this.maintainCalls(parentWf, def);
1113
+ return { outcome: 'rejected' };
1114
+ }
852
1115
  /** Retract a collection member (§11.3): drop it, terminally; abandon the index. */
853
1116
  retract(workflow, path, by, text) {
854
1117
  const def = this.defFor(workflow);
855
1118
  const el = parseElement(path);
856
1119
  if (!el || el.suffix !== '')
857
1120
  throw new Error(`retract is only valid on a collection member: ${path}`);
1121
+ // §4.1/§11.3: same authority rule as reject — only a consumer of the member's
1122
+ // stem (or human/engine) may drop it. Without this, any string actor name
1123
+ // (even one not in the def) could terminally retract a green member of a
1124
+ // sealed collection. assertAuthority resolves an element path to its stem
1125
+ // via parseElement internally, so `path` (not `el.stem`) is passed straight
1126
+ // through, same as reject().
1127
+ this.assertAuthority(def, by, path, 'retract');
858
1128
  this.store.tx(() => {
859
1129
  const art = this.store.getArtifact(workflow, path);
860
1130
  if (!art)
@@ -883,10 +1153,22 @@ export class Engine {
883
1153
  // Fingerprint the inputs this skip rests on, so the level-trigger only
884
1154
  // re-arms the branch when those inputs *move* (§16.1), not merely stay green.
885
1155
  const req = requiredInputs(def, arts, art);
1156
+ const fp = computeFingerprint(arts, req);
1157
+ // F4: a calls: step declares `consumes: []`, so `req` above never sees
1158
+ // its real input — the child outcome, which lives in another instance.
1159
+ // Capture the same version pin `childOutcomePin` uses elsewhere, so a
1160
+ // skip made on evidence from child version N survives arbitrary ticks
1161
+ // (order A) until the child actually rebuilds past N (order B).
1162
+ const producingStep = def.steps.find((s) => s.name === art.producer);
1163
+ if (producingStep?.calls) {
1164
+ const pin = this.childOutcomePin(workflow, path);
1165
+ if (pin !== undefined)
1166
+ fp[Engine.CHILD_OUTCOME_PIN_KEY] = pin;
1167
+ }
886
1168
  this.store.putArtifact({
887
1169
  ...art,
888
1170
  acceptance: 'skipped',
889
- fingerprint: computeFingerprint(arts, req),
1171
+ fingerprint: fp,
890
1172
  reasons: [...art.reasons, reason('skip', 'structural', by, text, art.version)],
891
1173
  });
892
1174
  this.settle(workflow, def);
@@ -903,10 +1185,21 @@ export class Engine {
903
1185
  */
904
1186
  retry(workflow, path, by = 'human', text = 'retry: stall cleared') {
905
1187
  const def = this.defFor(workflow);
1188
+ // §4.1: same authority rule as reject/retract — only a consumer of the
1189
+ // stem (or human/engine) may re-arm it.
1190
+ this.assertAuthority(def, by, path, 'retry');
906
1191
  this.store.tx(() => {
907
1192
  const art = this.store.getArtifact(workflow, path);
908
1193
  if (!art)
909
1194
  throw new Error(`cannot retry unknown artifact: ${path}`);
1195
+ // §11.3: retry re-arms to `owed`, but a bare collection element that has
1196
+ // been retracted has no producer firing that can ever rebuild it — retry
1197
+ // would resurrect a terminally-dropped member into a guaranteed wedge.
1198
+ // `retract` is final by design; every other state (rejected, stalled,
1199
+ // skipped, green) stays a legal retry target.
1200
+ if (art.acceptance === 'retracted') {
1201
+ throw new Error(`cannot retry '${path}': it was retracted, which is terminal (use a fresh collection element instead)`);
1202
+ }
910
1203
  this.store.putArtifact({
911
1204
  ...art,
912
1205
  acceptance: 'owed',
@@ -1296,9 +1589,15 @@ export class Engine {
1296
1589
  // re-arms when the upstream branch revives (mirrors a producer skip).
1297
1590
  // §26: an auto-skip of a losing group sibling tags rejectKind 'exclusive'
1298
1591
  // instead of the default 'structural' (op.rejectKind carries this).
1592
+ // §26.2: if the skipped sibling was `submitted` (awaiting judgment), it
1593
+ // may be carrying a partial approvals sign-off — clear it the same way
1594
+ // a cascade reject does (§24 §4.3), so a stale sign-off never leaks onto
1595
+ // a later resubmission if the winner is un-greened and the branch revives.
1596
+ const clearApprovals = art.acceptance === 'submitted' && art.approvals !== undefined;
1299
1597
  this.store.putArtifact({
1300
1598
  ...art,
1301
1599
  acceptance: 'skipped',
1600
+ ...(clearApprovals ? { approvals: undefined } : {}),
1302
1601
  fingerprint: computeFingerprint(arts, requiredInputs(def, arts, art)),
1303
1602
  reasons: [...art.reasons, reason('skip', op.rejectKind ?? 'structural', 'engine', op.reason, art.version)],
1304
1603
  });
package/dist/model.js CHANGED
@@ -657,13 +657,17 @@ export function maintainDecisions(def, arts, time) {
657
657
  }
658
658
  // §26: declarative exclusive produce-groups — auto-skip losing siblings.
659
659
  // Once a group (exactlyOne/atMostOne) has a green winner, every other member
660
- // still resting in a debt state (owed/rejected) can never legally commit —
661
- // the group's exclusivity is enforced at commit time by the engine's
662
- // groupCasCheck, so those siblings would just stall forever without this.
663
- // Auto-skip settles them; the ordinary skipped-artifact rearm loop above
664
- // (which runs on the artifact's own next maintenance pass) revives them if
665
- // the winner is later un-greened (rejected/retracted) and the group's
666
- // fingerprint-gated inputs move again — no separate rearm code is needed.
660
+ // still resting in a debt state (owed/rejected) or awaiting judgment
661
+ // (submitted) can never legally commit — the group's exclusivity is
662
+ // enforced at commit time by the engine's groupCasCheck, so those siblings
663
+ // would just stall forever without this. A submitted sibling in particular
664
+ // is an OUTSTANDING state; left alone the instance can never reach
665
+ // done: true. Auto-skip settles them (clearing any partial approvals so a
666
+ // later resubmission never inherits a stale sign-off); the ordinary
667
+ // skipped-artifact rearm loop above (which runs on the artifact's own next
668
+ // maintenance pass) revives them if the winner is later un-greened
669
+ // (rejected/retracted) and the group's fingerprint-gated inputs move again
670
+ // — no separate rearm code is needed.
667
671
  for (const step of def.steps) {
668
672
  if (!step.groups || step.groups.length === 0)
669
673
  continue;
@@ -679,7 +683,9 @@ export function maintainDecisions(def, arts, time) {
679
683
  const sib = arts.get(stem);
680
684
  if (!sib)
681
685
  continue;
682
- if (sib.acceptance !== 'owed' && sib.acceptance !== 'rejected')
686
+ if (sib.acceptance !== 'owed' &&
687
+ sib.acceptance !== 'rejected' &&
688
+ sib.acceptance !== 'submitted')
683
689
  continue; // already skipped/retracted/green
684
690
  ops.push({
685
691
  kind: 'skip',
@@ -1426,10 +1432,15 @@ function applyOpInMemory(arts, def, op) {
1426
1432
  return;
1427
1433
  }
1428
1434
  if (op.kind === 'skip') {
1429
- // mirrors Engine.applyOp skip branch: acceptance → 'skipped' + fingerprint
1435
+ // mirrors Engine.applyOp skip branch: acceptance → 'skipped' + fingerprint.
1436
+ // §26.2: also mirrors the approvals-clear now applied on the engine side —
1437
+ // a submitted sibling auto-skipped out of a losing group must not carry a
1438
+ // stale partial sign-off into a later re-arm.
1439
+ const clearApprovals = art.acceptance === 'submitted' && art.approvals !== undefined;
1430
1440
  arts.set(op.path, {
1431
1441
  ...art,
1432
1442
  acceptance: 'skipped',
1443
+ ...(clearApprovals ? { approvals: undefined } : {}),
1433
1444
  fingerprint: computeFingerprint(arts, requiredInputs(def, arts, art)),
1434
1445
  });
1435
1446
  return;
package/dist/store.js CHANGED
@@ -434,7 +434,10 @@ export class Store {
434
434
  }
435
435
  // -- artifact ----------------------------------------------------------------
436
436
  getArtifact(workflow, path) {
437
- return this.getArtifactById(artifactId(workflow, path));
437
+ const r = this.db
438
+ .prepare('SELECT * FROM artifact WHERE workflow = ? AND path = ?')
439
+ .get(workflow, path);
440
+ return r ? mapArtifact(r) : undefined;
438
441
  }
439
442
  getArtifactById(id) {
440
443
  const r = this.db.prepare('SELECT * FROM artifact WHERE id = ?').get(id);
@@ -456,7 +459,7 @@ export class Store {
456
459
  reasons, judgment_rejects, schema_rejects, seal_of, terminal, approvals, updated_at)
457
460
  VALUES (@id, @workflow, @path, @producer, @acceptance, @version, @value, @fingerprint,
458
461
  @reasons, @judgment_rejects, @schema_rejects, @seal_of, @terminal, @approvals, @updated_at)
459
- ON CONFLICT(id) DO UPDATE SET
462
+ ON CONFLICT(workflow, path) DO UPDATE SET
460
463
  producer = excluded.producer,
461
464
  acceptance = excluded.acceptance,
462
465
  version = excluded.version,
@@ -486,14 +489,16 @@ export class Store {
486
489
  approvals: toJson(data.approvals),
487
490
  updated_at: at,
488
491
  });
489
- return this.getArtifactById(id);
492
+ return this.getArtifact(data.workflow, data.path);
490
493
  }
491
494
  deleteArtifact(workflow, path) {
492
- this.db.prepare('DELETE FROM artifact WHERE id = ?').run(artifactId(workflow, path));
495
+ this.db.prepare('DELETE FROM artifact WHERE workflow = ? AND path = ?').run(workflow, path);
493
496
  }
494
497
  // -- task --------------------------------------------------------------------
495
498
  getTask(workflow, step, key) {
496
- const r = this.db.prepare('SELECT * FROM task WHERE id = ?').get(taskId(workflow, step, key));
499
+ const r = this.db
500
+ .prepare('SELECT * FROM task WHERE workflow = ? AND step = ? AND key = ?')
501
+ .get(workflow, step, key);
497
502
  return r ? mapTask(r) : undefined;
498
503
  }
499
504
  listTasks(workflow) {
@@ -514,7 +519,7 @@ export class Store {
514
519
  this.db
515
520
  .prepare(`INSERT INTO task (id, workflow, step, key, status, run, claimed_at, attempts, alarm_at, heartbeat_at, updated_at)
516
521
  VALUES (@id, @workflow, @step, @key, @status, @run, @claimed_at, @attempts, @alarm_at, @heartbeat_at, @updated_at)
517
- ON CONFLICT(id) DO UPDATE SET
522
+ ON CONFLICT(workflow, step, key) DO UPDATE SET
518
523
  status = excluded.status,
519
524
  run = excluded.run,
520
525
  claimed_at = excluded.claimed_at,
@@ -544,11 +549,10 @@ export class Store {
544
549
  }
545
550
  /** Persist an absolute alarm time for an idle evaluator step. */
546
551
  setAlarm(workflow, step, at) {
547
- const id = taskId(workflow, step, '');
548
552
  const existing = this.getTask(workflow, step, '');
549
553
  if (existing) {
550
- this.db.prepare('UPDATE task SET alarm_at = ?, updated_at = ? WHERE id = ?')
551
- .run(at, nowMs(), id);
554
+ this.db.prepare('UPDATE task SET alarm_at = ?, updated_at = ? WHERE workflow = ? AND step = ? AND key = ?')
555
+ .run(at, nowMs(), workflow, step, '');
552
556
  }
553
557
  else {
554
558
  // Rare: evaluator step has never been ticked. Insert a minimal idle row.
@@ -557,14 +561,12 @@ export class Store {
557
561
  }
558
562
  /** Clear the alarm (set alarm_at = NULL). */
559
563
  clearAlarm(workflow, step) {
560
- const id = taskId(workflow, step, '');
561
- this.db.prepare('UPDATE task SET alarm_at = NULL, updated_at = ? WHERE id = ?')
562
- .run(nowMs(), id);
564
+ this.db.prepare('UPDATE task SET alarm_at = NULL, updated_at = ? WHERE workflow = ? AND step = ? AND key = ?')
565
+ .run(nowMs(), workflow, step, '');
563
566
  }
564
567
  /** Update only heartbeat_at on the task row — targeted write, no read-modify-write. */
565
568
  touchHeartbeat(workflow, step, key, now) {
566
- const id = taskId(workflow, step, key);
567
- this.db.prepare('UPDATE task SET heartbeat_at = ?, updated_at = ? WHERE id = ?').run(now, nowMs(), id);
569
+ this.db.prepare('UPDATE task SET heartbeat_at = ?, updated_at = ? WHERE workflow = ? AND step = ? AND key = ?').run(now, nowMs(), workflow, step, key);
568
570
  }
569
571
  /**
570
572
  * Derive last_progress as MAX(artifact.updated_at) for the workflow.
package/dist/types.d.ts CHANGED
@@ -173,6 +173,17 @@ export interface ProducePattern {
173
173
  inputs?: boolean;
174
174
  cadence?: string;
175
175
  maxRunsPerDay?: number;
176
+ /** Declares which kind of executor this judge's synthesized order is for.
177
+ * Same opaque-passthrough contract as StepDef.worker — default 'agent'
178
+ * when omitted. */
179
+ worker?: string;
180
+ /** Required when worker is 'command'; the command string for that worker
181
+ * to run. Opaque to the engine — never parsed, never shelled out. */
182
+ command?: string;
183
+ /** Optional opaque config object for a non-agent/non-command worker type
184
+ * (or additionally alongside `command`). Shape-checked as a plain map
185
+ * only (mirrors `x:`'s asExtension contract) — contents never read. */
186
+ spec?: Record<string, unknown>;
176
187
  }>;
177
188
  }
178
189
  /**
@@ -227,6 +238,19 @@ export interface StepDef {
227
238
  * model.ts effectiveMaxSchemaFailures()). */
228
239
  maxSchemaFailures: number;
229
240
  model?: string;
241
+ /** Declares which kind of executor this step's order is for. Default
242
+ * 'agent' when omitted (today's behavior — every existing def is
243
+ * unchanged). Opaque to the engine beyond the shape rules validateDef
244
+ * enforces; carried through verbatim on the Order, same contract as
245
+ * `model`. */
246
+ worker?: string;
247
+ /** Required when worker is 'command'; the command string for that worker
248
+ * to run. Opaque to the engine — never parsed, never shelled out. */
249
+ command?: string;
250
+ /** Optional opaque config object for a non-agent/non-command worker type
251
+ * (or additionally alongside `command`). Shape-checked as a plain map
252
+ * only (mirrors `x:`'s asExtension contract) — contents never read. */
253
+ spec?: Record<string, unknown>;
230
254
  /** opaque location hint passed through on the order; no default — absent unless the def sets it */
231
255
  workdir?: string;
232
256
  /** the step's output is a destructive completion (e.g. a merge): green is terminal (§15.2) */
@@ -283,6 +307,10 @@ export interface WorkflowDef {
283
307
  /** §27.3: opaque workflow-level extension map (`x:`). Validated as a plain
284
308
  * map at load time, never interpreted by the engine. */
285
309
  x?: Record<string, unknown>;
310
+ /** Optional allow-list of worker values; when present, validateDef errors
311
+ * on any step/judge whose `worker` is not in this list (typo guard).
312
+ * Absent = any worker string accepted. */
313
+ workers?: string[];
286
314
  }
287
315
  export interface InputDef {
288
316
  name: string;