@openwop/openwop-conformance 1.0.0 → 1.1.1

package/src/scenarios/production-retention-expiry.test.ts

@@ -0,0 +1,164 @@
+/**
+ * RFC 0009 §C: production-profile event-retention expiry.
+ *
+ * Verifies that hosts claiming the `openwop-production` profile satisfy
+ * `spec/v1/production-profile.md` §"Event retention":
+ *
+ *   1. `capabilities.production.retention.supported: true` is advertised.
+ *   2. `capabilities.production.retention.minWindowSeconds >= 604800`
+ *      (7 days) — the minimum retention window for public hosts.
+ *   3. `GET /v1/runs/{expiredRunId}` on an expired run returns `410 Gone`
+ *      (preferred) or `404 Not Found` per spec, with the canonical
+ *      error envelope `{error, message, details?}`.
+ *
+ * Forcing expiry is host-private — the RFC defers endpoint normation
+ * (unresolved question #1). The scenario reads two env vars supplied
+ * by the operator running the suite:
+ *
+ *   - `OPENWOP_TEST_EXPIRED_RUN_ID` — id of a pre-expired run the
+ *     host has on file. Used by both the soft-skip and active paths.
+ *   - `OPENWOP_TEST_FORCE_EXPIRE_URL` — optional host-private endpoint
+ *     the suite POSTs to in order to evict a freshly-created run.
+ *     Honored only when `capabilities.production.retention.testForceExpire: true`.
+ *
+ * When neither path is available, the scenario asserts only the
+ * capability shape and soft-skips the envelope check.
+ *
+ * @see RFCS/0009-production-profile-conformance.md §C
+ * @see spec/v1/production-profile.md §"Event retention"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+
+interface RetentionCaps {
+  supported?: boolean;
+  minWindowSeconds?: number;
+  testForceExpire?: boolean;
+}
+
+interface ProductionCaps {
+  supported?: boolean;
+  retention?: RetentionCaps;
+}
+
+async function readProductionCaps(): Promise<ProductionCaps | undefined> {
+  const disco = await driver.get('/.well-known/openwop');
+  return (disco.json as { capabilities?: { production?: ProductionCaps } })
+    .capabilities?.production;
+}
+
+function isProfileAdvertised(prod: ProductionCaps | undefined): boolean {
+  return prod?.supported === true && prod?.retention?.supported === true;
+}
+
+const SEVEN_DAYS_SECONDS = 604800;
+
+describe('production-retention-expiry: capability shape', () => {
+  it('host claiming openwop-production with retention advertises required fields', async () => {
+    const prod = await readProductionCaps();
+
+    if (!behaviorGate('openwop-production', isProfileAdvertised(prod))) {
+      return;
+    }
+
+    expect(prod?.retention?.supported, driver.describe(
+      'production-profile.md §"Event retention"',
+      'capabilities.production.retention.supported MUST be true for production-profile claimants',
+    )).toBe(true);
+
+    expect(prod?.retention?.minWindowSeconds, driver.describe(
+      'production-profile.md §"Event retention"',
+      'capabilities.production.retention.minWindowSeconds MUST be advertised when retention.supported is true',
+    )).toBeDefined();
+
+    expect(
+      Number.isInteger(prod?.retention?.minWindowSeconds) &&
+        (prod?.retention?.minWindowSeconds ?? 0) >= SEVEN_DAYS_SECONDS,
+      driver.describe(
+        'production-profile.md §"Event retention"',
+        'minWindowSeconds MUST be an integer ≥ 604800 (7 days) for public production-profile claimants',
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('production-retention-expiry: 410/404 envelope on expired run', () => {
+  it('GET /v1/runs/{expiredRunId} returns 410 or 404 with canonical envelope', async () => {
+    const prod = await readProductionCaps();
+
+    if (!behaviorGate('openwop-production', isProfileAdvertised(prod))) {
+      return;
+    }
+
+    let expiredRunId = process.env.OPENWOP_TEST_EXPIRED_RUN_ID;
+
+    // Active expiry path: when the host advertises a test force-expire
+    // hook, create a fresh run and call the operator-supplied endpoint
+    // to evict it. The endpoint shape is host-private (RFC 0009 Q#1).
+    const forceExpireUrl = process.env.OPENWOP_TEST_FORCE_EXPIRE_URL;
+    const forceExpireMethod = process.env.OPENWOP_TEST_FORCE_EXPIRE_METHOD ?? 'POST';
+
+    if (
+      prod?.retention?.testForceExpire === true &&
+      forceExpireUrl !== undefined &&
+      expiredRunId === undefined
+    ) {
+      // Create a throwaway run.
+      const create = await driver.post('/v1/runs', {
+        workflowId: 'conformance-noop',
+      });
+      if (create.status === 201) {
+        const newRunId = (create.json as { runId: string }).runId;
+        // Call the host-private force-expire endpoint. Operator wires
+        // this to whatever route the host exposes.
+        const url = forceExpireUrl.replace('{runId}', encodeURIComponent(newRunId));
+        const forced = await fetch(url, { method: forceExpireMethod });
+        if (forced.ok || forced.status === 204) {
+          expiredRunId = newRunId;
+        }
+      }
+    }
+
+    if (expiredRunId === undefined) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[production-retention-expiry] no expired runId available (set OPENWOP_TEST_EXPIRED_RUN_ID or advertise testForceExpire + provide OPENWOP_TEST_FORCE_EXPIRE_URL); skipping envelope assertion',
+      );
+      return;
+    }
+
+    const res = await driver.get(`/v1/runs/${encodeURIComponent(expiredRunId)}`);
+
+    expect(
+      res.status === 410 || res.status === 404,
+      driver.describe(
+        'production-profile.md §"Event retention"',
+        'expired run MUST return 410 Gone (preferred) or 404 Not Found',
+      ),
+    ).toBe(true);
+
+    const body = res.json as {
+      error?: string;
+      message?: string;
+      details?: { expiredAt?: string };
+    };
+
+    expect(typeof body.error, driver.describe(
+      'production-profile.md §"Event retention"',
+      'expired-run response MUST use the canonical error envelope ({error, message, details?})',
+    )).toBe('string');
+    expect((body.error ?? '').length).toBeGreaterThan(0);
+
+    expect(typeof body.message).toBe('string');
+    expect((body.message ?? '').length).toBeGreaterThan(0);
+
+    // When the host returns 410, details.expiredAt is RECOMMENDED.
+    // Soft-check: when present, MUST be a non-empty string.
+    if (res.status === 410 && body.details?.expiredAt !== undefined) {
+      expect(typeof body.details.expiredAt).toBe('string');
+      expect(body.details.expiredAt.length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/scenarios/registry-public.test.ts

@@ -0,0 +1,222 @@
+/**
+ * Public-registry availability scenario — `packs.openwop.dev`.
+ *
+ * Unlike `pack-registry.test.ts` (which probes the host-under-test for an
+ * optional in-host registry), this scenario hits the *public, hosted*
+ * registry at `packs.openwop.dev` directly. Its purpose is to provide a
+ * single mechanical check that the public registry is up, serves the four
+ * documented endpoint shapes, and returns valid manifests for the
+ * spec-canonical packs currently published.
+ *
+ * Gating:
+ *   This scenario is skipped by default — `@openwop/openwop-conformance`
+ *   runs MUST NOT require outbound connectivity to `packs.openwop.dev`.
+ *   Opt-in via `OPENWOP_TEST_PUBLIC_REGISTRY=true`.
+ *
+ * Why this lives in the conformance suite even though it's not a host
+ * conformance scenario:
+ *   - It provides a one-command public-registry healthcheck for the
+ *     project's own operations.
+ *   - It documents (via assertions) the contract `packs.openwop.dev`
+ *     promises to serve.
+ *   - It reuses the same vitest scaffolding as the rest of the suite.
+ *
+ * @see spec/v1/registry-operations.md
+ * @see ROADMAP.md §"Hosted infrastructure"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+
+const REGISTRY_BASE = 'https://packs.openwop.dev';
+const ENABLED = process.env.OPENWOP_TEST_PUBLIC_REGISTRY === 'true';
+
+const PACK_NAME_RE = /^(core|vendor|community|private)\.[a-z][a-z0-9_-]*(\.[a-z][a-zA-Z0-9_-]*)+$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+async function get(path: string): Promise<{ status: number; json: unknown }> {
+  const res = await fetch(`${REGISTRY_BASE}${path}`, {
+    headers: { Accept: 'application/json' },
+  });
+  let json: unknown = undefined;
+  try {
+    json = await res.json();
+  } catch {
+    // body may not be JSON (e.g. tarball); caller handles.
+  }
+  return { status: res.status, json };
+}
+
+describe('registry-public: packs.openwop.dev discovery document', () => {
+  it('GET /.well-known/openwop-registry returns a valid discovery payload', async () => {
+    if (!ENABLED) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[registry-public] skipped — set OPENWOP_TEST_PUBLIC_REGISTRY=true to enable',
+      );
+      return;
+    }
+
+    const res = await get('/.well-known/openwop-registry');
+    expect(res.status).toBe(200);
+
+    const body = res.json as {
+      registryVersion?: string;
+      protocolVersion?: string;
+      url?: string;
+      supportedNamespaces?: string[];
+      supportedSigningMethods?: string[];
+      endpoints?: Record<string, string>;
+    };
+
+    expect(body.registryVersion).toBe('1.0.0');
+    expect(body.protocolVersion).toBe('1.0');
+    expect(typeof body.url).toBe('string');
+    expect(Array.isArray(body.supportedNamespaces)).toBe(true);
+    expect(body.supportedNamespaces).toEqual(
+      expect.arrayContaining(['core', 'vendor', 'community']),
+    );
+    expect(Array.isArray(body.supportedSigningMethods)).toBe(true);
+    expect(body.supportedSigningMethods).toEqual(expect.arrayContaining(['ed25519']));
+
+    // The four canonical endpoint shapes from registry-operations.md
+    // (filesystem-backed registries serve packMetadata at a file path; see endpointAliases note).
+    expect(typeof body.endpoints?.registryIndex).toBe('string');
+    expect(typeof body.endpoints?.packMetadata).toBe('string');
+    expect(typeof body.endpoints?.versionManifest).toBe('string');
+    expect(typeof body.endpoints?.versionTarball).toBe('string');
+  });
+});
+
+describe('registry-public: packs.openwop.dev index', () => {
+  it('GET /v1/index.json returns a non-empty pack list with valid name + version shapes', async () => {
+    if (!ENABLED) return;
+
+    const res = await get('/v1/index.json');
+    expect(res.status).toBe(200);
+
+    const body = res.json as {
+      packs?: Array<{ name?: string; latestVersion?: string }>;
+      generated?: string;
+    };
+
+    expect(Array.isArray(body.packs)).toBe(true);
+    expect(body.packs?.length ?? 0).toBeGreaterThan(0);
+
+    for (const p of body.packs ?? []) {
+      expect(p.name, `pack name must match reverse-DNS pattern: ${p.name}`).toMatch(PACK_NAME_RE);
+      expect(p.latestVersion, `pack version must be semver: ${p.latestVersion}`).toMatch(SEMVER_RE);
+    }
+  });
+});
+
+describe('registry-public: spec-canonical pack manifests resolve', () => {
+  const KNOWN_PACKS = [
+    { name: 'core.openwop.examples', version: '1.0.0' },
+    { name: 'community.openwop-team.demo', version: '0.1.0' },
+    { name: 'vendor.openwop.rust-hello', version: '1.0.0' },
+  ];
+
+  for (const { name, version } of KNOWN_PACKS) {
+    it(`GET /v1/packs/${name}/-/${version}.json returns a valid manifest`, async () => {
+      if (!ENABLED) return;
+
+      const res = await get(`/v1/packs/${name}/-/${version}.json`);
+      expect(res.status).toBe(200);
+
+      const manifest = res.json as { name?: string; version?: string };
+      expect(manifest.name).toBe(name);
+      expect(manifest.version).toBe(version);
+    });
+  }
+});
+
+describe('registry-public: tarball + signature + Ed25519 verify roundtrip', () => {
+  // core.openwop.examples@1.0.0 is the canonical reference pack for this
+  // check: published since the registry MVP, signed with the
+  // `openwop-registry-root` key over the whole tarball (method='ed25519').
+  // The same recipe applies to any pack at the registry; this scenario
+  // exercises the worst-case full roundtrip so clients have a wire-level
+  // contract for verifying packs before installing them.
+  //
+  // What gets asserted, in order:
+  //   1. Version manifest, tarball, signature, and public key all 200.
+  //   2. SRI integrity in the manifest matches a fresh sha256 of the
+  //      tarball bytes — protects against tarball tampering between
+  //      publish + retrieval.
+  //   3. Detached Ed25519 signature verifies against the public key over
+  //      the bytes the publisher signed (per signing.method).
+  const PACK_NAME = 'core.openwop.examples';
+  const PACK_VERSION = '1.0.0';
+
+  async function getBinary(path: string): Promise<{ status: number; bytes: Buffer }> {
+    const res = await fetch(`${REGISTRY_BASE}${path}`);
+    const ab = await res.arrayBuffer();
+    return { status: res.status, bytes: Buffer.from(ab) };
+  }
+
+  async function getText(path: string): Promise<{ status: number; body: string }> {
+    const res = await fetch(`${REGISTRY_BASE}${path}`);
+    const body = await res.text();
+    return { status: res.status, body };
+  }
+
+  it(`tarball + sig + public key all retrievable, SRI matches, Ed25519 verifies for ${PACK_NAME}@${PACK_VERSION}`, async () => {
+    if (!ENABLED) return;
+
+    // 1. Manifest (JSON).
+    const manifestRes = await get(`/v1/packs/${PACK_NAME}/-/${PACK_VERSION}.json`);
+    expect(manifestRes.status).toBe(200);
+    const manifest = manifestRes.json as {
+      signing?: { method?: string; keyId?: string; publicKeyUrl?: string };
+      integrity?: string;
+    };
+    expect(typeof manifest.signing?.method).toBe('string');
+    expect(typeof manifest.signing?.keyId).toBe('string');
+    expect(typeof manifest.integrity).toBe('string');
+
+    // 2. Tarball.
+    const tarball = await getBinary(`/v1/packs/${PACK_NAME}/-/${PACK_VERSION}.tgz`);
+    expect(tarball.status, 'tarball MUST be retrievable').toBe(200);
+    expect(tarball.bytes.byteLength, 'tarball MUST be non-empty').toBeGreaterThan(0);
+
+    // 3. Detached signature (64-byte raw Ed25519).
+    const sig = await getBinary(`/v1/packs/${PACK_NAME}/-/${PACK_VERSION}.sig`);
+    expect(sig.status, 'signature MUST be retrievable').toBe(200);
+    expect(sig.bytes.byteLength, 'Ed25519 detached signature MUST be 64 bytes').toBe(64);
+
+    // 4. Public key — fetch from the publisher-declared URL when present,
+    //    else fall back to the canonical `/keys/<keyId>.pub` shape.
+    const keyUrl = manifest.signing!.publicKeyUrl ?? `/keys/${manifest.signing!.keyId}.pub`;
+    const keyRes = await getText(keyUrl);
+    expect(keyRes.status, `public key MUST be retrievable at ${keyUrl}`).toBe(200);
+    const publicKey = createPublicKey(keyRes.body);
+
+    // 5. SRI integrity check: `sha256-<base64>=` MUST match a fresh
+    //    sha256 of the tarball bytes per registry-operations.md.
+    expect(manifest.integrity).toMatch(/^sha256-[A-Za-z0-9+/]+=*$/);
+    const expectedSri = `sha256-${createHash('sha256').update(tarball.bytes).digest('base64')}`;
+    expect(expectedSri, 'SRI integrity in manifest MUST match a fresh sha256 of the tarball').toBe(
+      manifest.integrity,
+    );
+
+    // 6. Ed25519 verification. Two canonical signing conventions per
+    //    `node-packs.md` §"Signing recipe": `method=ed25519` signs the
+    //    whole tarball; `method=manual` signs the pack.json bytes inside
+    //    the tarball. core.openwop.examples uses `ed25519`.
+    const method = manifest.signing!.method;
+    expect(['ed25519', 'manual']).toContain(method);
+
+    // For `ed25519` the signed bytes are the tarball; for `manual` the
+    // signed bytes are pack.json extracted from the tarball. This
+    // scenario picks `core.openwop.examples` specifically because it's
+    // `method=ed25519` — the simpler path. Extending to `manual` would
+    // require the tarball extractor from registry/scripts/verify-
+    // signatures.mjs which is intentionally out of scope here.
+    if (method !== 'ed25519') return;
+
+    const verified = cryptoVerify(null, tarball.bytes, publicKey, sig.bytes);
+    expect(verified, `Ed25519 signature over ${PACK_NAME}@${PACK_VERSION}.tgz MUST verify against ${manifest.signing!.keyId}`)
+      .toBe(true);
+  });
+});

package/src/scenarios/replay-llm-cache-key.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Cross-host LLM cache-key parity (replay.md §"LLM cache-key recipe").
+ *
+ * Verifies that two OpenWOP-compliant hosts replaying the same LLM
+ * provider request compute the same cache key. The recipe is normative
+ * (replay.md §B): canonical JSON of `(provider, model, messages, tools,
+ * temperature, topP, topK, responseFormat)` → SHA-256 → lowercase hex.
+ *
+ * Status: PLACEHOLDER. As of 2026-05-11, neither reference host
+ * (`examples/hosts/in-memory/`, `examples/hosts/sqlite/`) implements
+ * LLM-calling nodes — both execute only `core.noop` / `core.delay` /
+ * `core.approvalGate` fixtures. This scenario lands as `it.todo()` so
+ * the contract surface is tracked; assertions land when the first
+ * reference host ships an LLM-call node.
+ *
+ * What the live scenario WILL exercise (when implemented):
+ *   1. Boot host A against `OPENWOP_BASE_URL`.
+ *   2. Boot host B against `OPENWOP_BASE_URL_B`.
+ *   3. Submit the same workflow + inputs (an LLM-calling fixture).
+ *   4. Read each host's emitted `node.completed.payload.cacheKey` (or
+ *      equivalent debug-bundle surface).
+ *   5. Assert the two hex strings are equal.
+ *
+ * @see spec/v1/replay.md §"LLM cache-key recipe"
+ */
+
+import { describe, it } from 'vitest';
+
+describe('replay-llm-cache-key: cross-host determinism (placeholder)', () => {
+  it.todo(
+    'two hosts replaying the same LLM provider request compute the same cache key (replay.md §D)',
+  );
+  it.todo('LLM cache key is computed via SHA-256 of canonical JSON per replay.md §B');
+  it.todo('cache key omits non-recipe fields (max_tokens, stop, stream, seed, etc.) per replay.md §A');
+});

package/src/scenarios/replay-retention-expiry.test.ts

@@ -0,0 +1,178 @@
+/**
+ * Replay retention-expiry scenario per `spec/v1/replay.md` §"Retention
+ * and garbage collection."
+ *
+ * Verifies the normative `replay.md:246` requirement:
+ *
+ *   > If the source run still exists but the event range needed for
+ *   > `fromSeq` has expired, the host MUST reject the fork with
+ *   > `410 Gone` or `422 Unprocessable Entity` using the canonical
+ *   > error envelope. The error `details` SHOULD include `sourceRunId`,
+ *   > `fromSeq`, and the retention boundary when known.
+ *
+ * Forcing expiry is environmental (hosts don't standardize a force-
+ * expire endpoint — that's the same RFC 0009 Q#1 surface area). The
+ * scenario reads two operator-supplied env vars:
+ *
+ *   - `OPENWOP_TEST_EXPIRED_REPLAY_RUN_ID` — runId of a run whose
+ *     events past `fromSeq` are known-expired on the host under test.
+ *   - `OPENWOP_TEST_EXPIRED_REPLAY_FROM_SEQ` — the `fromSeq` to
+ *     fork against (defaults to 0; pre-expired ranges typically
+ *     start from the earliest event).
+ *
+ * When neither is supplied, the scenario asserts only that the
+ * `replay` capability advertisement is well-formed and that
+ * `retention` metadata (when present) types correctly. The
+ * 410/422 envelope assertion soft-skips.
+ *
+ * @see spec/v1/replay.md §"Retention and garbage collection"
+ * @see RFCS/0009-production-profile-conformance.md §C (parallel
+ *      retention-expiry pattern for run snapshots)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+
+interface ReplayRetentionCaps {
+  windowSeconds?: number;
+}
+
+interface ReplayCaps {
+  supported?: boolean;
+  modes?: string[];
+  retention?: ReplayRetentionCaps;
+}
+
+const PROFILE = 'openwop-replay-fork';
+
+async function readReplayCaps(): Promise<ReplayCaps | undefined> {
+  // Per existing replay-fork.test.ts convention: `replay` lives at the
+  // top level of the discovery body, not under capabilities.*.
+  const disco = await driver.get('/.well-known/openwop', { authenticated: false });
+  if (disco.status !== 200) return undefined;
+  return (disco.json as { replay?: ReplayCaps }).replay;
+}
+
+function isProfileAdvertised(replay: ReplayCaps | undefined): boolean {
+  return replay?.supported === true && Array.isArray(replay.modes) && replay.modes.length > 0;
+}
+
+describe('replay-retention-expiry: capability shape', () => {
+  it('host advertising replay surfaces well-formed retention metadata when present', async () => {
+    const replay = await readReplayCaps();
+
+    if (!behaviorGate(PROFILE, isProfileAdvertised(replay))) {
+      return;
+    }
+
+    expect(replay?.supported, driver.describe(
+      'replay.md §"Retention and garbage collection"',
+      'replay.supported MUST be true when the host claims the openwop-replay-fork profile',
+    )).toBe(true);
+
+    expect(
+      Array.isArray(replay?.modes) && (replay?.modes?.length ?? 0) > 0,
+      driver.describe(
+        'profiles.md §`openwop-replay-fork`',
+        'replay.modes MUST be a non-empty array',
+      ),
+    ).toBe(true);
+
+    // retention metadata is OPTIONAL per replay.md (the spec requires
+    // hosts document retention; it doesn't yet require advertising
+    // the window in discovery). When advertised, type strictly.
+    if (replay?.retention?.windowSeconds !== undefined) {
+      expect(
+        Number.isInteger(replay.retention.windowSeconds) &&
+          replay.retention.windowSeconds >= 0,
+        driver.describe(
+          'replay.md §"Retention and garbage collection"',
+          'replay.retention.windowSeconds MUST be a non-negative integer when advertised',
+        ),
+      ).toBe(true);
+    }
+  });
+});
+
+describe('replay-retention-expiry: 410/422 on expired-range fork', () => {
+  it('POST /v1/runs/{expiredRunId}:fork returns 410 or 422 with canonical envelope', async () => {
+    const replay = await readReplayCaps();
+
+    if (!behaviorGate(PROFILE, isProfileAdvertised(replay))) {
+      return;
+    }
+
+    const expiredRunId = process.env.OPENWOP_TEST_EXPIRED_REPLAY_RUN_ID;
+    if (!expiredRunId) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[replay-retention-expiry] OPENWOP_TEST_EXPIRED_REPLAY_RUN_ID not supplied; skipping envelope assertion (operator must produce a known-expired run id and pass it via env)',
+      );
+      return;
+    }
+
+    const fromSeqEnv = process.env.OPENWOP_TEST_EXPIRED_REPLAY_FROM_SEQ;
+    const fromSeq = fromSeqEnv ? Number.parseInt(fromSeqEnv, 10) : 0;
+    if (!Number.isFinite(fromSeq) || fromSeq < 0) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[replay-retention-expiry] OPENWOP_TEST_EXPIRED_REPLAY_FROM_SEQ=${String(fromSeqEnv)} is not a non-negative integer; skipping`,
+      );
+      return;
+    }
+
+    // Pick a mode the host advertises. Per replay.md the envelope
+    // assertion applies regardless of mode — replay and branch both
+    // depend on the source event log past fromSeq.
+    const mode = replay?.modes?.[0] ?? 'replay';
+
+    const res = await driver.post(
+      `/v1/runs/${encodeURIComponent(expiredRunId)}:fork`,
+      { mode, fromSeq },
+    );
+
+    expect(
+      res.status === 410 || res.status === 422,
+      driver.describe(
+        'replay.md §"Retention and garbage collection"',
+        'fork against expired event range MUST return 410 Gone or 422 Unprocessable Entity',
+      ),
+    ).toBe(true);
+
+    const body = res.json as {
+      error?: string;
+      message?: string;
+      details?: {
+        sourceRunId?: string;
+        fromSeq?: number;
+        retentionBoundary?: string | number;
+      };
+    };
+
+    expect(typeof body.error, driver.describe(
+      'replay.md §"Retention and garbage collection"',
+      'expired-fork response MUST use the canonical error envelope ({error, message, details?})',
+    )).toBe('string');
+    expect((body.error ?? '').length).toBeGreaterThan(0);
+
+    expect(typeof body.message).toBe('string');
+    expect((body.message ?? '').length).toBeGreaterThan(0);
+
+    // details.{sourceRunId, fromSeq, retentionBoundary} are SHOULD —
+    // soft-check when present, MUST NOT mismatch when present.
+    if (body.details?.sourceRunId !== undefined) {
+      expect(body.details.sourceRunId, driver.describe(
+        'replay.md §"Retention and garbage collection"',
+        'details.sourceRunId (when present) MUST match the runId in the request path',
+      )).toBe(expiredRunId);
+    }
+
+    if (body.details?.fromSeq !== undefined) {
+      expect(body.details.fromSeq, driver.describe(
+        'replay.md §"Retention and garbage collection"',
+        'details.fromSeq (when present) MUST match the fromSeq supplied in the request body',
+      )).toBe(fromSeq);
+    }
+  });
+});