@openwop/openwop-conformance 1.2.0 → 1.4.0

package/src/scenarios/provider-usage.test.ts

@@ -0,0 +1,185 @@
+/**
+ * RFC 0026 — `provider.usage` event conformance.
+ *
+ * Verifies the new optional event type added to `RunEventType` per RFC
+ * 0026. The event MUST fire after every LLM provider invocation,
+ * carrying per-call token counts + optional cost estimate. Three
+ * describe blocks:
+ *
+ *   1. Advertisement shape (`capabilities.providerUsage` block).
+ *   2. Schema round-trip (positive + negative fixtures).
+ *   3. Event presence + shape via the test-only emit seam +
+ *      event-log query seam (Thread E.1).
+ *
+ * Each describe block soft-skips when the host doesn't expose the
+ * relevant seam OR the matching capability isn't advertised.
+ *
+ * @see RFCS/0026-provider-usage-event.md
+ * @see schemas/run-event-payloads.schema.json#/$defs/providerUsage
+ * @see SECURITY/invariants.yaml#provider-usage-no-credential-leak
+ */
+
+import { describe, it, expect } from 'vitest';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driver } from '../lib/driver.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { queryTestEvents, isEventLogSeamAvailable, resetTestSeam } from '../lib/event-log-query.js';
+
+interface DiscoveryDoc {
+  capabilities?: {
+    providerUsage?: { supported?: boolean; costEstimates?: boolean; currency?: string };
+  };
+}
+
+async function readProviderUsageCap(): Promise<{ supported?: boolean; costEstimates?: boolean; currency?: string } | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const cap = body?.capabilities?.providerUsage;
+  return cap && typeof cap === 'object' ? cap : null;
+}
+
+describe('provider-usage: capability advertisement (RFC 0026 §E)', () => {
+  it('capabilities.providerUsage is either absent or a well-formed object', async () => {
+    const cap = await readProviderUsageCap();
+    if (cap === null) return; // host doesn't advertise — skip
+    expect(
+      typeof cap.supported,
+      driver.describe('RFC 0026 §E', 'capabilities.providerUsage.supported MUST be a boolean when the block is present'),
+    ).toBe('boolean');
+    if (cap.costEstimates !== undefined) {
+      expect(
+        typeof cap.costEstimates,
+        driver.describe('RFC 0026 §E', 'capabilities.providerUsage.costEstimates MUST be a boolean when present'),
+      ).toBe('boolean');
+    }
+    if (cap.currency !== undefined) {
+      expect(
+        /^[A-Z]{3}$/.test(cap.currency),
+        driver.describe('RFC 0026 §E', 'capabilities.providerUsage.currency MUST be a 3-letter uppercase ISO 4217 code when present'),
+      ).toBe(true);
+    }
+  });
+});
+
+describe('provider-usage: schema round-trip (RFC 0026 §A)', () => {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  // Load full payloads schema so internal $refs resolve.
+  const payloadsDoc = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'run-event-payloads.schema.json'), 'utf8')) as Record<string, unknown>;
+  const providerUsageDef = (payloadsDoc.$defs as Record<string, unknown>).providerUsage as Record<string, unknown>;
+  const validate = ajv.compile(providerUsageDef);
+
+  it('positive fixture validates', () => {
+    const ok = validate({
+      provider: 'anthropic',
+      model: 'claude-3-5-sonnet-20240620',
+      inputTokens: 145,
+      outputTokens: 312,
+      totalTokens: 457,
+      costEstimateUsd: 0.005115,
+      currency: 'USD',
+      cacheHit: false,
+      nodeId: 'chat-respond',
+    });
+    expect(ok, `positive fixture MUST validate; errors: ${JSON.stringify(validate.errors)}`).toBe(true);
+  });
+
+  it('negative fixture (missing required field) MUST be rejected', () => {
+    const ok = validate({
+      provider: 'anthropic',
+      model: 'claude-3-5-sonnet-20240620',
+      inputTokens: 100,
+      // outputTokens missing — required per §A
+    });
+    expect(
+      ok,
+      driver.describe('RFC 0026 §A', 'payload missing required `outputTokens` MUST fail schema validation'),
+    ).toBe(false);
+  });
+
+  it('negative fixture (additionalProperties — credentialRef leak) MUST be rejected', () => {
+    const ok = validate({
+      provider: 'anthropic',
+      model: 'claude-3-5-sonnet-20240620',
+      inputTokens: 100,
+      outputTokens: 50,
+      credentialRef: 'secret:tenant:byok-anthropic:v1', // banned — additionalProperties:false
+    });
+    expect(
+      ok,
+      driver.describe('RFC 0026 §D', 'additionalProperties:false MUST reject credentialRef-shaped fields per provider-usage-no-credential-leak'),
+    ).toBe(false);
+  });
+
+  it('negative fixture (non-integer token count) MUST be rejected', () => {
+    const ok = validate({
+      provider: 'openai',
+      model: 'gpt-4o',
+      inputTokens: 100.5, // non-integer
+      outputTokens: 50,
+    });
+    expect(ok, 'inputTokens MUST be integer per §A').toBe(false);
+  });
+});
+
+describe('provider-usage: event presence via emit-seam + event-log query (RFC 0026 §B)', () => {
+  it('emit-seam projects exactly one provider.usage event with required fields populated', async () => {
+    if (!(await isEventLogSeamAvailable())) return; // E.1 seam not exposed — soft-skip
+    const runId = `r-pu-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const correlationId = `${runId}:node-1:turn-0:pu-1`;
+    const payload = {
+      provider: 'anthropic',
+      model: 'claude-3-5-sonnet-20240620',
+      inputTokens: 200,
+      outputTokens: 80,
+      totalTokens: 280,
+      nodeId: 'node-1',
+    };
+    const emit = await driver.post('/v1/host/sample/test/emit-provider-usage', { runId, payload, correlationId, nodeId: 'node-1' });
+    if (emit.status === 404) return; // emit seam not exposed
+    expect(emit.status).toBe(200);
+
+    const events = await queryTestEvents(runId, { type: 'provider.usage' });
+    if (!events.ok) return;
+    expect(
+      events.events.length,
+      driver.describe('RFC 0026 §B', 'emit-seam MUST project exactly one provider.usage event'),
+    ).toBe(1);
+    const e = events.events[0]!;
+    expect(e.payload.provider).toBe('anthropic');
+    expect(e.payload.model).toBe('claude-3-5-sonnet-20240620');
+    expect(e.payload.inputTokens).toBe(200);
+    expect(e.payload.outputTokens).toBe(80);
+    expect(e.causationId).toBe(correlationId);
+    expect(e.nodeId).toBe('node-1');
+    await resetTestSeam();
+  });
+
+  it('emit-seam refuses payloads containing credentialRef-shaped content (provider-usage-no-credential-leak invariant)', async () => {
+    if (!(await isEventLogSeamAvailable())) return;
+    const runId = `r-pu-leak-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    // Inject a credentialRef-shaped field via a synthetic payload that
+    // contains 'secret:' in a string field. The seam's defense-in-depth
+    // check MUST refuse — even though the production emitter's schema
+    // validation would also catch this via additionalProperties:false.
+    const res = await driver.post('/v1/host/sample/test/emit-provider-usage', {
+      runId,
+      payload: {
+        provider: 'anthropic',
+        model: 'claude-3-5-sonnet-20240620',
+        inputTokens: 100,
+        outputTokens: 50,
+        nodeId: 'secret:tenant:byok-anthropic:v1', // banned content
+      },
+    });
+    if (res.status === 404) return;
+    expect(
+      res.status,
+      driver.describe('SECURITY/invariants.yaml provider-usage-no-credential-leak', 'payload with credentialRef-shaped content MUST be refused'),
+    ).toBe(400);
+    const body = res.json as { error?: { code?: string } };
+    expect(body.error?.code).toBe('provider_usage_credential_leak');
+    await resetTestSeam();
+  });
+});

package/src/scenarios/queue-ack-nack-dlq.test.ts

@@ -1,12 +1,12 @@
 /**
- * queue-ack-nack-dlq — RFC 0017 advertisement-shape verification + behavioral placeholders.
+ * queue-ack-nack-dlq — RFC 0017 advertisement-shape verification + behavioral roundtrip.
  *
- * Status: ACTIVE (advertisement-shape). RFC 0017 promoted to `Active`
- * 2026-05-17. The matching `capabilities.queueBus` block has landed in
- * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
- * shape against any host that boots the conformance suite, and keeps the
- * deeper behavioral assertions as `it.todo()` until a reference host wires
- * a test seam.
+ * Status: ACTIVE (advertisement-shape + behavioral). RFC 0017 promoted to
+ * `Active` 2026-05-17. The matching `capabilities.queueBus` block has
+ * landed in `schemas/capabilities.schema.json`. This scenario asserts the
+ * advertisement shape against any host that boots the conformance suite, and
+ * exercises the behavioral surface through the `/v1/host/sample/test/surface`
+ * seam (soft-skip with HTTP 404 on hosts that don't expose it).
  *
  * Summary: nack returns for redelivery; deadLetter routes to the configured DLQ.
  *
@@ -61,7 +61,61 @@ describe('queue-ack-nack-dlq: advertisement shape (RFC 0017)', () => {
   });
 });
 
-describe('queue-ack-nack-dlq: behavioral assertions (placeholders — need host test seam)', () => {
-  it.todo("nack(requeue=true) → message is redelivered on next consume");
-  it.todo("deadLetter → message appears on the configured DLQ");
+async function call(op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId: 'tenant-a', surface: 'queueBus', op, args });
+}
+
+describe('queue-ack-nack-dlq: behavioral (RFC 0017 §B point 2 — nack + DLQ)', () => {
+  it('nack(requeue=true) → message is redelivered on next consume with deliveryCount incremented', async () => {
+    const probe = await call('consume', { subject: '__probe__' });
+    if (probe.status === 404) return;
+    const subject = `q-nack-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await call('publish', { subject, payload: { v: 'redeliver-me' } });
+
+    const first = await call('consume', { subject });
+    const firstBody = first.json as { deliveryToken?: string; payload?: unknown; deliveryCount?: number };
+    expect(firstBody.deliveryCount).toBe(1);
+    const nackRes = await call('nack', { deliveryToken: firstBody.deliveryToken, requeue: true });
+    expect((nackRes.json as { requeued?: boolean }).requeued).toBe(true);
+
+    const second = await call('consume', { subject });
+    const secondBody = second.json as { found?: boolean; payload?: unknown; deliveryCount?: number };
+    expect(
+      secondBody.found,
+      driver.describe('RFC 0017 §B point 2', 'nack(requeue=true) MUST make the message available to next consume'),
+    ).toBe(true);
+    expect(secondBody.payload).toEqual(firstBody.payload);
+    expect(
+      secondBody.deliveryCount,
+      driver.describe('RFC 0017 §B point 2', 'redelivered message MUST have incremented deliveryCount'),
+    ).toBe(2);
+  });
+
+  it('deadLetter → message appears on the <subject>.dlq subject; original subject is empty', async () => {
+    const probe = await call('consume', { subject: '__probe__' });
+    if (probe.status === 404) return;
+    const subject = `q-dlq-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await call('publish', { subject, payload: { v: 'poison' } });
+
+    const consumed = await call('consume', { subject });
+    const deliveryToken = (consumed.json as { deliveryToken?: string }).deliveryToken;
+    const dlqRes = await call('deadLetter', { deliveryToken, reason: 'unparseable_payload' });
+    expect((dlqRes.json as { deadLettered?: boolean }).deadLettered).toBe(true);
+    const dlqSubject = (dlqRes.json as { dlqSubject?: string }).dlqSubject;
+    expect(dlqSubject).toBe(`${subject}.dlq`);
+
+    // Original subject MUST be empty now
+    const originalEmpty = await call('consume', { subject });
+    expect((originalEmpty.json as { found?: boolean }).found).toBe(false);
+
+    // DLQ MUST carry the message + the deadLetterReason
+    const dlqMsg = await call('consume', { subject: `${subject}.dlq` });
+    const dlqBody = dlqMsg.json as { found?: boolean; payload?: { original?: unknown; deadLetterReason?: string } };
+    expect(
+      dlqBody.found,
+      driver.describe('RFC 0017 §B point 2', 'deadLetter MUST route the message to the <subject>.dlq subject'),
+    ).toBe(true);
+    expect(dlqBody.payload?.deadLetterReason).toBe('unparseable_payload');
+    expect(dlqBody.payload?.original).toEqual({ v: 'poison' });
+  });
 });

package/src/scenarios/queue-publish-consume-roundtrip.test.ts

@@ -1,12 +1,12 @@
 /**
- * queue-publish-consume-roundtrip — RFC 0017 advertisement-shape verification + behavioral placeholders.
+ * queue-publish-consume-roundtrip — RFC 0017 advertisement-shape verification + behavioral roundtrip.
  *
- * Status: ACTIVE (advertisement-shape). RFC 0017 promoted to `Active`
- * 2026-05-17. The matching `capabilities.queueBus` block has landed in
- * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
- * shape against any host that boots the conformance suite, and keeps the
- * deeper behavioral assertions as `it.todo()` until a reference host wires
- * a test seam.
+ * Status: ACTIVE (advertisement-shape + behavioral). RFC 0017 promoted to
+ * `Active` 2026-05-17. The matching `capabilities.queueBus` block has
+ * landed in `schemas/capabilities.schema.json`. This scenario asserts the
+ * advertisement shape against any host that boots the conformance suite, and
+ * exercises the behavioral surface through the `/v1/host/sample/test/surface`
+ * seam (soft-skip with HTTP 404 on hosts that don't expose it).
  *
  * Summary: publish + consume + ack roundtrip.
  *
@@ -42,7 +42,47 @@ describe('queue-publish-consume-roundtrip: advertisement shape (RFC 0017)', () =
   });
 });
 
-describe('queue-publish-consume-roundtrip: behavioral assertions (placeholders — need host test seam)', () => {
-  it.todo("publish → consume returns the message with the right payload + headers");
-  it.todo("ack removes the message; subsequent consume returns not-found within timeout");
+async function call(op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId: 'tenant-a', surface: 'queueBus', op, args });
+}
+
+describe('queue-publish-consume-roundtrip: behavioral (RFC 0017 §B point 2)', () => {
+  it('publish → consume returns the same payload + subject', async () => {
+    const probe = await call('consume', { subject: '__probe__' });
+    if (probe.status === 404) return; // seam not exposed
+    const subject = `q-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const payload = { event: 'order.created', orderId: 42 };
+    const pub = await call('publish', { subject, payload });
+    expect(pub.status).toBe(200);
+
+    const got = await call('consume', { subject });
+    expect(got.status).toBe(200);
+    const body = got.json as { found?: boolean; subject?: string; payload?: unknown; deliveryToken?: string };
+    expect(body.found, 'consume MUST find the just-published message').toBe(true);
+    expect(body.subject).toBe(subject);
+    expect(
+      body.payload,
+      driver.describe('RFC 0017 §B point 2', 'consume MUST return the exact published payload'),
+    ).toEqual(payload);
+    expect(typeof body.deliveryToken, 'consume MUST return a deliveryToken for ack/nack').toBe('string');
+  });
+
+  it('ack removes the message; subsequent consume on empty queue returns found:false', async () => {
+    const probe = await call('consume', { subject: '__probe__' });
+    if (probe.status === 404) return;
+    const subject = `q-ack-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await call('publish', { subject, payload: { v: 1 } });
+    const got = await call('consume', { subject });
+    const deliveryToken = (got.json as { deliveryToken?: string }).deliveryToken;
+    const ackRes = await call('ack', { deliveryToken });
+    expect(ackRes.status).toBe(200);
+    expect((ackRes.json as { acked?: boolean }).acked).toBe(true);
+
+    const empty = await call('consume', { subject });
+    const emptyBody = empty.json as { found?: boolean };
+    expect(
+      emptyBody.found,
+      driver.describe('RFC 0017 §B point 2', 'consume after ack MUST surface as found:false'),
+    ).toBe(false);
+  });
 });

package/src/scenarios/replay-divergence-at-refusal.test.ts

@@ -0,0 +1,134 @@
+/**
+ * replay-divergence-at-refusal — RFC 0041 §B behavioral assertion.
+ *
+ * Status: ACTIVE (capability-gated behavioral; soft-skips when no Phase 4
+ * host advertises the contract). Gated on
+ * `capabilities.multiAgent.executionModel.version >= 4` AND
+ * `capabilities.multiAgent.executionModel.replayDeterminism.refusalDivergenceEmission: true`.
+ *
+ * Asserts (behavioral, when a Phase 4 host advertises both gates):
+ *
+ *   1. When the original run obtained a valid LLM envelope but the replay
+ *      gets a refusal, the host MUST emit a `replay.divergedAtRefusal`
+ *      event AND fail the replay with `error.code:
+ *      "replay_diverged_at_refusal"`. Silent substitution is non-conformant.
+ *
+ *   2. The emitted `replay.divergedAtRefusal` payload MUST carry
+ *      `originalEnvelopeKind: "valid"` + `replayEnvelopeKind: "refusal"`
+ *      (or the inverse for the original-refused case). The two MUST
+ *      differ — otherwise there is no divergence to report.
+ *
+ *   3. The error envelope MAY carry `details.atSequence`, `details.nodeId`,
+ *      `details.originalEnvelopeKind`, `details.replayEnvelopeKind` per
+ *      `spec/v1/rest-endpoints.md` §"Common error codes" — when present,
+ *      the values MUST be consistent with the emitted event.
+ *
+ * Driving the assertion requires a host-side test seam that can stage a
+ * mock provider returning a valid envelope on the original run and a
+ * refusal on the replay (or vice-versa). Reference workflow-engine ships
+ * a mock-AI provider (`OPENWOP_MULTI_AGENT_EXECUTION_MODEL=true`); the
+ * Phase 4 wiring extends it to honor a "refusal on replay" mode. Until
+ * that wiring lands, the assertion is surfaced as `it.todo` so test
+ * reporters track the gap rather than reporting a vacuous PASS.
+ *
+ * @see RFCS/0041-multi-agent-replay-under-nondeterminism.md §B
+ * @see spec/v1/replay.md §"Envelope-refusal recovery in replay (MAE-8 closure)"
+ * @see spec/v1/multi-agent-execution.md §"Phase 4 replay determinism"
+ * @see spec/v1/rest-endpoints.md §"Common error codes" — replay_diverged_at_refusal
+ * @see schemas/run-event-payloads.schema.json §replayDivergedAtRefusal
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+interface DiscoveryDoc {
+  capabilities?: {
+    multiAgent?: {
+      executionModel?: {
+        supported?: unknown;
+        version?: unknown;
+        replayDeterminism?: {
+          supported?: unknown;
+          refusalDivergenceEmission?: unknown;
+        };
+      };
+    };
+  };
+}
+
+async function readDiscovery(): Promise<DiscoveryDoc | null> {
+  try {
+    const res = await driver.get('/.well-known/openwop');
+    if (res.status !== 200) return null;
+    return res.json as DiscoveryDoc;
+  } catch { return null; }
+}
+
+describe.skipIf(HTTP_SKIP)('replay-divergence-at-refusal: advertisement shape (RFC 0041 §D)', () => {
+  it('replayDeterminism (when present) conforms to RFC 0041 §D', async (ctx) => {
+    const d = await readDiscovery();
+    if (d === null) {
+      ctx.skip();
+      return;
+    }
+    const rd = d.capabilities?.multiAgent?.executionModel?.replayDeterminism;
+    if (rd === undefined) {
+      ctx.skip(); // optional advertisement — host hasn't opted in
+      return;
+    }
+
+    expect(
+      typeof rd.supported,
+      driver.describe(
+        'RFCS/0041-multi-agent-replay-under-nondeterminism.md §D',
+        'replayDeterminism.supported MUST be boolean when present',
+      ),
+    ).toBe('boolean');
+
+    if (rd.supported === true) {
+      const version = d.capabilities?.multiAgent?.executionModel?.version as number | undefined;
+      expect(
+        typeof version === 'number' && version >= 4,
+        driver.describe(
+          'RFCS/0041-multi-agent-replay-under-nondeterminism.md §D',
+          'when replayDeterminism.supported: true, multiAgent.executionModel.version MUST be >= 4',
+        ),
+      ).toBe(true);
+
+      // Phase 4 hosts MUST commit to refusal-divergence emission per the
+      // schema description on capabilities.schema.json §replayDeterminism
+      // .refusalDivergenceEmission. The MUST is normative prose on the
+      // schema; JSON Schema can't express the conditional, so this
+      // assertion closes the conformance-enforcement gap.
+      expect(
+        rd.refusalDivergenceEmission,
+        driver.describe(
+          'schemas/capabilities.schema.json §replayDeterminism.refusalDivergenceEmission',
+          'hosts advertising version: 4 MUST set replayDeterminism.refusalDivergenceEmission to true',
+        ),
+      ).toBe(true);
+    }
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('replay-divergence-at-refusal: behavioral (RFC 0041 §B MAE-8)', () => {
+  // Behavioral assertion drives a workflow whose mock-AI provider returns a
+  // valid envelope on the original run + a refusal on the replay (or
+  // vice-versa via a second variant). The assertion sequence:
+  //   1. Stage mock provider: original returns valid envelope.
+  //   2. Run workflow `conformance-phase4-replay-divergence` end-to-end.
+  //   3. Re-stage mock provider: replay-of-this-runId returns refusal.
+  //   4. POST /v1/runs/{runId}:fork { mode: 'replay' }.
+  //   5. Assert the resulting run terminates with
+  //        error.code === 'replay_diverged_at_refusal'.
+  //   6. Assert event log contains a `replay.divergedAtRefusal` event with
+  //        originalEnvelopeKind === 'valid' AND replayEnvelopeKind === 'refusal'.
+  //   7. Assert NO silent substitution: the replay's continuation past the
+  //      diverging node MUST NOT execute (run terminates at the divergence).
+  // Until the reference host wires the staged-refusal seam, surfaced as
+  // `todo` so test reporters track the gap.
+  it.todo('Phase 4 host MUST emit replay.divergedAtRefusal + fail with replay_diverged_at_refusal when original=valid + replay=refusal');
+  it.todo('Phase 4 host MUST emit replay.divergedAtRefusal + fail with replay_diverged_at_refusal when original=refusal + replay=valid (symmetric case)');
+});

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

@@ -0,0 +1,197 @@
+/**
+ * replay-llm-cache-key-portable — RFC 0041 §E SECURITY-invariant probe.
+ *
+ * Status: ACTIVE (capability-gated behavioral). Gated on
+ * `capabilities.multiAgent.executionModel.version >= 4` AND
+ * `capabilities.multiAgent.executionModel.replayDeterminism.llmCacheKeyRecipe: "spec-rfc-0041"`.
+ *
+ * The CROSS-host parity assertion in `replay-llm-cache-key.test.ts §D`
+ * (gated on `OPENWOP_BASE_URL_B`) is the cross-instance probe. This file
+ * is the SECURITY-tier complement: it asserts that the SINGLE-host
+ * recipe is portable in the strict sense — given the recipe input, the
+ * host's emitted key is reproducible offline from the recipe alone
+ * (no host-internal secrets, sequence numbers, or trace context
+ * influence the key).
+ *
+ * Asserts:
+ *
+ *   1. Two probes with byte-identical recipe input MUST yield the same
+ *      cache key (intra-host determinism; subsumes the SECURITY
+ *      portability requirement at the single-host boundary).
+ *
+ *   2. The emitted key is reproducible offline: locally recomputed
+ *      SHA-256-over-RFC-8785-JCS over the canonical recipe MUST equal
+ *      the host's emission. This is the load-bearing claim — without
+ *      it, the recipe is private host state masquerading as a content-
+ *      addressable hash.
+ *
+ *   3. (Negative) Permuting any non-recipe field (`max_tokens`, `stop`,
+ *      `stream`, `seed`, `metadata`, `user`, request IDs, trace context)
+ *      MUST NOT shift the key. This is the security boundary: hosts
+ *      that mix non-recipe state into the key leak that state across
+ *      the cache boundary, defeating the portability claim and (via
+ *      the SR-1 sibling invariant) potentially leaking BYOK plaintexts
+ *      through the cache.
+ *
+ *   4. (Gated on Phase 4 advertisement.) The host's discovery doc MUST
+ *      advertise `replayDeterminism.llmCacheKeyRecipe` matching the
+ *      recipe it honors — `spec-rfc-0041` for the canonical recipe,
+ *      `x-host-<host>-<recipe-name>` for vendor variants per
+ *      `host-extensions.md` §"Canonical prefixes".
+ *
+ * The behavioral assertions reuse the existing test seam at
+ * `POST /v1/host/sample/test/llm-cache-key` (the same seam the sibling
+ * `replay-llm-cache-key.test.ts` drives). Hosts that don't expose the
+ * seam return 404 and the scenario soft-skips.
+ *
+ * @see RFCS/0041-multi-agent-replay-under-nondeterminism.md §E
+ * @see SECURITY/invariants.yaml §replay-llm-cache-key-portable
+ * @see spec/v1/replay.md §"LLM cache-key recipe" §A + §B + §D
+ * @see conformance/src/scenarios/replay-llm-cache-key.test.ts (the sibling behavioral suite)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { expectedCacheKey, callCacheKeySeam as callSeam } from '../lib/llm-cache-key-recipe.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+interface DiscoveryDoc {
+  capabilities?: {
+    multiAgent?: {
+      executionModel?: {
+        version?: unknown;
+        replayDeterminism?: {
+          supported?: unknown;
+          llmCacheKeyRecipe?: unknown;
+        };
+      };
+    };
+  };
+}
+
+async function readDiscovery(): Promise<DiscoveryDoc | null> {
+  try {
+    const res = await driver.get('/.well-known/openwop');
+    if (res.status !== 200) return null;
+    return res.json as DiscoveryDoc;
+  } catch { return null; }
+}
+
+describe.skipIf(HTTP_SKIP)('replay-llm-cache-key-portable: intra-host reproducibility (RFC 0041 §E)', () => {
+  it('host cache key MUST equal locally-recomputed SHA-256 over canonical JSON (reproducible offline)', async (ctx) => {
+    const input = {
+      provider: 'anthropic',
+      model: 'claude-3-5-sonnet-20240620',
+      messages: [
+        { role: 'system' as const, content: 'portability probe' },
+        { role: 'user' as const, content: 'reproduce offline' },
+      ],
+      temperature: 0.3,
+    };
+    const result = await callSeam(input);
+    if (result.status === 404) {
+      ctx.skip(); // host doesn't expose the test seam
+      return;
+    }
+    expect(result.status).toBe(200);
+    expect(
+      result.cacheKey,
+      driver.describe(
+        'SECURITY/invariants.yaml §replay-llm-cache-key-portable + replay.md §B',
+        'host cache key MUST be reproducible offline from the recipe alone — no host-internal state',
+      ),
+    ).toBe(expectedCacheKey(input));
+  });
+
+  it('two identical probes MUST yield byte-identical keys (intra-host determinism)', async (ctx) => {
+    const input = {
+      provider: 'openai',
+      model: 'gpt-4',
+      messages: [{ role: 'user' as const, content: 'idempotence probe' }],
+      temperature: 0.0,
+    };
+    const a = await callSeam(input);
+    if (a.status === 404) {
+      ctx.skip(); // host doesn't expose the test seam
+      return;
+    }
+    const b = await callSeam(input);
+    expect(
+      a.cacheKey,
+      driver.describe(
+        'SECURITY/invariants.yaml §replay-llm-cache-key-portable',
+        'two byte-identical recipe inputs MUST yield byte-identical keys (no per-request entropy)',
+      ),
+    ).toBe(b.cacheKey);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('replay-llm-cache-key-portable: non-recipe-field invariance (RFC 0041 §E security boundary)', () => {
+  it('non-recipe fields (request ID, trace context, tenant ID) MUST NOT influence the cache key', async (ctx) => {
+    const base = {
+      provider: 'openai',
+      model: 'gpt-4',
+      messages: [{ role: 'user' as const, content: 'security-boundary probe' }],
+      temperature: 0.5,
+    };
+    const baseResult = await callSeam(base);
+    if (baseResult.status === 404) {
+      ctx.skip(); // host doesn't expose the test seam
+      return;
+    }
+
+    // The security boundary: ANY of these fields leaking into the key
+    // would expose tenant/request state through cache-collision behavior.
+    const polluted = {
+      ...base,
+      max_tokens: 1000,
+      stop: ['STOP'],
+      stream: true,
+      seed: 42,
+      metadata: { tenantId: 'tenant-A', traceparent: '00-deadbeef-cafe-01' },
+      user: 'user-42',
+      'x-request-id': 'req-abc-123',
+    };
+    const pollutedResult = await callSeam(polluted);
+    expect(
+      pollutedResult.cacheKey,
+      driver.describe(
+        'SECURITY/invariants.yaml §replay-llm-cache-key-portable + replay.md §A',
+        'non-recipe fields (request id, trace context, tenant id) MUST NOT influence the cache key — leaking them defeats the portability invariant',
+      ),
+    ).toBe(baseResult.cacheKey);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('replay-llm-cache-key-portable: Phase 4 advertisement alignment (RFC 0041 §D)', () => {
+  it('hosts advertising version: 4 MUST advertise replayDeterminism.llmCacheKeyRecipe', async (ctx) => {
+    const d = await readDiscovery();
+    const em = d?.capabilities?.multiAgent?.executionModel;
+    const version = em?.version;
+    if (typeof version !== 'number' || version < 4) {
+      ctx.skip(); // pre-Phase-4 or no multiAgent advertisement
+      return;
+    }
+
+    const recipe = em?.replayDeterminism?.llmCacheKeyRecipe;
+    expect(
+      typeof recipe === 'string',
+      driver.describe(
+        'RFCS/0041-multi-agent-replay-under-nondeterminism.md §D',
+        'Phase 4 host MUST advertise replayDeterminism.llmCacheKeyRecipe (`spec-rfc-0041` or `x-host-<host>-<recipe>`)',
+      ),
+    ).toBe(true);
+
+    const r = recipe as string;
+    const canonical = r === 'spec-rfc-0041';
+    const vendor = /^x-host-[a-z][a-z0-9-]*-[a-z][a-z0-9-]*$/.test(r);
+    expect(
+      canonical || vendor,
+      driver.describe(
+        'schemas/capabilities.schema.json §replayDeterminism.llmCacheKeyRecipe',
+        'llmCacheKeyRecipe MUST be `spec-rfc-0041` OR match `^x-host-<host>-<recipe>$` per host-extensions.md',
+      ),
+    ).toBe(true);
+  });
+});