owenloop 0.5.8 → 0.5.10

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.
Files changed (131) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +81 -39
  3. package/bin/owenloop.mjs +16 -1
  4. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  5. package/dist/packages/work/src/agent/loop.js +55 -6
  6. package/dist/packages/work/src/bundle/pull.d.ts +21 -0
  7. package/dist/packages/work/src/bundle/pull.js +118 -0
  8. package/dist/packages/work/src/consumed-verifier.js +6 -17
  9. package/dist/packages/work/src/exec/instructions.d.ts +4 -1
  10. package/dist/packages/work/src/exec/instructions.js +3 -0
  11. package/dist/packages/work/src/exec/loop.d.ts +2 -2
  12. package/dist/packages/work/src/exec/loop.js +273 -46
  13. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  14. package/dist/packages/work/src/exec/receipt.js +6 -6
  15. package/dist/packages/work/src/harness/claude.js +116 -0
  16. package/dist/packages/work/src/harness/codex.d.ts +8 -0
  17. package/dist/packages/work/src/harness/codex.js +27 -1
  18. package/dist/packages/work/src/harness/contract.d.ts +9 -0
  19. package/dist/packages/work/src/hub/client.d.ts +19 -4
  20. package/dist/packages/work/src/hub/client.js +7 -3
  21. package/dist/packages/work/src/hub/types.d.ts +84 -0
  22. package/dist/packages/work/src/main.js +1 -0
  23. package/dist/packages/work/src/roles/agent-run.js +57 -32
  24. package/dist/packages/work/src/roles/exec.js +27 -8
  25. package/dist/packages/work/src/roles/settings.js +2 -0
  26. package/dist/packages/work/src/roles/shift.js +14 -2
  27. package/dist/packages/work/src/roles/util.d.ts +1 -0
  28. package/dist/packages/work/src/roles/util.js +10 -0
  29. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  30. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  31. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  32. package/dist/packages/work/src/settings/roster.js +364 -5
  33. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  34. package/dist/packages/work/src/settings/serving.js +79 -0
  35. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  36. package/dist/packages/work/src/settings/settings.js +14 -0
  37. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  38. package/dist/packages/work/src/shift/loop.js +416 -54
  39. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  40. package/dist/packages/work/src/shift/runtime.d.ts +18 -0
  41. package/dist/packages/work/src/shift/runtime.js +104 -5
  42. package/dist/packages/work/src/shift/server.js +2 -0
  43. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  44. package/dist/packages/work/src/shift/spawn.js +16 -13
  45. package/dist/packages/work/src/shift/state.d.ts +29 -2
  46. package/dist/packages/work/src/shift/state.js +45 -15
  47. package/dist/packages/work/src/submit-proof.d.ts +11 -8
  48. package/dist/packages/work/src/submit-proof.js +11 -8
  49. package/dist/packages/work/src/usage.d.ts +1 -1
  50. package/dist/packages/work/src/usage.js +7 -1
  51. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  52. package/dist/packages/work/src/util/modifier-init.js +73 -0
  53. package/dist/src/bundle/tar.d.ts +9 -4
  54. package/dist/src/bundle/tar.js +9 -4
  55. package/dist/src/capabilities.d.ts +76 -6
  56. package/dist/src/capabilities.js +49 -6
  57. package/dist/src/capability-mapping-client.d.ts +29 -0
  58. package/dist/src/capability-mapping-client.js +160 -0
  59. package/dist/src/cli.d.ts +16 -3
  60. package/dist/src/cli.js +1925 -281
  61. package/dist/src/config-dir.d.ts +1 -1
  62. package/dist/src/config-dir.js +1 -1
  63. package/dist/src/crypto/index.d.ts +1 -1
  64. package/dist/src/crypto/index.js +1 -1
  65. package/dist/src/crypto/org-root.d.ts +30 -12
  66. package/dist/src/crypto/org-root.js +162 -14
  67. package/dist/src/crypto/records.d.ts +2 -0
  68. package/dist/src/crypto/records.js +2 -0
  69. package/dist/src/defs.d.ts +38 -2
  70. package/dist/src/defs.js +593 -86
  71. package/dist/src/engine.d.ts +103 -25
  72. package/dist/src/engine.js +331 -79
  73. package/dist/src/hub.d.ts +77 -0
  74. package/dist/src/hub.js +162 -0
  75. package/dist/src/implements.d.ts +56 -0
  76. package/dist/src/implements.js +790 -0
  77. package/dist/src/index.d.ts +11 -9
  78. package/dist/src/index.js +6 -5
  79. package/dist/src/mcp/serve.d.ts +22 -0
  80. package/dist/src/mcp/serve.js +330 -41
  81. package/dist/src/mcp/server.d.ts +10 -7
  82. package/dist/src/mcp/server.js +53 -8
  83. package/dist/src/model.d.ts +48 -10
  84. package/dist/src/model.js +252 -99
  85. package/dist/src/order-resolver.d.ts +1 -0
  86. package/dist/src/order-resolver.js +8 -1
  87. package/dist/src/schemas/index.d.ts +11 -0
  88. package/dist/src/schemas/order.v1.schema.json +7 -1
  89. package/dist/src/store/def-source.d.ts +19 -0
  90. package/dist/src/store/def-source.js +87 -17
  91. package/dist/src/store/gc-recovery.d.ts +46 -0
  92. package/dist/src/store/gc-recovery.js +258 -0
  93. package/dist/src/store/gc.d.ts +94 -0
  94. package/dist/src/store/gc.js +562 -0
  95. package/dist/src/store/index.d.ts +3 -1
  96. package/dist/src/store/index.js +2 -0
  97. package/dist/src/store/install.d.ts +34 -5
  98. package/dist/src/store/install.js +73 -11
  99. package/dist/src/store/pre-commit-verifier.js +42 -2
  100. package/dist/src/store/snapshot-guard.d.ts +18 -0
  101. package/dist/src/store/snapshot-guard.js +94 -0
  102. package/dist/src/store.d.ts +69 -4
  103. package/dist/src/store.js +254 -16
  104. package/dist/src/types.d.ts +101 -20
  105. package/dist/src/util.js +4 -1
  106. package/docs/authoring.md +235 -10
  107. package/docs/bundles.md +45 -2
  108. package/docs/cli.md +437 -55
  109. package/docs/crypto.md +32 -10
  110. package/docs/design.md +177 -47
  111. package/docs/evals/mcp-charter-baseline.json +428 -0
  112. package/docs/mcp-charter-eval.md +124 -0
  113. package/docs/routing.md +189 -34
  114. package/docs/shift-logs.md +38 -9
  115. package/docs/wire-contracts.md +78 -14
  116. package/examples/workflows/compile-dev-playbook.yaml +1 -1
  117. package/examples/workflows/delivery.yaml +31 -14
  118. package/examples/workflows/ship.yaml +38 -4
  119. package/package.json +2 -1
  120. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  121. package/plugins/claude-code/plugin/.mcp.json +1 -1
  122. package/plugins/claude-code/plugin/skills/author/SKILL.md +22 -0
  123. package/plugins/claude-code/plugin/skills/ephemeral/SKILL.md +95 -0
  124. package/plugins/claude-code/plugin/skills/graduate/SKILL.md +156 -0
  125. package/plugins/claude-code/plugin/skills/plan/SKILL.md +236 -0
  126. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  127. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  128. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +22 -0
  129. package/plugins/codex/plugins/owenloop/skills/ephemeral/SKILL.md +95 -0
  130. package/plugins/codex/plugins/owenloop/skills/graduate/SKILL.md +156 -0
  131. package/plugins/codex/plugins/owenloop/skills/plan/SKILL.md +236 -0
package/dist/src/model.js CHANGED
@@ -11,6 +11,17 @@
11
11
  */
12
12
  import { bindProduce, elementPath, isMemberOf, parseElement, sealPath, sealStem, } from "./paths.js";
13
13
  import { DEBT_STATES, OUTSTANDING_STATES, SETTLED_STATES } from "./types.js";
14
+ /**
15
+ * Time facts used only when classifying a model-checker no-moves state. This
16
+ * asks whether elapsed idle time could release a move; it deliberately does
17
+ * not make time an input to BFS expansion or canonical state identity.
18
+ */
19
+ const EVENTUAL_TIME_FACTS = {
20
+ now: Number.POSITIVE_INFINITY,
21
+ lastProgressMs: 0,
22
+ inFlight: false,
23
+ alarms: new Map(),
24
+ };
14
25
  // ---- step shape classification ----------------------------------------------
15
26
  export function mapConsume(step) {
16
27
  return step.consumes.find((c) => c.mode === 'map');
@@ -43,6 +54,10 @@ export function judgeNameOf(step) {
43
54
  export function mapProduce(step) {
44
55
  return step.produces.find((p) => p.kind === 'map');
45
56
  }
57
+ /** All per-element outputs a map step owns for each input index. */
58
+ export function mapProduces(step) {
59
+ return step.produces.filter((p) => p.kind === 'map');
60
+ }
46
61
  /**
47
62
  * The concrete input artifact a map element binds on for index `i`. Normally the
48
63
  * bare collection member `stem[i]`. But when the map consume carries a suffix
@@ -81,6 +96,24 @@ export function isDebt(a) {
81
96
  export function isGreen(a) {
82
97
  return !!a && a.acceptance === 'green';
83
98
  }
99
+ /** The newest skip event wins: later structural routing can supersede an older exclusive skip. */
100
+ function latestSkipKind(art) {
101
+ for (let i = art.reasons.length - 1; i >= 0; i--) {
102
+ const reason = art.reasons[i];
103
+ if (reason.action === 'skip')
104
+ return reason.kind;
105
+ }
106
+ return undefined;
107
+ }
108
+ /** Only engine-authored structural skips are dead-branch cascades eligible for gate revival. */
109
+ function isEngineStructuralSkip(art) {
110
+ for (let i = art.reasons.length - 1; i >= 0; i--) {
111
+ const reason = art.reasons[i];
112
+ if (reason.action === 'skip')
113
+ return reason.kind === 'structural' && reason.by === 'engine';
114
+ }
115
+ return false;
116
+ }
84
117
  /**
85
118
  * §6 liveness: a judgment-rejected artifact that has been knocked back `cap`
86
119
  * times has *stalled*. It stays a debt (so it surfaces as stuck), but the engine
@@ -390,6 +423,18 @@ export function requiredInputs(def, arts, art) {
390
423
  }
391
424
  return plain;
392
425
  }
426
+ /**
427
+ * Dependencies used only by maintenance. A calls step's `callsInputs` are its
428
+ * scheduling gate and its dead-branch edge, but deliberately do not belong to
429
+ * `requiredInputs()`: that function defines build fingerprints, while live
430
+ * calls outputs also carry a child-outcome pin key.
431
+ */
432
+ function maintenanceInputs(def, arts, art) {
433
+ const step = stepByName(def, art.producer);
434
+ if (step?.calls)
435
+ return Object.values(step.callsInputs ?? {});
436
+ return requiredInputs(def, arts, art);
437
+ }
393
438
  /** The {path → version} snapshot over a set of input paths. */
394
439
  export function computeFingerprint(arts, paths) {
395
440
  const fp = {};
@@ -451,8 +496,8 @@ export function pendingOwed(def, arts) {
451
496
  const mode = stepMode(step);
452
497
  if (mode === 'map') {
453
498
  const mc = mapConsume(step);
454
- const mp = mapProduce(step);
455
- if (!mc || !mp)
499
+ const mps = mapProduces(step);
500
+ if (!mc || mps.length === 0)
456
501
  continue;
457
502
  // the bare members fix the index space; a child is owed only once that
458
503
  // index's actual consumed input (bare member, or its suffixed child) greens
@@ -462,7 +507,8 @@ export function pendingOwed(def, arts) {
462
507
  continue;
463
508
  if (!isGreen(arts.get(mapInputPath(mc, el.index))))
464
509
  continue;
465
- ensure(bindProduce(mp, el.index), step.name);
510
+ for (const mp of mps)
511
+ ensure(bindProduce(mp, el.index), step.name);
466
512
  }
467
513
  }
468
514
  else {
@@ -503,7 +549,10 @@ function idleEligible(step, arts, time) {
503
549
  }
504
550
  /**
505
551
  * Is a `calls:` step's gate ready in this state — i.e. is every parent artifact
506
- * wired into `callsInputs` green?
552
+ * wired into `callsInputs` green? Those stems are also the maintenance
553
+ * dead-input edges for the calls output. They intentionally remain absent from
554
+ * `StepDef.consumes` and `requiredInputs()`, which define build fingerprints:
555
+ * a live calls output additionally carries its child-outcome pin.
507
556
  *
508
557
  * This is the model-side mirror of `Engine.callsGateReady` (engine.ts) and MUST
509
558
  * read the same field it does: `callsInputs`, the mapping {child input name →
@@ -534,9 +583,10 @@ function callsGateReady(step, arts) {
534
583
  * deadlock/stall branch, which relabelled EVERY zero-firing state in the def —
535
584
  * so one unrelated `calls:` step anywhere in a def suppressed every genuine
536
585
  * deadlock in it. Modeling the discharge as a successor state instead keeps the
537
- * classification strictly per-state: the child greens ITS OWN artifact and
538
- * nothing else, so a deadlock elsewhere in the same def is still reached and
539
- * still reported.
586
+ * classification strictly per-state: the synthetic green represents the
587
+ * opaque completion of the whole child plus exposure of its one declared
588
+ * output, and nothing else in the parent changes. A deadlock elsewhere in the
589
+ * same def is therefore still reached and still reported.
540
590
  *
541
591
  * Kept separate from `eligibleFirings` deliberately: that function is the LIVE
542
592
  * engine scheduler and a `calls:` step must never become a worker order. These
@@ -561,6 +611,49 @@ function callsDischargeFirings(def, arts) {
561
611
  }
562
612
  return firings;
563
613
  }
614
+ /**
615
+ * The model-only collection-member retractions available in THIS state.
616
+ *
617
+ * `Engine.retract()` is an authority action rather than a scheduler action:
618
+ * every existing bare member that is not already retracted remains available
619
+ * to each authorized non-judge consumer. In particular, the transition must
620
+ * remain available after rejection, when a member has no ordinary map firing;
621
+ * otherwise modelCheck would call that runtime-valid state a deadlock.
622
+ *
623
+ * Kept separate from `eligibleFirings` deliberately: that function is the
624
+ * live worker scheduler, while these synthetic firings are consumed only by
625
+ * modelCheck's successor expansion.
626
+ */
627
+ export function memberRetractFirings(def, arts) {
628
+ const members = [...arts.values()]
629
+ .flatMap((art) => {
630
+ const el = parseElement(art.path);
631
+ return el && el.suffix === '' && art.acceptance !== 'retracted' ? [{ art, el }] : [];
632
+ })
633
+ .sort((a, b) => a.el.stem.localeCompare(b.el.stem) || a.el.index - b.el.index || a.art.path.localeCompare(b.art.path));
634
+ const firings = [];
635
+ for (const step of def.steps) {
636
+ // Synthesized judges may only invalidate the singleton in their `judges:`
637
+ // marker; their read-only context consumes grant no member-retract authority.
638
+ if (step.judges !== undefined)
639
+ continue;
640
+ for (const { art, el } of members) {
641
+ // Match Engine.assertAuthority's defensive exact-path comparison as well
642
+ // as its normal stem comparison. `some` also deduplicates repeated edges.
643
+ if (!step.consumes.some((consume) => consume.stem === el.stem || consume.stem === art.path))
644
+ continue;
645
+ firings.push({
646
+ modelTransition: 'member-retract',
647
+ step: step.name,
648
+ key: art.path,
649
+ index: el.index,
650
+ inputs: [],
651
+ outputs: [art.path],
652
+ });
653
+ }
654
+ }
655
+ return firings;
656
+ }
564
657
  /**
565
658
  * Every firing eligible *right now* — inputs satisfied AND an owed/rejected
566
659
  * output to discharge. This is the scheduling gate (§11.4): necessary, not
@@ -627,8 +720,8 @@ export function eligibleFirings(def, arts, time, opts) {
627
720
  else if (mode === 'map') {
628
721
  if (plainSatisfied) {
629
722
  const mc = mapConsume(step);
630
- const mp = mapProduce(step);
631
- if (mc && mp) {
723
+ const mps = mapProduces(step);
724
+ if (mc && mps.length > 0) {
632
725
  for (const m of members(arts, mc.stem)) {
633
726
  const el = parseElement(m.path);
634
727
  if (!el)
@@ -638,22 +731,25 @@ export function eligibleFirings(def, arts, time, opts) {
638
731
  const inPath = mapInputPath(mc, el.index);
639
732
  if (!isGreen(arts.get(inPath)))
640
733
  continue;
641
- const outPath = bindProduce(mp, el.index);
642
- const outArt = arts.get(outPath);
643
- // group: membership is singleton-only (§26.3), so a map-produce outPath can
644
- // never be a group member today — this check is defensive, not reachable,
645
- // and exists so a future relaxation of the singleton-only restriction can't
646
- // silently reopen the eligibility/commit-check gap this file fixes.
647
- if (!isDebt(outArt) ||
648
- (!opts?.ignoreFreeze && frozen(outArt, step)) ||
649
- groupBlockingWinner(def, arts, outPath) !== undefined)
734
+ const outputs = mps
735
+ .map((mp) => bindProduce(mp, el.index))
736
+ .filter((outPath) => {
737
+ const outArt = arts.get(outPath);
738
+ // Group membership is singleton-only (§26.3), so a map-produce
739
+ // path cannot be a group member today. Keep the defensive check
740
+ // so a future relaxation cannot reopen the eligibility/commit gap.
741
+ return isDebt(outArt)
742
+ && (opts?.ignoreFreeze || !frozen(outArt, step))
743
+ && groupBlockingWinner(def, arts, outPath) === undefined;
744
+ });
745
+ if (outputs.length === 0)
650
746
  continue;
651
747
  firings.push({
652
748
  step: step.name,
653
749
  key: m.path,
654
750
  index: el.index,
655
751
  inputs: [inPath, ...plainPaths],
656
- outputs: [outPath],
752
+ outputs,
657
753
  });
658
754
  }
659
755
  }
@@ -808,7 +904,7 @@ export function canEverFire(step, def, reachable) {
808
904
  case 'reduce':
809
905
  return singletonProduces(step).length > 0;
810
906
  case 'map':
811
- return !!mapProduce(step) && !!mapConsume(step);
907
+ return mapProduces(step).length > 0 && !!mapConsume(step);
812
908
  case 'plain':
813
909
  return plainOutputs(step).length > 0;
814
910
  default:
@@ -820,9 +916,11 @@ export function canEverFire(step, def, reachable) {
820
916
  * The standing guard: re-derive the invariant "an artifact is green only while
821
917
  * every artifact it directly consumed is green and unmoved" and report the
822
918
  * structural ops needed to restore it. Pure — the engine applies the ops and
823
- * re-runs to a fixpoint. Covers the forward reject cascade, retract/skip
824
- * tombstoning of map children, skip-propagation down dead branches, and the
825
- * re-arm of a skipped subtree when its branch revives.
919
+ * re-runs to a fixpoint. Covers ordinary build-fingerprint invalidation,
920
+ * retract/skip tombstoning of map children, skip-propagation down dead branches,
921
+ * and skipped-subtree revival. Calls gates are maintenance-local: they settle a
922
+ * dead calls branch and revive its engine cascade skip, but never validate a
923
+ * green calls fingerprint (which also includes a child-outcome pin).
826
924
  */
827
925
  export function maintainDecisions(def, arts, time) {
828
926
  const ops = [];
@@ -838,7 +936,9 @@ export function maintainDecisions(def, arts, time) {
838
936
  // Re-arming on "inputs are green" alone would thrash, since the skip itself
839
937
  // was made on green inputs (§16.1).
840
938
  if (art.acceptance === 'skipped') {
841
- const req = requiredInputs(def, arts, art);
939
+ const producerStep = stepByName(def, art.producer);
940
+ const isCallsCascade = producerStep?.calls && isEngineStructuralSkip(art);
941
+ const req = isCallsCascade ? maintenanceInputs(def, arts, art) : requiredInputs(def, arts, art);
842
942
  const allGreen = req.length > 0 && req.every((p) => isGreen(arts.get(p)));
843
943
  const moved = !fingerprintMatches(arts, req, art.fingerprint ?? {});
844
944
  if (allGreen && moved) {
@@ -846,13 +946,11 @@ export function maintainDecisions(def, arts, time) {
846
946
  }
847
947
  continue;
848
948
  }
849
- const req = requiredInputs(def, arts, art);
850
- if (req.length === 0)
851
- continue; // a seeded input with no producer-inputs: nothing to rest on
949
+ const maintenanceReq = maintenanceInputs(def, arts, art);
852
950
  // the first input that is not green (settled-dead or merely in-flight)
853
951
  let offender;
854
952
  let offenderPath;
855
- for (const p of req) {
953
+ for (const p of maintenanceReq) {
856
954
  const dep = arts.get(p);
857
955
  if (!isGreen(dep)) {
858
956
  offender = dep;
@@ -866,15 +964,16 @@ export function maintainDecisions(def, arts, time) {
866
964
  // (§11.8). `submitted` is never terminal (terminal applies at judge-approve
867
965
  // time, §4.8, so a still-submitted artifact cannot have terminal:true yet).
868
966
  if ((art.acceptance === 'green' && !art.terminal) || art.acceptance === 'submitted') {
869
- const versionsOk = fingerprintMatches(arts, req, art.fingerprint ?? {});
870
- if (!offender && versionsOk)
871
- continue; // invariant holds
872
- // Dead/settled input: structural cascade (retract or skip). NOT gated by effect:
873
- // (§17.5 — dead-input cascade for non-idempotent steps is unconditionally structural).
874
967
  if (offender && offenderPath) {
875
968
  ops.push(cascadeFromDeadInput(art.path, offender, offenderPath, isMapChild));
876
969
  continue;
877
970
  }
971
+ const req = requiredInputs(def, arts, art);
972
+ if (req.length === 0)
973
+ continue; // a seeded input with no producer-inputs: nothing to rest on
974
+ const versionsOk = fingerprintMatches(arts, req, art.fingerprint ?? {});
975
+ if (versionsOk)
976
+ continue; // invariant holds
878
977
  // All inputs are green but at least one moved (version changed). Route on effect:.
879
978
  const moved = req.find((p) => (arts.get(p)?.version ?? -1) !== (art.fingerprint ?? {})[p]);
880
979
  const producerStep = stepByName(def, art.producer);
@@ -909,19 +1008,12 @@ export function maintainDecisions(def, arts, time) {
909
1008
  ops.push(cascadeFromDeadInput(art.path, offender, offenderPath, isMapChild));
910
1009
  }
911
1010
  }
912
- // §26: declarative exclusive produce-groups — auto-skip losing siblings.
913
- // Once a group (exactlyOne/atMostOne) has a green winner, every other member
914
- // still resting in a debt state (owed/rejected) or awaiting judgment
915
- // (submitted) can never legally commit — the group's exclusivity is
916
- // enforced at commit time by the engine's groupCasCheck, so those siblings
917
- // would just stall forever without this. A submitted sibling in particular
918
- // is an OUTSTANDING state; left alone the instance can never reach
919
- // done: true. Auto-skip settles them (clearing any partial approvals so a
920
- // later resubmission never inherits a stale sign-off); the ordinary
921
- // skipped-artifact rearm loop above (which runs on the artifact's own next
922
- // maintenance pass) revives them if the winner is later un-greened
923
- // (rejected/retracted) and the group's fingerprint-gated inputs move again
924
- // — no separate rearm code is needed.
1011
+ // §26: declarative exclusive produce-groups. A green winner auto-skips
1012
+ // competing debt/submitted siblings. Once no winner remains, only siblings
1013
+ // whose latest skip reason is 'exclusive' re-arm: their routing decision was
1014
+ // the winner, not their producer inputs. The generic fingerprint gate above
1015
+ // intentionally cannot cover winner-only movement because those inputs did
1016
+ // not move. The two paths are mutually exclusive in one maintenance pass.
925
1017
  for (const step of def.steps) {
926
1018
  if (!step.groups || step.groups.length === 0)
927
1019
  continue;
@@ -929,8 +1021,19 @@ export function maintainDecisions(def, arts, time) {
929
1021
  if (g.mode === 'atLeastOne')
930
1022
  continue;
931
1023
  const winner = g.of.find((stem) => arts.get(stem)?.acceptance === 'green');
932
- if (!winner)
1024
+ if (!winner) {
1025
+ for (const stem of g.of) {
1026
+ const sib = arts.get(stem);
1027
+ if (sib?.acceptance !== 'skipped' || latestSkipKind(sib) !== 'exclusive')
1028
+ continue;
1029
+ ops.push({
1030
+ kind: 'rearm',
1031
+ path: stem,
1032
+ reason: `group '${g.group}' (${g.mode}): winner is no longer green, re-arming exclusive sibling`,
1033
+ });
1034
+ }
933
1035
  continue;
1036
+ }
934
1037
  for (const stem of g.of) {
935
1038
  if (stem === winner)
936
1039
  continue;
@@ -1017,6 +1120,31 @@ function cascadeFromDeadInput(path, offender, offenderPath, isMapChild) {
1017
1120
  }
1018
1121
  return { kind: 'reject', path, reason: `auto-invalidated: ${offenderPath} changed` };
1019
1122
  }
1123
+ /**
1124
+ * Whether one workflow instance has no outstanding artifact state (§17/§26).
1125
+ *
1126
+ * `atLeastOne` is the sole exception to a straight outstanding-state scan:
1127
+ * once any member is green, owed siblings may remain untouched forever without
1128
+ * keeping the workflow open. This predicate is intentionally cheaper than
1129
+ * `workflowStatus` so hot engine paths can share its exact completion rule
1130
+ * without building debts, eligibility, blockers, or pending-judge details.
1131
+ */
1132
+ export function workflowDone(def, arts) {
1133
+ const satisfiedAtLeastOneMembers = new Set();
1134
+ for (const step of def.steps) {
1135
+ if (!step.groups)
1136
+ continue;
1137
+ for (const g of step.groups) {
1138
+ if (g.mode !== 'atLeastOne')
1139
+ continue;
1140
+ if (g.of.some((stem) => arts.get(stem)?.acceptance === 'green')) {
1141
+ for (const stem of g.of)
1142
+ satisfiedAtLeastOneMembers.add(stem);
1143
+ }
1144
+ }
1145
+ }
1146
+ return ![...arts.values()].some((a) => OUTSTANDING_STATES.has(a.acceptance) && !(a.acceptance === 'owed' && satisfiedAtLeastOneMembers.has(a.path)));
1147
+ }
1020
1148
  /** Derive the operator view purely from artifact state (§17) — never stored. */
1021
1149
  export function workflowStatus(def, arts) {
1022
1150
  const debts = [];
@@ -1083,25 +1211,7 @@ export function workflowStatus(def, arts) {
1083
1211
  pending.push({ path: a.path, version: a.version, pendingJudges });
1084
1212
  }
1085
1213
  pending.sort((x, y) => x.path.localeCompare(y.path));
1086
- // §26: an `atLeastOne` group is satisfied once any one member is green — its
1087
- // other members may legitimately sit `owed` forever (no auto-skip fires for
1088
- // atLeastOne, unlike exactlyOne/atMostOne) without that being "not done".
1089
- // Stored acceptance is untouched; this is a done-ness computation only.
1090
- const satisfiedAtLeastOneMembers = new Set();
1091
- for (const step of def.steps) {
1092
- if (!step.groups)
1093
- continue;
1094
- for (const g of step.groups) {
1095
- if (g.mode !== 'atLeastOne')
1096
- continue;
1097
- if (g.of.some((stem) => arts.get(stem)?.acceptance === 'green')) {
1098
- for (const stem of g.of)
1099
- satisfiedAtLeastOneMembers.add(stem);
1100
- }
1101
- }
1102
- }
1103
- const done = ![...arts.values()].some((a) => OUTSTANDING_STATES.has(a.acceptance) && !(a.acceptance === 'owed' && satisfiedAtLeastOneMembers.has(a.path)));
1104
- return { done, debts, eligible, blocked, pending, inFlight: [] };
1214
+ return { done: workflowDone(def, arts), debts, eligible, blocked, pending, inFlight: [] };
1105
1215
  }
1106
1216
  /** The declared judge names for a produce stem (empty if the stem has no judges). */
1107
1217
  function declaredJudgeNames(def, stem) {
@@ -1116,12 +1226,12 @@ function stepOwesSomething(def, step, arts) {
1116
1226
  const mode = stepMode(step);
1117
1227
  if (mode === 'map') {
1118
1228
  const mc = mapConsume(step);
1119
- const mp = mapProduce(step);
1120
- if (!mc || !mp)
1229
+ const mps = mapProduces(step);
1230
+ if (!mc || mps.length === 0)
1121
1231
  return false;
1122
1232
  return members(arts, mc.stem).some((m) => {
1123
1233
  const el = parseElement(m.path);
1124
- return el ? isDebt(arts.get(bindProduce(mp, el.index))) : false;
1234
+ return el !== null && mps.some((mp) => isDebt(arts.get(bindProduce(mp, el.index))));
1125
1235
  });
1126
1236
  }
1127
1237
  return plainOutputs(step).some((p) => isDebt(arts.get(p)));
@@ -1151,13 +1261,13 @@ function blockingInputs(def, step, arts) {
1151
1261
  // a map child that owes but can't fire is blocked on its per-element input
1152
1262
  // (its bare member, or — for a chained map — the suffixed child upstream owes)
1153
1263
  const mc = mapConsume(step);
1154
- const mp = mapProduce(step);
1155
- if (mc && mp) {
1264
+ const mps = mapProduces(step);
1265
+ if (mc && mps.length > 0) {
1156
1266
  for (const m of members(arts, mc.stem)) {
1157
1267
  const el = parseElement(m.path);
1158
1268
  if (!el)
1159
1269
  continue;
1160
- if (!isDebt(arts.get(bindProduce(mp, el.index))))
1270
+ if (!mps.some((mp) => isDebt(arts.get(bindProduce(mp, el.index)))))
1161
1271
  continue;
1162
1272
  const inPath = mapInputPath(mc, el.index);
1163
1273
  if (!isGreen(arts.get(inPath)))
@@ -1218,9 +1328,8 @@ export function buildTrace(def, artifacts, runs) {
1218
1328
  stems.push(p.stem);
1219
1329
  for (const p of collectionProduces(step))
1220
1330
  stems.push(p.stem);
1221
- const mp = mapProduce(step);
1222
- if (mp)
1223
- stems.push(mp.raw); // use the raw pattern (e.g. "gather.source[$i].check")
1331
+ for (const mp of mapProduces(step))
1332
+ stems.push(mp.raw); // use raw patterns (e.g. "gather.source[$i].check")
1224
1333
  stepProducedStems.set(step.name, stems);
1225
1334
  }
1226
1335
  // --- step 3: build the timeline ---
@@ -1707,8 +1816,15 @@ function applyOpInMemory(arts, def, op) {
1707
1816
  if (!art)
1708
1817
  return;
1709
1818
  if (op.kind === 'rearm') {
1710
- // mirrors Engine.applyOp rearm branch: acceptance → 'owed'
1711
- arts.set(op.path, { ...art, acceptance: 'owed' });
1819
+ // mirrors Engine.applyOp rearm branch: acceptance → 'owed' + reopen reason.
1820
+ arts.set(op.path, {
1821
+ ...art,
1822
+ acceptance: 'owed',
1823
+ reasons: [
1824
+ ...art.reasons,
1825
+ { at: 0, action: 'reopen', kind: 'structural', by: 'engine', text: op.reason, fromVersion: art.version },
1826
+ ],
1827
+ });
1712
1828
  return;
1713
1829
  }
1714
1830
  if (op.kind === 'skip') {
@@ -1722,6 +1838,17 @@ function applyOpInMemory(arts, def, op) {
1722
1838
  acceptance: 'skipped',
1723
1839
  ...(clearApprovals ? { approvals: undefined } : {}),
1724
1840
  fingerprint: computeFingerprint(arts, requiredInputs(def, arts, art)),
1841
+ reasons: [
1842
+ ...art.reasons,
1843
+ {
1844
+ at: 0,
1845
+ action: 'skip',
1846
+ kind: op.rejectKind ?? 'structural',
1847
+ by: 'engine',
1848
+ text: op.reason,
1849
+ fromVersion: art.version,
1850
+ },
1851
+ ],
1725
1852
  });
1726
1853
  return;
1727
1854
  }
@@ -1824,6 +1951,9 @@ function seedArts(def, assumeProvided = false) {
1824
1951
  }
1825
1952
  /** Internal: the eligible outcomes for a given firing. */
1826
1953
  function eligibleOutcomes(def, arts, firing) {
1954
+ if (firing.modelTransition === 'member-retract') {
1955
+ return ['retract'];
1956
+ }
1827
1957
  const step = def.steps.find((l) => l.name === firing.step);
1828
1958
  if (!step)
1829
1959
  return ['green'];
@@ -1851,8 +1981,9 @@ function eligibleOutcomes(def, arts, firing) {
1851
1981
  }
1852
1982
  // M2: a `calls:` firing is the machine handing off to a child instance, not a
1853
1983
  // worker order. The only outcome the PARENT def can observe is the child's
1854
- // terminal outcome cascading up as a green on the calls artifact. None of the
1855
- // worker-verb outcomes apply: there is no worker to schema-reject a value, no
1984
+ // terminal completion cascading up as a green on the calls artifact while
1985
+ // exposing the child's declared output. None of the worker-verb outcomes
1986
+ // apply: there is no worker to schema-reject a value, no
1856
1987
  // consumer to judgment-reject (a calls: step declares `consumes: []`), and a
1857
1988
  // calls: produce may carry neither `judges:` nor `group:` (rejected by
1858
1989
  // `buildStep`). Modeling only the green keeps the successor set faithful to
@@ -1970,7 +2101,8 @@ function applyEmitSeal(def, arts, firing, maxCollectionSize) {
1970
2101
  * bumping judgmentRejects+1
1971
2102
  * 'schema-reject' — acceptance rejected, schemaRejects+1 on the output
1972
2103
  * 'skip' — acceptance skipped + fingerprint of requiredInputs
1973
- * 'retract' — acceptance retracted (collection member only)
2104
+ * 'retract' — a non-judge consumer retracts an authorized bare
2105
+ * collection member; acceptance becomes retracted
1974
2106
  * 'emit-seal' — collection producer: emit 1..maxCollectionSize green elements,
1975
2107
  * then seal; forks into (maxCollectionSize+1) successor states
1976
2108
  *
@@ -2080,6 +2212,10 @@ export function applyOutcome(def, arts, firing, outcome, opts) {
2080
2212
  ...art,
2081
2213
  acceptance: 'skipped',
2082
2214
  fingerprint: computeFingerprint(arts, requiredInputs(def, arts, art)),
2215
+ reasons: [
2216
+ ...art.reasons,
2217
+ { at: 0, action: 'skip', kind: 'structural', by: 'engine', text: 'producer skipped output', fromVersion: art.version },
2218
+ ],
2083
2219
  });
2084
2220
  }
2085
2221
  else if (outcome === 'retract') {
@@ -2100,8 +2236,8 @@ export function applyOutcome(def, arts, firing, outcome, opts) {
2100
2236
  * are distinct but anything >= cap is the same (frozen state)
2101
2237
  * schemaRejects: BUCKETED to min(count, maxSchemaFailures) similarly
2102
2238
  *
2103
- * For 'skipped' artifacts, the fingerprint is encoded as sorted "inputPath:versionRank"
2104
- * pairs to capture rearm eligibility correctly.
2239
+ * For 'skipped' artifacts, the fingerprint and latest skip kind are encoded to
2240
+ * capture their distinct rearm eligibility correctly.
2105
2241
  */
2106
2242
  function canonicalKey(def, arts) {
2107
2243
  const parts = [];
@@ -2142,6 +2278,8 @@ function canonicalKey(def, arts) {
2142
2278
  .join(',');
2143
2279
  entry += `|fp:${fpParts}`;
2144
2280
  }
2281
+ if (art.acceptance === 'skipped')
2282
+ entry += `|skip:${latestSkipKind(art) ?? 'none'}`;
2145
2283
  parts.push(entry);
2146
2284
  }
2147
2285
  return parts.join(';');
@@ -2152,13 +2290,14 @@ function canonicalKey(def, arts) {
2152
2290
  * Explores the full (or depth/state-bounded) state space via BFS to find:
2153
2291
  * - a non-done, zero-eligible-firings state is split into exactly ONE of two
2154
2292
  * mutually exclusive buckets by recomputing eligibility with every freeze
2155
- * lifted (unlimited attempts — see `eligibleFirings`'s `ignoreFreeze`):
2156
- * - stall states: the recompute yields >= 1 firing — the state's only
2157
- * blocker is a frozen/stalled debt (maxAttempts / maxSchemaFailures /
2158
- * held). A by-design human-escalation brake. EXPECTED, never a defect.
2293
+ * lifted and eventual idle time (unlimited attempts — see
2294
+ * `eligibleFirings`'s `ignoreFreeze`):
2295
+ * - stall states: the recompute yields >= 1 firing — a retryable frozen debt
2296
+ * or future idle threshold is the only blocker. An expected brake/wait,
2297
+ * never a defect.
2159
2298
  * - true deadlocks: the recompute STILL yields zero firings — a genuine
2160
- * structural dead-end with no path to completion even at unlimited
2161
- * attempts. A real defect.
2299
+ * structural dead-end with no move even after retry or elapsed idle time.
2300
+ * A real defect.
2162
2301
  * - stuck states: reachable states that have a stalled debt but STILL have
2163
2302
  * >= 1 eligible firing elsewhere (a brake tripped on one branch while the
2164
2303
  * line moves on another). Informational only; a no-moves state is never
@@ -2189,6 +2328,8 @@ export function modelCheck(def, opts = {}) {
2189
2328
  def: def.name,
2190
2329
  bounded: false,
2191
2330
  boundsHit: [],
2331
+ collectionCapApplied: false,
2332
+ maxCollectionSize,
2192
2333
  deadlocks: [],
2193
2334
  stallStates: [],
2194
2335
  stuck: [],
@@ -2250,8 +2391,9 @@ export function modelCheck(def, opts = {}) {
2250
2391
  // which is false: the engine does spawn the child and the debt is
2251
2392
  // discharged.
2252
2393
  //
2253
- // The child is modeled as a single opaque green of the calls artifact — the
2254
- // only thing the parent def can observe about it. `callsDischargeFirings`
2394
+ // The child is modeled as a single opaque whole-child completion that greens
2395
+ // the calls artifact and exposes its declared output — the only thing the
2396
+ // parent def can observe about it. `callsDischargeFirings`
2255
2397
  // gates per-step on `callsInputs` (the same field `Engine.callsGateReady`
2256
2398
  // reads), so a `calls:` step whose gate is NOT green yields no firing and
2257
2399
  // the state is classified on its own merits. Because the discharge greens
@@ -2261,15 +2403,20 @@ export function modelCheck(def, opts = {}) {
2261
2403
  // `eligibleFirings` (the LIVE engine scheduler) and `hasDefiniteCheckDefect`
2262
2404
  // (shared by check / add / push / install) are deliberately untouched.
2263
2405
  const callsFirings = callsDischargeFirings(def, node.arts);
2264
- const firings = [...status.eligible, ...callsFirings];
2265
- // Non-done state with no eligible firings: classify by recomputing eligibility
2266
- // as if every freeze/stall were lifted (unlimited attempts). If a producer
2267
- // would re-arm → an EXPECTED stall state (a by-design brake). If not → a
2268
- // TRUE deadlock (a structural dead-end with no path to completion even at
2269
- // unlimited attempts).
2406
+ // Member retraction is likewise a runtime-valid authority transition, not
2407
+ // a worker firing. It is separate from eligibleFirings so a rejected map
2408
+ // input still has the later retract move the runtime permits.
2409
+ const retractFirings = memberRetractFirings(def, node.arts);
2410
+ const firings = [...status.eligible, ...callsFirings, ...retractFirings];
2411
+ // Non-done state with no eligible firings: classify by recomputing
2412
+ // eligibility as if every freeze/stall were lifted and idle time had
2413
+ // elapsed. If retry or time would make a producer eligible, this is an
2414
+ // expected stall/wait; otherwise it is a true structural deadlock.
2415
+ // EVENTUAL_TIME_FACTS is classification-only: the timeless BFS below does
2416
+ // not enqueue these future idle transitions or include time in its key.
2270
2417
  if (firings.length === 0 && !status.done) {
2271
- const lifted = eligibleFirings(def, node.arts, undefined, { ignoreFreeze: true });
2272
- if (lifted.length > 0) {
2418
+ const eventualFirings = eligibleFirings(def, node.arts, EVENTUAL_TIME_FACTS, { ignoreFreeze: true });
2419
+ if (eventualFirings.length > 0) {
2273
2420
  report.stallStates.push({ path: node.path });
2274
2421
  }
2275
2422
  else {
@@ -2291,7 +2438,11 @@ export function modelCheck(def, opts = {}) {
2291
2438
  }
2292
2439
  // Expand successors
2293
2440
  outer: for (const firing of firings) {
2294
- firedSteps.add(firing.step);
2441
+ // An authority-only member retract does not prove its actor ever
2442
+ // produced an ordinary firing; preserve structural-dead-step accounting.
2443
+ if (firing.modelTransition !== 'member-retract') {
2444
+ firedSteps.add(firing.step);
2445
+ }
2295
2446
  const outcomes = eligibleOutcomes(def, node.arts, firing);
2296
2447
  for (const outcome of outcomes) {
2297
2448
  // Check state count before expanding
@@ -2300,6 +2451,8 @@ export function modelCheck(def, opts = {}) {
2300
2451
  break outer;
2301
2452
  }
2302
2453
  const step = { step: firing.step, key: firing.key, outcome };
2454
+ if (outcome === 'emit-seal')
2455
+ report.collectionCapApplied = true;
2303
2456
  const successors = applyOutcome(def, node.arts, firing, outcome, { maxCollectionSize });
2304
2457
  for (const suc of successors) {
2305
2458
  const key = canonicalKey(def, suc);
@@ -143,6 +143,7 @@ export interface OrderRuntimeVars {
143
143
  run: string;
144
144
  key: string;
145
145
  index?: number;
146
+ modifier?: string;
146
147
  }
147
148
  /**
148
149
  * The runtime placeholder substitution for an order's authored prompt body.
@@ -194,6 +194,7 @@ export function substituteOrderVars(body, runtime, opts = {}) {
194
194
  case 'STEP': return opts.step ?? m;
195
195
  case 'KEY': return runtime.key;
196
196
  case 'INDEX': return runtime.index === undefined ? '' : String(runtime.index);
197
+ case 'MODIFIER': return runtime.modifier ?? m;
197
198
  // Intentionally step-generic: a single firing can discharge multiple
198
199
  // outputs (order.outputs) at once, so there is no single produce to
199
200
  // resolve a per-produce maxAttempts override against here. This
@@ -246,7 +247,13 @@ export class OrderResolver {
246
247
  return instructions;
247
248
  return {
248
249
  ...instructions,
249
- prompt: substituteOrderVars(resolved.prompt, { workflow: order.workflow, run: order.run, key: order.key, ...(order.index !== undefined ? { index: order.index } : {}) }, { step: order.step, maxAttempts }),
250
+ prompt: substituteOrderVars(resolved.prompt, {
251
+ workflow: order.workflow,
252
+ run: order.run,
253
+ key: order.key,
254
+ ...(order.index !== undefined ? { index: order.index } : {}),
255
+ ...(order.modifier !== undefined ? { modifier: order.modifier } : {}),
256
+ }, { step: order.step, maxAttempts }),
250
257
  };
251
258
  }
252
259
  }