owenloop 0.5.10 → 0.5.11

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,13 @@ 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.5.11](https://github.com/typicalday/owenloop/compare/v0.5.10...v0.5.11) (2026-08-21)
8
+
9
+
10
+ ### Features
11
+
12
+ * **engine:** bind interface calls at instance start ([#263](https://github.com/typicalday/owenloop/issues/263)) ([84dde86](https://github.com/typicalday/owenloop/commit/84dde86be15d0d82a4a8a98137eb257f8a1868e7))
13
+
7
14
  ## [0.5.10](https://github.com/typicalday/owenloop/compare/v0.5.9...v0.5.10) (2026-08-21)
8
15
 
9
16
 
package/dist/src/cli.js CHANGED
@@ -43,7 +43,7 @@ import { parse as parseYaml } from 'yaml';
43
43
  import { Engine } from "./engine.js";
44
44
  import { buildGraph, buildTrace, graphToDot, graphToMermaid, hasDefiniteCheckDefect, modelCheck } from "./model.js";
45
45
  import { openStore, readRuntimeSnapshotBundlePins } from "./store.js";
46
- import { buildDef, DefError, finalizeDefs, lintDef, loadDefFile, loadDefs, loadDefsRaw, loadDefsUnfinalized, expandDefsRaw, reportCallsCycles, resolveCallsTarget, scanDefsRaw, validateCallsEdges, validateDef, } from "./defs.js";
46
+ import { buildDef, DefError, digestScopedCallsTargetKey, finalizeDefs, lintDef, loadDefFile, loadDefs, loadDefsRaw, loadDefsUnfinalized, expandDefsRaw, reportCallsCycles, resolveCallsTarget, scanDefsRaw, validateCallsEdges, validateDef, } from "./defs.js";
47
47
  import { implementsIssues } from "./implements.js";
48
48
  import { createDefInstructionSource } from "./order-resolver.js";
49
49
  import { CliError, dbPathRefusingSymlink, detId, mkdirRefusingSymlink, nowMs, parseDurationMs, randId } from "./util.js";
@@ -540,8 +540,10 @@ function openCtx(io, args, tolerantCasInspection = false) {
540
540
  // `finalizeDefs` validated against at load time, so load-time and run-time
541
541
  // agree). With `from` absent — every other resolver caller — this is the plain
542
542
  // flat-map lookup it has always been.
543
- const engine = new Engine(store, (name, from) => {
544
- const d = from === undefined ? defs.get(name) : resolveCallsTarget(defs, name, from);
543
+ const engine = new Engine(store, (name, from, bundleDigest) => {
544
+ const d = bundleDigest !== undefined
545
+ ? defs.get(digestScopedCallsTargetKey(bundleDigest, name)) ?? defs.get(name)
546
+ : from === undefined ? defs.get(name) : resolveCallsTarget(defs, name, from);
545
547
  if (!d)
546
548
  throw new CliError(`unknown workflow definition '${name}' (looked in ${defsDir})`);
547
549
  return d;
@@ -34,6 +34,15 @@ import type { StepDef, WorkflowDef } from './types.ts';
34
34
  export declare const SUPPORTED_ENGINE_VERSION = 1;
35
35
  export declare class DefError extends Error {
36
36
  }
37
+ /** Named, actionable refusal for a malformed authored interface call. */
38
+ export declare class InterfaceCallDefinitionError extends DefError {
39
+ readonly name = "InterfaceCallDefinitionError";
40
+ readonly step: string;
41
+ readonly interfaceName?: string;
42
+ readonly interfaceVersion?: string;
43
+ readonly detail: string;
44
+ constructor(step: string, claim: Record<string, unknown> | undefined, detail: string);
45
+ }
37
46
  /**
38
47
  * Instance-to-definition pinning (§28): a stable content hash of a compiled
39
48
  * WorkflowDef, used to detect when the live definition has drifted from an
package/dist/src/defs.js CHANGED
@@ -29,6 +29,7 @@ import { assertValidSchema } from "./schema.js";
29
29
  // The separator lives with composition/matching (capabilities.ts); the parser
30
30
  // only enforces that an AUTHORED name never contains it.
31
31
  import { MODIFIER_SEPARATOR } from "./capabilities.js";
32
+ import { isCallStep } from "./types.js";
32
33
  /** Hand-maintained key allowlist for RawInput — kept next to the interface so
33
34
  * the two can't silently drift (§27 unknown-key rejection). */
34
35
  const RAW_INPUT_KEYS = ['name', 'producer', 'seedOwed', 'schema'];
@@ -44,12 +45,12 @@ const RAW_STEP_KEYS = [
44
45
  'name', 'consumes', 'produces', 'generates', 'invalidates', 'cadence',
45
46
  'maxRunsPerDay', 'parallel', 'maxAttempts', 'maxSchemaFailures', 'model',
46
47
  'workdir', 'workdirFrom', 'terminal', 'effect', 'on', 'idleAfter', 'body', 'bodyFile',
47
- 'calls', 'reapTtl', 'capabilities', 'maxLease', 'x', 'executor', 'command', 'spec',
48
+ 'calls', 'callsInterface', 'reapTtl', 'capabilities', 'maxLease', 'x', 'executor', 'command', 'spec',
48
49
  'escalation', 'onCancel',
49
50
  ];
50
51
  /** Keys valid on a calls: step entry — a DIFFERENT (smaller) shape than RawStep;
51
52
  * the `calls:` key is what routes an entry here instead of RAW_STEP_KEYS. */
52
- const RAW_CALLS_KEYS = ['name', 'calls', 'inputs', 'produces'];
53
+ const RAW_CALLS_KEYS = ['name', 'calls', 'callsInterface', 'inputs', 'produces'];
53
54
  /** Keys valid on an include: directive entry — the `include:` key is the
54
55
  * discriminator that routes an entry here instead of RAW_STEP_KEYS/RAW_CALLS_KEYS. */
55
56
  const RAW_INCLUDE_KEYS = ['include', 'as', 'inputs'];
@@ -478,6 +479,45 @@ function parseProduces(v, ctx, baseDir) {
478
479
  }
479
480
  export class DefError extends Error {
480
481
  }
482
+ /** Named, actionable refusal for a malformed authored interface call. */
483
+ export class InterfaceCallDefinitionError extends DefError {
484
+ name = 'InterfaceCallDefinitionError';
485
+ step;
486
+ interfaceName;
487
+ interfaceVersion;
488
+ detail;
489
+ constructor(step, claim, detail) {
490
+ const interfaceName = typeof claim?.name === 'string' && claim.name.trim() !== '' ? claim.name : undefined;
491
+ const interfaceVersion = typeof claim?.version === 'string' && claim.version.trim() !== '' ? claim.version : undefined;
492
+ const coordinate = interfaceName === undefined
493
+ ? ''
494
+ : ` for interface '${interfaceName}${interfaceVersion === undefined ? '' : `@${interfaceVersion}`}'`;
495
+ super(`definition loading refused for interface-call step '${step}'${coordinate}: ${detail}`);
496
+ this.step = step;
497
+ this.interfaceName = interfaceName;
498
+ this.interfaceVersion = interfaceVersion;
499
+ this.detail = detail;
500
+ }
501
+ }
502
+ function parseCallsInterface(value, step) {
503
+ const claim = typeof value === 'object' && value !== null && !Array.isArray(value)
504
+ ? value
505
+ : undefined;
506
+ if (claim === undefined) {
507
+ throw new InterfaceCallDefinitionError(step, undefined, "callsInterface must be a map with exactly 'name' and 'version'");
508
+ }
509
+ const unknown = Object.keys(claim).filter((key) => key !== 'name' && key !== 'version');
510
+ if (unknown.length > 0) {
511
+ throw new InterfaceCallDefinitionError(step, claim, `callsInterface has unknown field${unknown.length === 1 ? '' : 's'} ${unknown.map((key) => `'${key}'`).join(', ')}`);
512
+ }
513
+ if (typeof claim.name !== 'string' || claim.name.trim() === '') {
514
+ throw new InterfaceCallDefinitionError(step, claim, 'callsInterface.name must be a non-empty string');
515
+ }
516
+ if (typeof claim.version !== 'string' || claim.version.trim() === '') {
517
+ throw new InterfaceCallDefinitionError(step, claim, 'callsInterface.version must be a non-empty string');
518
+ }
519
+ return { name: claim.name, version: claim.version };
520
+ }
481
521
  // ---- Mode 1 include-directive helpers (M1-GRAMMAR) ---------------------------
482
522
  /** Duck-check: does this raw step-list entry look like an include directive? */
483
523
  function isIncludeDirective(v) {
@@ -485,7 +525,7 @@ function isIncludeDirective(v) {
485
525
  }
486
526
  /** Duck-check: does this raw step-list entry look like a calls: directive (M2-GRAMMAR)? */
487
527
  function isCallsDirective(v) {
488
- return typeof v === 'object' && v !== null && 'calls' in v && !('include' in v);
528
+ return typeof v === 'object' && v !== null && ('calls' in v || 'callsInterface' in v) && !('include' in v);
489
529
  }
490
530
  /** Parse and validate a raw include directive (M1-GRAMMAR pre-checks). */
491
531
  function parseIncludeDirective(raw, i, parentName) {
@@ -1004,12 +1044,24 @@ function synthesizeJudgeSteps(producerStepName, pat, producerConsumeStems, produ
1004
1044
  });
1005
1045
  }
1006
1046
  function buildStep(rl, i, baseDir) {
1007
- // M2-GRAMMAR: if this entry carries a 'calls' key, parse it as a calls: step (Mode 2).
1008
- if (typeof rl.calls !== 'undefined') {
1047
+ // M2-GRAMMAR: either discriminator routes through the same restricted
1048
+ // machine-call shape. A definition may never author both.
1049
+ if (typeof rl.calls !== 'undefined' || typeof rl.callsInterface !== 'undefined') {
1009
1050
  const rawCalls = rl;
1010
1051
  assertNoUnknownKeys(rawCalls, RAW_CALLS_KEYS, `steps[${i}] (calls: step)`);
1011
1052
  const name = asString(rawCalls.name, `steps[${i}].name`);
1012
- const callsTarget = asString(rawCalls.calls, `step '${name}'.calls`);
1053
+ const hasCalls = rawCalls.calls !== undefined;
1054
+ const hasInterface = rawCalls.callsInterface !== undefined;
1055
+ const claimRecord = typeof rawCalls.callsInterface === 'object' && rawCalls.callsInterface !== null
1056
+ && !Array.isArray(rawCalls.callsInterface)
1057
+ ? rawCalls.callsInterface
1058
+ : undefined;
1059
+ if (hasCalls && hasInterface) {
1060
+ throw new InterfaceCallDefinitionError(name, claimRecord, 'calls and callsInterface are mutually exclusive; author exactly one call discriminator');
1061
+ }
1062
+ const callsTarget = hasCalls ? asString(rawCalls.calls, `step '${name}'.calls`) : undefined;
1063
+ const callsInterface = hasInterface ? parseCallsInterface(rawCalls.callsInterface, name) : undefined;
1064
+ const callLabel = callsInterface === undefined ? 'calls:' : 'callsInterface';
1013
1065
  // parse inputs: optional mapping of child input name -> parent artifact name
1014
1066
  const callsInputs = {};
1015
1067
  if (rawCalls.inputs !== undefined) {
@@ -1026,15 +1078,16 @@ function buildStep(rl, i, baseDir) {
1026
1078
  const { patterns: producesPatterns, groups: callsGroups } = parseProduces(rawCalls.produces, `step '${name}'.produces`, baseDir);
1027
1079
  for (const p of producesPatterns) {
1028
1080
  if (p.judges && p.judges.length > 0) {
1029
- throw new DefError(`step '${name}': judges: is not supported on a calls: step's produces (produce '${p.stem}')`);
1081
+ throw new DefError(`step '${name}': judges: is not supported on a ${callLabel} step's produces (produce '${p.stem}')`);
1030
1082
  }
1031
1083
  }
1032
1084
  if (callsGroups.length > 0) {
1033
- throw new DefError(`step '${name}': group: is not supported on a calls: step's produces (group '${callsGroups[0].group}')`);
1085
+ throw new DefError(`step '${name}': group: is not supported on a ${callLabel} step's produces (group '${callsGroups[0].group}')`);
1034
1086
  }
1035
1087
  const step = {
1036
1088
  name,
1037
- calls: callsTarget,
1089
+ ...(callsTarget === undefined ? {} : { calls: callsTarget }),
1090
+ ...(callsInterface === undefined ? {} : { callsInterface }),
1038
1091
  callsInputs,
1039
1092
  consumes: [], // calls: steps have no consumes in StepDef (eligibility is engine-managed)
1040
1093
  produces: producesPatterns,
@@ -1478,24 +1531,28 @@ export function validateDef(def) {
1478
1531
  // because validateDef is a pure per-def function with no resolver. Those checks live in loadDefs
1479
1532
  // Phase 2, analogous to how expandIncludes validates include input-key mappings.
1480
1533
  for (const l of def.steps) {
1481
- if (!l.calls)
1534
+ if (!isCallStep(l))
1482
1535
  continue;
1536
+ if (l.calls !== undefined && l.callsInterface !== undefined) {
1537
+ errors.push(`call step '${l.name}' declares both calls and callsInterface; the discriminators are mutually exclusive`);
1538
+ }
1539
+ const callLabel = l.callsInterface === undefined ? 'calls:' : 'callsInterface';
1483
1540
  // (a) calls: step must produce exactly one output (one child, one outcome path — v1)
1484
1541
  if (l.produces.length !== 1) {
1485
- errors.push(`calls: step '${l.name}' must produce exactly one output (got ${l.produces.length})`);
1542
+ errors.push(`${callLabel} step '${l.name}' must produce exactly one output (got ${l.produces.length})`);
1486
1543
  }
1487
1544
  // A calls: outcome is published by the composition machinery rather than
1488
1545
  // accepted through green(), so it has no transactional bind write path.
1489
1546
  // Refuse it at definition load instead of allowing a silently stale route.
1490
1547
  for (const produce of l.produces) {
1491
1548
  if (produce.bind !== undefined) {
1492
- errors.push(`calls: step '${l.name}' produce '${produce.raw}' declares bind, which is not supported on calls: outcomes`);
1549
+ errors.push(`${callLabel} step '${l.name}' produce '${produce.raw}' declares bind, which is not supported on ${callLabel} outcomes`);
1493
1550
  }
1494
1551
  }
1495
1552
  // (b) callsInputs VALUES must be real parent artifacts (inputs or step-produced stems)
1496
1553
  for (const [, parentArtifact] of Object.entries(l.callsInputs ?? {})) {
1497
1554
  if (!producerOf.has(parentArtifact)) {
1498
- errors.push(`calls: step '${l.name}' maps to parent artifact '${parentArtifact}' which is not produced by any step or input`);
1555
+ errors.push(`${callLabel} step '${l.name}' maps to parent artifact '${parentArtifact}' which is not produced by any step or input`);
1499
1556
  }
1500
1557
  }
1501
1558
  }
@@ -14,7 +14,7 @@ import type { SchemaIssue } from './schema.ts';
14
14
  import type { CapabilityMappings, CapabilityRewrites, CrewStamps } from './capabilities.ts';
15
15
  import type { MatchMode } from './capabilities.ts';
16
16
  import type { Store } from './store.ts';
17
- import type { Author, Fingerprint, Order, WorkflowDef } from './types.ts';
17
+ import type { Author, Fingerprint, InterfaceCallBinding, Order, WorkflowDef, WorkflowInterfaceClaim } from './types.ts';
18
18
  import { OrderResolver } from './order-resolver.ts';
19
19
  import type { OrderInstructionSource, ResolvedInstructions } from './order-resolver.ts';
20
20
  export type { Order } from './types.ts';
@@ -60,6 +60,32 @@ export declare class CallsPinError extends Error {
60
60
  readonly detail: string;
61
61
  constructor(target: string, detail: string);
62
62
  }
63
+ /**
64
+ * A caller-supplied start binding is missing, malformed, unresolved, or
65
+ * incompatible. This is a named 400-class refusal: no workflow row exists when
66
+ * it is thrown from the public start path.
67
+ */
68
+ export declare class InterfaceBindingRefusalError extends Error {
69
+ readonly name = "InterfaceBindingRefusalError";
70
+ readonly workflow: string;
71
+ readonly step: string;
72
+ readonly interfaceName?: string;
73
+ readonly interfaceVersion?: string;
74
+ readonly detail: string;
75
+ constructor(workflow: string, step: string, claim: Partial<WorkflowInterfaceClaim> | undefined, detail: string);
76
+ }
77
+ /**
78
+ * A persisted interface binding no longer agrees with the optimistically
79
+ * resolved child at spawn time. The provision transaction rolls back and the
80
+ * parent call artifact receives one visible structural refusal.
81
+ */
82
+ export declare class InterfaceCallPinError extends Error {
83
+ readonly name = "InterfaceCallPinError";
84
+ readonly interface: WorkflowInterfaceClaim;
85
+ readonly target: string;
86
+ readonly detail: string;
87
+ constructor(claim: WorkflowInterfaceClaim, target: string, detail: string);
88
+ }
63
89
  /**
64
90
  * §tick-deferred: an eligible firing the tick did NOT promote to an order, tagged
65
91
  * with why. `'in-flight'` — the step's task is already claimed by an open run;
@@ -172,6 +198,12 @@ export interface CreateOpts {
172
198
  * rewriting this stored value.
173
199
  */
174
200
  modifier?: string;
201
+ /**
202
+ * Hub-selected interface implementations. Every entry is validated and the
203
+ * complete normalized set is pinned immutably before the root row is written,
204
+ * then inherited by calls children.
205
+ */
206
+ interfaceBindings?: InterfaceCallBinding[];
175
207
  }
176
208
  /**
177
209
  * Thrown by `createInstance` when the requested modifier is not in the def's
@@ -196,9 +228,14 @@ export declare class ModifierRefusalError extends Error {
196
228
  * unrelated `build` from bundle B). Because the parameter is optional, every
197
229
  * existing single-argument resolver — including a host's hand-written one —
198
230
  * keeps today's exact behavior with no change: a resolver that ignores `from`
199
- * simply performs the flat lookup it always did.
231
+ * simply performs the flat lookup it always did. Interface bindings add the
232
+ * optional third `bundleDigest`: store-backed resolvers use it to prefer the
233
+ * exact digest-scoped alias, while the engine independently verifies the
234
+ * returned definition's digest before accepting or spawning it.
200
235
  */
201
- export type DefResolver = (defName: string, from?: WorkflowDef) => WorkflowDef;
236
+ export type DefResolver = (defName: string, from?: WorkflowDef,
237
+ /** Exact CAS bundle digest requested by a persisted interface binding. */
238
+ bundleDigest?: string) => WorkflowDef;
202
239
  /**
203
240
  * A push notification of a committed engine change, delivered to observers
204
241
  * registered via {@link Engine.subscribe}. Lets an in-process host react the
@@ -311,6 +348,10 @@ export declare class Engine {
311
348
  * its siblings. See {@link EngineEvent}.
312
349
  */
313
350
  subscribe(listener: EngineListener): () => void;
351
+ /** Validate, resolve, and JSON-normalize every supplied start binding. */
352
+ private normalizeInterfaceBindings;
353
+ /** Pure child-insert guard over an already-normalized inherited binding set. */
354
+ private assertDirectInterfaceBindings;
314
355
  /** Start a workflow instance: persist it, seed its declared inputs, settle. */
315
356
  createInstance(defName: string, opts?: CreateOpts): string;
316
357
  /**
@@ -470,6 +511,8 @@ export declare class Engine {
470
511
  * matter what moved concurrently.
471
512
  */
472
513
  private recordCallsDigestReject;
514
+ /** Persist one interface-binding/pin refusal with the unchanged-gate guard. */
515
+ private recordInterfaceCallPinReject;
473
516
  /**
474
517
  * M2B: Maintain all `calls:` steps for a parent workflow.
475
518
  * Called at the top of tick (outside any tx) and as cascade-up prompt.