@openwop/openwop-conformance 2.45.15 → 2.45.17

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-export-bundle-static.test.ts

@@ -0,0 +1,108 @@
+/**
+ * v2 — the export bundle, the `import.applied` payload and the `portability`
+ * record's `import ⇒ dryRun` rule, statically (`spec/v2/core/portability.md`;
+ * RFC 0098; invariant `export-bundle-no-credential-material`). The v1 twin is
+ * the server-free half of `export-bundle-portability`; its import-seam leg is
+ * not ported (v2 defines no import route).
+ *
+ *   version     a bundle carries `bundleVersion: "2"`. This FLIPS the v1 leg:
+ *               at v1 `"1"` was good and `"2"` rejected; at v2 `"1"` is
+ *               rejected;
+ *   shape       an unknown item kind and an item without `ref` are rejected;
+ *   no-cred     no credential-named field is admitted at the bundle root or
+ *               under `source` ("A bundle MUST NOT contain credential values");
+ *   applied     `import.applied` is a registered v2 event type, and its payload
+ *               is counts and references only, never item payloads;
+ *   dryRun      the capabilities seat refuses `import: true` without
+ *               `dryRun: true` ("A host advertising `import` MUST advertise
+ *               `dryRun: true`"). At v2 that `if/then` sits in the record's
+ *               `allOf`, so it is witnessed by validation, not by reading
+ *               `portability.if`.
+ *
+ * Host-free: every leg runs with no OPENWOP_BASE_URL.
+ *
+ * @see spec/v2/core/portability.md
+ * @see schemas/v2/export-bundle.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2RefValidator, v2Validator } from '../lib/v2.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'portability.md §The export bundle';
+const ID_VERSION = 'openwop.requirement.portability.bundle-version-2';
+const ID_SHAPE = 'openwop.requirement.portability.bundle-item-shape';
+const ID_NO_CRED = 'openwop.requirement.portability.bundle-no-credential-field';
+const ID_APPLIED = 'openwop.requirement.portability.import-applied-content-free';
+const ID_DRY_RUN = 'openwop.requirement.portability.import-dry-run-schema-rule';
+
+const CRED_NAMES = ['clientSecret', 'client_secret', 'apiKey', 'api_key', 'accessToken', 'refreshToken', 'password', 'privateKey'] as const;
+
+const GOOD = {
+  bundleVersion: '2',
+  source: { origin: 'https://host-a.example', exportedAt: '2026-10-04T00:00:00Z' },
+  items: [
+    { kind: 'prompt-template', ref: 'tpl-1', payload: { templateId: 'welcome', version: '1.0.0' } },
+    { kind: 'connection-ref', ref: 'conn-1', dependsOn: ['tpl-1'], payload: { provider: 'slack', credentialRef: 'cred:abc' } },
+  ],
+} as const;
+
+describe('v2 export bundle (portability.md §The export bundle)', () => {
+  const validate = v2Validator('export-bundle');
+
+  it('accepts a conforming bundle at bundleVersion "2"', () => {
+    const r = validate(GOOD);
+    expect(r.ok, req(ID_VERSION, DOC, `a conforming v2 bundle MUST validate (${r.errors})`)).toBe(true);
+  });
+
+  it('rejects the v1 bundleVersion "1" and a missing bundleVersion', () => {
+    expect(validate({ ...GOOD, bundleVersion: '1' }).ok, req(ID_VERSION, DOC, 'a v2 bundle MUST carry bundleVersion "2"; "1" MUST be rejected')).toBe(false);
+    const { bundleVersion: _gone, ...rest } = GOOD;
+    expect(validate(rest).ok, req(ID_VERSION, DOC, 'a bundle without bundleVersion MUST be rejected')).toBe(false);
+  });
+
+  it('rejects an unknown item kind and an item without ref', () => {
+    expect(validate({ ...GOOD, items: [{ kind: 'workflow', ref: 'x', payload: {} }] }).ok, req(ID_SHAPE, DOC, 'an unknown item kind MUST be rejected')).toBe(false);
+    expect(validate({ ...GOOD, items: [{ kind: 'agent', payload: {} }] }).ok, req(ID_SHAPE, DOC, 'an item without a ref MUST be rejected')).toBe(false);
+  });
+
+  it.each(CRED_NAMES)('admits no %s field at the bundle root or under source', (name) => {
+    expect(validate({ ...GOOD, [name]: 'xxx' }).ok, req(ID_NO_CRED, DOC, `a "${name}" field at the bundle root MUST NOT validate`)).toBe(false);
+    expect(validate({ ...GOOD, source: { ...GOOD.source, [name]: 'xxx' } }).ok, req(ID_NO_CRED, DOC, `a "${name}" field under source MUST NOT validate`)).toBe(false);
+  });
+});
+
+describe('v2 import.applied (portability.md §The import.applied event)', () => {
+  const applied = v2RefValidator('run-event-payloads.schema.json#/$defs/importApplied');
+  const ADOC = 'portability.md §The import.applied event';
+
+  it('import.applied is a registered v2 run-event type', () => {
+    const r = v2RefValidator('run-event.schema.json#/properties/type')('import.applied');
+    expect(r.ok, req(ID_APPLIED, ADOC, `import.applied MUST be accepted by the v2 run-event type union (${r.errors})`)).toBe(true);
+  });
+
+  it('a counts-and-refs payload validates; one carrying item payloads does not', () => {
+    const r = applied({ bundleOrigin: 'https://host-a.example', counts: { created: 2, skipped: 1 }, secretsToRebind: ['anthropic'] });
+    expect(r.ok, req(ID_APPLIED, ADOC, `a content-free import.applied MUST validate (${r.errors})`)).toBe(true);
+    expect(applied({ bundleOrigin: 'h', counts: { created: 1 }, items: [{ payload: {} }] }).ok, req(ID_APPLIED, ADOC, 'import.applied MUST NOT carry item payloads')).toBe(false);
+    expect(applied({ bundleOrigin: 'h', counts: { created: 1, leaked: 1 } }).ok, req(ID_APPLIED, ADOC, 'import.applied counts MUST be the four outcome tallies only')).toBe(false);
+  });
+});
+
+describe('v2 portability record: import ⇒ dryRun (portability.md §The portability record)', () => {
+  const record = v2RefValidator('capabilities.schema.json#/properties/portability');
+  const PDOC = 'portability.md §The portability record';
+  const base = { status: 'experimental', since: '2.0', until: '2099-01-01', witness: 'witnessable-gated', export: true } as const;
+
+  it('import: true with dryRun: true validates; import: false needs no dryRun', () => {
+    for (const r of [{ ...base, import: true, dryRun: true }, { ...base, import: false }, { ...base }]) {
+      const v = record(r);
+      expect(v.ok, req(ID_DRY_RUN, PDOC, `a portability record ${JSON.stringify(r)} MUST validate (${v.errors})`)).toBe(true);
+    }
+  });
+
+  it('import: true without dryRun, or with dryRun: false, is rejected', () => {
+    expect(record({ ...base, import: true }).ok, req(ID_DRY_RUN, PDOC, 'import: true without dryRun MUST be rejected')).toBe(false);
+    expect(record({ ...base, import: true, dryRun: false }).ok, req(ID_DRY_RUN, PDOC, 'import: true with dryRun: false MUST be rejected')).toBe(false);
+  });
+});

package/src/scenarios/v2-multi-party-conversation-advertisement.test.ts

@@ -0,0 +1,52 @@
+/**
+ * v2 — the `multiPartyConversation` advertisement (`spec/v2/core/conversation.md` §`multiPartyConversation`): the multi-party conversation (council) claim. The v1 twin is
+ * `multi-party-conversation-shape`;
+ * the legs live in `lib/family-advert-witness.ts` (witness wave 3).
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *   max-participants multiPartyConversation.maxParticipants is an integer of at least 2;
+ *
+ * Not here: roster enforcement and the over-cap refusal: v2 has no client route that opens a conversation with a roster, and the refusals name no error code (TODO §8).
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `multiPartyConversation` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/conversation.md §`multiPartyConversation`
+ */
+
+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 { multiPartyMaxParticipantsLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'conversation.md §multiPartyConversation';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.multi-party-conversation.advert-record-schema';
+const ID_MAX_PARTICIPANTS = 'openwop.requirement.multi-party-conversation.max-participants';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 multiPartyConversation advertisement (conversation.md §multiPartyConversation)', () => {
+  it('the multiPartyConversation record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('multiPartyConversation'))) return softSkip('inapplicable', 'the host does not advertise multiPartyConversation');
+    const out = recordSchemaLeg(PROFILE, doc, 'multiPartyConversation', 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('multiPartyConversation.maxParticipants is an integer of at least 2', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('multiPartyConversation'))) return softSkip('inapplicable', 'the host does not advertise multiPartyConversation');
+    const out = multiPartyMaxParticipantsLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_MAX_PARTICIPANTS, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-node-pack-runtimes-advertisement.test.ts

@@ -0,0 +1,52 @@
+/**
+ * v2 — the `nodePackRuntimes` advertisement (`spec/v2/core/node-pack-runtimes.md` §WASM): the node-pack runtimes a host loads. The v1 twin is
+ * `wasm-pack-load`;
+ * the legs live in `lib/family-advert-witness.ts` (witness wave 3).
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *   wasm-facet-shape nodePackRuntimes.wasm lists ABI versions and a memory cap in range;
+ *
+ * Not here: ABI rejection at load and the memory-cap breach need an operator-installed fixture pack.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `nodePackRuntimes` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/node-pack-runtimes.md §WASM
+ */
+
+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 { nodePackRuntimesWasmLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'node-pack-runtimes.md §WASM';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.node-pack-runtimes.advert-record-schema';
+const ID_WASM_FACET_SHAPE = 'openwop.requirement.node-pack-runtimes.wasm-facet-shape';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 nodePackRuntimes advertisement (node-pack-runtimes.md §WASM)', () => {
+  it('the nodePackRuntimes record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('nodePackRuntimes'))) return softSkip('inapplicable', 'the host does not advertise nodePackRuntimes');
+    const out = recordSchemaLeg(PROFILE, doc, 'nodePackRuntimes', 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('nodePackRuntimes.wasm lists ABI versions and a memory cap in range', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('nodePackRuntimes'))) return softSkip('inapplicable', 'the host does not advertise nodePackRuntimes');
+    const out = nodePackRuntimesWasmLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_WASM_FACET_SHAPE, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-nondeterminism-policy-advertisement.test.ts

@@ -0,0 +1,41 @@
+/**
+ * v2 — the `nondeterminismPolicy` advertisement (`spec/v2/core/replay.md` §Declared nondeterminism): the declared-nondeterminism claim. The v1 twin is
+ * `agent-platform-profile`;
+ * the legs live in `lib/family-advert-witness.ts` (witness wave 3).
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *
+ * Not here: recording every declared source needs a `sources[]` seat and a named event (TODO §8).
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `nondeterminismPolicy` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/replay.md §Declared nondeterminism
+ */
+
+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 = 'replay.md §Declared nondeterminism';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.nondeterminism-policy.advert-record-schema';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 nondeterminismPolicy advertisement (replay.md §Declared nondeterminism)', () => {
+  it('the nondeterminismPolicy record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('nondeterminismPolicy'))) return softSkip('inapplicable', 'the host does not advertise nondeterminismPolicy');
+    const out = recordSchemaLeg(PROFILE, doc, 'nondeterminismPolicy', 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-portability-advertisement.test.ts

@@ -0,0 +1,63 @@
+/**
+ * v2 — the `portability` advertisement (`spec/v2/core/portability.md`; RFC
+ * 0098). The v1 twin is the advertisement leg of `export-bundle-portability`;
+ * the legs live in `lib/family-advert-witness.ts`.
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *   import⇒dryRun  "A host advertising `import` MUST advertise `dryRun: true`",
+ *                  read as the schema reads it: `import: true` ⇒ `dryRun: true`;
+ *   kinds          unique export-bundle item kinds.
+ *
+ * Not here: import refusal of credential material, dry-run no-write and
+ * idempotence: v2 defines no import route ("a host serves them on routes of its
+ * own"). The bundle shape is `v2-export-bundle-static`.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `portability` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/portability.md §The portability record
+ */
+
+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 { portabilityImportDryRunLeg, portabilityKindsLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'portability.md §The portability record';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.portability.advert-record-schema';
+const ID_IMPORT_REQUIRES_DRY_RUN = 'openwop.requirement.portability.import-requires-dry-run';
+const ID_KINDS_SHAPE = 'openwop.requirement.portability.kinds-shape';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 portability advertisement (portability.md §The portability record)', () => {
+  it('the portability record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = recordSchemaLeg(PROFILE, doc, 'portability', 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('a host advertising portability.import advertises dryRun: true', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = portabilityImportDryRunLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_IMPORT_REQUIRES_DRY_RUN, x.doc, x.message)).toBe(true);
+  });
+
+  it('portability.kinds lists unique export-bundle item kinds', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = portabilityKindsLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_KINDS_SHAPE, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-prompt-library-advertisement.test.ts

@@ -0,0 +1,40 @@
+/**
+ * v2 — the `promptLibrary` advertisement (`spec/v2/core/host-services.md` §`promptLibrary`): the prompt library 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: returning a pinned version verbatim needs a fixture pack.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `promptLibrary` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/host-services.md §`promptLibrary`
+ */
+
+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 = 'host-services.md §promptLibrary';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.prompt-library.advert-record-schema';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 promptLibrary advertisement (host-services.md §promptLibrary)', () => {
+  it('the promptLibrary record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    if (!(await familyAdvertised('promptLibrary'))) return softSkip('inapplicable', 'the host does not advertise promptLibrary');
+    const out = recordSchemaLeg(PROFILE, doc, 'promptLibrary', 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-prompt-list-and-fetch.test.ts

@@ -8,7 +8,9 @@
  *               validates against the closed v2 PromptTemplate;
  *   filters     `?kind=system` and `?source=host` narrow;
  *   fetch       a listed template is fetched by id;
- *   etag        an ETag, when sent (a SHOULD), revalidates to `304`;
+ *   etag        advisory: an ETag, when sent (a SHOULD), revalidates to `304`;
+ *               a non-304 is recorded `inapplicable`, never failed (v2 binds
+ *               304 only on discovery and the run snapshot, headers.md);
  *   unknown     an unknown id is `404` with the v2 error envelope;
  *   gate off    NEW at v2, unaided: with `prompts.endpointsSupported` not
  *               advertised (the record absent, or the facet not `true`),
@@ -77,7 +79,7 @@ describe('v2 prompt library: read surface (host-services.md §prompts)', () => {
     for (const x of out.findings) expect(x.ok, req(ID_FETCH, x.doc, x.message)).toBe(true);
   });
 
-  it('an ETag, when sent, revalidates to 304', async () => {
+  it('advisory: an ETag, when sent, revalidates to 304', async () => {
     const r = await ready();
     if (!r.ok) return r.skip();
     const out = await etagLeg(PROFILE, r.a);

package/src/scenarios/v2-provider-usage-advertisement.test.ts

@@ -0,0 +1,61 @@
+/**
+ * v2 — the `providerUsage` advertisement (`spec/v2/core/events.md`
+ * §providerUsage; RFC 0026). The v1 twin is the advertisement leg of
+ * `provider-usage`; the legs live in `lib/family-advert-witness.ts`.
+ *
+ *   record         the record validates against its capabilities-schema seat;
+ *   costEstimates  one boolean;
+ *   currency       an ISO 4217 code, `^[A-Z]{3}$` (absent means USD).
+ *
+ * Not here: exactly-one-per-invocation emission needs a mock-provider run; the
+ * payload shape is `v2-provider-usage-payload-static`.
+ *
+ * Dispositions: discovery unreadable ⇒ `blocked`; `providerUsage` absent, or the
+ * facet a leg reads absent ⇒ `inapplicable`.
+ *
+ * @see spec/v2/core/events.md §providerUsage
+ */
+
+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 { providerUsageCostEstimatesLeg, providerUsageCurrencyLeg, recordSchemaLeg } from '../lib/family-advert-witness.js';
+
+const PROFILE = majorProfile(2);
+const DOC = 'events.md §providerUsage';
+const UNREADABLE = 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0';
+const ID_RECORD = 'openwop.requirement.provider-usage.advert-record-schema';
+const ID_COST_ESTIMATES_BOOLEAN = 'openwop.requirement.provider-usage.cost-estimates-boolean';
+const ID_CURRENCY_ISO_4217 = 'openwop.requirement.provider-usage.currency-iso-4217';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+describe('v2 providerUsage advertisement (events.md §providerUsage)', () => {
+  it('the providerUsage record validates against its capabilities-schema seat', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = recordSchemaLeg(PROFILE, doc, 'providerUsage', 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('providerUsage.costEstimates is one boolean', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = providerUsageCostEstimatesLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_COST_ESTIMATES_BOOLEAN, x.doc, x.message)).toBe(true);
+  });
+
+  it('providerUsage.currency is an ISO 4217 code', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', UNREADABLE);
+    const out = providerUsageCurrencyLeg(PROFILE, doc);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_CURRENCY_ISO_4217, x.doc, x.message)).toBe(true);
+  });
+});

package/src/scenarios/v2-provider-usage-emission.test.ts

@@ -0,0 +1,50 @@
+/**
+ * v2 — `provider.usage` emission (`spec/v2/core/events.md` §`providerUsage`:
+ * "A host advertising `providerUsage` MUST emit exactly one `provider.usage`
+ * per LLM provider invocation, before that node's `node.completed`"). The leg
+ * lives in `lib/provider-usage-witness.ts`.
+ *
+ * A run of `conformance-context-budget-live` (a supervisor on the host's LIVE
+ * model — the fixture catalog forbids advertising it with a mock) is created
+ * with `POST /runs` and its log read with `events/poll`:
+ *   - at least one `provider.usage` is on the log;
+ *   - each precedes a `node.completed` of the node it names;
+ *   - each payload validates against the v2 `providerUsage` def.
+ * "Exactly one per invocation" is NOT asserted: the invocation count is not
+ * observable from outside.
+ *
+ * Dispositions: `providerUsage` not advertised, or the fixture not in
+ * `fixtures[]` ⇒ `inapplicable`; the live run ends without completing and with
+ * no `provider.usage` ⇒ `blocked`; discovery unreadable ⇒ `blocked`.
+ *
+ * Proven against a double in `lib/provider-usage-witness.test.ts`.
+ *
+ * @see spec/v2/core/events.md §providerUsage
+ * @see conformance/fixtures.md conformance-context-budget-live
+ */
+
+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 { driveUsage, judgeUsage } from '../lib/provider-usage-witness.js';
+
+const PROFILE = majorProfile(2);
+const ID_EMITTED = 'openwop.requirement.provider-usage.emitted-before-node-completed';
+const validate = v2RefValidator('run-event-payloads.schema.json#/$defs/providerUsage');
+
+describe('v2 providerUsage: emission on a live model call (events.md §providerUsage)', () => {
+  it('a live-model run carries provider.usage, each before its node.completed and each payload valid', async () => {
+    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('providerUsage'))) return softSkip('inapplicable', 'the host does not advertise providerUsage');
+    const o = await driveUsage(PROFILE, doc);
+    if ('kind' in o) return softSkip(o.disposition, o.reason);
+    const out = judgeUsage(o, validate);
+    if (out.kind === 'skip') return softSkip(out.disposition, out.reason);
+    for (const x of out.findings) expect(x.ok, req(ID_EMITTED, x.doc, x.message)).toBe(true);
+  }, 330_000);
+});

package/src/scenarios/v2-provider-usage-payload-static.test.ts

@@ -0,0 +1,92 @@
+/**
+ * v2 — the `provider.usage` payload, statically (`spec/v2/core/events.md`
+ * §providerUsage; `schemas/v2/run-event-payloads.schema.json#/$defs/providerUsage`;
+ * RFC 0026; invariant `provider-usage-no-credential-leak`). The v1 twin is the
+ * schema half of `provider-usage`; its emit-seam legs (and the v1
+ * `provider_usage_credential_leak` code, which `spec/v2/errors.json` does not
+ * carry) are not ported.
+ *
+ *   type       `provider.usage` is a registered v2 event type;
+ *   positive   a payload with the four required fields, and one with every
+ *              optional field, validates;
+ *   required   a payload missing provider, model, inputTokens or outputTokens
+ *              is rejected;
+ *   counts     a fractional or negative token count is rejected;
+ *   cost       a negative `costEstimateUsd` is rejected; `currency` is an
+ *              ISO 4217 code ("`providerUsage.currency` is the ISO 4217
+ *              currency of `costEstimateUsd`");
+ *   no-leak    the payload is closed, so a credential ref, a hashed credential
+ *              id or prompt/response text is rejected ("The payload MUST NOT
+ *              carry credential refs, hashed credential identifiers, or prompt
+ *              or response text").
+ *
+ * Host-free: every leg runs with no OPENWOP_BASE_URL.
+ *
+ * @see spec/v2/core/events.md §providerUsage
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2RefValidator } from '../lib/v2.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'events.md §providerUsage';
+const ID_TYPE = 'openwop.requirement.provider-usage.event-type-registered';
+const ID_POSITIVE = 'openwop.requirement.provider-usage.payload-well-formed-accepted';
+const ID_REQUIRED = 'openwop.requirement.provider-usage.payload-required-fields';
+const ID_COUNTS = 'openwop.requirement.provider-usage.payload-token-counts';
+const ID_COST = 'openwop.requirement.provider-usage.payload-cost-and-currency';
+const ID_NO_LEAK = 'openwop.requirement.provider-usage.payload-no-credential-or-content';
+
+const MINIMAL = { provider: 'anthropic', model: 'claude-x', inputTokens: 120, outputTokens: 30 } as const;
+const FULL = { ...MINIMAL, totalTokens: 150, costEstimateUsd: 0.0021, currency: 'EUR', cacheHit: false, cacheReadTokens: 0, cacheWriteTokens: 64 } as const;
+
+function without(field: string): Record<string, unknown> {
+  const c: Record<string, unknown> = { ...MINIMAL };
+  delete c[field];
+  return c;
+}
+
+describe('v2 provider.usage payload (events.md §providerUsage)', () => {
+  const validate = v2RefValidator('run-event-payloads.schema.json#/$defs/providerUsage');
+
+  it('provider.usage is a registered v2 run-event type', () => {
+    const r = v2RefValidator('run-event.schema.json#/properties/type')('provider.usage');
+    expect(r.ok, req(ID_TYPE, DOC, `provider.usage MUST be accepted by the v2 run-event type union (${r.errors})`)).toBe(true);
+  });
+
+  it('accepts a minimal and a full payload', () => {
+    for (const p of [MINIMAL, FULL]) {
+      const r = validate(p);
+      expect(r.ok, req(ID_POSITIVE, DOC, `a well-formed provider.usage payload MUST validate (${r.errors})`)).toBe(true);
+    }
+  });
+
+  it.each(['provider', 'model', 'inputTokens', 'outputTokens'])('rejects a payload without %s', (field) => {
+    expect(validate(without(field)).ok, req(ID_REQUIRED, DOC, `a provider.usage payload without ${field} MUST be rejected`)).toBe(false);
+  });
+
+  it.each<[string, Record<string, unknown>]>([
+    ['a fractional inputTokens', { ...MINIMAL, inputTokens: 1.5 }],
+    ['a negative outputTokens', { ...MINIMAL, outputTokens: -1 }],
+    ['a string inputTokens', { ...MINIMAL, inputTokens: '120' }],
+  ])('rejects %s', (what, p) => {
+    expect(validate(p).ok, req(ID_COUNTS, DOC, `a provider.usage payload with ${what} MUST be rejected`)).toBe(false);
+  });
+
+  it.each<[string, Record<string, unknown>]>([
+    ['a negative costEstimateUsd', { ...MINIMAL, costEstimateUsd: -0.01 }],
+    ['a lower-case currency', { ...MINIMAL, costEstimateUsd: 0.01, currency: 'usd' }],
+    ['a currency symbol', { ...MINIMAL, costEstimateUsd: 0.01, currency: '$' }],
+  ])('rejects %s', (what, p) => {
+    expect(validate(p).ok, req(ID_COST, DOC, `a provider.usage payload with ${what} MUST be rejected`)).toBe(false);
+  });
+
+  it.each<[string, Record<string, unknown>]>([
+    ['a credential ref', { ...MINIMAL, credentialRef: 'secret:tenant:byok-anthropic:v1' }],
+    ['a hashed credential id', { ...MINIMAL, credentialHash: 'sha256:9f2c' }],
+    ['prompt text', { ...MINIMAL, prompt: 'summarize the attached notes' }],
+    ['response text', { ...MINIMAL, response: 'Here is a summary' }],
+  ])('rejects a payload carrying %s', (what, p) => {
+    expect(validate(p).ok, req(ID_NO_LEAK, DOC, `the provider.usage payload MUST NOT carry ${what}`)).toBe(false);
+  });
+});