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/store.js CHANGED
@@ -13,7 +13,125 @@
13
13
  * and (de)serialized at the boundary so callers always see real objects.
14
14
  */
15
15
  import { DatabaseSync } from 'node:sqlite';
16
+ import { lstatSync } from 'node:fs';
16
17
  import { detId, nowMs } from "./util.js";
18
+ import { compareStoreText, defDigest, isDefDigest, parseWorkflowCoordinate } from "./store/types.js";
19
+ import { withWorkflowSnapshotStoreGuard } from "./store/snapshot-guard.js";
20
+ function exactCallsFromSnapshot(record, workflow) {
21
+ const rawSteps = record.steps;
22
+ if (rawSteps === undefined)
23
+ return [];
24
+ if (!Array.isArray(rawSteps)) {
25
+ throw new Error(`workflow '${workflow}' has malformed def_snapshot.steps: expected an array`);
26
+ }
27
+ const exactCalls = new Set();
28
+ for (const [index, rawStep] of rawSteps.entries()) {
29
+ if (typeof rawStep !== 'object' || rawStep === null || Array.isArray(rawStep)) {
30
+ throw new Error(`workflow '${workflow}' has malformed def_snapshot.steps[${index}]: expected an object`);
31
+ }
32
+ const calls = rawStep.calls;
33
+ if (calls === undefined)
34
+ continue;
35
+ if (typeof calls !== 'string') {
36
+ throw new Error(`workflow '${workflow}' has malformed def_snapshot.steps[${index}].calls: expected a string`);
37
+ }
38
+ if (!calls.includes('@'))
39
+ continue;
40
+ try {
41
+ parseWorkflowCoordinate(calls);
42
+ }
43
+ catch (error) {
44
+ throw new Error(`workflow '${workflow}' has malformed exact def_snapshot calls target ${JSON.stringify(calls)}: ` +
45
+ error.message);
46
+ }
47
+ const rawLock = record.bundleLock;
48
+ if (typeof rawLock === 'object'
49
+ && rawLock !== null
50
+ && !Array.isArray(rawLock)
51
+ && Object.prototype.hasOwnProperty.call(rawLock, calls))
52
+ continue;
53
+ exactCalls.add(calls);
54
+ }
55
+ return [...exactCalls].sort(compareStoreText);
56
+ }
57
+ /**
58
+ * Read bundle pins from an EXISTING runtime database without migrating or
59
+ * otherwise writing it. GC deliberately cannot use {@link openStore}: opening
60
+ * the normal store enables write-oriented pragmas and schema migration, while
61
+ * a dry run must remain observational. Legacy databases without the workflow
62
+ * table or def_snapshot column simply predate snapshot pinning and contribute
63
+ * no pins.
64
+ */
65
+ export function readRuntimeSnapshotBundlePins(path) {
66
+ if (lstatSync(path, { throwIfNoEntry: false }) === undefined)
67
+ return [];
68
+ const db = new DatabaseSync(path, { readOnly: true });
69
+ try {
70
+ const hasMeta = db
71
+ .prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'meta'`)
72
+ .get() !== undefined;
73
+ if (hasMeta) {
74
+ const row = db.prepare(`SELECT v FROM meta WHERE k = 'schema_version'`).get();
75
+ const current = row?.v;
76
+ if (current !== undefined && parseInt(current, 10) > parseInt(SCHEMA_VERSION, 10)) {
77
+ throw new StoreVersionError(`database schema_version ${current} is newer than this owenloop's schema_version ${SCHEMA_VERSION}; ` +
78
+ 'upgrade your owenloop install to open this database');
79
+ }
80
+ }
81
+ const hasWorkflow = db
82
+ .prepare(`SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'workflow'`)
83
+ .get() !== undefined;
84
+ if (!hasWorkflow)
85
+ return [];
86
+ const columns = db.prepare('PRAGMA table_info(workflow)').all();
87
+ if (!columns.some((column) => column.name === 'def_snapshot'))
88
+ return [];
89
+ const rows = db
90
+ .prepare('SELECT id, def_snapshot FROM workflow WHERE def_snapshot IS NOT NULL ORDER BY created_at, id')
91
+ .all();
92
+ return rows.map((row) => {
93
+ let snapshot;
94
+ try {
95
+ snapshot = JSON.parse(row.def_snapshot);
96
+ }
97
+ catch (error) {
98
+ throw new Error(`workflow '${row.id}' has malformed def_snapshot JSON: ${error.message}`);
99
+ }
100
+ if (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot)) {
101
+ throw new Error(`workflow '${row.id}' has malformed def_snapshot: expected an object`);
102
+ }
103
+ const record = snapshot;
104
+ const rawDigest = record.bundleDigest;
105
+ let bundleDigest;
106
+ if (rawDigest !== undefined && rawDigest !== '') {
107
+ if (typeof rawDigest !== 'string' || !isDefDigest(rawDigest)) {
108
+ throw new Error(`workflow '${row.id}' has noncanonical def_snapshot.bundleDigest ${JSON.stringify(rawDigest)}`);
109
+ }
110
+ bundleDigest = rawDigest;
111
+ }
112
+ const rawLock = record.bundleLock;
113
+ if (rawLock !== undefined && (typeof rawLock !== 'object' || rawLock === null || Array.isArray(rawLock))) {
114
+ throw new Error(`workflow '${row.id}' has malformed def_snapshot.bundleLock: expected an object`);
115
+ }
116
+ const bundleLock = Object.entries((rawLock ?? {})).map(([target, digest]) => {
117
+ if (typeof digest !== 'string' || !isDefDigest(digest)) {
118
+ throw new Error(`workflow '${row.id}' has noncanonical def_snapshot.bundleLock[${JSON.stringify(target)}] ` +
119
+ `${JSON.stringify(digest)}`);
120
+ }
121
+ return digest;
122
+ });
123
+ const exactCalls = exactCallsFromSnapshot(record, row.id);
124
+ return {
125
+ ...(bundleDigest === undefined ? {} : { bundleDigest }),
126
+ bundleLock: [...new Set(bundleLock)].sort(compareStoreText),
127
+ ...(exactCalls.length === 0 ? {} : { exactCalls }),
128
+ };
129
+ });
130
+ }
131
+ finally {
132
+ db.close();
133
+ }
134
+ }
17
135
  // ---- deterministic ids -------------------------------------------------------
18
136
  export function artifactId(workflow, path) {
19
137
  return detId('art', workflow, path);
@@ -29,6 +147,7 @@ CREATE TABLE IF NOT EXISTS workflow (
29
147
  title TEXT,
30
148
  params TEXT NOT NULL DEFAULT '{}',
31
149
  modifier TEXT,
150
+ meta TEXT,
32
151
  created_at INTEGER NOT NULL
33
152
  );
34
153
 
@@ -150,8 +269,11 @@ CREATE TABLE IF NOT EXISTS meta (
150
269
  * nullable `modifier` column (see `migrate()`). Additive and un-backfilled —
151
270
  * NULL on every existing row means "unmodified run", which is the correct
152
271
  * reading of an instance created before modifiers existed.
272
+ *
273
+ * Bumped to '11' for bound artifacts: the `workflow` table gains nullable
274
+ * JSON `meta` for non-routing `meta.<key>` artifact binds.
153
275
  */
154
- const SCHEMA_VERSION = '10';
276
+ const SCHEMA_VERSION = '11';
155
277
  /** Thrown by the `Store` constructor when the on-disk `schema_version` is
156
278
  * newer than this binary's `SCHEMA_VERSION` — the operator needs to
157
279
  * upgrade their owenloop install to open this database. */
@@ -369,11 +491,19 @@ function mapWorkflow(r) {
369
491
  // become the same thing downstream, where '' would compose 'build:'.
370
492
  if (r.modifier !== null)
371
493
  out.modifier = r.modifier;
494
+ const meta = fromJson(r.meta, undefined, {
495
+ table: 'workflow',
496
+ id: r.id,
497
+ column: 'meta',
498
+ });
499
+ if (meta !== undefined)
500
+ out.meta = meta;
372
501
  return out;
373
502
  }
374
503
  // ---- the store ---------------------------------------------------------------
375
504
  export class Store {
376
505
  db;
506
+ activeSnapshotDigests = new Set();
377
507
  constructor(path) {
378
508
  this.db = new DatabaseSync(path);
379
509
  // Connection-scoped only — no file mutation, safe before the version check.
@@ -517,14 +647,18 @@ export class Store {
517
647
  if (!wfCols.some((c) => c.name === 'def_hash')) {
518
648
  this.db.exec(`ALTER TABLE workflow ADD COLUMN def_hash TEXT`);
519
649
  }
520
- // Routing modifier: the ONE modifier this instance carries, set once at
521
- // creation and never written again. NULL on every pre-existing row, which
522
- // is exactly right — an instance created before modifiers existed is an
523
- // unmodified run and every step is offered on bare capabilities. No
650
+ // Routing modifier: the ONE modifier this instance carries. The starter
651
+ // supplies its initial value; a def-declared artifact bind may later update
652
+ // it through the engine's routing writer. NULL on every pre-existing row,
653
+ // which is exactly right — an instance created before modifiers existed is
654
+ // an unmodified run and every step is offered on bare capabilities. No
524
655
  // backfill: there is no value to invent.
525
656
  if (!wfCols.some((c) => c.name === 'modifier')) {
526
657
  this.db.exec(`ALTER TABLE workflow ADD COLUMN modifier TEXT`);
527
658
  }
659
+ if (!wfCols.some((c) => c.name === 'meta')) {
660
+ this.db.exec(`ALTER TABLE workflow ADD COLUMN meta TEXT`);
661
+ }
528
662
  // Only a genuine pre-v8 -> v8 upgrade may backfill the current projection's
529
663
  // reason thread. Re-opening an already-v8 database must not manufacture a
530
664
  // second copy of its lifecycle events (even though the legacy keys differ
@@ -566,6 +700,35 @@ export class Store {
566
700
  throw err;
567
701
  }
568
702
  }
703
+ /**
704
+ * Persist one or more CAS-backed definition snapshots under the same
705
+ * workflow-store lock used by install and GC. Reachability is revalidated
706
+ * before `BEGIN IMMEDIATE`; the guarded digest set then authorizes only the
707
+ * low-level snapshot writes performed by this transaction.
708
+ */
709
+ txWithWorkflowSnapshots(snapshots, fn) {
710
+ const defs = Array.isArray(snapshots) ? snapshots : [snapshots];
711
+ return withWorkflowSnapshotStoreGuard(defs, (guardedDigests) => {
712
+ for (const digest of guardedDigests)
713
+ this.activeSnapshotDigests.add(digest);
714
+ try {
715
+ return this.tx(fn);
716
+ }
717
+ finally {
718
+ for (const digest of guardedDigests)
719
+ this.activeSnapshotDigests.delete(digest);
720
+ }
721
+ });
722
+ }
723
+ assertWorkflowSnapshotGuard(snapshot) {
724
+ if (snapshot?.bundleDigest === undefined || (snapshot.bundleStoreRoots?.length ?? 0) === 0)
725
+ return;
726
+ const digest = defDigest(snapshot.bundleDigest);
727
+ if (!this.activeSnapshotDigests.has(digest)) {
728
+ throw new Error(`refusing uncoordinated workflow snapshot write for bundle ${digest}: ` +
729
+ 'use txWithWorkflowSnapshots so bundle GC cannot race the commit');
730
+ }
731
+ }
569
732
  // -- meta --------------------------------------------------------------------
570
733
  getMeta(k) {
571
734
  const row = this.db.prepare('SELECT v FROM meta WHERE k = ?').get(k);
@@ -578,12 +741,13 @@ export class Store {
578
741
  }
579
742
  // -- workflow ----------------------------------------------------------------
580
743
  insertWorkflow(id, data, producedBy) {
744
+ this.assertWorkflowSnapshotGuard(data.defSnapshot);
581
745
  const at = nowMs();
582
746
  this.db
583
747
  .prepare(`INSERT INTO workflow
584
- (id, def, title, params, produced_by_wf, produced_by_path, def_snapshot, def_hash, modifier, created_at)
585
- VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
586
- .run(id, data.def, data.title ?? null, JSON.stringify(data.params ?? {}), producedBy?.parentWf ?? null, producedBy?.parentPath ?? null, toJson(data.defSnapshot), data.defHash ?? null, data.modifier ?? null, at);
748
+ (id, def, title, params, produced_by_wf, produced_by_path, def_snapshot, def_hash, modifier, meta, created_at)
749
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
750
+ .run(id, data.def, data.title ?? null, JSON.stringify(data.params ?? {}), producedBy?.parentWf ?? null, producedBy?.parentPath ?? null, toJson(data.defSnapshot), data.defHash ?? null, data.modifier ?? null, toJson(data.meta), at);
587
751
  return this.getWorkflow(id);
588
752
  }
589
753
  /**
@@ -592,10 +756,31 @@ export class Store {
592
756
  * decide what "drift" means, it just persists what the engine computed.
593
757
  */
594
758
  repinWorkflowDef(id, snapshot, hash) {
759
+ this.assertWorkflowSnapshotGuard(snapshot);
595
760
  this.db
596
761
  .prepare('UPDATE workflow SET def_snapshot = ?, def_hash = ? WHERE id = ?')
597
762
  .run(JSON.stringify(snapshot), hash, id);
598
763
  }
764
+ /** Apply an engine-authored routing patch without rewriting authored params. */
765
+ setWorkflowRouting(id, patch) {
766
+ const assignments = [];
767
+ const values = [];
768
+ if (patch.modifier !== undefined) {
769
+ assignments.push('modifier = ?');
770
+ values.push(patch.modifier);
771
+ }
772
+ if (patch.meta !== undefined) {
773
+ const current = this.getWorkflow(id);
774
+ if (current === undefined)
775
+ throw new Error(`cannot update routing for unknown workflow '${id}'`);
776
+ assignments.push('meta = ?');
777
+ values.push(JSON.stringify({ ...(current.meta ?? {}), ...patch.meta }));
778
+ }
779
+ if (assignments.length === 0)
780
+ return;
781
+ values.push(id);
782
+ this.db.prepare(`UPDATE workflow SET ${assignments.join(', ')} WHERE id = ?`).run(...values);
783
+ }
599
784
  getWorkflow(id) {
600
785
  const r = this.db.prepare('SELECT * FROM workflow WHERE id = ?').get(id);
601
786
  return r ? mapWorkflow(r) : undefined;
@@ -889,8 +1074,10 @@ export class Store {
889
1074
  if (!cur)
890
1075
  throw new Error(`run not found: ${id}`);
891
1076
  // order_json is DELIBERATELY excluded from `merged` and the UPDATE below:
892
- // the order packet is immutable after claim (§8 / Gap 1). Omitting it makes
893
- // that structural — no close/outcome/summary write can ever clobber it.
1077
+ // no close/outcome/summary write can ever clobber the order packet, and
1078
+ // omitting the column makes that structural rather than a convention.
1079
+ // `restampOrderTarget` below is the ONE writer of order_json after claim,
1080
+ // and it rewrites a single `owes[].version` and nothing else.
894
1081
  const merged = {
895
1082
  workflow: cur.workflow,
896
1083
  step: cur.step,
@@ -906,28 +1093,79 @@ export class Store {
906
1093
  .run(merged.key ?? '', merged.outcome ?? null, merged.summary ?? null, merged.sessionId ?? null, toJson(merged.fingerprint), merged.cause ?? null, nowMs(), id);
907
1094
  return this.getRun(id);
908
1095
  }
1096
+ /**
1097
+ * Re-stamp ONE owed version target on a run's persisted order packet.
1098
+ *
1099
+ * The order is frozen at claim with exactly one exception, and this is it.
1100
+ * When a reject re-arms a still-open claim, the artifact has already been
1101
+ * bumped by the commit that preceded the reject, so the target the claim
1102
+ * froze at issue names a version the next commit will overshoot — and the
1103
+ * producer would sign that stale number into its submission proof while the
1104
+ * hub keys the stored proof row by the version actually committed. Everything
1105
+ * else about the packet stays frozen, and `updateRun` still cannot touch it
1106
+ * at all.
1107
+ *
1108
+ * No-ops when the run has no persisted order (pre-schema-v7 rows), when the
1109
+ * order does not owe `path`, or when the target already is `version` — so
1110
+ * callers can call it unconditionally, and re-stamping is idempotent.
1111
+ */
1112
+ restampOrderTarget(id, path, version) {
1113
+ const cur = this.getRun(id);
1114
+ if (!cur?.order)
1115
+ return;
1116
+ const owed = cur.order.owes.find((o) => o.path === path);
1117
+ if (owed === undefined || owed.version === version)
1118
+ return;
1119
+ // Rebuilt immutably (map, not in-place mutation) so no caller is left
1120
+ // holding a half-mutated Order read before this write.
1121
+ const next = {
1122
+ ...cur.order,
1123
+ owes: cur.order.owes.map((o) => (o.path === path ? { ...o, version } : o)),
1124
+ };
1125
+ this.db
1126
+ .prepare('UPDATE run SET order_json = ?, updated_at = ? WHERE id = ?')
1127
+ .run(toJson(next), nowMs(), id);
1128
+ }
909
1129
  getRun(id) {
910
1130
  const r = this.db.prepare('SELECT * FROM run WHERE id = ?').get(id);
911
1131
  return r ? mapRun(r) : undefined;
912
1132
  }
913
- /** How many runs of this step since `sinceMs` (for the daily budget window). */
1133
+ /**
1134
+ * How many runs of this step since `sinceMs` (for the daily budget window).
1135
+ *
1136
+ * `released` RUNS ARE EXCLUDED — a lease returned unused is not a firing. See
1137
+ * `RunData.outcome` for why this is not the same as `no_work`, which stays
1138
+ * counted because the step did run.
1139
+ */
914
1140
  countRuns(workflow, step, sinceMs) {
915
1141
  const row = this.db
916
- .prepare('SELECT COUNT(*) AS n FROM run WHERE workflow = ? AND step = ? AND created_at >= ?')
1142
+ .prepare('SELECT COUNT(*) AS n FROM run WHERE workflow = ? AND step = ? AND created_at >= ?'
1143
+ + " AND (outcome IS NULL OR outcome != 'released')")
917
1144
  .get(workflow, step, sinceMs);
918
1145
  return row.n;
919
1146
  }
920
- /** The most recent run of this step, if any (for cadence gating). */
1147
+ /**
1148
+ * The most recent run of this step, if any (for cadence gating).
1149
+ *
1150
+ * `released` runs are excluded for the same reason `countRuns` excludes them:
1151
+ * a lease handed straight back did not fire the step, so it must not restart
1152
+ * the cadence clock. Without this a server that claims and releases on every
1153
+ * sweep holds a throttled step off indefinitely — each handback pushes the
1154
+ * next eligible time further out than the sweep interval that produced it.
1155
+ */
921
1156
  latestRun(workflow, step) {
922
1157
  const r = this.db
923
- .prepare('SELECT * FROM run WHERE workflow = ? AND step = ? ORDER BY created_at DESC LIMIT 1')
1158
+ .prepare("SELECT * FROM run WHERE workflow = ? AND step = ? AND (outcome IS NULL OR outcome != 'released')"
1159
+ + ' ORDER BY created_at DESC LIMIT 1')
924
1160
  .get(workflow, step);
925
1161
  return r ? mapRun(r) : undefined;
926
1162
  }
927
1163
  /**
928
1164
  * Count of consecutive trailing `failed` runs for this step+key — the
929
- * crash-step signal. Any closed run that is NOT `failed` (ok/no_work/skipped)
930
- * breaks the streak; still-open runs (outcome NULL) are ignored.
1165
+ * crash-step signal. Any closed run that is NOT `failed`
1166
+ * (ok/no_work/released/skipped) breaks the streak; still-open runs (outcome
1167
+ * NULL) are ignored. `released` breaks it exactly as `no_work` did before the
1168
+ * two were split, so the crash-step signal is unchanged by that split.
931
1169
  */
932
1170
  recentFailedRuns(workflow, step, key = '') {
933
1171
  const rows = this.db
@@ -51,6 +51,8 @@ export interface ReasonEntry {
51
51
  text: string;
52
52
  /** version the artifact was at when this entry was written (provenance) */
53
53
  fromVersion?: number;
54
+ /** Machine-readable correction supplied when rejecting a bound artifact. */
55
+ requested?: string;
54
56
  }
55
57
  /**
56
58
  * The fingerprint: the version of every consumed input at claim time
@@ -168,6 +170,12 @@ export interface Order {
168
170
  * (`wise` → `wise:deep`), or the authored names verbatim when the run
169
171
  * carries no modifier. Absent when the step authored none.
170
172
  *
173
+ * A caller may also supply a capability MAPPING, which substitutes its own
174
+ * capability name for the authored one before the modifier is attached. Such
175
+ * an order carries no in-band marker — unlike a reroute, nothing here says a
176
+ * mapping fired. The authored name stays recoverable through `defDigest`,
177
+ * which pins the def that wrote it.
178
+ *
171
179
  * This is the value a claiming crew's bindings are matched against and the
172
180
  * value the shift's settings map is keyed by. It is a snapshot of the offer:
173
181
  * an already-claimed order is never recomposed, so re-reading it later
@@ -178,6 +186,12 @@ export interface Order {
178
186
  * served, so it is the one a shift must resolve its model against.
179
187
  */
180
188
  capabilities?: string[];
189
+ /**
190
+ * Ordered crews the offering side matched for this order's capabilities.
191
+ * Absent when the caller supplied no stamps. Hub → worker, NOT the separate
192
+ * worker → hub `serve_crews` narrowing advertisement.
193
+ */
194
+ crews?: string[];
181
195
  /**
182
196
  * The composed capabilities this order WOULD have been offered under, present
183
197
  * only when a caller-supplied reroute rule substituted something else into
@@ -255,11 +269,12 @@ export interface Order {
255
269
  * stalls the step. This closes that: the requirement is stated up front,
256
270
  * from the same declaration the refusal will be measured against.
257
271
  *
258
- * It is a COPY, not a reference. The order is immutable once written
259
- * (`RunData.order`), so this is the schema as it stood at claim time; a def
260
- * edited mid-run leaves the projected schema and the enforced one able to
261
- * disagree, exactly as `defDigest` already records for the rest of the
262
- * order.
272
+ * It is a COPY, not a reference. Nothing rewrites the schema on a persisted
273
+ * order — `Store.restampOrderTarget`, the one post-claim writer, touches
274
+ * only `owes[].version` — so this is the schema as it stood at claim time;
275
+ * a def edited mid-run leaves the projected schema and the enforced one
276
+ * able to disagree, exactly as `defDigest` already records for the rest of
277
+ * the order.
263
278
  */
264
279
  schema?: JsonSchema;
265
280
  /**
@@ -291,7 +306,31 @@ export interface RunData {
291
306
  workflow: string;
292
307
  step: string;
293
308
  key?: string;
294
- outcome?: 'ok' | 'no_work' | 'failed' | 'skipped';
309
+ /**
310
+ * How the run ended, or `undefined` while it is still open.
311
+ *
312
+ * `no_work` and `released` are NOT the same thing, and the difference is
313
+ * load-bearing for the daily budget and the cadence gate:
314
+ *
315
+ * - `no_work` — the step RAN and had nothing to produce. A `merge-gate` that
316
+ * polled CI and found it still pending, an `ask` that handed the question
317
+ * to a human, a holder that rejected its input. Work happened; these runs
318
+ * spend budget and restart the cadence clock, which is exactly how a
319
+ * `cadenceSecs` poll stays throttled.
320
+ * - `released` — the LEASE WAS RETURNED UNUSED. Nothing ran. A server already
321
+ * at its agent cap handing the claim straight back or a pickup window that
322
+ * lapsed with no first contact increments the task's lease-churn
323
+ * `attempts`, while a private born-reject re-arm does not. All remain
324
+ * outside the daily budget and cadence: they are not firings, they are
325
+ * claims that were withdrawn.
326
+ *
327
+ * Conflating them stalled a live run. Six capacity handbacks against a step
328
+ * declaring `maxRunsPerDay: 6` spent the whole allowance before it executed
329
+ * once; the engine then deferred it `daily-budget` until local midnight while
330
+ * its artifact still read `attemptsUsed: 0`. Lease-churn attempts are status
331
+ * telemetry, not the rework budget (`judgmentRejects`) and not a run.
332
+ */
333
+ outcome?: 'ok' | 'no_work' | 'released' | 'failed' | 'skipped';
295
334
  summary?: string;
296
335
  sessionId?: string;
297
336
  /** the version of every consumed input at claim time (§12.2 commit CAS) */
@@ -300,8 +339,10 @@ export interface RunData {
300
339
  cause?: FiringTrigger;
301
340
  /** The flattened order packet issued at claim time (§8 / Gap 1) — the exact
302
341
  * Order buildOrder emitted, written in the SAME transaction that created
303
- * this run. Immutable after insert: updateRun never touches it. The
304
- * replay/eval/paper-trail record (buildOrder is deterministic modulo run
342
+ * this run. `updateRun` never touches it, so no close/outcome write can
343
+ * clobber it; `Store.restampOrderTarget` is the single narrow exception,
344
+ * rewriting one `owes[].version` when a reject re-arms a still-open claim.
345
+ * The replay/eval/paper-trail record (buildOrder is deterministic modulo run
305
346
  * id). Absent on runs created before schema v7. */
306
347
  order?: Order;
307
348
  }
@@ -311,14 +352,18 @@ export interface WorkflowData {
311
352
  params?: Record<string, string>;
312
353
  /**
313
354
  * The ONE modifier this run carries, validated against the def's declared
314
- * `modifiers` set when the run is created and immutable thereafter — no
315
- * step, worker or judge can write it (only `start_run` sets it; escalation
316
- * overrides it per-offer without changing it here).
355
+ * `modifiers` set when the run is created. The starter supplies the initial
356
+ * value; after that, only the engine may replace it while accepting an
357
+ * artifact whose def-declared bind targets `modifier`. No step, worker, or
358
+ * judge writes it directly; escalation still overrides it per-offer without
359
+ * changing the stored value.
317
360
  *
318
361
  * Absent = an unmodified run: every step is offered on bare capabilities.
319
362
  * Deletes with the run, like the rest of the row.
320
363
  */
321
364
  modifier?: string;
365
+ /** Engine-written, non-routing metadata populated by artifact binds. */
366
+ meta?: Record<string, unknown>;
322
367
  /** Instance-to-definition pinning (§28): the compiled def this instance was
323
368
  * created against, snapshotted verbatim as JSON. Absent on rows created
324
369
  * before this feature shipped — those instances fall back to today's
@@ -359,6 +404,11 @@ export interface GroupDef {
359
404
  mode: GroupMode;
360
405
  of: string[];
361
406
  }
407
+ /** A normalized artifact-to-instance routing write declared on a produce. */
408
+ export interface ArtifactBind {
409
+ to: string;
410
+ from: string;
411
+ }
362
412
  /** A parsed produce declaration. */
363
413
  export interface ProducePattern {
364
414
  raw: string;
@@ -368,6 +418,8 @@ export interface ProducePattern {
368
418
  suffix: string;
369
419
  /** optional JSON Schema the produced value must satisfy at commit time (§19) */
370
420
  schema?: JsonSchema;
421
+ /** Optional normalized artifact-to-instance write applied on acceptance. */
422
+ bind?: ArtifactBind;
371
423
  /** §6/§18 per-produce override of the step's maxAttempts (judgment-reject
372
424
  * stall cap). Falls back to the owning step's maxAttempts when absent —
373
425
  * see model.ts effectiveMaxAttempts(). Only meaningful on {name,...}
@@ -432,6 +484,22 @@ export interface EffectDef {
432
484
  * Defaults to 'escalate' when idempotent:false and omitted. */
433
485
  onInvalidate?: 'pin' | 'escalate' | string;
434
486
  }
487
+ /**
488
+ * Declares that a step is cleanup: it must still be dispatched when the run is
489
+ * cancelled, not only on the normal green path.
490
+ *
491
+ * This is not a firing trigger. `on:`/`FiringTrigger` is the in-run scheduler's
492
+ * vocabulary, evaluated from artifact state and time facts. Run cancellation is
493
+ * neither of those, so `onCancel:` is inert in this engine: it is a declaration
494
+ * the control plane reads when it cancels a run.
495
+ */
496
+ export interface OnCancelDef {
497
+ /** The subset of the step's own plain consume stems the cancel-path firing
498
+ * requires. Required, may be empty. This is explicit because a cleanup
499
+ * step's normal consume set may include a terminal artifact that never
500
+ * greens after cancellation, and the control plane must not guess inputs. */
501
+ consumes: string[];
502
+ }
435
503
  /** A step (step) definition. */
436
504
  /**
437
505
  * A step's escalation rule (def-authored, engine-applied).
@@ -514,6 +582,8 @@ export interface StepDef {
514
582
  idleAfter?: string;
515
583
  /** Parsed idleAfter in milliseconds. */
516
584
  idleAfterMs?: number;
585
+ /** Cleanup-on-cancel declaration. Absent = no cancel-path dispatch. See OnCancelDef. */
586
+ onCancel?: OnCancelDef;
517
587
  /** Per-step reap TTL override in milliseconds. Falls back to the engine's DEFAULT_REAP_TTL_MS. */
518
588
  reapTtlMs?: number;
519
589
  /** A2: opaque routing capabilities for peer-orchestrator claim filtering. A tick
@@ -766,11 +836,20 @@ export interface CheckReport {
766
836
  bounded: boolean;
767
837
  /** Which bounds were hit, for honest reporting. */
768
838
  boundsHit: ('maxDepth' | 'maxStates')[];
839
+ /**
840
+ * True when the search expanded at least one reachable `emit-seal` outcome.
841
+ * This describes the search shape, not a BFS stop condition, and does not
842
+ * contribute to `bounded`.
843
+ */
844
+ collectionCapApplied: boolean;
845
+ /** Effective per-seal member-count cap, including the default when unspecified. */
846
+ maxCollectionSize: number;
769
847
  /**
770
848
  * Reachable non-done states with zero eligible firings that have NO path to
771
- * completion even at unlimited attempts — i.e. recomputing eligibility with
772
- * all freezes lifted (a human `retry` = unlimited attempts) STILL yields
773
- * zero firings. A genuine structural dead-end (TRUE deadlock). A definite
849
+ * completion even after unlimited attempts and elapsed idle time — i.e.
850
+ * recomputing eligibility with all freezes lifted (a human `retry` =
851
+ * unlimited attempts) and eventual idle time STILL yields zero firings. A
852
+ * genuine structural dead-end (TRUE deadlock). A definite
774
853
  * defect only when the search was exhaustive (`!bounded`) — the
775
854
  * maxCollectionSize cap can otherwise manufacture a spurious no-moves
776
855
  * state. Always present ([] when none).
@@ -778,12 +857,14 @@ export interface CheckReport {
778
857
  deadlocks: CheckFinding[];
779
858
  /**
780
859
  * Reachable non-done states with zero eligible firings whose ONLY blocker
781
- * is a frozen/stalled debt (maxAttempts / maxSchemaFailures / held).
782
- * Recomputing eligibility with all freezes lifted (a human `retry` =
783
- * unlimited attempts) yields >= 1 firing, so a producer would re-arm and
784
- * the line could move. These are the DESIGNED human-escalation brakes —
785
- * EXPECTED, never a defect; they do not affect the exit code. Always
786
- * present ([] when none).
860
+ * is a frozen/stalled debt (maxAttempts / maxSchemaFailures / held) or an
861
+ * idle trigger whose threshold has not yet elapsed. Recomputing eligibility
862
+ * with all freezes lifted (a human `retry` = unlimited attempts) and
863
+ * eventual idle time yields >= 1 firing, so a producer would re-arm or an
864
+ * idle step would become eligible. These are expected brakes/waits — never
865
+ * a defect; they do not affect the exit code. This classification does not
866
+ * itself make an idle successor reachable in the timeless BFS, so
867
+ * `completable` can remain false. Always present ([] when none).
787
868
  */
788
869
  stallStates: CheckFinding[];
789
870
  /**
package/dist/src/util.js CHANGED
@@ -138,7 +138,10 @@ export function parseDurationMs(spec) {
138
138
  const m = DUR_RE.exec(String(spec).trim());
139
139
  if (!m)
140
140
  throw new Error(`bad duration: ${spec} (use 90m, 2h, or seconds)`);
141
- return Number(m[1]) * UNIT_MS[m[2]];
141
+ const milliseconds = Number(m[1]) * UNIT_MS[m[2]];
142
+ if (!Number.isFinite(milliseconds))
143
+ throw new Error(`bad duration: ${spec} (duration is too large)`);
144
+ return milliseconds;
142
145
  }
143
146
  /** "30m" → 1800 seconds. */
144
147
  export function parseDurationSecs(spec) {