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

package/src/scenarios/v2-effect-identity-business-key.test.ts

@@ -0,0 +1,132 @@
+/**
+ * RFC 0173 §B — `effect-identity-business-key` (suite 2.0.0, target major 2; gated on `idempotency`).
+ *
+ * Layer-2 effect identity is a core obligation keyed on business identity: a
+ * host that advertises `idempotency` assigns a logical effect id once per
+ * effect, stable across transport retries, injects it as the provider's
+ * idempotency key, and serves `GET /runs/{runId}/effects`
+ * (`schemas/v2/effect-ledger-projection.schema.json`) — each row
+ * `{ effectId, nodeId, attempt, keying: business-identity | activity-recipe,
+ * state, at }`, content-free of provider payloads (RFC 0150 §B; RFC 0173 §B row
+ * C6.7; `spec/v2/core/security-defaults.md` §Layer-2 effect identity).
+ *
+ * Legs:
+ *   1. the ledger read validates on a run of the noop fixture and every row's
+ *      `keying` is one of the two documented modes;
+ *   2. the "same provider key across two transport retries" leg needs the
+ *      suite's fixture provider (RFC 0173 §D.2 G4 — a provider that rejects a
+ *      changed key) driven through the seams profile; no such seam is
+ *      catalogued, so that leg records `blocked` naming it.
+ *
+ * @see spec/v2/core/security-defaults.md §Layer-2 effect identity
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { v2Discovery, gateFamily, v2Validator } from '../lib/v2.js';
+import { seamsProfileAdvertised, SEAMS_PREFIX } from '../lib/seams.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const FIXTURE = 'conformance-noop';
+const KEYING = ['business-identity', 'activity-recipe'];
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+async function waitTerminal(runId: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}`);
+    if (res.status === 200 && TERMINAL.has(String((res.json as { status?: unknown } | null)?.status))) return;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+describe('RFC 0173 §B — effect-identity-business-key (gated on idempotency)', () => {
+  it('GET /runs/{runId}/effects validates and every row is keyed on business identity or the activity recipe', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('idempotency'))) return softSkip('inapplicable', 'idempotency family not advertised — no Layer-2 obligation (gate recorded under openwop.family.idempotency)');
+    const fixtures = Array.isArray(doc['fixtures']) ? (doc['fixtures'] as unknown[]) : [];
+    if (!fixtures.includes(FIXTURE)) return softSkip('inapplicable', `${FIXTURE} fixture not advertised — no run to read`);
+
+    const create = await driver.post('/runs', { workflowId: FIXTURE });
+    expect(create.status, req('openwop.requirement.0173.effect-identity-business-key', 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await waitTerminal(runId, 10_000);
+
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}/effects`);
+    expect(
+      res.status,
+      req('openwop.requirement.0173.effect-identity-business-key', 'security-defaults.md §Layer-2 effect identity', 'a host advertising `idempotency` MUST serve GET /runs/{runId}/effects with 200 (RFC 0173 §B)'),
+    ).toBe(200);
+    const check = v2Validator('effect-ledger-projection')(res.json);
+    expect(
+      check.ok,
+      req('openwop.requirement.0173.effect-identity-business-key', 'effect-ledger-projection.schema.json', `the ledger projection MUST validate: ${check.errors}`),
+    ).toBe(true);
+    const body = res.json as { runId?: unknown; effects?: Array<{ effectId?: unknown; keying?: unknown; providerKey?: unknown }> };
+    expect(body.runId, req('openwop.requirement.0173.effect-identity-business-key', 'effect-ledger-projection.schema.json runId', 'runId MUST echo the run read')).toBe(runId);
+    const effects = body.effects ?? [];
+    const ids = new Set<string>();
+    for (const e of effects) {
+      expect(
+        KEYING,
+        req('openwop.requirement.0173.effect-identity-business-key', 'security-defaults.md §Layer-2 effect identity', `keying MUST be business-identity or activity-recipe (the documented fallback) — effect ${String(e.effectId)} declares ${String(e.keying)}`),
+      ).toContain(e.keying);
+      // One logical effect id per effect: a duplicate row is a re-assignment.
+      expect(
+        ids.has(String(e.effectId)),
+        req('openwop.requirement.0173.effect-identity-business-key', 'RFC 0150 §B', `effectId ${String(e.effectId)} MUST be assigned once per effect (duplicate ledger row)`),
+      ).toBe(false);
+      ids.add(String(e.effectId));
+      if (typeof e.providerKey === 'string') {
+        expect(
+          /(secret|bearer |sk-[a-z0-9]{8,})/i.test(e.providerKey),
+          req('openwop.requirement.0173.effect-identity-business-key', 'effect-ledger-projection.schema.json providerKey', 'providerKey is a redaction-safe identity, never credential material'),
+        ).toBe(false);
+      }
+    }
+    if (effects.length === 0) softSkip('inapplicable', 'the noop fixture issued no external effect — the per-row keying leg had no rows (an effect-issuing fixture would exercise it)');
+  });
+
+  it('the same provider key is presented across two transport retries', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('idempotency'))) return softSkip('inapplicable', 'idempotency family not advertised — no Layer-2 obligation (gate recorded under openwop.family.idempotency)');
+    if (!seamsProfileAdvertised(doc)) return softSkip('blocked', 'the retry leg is driven through the suite fixture provider (RFC 0173 §D.2 G4) under the seams profile — seams profile not advertised');
+    // The seam is catalogued (api/seams-v2.yaml `forceEffectTransportRetry`). An
+    // unreachable providerUrl forces the transport retry; the witness is the
+    // host's own Layer-2 ledger (RFC 0173 §C.2), where every attempt of one
+    // effect MUST carry the same business-identity key.
+    const fired = await driver.post(`${SEAMS_PREFIX}/sample/test/idempotency/effect-retry`, { providerUrl: 'http://127.0.0.1:1/' });
+    if (fired.status === 404 || fired.status === 403 || fired.status === 405) {
+      return softSkip('blocked', `the host advertises the seams profile but does not serve ${SEAMS_PREFIX}/sample/test/idempotency/effect-retry (answered ${fired.status}) — the cross-retry keying leg cannot be driven`);
+    }
+    const body = fired.json as { runId?: unknown; effectId?: unknown } | null;
+    if (fired.status !== 201 || typeof body?.runId !== 'string' || typeof body?.effectId !== 'string') {
+      return softSkip('blocked', `${SEAMS_PREFIX}/sample/test/idempotency/effect-retry answered ${fired.status} without { runId, effectId } — the seam contract in api/seams-v2.yaml is 201 { runId, effectId }`);
+    }
+    const ledger = await driver.get(`/runs/${body.runId}/effects`);
+    if (ledger.status !== 200) return softSkip('blocked', `GET /runs/{runId}/effects answered ${ledger.status} — the ledger is the witness for cross-retry keying`);
+    const all = ((ledger.json as { effects?: unknown } | null)?.effects ?? []) as Array<Record<string, unknown>>;
+    const attempts = all.filter((e) => e['effectId'] === body.effectId);
+    if (attempts.length < 2) {
+      return softSkip('blocked', `the seam produced ${attempts.length} ledger row(s) for effect ${String(body.effectId)} — a cross-retry assertion needs at least two attempts`);
+    }
+    const keys = new Set(attempts.map((e) => String(e['providerKey'] ?? '')));
+    expect(
+      keys.size,
+      req('openwop.requirement.0173.effect-identity-business-key.retry', 'spec/v2/core/replay.md §Effect identity', `every attempt of one effect MUST present the same provider key across a transport retry — ${attempts.length} attempt(s) presented ${keys.size} distinct key(s)`),
+    ).toBe(1);
+    for (const a of attempts) {
+      expect(
+        a['keying'],
+        req('openwop.requirement.0173.effect-identity-business-key.retry', 'spec/v2/core/replay.md §Effect identity', `a Layer-2 host keys a retried effect on business identity, not the activity recipe (attempt ${String(a['attempt'])})`),
+      ).toBe('business-identity');
+    }
+  });
+});

package/src/scenarios/v2-effect-seam-manifest.test.ts

@@ -0,0 +1,163 @@
+/**
+ * RFC 0173 §C.1 — `effect-seam-manifest` (suite 2.0.0, target major 2; gated on `replay`).
+ *
+ * A v2 host that advertises `replay` MUST publish the effect-seam manifest at
+ * `GET /host/effect-seams` (`api/v2/openapi.yaml` `getEffectSeamManifest`,
+ * `schemas/v2/effect-seam-manifest.schema.json`): one row per outbound effect
+ * path the node runtime can reach, every row `guarded: true` with a
+ * `guardedBy`. The `replay` facet names the address as the constant
+ * `effectSeamsManifest: "/host/effect-seams"` (`spec/v2/facets/replay.schema.json`).
+ *
+ * Legs:
+ *   1. the manifest validates; every row is guarded; at least one row exists
+ *      for every `kind` the host declares (the manifest is the host's own
+ *      enumeration — RFC 0140 G7 answered by making the host list it);
+ *   2. the facet constant equals the served address;
+ *   3. driving one seam of each kind through the suite's receiver and
+ *      observing no re-fire needs a seam that fires a named manifest row inside
+ *      a run — none is catalogued (`host-sample-test-seams.md`,
+ *      `api/seams-v2.yaml`), so that leg records `blocked` naming it.
+ *
+ * Completeness of the manifest (a seam outside it) is negative-existence and is
+ * not asserted here (RFC 0173 falsifiability table, §C.1 row).
+ *
+ * @see spec/v2/core/replay.md §The effect-seam manifest
+ * @see spec/v2/core/security-defaults.md §Replay suppression
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, gateFamily, v2Validator } from '../lib/v2.js';
+import { seamsProfileAdvertised, SEAMS_PREFIX } from '../lib/seams.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const MANIFEST_PATH = '/host/effect-seams';
+const KINDS = ['http', 'queue', 'storage', 'provider-sdk', 'webhook-fanout'] as const;
+
+interface SeamRow { seam?: unknown; kind?: unknown; guarded?: unknown; guardedBy?: unknown; branchReFires?: unknown }
+interface Manifest { manifestVersion?: unknown; seams?: SeamRow[] }
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+async function manifest(): Promise<{ status: number; body: Manifest | null }> {
+  const res = await driver.get(MANIFEST_PATH);
+  return { status: res.status, body: res.status === 200 && res.json && typeof res.json === 'object' ? (res.json as Manifest) : null };
+}
+
+describe('RFC 0173 §C.1 — effect-seam-manifest (gated on replay)', () => {
+  it('GET /host/effect-seams validates and every row is guarded', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const replay = await gateFamily('replay');
+    if (!replay) return softSkip('inapplicable', 'replay family not advertised (gate recorded under openwop.family.replay)');
+
+    const { status, body } = await manifest();
+    expect(
+      status,
+      req('openwop.requirement.0173.effect-seam-manifest', 'replay.md §The effect-seam manifest', 'a host advertising `replay` MUST serve GET /host/effect-seams with 200 (RFC 0173 §C.1)'),
+    ).toBe(200);
+    const check = v2Validator('effect-seam-manifest')(body);
+    expect(
+      check.ok,
+      req('openwop.requirement.0173.effect-seam-manifest', 'effect-seam-manifest.schema.json', `the manifest MUST validate against schemas/v2/effect-seam-manifest.schema.json: ${check.errors}`),
+    ).toBe(true);
+    const rows = body?.seams ?? [];
+    expect(
+      rows.length,
+      req('openwop.requirement.0173.effect-seam-manifest', 'replay.md §The effect-seam manifest', 'the manifest MUST enumerate at least one outbound effect seam — a node runtime with no effect path does not need `replay`'),
+    ).toBeGreaterThan(0);
+    for (const row of rows) {
+      expect(
+        row.guarded,
+        req('openwop.requirement.0173.effect-seam-manifest', 'RFC 0173 §C.1', `every manifest row MUST be guarded: true — seam ${String(row.seam)} (kind ${String(row.kind)})`),
+      ).toBe(true);
+      expect(
+        typeof row.guardedBy === 'string' && row.guardedBy.length > 0,
+        req('openwop.requirement.0173.effect-seam-manifest', 'RFC 0173 §C.1', `every row MUST name the mechanism that records the outcome instead of re-firing (guardedBy) — seam ${String(row.seam)}`),
+      ).toBe(true);
+      expect(
+        (KINDS as readonly string[]).includes(String(row.kind)),
+        req('openwop.requirement.0173.effect-seam-manifest', 'effect-seam-manifest.schema.json seams[].kind', `kind MUST be one of ${KINDS.join(' | ')} — seam ${String(row.seam)} declares ${String(row.kind)}`),
+      ).toBe(true);
+    }
+    // One row per kind the host declares: the set of kinds the manifest names is
+    // the host's declaration, and each named kind is backed by at least one row.
+    const declared = new Set(rows.map((r) => String(r.kind)));
+    for (const kind of declared) {
+      expect(
+        rows.filter((r) => r.kind === kind).length,
+        req('openwop.requirement.0173.effect-seam-manifest', 'RFC 0173 §C.1', `at least one manifest row per declared kind (${kind})`),
+      ).toBeGreaterThanOrEqual(1);
+    }
+    // RFC 0140 G6: a `branch` re-fire is stated as a permission, and a permission
+    // for a mode the host does not offer is a claim about nothing.
+    const modes = Array.isArray(replay['modes']) ? (replay['modes'] as unknown[]) : [];
+    for (const row of rows.filter((r) => r.branchReFires === true)) {
+      expect(
+        modes,
+        req('openwop.requirement.0173.effect-seam-manifest', 'effect-seam-manifest.schema.json seams[].branchReFires', `seam ${String(row.seam)} states branchReFires: true, so the replay facet MUST offer the branch mode it refers to`),
+      ).toContain('branch');
+    }
+  });
+
+  it('the replay facet names the manifest address as the constant /host/effect-seams', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const replay = await gateFamily('replay');
+    if (!replay) return softSkip('inapplicable', 'replay family not advertised (gate recorded under openwop.family.replay)');
+    expect(
+      replay['effectSeamsManifest'],
+      req('openwop.requirement.0173.effect-seam-manifest.facet', 'facets/replay.schema.json effectSeamsManifest', 'the facet MUST carry the constant "/host/effect-seams" (replay.md §The surface)'),
+    ).toBe(MANIFEST_PATH);
+  });
+
+  it('driving one seam of each kind observes no re-fire on replay', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const replay = await gateFamily('replay');
+    if (!replay) return softSkip('inapplicable', 'replay family not advertised (gate recorded under openwop.family.replay)');
+    if (!seamsProfileAdvertised(doc)) {
+      return softSkip('blocked', `the no-re-fire leg is seam-gated (RFC 0173 falsifiability §B replay row is witnessable-gated only through a seam that fires a named manifest row inside a run) — seams profile not advertised (conformance.seamsProfile)`);
+    }
+    // The seam is catalogued (api/seams-v2.yaml `fireEffectSeam`). The witness is
+    // the host's own Layer-2 ledger, not an externally reachable receiver: fire a
+    // guarded row that states `branchReFires: false`, fork the run in `replay`
+    // mode, and read GET /runs/{runId}/effects on the fork. Suppression means the
+    // fork issues no further attempt for that seam, so its effect ledger cannot
+    // grow past the parent's.
+    const manifest = await driver.get(MANIFEST_PATH);
+    const seamRows: SeamRow[] = manifest.status === 200 && manifest.json && typeof manifest.json === 'object'
+      ? ((manifest.json as Manifest).seams ?? []) : [];
+    const target = seamRows.find((r) => r.guarded === true && r.branchReFires === false);
+    if (!target) return softSkip('inapplicable', `no manifest row is both guarded and branchReFires: false — nothing to witness suppression on (${seamRows.length} row(s) at ${MANIFEST_PATH})`);
+    const fired = await driver.post(`${SEAMS_PREFIX}/sample/effect-seams/fire`, { seam: String(target.seam) });
+    if (fired.status === 404 || fired.status === 403 || fired.status === 405) {
+      return softSkip('blocked', `the host advertises the seams profile but does not serve ${SEAMS_PREFIX}/sample/effect-seams/fire (answered ${fired.status}) — the no-re-fire leg cannot be driven`);
+    }
+    const firedBody = fired.json as { runId?: unknown } | null;
+    if (fired.status !== 201 || typeof firedBody?.runId !== 'string') {
+      return softSkip('blocked', `${SEAMS_PREFIX}/sample/effect-seams/fire answered ${fired.status} without { runId } — the seam contract in api/seams-v2.yaml is 201 { runId }`);
+    }
+    const parentId = firedBody.runId;
+    const parentEffects = await driver.get(`/runs/${parentId}/effects`);
+    if (parentEffects.status !== 200) return softSkip('blocked', `GET /runs/{runId}/effects answered ${parentEffects.status} on the fired run — the ledger is the witness for suppression (RFC 0173 §C.2)`);
+    const countOf = (r: OpenWOPResponse): number => {
+      const b = r.json as { effects?: unknown } | null;
+      return Array.isArray(b?.effects) ? (b.effects as unknown[]).length : 0;
+    };
+    const forked = await driver.post(`/runs/${parentId}:fork`, { mode: 'replay' });
+    const forkBody = forked.json as { runId?: unknown } | null;
+    if (forked.status !== 201 || typeof forkBody?.runId !== 'string') {
+      return softSkip('blocked', `POST /runs/{runId}:fork mode replay answered ${forked.status} on the fired run — suppression is witnessed on the fork`);
+    }
+    const forkEffects = await driver.get(`/runs/${String(forkBody.runId)}/effects`);
+    if (forkEffects.status !== 200) return softSkip('blocked', `GET /runs/{runId}/effects answered ${forkEffects.status} on the replay fork`);
+    expect(
+      countOf(forkEffects),
+      req('openwop.requirement.0173.effect-seam-manifest.no-re-fire', 'spec/v2/core/replay.md §The effect-seam manifest', `seam ${String(target.seam)} states branchReFires: false, so a replay fork MUST NOT issue a further attempt through it — the fork's effect ledger (${countOf(forkEffects)}) cannot exceed the parent's (${countOf(parentEffects)})`),
+    ).toBeLessThanOrEqual(countOf(parentEffects));
+  });
+});

package/src/scenarios/v2-enum-growth-rule.test.ts

@@ -0,0 +1,69 @@
+/**
+ * v2 — `enum-growth-rule` (suite 2.0.0; RFC 0171 §A.1, §A.5;
+ * `spec/v2/core/events.md` §"Types" — Growth; `overview.md` §0).
+ *
+ * Witness class: witnessable — unaided. A registry-backed enum grows by adding
+ * a row and regenerating; a consumer MUST accept an unknown registered member
+ * and MUST NOT act on it, and a producer MUST NOT emit an unregistered member.
+ * The schema half is server-free: `run-event.schema.json`'s `oneOf` accepts a
+ * vendor type `<org>.thing` (the org read from the host's `extensions`, `acme`
+ * when the host is unreachable or advertises none) that is unknown to this
+ * suite, and rejects the reserved `openwop.` prefix. The reader half is the
+ * suite's own fold: `event-type-closed` and `payload-registry-closed` ignore a
+ * vendor event's payload rather than acting on it, which is what the growth
+ * rule requires of a consumer. The producer half is `event-type-closed`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { v2Discovery, v2Validator } from '../lib/v2.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/events.md §Types (Growth)';
+
+async function org(): Promise<string> {
+  let doc: Record<string, unknown> | null;
+  try { doc = await v2Discovery(); } catch { doc = null; }
+  const ext = doc?.['extensions'];
+  const first = ext !== null && typeof ext === 'object' ? Object.keys(ext as Record<string, unknown>)[0] : undefined;
+  const o = first?.split('.')[0];
+  return o !== undefined && o.length > 0 ? o : 'acme';
+}
+
+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 ?? []));
+}
+
+function event(type: string): Record<string, unknown> {
+  return {
+    eventId: 'conformanceevent0123456789',
+    runId: 'openwop-conformance-tenant/conformancerun0123456789',
+    type,
+    payload: { anything: 'the suite does not act on it' },
+    timestamp: '2026-09-03T00:00:00Z',
+    sequence: 0,
+    schemaVersion: 1,
+  };
+}
+
+describe('v2 enum-growth-rule (RFC 0171 §A.5)', () => {
+  it('the envelope accepts a registered-but-unknown-to-this-suite vendor member', async () => {
+    const validate = v2Validator('run-event');
+    const type = `${await org()}.thing`;
+    expect(protocolTypes().has(type), req('openwop.requirement.0171.enum-growth-rule.unknown-member-accepted', DOC, `${type} MUST NOT be a member of the suite's closed protocol enum — it is the unknown member the rule is about`)).toBe(false);
+    const r = validate(event(type));
+    expect(r.ok, req('openwop.requirement.0171.enum-growth-rule.unknown-member-accepted', DOC, `a consumer MUST accept an unknown registered member: the schema's oneOf vendor branch MUST admit ${type} (${r.errors})`)).toBe(true);
+    const three = validate(event(`${await org()}.thing.happened`));
+    expect(three.ok, req('openwop.requirement.0171.enum-growth-rule.unknown-member-accepted', DOC, 'the vendor branch admits an optional third segment (<org>.<domain>.<name>)')).toBe(true);
+  });
+
+  it('the reserved prefix and a malformed member are rejected', () => {
+    const validate = v2Validator('run-event');
+    expect(validate(event('openwop.thing')).ok, req('openwop.requirement.0171.enum-growth-rule.reserved-rejected', DOC, 'openwop. is the only reserved prefix; a type under it that is not in the enum MUST fail')).toBe(false);
+    expect(validate(event('Acme.Thing')).ok, req('openwop.requirement.0171.enum-growth-rule.reserved-rejected', DOC, 'a member outside the positive pattern (upper-case) MUST fail')).toBe(false);
+    expect(validate(event('thing')).ok, req('openwop.requirement.0171.enum-growth-rule.reserved-rejected', DOC, 'a single-segment member MUST fail — every type is <domain>.<name> or <org>.<name>')).toBe(false);
+  });
+});

package/src/scenarios/v2-era-key.test.ts

@@ -0,0 +1,86 @@
+/**
+ * RFC 0176 §A.2 — `era-key` (suite 2.0.0, target major 2; unaided).
+ *
+ * `eventLogSchemaVersion` is the era key: a v2 host MUST stamp `3` on every run
+ * it creates, the field is REQUIRED on every run snapshot
+ * (`schemas/v2/run-snapshot.schema.json`), and discovery advertises the value
+ * the host writes for new runs and nothing else (`spec/v2/core/persistence.md`
+ * §The era key; versioning.md §2.2). The absent-⇒-`2` half of the rule is a
+ * property of a store a v1 host has written and is witnessed by the seam-gated
+ * `v2-v1-events-translated` scenario, not here.
+ *
+ * Legs:
+ *   1. a run created now (`POST /runs`, the `conformance-noop` fixture) reads
+ *      back with `eventLogSchemaVersion: 3`;
+ *   2. discovery's `eventLogSchemaVersion` equals the value the host wrote.
+ *
+ * @see spec/v2/core/persistence.md §The era key
+ * @see spec/v2/core/runs.md §getRun
+ */
+
+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/persistence.md §The era key';
+const NOOP_WORKFLOW_ID = 'conformance-noop';
+const V2_ERA = 3;
+
+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 freshSnapshot(): Promise<{ snapshot: Record<string, unknown> } | { reason: string }> {
+  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 snap = await http(() => driver.get(`/runs/${encodeURIComponent(runId)}`));
+  if (snap === null || snap.status !== 200 || !snap.json || typeof snap.json !== 'object') return { reason: `GET /runs/{runId} answered ${snap?.status ?? 'no response'} for the run just created` };
+  return { snapshot: snap.json as Record<string, unknown> };
+}
+
+describe('RFC 0176 §A.2 — era-key (unaided)', () => {
+  it('a run created now carries eventLogSchemaVersion 3 on its snapshot', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const s = await freshSnapshot();
+    if ('reason' in s) return softSkip('blocked', s.reason);
+    expect(
+      s.snapshot['eventLogSchemaVersion'],
+      req('openwop.requirement.0176.era-key', DOC, 'eventLogSchemaVersion is REQUIRED on every run snapshot (run-snapshot.schema.json) — the era key is never absent on a run a v2 host created'),
+    ).toBeDefined();
+    expect(
+      s.snapshot['eventLogSchemaVersion'],
+      req('openwop.requirement.0176.era-key', DOC, `a v2 host MUST stamp ${V2_ERA} on every run it creates (RFC 0176 §A.2; versioning.md §2.2) — got ${String(s.snapshot['eventLogSchemaVersion'])}`),
+    ).toBe(V2_ERA);
+  });
+
+  it('discovery advertises the value the host writes for new runs and nothing else', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const advertised = doc['eventLogSchemaVersion'];
+    expect(
+      Number.isInteger(advertised),
+      req('openwop.requirement.0176.era-key.discovery', 'spec/v2/core/versioning.md §2.2', `discovery MUST advertise eventLogSchemaVersion as an integer (metadata key, capabilities.md §Metadata) — got ${String(advertised)}`),
+    ).toBe(true);
+    expect(
+      advertised,
+      req('openwop.requirement.0176.era-key.discovery', 'spec/v2/core/versioning.md §2.2', `the advertised value is the one the host writes for NEW runs: ${V2_ERA} on a v2 host (a host holds one constant for this axis, RFC 0167 §F)`),
+    ).toBe(V2_ERA);
+    const s = await freshSnapshot();
+    if ('reason' in s) return softSkip('blocked', `${s.reason} — the advertised value was checked, its agreement with a written run was not`);
+    expect(
+      s.snapshot['eventLogSchemaVersion'],
+      req('openwop.requirement.0176.era-key.discovery', DOC, 'the value stamped on a run created now MUST equal the value discovery advertises'),
+    ).toBe(advertised);
+  });
+});

package/src/scenarios/v2-error-registry.test.ts

@@ -0,0 +1,89 @@
+/**
+ * v2 — `error-registry` (suite 2.0.0; RFC 0171 §B.1–§B.2;
+ * `spec/v2/core/errors.md` §"The envelope", §"Retry timing").
+ *
+ * Witness class: witnessable — unaided (the `Retry-After` leg is gated on a
+ * rate-limited response being observed). Every error response MUST be the
+ * closed envelope `{ error, message, details? }` with a registered (or vendor)
+ * code answered at its registered HTTP status; `details.retryAfter`,
+ * `retryAfterMs` and `retryAfterSeconds` MUST NOT be emitted — retry timing
+ * lives in `Retry-After` only, which a `429 rate_limited` MUST set. The
+ * deliberately bad request is `GET /runs/does-not-exist` (outside the runId
+ * grammar, so a host may answer `400 validation_error` or `404 not_found`).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2Validator } 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/errors.md §The envelope';
+const ERRORS_PATH = join(SCHEMAS_DIR, '..', 'spec', 'v2', 'errors.json');
+const RETRY_SPELLINGS = ['retryAfter', 'retryAfterMs', 'retryAfterSeconds'];
+
+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; }
+}
+
+/** code → registered httpStatus, when the registry ships in this layout. */
+function registryStatus(): Map<string, number> | null {
+  if (!existsSync(ERRORS_PATH)) return null;
+  const rows = (JSON.parse(readFileSync(ERRORS_PATH, 'utf8')) as { rows?: Array<{ code: string; httpStatus: number }> }).rows ?? [];
+  return new Map(rows.map((r) => [r.code, r.httpStatus]));
+}
+
+async function badRequest(): Promise<OpenWOPResponse | { 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 res = await http(() => driver.get('/runs/does-not-exist'));
+  if (res === null) return { reason: 'GET /runs/does-not-exist unreachable (fetch failed)' };
+  if (res.status < 400) return { reason: `GET /runs/does-not-exist answered ${res.status} — no error envelope to observe` };
+  return res;
+}
+
+describe('v2 error-registry (RFC 0171 §B.1–§B.2)', () => {
+  it('an error response is the closed envelope with a registered code at its registered status', async () => {
+    const res = await badRequest();
+    if ('reason' in res) return softSkip('blocked', res.reason);
+    const r = v2Validator('error-envelope')(res.json);
+    expect(r.ok, req('openwop.requirement.0171.error-registry.envelope', DOC, `every error body MUST be { error, message, details? } and nothing else, with error a registered or vendor code (${r.errors})`)).toBe(true);
+    const code = readErrorCode(res.json);
+    const registry = registryStatus();
+    if (registry !== null && code !== undefined && registry.has(code)) {
+      expect(res.status, req('openwop.requirement.0171.error-registry.envelope', DOC, `a host MUST answer ${code} with its registered status ${String(registry.get(code))}`)).toBe(registry.get(code));
+    }
+  });
+
+  it('retry timing is never spelled inside details', async () => {
+    const res = await badRequest();
+    if ('reason' in res) return softSkip('blocked', res.reason);
+    const details = (res.json as { details?: unknown } | undefined)?.details;
+    const spelled = details !== null && typeof details === 'object' ? RETRY_SPELLINGS.filter((k) => k in (details as Record<string, unknown>)) : [];
+    expect(spelled, req('openwop.requirement.0171.error-registry.no-retry-details', 'spec/v2/core/errors.md §Retry timing', 'details.retryAfter / retryAfterMs / retryAfterSeconds are not part of v2 and a host MUST NOT emit them — Retry-After is the only retry timing')).toEqual([]);
+  });
+
+  it('a 429 rate_limited response carries Retry-After', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');
+    // The suite does not manufacture load; it inspects whatever the probes it
+    // already makes return. A host that never rate-limits the suite records the
+    // leg as inapplicable (witnessable — gated on a host advertising limits).
+    const seen: OpenWOPResponse[] = [];
+    for (let i = 0; i < 3; i++) {
+      const res = await http(() => driver.get('/runs/does-not-exist'));
+      if (res !== null) seen.push(res);
+    }
+    const limited = seen.filter((r) => r.status === 429);
+    if (limited.length === 0) return softSkip('inapplicable', 'no 429 rate_limited response was observed during the suite\'s probes — the Retry-After leg is gated on a rate-limited response');
+    for (const r of limited) {
+      expect(readErrorCode(r.json), req('openwop.requirement.0171.error-registry.retry-after', 'spec/v2/core/errors.md §Retry timing', 'a 429 MUST carry the registered code rate_limited')).toBe('rate_limited');
+      expect(r.headers.get('retry-after'), req('openwop.requirement.0171.error-registry.retry-after', 'spec/v2/core/errors.md §Retry timing', 'a 429 rate_limited response MUST set Retry-After')).not.toBeNull();
+    }
+  });
+});

package/src/scenarios/v2-event-type-closed.test.ts

@@ -0,0 +1,97 @@
+/**
+ * v2 — `event-type-closed` (suite 2.0.0; RFC 0171 §A.1, §A.5;
+ * `spec/v2/core/events.md` §"The envelope", §"Types").
+ *
+ * Witness class: witnessable — unaided. Every event a host emits on a run's
+ * poll response carries a `type` that is EITHER a member of the closed enum in
+ * `schemas/v2/run-event.schema.json` OR a vendor type matching the positive
+ * `<org>.<name>` pattern whose org the host itself advertises under
+ * `extensions` — a producer MUST NOT emit an unregistered member. Each event is
+ * validated as a whole `RunEventDoc`. The run is the `conformance-noop`
+ * fixture, awaited to a terminal status so the log holds the run transitions.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2Validator } 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 §Types';
+const NOOP_WORKFLOW_ID = 'conformance-noop';
+const VENDOR = /^(?!openwop\.)[a-z][a-z0-9]*(-[a-z0-9]+)*\.[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*)?$/;
+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; }
+}
+
+/** The closed protocol enum, read from the generated schema. */
+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 ?? []));
+}
+
+/** Orgs the host registers under `extensions.<org>.<name>`. */
+function advertisedOrgs(doc: Record<string, unknown>): Set<string> {
+  const ext = doc['extensions'];
+  const keys = ext !== null && typeof ext === 'object' ? Object.keys(ext as Record<string, unknown>) : [];
+  return new Set(keys.map((k) => k.split('.')[0] ?? ''));
+}
+
+async function terminalEvents(): Promise<{ events: unknown[]; doc: Record<string, unknown> } | { reason: string }> {
+  const doc = await discovery();
+  if (!doc) 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 — the log is not observable' };
+  return { events, doc };
+}
+
+describe('v2 event-type-closed (RFC 0171 §A.1, §A.5)', () => {
+  it('every emitted type is a registered protocol type or a vendor type under an advertised org', async () => {
+    const t = await terminalEvents();
+    if ('reason' in t) return softSkip('blocked', t.reason);
+    const enumSet = protocolTypes();
+    const orgs = advertisedOrgs(t.doc);
+    for (const ev of t.events) {
+      const type = String((ev as { type?: unknown }).type);
+      const registered = enumSet.has(type);
+      const vendor = !registered && VENDOR.test(type) && orgs.has(type.split('.')[0] ?? '');
+      expect(registered || vendor, req('openwop.requirement.0171.event-type-closed.type', DOC, `event type ${type} MUST be a member of the closed enum or a vendor type <org>.<name> whose org the host advertises under extensions (a producer MUST NOT emit an unregistered member; openwop. is reserved)`)).toBe(true);
+    }
+  });
+
+  it('every emitted event validates as a RunEventDoc', async () => {
+    const t = await terminalEvents();
+    if ('reason' in t) return softSkip('blocked', t.reason);
+    const validate = v2Validator('run-event');
+    let previous = -1;
+    for (const ev of t.events) {
+      const r = validate(ev);
+      expect(r.ok, req('openwop.requirement.0171.event-type-closed.envelope', 'spec/v2/core/events.md §The envelope', `every event MUST validate against schemas/v2/run-event.schema.json — eventId, runId, type, payload, timestamp, sequence, schemaVersion REQUIRED; closed (${r.errors})`)).toBe(true);
+      const seq = (ev as { sequence?: unknown }).sequence;
+      expect(typeof seq === 'number' && seq > previous, req('openwop.requirement.0171.event-type-closed.envelope', 'spec/v2/core/events.md §The envelope', 'sequence is the one ordering field: integer ≥ 0, strictly increasing per run')).toBe(true);
+      previous = typeof seq === 'number' ? seq : previous;
+    }
+  });
+});