@openwop/openwop-conformance 1.47.0 → 1.51.0

package/src/scenarios/dispatch-per-item-input.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Data-parallel dispatch — per-item child inputs. `node-packs.md` §"`core.dispatch`
+ * per-item input — data-parallel fan-out" (RFC 0126). Validates the additive, OPTIONAL
+ * `nextWorkerInputs` array on `NextWorkerDecision` (`orchestrator-decision.schema.json`)
+ * and the `capabilities.dispatch.perItemInput` fail-closed gate.
+ *
+ * `nextWorkerInputs[i]` is a per-child input object, index-aligned with `nextWorkerIds`,
+ * projected into the child dispatched for `nextWorkerIds[i]` — fanning ONE childWorkflowId
+ * over N runtime items with distinct inputs (the map-over-collection pattern). It rides the
+ * recorded `runOrchestrator.decided` event, so `:fork`/replay reproduces byte-identical
+ * children.
+ *
+ * Two layers:
+ *
+ *   A. Always-on, server-free schema probe — `NextWorkerDecision` accepts a well-formed
+ *      `nextWorkerInputs`, still accepts a decision that omits it (additive/back-compat),
+ *      rejects a non-object item, and — because `additionalProperties:false` — rejects the
+ *      field on a pre-RFC-0126 strict validator only when the property name differs (the
+ *      point of the fail-closed gate). Array-length equality with `nextWorkerIds` is NOT
+ *      JSON-Schema-expressible, so the schema ADMITS a length-mismatch; that MUST is a
+ *      HOST runtime check, driven in layer B.
+ *
+ *   B. Capability-gated behavioral legs — on a host advertising
+ *      `capabilities.dispatch.perItemInput: true` that exposes the dispatch test seam, a
+ *      length-mismatched decision fails with a validation_error and dispatches no child,
+ *      and each child receives its own `nextWorkerInputs[i]`. On a host NOT advertising the
+ *      capability, a non-empty `nextWorkerInputs` MUST fail closed (validation_error), never
+ *      silently drop-and-dispatch N identical children. No conformant host advertises
+ *      perItemInput yet — these legs soft-skip until a reference host wires it (the first
+ *      witness toward `Active → Accepted`).
+ *
+ * @see spec/v1/node-packs.md §"core.dispatch per-item input — data-parallel fan-out (RFC 0126)"
+ * @see spec/v1/capabilities.md §dispatch
+ * @see schemas/orchestrator-decision.schema.json
+ * @see RFCS/0126-data-parallel-dispatch-per-item-input.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const DECISION = join(SCHEMAS_DIR, 'orchestrator-decision.schema.json');
+
+describe('dispatch-per-item: NextWorkerDecision.nextWorkerInputs schema (always-on, server-free)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(JSON.parse(readFileSync(DECISION, 'utf8')));
+
+  it('accepts a next-worker decision carrying a well-formed, index-aligned nextWorkerInputs', () => {
+    const decision = {
+      kind: 'next-worker',
+      nextWorkerIds: ['pack.re-engage-contact', 'pack.re-engage-contact', 'pack.re-engage-contact'],
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }, { contactId: 'c-3' }],
+    };
+    expect(
+      validate(decision),
+      `orchestrator-decision.schema.json §NextWorkerDecision — a well-formed nextWorkerInputs MUST validate. Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('still accepts a next-worker decision that omits nextWorkerInputs (additive / back-compat)', () => {
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['pack.child'] }),
+      'a pre-RFC-0126 next-worker decision MUST stay valid — the field is OPTIONAL',
+    ).toBe(true);
+  });
+
+  it('rejects a non-object nextWorkerInputs item', () => {
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['a'], nextWorkerInputs: ['not-an-object'] }),
+      'each nextWorkerInputs entry MUST be a per-child input object',
+    ).toBe(false);
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['a'], nextWorkerInputs: 'nope' }),
+      'nextWorkerInputs MUST be an array',
+    ).toBe(false);
+  });
+
+  it('still rejects an unknown property (additionalProperties:false) — the fail-closed gate', () => {
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['a'], perItemInputs: [{ x: 1 }] }),
+      'NextWorkerDecision is additionalProperties:false — a mis-named field MUST be rejected, so old strict validators fail closed on unknown per-item shapes',
+    ).toBe(false);
+  });
+
+  it('ADMITS a length-mismatch — array-length equality is a runtime MUST, not schema-expressible', () => {
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['a', 'b'], nextWorkerInputs: [{ x: 1 }] }),
+      'the wire schema cannot express nextWorkerInputs.length == nextWorkerIds.length; the host enforces it at decision time (layer B)',
+    ).toBe(true);
+  });
+});
+
+describe('dispatch-per-item: per-item input behavior (capability-gated, RFC 0126)', () => {
+  it('a host advertising perItemInput projects nextWorkerInputs[i] into child i', async () => {
+    const dispatch = await readCapabilityFamily<{ perItemInput?: boolean }>('dispatch');
+    if (!behaviorGate('dispatch.perItemInput', dispatch?.perItemInput === true)) return;
+
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const body = res.json as { children?: Array<{ inputs?: Record<string, unknown> }> } | undefined;
+    expect(
+      body?.children?.length,
+      driver.describe('node-packs.md §core.dispatch per-item input', 'one child dispatched per nextWorkerIds entry'),
+    ).toBe(2);
+    expect(
+      body?.children?.map((c) => c.inputs?.contactId),
+      driver.describe('node-packs.md §core.dispatch per-item input', 'each child receives its own nextWorkerInputs[i] (per-item value wins over inputMapping)'),
+    ).toEqual(['c-1', 'c-2']);
+  });
+
+  it('a length-mismatched nextWorkerInputs fails with a validation_error and dispatches no child', async () => {
+    const dispatch = await readCapabilityFamily<{ perItemInput?: boolean }>('dispatch');
+    if (!behaviorGate('dispatch.perItemInput', dispatch?.perItemInput === true)) return;
+
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      nextWorkerInputs: [{ contactId: 'c-1' }],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    expect(
+      res.status >= 400 && res.status < 500,
+      driver.describe('node-packs.md §core.dispatch per-item input', 'nextWorkerInputs.length != nextWorkerIds.length MUST fail the dispatch node (4xx validation_error), dispatching no child'),
+    ).toBe(true);
+  });
+
+  it('nextWorkerInputs[i] OVERRIDES the inputMapping projection on key collision (G1 precedence)', async () => {
+    const dispatch = await readCapabilityFamily<{ perItemInput?: boolean }>('dispatch');
+    if (!behaviorGate('dispatch.perItemInput', dispatch?.perItemInput === true)) return;
+
+    // The seam applies `inputMapping` first (parent-variable projection, RFC 0022), then overlays
+    // nextWorkerInputs[i]. A key present in BOTH MUST resolve to the per-item value (most-specific wins).
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      inputMapping: { contactId: 'from-mapping', region: 'us' },
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const body = res.json as { children?: Array<{ inputs?: Record<string, unknown> }> } | undefined;
+    expect(
+      body?.children?.map((c) => c.inputs?.contactId),
+      driver.describe('node-packs.md §core.dispatch per-item input', 'on key collision the per-item value wins over inputMapping (G1)'),
+    ).toEqual(['c-1', 'c-2']);
+    expect(
+      body?.children?.every((c) => c.inputs?.region === 'us'),
+      driver.describe('node-packs.md §core.dispatch per-item input', 'non-colliding inputMapping keys still project (per-item merges OVER, does not replace)'),
+    ).toBe(true);
+  });
+
+  it('replay re-reads the recorded nextWorkerInputs verbatim — no recomputation (R5 replay-freeze)', async () => {
+    const dispatch = await readCapabilityFamily<{ perItemInput?: boolean }>('dispatch');
+    if (!behaviorGate('dispatch.perItemInput', dispatch?.perItemInput === true)) return;
+
+    // A :fork/replay MUST re-read the per-item inputs frozen in the recorded runOrchestrator.decided
+    // decision and reproduce byte-identical children (CP-2), never re-derive them at replay time.
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }],
+      replay: true,
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const body = res.json as { children?: Array<{ inputs?: Record<string, unknown> }>; replayed?: boolean } | undefined;
+    expect(
+      body?.children?.map((c) => c.inputs?.contactId),
+      driver.describe('node-packs.md §core.dispatch per-item input', 'replay/:fork reproduces the recorded per-item children verbatim (frozen at decision time)'),
+    ).toEqual(['c-1', 'c-2']);
+  });
+
+  it('a host NOT advertising perItemInput MUST fail closed on a non-empty nextWorkerInputs', async () => {
+    const dispatch = await readCapabilityFamily<{ supported?: boolean; perItemInput?: boolean }>('dispatch');
+    if (!dispatch?.supported) return; // no dispatch surface → out of scope
+    if (dispatch.perItemInput === true) return; // this leg targets non-supporting hosts
+
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    expect(
+      res.status >= 400 && res.status < 500,
+      driver.describe('node-packs.md §core.dispatch per-item input', 'a host not advertising perItemInput MUST fail closed (4xx) on a non-empty nextWorkerInputs — never silently drop it and dispatch N identical children'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/self-hosted-runner.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Self-hosted runner — remote-driven local execution (RFC 0122, `Active`).
+ *
+ * A host routes a run's per-step model/tool DISPATCH to a user-controlled runner
+ * that dials OUT to the host (SSE receive + POST result) and holds local
+ * credentials the host cannot reach. The host stays the sole orchestration/
+ * persistence/replay authority; the runner is a stateless dispatch executor.
+ *
+ * Three assertion tiers (mirroring RFC 0108/0121 shape/behavior split):
+ *   1. Schema shape (always-on, server-free) — the `selfHostedRunner` capability
+ *      block + the dispatch-frame / result-frame / registration schema shapes.
+ *   2. Advertisement-gated — the live `selfHostedRunner` block is well-formed
+ *      (`supported` boolean; `dispatchKinds` ⊂ {model,tool}). Gated on
+ *      `behaviorGate('openwop-self-hosted-runner', supported)`.
+ *   3. Seam-gated behavioral — drives the `POST /v1/host/sample/runner/*` seams
+ *      (`host-sample-test-seams.md` §19), soft-skipping on 404, to assert
+ *      subject-first match (no cross-subject routing), at-most-once dispatch
+ *      dedup, credential non-transit, and retriable `runner_unavailable` on
+ *      liveness loss.
+ *
+ * RFC 0122 is `Active` (not `Accepted`): no reference host advertises
+ * `selfHostedRunner.supported: true` yet, so tiers 2/3 soft-skip today; the
+ * shape tier is the always-on floor.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/self-hosted-runner.md
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/capabilities.md §"selfHostedRunner"
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0122-self-hosted-runner-remote-execution.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const GATE = 'openwop-self-hosted-runner';
+
+interface JsonSchema {
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  additionalProperties?: boolean;
+  type?: string;
+  enum?: string[];
+  items?: JsonSchema;
+}
+
+function readSchema(name: string): JsonSchema {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as JsonSchema;
+}
+
+/** Read the canonical error code from a response body (tolerant of shapes). */
+function errCode(json: unknown): string | undefined {
+  const j = json as { error?: unknown; code?: unknown };
+  if (typeof j?.code === 'string') return j.code;
+  if (typeof j?.error === 'string') return j.error;
+  const e = j?.error as { code?: unknown } | undefined;
+  if (e && typeof e.code === 'string') return e.code;
+  return undefined;
+}
+
+/** Read a boolean `retriable` flag from either `{retriable}` or `{error:{retriable}}`. */
+function retriable(json: unknown): boolean | undefined {
+  const j = json as { retriable?: unknown; error?: { retriable?: unknown } };
+  if (typeof j?.retriable === 'boolean') return j.retriable;
+  if (j?.error && typeof j.error.retriable === 'boolean') return j.error.retriable;
+  return undefined;
+}
+
+interface SelfHostedRunner {
+  supported?: boolean;
+  dispatchKinds?: string[];
+}
+
+const REGISTER = '/v1/host/sample/runner/register';
+const DISPATCH = '/v1/host/sample/runner/dispatch';
+
+describe('self-hosted-runner: schema shape (RFC 0122, server-free)', () => {
+  it('capabilities.schema.json declares selfHostedRunner {supported} with required supported', () => {
+    const caps = readSchema('capabilities.schema.json');
+    const shr = caps.properties?.selfHostedRunner;
+    expect(shr, 'capabilities.md §selfHostedRunner — the block MUST be declared').toBeDefined();
+    expect(
+      shr?.required,
+      'RFC 0122 — selfHostedRunner.supported is REQUIRED when the block is present',
+    ).toContain('supported');
+    expect(
+      shr?.properties?.supported?.type,
+      'selfHostedRunner.supported MUST be a boolean',
+    ).toBe('boolean');
+    expect(
+      shr?.additionalProperties,
+      'selfHostedRunner MUST be a closed object',
+    ).toBe(false);
+  });
+
+  it('the dispatch frame schema pins {runId, stepId, seq, kind, inputs} with an integer cursor', () => {
+    const s = readSchema('self-hosted-runner-dispatch-frame.schema.json');
+    for (const f of ['runId', 'stepId', 'seq', 'kind', 'inputs']) {
+      expect(s.required, `dispatch frame MUST require '${f}'`).toContain(f);
+    }
+    expect(s.additionalProperties, 'dispatch frame MUST be a closed object').toBe(false);
+    expect(
+      s.properties?.seq?.type,
+      'RFC 0122 §Channel — the dispatch cursor `seq` MUST be an integer (distinct from the event-log sequence)',
+    ).toBe('integer');
+    expect(s.properties?.kind?.enum, "dispatch kind MUST be one of {model, tool}").toEqual(
+      expect.arrayContaining(['model', 'tool']),
+    );
+  });
+
+  it('the result frame schema pins {runId, stepId, seq, output} and is closed', () => {
+    const s = readSchema('self-hosted-runner-result-frame.schema.json');
+    for (const f of ['runId', 'stepId', 'seq', 'output']) {
+      expect(s.required, `result frame MUST require '${f}'`).toContain(f);
+    }
+    // additionalProperties:false is the schema-level runner-credential-non-transit rail —
+    // a runner cannot smuggle a credential field onto a result frame.
+    expect(
+      s.additionalProperties,
+      'result frame MUST be a closed object (runner-credential-non-transit)',
+    ).toBe(false);
+  });
+
+  it('the registration schema pins {runnerId, subject, capabilities} and is closed', () => {
+    const s = readSchema('self-hosted-runner-registration.schema.json');
+    for (const f of ['runnerId', 'subject', 'capabilities']) {
+      expect(s.required, `registration MUST require '${f}'`).toContain(f);
+    }
+    expect(s.additionalProperties, 'registration MUST be a closed object').toBe(false);
+    expect(
+      s.properties?.capabilities?.additionalProperties,
+      'registration.capabilities MUST be a closed object',
+    ).toBe(false);
+  });
+});
+
+describe('self-hosted-runner: advertisement shape (gated)', () => {
+  it('an advertised selfHostedRunner block is well-formed', async () => {
+    const shr = await readCapabilityFamily<SelfHostedRunner>('selfHostedRunner');
+    if (!behaviorGate(GATE, shr?.supported === true)) return;
+
+    expect(
+      typeof shr?.supported,
+      driver.describe('capabilities.md §selfHostedRunner', 'supported MUST be a boolean'),
+    ).toBe('boolean');
+    if (shr?.dispatchKinds !== undefined) {
+      for (const k of shr.dispatchKinds) {
+        expect(
+          ['model', 'tool'],
+          driver.describe('capabilities.md §selfHostedRunner', `dispatchKinds entry '${k}' MUST be model|tool`),
+        ).toContain(k);
+      }
+    }
+  });
+});
+
+describe('self-hosted-runner: behavioral (seam-gated, soft-skip 404)', () => {
+  it('a dispatch for a subject with no runner fails retriably with runner_unavailable', async () => {
+    // Register a runner for subject B only, then dispatch for subject A. The host
+    // MUST NOT fall back to B's runner (subject-first isolation); with no runner
+    // for A the dispatch MUST fail with the retriable `runner_unavailable`.
+    const reg = await driver.post(REGISTER, {
+      runnerId: 'runner_b_1',
+      subject: 'subject_B',
+      capabilities: { providers: ['anthropic'] },
+    });
+    if (reg.status === 404) return; // seam unwired — soft-skip
+
+    const res = await driver.post(DISPATCH, {
+      subject: 'subject_A',
+      runId: 'run_iso',
+      stepId: 'step_0',
+      seq: 0,
+      kind: 'model',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      inputs: { messages: [] },
+    });
+    if (res.status === 404) return;
+
+    expect(
+      res.status >= 400,
+      driver.describe('self-hosted-runner.md §Behavior#1', 'a subject-A dispatch MUST NOT route to a subject-B runner'),
+    ).toBe(true);
+    expect(
+      errCode(res.json),
+      driver.describe('RFC 0122 §Behavior#5', 'a dispatch with no owning-subject runner MUST fail `runner_unavailable`'),
+    ).toBe('runner_unavailable');
+    expect(
+      retriable(res.json),
+      driver.describe('RFC 0122 §Behavior#5', '`runner_unavailable` MUST be retriable'),
+    ).toBe(true);
+  });
+
+  it('a redelivered {runId, stepId} dispatch is dropped, not re-executed (at-most-once)', async () => {
+    const reg = await driver.post(REGISTER, {
+      runnerId: 'runner_a_1',
+      subject: 'subject_A',
+      capabilities: { providers: ['anthropic'] },
+    });
+    if (reg.status === 404) return;
+
+    const frame = {
+      subject: 'subject_A',
+      runId: 'run_idem',
+      stepId: 'step_1',
+      seq: 0,
+      kind: 'model',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      inputs: { messages: [] },
+    };
+    const first = await driver.post(DISPATCH, frame);
+    if (first.status === 404) return;
+    // A host without a live runner backing the seam MAY answer runner_unavailable;
+    // the at-most-once property is only observable when the first dispatch resolved.
+    if (errCode(first.json) === 'runner_unavailable') return;
+
+    const second = await driver.post(DISPATCH, frame);
+    const body = second.json as { deduped?: unknown };
+    expect(
+      body?.deduped,
+      driver.describe(
+        'self-hosted-runner.md §At-most-once dispatch',
+        'a redelivered {runId, stepId} with a persisted result MUST be dropped (deduped:true), not re-dispatched',
+      ),
+    ).toBe(true);
+  });
+});