@openwop/openwop-conformance 2.45.14 → 2.45.16

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

package/src/scenarios/v2-envelope-contracts-advertisement.test.ts

@@ -0,0 +1,40 @@
+/**
+ * v2 — the `envelopeContracts` advertisement (`spec/v2/core/events.md` §Envelope contracts): the envelope contract claim. It had no v1 witness;
+ * the legs live in `lib/family-advert-witness.ts` (witness wave 3).
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *
+ * Not here: the refusal leg needs an error code in the prose and a fixture pack.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `envelopeContracts` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/events.md §Envelope contracts
+ */
+
+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 { recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'events.md §Envelope contracts';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.envelope-contracts.advert-record-schema';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 envelopeContracts advertisement (events.md §Envelope contracts)', () => {
+  it('the envelopeContracts record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('envelopeContracts'))) return softSkip('inapplicable', 'the host does not advertise envelopeContracts');
+    const out = recordSchemaLeg(PROFILE, doc, 'envelopeContracts', 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);
+  });
+});

package/src/scenarios/v2-envelope-reasoning-shape.test.ts

@@ -0,0 +1,81 @@
+/**
+ * v2 — the optional `reasoning` payload field (`spec/v2/core/events.md`
+ * §`envelopes`; RFC 0030 §A). Static: reads `schemas/v2/envelopes/` only. The
+ * v1 twin is `envelope-reasoning-shape`; its two advertisement legs
+ * (`envelopes.reasoning`, `envelopes.tierOneSubsetCompliance`) are ported to
+ * `v2-envelopes-advertisement`, not repeated here.
+ *
+ *   declared   `clarification.request`, `schema.request` and `error` declare an
+ *              OPTIONAL `reasoning: string` ("A vendor kind whose payload needs
+ *              multi-step reasoning SHOULD declare it as optional");
+ *   omitted    `schema.response` (a side-channel ack) does not declare it;
+ *   absent ok  each of the three validates WITHOUT `reasoning` ("A host MUST NOT
+ *              reject an envelope without it, whatever `promptDirective` says");
+ *   present ok each validates WITH a string `reasoning`;
+ *   typed      a non-string `reasoning` is rejected.
+ *
+ * Host-free: every leg runs with no OPENWOP_BASE_URL.
+ *
+ * @see spec/v2/core/events.md §envelopes
+ * @see schemas/v2/envelopes/
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2Validator } from '../lib/v2.js';
+import { req } from '../lib/requirement-ids.js';
+import { loadV2EnvelopeSchema } from '../lib/envelope-schema-static.js';
+
+const DOC = 'events.md §envelopes';
+const ID_DECLARED = 'openwop.requirement.envelopes.reasoning-declared-optional-string';
+const ID_OMITTED = 'openwop.requirement.envelopes.reasoning-omitted-from-schema-response';
+const ID_ABSENT_OK = 'openwop.requirement.envelopes.reasoning-absent-accepted';
+const ID_PRESENT_OK = 'openwop.requirement.envelopes.reasoning-present-accepted';
+const ID_TYPED = 'openwop.requirement.envelopes.reasoning-non-string-rejected';
+
+/** A valid payload per kind, without `reasoning`. */
+const BASE: Readonly<Record<string, Record<string, unknown>>> = {
+  'clarification.request': { questions: [{ id: 'q1', question: 'Which provider?' }] },
+  'schema.request': { envelopeType: 'acme.prd.create' },
+  error: { code: 'validation_failed', message: 'Could not match the schema.' },
+};
+const KINDS = Object.keys(BASE);
+
+describe('v2 envelope reasoning: payload schemas (events.md §envelopes)', () => {
+  for (const kind of KINDS) {
+    it(`${kind} declares an optional reasoning of type string`, () => {
+      const schema = loadV2EnvelopeSchema(kind);
+      const props = (schema?.['properties'] ?? {}) as Record<string, Record<string, unknown>>;
+      const required = (schema?.['required'] ?? []) as unknown[];
+      expect(schema !== null, req(ID_DECLARED, DOC, `schemas/v2/envelopes/${kind}.schema.json MUST exist`)).toBe(true);
+      expect(props['reasoning']?.['type'], req(ID_DECLARED, DOC, `${kind} MUST declare reasoning as type string`)).toBe('string');
+      expect(required.includes('reasoning'), req(ID_DECLARED, DOC, `${kind} MUST NOT require reasoning — it is optional`)).toBe(false);
+    });
+  }
+
+  it('schema.response does not declare reasoning (a side-channel ack)', () => {
+    const schema = loadV2EnvelopeSchema('schema.response');
+    const props = (schema?.['properties'] ?? {}) as Record<string, unknown>;
+    expect(schema !== null, req(ID_OMITTED, 'RFC 0030 §A', 'schemas/v2/envelopes/schema.response.schema.json MUST exist')).toBe(true);
+    expect('reasoning' in props, req(ID_OMITTED, 'RFC 0030 §A', 'schema.response MUST NOT declare reasoning')).toBe(false);
+  });
+});
+
+describe('v2 envelope reasoning: round-trip (events.md §envelopes)', () => {
+  for (const kind of KINDS) {
+    const validate = v2Validator(`envelopes/${kind}`);
+
+    it(`${kind} validates without reasoning`, () => {
+      const r = validate(BASE[kind]);
+      expect(r.ok, req(ID_ABSENT_OK, DOC, `a ${kind} payload without reasoning MUST validate — a host MUST NOT reject it (${r.errors})`)).toBe(true);
+    });
+
+    it(`${kind} validates with a string reasoning`, () => {
+      const r = validate({ reasoning: 'The input named X twice; I asked which one.', ...BASE[kind] });
+      expect(r.ok, req(ID_PRESENT_OK, DOC, `a ${kind} payload with a string reasoning MUST validate (${r.errors})`)).toBe(true);
+    });
+
+    it(`${kind} rejects a non-string reasoning`, () => {
+      expect(validate({ reasoning: 42, ...BASE[kind] }).ok, req(ID_TYPED, DOC, `${kind}: a numeric reasoning MUST be rejected — reasoning is a plain string`)).toBe(false);
+    });
+  }
+});

package/src/scenarios/v2-envelope-tier-one-subset-static.test.ts

@@ -0,0 +1,77 @@
+/**
+ * v2 — the Tier-1 structured-output subset, statically (RFC 0030 §B;
+ * `envelopes.tierOneSubsetCompliance` in `schemas/v2/capabilities.schema.json`).
+ * The v1 twin is `envelope-tier-one-subset-static`; the walker lives in
+ * `lib/envelope-schema-static.ts`.
+ *
+ *   load-bearing  ALWAYS ON, host-free: each universal-kind payload schema in
+ *                 `schemas/v2/envelopes/` uses none of the keywords that fail
+ *                 across several Tier-1 vendors (`oneOf`, `allOf`, `not`,
+ *                 `if`/`then`/`else`, `dependencies`, `prefixItems`,
+ *                 `propertyNames`), nests at most 5 deep and has at most 100
+ *                 properties;
+ *   strict        LIVE: a host advertising `tierOneSubsetCompliance: "strict"`
+ *                 has, for every kind it lists in `supportedEnvelopes.kinds`
+ *                 that resolves to a corpus schema, a schema meeting the whole
+ *                 intersection (closed objects, every property required, no
+ *                 string/number/array bounds). Host-served vendor schemas are
+ *                 not fetched, as at v1.
+ *
+ * The strict rule is stated by the schema seat's description ("`strict`: every
+ * host-served envelope schema passes the static subset-compliance check"). The
+ * v2 prose (`events.md` §envelopes) states a different, behavioural rule — the
+ * host MUST accept an envelope restricted to the subset from any advertised
+ * provider — and does not distinguish strict, warn and off.
+ *
+ * Dispositions (strict leg): discovery unreadable ⇒ `blocked`; `envelopes` not
+ * advertised, or `tierOneSubsetCompliance` other than "strict" ⇒
+ * `inapplicable`; no advertised kind resolving to a corpus schema ⇒
+ * `inapplicable`.
+ *
+ * @see RFCS/0030-envelope-reasoning-and-tier-one-subset.md §B
+ * @see spec/v2/core/events.md §envelopes
+ */
+
+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 { loadV2EnvelopeSchema, tierOneViolations, UNIVERSAL_KINDS, type SchemaViolation } from '../lib/envelope-schema-static.js';
+
+const ID_LOAD_BEARING = 'openwop.requirement.envelopes.tier-one-load-bearing-universal-kinds';
+const ID_STRICT = 'openwop.requirement.envelopes.tier-one-strict-advertised-kinds';
+
+describe('v2 Tier-1 subset: universal kinds meet the load-bearing rules (always on)', () => {
+  for (const kind of UNIVERSAL_KINDS) {
+    it(`${kind} uses no keyword that fails across Tier-1 vendors`, () => {
+      const schema = loadV2EnvelopeSchema(kind);
+      expect(schema !== null, req(ID_LOAD_BEARING, 'RFC 0030 §B', `schemas/v2/envelopes/${kind}.schema.json MUST exist`)).toBe(true);
+      const violations = schema === null ? [] : tierOneViolations(schema, 'load-bearing');
+      expect(violations, req(ID_LOAD_BEARING, 'RFC 0030 §B', `${kind} load-bearing Tier-1 violations: ${JSON.stringify(violations)}`)).toEqual([]);
+    });
+  }
+});
+
+describe('v2 Tier-1 subset: a strict host\'s advertised kinds meet the whole intersection', () => {
+  it('a host advertising tierOneSubsetCompliance strict has advertised kinds whose corpus schemas satisfy the Tier-1 intersection', async () => {
+    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');
+    const envelopes = await familyAdvertised('envelopes');
+    if (envelopes === null) return softSkip('inapplicable', 'the host does not advertise envelopes');
+    if (envelopes['tierOneSubsetCompliance'] !== 'strict') return softSkip('inapplicable', `envelopes.tierOneSubsetCompliance is ${JSON.stringify(envelopes['tierOneSubsetCompliance'])}, not "strict" — the strict walk binds only a strict host`);
+    const catalog = await familyAdvertised('supportedEnvelopes');
+    const kinds = Array.isArray(catalog?.['kinds']) ? (catalog['kinds'] as unknown[]).filter((k): k is string => typeof k === 'string') : [];
+    const walked: Record<string, SchemaViolation[]> = {};
+    let resolved = 0;
+    for (const kind of kinds) {
+      const schema = loadV2EnvelopeSchema(kind);
+      if (schema === null) continue;
+      resolved++;
+      const v = tierOneViolations(schema, 'strict');
+      if (v.length > 0) walked[kind] = v;
+    }
+    if (resolved === 0) return softSkip('inapplicable', `none of the ${kinds.length} kinds in supportedEnvelopes.kinds resolves to a corpus schema; host-served vendor schemas are not fetched`);
+    expect(walked, req(ID_STRICT, 'capabilities.schema.json §envelopes.tierOneSubsetCompliance', `a strict host's advertised kinds MUST satisfy the Tier-1 intersection: ${JSON.stringify(walked)}`)).toEqual({});
+  });
+});