@openwop/openwop-conformance 1.2.0 → 1.4.0

package/src/scenarios/agentReasoningStreaming.test.ts

@@ -0,0 +1,193 @@
+/**
+ * RFC 0024 — streaming `agent.reasoning.delta` events.
+ *
+ * Verifies that hosts advertising `capabilities.agents.reasoning.streaming: true`
+ * emit incremental `agent.reasoning.delta` events while a reasoning
+ * block is still open, followed by exactly one closing `agent.reasoned`
+ * event carrying the full authoritative content.
+ *
+ * Capability-gated: skips when the host doesn't advertise
+ * `capabilities.agents.supported: true` AND
+ * `capabilities.agents.reasoning.streaming: true`, OR when reasoning
+ * verbosity is `'off'`.
+ *
+ * Driven by the `core.conformance.mock-agent` typeId (RFC 0023)
+ * extended with `mockReasoning.streamChunks` per RFC 0024 §"Conformance"
+ * (see `schemas/core-conformance-mock-agent-config.schema.json`).
+ *
+ * @see RFCS/0024-agent-reasoning-streaming.md
+ * @see schemas/run-event-payloads.schema.json §`agentReasoningDelta`
+ * @see schemas/capabilities.schema.json §`agents.reasoning.streaming`
+ */
+
+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 {
+  isAgentSupported,
+  isReasoningStreamingSupported,
+  getReasoningVerbosity,
+} from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-agent-reasoning-streaming';
+/** Expected concatenation of the fixture's `streamChunks` — kept in sync
+ *  with `conformance/fixtures/conformance-agent-reasoning-streaming.json`.
+ *  When the fixture changes, this constant changes with it. */
+const EXPECTED_CHUNKS = [
+  'Let me think about this. ',
+  'First, the user is asking a question. ',
+  'Therefore, I should respond clearly.',
+] as const;
+const EXPECTED_FULL = EXPECTED_CHUNKS.join('');
+
+const SKIP =
+  !isAgentSupported() ||
+  !isReasoningStreamingSupported() ||
+  getReasoningVerbosity() === 'off' ||
+  !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('agentReasoningStreaming: RFC 0024 incremental + closing event contract', () => {
+  it('emits N agent.reasoning.delta events followed by exactly one closing agent.reasoned', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId);
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    expect(events.status).toBe(200);
+    const list = (events.json as { events: Array<{ type: string; payload?: Record<string, unknown> }> }).events;
+
+    const deltas = list.filter((e) => e.type === 'agent.reasoning.delta');
+    const finals = list.filter((e) => e.type === 'agent.reasoned');
+
+    expect(
+      deltas.length,
+      driver.describe(
+        'RFCS/0024-agent-reasoning-streaming.md §Proposal',
+        'streaming host MUST emit one agent.reasoning.delta per streamChunks entry',
+      ),
+    ).toBe(EXPECTED_CHUNKS.length);
+    expect(
+      finals.length,
+      driver.describe(
+        'RFCS/0024-agent-reasoning-streaming.md §Proposal',
+        'streaming host MUST emit exactly one closing agent.reasoned event after the deltas',
+      ),
+    ).toBe(1);
+  });
+
+  it('agent.reasoning.delta `sequence` starts at 0 and increments by 1 within the block', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId);
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    const list = (events.json as { events: Array<{ type: string; payload?: Record<string, unknown> }> }).events;
+
+    const deltas = list.filter((e) => e.type === 'agent.reasoning.delta');
+    const sequences = deltas
+      .map((e) => e.payload?.sequence)
+      .filter((s): s is number => typeof s === 'number');
+
+    expect(
+      sequences,
+      driver.describe(
+        'RFCS/0024-agent-reasoning-streaming.md §Proposal',
+        '`sequence` MUST start at 0 and increment by 1 per delta within a block',
+      ),
+    ).toEqual(EXPECTED_CHUNKS.map((_, i) => i));
+  });
+
+  it('closing agent.reasoned.reasoning is the concatenation of the deltas (authoritative)', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId);
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    const list = (events.json as { events: Array<{ type: string; payload?: Record<string, unknown> }> }).events;
+
+    const finalEvent = list.find((e) => e.type === 'agent.reasoned');
+    expect(finalEvent, 'closing agent.reasoned must be present').toBeDefined();
+    const reasoning = finalEvent?.payload?.reasoning;
+    expect(typeof reasoning, 'closing event MUST carry a reasoning string').toBe('string');
+    // The mock-agent's contract: closing reasoning equals concat(streamChunks).
+    // Real hosts MAY transform at finalize (summary truncation, redaction);
+    // for the mock-agent fixture, no transform applies — exact equality.
+    expect(
+      reasoning,
+      driver.describe(
+        'RFCS/0024-agent-reasoning-streaming.md §Proposal',
+        'closing agent.reasoned.reasoning is authoritative; for the mock-agent fixture, equals delta concatenation',
+      ),
+    ).toBe(EXPECTED_FULL);
+  });
+
+  it('agentId is consistent across all streaming + closing events in a block', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId);
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    const list = (events.json as { events: Array<{ type: string; payload?: Record<string, unknown> }> }).events;
+
+    const relevant = list.filter(
+      (e) => e.type === 'agent.reasoning.delta' || e.type === 'agent.reasoned',
+    );
+    const agentIds = new Set(
+      relevant
+        .map((e) => e.payload?.agentId)
+        .filter((a): a is string => typeof a === 'string' && a.length > 0),
+    );
+
+    expect(
+      agentIds.size,
+      driver.describe(
+        'RFCS/0024-agent-reasoning-streaming.md §Proposal',
+        'agentId MUST be consistent across all `agent.reasoning.delta` events AND the closing `agent.reasoned` for a given block',
+      ),
+    ).toBe(1);
+  });
+
+  it('all agent.reasoning.delta events arrive BEFORE the closing agent.reasoned', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId);
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    const list = (events.json as Array<{ type: string }> | { events: Array<{ type: string }> });
+    const arr = Array.isArray(list) ? list : list.events;
+
+    const closingIdx = arr.findIndex((e) => e.type === 'agent.reasoned');
+    expect(closingIdx, 'closing event present').toBeGreaterThan(-1);
+    const lastDeltaIdx = arr.map((e) => e.type).lastIndexOf('agent.reasoning.delta');
+
+    // Guard against vacuous pass: a host advertising streaming but
+    // emitting ZERO deltas would otherwise pass `-1 < closingIdx`
+    // trivially. The fixture configures 3 streamChunks, so at least
+    // one delta MUST appear in the event log.
+    expect(
+      lastDeltaIdx,
+      driver.describe(
+        'RFCS/0024-agent-reasoning-streaming.md §Proposal',
+        'streaming host MUST emit at least one `agent.reasoning.delta` for a fixture with non-empty `streamChunks`',
+      ),
+    ).toBeGreaterThan(-1);
+    expect(
+      lastDeltaIdx,
+      driver.describe(
+        'RFCS/0024-agent-reasoning-streaming.md §Proposal',
+        'every `agent.reasoning.delta` MUST precede the closing `agent.reasoned` for the same block',
+      ),
+    ).toBeLessThan(closingIdx);
+  });
+});

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

@@ -161,13 +161,101 @@ describe('aiEnvelope.capBreached: behavioral cap enforcement (FINAL v1.1)', () =
   });
 });
 
-describe('aiEnvelope.capBreached: engine-integration placeholders', () => {
-  // These require the engine to project `breached` outcomes onto the
-  // existing `cap.breached` event surface per
-  // capabilities.md §"Engine-enforced limits and the cap.breached event".
-  // The pure-function acceptor surfaces the `breached` outcome with
-  // capKind; the engine projects it to the event log.
-  it.todo('project breached outcome onto cap.breached { kind: "envelopes" } event');
-  it.todo('cap.breached payload includes limit, observed, and (for node-scoped kinds) nodeId per capabilities.md');
-  it.todo('cap.breached → node.failed terminal transition');
+// E.1 engine-projection via the test-only event-log seam. The acceptor
+// returns the breached outcome; the seam projects it onto cap.breached +
+// node.failed per capabilities.md §"Engine-enforced limits". Tests
+// soft-skip on HTTP 404 when the seam isn't exposed.
+import { queryTestEvents, isEventLogSeamAvailable, resetTestSeam } from '../lib/event-log-query.js';
+
+describe('aiEnvelope.capBreached: engine projection via event-log seam (capabilities.md §"cap.breached")', () => {
+  it('breached outcome projects to cap.breached { kind: "envelopes" } event with causationId chain', async () => {
+    if (!(await isEventLogSeamAvailable())) return;
+    const runId = `r-cap-env-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const correlationId = `${runId}:node-1:turn-0:cap-env`;
+    const r = await accept(
+      {
+        type: 'error',
+        schemaVersion: 1,
+        envelopeId: 'env-proj-cap-env',
+        correlationId,
+        payload: { code: 'x', message: 'y' },
+        meta: baseMeta,
+      },
+      {
+        counters: { envelopesPerTurn: { current: 32, cap: 32 } },
+        projectTo: { runId, nodeId: 'node-1' },
+      },
+    );
+    if (r.status === 404) return;
+    expect(r.body.status).toBe('breached');
+
+    const events = await queryTestEvents(runId, { type: 'cap.breached' });
+    if (!events.ok) return;
+    expect(
+      events.events.length,
+      driver.describe('capabilities.md §"Engine-enforced limits and the cap.breached event"', 'breached outcome MUST project to exactly one cap.breached event'),
+    ).toBe(1);
+    const evt = events.events[0]!;
+    expect(evt.payload.kind).toBe('envelopes');
+    expect(evt.causationId).toBe(correlationId);
+    await resetTestSeam();
+  });
+
+  it('cap.breached payload includes limit, observed, and nodeId per capabilities.md', async () => {
+    if (!(await isEventLogSeamAvailable())) return;
+    const runId = `r-cap-payload-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await accept(
+      {
+        type: 'clarification.request',
+        schemaVersion: 1,
+        envelopeId: 'env-proj-cap-clar',
+        correlationId: `${runId}:node-2:turn-0:cap`,
+        payload: { questions: [{ id: 'q1', question: 'why?' }] },
+        meta: baseMeta,
+      },
+      {
+        counters: { clarificationRounds: { current: 5, cap: 5 } },
+        projectTo: { runId, nodeId: 'node-2' },
+      },
+    );
+    const events = await queryTestEvents(runId, { type: 'cap.breached' });
+    if (!events.ok || events.events.length === 0) return;
+    const evt = events.events[0]!;
+    expect(evt.payload.kind).toBe('clarification');
+    expect(
+      typeof evt.payload.limit,
+      driver.describe('capabilities.md §"cap.breached"', 'payload.limit MUST be present as a number'),
+    ).toBe('number');
+    expect(evt.payload.nodeId).toBe('node-2');
+    await resetTestSeam();
+  });
+
+  it('cap.breached MUST be paired with a terminal node.failed transition', async () => {
+    if (!(await isEventLogSeamAvailable())) return;
+    const runId = `r-cap-fail-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await accept(
+      {
+        type: 'schema.request',
+        schemaVersion: 1,
+        envelopeId: 'env-proj-cap-fail',
+        correlationId: `${runId}:node-3:turn-0:cap`,
+        payload: { envelopeType: 'vendor.acme.foo' },
+        meta: baseMeta,
+      },
+      {
+        counters: { schemaRounds: { current: 3, cap: 3 } },
+        projectTo: { runId, nodeId: 'node-3' },
+      },
+    );
+    const breached = await queryTestEvents(runId, { type: 'cap.breached' });
+    const failed = await queryTestEvents(runId, { type: 'node.failed' });
+    if (!breached.ok || !failed.ok) return;
+    expect(breached.events.length).toBe(1);
+    expect(
+      failed.events.length,
+      driver.describe('capabilities.md §"cap.breached"', 'cap.breached MUST be paired with a terminal node.failed event'),
+    ).toBe(1);
+    expect((failed.events[0]!.payload.error as { code?: string }).code).toBe('cap_breached');
+    await resetTestSeam();
+  });
 });

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

@@ -1,9 +1,10 @@
 /**
- * aiEnvelope.contractRefusal — FINAL v1.1 advertisement-shape verification + behavioral placeholders.
+ * aiEnvelope.contractRefusal — FINAL v1.1 advertisement-shape + behavioral.
  *
- * Status: DRAFT (advertisement-shape). `spec/v1/ai-envelope.md` landed
- * 2026-05-17 as DRAFT v1.x. Behavioral assertions stay `it.todo()` until a
- * reference host wires Envelope Contract enforcement on a node typeId.
+ * Status: ACTIVE (advertisement-shape + behavioral). `spec/v1/ai-envelope.md`
+ * promoted Draft → FINAL v1.1 2026-05-18. Live behavioral via the
+ * `POST /v1/host/sample/envelope/accept` seam + the capability-toggle seam
+ * (soft-skip when either is absent).
  *
  * Summary: an Envelope Contract is a per-typeId declaration of which envelope
  * kinds that node accepts (`accepts: string[]` plus implicit universals). When
@@ -19,8 +20,9 @@
  * @see spec/v1/ai-envelope.md §"Envelope Contract"
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { setHostCapability, resetHostCapabilities, isToggleAvailable } from '../lib/host-toggle.js';
 
 interface DiscoveryDoc {
   capabilities?: Record<string, unknown>;
@@ -137,14 +139,221 @@ describe('aiEnvelope.contractRefusal: behavioral accept-gate (FINAL v1.1)', () =
   });
 });
 
-describe('aiEnvelope.contractRefusal: engine-integration placeholders', () => {
-  // These require the engine to project gated outcomes onto RunEventDocs
-  // / node.failed events / log.appended (level: warn) per refusalMode.
-  // The pure-function acceptor surfaces `gated` outcomes; the engine
-  // projects them to the event log.
-  it.todo('node.failed event carries error.code = "envelope_contract_violation"');
-  it.todo('refused envelope error.details.acceptedTypes lists the declared accepts[]');
-  it.todo('refused envelope error.details.refusedType names the emitted type');
-  it.todo('refusalMode:"discard-and-warn" emits log.appended level:"warn" instead of node.failed');
-  it.todo('capability-gated typeId refusal stacks atop Envelope Contract refusal (host.aiEnvelope absent → typeId refused first)');
+// E.1 engine-projection via the test-only event-log seam.
+import { queryTestEvents, isEventLogSeamAvailable, resetTestSeam } from '../lib/event-log-query.js';
+
+describe('aiEnvelope.contractRefusal: engine projection via event-log seam', () => {
+  it('gated (fail-node) → node.failed { error.code: "envelope_contract_violation" }', async () => {
+    if (!(await isEventLogSeamAvailable())) return;
+    const runId = `r-cr-fail-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const r = await accept(
+      {
+        type: 'vendor.x.bar.create',
+        schemaVersion: 1,
+        envelopeId: 'env-cr-proj-1',
+        correlationId: `${runId}:n:0:cr-proj-1`,
+        payload: {},
+        meta: baseMeta,
+      },
+      {
+        hostSupportedEnvelopes: ['vendor.x.bar.create', 'vendor.x.foo.create'],
+        nodeAllowedKinds: ['vendor.x.foo.create'],
+        projectTo: { runId, nodeId: 'n', refusalMode: 'fail-node' },
+      },
+    );
+    if (r.status === 404) return;
+    expect(r.body.status).toBe('gated');
+    const events = await queryTestEvents(runId, { type: 'node.failed' });
+    if (!events.ok || events.events.length === 0) return;
+    const err = events.events[0]!.payload.error as { code?: string; details?: { refusedType?: string; acceptedTypes?: string[] } };
+    expect(
+      err.code,
+      driver.describe('ai-envelope.md §"Envelope Contract"', 'gated outcome MUST project to node.failed with error.code = envelope_contract_violation'),
+    ).toBe('envelope_contract_violation');
+  });
+
+  it('refused envelope: error.details.refusedType names emitted kind; acceptedTypes lists allowed kinds', async () => {
+    if (!(await isEventLogSeamAvailable())) return;
+    const runId = `r-cr-details-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await accept(
+      {
+        type: 'vendor.x.bar.create',
+        schemaVersion: 1,
+        envelopeId: 'env-cr-proj-details',
+        correlationId: `${runId}:n:0:cr-details`,
+        payload: {},
+        meta: baseMeta,
+      },
+      {
+        hostSupportedEnvelopes: ['vendor.x.bar.create', 'vendor.x.foo.create'],
+        nodeAllowedKinds: ['vendor.x.foo.create'],
+        projectTo: { runId, nodeId: 'n' },
+      },
+    );
+    const events = await queryTestEvents(runId, { type: 'node.failed' });
+    if (!events.ok || events.events.length === 0) return;
+    const details = (events.events[0]!.payload.error as { details?: { refusedType?: string; acceptedTypes?: string[] } }).details;
+    expect(details?.refusedType).toBe('vendor.x.bar.create');
+    expect(
+      Array.isArray(details?.acceptedTypes) && details!.acceptedTypes!.includes('vendor.x.foo.create'),
+      driver.describe('ai-envelope.md §"Envelope Contract"', 'error.details.acceptedTypes MUST list the node\'s declared accepts[] (plus universals)'),
+    ).toBe(true);
+  });
+
+  it('refusalMode:"discard-and-warn" → log.appended { level: "warn" } instead of node.failed', async () => {
+    if (!(await isEventLogSeamAvailable())) return;
+    const runId = `r-cr-warn-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await accept(
+      {
+        type: 'vendor.x.bar.create',
+        schemaVersion: 1,
+        envelopeId: 'env-cr-proj-warn',
+        correlationId: `${runId}:n:0:cr-warn`,
+        payload: {},
+        meta: baseMeta,
+      },
+      {
+        hostSupportedEnvelopes: ['vendor.x.bar.create'],
+        nodeAllowedKinds: ['vendor.x.foo.create'], // gated
+        projectTo: { runId, nodeId: 'n', refusalMode: 'discard-and-warn' },
+      },
+    );
+    const warnEvents = await queryTestEvents(runId, { type: 'log.appended' });
+    const failEvents = await queryTestEvents(runId, { type: 'node.failed' });
+    if (!warnEvents.ok || !failEvents.ok) return;
+    expect(
+      warnEvents.events.some((e) => (e.payload as { level?: string }).level === 'warn'),
+      driver.describe('ai-envelope.md §"Envelope Contract"', 'discard-and-warn MUST emit log.appended at warn level'),
+    ).toBe(true);
+    expect(
+      failEvents.events.length,
+      driver.describe('ai-envelope.md §"Envelope Contract"', 'discard-and-warn MUST NOT emit node.failed'),
+    ).toBe(0);
+    await resetTestSeam();
+  });
+
+  it('host-gate refusal (hostSupportedEnvelopes) projects to node.failed with envelope_contract_violation', async () => {
+    if (!(await isEventLogSeamAvailable())) return;
+    const runId = `r-cr-host-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    await accept(
+      {
+        type: 'vendor.unadvertised.kind',
+        schemaVersion: 1,
+        envelopeId: 'env-cr-proj-host',
+        correlationId: `${runId}:n:0:cr-host`,
+        payload: {},
+        meta: baseMeta,
+      },
+      {
+        hostSupportedEnvelopes: ['vendor.advertised.only'],
+        nodeAllowedKinds: ['vendor.unadvertised.kind'],
+        projectTo: { runId, nodeId: 'n' },
+      },
+    );
+    const events = await queryTestEvents(runId, { type: 'node.failed' });
+    if (!events.ok || events.events.length === 0) return;
+    expect(
+      (events.events[0]!.payload.error as { code?: string }).code,
+      driver.describe('ai-envelope.md §"Capability handshake integration"', 'host-gate refusal MUST project to node.failed envelope_contract_violation (stacks above node-gate)'),
+    ).toBe('envelope_contract_violation');
+  });
+});
+
+// Capability-stacking — backed by the `host.aiEnvelope.supported`
+// flag in the workflow-engine's capability overlay. Per ai-envelope.md
+// §"Capability handshake integration" line 305: capability-gated
+// typeId refusal MUST stack atop envelope-contract refusal. When the
+// host doesn't advertise `host.aiEnvelope: supported`, every
+// envelope/accept call refuses BEFORE the per-envelope contract
+// gates (host-gate, node-gate, schema-floor) fire — observable as
+// `reason: "capability_required"` (NOT "envelope_contract_violation").
+
+describe('aiEnvelope.contractRefusal: capability-stacking (FINAL v1.1)', () => {
+  afterEach(async () => {
+    // Restore overlay after each test so subsequent scenarios see the
+    // default advertisement.
+    await resetHostCapabilities();
+  });
+
+  it('host.aiEnvelope.supported = false → envelope/accept refuses with capability_required BEFORE envelope contract gates', async () => {
+    if (!(await isToggleAvailable())) return; // seam not exposed — soft-skip
+
+    const toggle = await setHostCapability('host.aiEnvelope.supported', false);
+    if (!toggle.ok) return;
+
+    // Same envelope shape that the existing host-gate scenario uses
+    // (line 233-257 above) — the type IS in hostSupportedEnvelopes AND
+    // matches nodeAllowedKinds, so the envelope-contract gate would
+    // normally accept. The capability gate must fire FIRST and return
+    // capability_required regardless.
+    const r = await accept(
+      {
+        type: 'vendor.advertised.kind',
+        schemaVersion: 1,
+        envelopeId: 'env-cr-capstack-1',
+        correlationId: 'r:n:0:cr-capstack',
+        payload: {},
+        meta: baseMeta,
+      },
+      {
+        hostSupportedEnvelopes: ['vendor.advertised.kind'],
+        nodeAllowedKinds: ['vendor.advertised.kind'],
+      },
+    );
+    if (r.status === 404) return;
+    expect(
+      r.body.status,
+      driver.describe(
+        'ai-envelope.md §"Capability handshake integration"',
+        'capability-absent host MUST refuse envelope acceptance regardless of host-gate / node-gate match',
+      ),
+    ).toBe('invalid');
+    expect(
+      r.body.reason,
+      driver.describe(
+        'capabilities.md §"Unsupported capability — refusal contract"',
+        'refusal reason MUST be capability_required (NOT envelope_contract_violation) — capability gate stacks above the envelope-contract gate',
+      ),
+    ).toBe('capability_required');
+  });
+
+  it('host.aiEnvelope.supported = true → envelope/accept falls through to envelope-contract gates', async () => {
+    if (!(await isToggleAvailable())) return;
+    const toggle = await setHostCapability('host.aiEnvelope.supported', true);
+    if (!toggle.ok) return;
+
+    // With capability advertised, a normally-rejected envelope (type
+    // not in hostSupportedEnvelopes) reaches the envelope-contract
+    // gate and refuses with `envelope_contract_violation`, NOT
+    // `capability_required`. Proves the capability gate is gated on
+    // the flag and doesn't short-circuit the contract path when the
+    // capability IS advertised.
+    const r = await accept(
+      {
+        type: 'vendor.unadvertised.kind',
+        schemaVersion: 1,
+        envelopeId: 'env-cr-capstack-2',
+        correlationId: 'r:n:0:cr-capstack-fallthrough',
+        payload: {},
+        meta: baseMeta,
+      },
+      {
+        hostSupportedEnvelopes: ['vendor.advertised.only'],
+        nodeAllowedKinds: ['vendor.unadvertised.kind'],
+      },
+    );
+    if (r.status === 404) return;
+    expect(
+      r.body.status,
+      driver.describe(
+        'ai-envelope.md §"Capability handshake integration"',
+        'when capability IS advertised, envelope-contract gates run normally',
+      ),
+    ).toBe('gated');
+    // `gated` is the envelope-contract-gate outcome (host-gate +
+    // node-gate); reason text varies. The key contract: status is NOT
+    // `invalid` with `capability_required` — the capability layer
+    // didn't intercept.
+    expect(r.body.reason).not.toBe('capability_required');
+  });
 });