@openwop/openwop-conformance 1.3.0 → 1.5.0

package/src/scenarios/aiEnvelope.universalKinds.test.ts

@@ -1,12 +1,12 @@
 /**
- * aiEnvelope.universalKinds — FINAL v1.1 advertisement-shape verification + behavioral placeholders.
+ * aiEnvelope.universalKinds — FINAL v1.1 advertisement-shape + behavioral.
  *
- * Status: DRAFT (advertisement-shape). `spec/v1/ai-envelope.md` landed
- * 2026-05-17 as DRAFT v1.x. This scenario asserts the advertisement shape
- * for hosts that opt into the new envelope-contracts surface
- * (`capabilities.envelopeContracts.advertised: true`) and keeps the deeper
- * behavioral assertions as `it.todo()` until a reference host wires the
- * accept path.
+ * Status: ACTIVE (advertisement-shape + behavioral). `spec/v1/ai-envelope.md`
+ * promoted Draft → FINAL v1.1 2026-05-18. Asserts the advertisement shape
+ * for hosts that opt into envelope-contracts
+ * (`capabilities.envelopeContracts.advertised: true`), plus live behavioral
+ * universal-kind acceptance through the `POST /v1/host/sample/envelope/accept`
+ * seam (soft-skip on HTTP 404).
  *
  * Summary: hosts MUST advertise the four universal kinds (`clarification.request`,
  * `schema.request`, `schema.response`, `error`) in `capabilities.supportedEnvelopes`

package/src/scenarios/blob-presign-expiry.test.ts

@@ -1,12 +1,12 @@
 /**
- * blob-presign-expiry — RFC 0019 advertisement-shape verification + behavioral placeholders.
+ * blob-presign-expiry — RFC 0019 advertisement-shape verification + behavioral roundtrip.
  *
- * Status: ACTIVE (advertisement-shape). RFC 0019 promoted to `Active`
- * 2026-05-17. The matching `capabilities.blobStorage` 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 0019 promoted to
+ * `Active` 2026-05-17. The matching `capabilities.blobStorage` 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: Presigned URLs MUST expire at the advertised TTL.
  *

package/src/scenarios/cache-ttl-expiry.test.ts

@@ -1,12 +1,12 @@
 /**
- * cache-ttl-expiry — RFC 0019 advertisement-shape verification + behavioral placeholders.
+ * cache-ttl-expiry — RFC 0019 advertisement-shape verification + behavioral roundtrip.
  *
- * Status: ACTIVE (advertisement-shape). RFC 0019 promoted to `Active`
- * 2026-05-17. The matching `capabilities.cache` block has landed in
+ * Status: ACTIVE (advertisement-shape + behavioral). RFC 0019 promoted to
+ * `Active` 2026-05-17. The matching `capabilities.cache` 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.
+ * 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: Cache TTL honored with at most 1-second drift.
  *

package/src/scenarios/cost-attribution.test.ts

@@ -17,10 +17,13 @@
  *      error envelope and skips trivially-pass when absent. When present,
  *      asserts the canary cost shape lands in `metrics.openwopCost` end-to-end.
  *
- * Two scenarios remain `it.todo` because they need observable-span
- * access — the conformance suite is black-box and can only see what the
- * REST + event-log surfaces expose. Hosts should cover runtime-side
- * enforcement in host-specific observability tests.
+ * Two runtime-side enforcement claims (raw-OTel-span allowlist + per-attribute
+ * type validation at emission) are intentionally out of scope here — the
+ * conformance suite is black-box and can only see what the REST + event-log
+ * surfaces expose. Hosts cover those enforcement paths in host-specific
+ * unit tests against their own observability module (the reference
+ * workflow-engine ships them alongside the implementation, separately from
+ * this black-box suite).
  *
  * Spec references:
  *   - https://github.com/openwop/openwop/blob/main/spec/v1/observability.md §"AI cost"
@@ -32,12 +35,36 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { getCollector, waitForRunSpans } from '../lib/otel-collector.js';
 
 const NOOP_WORKFLOW_ID = 'conformance-noop';
 const COST_EMIT_WORKFLOW_ID = 'openwop-smoke-cost-emit';
 const SKIP_NO_NOOP = !isFixtureAdvertised(NOOP_WORKFLOW_ID);
 const SKIP_NO_COST_EMIT = !isFixtureAdvertised(COST_EMIT_WORKFLOW_ID);
 
+/** Canonical attribute allowlist mirroring
+ *  `spec/v1/observability.md §"Cost attribution attributes"`. Kept
+ *  in-suite (not imported from the SDK) so the assertion is a
+ *  cross-host wire contract rather than a sanity check on the host's
+ *  own constant. Hosts SHOULD use `sanitizeCostAttributes` from
+ *  `@openwop/openwop` at emit time; the suite asserts against the
+ *  wire-side projection independently. */
+const OPENWOP_COST_ATTRIBUTE_NAMES: readonly string[] = [
+  'openwop.cost.tokens.input',
+  'openwop.cost.tokens.output',
+  'openwop.cost.tokens.total',
+  'openwop.cost.usd',
+  'openwop.cost.currency',
+  'openwop.cost.estimated',
+  'openwop.cost.provider',
+];
+
+/** BYOK / Bearer credential-shape detection — same families covered by
+ *  `aiEnvelope.redaction.test.ts` and the host-side ephemeralRunSecrets
+ *  scrubber. Lookarounds anchor to alphanumerics so credentials embedded
+ *  in snake_case / kebab-case neighbors still match. */
+const CREDENTIAL_SHAPE_RE = /(?<![A-Za-z0-9_])(?:sk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}|Bearer\s+[A-Za-z0-9._~+/=-]{20,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,})(?![A-Za-z0-9])|CANARY-openwop-CONFORMANCE-NEVER-SECRET[A-Za-z0-9_-]*/g;
+
 describe.skipIf(SKIP_NO_NOOP)('cost-attribution: metrics.openwopCost forward-compat shape (G6)', () => {
   it('on any run, IF metrics.openwopCost is present, its shape MUST match the spec', async () => {
     // Use the noop fixture so we don't depend on AI nodes. The fixture
@@ -196,12 +223,98 @@ describe.skipIf(SKIP_NO_COST_EMIT)('cost-attribution: end-to-end roundtrip via c
   });
 });
 
-describe('cost-attribution: G6 / O4 (still deferred — observable-span access required)', () => {
-  it.todo(
-    'the OTel span attribute set MUST NOT contain any key outside OPENWOP_COST_ATTRIBUTE_NAMES (redaction) — BLOCKED on observable-span access; runtime enforcement belongs in host-specific observability tests',
-  );
+describe.skipIf(SKIP_NO_COST_EMIT)('cost-attribution: G6 / O4 allowlist + redaction (live OTel spans)', () => {
+  // Drives the `openwop-smoke-cost-emit` fixture, which posts arbitrary
+  // `attrs` into `conformance.cost.emit` — a mix of (a) all 7
+  // allowlisted attribute names, (b) one non-allowlisted key
+  // (`openwop.cost.evil`), and (c) a credential-shaped canary under a
+  // non-allowlisted name. The host's `sanitizeCostForOtel` MUST drop
+  // (b) and (c) before they reach the active OTel span.
+  //
+  // Reads the live span via the in-suite OTel collector (setup boots it
+  // when `OPENWOP_OTEL_COLLECTOR=true`; the test soft-skips when the
+  // collector isn't available, matching `otel-emission.test.ts`).
+
+  it('only allowlisted openwop.cost.* attributes reach the OTel span (G6 close criteria — allowlist enforcement)', async () => {
+    if (!getCollector()) {
+      // eslint-disable-next-line no-console
+      console.warn('[cost-attribution] OTel collector not started; set OPENWOP_OTEL_COLLECTOR=true to run');
+      return;
+    }
+    const collector = getCollector()!;
+    collector.reset();
+
+    const create = await driver.post('/v1/runs', { workflowId: COST_EMIT_WORKFLOW_ID });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await pollUntilTerminal(runId, { timeoutMs: 15_000 });
+
+    const runSpans = await waitForRunSpans(runId, { timeoutMs: 5_000, minCount: 1 });
+    expect(runSpans.length, driver.describe(
+      'observability.md §"Span attributes"',
+      'host MUST emit at least one span for the cost-emit run',
+    )).toBeGreaterThan(0);
 
-  it.todo(
-    'credential-shaped fields in the upstream provider response MUST NOT appear in any OTel attribute or in metrics.openwopCost (regression test for G6 close-criteria allowlist enforcement) — BLOCKED on observable-span access; sanitizer-level redaction is unit-tested today',
-  );
+    // Inspect every span across the run for stray cost-namespace attrs.
+    // The fixture only emits on the `emit-cost` node's span, but the
+    // assertion is global: NO openwop.cost.* key may appear outside the
+    // allowlist on ANY span attributable to this run.
+    const ALLOWLIST = new Set(OPENWOP_COST_ATTRIBUTE_NAMES);
+    const stray: Array<{ span: string; key: string }> = [];
+    for (const span of runSpans) {
+      for (const key of span.attributes.keys()) {
+        if (key.startsWith('openwop.cost.') && !ALLOWLIST.has(key)) {
+          stray.push({ span: span.name, key });
+        }
+      }
+    }
+    expect(stray, driver.describe(
+      'observability.md §"Cost attribution attributes" (allowlist enforcement)',
+      'host MUST NOT emit any openwop.cost.* attribute outside OPENWOP_COST_ATTRIBUTE_NAMES; defense-in-depth against accidental leakage of upstream provider fields under unfamiliar key names',
+    )).toEqual([]);
+  });
+
+  it('credential-shaped canaries do NOT leak to any OTel attribute (G6 close criteria — redaction)', async () => {
+    if (!getCollector()) {
+      // eslint-disable-next-line no-console
+      console.warn('[cost-attribution] OTel collector not started; set OPENWOP_OTEL_COLLECTOR=true to run');
+      return;
+    }
+    const collector = getCollector()!;
+    collector.reset();
+
+    const create = await driver.post('/v1/runs', { workflowId: COST_EMIT_WORKFLOW_ID });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await pollUntilTerminal(runId, { timeoutMs: 15_000 });
+
+    const runSpans = await waitForRunSpans(runId, { timeoutMs: 5_000, minCount: 1 });
+
+    // Serialize EVERY span attribute value across the run and assert
+    // the canary marker is absent. The fixture deliberately ships the
+    // canary under a non-allowlisted key (`openwop.cost.leaked_token`)
+    // so the only way it appears in spans is if the sanitizer leaked.
+    const corpus = runSpans
+      .flatMap((span) => Array.from(span.attributes.values()))
+      .map((v) => (typeof v === 'string' ? v : JSON.stringify(v)))
+      .join('\n');
+
+    expect(
+      corpus.includes('CANARY-openwop-CONFORMANCE-NEVER-SECRET'),
+      driver.describe(
+        'SECURITY/invariants.yaml cost-attribution-allowlist-redaction',
+        'no canary plaintext substring may survive the allowlist sanitizer on its way to OTel spans',
+      ),
+    ).toBe(false);
+
+    // Belt-and-suspenders: also assert no BYOK-shape match anywhere in
+    // span attributes — catches credential-shaped values smuggled
+    // through non-canary keys that the allowlist still happens to let
+    // through (none today, but the regression test is cheap).
+    const byokMatches = corpus.match(CREDENTIAL_SHAPE_RE) ?? [];
+    expect(byokMatches, driver.describe(
+      'SECURITY/invariants.yaml cost-attribution-allowlist-redaction',
+      'no credential-shape substring may appear in cost-attribute span values',
+    )).toEqual([]);
+  });
 });

package/src/scenarios/cross-engine-append-ordering.test.ts

@@ -0,0 +1,99 @@
+/**
+ * cross-engine-append-ordering — RFC 0036 §B advertisement-shape + behavioral.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0036 promoted Draft → Active
+ * 2026-05-21. Capability-gated on `capabilities.eventLog.crossEngineOrdering.supported: true`.
+ * Hosts that don't advertise the capability soft-skip cleanly.
+ *
+ * Asserts (advertisement-shape — always-on when discovery is reachable):
+ *   1. capabilities.eventLog.crossEngineOrdering.supported MUST be boolean when present.
+ *   2. capabilities.eventLog.crossEngineOrdering.orderingModel MUST be one of
+ *      {lamport, vector-clock, global-sequencer} when present.
+ *   3. When supported: true, orderingModel MUST be present (otherwise the
+ *      claim has no operational meaning).
+ *
+ * Behavioral assertion (drives a two-engine fixture against the host's
+ * multi-engine simulator at apps/workflow-engine/.../multi-region-simulator.ts):
+ * concurrent appends from two engines to the same runId converge on a total
+ * order that both engines observe consistently on read. This assertion lands
+ * when the simulator harness is wired in a follow-up commit (per RFC 0036 §C);
+ * today's scenario soft-skips behavioral when the simulator env-gate
+ * (`OPENWOP_TEST_MULTI_ENGINE=true`) is unset.
+ *
+ * @see RFCS/0036-multi-region-and-cross-engine-guarantees.md §B
+ * @see schemas/capabilities.schema.json §capabilities.eventLog.crossEngineOrdering
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const ORDERING_MODELS = new Set(['lamport', 'vector-clock', 'global-sequencer']);
+
+interface DiscoveryDoc {
+  capabilities?: {
+    eventLog?: {
+      crossEngineOrdering?: {
+        supported?: unknown;
+        orderingModel?: 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)('cross-engine-append-ordering: advertisement shape (RFC 0036 §B)', () => {
+  it('capabilities.eventLog.crossEngineOrdering (when present) conforms to RFC 0036 §B', async () => {
+    const d = await readDiscovery();
+    if (d === null) return;
+    const ceo = d.capabilities?.eventLog?.crossEngineOrdering;
+    if (ceo === undefined) return; // host doesn't advertise — soft-skip
+
+    expect(
+      typeof ceo.supported,
+      driver.describe(
+        'RFCS/0036-multi-region-and-cross-engine-guarantees.md §B',
+        'capabilities.eventLog.crossEngineOrdering.supported MUST be boolean when present',
+      ),
+    ).toBe('boolean');
+
+    if (ceo.orderingModel !== undefined) {
+      expect(
+        ORDERING_MODELS.has(ceo.orderingModel as string),
+        driver.describe(
+          'RFCS/0036-multi-region-and-cross-engine-guarantees.md §B',
+          'orderingModel MUST be one of {lamport, vector-clock, global-sequencer}',
+        ),
+      ).toBe(true);
+    }
+
+    if (ceo.supported === true) {
+      expect(
+        ceo.orderingModel,
+        driver.describe(
+          'RFCS/0036-multi-region-and-cross-engine-guarantees.md §B',
+          'when supported: true, orderingModel MUST be present (the categorical claim has no operational meaning without an advertised mechanism)',
+        ),
+      ).toBeDefined();
+    }
+  });
+});
+
+// Behavioral assertion — drives a two-engine append + cross-engine read against
+// the host's multi-engine simulator. Lands when the simulator harness is wired
+// in a follow-up commit per RFC 0036 §C. Today the scenario soft-skips behavioral
+// when the simulator env-gate is unset; capability-gated advertisement-shape
+// probe above is the today-landable contract surface.
+//
+// Cross-host promotion path per RFCs/0001 §"Promotion to Accepted": once the
+// simulator lands + a host advertises + the behavioral assertion passes against
+// it, RFC 0036's cross-engine half graduates Active → Accepted.

package/src/scenarios/cross-host-ancestry-endpoint.test.ts

@@ -0,0 +1,136 @@
+/**
+ * cross-host-ancestry-endpoint — RFC 0040 §C `GET /v1/runs/{runId}/ancestry` behavioral.
+ *
+ * Status: ACTIVE (capability-gated behavioral). Gated on
+ * `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported: true`.
+ * Hosts that don't advertise the endpoint soft-skip; hosts that DO
+ * advertise MUST serve the endpoint with the documented response shape.
+ *
+ * Asserts:
+ *
+ *   1. Top-level run (no parent dispatch): `GET /v1/runs/{runId}/ancestry`
+ *      returns 200 with body `{runId, hostId, parent: null}`.
+ *
+ *   2. Response shape conforms to `schemas/run-ancestry-response.schema.json`:
+ *      `runId` matches the request path; `hostId` matches the host's
+ *      advertised `crossHostCausation.hostId`; `parent` is either null OR
+ *      an object with `{runId, hostId, cause}` required + optional
+ *      `wellKnownUrl` (present for cross-host parents).
+ *
+ *   3. (Behavioral, soft-skip if no cross-host fixture) Cross-host
+ *      parent: a run dispatched from a different host's MCP tool call OR
+ *      A2A message returns `parent.wellKnownUrl` set + `parent.cause` ∈
+ *      {mcp-tool-call, a2a-message}. Lands when a cross-host test
+ *      fixture ships.
+ *
+ *   4. Hosts that advertise `crossHostCausation.supported: true` but NOT
+ *      `ancestryEndpointSupported: true` MUST return 404 from the
+ *      endpoint (per spec/v1/multi-agent-execution.md §"GET /v1/runs/{runId}/ancestry").
+ *
+ * @see RFCS/0040-multi-agent-cross-host-causation.md §C
+ * @see spec/v1/multi-agent-execution.md §"GET /v1/runs/{runId}/ancestry endpoint"
+ * @see schemas/run-ancestry-response.schema.json
+ * @see api/openapi.yaml §getRunAncestry
+ */
+
+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?: {
+        crossHostCausation?: {
+          supported?: unknown;
+          hostId?: unknown;
+          ancestryEndpointSupported?: 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)('cross-host-ancestry-endpoint: behavioral (RFC 0040 §C)', () => {
+  it('hosts advertising ancestryEndpointSupported MUST serve GET /v1/runs/{runId}/ancestry with the documented shape on a top-level run', async (ctx) => {
+    const d = await readDiscovery();
+    const chc = d?.capabilities?.multiAgent?.executionModel?.crossHostCausation;
+    if (chc?.ancestryEndpointSupported !== true) {
+      ctx.skip();
+      return;
+    }
+
+    // Create a fresh top-level run via the host's conformance-dispatch-loop
+    // fixture (any always-on fixture works; the ancestry semantics don't
+    // depend on the specific workflow).
+    const create = await driver.post('/v1/runs', { workflowId: 'conformance-dispatch-loop' });
+    if (create.status !== 201) {
+      ctx.skip();
+      return;
+    }
+    const runId = (create.json as { runId: string }).runId;
+
+    const ancestryRes = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/ancestry`);
+    expect(ancestryRes.status, driver.describe(
+      'RFCS/0040-multi-agent-cross-host-causation.md §C',
+      'host advertising ancestryEndpointSupported MUST serve the endpoint (200) — 404 is non-conformant',
+    )).toBe(200);
+
+    const body = ancestryRes.json as { runId?: string; hostId?: string; parent?: unknown };
+    expect(body.runId, 'runId in response MUST match the request path').toBe(runId);
+    expect(
+      typeof body.hostId === 'string' && (body.hostId as string).length >= 1,
+      'hostId MUST be present + non-empty',
+    ).toBe(true);
+    if (chc.hostId !== undefined) {
+      expect(
+        body.hostId,
+        'hostId in response MUST equal the host\'s advertised crossHostCausation.hostId',
+      ).toBe(chc.hostId);
+    }
+
+    // Top-level run: parent is null.
+    expect(
+      body.parent,
+      driver.describe(
+        'RFCS/0040-multi-agent-cross-host-causation.md §C + schemas/run-ancestry-response.schema.json',
+        'a top-level run (not dispatched from any other run) MUST return parent: null',
+      ),
+    ).toBeNull();
+  });
+
+  it('hosts advertising crossHostCausation.supported but NOT ancestryEndpointSupported MUST return 404 from the ancestry endpoint', async (ctx) => {
+    const d = await readDiscovery();
+    const chc = d?.capabilities?.multiAgent?.executionModel?.crossHostCausation;
+    if (chc?.supported !== true) {
+      ctx.skip();
+      return;
+    }
+    if (chc.ancestryEndpointSupported === true) {
+      ctx.skip(); // covered by the test above
+      return;
+    }
+
+    // Use any runId — even a synthetic non-existent one. The endpoint should
+    // 404 regardless of run existence when the capability is not advertised.
+    const ancestryRes = await driver.get('/v1/runs/synthetic-test-run-id/ancestry');
+    expect(
+      ancestryRes.status,
+      driver.describe(
+        'spec/v1/multi-agent-execution.md §"GET /v1/runs/{runId}/ancestry endpoint"',
+        'hosts that advertise crossHostCausation.supported: true but NOT ancestryEndpointSupported MUST return 404 — the endpoint is opt-in even within Phase 3',
+      ),
+    ).toBe(404);
+  });
+});

package/src/scenarios/cross-host-causation-shape.test.ts

@@ -0,0 +1,117 @@
+/**
+ * cross-host-causation-shape — RFC 0040 advertisement-shape + payload-field shape.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0040 Phase 3 filed Draft
+ * 2026-05-22. Capability-gated on
+ * `capabilities.multiAgent.executionModel.crossHostCausation.supported: true`.
+ * Hosts that don't advertise soft-skip cleanly.
+ *
+ * Asserts (advertisement-shape — always-on when discovery is reachable):
+ *
+ *   1. capabilities.multiAgent.executionModel.crossHostCausation.supported
+ *      MUST be boolean when present.
+ *   2. When crossHostCausation.supported: true, hostId MUST be present + non-empty.
+ *   3. ancestryEndpointSupported (when present) MUST be boolean.
+ *   4. When crossHostCausation.supported: true, the host's executionModel.version
+ *      MUST be >= 3 (Phase 3 requires the multi-agent execution model framework).
+ *
+ * Behavioral assertion (payload-field shape, soft-skipped when no host
+ * emits cross-host events): cross-host event payloads carry
+ * `causationHostId` matching the originating host's hostId. Lands when
+ * a cross-host composition test fixture ships.
+ *
+ * @see RFCS/0040-multi-agent-cross-host-causation.md
+ * @see spec/v1/multi-agent-execution.md §"Cross-host causation (RFC 0040 Phase 3, normative)"
+ * @see schemas/capabilities.schema.json §multiAgent.executionModel.crossHostCausation
+ */
+
+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;
+        crossHostCausation?: {
+          supported?: unknown;
+          hostId?: unknown;
+          ancestryEndpointSupported?: 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)('cross-host-causation-shape: advertisement shape (RFC 0040 §D)', () => {
+  it('crossHostCausation (when present) conforms to RFC 0040 §D', async (ctx) => {
+    const d = await readDiscovery();
+    if (d === null) {
+      ctx.skip();
+      return;
+    }
+    const chc = d.capabilities?.multiAgent?.executionModel?.crossHostCausation;
+    if (chc === undefined) {
+      ctx.skip(); // host doesn't advertise — soft-skip
+      return;
+    }
+
+    expect(
+      typeof chc.supported,
+      driver.describe(
+        'RFCS/0040-multi-agent-cross-host-causation.md §D',
+        'crossHostCausation.supported MUST be boolean when present',
+      ),
+    ).toBe('boolean');
+
+    if (chc.supported === true) {
+      const version = d.capabilities?.multiAgent?.executionModel?.version as number | undefined;
+      expect(
+        typeof version === 'number' && version >= 3,
+        driver.describe(
+          'RFCS/0040-multi-agent-cross-host-causation.md §D',
+          'when crossHostCausation.supported: true, multiAgent.executionModel.version MUST be >= 3',
+        ),
+      ).toBe(true);
+
+      expect(
+        typeof chc.hostId === 'string' && (chc.hostId as string).length >= 1,
+        driver.describe(
+          'RFCS/0040-multi-agent-cross-host-causation.md §D',
+          'when crossHostCausation.supported: true, hostId MUST be present + non-empty',
+        ),
+      ).toBe(true);
+    }
+
+    if (chc.ancestryEndpointSupported !== undefined) {
+      expect(
+        typeof chc.ancestryEndpointSupported,
+        driver.describe(
+          'RFCS/0040-multi-agent-cross-host-causation.md §D',
+          'ancestryEndpointSupported MUST be boolean when present',
+        ),
+      ).toBe('boolean');
+    }
+  });
+});
+
+// Behavioral payload-field assertion lands when a cross-host composition test
+// fixture ships. Expected: a `core.workflowChain.event` (or any payload type
+// listed in spec/v1/multi-agent-execution.md §"causationHostId payload field")
+// emitted in response to a cross-host invocation carries `causationHostId`
+// equal to the originating host's advertised hostId. Today's reference
+// workflow-engine sample doesn't have a cross-host fixture; the assertion
+// soft-skips on hosts that don't emit cross-host events.

package/src/scenarios/cross-host-traceparent-propagation.test.ts

@@ -0,0 +1,60 @@
+/**
+ * cross-host-traceparent-propagation — RFC 0040 §B behavioral (capability-gated).
+ *
+ * Status: ACTIVE (capability-gated; behavioral assertion soft-skipped
+ * until a cross-host MCP/A2A composition test fixture ships). Gated on
+ * `capabilities.multiAgent.executionModel.version >= 3` AND
+ * `capabilities.multiAgent.executionModel.crossHostCausation.supported: true`.
+ *
+ * Asserts (when host advertises Phase 3 + a real MCP/A2A composition
+ * endpoint is reachable):
+ *
+ *   1. An outbound MCP tool call dispatched from a Phase 3 host MUST
+ *      carry the parent run's W3C `traceparent` header. The MCP server
+ *      receives the header AND uses it as the parent trace for any
+ *      spans it emits (closing the cross-host span linkage that
+ *      RFC 0023's same-host coverage left open).
+ *
+ *   2. An inbound MCP tool reply OR A2A message handler MUST adopt the
+ *      `traceparent` header from the inbound envelope as the trace
+ *      parent for any subsequent events the receiving agent emits.
+ *
+ *   3. (Symmetric) Outbound A2A messages MUST carry the parent run's
+ *      `traceparent`; inbound A2A handlers MUST adopt it.
+ *
+ * Behavioral wiring requires a cross-host test harness: either a real
+ * MCP server peer (`OPENWOP_MCP_REAL_SERVER_URL`) or an A2A peer
+ * (`OPENWOP_A2A_REAL_PEER_URL`) the host can call into. Without those,
+ * the assertion soft-skips and only the shape probe in
+ * cross-host-causation-shape.test.ts applies.
+ *
+ * @see RFCS/0040-multi-agent-cross-host-causation.md §B
+ * @see spec/v1/multi-agent-execution.md §"W3C tracecontext across MCP + A2A composition"
+ * @see RFCS/0023-conformance-agent-event-emitters.md (the same-host predecessor)
+ */
+
+import { describe, it } from 'vitest';
+
+// Behavioral assertions in this file are currently `it.todo` placeholders;
+// the cross-host MCP / A2A peer harness (gated on OPENWOP_MCP_REAL_SERVER_URL
+// / OPENWOP_A2A_REAL_PEER_URL) hasn't landed yet. When it does, the
+// `it.todo` calls flip back to runnable `it(...)` bodies that read discovery
+// (via `driver.get('/.well-known/openwop')`), gate on `Phase 3` advertisement,
+// and drive the workflow through the configured real peer.
+
+describe('cross-host-traceparent-propagation: behavioral (RFC 0040 §B)', () => {
+  // Behavioral assertion drives a workflow that calls an MCP tool via the
+  // host's `core.mcp.toolCall` node. The MCP peer (configured via
+  // OPENWOP_MCP_REAL_SERVER_URL) records inbound headers; the test reads
+  // the recorded headers and asserts `traceparent` is present + matches
+  // the format `00-{traceId}-{spanId}-{flags}` per W3C tracecontext.
+  // Until the peer harness lands, the assertion is surfaced as `todo` so
+  // test reporters track the gap rather than reporting a vacuous PASS.
+  it.todo('Phase 3 host MUST inject parent run\'s traceparent into outbound MCP requests');
+
+  // Behavioral assertion drives a workflow that dispatches an A2A message
+  // via the host's `core.a2a.send` (or equivalent) node. The A2A peer
+  // (configured via OPENWOP_A2A_REAL_PEER_URL) records inbound headers;
+  // the test asserts `traceparent` is present + well-formed.
+  it.todo('Phase 3 host MUST inject parent run\'s traceparent into outbound A2A messages');
+});