@openwop/openwop-conformance 1.2.0 → 1.3.0

package/src/lib/env.ts

@@ -25,6 +25,28 @@
  *     hosts go strict-mode green without falsifying capability claims.
  *     Example for SQLite:
  *       OPENWOP_OPTED_OUT_PROFILES=openwop-production,openwop-auth-mtls
+ *
+ *   OPENWOP_OPTED_OUT_FIXTURES — comma-separated fixture ids (or
+ *     trailing-`*` globs) the host operator has DELIBERATELY chosen
+ *     not to honor. Applied in `lib/fixtures.ts` by filtering matching
+ *     entries out of the cached advertised-fixture set, so any
+ *     scenario gated via `isFixtureAdvertised(...)` skips cleanly.
+ *     Use when a host auto-loads every `conformance-*.json` on disk
+ *     (so the fixture id IS in the discovery doc) but the host doesn't
+ *     implement the gated feature. Symmetric to `OPENWOP_OPTED_OUT_
+ *     PROFILES` for the fixture-id axis. Example for SQLite:
+ *       OPENWOP_OPTED_OUT_FIXTURES=conformance-dispatch-*,conformance-subworkflow-input-mapping*
+ *
+ *   OPENWOP_OPTED_OUT_SCENARIOS — comma-separated scenario ids that
+ *     individual tests consult to skip themselves where neither
+ *     profile-opt-out nor fixture-opt-out is fine-grained enough
+ *     (e.g., OTel trace-inheritance across `core.subWorkflow` —
+ *     `conformance-subworkflow-parent` is correctly advertised because
+ *     non-OTel subworkflow scenarios pass, but the host doesn't
+ *     propagate traceparent across the dispatch boundary). Use
+ *     `isScenarioOptedOut(scenarioId)` from `env.ts` in the test's
+ *     skip predicate. Reserved for cases where the suite-wide
+ *     skip mechanisms can't carry the granularity.
  */
 
 export interface ConformanceEnv {
@@ -84,3 +106,32 @@ export function loadEnv(): ConformanceEnv {
   };
   return cached;
 }
+
+/**
+ * Returns true when the operator has listed `scenarioId` in
+ * `OPENWOP_OPTED_OUT_SCENARIOS`. Use inside a test's `describe.skipIf`
+ * predicate when neither profile-opt-out nor fixture-opt-out is
+ * granular enough. Logs the skip reason via the caller — this helper
+ * is silent so callers can format their own message.
+ *
+ * Re-reads `process.env` on every call (single env access + split, no
+ * cache). Symmetric with `lib/fixtures.ts:loadOptedOutPredicate` which
+ * re-reads on every `setAdvertisedFixtures(...)` call — so unit tests
+ * can mutate `process.env.OPENWOP_OPTED_OUT_SCENARIOS` between cases
+ * without having to invalidate a memoization.
+ */
+export function isScenarioOptedOut(scenarioId: string): boolean {
+  const raw = process.env.OPENWOP_OPTED_OUT_SCENARIOS?.trim() ?? '';
+  if (raw.length === 0) return false;
+  for (const entry of raw.split(',')) {
+    if (entry.trim() === scenarioId) return true;
+  }
+  return false;
+}
+
+/** Test-only: clear the `loadEnv()` memoization so subsequent calls
+ * re-read `process.env`. Required for any test that mutates the env
+ * vars consumed by `loadEnv()` mid-suite. */
+export function __resetEnvCacheForTests(): void {
+  cached = null;
+}

package/src/lib/event-log-query.ts

@@ -0,0 +1,62 @@
+/**
+ * Driver helpers for the test-only event-log query seam
+ * (`GET /v1/host/sample/test/runs/:runId/events`).
+ *
+ * Used by aiEnvelope engine-projection scenarios that verify the
+ * spec-prescribed events the host MUST emit on each envelope outcome
+ * (per RFC 0021 §A point 1-7 + interrupt.md + capabilities.md
+ * §"cap.breached"). All operations soft-skip on HTTP 404 — hosts
+ * without the seam keep the existing advertisement-shape coverage.
+ *
+ * Reset semantics: callers SHOULD `resetTestSeam()` in their test's
+ * `afterEach` (or scope each test to a unique runId) to keep state
+ * from leaking across scenarios.
+ */
+
+import { driver } from './driver.js';
+
+export interface TestEvent {
+  readonly eventId: string;
+  readonly runId: string;
+  readonly type: string;
+  readonly payload: Record<string, unknown>;
+  readonly timestamp: string;
+  readonly sequence: number;
+  readonly causationId?: string;
+  readonly nodeId?: string;
+  readonly contentTrust?: 'trusted' | 'untrusted';
+}
+
+export type QueryOutcome =
+  | { ok: true; events: TestEvent[] }
+  | { ok: false; reason: 'seam_unavailable' }
+  | { ok: false; reason: 'http_error'; status: number };
+
+/** Query the test-only event log for a run, with optional filters. */
+export async function queryTestEvents(
+  runId: string,
+  filter: { type?: string; correlationId?: string; causationId?: string; nodeId?: string } = {},
+): Promise<QueryOutcome> {
+  const qs = new URLSearchParams();
+  if (filter.type) qs.set('type', filter.type);
+  if (filter.correlationId) qs.set('correlationId', filter.correlationId);
+  if (filter.causationId) qs.set('causationId', filter.causationId);
+  if (filter.nodeId) qs.set('nodeId', filter.nodeId);
+  const url = `/v1/host/sample/test/runs/${encodeURIComponent(runId)}/events${qs.toString() ? '?' + qs.toString() : ''}`;
+  const res = await driver.get(url);
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { events?: TestEvent[] };
+  return { ok: true, events: body.events ?? [] };
+}
+
+/** Reset the test-only event log + capability overlay (suite teardown). */
+export async function resetTestSeam(): Promise<void> {
+  await driver.post('/v1/host/sample/test/reset', {});
+}
+
+/** Probe whether the seam is exposed. Use to soft-skip early. */
+export async function isEventLogSeamAvailable(): Promise<boolean> {
+  const res = await queryTestEvents('__probe__');
+  return res.ok;
+}

package/src/lib/fixtures.ts

@@ -26,6 +26,16 @@
  * This module is sync. The async fetch lives in `setup.ts` which calls
  * `setAdvertisedFixtures(...)` from a top-level `await`.
  *
+ * Honest opt-out (symmetric to `OPENWOP_OPTED_OUT_PROFILES`):
+ *   `OPENWOP_OPTED_OUT_FIXTURES` (CSV, supports trailing `*` glob)
+ *   subtracts matching fixture-ids from the cached set even when the
+ *   host advertises them. Operators use this when the host happens to
+ *   carry a fixture file (e.g., it auto-loads every `conformance-*.json`
+ *   on disk) but does NOT implement the underlying feature — so the
+ *   gated scenario should skip instead of running and failing. The
+ *   subtraction happens at cache-population time, so the predicate
+ *   remains a single sync set lookup at scenario-evaluation time.
+ *
  * @see spec/v1/capabilities.md §`fixtures`
  * @see spec/v1/profiles.md §`openwop-fixtures`
  * @see RFCS/0003-fixture-gating.md
@@ -35,19 +45,46 @@ import type { DiscoveryPayload } from './profiles.js';
 
 let _advertisedFixtures: ReadonlySet<string> | null = null;
 
+/**
+ * Parse `OPENWOP_OPTED_OUT_FIXTURES` into a match predicate. Each entry
+ * is either an exact id or a glob with a trailing `*`. Returns a
+ * function that answers "is this fixture-id opted out?" — empty / unset
+ * env reduces to "always false."
+ */
+function loadOptedOutPredicate(): (id: string) => boolean {
+  const raw = process.env.OPENWOP_OPTED_OUT_FIXTURES?.trim() ?? '';
+  if (raw.length === 0) return () => false;
+  const exact = new Set<string>();
+  const prefixes: string[] = [];
+  for (const entry of raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0)) {
+    if (entry.endsWith('*')) {
+      prefixes.push(entry.slice(0, -1));
+    } else {
+      exact.add(entry);
+    }
+  }
+  return (id) => exact.has(id) || prefixes.some((p) => id.startsWith(p));
+}
+
 /**
  * Populate the cache from a discovery-doc payload. The function is
  * tolerant of malformed inputs — anything other than a string array
  * collapses to "no fixtures advertised" rather than throwing, so the
  * suite remains resilient against host bugs in the discovery surface.
+ *
+ * Applies `OPENWOP_OPTED_OUT_FIXTURES` at this step: opted-out ids are
+ * filtered out of the cache before storage so downstream lookups can
+ * stay a single sync set-membership test.
  */
 export function setAdvertisedFixtures(c: DiscoveryPayload | null | undefined): void {
   if (c == null || !Array.isArray(c.fixtures)) {
     _advertisedFixtures = new Set();
     return;
   }
+  const isOptedOut = loadOptedOutPredicate();
   const ids = c.fixtures.filter(
-    (entry): entry is string => typeof entry === 'string' && entry.length > 0,
+    (entry): entry is string =>
+      typeof entry === 'string' && entry.length > 0 && !isOptedOut(entry),
   );
   _advertisedFixtures = new Set(ids);
 }

package/src/lib/host-toggle.ts

@@ -0,0 +1,54 @@
+/**
+ * Capability-toggle harness primitive — driver helper for the
+ * env-gated test-seam endpoint at
+ * `POST /v1/host/sample/test/capability-toggle`.
+ *
+ * Lets refusal-case scenarios (RFC 0022 §C HVMAP-1a-refusal,
+ * HVMAP-2-refusal, etc.) flip a capability flag off temporarily,
+ * exercise the host's refusal path, then restore the default.
+ *
+ * All operations soft-skip on HTTP 404 — hosts that don't expose the
+ * seam keep the existing advertisement-shape coverage intact.
+ *
+ * Reset semantics: callers MUST `resetHostCapabilities()` in their
+ * test's `afterEach` (or equivalent) to keep state from leaking
+ * across scenarios.
+ */
+
+import { driver } from './driver.js';
+
+export type ToggleOutcome =
+  | { ok: true; overlay: Record<string, boolean> }
+  | { ok: false; reason: 'seam_unavailable' }
+  | { ok: false; reason: 'http_error'; status: number };
+
+/** Set a capability flag's overlay value. `value: null` removes the
+ *  overlay entry (restoring the host's hard-coded default). */
+export async function setHostCapability(
+  name: string,
+  value: boolean | null,
+): Promise<ToggleOutcome> {
+  const res = await driver.post('/v1/host/sample/test/capability-toggle', { name, value });
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { overlay?: Record<string, boolean> };
+  return { ok: true, overlay: body.overlay ?? {} };
+}
+
+/** Clear ALL capability overlay entries on the host. */
+export async function resetHostCapabilities(): Promise<ToggleOutcome> {
+  const res = await driver.post('/v1/host/sample/test/capability-toggle', { reset: true });
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { overlay?: Record<string, boolean> };
+  return { ok: true, overlay: body.overlay ?? {} };
+}
+
+/** Probe whether the host exposes the capability-toggle seam at all.
+ *  Use this to soft-skip a scenario early when the host lacks the
+ *  toggle (the refusal contract is still spec-normative; the test just
+ *  can't drive it from outside). */
+export async function isToggleAvailable(): Promise<boolean> {
+  const probe = await setHostCapability('__probe__', null);
+  return probe.ok;
+}

package/src/lib/multi-agent-capabilities.ts

@@ -37,6 +37,9 @@ interface AgentCaps {
     | {
         verbosity: 'summary' | 'full' | 'off' | undefined;
         tokenLimit: number | undefined;
+        /** RFC 0024. When true, host may emit `agent.reasoning.delta`
+         *  events in addition to the closing `agent.reasoned`. */
+        streaming: boolean;
       }
     | undefined;
 }
@@ -84,6 +87,7 @@ export function setMultiAgentCapabilities(c: DiscoveryPayload | null | undefined
               typeof (reasoningRaw as Record<string, unknown>).tokenLimit === 'number'
                 ? ((reasoningRaw as Record<string, unknown>).tokenLimit as number)
                 : undefined,
+            streaming: asBoolean((reasoningRaw as Record<string, unknown>).streaming),
           }
         : undefined;
     _agentCaps = {
@@ -113,6 +117,12 @@ export function getReasoningVerbosity(): 'summary' | 'full' | 'off' | undefined
   return _agentCaps?.reasoning?.verbosity;
 }
 
+/** RFC 0024 — host emits incremental `agent.reasoning.delta` events
+ *  while a reasoning block is still open. */
+export function isReasoningStreamingSupported(): boolean {
+  return _agentCaps?.reasoning?.streaming === true;
+}
+
 /** Phase 2 — host supports the named modelClass. */
 export function hasModelClass(modelClass: string): boolean {
   return _agentCaps?.modelClasses.has(modelClass) === true;

package/src/lib/otel-scrape.ts

@@ -0,0 +1,59 @@
+/**
+ * Driver helpers for the OTel + debug-bundle test seams (E.2 + E.3).
+ *
+ * Used by aiEnvelope + cost-attribution scenarios that need to verify
+ * span-attribute redaction (no BYOK canary in OTel attributes) and
+ * debug-bundle export shape.
+ */
+
+import { driver } from './driver.js';
+
+export interface TestSpan {
+  readonly spanId: string;
+  readonly name: string;
+  readonly attributes: Record<string, string | number | boolean>;
+  readonly envelopeId?: string;
+  readonly runId?: string;
+  readonly timestamp: string;
+}
+
+export interface DebugBundle {
+  readonly runId: string;
+  readonly events: unknown[];
+  readonly spans: TestSpan[];
+  readonly exportedAt: string;
+}
+
+export type ScrapeOutcome<T> =
+  | { ok: true; data: T }
+  | { ok: false; reason: 'seam_unavailable' }
+  | { ok: false; reason: 'http_error'; status: number };
+
+export async function queryTestSpans(
+  filter: { envelopeId?: string; runId?: string; name?: string } = {},
+): Promise<ScrapeOutcome<TestSpan[]>> {
+  const qs = new URLSearchParams();
+  if (filter.envelopeId) qs.set('envelopeId', filter.envelopeId);
+  if (filter.runId) qs.set('runId', filter.runId);
+  if (filter.name) qs.set('name', filter.name);
+  const url = `/v1/host/sample/test/otel/spans${qs.toString() ? '?' + qs.toString() : ''}`;
+  const res = await driver.get(url);
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { spans?: TestSpan[] };
+  return { ok: true, data: body.spans ?? [] };
+}
+
+export async function exportDebugBundle(runId: string): Promise<ScrapeOutcome<DebugBundle>> {
+  const res = await driver.post('/v1/host/sample/test/debug-bundle/export', { runId });
+  if (res.status === 404) return { ok: false, reason: 'seam_unavailable' };
+  if (res.status !== 200) return { ok: false, reason: 'http_error', status: res.status };
+  const body = res.json as { bundle?: DebugBundle };
+  if (!body.bundle) return { ok: false, reason: 'http_error', status: 500 };
+  return { ok: true, data: body.bundle };
+}
+
+export async function isOtelSeamAvailable(): Promise<boolean> {
+  const res = await queryTestSpans({ runId: '__probe__' });
+  return res.ok;
+}

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