@openwop/openwop-conformance 2.45.14 → 2.45.15

package/src/scenarios/v2-ai-envelope-shape-static.test.ts

@@ -0,0 +1,93 @@
+/**
+ * v2 — the AI envelope wire shape, statically (`spec/v2/core/events.md`
+ * §"AI envelopes: E1–E5"; `schemas/v2/ai-envelope.schema.json`). The v1 twin is
+ * the static half of `ai-envelope-shape`; its live halves (the
+ * `envelope/accept` seam legs) are seam-only and not ported.
+ *
+ *   compile     `ai-envelope.schema.json` and each universal-kind payload
+ *               schema compile under Ajv 2020 with the v2 tree registered;
+ *   positive    a well-formed envelope validates — with `correlationId` and
+ *               `meta.source`, which v2 makes REQUIRED (migration C4.16);
+ *   meta        an envelope without `meta` is rejected;
+ *   closed      an unknown top-level property is rejected;
+ *   correlation NEW at v2: an envelope without `correlationId` is rejected
+ *               ("`correlationId` and `meta.source` are REQUIRED on every
+ *               envelope … nothing is synthesized");
+ *   source      NEW at v2: an envelope whose `meta` has no `source` is rejected.
+ *
+ * The `<org>.` namespacing rule for kinds is not witnessed here: the schema's
+ * `type` is an open string, so the rule binds the engine's acceptance, not the
+ * wire shape.
+ *
+ * Host-free: every leg runs with no OPENWOP_BASE_URL.
+ *
+ * @see spec/v2/core/events.md §"AI envelopes: E1–E5"
+ * @see spec/v1/migrations.json openwop.migration.C4.16
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2Validator } from '../lib/v2.js';
+import { req } from '../lib/requirement-ids.js';
+import { UNIVERSAL_KINDS } from '../lib/envelope-schema-static.js';
+
+const DOC = 'events.md §AI envelopes: E1–E5';
+const ID_COMPILE = 'openwop.requirement.ai-envelope.schemas-compile';
+const ID_POSITIVE = 'openwop.requirement.ai-envelope.well-formed-accepted';
+const ID_META = 'openwop.requirement.ai-envelope.meta-required';
+const ID_CLOSED = 'openwop.requirement.ai-envelope.top-level-closed';
+const ID_CORRELATION = 'openwop.requirement.ai-envelope.correlation-id-required';
+const ID_SOURCE = 'openwop.requirement.ai-envelope.meta-source-required';
+
+const WELL_FORMED = {
+  type: 'clarification.request',
+  schemaVersion: 1,
+  envelopeId: 'env-v2-positive-1',
+  correlationId: 'run-1:node-2:turn-0:abc123',
+  payload: { questions: [{ id: 'q1', question: 'Which provider?' }] },
+  meta: { source: 'ai-generation', ts: '2026-10-04T10:00:00Z', contentTrust: 'trusted' },
+} as const;
+
+/** The well-formed envelope with one top-level field removed. */
+function without(field: string): Record<string, unknown> {
+  const e: Record<string, unknown> = { ...WELL_FORMED };
+  delete e[field];
+  return e;
+}
+
+describe('v2 AI envelope shape: schemas compile', () => {
+  it('ai-envelope.schema.json compiles under Ajv 2020', () => {
+    expect(() => v2Validator('ai-envelope'), req(ID_COMPILE, DOC, 'schemas/v2/ai-envelope.schema.json MUST compile')).not.toThrow();
+  });
+
+  for (const kind of UNIVERSAL_KINDS) {
+    it(`envelopes/${kind}.schema.json compiles under Ajv 2020`, () => {
+      expect(() => v2Validator(`envelopes/${kind}`), req(ID_COMPILE, DOC, `schemas/v2/envelopes/${kind}.schema.json MUST compile`)).not.toThrow();
+    });
+  }
+});
+
+describe('v2 AI envelope shape: round-trip', () => {
+  const validate = v2Validator('ai-envelope');
+
+  it('accepts a well-formed envelope carrying correlationId and meta.source', () => {
+    const r = validate(WELL_FORMED);
+    expect(r.ok, req(ID_POSITIVE, DOC, `a well-formed envelope MUST validate (${r.errors})`)).toBe(true);
+  });
+
+  it('rejects an envelope missing meta', () => {
+    expect(validate(without('meta')).ok, req(ID_META, DOC, 'an envelope without meta MUST be rejected')).toBe(false);
+  });
+
+  it('rejects an envelope with an unknown top-level property', () => {
+    expect(validate({ ...WELL_FORMED, unknownTopLevel: 'x' }).ok, req(ID_CLOSED, 'schemas/v2/ai-envelope.schema.json', 'the envelope is closed: an unknown top-level property MUST be rejected')).toBe(false);
+  });
+
+  it('rejects an envelope missing correlationId', () => {
+    expect(validate(without('correlationId')).ok, req(ID_CORRELATION, DOC, 'correlationId is REQUIRED on every envelope at v2 — an envelope without it MUST be rejected, never synthesized')).toBe(false);
+  });
+
+  it('rejects an envelope whose meta carries no source', () => {
+    const { source: _source, ...meta } = WELL_FORMED.meta;
+    expect(validate({ ...WELL_FORMED, meta }).ok, req(ID_SOURCE, DOC, 'meta.source is REQUIRED on every envelope at v2 — an envelope without it MUST be rejected')).toBe(false);
+  });
+});

package/src/scenarios/v2-ai-providers-advertisement.test.ts

@@ -0,0 +1,94 @@
+/**
+ * v2 — the `aiProviders` advertisement facets that survive at major 2
+ * (`spec/v2/core/host-services.md` §aiProviders; migration C2.11 narrowed the
+ * v1 facets). The v1 twins are the advertisement halves of
+ * `aiproviders-selfhosted-shape`, `byok-auth-modes` and `media-url-inline-cap`;
+ * the legs live in `lib/family-advert-witness.ts`.
+ *
+ *   record              the record validates against its seat in
+ *                       `schemas/v2/capabilities.schema.json`;
+ *   selfHosted          one boolean (the v1 `selfHosted[]` id list retired);
+ *   authModes shape     one flat list (the v1 per-provider map retired);
+ *   (not a leg) authModes vocabulary: the prose names `apiKey`, `oauth-pkce`,
+ *                       `oauth-device`, `none`, `subscription`, but its only
+ *                       MUSTs bind clients ("a client MUST ignore an unknown
+ *                       mode"), and the v2 schema seat is `string[]` with no
+ *                       enum. No host-side MUST exists, so a misspelt mode is an
+ *                       interop defect the host should fix, not a failing row.
+ *                       Restoring the v1 enum would need an RFC.
+ *   maxInlineMediaBytes an integer ≥ 1;
+ *   promptPrefixCache   one boolean (the v1 `{ supported, providers[] }` retired).
+ *
+ * The v1 rules C2.11 retired (`selfHosted[]` ⊆ `supported[]`, the per-provider
+ * `authModes` keys/byok/`["none"]` rules) are not ported: they have no v2 seat.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `aiProviders` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/host-services.md §aiProviders
+ * @see spec/v1/migrations.json openwop.migration.C2.11
+ */
+
+import { describe, it, expect } from 'vitest';
+import { 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 {
+  aiProvidersAuthModesShapeLeg, aiProvidersInlineMediaLeg, aiProvidersPromptPrefixCacheLeg, aiProvidersSelfHostedLeg,
+  recordSchemaLeg,
+} from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.ai-providers.advert-record-schema';
+const ID_SELF_HOSTED = 'openwop.requirement.ai-providers.self-hosted-boolean';
+const ID_AUTH_SHAPE = 'openwop.requirement.ai-providers.auth-modes-flat-list';
+const ID_INLINE_MEDIA = 'openwop.requirement.ai-providers.max-inline-media-bytes';
+const ID_PREFIX_CACHE = 'openwop.requirement.ai-providers.prompt-prefix-cache-boolean';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 aiProviders advertisement (host-services.md §aiProviders)', () => {
+  it('the aiProviders record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = recordSchemaLeg(PROFILE, doc, 'aiProviders', 'host-services.md §aiProviders');
+    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('aiProviders.selfHosted is one boolean', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = aiProvidersSelfHostedLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_SELF_HOSTED, x.doc, x.message)).toBe(true);
+  });
+
+  it('aiProviders.authModes is one flat list of modes', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = aiProvidersAuthModesShapeLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_AUTH_SHAPE, x.doc, x.message)).toBe(true);
+  });
+
+  it('aiProviders.maxInlineMediaBytes is an integer of at least 1', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = aiProvidersInlineMediaLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_INLINE_MEDIA, x.doc, x.message)).toBe(true);
+  });
+
+  it('aiProviders.promptPrefixCache is one boolean', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = aiProvidersPromptPrefixCacheLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_PREFIX_CACHE, 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({});
+  });
+});

package/src/scenarios/v2-envelope-variant-discriminator-static.test.ts

@@ -0,0 +1,57 @@
+/**
+ * v2 — variant payload discrimination, statically (RFC 0031 §A). The v1 twin
+ * is `envelope-variant-discriminator-static`; the walker lives in
+ * `lib/envelope-schema-static.ts`.
+ *
+ * For every payload schema in `schemas/v2/envelopes/`:
+ *   no oneOf       `oneOf` appears at no depth (Gemini drops it silently, so a
+ *                  model gets a looser schema than declared);
+ *   discriminated  in a variant union — an `anyOf` where two or more branches
+ *                  can be objects — every object branch declares, in `required`,
+ *                  a property of `type: string` with a one-value `enum`; a `$ref`
+ *                  branch is accepted unresolved, as at v1. A type union with at
+ *                  most one object branch (`string | binding`, as
+ *                  `ui.a2ui-surface` payload v2's `dyn*` defs declare) is
+ *                  selected by JSON type and is not judged: a scalar branch has
+ *                  no property to discriminate on. This scoping is new at v2 —
+ *                  the v1 walker flagged every non-`$ref` branch, which no v1
+ *                  schema exercised.
+ *
+ * No v2 core document states this rule: `spec/v2/core/` carries no text on
+ * variant payload discrimination (the nearest is `ext/a2uiSurface/README.md`,
+ * whose components are "discriminated by a single-string-enum `component`").
+ * The requirement is cited to RFC 0031 §A, its only normative home.
+ *
+ * Host-free: every leg runs with no OPENWOP_BASE_URL.
+ *
+ * @see RFCS/0031-envelope-variants-and-model-capabilities.md §A
+ */
+
+import { describe, it, expect } from 'vitest';
+import { req } from '../lib/requirement-ids.js';
+import { anyOfDiscriminatorViolations, listV2EnvelopeKinds, loadV2EnvelopeSchema, oneOfViolations, UNIVERSAL_KINDS } from '../lib/envelope-schema-static.js';
+
+const DOC = 'RFC 0031 §A';
+const ID_PRESENT = 'openwop.requirement.envelopes.payload-schemas-present';
+const ID_NO_ONEOF = 'openwop.requirement.envelopes.variant-no-oneof';
+const ID_DISCRIMINATED = 'openwop.requirement.envelopes.variant-anyof-discriminated';
+
+const KINDS = listV2EnvelopeKinds();
+
+describe('v2 envelope variant discrimination (RFC 0031 §A)', () => {
+  it('schemas/v2/envelopes carries a payload schema for each universal kind', () => {
+    for (const k of UNIVERSAL_KINDS) expect(KINDS.includes(k), req(ID_PRESENT, DOC, `schemas/v2/envelopes/${k}.schema.json MUST exist`)).toBe(true);
+  });
+
+  for (const kind of KINDS) {
+    it(`${kind} contains no oneOf at any depth`, () => {
+      const v = oneOfViolations(loadV2EnvelopeSchema(kind));
+      expect(v, req(ID_NO_ONEOF, DOC, `${kind} MUST NOT use oneOf — use anyOf with a single-string-enum discriminator: ${JSON.stringify(v)}`)).toEqual([]);
+    });
+
+    it(`${kind} discriminates every anyOf branch by a single-string-enum property`, () => {
+      const v = anyOfDiscriminatorViolations(loadV2EnvelopeSchema(kind));
+      expect(v, req(ID_DISCRIMINATED, DOC, `${kind} anyOf branches without a discriminator: ${JSON.stringify(v)}`)).toEqual([]);
+    });
+  }
+});

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

@@ -0,0 +1,85 @@
+/**
+ * v2 — the `envelopes` advertisement (`spec/v2/core/events.md` §`envelopes`;
+ * RFCs 0030, 0032, 0033). A claims-check family: what the host says about its
+ * envelope posture is what is witnessed. The v1 twins are the advertisement
+ * legs of `envelope-reasoning-shape`, `envelope-retry-attempted` /
+ * `envelope-refusal-shape` and `envelope-completion-distinguishes-truncation`;
+ * the legs live in `lib/family-advert-witness.ts`.
+ *
+ *   record       the record validates against its seat in
+ *                `schemas/v2/capabilities.schema.json` (no v1 `supported` seat);
+ *   reasoning    `reasoning.promptDirective` is mandatory | advisory | off;
+ *   tier-one     `tierOneSubsetCompliance` is strict | warn | off;
+ *   reliability  `reliability.events[]` names only reliability events and, with
+ *                the four v1 dotted names folded to their v2 equivalents
+ *                (aliases until 3.0, RFC 0228 §G), lists the two MUST-tier
+ *                events `envelope.retry-exhausted` and `envelope.refusal`;
+ *   completion   `reliability.completion.distinguishesTruncation` is a boolean
+ *                and `truncationBudgetMultiplier` is in [1, 8].
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `envelopes` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/events.md §envelopes
+ */
+
+import { describe, it, expect } from 'vitest';
+import { 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 { envelopesCompletionLeg, envelopesReasoningLeg, envelopesReliabilityLeg, envelopesTierOneLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const ID_RECORD = 'openwop.requirement.envelopes.advert-record-schema';
+const ID_REASONING = 'openwop.requirement.envelopes.reasoning-advert-shape';
+const ID_TIER_ONE = 'openwop.requirement.envelopes.tier-one-subset-compliance-value';
+const ID_RELIABILITY = 'openwop.requirement.envelopes.reliability-events-advert';
+const ID_COMPLETION = 'openwop.requirement.envelopes.completion-advert-shape';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+
+describe('v2 envelopes advertisement (events.md §envelopes)', () => {
+  it('the envelopes record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = recordSchemaLeg(PROFILE, doc, 'envelopes', 'events.md §envelopes');
+    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('envelopes.reasoning.promptDirective is mandatory, advisory or off', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = envelopesReasoningLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_REASONING, x.doc, x.message)).toBe(true);
+  });
+
+  it('envelopes.tierOneSubsetCompliance is strict, warn or off', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = envelopesTierOneLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_TIER_ONE, x.doc, x.message)).toBe(true);
+  });
+
+  it('envelopes.reliability.events lists only reliability events and includes retry-exhausted and refusal', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = envelopesReliabilityLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_RELIABILITY, x.doc, x.message)).toBe(true);
+  });
+
+  it('envelopes.reliability.completion.distinguishesTruncation is a boolean', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = envelopesCompletionLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_COMPLETION, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-i18n-negotiation.test.ts

@@ -0,0 +1,91 @@
+/**
+ * v2 — locale negotiation (`spec/v2/core/i18n.md` §`Accept-Language`,
+ * §Fallback, §Error envelopes, §The `i18n` record). The v1 twin is
+ * `i18n-negotiation`; the legs live in `lib/i18n-negotiation-witness.ts`, and
+ * what differs between majors (the unversioned run path, the `~`-projected
+ * bound id, presence-as-advertisement) is the profile row.
+ *
+ *   shape        the `i18n` record validates against the v2 capabilities
+ *                schema, and `supportedLocales` contains `defaultLocale`;
+ *   unsupported  an unsupported `Accept-Language` is answered exactly as the
+ *                same request without it; `Content-Language`, when sent, is a
+ *                BCP 47 tag naming the default locale;
+ *   malformed    a malformed `Accept-Language` never yields `400`;
+ *   error code   the `error` code and the `details` keys are identical under
+ *                the default and a negotiated locale.
+ *
+ * The probe reads a run id no host minted (`GET /runs/{bound id}`). Its answer
+ * is not pinned — `404 not_found`, or `403 id_tenant_mismatch` because the
+ * tenant segment is not the caller's — since every leg compares against the
+ * same request with no `Accept-Language`.
+ *
+ * Dispositions: no target ⇒ `inapplicable`; discovery unreadable ⇒ `blocked`;
+ * `i18n` not advertised ⇒ `inapplicable` (gated with the record's presence,
+ * never a strict-mode failure); a probe that answers no 4xx envelope ⇒
+ * `blocked` (no baseline).
+ *
+ * Proven against a scratch double in `lib/i18n-negotiation-witness.test.ts`.
+ *
+ * @see spec/v2/core/i18n.md
+ * @see schemas/v2/capabilities.schema.json §i18n
+ */
+
+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 { errorCodeLeg, i18nAdverts, malformedLeg, shapeLeg, unsupportedLeg, type I18nAdverts } from '../lib/i18n-negotiation-witness.js';
+
+const PROFILE = majorProfile(2);
+const ID_SHAPE = 'openwop.requirement.i18n.record-shape';
+const ID_UNSUPPORTED = 'openwop.requirement.i18n.unsupported-locale-falls-back';
+const ID_MALFORMED = 'openwop.requirement.i18n.malformed-accept-language-not-400';
+const ID_CODE = 'openwop.requirement.i18n.error-code-locale-invariant';
+const HTTP_SKIP = !process.env['OPENWOP_BASE_URL'];
+const validRecord = v2RefValidator('capabilities.schema.json#/properties/i18n');
+
+type Ready = { ok: true; a: I18nAdverts } | { ok: false; skip: () => undefined };
+async function ready(): Promise<Ready> {
+  if (HTTP_SKIP) return { ok: false, skip: () => 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 { ok: false, skip: () => softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0') };
+  if ((await familyAdvertised('i18n')) === null) return { ok: false, skip: () => softSkip('inapplicable', 'the host does not advertise i18n — it serves one locale and ignores Accept-Language (i18n.md §The i18n record)') };
+  return { ok: true, a: i18nAdverts(PROFILE, doc) };
+}
+
+describe('v2 i18n negotiation (i18n.md §Accept-Language, §Fallback, §Error envelopes)', () => {
+  it('the advertised i18n record is well-formed and lists its default locale', async () => {
+    const r = await ready();
+    if (!r.ok) return r.skip();
+    const v = validRecord(r.a.record);
+    const out = shapeLeg(r.a);
+    expect(v.ok, req(ID_SHAPE, 'schemas/v2/capabilities.schema.json §i18n', `the i18n record MUST validate: ${v.errors}`)).toBe(true);
+    if (out.kind === 'observed') for (const x of out.findings) expect(x.ok, req(ID_SHAPE, x.doc, x.message)).toBe(true);
+  });
+
+  it('an unsupported Accept-Language falls back and Content-Language never lies', async () => {
+    const r = await ready();
+    if (!r.ok) return r.skip();
+    const out = await unsupportedLeg(PROFILE, r.a);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_UNSUPPORTED, x.doc, x.message)).toBe(true);
+  });
+
+  it('a malformed Accept-Language does not cause 400', async () => {
+    const r = await ready();
+    if (!r.ok) return r.skip();
+    const out = await malformedLeg(PROFILE, r.a);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_MALFORMED, x.doc, x.message)).toBe(true);
+  });
+
+  it('the error code and details keys are identical under every negotiated locale', async () => {
+    const r = await ready();
+    if (!r.ok) return r.skip();
+    const out = await errorCodeLeg(PROFILE, r.a);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_CODE, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-limits-envelope-caps-advertisement.test.ts

@@ -0,0 +1,61 @@
+/**
+ * v2 — the three envelope caps on `limits` (`spec/v2/core/runs.md` §Limits:
+ * "`limits` always carries `clarificationRounds` (per task), `schemaRounds`
+ * (per envelope) and `envelopesPerTurn` (per chat turn)"). The v1 twin is the
+ * advertisement half of `aiEnvelope.capBreached`; the legs live in
+ * `lib/family-advert-witness.ts`. The other `limits` facets
+ * (`maxRunDurationMs`, `maxLoopIterations`) are `v2-run-execution-bounds`.
+ *
+ * Each cap MUST be present and validate against its subschema in
+ * `schemas/v2/capabilities.schema.json` (a non-negative integer).
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `limits` absent ⇒
+ * `inapplicable` (at v2 presence of the record is the claim; the v1 rule that
+ * `limits` itself is always present has no v2 seat — the root schema requires
+ * only `protocolVersions` and `preferredVersion`).
+ *
+ * @see spec/v2/core/runs.md §Limits
+ */
+
+import { describe, it, expect } from 'vitest';
+import { 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 { limitsCapLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_CLARIFICATION = 'openwop.requirement.limits.clarification-rounds-advertised';
+const ID_SCHEMA = 'openwop.requirement.limits.schema-rounds-advertised';
+const ID_ENVELOPES = 'openwop.requirement.limits.envelopes-per-turn-advertised';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 limits envelope caps (runs.md §Limits)', () => {
+  it('limits.clarificationRounds is present and a non-negative integer', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = limitsCapLeg(PROFILE, doc, 'clarificationRounds');
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_CLARIFICATION, x.doc, x.message)).toBe(true);
+  });
+
+  it('limits.schemaRounds is present and a non-negative integer', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = limitsCapLeg(PROFILE, doc, 'schemaRounds');
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_SCHEMA, x.doc, x.message)).toBe(true);
+  });
+
+  it('limits.envelopesPerTurn is present and a non-negative integer', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = limitsCapLeg(PROFILE, doc, 'envelopesPerTurn');
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_ENVELOPES, x.doc, x.message)).toBe(true);
+  });
+});