@openwop/openwop-conformance 2.45.9 → 2.45.11

package/src/lib/major-profile.ts

@@ -20,6 +20,7 @@
 
 import { capabilityFamily } from './discovery-capabilities.js';
 import { codemapV1toV2 } from './era2-seed.js';
+import { projectBoundId } from './bound-id.js';
 
 export interface MajorProfile {
   readonly major: number;
@@ -49,6 +50,16 @@ export interface MajorProfile {
    * unread observation and never guesses a name.
    */
   eventType(era1Name: string): string | undefined;
+  /** The trigger subscription collection, e.g. `/v1/trigger-subscriptions` or `/trigger-subscriptions`. */
+  readonly triggerSubscriptionsPath: string;
+  /** An id as one URL path segment: percent-encoded at v1, the `~` bound-id projection at v2 (`identity.md` §5). */
+  idSegment(id: string): string;
+  /**
+   * How a read of another tenant's id is refused. `not_found`: as an id never
+   * minted (v1, bare ids). `id_tenant_mismatch`: `403`, because a v2 bound id
+   * names its tenant and `identity.md` §5 requires the refusal to say so.
+   */
+  readonly foreignTenantRead: 'not_found' | 'id_tenant_mismatch';
 }
 
 const isRecord = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
@@ -68,6 +79,9 @@ export const MAJOR_PROFILES: Readonly<Record<number, MajorProfile>> = {
     // v1 budgets are driven through a host seam, not `createRun`.
     runBudget: () => null,
     eventType: (era1Name) => era1Name,
+    triggerSubscriptionsPath: '/v1/trigger-subscriptions',
+    idSegment: (id) => encodeURIComponent(id),
+    foreignTenantRead: 'not_found',
   },
   2: {
     major: 2,
@@ -82,6 +96,9 @@ export const MAJOR_PROFILES: Readonly<Record<number, MajorProfile>> = {
     },
     runBudget: (policy) => ({ configurable: { version: 1, budget: { ...policy } } }),
     eventType: (era1Name) => codemapV1toV2().get(era1Name),
+    triggerSubscriptionsPath: '/trigger-subscriptions',
+    idSegment: (id) => projectBoundId(id),
+    foreignTenantRead: 'id_tenant_mismatch',
   },
 };
 

package/src/lib/trigger-dead-letter-witness.ts

@@ -0,0 +1,143 @@
+/**
+ * The trigger dead-letter read witness (RFC 0232), leg 4's normative-surface
+ * path in `trigger-bridge-delivery.test.ts`.
+ *
+ * A dead-lettered trigger delivery started no run, so it is on no run's log.
+ * On a host that serves no test seam, the only place the suite can see it is
+ * `GET /v1/trigger-subscriptions/{id}/dead-letters`. The suite causes one
+ * unaided: it posts a body carrying a canary with a bad signature to a
+ * `required` subscription (RFC 0230 leg 2), then reads the subscription's
+ * dead letters.
+ *
+ * Two halves: {@link readDeadLetters} observes and asserts nothing; {@link judge}
+ * is pure, so each defect it convicts is proven in `trigger-dead-letter-witness.test.ts`.
+ *
+ * Not witnessed here: a record's `stateChange`. No wire surface causes a
+ * subscription state change on a host without the seam (RFC 0232 gap G2), so
+ * that half of leg 4 stays seam-witnessed.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { driver } from './driver.js';
+import { SCHEMAS_DIR } from './paths.js';
+
+export interface DeadLetterFacet {
+  readonly retentionDays: number;
+  readonly maxPageSize: number;
+}
+
+/** The advertised `triggerBridge.deadLetter` facet, or null when the host does not advertise it. */
+export function deadLetterFacet(discovery: unknown): DeadLetterFacet | null {
+  const d = discovery as { triggerBridge?: unknown; capabilities?: { triggerBridge?: unknown } } | null | undefined;
+  const tb = (d?.triggerBridge ?? d?.capabilities?.triggerBridge) as { deadLetter?: unknown } | undefined;
+  const f = tb?.deadLetter as { retentionDays?: unknown; maxPageSize?: unknown } | undefined;
+  if (f === undefined || f === null || typeof f !== 'object') return null;
+  if (typeof f.retentionDays !== 'number' || typeof f.maxPageSize !== 'number') return null;
+  return { retentionDays: f.retentionDays, maxPageSize: f.maxPageSize };
+}
+
+/** A canary no conforming record can contain: it only ever travels in the refused body. */
+export function freshCanary(): string {
+  return `openwop-canary-${randomBytes(9).toString('hex')}`;
+}
+
+export interface DeadLetterRead {
+  readonly status: number;
+  readonly json: unknown;
+}
+
+/** GET one page of a subscription's dead letters. Asserts nothing. */
+export async function readDeadLetters(subscriptionId: string, query: { limit?: number; cursor?: string } = {}): Promise<DeadLetterRead> {
+  const qs = new URLSearchParams();
+  if (query.limit !== undefined) qs.set('limit', String(query.limit));
+  if (query.cursor !== undefined) qs.set('cursor', query.cursor);
+  const suffix = qs.toString() === '' ? '' : `?${qs.toString()}`;
+  const res = await driver.get(`/v1/trigger-subscriptions/${encodeURIComponent(subscriptionId)}/dead-letters${suffix}`);
+  return { status: res.status, json: res.json };
+}
+
+let pageValidator: ((v: unknown) => boolean) & { errors?: unknown } | undefined;
+/** Validate a page against `trigger-dead-letter-page.schema.json` (v1), resolving the event payload `$ref`s. */
+export function validatePage(page: unknown): { ok: boolean; errors: string } {
+  if (pageValidator === undefined) {
+    const ajv = addFormats(new Ajv2020({ strict: false }));
+    const load = (n: string): Record<string, unknown> => JSON.parse(readFileSync(join(SCHEMAS_DIR, n), 'utf8')) as Record<string, unknown>;
+    const payloads = load('run-event-payloads.schema.json');
+    // Both carry `https://openwop.dev/spec/v1/…` ids, so the page's relative
+    // `run-event-payloads.schema.json#/$defs/…` refs resolve to this schema.
+    ajv.addSchema(payloads);
+    pageValidator = ajv.compile(load('trigger-dead-letter-page.schema.json'));
+  }
+  const ok = pageValidator(page) === true;
+  return { ok, errors: ok ? '' : JSON.stringify(pageValidator.errors ?? []).slice(0, 400) };
+}
+
+/** What the suite posted, so the judge can look for it in the record. */
+export interface RefusedPost {
+  readonly subscriptionId: string;
+  readonly canary: string;
+  readonly signature: string;
+  readonly signingSecret: string;
+  readonly retentionDays: number;
+}
+
+export type DeadLetterRule = 'page-valid' | 'present' | 'content-free' | 'attempt-shape' | 'no-state-change' | 'retention';
+
+export interface DeadLetterFinding {
+  readonly rule: DeadLetterRule;
+  readonly ok: boolean;
+  readonly message: string;
+}
+
+const DAY_MS = 86_400_000;
+/** One minute of slack either way: hosts round timestamps. */
+const RETENTION_SLACK_MS = 60_000;
+
+/**
+ * Judge one read against the refused post that should have produced a record.
+ * Pure. `validate` defaults to {@link validatePage}; the unit tests pass it in.
+ */
+export function judge(read: DeadLetterRead, post: RefusedPost, validate: (page: unknown) => { ok: boolean; errors: string } = validatePage): DeadLetterFinding[] {
+  const out: DeadLetterFinding[] = [];
+  if (read.status !== 200) {
+    out.push({ rule: 'page-valid', ok: false, message: `a host advertising triggerBridge.deadLetter MUST serve the read (answered ${read.status})` });
+    return out;
+  }
+  const v = validate(read.json);
+  out.push({ rule: 'page-valid', ok: v.ok, message: `the page MUST validate against trigger-dead-letter-page.schema.json${v.ok ? '' : `: ${v.errors}`}` });
+
+  const deliveries = ((read.json as { deliveries?: unknown } | undefined)?.deliveries ?? []) as Array<Record<string, unknown>>;
+  const mine = Array.isArray(deliveries)
+    ? deliveries.filter((r) => r !== null && typeof r === 'object' && r['reason'] === 'verification_failed' && r['subscriptionId'] === post.subscriptionId)
+    : [];
+  out.push({ rule: 'present', ok: mine.length >= 1, message: `the refused delivery MUST appear with reason "verification_failed" (saw ${Array.isArray(deliveries) ? deliveries.length : 0} record(s), ${mine.length} matching)` });
+
+  // Content-free: the canary, the signature and the secret appear nowhere in
+  // ANY record on the page, not just the matched one — a host that leaked them
+  // into a record it mis-labelled is still leaking them.
+  const text = JSON.stringify(read.json ?? null);
+  const leaked = [['the canary from the refused body', post.canary], ['the signature', post.signature], ['the signing secret', post.signingSecret]]
+    .filter(([, needle]) => needle !== '' && text.includes(needle as string)).map(([what]) => what);
+  const secretKey = post.signingSecret.replace(/^whsec_/, '');
+  if (secretKey !== '' && secretKey !== post.signingSecret && text.includes(secretKey)) leaked.push('the signing key');
+  out.push({ rule: 'content-free', ok: leaked.length === 0, message: `a record MUST NOT carry inbound content or credentials (found ${leaked.join(', ') || 'none'})` });
+
+  const rec = mine[0];
+  if (rec !== undefined) {
+    const attempt = rec['attempt'] as Record<string, unknown> | undefined;
+    const attemptOk = attempt !== undefined && attempt !== null && typeof attempt === 'object'
+      && attempt['outcome'] === 'dead-lettered' && attempt['subscriptionId'] === post.subscriptionId;
+    out.push({ rule: 'attempt-shape', ok: attemptOk, message: `attempt MUST be the dead-lettered trigger.delivery.attempted payload for this subscription (got ${JSON.stringify(attempt ?? null).slice(0, 200)})` });
+    out.push({ rule: 'no-state-change', ok: !('stateChange' in rec), message: 'a delivery refused by verification MUST NOT carry a stateChange (a refused event MUST NOT change the subscription\'s state)' });
+    const from = Date.parse(String(rec['deadLetteredAt']));
+    const to = Date.parse(String(rec['expiresAt']));
+    const want = post.retentionDays * DAY_MS;
+    const retentionOk = Number.isFinite(from) && Number.isFinite(to) && Math.abs((to - from) - want) <= RETENTION_SLACK_MS;
+    out.push({ rule: 'retention', ok: retentionOk, message: `expiresAt − deadLetteredAt MUST match retentionDays (${post.retentionDays}); got ${Number.isFinite(to - from) ? `${((to - from) / DAY_MS).toFixed(4)} days` : 'unparseable timestamps'}` });
+  }
+  return out;
+}

package/src/lib/trigger-delivery-witness.ts

@@ -0,0 +1,277 @@
+/**
+ * The trigger-bridge delivery witness on the normative surface (RFC 0230's
+ * signed ingest, RFC 0232's dead-letter read), shared by every major that
+ * serves it. What differs between majors — the subscription path, how an id
+ * becomes a path segment, event names, the page schema — is the profile row
+ * in `major-profile.ts`.
+ *
+ * Each leg OBSERVES and returns findings; it asserts nothing. The scenario file
+ * maps findings to requirement ids, and `trigger-delivery-witness.test.ts`
+ * proves every leg against a scratch double with one defect turned on.
+ *
+ * There is no seam path here. At major 2 no seam drives a trigger delivery, so
+ * a leg whose only surface is a seam is `inapplicable` (no party can cause the
+ * condition), never `blocked`.
+ *
+ * Today only `v2-trigger-bridge-delivery` and `v2-trigger-dead-letter-read` use
+ * it; the major-1 files keep their own inline legs, which the production hosts
+ * have already witnessed.
+ */
+
+import { driver } from './driver.js';
+import { readErrorCode } from './error-envelope.js';
+import type { MajorProfile } from './major-profile.js';
+import { freshWebhookId, standardWebhooksSignature } from './triggerBridge.js';
+import { freshCanary, judge as judgeDeadLetters, type DeadLetterRead } from './trigger-dead-letter-witness.js';
+
+export interface TriggerFinding {
+  readonly ok: boolean;
+  readonly doc: string;
+  readonly message: string;
+}
+export type LegOutcome =
+  | { readonly kind: 'skip'; readonly disposition: 'inapplicable' | 'blocked'; readonly reason: string }
+  | { readonly kind: 'observed'; readonly findings: readonly TriggerFinding[]; readonly note?: string };
+
+const isRecord = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+const f = (ok: boolean, doc: string, message: string): TriggerFinding => ({ ok, doc, message });
+
+/** What the host advertises for the trigger bridge at this major. */
+export interface TriggerAdverts {
+  readonly family: Record<string, unknown> | null;
+  readonly inboundSigning: boolean;
+  readonly deadLetter: { readonly retentionDays: number; readonly maxPageSize: number } | null;
+}
+
+export function adverts(profile: MajorProfile, doc: unknown): TriggerAdverts {
+  const family = profile.family(doc, 'triggerBridge');
+  const ingestion = isRecord(family?.['ingestion']) ? family!['ingestion'] as Record<string, unknown> : undefined;
+  const signing = ingestion?.['inboundSigning'];
+  const dl = isRecord(family?.['deadLetter']) ? family!['deadLetter'] as Record<string, unknown> : undefined;
+  return {
+    family,
+    inboundSigning: Array.isArray(signing) && signing.includes('standard-webhooks-1'),
+    deadLetter: dl !== undefined && typeof dl['retentionDays'] === 'number' && typeof dl['maxPageSize'] === 'number'
+      ? { retentionDays: dl['retentionDays'] as number, maxPageSize: dl['maxPageSize'] as number }
+      : null,
+  };
+}
+
+/** The gate every signed-path leg shares. */
+export function signedGate(a: TriggerAdverts): LegOutcome | null {
+  if (a.family === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise triggerBridge' };
+  if (!a.inboundSigning) return { kind: 'skip', disposition: 'inapplicable', reason: 'triggerBridge.ingestion.inboundSigning does not list standard-webhooks-1, and no other wire surface delivers a trigger event at this major' };
+  return null;
+}
+
+export interface Sub { readonly subscriptionId: string; readonly ingestUrl: string; readonly signingSecret: string }
+
+async function register(profile: MajorProfile, mode: 'none' | 'required'): Promise<Sub | string> {
+  const res = await driver.post(profile.triggerSubscriptionsPath, { source: 'webhook', workflowId: 'conformance-noop', verification: { mode } });
+  const body = res.json as { subscription?: { subscriptionId?: unknown }; binding?: { ingestUrl?: unknown; signingSecret?: unknown } } | undefined;
+  const subscriptionId = body?.subscription?.subscriptionId;
+  const ingestUrl = body?.binding?.ingestUrl;
+  const signingSecret = body?.binding?.signingSecret;
+  if (res.status !== 201 || typeof subscriptionId !== 'string' || typeof ingestUrl !== 'string' || typeof signingSecret !== 'string') {
+    return `POST ${profile.triggerSubscriptionsPath} answered ${res.status} without the binding (subscriptionId, ingestUrl, signingSecret)`;
+  }
+  return { subscriptionId, ingestUrl, signingSecret };
+}
+
+async function ingest(sub: Sub, body: string, opts: { webhookId?: string; signature?: string } = {}): Promise<{ status: number; json: Record<string, unknown> | undefined }> {
+  const id = opts.webhookId ?? freshWebhookId();
+  const ts = String(Math.floor(Date.now() / 1000));
+  const sig = opts.signature ?? standardWebhooksSignature(sub.signingSecret, id, ts, body);
+  const res = await driver.post(sub.ingestUrl, body, {
+    authenticated: false,
+    headers: { 'Content-Type': 'application/json', 'webhook-id': id, 'webhook-timestamp': ts, 'webhook-signature': sig },
+  });
+  return { status: res.status, json: isRecord(res.json) ? res.json : undefined };
+}
+
+export const BAD_SIGNATURE = 'v1,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
+const DOC_INGEST = 'webhooks.md §Inbound triggers';
+
+/** A registration that did not yield the binding is a host defect on an advertised surface. */
+function bindingFinding(reason: string): LegOutcome {
+  return { kind: 'observed', findings: [f(false, DOC_INGEST, `a host advertising inboundSigning MUST return the binding on webhook registration: ${reason}`)] };
+}
+
+/** Leg 1: a repeated `webhook-id` is effectively-once. */
+export async function dedupLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  const sub = await register(profile, 'none'); if (typeof sub === 'string') return bindingFinding(sub);
+  const body = JSON.stringify({ conformance: 'dedup' });
+  const webhookId = freshWebhookId();
+  const first = await ingest(sub, body, { webhookId });
+  const runId = first.json?.['runId'];
+  const again = await ingest(sub, body, { webhookId });
+  return { kind: 'observed', findings: [
+    f(first.status === 202, DOC_INGEST, `a signed delivery MUST answer 202 (got ${first.status})`),
+    f(typeof runId === 'string' && runId.length > 0, DOC_INGEST, 'a 202 MUST carry the started runId'),
+    f(again.status === 200, DOC_INGEST, `a repeated webhook-id MUST answer 200, starting no new run (got ${again.status})`),
+    f(again.json?.['outcome'] === 'duplicate', DOC_INGEST, `the dedup no-op MUST say outcome "duplicate" (got ${String(again.json?.['outcome'])})`),
+    f(again.json?.['runId'] === runId, DOC_INGEST, 'a dedup no-op MUST return the prior runId'),
+  ] };
+}
+
+/** Leg 2: a refused post starts no run and does not change the subscription's state. */
+export async function refusedLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  const sub = await register(profile, 'required'); if (typeof sub === 'string') return bindingFinding(sub);
+  const body = JSON.stringify({ conformance: 'dead-letter' });
+  const bad = await ingest(sub, body, { signature: BAD_SIGNATURE });
+  const read = await driver.get(`${profile.triggerSubscriptionsPath}/${profile.idSegment(sub.subscriptionId)}`);
+  const state = (read.json as { subscription?: { state?: unknown } } | undefined)?.subscription?.state;
+  const ok = await ingest(sub, body);
+  return { kind: 'observed', findings: [
+    f(bad.status === 401, DOC_INGEST, `a bad signature under required verification MUST answer 401 (got ${bad.status})`),
+    f(readErrorCode(bad.json) === 'signature_invalid', DOC_INGEST, `the refusal MUST carry signature_invalid (got ${String(readErrorCode(bad.json))})`),
+    f(bad.json?.['runId'] === undefined, DOC_INGEST, 'a failed required check MUST NOT start a run'),
+    f(state === 'active', DOC_INGEST, `a refused event MUST NOT change the subscription's state (read answered ${read.status}, state ${String(state)})`),
+    f(ok.status === 202, DOC_INGEST, `after a refused post the subscription MUST still deliver a correctly signed one (got ${ok.status})`),
+  ] };
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** Leg 3: the delivered run's `run.started` carries the delivery as `causationId`. */
+export async function causationLeg(profile: MajorProfile, a: TriggerAdverts, opts: { pollMs?: number; pollTries?: number } = {}): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  const sub = await register(profile, 'none'); if (typeof sub === 'string') return bindingFinding(sub);
+  const res = await ingest(sub, JSON.stringify({ conformance: 'causation' }));
+  const runId = res.json?.['runId'];
+  if (res.status !== 202 || typeof runId !== 'string' || runId.length === 0) {
+    return { kind: 'observed', findings: [f(false, DOC_INGEST, `a signed delivery MUST answer 202 with the started runId (got ${res.status} ${JSON.stringify(res.json ?? null).slice(0, 200)})`)] };
+  }
+  const startedType = profile.eventType('run.started');
+  const attemptType = profile.eventType('trigger.delivery.attempted');
+  if (startedType === undefined || attemptType === undefined) return { kind: 'skip', disposition: 'blocked', reason: 'the event codemap is not on disk in this layout, so this major\'s event names are unknown' };
+  let events: Array<Record<string, unknown>> = [];
+  let pollStatus = 0;
+  for (let i = 0; i < (opts.pollTries ?? 10); i++) {
+    const poll = await driver.get(`${profile.runsPath}/${profile.idSegment(runId)}/events/poll`);
+    pollStatus = poll.status;
+    events = ((poll.json as { events?: unknown } | undefined)?.events as Array<Record<string, unknown>> | undefined) ?? [];
+    if (events.some((e) => e['type'] === startedType)) break;
+    await sleep(opts.pollMs ?? 500);
+  }
+  const started = events.find((e) => e['type'] === startedType);
+  const causationId = started?.['causationId'];
+  const delivered = events.find((e) => e['type'] === attemptType && isRecord(e['payload']) && (e['payload'] as Record<string, unknown>)['outcome'] === 'delivered');
+  const findings = [
+    f(started !== undefined, 'webhooks.md §Inbound triggers', `a delivered run MUST emit ${startedType} (poll answered ${pollStatus}; saw ${events.map((e) => String(e['type'])).join(',') || 'none'})`),
+    f(typeof causationId === 'string' && causationId.length > 0, 'webhooks.md §Inbound triggers', `${startedType} MUST carry the delivery id as causationId`),
+  ];
+  if (delivered !== undefined) findings.push(f(causationId === delivered['eventId'], 'webhooks.md §Inbound triggers', `${startedType}.causationId MUST equal the delivered attempt's eventId`));
+  return { kind: 'observed', findings, note: delivered === undefined ? 'the delivered attempt event is not on the run log, so equality was not checked' : 'causationId equals the delivered attempt' };
+}
+
+/** GET one page of a subscription's dead letters at this major. Asserts nothing. */
+export async function readDeadLettersAt(profile: MajorProfile, subscriptionId: string, query: { limit?: number; cursor?: string } = {}, headers?: Record<string, string>): Promise<DeadLetterRead> {
+  const qs = new URLSearchParams();
+  if (query.limit !== undefined) qs.set('limit', String(query.limit));
+  if (query.cursor !== undefined) qs.set('cursor', query.cursor);
+  const suffix = qs.toString() === '' ? '' : `?${qs.toString()}`;
+  const res = await driver.get(`${profile.triggerSubscriptionsPath}/${profile.idSegment(subscriptionId)}/dead-letters${suffix}`, headers ? { headers } : {});
+  return { status: res.status, json: res.json };
+}
+
+/** Leg 4a: a dead-lettered (run-less) attempt is content-free, read through RFC 0232's read. */
+export async function runlessAttemptLeg(profile: MajorProfile, a: TriggerAdverts, validate: (page: unknown) => { ok: boolean; errors: string }): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  if (a.deadLetter === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'a dead-lettered attempt is on no run\'s log, and the host does not advertise triggerBridge.deadLetter, the only surface that reads it at this major' };
+  const sub = await register(profile, 'required'); if (typeof sub === 'string') return bindingFinding(sub);
+  const canary = freshCanary();
+  const bad = await ingest(sub, JSON.stringify({ conformance: 'runless-attempt', canary }), { signature: BAD_SIGNATURE });
+  const read = await readDeadLettersAt(profile, sub.subscriptionId);
+  const findings = [f(bad.status === 401, DOC_INGEST, `a bad signature under required verification MUST answer 401 (got ${bad.status})`)];
+  for (const j of judgeDeadLetters(read, { subscriptionId: sub.subscriptionId, canary, signature: BAD_SIGNATURE, signingSecret: sub.signingSecret, retentionDays: a.deadLetter.retentionDays }, validate)) {
+    findings.push(f(j.ok, DOC_INGEST, j.message));
+  }
+  return { kind: 'observed', findings, note: 'RFC 0232 dead-letter read' };
+}
+
+/** Leg 4b: a run-less state change. No surface causes one without a seam, and no seam exists at this major. */
+export function runlessStateChangeLeg(a: TriggerAdverts): LegOutcome {
+  if (a.family === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise triggerBridge' };
+  return { kind: 'skip', disposition: 'inapplicable', reason: 'no wire surface causes a trigger subscription state change, and no seam drives one at this major (RFC 0232 §E, gap G2)' };
+}
+
+// ---------------------------------------------------------------------------
+// The read's own rules (RFC 0232 §B).
+// ---------------------------------------------------------------------------
+
+function readGate(a: TriggerAdverts): LegOutcome | null {
+  if (a.family === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise triggerBridge' };
+  if (a.deadLetter === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise triggerBridge.deadLetter' };
+  if (!a.inboundSigning) return { kind: 'skip', disposition: 'inapplicable', reason: 'triggerBridge.deadLetter is advertised without inboundSigning, so the suite cannot cause a dead letter unaided' };
+  return null;
+}
+
+async function refusedTwice(profile: MajorProfile, n: number): Promise<Sub | string> {
+  const sub = await register(profile, 'required'); if (typeof sub === 'string') return sub;
+  for (let i = 0; i < n; i++) await ingest(sub, JSON.stringify({ conformance: 'dead-letter-read', i }), { signature: BAD_SIGNATURE });
+  return sub;
+}
+const deliveriesOf = (json: unknown): unknown[] => { const d = (json as { deliveries?: unknown } | undefined)?.deliveries; return Array.isArray(d) ? d : []; };
+const cursorOf = (json: unknown): unknown => (json as { nextCursor?: unknown } | undefined)?.nextCursor;
+
+export async function pagingLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = readGate(a); if (gate) return gate;
+  const sub = await refusedTwice(profile, 2); if (typeof sub === 'string') return bindingFinding(sub);
+  const first = await readDeadLettersAt(profile, sub.subscriptionId, { limit: 1 });
+  const cursor = cursorOf(first.json);
+  const second = typeof cursor === 'string' ? await readDeadLettersAt(profile, sub.subscriptionId, { limit: 1, cursor }) : undefined;
+  const big = await readDeadLettersAt(profile, sub.subscriptionId, { limit: a.deadLetter!.maxPageSize + 1 });
+  return { kind: 'observed', findings: [
+    f(first.status === 200, DOC_INGEST, `a host advertising triggerBridge.deadLetter MUST serve the read (got ${first.status})`),
+    f(deliveriesOf(first.json).length === 1, DOC_INGEST, `a page MUST NOT exceed limit (got ${deliveriesOf(first.json).length} for limit 1)`),
+    f(typeof cursor === 'string' && cursor.length > 0, DOC_INGEST, 'with two dead letters and limit 1, the page MUST carry nextCursor'),
+    f(second?.status === 200 && deliveriesOf(second.json).length === 1, DOC_INGEST, `the page's own cursor MUST continue to the second dead letter (got ${String(second?.status)})`),
+    f(big.status === 200, DOC_INGEST, `a limit above maxPageSize MUST be clamped, not refused (got ${big.status})`),
+  ] };
+}
+
+export async function cursorLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = readGate(a); if (gate) return gate;
+  const subA = await refusedTwice(profile, 2); if (typeof subA === 'string') return bindingFinding(subA);
+  const page = await readDeadLettersAt(profile, subA.subscriptionId, { limit: 1 });
+  const cursor = cursorOf(page.json);
+  if (typeof cursor !== 'string' || cursor.length === 0) {
+    return { kind: 'observed', findings: [f(false, DOC_INGEST, `with two dead letters and limit 1, the page MUST carry nextCursor (read answered ${page.status})`)] };
+  }
+  const subB = await refusedTwice(profile, 1); if (typeof subB === 'string') return bindingFinding(subB);
+  const cross = await readDeadLettersAt(profile, subB.subscriptionId, { cursor });
+  return { kind: 'observed', findings: [
+    f(cross.status === 400, DOC_INGEST, `a cursor minted for another subscription MUST be refused 400 (got ${cross.status})`),
+    f(readErrorCode(cross.json) === 'validation_error', DOC_INGEST, `the refusal MUST carry validation_error (got ${String(readErrorCode(cross.json))})`),
+  ] };
+}
+
+export async function tenantLeg(profile: MajorProfile, a: TriggerAdverts, otherTenantKey: string | undefined, ownKey: string): Promise<LegOutcome> {
+  const gate = readGate(a); if (gate) return gate;
+  if (!otherTenantKey) return { kind: 'skip', disposition: 'blocked', reason: 'OPENWOP_TEST_TENANT_B_API_KEY (a credential bound to a second tenant) is not set — the cross-tenant read cannot run' };
+  if (otherTenantKey.trim() === ownKey) return { kind: 'skip', disposition: 'blocked', reason: 'OPENWOP_TEST_TENANT_B_API_KEY equals OPENWOP_API_KEY — the second credential must resolve to a DIFFERENT tenant, or the leg measures nothing' };
+  const sub = await refusedTwice(profile, 1); if (typeof sub === 'string') return bindingFinding(sub);
+  const foreign = await readDeadLettersAt(profile, sub.subscriptionId, {}, { Authorization: `Bearer ${otherTenantKey}` });
+  const unknown = await readDeadLettersAt(profile, `${sub.subscriptionId}-never-minted`);
+  const noDisclosure = f(!JSON.stringify(foreign.json ?? null).includes('verification_failed'), DOC_INGEST, 'a foreign read MUST NOT disclose a record');
+  const unknownFinding = f(unknown.status === 404, DOC_INGEST, `an id the host never minted MUST answer 404 (got ${unknown.status})`);
+  if (profile.foreignTenantRead === 'id_tenant_mismatch') {
+    // identity.md §5: a bound id whose tenant segment is not the caller's is
+    // refused 403 id_tenant_mismatch, before any lookup, so it discloses nothing.
+    return { kind: 'observed', findings: [
+      f(foreign.status === 403, 'identity.md §5', `another tenant's bound id MUST be refused 403 (got ${foreign.status})`),
+      f(readErrorCode(foreign.json) === 'id_tenant_mismatch', 'identity.md §5', `the refusal MUST carry id_tenant_mismatch (got ${String(readErrorCode(foreign.json))})`),
+      noDisclosure,
+      unknownFinding,
+    ] };
+  }
+  return { kind: 'observed', findings: [
+    f(foreign.status === 404, DOC_INGEST, `another tenant's read MUST answer 404 (got ${foreign.status})`),
+    noDisclosure,
+    unknownFinding,
+    f(readErrorCode(foreign.json) === readErrorCode(unknown.json), DOC_INGEST, 'a foreign id MUST be answered exactly as an unknown one'),
+  ] };
+}

package/src/lib/trigger-double.ts

@@ -0,0 +1,131 @@
+/**
+ * A scratch double for the trigger bridge's normative surface at major 2: the
+ * signed ingest (RFC 0230) and the dead-letter read (RFC 0232). Each self-test
+ * turns on ONE defect to show `trigger-delivery-witness.ts` convicts it, and a
+ * standalone instance lets the scenario files themselves be run against it.
+ *
+ * A test double, not a host: it executes nothing, and nothing it does is
+ * evidence about any implementation.
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { unprojectBoundId } from './bound-id.js';
+import { standardWebhooksSignature } from './triggerBridge.js';
+
+/** The credential the double treats as a second tenant. */
+export const OTHER_TENANT_KEY = 'tenant-b-key';
+
+export type TriggerDefect =
+  | 'none' | 'dedup-new-run' | 'refused-starts-run' | 'refused-changes-state' | 'no-causation'
+  | 'record-leaks-canary' | 'refused-not-recorded' | 'refused-records-state-change' | 'wrong-retention'
+  | 'limit-ignored' | 'cursor-not-bound' | 'tenant-leak' | 'tenant-404';
+
+interface DoubleSub { id: string; n: number; mode: string; secret: string; state: string; seen: Map<string, string>; dead: Array<Record<string, unknown>> }
+
+export class TriggerDouble {
+  defect: TriggerDefect = 'none';
+  url = '';
+  private server: Server | undefined;
+  private subs = new Map<string, DoubleSub>();
+  private runs = new Map<string, Array<Record<string, unknown>>>();
+  private seq = 0;
+  discovery: Record<string, unknown> = { triggerBridge: { status: 'experimental', since: '2.45', witness: 'self', ingestion: { inboundSigning: ['standard-webhooks-1'] }, deadLetter: { retentionDays: 7, maxPageSize: 100 } } };
+
+  async start(): Promise<string> {
+    this.server = createServer((req, res) => { void this.handle(req, res); });
+    await new Promise<void>((r) => this.server!.listen(0, '127.0.0.1', r));
+    this.url = `http://127.0.0.1:${(this.server.address() as AddressInfo).port}`;
+    return this.url;
+  }
+  async stop(): Promise<void> { const s = this.server; if (s) { s.closeAllConnections(); await new Promise<void>((r) => s.close(() => r())); } }
+  reset(defect: TriggerDefect): void { this.defect = defect; this.subs.clear(); this.runs.clear(); }
+
+  private id(prefix: string): string { return `acme/${prefix}-${String(++this.seq).padStart(16, '0')}`; }
+  private send(res: ServerResponse, status: number, body: unknown): void { res.writeHead(status, { 'content-type': 'application/json' }); res.end(JSON.stringify(body)); }
+  private async raw(req: IncomingMessage): Promise<string> { const c: Buffer[] = []; for await (const x of req) c.push(x as Buffer); return Buffer.concat(c).toString('utf8'); }
+
+  private startRun(sub: DoubleSub): string {
+    const runId = this.id('run');
+    const attemptId = `evt${String(++this.seq).padStart(16, '0')}`;
+    this.runs.set(runId, [
+      { eventId: attemptId, type: 'trigger.delivery-attempted', payload: { subscriptionId: sub.id, dedupKey: 'opaque', attempt: 1, outcome: 'delivered', runId }, sequence: 1 },
+      { eventId: `evt${String(++this.seq).padStart(16, '0')}`, type: 'run.started', ...(this.defect === 'no-causation' ? {} : { causationId: attemptId }), payload: {}, sequence: 2 },
+    ]);
+    return runId;
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const u = new URL(req.url ?? '/', 'http://x');
+    const path = u.pathname;
+    if (req.method === 'GET' && path === '/.well-known/openwop') return this.send(res, 200, this.discovery);
+
+    if (req.method === 'POST' && path === '/trigger-subscriptions') {
+      const body = JSON.parse(await this.raw(req) || '{}') as { verification?: { mode?: string } };
+      const n = this.subs.size + 1;
+      const sub: DoubleSub = { id: this.id('sub'), n, mode: body.verification?.mode ?? 'none', secret: `whsec_${Buffer.from(`secret-${n}-bytes`).toString('base64')}`, state: 'active', seen: new Map(), dead: [] };
+      this.subs.set(sub.id, sub);
+      return this.send(res, 201, { subscription: { subscriptionId: sub.id, source: 'webhook', state: 'active' }, binding: { ingestUrl: `${this.url}/ingest/${n}`, signingSecret: sub.secret } });
+    }
+
+    const ing = /^\/ingest\/(\d+)$/.exec(path);
+    if (req.method === 'POST' && ing) {
+      const sub = [...this.subs.values()].find((s) => s.n === Number(ing[1]));
+      if (!sub) return this.send(res, 404, { error: 'not_found', message: 'no ingest' });
+      const body = await this.raw(req);
+      const id = String(req.headers['webhook-id'] ?? ''); const ts = String(req.headers['webhook-timestamp'] ?? '');
+      const good = req.headers['webhook-signature'] === standardWebhooksSignature(sub.secret, id, ts, body);
+      if (!good && sub.mode === 'required') {
+        if (this.defect !== 'refused-not-recorded') {
+          const at = Date.now();
+          sub.dead.unshift({
+            subscriptionId: sub.id, attemptEventId: `evt${String(++this.seq).padStart(16, '0')}`,
+            attempt: { subscriptionId: sub.id, dedupKey: 'opaque', attempt: 1, outcome: 'dead-lettered' },
+            reason: 'verification_failed',
+            deadLetteredAt: new Date(at).toISOString(),
+            expiresAt: new Date(at + (this.defect === 'wrong-retention' ? 1 : 7) * 86_400_000).toISOString(),
+            ...(this.defect === 'record-leaks-canary' ? { body } : {}),
+            ...(this.defect === 'refused-records-state-change' ? { stateChange: { subscriptionId: sub.id, source: 'webhook', fromState: 'active', toState: 'failed', reason: 'signature-invalid' } } : {}),
+          });
+        }
+        if (this.defect === 'refused-changes-state') sub.state = 'failed';
+        return this.send(res, 401, { error: 'signature_invalid', message: 'bad signature', ...(this.defect === 'refused-starts-run' ? { runId: this.startRun(sub) } : {}) });
+      }
+      const prior = sub.seen.get(id);
+      if (prior !== undefined && this.defect !== 'dedup-new-run') return this.send(res, 200, { outcome: 'duplicate', runId: prior });
+      const runId = this.startRun(sub);
+      sub.seen.set(id, runId);
+      return this.send(res, 202, { outcome: 'delivered', runId });
+    }
+
+    const poll = /^\/runs\/([^/]+)\/events\/poll$/.exec(path);
+    if (req.method === 'GET' && poll) {
+      const events = this.runs.get(unprojectBoundId(poll[1]!));
+      return events ? this.send(res, 200, { events }) : this.send(res, 404, { error: 'not_found', message: 'no run' });
+    }
+
+    const m = /^\/trigger-subscriptions\/([^/]+)(\/dead-letters)?$/.exec(path);
+    if (req.method === 'GET' && m) {
+      const auth = String(req.headers['authorization'] ?? '');
+      const sub = this.subs.get(unprojectBoundId(m[1]!));
+      // identity.md §5: tenant B reading acme's bound id is refused 403 before any lookup.
+      if (auth === `Bearer ${OTHER_TENANT_KEY}` && this.defect === 'tenant-404') return this.send(res, 404, { error: 'not_found', message: 'no such subscription' });
+      if (auth === `Bearer ${OTHER_TENANT_KEY}` && this.defect !== 'tenant-leak') return this.send(res, 403, { error: 'id_tenant_mismatch', message: 'tenant segment is not the caller\'s' });
+      if (!sub) return this.send(res, 404, { error: 'not_found', message: 'no such subscription' });
+      if (!m[2]) return this.send(res, 200, { subscription: { subscriptionId: sub.id, source: 'webhook', state: sub.state } });
+      const limit = Math.min(Number(u.searchParams.get('limit') ?? '100'), 100);
+      const cursor = u.searchParams.get('cursor');
+      let offset = 0;
+      if (cursor !== null) {
+        const [cid, off] = Buffer.from(cursor, 'base64url').toString('utf8').split('|');
+        if (cid !== sub.id && this.defect !== 'cursor-not-bound') return this.send(res, 400, { error: 'validation_error', message: 'cursor is for another subscription' });
+        offset = Number(off);
+      }
+      const size = this.defect === 'limit-ignored' ? sub.dead.length : limit;
+      const page = sub.dead.slice(offset, offset + size);
+      const next = offset + size < sub.dead.length ? Buffer.from(`${sub.id}|${offset + size}`).toString('base64url') : undefined;
+      return this.send(res, 200, { deliveries: page, ...(next ? { nextCursor: next } : {}) });
+    }
+    return this.send(res, 404, { error: 'not_found', message: `no route ${req.method} ${path}` });
+  }
+}