owenloop 0.5.1 → 0.5.2

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 (81) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +9 -2
  3. package/dist/packages/work/src/agent/brief.d.ts +21 -0
  4. package/dist/packages/work/src/agent/brief.js +42 -1
  5. package/dist/packages/work/src/agent/capability-model.d.ts +123 -0
  6. package/dist/packages/work/src/agent/capability-model.js +148 -0
  7. package/dist/packages/work/src/agent/loop.d.ts +47 -4
  8. package/dist/packages/work/src/agent/loop.js +83 -53
  9. package/dist/packages/work/src/exec/loop.d.ts +17 -0
  10. package/dist/packages/work/src/exec/loop.js +195 -34
  11. package/dist/packages/work/src/exec/runner.js +15 -5
  12. package/dist/packages/work/src/harness/session-store.d.ts +3 -1
  13. package/dist/packages/work/src/harness/session-store.js +46 -22
  14. package/dist/packages/work/src/hold/mcp.js +9 -2
  15. package/dist/packages/work/src/hub/client.d.ts +7 -1
  16. package/dist/packages/work/src/hub/client.js +1 -0
  17. package/dist/packages/work/src/hub/types.d.ts +71 -3
  18. package/dist/packages/work/src/roles/agent-run.js +8 -9
  19. package/dist/packages/work/src/roles/hold.d.ts +2 -0
  20. package/dist/packages/work/src/roles/hold.js +39 -8
  21. package/dist/packages/work/src/roles/settings.js +18 -6
  22. package/dist/packages/work/src/roles/shift.js +13 -1
  23. package/dist/packages/work/src/settings/settings.d.ts +60 -7
  24. package/dist/packages/work/src/settings/settings.js +69 -22
  25. package/dist/packages/work/src/shift/logretention.d.ts +253 -0
  26. package/dist/packages/work/src/shift/logretention.js +407 -0
  27. package/dist/packages/work/src/shift/logsink.d.ts +14 -0
  28. package/dist/packages/work/src/shift/logsink.js +98 -0
  29. package/dist/packages/work/src/shift/loop.d.ts +18 -1
  30. package/dist/packages/work/src/shift/loop.js +250 -12
  31. package/dist/packages/work/src/shift/protocol.d.ts +124 -1
  32. package/dist/packages/work/src/shift/protocol.js +14 -0
  33. package/dist/packages/work/src/shift/runtime.d.ts +14 -0
  34. package/dist/packages/work/src/shift/runtime.js +229 -6
  35. package/dist/packages/work/src/shift/server.d.ts +13 -0
  36. package/dist/packages/work/src/shift/server.js +61 -36
  37. package/dist/packages/work/src/shift/spawn.d.ts +78 -5
  38. package/dist/packages/work/src/shift/spawn.js +158 -12
  39. package/dist/packages/work/src/shift/state.d.ts +25 -0
  40. package/dist/packages/work/src/shift/state.js +29 -5
  41. package/dist/packages/work/src/shift/truncate.d.ts +35 -0
  42. package/dist/packages/work/src/shift/truncate.js +73 -0
  43. package/dist/packages/work/src/submit-proof.d.ts +31 -6
  44. package/dist/packages/work/src/submit-proof.js +33 -7
  45. package/dist/packages/work/src/submit-value.d.ts +48 -0
  46. package/dist/packages/work/src/submit-value.js +118 -0
  47. package/dist/packages/work/src/usage.d.ts +1 -1
  48. package/dist/packages/work/src/usage.js +11 -0
  49. package/dist/src/capabilities.d.ts +93 -0
  50. package/dist/src/capabilities.js +101 -0
  51. package/dist/src/cli.js +14 -9
  52. package/dist/src/crypto/records.d.ts +3 -0
  53. package/dist/src/crypto/records.js +11 -0
  54. package/dist/src/defs.js +192 -4
  55. package/dist/src/engine.d.ts +112 -3
  56. package/dist/src/engine.js +224 -28
  57. package/dist/src/hub.d.ts +27 -11
  58. package/dist/src/hub.js +24 -18
  59. package/dist/src/index.d.ts +3 -1
  60. package/dist/src/index.js +4 -1
  61. package/dist/src/mcp/serve.js +11 -4
  62. package/dist/src/model.d.ts +36 -0
  63. package/dist/src/model.js +46 -0
  64. package/dist/src/schemas/index.d.ts +17 -0
  65. package/dist/src/schemas/order.v1.schema.json +17 -3
  66. package/dist/src/store.d.ts +33 -1
  67. package/dist/src/store.js +57 -4
  68. package/dist/src/types.d.ts +102 -2
  69. package/docs/authoring.md +7 -0
  70. package/docs/bundles.md +103 -3
  71. package/docs/cli.md +127 -9
  72. package/docs/crypto.md +23 -7
  73. package/docs/shift-logs.md +642 -0
  74. package/docs/wire-contracts.md +34 -19
  75. package/package.json +1 -1
  76. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +1 -1
  77. package/plugins/claude-code/plugin/.mcp.json +1 -1
  78. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +1 -1
  79. package/plugins/codex/plugins/owenloop/.mcp.json +1 -1
  80. package/dist/packages/work/src/agent/model-policy.d.ts +0 -49
  81. package/dist/packages/work/src/agent/model-policy.js +0 -138
package/dist/src/defs.js CHANGED
@@ -26,6 +26,9 @@ import { parse as parseYaml } from 'yaml';
26
26
  import { parseConsume, parseProduce, parseWorkdirFrom } from "./paths.js";
27
27
  import { parseDurationMs, parseDurationSecs } from "./util.js";
28
28
  import { assertValidSchema } from "./schema.js";
29
+ // The separator lives with composition/matching (capabilities.ts); the parser
30
+ // only enforces that an AUTHORED name never contains it.
31
+ import { MODIFIER_SEPARATOR } from "./capabilities.js";
29
32
  /** Hand-maintained key allowlist for RawInput — kept next to the interface so
30
33
  * the two can't silently drift (§27 unknown-key rejection). */
31
34
  const RAW_INPUT_KEYS = ['name', 'producer', 'seedOwed', 'schema'];
@@ -35,13 +38,14 @@ const RAW_PRODUCE_KEYS = ['name', 'schema', 'judges', 'maxAttempts', 'maxSchemaF
35
38
  * fields, so it gets its own allowlist rather than folding into
36
39
  * RAW_PRODUCE_KEYS (§27 unknown-key rejection). */
37
40
  const RAW_GROUP_KEYS = ['group', 'mode', 'of'];
38
- const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'executor', 'command', 'spec'];
41
+ const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'executor', 'command', 'spec', 'capabilities'];
39
42
  /** Keys valid on a normal (non-calls:, non-include:) step entry. */
40
43
  const RAW_STEP_KEYS = [
41
44
  'name', 'consumes', 'produces', 'generates', 'invalidates', 'cadence',
42
45
  'maxRunsPerDay', 'parallel', 'maxAttempts', 'maxSchemaFailures', 'model',
43
46
  'workdir', 'workdirFrom', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
44
47
  'calls', 'reapTtl', 'capabilities', 'maxLease', 'x', 'executor', 'command', 'spec',
48
+ 'escalation',
45
49
  ];
46
50
  /** Keys valid on a calls: step entry — a DIFFERENT (smaller) shape than RawStep;
47
51
  * the `calls:` key is what routes an entry here instead of RAW_STEP_KEYS. */
@@ -49,7 +53,7 @@ const RAW_CALLS_KEYS = ['name', 'calls', 'inputs', 'produces'];
49
53
  /** Keys valid on an include: directive entry — the `include:` key is the
50
54
  * discriminator that routes an entry here instead of RAW_STEP_KEYS/RAW_CALLS_KEYS. */
51
55
  const RAW_INCLUDE_KEYS = ['include', 'as', 'inputs'];
52
- const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'executors'];
56
+ const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'executors', 'modifiers'];
53
57
  // ---- defaults ----------------------------------------------------------------
54
58
  const DEFAULTS = {
55
59
  cadence: '0s',
@@ -84,6 +88,75 @@ function asStringArray(v, ctx) {
84
88
  }
85
89
  return v;
86
90
  }
91
+ /**
92
+ * A routing capability as an author may write it: no separator, no surrounding
93
+ * whitespace, non-empty.
94
+ *
95
+ * Deliberately NOT a full charset rule. Capability names are opaque routing
96
+ * labels shared with a hub whose own validation is length + non-empty + no
97
+ * `personal:` prefix; imposing a charset here would reject names that already
98
+ * bind successfully today. The one new restriction is the reserved separator.
99
+ */
100
+ function assertAuthoredCapability(value, ctx) {
101
+ if (value.trim().length === 0) {
102
+ throw new DefError(`${ctx}: capability names must not be empty or whitespace`);
103
+ }
104
+ if (value.includes(MODIFIER_SEPARATOR)) {
105
+ throw new DefError(`${ctx}: capability '${value}' must not contain '${MODIFIER_SEPARATOR}' — ` +
106
+ 'the suffix position is reserved for the modifier the engine composes at offer time ' +
107
+ "(a run carrying 'deep' turns the authored capability 'wise' into 'wise:deep')");
108
+ }
109
+ }
110
+ /**
111
+ * Parse the def-level `modifiers:` block into a validated, order-insensitive
112
+ * set of plain names.
113
+ *
114
+ * Order is NOT preserved as meaning: the list is a vocabulary, and nothing in
115
+ * the engine compares two modifiers or treats one as higher than another. The
116
+ * array shape is only YAML's way of writing a set.
117
+ */
118
+ function parseModifiers(v, ctx) {
119
+ const values = asStringArray(v, ctx);
120
+ if (values.length === 0) {
121
+ throw new DefError(`${ctx} must list at least one modifier, or be omitted entirely`);
122
+ }
123
+ const seen = new Set();
124
+ for (const value of values) {
125
+ if (value.trim().length === 0) {
126
+ throw new DefError(`${ctx}: modifier names must not be empty or whitespace`);
127
+ }
128
+ if (value.includes(MODIFIER_SEPARATOR)) {
129
+ throw new DefError(`${ctx}: modifier '${value}' must not contain '${MODIFIER_SEPARATOR}' — ` +
130
+ 'it is the separator the engine composes with');
131
+ }
132
+ if (seen.has(value))
133
+ throw new DefError(`${ctx}: duplicate modifier '${value}'`);
134
+ seen.add(value);
135
+ }
136
+ return values;
137
+ }
138
+ /** Parse a step's `escalation:` block. Cross-checks against the def's declared
139
+ * modifier set and the step's effective maxAttempts happen in `validateDef`,
140
+ * which is the first place that sees the whole def. */
141
+ function parseEscalation(v, ctx) {
142
+ if (typeof v !== 'object' || v === null || Array.isArray(v)) {
143
+ throw new DefError(`${ctx} must be a mapping of { after, modifier }`);
144
+ }
145
+ const raw = v;
146
+ assertNoUnknownKeys(raw, ['after', 'modifier'], ctx);
147
+ if (raw['after'] === undefined)
148
+ throw new DefError(`${ctx} must set 'after'`);
149
+ if (raw['modifier'] === undefined)
150
+ throw new DefError(`${ctx} must set 'modifier'`);
151
+ const after = asNumber(raw['after'], 0, `${ctx}.after`);
152
+ if (!Number.isInteger(after) || after < 1) {
153
+ throw new DefError(`${ctx}.after must be a positive integer (rejection count that triggers the escalated re-offer)`);
154
+ }
155
+ const modifier = asString(raw['modifier'], `${ctx}.modifier`);
156
+ if (modifier.trim().length === 0)
157
+ throw new DefError(`${ctx}.modifier must not be empty`);
158
+ return { after, modifier };
159
+ }
87
160
  function asNumber(v, fallback, ctx) {
88
161
  if (v === undefined)
89
162
  return fallback;
@@ -269,6 +342,15 @@ function parseJudges(v, ctx, baseDir) {
269
342
  judge.command = asString(raw.command, `judge '${name}'.command`);
270
343
  if (raw.spec !== undefined)
271
344
  judge.spec = asExtension(raw.spec, `judge '${name}'.spec`);
345
+ if (raw.capabilities !== undefined) {
346
+ const caps = asStringArray(raw.capabilities, `judge '${name}'.capabilities`);
347
+ if (caps.length === 0) {
348
+ throw new DefError(`judge '${name}'.capabilities must not be empty — omit the key to inherit the producing step's capabilities`);
349
+ }
350
+ for (const cap of caps)
351
+ assertAuthoredCapability(cap, `judge '${name}'.capabilities`);
352
+ judge.capabilities = caps;
353
+ }
272
354
  return judge;
273
355
  });
274
356
  }
@@ -576,6 +658,8 @@ export function buildDef(raw, source, baseDir) {
576
658
  def.x = asExtension(r.x, `workflow '${name}'.x`);
577
659
  if (r.executors !== undefined)
578
660
  def.executors = asStringArray(r.executors, `workflow '${name}'.executors`);
661
+ if (r.modifiers !== undefined)
662
+ def.modifiers = parseModifiers(r.modifiers, `workflow '${name}'.modifiers`);
579
663
  return def;
580
664
  }
581
665
  // ---- Mode 1 expand helpers (M1-EXPAND) ----------------------------------------
@@ -772,7 +856,7 @@ export function parseDef(raw, source, baseDir) {
772
856
  * an ordinary step, because judge orders flow through the normal
773
857
  * eligibleFirings → applySchedule → claim → buildOrder pipeline (§7.1).
774
858
  */
775
- function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, producerX) {
859
+ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, producerX, producerCapabilities) {
776
860
  if (!pat.judges || pat.judges.length === 0)
777
861
  return [];
778
862
  return pat.judges.map((j) => {
@@ -798,6 +882,17 @@ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, produ
798
882
  // alter another synthesized step. Absence stays absence: no empty x bag.
799
883
  if (producerX !== undefined)
800
884
  step.x = structuredClone(producerX);
885
+ // Routing: an explicit judge `capabilities:` wins; otherwise the judge
886
+ // INHERITS the producer's. Without inheritance every synthesized judge
887
+ // would be capability-silent, and a capability-silent step bypasses the
888
+ // claim filter entirely — any polling crew could claim the judge that
889
+ // gates work routed deliberately to one crew. Copied, not shared, so a
890
+ // later mutation of either step cannot reach the other (same contract as
891
+ // the `x` clone above).
892
+ if (j.capabilities !== undefined)
893
+ step.capabilities = [...j.capabilities];
894
+ else if (producerCapabilities !== undefined)
895
+ step.capabilities = [...producerCapabilities];
801
896
  if (j.model !== undefined)
802
897
  step.model = j.model;
803
898
  if (j.executor !== undefined)
@@ -955,9 +1050,14 @@ function buildStep(rl, i, baseDir) {
955
1050
  // any caller), mirroring the groups.length > 0 pattern below.
956
1051
  if (rl.capabilities !== undefined) {
957
1052
  const ls = asStringArray(rl.capabilities, `step '${name}'.capabilities`);
1053
+ for (const cap of ls)
1054
+ assertAuthoredCapability(cap, `step '${name}'.capabilities`);
958
1055
  if (ls.length > 0)
959
1056
  step.capabilities = ls;
960
1057
  }
1058
+ if (rl.escalation !== undefined) {
1059
+ step.escalation = parseEscalation(rl.escalation, `step '${name}'.escalation`);
1060
+ }
961
1061
  // A3: per-step max total lease lifetime (duration string, same as reapTtl).
962
1062
  if (rl.maxLease !== undefined) {
963
1063
  step.maxLeaseMs = parseDurationMs(asString(rl.maxLease, `step '${name}'.maxLease`));
@@ -970,7 +1070,7 @@ function buildStep(rl, i, baseDir) {
970
1070
  }
971
1071
  }
972
1072
  const producerConsumeStems = consumes.map((c) => c.stem);
973
- const judgeSteps = producesPatterns.flatMap((p) => synthesizeJudgeSteps(name, p, producerConsumeStems, step.x));
1073
+ const judgeSteps = producesPatterns.flatMap((p) => synthesizeJudgeSteps(name, p, producerConsumeStems, step.x, step.capabilities));
974
1074
  return [step, ...judgeSteps];
975
1075
  }
976
1076
  // ---- validation --------------------------------------------------------------
@@ -1303,6 +1403,94 @@ export function validateDef(def) {
1303
1403
  }
1304
1404
  }
1305
1405
  }
1406
+ // ---- routing modifiers and escalation ------------------------------------
1407
+ //
1408
+ // Three separate rules, each with its own precondition. They are grouped
1409
+ // because they all read `def.modifiers`, not because they are one check.
1410
+ //
1411
+ // R1 escalation.modifier must be a member of the def's declared set, and
1412
+ // a step may not carry `escalation:` at all in a def that declares no
1413
+ // `modifiers:` — there is no target vocabulary for it to draw from.
1414
+ // R2 escalation.after must be strictly less than the effective maxAttempts
1415
+ // of EVERY produce on the step. At judgmentRejects >= maxAttempts the
1416
+ // engine freezes the artifact (`model.ts` isStalled), so a rule
1417
+ // authored at or past that threshold re-offers a step that can never
1418
+ // run again. Taking the MINIMUM across produces is the conservative
1419
+ // reading: the step is dead as soon as its shortest-fused produce
1420
+ // freezes, whatever the others allow.
1421
+ // R3 in a def that declares `modifiers:`, every command step must author
1422
+ // `capabilities`. A capability-silent step bypasses the claim filter
1423
+ // (`engine.ts` A2) entirely, so any polling crew could claim it —
1424
+ // and, under composition, it would never receive a modifier suffix
1425
+ // either, silently opting out of the routing the def just declared.
1426
+ //
1427
+ // SCOPED DELIBERATELY to modifier-declaring defs. The plan document
1428
+ // states this rule unconditionally, but every def that predates
1429
+ // modifiers (examples/workflows/command-executor.yaml among them) has
1430
+ // capability-silent command steps, and the same document promises
1431
+ // "defs without `modifiers:` run exactly as today". Opting into the
1432
+ // new routing vocabulary is what turns the stricter rule on.
1433
+ const declaredModifiers = new Set(def.modifiers ?? []);
1434
+ for (const l of def.steps) {
1435
+ if (l.escalation === undefined)
1436
+ continue;
1437
+ if (declaredModifiers.size === 0) {
1438
+ errors.push(`step '${l.name}': escalation is set but workflow '${def.name}' declares no modifiers:; ` +
1439
+ 'escalation.modifier must name a declared modifier');
1440
+ }
1441
+ else if (!declaredModifiers.has(l.escalation.modifier)) {
1442
+ errors.push(`step '${l.name}': escalation.modifier '${l.escalation.modifier}' is not in workflow ` +
1443
+ `'${def.name}'.modifiers (${[...declaredModifiers].join(', ')})`);
1444
+ }
1445
+ // An escalated re-offer is the same step's capabilities composed with the
1446
+ // target modifier. A step with no capabilities composes nothing, so the
1447
+ // re-offer would be byte-identical to the original offer: a rule that can
1448
+ // never route anywhere new.
1449
+ if (l.capabilities === undefined || l.capabilities.length === 0) {
1450
+ errors.push(`step '${l.name}': escalation is set but the step authors no capabilities; ` +
1451
+ 'an escalated re-offer composes <capability>:<modifier>, so there is nothing to escalate');
1452
+ }
1453
+ // The rule is REACHABILITY: at least one owed output must be able to sit at
1454
+ // `after` judgment rejects while still being re-offered. That is a MAX over
1455
+ // the per-produce caps, not a MIN, because the engine evaluates the trigger
1456
+ // per owed path and drops frozen paths from the firing rather than killing
1457
+ // the firing:
1458
+ //
1459
+ // - eligibleFirings (model.ts) filters a step's outputs to the ones that
1460
+ // are still debt AND not frozen, and emits the firing when that filtered
1461
+ // list is non-empty. A step producing `plan` (cap 6) and `consult`
1462
+ // (cap 2) keeps firing for `plan` after `consult` has stalled.
1463
+ // - routingFor (engine.ts) then tests `f.outputs.find((p) => isEscalated(
1464
+ // arts.get(p), rule.after))` — the SAME filtered list. One live path over
1465
+ // the threshold is enough to route.
1466
+ //
1467
+ // So the shortest-fused produce freezing does not end the step, and a
1468
+ // MIN ceiling would reject a def whose escalation is plainly reachable
1469
+ // through a longer-fused produce. The `>=` is still right at the MAX: an
1470
+ // artifact with `judgmentRejects >= cap` is stalled (isStalled, model.ts),
1471
+ // therefore frozen, therefore filtered out of `f.outputs` before routingFor
1472
+ // ever looks at it — so `after` equal to the highest cap can never fire.
1473
+ const attemptCeilings = l.produces.length > 0
1474
+ ? l.produces.map((p) => p.maxAttempts ?? l.maxAttempts)
1475
+ : [l.maxAttempts];
1476
+ const ceiling = Math.max(...attemptCeilings);
1477
+ if (l.escalation.after >= ceiling) {
1478
+ errors.push(`step '${l.name}': escalation.after (${l.escalation.after}) must be strictly less than ` +
1479
+ `the step's highest per-produce maxAttempts (${ceiling}); at ${ceiling} rejections every ` +
1480
+ 'output has frozen, so the escalated re-offer could never run');
1481
+ }
1482
+ }
1483
+ if (declaredModifiers.size > 0) {
1484
+ for (const l of def.steps) {
1485
+ if ((l.executor ?? 'agent') !== 'command')
1486
+ continue;
1487
+ if (l.capabilities === undefined || l.capabilities.length === 0) {
1488
+ errors.push(`step '${l.name}': workflow '${def.name}' declares modifiers:, so every command step must ` +
1489
+ 'author capabilities: — a capability-silent step is claimable by any crew and never ' +
1490
+ 'receives a modifier');
1491
+ }
1492
+ }
1493
+ }
1306
1494
  // Semantic invariant validation: unknown stem references and duplicate names.
1307
1495
  if (def.invariants && def.invariants.length > 0) {
1308
1496
  const invariantNames = new Set();
@@ -11,6 +11,7 @@
11
11
  */
12
12
  import type { WorkflowStatus } from './model.ts';
13
13
  import type { SchemaIssue } from './schema.ts';
14
+ import type { MatchMode } from './capabilities.ts';
14
15
  import type { Store } from './store.ts';
15
16
  import type { Author, Fingerprint, Order, WorkflowDef } from './types.ts';
16
17
  import { OrderResolver } from './order-resolver.ts';
@@ -157,6 +158,30 @@ export interface CreateOpts {
157
158
  parentWf: string;
158
159
  parentPath: string;
159
160
  };
161
+ /**
162
+ * The ONE routing modifier this instance carries for its whole life. Must be
163
+ * a member of the def's declared `modifiers` set — `createInstance` throws
164
+ * {@link ModifierRefusalError} otherwise, rather than starting a run that
165
+ * would compose capabilities no crew was ever bound to.
166
+ *
167
+ * Absent = an unmodified run: every step is offered on bare capabilities.
168
+ * Never mutated after creation; an escalated re-offer carries its own target
169
+ * modifier per-offer without rewriting this.
170
+ */
171
+ modifier?: string;
172
+ }
173
+ /**
174
+ * Thrown by `createInstance` when the requested modifier is not in the def's
175
+ * declared `modifiers` set (including the case of a def that declares none).
176
+ * Its own class so the hub can map it to a 400 instead of an opaque 500 —
177
+ * this is a caller mistake, not an engine fault.
178
+ */
179
+ export declare class ModifierRefusalError extends Error {
180
+ readonly defName: string;
181
+ readonly modifier: string;
182
+ /** The def's declared modifier set — empty when the def declares none. */
183
+ readonly declared: string[];
184
+ constructor(defName: string, modifier: string, declared: string[]);
160
185
  }
161
186
  /**
162
187
  * Map a definition name to its `WorkflowDef`, or throw if there is none.
@@ -503,7 +528,23 @@ export declare class Engine {
503
528
  tick(workflow: string, opts?: {
504
529
  now?: number;
505
530
  deep?: boolean;
531
+ /**
532
+ * The claiming crew's capabilities. OMITTING this is not the same as
533
+ * passing `[]`: omitted means "no filter presented" (a local operator or
534
+ * test driver — everything matches, as before capabilities existed),
535
+ * while `[]` means a crew that serves nothing and therefore matches only
536
+ * capability-silent steps. See `claimMatches`.
537
+ */
506
538
  capabilities?: string[];
539
+ /**
540
+ * Per-offered-capability claim mode, keyed by the COMPOSED capability
541
+ * (`wise:deep`), supplied by the caller that can see crew bindings — the
542
+ * hub. Any capability absent from the map is matched by name part
543
+ * (`DEFAULT_MATCH_MODE`), which is what a caller with no binding
544
+ * knowledge should get: the permissive tier. The pure engine never
545
+ * decides a mode, it only enforces the one it is handed.
546
+ */
547
+ matchModes?: Record<string, MatchMode>;
507
548
  }): TickResult;
508
549
  /**
509
550
  * The recursive tick worker. Runs this instance's own maintain → reap →
@@ -576,11 +617,23 @@ export declare class Engine {
576
617
  private callsDescendTargets;
577
618
  /**
578
619
  * Per-step cadence + daily budget + parallel cap over the eligible firings.
579
- * A2: `capabilities` is the tick caller's optional claim filter — when non-empty, a
580
- * step whose own `capabilities` are also non-empty is only schedulable when the two
581
- * intersect; a disjoint step's firings are deferred as `'capability-mismatch'`.
620
+ *
621
+ * A2: `capabilities` is the tick caller's claim filter, matched against the
622
+ * step's OFFERED capabilities — the authored list composed with the modifier
623
+ * this firing will actually be offered under (`wise` + `deep` → `wise:deep`),
624
+ * which is the same list the order will carry. `claimMatches` owns the rule;
625
+ * see it for the four cases (no filter presented, capability-silent step,
626
+ * empty caller list, both non-empty) and for what `matchModes` changes.
627
+ * A firing this caller may not claim is deferred as `'capability-mismatch'`.
582
628
  * Filtering here (before cadence/budget) means a mismatched firing never
583
629
  * consumes the caller's slots and never perturbs cadence math.
630
+ *
631
+ * The filter is per FIRING, not per step, because §7 escalation is per firing:
632
+ * on a map step one element may have escalated to `build:deep` while its
633
+ * siblings are still offered at `build:standard`, and a crew bound to only one
634
+ * of those must be judged against the compound its own firing carries. With no
635
+ * escalation authored every firing of a step composes identically, so this
636
+ * behaves exactly as a per-step filter would.
584
637
  */
585
638
  private applySchedule;
586
639
  /** Return the effective reap TTL for a step — per-step override or engine default. */
@@ -861,7 +914,63 @@ export declare class Engine {
861
914
  * make `status(parent)` throw (same stance as the §28 drift flag).
862
915
  */
863
916
  private childStatusSummary;
917
+ /**
918
+ * The two per-instance facts a tick needs, from ONE run-record read: the def
919
+ * this instance is pinned to, and the routing modifier it carries.
920
+ *
921
+ * Offer-time composition needs the modifier inside the claim path, where the
922
+ * run record was not previously in scope. Reading it here — in the same
923
+ * `getWorkflow` the def resolution already performs, once per tick frame —
924
+ * keeps that cost at zero extra reads rather than one per claim.
925
+ */
926
+ private instanceFor;
864
927
  private defFor;
928
+ /**
929
+ * §7: the modifier ONE offer of ONE firing composes with — the run's, or the
930
+ * step's escalation target when the escalation rule has tripped.
931
+ *
932
+ * Derived, never stored. Every offer re-evaluates it from the artifact
933
+ * counters, which is what makes the transition atomic (there is no separate
934
+ * write that could half-apply), idempotent (recomputing it changes nothing),
935
+ * and self-reversing (a human `retry` zeroes `judgmentRejects`, and the very
936
+ * next offer composes with the run's modifier again).
937
+ *
938
+ * The trigger is per OUTPUT PATH: the firing escalates when any path it owes
939
+ * has taken `escalation.after` judgment rejections. For a plain step that is
940
+ * its single produce; for a map step each element firing escalates on its own
941
+ * element's count, so one bad element does not promote the whole step.
942
+ *
943
+ * Three cases return the run's modifier untouched:
944
+ * - the step authors no `escalation:` block — rejections run the normal
945
+ * retry path at the same compound until the stall brake;
946
+ * - no owed path has reached the threshold yet;
947
+ * - the run's modifier ALREADY equals the escalation target — there is
948
+ * nothing to promote, so no `escalated` flag and no history record. A
949
+ * `deep` run whose builder escalates to `deep` is a no-op, not an event.
950
+ *
951
+ * `escalation` on the result is set ONLY in the case that actually changed
952
+ * the routing; `claim` writes the history record from it.
953
+ */
954
+ private routingFor;
955
+ /**
956
+ * Write the ONE artifact-history record for an escalation promotion.
957
+ *
958
+ * `version: 0` on purpose. The promotion belongs to the artifact across a
959
+ * whole rejection episode, not to any single produced version — the episode
960
+ * spans every attempt from the crossing rejection to the human `retry` that
961
+ * ends it, and those attempts each produce their own version. Anchoring the
962
+ * record to a version would either mislabel it or (since the row id mixes in
963
+ * the version) write one row per version, breaking the once-per-episode
964
+ * guarantee. `getArtifactHistory` collects version-0 events in its
965
+ * artifact-level `events` bucket, which is exactly where this belongs; the
966
+ * version the promotion took effect at is in `metadata.atVersion`.
967
+ *
968
+ * The dedupe key is `(step, firing key, episode)`. Step and key are in it
969
+ * because two different steps can owe the same path in different firings; the
970
+ * episode ordinal is what makes a SECOND promotion, after a human `retry` and
971
+ * three fresh rejections, a distinct row rather than a swallowed duplicate.
972
+ */
973
+ private recordEscalation;
865
974
  private step;
866
975
  /**
867
976
  * The JSON Schema (if any) declared for the artifact `art` greened by `green()`