@openwop/openwop-conformance 2.45.15 → 2.45.17

package/src/scenarios/v2-conversation-turn-model-provenance.test.ts

@@ -0,0 +1,110 @@
+/**
+ * v2 — `conversationTurnModelProvenance`, the emission legs
+ * (`spec/v2/core/conversation.md` §`conversationTurnModelProvenance`). The v1
+ * twin is `conversation-turn-model-provenance-shape`; the advertisement record
+ * leg is `v2-conversation-turn-model-provenance-advertisement`.
+ *
+ *   stamp-requires-advert  a host that stamps `agent.model` on an agent turn
+ *                          MUST advertise `conversationTurnModelProvenance`;
+ *   stamp-closed           the stamp carries provider and model identifiers
+ *                          only, so no prompt or completion content can ride
+ *                          in it (closed at `conversation-turn.schema.json`).
+ *
+ * Both legs read the turns of one `conformance-conversation-lifecycle` run,
+ * the fixture `v2-conversation-turn-parts` drives. A host whose turns carry no
+ * stamp records both legs `inapplicable`: the rule binds a host that stamps,
+ * and the suite cannot make it stamp.
+ *
+ * Gates, decided before any assertion: discovery unreadable ⇒ `blocked`;
+ * `conversationPrimitive` or the fixture not advertised ⇒ `inapplicable`; the
+ * fixture run not completing, or completing with no turn ⇒ `blocked` (the
+ * fixture's own contract is one exchange).
+ *
+ * @see spec/v2/core/conversation.md §`conversationTurnModelProvenance`
+ * @see schemas/v2/conversation-turn.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { familyAdvertised, v2Discovery, v2RefValidator } 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-conversation-lifecycle';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+const DOC = 'conversation.md §conversationTurnModelProvenance';
+const ID_ADVERT = 'openwop.requirement.conversation-turn-model-provenance.stamp-requires-advert';
+const ID_CLOSED = 'openwop.requirement.conversation-turn-model-provenance.stamp-closed';
+
+type Turns = { kind: 'turns'; turns: Json[] } | { kind: 'skip'; disposition: 'blocked' | 'inapplicable'; reason: string };
+let cached: Promise<Turns> | undefined;
+
+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));
+  }
+}
+
+/** One fixture run per file: both legs read the same turns. */
+function fixtureTurns(): Promise<Turns> {
+  cached ??= (async (): Promise<Turns> => {
+    let doc: Json | null;
+    try { doc = await v2Discovery(); } catch { doc = null; }
+    if (!doc) return { kind: 'skip', disposition: 'blocked', reason: 'v2 discovery unreachable' };
+    if (!(await familyAdvertised('conversationPrimitive'))) return { kind: 'skip', disposition: 'inapplicable', reason: 'host does not advertise conversationPrimitive' };
+    const fixtures = Array.isArray(doc['fixtures']) ? (doc['fixtures'] as unknown[]) : [];
+    if (!fixtures.includes(FIXTURE)) return { kind: 'skip', disposition: 'inapplicable', reason: `host does not advertise the ${FIXTURE} fixture` };
+    const create = await driver.post('/runs', { workflowId: FIXTURE });
+    if (create.status !== 201) return { kind: 'skip', disposition: 'blocked', reason: `POST /runs {workflowId: ${FIXTURE}} answered ${create.status}` };
+    const runId = String((create.json as { runId?: unknown } | null)?.runId ?? '');
+    const status = await waitTerminal(runId, 20_000);
+    if (status !== 'completed') return { kind: 'skip', disposition: '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 turns = (Array.isArray(events) ? events : [])
+      .filter((e) => e['type'] === 'conversation.exchanged')
+      .map((e) => ((e['payload'] ?? {}) as Json)['turn'])
+      .filter((t): t is Json => t !== null && typeof t === 'object' && !Array.isArray(t));
+    if (turns.length === 0) return { kind: 'skip', disposition: 'blocked', reason: `${FIXTURE} completed without a conversation.exchanged event carrying a turn` };
+    return { kind: 'turns', turns };
+  })();
+  return cached;
+}
+
+/** The `agent.model` stamps the run's turns carry. */
+function stamps(turns: Json[]): { messageId: string; model: unknown }[] {
+  return turns.flatMap((t) => {
+    const agent = t['agent'];
+    if (agent === null || typeof agent !== 'object' || Array.isArray(agent) || !('model' in agent)) return [];
+    return [{ messageId: String(t['messageId']), model: (agent as Json)['model'] }];
+  });
+}
+
+describe('v2 conversationTurnModelProvenance emission (conversation.md §conversationTurnModelProvenance)', () => {
+  it('a host that stamps agent.model on a turn advertises conversationTurnModelProvenance', async () => {
+    const out = await fixtureTurns();
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    const stamped = stamps(out.turns);
+    if (stamped.length === 0) return softSkip('inapplicable', 'no emitted turn carries an agent.model stamp');
+    const advertised = (await familyAdvertised('conversationTurnModelProvenance')) !== null;
+    expect(advertised, req(ID_ADVERT, DOC, `${stamped.length} turn(s) carry agent.model (first: ${stamped[0]?.messageId}); a host that stamps MUST advertise conversationTurnModelProvenance`)).toBe(true);
+  });
+
+  it('every agent.model stamp carries provider and model identifiers only', async () => {
+    const out = await fixtureTurns();
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    const stamped = stamps(out.turns);
+    if (stamped.length === 0) return softSkip('inapplicable', 'no emitted turn carries an agent.model stamp');
+    const validate = v2RefValidator('conversation-turn.schema.json#/properties/agent/properties/model');
+    for (const s of stamped) {
+      const r = validate(s.model);
+      expect(r.ok, req(ID_CLOSED, DOC, `turn ${s.messageId}: agent.model MUST validate against schemas/v2/conversation-turn.schema.json (provider and model only): ${r.errors}`)).toBe(true);
+    }
+  });
+});

package/src/scenarios/v2-credentials-advertisement.test.ts

@@ -0,0 +1,66 @@
+/**
+ * v2 — the `credentials` advertisement (`spec/v2/core/oauth.md` §Credentials;
+ * RFC 0046). The v1 twin is the advertisement legs of
+ * `credentials-capability-shape`; the legs live in
+ * `lib/family-advert-witness.ts`.
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *   scopes         `scopes` is a subset of user, workspace, tenant (a scope
+ *                  outside it is refused `credential_scope_unsupported`);
+ *   rotation       `rotation` is `none` or `two-key-overlap`.
+ *
+ * Not here: resolution, scope refusal, rotation overlap and redaction need a
+ * credential seam (`credential-payload-redaction` has no v2 seam).
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `credentials` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/oauth.md §Credentials
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2Discovery, familyAdvertised } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { majorProfile } from '../lib/major-profile.js';
+import { credentialsRotationLeg, credentialsScopesLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'oauth.md §Credentials';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.credentials.advert-record-schema';
+const ID_SCOPES_SUBSET = 'openwop.requirement.credentials.scopes-subset';
+const ID_ROTATION_VALUE = 'openwop.requirement.credentials.rotation-value';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 credentials advertisement (oauth.md §Credentials)', () => {
+  it('the credentials record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('credentials'))) return softSkip('inapplicable', 'the host does not advertise credentials');
+    const out = recordSchemaLeg(PROFILE, doc, 'credentials', DOC);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_RECORD, x.doc, x.message)).toBe(true);
+  });
+
+  it('credentials.scopes is a subset of user, workspace, tenant', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('credentials'))) return softSkip('inapplicable', 'the host does not advertise credentials');
+    const out = credentialsScopesLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_SCOPES_SUBSET, x.doc, x.message)).toBe(true);
+  });
+
+  it('credentials.rotation is none or two-key-overlap', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('credentials'))) return softSkip('inapplicable', 'the host does not advertise credentials');
+    const out = credentialsRotationLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_ROTATION_VALUE, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-data-residency-admission.test.ts

@@ -0,0 +1,98 @@
+/**
+ * v2 — `dataResidency` admission control (`spec/v2/core/runs.md` §Refusals and
+ * §`dataResidency`). The v1 twin is `data-residency-admission`.
+ *
+ * A host advertising `dataResidency` MUST honour or reject a `residency`
+ * constraint on `POST /runs`, and MUST NOT accept and ignore one:
+ *
+ *   reject   a region outside `dataResidency.regions` answers
+ *            `422 residency_unavailable` and creates no run;
+ *   accept   a region inside `dataResidency.regions` is not refused for its
+ *            residency: the create answers `201`.
+ *
+ * The legs drive the normative create route only; no seam. The refused region
+ * is made up by the suite and checked against the advertised list, so it can
+ * never collide with a real one. The accept leg posts the `conformance-noop`
+ * fixture workflow; a host that does not install it answers 404 and the leg is
+ * `inapplicable` rather than a pass. Physical confinement is an operator SHOULD
+ * and cannot be observed on the wire.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `dataResidency` absent or no
+ * advertised region ⇒ `inapplicable`; a 429 ⇒ `blocked` (the run budget, not
+ * the wire).
+ *
+ * @see spec/v2/core/runs.md §Refusals
+ * @see spec/v2/core/runs.md §`dataResidency`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, familyAdvertised } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+
+const DOC = 'spec/v2/core/runs.md §dataResidency';
+const ID_REJECT = 'openwop.requirement.data-residency.reject-unadvertised-region';
+const ID_ACCEPT = 'openwop.requirement.data-residency.accept-advertised-region';
+const NOOP = 'conformance-noop';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+/** The advertised regions, or a skip reason. */
+async function advertisedRegions(): Promise<string[] | { disposition: 'blocked' | 'inapplicable'; reason: string }> {
+  let doc: Record<string, unknown> | null;
+  try { doc = await v2Discovery(); } catch { doc = null; }
+  if (!doc) return { disposition: 'blocked', reason: UNREADABLE };
+  const rec = await familyAdvertised('dataResidency');
+  if (!rec) return { disposition: 'inapplicable', reason: 'the host does not advertise dataResidency' };
+  const regions = Array.isArray(rec['regions']) ? rec['regions'].filter((r): r is string => typeof r === 'string' && r.length > 0) : [];
+  if (regions.length === 0) return { disposition: 'inapplicable', reason: 'dataResidency advertises no region (regions is empty or malformed; the record leg owns that)' };
+  return regions;
+}
+
+/** Cancel a run the host created, so a failing row leaves nothing behind. */
+async function cancelIfCreated(res: OpenWOPResponse): Promise<string | undefined> {
+  const runId = (res.json as { runId?: unknown } | undefined)?.runId;
+  if (typeof runId !== 'string') return undefined;
+  await http(() => driver.post(`/runs/${encodeURIComponent(runId)}/cancel`, {}));
+  return runId;
+}
+
+describe('v2 dataResidency admission (runs.md §dataResidency)', () => {
+  it('a region outside dataResidency.regions answers 422 residency_unavailable and creates no run', async () => {
+    const regions = await advertisedRegions();
+    if (!Array.isArray(regions)) return softSkip(regions.disposition, regions.reason);
+    let bogus = 'zz-conformance-nowhere';
+    while (regions.includes(bogus)) bogus += '-x';
+
+    const res = await http(() => driver.post('/runs', { workflowId: NOOP, residency: { region: bogus } }));
+    if (res === null) return softSkip('blocked', 'POST /runs unreachable (fetch failed)');
+    if (res.status === 429) return softSkip('blocked', 'POST /runs answered 429 — the run budget, not the wire');
+    const runId = await cancelIfCreated(res);
+
+    expect(res.status, req(ID_REJECT, DOC, `an unadvertised region ("${bogus}") MUST be refused with 422 (got ${res.status} ${readErrorCode(res.json) ?? ''})`.trim())).toBe(422);
+    expect(readErrorCode(res.json), req(ID_REJECT, DOC, 'the refusal MUST carry the registered code residency_unavailable')).toBe('residency_unavailable');
+    expect(runId, req(ID_REJECT, DOC, `a refused residency request MUST create no run (the response carried runId ${String(runId)})`)).toBeUndefined();
+  });
+
+  it('a region inside dataResidency.regions is accepted', async () => {
+    const regions = await advertisedRegions();
+    if (!Array.isArray(regions)) return softSkip(regions.disposition, regions.reason);
+    const region = regions[0] as string;
+
+    const res = await http(() => driver.post('/runs', { workflowId: NOOP, residency: { region } }));
+    if (res === null) return softSkip('blocked', 'POST /runs unreachable (fetch failed)');
+    if (res.status === 429) return softSkip('blocked', 'POST /runs answered 429 — the run budget, not the wire');
+    await cancelIfCreated(res);
+    if (res.status === 404 && readErrorCode(res.json) !== 'residency_unavailable') {
+      return softSkip('inapplicable', `the host does not install the ${NOOP} fixture workflow (404 ${readErrorCode(res.json) ?? ''}); the accept leg needs a workflow to create`.trim());
+    }
+
+    expect(readErrorCode(res.json), req(ID_ACCEPT, DOC, `an advertised region ("${region}") MUST NOT be refused residency_unavailable`)).not.toBe('residency_unavailable');
+    expect(res.status, req(ID_ACCEPT, DOC, `a create with an advertised region MUST answer 201 (got ${res.status} ${readErrorCode(res.json) ?? ''})`.trim())).toBe(201);
+  });
+});

package/src/scenarios/v2-data-residency-advertisement.test.ts

@@ -0,0 +1,52 @@
+/**
+ * v2 — the `dataResidency` advertisement (`spec/v2/core/runs.md` §`dataResidency`): the residency regions a host will honour. The v1 twin is
+ * `data-residency-admission`;
+ * the legs live in `lib/family-advert-witness.ts` (witness wave 3).
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *   regions-shape  dataResidency.regions holds unique non-empty region codes;
+ *
+ * Not here: the admission rule (accept an advertised region, refuse any other with `422 residency_unavailable`, create no run) is in `v2-data-residency-admission.test.ts`.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `dataResidency` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/runs.md §`dataResidency`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2Discovery, familyAdvertised } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { majorProfile } from '../lib/major-profile.js';
+import { dataResidencyRegionsLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'runs.md §dataResidency';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.data-residency.advert-record-schema';
+const ID_REGIONS_SHAPE = 'openwop.requirement.data-residency.regions-shape';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 dataResidency advertisement (runs.md §dataResidency)', () => {
+  it('the dataResidency record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('dataResidency'))) return softSkip('inapplicable', 'the host does not advertise dataResidency');
+    const out = recordSchemaLeg(PROFILE, doc, 'dataResidency', DOC);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_RECORD, x.doc, x.message)).toBe(true);
+  });
+
+  it('dataResidency.regions holds unique non-empty region codes', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('dataResidency'))) return softSkip('inapplicable', 'the host does not advertise dataResidency');
+    const out = dataResidencyRegionsLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_REGIONS_SHAPE, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-dead-letter-advertisement.test.ts

@@ -0,0 +1,54 @@
+/**
+ * v2 — the `deadLetter` advertisement (`spec/v2/core/runs.md` §Dead letters;
+ * RFC 0053). The v1 twin is the advertisement legs of
+ * `deadletter-capability-shape`; the legs live in
+ * `lib/family-advert-witness.ts`.
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *   retentionDays  an integer of at least 1.
+ *
+ * Not here: routing to the sink, `run.dead-lettered` and fork-eligibility for
+ * `retentionDays` need a retry-exhaustion fixture run.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `deadLetter` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/runs.md §Dead letters
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2Discovery, familyAdvertised } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { majorProfile } from '../lib/major-profile.js';
+import { deadLetterRetentionDaysLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'runs.md §Dead letters';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.dead-letter.advert-record-schema';
+const ID_RETENTION_DAYS = 'openwop.requirement.dead-letter.retention-days';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 deadLetter advertisement (runs.md §Dead letters)', () => {
+  it('the deadLetter record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('deadLetter'))) return softSkip('inapplicable', 'the host does not advertise deadLetter');
+    const out = recordSchemaLeg(PROFILE, doc, 'deadLetter', DOC);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_RECORD, x.doc, x.message)).toBe(true);
+  });
+
+  it('deadLetter.retentionDays is an integer of at least 1', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('deadLetter'))) return softSkip('inapplicable', 'the host does not advertise deadLetter');
+    const out = deadLetterRetentionDaysLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_RETENTION_DAYS, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-discovery-etag.test.ts

@@ -0,0 +1,86 @@
+/**
+ * v2 — the discovery document's conditional GET (`spec/v2/core/capabilities.md`
+ * §1; `headers.md` §Request headers). The v1 twin is the presence-gated leg in
+ * `discovery.test.ts`, which runs at major 1 only, so until 2.45.17 nothing
+ * witnessed this MUST at major 2.
+ *
+ * At v2 both halves are MUSTs: a host MUST emit a standard `ETag` on the
+ * discovery document and MUST honour `If-None-Match` with `304`. The 304
+ * carries no body and carries `OpenWOP-Version` like every response
+ * (versioning.md §1.4).
+ *
+ *   etag-emitted       the 200 carries a non-empty `ETag`;
+ *   etag-revalidates   a matching `If-None-Match` receives `304`, no body,
+ *                      `OpenWOP-Version` present; a non-matching one receives
+ *                      `200` with the document (control: a host that answers
+ *                      304 to any conditional request fails).
+ *
+ * The revalidation runs once per client spelling: `OpenWOP-Version: 2.0` and
+ * `2` (versioning.md §1: a host MUST accept both), and `2` with a wildcard `Accept`
+ * (curl, a default fetch). openwop-app's public origin answered `304` to the
+ * suite's own spelling and `200` to the bare one, so a single spelling hid a
+ * violation every other client sees.
+ *
+ * Measured against the PUBLIC origin a host is cut on. A front door that drops
+ * `If-None-Match` on the way to a correct origin (openwop-app, 2026-10-04:
+ * direct `304`, through the hosting rewrite `200`) fails here, as it should:
+ * the rule binds what clients reach.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`. No other skip — the rule is
+ * unconditional at v2.
+ *
+ * @see spec/v2/core/capabilities.md §1
+ * @see spec/v2/core/headers.md §Request headers
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/capabilities.md §1';
+const ID_EMITTED = 'openwop.requirement.capabilities.discovery-etag-emitted';
+const ID_REVALIDATES = 'openwop.requirement.capabilities.discovery-etag-revalidates';
+const V2 = { 'OpenWOP-Version': '2.0' };
+/** The client spellings a host MUST treat alike (versioning.md §1). */
+const SPELLINGS: ReadonlyArray<Readonly<Record<string, string>>> = [
+  { 'OpenWOP-Version': '2.0' },
+  { 'OpenWOP-Version': '2' },
+  { 'OpenWOP-Version': '2', Accept: '*/*' },
+];
+const label = (h: Readonly<Record<string, string>>): string => Object.entries(h).map(([k, v]) => `${k}: ${v}`).join(', ');
+
+async function get(headers: Readonly<Record<string, string>> = V2): Promise<OpenWOPResponse | null> {
+  try { return await driver.get('/.well-known/openwop', { authenticated: false, headers: { ...headers } }); } catch { return null; }
+}
+
+describe('v2 discovery ETag (capabilities.md §1)', () => {
+  it('the discovery document carries an ETag', async () => {
+    const first = await get();
+    if (first === null || first.status !== 200) return softSkip('blocked', `v2 discovery unreachable (${first?.status ?? 'no response'})`);
+    const etag = first.headers.get('etag');
+    expect(etag !== null && etag.trim().length > 0, req(ID_EMITTED, DOC, `a host MUST emit a standard ETag on the discovery document (got ${etag === null ? 'none' : JSON.stringify(etag)})`)).toBe(true);
+  });
+
+  it('a matching If-None-Match receives 304 with no body and the version header; a non-matching one receives 200', async () => {
+    const first = await get();
+    if (first === null || first.status !== 200) return softSkip('blocked', `v2 discovery unreachable (${first?.status ?? 'no response'})`);
+    const etag = first.headers.get('etag');
+    if (etag === null || etag.trim().length === 0) return softSkip('inapplicable', 'no ETag to revalidate — the emitted-ETag leg records that MUST');
+
+    for (const spelling of SPELLINGS) {
+      const own = await get(spelling);
+      if (own === null || own.status !== 200) return softSkip('blocked', `v2 discovery unreachable under ${label(spelling)} (${own?.status ?? 'no response'})`);
+      const tag = own.headers.get('etag') ?? etag;
+      const hit = await get({ ...spelling, 'If-None-Match': tag });
+      if (hit === null) return softSkip('blocked', 'conditional GET unreachable (fetch failed)');
+      expect(hit.status, req(ID_REVALIDATES, DOC, `under ${label(spelling)}, a matching If-None-Match MUST receive 304 (got ${hit.status}; ETag sent ${tag}, answered ${String(hit.headers.get('etag'))})`)).toBe(304);
+      expect(hit.text.length, req(ID_REVALIDATES, 'spec/v2/core/headers.md §Request headers', `under ${label(spelling)}, the 304 MUST carry no body (got ${hit.text.length} byte(s))`)).toBe(0);
+      expect(hit.headers.get('openwop-version'), req(ID_REVALIDATES, 'spec/v2/core/versioning.md §1.4', `under ${label(spelling)}, the 304 carries OpenWOP-Version like every response`)).not.toBeNull();
+    }
+
+    const miss = await get({ ...V2, 'If-None-Match': '"openwop-conformance-no-such-tag"' });
+    if (miss === null) return softSkip('blocked', 'conditional GET unreachable (fetch failed)');
+    expect(miss.status, req(ID_REVALIDATES, DOC, `a non-matching If-None-Match MUST receive 200 with the document (got ${miss.status})`)).toBe(200);
+  });
+});

package/src/scenarios/v2-dispatch-input-mapping.test.ts

@@ -0,0 +1,70 @@
+/**
+ * v2 — `core.dispatch` `inputMapping` (`spec/v2/facets/agents.schema.json`
+ * `dispatchMapping`: a host advertising it honors `inputMapping`, "building
+ * child inputs from parent variables before dispatch";
+ * `schemas/v2/dispatch-config.schema.json` `inputMapping`: "Child receives
+ * `inputs[childKey] = parentVariables[parentKey]`", mirroring
+ * `core.subWorkflow`'s `inputMapping`). The v1 twin is `dispatch-input-mapping`
+ * (HVMAP-1a, HVMAP-1a-null); the legs live in `lib/dispatch-witness.ts`.
+ *
+ *   projection  `conformance-dispatch-input-mapping`: the dispatched child's
+ *               `inputs.childGreeting` is the parent's `parentName` ("Alice");
+ *   unset       `conformance-dispatch-input-mapping-no-default`: `parentName`
+ *               is unset, so the child's `inputs.childGreeting` is absent —
+ *               never `null` or a placeholder.
+ * The child is found by the parent's `node.dispatched` (`childWorkflowId`), or
+ * else the dispatch node's `node.completed` `outputs.childRunId`.
+ * NOT ported: the registration-refusal leg (it drives a capability-toggle seam).
+ *
+ * Dispositions: `agents.dispatchMapping` not `true`, or a fixture not in
+ * `fixtures[]` ⇒ `inapplicable`; the child unlocatable on the parent's log ⇒
+ * `blocked`; discovery unreadable ⇒ `blocked`.
+ *
+ * Proven against a double in `lib/dispatch-witness.test.ts`.
+ *
+ * @see spec/v2/facets/agents.schema.json §dispatchMapping
+ * @see schemas/v2/dispatch-config.schema.json §inputMapping
+ */
+
+import { describe, it, expect } from 'vitest';
+import { familyAdvertised, v2Discovery } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { majorProfile } from '../lib/major-profile.js';
+import type { Outcome, Skip } from '../lib/fixture-run-observer.js';
+import { DISPATCH_NO_DEFAULT_FIXTURE, DISPATCH_PARENT_FIXTURE, driveDispatchMapping, judgeProjection, judgeUnsetProjection, type DispatchObservation } from '../lib/dispatch-witness.js';
+
+const PROFILE = majorProfile(2);
+const ID_PROJECTION = 'openwop.requirement.agents.dispatch-input-mapping-projection';
+const ID_UNSET = 'openwop.requirement.agents.dispatch-input-mapping-unset-undefined';
+
+const runs = new Map<string, Promise<Skip | DispatchObservation>>();
+async function observation(fixture: string): Promise<DispatchObservation | (() => undefined)> {
+  if (!process.env['OPENWOP_BASE_URL']) return () => softSkip('inapplicable', 'no target: OPENWOP_BASE_URL is unset');
+  let doc: Record<string, unknown> | null;
+  try { doc = await v2Discovery(); } catch { doc = null; }
+  if (!doc) return () => softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0');
+  if (!(await familyAdvertised('agents'))) return () => softSkip('inapplicable', 'the host does not advertise agents');
+  if (!runs.has(fixture)) runs.set(fixture, driveDispatchMapping(PROFILE, doc, fixture));
+  const o = await runs.get(fixture)!;
+  return 'kind' in o ? () => softSkip(o.disposition, o.reason) : o;
+}
+function assert(id: string, out: Outcome): undefined {
+  if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+  for (const x of out.findings) expect(x.ok, req(id, x.doc, x.message)).toBe(true);
+  return undefined;
+}
+
+describe('v2 dispatch: inputMapping (agents.dispatchMapping)', () => {
+  it('inputMapping projects the parent variable into the dispatched child inputs', async () => {
+    const o = await observation(DISPATCH_PARENT_FIXTURE);
+    if (typeof o === 'function') return o();
+    return assert(ID_PROJECTION, judgeProjection(o));
+  }, 90_000);
+
+  it('an unset parent variable projects to undefined: the child input is absent, never null', async () => {
+    const o = await observation(DISPATCH_NO_DEFAULT_FIXTURE);
+    if (typeof o === 'function') return o();
+    return assert(ID_UNSET, judgeUnsetProjection(o));
+  }, 90_000);
+});

package/src/scenarios/v2-dispatch-loop.test.ts

@@ -0,0 +1,80 @@
+/**
+ * v2 — the supervisor loop (`spec/v2/core/execution.md` §`multiAgent`, levels
+ * 1 and 5). The v1 twin is `dispatchLoop`; the legs live in
+ * `lib/dispatch-witness.ts`. Event names come from the codemap through the
+ * profile: `runOrchestrator.decided` is `orchestrator.decided` at major 2.
+ *
+ * A run of `conformance-dispatch-loop` (`core.orchestrator.supervisor` ⇄
+ * `core.dispatch`) is created with `POST /runs` and its log read with
+ * `events/poll`:
+ *   terminates  the run completes; each turn records its decision, the last
+ *               is `terminate`, and none follows it ("`terminate` completes
+ *               the run");
+ *   decisions   every decision payload is well-formed (the decision checked
+ *               against the `OrchestratorDecision` branches) and its `agentId`
+ *               never changes;
+ *   iteration   at `executionModel.version >= 5`, `iteration` is 1-based and
+ *               +1 per turn.
+ * NOT ported: v1's exact `['next-worker', 'terminate']` sequence. That is the
+ * fixture catalog's prerequisite on the host's supervisor, not a rule the v2
+ * text states.
+ *
+ * Dispositions: `multiAgent.executionModel` not advertised, or the fixture not
+ * in `fixtures[]` ⇒ `inapplicable`; version below 5 ⇒ the iteration leg
+ * `inapplicable`; discovery unreadable ⇒ `blocked`.
+ *
+ * Proven against a double in `lib/dispatch-witness.test.ts`.
+ *
+ * @see spec/v2/core/execution.md §multiAgent
+ */
+
+import { describe, it, expect } from 'vitest';
+import { familyAdvertised, v2Discovery, v2RefValidator } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { majorProfile } from '../lib/major-profile.js';
+import type { Outcome, Skip } from '../lib/fixture-run-observer.js';
+import { decisionBranchValidator, driveLoop, judgeDecisions, judgeIteration, judgeLoopTerminates, type LoopObservation } from '../lib/dispatch-witness.js';
+
+const PROFILE = majorProfile(2);
+const ID_TERMINATES = 'openwop.requirement.multi-agent.supervisor-loop-terminates';
+const ID_DECISIONS = 'openwop.requirement.multi-agent.decision-recorded-well-formed';
+const ID_ITERATION = 'openwop.requirement.multi-agent.decision-iteration-monotonic';
+const validateDecision = decisionBranchValidator((i) => v2RefValidator(`orchestrator-decision.schema.json#/oneOf/${i}`));
+
+let run: Promise<Skip | LoopObservation> | undefined;
+async function observation(): Promise<LoopObservation | (() => undefined)> {
+  if (!process.env['OPENWOP_BASE_URL']) return () => softSkip('inapplicable', 'no target: OPENWOP_BASE_URL is unset');
+  let doc: Record<string, unknown> | null;
+  try { doc = await v2Discovery(); } catch { doc = null; }
+  if (!doc) return () => softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0');
+  if (!(await familyAdvertised('multiAgent'))) return () => softSkip('inapplicable', 'the host does not advertise multiAgent');
+  run ??= driveLoop(PROFILE, doc);
+  const o = await run;
+  return 'kind' in o ? () => softSkip(o.disposition, o.reason) : o;
+}
+function assert(id: string, out: Outcome): undefined {
+  if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+  for (const x of out.findings) expect(x.ok, req(id, x.doc, x.message)).toBe(true);
+  return undefined;
+}
+
+describe('v2 multiAgent: the supervisor loop (execution.md §multiAgent)', () => {
+  it('each turn records its decision and terminate completes the run', async () => {
+    const o = await observation();
+    if (typeof o === 'function') return o();
+    return assert(ID_TERMINATES, judgeLoopTerminates(o));
+  }, 90_000);
+
+  it('every recorded decision is well-formed and the deciding agent never changes', async () => {
+    const o = await observation();
+    if (typeof o === 'function') return o();
+    return assert(ID_DECISIONS, judgeDecisions(o, validateDecision));
+  }, 90_000);
+
+  it('at executionModel.version >= 5, iteration is 1-based and increments by exactly 1 per turn', async () => {
+    const o = await observation();
+    if (typeof o === 'function') return o();
+    return assert(ID_ITERATION, judgeIteration(o));
+  }, 90_000);
+});