@openwop/openwop-conformance 1.18.0 → 1.19.0

package/src/cli.ts

@@ -11,6 +11,7 @@
  *   openwop-conformance --offline                       # server-free subset only
  *   openwop-conformance --filter discovery               # category filter
  *   openwop-conformance --base-url ... --api-key ... --filter "interrupt|cancellation"
+ *   openwop-conformance --base-url ... --api-key ... --certify out.json   # RFC 0089 bundle
  *
  * Environment variables override flags (per the conformance harness's
  * existing convention):
@@ -25,7 +26,19 @@
 
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { dirname, resolve as resolvePath } from 'node:path';
+import { dirname, resolve as resolvePath, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from './lib/paths.js';
+import {
+  deriveProfiles,
+  isCoreStandard,
+  agentPlatformStatus,
+  type DiscoveryPayload,
+} from './lib/profiles.js';
 
 interface ParsedArgs {
   readonly baseUrl: string | undefined;
@@ -35,6 +48,8 @@ interface ParsedArgs {
   readonly help: boolean;
   readonly impl: string | undefined;
   readonly implVersion: string | undefined;
+  /** RFC 0089 — emit a conformance certification bundle to this path. */
+  readonly certify: string | undefined;
 }
 
 function parseArgs(argv: readonly string[]): ParsedArgs {
@@ -45,6 +60,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
   let help = false;
   let impl: string | undefined;
   let implVersion: string | undefined;
+  let certify: string | undefined;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i] ?? '';
@@ -87,6 +103,9 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
       case '--implementation-version':
         implVersion = nextValue();
         break;
+      case '--certify':
+        certify = nextValue();
+        break;
       default:
         if (arg.startsWith('-')) {
           // Unknown flag — pass through to vitest by ignoring here.
@@ -94,7 +113,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
     }
   }
 
-  return { baseUrl, apiKey, offline, filter, help, impl, implVersion };
+  return { baseUrl, apiKey, offline, filter, help, impl, implVersion, certify };
 }
 
 const HELP_TEXT = `openwop-conformance — run the openwop conformance suite against a server
@@ -114,6 +133,14 @@ Implementation labels (cosmetic — surface in failure messages):
   --impl <name>             Implementation name        (env: OPENWOP_IMPLEMENTATION_NAME)
   --impl-version <version>  Implementation version     (env: OPENWOP_IMPLEMENTATION_VERSION)
 
+Certification (RFC 0089):
+  --certify <out.json>  Generate a machine-readable conformance certification
+                        bundle: fetch /.well-known/openwop (captured verbatim +
+                        SHA-256), derive claimedProfiles from it, run the suite
+                        recording each scenario's terminal state, validate the
+                        assembled bundle against the bundle schema, and write it
+                        to <out.json>. Requires --base-url (and --api-key as usual).
+
 Other:
   --help, -h            Show this message
 
@@ -121,9 +148,234 @@ Examples:
   openwop-conformance --offline
   openwop-conformance --base-url https://api.example.com --api-key hk_test_abc
   openwop-conformance --filter "discovery|errors"
+  openwop-conformance --base-url https://api.example.com --api-key hk_test_abc \\
+    --certify certification-bundle.json
 `;
 
-function main(): never {
+/** This CLI package's own version — surfaced as `generator.version` + `suite.version`. */
+function suiteVersion(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkgPath = resolvePath(here, '..', 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { version?: unknown };
+  return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+}
+
+/**
+ * Deterministic canonical-JSON serialization (RFC 8785 spirit): object keys
+ * sorted lexicographically at every level, arrays preserved in order. Used to
+ * compute `discovery.sha256` so a verifier can re-derive the same digest from
+ * a live `/.well-known/openwop` fetch regardless of incidental key order.
+ */
+function canonicalJSON(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJSON).join(',')}]`;
+  const obj = value as Record<string, unknown>;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJSON(obj[k])}`).join(',')}}`;
+}
+
+/**
+ * The full set of profiles a discovery document derives — the closed
+ * `deriveProfiles` catalog plus the two operational annexes
+ * (`openwop-core-standard`, `openwop-agent-platform`) when their discovery
+ * predicate holds. This is `claimedProfiles`: a generated bundle MUST NOT
+ * claim a profile its own discovery document does not derive (RFC 0089 §B(1)).
+ */
+function claimedProfilesFor(doc: DiscoveryPayload): string[] {
+  const profiles: string[] = [...deriveProfiles(doc)];
+  if (isCoreStandard(doc)) profiles.push('openwop-core-standard');
+  if (agentPlatformStatus(doc) !== 'none') profiles.push('openwop-agent-platform');
+  return profiles;
+}
+
+/** A single scenario test file's terminal state, derived from the vitest JSON report. */
+type ScenarioState = 'passed' | 'failed' | 'skipped';
+
+/** The subset of vitest's JSON reporter output we read. */
+interface VitestJsonReport {
+  readonly testResults?: ReadonlyArray<{
+    readonly name?: string;
+    readonly assertionResults?: ReadonlyArray<{ readonly status?: string }>;
+  }>;
+}
+
+/**
+ * Reduce a vitest JSON report into a per-scenario-file terminal state, keyed by
+ * the test-file basename (e.g. `discovery.test.ts`) to align with the basenames
+ * in `PROFILE_FLOOR_SCENARIOS`. A file is `passed` only if it ran AND had ≥1
+ * passing assertion AND zero failures (non-vacuous, per §C); a fully-skipped
+ * file is `skipped`; any failed assertion makes the file `failed`.
+ */
+function scenarioStatesFromReport(report: VitestJsonReport): Map<string, ScenarioState> {
+  const states = new Map<string, ScenarioState>();
+  for (const file of report.testResults ?? []) {
+    const name = file.name;
+    if (typeof name !== 'string') continue;
+    const basename = name.split('/').pop() ?? name;
+    const assertions = file.assertionResults ?? [];
+    let passes = 0;
+    let failures = 0;
+    let nonSkipped = 0;
+    for (const a of assertions) {
+      if (a.status === 'passed') {
+        passes++;
+        nonSkipped++;
+      } else if (a.status === 'failed') {
+        failures++;
+        nonSkipped++;
+      }
+      // `skipped` / `todo` / `pending` count toward neither pass nor fail.
+    }
+    let state: ScenarioState;
+    if (failures > 0) state = 'failed';
+    else if (passes > 0 && nonSkipped > 0) state = 'passed';
+    else state = 'skipped';
+    states.set(basename, state);
+  }
+  return states;
+}
+
+/** Generate + validate + write an RFC 0089 conformance certification bundle. */
+async function runCertify(args: ParsedArgs, baseUrl: string, apiKey: string): Promise<never> {
+  const outPath = args.certify;
+  if (outPath === undefined) process.exit(2);
+
+  // (a) Fetch /.well-known/openwop verbatim + its canonical-JSON SHA-256.
+  const discoveryUrl = `${baseUrl.replace(/\/$/, '')}/.well-known/openwop`;
+  let document: DiscoveryPayload;
+  try {
+    const resp = await fetch(discoveryUrl, { headers: { Accept: 'application/json' } });
+    if (!resp.ok) {
+      process.stderr.write(
+        `openwop-conformance --certify: GET ${discoveryUrl} returned HTTP ${resp.status}.\n`,
+      );
+      process.exit(2);
+    }
+    document = (await resp.json()) as DiscoveryPayload;
+  } catch (err) {
+    process.stderr.write(
+      `openwop-conformance --certify: failed to fetch ${discoveryUrl}: ${String(err)}\n`,
+    );
+    process.exit(2);
+  }
+  const sha256 = createHash('sha256').update(canonicalJSON(document)).digest('hex');
+
+  // (b) Derive claimedProfiles from the captured document.
+  const claimedProfiles = claimedProfilesFor(document);
+
+  // (c) Run the suite, capturing per-scenario terminal state via the vitest
+  // JSON reporter. server-targeted scenarios live under src/scenarios/.
+  const here = dirname(fileURLToPath(import.meta.url));
+  const conformanceRoot = resolvePath(here, '..');
+  const reportDir = mkdtempSync(join(tmpdir(), 'owp-certify-'));
+  const reportFile = join(reportDir, 'vitest-report.json');
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  env.OPENWOP_BASE_URL = baseUrl;
+  env.OPENWOP_API_KEY = apiKey;
+  if (args.impl) env.OPENWOP_IMPLEMENTATION_NAME = args.impl;
+  if (args.implVersion) env.OPENWOP_IMPLEMENTATION_VERSION = args.implVersion;
+
+  const vitestArgs: string[] = [
+    'vitest',
+    'run',
+    '--config',
+    resolvePath(conformanceRoot, 'vitest.config.ts'),
+    '--reporter=json',
+    `--outputFile=${reportFile}`,
+  ];
+  const runResult = spawnSync('npx', vitestArgs, { cwd: conformanceRoot, env, stdio: 'inherit' });
+  if (runResult.error) {
+    process.stderr.write(
+      `openwop-conformance --certify: failed to spawn vitest: ${String(runResult.error)}\n`,
+    );
+    process.exit(2);
+  }
+
+  let report: VitestJsonReport;
+  try {
+    report = JSON.parse(readFileSync(reportFile, 'utf8')) as VitestJsonReport;
+  } catch (err) {
+    process.stderr.write(
+      `openwop-conformance --certify: could not read vitest JSON report at ${reportFile}: ${String(err)}\n`,
+    );
+    process.exit(2);
+  } finally {
+    rmSync(reportDir, { recursive: true, force: true });
+  }
+
+  const states = scenarioStatesFromReport(report);
+  const passed: string[] = [];
+  const failed: string[] = [];
+  const skipped: string[] = [];
+  for (const [basename, state] of [...states.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    if (state === 'passed') passed.push(basename);
+    else if (state === 'failed') failed.push(basename);
+    else skipped.push(basename);
+  }
+
+  // (d) Assemble the bundle.
+  const version = suiteVersion();
+  const impl = (document as { implementation?: { name?: unknown; version?: unknown; vendor?: unknown } })
+    .implementation;
+  const hostName =
+    args.impl ?? (typeof impl?.name === 'string' ? impl.name : 'unknown-host');
+  const hostVersion =
+    args.implVersion ?? (typeof impl?.version === 'string' ? impl.version : '0.0.0');
+  const host: { name: string; version: string; vendor?: string } = {
+    name: hostName,
+    version: hostVersion,
+  };
+  if (typeof impl?.vendor === 'string') host.vendor = impl.vendor;
+
+  const bundle = {
+    bundleVersion: '1' as const,
+    generatedAt: new Date().toISOString(),
+    generator: { name: '@openwop/openwop-conformance --certify', version },
+    suite: { package: '@openwop/openwop-conformance' as const, version },
+    host,
+    discovery: { url: discoveryUrl, sha256, document },
+    claimedProfiles,
+    results: {
+      totals: {
+        passed: passed.length,
+        failed: failed.length,
+        skipped: skipped.length,
+        total: passed.length + failed.length + skipped.length,
+      },
+      passed,
+      failed,
+      skipped,
+    },
+  };
+
+  // (e) Validate against the bundle schema BEFORE writing.
+  const schema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'conformance-certification-bundle.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(schema);
+  if (!validate(bundle)) {
+    process.stderr.write(
+      'openwop-conformance --certify: assembled bundle FAILED schema validation:\n' +
+        `${JSON.stringify(validate.errors, null, 2)}\n`,
+    );
+    process.exit(2);
+  }
+
+  writeFileSync(outPath, `${JSON.stringify(bundle, null, 2)}\n`);
+  process.stdout.write(
+    `openwop-conformance --certify: wrote certification bundle to ${outPath}\n` +
+      `  host: ${host.name}@${host.version}\n` +
+      `  claimedProfiles: ${claimedProfiles.length > 0 ? claimedProfiles.join(', ') : '(none)'}\n` +
+      `  results: ${passed.length} passed / ${failed.length} failed / ${skipped.length} skipped\n`,
+  );
+  // Exit code mirrors the suite outcome: a failing run still produces a bundle
+  // (the failures are recorded), but the process exit reflects pass/fail.
+  process.exit(failed.length > 0 ? 1 : 0);
+}
+
+async function main(): Promise<never> {
   const args = parseArgs(process.argv.slice(2));
 
   if (args.help) {
@@ -139,6 +391,18 @@ function main(): never {
   if (args.impl) env.OPENWOP_IMPLEMENTATION_NAME = args.impl;
   if (args.implVersion) env.OPENWOP_IMPLEMENTATION_VERSION = args.implVersion;
 
+  // RFC 0089 — certification-bundle generation requires a live host.
+  if (args.certify !== undefined) {
+    if (!env.OPENWOP_BASE_URL || !env.OPENWOP_API_KEY) {
+      process.stderr.write(
+        'openwop-conformance --certify: --base-url and --api-key are required.\n' +
+          'Run `openwop-conformance --help` for usage.\n',
+      );
+      process.exit(2);
+    }
+    return runCertify(args, env.OPENWOP_BASE_URL, env.OPENWOP_API_KEY);
+  }
+
   if (!args.offline && (!env.OPENWOP_BASE_URL || !env.OPENWOP_API_KEY)) {
     process.stderr.write(
       'openwop-conformance: --base-url and --api-key are required (or use --offline).\n' +
@@ -184,4 +448,4 @@ function main(): never {
   process.exit(result.status ?? 1);
 }
 
-main();
+void main();

package/src/lib/profiles.ts

@@ -428,3 +428,88 @@ export function hasProfile(c: DiscoveryPayload, profile: ProfileName): boolean {
       return isTriggerBridge(c);
   }
 }
+
+// ── RFC 0089: conformance certification bundle — floor-scenario sets + verifier ──
+//
+// G1 (RFC 0089): the §B binding rule needs each profile's REQUIRED floor
+// scenarios in a machine-readable form. Source of truth for
+// `openwop-core-standard` is `core-standard-profile.md` §C — the nine named
+// black-box floor scenarios plus the `interrupt-*` family. Keyed by profile
+// name (string) because annex profiles like `openwop-core-standard` sit outside
+// the closed `PROFILE_NAMES` catalog.
+
+export interface ProfileFloor {
+  /** Scenario files (basenames) that MUST each appear in `results.passed`. */
+  readonly required: readonly string[];
+  /** Prefix groups where ≥1 matching passed scenario satisfies the group. */
+  readonly requiredAnyPrefix?: readonly string[];
+}
+
+export const PROFILE_FLOOR_SCENARIOS: Readonly<Record<string, ProfileFloor>> = {
+  'openwop-core-standard': {
+    required: [
+      'runs-lifecycle.test.ts',
+      'discovery.test.ts',
+      'auth.test.ts',
+      'eventOrdering.test.ts',
+      'failure-path.test.ts',
+      'idempotency.test.ts',
+      'idempotency-key-determinism.test.ts',
+      'webhook-negative.test.ts',
+      'audit-log-verification.test.ts',
+    ],
+    requiredAnyPrefix: ['interrupt-'],
+  },
+};
+
+/** Is `profile` derivable from a discovery document? Maps a profile name to its predicate (RFC 0089 §B(1)). */
+export function profileDerivable(c: DiscoveryPayload, profile: string): boolean {
+  if (profile === 'openwop-core-standard') return isCoreStandard(c);
+  if (profile === 'openwop-agent-platform') return agentPlatformStatus(c) !== 'none';
+  if ((PROFILE_NAMES as readonly string[]).includes(profile)) {
+    return deriveProfiles(c).includes(profile as ProfileName);
+  }
+  return false;
+}
+
+/** Minimal shape of an RFC 0089 certification bundle the verifier reads. */
+export interface CertificationBundleLike {
+  readonly discovery: { readonly document: DiscoveryPayload };
+  readonly claimedProfiles: readonly string[];
+  readonly results: { readonly passed: readonly string[] };
+}
+
+export interface BundleProfileVerdict {
+  readonly profile: string;
+  /** §B(1): derivable from the captured discovery document. */
+  readonly derivable: boolean;
+  /** §B(2): every floor scenario for the profile is in `results.passed`. */
+  readonly floorProven: boolean;
+  readonly valid: boolean;
+  readonly missingFloor: readonly string[];
+}
+
+const scenarioBasename = (id: string): string => id.split('/').pop() ?? id;
+
+/**
+ * Verify a bundle's claim for one profile per RFC 0089 §B. A consumer MUST
+ * re-derive (this function) rather than trust `claimedProfiles` verbatim.
+ */
+export function verifyBundleProfile(bundle: CertificationBundleLike, profile: string): BundleProfileVerdict {
+  const derivable = profileDerivable(bundle.discovery.document, profile);
+  const floor = PROFILE_FLOOR_SCENARIOS[profile];
+  const passed = new Set(bundle.results.passed.map(scenarioBasename));
+  const missingFloor = floor ? floor.required.filter((r) => !passed.has(scenarioBasename(r))) : [];
+  const prefixOk = (floor?.requiredAnyPrefix ?? []).every((p) => [...passed].some((s) => s.startsWith(p)));
+  const floorProven = missingFloor.length === 0 && prefixOk;
+  return { profile, derivable, floorProven, valid: derivable && floorProven, missingFloor };
+}
+
+/** Verify every profile in `bundle.claimedProfiles`; the bundle is valid iff all claims are valid. */
+export function verifyBundle(bundle: CertificationBundleLike): {
+  readonly valid: boolean;
+  readonly verdicts: readonly BundleProfileVerdict[];
+} {
+  const verdicts = bundle.claimedProfiles.map((p) => verifyBundleProfile(bundle, p));
+  return { valid: verdicts.every((v) => v.valid), verdicts };
+}

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);
+  });
+});