@openwop/openwop-conformance 1.10.0 → 1.12.0

package/src/scenarios/safefetch-live-audit.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Live-run safe-fetch audit emission — `host-capabilities.md` §host.http
+ * (`ctx.http.safeFetch`) + RFC 0076 §B + RFC 0064 §B.
+ *
+ * Closes the seam-vs-production gap left by `safefetch-behavior.test.ts`. That
+ * scenario drives `POST /v1/host/sample/http/safe-fetch` and reads the audit
+ * pair the SEAM returns INLINE — it never proves the *production* per-ctx
+ * `ctx.http.safeFetch` (the client injected into a real run) emits anything. A
+ * host can co-advertise `toolHooks.prePostEvents` + `httpClient.safeFetch`,
+ * pass the seam, and still ship a production `createSafeFetch()` with no audit
+ * hooks — the "quiet bypass" §host.http line "centralizing egress in the host
+ * must increase auditability, not become a quiet bypass" forbids.
+ *
+ * The normative MUST (host-capabilities.md §host.http; RFC 0076 §B):
+ *   When `toolHooks.prePostEvents: true` AND `httpClient.safeFetch.supported:
+ *   true` are BOTH advertised, the host MUST emit the `agent.toolCalled` /
+ *   `agent.toolReturned` pair (`transport: "http"`) **for every `safeFetch`
+ *   invocation** — including a *refused* one (a blocked egress attempt is
+ *   exactly the security-relevant event the audit log must capture).
+ *
+ * This scenario verifies that MUST against the DURABLE run event log, not the
+ * seam's inline echo, and does so **without depending on outbound egress** so
+ * the bar can never pass vacuously:
+ *   1. EGRESS-FREE FLOOR (required): drive one `ctx.http.safeFetch` to a
+ *      guaranteed-blocked link-local / cloud-metadata URL inside a REAL run via
+ *      `POST /v1/host/sample/http/safe-fetch-run`. A conformant SSRF guard
+ *      refuses it on every host with zero connectivity, yet the production
+ *      injection + auditHooks path is still exercised, so the durable pair MUST
+ *      be present. This removes the "no public egress ⇒ green-but-proves-nothing"
+ *      hole that a `fetched`-only assertion left.
+ *   2. SUCCESS-PATH COVERAGE (best-effort): drive a public URL; when it actually
+ *      `fetched`, assert the same durable pair (catches a host that audits only
+ *      the reject path). Skipped — not failed — where the environment has no
+ *      public egress; the floor already proved emission.
+ *   3. Read each run's persisted events via the test event-log seam
+ *      (`GET /v1/host/sample/test/runs/:runId/events`) and assert a `callId`-
+ *      paired `agent.toolCalled` (`transport:"http"`) / `agent.toolReturned`.
+ *
+ * Gating: `behaviorGate('openwop-safefetch-live-audit', <both flags>)` — NOT an
+ * inline soft-skip. So it skips-with-reason in default mode but FAILS under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true` when a host advertises both flags yet does not
+ * emit. This is the RFC 0076 §B → Accepted bar a non-steward host validates
+ * against. The run seam itself (`safe-fetch-run`) is host-pending: a 404 from a
+ * not-yet-wired seam soft-skips even in strict mode (the seam is test-only
+ * infrastructure, distinct from the advertised production capability).
+ * The SSRF guarantee reuses the existing `http-client-ssrf-guard` invariant —
+ * no new SECURITY invariant; the audit MUST is RFC 0064's existing posture.
+ *
+ * @see spec/v1/host-capabilities.md §host.http
+ * @see spec/v1/host-sample-test-seams.md §"Open seams" (safe-fetch-run)
+ * @see RFCS/0076-pack-runtime-requirements-and-host-safe-fetch.md §B
+ * @see RFCS/0064-tool-invocation-hooks-and-authorization.md §B
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { isSafeFetchLiveAuditAdvertised, safeFetchViaRun } from '../lib/safeFetch.js';
+import { queryTestEvents } from '../lib/event-log-query.js';
+
+const PROFILE = 'openwop-safefetch-live-audit';
+const CITE = 'host-capabilities.md §host.http';
+
+// A link-local / cloud-metadata URL the SSRF guard MUST refuse — reachable on
+// EVERY host regardless of outbound egress, so the durable-pair assertion never
+// passes vacuously. Per §host.http the audit MUST is per-invocation: a *blocked*
+// safeFetch still emits the agent.toolCalled/agent.toolReturned pair (the
+// toolReturned carries the forbidden status). cf. `http-client-ssrf-guard`.
+const BLOCKED_URL = 'http://169.254.169.254/latest/meta-data/';
+// A public URL the guard SHOULD allow — best-effort coverage of the *success*
+// path; skipped (not failed) where the environment has no public egress.
+const FETCH_URL = 'https://example.com/';
+
+/**
+ * Read the durable run event log for `runId` and assert a `callId`-paired
+ * `agent.toolCalled` (`transport:"http"`) / `agent.toolReturned` exists, with
+ * the RFC 0002 §B causation chain tolerated when the host surfaces it. Returns
+ * `false` (caller treats as host-pending soft-skip) only when the event-log
+ * query seam is unavailable; otherwise asserts and returns `true`.
+ */
+async function assertDurableHttpPair(runId: string, label: string): Promise<boolean> {
+  const calledQ = await queryTestEvents(runId, { type: 'agent.toolCalled' });
+  const returnedQ = await queryTestEvents(runId, { type: 'agent.toolReturned' });
+  if (!calledQ.ok || !returnedQ.ok) {
+    // eslint-disable-next-line no-console
+    console.warn(`[${PROFILE}] event-log query seam unavailable; host-pending — skipping`);
+    return false;
+  }
+
+  // The HTTP-transport tool call: a durable agent.toolCalled with transport:"http".
+  const httpCall = calledQ.events.find((e) => (e.payload as { transport?: string }).transport === 'http');
+  expect(
+    httpCall !== undefined,
+    driver.describe(
+      CITE,
+      `(${label}) when toolHooks.prePostEvents + safeFetch are both advertised, a production ctx.http.safeFetch call MUST persist an agent.toolCalled with transport:"http" to the durable run event log (not just the seam echo), for EVERY invocation incl. blocked ones`,
+    ),
+  ).toBe(true);
+  if (!httpCall) return true;
+
+  const callId = (httpCall.payload as { callId?: string }).callId;
+  expect(
+    typeof callId === 'string' && callId.length > 0,
+    driver.describe(CITE, `(${label}) the persisted agent.toolCalled MUST carry the required callId (run-event-payloads.schema.json §agentToolCalled)`),
+  ).toBe(true);
+
+  // The paired agent.toolReturned — matched by the required callId (RFC 0002 §B pairing).
+  const paired = returnedQ.events.find((e) => (e.payload as { callId?: string }).callId === callId);
+  expect(
+    paired !== undefined,
+    driver.describe(CITE, `(${label}) the agent.toolCalled MUST be followed by a callId-paired agent.toolReturned in the durable log (no quiet bypass)`),
+  ).toBe(true);
+
+  // Stricter, when the host surfaces causation: RFC 0002 §B says
+  // toolReturned.causationId === the paired toolCalled.eventId. Tolerate
+  // hosts that omit causationId (callId pairing already proven above).
+  if (paired && typeof paired.causationId === 'string') {
+    expect(
+      paired.causationId,
+      driver.describe('RFC 0002 §B', 'agent.toolReturned.causationId MUST equal the paired agent.toolCalled.eventId when surfaced'),
+    ).toBe(httpCall.eventId);
+  }
+  return true;
+}
+
+describe('safefetch-live-audit (RFC 0076 §B / RFC 0064 §B — production path, durable log)', () => {
+  it('a BLOCKED real-run safeFetch emits the durable agent.toolCalled/agent.toolReturned pair (transport:"http") — egress-free floor', async () => {
+    const advertised = await isSafeFetchLiveAuditAdvertised();
+    if (!behaviorGate(PROFILE, advertised)) return; // default-skip; strict-fail when both flags advertised
+
+    // Run seam is host-pending infrastructure — soft-skip (even in strict mode)
+    // until a safeFetch host wires it. behaviorGate above already enforced the
+    // capability co-advertisement; this only gates on the test vehicle.
+    const run = await safeFetchViaRun({ url: BLOCKED_URL });
+    if (run === null) {
+      // eslint-disable-next-line no-console
+      console.warn(`[${PROFILE}] safe-fetch-run seam unwired (404); host-pending — skipping`);
+      return;
+    }
+
+    // The metadata IP MUST be refused by a conformant SSRF guard
+    // (http-client-ssrf.test.ts owns that contract). Regardless of the exact
+    // outcome, the production injection path ran, so the durable audit pair MUST
+    // exist — this is the egress-independent floor that makes the bar non-vacuous.
+    expect(
+      typeof run.runId === 'string' && (run.runId as string).length > 0,
+      driver.describe(CITE, 'the safe-fetch-run seam MUST return the runId of the real run it executed the safeFetch in'),
+    ).toBe(true);
+    await assertDurableHttpPair(run.runId as string, 'blocked');
+  });
+
+  it('a FETCHED real-run safeFetch also emits the durable pair (success-path coverage — skipped without public egress)', async () => {
+    const advertised = await isSafeFetchLiveAuditAdvertised();
+    if (!behaviorGate(PROFILE, advertised)) return;
+
+    const run = await safeFetchViaRun({ url: FETCH_URL });
+    if (run === null) return; // seam unwired — already warned by the floor test
+
+    if (run.outcome !== 'fetched') {
+      // No public egress in this environment — the blocked-path floor already
+      // proved the production audit path emits. Skip success-path coverage
+      // rather than fail; this is coverage, not the floor.
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[${PROFILE}] ${FETCH_URL} did not fetch (outcome=${run.outcome ?? 'n/a'}); no public egress — success-path coverage skipped (the blocked floor covers emission)`,
+      );
+      return;
+    }
+    expect(
+      typeof run.runId === 'string' && (run.runId as string).length > 0,
+      driver.describe(CITE, 'the safe-fetch-run seam MUST return the runId of the real run it executed the fetch in'),
+    ).toBe(true);
+    await assertDurableHttpPair(run.runId as string, 'fetched');
+  });
+});

package/src/scenarios/spec-corpus-validity.test.ts

@@ -384,16 +384,32 @@ function extractReadmeDocumentIndex(readme: string): string {
   return readme.slice(start, end);
 }
 
-function listMarkdownFilesRecursive(dir: string): string[] {
+function listMarkdownFilesRecursive(dir: string, repoRoot: string = dir): string[] {
   const ignoredDirs = new Set(['.git', 'node_modules', 'dist']);
+  // Repo-relative directory paths to prune. These are subtrees whose
+  // content shouldn't be link-checked because either (a) they're
+  // generated build output (`site/out`) or (b) they're a vendored
+  // mirror of a canonical source whose READMEs use links relative to
+  // the canonical path, not the vendored path:
+  //
+  //  - `apps/workflow-engine/packs/` mirrors repo-root `packs/`, synced
+  //    via `apps/workflow-engine/scripts/sync-packs.sh` so the Cloud
+  //    Run image's `apps/workflow-engine/` build context can ship them.
+  //    Pack READMEs use `../../RFCS/...` / `../../spec/v1/...` links
+  //    that resolve from the canonical location (which this walker
+  //    DOES check) but break from the deeper vendored path. The
+  //    canonical copies are authoritative; the vendored copies are
+  //    byte-for-byte identical via cp -R.
+  const prunedRepoRelative = new Set(['site/out', 'apps/workflow-engine/packs']);
   const files: string[] = [];
 
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
       if (ignoredDirs.has(entry.name)) continue;
       const child = join(dir, entry.name);
-      if (relative(dir, child).startsWith('site/out')) continue;
-      files.push(...listMarkdownFilesRecursive(child));
+      const repoRelChild = relative(repoRoot, child);
+      if (prunedRepoRelative.has(repoRelChild)) continue;
+      files.push(...listMarkdownFilesRecursive(child, repoRoot));
       continue;
     }
     if (entry.isFile() && entry.name.endsWith('.md')) {

package/src/scenarios/tool-descriptor-shape.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Portable tool catalog — descriptor + capability + session-event shapes (RFC 0078).
+ *
+ * Always-on, server-free schema-shape probe. Verifies that:
+ *   - `tool-descriptor.schema.json` compiles and round-trips a conforming
+ *     `ToolDescriptor`, and rejects a descriptor missing the REQUIRED
+ *     `safetyTier`.
+ *   - the §C-1 / §F-4 cross-field MUST is enforced: a `safetyTier: "exec"`
+ *     descriptor MUST carry `source: "host-extension"` (RFC 0069 — exec is never
+ *     protocol-tier); an `exec` + `node-pack` descriptor is rejected, an `exec`
+ *     + `host-extension` descriptor is accepted.
+ *   - `capabilities.toolCatalog` is declared with its `supported` / `sources` /
+ *     `sessionLifecycle` sub-flags.
+ *   - the `tool.session.opened` / `tool.session.closed` payload $defs validate
+ *     conforming content-free records and reject malformed ones (a `closed`
+ *     missing `outcome`; an out-of-enum `outcome`), and both event names appear
+ *     in the RunEventType enum.
+ *
+ * Behavioral assertions (a live `GET /v1/tools` returning authorization-scoped
+ * descriptors, the `404` non-disclosure, the `tool.session.*` bracket ordering)
+ * are gated on `capabilities.toolCatalog.supported` and land in
+ * `tool-catalog-projection.test.ts` + `tool-session-lifecycle.test.ts` (deferred
+ * per RFC 0078 §Conformance — reference host deferred). This scenario asserts the
+ * wire contract, not host behavior.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/tool-catalog.md
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0078-portable-tool-catalog-and-tool-session-contract.md
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0069-exec-class-tool-host-extension-safety-contract.md (exec ⇒ host-extension)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+
+function loadSchema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+
+describe('tool-descriptor-shape: ToolDescriptor (RFC 0078 §C, server-free)', () => {
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const validate = ajv.compile(loadSchema('tool-descriptor.schema.json'));
+
+  it('a conforming descriptor validates', () => {
+    expect(
+      validate({
+        toolId: 'mcp:fs.read', source: 'mcp', title: 'Read file',
+        inputSchema: { type: 'object' }, auth: { scopes: ['tools:fs:read'] },
+        egress: 'none', approval: 'never', replayPolicy: 'idempotent',
+        safetyTier: 'read', costHint: 'low', latencyHint: 'low',
+      }),
+      why('tool-catalog.md §C', 'a conforming ToolDescriptor MUST validate'),
+    ).toBe(true);
+  });
+
+  it('a descriptor missing the REQUIRED safetyTier is rejected', () => {
+    expect(
+      validate({ toolId: 'x', source: 'mcp' }),
+      why('tool-catalog.md §C', 'safetyTier is REQUIRED'),
+    ).toBe(false);
+  });
+
+  it('enforces exec ⇒ host-extension (RFC 0069; §C-1/§F-4)', () => {
+    expect(
+      validate({ toolId: 'x-host-acme-shell', source: 'host-extension', safetyTier: 'exec', approval: 'always', egress: 'host-owned' }),
+      why('tool-catalog.md §C-1', 'an exec tool sourced from host-extension MUST validate'),
+    ).toBe(true);
+    expect(
+      validate({ toolId: 'openwop:run-shell', source: 'node-pack', safetyTier: 'exec' }),
+      why('tool-catalog.md §C-1 / RFC 0069', 'an exec tool MUST NOT be protocol-tier (node-pack)'),
+    ).toBe(false);
+  });
+
+  it('rejects an unknown property (additionalProperties:false)', () => {
+    expect(
+      validate({ toolId: 'x', source: 'mcp', safetyTier: 'read', danger: true }),
+      why('tool-catalog.md §C', 'ToolDescriptor MUST be additionalProperties:false'),
+    ).toBe(false);
+  });
+});
+
+describe('tool-descriptor-shape: capability advertisement (RFC 0078 §A, server-free)', () => {
+  it('capabilities.toolCatalog is declared with its sub-flags', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const toolCatalog = (caps.properties as Record<string, { properties?: Record<string, unknown> }>).toolCatalog;
+    expect(
+      toolCatalog,
+      why('capabilities.md §toolCatalog', 'capabilities.toolCatalog MUST be declared'),
+    ).toBeDefined();
+    for (const flag of ['supported', 'sources', 'sessionLifecycle']) {
+      expect(
+        toolCatalog?.properties?.[flag],
+        why('tool-catalog.md §A', `capabilities.toolCatalog.${flag} MUST be declared`),
+      ).toBeDefined();
+    }
+  });
+});
+
+describe('tool-descriptor-shape: session lifecycle events (RFC 0078 §D, server-free)', () => {
+  const payloads = loadSchema('run-event-payloads.schema.json');
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const compile = (defName: string) => ajv.compile({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $defs: (payloads as { $defs: Record<string, unknown> }).$defs,
+    $ref: `#/$defs/${defName}`,
+  } as Record<string, unknown>);
+
+  it('tool.session.opened validates a content-free record', () => {
+    const v = compile('toolSessionOpened');
+    expect(v({ sessionId: 's1', toolId: 'mcp:fs.read' }), why('tool-catalog.md §D', 'opened MUST validate')).toBe(true);
+    expect(v({ toolId: 'mcp:fs.read' }), why('tool-catalog.md §D', 'opened requires sessionId')).toBe(false);
+  });
+
+  it('tool.session.closed validates + enforces the closed outcome enum', () => {
+    const v = compile('toolSessionClosed');
+    expect(v({ sessionId: 's1', toolId: 'mcp:fs.read', outcome: 'completed' }), why('tool-catalog.md §D', 'closed MUST validate')).toBe(true);
+    expect(v({ sessionId: 's1', toolId: 'mcp:fs.read' }), why('tool-catalog.md §D', 'closed requires outcome')).toBe(false);
+    expect(v({ sessionId: 's1', toolId: 'mcp:fs.read', outcome: 'exploded' }), why('tool-catalog.md §D', 'outcome is a closed enum')).toBe(false);
+  });
+
+  it('both session event names appear in the RunEventType enum', () => {
+    const runEvent = loadSchema('run-event.schema.json');
+    const enumVals = ((runEvent.$defs as Record<string, { enum?: string[] }>).RunEventType?.enum) ?? [];
+    for (const name of ['tool.session.opened', 'tool.session.closed']) {
+      expect(enumVals.includes(name), why('run-event.schema.json', `${name} MUST be in the RunEventType enum`)).toBe(true);
+    }
+  });
+});

package/src/scenarios/trigger-bridge-delivery.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Durable trigger bridge — delivery model (RFC 0083 §C) — behavioral.
+ *
+ * Profile-gated on `openwop-trigger-bridge` (derived from the live discovery
+ * doc per RFC 0083 §D: the bridge advertised + a dead-letter sink + a durable
+ * source). Soft-skips when the profile isn't derived (default) / hard-fails
+ * under `OPENWOP_REQUIRE_BEHAVIOR=true`. The always-on wire-shape coverage
+ * lives in `trigger-bridge-shape.test.ts`; this asserts host BEHAVIOR via the
+ * `POST /v1/host/sample/trigger-bridge/deliver` seam + the test event-log seam:
+ *
+ *   1. DEDUP (§C-1) — the same `dedupKey` delivered twice is effectively-once:
+ *      exactly one `trigger.delivery.attempted { outcome:"delivered" }` for that
+ *      key (at-least-once collapses to once within the retention window).
+ *   2. RETRY → DEAD-LETTER (§C-2 + RFC 0053) — an exhausted retry policy lands a
+ *      terminal `trigger.delivery.attempted { outcome:"dead-lettered" }` and a
+ *      `trigger.subscription.state.changed { toState:"dead-lettered" }`; both
+ *      content-free (SR-1: ids/states/counters only).
+ *   3. CAUSATION (§C / RFC 0040) — a successful delivery's resulting run carries
+ *      `run.started.causationId` == the delivery id (trigger → run is resolvable
+ *      via `/ancestry`).
+ *
+ * Each leg soft-skips independently (seam absent / event-log seam absent).
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/trigger-bridge.md (§C)
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0083-durable-trigger-and-channel-bridge-profile.md
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/profiles.md (§openwop-trigger-bridge)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import {
+  isTriggerBridgeProfileAdvertised,
+  driveDelivery,
+  DELIVERY_OUTCOMES,
+  SUBSCRIPTION_STATES,
+} from '../lib/triggerBridge.js';
+import { queryTestEvents, isEventLogSeamAvailable, resetTestSeam } from '../lib/event-log-query.js';
+
+const CONTENT_FREE_FORBIDDEN = ['body', 'headers', 'payload', 'secret', 'credentials', 'token', 'apiKey'];
+
+function expectContentFree(payload: Record<string, unknown>, where: string): void {
+  for (const f of CONTENT_FREE_FORBIDDEN) {
+    expect(
+      !(f in payload),
+      driver.describe('RFC 0083 §C (SR-1)', `${where} MUST be content-free (no ${f})`),
+    ).toBe(true);
+  }
+}
+
+describe('trigger-bridge-delivery (RFC 0083 §C)', () => {
+  it('de-dups by dedupKey, retries to dead-letter, and links delivery→run causation', async () => {
+    if (!behaviorGate('openwop-trigger-bridge', await isTriggerBridgeProfileAdvertised())) return;
+    if (!(await isEventLogSeamAvailable())) return; // event-log seam absent — soft-skip
+
+    // ---- Leg 1: dedup → effectively-once (§C-1) ---------------------------
+    const dedup = await driveDelivery({ scenario: 'dedup', dedupKey: 'conformance-dedup-key', source: 'queue' });
+    if (dedup === null) return; // delivery seam unwired — soft-skip the whole behavioral suite
+    if (dedup.runId || dedup.subscriptionId) {
+      const subId = dedup.subscriptionId;
+      const q = await queryTestEvents(dedup.runId ?? '__dedup__', { type: 'trigger.delivery.attempted' });
+      if (q.ok) {
+        const deliveredForKey = q.events.filter(
+          (e) => e.payload.dedupKey === 'conformance-dedup-key' && e.payload.outcome === 'delivered',
+        );
+        // Effectively-once: a repeated dedupKey MUST NOT produce two 'delivered' attempts.
+        expect(
+          deliveredForKey.length <= 1,
+          driver.describe('trigger-bridge.md §C-1', 'a repeated dedupKey MUST be effectively-once (≤1 delivered attempt)'),
+        ).toBe(true);
+        for (const e of q.events) {
+          expect(
+            typeof e.payload.outcome === 'string' && DELIVERY_OUTCOMES.includes(e.payload.outcome as string),
+            driver.describe('run-event-payloads.schema.json#triggerDeliveryAttempted', 'outcome MUST be delivered|retrying|dead-lettered'),
+          ).toBe(true);
+          expectContentFree(e.payload, 'trigger.delivery.attempted');
+        }
+      }
+      void subId;
+    }
+
+    // ---- Leg 2: retry → dead-letter (§C-2 + RFC 0053) --------------------
+    const exhaust = await driveDelivery({ scenario: 'exhaust', source: 'webhook' });
+    if (exhaust && (exhaust.runId || exhaust.subscriptionId)) {
+      const key = exhaust.runId ?? '__exhaust__';
+      const dq = await queryTestEvents(key, { type: 'trigger.delivery.attempted' });
+      if (dq.ok && dq.events.length > 0) {
+        const terminal = dq.events.sort((a, b) => a.sequence - b.sequence)[dq.events.length - 1]!;
+        expect(
+          terminal.payload.outcome === 'dead-lettered',
+          driver.describe('trigger-bridge.md §C-2', 'an exhausted retry policy MUST terminate in a dead-lettered delivery'),
+        ).toBe(true);
+      }
+      const sq = await queryTestEvents(key, { type: 'trigger.subscription.state.changed' });
+      if (sq.ok && sq.events.length > 0) {
+        const toDeadLetter = sq.events.some((e) => e.payload.toState === 'dead-lettered');
+        expect(
+          toDeadLetter,
+          driver.describe('trigger-bridge.md §B', 'the subscription MUST transition to dead-lettered on exhaustion'),
+        ).toBe(true);
+        for (const e of sq.events) {
+          expect(
+            typeof e.payload.toState === 'string' && SUBSCRIPTION_STATES.includes(e.payload.toState as string),
+            driver.describe('trigger-bridge.md §B', 'toState MUST be in the four-state vocabulary'),
+          ).toBe(true);
+          expectContentFree(e.payload, 'trigger.subscription.state.changed');
+        }
+      }
+    }
+
+    // ---- Leg 3: delivery → run causation (§C / RFC 0040) -----------------
+    const delivered = await driveDelivery({ scenario: 'deliver', source: 'schedule' });
+    if (delivered?.runId) {
+      const rq = await queryTestEvents(delivered.runId, { type: 'run.started' });
+      if (rq.ok && rq.events[0]) {
+        expect(
+          typeof rq.events[0].causationId === 'string' && (rq.events[0].causationId as string).length > 0,
+          driver.describe('trigger-bridge.md §C / RFC 0040', 'the delivered run.started MUST carry the delivery causationId (resolvable via /ancestry)'),
+        ).toBe(true);
+      }
+    }
+
+    await resetTestSeam();
+  });
+});

package/src/scenarios/trigger-bridge-shape.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Durable trigger + channel bridge — subscription + events + profile shapes (RFC 0083).
+ *
+ * Always-on, server-free schema-shape probe. Verifies that:
+ *   - `trigger-subscription.schema.json` round-trips a conforming
+ *     `TriggerSubscription` and rejects the malformed (missing REQUIRED `state`;
+ *     an out-of-enum `source`; an unknown property under
+ *     `additionalProperties:false`).
+ *   - the four-state vocabulary (`active`/`paused`/`failed`/`dead-lettered`) is
+ *     stable on the subscription `state` + the event `fromState`/`toState`.
+ *   - the `trigger.subscription.state.changed` + `trigger.delivery.attempted`
+ *     payload $defs validate conforming content-free records and reject malformed
+ *     ones (a missing `outcome`; an out-of-enum `outcome`), and both event names
+ *     appear in the RunEventType enum.
+ *   - `capabilities.triggerBridge` (+ `webhooks.durable`) is declared.
+ *   - `deriveProfiles` surfaces `openwop-trigger-bridge` for a host advertising
+ *     the bridge + a dead-letter sink + a durable source, and withholds it when
+ *     the dead-letter sink is absent (the §D predicate's OR + sink requirement).
+ *
+ * Behavioral assertions (the dedup → retry → dead-letter → causation delivery
+ * loop) are gated on the `openwop-trigger-bridge` profile and land in
+ * `trigger-bridge-delivery.test.ts` (deferred per RFC 0083 §Conformance —
+ * reference host deferred). This scenario asserts the wire contract, not host
+ * behavior.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/trigger-bridge.md
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/profiles.md (§`openwop-trigger-bridge`)
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0083-durable-trigger-and-channel-bridge-profile.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { deriveProfiles } from '../lib/profiles.js';
+
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+
+function loadSchema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+
+const STATES = ['active', 'paused', 'failed', 'dead-lettered'] as const;
+
+describe('trigger-bridge-shape: TriggerSubscription (RFC 0083 §B, server-free)', () => {
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const sub = loadSchema('trigger-subscription.schema.json');
+  const validate = ajv.compile(sub);
+
+  it('a conforming subscription validates', () => {
+    expect(
+      validate({ subscriptionId: 'sub-1', source: 'webhook', state: 'active', dedupEnabled: true, retryPolicy: { maxAttempts: 8, backoff: 'exponential' }, webhookId: 'wh-1', secretFingerprint: 'fp-abc' }),
+      why('trigger-bridge.md §B', 'a conforming TriggerSubscription MUST validate'),
+    ).toBe(true);
+  });
+
+  it('rejects a missing REQUIRED state, an out-of-enum source, and an unknown property', () => {
+    expect(validate({ subscriptionId: 's', source: 'webhook' }), why('trigger-bridge.md §B', 'state is REQUIRED')).toBe(false);
+    expect(validate({ subscriptionId: 's', source: 'carrier-pigeon', state: 'active' }), why('trigger-bridge.md §B', 'source is a closed enum')).toBe(false);
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', body: 'inbound' }), why('trigger-bridge.md §B', 'TriggerSubscription MUST be additionalProperties:false')).toBe(false);
+  });
+
+  it('secretFingerprint MUST be bounded — a full 64-hex (unsalted-hash-smelling) digest is rejected', () => {
+    const truncated = 'a1b2c3d4e5f6a7b8';      // 16 hex — a truncated host-keyed fingerprint
+    const fullDigest = 'a'.repeat(64);          // 64 hex — smells like an unsalted SHA256(secret)
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', secretFingerprint: truncated }), why('trigger-bridge.md §B', 'a truncated fingerprint MUST validate')).toBe(true);
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', secretFingerprint: fullDigest }), why('SR-1', 'a full 64-hex digest MUST be rejected (brute-force oracle)')).toBe(false);
+  });
+
+  it('the state enum is exactly the four §B states', () => {
+    const stateEnum = ((sub.properties as Record<string, { enum?: string[] }>).state?.enum) ?? [];
+    expect([...stateEnum].sort(), why('trigger-bridge.md §B', 'the four-state vocabulary MUST be stable')).toEqual([...STATES].sort());
+  });
+});
+
+describe('trigger-bridge-shape: trigger.* events (RFC 0083 §C, server-free)', () => {
+  const payloads = loadSchema('run-event-payloads.schema.json');
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const compile = (defName: string) => ajv.compile({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $defs: (payloads as { $defs: Record<string, unknown> }).$defs,
+    $ref: `#/$defs/${defName}`,
+  } as Record<string, unknown>);
+
+  it('trigger.subscription.state.changed validates + reason is a CLOSED enum (no URL-bearing free text)', () => {
+    const v = compile('triggerSubscriptionStateChanged');
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active', toState: 'dead-lettered', reason: 'retry-exhausted' }), why('trigger-bridge.md §C', 'state-changed MUST validate')).toBe(true);
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active' }), why('trigger-bridge.md §C', 'toState is REQUIRED')).toBe(false);
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active', toState: 'failed', reason: 'https://attacker.example/leak?token=sk' }), why('SR-1', 'a free-form / URL-bearing reason MUST be rejected')).toBe(false);
+  });
+
+  it('trigger.delivery.attempted validates + enforces the outcome enum', () => {
+    const v = compile('triggerDeliveryAttempted');
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1, outcome: 'delivered', runId: 'run_x' }), why('trigger-bridge.md §C', 'delivery-attempted MUST validate')).toBe(true);
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1 }), why('trigger-bridge.md §C', 'outcome is REQUIRED')).toBe(false);
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1, outcome: 'exploded' }), why('trigger-bridge.md §C', 'outcome is a closed enum')).toBe(false);
+  });
+
+  it('both trigger event names appear in the RunEventType enum', () => {
+    const runEvent = loadSchema('run-event.schema.json');
+    const enumVals = ((runEvent.$defs as Record<string, { enum?: string[] }>).RunEventType?.enum) ?? [];
+    for (const name of ['trigger.subscription.state.changed', 'trigger.delivery.attempted']) {
+      expect(enumVals.includes(name), why('run-event.schema.json', `${name} MUST be in the RunEventType enum`)).toBe(true);
+    }
+  });
+});
+
+describe('trigger-bridge-shape: capability + profile derivation (RFC 0083 §A/§D, server-free)', () => {
+  it('capabilities.triggerBridge + webhooks.durable are declared', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const props = caps.properties as Record<string, { properties?: Record<string, unknown> }>;
+    expect(props.triggerBridge?.properties?.supported, why('trigger-bridge.md §A', 'triggerBridge.supported MUST be declared')).toBeDefined();
+    expect(props.webhooks?.properties?.durable, why('trigger-bridge.md §A', 'webhooks.durable MUST be declared')).toBeDefined();
+  });
+
+  const coreBase = {
+    protocolVersion: '1.0',
+    supportedEnvelopes: ['clarification.request'],
+    schemaVersions: {},
+    limits: { clarificationRounds: 1, schemaRounds: 1, envelopesPerTurn: 1 },
+  };
+
+  it('deriveProfiles surfaces openwop-trigger-bridge for bridge + deadLetter + a durable source', () => {
+    const c = { ...coreBase, triggerBridge: { supported: true }, deadLetter: { supported: true }, queueBus: { supported: true } } as Record<string, unknown>;
+    expect(deriveProfiles(c).includes('openwop-trigger-bridge'), why('profiles.md §openwop-trigger-bridge', 'bridge + sink + durable source MUST derive the profile')).toBe(true);
+  });
+
+  it('deriveProfiles withholds openwop-trigger-bridge when the dead-letter sink is absent', () => {
+    const c = { ...coreBase, triggerBridge: { supported: true }, webhooks: { durable: true } } as Record<string, unknown>;
+    expect(deriveProfiles(c).includes('openwop-trigger-bridge'), why('profiles.md §openwop-trigger-bridge', 'no deadLetter sink ⇒ MUST NOT derive the profile')).toBe(false);
+  });
+});