@openwop/openwop-conformance 1.18.1 → 1.19.0

package/src/scenarios/agent-channel-dispatch.test.ts

@@ -0,0 +1,229 @@
+/**
+ * agent-channel-dispatch (RFC 0082 §B) — PRODUCTION run-graph channel pin +
+ * replay reuse, exercised black-box.
+ *
+ * Complements `agent-deployment-lifecycle.test.ts` Leg 4, which drives the §B
+ * pin through the host-sample `deployment-transition` SEAM. This scenario
+ * proves the SAME contract from a real run graph (no seam): a canonical
+ * `POST /v1/runs` of a workflow whose node binds `agent.channel` MUST
+ *   (1) resolve the channel to a concrete version at first resolution and
+ *       record it as `resolvedChannel` + `resolvedAgentVersion` on
+ *       `agent.invocation.started` (RFC 0077 recorded fact), and
+ *   (2) on `POST /v1/runs/{runId}:fork {mode:"replay"}` RE-READ that recorded
+ *       version — and MUST NOT re-resolve a since-moved channel
+ * per `agent-deployment.md §B` and `version-negotiation.md`
+ * §"Channel resolution + replay determinism". This graduates §B from
+ * seam-proven to production-path-proven.
+ *
+ * Leg 3 (the load-bearing non-re-resolution proof) MOVES the `stable` channel
+ * between the original run and a replay fork via the optional deployment
+ * seam, then asserts the fork STILL carries the ORIGINAL pin (not the moved
+ * version). It self-guards: it runs only when the seam exists AND the move is
+ * observable (a fresh run resolves to a different version); otherwise it logs
+ * and skips its strict assertion without failing.
+ *
+ * Gating (root-first per RFC 0073): soft-skips unless the host advertises
+ * `agents.deployment.supported:true` AND seeds+advertises the
+ * `conformance-agent-channel-dispatch` fixture AND advertises replay mode
+ * `replay`. Visible skip by default; hard-fails under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true` (per `lib/behavior-gate.ts`). Hosts that omit
+ * `agents.deployment` MUST reject a channel-bearing ref with `validation_error`
+ * (`agent-ref.schema.json`) and so cannot seed the fixture — they gate out.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/agent-deployment.md (§B)
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/version-negotiation.md
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0082-agent-deployment-lifecycle.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readDeploymentCap, driveDeploymentTransition } from '../lib/agentDeployment.js';
+
+const FIXTURE_ID = 'conformance-agent-channel-dispatch';
+const BOUND_CHANNEL = 'stable';
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+interface RunEventDoc {
+  eventId: string;
+  runId: string;
+  type: string;
+  payload: Record<string, unknown>;
+  sequence: number;
+}
+interface PollEventsResponse {
+  events: RunEventDoc[];
+  isComplete?: boolean;
+}
+
+async function readAllEvents(runId: string): Promise<RunEventDoc[]> {
+  const res = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events/poll?lastSequence=0`);
+  if (res.status !== 200) return [];
+  const body = res.json as PollEventsResponse;
+  return body.events ?? [];
+}
+
+/** Advertised replay modes (root-level `replay.modes`, RFC 0073 / profiles.ts). */
+async function fetchReplayModes(): Promise<readonly string[]> {
+  const res = await driver.get('/.well-known/openwop', { authenticated: false });
+  if (res.status !== 200) return [];
+  const replay = (res.json as { replay?: { supported?: unknown; modes?: unknown } })?.replay;
+  if (replay?.supported !== true || !Array.isArray(replay.modes)) return [];
+  return replay.modes.filter((m): m is string => typeof m === 'string');
+}
+
+/** First `agent.invocation.started` (by sequence) of a run, or null. */
+async function firstInvocationStarted(runId: string): Promise<RunEventDoc | null> {
+  const events = (await readAllEvents(runId))
+    .filter((e) => e.type === 'agent.invocation.started')
+    .sort((a, b) => a.sequence - b.sequence);
+  return events[0] ?? null;
+}
+
+/** Start the channel-bound fixture, wait for terminal, return its runId. */
+async function startChannelRun(): Promise<string> {
+  const create = await driver.post('/v1/runs', { workflowId: FIXTURE_ID });
+  expect(
+    create.status,
+    driver.describe(
+      'agent-deployment.md §B',
+      `a host advertising agents.deployment + the ${FIXTURE_ID} fixture MUST accept a channel-bound run (201)`,
+    ),
+  ).toBe(201);
+  const runId = (create.json as { runId: string }).runId;
+  await pollUntilTerminal(runId, { timeoutMs: 15_000 });
+  return runId;
+}
+
+describe.skipIf(HTTP_SKIP)('agent-channel-dispatch (RFC 0082 §B): production run-graph channel pin + replay reuse', () => {
+  it('resolves + records the channel pin on a real run and re-reads it on replay (never re-resolving a moved channel)', async (ctx) => {
+    const cap = await readDeploymentCap();
+    if (!behaviorGate('openwop-deployment-channel-dispatch', cap?.supported === true)) return;
+    if (!isFixtureAdvertised(FIXTURE_ID)) {
+      // Host advertises agents.deployment but hasn't seeded the channel-bound
+      // fixture — a host-config precondition, not a conformance failure.
+      ctx.skip();
+      return;
+    }
+    const modes = await fetchReplayModes();
+    if (!modes.includes('replay')) {
+      ctx.skip();
+      return;
+    }
+
+    // ---- Leg 1: production-path channel resolution + recorded pin (§B) ----
+    const sourceRunId = await startChannelRun();
+    const started = await firstInvocationStarted(sourceRunId);
+    expect(
+      started !== null,
+      driver.describe(
+        'agent-deployment.md §B',
+        'a @channel-bound run MUST emit agent.invocation.started',
+      ),
+    ).toBe(true);
+    expect(
+      started!.payload.resolvedChannel === BOUND_CHANNEL,
+      driver.describe(
+        'agent-deployment.md §B',
+        `agent.invocation.started MUST carry the bound channel as resolvedChannel ("${BOUND_CHANNEL}")`,
+      ),
+    ).toBe(true);
+    const pinnedVersion = started!.payload.resolvedAgentVersion;
+    expect(
+      typeof pinnedVersion === 'string' && (pinnedVersion as string).length > 0,
+      driver.describe(
+        'agent-deployment.md §B',
+        'a @channel-bound run MUST record a concrete resolvedAgentVersion (the recorded fact a replay re-reads, RFC 0077)',
+      ),
+    ).toBe(true);
+
+    // ---- Leg 2: replay re-reads the recorded version --------------------
+    const fork1 = await driver.post(
+      `/v1/runs/${encodeURIComponent(sourceRunId)}:fork`,
+      { fromSeq: 0, mode: 'replay' },
+    );
+    if (fork1.status === 501) {
+      // replay advertised but not implemented for this run — skip-equivalent.
+      ctx.skip();
+      return;
+    }
+    expect(
+      fork1.status,
+      driver.describe('rest-endpoints.md POST /v1/runs/{runId}:fork', 'replay fork MUST return 201'),
+    ).toBe(201);
+    const fork1RunId = (fork1.json as { runId: string }).runId;
+    await pollUntilTerminal(fork1RunId, { timeoutMs: 15_000 });
+    const fork1Started = await firstInvocationStarted(fork1RunId);
+    expect(
+      fork1Started !== null,
+      driver.describe('agent-deployment.md §B', 'a replay fork MUST re-emit agent.invocation.started'),
+    ).toBe(true);
+    expect(
+      fork1Started!.payload.resolvedAgentVersion === pinnedVersion,
+      driver.describe(
+        'agent-deployment.md §B',
+        'a replay MUST re-read the recorded resolvedAgentVersion (NOT re-resolve the channel)',
+      ),
+    ).toBe(true);
+
+    // ---- Leg 3 (seam-guarded): move the channel, prove non-re-resolution -
+    // The strongest form of §B: after the original pin, MOVE `stable` to a new
+    // active version via the optional deployment seam. A replay fork of the
+    // ORIGINAL run MUST still carry the ORIGINAL pin — proving the host re-reads
+    // the recorded fact rather than re-resolving the (now-moved) channel.
+    const moved = await driveDeploymentTransition({
+      scenario: 'promote',
+      channel: BOUND_CHANNEL,
+    });
+    if (moved === null) {
+      // No deployment-transition seam — Leg 1+2 already give production-path
+      // evidence; the cross-move proof needs the seam. Honest skip of Leg 3.
+      // eslint-disable-next-line no-console
+      console.warn('[agent-channel-dispatch] deployment seam absent — skipping the channel-move non-re-resolution leg (Leg 3)');
+      return;
+    }
+    // Confirm the move is OBSERVABLE: a fresh channel-bound run must now resolve
+    // to a DIFFERENT version. If it doesn't (canary split, no-op promote), we
+    // can't prove movement — skip the strict assertion rather than assert falsely.
+    const controlRunId = await startChannelRun();
+    const controlStarted = await firstInvocationStarted(controlRunId);
+    const movedVersion = controlStarted?.payload.resolvedAgentVersion;
+    if (typeof movedVersion !== 'string' || movedVersion === pinnedVersion) {
+      // eslint-disable-next-line no-console
+      console.warn('[agent-channel-dispatch] channel did not observably move — skipping Leg 3 strict assertion');
+      return;
+    }
+    const fork2 = await driver.post(
+      `/v1/runs/${encodeURIComponent(sourceRunId)}:fork`,
+      { fromSeq: 0, mode: 'replay' },
+    );
+    if (fork2.status === 501) {
+      ctx.skip();
+      return;
+    }
+    expect(
+      fork2.status,
+      driver.describe('rest-endpoints.md POST /v1/runs/{runId}:fork', 'replay fork MUST return 201'),
+    ).toBe(201);
+    const fork2RunId = (fork2.json as { runId: string }).runId;
+    await pollUntilTerminal(fork2RunId, { timeoutMs: 15_000 });
+    const fork2Started = await firstInvocationStarted(fork2RunId);
+    expect(
+      fork2Started?.payload.resolvedAgentVersion === pinnedVersion,
+      driver.describe(
+        'agent-deployment.md §B',
+        'after the channel moves, a replay of the original run MUST still carry the ORIGINAL pin — never re-resolving the moved channel',
+      ),
+    ).toBe(true);
+    expect(
+      fork2Started?.payload.resolvedAgentVersion !== movedVersion,
+      driver.describe(
+        'agent-deployment.md §B',
+        'a replay MUST NOT resolve to the post-move version (proves the recorded fact is re-read, not re-resolved)',
+      ),
+    ).toBe(true);
+  });
+});

package/src/scenarios/spec-corpus-validity.test.ts

@@ -35,6 +35,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { dirname, join, relative, resolve as pathResolve } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
@@ -53,6 +54,7 @@ import {
   TYPESCRIPT_RUN_HELPERS_PATH,
   V1_DIR,
 } from '../lib/paths.js';
+import { verifyBundle, PROFILE_FLOOR_SCENARIOS } from '../lib/profiles.js';
 
 // Layout-aware paths come from `lib/paths.ts`. Three layouts:
 //   - Repo (github.com/openwop/openwop): schemas/api at repo root,
@@ -721,6 +723,51 @@ describe('spec-corpus: OpenAPI 3.1 spec is structurally valid', () => {
     }
   });
 
+  // ── Reserved-route disambiguation (RFC 0086/0087 + audit PR #495) ──────────
+  // The literal collection routes /v1/agents/roster and /v1/agents/org-chart
+  // share a prefix with the parameterized /v1/agents/{agentId}. The mitigation
+  // excludes the reserved literals from the {agentId} path param via a
+  // negative-lookahead pattern, AND the agent-manifest agentId pattern requires
+  // a dotted-tier form the bare literals can't satisfy. These guard both halves
+  // from silently regressing (the external standards-readiness audit asked the
+  // reserved-route mitigation be bound to a test).
+  it('declares both the literal /v1/agents/{roster,org-chart} routes and the {agentId} param route', () => {
+    const { raw } = readYamlHeader(openapiPath);
+    expect(raw).toContain('/v1/agents/{agentId}:');
+    expect(raw).toContain('/v1/agents/roster:');
+    expect(raw).toContain('/v1/agents/org-chart:');
+  });
+
+  it('every /v1/agents/{agentId} param excludes the reserved literals (roster, org-chart)', () => {
+    const { raw } = readYamlHeader(openapiPath);
+    const paramRoutes = (raw.match(/\/v1\/agents\/\{agentId\}/g) ?? []).length;
+    const exclusions = (raw.match(/\(\?!roster\$\|org-chart\$\)/g) ?? []).length;
+    expect(paramRoutes, 'expected ≥2 /v1/agents/{agentId...} routes (base + /deployments)').toBeGreaterThanOrEqual(2);
+    expect(
+      exclusions,
+      'each /v1/agents/{agentId} param schema MUST exclude the reserved literals via a (?!roster$|org-chart$) lookahead',
+    ).toBeGreaterThanOrEqual(2);
+  });
+
+  it('the reserved-literal exclusion pattern rejects roster/org-chart and accepts a real agentId', () => {
+    const re = /^(?!roster$|org-chart$).+$/;
+    expect(re.test('roster'), 'roster MUST NOT match the {agentId} param').toBe(false);
+    expect(re.test('org-chart'), 'org-chart MUST NOT match the {agentId} param').toBe(false);
+    expect(re.test('core.example.pack.agent')).toBe(true);
+  });
+
+  it('the agent-manifest agentId pattern can never produce a reserved literal (defense in depth)', () => {
+    const manifest = readJson(join(SCHEMAS_DIR, 'agent-manifest.schema.json')) as {
+      properties?: { agentId?: { pattern?: string } };
+    };
+    const pattern = manifest.properties?.agentId?.pattern;
+    expect(typeof pattern, 'agent-manifest.schema.json MUST constrain agentId with a pattern').toBe('string');
+    const re = new RegExp(pattern as string);
+    expect(re.test('roster'), 'manifest agentId MUST NOT permit the reserved literal `roster`').toBe(false);
+    expect(re.test('org-chart'), 'manifest agentId MUST NOT permit the reserved literal `org-chart`').toBe(false);
+    expect(re.test('core.example.pack.agent')).toBe(true);
+  });
+
   it('typed error specializations compose the canonical Error schema', () => {
     const { raw } = readYamlHeader(openapiPath);
 
@@ -1351,3 +1398,139 @@ describe.skipIf(FIXTURES_DOC_PATH === null)('spec-corpus: fixtures.json catalog
     }
   });
 });
+
+// RFC 0089 — conformance certification bundle. The schema itself is compiled +
+// $id-checked by the "JSON Schemas compile under Ajv2020" block above; here we
+// assert a sample bundle validates AND that the §B binding rule (verifyBundle)
+// correctly accepts a valid claim and rejects both a not-derivable claim and a
+// missing-floor-scenario one.
+describe('spec-corpus: RFC 0089 conformance certification bundle + binding rule', () => {
+  // A discovery document that derives `openwop-core-standard`
+  // (isCore ∧ isInterrupts ∧ a transport — supportedTransports omitted ⇒ rest).
+  const coreStandardDiscovery = {
+    protocolVersion: '1.0',
+    supportedEnvelopes: ['final', 'clarification.request'],
+    schemaVersions: { 'workflow-definition': '1.0' },
+    limits: { clarificationRounds: 3, schemaRounds: 2, envelopesPerTurn: 8 },
+  };
+  const coreStandardFloorPassed = [
+    ...PROFILE_FLOOR_SCENARIOS['openwop-core-standard']!.required,
+    'interrupt-resume.test.ts',
+  ];
+  const sampleBundle = {
+    bundleVersion: '1',
+    generatedAt: '2026-06-02T00:00:00Z',
+    generator: { name: '@openwop/openwop-conformance --certify', version: '1.18.1' },
+    suite: { package: '@openwop/openwop-conformance', version: '1.18.1' },
+    host: { name: 'openwop-host-sqlite', version: '1.0.0' },
+    discovery: {
+      url: 'https://example.test/.well-known/openwop',
+      sha256: 'a'.repeat(64),
+      document: coreStandardDiscovery,
+    },
+    claimedProfiles: ['openwop-core-standard'],
+    results: {
+      totals: { passed: coreStandardFloorPassed.length, failed: 0, skipped: 0, total: coreStandardFloorPassed.length },
+      passed: coreStandardFloorPassed,
+      failed: [],
+      skipped: [],
+    },
+  };
+
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const bundleSchema = readJson(join(SCHEMAS_DIR, 'conformance-certification-bundle.schema.json')) as Record<string, unknown>;
+
+  it('a sample bundle validates against conformance-certification-bundle.schema.json', () => {
+    const validate = ajv.compile(bundleSchema);
+    const ok = validate(sampleBundle);
+    expect(ok, JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it('verifyBundle ACCEPTS a claim that is discovery-derivable AND floor-proven (§B)', () => {
+    const r = verifyBundle(sampleBundle);
+    expect(r.valid).toBe(true);
+    expect(r.verdicts[0]?.derivable).toBe(true);
+    expect(r.verdicts[0]?.floorProven).toBe(true);
+  });
+
+  it('verifyBundle REJECTS a profile its discovery document does not derive (§B(1))', () => {
+    const notDerivable = {
+      ...sampleBundle,
+      discovery: { ...sampleBundle.discovery, document: { ...coreStandardDiscovery, supportedEnvelopes: ['final'] } },
+    };
+    const r = verifyBundle(notDerivable);
+    expect(r.valid).toBe(false);
+    expect(r.verdicts[0]?.derivable).toBe(false);
+  });
+
+  it('verifyBundle REJECTS a bundle missing a floor scenario (§B(2))', () => {
+    const missingFloor = {
+      ...sampleBundle,
+      results: { ...sampleBundle.results, passed: coreStandardFloorPassed.filter((s) => s !== 'auth.test.ts') },
+    };
+    const r = verifyBundle(missingFloor);
+    expect(r.valid).toBe(false);
+    expect(r.verdicts[0]?.floorProven).toBe(false);
+    expect(r.verdicts[0]?.missingFloor).toContain('auth.test.ts');
+  });
+});
+
+// RFC 0089 — the committed REAL reference-host bundle, generated by
+// `openwop-conformance --certify` against the in-memory reference host
+// (examples/hosts/in-memory). This is the at-`Accepted` "reference host commits
+// a real generated bundle" evidence: it must (a) validate against the schema and
+// (b) pass the §B binding rule — every profile it CLAIMS must re-derive from its
+// own captured discovery document AND be floor-proven. The bundle lives in
+// `examples/`, which is NOT bundled into the published tarball, so this skips
+// cleanly under the published layout (V1_DIR === null).
+describe.skipIf(V1_DIR === null)('spec-corpus: RFC 0089 committed reference-host certification bundle', () => {
+  const repoRoot = V1_DIR === null ? '' : pathResolve(V1_DIR, '..', '..');
+  const bundlePath = join(repoRoot, 'examples', 'hosts', 'in-memory', 'certification-bundle.json');
+
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const bundleSchema = readJson(join(SCHEMAS_DIR, 'conformance-certification-bundle.schema.json')) as Record<
+    string,
+    unknown
+  >;
+
+  it('the committed bundle file exists (generated by --certify)', () => {
+    expect(existsSync(bundlePath), `expected a committed reference bundle at ${bundlePath}`).toBe(true);
+  });
+
+  it('the committed reference bundle validates against the bundle schema (§A)', () => {
+    const bundle = readJson(bundlePath);
+    const validate = ajv.compile(bundleSchema);
+    const ok = validate(bundle);
+    expect(ok, JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it('verifyBundle ACCEPTS the committed reference bundle — every claimed profile re-derives + is floor-proven (§B)', () => {
+    const bundle = readJson(bundlePath) as Parameters<typeof verifyBundle>[0];
+    const r = verifyBundle(bundle);
+    // The host honestly claims ONLY profiles its discovery document derives, none
+    // of which it fails a floor scenario for — so verifyBundle MUST accept it.
+    const offending = r.verdicts.filter((v) => !v.valid);
+    expect(
+      r.valid,
+      `verifyBundle rejected claimed profile(s): ${JSON.stringify(offending)}`,
+    ).toBe(true);
+  });
+
+  it('discovery.sha256 is the canonical-JSON SHA-256 of the captured discovery.document', () => {
+    const bundle = readJson(bundlePath) as {
+      discovery: { sha256: string; document: unknown };
+    };
+    // Mirror the generator's canonical serialization (sorted keys at every level).
+    const canonical = (value: unknown): string => {
+      if (value === null || typeof value !== 'object') return JSON.stringify(value);
+      if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+      const obj = value as Record<string, unknown>;
+      const keys = Object.keys(obj).sort();
+      return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(',')}}`;
+    };
+    const recomputed = createHash('sha256').update(canonical(bundle.discovery.document)).digest('hex');
+    expect(bundle.discovery.sha256).toBe(recomputed);
+  });
+});