@openwop/openwop-conformance 2.0.0-rc.0 → 2.0.0-rc.2

package/src/scenarios/v2-payload-registry-closed.test.ts

@@ -0,0 +1,110 @@
+/**
+ * v2 — `payload-registry-closed` (suite 2.0.0; RFC 0171 §A.4;
+ * `spec/v2/core/events.md` §"Payloads").
+ *
+ * Witness class: witnessable — unaided. `schemas/v2/run-event-payloads.schema.json`
+ * holds one closed `$defs` entry per payload and the NORMATIVE `_typeIndex`
+ * from v2 type to `$defs` key. A host MUST emit, for every registered type, a
+ * payload that validates against the entry `_typeIndex` names; a registered
+ * type with no index entry is a corpus defect and fails here too. Vendor
+ * events have no registry entry and are not checked. The payload validator is
+ * built locally (a `$ref` into the payload registry's `$defs`), because
+ * `v2Validator` resolves whole schema files only.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery } from '../lib/v2.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/events.md §Payloads';
+const NOOP_WORKFLOW_ID = 'conformance-noop';
+const PAYLOADS_ID = 'https://openwop.dev/spec/v2/run-event-payloads.schema.json';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+const TIMEOUT_MS = Number(process.env['OPENWOP_LIFECYCLE_TIMEOUT_MS'] ?? 10_000);
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+let ajv: Ajv2020 | undefined;
+function registry(): Ajv2020 {
+  if (ajv) return ajv;
+  ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const walk = (d: string): string[] => readdirSync(d).flatMap((n) => { const p = join(d, n); return statSync(p).isDirectory() ? walk(p) : p.endsWith('.schema.json') ? [p] : []; });
+  for (const p of walk(join(SCHEMAS_DIR, 'v2'))) { try { ajv.addSchema(JSON.parse(readFileSync(p, 'utf8')) as Record<string, unknown>); } catch { /* a duplicate $id is registered once */ } }
+  return ajv;
+}
+
+/** `_typeIndex.properties[type].$ref` → the `$defs` key. */
+function typeIndex(): Map<string, string> {
+  const schema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'v2', 'run-event-payloads.schema.json'), 'utf8')) as { _typeIndex?: { properties?: Record<string, { $ref?: string }> } };
+  const out = new Map<string, string>();
+  for (const [type, ref] of Object.entries(schema._typeIndex?.properties ?? {})) {
+    const key = ref.$ref?.replace(/^#\/\$defs\//, '');
+    if (key !== undefined) out.set(type, key);
+  }
+  return out;
+}
+
+function protocolTypes(): Set<string> {
+  const schema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'v2', 'run-event.schema.json'), 'utf8')) as { properties: { type: { oneOf: Array<{ enum?: string[] }> } } };
+  return new Set(schema.properties.type.oneOf.flatMap((b) => b.enum ?? []));
+}
+
+const defValidators = new Map<string, ReturnType<Ajv2020['compile']>>();
+function validatePayload(defKey: string, payload: unknown): { ok: boolean; errors: string } {
+  const a = registry();
+  let v = defValidators.get(defKey);
+  if (v === undefined) { v = a.compile({ $ref: `${PAYLOADS_ID}#/$defs/${defKey}` }); defValidators.set(defKey, v); }
+  return { ok: v(payload) as boolean, errors: a.errorsText(v.errors, { separator: '; ' }) };
+}
+
+async function terminalEvents(): Promise<unknown[] | { reason: string }> {
+  if (!(await discovery())) return { reason: 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0' };
+  const created = await http(() => driver.post('/runs', { workflowId: NOOP_WORKFLOW_ID }));
+  if (created === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (created.json as { runId?: unknown } | undefined)?.runId;
+  if (created.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs {workflowId: ${NOOP_WORKFLOW_ID}} answered ${created.status} ${readErrorCode(created.json) ?? ''} — the smallest valid create was refused (fixture not seeded?)`.trim() };
+  const deadline = Date.now() + TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const snap = await http(() => driver.get(`/runs/${encodeURIComponent(runId)}`));
+    if (snap !== null && TERMINAL.has(String((snap.json as { status?: unknown } | undefined)?.status))) break;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  const poll = await http(() => driver.get(`/runs/${encodeURIComponent(runId)}/events/poll?timeout=1`));
+  if (poll === null || poll.status !== 200) return { reason: `GET /runs/{runId}/events/poll answered ${poll?.status ?? 'no response'}` };
+  const events = (poll.json as { events?: unknown } | undefined)?.events;
+  if (!Array.isArray(events) || events.length === 0) return { reason: 'the poll returned no events for a run driven to terminal status — no payload is observable' };
+  return events;
+}
+
+describe('v2 payload-registry-closed (RFC 0171 §A.4)', () => {
+  it('every registered event carries a payload that validates against its _typeIndex entry', async () => {
+    const events = await terminalEvents();
+    if (!Array.isArray(events)) return softSkip('blocked', events.reason);
+    const index = typeIndex();
+    const enumSet = protocolTypes();
+    const registered = events.filter((ev) => enumSet.has(String((ev as { type?: unknown }).type)));
+    if (registered.length === 0) return softSkip('blocked', 'the run emitted only vendor events — no registered payload to check');
+    for (const ev of registered) {
+      const type = String((ev as { type?: unknown }).type);
+      const key = index.get(type);
+      expect(key, req('openwop.requirement.0171.payload-registry-closed', DOC, `_typeIndex is normative: registered type ${type} MUST map to a $defs entry in run-event-payloads.schema.json`)).toBeDefined();
+      if (key === undefined) continue;
+      const r = validatePayload(key, (ev as { payload?: unknown }).payload);
+      expect(r.ok, req('openwop.requirement.0171.payload-registry-closed', DOC, `the payload of ${type} MUST validate against $defs/${key} (every entry additionalProperties: false) (${r.errors})`)).toBe(true);
+    }
+  });
+});

package/src/scenarios/v2-peer-dependency-declared.test.ts

@@ -0,0 +1,132 @@
+/**
+ * v2-peer-dependency-declared — RFC 0177 §B.1/§B.2; `spec/v2/core/packs.md`
+ * §"Peer-dependency identifiers" and §"The alias table".
+ *
+ * Suite 2.0.0, target major 2. A `peerDependencies` key MUST be a root key of
+ * `spec/v2/declaration.json`; a host MUST refuse a key the declaration file does
+ * not name with `pack_peer_dependency_undefined` (400). During the overlap a
+ * host MAY resolve a v1 grammar through the generated alias table
+ * (`spec/v2/peer-dependency-aliases.json`, e.g. `host.fs → fs`).
+ *
+ *   1. `peerDependencies: { "host.nonexistent": "required" }` → refused,
+ *      pack_peer_dependency_undefined.
+ *   2. an alias row whose family the host advertises (`host.fs` when `fs` is
+ *      advertised, else the first facet-less row with an advertised family)
+ *      installs through the overlap. §B.2 is a MAY, so a host that refuses the
+ *      alias with pack_peer_dependency_undefined records `skipped`, not a
+ *      failure; any other refusal fails.
+ *
+ * Both legs install through the seams-profile publish seam
+ * (`/conformance/seams/packs-test/…`, RFC 0168 §C.2). Gated on `packs` + the
+ * seams profile.
+ *
+ * @see RFCS/0177-v2-registry-packs-and-extension-tail.md §B.1, §B.2
+ * @see spec/v2/core/packs.md §"Peer-dependency identifiers", §"The alias table"
+ * @see spec/v2/peer-dependency-aliases.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { gzipSync } from 'node:zlib';
+import { driver } from '../lib/driver.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip, type SoftSkipKind } from '../lib/soft-skip.js';
+import { seamsProfileAdvertised, targetMajor } from '../lib/seams.js';
+import { v2Discovery, gateFamily, familyAdvertised } from '../lib/v2.js';
+
+const SECTION = 'packs.md §"Peer-dependency identifiers" (RFC 0177 §B.1)';
+const ALIASES = join(SCHEMAS_DIR, '..', 'spec', 'v2', 'peer-dependency-aliases.json');
+
+interface AliasRow { alias: string; family: string; facets?: string[] }
+
+function tarEntry(name: string, data: Buffer): Buffer {
+  const h = Buffer.alloc(512, 0);
+  h.write(name, 0, 100, 'utf8');
+  h.write('0000644\0', 100, 8, 'utf8');
+  h.write('0000000\0', 108, 8, 'utf8');
+  h.write('0000000\0', 116, 8, 'utf8');
+  h.write(`${data.length.toString(8).padStart(11, '0')}\0`, 124, 12, 'utf8');
+  h.write('00000000000\0', 136, 12, 'utf8');
+  h.write('        ', 148, 8, 'utf8');
+  h.write('0', 156, 1, 'utf8');
+  h.write('ustar\0', 257, 6, 'utf8');
+  h.write('00', 263, 2, 'utf8');
+  let sum = 0;
+  for (const b of h) sum += b;
+  h.write(`${sum.toString(8).padStart(6, '0')}\0 `, 148, 8, 'utf8');
+  const pad = (512 - (data.length % 512)) % 512;
+  return Buffer.concat([h, data, Buffer.alloc(pad, 0)]);
+}
+function packTarball(files: Record<string, string>): Buffer {
+  return gzipSync(Buffer.concat([...Object.entries(files).map(([n, c]) => tarEntry(n, Buffer.from(c, 'utf8'))), Buffer.alloc(1024, 0)]));
+}
+const ENTRY = 'export default { execute: async (input) => input };\n';
+function freshName(slug: string): string {
+  return `core.openwop.v2-${slug}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+function nodePack(name: string, peerDependencies: Record<string, string>): Record<string, unknown> {
+  return {
+    name,
+    version: '1.0.0',
+    kind: 'node',
+    engines: { openwop: '>=2.0.0 <3.0.0' },
+    runtime: { language: 'javascript', entry: 'index.mjs', format: 'esm' },
+    peerDependencies,
+    nodes: [{ typeId: `${name}.echo`, version: '1.0.0', category: 'data', role: 'pure' }],
+  };
+}
+async function publish(manifest: Record<string, unknown>) {
+  const name = manifest['name'] as string;
+  const version = manifest['version'] as string;
+  const body = packTarball({ 'pack.json': JSON.stringify(manifest, null, 2), 'index.mjs': ENTRY });
+  return driver.put(`/v1/packs-test/${encodeURIComponent(name)}/-/${encodeURIComponent(version)}.tgz`, body, {
+    headers: { 'Content-Type': 'application/octet-stream' },
+  });
+}
+async function preflight(): Promise<{ kind: SoftSkipKind; reason: string } | null> {
+  if (targetMajor() !== 2) return { kind: 'inapplicable', reason: 'suite 2.0.0 v2 scenario: OPENWOP_TARGET_MAJOR is not 2' };
+  let doc: Record<string, unknown> | null;
+  try {
+    doc = await v2Discovery();
+  } catch {
+    doc = null;
+  }
+  if (!doc) return { kind: 'blocked', reason: 'discovery unreachable — /.well-known/openwop (OpenWOP-Version: 2.0) did not answer 200 JSON' };
+  if (!(await gateFamily('packs'))) return { kind: 'inapplicable', reason: 'v2 discovery does not advertise the packs family (RFC 0169 §A.2)' };
+  if (!seamsProfileAdvertised(doc)) return { kind: 'blocked', reason: 'host does not advertise conformance.seamsProfile: openwop-conformance-seams-v2 — the packs-test publish seam is the only install path the suite can drive (RFC 0168 §C.1)' };
+  return null;
+}
+
+describe('v2-peer-dependency-declared (RFC 0177 §B.1/§B.2)', () => {
+  it('a peerDependencies key the declaration file does not name is refused with pack_peer_dependency_undefined', async () => {
+    const skip = await preflight();
+    if (skip) return softSkip(skip.kind, skip.reason);
+    const res = await publish(nodePack(freshName('peer-undefined'), { 'host.nonexistent': 'required' }));
+    if (res.status === 404) return softSkip('blocked', 'packs-test publish seam answered 404 — seams profile advertised but the seam is not mounted');
+    expect(res.status, req('openwop.requirement.0177.peer-dependency-declared.undefined-key', SECTION, 'a key absent from spec/v2/declaration.json MUST be refused with 400 pack_peer_dependency_undefined')).toBe(400);
+    expect(readErrorCode(res.json), req('openwop.requirement.0177.peer-dependency-declared.undefined-key', SECTION, 'the refusal code MUST be pack_peer_dependency_undefined')).toBe('pack_peer_dependency_undefined');
+  });
+
+  it('an alias-table row (host.fs → fs) resolves through the overlap and the pack installs', async () => {
+    const skip = await preflight();
+    if (skip) return softSkip(skip.kind, skip.reason);
+    if (!existsSync(ALIASES)) return softSkip('blocked', 'spec/v2/peer-dependency-aliases.json is not present in this layout — the alias row cannot be chosen');
+    const rows = (JSON.parse(readFileSync(ALIASES, 'utf8')) as { rows: AliasRow[] }).rows.filter((r) => !r.facets || r.facets.length === 0);
+    let chosen: AliasRow | null = null;
+    const fs = rows.find((r) => r.alias === 'host.fs');
+    if (fs && (await familyAdvertised(fs.family))) chosen = fs;
+    for (const r of rows) {
+      if (chosen) break;
+      if (await familyAdvertised(r.family)) chosen = r;
+    }
+    if (!chosen) return softSkip('inapplicable', 'no facet-less alias row names a family this host advertises — the overlap alias cannot be exercised');
+    const res = await publish(nodePack(freshName('peer-alias'), { [chosen.alias]: 'required' }));
+    if (res.status === 404) return softSkip('blocked', 'packs-test publish seam answered 404 — seams profile advertised but the seam is not mounted');
+    const code = readErrorCode(res.json);
+    if (res.status === 400 && code === 'pack_peer_dependency_undefined') return softSkip('skipped', `host does not resolve the overlap alias ${chosen.alias} (RFC 0177 §B.2 is a MAY during the overlap; MUST NOT after v1 end-of-support)`);
+    expect([200, 201].includes(res.status), req('openwop.requirement.0177.peer-dependency-declared.alias-overlap', 'packs.md §"The alias table" (RFC 0177 §B.2)', `alias ${chosen.alias} → ${chosen.family} (advertised) MUST install through the overlap or be refused only with pack_peer_dependency_undefined (got ${res.status} ${code ?? ''})`)).toBe(true);
+  });
+});

package/src/scenarios/v2-pinned-run-disposition.test.ts

@@ -0,0 +1,124 @@
+/**
+ * RFC 0176 §B.1 — `pinned-run-disposition` (suite 2.0.0, target major 2;
+ * seam-gated on `openwop-conformance-seams-v2`).
+ *
+ * A non-terminal run a v2 host inherits carries `version.pinned` events naming
+ * change ids. The host MUST continue it or cancel it, never follow a pin
+ * silently: every pinned change id still implemented ⇒ the run continues under
+ * the reader rule with the pin honoured verbatim (`version.pinned` is never
+ * rewritten); any pinned change id no longer implemented ⇒ `run.cancelled`
+ * with reason `v1_pin_unsupported` and `cancelledBy: "v2-cutover"`
+ * (`spec/v2/core/persistence.md` §Runs pinned to v1; migration rows C9.4/C9.5).
+ *
+ * Legs:
+ *   1. an era-2 running log seeded through the event-log seed seam
+ *      (lib/era2-seed.ts) whose `version.pinned` names a change id no host
+ *      implements reads back `cancelled` with the named reason and actor, and
+ *      the pin row survives untouched;
+ *   2. a pin naming a change id the host implements continues — no normative
+ *      surface lists implemented change ids, so the id is the operator opt-in
+ *      `OPENWOP_TEST_IMPLEMENTED_CHANGE_ID`; absent, the leg records `skipped`.
+ *
+ * @see spec/v2/core/persistence.md §Runs pinned to v1
+ * @see schemas/v2/run-event-payloads.schema.json runCancelled
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { era2Gate, eventsOf, pollEvents, seedEra2Log, type ReadEvent, type SeedEvent } from '../lib/era2-seed.js';
+
+const DOC = 'spec/v2/core/persistence.md §Runs pinned to v1';
+const REASON = 'v1_pin_unsupported';
+const CANCELLED_BY = 'v2-cutover';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+const SETTLE_MS = Number(process.env['OPENWOP_LIFECYCLE_TIMEOUT_MS'] ?? 10_000);
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+function pinnedLog(changeId: string): SeedEvent[] {
+  const t0 = Date.parse('2026-01-15T12:00:00.000Z');
+  const ts = (i: number) => new Date(t0 + i * 1000).toISOString();
+  return [
+    { type: 'run.started', sequence: 0, payload: { workflowId: 'conformance-noop' }, timestamp: ts(0) },
+    { type: 'version.pinned', sequence: 1, payload: { changeId, version: 1 }, timestamp: ts(1) },
+  ];
+}
+
+type Read = { readonly ok: true; readonly status: string; readonly events: ReadEvent[] } | { readonly ok: false; readonly kind: 'blocked' | 'inapplicable' | 'skipped'; readonly reason: string };
+
+/** Seed, then read the snapshot status and the log once the host has decided (the disposition is applied at first v2 read or at the cut). */
+async function seedAndRead(changeId: string): Promise<Read> {
+  const seeded = await seedEra2Log(pinnedLog(changeId), 'running');
+  if (!seeded.ok) return { ok: false, kind: seeded.kind, reason: seeded.reason };
+  const deadline = Date.now() + SETTLE_MS;
+  let status = '';
+  for (;;) {
+    const snap = await http(() => driver.get(`/runs/${encodeURIComponent(seeded.runId)}`));
+    if (snap === null || snap.status !== 200) return { ok: false, kind: 'blocked', reason: `GET /runs/{runId} answered ${snap?.status ?? 'no response'} for the seeded run` };
+    status = String((snap.json as { status?: unknown } | undefined)?.status ?? '');
+    if (TERMINAL.has(status) || Date.now() > deadline) break;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  const poll = await pollEvents(seeded.runId);
+  if (poll === null || poll.status !== 200) return { ok: false, kind: 'blocked', reason: `GET /runs/{runId}/events/poll answered ${poll?.status ?? 'no response'} for the seeded run` };
+  return { ok: true, status, events: eventsOf(poll.json) };
+}
+
+describe('RFC 0176 §B.1 — pinned-run-disposition (seam-gated)', () => {
+  it('a pin naming a change id the host does not implement is cancelled with v1_pin_unsupported / v2-cutover', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const gate = era2Gate(doc);
+    if (gate !== null && !gate.ok) return softSkip(gate.kind, gate.reason);
+    const changeId = `conformance-unknown-change-${Date.now().toString(36)}`;
+    const r = await seedAndRead(changeId);
+    if (!r.ok) return softSkip(r.kind, r.reason);
+    expect(
+      r.status,
+      req('openwop.requirement.0176.pinned-run-disposition.cancelled', DOC, `a run pinned to a change id the host no longer implements MUST be cancelled, never followed silently — snapshot status is ${r.status}`),
+    ).toBe('cancelled');
+    const cancelled = r.events.filter((e) => e.type === 'run.cancelled');
+    expect(cancelled.length, req('openwop.requirement.0176.pinned-run-disposition.cancelled', DOC, 'the cancellation MUST be an event on the run\'s own log (run.cancelled), not a silent status flip')).toBe(1);
+    const payload = (cancelled[0]?.payload ?? {}) as { reason?: unknown; cancelledBy?: unknown };
+    expect(payload.reason, req('openwop.requirement.0176.pinned-run-disposition.cancelled', 'run-event-payloads.schema.json runCancelled.reason', `reason MUST be the registered ${REASON}`)).toBe(REASON);
+    expect(payload.cancelledBy, req('openwop.requirement.0176.pinned-run-disposition.cancelled', 'run-event-payloads.schema.json runCancelled.cancelledBy', `cancelledBy MUST be ${CANCELLED_BY}`)).toBe(CANCELLED_BY);
+    const pin = r.events.find((e) => e.type === 'version.pinned');
+    expect(pin, req('openwop.requirement.0176.pinned-run-disposition.cancelled', DOC, 'the version.pinned row MUST survive the cancellation — the log is preserved (adversarial review 4)')).toBeDefined();
+    expect(
+      (pin?.payload as { changeId?: unknown } | undefined)?.changeId,
+      req('openwop.requirement.0176.pinned-run-disposition.cancelled', DOC, 'version.pinned is never rewritten: the pin still names the change id it was seeded with'),
+    ).toBe(changeId);
+  });
+
+  it('a pin naming a change id the host still implements continues under the reader rule with the pin verbatim', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const gate = era2Gate(doc);
+    if (gate !== null && !gate.ok) return softSkip(gate.kind, gate.reason);
+    const changeId = process.env['OPENWOP_TEST_IMPLEMENTED_CHANGE_ID']?.trim();
+    if (!changeId) return softSkip('skipped', 'opt-in not supplied: no normative surface lists the change ids a host implements, so the continue leg needs OPENWOP_TEST_IMPLEMENTED_CHANGE_ID naming one');
+    const r = await seedAndRead(changeId);
+    if (!r.ok) return softSkip(r.kind, r.reason);
+    expect(
+      r.status,
+      req('openwop.requirement.0176.pinned-run-disposition.continued', DOC, `a run whose every pinned change id is still implemented MUST continue under the adapter — it was cancelled (status ${r.status}) for a pin the operator says the host implements (${changeId})`),
+    ).not.toBe('cancelled');
+    expect(
+      r.events.filter((e) => e.type === 'run.cancelled' && (e.payload as { reason?: unknown } | undefined)?.reason === REASON),
+      req('openwop.requirement.0176.pinned-run-disposition.continued', DOC, `no run.cancelled { reason: ${REASON} } may appear on a run whose pin is implemented`),
+    ).toEqual([]);
+    const pin = r.events.find((e) => e.type === 'version.pinned');
+    expect(
+      (pin?.payload as { changeId?: unknown; version?: unknown } | undefined),
+      req('openwop.requirement.0176.pinned-run-disposition.continued', DOC, 'the pin is honoured verbatim — version.pinned reads back with the seeded changeId and version'),
+    ).toMatchObject({ changeId, version: 1 });
+  });
+});

package/src/scenarios/v2-poll-cursor-v2.test.ts

@@ -0,0 +1,114 @@
+/**
+ * v2 — `poll-cursor-v2` (suite 2.0.0; RFC 0171 §E.2;
+ * `spec/v2/core/events.md` §"Poll").
+ *
+ * Witness class: witnessable — unaided. `GET /runs/{runId}/events/poll`
+ * without a cursor returns from the first event (sequence 0);
+ * `?afterSequence=N` returns only events with `sequence > N`; a cursor past
+ * the end of the log returns `200` with an empty `events` array; the response
+ * is the closed `{ runId, events, lastSequence, status, isTerminal }`. The run
+ * is the `conformance-noop` fixture, awaited to a terminal status.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/events.md §Poll';
+const NOOP_WORKFLOW_ID = 'conformance-noop';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+const TIMEOUT_MS = Number(process.env['OPENWOP_LIFECYCLE_TIMEOUT_MS'] ?? 10_000);
+const SHAPE = ['runId', 'events', 'lastSequence', 'status', 'isTerminal'];
+
+interface Poll { readonly runId?: unknown; readonly events?: unknown; readonly lastSequence?: unknown; readonly status?: unknown; readonly isTerminal?: unknown }
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+async function terminalRun(): Promise<{ runId: string } | { reason: string }> {
+  if (!(await discovery())) return { reason: 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0' };
+  const created = await http(() => driver.post('/runs', { workflowId: NOOP_WORKFLOW_ID }));
+  if (created === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (created.json as { runId?: unknown } | undefined)?.runId;
+  if (created.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs {workflowId: ${NOOP_WORKFLOW_ID}} answered ${created.status} ${readErrorCode(created.json) ?? ''} — the smallest valid create was refused (fixture not seeded?)`.trim() };
+  const deadline = Date.now() + TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    const snap = await http(() => driver.get(`/runs/${encodeURIComponent(runId)}`));
+    if (snap !== null && TERMINAL.has(String((snap.json as { status?: unknown } | undefined)?.status))) break;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return { runId };
+}
+
+async function poll(runId: string, query: string): Promise<OpenWOPResponse | null> {
+  return http(() => driver.get(`/runs/${encodeURIComponent(runId)}/events/poll?timeout=1${query}`));
+}
+
+function sequences(body: unknown): number[] {
+  const events = (body as Poll | undefined)?.events;
+  return Array.isArray(events) ? events.map((e) => Number((e as { sequence?: unknown }).sequence)) : [];
+}
+
+describe('v2 poll-cursor-v2 (RFC 0171 §E.2)', () => {
+  it('the response is the closed { runId, events, lastSequence, status, isTerminal }', async () => {
+    const r = await terminalRun();
+    if ('reason' in r) return softSkip('blocked', r.reason);
+    const res = await poll(r.runId, '');
+    if (res === null) return softSkip('blocked', 'GET /runs/{runId}/events/poll unreachable (fetch failed)');
+    expect(res.status, req('openwop.requirement.0171.poll-cursor-v2.shape', DOC, 'pollRunEvents MUST answer 200')).toBe(200);
+    const body = res.json as Poll | undefined;
+    expect(Object.keys(body ?? {}).sort(), req('openwop.requirement.0171.poll-cursor-v2.shape', DOC, 'the poll response MUST be exactly { runId, events, lastSequence, status, isTerminal } (closed)')).toEqual([...SHAPE].sort());
+    expect(body?.runId, req('openwop.requirement.0171.poll-cursor-v2.shape', DOC, 'runId MUST echo the polled run')).toBe(r.runId);
+    expect(Array.isArray(body?.events), req('openwop.requirement.0171.poll-cursor-v2.shape', DOC, 'events MUST be an array')).toBe(true);
+    expect(Number.isInteger(body?.lastSequence) && (body?.lastSequence as number) >= -1, req('openwop.requirement.0171.poll-cursor-v2.shape', DOC, 'lastSequence is the highest sequence in the log (−1 when empty)')).toBe(true);
+    expect(typeof body?.status, req('openwop.requirement.0171.poll-cursor-v2.shape', DOC, 'status is the snapshot status')).toBe('string');
+    expect(typeof body?.isTerminal, req('openwop.requirement.0171.poll-cursor-v2.shape', DOC, 'isTerminal is a boolean')).toBe('boolean');
+    const seqs = sequences(body);
+    if (seqs.length > 0) expect(Math.max(...seqs), req('openwop.requirement.0171.poll-cursor-v2.shape', DOC, 'lastSequence MUST equal the highest sequence returned when the response carries the whole log')).toBeLessThanOrEqual(body?.lastSequence as number);
+  });
+
+  it('omitting the cursor returns from the first event (sequence 0)', async () => {
+    const r = await terminalRun();
+    if ('reason' in r) return softSkip('blocked', r.reason);
+    const res = await poll(r.runId, '');
+    if (res === null || res.status !== 200) return softSkip('blocked', `GET /runs/{runId}/events/poll answered ${res?.status ?? 'no response'}`);
+    const seqs = sequences(res.json);
+    if (seqs.length === 0) return softSkip('blocked', 'the poll returned no events for a run driven to terminal status — the first-event rule is unobservable');
+    expect(seqs[0], req('openwop.requirement.0171.poll-cursor-v2.from-first', DOC, 'omission of afterSequence means "from the first event": the first returned sequence MUST be 0')).toBe(0);
+  });
+
+  it('afterSequence=N returns only events with sequence > N', async () => {
+    const r = await terminalRun();
+    if ('reason' in r) return softSkip('blocked', r.reason);
+    const all = await poll(r.runId, '');
+    if (all === null || all.status !== 200) return softSkip('blocked', `GET /runs/{runId}/events/poll answered ${all?.status ?? 'no response'}`);
+    const seqs = sequences(all.json);
+    if (seqs.length === 0) return softSkip('blocked', 'the poll returned no events for a run driven to terminal status — the cursor rule is unobservable');
+    const n = seqs[0] as number;
+    const res = await poll(r.runId, `&afterSequence=${n}`);
+    if (res === null) return softSkip('blocked', 'GET /runs/{runId}/events/poll?afterSequence= unreachable (fetch failed)');
+    expect(res.status, req('openwop.requirement.0171.poll-cursor-v2.after-sequence', DOC, 'afterSequence is an integer ≥ 0 and MUST be accepted')).toBe(200);
+    const after = sequences(res.json);
+    expect(after.every((s) => s > n), req('openwop.requirement.0171.poll-cursor-v2.after-sequence', DOC, `every returned sequence MUST be > afterSequence (${n}); got [${after.join(', ')}]`)).toBe(true);
+    expect(after, req('openwop.requirement.0171.poll-cursor-v2.after-sequence', DOC, 'the cursor is exclusive and the log is not renumbered: afterSequence=first yields exactly the rest of the log')).toEqual(seqs.filter((s) => s > n));
+  });
+
+  it('a cursor past the end of the log returns 200 with an empty events array', async () => {
+    const r = await terminalRun();
+    if ('reason' in r) return softSkip('blocked', r.reason);
+    const all = await poll(r.runId, '');
+    if (all === null || all.status !== 200) return softSkip('blocked', `GET /runs/{runId}/events/poll answered ${all?.status ?? 'no response'}`);
+    const last = Number((all.json as Poll | undefined)?.lastSequence);
+    const res = await poll(r.runId, `&afterSequence=${(Number.isFinite(last) ? last : 0) + 1000}`);
+    if (res === null) return softSkip('blocked', 'GET /runs/{runId}/events/poll?afterSequence= unreachable (fetch failed)');
+    expect(res.status, req('openwop.requirement.0171.poll-cursor-v2.past-end', DOC, 'a cursor past the end of the log MUST return 200')).toBe(200);
+    expect((res.json as Poll | undefined)?.events, req('openwop.requirement.0171.poll-cursor-v2.past-end', DOC, 'a cursor past the end of the log MUST return an empty events array')).toEqual([]);
+  });
+});

package/src/scenarios/v2-preferred-version-default.test.ts

@@ -0,0 +1,83 @@
+/**
+ * v2 — `preferred-version-default` (suite 2.0.0; RFC 0172 §A.1, §A.3;
+ * `spec/v2/core/versioning.md` §1.1 "Advertisement", §1.3 "The request header";
+ * `spec/v2/core/capabilities.md` §1 "One well-known resource").
+ *
+ * Witness class: witnessable — unaided. `preferredVersion` MUST be a member of
+ * `protocolVersions[]`; a header-less request on an unversioned path MUST be
+ * served `preferredVersion`'s major, so a header-less `GET /.well-known/openwop`
+ * is the `preferredVersion` representation and its `OpenWOP-Version` response
+ * header names that major. The header-less fetch bypasses the driver (which
+ * stamps `OpenWOP-Version: 2.0` under target major 2).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { loadEnv } from '../lib/env.js';
+import { v2Discovery, v2Validator } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/versioning.md §1.1';
+const VERSION = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+async function headerless(): Promise<{ status: number; version: string | null; json: unknown } | null> {
+  try {
+    const res = await fetch(`${loadEnv().baseUrl}/.well-known/openwop`, { headers: { Accept: 'application/json' } });
+    const text = await res.text();
+    let json: unknown;
+    try { json = text.length > 0 ? JSON.parse(text) : undefined; } catch { json = undefined; }
+    return { status: res.status, version: res.headers.get('openwop-version'), json };
+  } catch {
+    return null;
+  }
+}
+
+describe('v2 preferred-version-default (RFC 0172 §A.1, §A.3)', () => {
+  it('preferredVersion is a member of protocolVersions[]', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');
+    const versions = Array.isArray(doc['protocolVersions']) ? (doc['protocolVersions'] as unknown[]) : [];
+    const preferred = doc['preferredVersion'];
+    expect(typeof preferred === 'string' && VERSION.test(preferred), req('openwop.requirement.0172.preferred-version-default.member', DOC, 'preferredVersion is REQUIRED root metadata with the <major>.<minor> grammar')).toBe(true);
+    expect(versions.includes(preferred), req('openwop.requirement.0172.preferred-version-default.member', DOC, `preferredVersion (${String(preferred)}) MUST be a member of protocolVersions[] [${versions.map(String).join(', ')}]`)).toBe(true);
+    if (versions.length === 1) {
+      expect(doc['protocolVersion'] === undefined || doc['protocolVersion'] === preferred, req('openwop.requirement.0172.preferred-version-default.member', DOC, 'on a host serving a single major, preferredVersion MUST equal protocolVersion (RFC 0179 §A.1)')).toBe(true);
+    }
+  });
+
+  it('a header-less GET /.well-known/openwop is the preferredVersion representation', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');
+    const preferred = String(doc['preferredVersion']);
+    const res = await headerless();
+    if (res === null) return softSkip('blocked', 'header-less GET /.well-known/openwop unreachable (fetch failed)');
+    expect(res.status, req('openwop.requirement.0172.preferred-version-default.headerless', 'spec/v2/core/versioning.md §1.3', 'the discovery resource MUST answer a header-less request')).toBe(200);
+    const preferredMajor = preferred.split('.')[0];
+    expect(res.version?.trim().split('.')[0], req('openwop.requirement.0172.preferred-version-default.headerless', 'spec/v2/core/versioning.md §1.3', `with the header absent the host MUST serve preferredVersion's major (${preferredMajor}) and report it in OpenWOP-Version`)).toBe(preferredMajor);
+    const body = res.json as Record<string, unknown> | undefined;
+    if (preferredMajor === '2') {
+      const r = v2Validator('capabilities')(body);
+      expect(r.ok, req('openwop.requirement.0172.preferred-version-default.headerless', 'spec/v2/core/capabilities.md §1', `preferredVersion is 2.x, so the header-less representation MUST be the closed v2 root (${r.errors})`)).toBe(true);
+    } else {
+      expect(typeof body?.['protocolVersion'], req('openwop.requirement.0172.preferred-version-default.headerless', 'spec/v2/core/capabilities.md §1', 'preferredVersion is 1.x, so the header-less representation MUST be the v1 document (protocolVersion present) through the overlap')).toBe('string');
+      expect(Array.isArray(body?.['protocolVersions']) && typeof body?.['preferredVersion'] === 'string', req('openwop.requirement.0172.preferred-version-default.headerless', 'spec/v2/core/capabilities.md §1', 'the v1 representation MUST carry protocolVersions[] and preferredVersion additively so a single fetch names the other major')).toBe(true);
+    }
+  });
+  it('through the overlap preferredVersion names a 1.x member', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');
+    const advertised = Array.isArray(doc['protocolVersions']) ? (doc['protocolVersions'] as unknown[]).map(String) : [];
+    if (!advertised.some((v) => v.startsWith('1.'))) return softSkip('inapplicable', `the host advertises no 1.x member (${advertised.join(', ') || 'none'}) — it is past the overlap, so preferredVersion is a 2.x and the header-less representation is the closed v2 root`);
+    // The header-less representation is the v1 document through the overlap
+    // (capabilities.md §1) and the header-less default is preferredVersion's
+    // major (§1.3); the two agree only when preferredVersion is the 1.x member.
+    expect(
+      String(doc['preferredVersion']).split('.')[0],
+      req('openwop.requirement.0172.preferred-version-default.overlap', 'spec/v2/core/versioning.md §1.1', `the host advertises a 1.x member (${advertised.join(', ')}), so preferredVersion MUST be that 1.x — otherwise versioning.md §1.3 and RFC 0176 §C.1 select different representations for the same header-less request (got ${String(doc['preferredVersion'])})`),
+    ).toBe('1');
+  });
+});

package/src/scenarios/v2-profiles-derived-only.test.ts

@@ -0,0 +1,70 @@
+/**
+ * v2 — `profiles-derived-only` (suite 2.0.0; RFC 0169 §C.1, §C.3;
+ * `spec/v2/core/capabilities.md` §7 "Profiles").
+ *
+ * Witness class: witnessable — unaided. A profile is a predicate over the
+ * declaration file, published in `spec/v2/profiles.json`; it is never a wire
+ * field. The host's v2 document MUST NOT carry a root `profiles[]`, and every
+ * profile in the registry MUST be derivable from the document alone: every
+ * listed family present as a record and every listed metadata key present.
+ * `profiles.json` is read from the spec tree beside `SCHEMAS_DIR`; under a
+ * layout that does not ship it the derivation leg records `blocked`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { v2Discovery } from '../lib/v2.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/capabilities.md §7';
+const PROFILES_PATH = join(SCHEMAS_DIR, '..', 'spec', 'v2', 'profiles.json');
+
+interface ProfileRow { readonly id: string; readonly predicate: { readonly families?: readonly string[]; readonly metadata?: readonly string[] } }
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v) && typeof (v as Record<string, unknown>)['status'] === 'string';
+}
+
+/** RFC 0169 §C.1 — the predicate, evaluated over the document alone. */
+function derive(doc: Record<string, unknown>, p: ProfileRow): boolean {
+  const families = p.predicate.families ?? [];
+  const metadata = p.predicate.metadata ?? [];
+  return families.every((f) => isRecord(doc[f])) && metadata.every((m) => doc[m] !== undefined);
+}
+
+describe('v2 profiles-derived-only (RFC 0169 §C.1, §C.3)', () => {
+  it('the v2 document carries no root `profiles[]`', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');
+    expect('profiles' in doc, req('openwop.requirement.0169.profiles-derived-only.no-root-profiles', DOC, 'no `profiles[]` exists at the v2 root; a profile is a derived predicate, never a wire field (row C2.10)')).toBe(false);
+  });
+
+  it('every registry profile is derivable from the document; the discovery-core predicate holds on a valid document', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');
+    if (!existsSync(PROFILES_PATH)) return softSkip('blocked', `spec/v2/profiles.json is not shipped in this layout (${PROFILES_PATH}) — the profile registry cannot be read`);
+    const rows = (JSON.parse(readFileSync(PROFILES_PATH, 'utf8')) as { profiles?: ProfileRow[] }).profiles ?? [];
+    expect(rows.length, req('openwop.requirement.0169.profiles-derived-only.derivable', DOC, 'spec/v2/profiles.json MUST list at least one profile')).toBeGreaterThan(0);
+    for (const p of rows) {
+      // Every listed family the host advertises MUST be a record — a profile
+      // predicate over a non-record value (a boolean, a bare object) is not derivable.
+      for (const f of p.predicate.families ?? []) {
+        if (doc[f] !== undefined) {
+          expect(isRecord(doc[f]), req('openwop.requirement.0169.profiles-derived-only.derivable', DOC, `profile ${p.id} lists family ${f}; the host advertises it, so it MUST be one capability record {status, since, witness, …}`)).toBe(true);
+        }
+      }
+      expect(typeof derive(doc, p), req('openwop.requirement.0169.profiles-derived-only.derivable', DOC, `profile ${p.id} MUST be decidable from the document alone`)).toBe('boolean');
+    }
+    const core = rows.find((p) => p.id === 'openwop-discovery-core');
+    if (core !== undefined) {
+      expect(derive(doc, core), req('openwop.requirement.0169.profiles-derived-only.derivable', DOC, 'openwop-discovery-core (metadata protocolVersions + preferredVersion, both REQUIRED at the root) MUST derive true from every valid v2 document')).toBe(true);
+    }
+  });
+});