owenloop 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,17 @@ All notable changes to this project are documented here. The format is based on
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
5
5
  adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.2.1](https://github.com/typicalday/owenloop/compare/v0.2.0...v0.2.1) (2026-07-04)
8
+
9
+
10
+ ### Bug Fixes
11
+
12
+ * auto-skip submitted group siblings to prevent permanent wedge ([#15](https://github.com/typicalday/owenloop/issues/15)) ([484aea2](https://github.com/typicalday/owenloop/commit/484aea20d682196574b5c8c7da35bfd3e10619d3))
13
+ * catch child schema refusals as debts and version-pin the calls: mirror ([#16](https://github.com/typicalday/owenloop/issues/16)) ([500cce7](https://github.com/typicalday/owenloop/commit/500cce7152023391c19393ee5dcb18d802a6b2e8))
14
+ * close three commit-side verb guard gaps (F3, F5, F7) ([#11](https://github.com/typicalday/owenloop/issues/11)) ([fbcc777](https://github.com/typicalday/owenloop/commit/fbcc77700fefcf66f287e5e903ad7c03e9b59b64))
15
+ * refuse emit after the collection seal has greened (§11.1, F6) ([#17](https://github.com/typicalday/owenloop/issues/17)) ([cd963cf](https://github.com/typicalday/owenloop/commit/cd963cf9296504dc0278f9fa68d097a60e318c0f))
16
+ * ship src/ in the npm files allowlist ([#13](https://github.com/typicalday/owenloop/issues/13)) ([20ffcea](https://github.com/typicalday/owenloop/commit/20ffcea9132610203ef9da3cfa147990ad157ca9))
17
+
7
18
  ## [0.2.0](https://github.com/typicalday/owenloop/compare/v0.1.1...v0.2.0) (2026-07-04)
8
19
 
9
20
 
package/README.md CHANGED
@@ -158,6 +158,10 @@ Two things make this more than running steps in dependency order:
158
158
  *width* — a producer can emit any number of elements — but the wiring graph
159
159
  itself (which steps exist, what each consumes and produces) is fixed when
160
160
  the definition loads, not mutable while an instance runs.
161
+ - **Not a command runner.** `worker:`/`command:` label which kind of
162
+ executor an order is for and carry a command string through untouched —
163
+ the engine never shells out, executes, or interprets it. Actually running
164
+ anything is always the dispatcher's job, on the other side of `tick`.
161
165
 
162
166
  ---
163
167
 
@@ -250,6 +254,20 @@ opt-in `strongest` tier is for, reserved for the rare step where nothing less
250
254
  will do. See
251
255
  [`docs/authoring.md`](docs/authoring.md#model--quality-tiers-not-vendor-ids).
252
256
 
257
+ ### Worker dispatch
258
+
259
+ `worker: agent | command | …` declares which kind of executor a step's order
260
+ is for — the default (`agent`, silent when omitted) is unaffected; every
261
+ def written before this feature stays byte for byte the same. Opt a step
262
+ into `worker: command` and give it a `command:` string to switch it to a
263
+ deterministic executor instead of an LLM — the engine never runs it, only
264
+ carries it through on the order for your dispatcher to branch on. An
265
+ optional `spec:` map carries further opaque config (a timeout, a working
266
+ directory), and a judge entry accepts the same fields, so a quality gate can
267
+ be a script's exit code instead of a verdict. See
268
+ [`docs/authoring.md`](docs/authoring.md#worker--declaring-the-executor) and
269
+ [`command-worker.yaml`](examples/workflows/command-worker.yaml).
270
+
253
271
  ### Event subscription — for embedding
254
272
 
255
273
  Driving the engine in-process doesn't require polling: `engine.subscribe(...)`
package/dist/defs.js CHANGED
@@ -35,13 +35,13 @@ const RAW_PRODUCE_KEYS = ['name', 'schema', 'judges', 'maxAttempts', 'maxSchemaF
35
35
  * fields, so it gets its own allowlist rather than folding into
36
36
  * RAW_PRODUCE_KEYS (§27 unknown-key rejection). */
37
37
  const RAW_GROUP_KEYS = ['group', 'mode', 'of'];
38
- const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay'];
38
+ const RAW_JUDGE_KEYS = ['name', 'body', 'bodyFile', 'model', 'inputs', 'cadence', 'maxRunsPerDay', 'worker', 'command', 'spec'];
39
39
  /** Keys valid on a normal (non-calls:, non-include:) step entry. */
40
40
  const RAW_STEP_KEYS = [
41
41
  'name', 'consumes', 'produces', 'generates', 'invalidates', 'cadence',
42
42
  'maxRunsPerDay', 'parallel', 'maxAttempts', 'maxSchemaFailures', 'model',
43
43
  'workdir', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
44
- 'calls', 'reapTtl', 'x',
44
+ 'calls', 'reapTtl', 'x', 'worker', 'command', 'spec',
45
45
  ];
46
46
  /** Keys valid on a calls: step entry — a DIFFERENT (smaller) shape than RawStep;
47
47
  * the `calls:` key is what routes an entry here instead of RAW_STEP_KEYS. */
@@ -49,7 +49,7 @@ const RAW_CALLS_KEYS = ['name', 'calls', 'inputs', 'produces'];
49
49
  /** Keys valid on an include: directive entry — the `include:` key is the
50
50
  * discriminator that routes an entry here instead of RAW_STEP_KEYS/RAW_CALLS_KEYS. */
51
51
  const RAW_INCLUDE_KEYS = ['include', 'as', 'inputs'];
52
- const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x'];
52
+ const RAW_DEF_KEYS = ['name', 'title', 'description', 'inputs', 'steps', 'outputs', 'invariants', 'engine', 'x', 'workers'];
53
53
  // ---- defaults ----------------------------------------------------------------
54
54
  const DEFAULTS = {
55
55
  cadence: '0s',
@@ -215,6 +215,12 @@ function parseJudges(v, ctx, baseDir) {
215
215
  if (raw.maxRunsPerDay !== undefined) {
216
216
  judge.maxRunsPerDay = asNumber(raw.maxRunsPerDay, DEFAULTS.maxRunsPerDay, `judge '${name}'.maxRunsPerDay`);
217
217
  }
218
+ if (raw.worker !== undefined)
219
+ judge.worker = asString(raw.worker, `judge '${name}'.worker`);
220
+ if (raw.command !== undefined)
221
+ judge.command = asString(raw.command, `judge '${name}'.command`);
222
+ if (raw.spec !== undefined)
223
+ judge.spec = asExtension(raw.spec, `judge '${name}'.spec`);
218
224
  return judge;
219
225
  });
220
226
  }
@@ -520,6 +526,8 @@ export function buildDef(raw, source, baseDir) {
520
526
  }
521
527
  if (r.x !== undefined)
522
528
  def.x = asExtension(r.x, `workflow '${name}'.x`);
529
+ if (r.workers !== undefined)
530
+ def.workers = asStringArray(r.workers, `workflow '${name}'.workers`);
523
531
  return def;
524
532
  }
525
533
  // ---- Mode 1 expand helpers (M1-EXPAND) ----------------------------------------
@@ -724,6 +732,12 @@ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems) {
724
732
  };
725
733
  if (j.model !== undefined)
726
734
  step.model = j.model;
735
+ if (j.worker !== undefined)
736
+ step.worker = j.worker;
737
+ if (j.command !== undefined)
738
+ step.command = j.command;
739
+ if (j.spec !== undefined)
740
+ step.spec = j.spec;
727
741
  return step;
728
742
  });
729
743
  }
@@ -823,6 +837,12 @@ function buildStep(rl, i, baseDir) {
823
837
  step.workdir = asString(rl.workdir, `step '${name}'.workdir`);
824
838
  if (rl.model !== undefined)
825
839
  step.model = asString(rl.model, `step '${name}'.model`);
840
+ if (rl.worker !== undefined)
841
+ step.worker = asString(rl.worker, `step '${name}'.worker`);
842
+ if (rl.command !== undefined)
843
+ step.command = asString(rl.command, `step '${name}'.command`);
844
+ if (rl.spec !== undefined)
845
+ step.spec = asExtension(rl.spec, `step '${name}'.spec`);
826
846
  if (rl.x !== undefined)
827
847
  step.x = asExtension(rl.x, `step '${name}'.x`);
828
848
  if (asBool(rl.terminal, false, `step '${name}'.terminal`))
@@ -1013,6 +1033,43 @@ export function validateDef(def) {
1013
1033
  }
1014
1034
  }
1015
1035
  }
1036
+ // W1-VALIDATE: worker:/command: shape rules (declarative executor dispatch).
1037
+ // Only two hard requirements; any other worker value is fully opaque.
1038
+ for (const l of def.steps) {
1039
+ const worker = l.worker ?? 'agent';
1040
+ // Deliberately `l.worker === 'agent'` (explicit opt-in), NOT
1041
+ // `(l.worker ?? 'agent') === 'agent'` — that stricter form would also
1042
+ // catch every default-agent step that already gets away with an empty
1043
+ // body today (e.g. calls:-adjacent or generator-only fixtures), breaking
1044
+ // existing defs that never write `worker:` at all. Scoping the check to
1045
+ // an EXPLICIT `worker: agent` keeps every pre-existing def byte-for-byte
1046
+ // unaffected while still catching "someone opted into the agent worker
1047
+ // type and forgot a body".
1048
+ if (l.worker === 'agent' && l.body.trim() === '') {
1049
+ errors.push(`step '${l.name}' has worker 'agent' but no body: (an agent step needs a prompt)`);
1050
+ }
1051
+ else if (worker === 'command') {
1052
+ if (l.command === undefined) {
1053
+ errors.push(`step '${l.name}' has worker 'command' but no command:`);
1054
+ }
1055
+ }
1056
+ // any other worker value: opaque, no body/command requirement
1057
+ }
1058
+ // W1-VALIDATE: workers: def-level allow-list typo guard. Applied AFTER the
1059
+ // per-step `worker` default (?? 'agent') — a def declaring `workers:
1060
+ // [command]` (deliberately excluding 'agent') still fails a step that omits
1061
+ // `worker:` entirely, since its effective worker is 'agent'. This is
1062
+ // intended (the list is exhaustive once declared), documented in
1063
+ // docs/authoring.md.
1064
+ if (def.workers && def.workers.length > 0) {
1065
+ const allowed = new Set(def.workers);
1066
+ for (const l of def.steps) {
1067
+ const worker = l.worker ?? 'agent';
1068
+ if (!allowed.has(worker)) {
1069
+ errors.push(`step '${l.name}' has worker '${worker}' but workflow '${def.name}'.workers does not list it`);
1070
+ }
1071
+ }
1072
+ }
1016
1073
  // on: token validation — belt-and-suspenders over buildStep's throw
1017
1074
  for (const l of def.steps) {
1018
1075
  if (!l.on)
package/dist/engine.d.ts CHANGED
@@ -13,6 +13,19 @@ import type { WorkflowStatus } from './model.ts';
13
13
  import type { SchemaIssue } from './schema.ts';
14
14
  import type { Store } from './store.ts';
15
15
  import type { Author, FiringTrigger, ReasonEntry, WorkflowDef } from './types.ts';
16
+ /**
17
+ * F2: a typed refusal for a produced-value/input-value schema mismatch, thrown
18
+ * by `createInstance` (seed provide) and `provideInput`. Distinct from a bare
19
+ * `Error` so callers that need to distinguish "this value doesn't fit the
20
+ * schema" from a genuine bug (e.g. `maintainCalls`'s STEP 3/STEP 5, which must
21
+ * turn a CHILD's schema refusal into a debt on the parent rather than crash
22
+ * the parent's tick) can catch narrowly instead of blanket-catching.
23
+ */
24
+ export declare class SchemaRefusalError extends Error {
25
+ readonly inputName: string;
26
+ readonly issues: SchemaIssue[];
27
+ constructor(inputName: string, issues: SchemaIssue[]);
28
+ }
16
29
  /** A self-contained unit of work emitted by a tick. */
17
30
  export interface Order {
18
31
  run: string;
@@ -24,6 +37,16 @@ export interface Order {
24
37
  outputs: string[];
25
38
  workdir?: string;
26
39
  model?: string;
40
+ /** Declares which kind of executor this order is for. Absent = 'agent'
41
+ * (today's behavior). Opaque to the engine; carried through verbatim from
42
+ * the step definition, same pass-through contract as `model`/`x`. */
43
+ worker?: string;
44
+ /** The command string for a `worker: command` order. Opaque to the engine
45
+ * — never parsed, never shelled out. */
46
+ command?: string;
47
+ /** Opaque config object for a non-agent/non-command worker type (or
48
+ * alongside `command`). Carried through untouched, contents never read. */
49
+ spec?: Record<string, unknown>;
27
50
  /** §27.3: the step's opaque `x:` extension map, carried through untouched
28
51
  * (same pass-through contract as `model`). The engine never reads it —
29
52
  * it exists for the external runner/tooling consuming this order. */
@@ -96,7 +119,7 @@ export interface CommitResult {
96
119
  }
97
120
  /** The outcome of an `emit` (collection accretion) — possibly schema-refused. */
98
121
  export interface EmitResult {
99
- outcome: 'emitted' | 'born-rejected' | 'schema-rejected';
122
+ outcome: 'emitted' | 'born-rejected' | 'schema-rejected' | 'sealed-rejected';
100
123
  /** the element paths created (empty unless `emitted`) */
101
124
  created: string[];
102
125
  reason?: string;
@@ -192,6 +215,36 @@ export declare class Engine {
192
215
  defHash: string;
193
216
  previousHash?: string;
194
217
  };
218
+ /**
219
+ * F4: the synthetic fingerprint key a `calls:` artifact uses to pin its
220
+ * fingerprint to the child outcome's version. A calls: step declares
221
+ * `consumes: []` (§ M2B), so its produce's fingerprint would otherwise never
222
+ * see the child outcome (which lives in another instance entirely) — this
223
+ * key is how that pin rides inside the same `Fingerprint` map alongside the
224
+ * gate stems, without colliding with any real parent artifact path (gate
225
+ * stems are bare names; this key is namespaced and reserved).
226
+ */
227
+ private static readonly CHILD_OUTCOME_PIN_KEY;
228
+ /**
229
+ * F4: the single place that computes "what child-outcome version is this
230
+ * calls: artifact currently resting on" — used both when machine-greening
231
+ * (STEP 6) and when stamping the pin at verdict time (reject propagation,
232
+ * human skip). Returns undefined if no child has ever been spawned (nothing
233
+ * to pin to).
234
+ */
235
+ private childOutcomePin;
236
+ /**
237
+ * F2: record a child input-schema refusal (from STEP 3 spawn or STEP 5
238
+ * re-provide) as a debt on the PARENT calls artifact — same shape as
239
+ * green()'s schema-reject branch (acceptance: 'rejected', schemaRejects+1,
240
+ * a 'validation' reasons entry naming the child input and the schema
241
+ * issues) — so the tick can proceed instead of throwing, and the parent
242
+ * calls artifact surfaces as a stallable debt (maxSchemaFailures/retry).
243
+ * Stamps the current gate fingerprint on the rejected artifact so the
244
+ * STEP-2 guard can tell "gate unmoved, don't re-attempt" from "gate moved,
245
+ * worth retrying" on the next tick.
246
+ */
247
+ private recordCallsSchemaReject;
195
248
  /**
196
249
  * M2B: Maintain all `calls:` steps for a parent workflow.
197
250
  * Called at the top of tick (outside any tx) and as cascade-up prompt.
@@ -287,6 +340,20 @@ export declare class Engine {
287
340
  outcome: 'rejected' | 'born-rejected';
288
341
  reason?: string;
289
342
  };
343
+ /**
344
+ * F4: forward a reject on a `calls:`-produced artifact to the CHILD's
345
+ * outcome artifact, then reopen the parent calls artifact to `owed` pinned
346
+ * (via `childOutcomePin`) to the just-rejected child outcome version, so
347
+ * STEP 6's mirror only fires again once the child has actually rebuilt past
348
+ * this verdict (§ F4 settled design).
349
+ *
350
+ * The forward is engine-internal: authority was already checked against the
351
+ * PARENT def by `assertAuthority` in `reject()` above, so the child's own
352
+ * `assertAuthority` is not consulted — the author recorded on the child's
353
+ * reasons entry is `parent:<by>` to make the indirection visible in its
354
+ * audit thread.
355
+ */
356
+ private rejectCallsArtifact;
290
357
  /** Retract a collection member (§11.3): drop it, terminally; abandon the index. */
291
358
  retract(workflow: string, path: string, by: Author, text: string): void;
292
359
  /** A producer skips its own owed output on a dead branch (§16.1 routing). */