@openwop/openwop-conformance 2.35.0 → 2.36.0

package/src/scenarios/v2-a2ui-v09-surface.test.ts

@@ -0,0 +1,283 @@
+/**
+ * v2-a2ui-v09-surface — RFC 0209 §A.1, §A.2, §C.9, §C.11, §C.12, the seam-gated
+ * legs (suite 2.36.0, target major 2).
+ *
+ * `ui.a2ui-surface` at per-kind schema version 2 carries A2UI v0.9 messages. The
+ * suite cannot make a model emit a chosen envelope, so every leg here drives the
+ * v2 emit-surface seam (`POST /conformance/seams/sample/a2ui/emit-surface`,
+ * api/seams-v2.yaml), which a host MUST route through its production envelope
+ * admission. The server-free legs (profile ⊂ upstream, the excluded affordances,
+ * the pinned catalog, the kind carve-out) are corpus rows in
+ * `src/coherence/a2ui-v09-profile.test.ts`.
+ *
+ * Gates, all decided before any assertion so a skipped leg never records a
+ * partial witness: the seams profile advertised; `schemaVersions.kinds` giving
+ * the kind a floor of at least 2 (version-2 legs) or exactly 1 (the legacy leg);
+ * the seam answering something other than 404/405. Any of these absent ⇒
+ * `inapplicable` — a leg never passes on a non-answer.
+ *
+ * Every refusal leg carries an admitted control in the same run, so a host that
+ * refuses everything fails as surely as one that refuses nothing.
+ *
+ * @see RFCS/0209-v2-a2ui-surfaces-are-a2ui-v0-9.md
+ * @see spec/v2/ext/a2uiSurface/README.md
+ * @see spec/v2/core/events.md §"The envelope-kind catalog"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery } from '../lib/v2.js';
+import { seamsProfileAdvertised, SEAMS_PREFIX } from '../lib/seams.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { FIXTURES_DIR } from '../lib/paths.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+type Json = Record<string, unknown>;
+const KIND = 'ui.a2ui-surface';
+const SEAM = `${SEAMS_PREFIX}/sample/a2ui/emit-surface`;
+const FIXTURE = 'conformance-approval';
+const GATE_NODE = 'gate';
+const CATALOG = 'https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json';
+const clone = <T>(o: T): T => JSON.parse(JSON.stringify(o)) as T;
+const POSITIVE = JSON.parse(readFileSync(join(FIXTURES_DIR, 'a2ui-v09', 'positive-approve-brief.json'), 'utf8')) as Json;
+const V1_SURFACE: Json = { catalogVersion: '0.9.1', surface: { title: 'Kickoff', components: [{ component: 'heading', text: 'Kickoff', level: 2 }, { component: 'action.button', id: 'go', label: 'Go', action: { target: 'resume' } }] } };
+
+let seq = 0;
+const nonce = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+function envelope(schemaVersion: number, payload: unknown, opts: { trust?: 'trusted' | 'untrusted'; nodeId?: string } = {}): Json {
+  seq += 1;
+  const meta: Json = { source: 'ai-generation', ts: new Date().toISOString() };
+  if (opts.trust) meta['contentTrust'] = opts.trust;
+  return { type: KIND, schemaVersion, envelopeId: `env-0209-${nonce}-${seq}`, correlationId: `corr-0209-${nonce}-${seq}`, ...(opts.nodeId ? { nodeId: opts.nodeId } : {}), payload, meta };
+}
+/** A version-2 payload for `surfaceId` carrying `messages` (surfaceId stamped into each). */
+function v2(surfaceId: string, messages: Json[]): Json {
+  return { version: 'v0.9', catalogId: CATALOG, surfaceId, messages: messages.map((m) => { const c = clone(m); const body = Object.entries(c).find(([k]) => k !== 'version')?.[1] as Json; body['surfaceId'] = surfaceId; return c; }) };
+}
+const createMsg = (): Json => ({ version: 'v0.9', createSurface: { surfaceId: '', catalogId: CATALOG } });
+const componentsMsg = (): Json => clone((POSITIVE['messages'] as Json[])[1]);
+const dataMsg = (): Json => ({ version: 'v0.9', updateDataModel: { surfaceId: '', value: { name: 'x' } } });
+const deleteMsg = (): Json => ({ version: 'v0.9', deleteSurface: { surfaceId: '' } });
+const sid = (tag: string): string => `s-${tag}-${nonce}`;
+
+async function emit(runId: string, env: Json): Promise<OpenWOPResponse> {
+  return driver.post(SEAM, { runId, envelope: env });
+}
+const code = (r: OpenWOPResponse): string => `${r.status} ${readErrorCode(r.json) ?? ''}`.trim();
+
+async function waitStatus(runId: string, wanted: ReadonlySet<string>, timeoutMs: number): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}`);
+    const status = res.status === 200 ? String((res.json as { status?: unknown } | null)?.status ?? '') : null;
+    if (status !== null && wanted.has(status)) return status;
+    if (Date.now() > deadline) return status;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+type Ctx = { readonly floor: number; readonly strict: boolean; readonly runId: string };
+type Gate = { ok: true; ctx: Ctx } | { ok: false; kind: 'inapplicable' | 'blocked'; reason: string };
+
+/** Everything a leg needs, decided before its first assertion. `want` is the floor predicate. */
+async function gate(want: (floor: number) => boolean, wantText: string): Promise<Gate> {
+  const doc = await v2Discovery();
+  if (!doc) return { ok: false, kind: 'blocked', reason: 'v2 discovery unreachable' };
+  if (!seamsProfileAdvertised(doc)) return { ok: false, kind: 'inapplicable', reason: 'host does not advertise conformance.seamsProfile: openwop-conformance-seams-v2 — the emit-surface seam is the only way the suite can choose an envelope (RFC 0209 Falsifiability)' };
+  const kinds = ((doc['schemaVersions'] as Json | undefined)?.['kinds'] ?? {}) as Json;
+  const floor = typeof kinds[KIND] === 'number' ? (kinds[KIND] as number) : 0;
+  if (!want(floor)) return { ok: false, kind: 'inapplicable', reason: `schemaVersions.kinds["${KIND}"] is ${floor}; this leg needs ${wantText}` };
+  const strict = ((doc['envelopeStrictness'] as Json | undefined)?.['mode']) === 'strict';
+  const fixtures = Array.isArray(doc['fixtures']) ? (doc['fixtures'] as unknown[]) : [];
+  if (!fixtures.includes(FIXTURE)) return { ok: false, kind: 'inapplicable', reason: `the host does not advertise the ${FIXTURE} fixture the legs run inside` };
+  const create = await driver.post('/runs', { workflowId: FIXTURE });
+  if (create.status !== 201) return { ok: false, kind: 'blocked', reason: `POST /runs {workflowId: ${FIXTURE}} answered ${code(create)}` };
+  const runId = (create.json as { runId: string }).runId;
+  const status = await waitStatus(runId, new Set(['waiting-approval', 'completed', 'failed', 'cancelled']), 10_000);
+  if (status !== 'waiting-approval') return { ok: false, kind: 'blocked', reason: `${FIXTURE} did not suspend (status ${status})` };
+  // Probe the seam with a payload every host that has it must refuse (no createSurface first), so the probe records nothing.
+  const probe = await emit(runId, envelope(floor, floor >= 2 ? v2(sid('probe'), [dataMsg()]) : { catalogVersion: '9.9.9', surface: { components: [] } }));
+  if (probe.status === 404 || probe.status === 405) {
+    await driver.post(`/runs/${encodeURIComponent(runId)}/cancel`, {});
+    return { ok: false, kind: 'inapplicable', reason: `${SEAM} answered ${probe.status} — the emit-surface seam is not wired` };
+  }
+  return { ok: true, ctx: { floor, strict, runId } };
+}
+async function done(runId: string): Promise<void> { await driver.post(`/runs/${encodeURIComponent(runId)}/cancel`, {}); }
+
+/** Every subtree of `v`, depth-first. */
+function* subtrees(v: unknown): Generator<unknown> {
+  yield v;
+  if (Array.isArray(v)) for (const x of v) yield* subtrees(x);
+  else if (v && typeof v === 'object') for (const x of Object.values(v)) yield* subtrees(x);
+}
+const carries = (events: unknown[], payload: unknown): boolean => {
+  const want = JSON.stringify(payload);
+  return events.some((e) => [...subtrees((e as Json)['payload'])].some((s) => JSON.stringify(s) === want));
+};
+async function eventsOf(runId: string): Promise<unknown[]> {
+  const r = await driver.get(`/runs/${encodeURIComponent(runId)}/events/poll?timeout=1`);
+  const ev = (r.json as { events?: unknown } | null)?.events;
+  return Array.isArray(ev) ? ev : [];
+}
+
+describe('RFC 0209 §A.1 — the schema version selects the branch (seam-gated)', () => {
+  it('a version-2 envelope carrying a version-1 body is refused; the positive is admitted; above the floor is refused; below it follows envelopeStrictness', async () => {
+    const g = await gate((f) => f >= 2, 'a floor of at least 2');
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { runId, floor, strict } = g.ctx;
+    try {
+      const good = await emit(runId, envelope(2, v2(sid('vsb-good'), (POSITIVE['messages'] as Json[]))));
+      expect(good.status, req('openwop.requirement.0209.version-selects-branch', 'RFC 0209 §A.1', `the positive version-2 surface MUST be admitted (201), got ${code(good)}`)).toBe(201);
+      expect(typeof (good.json as { sequence?: unknown } | null)?.sequence, req('openwop.requirement.0209.version-selects-branch', 'api/seams-v2.yaml emitA2uiSurface', 'a 201 names the recording event sequence')).toBe('number');
+      const mixed = await emit(runId, envelope(2, V1_SURFACE));
+      expect(mixed.status, req('openwop.requirement.0209.version-selects-branch', 'RFC 0209 §A.1', `a schemaVersion 2 envelope with a payloadV1 body MUST be refused — validating against the anyOf union would admit it (got ${code(mixed)})`)).toBe(422);
+      expect(readErrorCode(mixed.json), req('openwop.requirement.0209.version-selects-branch', 'spec/v2/ext/a2uiSurface/README.md §Versions', 'the refusal is envelope_invalid')).toBe('envelope_invalid');
+      const above = await emit(runId, envelope(floor + 1, v2(sid('vsb-above'), [createMsg()])));
+      expect(code(above), req('openwop.requirement.0209.version-selects-branch', 'events.md §"The envelope-kind catalog"', 'a schemaVersion above the floor MUST be refused with unknown_schema_version whatever the strictness')).toBe('422 unknown_schema_version');
+      const below = await emit(runId, envelope(1, v2(sid('vsb-below'), [createMsg()])));
+      if (strict) {
+        expect(code(below), req('openwop.requirement.0209.version-selects-branch', 'events.md §"The envelope-kind catalog"', 'under strict, a schemaVersion 1 envelope below floor 2 MUST be refused with unknown_schema_version')).toBe('422 unknown_schema_version');
+      } else {
+        expect(below.status, req('openwop.requirement.0209.version-selects-branch', 'events.md §"The envelope-kind catalog"', `under warn, a schemaVersion 1 envelope is validated against the advertised version 2; a payloadV2 body is therefore admitted with a drift log (got ${code(below)})`)).toBe(201);
+        const belowV1 = await emit(runId, envelope(1, V1_SURFACE));
+        expect(code(belowV1), req('openwop.requirement.0209.version-selects-branch', 'RFC 0209 §A.1', 'under warn, a schemaVersion 1 envelope with a payloadV1 body is validated against version 2 and MUST be refused')).toBe('422 envelope_invalid');
+      }
+    } finally { await done(runId); }
+  });
+});
+
+describe('RFC 0209 §C.9 — the fold is guarded at record time (seam-gated)', () => {
+  it('no first createSurface, a message after deleteSurface, and a second createSurface are each refused; the valid steps are admitted', async () => {
+    const g = await gate((f) => f >= 2, 'a floor of at least 2');
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { runId } = g.ctx;
+    const R = (why: string) => req('openwop.requirement.0209.fold-guarded', 'RFC 0209 §C.9', why);
+    try {
+      const orphan = await emit(runId, envelope(2, v2(sid('fold-a'), [componentsMsg()])));
+      expect(code(orphan), R('the first envelope for a surfaceId MUST begin with createSurface — updateComponents alone is refused, not recorded')).toBe('422 envelope_invalid');
+      const bCreate = await emit(runId, envelope(2, v2(sid('fold-b'), [createMsg(), componentsMsg()])));
+      expect(bCreate.status, R(`createSurface + updateComponents for a new surfaceId MUST be admitted (control), got ${code(bCreate)}`)).toBe(201);
+      const bDelete = await emit(runId, envelope(2, v2(sid('fold-b'), [deleteMsg()])));
+      expect(bDelete.status, R(`deleteSurface on a live surface MUST be admitted (control), got ${code(bDelete)}`)).toBe(201);
+      const bAfter = await emit(runId, envelope(2, v2(sid('fold-b'), [dataMsg()])));
+      expect(code(bAfter), R('a message after deleteSurface without a new createSurface MUST be refused')).toBe('422 envelope_invalid');
+      const cCreate = await emit(runId, envelope(2, v2(sid('fold-c'), [createMsg()])));
+      expect(cCreate.status, R(`createSurface for a new surfaceId MUST be admitted (control), got ${code(cCreate)}`)).toBe(201);
+      const cAgain = await emit(runId, envelope(2, v2(sid('fold-c'), [createMsg()])));
+      expect(code(cAgain), R('createSurface for a live surfaceId MUST be refused')).toBe('422 envelope_invalid');
+      const bRecreate = await emit(runId, envelope(2, v2(sid('fold-b'), [createMsg(), dataMsg()])));
+      expect(bRecreate.status, R(`a new createSurface after deleteSurface MUST be admitted (control), got ${code(bRecreate)}`)).toBe(201);
+    } finally { await done(runId); }
+  });
+});
+
+describe('RFC 0209 §A.2 — the cross-field rules are checked at admission (seam-gated)', () => {
+  it('a createSurface.catalogId differing from the payload catalogId is refused', async () => {
+    const g = await gate((f) => f >= 2, 'a floor of at least 2');
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { runId } = g.ctx;
+    try {
+      const p = v2(sid('cat'), [createMsg()]);
+      ((p['messages'] as Json[])[0]['createSurface'] as Json)['catalogId'] = 'https://a2ui.org/specification/v0_9/catalogs/other/catalog.json';
+      const r = await emit(runId, envelope(2, p));
+      expect(code(r), req('openwop.requirement.0209.catalog-equality', 'RFC 0209 §A.2', 'a createSurface.catalogId MUST equal the payload catalogId; a differing one is refused, not recorded')).toBe('422 envelope_invalid');
+      const ok = await emit(runId, envelope(2, v2(sid('cat-ok'), [createMsg()])));
+      expect(ok.status, req('openwop.requirement.0209.catalog-equality', 'RFC 0209 §A.2', `the same payload with equal catalogIds MUST be admitted (control), got ${code(ok)}`)).toBe(201);
+    } finally { await done(runId); }
+  });
+
+  it('a message whose surfaceId differs from the payload surfaceId is refused', async () => {
+    const g = await gate((f) => f >= 2, 'a floor of at least 2');
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { runId } = g.ctx;
+    try {
+      const p = v2(sid('sid'), [createMsg(), componentsMsg()]);
+      ((p['messages'] as Json[])[1]['updateComponents'] as Json)['surfaceId'] = sid('sid-other');
+      const r = await emit(runId, envelope(2, p));
+      expect(code(r), req('openwop.it.v2-a2ui-v09-surface.surface-id-equality', 'RFC 0209 §A.2', 'every message surfaceId MUST equal the payload surfaceId — the schema cannot express it, so the engine MUST refuse a mismatch')).toBe('422 envelope_invalid');
+      const ok = await emit(runId, envelope(2, v2(sid('sid'), [createMsg(), componentsMsg()])));
+      expect(ok.status, req('openwop.it.v2-a2ui-v09-surface.surface-id-equality', 'RFC 0209 §A.2', `the refused envelope left no trace: the same surfaceId is still new and admits createSurface (got ${code(ok)})`)).toBe(201);
+    } finally { await done(runId); }
+  });
+});
+
+describe('RFC 0209 §C.11 — recorded surfaces are returned as recorded (seam-gated)', () => {
+  it('a recorded version-2 surface is returned byte-equal on poll and carried by a fork at a later fromSeq', async () => {
+    const g = await gate((f) => f >= 2, 'a floor of at least 2');
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { runId } = g.ctx;
+    try {
+      const payload = v2(sid('rec'), (POSITIVE['messages'] as Json[]));
+      const r = await emit(runId, envelope(2, payload));
+      expect(r.status, req('openwop.it.v2-a2ui-v09-surface.recorded-as-recorded', 'RFC 0209 §C.11', `the positive surface MUST be admitted, got ${code(r)}`)).toBe(201);
+      const sequence = (r.json as { sequence: number }).sequence;
+      const events = await eventsOf(runId);
+      expect(carries(events, payload), req('openwop.it.v2-a2ui-v09-surface.recorded-as-recorded', 'RFC 0209 §C.11', 'the run\'s poll MUST return the recorded surface payload byte-equal — no surface is regenerated')).toBe(true);
+      const fork = await driver.post(`/runs/${encodeURIComponent(runId)}:fork`, { mode: 'replay', fromSeq: sequence + 1 });
+      expect(fork.status, req('openwop.it.v2-a2ui-v09-surface.recorded-as-recorded', 'RFC 0209 §C.11', `POST :fork at fromSeq ${sequence + 1} MUST answer 201, got ${code(fork)}`)).toBe(201);
+      const forkId = (fork.json as { runId: string }).runId;
+      expect(carries(await eventsOf(forkId), payload), req('openwop.it.v2-a2ui-v09-surface.recorded-as-recorded', 'RFC 0209 §C.11', 'a fork at a fromSeq after the surface MUST carry it unchanged')).toBe(true);
+      await done(forkId);
+    } finally { await done(runId); }
+  });
+
+  it('a version-1 surface recorded at floor 1 is returned byte-equal on poll and carried by a fork', async () => {
+    const g = await gate((f) => f === 1, 'a floor of exactly 1 — a host whose floor is 2 has no admission path for a version-1 surface, and the suite cannot seed one (RFC 0209 §C.11 holds for what it recorded before raising the floor)');
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { runId } = g.ctx;
+    try {
+      const r = await emit(runId, envelope(1, V1_SURFACE));
+      expect(r.status, req('openwop.requirement.0209.legacy-readable', 'RFC 0209 §C.11', `a version-1 surface at floor 1 MUST be admitted, got ${code(r)}`)).toBe(201);
+      const sequence = (r.json as { sequence: number }).sequence;
+      expect(carries(await eventsOf(runId), V1_SURFACE), req('openwop.requirement.0209.legacy-readable', 'RFC 0209 §C.11', 'the poll MUST return the version-1 surface byte-equal')).toBe(true);
+      const fork = await driver.post(`/runs/${encodeURIComponent(runId)}:fork`, { mode: 'replay', fromSeq: sequence + 1 });
+      expect(fork.status, req('openwop.requirement.0209.legacy-readable', 'RFC 0209 §C.11', `POST :fork MUST answer 201, got ${code(fork)}`)).toBe(201);
+      const forkId = (fork.json as { runId: string }).runId;
+      expect(carries(await eventsOf(forkId), V1_SURFACE), req('openwop.requirement.0209.legacy-readable', 'RFC 0209 §C.11', 'a fork at a later fromSeq MUST carry the version-1 surface unchanged')).toBe(true);
+      await done(forkId);
+    } finally { await done(runId); }
+  });
+});
+
+describe('RFC 0209 §C.12 — trust is sticky across the fold (seam-gated)', () => {
+  it('one untrusted update taints a trusted surface, a later trusted update does not launder it, and the approval does not advance; an all-trusted surface does', async () => {
+    const g = await gate((f) => f >= 2, 'a floor of at least 2');
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { runId } = g.ctx;
+    const R = (why: string) => req('openwop.requirement.0209.taint-sticky', 'RFC 0209 §C.12', why);
+    let controlRun: string | null = null;
+    try {
+      const s = sid('taint');
+      const steps = [
+        await emit(runId, envelope(2, v2(s, [createMsg(), componentsMsg()]), { nodeId: GATE_NODE })),
+        await emit(runId, envelope(2, v2(s, [componentsMsg()]), { nodeId: GATE_NODE, trust: 'untrusted' })),
+        await emit(runId, envelope(2, v2(s, [componentsMsg()]), { nodeId: GATE_NODE, trust: 'trusted' })),
+      ];
+      steps.forEach((r, i) => expect(r.status, R(`surface step ${i} MUST be recorded (201) — an untrusted envelope is recorded and tainted, not refused; got ${code(r)}`)).toBe(201));
+      const resolve = await driver.post(`/runs/${encodeURIComponent(runId)}/interrupts/${GATE_NODE}`, { resumeValue: { action: 'accept' } });
+      expect(resolve.status >= 400 && resolve.status < 500, R(`resolving the approval bound to a tainted surface MUST be refused (4xx), got ${code(resolve)}`)).toBe(true);
+      const text = JSON.stringify(resolve.json ?? {});
+      expect(text.includes('untrusted_content_blocks_approval'), R(`the refusal MUST name untrusted_content_blocks_approval (in error.details or message): ${text.slice(0, 300)}`)).toBe(true);
+      expect(await waitStatus(runId, new Set(['waiting-approval']), 1_000), R('a refused resolve MUST NOT advance the run — the approval stays pending')).toBe('waiting-approval');
+
+      // Control: the same fold with no untrusted envelope MUST let the approval advance, or the refusal above proves nothing.
+      const ctl = await driver.post('/runs', { workflowId: FIXTURE });
+      expect(ctl.status, R(`control run MUST start, got ${code(ctl)}`)).toBe(201);
+      controlRun = (ctl.json as { runId: string }).runId;
+      expect(await waitStatus(controlRun, new Set(['waiting-approval', 'completed', 'failed', 'cancelled']), 10_000), R('the control run MUST suspend on its approval')).toBe('waiting-approval');
+      const c = sid('trusted');
+      const c1 = await emit(controlRun, envelope(2, v2(c, [createMsg(), componentsMsg()]), { nodeId: GATE_NODE }));
+      const c2 = await emit(controlRun, envelope(2, v2(c, [componentsMsg()]), { nodeId: GATE_NODE, trust: 'trusted' }));
+      expect([c1.status, c2.status], R('the control surface MUST be recorded')).toEqual([201, 201]);
+      const ok = await driver.post(`/runs/${encodeURIComponent(controlRun)}/interrupts/${GATE_NODE}`, { resumeValue: { action: 'accept' } });
+      expect(ok.status, R(`resolving the approval bound to an all-trusted surface MUST succeed (control), got ${code(ok)}`)).toBe(200);
+    } finally {
+      await done(runId);
+      if (controlRun) await done(controlRun);
+    }
+  });
+});

package/src/scenarios/v2-advertised-fixtures-exist.test.ts

@@ -41,7 +41,7 @@ import { softSkip } from '../lib/soft-skip.js';
 import { req } from '../lib/requirement-ids.js';
 
 const ID = 'openwop.requirement.0168.advertised-fixtures-exist';
-const DOC = 'spec/v2/core/conformance.md §Fixtures';
+const DOC = 'RFC 0168 §C.3';
 /** Creating one run per advertised fixture would be a load test, not a check. */
 const SAMPLE = 5;
 
@@ -58,7 +58,7 @@ function advertisedIds(doc: Record<string, unknown>): string[] {
   return Array.isArray(raw) ? raw.filter((x): x is string => typeof x === 'string') : [];
 }
 
-describe('v2-advertised-fixtures-exist (conformance.md §Fixtures)', () => {
+describe('v2-advertised-fixtures-exist (RFC 0168 §C.3)', () => {
   it('a sampled advertised fixture is actually creatable, not just listed', async () => {
     const doc = await v2Discovery().catch(() => null);
     if (!doc) return softSkip('blocked', 'v2 discovery unreachable');

package/src/scenarios/v2-artifact-a2a-shape.test.ts

@@ -0,0 +1,122 @@
+/**
+ * v2-artifact-a2a-shape — RFC 0205 §A, the behavioural legs (suite 2.36.0,
+ * target major 2).
+ *
+ * `getArtifact` (`GET /runs/{runId}/artifacts/{artifactId}`) MAY answer an A2A
+ * `Artifact` when the client's `Accept` prefers `application/a2a+json`. The
+ * discriminator is the response `Content-Type`: a `200` served as
+ * `application/a2a+json` MUST validate against `schemas/v2/artifact.schema.json`,
+ * its `artifactId` MUST equal the path segment, and a `url` Part in it MUST NOT
+ * resolve beyond the caller's `artifacts:read` authorization.
+ *
+ * The suite needs an artifact it can name, so the legs run inside the
+ * `conformance-artifact-emit` fixture (one node that produces one artifact and
+ * emits `artifact.created`). Gates, decided before any assertion so a skipped
+ * leg never records a partial witness:
+ *   - the fixture is not advertised ⇒ `inapplicable`;
+ *   - the host answers `application/json` (it MAY; SHOULD offer the A2A shape)
+ *     ⇒ `inapplicable`, never a pass;
+ *   - the `url` leg: no `url` Part in the body ⇒ `inapplicable`; a `url` Part
+ *     but no `OPENWOP_TEST_TENANT_B_API_KEY` ⇒ `blocked`.
+ * The server-free legs (the schemas against A2A v1.0.1) are corpus rows in
+ * `src/coherence/a2a-parts-schemas.test.ts`.
+ *
+ * @see RFCS/0205-run-artifacts-and-turns-speak-a2a-parts.md
+ * @see spec/v2/core/runs.md §"Annotations, artifacts, eval summary"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { loadEnv } from '../lib/env.js';
+import { v2Discovery, v2Validator } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+type Json = Record<string, unknown>;
+const FIXTURE = 'conformance-artifact-emit';
+const A2A = 'application/a2a+json';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+async function waitTerminal(runId: string, timeoutMs: number): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}`);
+    const status = res.status === 200 ? String((res.json as { status?: unknown } | null)?.status ?? '') : null;
+    if (status !== null && TERMINAL.has(status)) return status;
+    if (Date.now() > deadline) return status;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+}
+
+type Read = { runId: string; artifactId: string; status: number; contentType: string; body: unknown };
+type Gate = { ok: true; read: Read } | { ok: false; kind: 'inapplicable' | 'blocked'; reason: string };
+
+let memo: Promise<Gate> | undefined;
+/** One run, one artifact, one negotiated read — shared by both legs. */
+function negotiatedRead(): Promise<Gate> {
+  memo ??= (async (): Promise<Gate> => {
+    const doc = await v2Discovery();
+    if (!doc) return { ok: false, kind: 'blocked', reason: 'v2 discovery unreachable' };
+    const fixtures = Array.isArray(doc['fixtures']) ? (doc['fixtures'] as unknown[]) : [];
+    if (!fixtures.includes(FIXTURE)) return { ok: false, kind: 'inapplicable', reason: `no artifact-producing fixture: the host does not advertise ${FIXTURE} (RFC 0205 register G2)` };
+    const create = await driver.post('/runs', { workflowId: FIXTURE });
+    if (create.status !== 201) return { ok: false, kind: 'blocked', reason: `POST /runs {workflowId: ${FIXTURE}} answered ${create.status}` };
+    const runId = String((create.json as { runId?: unknown } | null)?.runId ?? '');
+    const status = await waitTerminal(runId, 15_000);
+    if (status !== 'completed') return { ok: false, kind: 'blocked', reason: `${FIXTURE} did not complete (status ${status})` };
+    const poll = await driver.get(`/runs/${encodeURIComponent(runId)}/events/poll?timeout=1`);
+    const events = ((poll.json as { events?: unknown } | null)?.events ?? []) as Json[];
+    const created = Array.isArray(events) ? events.find((e) => e['type'] === 'artifact.created') : undefined;
+    const artifactId = String(((created?.['payload'] ?? {}) as Json)['artifactId'] ?? '');
+    if (!artifactId) return { ok: false, kind: 'blocked', reason: `${FIXTURE} completed without an artifact.created event naming an artifactId` };
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}`, { headers: { Accept: `${A2A}, application/json;q=0.5` } });
+    const contentType = (res.headers.get('content-type') ?? '').split(';')[0]?.trim().toLowerCase() ?? '';
+    return { ok: true, read: { runId, artifactId, status: res.status, contentType, body: res.json } };
+  })();
+  return memo;
+}
+
+describe('RFC 0205 §A.2 — an application/a2a+json artifact read is an A2A Artifact', () => {
+  it('a getArtifact answered as application/a2a+json validates against artifact.schema.json', async () => {
+    const g = await negotiatedRead();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { status, contentType, body } = g.read;
+    if (status === 404 || status === 405) return softSkip('inapplicable', `getArtifact answered ${status} for the artifact the fixture announced — the read is not implemented`);
+    if (status === 200 && contentType === 'application/json') return softSkip('inapplicable', 'host does not serve application/a2a+json (SHOULD); it answered application/json, whose shape is implementation-defined');
+    expect(status, req('openwop.requirement.0205.artifact-a2a-shape', 'spec/v2/core/runs.md', `getArtifact for an artifact the run announced MUST answer 200 (got ${status}, ${contentType})`)).toBe(200);
+    expect(contentType, req('openwop.requirement.0205.artifact-a2a-shape', 'RFC 0205 §A.1', `a 200 is application/json or ${A2A}; got ${contentType}`)).toBe(A2A);
+    const r = v2Validator('artifact')(body);
+    expect(r.ok, req('openwop.requirement.0205.artifact-a2a-shape', 'RFC 0205 §A.2', `a body served as ${A2A} MUST validate against schemas/v2/artifact.schema.json: ${r.errors}`)).toBe(true);
+  });
+
+  it('the artifactId of an application/a2a+json body equals the {artifactId} path segment', async () => {
+    const g = await negotiatedRead();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { artifactId, status, contentType, body } = g.read;
+    if (status !== 200 || contentType !== A2A) return softSkip('inapplicable', `no ${A2A} artifact body to compare (status ${status}, ${contentType || 'no content type'}); the host does not serve the A2A shape (SHOULD)`);
+    expect(body !== null && typeof body === 'object', req('openwop.requirement.0205.artifact-id-matches-path', 'RFC 0205 §A.2', 'an application/a2a+json body is a JSON object')).toBe(true);
+    expect((body as Json)['artifactId'], req('openwop.requirement.0205.artifact-id-matches-path', 'RFC 0205 §A.2', 'the body artifactId MUST equal the {artifactId} path segment')).toBe(artifactId);
+  });
+});
+
+describe('RFC 0205 §A.3 — a url Part does not resolve beyond the caller\'s authorization', () => {
+  it('the url of a url Part answers no 2xx to a second tenant or to no credential', async () => {
+    const g = await negotiatedRead();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const { status, contentType, body } = g.read;
+    if (status !== 200 || contentType !== A2A) return softSkip('inapplicable', `no ${A2A} artifact body to read a url Part from (status ${status}, ${contentType || 'no content type'})`);
+    const parts = Array.isArray((body as Json)['parts']) ? ((body as Json)['parts'] as Json[]) : [];
+    const urls = parts.map((p) => p['url']).filter((u): u is string => typeof u === 'string');
+    if (urls.length === 0) return softSkip('inapplicable', 'the artifact carries no url Part (the host emits data/text/raw Parts only; RFC 0205 register G3)');
+    const tenantB = process.env['OPENWOP_TEST_TENANT_B_API_KEY'];
+    if (!tenantB) return softSkip('blocked', 'the artifact carries a url Part but OPENWOP_TEST_TENANT_B_API_KEY is not supplied — the second-tenant leg cannot run');
+    const base = loadEnv().baseUrl;
+    for (const u of urls) {
+      const abs = new URL(u, base).toString();
+      const asB = await fetch(abs, { headers: { Authorization: `Bearer ${tenantB}` }, redirect: 'manual' });
+      expect(asB.status >= 200 && asB.status < 300, req('openwop.requirement.0205.artifact-url-part-scoped', 'RFC 0205 §A.3', `${abs} MUST NOT answer 2xx to tenant B's credential (got ${asB.status})`)).toBe(false);
+      const anon = await fetch(abs, { redirect: 'manual' });
+      expect(anon.status >= 200 && anon.status < 300, req('openwop.requirement.0205.artifact-url-part-scoped', 'RFC 0205 §A.3', `${abs} MUST NOT answer 2xx with no credential (got ${anon.status})`)).toBe(false);
+    }
+  });
+});

package/src/scenarios/v2-auth-challenge.test.ts

@@ -0,0 +1,119 @@
+/**
+ * RFC 0200 §B.1 — the `WWW-Authenticate` challenge on a refusal (suite 2.36.0, target
+ * major 2; gated on an advertised `oauth2`/`oidc` lane).
+ *
+ * HTTP itself has always required it ("The server generating a 401 response MUST send a
+ * WWW-Authenticate header field", RFC 9110 §15.5.2) and no OpenWOP host sent one. §B.1
+ * makes it a MUST on a host bound by §A, and pins the two things a generic client needs
+ * that a bare `Bearer` does not give: where the metadata is, and — on a scope refusal —
+ * EVERY scope the operation requires, because `auth.md` §Scopes says `runs:cancel` does
+ * not imply `runs:read`, so a single-scope hint can send a client to ask for the wrong
+ * grant.
+ *
+ * Two legs, one requirement id each:
+ *
+ *   1. `challenge-401` — a no-credential read carries `Bearer` with `resource_metadata`
+ *      equal to the §A.2 URL and NO `error` code (RFC 6750 §3.1: an error code is for a
+ *      credential that was presented and refused); a garbage bearer carries
+ *      `error="invalid_token"`.
+ *   2. `challenge-403-scope` — harness-gated on `OPENWOP_TEST_LOW_SCOPE_KEY`: an
+ *      operation that key lacks scope for answers `403` with
+ *      `error="insufficient_scope"` and a `scope` parameter containing the scope the
+ *      operation requires.
+ *
+ * How each FAILS (the sabotage run before citing a row):
+ *   (a) the host sends no WWW-Authenticate                  → leg 1
+ *   (b) the host adds error="invalid_token" when NO credential was sent → leg 1
+ *   (c) resource_metadata points at the root on a sub-path host → leg 1
+ *   (d) the 403 omits `scope`, or names only one of two      → leg 2
+ *
+ * @see spec/v2/core/identity.md §2.5
+ * @see RFCS/0200-host-as-oauth-protected-resource.md §B
+ */
+
+import { describe, it, expect } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { driver } from '../lib/driver.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { parseChallenge, prmGate } from '../lib/protected-resource.js';
+import { projectBoundId } from '../lib/bound-id.js';
+
+const DOC = 'spec/v2/core/identity.md §2.5 (RFC 0200 §B.1)';
+const C401 = 'openwop.requirement.0200.challenge-401';
+const C403 = 'openwop.requirement.0200.challenge-403-scope';
+
+/** A tenant-bound id the host certainly did not mint, so the read is a refusal about the CREDENTIAL, not the resource. */
+function unknownRunId(tenant: string): string {
+  return projectBoundId(`${tenant}/${randomBytes(12).toString('hex')}`);
+}
+
+describe('RFC 0200 §B — v2-auth-challenge (gated on an advertised oauth2/oidc lane)', () => {
+  it('a 401 names Bearer and the metadata, and carries an error code only when a credential was presented', async () => {
+    const g = await prmGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const tenant = String((g.doc['host'] as { tenant?: unknown } | undefined)?.tenant ?? 'unknown-tenant');
+
+    const none = await driver.get(`/runs/${unknownRunId(tenant)}`, { authenticated: false });
+    expect(
+      none.status,
+      req(C401, `${DOC}`, `a request with no credential MUST be refused 401 before the resource is looked up (got ${none.status})`),
+    ).toBe(401);
+    const c1 = parseChallenge(none.headers.get('www-authenticate'));
+    expect(
+      c1?.scheme,
+      req(C401, `${DOC}`, `a 401 MUST carry WWW-Authenticate naming Bearer (RFC 9110 §15.5.2; got ${none.headers.get('www-authenticate') ?? 'no header'})`),
+    ).toBe('bearer');
+    expect(
+      c1?.params['resource_metadata'],
+      req(C401, `${DOC}`, `the challenge MUST carry resource_metadata naming the §A.2 URL, so a generic OAuth client can discover the authorization server from the refusal alone`),
+    ).toBe(g.prmUrl);
+    expect(
+      c1?.params['error'],
+      req(C401, `${DOC} (RFC 6750 §3.1)`, `a 401 for a request that presented NO credential MUST NOT carry an error code — an error code describes a credential that was refused, and inventing one tells a client its (absent) token was rejected`),
+    ).toBeUndefined();
+
+    const bad = await driver.get(`/runs/${unknownRunId(tenant)}`, { authenticated: false, headers: { Authorization: `Bearer not-a-real-credential-${randomBytes(8).toString('hex')}` } });
+    expect(
+      bad.status,
+      req(C401, `${DOC}`, `a garbage bearer MUST be refused 401 (got ${bad.status})`),
+    ).toBe(401);
+    const c2 = parseChallenge(bad.headers.get('www-authenticate'));
+    expect(
+      c2?.params['error'],
+      req(C401, `${DOC} (RFC 6750 §3.1)`, `a 401 for a credential that WAS presented and refused MUST carry error="invalid_token" (got ${bad.headers.get('www-authenticate') ?? 'no header'})`),
+    ).toBe('invalid_token');
+    expect(
+      c2?.params['resource_metadata'],
+      req(C401, `${DOC}`, 'the invalid_token challenge MUST also carry resource_metadata'),
+    ).toBe(g.prmUrl);
+  }, 30_000);
+
+  it('a 403 for insufficient scope names every scope the operation requires', async () => {
+    const g = await prmGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const low = process.env['OPENWOP_TEST_LOW_SCOPE_KEY']?.trim();
+    if (!low) {
+      return softSkip('blocked', 'OPENWOP_TEST_LOW_SCOPE_KEY is not set — a scope 403 needs a credential that LACKS a scope, and the suite will not infer one; without it the insufficient_scope clause never runs');
+    }
+    const auth = { authenticated: false as const, headers: { Authorization: `Bearer ${low}` } };
+    const res = await driver.post('/runs', { workflowId: 'conformance-noop' }, auth);
+    if (res.status === 401) {
+      return softSkip('blocked', 'OPENWOP_TEST_LOW_SCOPE_KEY did not authenticate (401) — it must be a valid credential that merely lacks runs:create');
+    }
+    expect(
+      res.status,
+      req(C403, `${DOC}`, `a credential that lacks runs:create MUST be refused 403, not 401 and not 201 (got ${res.status}) — OPENWOP_TEST_LOW_SCOPE_KEY names a key without it`),
+    ).toBe(403);
+    const c = parseChallenge(res.headers.get('www-authenticate'));
+    expect(
+      c?.params['error'],
+      req(C403, `${DOC}`, `a 403 for insufficient scope MUST carry error="insufficient_scope" (got ${res.headers.get('www-authenticate') ?? 'no header'})`),
+    ).toBe('insufficient_scope');
+    const scopes = (c?.params['scope'] ?? '').split(/\s+/).filter((s) => s.length > 0);
+    expect(
+      scopes.includes('runs:create'),
+      req(C403, `${DOC}`, `the challenge MUST carry \`scope\` listing EVERY scope the operation requires, space-delimited — runs:create for POST /runs (got "${c?.params['scope'] ?? ''}"); a partial list sends the client to request the wrong grant, because runs:cancel does not imply runs:read`),
+    ).toBe(true);
+  }, 30_000);
+});

package/src/scenarios/v2-bound-id-kinds.test.ts

@@ -140,7 +140,7 @@ describe('v2 bound-id kinds (identity.md §5, RFC 0187 §A)', () => {
       const reg = await http(() => driver.post('/webhooks', { url: registration.url, events: ['run.completed'] }));
       if (reg === null) return softSkip('blocked', 'POST /webhooks unreachable (fetch failed)');
       if (reg.status === 400 && readErrorCode(reg.json) === 'webhook_url_rejected') {
-        return softSkip('blocked', `host SSRF guard rejected the suite receiver ${registration.url} (webhooks.md §SSRF requires it) — set OPENWOP_WEBHOOK_RECEIVER_URL to a public https front for the receiver to witness what the host emits`);
+        return softSkip('blocked', `host SSRF guard rejected the suite receiver ${registration.url} (webhooks.md §Egress requires it) — set OPENWOP_WEBHOOK_RECEIVER_URL to a public https front for the receiver to witness what the host emits`);
       }
       const minted = (reg.json as { webhookId?: unknown } | null)?.webhookId;
       if (reg.status !== 201 || typeof minted !== 'string') return softSkip('blocked', `POST /webhooks answered ${reg.status} without a webhookId — the mint leg above owns that obligation; this leg needs an id to compare`);

package/src/scenarios/v2-callback-url-guarded.test.ts

@@ -1,6 +1,6 @@
 /**
  * RFC 0196 §A.3 — a host that advertises `interrupt.callbackDelivery` holds
- * `createRun.callbackUrl` to the `webhooks.md` §SSRF guard at create time
+ * `createRun.callbackUrl` to the `webhooks.md` §Egress guard at create time
  * (`spec/v2/core/interrupt.md` §Callback delivery). Target major 2.
  *
  * `callbackUrl` is an outbound request to a URL the CALLER chooses — the
@@ -47,7 +47,7 @@ describe('v2 callbackUrl egress guard (RFC 0196 §A.3)', () => {
       const field = (r.json as { details?: { field?: unknown } } | null)?.details?.field;
       if (r.status !== 400 || readErrorCode(r.json) !== 'validation_error' || field !== 'callbackUrl') wrong.push(`${p.cls}: ${r.status} ${readErrorCode(r.json) ?? ''} field=${String(field)}`);
     }
-    expect(accepted, req(ID, DOC, 'a host advertising interrupt.callbackDelivery MUST refuse at createRun a callbackUrl the webhooks.md §SSRF registration guard would refuse')).toEqual([]);
+    expect(accepted, req(ID, DOC, 'a host advertising interrupt.callbackDelivery MUST refuse at createRun a callbackUrl the webhooks.md §Egress registration guard would refuse')).toEqual([]);
     expect(wrong, req(ID, DOC, 'the refusal MUST be 400 validation_error naming details.field "callbackUrl"')).toEqual([]);
   });
 });