@openwop/openwop-conformance 2.45.2 → 2.45.4

package/src/lib/certification-bundle-verify.ts

@@ -31,7 +31,7 @@ import {
   type DiscoveryPayload,
 } from './profiles.js';
 import { CERTIFIABLE, DISPOSITIONS, type Disposition } from './requirement-ledger.js';
-import { floorFilesFor, requirementIdForPrefix, requirementIdForScenario } from './requirement-registry.js';
+import { floorFilesFor, requirementIdForAnyOf, requirementIdForPrefix, requirementIdForScenario } from './requirement-registry.js';
 import { UNCLASSIFIED_RETURN_DETAIL } from './soft-skip.js';
 
 /**
@@ -149,7 +149,7 @@ export function findLiteral(value: unknown, literal: string): string[] {
  * it is the prefix requirement id, and the rows that satisfy it are the
  * matching scenario rows.
  */
-function requiredFor(profile: string, document: Readonly<Record<string, unknown>>): { files: string[]; prefixes: string[]; discoveryOnly: boolean } | null {
+function requiredFor(profile: string, document: Readonly<Record<string, unknown>>): { files: string[]; prefixes: string[]; anyOf: Array<readonly string[]>; discoveryOnly: boolean } | null {
   const floor = PROFILE_FLOOR_SCENARIOS[profile];
   if (floor === undefined) return null;
   // Discovery-conditional floors (G7) are evaluated against the bundle's own
@@ -159,6 +159,7 @@ function requiredFor(profile: string, document: Readonly<Record<string, unknown>
   return {
     files: [...files],
     prefixes: [...(floor.requiredAnyPrefix ?? [])],
+    anyOf: [...(floor.requiredAnyOf ?? [])],
     discoveryOnly: floor.discoveryOnly === true,
   };
 }
@@ -272,6 +273,26 @@ export function verifyBundleV2(bundle: BundleV2Like): BundleV2Verdict {
       if (!considered.some((r) => isWitnessedPass(r))) notCertifiable.push(id);
     }
 
+    for (const group of req.anyOf) {
+      // RFC 0229 §E: one requirement, satisfied by a WITNESSED pass of any
+      // member with no member failing. The emitter writes a summary row under
+      // the group id; member rows are read when it is absent.
+      const id = requirementIdForAnyOf(group);
+      required.push(id);
+      const summary = byId.get(id)?.[0];
+      const members = group.map((f) => byId.get(requirementIdForScenario(scenarioBasename(f)))?.[0]).filter((r): r is BundleV2Requirement => r !== undefined);
+      if (summary === undefined && members.length === 0) {
+        profileRejections.push({ kind: 'unwitnessed-requirement', profile, requirementId: id, detail: `${id}: no alternative (${group.join(', ')}) recorded a row` });
+        continue;
+      }
+      const considered = summary !== undefined ? [summary] : members;
+      if (considered.some((r) => r.disposition === 'executed-pass' && !isWitnessedPass(r))) {
+        profileRejections.push({ kind: 'vacuous-pass', profile, requirementId: id, detail: `${id}: executed-pass with no witnessed assertion` });
+        continue;
+      }
+      if (considered.some((r) => r.disposition === 'executed-fail') || !considered.some((r) => isWitnessedPass(r))) notCertifiable.push(id);
+    }
+
     const evidenceValid = profileRejections.length === 0;
     const certified = derivable && evidenceValid && notCertifiable.length === 0 && (req.discoveryOnly || required.length > 0);
     return { profile, derivable, floorUnspecified: false, required, rejections: profileRejections, notCertifiable, evidenceValid, certified };

package/src/lib/driver.ts

@@ -11,6 +11,46 @@
 
 import { loadEnv } from './env.js';
 import { seamPath, targetMajor } from './seams.js';
+import { scaledTimeoutMs } from './timeout-scale.js';
+
+/**
+ * How long one request may go unanswered before the driver gives up (#1829).
+ * Below vitest's 30 s `testTimeout`, so a lost response ends as a named
+ * {@link TransportError} and not as a bare harness timeout. Driver long-polls
+ * are at most 5 s. Scales with `OPENWOP_POLL_TIMEOUT_SCALE`.
+ */
+export const REQUEST_TIMEOUT_MS = 20_000;
+
+/** Leads every {@link TransportError} message; `resolveItRecord` keys on it. */
+export const TRANSPORT_LOSS_PREFIX = 'transport-loss: ';
+
+/**
+ * No response arrived: the request timed out or the connection failed. The
+ * suite observed nothing about the host, so this is never a verdict on it. A
+ * runner whose network dropped for 9 s once recorded `executed-fail` against a
+ * host that had answered in 2.6 ms (MyndHyve cut, suite 2.45.2).
+ */
+export class TransportError extends Error {
+  constructor(
+    readonly kind: 'timeout' | 'network',
+    readonly method: string,
+    /** Origin and path only. A query string can carry a token. */
+    readonly target: string,
+    reason: string,
+  ) {
+    super(`${TRANSPORT_LOSS_PREFIX}${method} ${target} got no response (${reason}); the suite could not observe the host`);
+    this.name = 'TransportError';
+  }
+}
+
+function withoutQuery(url: string): string {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return url.split('?')[0] ?? url;
+  }
+}
 
 export interface OpenWOPResponse {
   readonly status: number;
@@ -25,6 +65,10 @@ export interface OpenWOPRequestInit {
   /** `false` sends no default credential. A caller-supplied `Authorization`
    *  header is always sent as given, whatever this says. */
   readonly authenticated?: boolean;
+  /** Replaces the driver's own bound entirely; an abort it raises is rethrown as-is. */
+  readonly signal?: AbortSignal;
+  /** Overrides {@link REQUEST_TIMEOUT_MS} for one request (scaled the same way). */
+  readonly timeoutMs?: number;
 }
 
 class OpenWOPDriver {
@@ -83,9 +127,24 @@ class OpenWOPDriver {
         fetchInit.body = JSON.stringify(init.body);
       }
     }
-    const res = await fetch(url, fetchInit);
+    const boundMs = scaledTimeoutMs(init.timeoutMs ?? REQUEST_TIMEOUT_MS);
+    fetchInit.signal = init.signal ?? AbortSignal.timeout(boundMs);
+    let res: Response;
+    let text: string;
+    try {
+      res = await fetch(url, fetchInit);
+      // The body is read under the same bound: a response whose headers arrive
+      // and whose body never does is the same lost observation.
+      text = await res.text();
+    } catch (err) {
+      // The caller's own signal aborted: that is the caller's event, not a loss.
+      if (init.signal?.aborted === true) throw err;
+      const name = err instanceof Error ? err.name : '';
+      if (name === 'TimeoutError') throw new TransportError('timeout', method, withoutQuery(url), `no response within ${boundMs} ms`);
+      const cause = err instanceof Error ? (err.cause instanceof Error ? err.cause.message : err.message) : String(err);
+      throw new TransportError('network', method, withoutQuery(url), cause.slice(0, 160));
+    }
 
-    const text = await res.text();
     let json: unknown;
     try {
       json = text.length > 0 ? JSON.parse(text) : undefined;

package/src/lib/major-profile.ts

@@ -0,0 +1,93 @@
+/**
+ * What differs between protocol majors, as data.
+ *
+ * A scenario that is "the same requirement at another major" used to be a
+ * copy of the earlier file with the paths, event names and envelope rules
+ * edited by hand. The differences are few and regular, so they live in one
+ * table here. A shared witness (`backpressure-witness.ts`) takes a profile and
+ * never names a major; the scenario file for each major is a thin wrapper.
+ *
+ * **Adding a major** is one row in {@link MAJOR_PROFILES} plus one thin
+ * scenario file per ported witness. `majorProfile()` throws on a major with no
+ * row, so a missing row is a loud failure and never a silent fall back to an
+ * older major's rules.
+ *
+ * Keep a field here only when a shared witness reads it. A rule one major
+ * states and another does not is not a field: the witness asks the profile
+ * whether the rule binds (see `retryTiming`), and cites the document that
+ * states it.
+ */
+
+import { capabilityFamily } from './discovery-capabilities.js';
+import { codemapV1toV2 } from './era2-seed.js';
+
+export interface MajorProfile {
+  readonly major: number;
+  /** The run collection, e.g. `/v1/runs` or `/runs`. */
+  readonly runsPath: string;
+  /** Headers a raw `fetch` must add to speak this major (the driver adds its own). */
+  readonly versionHeaders: Readonly<Record<string, string>>;
+  /** Where the corpus states this major's rules, for requirement citations. */
+  readonly specRoot: string;
+  /**
+   * Where retry timing lives on an error response. `header-and-details`: the
+   * envelope repeats `Retry-After` in `details.retryAfter`. `header-only`: the
+   * header is the only place, and `details.retryAfter*` is forbidden.
+   */
+  readonly retryTiming: 'header-and-details' | 'header-only';
+  /** The advertised record for a capability family, or `null` when the host does not advertise it. */
+  family(doc: unknown, key: string): Record<string, unknown> | null;
+  /**
+   * The `createRun` body fragment that carries a run budget policy, or `null`
+   * when this major has no run wire surface for one (a witness that needs it
+   * is then `inapplicable` at this major).
+   */
+  runBudget(policy: Readonly<Record<string, unknown>>): Record<string, unknown> | null;
+  /**
+   * This major's name for an event, given its era-1 name. `undefined` when the
+   * mapping is not on disk in this layout: the caller records that as an
+   * unread observation and never guesses a name.
+   */
+  eventType(era1Name: string): string | undefined;
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+export const MAJOR_PROFILES: Readonly<Record<number, MajorProfile>> = {
+  1: {
+    major: 1,
+    runsPath: '/v1/runs',
+    versionHeaders: {},
+    specRoot: 'spec/v1',
+    retryTiming: 'header-and-details',
+    // v1: a family is advertised when its record says `supported: true`.
+    family: (doc, key) => {
+      const rec = capabilityFamily(doc, key);
+      return isRecord(rec) && rec['supported'] === true ? rec : null;
+    },
+    // v1 budgets are driven through a host seam, not `createRun`.
+    runBudget: () => null,
+    eventType: (era1Name) => era1Name,
+  },
+  2: {
+    major: 2,
+    runsPath: '/runs',
+    versionHeaders: { 'OpenWOP-Version': '2.0' },
+    specRoot: 'spec/v2/core',
+    retryTiming: 'header-only',
+    // v2: presence of the record is the advertisement.
+    family: (doc, key) => {
+      const rec = isRecord(doc) ? doc[key] : undefined;
+      return isRecord(rec) ? rec : null;
+    },
+    runBudget: (policy) => ({ configurable: { version: 1, budget: { ...policy } } }),
+    eventType: (era1Name) => codemapV1toV2().get(era1Name),
+  },
+};
+
+/** The profile for a major. Throws when the table has no row for it. */
+export function majorProfile(major: number): MajorProfile {
+  const p = MAJOR_PROFILES[major];
+  if (p === undefined) throw new Error(`no MajorProfile for major ${major} — add a row to MAJOR_PROFILES in lib/major-profile.ts`);
+  return p;
+}

package/src/lib/memoryAttribution.ts

@@ -42,9 +42,19 @@ export async function readMemoryAttributionCap(): Promise<Record<string, unknown
   return attr && typeof attr === 'object' ? (attr as Record<string, unknown>) : null;
 }
 
-/** True when the host commits to emitting `memory.written`. */
+/**
+ * True when the host commits to emitting `memory.written`.
+ *
+ * Major 1: the v1 block's `supported: true` (its schema `const`) AND
+ * `emitsWriteEvents: true`. Major 2: there is no `supported` field — presence
+ * of the `memory` family record IS the claim (RFC 0169 §A.2), and
+ * `readMemoryAttributionCap` returns the `attribution` object only when that
+ * record is present — so the commitment is `emitsWriteEvents: true` alone.
+ * Requiring `supported` at major 2 soft-skipped every v2 host (suite 2.45.3).
+ */
 export function emitsWriteEvents(cap: Record<string, unknown> | null): boolean {
-  return cap?.['supported'] === true && cap?.['emitsWriteEvents'] === true;
+  if (cap?.['emitsWriteEvents'] !== true) return false;
+  return targetMajor() === 2 ? true : cap['supported'] === true;
 }
 
 const SEED_FIXTURE = 'conformance-noop';
@@ -71,9 +81,34 @@ interface RunEventLike {
   payload?: Record<string, unknown>;
 }
 
-/** Fetches a run's events and returns only the `memory.written` ones. */
+/**
+ * Fetches a run's events and returns only the `memory.written` ones.
+ *
+ * Major 2: `GET /runs/{runId}/events` is the SSE stream (`streamRunEvents`,
+ * `text/event-stream` only), so a JSON read of it yields nothing and every leg
+ * would soft-skip "run wrote no memory" — a `blocked` row that denies
+ * certification for a suite defect. The JSON projection at v2 is the poll
+ * (`events.md` §Poll), read from sequence 0 and paged on `afterSequence` until
+ * `lastSequence` is reached.
+ */
 export async function memoryWrittenEvents(runId: string): Promise<RunEventLike[]> {
-  const res = await driver.get(`${runsPath()}/${encodeURIComponent(runId)}/events`);
-  const events = (res.json as { events?: RunEventLike[] } | undefined)?.events ?? [];
-  return events.filter((e) => e.type === 'memory.written');
+  if (targetMajor() !== 2) {
+    const res = await driver.get(`${runsPath()}/${encodeURIComponent(runId)}/events`);
+    const events = (res.json as { events?: RunEventLike[] } | undefined)?.events ?? [];
+    return events.filter((e) => e.type === 'memory.written');
+  }
+  const out: RunEventLike[] = [];
+  let after = -1;
+  for (let page = 0; page < 50; page++) {
+    const q = after < 0 ? '' : `&afterSequence=${after}`;
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}/events/poll?timeout=1${q}`);
+    const body = res.json as { events?: Array<RunEventLike & { sequence?: number }>; lastSequence?: number } | undefined;
+    const events = res.status === 200 && Array.isArray(body?.events) ? body.events : [];
+    out.push(...events);
+    const seqs = events.map((e) => e.sequence).filter((s): s is number => typeof s === 'number');
+    const next = seqs.length ? Math.max(...seqs) : after;
+    if (next <= after || typeof body?.lastSequence !== 'number' || next >= body.lastSequence) break;
+    after = next;
+  }
+  return out.filter((e) => e.type === 'memory.written');
 }

package/src/lib/polling.ts

@@ -28,6 +28,7 @@
  */
 
 import { driver } from './driver.js';
+import { scaledTimeoutMs } from './timeout-scale.js';
 import { targetMajor } from './seams.js';
 
 export interface RunSnapshot {
@@ -52,24 +53,7 @@ export interface RunSnapshot {
 const POLL_INTERVAL_MS = 250;
 const DEFAULT_TIMEOUT_MS = Number(process.env.OPENWOP_LIFECYCLE_TIMEOUT_MS ?? 10_000);
 
-/**
- * Multiplier applied to every poll bound (see the module docstring). Invalid,
- * non-positive, or non-finite values fall back to `1` rather than silently
- * producing a zero or negative deadline — a mis-set knob must not turn every
- * poll into an instant failure that looks like a host defect.
- */
-function pollTimeoutScale(): number {
-  const raw = process.env.OPENWOP_POLL_TIMEOUT_SCALE;
-  if (raw === undefined || raw === '') return 1;
-  const n = Number(raw);
-  return Number.isFinite(n) && n > 0 ? n : 1;
-}
-
-/** Apply the scale to a bound, rounding up so a scale of 1 is exactly a no-op. */
-export function scaledTimeoutMs(timeoutMs: number): number {
-  const scale = pollTimeoutScale();
-  return scale === 1 ? timeoutMs : Math.ceil(timeoutMs * scale);
-}
+export { scaledTimeoutMs };
 
 /**
  * Live-model scenarios (RFC 0111's `conformance-context-budget-live`) drive real

package/src/lib/profiles.ts

@@ -495,6 +495,16 @@ export interface ProfileFloor {
   readonly required: readonly string[];
   /** Prefix groups where ≥1 matching passed scenario satisfies the group. */
   readonly requiredAnyPrefix?: readonly string[];
+  /**
+   * RFC 0229 §E — ANY-OF groups: each inner list names alternative scenario
+   * files, and the group is satisfied when at least one of them records a
+   * WITNESSED pass and none of them records a failure. A group is one
+   * requirement (`openwop.floor.anyof.<stem>+<stem>`, a summary row the runner
+   * derives from the members, like `requiredAnyPrefix`). An `inapplicable` or
+   * `skipped` member never satisfies it: `openwop-secrets` is certified by the
+   * canary round-trip OR the run-witness, not by the absence of both.
+   */
+  readonly requiredAnyOf?: ReadonlyArray<readonly string[]>;
   /**
    * The profile is discovery-payload-only: its predicate IS the whole claim and
    * it has no runtime floor. This flag exists so an EMPTY floor is a decision on
@@ -529,6 +539,11 @@ export interface ProfileFloor {
   readonly conditional?: ReadonlyArray<{ readonly path: string; readonly includes: string; readonly required: readonly string[] }>;
 }
 
+/** Every scenario FILE a floor names: `required`, every `conditional` branch, and every `requiredAnyOf` member. */
+export function floorMemberFiles(floor: ProfileFloor): string[] {
+  return [...floor.required, ...(floor.conditional ?? []).flatMap((c) => c.required), ...(floor.requiredAnyOf ?? []).flat()];
+}
+
 export const PROFILE_FLOOR_SCENARIOS: Readonly<Record<string, ProfileFloor>> = {
   'openwop-core-standard': {
     required: [
@@ -607,7 +622,11 @@ export const PROFILE_FLOOR_SCENARIOS: Readonly<Record<string, ProfileFloor>> = {
   // `profiles.md` §`openwop-secrets`: credential resolution per `run-options.md`
   // §"Credential references" — the BYOK canary round-trip (`fixtures.md`
   // §conformance-secrets-roundtrip, SR-1) is the profile's proof.
-  'openwop-secrets': { required: ['byok-roundtrip.test.ts'] },
+  // RFC 0229 §E (2026-09-30): a SECOND floor path, as an any-of group. The
+  // canary fixture's node is an oracle over whatever its name reaches, so a
+  // production host rightly withholds it; the run-witness reads only a value
+  // the caller supplied with the same run and outputs only `matched`.
+  'openwop-secrets': { required: [], requiredAnyOf: [['byok-roundtrip.test.ts', 'secrets-run-witness.test.ts']] },
 
   // `profiles.md` §`openwop-provider-policy`: the four-mode taxonomy shape and
   // its enforcement on the wire.
@@ -756,9 +775,14 @@ export function verifyBundleProfile(bundle: CertificationBundleLike, profile: st
   }
   const missingFloor = requiredFiles.filter((r) => !passed.has(scenarioBasename(r)));
   const prefixOk = (floor.requiredAnyPrefix ?? []).every((p) => [...passed].some((s) => s.startsWith(p)));
+  // RFC 0229 §E any-of groups: a v1 bundle lists only what passed, so a group
+  // holds when one member is in `results.passed`; an unmet group is reported
+  // as missing, spelled as its alternatives.
+  const groups = floor.requiredAnyOf ?? [];
+  for (const g of groups) if (!g.some((f) => passed.has(scenarioBasename(f)))) missingFloor.push(g.join(' | '));
   // A conditional floor none of whose branches matched requires nothing — that
   // is unprovable for a non-discovery-only profile, not proven.
-  const evaluable = floor.discoveryOnly === true || requiredFiles.length > 0 || (floor.requiredAnyPrefix ?? []).length > 0;
+  const evaluable = floor.discoveryOnly === true || requiredFiles.length > 0 || (floor.requiredAnyPrefix ?? []).length > 0 || groups.length > 0;
   const floorProven = evaluable && missingFloor.length === 0 && prefixOk;
   return {
     profile,

package/src/lib/requirement-registry.ts

@@ -36,6 +36,15 @@ export function requirementIdForPrefix(prefix: string): string {
   return `openwop.floor.any.${prefix}`;
 }
 
+/**
+ * Any-of groups (RFC 0229 §E) become one requirement:
+ * `['byok-roundtrip.test.ts', 'secrets-run-witness.test.ts']` →
+ * `openwop.floor.anyof.byok-roundtrip+secrets-run-witness`.
+ */
+export function requirementIdForAnyOf(files: readonly string[]): string {
+  return `openwop.floor.anyof.${files.map((f) => f.replace(/\.test\.ts$/, '')).join('+')}`;
+}
+
 /**
  * The requirement IDs a profile's certification rests on.
  *
@@ -122,6 +131,7 @@ export function requirementsFor(profile: string, document?: Readonly<Record<stri
   return [
     ...files.map(requirementIdForScenario),
     ...(floor.requiredAnyPrefix ?? []).map(requirementIdForPrefix),
+    ...(floor.requiredAnyOf ?? []).map(requirementIdForAnyOf),
   ];
 }
 
@@ -134,6 +144,8 @@ export function allRequirements(): readonly string[] {
     for (const f of floor.required) ids.add(requirementIdForScenario(f));
     for (const c of floor.conditional ?? []) for (const f of c.required) ids.add(requirementIdForScenario(f));
     for (const p of floor.requiredAnyPrefix ?? []) ids.add(requirementIdForPrefix(p));
+    // an any-of group is one requirement, and each member file records under its own floor id
+    for (const g of floor.requiredAnyOf ?? []) { ids.add(requirementIdForAnyOf(g)); for (const f of g) ids.add(requirementIdForScenario(f)); }
     void profile;
   }
   return [...ids].sort();

package/src/lib/run-secrets-witness.ts

@@ -0,0 +1,240 @@
+/**
+ * RFC 0229 — the production-safe secret witness, shared by `secrets-run-witness`
+ * (major 1, `/v1/...`) and `v2-secrets-run-witness` (major 2, unversioned
+ * paths under `OpenWOP-Version: 2.0`, which the driver adds).
+ *
+ * The suite draws a fresh value `C` per run (48 CSPRNG bytes, base64url, 64
+ * characters, no fixed prefix) and supplies it as the top-level
+ * `runSecrets: [{ ref, value: C }]` of `createRun`. The fixture
+ * `openwop-secrets-run-witness` runs one `core.secret.witness` node that
+ * compares `sha256(C)` with an `expectedSha256` input and outputs only
+ * `{ matched }`. The scans read RAW response text, never parsed JSON, so an
+ * escaping difference cannot hide a hit (RFC 0229 Implementation notes).
+ *
+ * @see spec/v2/core/host-services.md §Run-supplied secrets
+ * @see spec/v1/capabilities.md §"Run-supplied secrets"
+ * @see RFCS/0229-production-safe-secrets-witness.md
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { driver, type OpenWOPResponse } from './driver.js';
+import { loadEnv } from './env.js';
+import { discoveryFamilies } from './discovery-capabilities.js';
+import { isFixtureAdvertised } from './fixtures.js';
+
+export const WITNESS_FIXTURE = 'openwop-secrets-run-witness';
+export const WITNESS_NODE = 'witness';
+export const WITNESS_REF = 'run:openwop-witness';
+export const CANARY_NAME = 'openwop-conformance-canary-secret';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+export type Major = 1 | 2;
+export type Gate =
+  | { ok: true; maxEntries: number; branchFork: boolean }
+  | { ok: false; kind: 'inapplicable' | 'blocked'; reason: string };
+
+export const sha256Hex = (s: string): string => createHash('sha256').update(s, 'utf8').digest('hex');
+
+/** A fresh witness value: 48 CSPRNG bytes, base64url, 64 characters, no fixed prefix. */
+export function freshValue(): string {
+  return randomBytes(48).toString('base64url');
+}
+
+/** A fresh non-`run:` secret name (the scope leg's "random name"). */
+export function freshName(): string {
+  return `openwop-witness-${randomBytes(9).toString('hex')}`;
+}
+
+/**
+ * Every form in which `C` "appears" (RFC 0229 §F row 2): raw; standard and
+ * URL-safe base64 of its UTF-8 bytes, padded and not; lower- and upper-case
+ * hex of those bytes; percent-encoded; JSON-string-escaped; and `sha256(C)`
+ * (lower and upper hex, and base64) — the digest is an output §B.3 forbids.
+ */
+export function forms(c: string): ReadonlyArray<{ name: string; text: string }> {
+  const bytes = Buffer.from(c, 'utf8');
+  const b64 = bytes.toString('base64');
+  const b64url = bytes.toString('base64url');
+  const digest = createHash('sha256').update(bytes).digest();
+  const out = [
+    { name: 'raw', text: c },
+    { name: 'base64', text: b64 },
+    { name: 'base64 (unpadded)', text: b64.replace(/=+$/, '') },
+    { name: 'base64url', text: b64url },
+    { name: 'base64url (padded)', text: b64url + '='.repeat((4 - (b64url.length % 4)) % 4) },
+    { name: 'hex', text: bytes.toString('hex') },
+    { name: 'HEX', text: bytes.toString('hex').toUpperCase() },
+    { name: 'percent-encoded', text: encodeURIComponent(c) },
+    { name: 'JSON-escaped', text: JSON.stringify(c).slice(1, -1) },
+    { name: 'sha256 hex', text: digest.toString('hex') },
+    { name: 'SHA256 HEX', text: digest.toString('hex').toUpperCase() },
+    { name: 'sha256 base64', text: digest.toString('base64') },
+  ];
+  return out.filter((f, i) => out.findIndex((g) => g.text === f.text) === i);
+}
+
+/**
+ * The forms of `c` that occur in `text`. `digestSupplied`: the suite itself
+ * passed `sha256(C)` as the run's `expectedSha256` input, which a host may
+ * legitimately echo as an input, so the digest forms are not a leak for that
+ * run and are not scanned. They are scanned for every value whose digest the
+ * suite never sent (the mismatch run, and the retried value `C′`).
+ */
+export function hits(text: string, c: string, digestSupplied = false): string[] {
+  return forms(c).filter((f) => !(digestSupplied && f.name.toLowerCase().startsWith('sha256'))).filter((f) => text.includes(f.text)).map((f) => f.name);
+}
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+export class WitnessHost {
+  constructor(readonly major: Major) {}
+
+  private p(path: string): string {
+    return this.major === 1 ? `/v1${path}` : path;
+  }
+
+  private enc(id: string): string {
+    return encodeURIComponent(id);
+  }
+
+  async discovery(): Promise<Record<string, unknown> | null> {
+    const res = await http(() => driver.get('/.well-known/openwop', { authenticated: false }));
+    return res?.status === 200 && res.json && typeof res.json === 'object' ? discoveryFamilies(res.json) : null;
+  }
+
+  /**
+   * RFC 0229 §F dispositions: facet absent ⇒ `inapplicable` (the host offers
+   * no run-supplied secrets); facet advertised without the fixture ⇒ `blocked`
+   * (§C requires it). Discovery unreadable ⇒ `blocked`.
+   */
+  async gate(): Promise<Gate> {
+    const doc = await this.discovery();
+    if (doc === null) return { ok: false, kind: 'blocked', reason: '/.well-known/openwop did not answer 200 with a JSON body' };
+    const secrets = doc['secrets'];
+    const rs = secrets && typeof secrets === 'object' ? (secrets as Record<string, unknown>)['runSecrets'] : undefined;
+    if (rs === undefined || rs === null || typeof rs !== 'object') {
+      return { ok: false, kind: 'inapplicable', reason: 'secrets.runSecrets is not advertised — the host offers no run-supplied secrets (RFC 0229 §D)' };
+    }
+    if (!isFixtureAdvertised(WITNESS_FIXTURE)) {
+      return { ok: false, kind: 'blocked', reason: `secrets.runSecrets is advertised but the fixture ${WITNESS_FIXTURE} is not — RFC 0229 §C requires it, so the witness cannot run` };
+    }
+    const maxEntries = Number((rs as Record<string, unknown>)['maxEntries']);
+    const replay = doc['replay'];
+    const modes = replay && typeof replay === 'object' ? (replay as Record<string, unknown>)['modes'] : undefined;
+    const supported = this.major === 1 ? (replay as Record<string, unknown> | undefined)?.['supported'] === true : replay !== undefined;
+    return { ok: true, maxEntries: Number.isFinite(maxEntries) ? maxEntries : 1, branchFork: supported && Array.isArray(modes) && modes.includes('branch') };
+  }
+
+  /** `createRun` of the witness fixture. `runSecrets` is omitted when `undefined`. */
+  create(inputs: { ref: string; expectedSha256: string }, runSecrets?: ReadonlyArray<{ ref: string; value: string }>, idempotencyKey?: string): Promise<OpenWOPResponse | null> {
+    const body: Record<string, unknown> = { workflowId: WITNESS_FIXTURE, inputs };
+    if (runSecrets !== undefined) body['runSecrets'] = runSecrets;
+    return http(() => driver.post(this.p('/runs'), body, idempotencyKey === undefined ? {} : { headers: { 'Idempotency-Key': idempotencyKey } }));
+  }
+
+  async snapshot(runId: string): Promise<OpenWOPResponse | null> {
+    return http(() => driver.get(this.p(`/runs/${this.enc(runId)}`)));
+  }
+
+  async waitTerminal(runId: string, timeoutMs = 20_000): Promise<Record<string, unknown> | null> {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const res = await this.snapshot(runId);
+      const snap = res?.status === 200 && res.json && typeof res.json === 'object' ? (res.json as Record<string, unknown>) : null;
+      if (snap !== null && TERMINAL.has(String(snap['status']))) return snap;
+      if (Date.now() > deadline) return snap;
+      await new Promise((r) => setTimeout(r, 250));
+    }
+  }
+
+  async events(runId: string): Promise<{ text: string; events: Array<Record<string, unknown>> }> {
+    const res = await http(() => driver.get(this.p(`/runs/${this.enc(runId)}/events/poll?timeout=1`)));
+    let events: Array<Record<string, unknown>> = [];
+    const body = res?.json as { events?: unknown } | undefined;
+    if (Array.isArray(body?.events)) events = body.events as Array<Record<string, unknown>>;
+    if (events.length === 0 && this.major === 1) {
+      const alt = await http(() => driver.get(this.p(`/runs/${this.enc(runId)}/events`)));
+      const b = alt?.json as { events?: unknown } | undefined;
+      if (Array.isArray(b?.events)) return { text: `${res?.text ?? ''}\n${alt?.text ?? ''}`, events: b.events as Array<Record<string, unknown>> };
+    }
+    return { text: res?.text ?? '', events };
+  }
+
+  /** The raw SSE text under `streamMode=debug` — the most verbose mode (events.md §Stream modes). */
+  async debugStream(runId: string, timeoutMs = 6_000): Promise<string> {
+    const env = loadEnv();
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${env.baseUrl}${this.p(`/runs/${this.enc(runId)}/events`)}?streamMode=debug`, {
+        headers: { Accept: 'text/event-stream', Authorization: `Bearer ${env.apiKey}`, ...(this.major === 2 ? { 'OpenWOP-Version': '2.0' } : {}) },
+        signal: ctl.signal,
+      });
+      if (res.body === null) return '';
+      try { return await res.text(); } catch { return ''; }
+    } catch {
+      return '';
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Every readable surface of a terminal run, as raw text: the create answer,
+   * the snapshot, the polled events, the `debug` stream, the run list (where
+   * served), and the debug bundle (where the seam serves one).
+   */
+  async surfaces(runId: string, extra: readonly string[] = []): Promise<{ text: string; read: string[] }> {
+    const read: string[] = [];
+    const parts: string[] = [...extra];
+    if (extra.length > 0) read.push('createRun response');
+    const snap = await this.snapshot(runId);
+    if (snap !== null) { parts.push(snap.text); read.push('snapshot'); }
+    const ev = await this.events(runId);
+    parts.push(ev.text); read.push('events (poll)');
+    const dbg = await this.debugStream(runId);
+    if (dbg.length > 0) { parts.push(dbg); read.push('events (streamMode=debug)'); }
+    const list = await http(() => driver.get(this.p('/runs?limit=50')));
+    if (list?.status === 200) { parts.push(list.text); read.push('listRuns'); }
+    const bundle = await http(() => driver.post('/v1/host/sample/test/debug-bundle/export', { runId }));
+    if (bundle?.status === 200) { parts.push(bundle.text); read.push('debug bundle'); }
+    return { text: parts.join('\n'), read };
+  }
+
+  /** `witness`'s `matched`, from `node.completed` outputs or the snapshot; `undefined` when not observable. */
+  async matched(runId: string, snap: Record<string, unknown> | null): Promise<boolean | undefined> {
+    const { events } = await this.events(runId);
+    for (const e of events) {
+      if (e['type'] !== 'node.completed') continue;
+      const payload = (e['payload'] ?? e['data'] ?? {}) as Record<string, unknown>;
+      if ((payload['nodeId'] ?? e['nodeId']) !== WITNESS_NODE) continue;
+      const outputs = (payload['outputs'] ?? e['outputs']) as Record<string, unknown> | undefined;
+      if (typeof outputs?.['matched'] === 'boolean') return outputs['matched'] as boolean;
+    }
+    for (const key of ['outputs', 'variables', 'nodeOutputs']) {
+      const bag = snap?.[key] as Record<string, unknown> | undefined;
+      const node = bag?.[WITNESS_NODE] as Record<string, unknown> | undefined;
+      if (typeof node?.['matched'] === 'boolean') return node['matched'] as boolean;
+    }
+    return undefined;
+  }
+
+  /** `witness`'s `node.failed` error code; `null` when no `node.failed` names it. */
+  async nodeFailedCode(runId: string): Promise<string | null> {
+    const { events } = await this.events(runId);
+    for (const e of events) {
+      if (e['type'] !== 'node.failed') continue;
+      const payload = (e['payload'] ?? e['data'] ?? {}) as Record<string, unknown>;
+      if ((payload['nodeId'] ?? e['nodeId']) !== WITNESS_NODE) continue;
+      const err = (payload['error'] ?? e['error']) as Record<string, unknown> | undefined;
+      return typeof err?.['code'] === 'string' ? (err['code'] as string) : '';
+    }
+    return null;
+  }
+
+  fork(runId: string): Promise<OpenWOPResponse | null> {
+    return http(() => driver.post(this.p(`/runs/${this.enc(runId)}:fork`), { mode: 'branch', fromSeq: 0 }));
+  }
+}