@openwop/openwop-conformance 1.163.0 → 2.0.0-rc.1

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

@@ -0,0 +1,175 @@
+/**
+ * Certification bundle v3 (RFC 0168 §E; schemas/v2/certification-bundle.schema.json).
+ *
+ * What v3 adds over v2 and why:
+ *   - a closed root and `witnessSha256` over the reporter record (RFC 0148 §C
+ *     asked for it; the v2 schema listed it optional and no emitter wrote it);
+ *   - `assertionCount`, `host.build`, per-profile `evidenceTier`/`witnessCount`,
+ *     `detail` (required when any result is not executed-pass);
+ *   - an Ed25519 attestation over the canonical JSON of
+ *     { witnessSha256, host.build, suite.version, discovery.sha256 } — the same
+ *     commit rebuilt once scored 283/22 and 303/2 and nothing in the bundle could
+ *     tell them apart; the build id plus the signature can;
+ *   - `evidenceTier: independent` REQUIRES a verifier signature under a key id
+ *     distinct from the host's (RFC 0148 R5: a malicious generator fabricates
+ *     witnesses — a self-signed "independent" claim is refused, not warned).
+ *
+ * This module is schema-agnostic on purpose (the schema check is a separate step
+ * in cli.ts) and pure: it never reads the environment.
+ */
+import { createHash, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify, type KeyObject } from 'node:crypto';
+
+export type BundleV3Result = 'executed-pass' | 'executed-fail' | 'skipped' | 'inapplicable' | 'blocked';
+
+export interface BundleV3Requirement {
+  readonly id: string;
+  readonly scenario: string;
+  readonly result: BundleV3Result;
+  readonly assertions?: number;
+  readonly detail?: string;
+}
+export interface BundleV3Profile {
+  readonly id: string;
+  readonly evidenceTier: 'self' | 'steward' | 'independent';
+  readonly witnessCount: number;
+  readonly certified: boolean;
+}
+export interface BundleV3Relaxation { readonly obligation: string; readonly durability: 'session' | 'deployment' | 'persisted'; readonly reason: string }
+export interface BundleV3Signature { readonly alg: 'ed25519'; readonly keyId: string; readonly sig: string; readonly over: readonly string[]; readonly verifierKeyId?: string }
+export interface BundleV3 {
+  bundleVersion: '3';
+  generatedAt: string;
+  suite: { name: '@openwop/openwop-conformance'; version: string; targetMajor: 1 | 2; specArtifactsVersion: string; stampSha256?: string };
+  host: { name: string; version: string; vendor?: string; build: { kind: 'image-digest' | 'commit' | 'artifact-sha256'; id: string }; signingKeyId?: string; relaxations?: BundleV3Relaxation[] };
+  discovery: { url: string; sha256: string; protocolVersions: string[]; preferredVersion: string };
+  claimedProfiles: BundleV3Profile[];
+  results: { totals: Record<'executedPass' | 'executedFail' | 'skipped' | 'inapplicable' | 'blocked', number>; requirements: BundleV3Requirement[] };
+  witnessSha256: string;
+  assertionCount: number;
+  detail?: { nonPass: { id: string; result: string; reason: string }[] };
+  signature: BundleV3Signature;
+  verifierSignature?: { alg: 'ed25519'; keyId: string; sig: string };
+}
+
+export const SIGNATURE_OVER = ['witnessSha256', 'host.build', 'suite.version', 'discovery.sha256'] as const;
+
+/** Deterministic JSON: keys sorted at every level, no whitespace. */
+export function canonicalJSON(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJSON).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.keys(value as Record<string, unknown>).sort().map((k) => `${JSON.stringify(k)}:${canonicalJSON((value as Record<string, unknown>)[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+/** RFC 0148 §C — the digest over the reporter record (the requirement rows). */
+export function witnessDigest(rows: readonly BundleV3Requirement[]): string {
+  const canonicalRows = [...rows].sort((a, b) => a.id.localeCompare(b.id)).map((r) => ({ id: r.id, scenario: r.scenario, result: r.result, ...(r.assertions === undefined ? {} : { assertions: r.assertions }), ...(r.detail === undefined ? {} : { detail: r.detail }) }));
+  return createHash('sha256').update(canonicalJSON(canonicalRows), 'utf8').digest('hex');
+}
+
+/** The bytes the attestation covers. */
+export function attestationPayload(b: Pick<BundleV3, 'witnessSha256' | 'host' | 'suite' | 'discovery'>): Buffer {
+  return Buffer.from(canonicalJSON({ witnessSha256: b.witnessSha256, 'host.build': b.host.build, 'suite.version': b.suite.version, 'discovery.sha256': b.discovery.sha256 }), 'utf8');
+}
+
+function toBase64url(buf: Buffer): string { return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, ''); }
+function fromBase64url(s: string): Buffer { return Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/'), 'base64'); }
+
+export function signBundleV3(bundle: Omit<BundleV3, 'signature'>, privateKeyPem: string, keyId: string): BundleV3Signature {
+  const key = createPrivateKey(privateKeyPem);
+  if (key.asymmetricKeyType !== 'ed25519') throw new Error(`bundle v3 signing key must be Ed25519, got ${String(key.asymmetricKeyType)}`);
+  const sig = edSign(null, attestationPayload(bundle), key);
+  return { alg: 'ed25519', keyId, sig: toBase64url(sig), over: [...SIGNATURE_OVER] };
+}
+
+export function verifierSign(bundle: Pick<BundleV3, 'witnessSha256' | 'host' | 'suite' | 'discovery'>, privateKeyPem: string, keyId: string): NonNullable<BundleV3['verifierSignature']> {
+  const key = createPrivateKey(privateKeyPem);
+  return { alg: 'ed25519', keyId, sig: toBase64url(edSign(null, attestationPayload(bundle), key)) };
+}
+
+export function publicKeyFromPrivate(privateKeyPem: string): string {
+  return createPublicKey(createPrivateKey(privateKeyPem)).export({ type: 'spki', format: 'pem' }) as string;
+}
+
+export interface VerifyV3Options {
+  /** The host's public key (PEM). Without it the signature's bytes are checked for shape only and the verdict says `signatureVerified: false`. */
+  readonly hostPublicKeyPem?: string;
+  /** The verifier's public key (PEM) — required to verify an `independent` claim. */
+  readonly verifierPublicKeyPem?: string;
+}
+export interface V3Rejection { readonly kind: string; readonly detail: string; readonly profile?: string }
+export interface V3Verdict {
+  readonly rejections: V3Rejection[];
+  readonly signatureVerified: boolean;
+  readonly verifierSignatureVerified: boolean;
+  readonly certifiedProfiles: string[];
+}
+
+export function verifyBundleV3(bundle: BundleV3, opts: VerifyV3Options = {}): V3Verdict {
+  const rejections: V3Rejection[] = [];
+  if (bundle.bundleVersion !== '3') rejections.push({ kind: 'not-v3', detail: `bundleVersion is ${JSON.stringify(bundle.bundleVersion)}, expected "3"` });
+  const rows = bundle.results?.requirements ?? [];
+  const seen = new Set<string>();
+  for (const r of rows) {
+    if (seen.has(r.id)) rejections.push({ kind: 'duplicate-requirement', detail: `${r.id}: more than one row (RFC 0148 §A)` });
+    seen.add(r.id);
+    if (r.result !== 'executed-pass' && !(r.detail && r.detail.trim())) rejections.push({ kind: 'reason-missing', detail: `${r.id}: '${r.result}' recorded without a reason` });
+    if (r.result === 'executed-pass' && !(r.assertions && r.assertions > 0)) rejections.push({ kind: 'vacuous-pass', detail: `${r.id}: executed-pass with no assertions is a witness of nothing (RFC 0148 §C)` });
+  }
+  const count = (d: BundleV3Result): number => rows.filter((r) => r.result === d).length;
+  const expected = { executedPass: count('executed-pass'), executedFail: count('executed-fail'), skipped: count('skipped'), inapplicable: count('inapplicable'), blocked: count('blocked') };
+  for (const k of Object.keys(expected) as (keyof typeof expected)[]) if (bundle.results?.totals?.[k] !== expected[k]) rejections.push({ kind: 'totals-mismatch', detail: `totals.${k} is ${String(bundle.results?.totals?.[k])} but the rows count ${expected[k]}` });
+  const digest = witnessDigest(rows);
+  if (bundle.witnessSha256 !== digest) rejections.push({ kind: 'witness-digest', detail: `witnessSha256 ${String(bundle.witnessSha256).slice(0, 12)} does not equal the digest of the rows (${digest.slice(0, 12)})` });
+  const assertions = rows.reduce((n, r) => n + (r.assertions ?? 0), 0);
+  if (bundle.assertionCount !== assertions) rejections.push({ kind: 'assertion-count', detail: `assertionCount is ${String(bundle.assertionCount)} but the rows sum to ${assertions}` });
+  const nonPass = rows.filter((r) => r.result !== 'executed-pass');
+  if (nonPass.length > 0 && !bundle.detail) rejections.push({ kind: 'detail-missing', detail: `${nonPass.length} non-pass row(s) and no detail block` });
+  if (!bundle.host?.build?.kind || !bundle.host?.build?.id) rejections.push({ kind: 'build-missing', detail: 'host.build.{kind,id} is required — a bundle attributes to a BUILD, not a commit' });
+
+  // Signature
+  let signatureVerified = false;
+  const sig = bundle.signature;
+  if (!sig || sig.alg !== 'ed25519' || !sig.keyId || !sig.sig) rejections.push({ kind: 'signature-missing', detail: 'signature.{alg: ed25519, keyId, sig} is required in v3' });
+  else if (JSON.stringify(sig.over) !== JSON.stringify(SIGNATURE_OVER)) rejections.push({ kind: 'signature-over', detail: `signature.over must be ${JSON.stringify(SIGNATURE_OVER)}` });
+  else if (opts.hostPublicKeyPem) {
+    const key: KeyObject = createPublicKey(opts.hostPublicKeyPem);
+    signatureVerified = edVerify(null, attestationPayload(bundle), key, fromBase64url(sig.sig));
+    if (!signatureVerified) rejections.push({ kind: 'signature-invalid', detail: 'the attestation does not verify under the host key' });
+  }
+  // Independent tier
+  let verifierSignatureVerified = false;
+  const claimsIndependent = (bundle.claimedProfiles ?? []).some((p) => p.evidenceTier === 'independent');
+  if (claimsIndependent) {
+    const vs = bundle.verifierSignature;
+    if (!vs || !vs.keyId || !vs.sig) rejections.push({ kind: 'independent-unsigned', detail: 'evidenceTier independent requires a verifierSignature (RFC 0168 §E.2)' });
+    else if (vs.keyId === sig?.keyId || vs.keyId === bundle.host?.signingKeyId) rejections.push({ kind: 'independent-self-signed', detail: 'the verifier key must be distinct from the host key (RFC 0148 R5)' });
+    else if (opts.verifierPublicKeyPem) {
+      verifierSignatureVerified = edVerify(null, attestationPayload(bundle), createPublicKey(opts.verifierPublicKeyPem), fromBase64url(vs.sig));
+      if (!verifierSignatureVerified) rejections.push({ kind: 'verifier-signature-invalid', detail: 'the verifier attestation does not verify' });
+    } else rejections.push({ kind: 'independent-unverifiable', detail: 'an independent claim needs the verifier public key to verify; refused, not assumed' });
+  }
+  // Relaxations: a relaxed obligation's profile cannot certify (RFC 0173 §A.2).
+  const relaxed = new Set((bundle.host?.relaxations ?? []).map((r) => r.obligation.split('.')[0]));
+  const certifiedProfiles: string[] = [];
+  for (const p of bundle.claimedProfiles ?? []) {
+    if (p.certified && relaxed.size > 0 && [...relaxed].some((o) => p.id.includes(o))) rejections.push({ kind: 'relaxed-profile-certified', profile: p.id, detail: `${p.id} is marked certified while a relaxation on ${[...relaxed].join(', ')} is recorded (RFC 0173 §A.2)` });
+    else if (p.certified) certifiedProfiles.push(p.id);
+  }
+  if (expected.blocked > 0 && certifiedProfiles.length > 0) rejections.push({ kind: 'blocked-certified', detail: `${expected.blocked} blocked row(s): a bundle with blocked > 0 does not certify (RFC 0168 §E.1)` });
+  // RFC 0168 §E.2: the verifier REFUSES, it does not warn — but a refusal is
+  // scoped to what it names. A rejection carrying a `profile` removes that
+  // profile only (a relaxation on one obligation does not poison an unrelated
+  // one, RFC 0173 §A.2); a rejection that names no profile is a statement about
+  // the bundle — a bad witness digest, an unverifiable signature, a self-signed
+  // `independent` claim, a blocked row — and nothing in it certifies.
+  const bundleWide = rejections.filter((r) => !('profile' in r) || !r.profile);
+  const scoped = new Set(rejections.map((r) => r.profile).filter((p): p is string => typeof p === 'string'));
+  return {
+    rejections,
+    signatureVerified,
+    verifierSignatureVerified,
+    certifiedProfiles: bundleWide.length > 0 ? [] : certifiedProfiles.filter((p) => !scoped.has(p)),
+  };
+}

package/src/lib/corpus-stamp.ts

@@ -26,7 +26,8 @@
 
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
+import { createRequire } from 'node:module';
+import { join, relative, sep, dirname } from 'node:path';
 
 export interface CorpusStamp {
   readonly suiteVersion?: string;
@@ -73,6 +74,33 @@ export function digestVendoredFiles(root: string): Record<string, string> {
  * Compare the stamp's `files` map against the bytes on disk. Pure: reads,
  * never writes, never throws on a mismatch — the caller decides how loud.
  */
+/**
+ * Suite 2.0.0 (RFC 0168 §D.2): the contract is the `@openwop/spec-artifacts` peer.
+ * The suite embeds, at pack time, `dist/spec-artifacts.lock.json` =
+ * { version, stampSha256 } for the peer it was built against; at start it
+ * resolves the installed peer, recomputes its stamp digest, and refuses to run
+ * on a version or digest mismatch (a floating peer makes a bundle
+ * irreproducible). The peer's own files are then verified against its stamp.
+ */
+export function verifyPeerContract(pkgRoot: string): StampVerdict {
+  const lockPath = join(pkgRoot, 'dist', 'spec-artifacts.lock.json');
+  if (!existsSync(lockPath)) return { kind: 'not-applicable', reason: 'dist/spec-artifacts.lock.json is absent — a repo checkout, not a packed 2.x suite' };
+  let lock: { version: string; stampSha256: string };
+  try { lock = JSON.parse(readFileSync(lockPath, 'utf8')); } catch { return { kind: 'mismatch', missing: ['dist/spec-artifacts.lock.json'], altered: [], extra: [] }; }
+  let peerRoot: string;
+  try { peerRoot = dirname(createRequire(join(pkgRoot, 'package.json')).resolve('@openwop/spec-artifacts/package.json')); }
+  catch { return { kind: 'mismatch', missing: ['node_modules/@openwop/spec-artifacts (peer dependency not installed)'], altered: [], extra: [] }; }
+  const stampPath = join(peerRoot, 'CORPUS-STAMP.json');
+  if (!existsSync(stampPath)) return { kind: 'mismatch', missing: ['@openwop/spec-artifacts/CORPUS-STAMP.json'], altered: [], extra: [] };
+  const stamp = JSON.parse(readFileSync(stampPath, 'utf8')) as { package: string; version: string; files: Record<string, string> };
+  const digest = createHash('sha256').update(JSON.stringify({ package: stamp.package, version: stamp.version, files: stamp.files })).digest('hex');
+  if (stamp.version !== lock.version || digest !== lock.stampSha256) return { kind: 'mismatch', missing: [], altered: [`@openwop/spec-artifacts ${stamp.version} (digest ${digest.slice(0, 12)}) ≠ the suite's lock ${lock.version} (${lock.stampSha256.slice(0, 12)})`], extra: [] };
+  const missing: string[] = []; const altered: string[] = [];
+  for (const [rel, d] of Object.entries(stamp.files)) { const p = join(peerRoot, ...rel.split('/')); if (!existsSync(p)) missing.push(rel); else if (sha256File(p) !== d) altered.push(rel); }
+  if (missing.length || altered.length) return { kind: 'mismatch', missing, altered, extra: [] };
+  return { kind: 'verified', files: Object.keys(stamp.files).length };
+}
+
 export function verifyCorpusStamp(root: string, layout: string): StampVerdict {
   if (layout !== 'published') {
     return { kind: 'not-applicable', reason: `layout is '${layout}' — the vendored copy exists only in the published package` };

package/src/lib/driver.ts

@@ -10,6 +10,7 @@
  */
 
 import { loadEnv } from './env.js';
+import { seamPath, targetMajor } from './seams.js';
 
 export interface OpenWOPResponse {
   readonly status: number;
@@ -37,10 +38,17 @@ class OpenWOPDriver {
     const env = loadEnv();
     // An absolute URL is used as-is (a host may advertise its MCP server mount or
     // an A2A endpoint on another origin); a path is joined to the base URL.
-    const url = /^https?:\/\//i.test(path) ? path : `${env.baseUrl}${path}`;
+    // Suite 2.0.0: under target major 2 a v1 seam path is rewritten to its
+    // api/seams-v2.yaml address (RFC 0168 §C.2) and every request names the
+    // contract it speaks with `OpenWOP-Version` (RFC 0172 §A.3) unless the
+    // scenario set one itself (the negotiation scenarios do).
+    const major = targetMajor();
+    const effectivePath = major === 2 ? seamPath(path) : path;
+    const url = /^https?:\/\//i.test(effectivePath) ? effectivePath : `${env.baseUrl}${effectivePath}`;
 
     const headers: Record<string, string> = {
       Accept: 'application/json',
+      ...(major === 2 && !Object.keys(init.headers ?? {}).some((h) => h.toLowerCase() === 'openwop-version') ? { 'OpenWOP-Version': '2.0' } : {}),
       ...(init.headers ?? {}),
     };
     if (init.body !== undefined && headers['Content-Type'] === undefined) {

package/src/lib/era2-seed.ts

@@ -0,0 +1,197 @@
+/**
+ * Suite 2.0.0 — the era-`2` event-log seed for the RFC 0176 persisted-data
+ * scenarios (`v2-v1-events-translated`, `v2-unmapped-type-refused`,
+ * `v2-fork-a-v1-run`, `v2-pinned-run-disposition`).
+ *
+ * A v2 host reading a run written by a v1 host translates every event through
+ * `spec/v2/event-codemap.json` at the storage boundary (persistence.md §The
+ * reader rule). To witness that from outside, the suite needs a run whose
+ * persisted log is in v1 vocabulary — which only a host that predates the cut
+ * has, unless a seam writes one. The seam these scenarios drive (seams-profile
+ * gated, RFC 0168 §C):
+ *
+ *   POST /conformance/seams/sample/event-log/seed
+ *     { eventLogSchemaVersion: 2, status, events: [{ type, sequence, payload, timestamp?, causationId? }] }
+ *     → 201 { runId }
+ *
+ * The host MUST persist the rows verbatim (v1 `type` strings, the given
+ * `sequence` space, no era stamp — the run reads as era `2` by the absent-⇒-`2`
+ * rule) and MUST NOT translate them at write time; the point of the seam is
+ * that the read projection does the work. `status` is the snapshot status the
+ * seeded run holds (`completed` for a finished log, `running` for a run the
+ * pinned-run disposition must decide). The seam is catalogued in
+ * `api/seams-v2.yaml` (`seedEra2EventLog`); a host answering `404` /
+ * `403` / `405` records `blocked` naming it (never a pass), and a host that
+ * answers anything but `201 { runId }` records `blocked` with the status.
+ *
+ * The scenarios name the seam by its v1-shaped path
+ * (`/v1/host/sample/event-log/seed`); under target major 2 the driver rewrites
+ * it to the address above (lib/seams.ts).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driver, type OpenWOPResponse } from './driver.js';
+import { loadEnv } from './env.js';
+import { seamPath, seamsProfileAdvertised } from './seams.js';
+import { readErrorCode } from './error-envelope.js';
+import { V1_DIR } from './paths.js';
+
+export const SEED_PATH_V1 = '/v1/host/sample/event-log/seed';
+export const SEED_PATH = seamPath(SEED_PATH_V1);
+
+export interface SeedEvent {
+  readonly type: string;
+  readonly sequence: number;
+  readonly payload: Record<string, unknown>;
+  readonly timestamp?: string;
+  readonly causationId?: string;
+}
+
+export interface ReadEvent {
+  readonly type?: unknown;
+  readonly sequence?: unknown;
+  readonly payload?: unknown;
+  readonly eventId?: unknown;
+  readonly timestamp?: unknown;
+  readonly causationId?: unknown;
+}
+
+export type Seeded =
+  | { readonly ok: true; readonly runId: string }
+  | { readonly ok: false; readonly kind: 'blocked' | 'inapplicable' | 'skipped'; readonly reason: string };
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+/** The gate every era-2 scenario applies before touching the seam. */
+export function era2Gate(doc: Record<string, unknown> | null): Seeded | null {
+  if (!doc) return { ok: false, kind: 'blocked', reason: 'discovery unreachable' };
+  if (!seamsProfileAdvertised(doc)) {
+    return { ok: false, kind: 'blocked', reason: `seams profile not advertised (conformance.seamsProfile !== openwop-conformance-seams-v2) — an era-2 log can only be seeded through ${SEED_PATH}` };
+  }
+  return null;
+}
+
+/** Seed an era-2 log in v1 vocabulary; the reason names the seam when it is absent. */
+export async function seedEra2Log(events: readonly SeedEvent[], status: 'completed' | 'running' | 'paused' = 'completed'): Promise<Seeded> {
+  const res = await http(() => driver.post(SEED_PATH_V1, { eventLogSchemaVersion: 2, status, events }));
+  if (res === null) return { ok: false, kind: 'blocked', reason: `${SEED_PATH} unreachable (fetch failed)` };
+  if (res.status === 404 || res.status === 403 || res.status === 405) {
+    return { ok: false, kind: 'blocked', reason: `no seam seeds an era-2 event log — ${SEED_PATH} answered ${res.status} (uncatalogued in api/seams-v2.yaml; the reader rule is seam-gated, RFC 0176 falsifiability §A.3)` };
+  }
+  const runId = (res.json as { runId?: unknown } | undefined)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') {
+    return { ok: false, kind: 'blocked', reason: `${SEED_PATH} answered ${res.status} ${readErrorCode(res.json) ?? ''} without a 201 { runId } — the seed contract is not honoured`.trim() };
+  }
+  return { ok: true, runId };
+}
+
+/** `GET /runs/{runId}/events/poll` under OpenWOP-Version: 2.0 (the driver adds the header). */
+export async function pollEvents(runId: string, query = ''): Promise<OpenWOPResponse | null> {
+  return http(() => driver.get(`/runs/${encodeURIComponent(runId)}/events/poll?timeout=1${query}`));
+}
+
+export function eventsOf(body: unknown): ReadEvent[] {
+  const events = (body as { events?: unknown } | undefined)?.events;
+  return Array.isArray(events) ? (events as ReadEvent[]) : [];
+}
+
+/**
+ * `GET /runs/{runId}/events?streamMode=debug` under OpenWOP-Version: 2.0 —
+ * `debug` admits every event (events.md §Stream modes), so a `version.pinned`
+ * or a vendor row is visible. lib/sse.ts sends no version header, and a
+ * header-less request selects the v1 representation (RFC 0172 §A.3), so the
+ * stream is read here with the header the scenario is speaking.
+ */
+export async function streamEvents(runId: string, timeoutMs = 8_000): Promise<{ status: number; events: ReadEvent[] } | null> {
+  const env = loadEnv();
+  const ctl = new AbortController();
+  const timer = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${env.baseUrl}/runs/${encodeURIComponent(runId)}/events?streamMode=debug`, {
+      headers: { Accept: 'text/event-stream', Authorization: `Bearer ${env.apiKey}`, 'OpenWOP-Version': '2.0' },
+      signal: ctl.signal,
+    });
+    if (res.status !== 200 || res.body === null) return { status: res.status, events: [] };
+    let text = '';
+    try { text = await res.text(); } catch (err) { if ((err as { name?: string }).name !== 'AbortError') throw err; }
+    const events: ReadEvent[] = [];
+    for (const frame of text.split(/\r?\n\r?\n/)) {
+      const data = frame.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).replace(/^ /, '')).join('\n');
+      if (data.length === 0) continue;
+      try {
+        const parsed = JSON.parse(data) as unknown;
+        for (const e of Array.isArray(parsed) ? parsed : [parsed]) if (e && typeof e === 'object') events.push(e as ReadEvent);
+      } catch { /* a keep-alive or a non-JSON frame */ }
+    }
+    return { status: res.status, events };
+  } catch (err) {
+    if ((err as { name?: string }).name === 'AbortError') return { status: 0, events: [] };
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** `POST /runs/{runId}:fork`; null when the request could not be made. */
+export async function forkRun(runId: string, body: Record<string, unknown>): Promise<OpenWOPResponse | null> {
+  return http(() => driver.post(`/runs/${encodeURIComponent(runId)}:fork`, body));
+}
+
+/**
+ * The v1→v2 rows the seeds use, taken from `spec/v2/event-codemap.json` when the
+ * corpus is present (the published tarball ships the codemap beside the
+ * schemas; a layout without it falls back to the same rows spelled here, which
+ * is what the codemap says for them — `counts.renamed: 36`).
+ */
+const FALLBACK: ReadonlyArray<readonly [string, string]> = [
+  ['run.started', 'run.started'],
+  ['run.completed', 'run.completed'],
+  ['run.cancelled', 'run.cancelled'],
+  ['version.pinned', 'version.pinned'],
+  ['agent.toolCalled', 'agent.tool-called'],
+  ['agent.toolReturned', 'agent.tool-returned'],
+  ['run.resuming', 'run.resume-started'],
+];
+
+let codemap: Map<string, string> | undefined;
+export function codemapV1toV2(): Map<string, string> {
+  if (codemap) return codemap;
+  const m = new Map<string, string>(FALLBACK);
+  const candidate = V1_DIR ? join(V1_DIR, '..', 'v2', 'event-codemap.json') : null;
+  if (candidate && existsSync(candidate)) {
+    try {
+      const doc = JSON.parse(readFileSync(candidate, 'utf8')) as { rows?: Array<{ v1?: unknown; v2?: unknown }> };
+      for (const r of doc.rows ?? []) if (typeof r.v1 === 'string' && typeof r.v2 === 'string') m.set(r.v1, r.v2);
+    } catch { /* the fallback rows stand */ }
+  }
+  codemap = m;
+  return m;
+}
+
+/** A minimal era-2 log in v1 vocabulary: two renamed rows between run.started and run.completed. */
+export function v1FixtureLog(workflowId = 'conformance-noop'): SeedEvent[] {
+  const t0 = Date.parse('2026-01-15T10:00:00.000Z');
+  const ts = (i: number) => new Date(t0 + i * 1000).toISOString();
+  return [
+    { type: 'run.started', sequence: 0, payload: { workflowId }, timestamp: ts(0) },
+    { type: 'agent.toolCalled', sequence: 1, payload: { agentId: 'conformance-agent', toolName: 'echo', callId: 'call-0001' }, timestamp: ts(1) },
+    { type: 'agent.toolReturned', sequence: 2, payload: { agentId: 'conformance-agent', toolName: 'echo', callId: 'call-0001', status: 'ok' }, timestamp: ts(2) },
+    { type: 'run.completed', sequence: 3, payload: { durationMs: 3000 }, timestamp: ts(3) },
+  ];
+}
+
+/** The observable part of an event for RFC 0041 §C byte-equivalence: type, sequence, payload (clock fields and minted ids excluded). */
+export function observable(e: ReadEvent): string {
+  return JSON.stringify({ type: e.type, sequence: e.sequence, payload: canonical(e.payload) });
+}
+
+function canonical(v: unknown): unknown {
+  if (Array.isArray(v)) return v.map(canonical);
+  if (v !== null && typeof v === 'object') {
+    return Object.fromEntries(Object.keys(v as Record<string, unknown>).sort().map((k) => [k, canonical((v as Record<string, unknown>)[k])]));
+  }
+  return v;
+}

package/src/lib/paths.ts

@@ -36,6 +36,7 @@
 
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 import { dirname, join, resolve as pathResolve } from 'node:path';
 
 // `dirname(fileURLToPath(import.meta.url))` for an ESM module compiled or
@@ -77,7 +78,22 @@ interface ResolvedLayout {
   readonly layout: 'env-override' | 'repo' | 'published';
 }
 
-function resolveFromRoot(root: string, layout: ResolvedLayout['layout']): ResolvedLayout {
+/**
+ * Suite 2.0.0 (RFC 0168 §D.2): in the published layout the CONTRACT (api/ and
+ * schemas/) is the `@openwop/spec-artifacts` peer package, not files vendored
+ * into this tarball. Resolve its root through Node's resolver from this package
+ * so the host's installed peer is what the suite validates against.
+ */
+function resolvePeerRoot(): string | null {
+  try {
+    const req = createRequire(join(PKG_ROOT, 'package.json'));
+    return dirname(req.resolve('@openwop/spec-artifacts/package.json'));
+  } catch {
+    return null;
+  }
+}
+
+function resolveFromRoot(root: string, layout: ResolvedLayout['layout'], contractRoot: string = root): ResolvedLayout {
   // Two on-disk shapes for the layout root:
   //   - Repo: <root>/schemas, <root>/api, <root>/conformance/fixtures,
   //           <root>/conformance/{fixtures.md,coverage.md}, <root>/spec/v1/*.md
@@ -86,8 +102,8 @@ function resolveFromRoot(root: string, layout: ResolvedLayout['layout']): Resolv
   //           <root>/fixtures.md (when bundled), no spec/v1.
   // Probe by checking whether `schemas/` lives at the conformance pkg root
   // (vendored) vs one level up (repo).
-  const schemasDir = join(root, 'schemas');
-  const apiDir = join(root, 'api');
+  const schemasDir = join(contractRoot, 'schemas');
+  const apiDir = join(contractRoot, 'api');
   const repoFixturesDir = join(root, 'conformance', 'fixtures');
   const vendoredFixturesDir = join(root, 'fixtures');
   const fixturesDir = existsSync(repoFixturesDir) ? repoFixturesDir : vendoredFixturesDir;
@@ -166,7 +182,13 @@ function resolveLayout(): ResolvedLayout {
   if (parentHasSchemas) {
     return resolveFromRoot(parent, 'repo');
   }
+  const peer = resolvePeerRoot();
+  if (peer) {
+    return resolveFromRoot(PKG_ROOT, 'published', peer);
+  }
   if (pkgHasSchemas) {
+    // A pre-2.0 tarball layout (schemas vendored in-package); kept so an old
+    // layout still resolves, but the 2.x stamp check refuses to run without the peer.
     return resolveFromRoot(PKG_ROOT, 'published');
   }
   // Neither — return the published-style resolution rooted at PKG_ROOT

package/src/lib/requirement-ids.ts

@@ -24,6 +24,20 @@
  * `~3`, … (vitest allows duplicate titles; the ledger does not allow duplicate
  * ids). A scenario MAY override the derived id for the current test with
  * `req()` when it wants a hand-authored, registry-listed id.
+ *
+ * requireExplicitIds (suite 2.0.0, RFC 0168 §A.1): from 2.0.0 `req(id, section,
+ * requirement)` is the ONLY assertion-message form in `src/scenarios` and
+ * `src/coherence` — `driver.describe(section, requirement)` is gone from every
+ * scenario, and `scripts/check-req-only.mjs` (root) fails the gate when a
+ * scenario reintroduces it, when an `expect` carries a bare string message,
+ * when an `it` body returns without `softSkip` / `seamAbsent`, or when two
+ * `it`s in one file share an explicit id. Every `it` therefore names the
+ * requirement it witnesses on the wire; the title-derived allocator below is
+ * the fallback for an `it` that makes no cited assertion at all. The ids the
+ * 2.0.0 sweep wrote are exactly the ids the allocator derived in 1.x (same
+ * stem + slug + `~n` order), so no bundle id changed at the cut-over; an `it`
+ * with an interpolated title carries a hand-minted id from the static parts of
+ * its title, unique within the file.
  */
 
 export const IT_ID_PREFIX = 'openwop.it.';
@@ -60,6 +74,27 @@ export function scenarioFileOfItId(requirementId: string): string | null {
   return `${rest.slice(0, dot)}.test.ts`;
 }
 
+/**
+ * Every FILE-derived id back to its file: the per-test `openwop.it.<stem>.<title>`
+ * plus the per-file rows the ledger also carries, `openwop.scenario.<stem>` and
+ * `openwop.floor.<stem>`. Gate rows (`openwop.profile.*`, `openwop.family.*`),
+ * explicit `req()` ids and the `openwop.floor.any.<prefix>` GROUP name no single
+ * file and return null. A caller that understood only `it` ids read a per-file
+ * row as an un-cited requirement and demanded a `req()` literal that, by
+ * construction, never exists.
+ */
+export function scenarioFileOfId(requirementId: string): string | null {
+  const it = scenarioFileOfItId(requirementId);
+  if (it !== null) return it;
+  for (const prefix of ['openwop.scenario.', 'openwop.floor.']) {
+    if (!requirementId.startsWith(prefix)) continue;
+    const rest = requirementId.slice(prefix.length);
+    if (rest.length === 0 || rest.startsWith('any.')) return null;
+    return `${rest}.test.ts`;
+  }
+  return null;
+}
+
 /**
  * Collision suffixing: the first occurrence keeps the bare id, later ones get
  * `~2`, `~3`, … Keyed per file so a worker running many files never crosses
@@ -70,7 +105,11 @@ export class ItIdAllocator {
 
   allocate(scenarioFile: string, title: string): string {
     const base = itRequirementId(scenarioFile, title);
-    const n = (this.seen.get(base) ?? 0) + 1;
+    let n = (this.seen.get(base) ?? 0) + 1;
+    // An id a sibling `it` already claimed through `req()` never reached this
+    // allocator, so a same-titled `it` that cites nothing must skip past it —
+    // otherwise the first explicit `exists` and the derived `exists` collide.
+    while (claimedExplicit.has(n === 1 ? base : `${base}~${n}`)) n++;
     this.seen.set(base, n);
     return n === 1 ? base : `${base}~${n}`;
   }
@@ -85,22 +124,33 @@ export class ItIdAllocator {
 // ---------------------------------------------------------------------------
 
 let explicitId: string | null = null;
+/** Every id handed to `req()` in this worker — consulted by `ItIdAllocator`. */
+const claimedExplicit = new Set<string>();
 
 /**
  * Attach a hand-authored requirement id to the CURRENT test. The per-`it`
  * ledger row for this test is recorded under `id` instead of the derived
- * title id. Returns the usual `driver.describe`-style message so the call
- * doubles as the assertion message:
+ * title id. Returns the SAME message shape `driver.describe` returns —
+ * `[<impl>@<version>] <section>: <requirement>` — so a failure still names
+ * the implementation under test:
  *
  *   expect(x, req('openwop.auth.subject-link.leaver-deny', 'auth-profiles.md §Subject linking', 'deactivation MUST deny')).toBe(true)
  *
+ * The implementation label is read straight from `OPENWOP_IMPLEMENTATION_NAME`
+ * / `OPENWOP_IMPLEMENTATION_VERSION` with the defaults `env.ts` uses (`unknown`)
+ * rather than through `loadEnv()`, so a suite self-test can call `req()`
+ * without `OPENWOP_BASE_URL` set.
+ *
  * The id MUST be listed in `conformance/requirements.json` (the generator
  * collects `req(` first-argument literals); an unlisted id fails the registry
  * check, so a hand id cannot drift from the registry silently.
  */
 export function req(id: string, specSection: string, requirement: string): string {
   explicitId = id;
-  return `${specSection}: ${requirement}`;
+  claimedExplicit.add(id);
+  const impl = process.env['OPENWOP_IMPLEMENTATION_NAME']?.trim() ?? 'unknown';
+  const version = process.env['OPENWOP_IMPLEMENTATION_VERSION']?.trim() ?? 'unknown';
+  return `[${impl}@${version}] ${specSection}: ${requirement}`;
 }
 
 /** setup.ts reads and clears the override after each test. */

package/src/lib/requirement-ledger.ts

@@ -61,6 +61,11 @@ export interface LedgerEntry {
    *  program exists to make visible; the runner treats it as unclassified for
    *  a claimed profile's floor. */
   readonly assertionCount?: number;
+  /** The scenario file that recorded it. An explicit `req()` id carries no file
+   *  in its own text, so without this the `--certify` runner cannot attribute
+   *  the row to a file and drops it — which is how every explicit requirement id
+   *  went missing from bundle v3 while the per-`it` ids came through. */
+  readonly scenarioFile?: string;
 }
 
 const ledger = new Map<string, LedgerEntry>();
@@ -82,7 +87,7 @@ export function recordRequirement(
   requirementId: string,
   disposition: Disposition,
   detail?: string,
-  extras?: { assertionCount?: number },
+  extras?: { assertionCount?: number; scenarioFile?: string },
 ): void {
   const prior = ledger.get(requirementId);
   if (prior !== undefined && prior.disposition !== disposition) {
@@ -102,6 +107,7 @@ export function recordRequirement(
     disposition,
     ...(detail === undefined ? {} : { detail }),
     ...(extras?.assertionCount === undefined ? {} : { assertionCount: extras.assertionCount }),
+    ...(extras?.scenarioFile === undefined ? {} : { scenarioFile: extras.scenarioFile }),
   };
   ledger.set(requirementId, entry);
   journal.push(entry);

package/src/lib/scenario-disposition.ts

@@ -124,6 +124,7 @@ export function resolveFileRecord(
   // them. See lib/spec-coherence.ts for why not a new disposition value.
   if (
     specCoherenceFile !== undefined
+    && process.env.OPENWOP_CORPUS_GATE !== '1' // suite 2.0.0: under the corpus gate the coherence scenario IS the subject
     && SPEC_COHERENCE_SCENARIOS.has(specCoherenceFile)
     && !states.includes('fail')
     && assertionCount === 0
@@ -292,7 +293,11 @@ export function deriveRequirementDispositions(
   // them. This is the granularity RFC 0148 §A describes and the G8 fix.
   const emitted = new Set(rows.map((r) => r.requirementId));
   for (const e of [...ledger].sort((a, b) => a.requirementId.localeCompare(b.requirementId))) {
-    const file = scenarioFileOfItId(e.requirementId);
+    // Prefer the file the entry recorded: an explicit `req()` id
+    // (`openwop.requirement.…`) is authored, not file-derived, so deriving a
+    // file from the id alone returned null and the row was dropped — every
+    // explicit requirement id was missing from bundle v3 for that reason.
+    const file = e.scenarioFile ?? scenarioFileOfItId(e.requirementId);
     // Attribute only to files this run reported on: a worker's ledger can carry
     // rows from files outside the certified set (the suite's own lib tests, or
     // a filtered run), and those are not evidence about the host.