owenloop 0.5.8 → 0.5.9

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 (87) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +4 -2
  3. package/dist/packages/work/src/agent/loop.d.ts +23 -8
  4. package/dist/packages/work/src/agent/loop.js +48 -6
  5. package/dist/packages/work/src/consumed-verifier.js +6 -17
  6. package/dist/packages/work/src/exec/loop.d.ts +1 -1
  7. package/dist/packages/work/src/exec/loop.js +181 -32
  8. package/dist/packages/work/src/exec/receipt.d.ts +7 -7
  9. package/dist/packages/work/src/exec/receipt.js +6 -6
  10. package/dist/packages/work/src/harness/claude.js +100 -0
  11. package/dist/packages/work/src/hub/client.d.ts +19 -4
  12. package/dist/packages/work/src/hub/client.js +7 -3
  13. package/dist/packages/work/src/hub/types.d.ts +84 -0
  14. package/dist/packages/work/src/main.js +1 -0
  15. package/dist/packages/work/src/roles/agent-run.js +19 -22
  16. package/dist/packages/work/src/roles/exec.js +2 -0
  17. package/dist/packages/work/src/roles/settings.js +2 -0
  18. package/dist/packages/work/src/roles/shift.js +14 -2
  19. package/dist/packages/work/src/roles/util.d.ts +1 -0
  20. package/dist/packages/work/src/roles/util.js +10 -0
  21. package/dist/packages/work/src/settings/hub-roster-cache.d.ts +68 -0
  22. package/dist/packages/work/src/settings/hub-roster-cache.js +370 -0
  23. package/dist/packages/work/src/settings/roster.d.ts +84 -0
  24. package/dist/packages/work/src/settings/roster.js +364 -5
  25. package/dist/packages/work/src/settings/serving.d.ts +17 -0
  26. package/dist/packages/work/src/settings/serving.js +79 -0
  27. package/dist/packages/work/src/settings/settings.d.ts +14 -1
  28. package/dist/packages/work/src/settings/settings.js +14 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +108 -5
  30. package/dist/packages/work/src/shift/loop.js +299 -51
  31. package/dist/packages/work/src/shift/protocol.d.ts +7 -5
  32. package/dist/packages/work/src/shift/runtime.d.ts +15 -0
  33. package/dist/packages/work/src/shift/runtime.js +94 -4
  34. package/dist/packages/work/src/shift/server.js +2 -0
  35. package/dist/packages/work/src/shift/spawn.d.ts +17 -2
  36. package/dist/packages/work/src/shift/spawn.js +16 -13
  37. package/dist/packages/work/src/shift/state.d.ts +29 -2
  38. package/dist/packages/work/src/shift/state.js +45 -15
  39. package/dist/packages/work/src/usage.d.ts +1 -1
  40. package/dist/packages/work/src/usage.js +7 -1
  41. package/dist/packages/work/src/util/modifier-init.d.ts +7 -0
  42. package/dist/packages/work/src/util/modifier-init.js +73 -0
  43. package/dist/src/bundle/tar.d.ts +9 -4
  44. package/dist/src/bundle/tar.js +9 -4
  45. package/dist/src/capabilities.d.ts +6 -0
  46. package/dist/src/cli.d.ts +14 -1
  47. package/dist/src/cli.js +687 -75
  48. package/dist/src/config-dir.d.ts +1 -1
  49. package/dist/src/config-dir.js +1 -1
  50. package/dist/src/crypto/index.d.ts +1 -1
  51. package/dist/src/crypto/index.js +1 -1
  52. package/dist/src/crypto/org-root.d.ts +30 -12
  53. package/dist/src/crypto/org-root.js +162 -14
  54. package/dist/src/crypto/records.d.ts +2 -0
  55. package/dist/src/crypto/records.js +2 -0
  56. package/dist/src/defs.d.ts +6 -1
  57. package/dist/src/defs.js +203 -8
  58. package/dist/src/engine.d.ts +42 -7
  59. package/dist/src/engine.js +158 -16
  60. package/dist/src/index.d.ts +4 -4
  61. package/dist/src/index.js +2 -2
  62. package/dist/src/mcp/serve.d.ts +22 -0
  63. package/dist/src/mcp/serve.js +88 -8
  64. package/dist/src/model.d.ts +2 -0
  65. package/dist/src/model.js +32 -25
  66. package/dist/src/order-resolver.d.ts +1 -0
  67. package/dist/src/order-resolver.js +8 -1
  68. package/dist/src/schemas/index.d.ts +11 -0
  69. package/dist/src/schemas/order.v1.schema.json +7 -1
  70. package/dist/src/store.d.ts +5 -0
  71. package/dist/src/store.js +43 -8
  72. package/dist/src/types.d.ts +40 -3
  73. package/docs/authoring.md +90 -2
  74. package/docs/bundles.md +26 -2
  75. package/docs/cli.md +170 -28
  76. package/docs/crypto.md +19 -3
  77. package/docs/design.md +70 -1
  78. package/docs/routing.md +189 -34
  79. package/docs/shift-logs.md +20 -9
  80. package/docs/wire-contracts.md +50 -7
  81. package/examples/workflows/delivery.yaml +31 -14
  82. package/examples/workflows/ship.yaml +10 -2
  83. package/package.json +1 -1
  84. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  85. package/plugins/claude-code/plugin/.mcp.json +1 -1
  86. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  87. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
package/dist/src/model.js CHANGED
@@ -43,6 +43,10 @@ export function judgeNameOf(step) {
43
43
  export function mapProduce(step) {
44
44
  return step.produces.find((p) => p.kind === 'map');
45
45
  }
46
+ /** All per-element outputs a map step owns for each input index. */
47
+ export function mapProduces(step) {
48
+ return step.produces.filter((p) => p.kind === 'map');
49
+ }
46
50
  /**
47
51
  * The concrete input artifact a map element binds on for index `i`. Normally the
48
52
  * bare collection member `stem[i]`. But when the map consume carries a suffix
@@ -451,8 +455,8 @@ export function pendingOwed(def, arts) {
451
455
  const mode = stepMode(step);
452
456
  if (mode === 'map') {
453
457
  const mc = mapConsume(step);
454
- const mp = mapProduce(step);
455
- if (!mc || !mp)
458
+ const mps = mapProduces(step);
459
+ if (!mc || mps.length === 0)
456
460
  continue;
457
461
  // the bare members fix the index space; a child is owed only once that
458
462
  // index's actual consumed input (bare member, or its suffixed child) greens
@@ -462,7 +466,8 @@ export function pendingOwed(def, arts) {
462
466
  continue;
463
467
  if (!isGreen(arts.get(mapInputPath(mc, el.index))))
464
468
  continue;
465
- ensure(bindProduce(mp, el.index), step.name);
469
+ for (const mp of mps)
470
+ ensure(bindProduce(mp, el.index), step.name);
466
471
  }
467
472
  }
468
473
  else {
@@ -627,8 +632,8 @@ export function eligibleFirings(def, arts, time, opts) {
627
632
  else if (mode === 'map') {
628
633
  if (plainSatisfied) {
629
634
  const mc = mapConsume(step);
630
- const mp = mapProduce(step);
631
- if (mc && mp) {
635
+ const mps = mapProduces(step);
636
+ if (mc && mps.length > 0) {
632
637
  for (const m of members(arts, mc.stem)) {
633
638
  const el = parseElement(m.path);
634
639
  if (!el)
@@ -638,22 +643,25 @@ export function eligibleFirings(def, arts, time, opts) {
638
643
  const inPath = mapInputPath(mc, el.index);
639
644
  if (!isGreen(arts.get(inPath)))
640
645
  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)
646
+ const outputs = mps
647
+ .map((mp) => bindProduce(mp, el.index))
648
+ .filter((outPath) => {
649
+ const outArt = arts.get(outPath);
650
+ // Group membership is singleton-only (§26.3), so a map-produce
651
+ // path cannot be a group member today. Keep the defensive check
652
+ // so a future relaxation cannot reopen the eligibility/commit gap.
653
+ return isDebt(outArt)
654
+ && (opts?.ignoreFreeze || !frozen(outArt, step))
655
+ && groupBlockingWinner(def, arts, outPath) === undefined;
656
+ });
657
+ if (outputs.length === 0)
650
658
  continue;
651
659
  firings.push({
652
660
  step: step.name,
653
661
  key: m.path,
654
662
  index: el.index,
655
663
  inputs: [inPath, ...plainPaths],
656
- outputs: [outPath],
664
+ outputs,
657
665
  });
658
666
  }
659
667
  }
@@ -808,7 +816,7 @@ export function canEverFire(step, def, reachable) {
808
816
  case 'reduce':
809
817
  return singletonProduces(step).length > 0;
810
818
  case 'map':
811
- return !!mapProduce(step) && !!mapConsume(step);
819
+ return mapProduces(step).length > 0 && !!mapConsume(step);
812
820
  case 'plain':
813
821
  return plainOutputs(step).length > 0;
814
822
  default:
@@ -1116,12 +1124,12 @@ function stepOwesSomething(def, step, arts) {
1116
1124
  const mode = stepMode(step);
1117
1125
  if (mode === 'map') {
1118
1126
  const mc = mapConsume(step);
1119
- const mp = mapProduce(step);
1120
- if (!mc || !mp)
1127
+ const mps = mapProduces(step);
1128
+ if (!mc || mps.length === 0)
1121
1129
  return false;
1122
1130
  return members(arts, mc.stem).some((m) => {
1123
1131
  const el = parseElement(m.path);
1124
- return el ? isDebt(arts.get(bindProduce(mp, el.index))) : false;
1132
+ return el !== null && mps.some((mp) => isDebt(arts.get(bindProduce(mp, el.index))));
1125
1133
  });
1126
1134
  }
1127
1135
  return plainOutputs(step).some((p) => isDebt(arts.get(p)));
@@ -1151,13 +1159,13 @@ function blockingInputs(def, step, arts) {
1151
1159
  // a map child that owes but can't fire is blocked on its per-element input
1152
1160
  // (its bare member, or — for a chained map — the suffixed child upstream owes)
1153
1161
  const mc = mapConsume(step);
1154
- const mp = mapProduce(step);
1155
- if (mc && mp) {
1162
+ const mps = mapProduces(step);
1163
+ if (mc && mps.length > 0) {
1156
1164
  for (const m of members(arts, mc.stem)) {
1157
1165
  const el = parseElement(m.path);
1158
1166
  if (!el)
1159
1167
  continue;
1160
- if (!isDebt(arts.get(bindProduce(mp, el.index))))
1168
+ if (!mps.some((mp) => isDebt(arts.get(bindProduce(mp, el.index)))))
1161
1169
  continue;
1162
1170
  const inPath = mapInputPath(mc, el.index);
1163
1171
  if (!isGreen(arts.get(inPath)))
@@ -1218,9 +1226,8 @@ export function buildTrace(def, artifacts, runs) {
1218
1226
  stems.push(p.stem);
1219
1227
  for (const p of collectionProduces(step))
1220
1228
  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")
1229
+ for (const mp of mapProduces(step))
1230
+ stems.push(mp.raw); // use raw patterns (e.g. "gather.source[$i].check")
1224
1231
  stepProducedStems.set(step.name, stems);
1225
1232
  }
1226
1233
  // --- step 3: build the timeline ---
@@ -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
  }
@@ -555,6 +555,9 @@ export declare const WIRE_SCHEMAS: {
555
555
  type: string;
556
556
  minimum: number;
557
557
  };
558
+ requested: {
559
+ type: string;
560
+ };
558
561
  };
559
562
  };
560
563
  };
@@ -590,6 +593,14 @@ export declare const WIRE_SCHEMAS: {
590
593
  minLength: number;
591
594
  };
592
595
  };
596
+ crews: {
597
+ type: string;
598
+ description: string;
599
+ items: {
600
+ type: string;
601
+ minLength: number;
602
+ };
603
+ };
593
604
  reroutedFrom: {
594
605
  type: string;
595
606
  description: string;
@@ -92,7 +92,8 @@
92
92
  },
93
93
  "by": { "type": "string" },
94
94
  "text": { "type": "string" },
95
- "fromVersion": { "type": "integer", "minimum": 0 }
95
+ "fromVersion": { "type": "integer", "minimum": 0 },
96
+ "requested": { "type": "string" }
96
97
  }
97
98
  }
98
99
  },
@@ -116,6 +117,11 @@
116
117
  "description": "The composed routing capabilities this order was offered under: each authored step capability, suffixed ':<modifier>' where a modifier applied. A snapshot of the offer — a claimed order is never recomposed. When 'reroutedFrom' is present this holds the reroute target instead, because this is the capability actually being served.",
117
118
  "items": { "type": "string", "minLength": 1 }
118
119
  },
120
+ "crews": {
121
+ "type": "array",
122
+ "description": "The ordered crews the offering side matched for this capability-bearing order. Hub → worker; unlike worker → hub serve_crews, this snapshot decides which local roster resolves the order.",
123
+ "items": { "type": "string", "minLength": 1 }
124
+ },
119
125
  "reroutedFrom": {
120
126
  "type": "array",
121
127
  "description": "The composed capabilities this order WOULD have been offered under, present only when a reroute rule substituted something else into 'capabilities'. Absent on every ordinary offer, so its presence is itself the signal that the order is not running on the capability its definition asked for.",
@@ -87,6 +87,11 @@ export declare class Store {
87
87
  * decide what "drift" means, it just persists what the engine computed.
88
88
  */
89
89
  repinWorkflowDef(id: string, snapshot: WorkflowDef, hash: string): void;
90
+ /** Apply an engine-authored routing patch without rewriting authored params. */
91
+ setWorkflowRouting(id: string, patch: {
92
+ modifier?: string;
93
+ meta?: Record<string, unknown>;
94
+ }): void;
90
95
  getWorkflow(id: string): WorkflowRow | undefined;
91
96
  listWorkflows(): WorkflowRow[];
92
97
  /** Deletes only this workflow's own rows (artifact/task/run/workflow). Does NOT
package/dist/src/store.js CHANGED
@@ -29,6 +29,7 @@ CREATE TABLE IF NOT EXISTS workflow (
29
29
  title TEXT,
30
30
  params TEXT NOT NULL DEFAULT '{}',
31
31
  modifier TEXT,
32
+ meta TEXT,
32
33
  created_at INTEGER NOT NULL
33
34
  );
34
35
 
@@ -150,8 +151,11 @@ CREATE TABLE IF NOT EXISTS meta (
150
151
  * nullable `modifier` column (see `migrate()`). Additive and un-backfilled —
151
152
  * NULL on every existing row means "unmodified run", which is the correct
152
153
  * reading of an instance created before modifiers existed.
154
+ *
155
+ * Bumped to '11' for bound artifacts: the `workflow` table gains nullable
156
+ * JSON `meta` for non-routing `meta.<key>` artifact binds.
153
157
  */
154
- const SCHEMA_VERSION = '10';
158
+ const SCHEMA_VERSION = '11';
155
159
  /** Thrown by the `Store` constructor when the on-disk `schema_version` is
156
160
  * newer than this binary's `SCHEMA_VERSION` — the operator needs to
157
161
  * upgrade their owenloop install to open this database. */
@@ -369,6 +373,13 @@ function mapWorkflow(r) {
369
373
  // become the same thing downstream, where '' would compose 'build:'.
370
374
  if (r.modifier !== null)
371
375
  out.modifier = r.modifier;
376
+ const meta = fromJson(r.meta, undefined, {
377
+ table: 'workflow',
378
+ id: r.id,
379
+ column: 'meta',
380
+ });
381
+ if (meta !== undefined)
382
+ out.meta = meta;
372
383
  return out;
373
384
  }
374
385
  // ---- the store ---------------------------------------------------------------
@@ -517,14 +528,18 @@ export class Store {
517
528
  if (!wfCols.some((c) => c.name === 'def_hash')) {
518
529
  this.db.exec(`ALTER TABLE workflow ADD COLUMN def_hash TEXT`);
519
530
  }
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
531
+ // Routing modifier: the ONE modifier this instance carries. The starter
532
+ // supplies its initial value; a def-declared artifact bind may later update
533
+ // it through the engine's routing writer. NULL on every pre-existing row,
534
+ // which is exactly right — an instance created before modifiers existed is
535
+ // an unmodified run and every step is offered on bare capabilities. No
524
536
  // backfill: there is no value to invent.
525
537
  if (!wfCols.some((c) => c.name === 'modifier')) {
526
538
  this.db.exec(`ALTER TABLE workflow ADD COLUMN modifier TEXT`);
527
539
  }
540
+ if (!wfCols.some((c) => c.name === 'meta')) {
541
+ this.db.exec(`ALTER TABLE workflow ADD COLUMN meta TEXT`);
542
+ }
528
543
  // Only a genuine pre-v8 -> v8 upgrade may backfill the current projection's
529
544
  // reason thread. Re-opening an already-v8 database must not manufacture a
530
545
  // second copy of its lifecycle events (even though the legacy keys differ
@@ -581,9 +596,9 @@ export class Store {
581
596
  const at = nowMs();
582
597
  this.db
583
598
  .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);
599
+ (id, def, title, params, produced_by_wf, produced_by_path, def_snapshot, def_hash, modifier, meta, created_at)
600
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
601
+ .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
602
  return this.getWorkflow(id);
588
603
  }
589
604
  /**
@@ -596,6 +611,26 @@ export class Store {
596
611
  .prepare('UPDATE workflow SET def_snapshot = ?, def_hash = ? WHERE id = ?')
597
612
  .run(JSON.stringify(snapshot), hash, id);
598
613
  }
614
+ /** Apply an engine-authored routing patch without rewriting authored params. */
615
+ setWorkflowRouting(id, patch) {
616
+ const assignments = [];
617
+ const values = [];
618
+ if (patch.modifier !== undefined) {
619
+ assignments.push('modifier = ?');
620
+ values.push(patch.modifier);
621
+ }
622
+ if (patch.meta !== undefined) {
623
+ const current = this.getWorkflow(id);
624
+ if (current === undefined)
625
+ throw new Error(`cannot update routing for unknown workflow '${id}'`);
626
+ assignments.push('meta = ?');
627
+ values.push(JSON.stringify({ ...(current.meta ?? {}), ...patch.meta }));
628
+ }
629
+ if (assignments.length === 0)
630
+ return;
631
+ values.push(id);
632
+ this.db.prepare(`UPDATE workflow SET ${assignments.join(', ')} WHERE id = ?`).run(...values);
633
+ }
599
634
  getWorkflow(id) {
600
635
  const r = this.db.prepare('SELECT * FROM workflow WHERE id = ?').get(id);
601
636
  return r ? mapWorkflow(r) : undefined;
@@ -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
@@ -178,6 +180,12 @@ export interface Order {
178
180
  * served, so it is the one a shift must resolve its model against.
179
181
  */
180
182
  capabilities?: string[];
183
+ /**
184
+ * Ordered crews the offering side matched for this order's capabilities.
185
+ * Absent when the caller supplied no stamps. Hub → worker, NOT the separate
186
+ * worker → hub `serve_crews` narrowing advertisement.
187
+ */
188
+ crews?: string[];
181
189
  /**
182
190
  * The composed capabilities this order WOULD have been offered under, present
183
191
  * only when a caller-supplied reroute rule substituted something else into
@@ -311,14 +319,18 @@ export interface WorkflowData {
311
319
  params?: Record<string, string>;
312
320
  /**
313
321
  * 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).
322
+ * `modifiers` set when the run is created. The starter supplies the initial
323
+ * value; after that, only the engine may replace it while accepting an
324
+ * artifact whose def-declared bind targets `modifier`. No step, worker, or
325
+ * judge writes it directly; escalation still overrides it per-offer without
326
+ * changing the stored value.
317
327
  *
318
328
  * Absent = an unmodified run: every step is offered on bare capabilities.
319
329
  * Deletes with the run, like the rest of the row.
320
330
  */
321
331
  modifier?: string;
332
+ /** Engine-written, non-routing metadata populated by artifact binds. */
333
+ meta?: Record<string, unknown>;
322
334
  /** Instance-to-definition pinning (§28): the compiled def this instance was
323
335
  * created against, snapshotted verbatim as JSON. Absent on rows created
324
336
  * before this feature shipped — those instances fall back to today's
@@ -359,6 +371,11 @@ export interface GroupDef {
359
371
  mode: GroupMode;
360
372
  of: string[];
361
373
  }
374
+ /** A normalized artifact-to-instance routing write declared on a produce. */
375
+ export interface ArtifactBind {
376
+ to: string;
377
+ from: string;
378
+ }
362
379
  /** A parsed produce declaration. */
363
380
  export interface ProducePattern {
364
381
  raw: string;
@@ -368,6 +385,8 @@ export interface ProducePattern {
368
385
  suffix: string;
369
386
  /** optional JSON Schema the produced value must satisfy at commit time (§19) */
370
387
  schema?: JsonSchema;
388
+ /** Optional normalized artifact-to-instance write applied on acceptance. */
389
+ bind?: ArtifactBind;
371
390
  /** §6/§18 per-produce override of the step's maxAttempts (judgment-reject
372
391
  * stall cap). Falls back to the owning step's maxAttempts when absent —
373
392
  * see model.ts effectiveMaxAttempts(). Only meaningful on {name,...}
@@ -432,6 +451,22 @@ export interface EffectDef {
432
451
  * Defaults to 'escalate' when idempotent:false and omitted. */
433
452
  onInvalidate?: 'pin' | 'escalate' | string;
434
453
  }
454
+ /**
455
+ * Declares that a step is cleanup: it must still be dispatched when the run is
456
+ * cancelled, not only on the normal green path.
457
+ *
458
+ * This is not a firing trigger. `on:`/`FiringTrigger` is the in-run scheduler's
459
+ * vocabulary, evaluated from artifact state and time facts. Run cancellation is
460
+ * neither of those, so `onCancel:` is inert in this engine: it is a declaration
461
+ * the control plane reads when it cancels a run.
462
+ */
463
+ export interface OnCancelDef {
464
+ /** The subset of the step's own plain consume stems the cancel-path firing
465
+ * requires. Required, may be empty. This is explicit because a cleanup
466
+ * step's normal consume set may include a terminal artifact that never
467
+ * greens after cancellation, and the control plane must not guess inputs. */
468
+ consumes: string[];
469
+ }
435
470
  /** A step (step) definition. */
436
471
  /**
437
472
  * A step's escalation rule (def-authored, engine-applied).
@@ -514,6 +549,8 @@ export interface StepDef {
514
549
  idleAfter?: string;
515
550
  /** Parsed idleAfter in milliseconds. */
516
551
  idleAfterMs?: number;
552
+ /** Cleanup-on-cancel declaration. Absent = no cancel-path dispatch. See OnCancelDef. */
553
+ onCancel?: OnCancelDef;
517
554
  /** Per-step reap TTL override in milliseconds. Falls back to the engine's DEFAULT_REAP_TTL_MS. */
518
555
  reapTtlMs?: number;
519
556
  /** A2: opaque routing capabilities for peer-orchestrator claim filtering. A tick
package/docs/authoring.md CHANGED
@@ -41,7 +41,8 @@ steps:
41
41
  properties: { plan: { type: string } }
42
42
  # maxAttempts: 2 # optional; overrides the step's maxAttempts (below)
43
43
  # maxSchemaFailures: 1 # just for this produce — see design.md §6
44
- body: | # the prompt; ${WORKFLOW} ${RUN} ${INDEX} are filled in
44
+ # bind: modifier # accepted value's `modifier` key writes through to run routing
45
+ body: | # the prompt; runtime placeholders are filled in when available
45
46
  Read the proposal and produce a `plan`.
46
47
  bodyFile: path/to.md # load body from a file, relative to this workflow's dir (must resolve inside it); mutually exclusive with body
47
48
 
@@ -62,6 +63,8 @@ steps:
62
63
  onInvalidate: escalate # consulted only when idempotent: false (see below)
63
64
  on: [inputsGreen] # optional; firing trigger (see below)
64
65
  idleAfter: 30m # required when 'idle' is in on:
66
+ onCancel: # optional cleanup declaration (see below)
67
+ consumes: [workspace] # plain consume subset needed after cancellation
65
68
  invalidates: [plan] # which input stems this step may invalidate
66
69
  cadence: "0s" # min spacing between runs (e.g. "30m")
67
70
  maxRunsPerDay: 1000
@@ -225,7 +228,9 @@ full contract.
225
228
  A command step's `consumes:` reach the command through its environment, not its
226
229
  working directory: `owenloop work exec` sets `OWENLOOP_CONSUMES` with the JSON
227
230
  inline, or `OWENLOOP_CONSUMES_FILE` with a path to it once that JSON exceeds
228
- 64 KiB. See [`docs/bundles.md` § Consumed inputs for command
231
+ 64 KiB. The worker also supplies rejection feedback and the order's current
232
+ modifier through `OWENLOOP_FEEDBACK`/`OWENLOOP_FEEDBACK_FILE` and
233
+ `OWENLOOP_MODIFIER`. See [`docs/bundles.md` § Consumed inputs for command
229
234
  steps](bundles.md#consumed-inputs-for-command-steps) for the reader snippet and
230
235
  the omitted-key rule.
231
236
 
@@ -314,6 +319,57 @@ if nothing consumes it. A stem under `generates:` is deliberately consumed by no
314
319
  are otherwise identical: schema-validated, fingerprinted, greenable, and visible in
315
320
  `status`/`show`.
316
321
 
322
+ ## `bind:` — write an accepted artifact into run state
323
+
324
+ A produce mapping may declare a `bind:` target. When that artifact is accepted,
325
+ the engine writes the selected value into the run instance in the same
326
+ acceptance transaction. The artifact's own version and event history remains the
327
+ record of the value and any later rejection; the bind adds the engine's sync
328
+ event.
329
+
330
+ The short form reads the accepted object's key named after the final segment of
331
+ the target. Here, the producer submits an object such as
332
+ `{ modifier: 'deep' }`; `bind: modifier` reads its `modifier` key.
333
+
334
+ ```yaml
335
+ modifiers: [express, standard, deep]
336
+ steps:
337
+ - name: choose_modifier
338
+ produces:
339
+ - name: modifier
340
+ bind: modifier
341
+ ```
342
+
343
+ The mapping form selects a dotted object path. It is equivalent to the short
344
+ form when `from` is omitted: `bind: { to: meta.customer }` reads the
345
+ accepted object's `customer` key.
346
+
347
+ ```yaml
348
+ - { name: customer, bind: { to: meta.customer } }
349
+ - name: decision
350
+ bind: { to: modifier, from: payload.value }
351
+ ```
352
+
353
+ The two supported target families are:
354
+
355
+ - `modifier` — the extracted value must be one member of the workflow's
356
+ declared `modifiers:` list. A name with whitespace cannot be in that list
357
+ because `modifiers:` refuses it at definition-parse time. A workflow may bind
358
+ `modifier` only once. A value outside the list is refused at submit time.
359
+ - `meta.<key>` — writes any JSON value into non-routing instance metadata.
360
+ Metadata never changes capability composition or routing.
361
+
362
+ `from` is always a dot-separated path through object keys; there is no
363
+ whole-value form. Arrays, escaping, and array indexes are not part of this
364
+ grammar. A missing path is a submit-time refusal.
365
+ Bindings are supported on singleton and map produces, not collection produces.
366
+ Only a green acceptance applies the bind: a producer submission that is waiting
367
+ for judges has not synchronized the run yet.
368
+
369
+ When a capability-bearing step can run before the modifier-bound artifact is
370
+ accepted, lint warns that the step is not downstream of the bound artifact.
371
+ Wire the dependency explicitly if that step must use the synchronized modifier.
372
+
317
373
  ## `judges:` — quality gates before green
318
374
 
319
375
  A `produces` entry can declare one or more **judges**: deterministic quality
@@ -572,6 +628,38 @@ carry an empty input fingerprint, so a commit can never satisfy it, and
572
628
  relative `idleAfter` window and survives a process restart.
573
629
  `engine.nextAlarm(workflow)` tells an external scheduler when to wake the instance.
574
630
 
631
+ ## `onCancel:` — cleanup that survives cancellation
632
+
633
+ `onCancel:` declares that a step is cleanup a control plane should dispatch when
634
+ it cancels a run. It is **not** an `on:` firing trigger: the standalone engine
635
+ has no run-cancellation state and never schedules it. A host that supports
636
+ cancellation reads this declaration separately.
637
+
638
+ The declaration names the inputs needed on the cancel path:
639
+
640
+ ```yaml
641
+ - name: deprovisioner
642
+ consumes: [merge, workspace] # normal path
643
+ onCancel:
644
+ consumes: [workspace] # cancel path
645
+ ```
646
+
647
+ The subset is explicit because cancellation can leave a normal input permanently
648
+ non-green. In this example, `merge` is terminal and will not green after a
649
+ cancel, so the control plane must not guess whether to wait for it or omit it.
650
+
651
+ `onCancel:` must be a mapping with a required `consumes:` list; an empty list
652
+ is allowed. Each listed name must be one of the step's own plain consumes, and a
653
+ name may appear only once. Map (`[$i]`) and reduce (`[*]`) consumes are not
654
+ allowed because a cancellation firing is keyless and runs once. The key is not
655
+ valid on a `calls:` step. An `allGreen` or `idle` evaluator may carry
656
+ `onCancel:`, but because evaluators cannot consume inputs, its list must be
657
+ empty.
658
+
659
+ `terminal: true` and `onCancel:` are deliberately compatible. Whether running
660
+ a destructive step during cleanup is sensible is the workflow author's decision,
661
+ not an engine policy.
662
+
575
663
  ## Consume / produce grammar
576
664
 
577
665
  | pattern | role | fires |
package/docs/bundles.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # `.wnlp` bundle format
2
2
 
3
- A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces identical archive bytes.
3
+ A `.wnlp` file packages one versioned package namespace, one or more named workflow definitions, and the regular files those definitions reference. The physical format is a gzip-compressed POSIX/PAX tar archive. Packing the same source bytes and canonical executable-bit choices produces an identical uncompressed canonical tar and therefore an identical bundle digest. The gzip wrapper's compressed payload depends on the zlib implementation linked by the running Node process and is not part of the bundle identity.
4
4
 
5
5
  The bundle APIs are independent of the local workflow store and the network:
6
6
 
@@ -135,7 +135,7 @@ For every regular file:
135
135
  - Every entry's data padding, including the padding after a `PaxHeader` data record, is zero-filled.
136
136
  - The archive ends with exactly two zero blocks and no bytes after the terminator.
137
137
 
138
- The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Gzip mtime bytes are zero, and gzip header byte 9 (the OS byte) is explicitly forced to zero so Darwin and Linux produce the same bytes.
138
+ The gzip wrapper uses compression level 9 and has no optional filename, comment, or extra fields. Its magic, CM, FLG, MTIME, and OS ranges (bytes 0-1, 2, 3, 4-7, and 9) are fixed; mtime is zero and header byte 9 (the OS byte) is explicitly forced to zero. XFL (byte 8) comes from the linked zlib implementation and is intentionally not normalized. The compressed payload itself varies with the linked zlib implementation and is not the bundle identity; see the def digest above.
139
139
 
140
140
  The canonical tar contains regular-file entries only. Parent directories are implied by `/`-separated file paths and are never emitted as tar entries. The strict reader rejects archive symlink, hardlink, device, FIFO, socket, directory, and unknown entry types. The packer rejects source symlinks and non-regular filesystem nodes. Absolute paths, `.` segments, and `..` traversal are refused rather than normalized.
141
141
 
@@ -255,6 +255,30 @@ consume-side verification under its hard rule and refuses the whole order when
255
255
  the consumed evidence is absent, unverifiable, or invalid, so the environment
256
256
  block is built only for an order whose inputs already verified.
257
257
 
258
+ ### Rejection feedback and modifier context
259
+
260
+ When an order has owed paths with non-empty reason threads, `owenloop work exec`
261
+ also supplies the feedback as a JSON array through one of these variables:
262
+
263
+ | Variable | Set when | Value |
264
+ | --- | --- | --- |
265
+ | `OWENLOOP_FEEDBACK` | serialized feedback is at or under 65536 bytes | inline array of `{path, reasons}` objects |
266
+ | `OWENLOOP_FEEDBACK_FILE` | serialized feedback is strictly larger | absolute path to a private `0600` UTF-8 file containing that array |
267
+
268
+ Exactly one feedback variable is present when feedback exists; both are removed
269
+ when there is no feedback, so a nested command cannot inherit a stale thread.
270
+ The overflow file is removed after the command exits. Each `reasons` entry is
271
+ the normal artifact reason shape and may include `requested`, the machine-readable
272
+ replacement requested for a bound modifier artifact.
273
+
274
+ `OWENLOOP_MODIFIER` is set to the modifier stamped on this order, including an
275
+ escalation target when the order is an escalated re-offer. It is absent when the
276
+ run has no modifier. This is order metadata, not an instruction to mutate the
277
+ run; only an accepted artifact with a declared bind can do that.
278
+
279
+ An agent prompt can read the same value as `${MODIFIER}`. Unknown placeholders
280
+ remain unchanged; when an order has no modifier, `${MODIFIER}` remains literal.
281
+
258
282
  ## Working directory for command steps
259
283
 
260
284
  An order carries a `workdir` when its step declared `workdir:` or