@openwop/openwop-conformance 2.45.15 → 2.45.17

package/src/lib/family-advert-witness.ts

@@ -1,7 +1,14 @@
 /**
- * The advertisement-shape witness for the claims-check AI families at major 2:
- * `envelopes`, `limits` (the three envelope caps), `modelCapabilities` and
- * `aiProviders`.
+ * The advertisement-shape witness at major 2. Wave 1: the claims-check AI
+ * families `envelopes`, `limits` (the three envelope caps), `modelCapabilities`
+ * and `aiProviders`. Wave 2: the record and facet shapes of `selfHostedRunner`,
+ * `credentials`, `authorization`, `providerUsage`, `subWorkflow`, `scheduling`,
+ * `artifactTypes`, `aiEnvelope`, `deadLetter` and `portability`. Wave 3: the
+ * families no host serves at v2 — `dataResidency`, `multiPartyConversation`,
+ * `nodePackRuntimes`, `uiPlugins`, `purposePropagation` and `agentRuntime` get
+ * facet legs; `conversationTurnModelProvenance`, `channelPresence`,
+ * `nondeterminismPolicy`, `promptLibrary` and `envelopeContracts` carry no facet
+ * a host-binding v2 rule gives meaning to, so they get the record leg only.
  *
  * A claims-check family is witnessed by what the host says about itself, so
  * every leg here reads the discovery record alone. Each leg checks one facet
@@ -13,7 +20,13 @@
  * Not here, on purpose:
  *   - `limits.maxRunDurationMs` / `maxLoopIterations` — `run-bounds-witness.ts`;
  *   - every runtime rule of these families (retry routing, refusal, substitution,
- *     cap enforcement) — they need a mock-provider or envelope-accept seam.
+ *     cap enforcement, credential resolution, dispatch, schedule firing, dead-
+ *     letter retention, import) — they need a seam or a fixture run;
+ *   - `scheduling.maxFutureHorizon` as an ISO-8601 duration: the v2 schema seat
+ *     is a plain string and no v2 prose states the format as binding the host;
+ *   - a `supported` field on any record: it is not a v2 field
+ *     (`capabilities.md` §2). The record-schema leg rejects one as an unknown
+ *     key; no leg ever asserts its presence.
  *
  * Every leg is pure: `(profile, discovery) → outcome`. A family the host does
  * not advertise, or a facet it does not carry, is `inapplicable` — never a
@@ -50,7 +63,15 @@ function onFamily(profile: MajorProfile, discovery: unknown, family: string, leg
 }
 
 /** The record as a whole against its seat in the capabilities schema. Catches every v1 shape v2 retired (`supported`, `selfHosted[]`, the per-provider `authModes` map, …). */
-export function recordSchemaLeg(profile: MajorProfile, discovery: unknown, family: 'envelopes' | 'modelCapabilities' | 'aiProviders', doc: string): AdvertOutcome {
+export type AdvertFamily =
+  | 'envelopes' | 'modelCapabilities' | 'aiProviders'
+  | 'selfHostedRunner' | 'credentials' | 'authorization' | 'providerUsage' | 'subWorkflow'
+  | 'scheduling' | 'artifactTypes' | 'aiEnvelope' | 'deadLetter' | 'portability'
+  | 'dataResidency' | 'conversationTurnModelProvenance' | 'multiPartyConversation' | 'channelPresence'
+  | 'nodePackRuntimes' | 'uiPlugins' | 'purposePropagation' | 'nondeterminismPolicy'
+  | 'agentRuntime' | 'promptLibrary' | 'envelopeContracts';
+
+export function recordSchemaLeg(profile: MajorProfile, discovery: unknown, family: AdvertFamily, doc: string): AdvertOutcome {
   return onFamily(profile, discovery, family, (rec) => observed([bySchema(`/properties/${family}`, rec, doc, `the ${family} record`)]));
 }
 
@@ -210,3 +231,181 @@ export const aiProvidersPromptPrefixCacheLeg = (p: MajorProfile, d: unknown): Ad
   if (v === undefined) return inapplicable('the host does not advertise aiProviders.promptPrefixCache');
   return observed([bySchema(`${AP}/promptPrefixCache`, v, AP_DOC, 'aiProviders.promptPrefixCache (a boolean at v2, not the v1 object)')]);
 });
+
+// ---------------------------------------------------------------------------
+// Wave 2. Each facet leg validates the facet against its seat in the v2
+// capabilities schema, and adds a prose check only where a v2 core document
+// states the rule as binding the host. An absent facet is `inapplicable`.
+// ---------------------------------------------------------------------------
+
+/** One optional facet against its schema seat: absent ⇒ inapplicable. */
+function facetBySchema(p: MajorProfile, d: unknown, family: AdvertFamily, facet: string, doc: string, what = `${family}.${facet}`): AdvertOutcome {
+  return onFamily(p, d, family, (rec) => {
+    const v = rec[facet];
+    if (v === undefined) return inapplicable(`the host does not advertise ${family}.${facet} (optional)`);
+    return observed([bySchema(`/properties/${family}/properties/${facet}`, v, doc, what)]);
+  });
+}
+
+// selfHostedRunner — spec/v2/core/execution.md §selfHostedRunner
+
+/** `selfHostedRunner.dispatchKinds`: unique members of {model, tool} ("`dispatchKinds` lists `model`, `tool` or both"). */
+export const selfHostedRunnerDispatchKindsLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'selfHostedRunner', 'dispatchKinds', 'execution.md §selfHostedRunner', 'selfHostedRunner.dispatchKinds (unique members of model, tool)');
+
+// credentials — spec/v2/core/oauth.md §Credentials
+
+const CRED_DOC = 'oauth.md §Credentials';
+
+/** `credentials.scopes`: unique members of {user, workspace, tenant}; a scope outside it is `credential_scope_unsupported`. */
+export const credentialsScopesLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'credentials', 'scopes', CRED_DOC, 'credentials.scopes (a subset of user, workspace, tenant)');
+
+/** `credentials.rotation`: `none` or `two-key-overlap`. */
+export const credentialsRotationLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'credentials', 'rotation', CRED_DOC, 'credentials.rotation (none or two-key-overlap)');
+
+// authorization — spec/v2/core/identity.md §2.1
+
+const AUTHZ_DOC = 'identity.md §2.1 (authorization)';
+
+/** `authorization.failClosed`: "MUST be `true` when present" (invariant `authorization-fail-closed`). */
+export const authorizationFailClosedLeg = (p: MajorProfile, d: unknown): AdvertOutcome => onFamily(p, d, 'authorization', (rec) => {
+  const v = rec['failClosed'];
+  if (v === undefined) return inapplicable('the host does not advertise authorization.failClosed (optional)');
+  return observed([
+    bySchema('/properties/authorization/properties/failClosed', v, AUTHZ_DOC, 'authorization.failClosed'),
+    { ok: v === true, doc: AUTHZ_DOC, message: `authorization.failClosed MUST be true when present (got ${JSON.stringify(v)})` },
+  ]);
+});
+
+/** `authorization.roles`: each entry a non-empty `role` and a unique `scopes[]` of non-empty strings. */
+export const authorizationRolesLeg = (p: MajorProfile, d: unknown): AdvertOutcome => onFamily(p, d, 'authorization', (rec) => {
+  const v = rec['roles'];
+  if (v === undefined) return inapplicable('the host does not advertise authorization.roles (optional)');
+  const out = [bySchema('/properties/authorization/properties/roles', v, AUTHZ_DOC, 'authorization.roles')];
+  if (Array.isArray(v)) {
+    v.forEach((r, i) => out.push(bySchema('/properties/authorization/properties/roles/items', r, AUTHZ_DOC, `authorization.roles[${i}]`)));
+  }
+  return observed(out);
+});
+
+// providerUsage — spec/v2/core/events.md §providerUsage
+
+const PU_DOC = 'events.md §providerUsage';
+
+/** `providerUsage.costEstimates`: one boolean. */
+export const providerUsageCostEstimatesLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'providerUsage', 'costEstimates', PU_DOC);
+
+/** `providerUsage.currency`: "the ISO 4217 currency of `costEstimateUsd`" — three upper-case letters. */
+export const providerUsageCurrencyLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'providerUsage', 'currency', PU_DOC, 'providerUsage.currency (an ISO 4217 code, ^[A-Z]{3}$)');
+
+// subWorkflow — spec/v2/core/execution.md §subWorkflow
+
+/** `subWorkflow.inputMapping`: one boolean (a host not advertising it refuses a non-empty `inputMapping`). */
+export const subWorkflowInputMappingLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'subWorkflow', 'inputMapping', 'execution.md §subWorkflow');
+
+// scheduling — spec/v2/core/host-services.md §scheduling
+
+export const SCHEDULING_FORMS = ['cron', 'delayed', 'calendar'] as const;
+
+/** `scheduling.{cron,delayed,calendar}`: each present form is one boolean. All three absent ⇒ inapplicable. */
+export const schedulingFormsLeg = (p: MajorProfile, d: unknown): AdvertOutcome => onFamily(p, d, 'scheduling', (rec) => {
+  const present = SCHEDULING_FORMS.filter((f) => rec[f] !== undefined);
+  if (present.length === 0) return inapplicable('the host advertises none of scheduling.cron, delayed, calendar');
+  return observed(present.map((f) => bySchema(`/properties/scheduling/properties/${f}`, rec[f], 'host-services.md §scheduling', `scheduling.${f}`)));
+});
+
+// artifactTypes — spec/v2/core/artifact-type-packs.md §The capability
+
+const AT_DOC = 'artifact-type-packs.md §The capability';
+
+/** `artifactTypes.{store,render,export}`: the global facets — two booleans and a list of export-format ids. */
+export const artifactTypesGlobalFacetsLeg = (p: MajorProfile, d: unknown): AdvertOutcome => onFamily(p, d, 'artifactTypes', (rec) => {
+  const present = (['store', 'render', 'export'] as const).filter((f) => rec[f] !== undefined);
+  if (present.length === 0) return inapplicable('the host advertises none of artifactTypes.store, render, export');
+  return observed(present.map((f) => bySchema(`/properties/artifactTypes/properties/${f}`, rec[f], AT_DOC, `artifactTypes.${f}`)));
+});
+
+/**
+ * `artifactTypes.types`: each per-type entry validates against the entry seat —
+ * closed, `validation` open | closed, `schemaVersion` a non-negative integer,
+ * `registrationSource` pack | host (artifact-type-packs.md §Registration).
+ */
+export const artifactTypesPerTypeLeg = (p: MajorProfile, d: unknown): AdvertOutcome => onFamily(p, d, 'artifactTypes', (rec) => {
+  const t = rec['types'];
+  if (t === undefined) return inapplicable('the host does not advertise artifactTypes.types (optional)');
+  if (!isRecord(t)) return observed([bySchema('/properties/artifactTypes/properties/types', t, AT_DOC, 'artifactTypes.types')]);
+  const entries = Object.entries(t);
+  if (entries.length === 0) return observed([bySchema('/properties/artifactTypes/properties/types', t, AT_DOC, 'artifactTypes.types')]);
+  return observed(entries.map(([id, e]) => bySchema('/properties/artifactTypes/properties/types/additionalProperties', e, 'artifact-type-packs.md §Registration', `artifactTypes.types[${JSON.stringify(id)}]`)));
+});
+
+// deadLetter — spec/v2/core/runs.md §Dead letters
+
+/** `deadLetter.retentionDays`: an integer ≥ 1 (the failed run stays fork-eligible that long). */
+export const deadLetterRetentionDaysLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'deadLetter', 'retentionDays', 'runs.md §Dead letters', 'deadLetter.retentionDays (an integer of at least 1)');
+
+// portability — spec/v2/core/portability.md §The portability record
+
+const PORT_DOC = 'portability.md §The portability record';
+
+/** "A host advertising `import` MUST advertise `dryRun: true`." Read as `import: true` ⇒ `dryRun: true`, as the schema's `allOf` if/then reads it. */
+export const portabilityImportDryRunLeg = (p: MajorProfile, d: unknown): AdvertOutcome => onFamily(p, d, 'portability', (rec) => {
+  if (rec['import'] !== true) return inapplicable('the host does not advertise portability.import: true');
+  return observed([{ ok: rec['dryRun'] === true, doc: PORT_DOC, message: `a host advertising portability.import MUST advertise dryRun: true (got ${JSON.stringify(rec['dryRun'])})` }]);
+});
+
+/** `portability.kinds`: unique members of the seven export-bundle item kinds. */
+export const portabilityKindsLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'portability', 'kinds', PORT_DOC, 'portability.kinds (unique export-bundle item kinds)');
+
+// ---------------------------------------------------------------------------
+// Wave 3 — families no host serves at v2 (architect ruling, 2026-10-04).
+// ---------------------------------------------------------------------------
+
+/** `dataResidency.regions`: unique non-empty region codes (runs.md §`dataResidency`). */
+export const dataResidencyRegionsLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'dataResidency', 'regions', 'runs.md §dataResidency', 'dataResidency.regions (unique non-empty region codes)');
+
+/** `multiPartyConversation.maxParticipants`: an integer of at least 2 (a council of one is not multi-party). */
+export const multiPartyMaxParticipantsLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'multiPartyConversation', 'maxParticipants', 'conversation.md §multiPartyConversation', 'multiPartyConversation.maxParticipants (an integer ≥ 2)');
+
+/** `nodePackRuntimes.wasm`: `abiVersions` unique integers ≥ 1 with at least one entry; `maxMemoryBytes` within 1 MiB – 8 GiB. */
+export const nodePackRuntimesWasmLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'nodePackRuntimes', 'wasm', 'node-pack-runtimes.md §WASM', 'nodePackRuntimes.wasm (abiVersions non-empty unique integers ≥ 1; maxMemoryBytes 1 MiB – 8 GiB)');
+
+const UIP_DOC = 'packs.md §Front-end plugin packs';
+/** `uiPlugins.isolation`: one of the five mechanisms or an `x-host-<host>-<key>` value — it names the mechanism, never relaxes the property. */
+export const uiPluginsIsolationLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'uiPlugins', 'isolation', UIP_DOC, 'uiPlugins.isolation (a closed mechanism or x-host-<host>-<key>)');
+/** `uiPlugins.surfaces`: unique members of the closed surface set. */
+export const uiPluginsSurfacesLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'uiPlugins', 'surfaces', UIP_DOC, 'uiPlugins.surfaces (unique members of the closed surface set)');
+/** `uiPlugins.hostApi`: unique members of the closed `ui-plugin/1` method set. */
+export const uiPluginsHostApiLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'uiPlugins', 'hostApi', UIP_DOC, 'uiPlugins.hostApi (unique members of the closed ui-plugin/1 method set)');
+/** `uiPlugins.maxEntryBytes`: a positive integer. */
+export const uiPluginsMaxEntryBytesLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'uiPlugins', 'maxEntryBytes', UIP_DOC, 'uiPlugins.maxEntryBytes (a positive integer)');
+
+/** `purposePropagation.propagatesOnward`: a boolean (security-defaults.md §Onward hops). */
+export const purposePropagatesOnwardLeg = (p: MajorProfile, d: unknown): AdvertOutcome =>
+  facetBySchema(p, d, 'purposePropagation', 'propagatesOnward', 'security-defaults.md §Onward hops', 'purposePropagation.propagatesOnward (a boolean)');
+
+/**
+ * `agentRuntime` implies `agents.manifestRuntime` (host-services.md §`agentRuntime`:
+ * "Advertising it implies `agents.manifestRuntime`, which the host MUST satisfy").
+ * The suite reads both from discovery, so this is the one cross-family rule of
+ * the wave the host's own claim can falsify.
+ */
+export const agentRuntimeImpliesManifestRuntimeLeg = (p: MajorProfile, d: unknown): AdvertOutcome => onFamily(p, d, 'agentRuntime', () => {
+  const agents = p.family(d, 'agents');
+  const ok = agents !== null && isRecord(agents['manifestRuntime']);
+  return observed([{ ok, doc: 'host-services.md §agentRuntime', message: `a host advertising agentRuntime MUST also advertise agents.manifestRuntime${ok ? '' : agents === null ? ' (agents is absent)' : ' (agents.manifestRuntime is absent)'}` }]);
+});

package/src/lib/fixture-run-observer.ts

@@ -0,0 +1,97 @@
+/**
+ * Observe one fixture run on the normative run surface: create it, wait for a
+ * terminal status, read its final snapshot and its durable log. Shared by the
+ * wave-2 fixture witnesses (`subworkflow-witness.ts`, `dispatch-witness.ts`,
+ * `provider-usage-witness.ts`). It observes and asserts nothing; what differs
+ * between majors (the run path, the id segment) is the profile row.
+ */
+
+import { driver } from './driver.js';
+import type { MajorProfile } from './major-profile.js';
+
+export const isRecord = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+/** A finding: one rule, judged. */
+export interface Finding { readonly ok: boolean; readonly doc: string; readonly message: string }
+export type Skip = { readonly kind: 'skip'; readonly disposition: 'inapplicable' | 'blocked'; readonly reason: string };
+export type Outcome = Skip | { readonly kind: 'observed'; readonly findings: readonly Finding[] };
+export type Validate = (doc: unknown) => { ok: boolean; errors: string };
+
+export const finding = (ok: boolean, doc: string, message: string): Finding => ({ ok, doc, message });
+export const skip = (disposition: Skip['disposition'], reason: string): Skip => ({ kind: 'skip', disposition, reason });
+export const observed = (findings: readonly Finding[]): Outcome => ({ kind: 'observed', findings });
+
+export interface Ev {
+  readonly type: string;
+  readonly sequence: number;
+  /** The envelope `nodeId`, else the payload's. */
+  readonly nodeId: string | undefined;
+  readonly payload: Record<string, unknown>;
+}
+
+export interface RunRead { readonly status: number; readonly snapshot: Record<string, unknown> }
+
+export interface ObservedRun {
+  readonly workflowId: string;
+  readonly createStatus: number;
+  readonly runId: string | undefined;
+  readonly terminalStatus: string | undefined;
+  /** The last `GET /runs/{runId}` body. */
+  readonly snapshot: Record<string, unknown>;
+  /** Sorted by `sequence`. */
+  readonly events: readonly Ev[];
+}
+
+export interface ObserveOpts { readonly timeoutMs?: number; readonly pollMs?: number }
+
+/** `GET /runs/{runId}`. */
+export async function readRun(profile: MajorProfile, runId: string): Promise<RunRead> {
+  const r = await driver.get(`${profile.runsPath}/${profile.idSegment(runId)}`);
+  return { status: r.status, snapshot: isRecord(r.json) ? r.json : {} };
+}
+
+/** `GET /runs/{runId}/events/poll`, normalised and sorted. */
+export async function readEvents(profile: MajorProfile, runId: string): Promise<Ev[]> {
+  const poll = await driver.get(`${profile.runsPath}/${profile.idSegment(runId)}/events/poll`);
+  const raw = isRecord(poll.json) && Array.isArray(poll.json['events']) ? (poll.json['events'] as unknown[]) : [];
+  return raw.filter(isRecord).map((e): Ev => {
+    const payload = isRecord(e['payload']) ? e['payload'] : {};
+    const nodeId = typeof e['nodeId'] === 'string' ? e['nodeId'] : typeof payload['nodeId'] === 'string' ? payload['nodeId'] : undefined;
+    return { type: String(e['type']), sequence: typeof e['sequence'] === 'number' ? e['sequence'] : Number.MAX_SAFE_INTEGER, nodeId, payload };
+  }).sort((x, y) => x.sequence - y.sequence);
+}
+
+/** Wait for a terminal status (or the deadline); return the last read. */
+export async function pollTerminal(profile: MajorProfile, runId: string, opts: ObserveOpts = {}): Promise<RunRead> {
+  const deadline = Date.now() + (opts.timeoutMs ?? 30_000);
+  for (;;) {
+    const r = await readRun(profile, runId);
+    const s = r.snapshot['status'];
+    if ((typeof s === 'string' && TERMINAL.has(s)) || Date.now() > deadline) return r;
+    await new Promise((res) => setTimeout(res, opts.pollMs ?? 250));
+  }
+}
+
+/** Create a run of `workflowId`, wait for it, read its log. Asserts nothing. */
+export async function observeRun(profile: MajorProfile, workflowId: string, opts: ObserveOpts = {}): Promise<ObservedRun> {
+  const created = await driver.post(profile.runsPath, { workflowId });
+  const runId = isRecord(created.json) && typeof created.json['runId'] === 'string' ? created.json['runId'] : undefined;
+  if ((created.status !== 201 && created.status !== 202) || runId === undefined) {
+    return { workflowId, createStatus: created.status, runId: undefined, terminalStatus: undefined, snapshot: {}, events: [] };
+  }
+  const r = await pollTerminal(profile, runId, opts);
+  const status = r.snapshot['status'];
+  return { workflowId, createStatus: created.status, runId, terminalStatus: typeof status === 'string' ? status : undefined, snapshot: r.snapshot, events: await readEvents(profile, runId) };
+}
+
+/** The create was accepted and the fixture run ended `completed`, as its catalog entry says. */
+export function runCompleted(o: ObservedRun): Finding[] {
+  return [
+    finding(o.createStatus === 201 || o.createStatus === 202, 'runs.md createRun', `createRun of ${o.workflowId} MUST be accepted (got ${o.createStatus})`),
+    finding(o.terminalStatus === 'completed', `fixtures.md ${o.workflowId}`, `the fixture run MUST end completed (got ${String(o.terminalStatus)})`),
+  ];
+}
+
+/** The `node.completed` events of one node. */
+export const completionsOf = (events: readonly Ev[], nodeId: string): Ev[] => events.filter((e) => e.type === 'node.completed' && e.nodeId === nodeId);

package/src/lib/prompt-library-witness.ts

@@ -152,7 +152,15 @@ export async function fetchLeg(profile: MajorProfile, a: PromptAdverts, validate
   ] };
 }
 
-/** Leg: an ETag, when sent, revalidates to `304`. `getPromptTemplate` SHOULD send one; none is inapplicable. */
+/**
+ * Leg (advisory): an ETag, when sent, revalidates to `304`. v2 binds the host
+ * to nothing here: `getPromptTemplate` SHOULD send an ETag (host-services.md
+ * §prompts), and the `304` MUST in headers.md §Request headers covers only the
+ * discovery document and the run snapshot. So the leg passes on a `304` and
+ * records `inapplicable` otherwise; it is never failed (the
+ * `tool-catalog-projection` advisory precedent). Until 2.45.17 it failed on
+ * RFC 9110 alone, which no v2 rule imports for this read.
+ */
 export async function etagLeg(profile: MajorProfile, a: PromptAdverts): Promise<PromptOutcome> {
   const g = endpointsGate(a); if (g) return g;
   const t = await aTemplate(a);
@@ -161,7 +169,8 @@ export async function etagLeg(profile: MajorProfile, a: PromptAdverts): Promise<
   const etag = first.headers.get('etag');
   if (first.status !== 200 || etag === null || etag.length === 0) return { kind: 'skip', disposition: 'inapplicable', reason: `getPromptTemplate sent no ETag (status ${first.status}) — a SHOULD, so there is nothing to revalidate` };
   const again = await driver.get(tplPath(profile, a, t.templateId), { headers: { 'If-None-Match': etag } });
-  return { kind: 'observed', findings: [f(again.status === 304, `${DOC_LIB}; RFC 9110 §13.1.2`, `If-None-Match with the current ETag MUST answer 304 (got ${again.status})`)] };
+  if (again.status !== 304) return { kind: 'skip', disposition: 'inapplicable', reason: `advisory SHOULD not met: If-None-Match with the current ETag answered ${again.status}, not 304 — v2 binds 304 only on discovery and the run snapshot (headers.md), so this is recorded, never failed` };
+  return { kind: 'observed', findings: [f(true, `${DOC_LIB} (SHOULD); RFC 9110 §13.1.2`, 'If-None-Match with the current ETag answers 304')] };
 }
 
 /** Leg: an unknown template id is `404` with the error envelope. */

package/src/lib/provider-usage-witness.ts

@@ -0,0 +1,63 @@
+/**
+ * The `provider.usage` emission witness (`events.md` §`providerUsage`): "A
+ * host advertising `providerUsage` MUST emit exactly one `provider.usage` per
+ * LLM provider invocation, before that node's `node.completed`."
+ *
+ * Driven on `conformance-context-budget-live` — a supervisor on the host's LIVE
+ * model (the fixture's catalog entry forbids a mock), so a completed run made
+ * at least one provider invocation. From outside, the number of invocations
+ * is unknowable, so "exactly one per invocation" is NOT asserted; what is:
+ *   emitted   at least one `provider.usage` is on the log;
+ *   ordering  each one precedes a `node.completed` of the node it names (or,
+ *             when it names none, some `node.completed`);
+ *   payload   each payload validates against the v2 `providerUsage` def (whose
+ *             closed shape also keeps credential refs and prompt text out).
+ *
+ * {@link driveUsage} observes and asserts nothing; {@link judgeUsage} is pure,
+ * proven in `provider-usage-witness.test.ts`.
+ */
+
+import { isFixtureAdvertised } from './fixtures.js';
+import type { MajorProfile } from './major-profile.js';
+import { finding, observed, observeRun, skip, type ObservedRun, type ObserveOpts, type Outcome, type Skip, type Validate } from './fixture-run-observer.js';
+
+export const LIVE_FIXTURE = 'conformance-context-budget-live';
+const DOC = 'events.md §providerUsage';
+
+export interface UsageObservation { readonly run: ObservedRun; readonly usageType: string }
+
+/** The `providerUsage` record, the live fixture, and this major's event name. */
+export function usageGate(profile: MajorProfile, doc: unknown): Skip | { usageType: string } {
+  if (profile.family(doc, 'providerUsage') === null) return skip('inapplicable', 'the host does not advertise providerUsage');
+  if (!isFixtureAdvertised(LIVE_FIXTURE)) return skip('inapplicable', `fixture ${LIVE_FIXTURE} is not advertised — the fixture is the opt-in (a host whose supervisor has no live model must not advertise it)`);
+  const usageType = profile.eventType('provider.usage');
+  if (usageType === undefined) return skip('blocked', 'the event codemap is not on disk in this layout — the suite will not guess an event name');
+  return { usageType };
+}
+
+/** Run the live fixture. Asserts nothing. */
+export async function driveUsage(profile: MajorProfile, doc: unknown, opts: ObserveOpts = {}): Promise<Skip | UsageObservation> {
+  const g = usageGate(profile, doc);
+  if ('kind' in g) return g;
+  return { run: await observeRun(profile, LIVE_FIXTURE, { timeoutMs: 300_000, pollMs: 1000, ...opts }), ...g };
+}
+
+/** Emission, ordering and payload shape. Pure. */
+export function judgeUsage(o: UsageObservation, validate: Validate): Outcome {
+  const usage = o.run.events.filter((e) => e.type === o.usageType);
+  const completions = o.run.events.filter((e) => e.type === 'node.completed');
+  if (o.run.createStatus !== 201 && o.run.createStatus !== 202) {
+    return observed([finding(false, 'runs.md createRun', `createRun of ${LIVE_FIXTURE} MUST be accepted (got ${o.run.createStatus})`)]);
+  }
+  if (usage.length === 0 && o.run.terminalStatus !== 'completed') {
+    return skip('blocked', `the live run ended ${String(o.run.terminalStatus)} with no ${o.usageType} — no provider invocation is shown to have happened`);
+  }
+  return observed([
+    finding(usage.length > 0, DOC, `a completed run of a live-model supervisor MUST carry at least one ${o.usageType} (got none)`),
+    ...usage.map((u) => {
+      const after = completions.some((c) => c.sequence > u.sequence && (u.nodeId === undefined || c.nodeId === u.nodeId));
+      return finding(after, DOC, `${o.usageType} (seq ${u.sequence}${u.nodeId === undefined ? '' : `, node ${u.nodeId}`}) MUST precede that node's node.completed`);
+    }),
+    ...usage.map((u) => { const v = validate(u.payload); return finding(v.ok, 'schemas run-event-payloads providerUsage', `every ${o.usageType} payload MUST validate (seq ${u.sequence}): ${v.errors}`); }),
+  ]);
+}

package/src/lib/run-graph-double.ts

@@ -0,0 +1,144 @@
+/**
+ * A run-graph double: the smallest HTTP server the wave-2 fixture witnesses
+ * (sub-workflow linkage and input mapping, dispatch input mapping, the
+ * dispatch loop, provider usage) and the artifact schema-URL witness can be
+ * proven against, in both directions.
+ *
+ * `ScratchHost` plays one run per create. These witnesses follow a parent run
+ * to the child it started, read the child's snapshot (`variables`, `inputs`)
+ * and its `getRunAncestry` answer, and fetch paths outside the run surface,
+ * so this double lets a case script a parent that spawns children, and answer
+ * any other GET.
+ *
+ * It is a test double, not a host: it executes nothing, and nothing it does is
+ * evidence about any implementation. Ids are tenant-bound (`<tenant>/<opaque>`,
+ * `ids.schema.json#/$defs/runId`) and accepted `~`-projected or percent-encoded.
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { unprojectBoundId } from './bound-id.js';
+
+export interface DoubleEvent {
+  readonly type: string;
+  /** The envelope's top-level `nodeId`. */
+  readonly nodeId?: string | undefined;
+  readonly payload?: Record<string, unknown> | undefined;
+}
+export interface DoubleRun {
+  readonly workflowId?: string;
+  readonly status: string;
+  readonly variables?: Record<string, unknown> | undefined;
+  readonly inputs?: Record<string, unknown> | undefined;
+  readonly events?: readonly DoubleEvent[];
+  /** The `GET /runs/{runId}/ancestry` answer, given the run's own id. Unset: 404. */
+  readonly ancestry?: ((self: string) => { readonly status: number; readonly body: unknown }) | undefined;
+}
+export interface RawAnswer { readonly status: number; readonly headers?: Readonly<Record<string, string>>; readonly body: string }
+export interface DoubleOptions {
+  readonly discovery: Readonly<Record<string, unknown>>;
+  /**
+   * The run a create makes. `spawn` stores a further run (a child) and returns
+   * its id; `self` is the id the created run will carry. Unset: every create is 404.
+   */
+  readonly onCreate?: ((workflowId: string, spawn: (run: DoubleRun) => string, self: string) => DoubleRun | undefined) | undefined;
+  /** Any other GET, by path. `undefined` is 404. */
+  readonly onGet?: ((path: string) => RawAnswer | undefined) | undefined;
+}
+
+export const DOUBLE_TENANT = 'tenant-a';
+
+export class RunGraphDouble {
+  private server: Server | undefined;
+  private readonly runs = new Map<string, DoubleRun>();
+  private seq = 0;
+  url = '';
+
+  constructor(private opts: DoubleOptions) {}
+
+  /** Swap behaviour between cases. The address stays the same, since the driver caches its base URL per file. */
+  reconfigure(next: Partial<DoubleOptions>): void {
+    this.opts = { ...this.opts, ...next };
+    this.runs.clear();
+  }
+
+  get discovery(): Readonly<Record<string, unknown>> { return this.opts.discovery; }
+
+  async start(): Promise<string> {
+    this.server = createServer((req, res) => { void this.handle(req, res); });
+    await new Promise<void>((r) => this.server!.listen(0, '127.0.0.1', r));
+    this.url = `http://127.0.0.1:${(this.server.address() as AddressInfo).port}`;
+    return this.url;
+  }
+
+  async stop(): Promise<void> {
+    const s = this.server;
+    if (s === undefined) return;
+    s.closeAllConnections();
+    await new Promise<void>((r) => s.close(() => r()));
+  }
+
+  private mint(): string { return `${DOUBLE_TENANT}/run-${String(++this.seq).padStart(16, '0')}`; }
+
+  private send(res: ServerResponse, status: number, body: unknown, headers: Readonly<Record<string, string>> = {}): void {
+    res.writeHead(status, { 'content-type': 'application/json', ...headers });
+    res.end(typeof body === 'string' ? body : JSON.stringify(body));
+  }
+
+  private async body(req: IncomingMessage): Promise<Record<string, unknown>> {
+    const chunks: Buffer[] = [];
+    for await (const c of req) chunks.push(c as Buffer);
+    try {
+      const v: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+      return v !== null && typeof v === 'object' && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+    } catch { return {}; }
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const path = (req.url ?? '/').split('?')[0] ?? '/';
+    if (req.method === 'GET' && path === '/.well-known/openwop') return this.send(res, 200, this.opts.discovery);
+
+    if (req.method === 'POST' && path === '/runs') {
+      const workflowId = String((await this.body(req))['workflowId'] ?? '');
+      const self = this.mint();
+      const run = this.opts.onCreate?.(workflowId, (child) => { const id = this.mint(); this.runs.set(id, child); return id; }, self);
+      if (run === undefined) return this.send(res, 404, { error: 'not_found', message: `no workflow ${workflowId}` });
+      this.runs.set(self, { workflowId, ...run });
+      return this.send(res, 201, { runId: self, status: 'running' });
+    }
+
+    const m = /^\/runs\/([^/]+)(\/events\/poll|\/ancestry)?$/.exec(path);
+    if (req.method === 'GET' && m) {
+      const seg = m[1] as string;
+      const id = seg.includes('~') ? unprojectBoundId(seg) : decodeURIComponent(seg);
+      const run = this.runs.get(id);
+      if (run === undefined) return this.send(res, 404, { error: 'not_found', message: 'no such run' });
+      if (m[2] === '/ancestry') {
+        const a = run.ancestry?.(id);
+        return a === undefined ? this.send(res, 404, { error: 'not_found', message: 'ancestry not served' }) : this.send(res, a.status, a.body);
+      }
+      if (m[2] === '/events/poll') {
+        const events = (run.events ?? []).map((e, i) => ({
+          eventId: `e${i + 1}`, runId: id, type: e.type, ...(e.nodeId === undefined ? {} : { nodeId: e.nodeId }),
+          payload: e.payload ?? {}, sequence: i + 1, schemaVersion: 2, timestamp: new Date(0).toISOString(),
+        }));
+        return this.send(res, 200, { events });
+      }
+      return this.send(res, 200, {
+        runId: id, workflowId: run.workflowId ?? 'double', status: run.status,
+        ...(run.variables === undefined ? {} : { variables: run.variables }),
+        ...(run.inputs === undefined ? {} : { inputs: run.inputs }),
+      });
+    }
+
+    if (req.method === 'GET') {
+      const raw = this.opts.onGet?.(path);
+      if (raw !== undefined) {
+        res.writeHead(raw.status, { ...(raw.headers ?? {}) });
+        res.end(raw.body);
+        return;
+      }
+    }
+    return this.send(res, 404, { error: 'not_found', message: 'no such route' });
+  }
+}