@openwop/openwop-conformance 2.46.44 → 2.48.0

package/src/scenarios/v2-compensation-unwind.test.ts

@@ -0,0 +1,244 @@
+/**
+ * v2 — compensation behavior, witnessed through a failing fixture (RFC 0265;
+ * the rules are `spec/v2/core/security-defaults.md` §Compensation, the
+ * `compensation.*` events in `api/v2/asyncapi.yaml` and
+ * `schemas/v2/compensation-projection.schema.json`).
+ *
+ * `v2-compensation-read-projection` reads the projection on a run with nothing
+ * to unwind. This scenario makes a host unwind. The `conformance-compensate-unwind`
+ * fixture runs three compensable effects (`e1 → e2 → e3`, the conformance-RESERVED
+ * `core.conformance.compensable-effect`) and then a node that fails, under a
+ * `reverse-completion` policy triggered on `node-failure`. The suite causes that
+ * condition unaided and reads the result through normative paths only — the
+ * run's event log, `GET /runs/{runId}/compensation` and `GET /runs/{runId}/effects`.
+ * No seam is involved: the v1 legs (`compensation-behavior`, `compensation-recovery`)
+ * asked a host seam how many effects re-fired, and a host that never compensates
+ * can answer 0.
+ *
+ * One run is shared by every leg (a module-level lazy promise); judges are in
+ * `lib/compensation-unwind.ts`.
+ *   1. `0265.plan-before-inverse` — `compensation.requested` precedes the first
+ *      `compensation.started` in the log (asyncapi: "MUST follow").
+ *   2. `0265.reverse-completion`  — the projection's `attempts[]` names `e3, e2, e1`,
+ *      the reverse of the forward `node.completed` order.
+ *   3. `0265.inverse-once`        — the effect ledger holds exactly three inverse
+ *      records, one per forward effect, each performed once.
+ *   4. `0265.projection-agrees`   — the projection's `status` is `completed` exactly
+ *      when the log holds `compensation.completed`, and `plan[]` names the three
+ *      effect nodes.
+ *   5. `0265.replay-no-refire`    — a `mode: "replay"` fork adds no newly performed
+ *      effect to the fork's ledger (invariant `compensation-replay-no-refire`).
+ *
+ * Dispositions: `compensation` not advertised, or the fixture not listed ⇒
+ * `inapplicable` (every leg). Legs 3 and 5 also need the effect ledger, which
+ * idempotency.md §Witness owes only under `idempotency`; leg 5 needs
+ * `replay.modes ∋ replay` — absent ⇒ `inapplicable`. A run that cannot be
+ * created or finished, a fixture whose effects did not all complete or whose
+ * run did not fail, an unreadable projection or ledger, or a ledger with no
+ * forward record for an effect node (RFC 0265 R1: the host did not map the
+ * reserved node to a ledgered effect) ⇒ `blocked`.
+ *
+ * @see RFCS/0265-compensation-unwind-witness.md
+ * @see spec/v2/core/security-defaults.md §Compensation
+ * @see spec/v2/core/replay.md §Suppression
+ * @see conformance/fixtures.md `conformance-compensate-unwind`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, gateFamily, familyAdvertised } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { projectBoundId } from '../lib/bound-id.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { scaledTimeoutMs } from '../lib/polling.js';
+import {
+  EFFECT_NODES, COMPENSATION_TERMINAL,
+  forwardCompletionOrder, judgePlanBeforeInverse, judgeReverseCompletion, splitLedger,
+  judgeInverseOnce, judgeProjectionAgrees, refiredOnFork,
+  type Attempt, type Ev, type Finding, type LedgerRow, type Projection,
+} from '../lib/compensation-unwind.js';
+
+const FIXTURE = 'conformance-compensate-unwind';
+const DOC = 'security-defaults.md §Compensation; asyncapi compensation.*; compensation-projection.schema.json (RFC 0265)';
+const ID_PLAN = 'openwop.requirement.0265.plan-before-inverse';
+const ID_ORDER = 'openwop.requirement.0265.reverse-completion';
+const ID_ONCE = 'openwop.requirement.0265.inverse-once';
+const ID_AGREES = 'openwop.requirement.0265.projection-agrees';
+const ID_REPLAY = 'openwop.requirement.0265.replay-no-refire';
+const RUN_TERMINAL = /^run\.(completed|failed|cancelled)$/;
+
+type Skip = readonly ['inapplicable' | 'blocked', string];
+type Rec = Record<string, unknown>;
+const isRec = (v: unknown): v is Rec => typeof v === 'object' && v !== null && !Array.isArray(v);
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const assertAll = (id: string, fs: readonly Finding[]): void => { for (const x of fs) expect(x.ok, req(id, DOC, x.message)).toBe(true); };
+const seqOf = (e: Ev): number => (typeof e.sequence === 'number' ? e.sequence : Number.NaN);
+
+async function logOf(runId: string): Promise<Ev[]> {
+  const res = await http(() => driver.get(`/runs/${projectBoundId(runId)}/events/poll?timeout=1`));
+  const body = res?.json;
+  const events = isRec(body) ? body['events'] : undefined;
+  return Array.isArray(events) ? (events as Ev[]).filter((e) => Number.isFinite(seqOf(e))).sort((a, b) => seqOf(a) - seqOf(b)) : [];
+}
+
+/**
+ * Poll until the run has a terminal run event and, if an unwind began (or, for
+ * the source run, is owed), a compensation terminal event. The compensation
+ * tail MAY follow the run's terminal event (replay.md §Refusals), so the run
+ * event alone is not the end. On the deadline the log is returned as it stands:
+ * an unwind that never finishes is for the legs to judge, not a reason to skip.
+ */
+async function settle(runId: string, unwindOwed: boolean): Promise<{ log: Ev[] } | { reason: string }> {
+  const deadline = Date.now() + scaledTimeoutMs(30_000);
+  for (;;) {
+    const log = await logOf(runId);
+    const ended = log.some((e) => typeof e.type === 'string' && RUN_TERMINAL.test(e.type));
+    const begun = unwindOwed || log.some((e) => e.type === 'compensation.requested' || e.type === 'compensation.started');
+    const unwound = log.some((e) => typeof e.type === 'string' && COMPENSATION_TERMINAL.has(e.type));
+    if (ended && (!begun || unwound)) return { log };
+    if (Date.now() > deadline) return ended ? { log } : { reason: `run ${runId} logged no terminal run event within the bound (${log.length} event(s))` };
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+let disc: Promise<Rec | null> | undefined;
+const discovery = (): Promise<Rec | null> => (disc ??= v2Discovery().catch(() => null));
+
+/** The two gates every leg shares: the `compensation` record and the fixture. */
+async function gate(): Promise<Skip | null> {
+  if (!(await discovery())) return ['blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0'];
+  if (!(await gateFamily('compensation'))) return ['inapplicable', 'compensation family not advertised — no obligation (gate recorded under openwop.family.compensation)'];
+  if (!isFixtureAdvertised(FIXTURE)) return ['inapplicable', `the host does not advertise fixture ${FIXTURE} (serving it is OPTIONAL, RFC 0265 §A)`];
+  return null;
+}
+async function ledgerGate(): Promise<Skip | null> {
+  if (!(await familyAdvertised('idempotency'))) return ['inapplicable', 'the host does not advertise idempotency, so it owes no effect ledger (idempotency.md §Witness) and the inverse records cannot be read'];
+  return null;
+}
+
+interface Unwind { readonly runId: string; readonly log: Ev[]; readonly projection: OpenWOPResponse | null }
+
+/** The shared source run: start the fixture, wait out the run and its unwind, read the projection. Asserts nothing. */
+async function drive(): Promise<{ skip: Skip } | { u: Unwind }> {
+  const created = await http(() => driver.post('/runs', { workflowId: FIXTURE }));
+  const createdBody = created?.json;
+  const runId = isRec(createdBody) ? createdBody['runId'] : undefined;
+  if (created === null || created.status !== 201 || typeof runId !== 'string') return { skip: ['blocked', `POST /runs {workflowId: ${FIXTURE}} answered ${created?.status ?? 'nothing'} ${readErrorCode(created?.json) ?? ''}`.trim()] };
+  const s = await settle(runId, true);
+  if ('reason' in s) return { skip: ['blocked', s.reason] };
+  if (!s.log.some((e) => e.type === 'run.failed')) {
+    return { skip: ['blocked', `the ${FIXTURE} run did not end run.failed (its terminal node is core.fail), so the condition an unwind exists for was not caused — the host does not serve the fixture as fixtures.md specifies`] };
+  }
+  const projection = await http(() => driver.get(`/runs/${projectBoundId(runId)}/compensation`));
+  return { u: { runId, log: s.log, projection } };
+}
+let source: Promise<{ skip: Skip } | { u: Unwind }> | undefined;
+const once = (): Promise<{ skip: Skip } | { u: Unwind }> => (source ??= drive());
+
+/** The shared source run's effect ledger, read once after the unwind. */
+let ledger: Promise<{ skip: Skip } | { rows: LedgerRow[] }> | undefined;
+const sourceLedger = (runId: string): Promise<{ skip: Skip } | { rows: LedgerRow[] }> => (ledger ??= (async () => {
+  const res = await http(() => driver.get(`/runs/${projectBoundId(runId)}/effects`));
+  const body = res?.json;
+  const effects = isRec(body) ? body['effects'] : undefined;
+  if (res === null || res.status !== 200 || !Array.isArray(effects)) {
+    return { skip: ['blocked', `GET /runs/{runId}/effects answered ${res?.status ?? 'nothing'} ${readErrorCode(res?.json) ?? ''} — idempotency.md §Witness owns that contract`.trim()] as const };
+  }
+  return { rows: effects as LedgerRow[] };
+})());
+
+function projectionOf(u: Unwind): { body: Projection } | { skip: Skip } {
+  const p = u.projection;
+  const body = p?.json;
+  if (p === null || p.status !== 200 || !isRec(body)) {
+    return { skip: ['blocked', `GET /runs/{runId}/compensation answered ${p?.status ?? 'nothing'} ${readErrorCode(body) ?? ''} on the unwound run — v2-compensation-read-projection owns that obligation`.trim()] };
+  }
+  return { body };
+}
+
+describe('v2 RFC 0265 — compensation unwind through a failing fixture (host)', () => {
+  it('compensation.requested precedes the first compensation.started', async () => {
+    const g = await gate();
+    if (g) return softSkip(...g);
+    const s = await once();
+    if ('skip' in s) return softSkip(...s.skip);
+    assertAll(ID_PLAN, judgePlanBeforeInverse(s.u.log));
+  }, 120_000);
+
+  it('the projection attempts the effect nodes in the reverse of their forward completion order', async () => {
+    const g = await gate();
+    if (g) return softSkip(...g);
+    const s = await once();
+    if ('skip' in s) return softSkip(...s.skip);
+    const forward = forwardCompletionOrder(s.u.log);
+    if (forward.length !== EFFECT_NODES.length) {
+      return softSkip('blocked', `the log holds a forward node.completed for ${forward.join(', ') || 'none'} of ${EFFECT_NODES.join(', ')}, so there is no forward completion order to reverse`);
+    }
+    const p = projectionOf(s.u);
+    if ('skip' in p) return softSkip(...p.skip);
+    const attempts = Array.isArray(p.body.attempts) ? (p.body.attempts as Attempt[]) : [];
+    assertAll(ID_ORDER, judgeReverseCompletion(forward, attempts));
+  }, 120_000);
+
+  it('the effect ledger holds exactly one inverse record per forward effect', async () => {
+    const g = (await gate()) ?? (await ledgerGate());
+    if (g) return softSkip(...g);
+    const s = await once();
+    if ('skip' in s) return softSkip(...s.skip);
+    const l = await sourceLedger(s.u.runId);
+    if ('skip' in l) return softSkip(...l.skip);
+    const split = splitLedger(l.rows);
+    if (split.missingForward.length > 0) {
+      return softSkip('blocked', `the effect ledger has no record for ${split.missingForward.join(', ')}: the forward effects are absent too, so the host did not map core.conformance.compensable-effect to a ledgered effect (RFC 0265 §A, risk R1) and the inverse count cannot be measured`);
+    }
+    assertAll(ID_ONCE, judgeInverseOnce(split));
+  }, 120_000);
+
+  it('the projection status and plan agree with the event log', async () => {
+    const g = await gate();
+    if (g) return softSkip(...g);
+    const s = await once();
+    if ('skip' in s) return softSkip(...s.skip);
+    const p = projectionOf(s.u);
+    if ('skip' in p) return softSkip(...p.skip);
+    assertAll(ID_AGREES, judgeProjectionAgrees(p.body, s.u.log));
+  }, 120_000);
+
+  it('a replay fork of the unwound run performs no inverse again', async () => {
+    const g = (await gate()) ?? (await ledgerGate());
+    if (g) return softSkip(...g);
+    const replay = await familyAdvertised('replay');
+    if (!replay || !(Array.isArray(replay['modes']) && replay['modes'].includes('replay'))) return softSkip('inapplicable', 'replay.modes does not list replay, so no replay fork can be requested');
+    const s = await once();
+    if ('skip' in s) return softSkip(...s.skip);
+    const l = await sourceLedger(s.u.runId);
+    if ('skip' in l) return softSkip(...l.skip);
+    const split = splitLedger(l.rows);
+    if (split.missingForward.length > 0 || split.inverse.length === 0) {
+      return softSkip('blocked', `the source run's ledger records ${split.missingForward.length > 0 ? `no forward effect for ${split.missingForward.join(', ')}` : 'no inverse effect'}, so a fork that also records none would compare nothing against nothing (RFC 0265 R1)`);
+    }
+    const first = s.u.log[0];
+    if (first === undefined) return softSkip('blocked', 'the source run logged no event to fork from');
+    const forked = await http(() => driver.post(`/runs/${projectBoundId(s.u.runId)}:fork`, { mode: 'replay', fromSeq: first.sequence }));
+    const forkedBody = forked?.json;
+    const forkId = isRec(forkedBody) ? forkedBody['runId'] : undefined;
+    if (forked === null || forked.status !== 201 || typeof forkId !== 'string') {
+      return softSkip('blocked', `POST /runs/{runId}:fork {mode: replay} answered ${forked?.status ?? 'nothing'} ${readErrorCode(forked?.json) ?? ''} on the unwound run`.trim());
+    }
+    const settled = await settle(forkId, false);
+    if ('reason' in settled) return softSkip('blocked', settled.reason);
+    const forkLedger = await http(() => driver.get(`/runs/${projectBoundId(forkId)}/effects`));
+    const forkLedgerBody = forkLedger?.json;
+    const forkRows = isRec(forkLedgerBody) ? forkLedgerBody['effects'] : undefined;
+    if (forkLedger === null || forkLedger.status !== 200 || !Array.isArray(forkRows)) {
+      return softSkip('blocked', `GET /runs/{runId}/effects answered ${forkLedger?.status ?? 'nothing'} on the replay fork`);
+    }
+    const refired = refiredOnFork(l.rows, forkRows as LedgerRow[]);
+    expect(
+      refired.length,
+      req(ID_REPLAY, 'replay.md §Suppression; invariant compensation-replay-no-refire (RFC 0265 §B.5)', `a mode: "replay" fork MUST NOT perform an inverse action again — the fork's effect ledger records ${refired.length} effect(s) the source run never made: ${JSON.stringify(refired).slice(0, 300)}`),
+    ).toBe(0);
+  }, 180_000);
+});

package/src/scenarios/v2-replay-llm-cache-key.test.ts

@@ -0,0 +1,160 @@
+/**
+ * v2 — LLM cache key recipe 2 (RFC 0260; the rules are the
+ * `replay.llmCacheKeyRecipe` facet description in `spec/v2/facets/replay.schema.json`
+ * and the `cacheKey` description in `schemas/v2/effect-ledger-projection.schema.json`).
+ *
+ * Server-free (always on):
+ *   1. `0260.shape` — the effect-ledger record admits `cacheKey: {recipe, digest}`
+ *      with a closed recipe vocabulary and a 64-hex digest, and refuses anything else.
+ *
+ * Host legs, unaided through the `conformance-llm-cache-key` fixture: its node makes
+ * one `ctx.callAI` call through the host's conformance mock with the run's
+ * `inputs.request` (prompt and params) unchanged. The suite reads the call's record
+ * on `GET /runs/{runId}/effects` (idempotency.md §Witness), which is a normative
+ * observation path, so no seam is needed:
+ *   2. `0260.key-recorded`  — the record carries `cacheKey` with recipe `openwop-llm-key-2`
+ *   3. `0260.params-in-key` — runs differing only in `maxTokens` have different digests
+ *   4. `0260.key-stable`    — two identical runs have the same digest
+ *   5. `0260.key-portable`  — the digest equals recipe 2 recomputed by the suite
+ *                             (lib/llm-cache-key-2.ts) over the inputs the fixture pins
+ *
+ * Dispositions: `replay.llmCacheKeyRecipe` not advertised, `idempotency` absent, or the
+ * fixture not listed ⇒ `inapplicable`. A run that cannot be created, read or finished,
+ * or a ledger with no record for the node ⇒ `blocked`.
+ *
+ * @see RFCS/0260-llm-cache-key-recipe-2.md
+ * @see spec/v2/core/replay.md §Suppression (the cache key for LLM-calling nodes)
+ * @see conformance/fixtures.md §The LLM cache-key fixture
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2RefValidator } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { projectBoundId } from '../lib/bound-id.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { scaledTimeoutMs } from '../lib/polling.js';
+import {
+  RECIPE_2, FIXTURE, NODE_ID, fixtureInputs, readLedgerKey,
+  judgeRecorded, judgeParamsInKey, judgeStable, judgePortable, type Finding, type LedgerKey, type NamedParam,
+} from '../lib/llm-cache-key-2.js';
+
+const DOC = 'replay facet llmCacheKeyRecipe + effect-ledger-projection cacheKey (RFC 0260)';
+const R = (slug: string): string => `openwop.requirement.0260.${slug}`;
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+const PROMPT = 'Say ok.';
+const PARAMS_A: Partial<Record<NamedParam, unknown>> = { maxTokens: 16, temperature: 0 };
+const PARAMS_B: Partial<Record<NamedParam, unknown>> = { maxTokens: 32, temperature: 0 };
+
+type Skip = readonly ['inapplicable' | 'blocked', string];
+const isRec = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const assertAll = (id: string, fs: readonly Finding[]): void => { for (const x of fs) expect(x.ok, req(id, DOC, x.message)).toBe(true); };
+
+let disc: Promise<Record<string, unknown> | null> | undefined;
+const discovery = (): Promise<Record<string, unknown> | null> => (disc ??= v2Discovery().catch(() => null));
+
+async function gate(): Promise<Skip | null> {
+  const doc = await discovery();
+  if (!doc) return ['blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0'];
+  const replay = doc['replay'];
+  if (!isRec(replay) || replay['llmCacheKeyRecipe'] !== RECIPE_2) return ['inapplicable', `the host does not advertise replay.llmCacheKeyRecipe "${RECIPE_2}" (absent ⇒ the RFC 0041 recipe, opt-in per RFC 0260)`];
+  if (!isRec(doc['idempotency'])) return ['inapplicable', 'the host does not advertise idempotency, so it serves no effect ledger to read the key from'];
+  if (!isFixtureAdvertised(FIXTURE)) return ['inapplicable', `the host does not advertise fixture ${FIXTURE}`];
+  return null;
+}
+
+async function terminal(runId: string): Promise<string | null> {
+  const deadline = Date.now() + scaledTimeoutMs(30_000);
+  for (;;) {
+    const snap = await http(() => driver.get(`/runs/${projectBoundId(runId)}`));
+    const status = String((snap?.json as { status?: unknown } | undefined)?.status ?? '');
+    if (TERMINAL.has(status)) return status;
+    if (Date.now() > deadline) return null;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+/** One fixture run with these params, and the key its provider-call record carries. Asserts nothing. */
+async function keyed(params: Partial<Record<NamedParam, unknown>>): Promise<{ skip: Skip } | { key: LedgerKey | undefined }> {
+  const created = await http(() => driver.post('/runs', { workflowId: FIXTURE, inputs: { request: { prompt: PROMPT, params } } }));
+  const runId = (created?.json as { runId?: unknown } | undefined)?.runId;
+  if (created === null || created.status !== 201 || typeof runId !== 'string') return { skip: ['blocked', `POST /runs {workflowId: ${FIXTURE}} answered ${created?.status ?? 'nothing'} ${readErrorCode(created?.json) ?? ''}`.trim()] };
+  const status = await terminal(runId);
+  if (status !== 'completed') return { skip: ['blocked', `the ${FIXTURE} run ended ${status ?? 'not at all within the timeout'}, so its provider call is not on record`] };
+  const ledger = await http(() => driver.get(`/runs/${projectBoundId(runId)}/effects`));
+  if (ledger === null || ledger.status !== 200) return { skip: ['blocked', `GET /runs/{runId}/effects answered ${ledger?.status ?? 'nothing'} — idempotency.md §Witness owns that contract`] };
+  const key = readLedgerKey(ledger.json, NODE_ID);
+  if (key === 'no-record') return { skip: ['blocked', `the effect ledger has no record for node ${NODE_ID}: the host did not record the provider call as an effect (idempotency.md §Composition)`] };
+  return { key };
+}
+
+const memo = new Map<string, ReturnType<typeof keyed>>();
+const once = (name: 'a' | 'a2' | 'b'): ReturnType<typeof keyed> => {
+  let p = memo.get(name);
+  if (!p) { p = keyed(name === 'b' ? PARAMS_B : PARAMS_A); memo.set(name, p); }
+  return p;
+};
+
+describe('v2 RFC 0260 — cacheKey wire shape (server-free)', () => {
+  it('the effect-ledger record admits cacheKey {recipe, digest} and refuses anything else', () => {
+    const v = v2RefValidator('effect-ledger-projection.schema.json');
+    const base = { effectId: 'acme/0123456789abcdef', nodeId: 'llm-call', attempt: 1, keying: 'activity-recipe', state: 'completed', at: '2026-11-13T00:00:00Z' };
+    const doc = (rec: Record<string, unknown>) => ({ runId: 'acme/0123456789abcdef', effects: [rec] });
+    const digest = 'f1714d7aa2abf5994dd375f66aac14514b1c2439f203a6171dc6053c59f54402';
+    expect(v(doc(base)).ok, req(R('shape'), DOC, 'a record without cacheKey MUST validate (the facet is opt-in)')).toBe(true);
+    expect(v(doc({ ...base, cacheKey: { recipe: RECIPE_2, digest } })).ok, req(R('shape'), DOC, 'cacheKey {recipe: openwop-llm-key-2, digest: 64 hex} MUST validate')).toBe(true);
+    expect(v(doc({ ...base, cacheKey: { recipe: 'spec-rfc-0041', digest } })).ok, req(R('shape'), DOC, 'an unregistered recipe MUST fail')).toBe(false);
+    expect(v(doc({ ...base, cacheKey: { recipe: RECIPE_2, digest: digest.toUpperCase() } })).ok, req(R('shape'), DOC, 'an uppercase or short digest MUST fail')).toBe(false);
+    expect(v(doc({ ...base, cacheKey: { recipe: RECIPE_2 } })).ok, req(R('shape'), DOC, 'digest is REQUIRED')).toBe(false);
+    expect(v(doc({ ...base, cacheKey: { recipe: RECIPE_2, digest, preimage: '{}' } })).ok, req(R('shape'), DOC, 'cacheKey is closed: a preimage member MUST fail')).toBe(false);
+  });
+});
+
+describe('v2 RFC 0260 — recipe 2 on the effect ledger (host)', () => {
+  it('a host advertising replay.llmCacheKeyRecipe also advertises idempotency', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0');
+    const replay = doc['replay'];
+    if (!isRec(replay) || replay['llmCacheKeyRecipe'] === undefined) return softSkip('inapplicable', 'the host does not advertise replay.llmCacheKeyRecipe');
+    expect(isRec(doc['idempotency']), req(R('implies-idempotency'), DOC, 'a host advertising replay.llmCacheKeyRecipe MUST advertise idempotency: the effect ledger is where the key is recorded')).toBe(true);
+  });
+
+  it('the provider-call record carries cacheKey with recipe openwop-llm-key-2', async () => {
+    const g = await gate();
+    if (g) return softSkip(...g);
+    const a = await once('a');
+    if ('skip' in a) return softSkip(...a.skip);
+    assertAll(R('key-recorded'), judgeRecorded(a.key));
+  }, 120_000);
+
+  it('two runs that differ only in maxTokens have different keys', async () => {
+    const g = await gate();
+    if (g) return softSkip(...g);
+    const a = await once('a');
+    if ('skip' in a) return softSkip(...a.skip);
+    const b = await once('b');
+    if ('skip' in b) return softSkip(...b.skip);
+    assertAll(R('params-in-key'), judgeParamsInKey(a.key, b.key));
+  }, 120_000);
+
+  it('two identical runs have the same key', async () => {
+    const g = await gate();
+    if (g) return softSkip(...g);
+    const a = await once('a');
+    if ('skip' in a) return softSkip(...a.skip);
+    const a2 = await once('a2');
+    if ('skip' in a2) return softSkip(...a2.skip);
+    assertAll(R('key-stable'), judgeStable(a.key, a2.key));
+  }, 120_000);
+
+  it('the key equals recipe 2 recomputed over the inputs the fixture pins', async () => {
+    const g = await gate();
+    if (g) return softSkip(...g);
+    const a = await once('a');
+    if ('skip' in a) return softSkip(...a.skip);
+    assertAll(R('key-portable'), judgePortable(a.key, fixtureInputs(PROMPT, PARAMS_A)));
+  }, 120_000);
+});

package/src/scenarios/v2-telemetry-export.test.ts

@@ -0,0 +1,181 @@
+/**
+ * v2 — the `telemetry` family: a host exports OTLP traces (RFC 0262; the rules
+ * are `spec/v2/core/telemetry.md`, the facets `spec/v2/facets/telemetry.schema.json`).
+ *
+ * Server-free (always on):
+ *   1. `0262.shape` — the generated `telemetry` record requires `otlp` with a
+ *      non-empty `protocols` from the closed transport vocabulary; the optional
+ *      `genAiSemconv` is a semver string.
+ *
+ * Host legs — gated on the `telemetry` family record AND on the suite's OTLP
+ * collector (`OPENWOP_OTEL_COLLECTOR=true`, the host's exporter pointed at it
+ * with `OTEL_EXPORTER_OTLP_ENDPOINT`). The host calls the suite, so a host in
+ * another network namespace records `blocked`, not a failure.
+ *   2. `0262.run-span` — a `conformance-noop` run exports an `openwop.run` span
+ *      carrying its `openwop.run_id` and `openwop.workflow_id`.
+ *   3. `0262.node-span` — the same run exports an `openwop.node.<typeId>` span
+ *      carrying `openwop.node_id`, `openwop.node_type` and a non-negative
+ *      `openwop.node_attempt`.
+ *   4. `0262.traceparent-continued` — a run created with a suite-minted
+ *      `traceparent` exports its spans under that `traceId`.
+ *   5. `0262.no-secret-in-spans` — after an `openwop-smoke-byok-roundtrip` run,
+ *      no captured span name, attribute or resource attribute carries the store
+ *      canary (digest detector, plus the plaintext when the operator supplies
+ *      `OPENWOP_CANARY_SECRET_VALUE`; `lib/secret-scan.ts`).
+ *   6. `0262.gen-ai-attributes` — gated on `telemetry.genAiSemconv` and the
+ *      `conformance-callai-attempt-accounting` fixture: the model-call span
+ *      carries `gen_ai.operation.name`, a provider attribute, `gen_ai.request.model`
+ *      and both usage-token attributes.
+ *
+ * A host leg whose run exported NO span records `blocked`: an empty export is
+ * not a pass, so a host that advertises the family and exports nothing cannot
+ * certify (RFC 0262 R2).
+ *
+ * @see RFCS/0262-telemetry-family.md
+ * @see spec/v2/core/telemetry.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { familyAdvertised, v2Discovery, v2RefValidator } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { getCollector, waitForRunSpans, type CapturedSpan } from '../lib/otel-collector.js';
+import { digestDetector, findSecretDigest, leaks, valueDetector, type SecretDetector, type Surface } from '../lib/secret-scan.js';
+
+/**
+ * Callback-shaped: the host exports OTLP to the suite's collector.
+ * Unwitnessable when the host is in a separate network namespace — see
+ * `../lib/host-callback.ts`. Not host non-conformance.
+ */
+export const REQUIRES_HOST_CALLBACK = "the host exports OTLP traces to the suite's collector";
+
+const DOC = 'spec/v2/core/telemetry.md (RFC 0262)';
+const R = (slug: string): string => `openwop.requirement.0262.${slug}`;
+const NOOP = 'conformance-noop';
+const BYOK = 'openwop-smoke-byok-roundtrip';
+const CALLAI = 'conformance-callai-attempt-accounting';
+
+type Skip = { skip: ['inapplicable' | 'blocked', string] };
+const skipped = (s: Skip): undefined => softSkip(s.skip[0], s.skip[1]);
+const isRec = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+
+/** The family record, or why the host legs do not bind. */
+async function gate(fixture: string): Promise<Skip | { record: Record<string, unknown> }> {
+  if (!(await v2Discovery())) return { skip: ['blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 under OpenWOP-Version: 2.0'] };
+  const record = await familyAdvertised('telemetry');
+  if (record === null) return { skip: ['inapplicable', 'the telemetry family is not advertised — no export claim'] };
+  if (!getCollector()) return { skip: ['blocked', 'the suite OTLP collector is not running (set OPENWOP_OTEL_COLLECTOR=true and point the host exporter at it)'] };
+  if (!isFixtureAdvertised(fixture)) return { skip: ['inapplicable', `fixture ${fixture} is not advertised`] };
+  return { record };
+}
+
+/** Start a run, wait for it to settle, then wait for its exported spans. */
+async function exportedRun(body: Record<string, unknown>, headers?: Record<string, string>): Promise<Skip | { runId: string; created: OpenWOPResponse; spans: readonly CapturedSpan[] }> {
+  const created = await http(() => driver.post('/runs', body, headers ? { headers } : {}));
+  const runId = isRec(created?.json) ? created.json['runId'] : undefined;
+  if (created === null || created.status !== 201 || typeof runId !== 'string') return { skip: ['blocked', `POST /runs (${String(body['workflowId'])}) answered ${created?.status ?? 'nothing'} ${readErrorCode(created?.json) ?? ''}`.trim()] };
+  try { await pollUntilTerminal(runId, { timeoutMs: 20_000 }); } catch { return { skip: ['blocked', `run ${runId} did not settle within 20 s`] }; }
+  const spans = await waitForRunSpans(runId, { timeoutMs: 8_000, minCount: 2 });
+  if (spans.length === 0) return { skip: ['blocked', `the collector captured no span carrying openwop.run_id ${runId} — the host advertised telemetry but nothing arrived (an empty export is not a pass)`] };
+  return { runId, created, spans };
+}
+
+let noopRun: ReturnType<typeof exportedRun> | undefined;
+const noop = (): ReturnType<typeof exportedRun> => {
+  if (!noopRun) { getCollector()?.reset(); noopRun = exportedRun({ workflowId: NOOP }); }
+  return noopRun;
+};
+
+function spanSurfaces(spans: readonly CapturedSpan[]): Surface[] {
+  return spans.map((s) => ({
+    name: `span ${s.name}`,
+    text: JSON.stringify({ name: s.name, attributes: Object.fromEntries(s.attributes), resource: Object.fromEntries(s.resourceAttributes) }),
+  }));
+}
+
+describe('v2 RFC 0262 — telemetry facet shape (server-free)', () => {
+  it('the telemetry record requires otlp.protocols from the closed transports; genAiSemconv is semver', () => {
+    const v = v2RefValidator('capabilities.schema.json#/properties/telemetry');
+    const base = { status: 'experimental', since: '2.0', witness: 'witnessable-gated' };
+    expect(v({ ...base, otlp: { protocols: ['http/protobuf'] } }).ok, req(R('shape'), DOC, 'a record with otlp.protocols MUST validate')).toBe(true);
+    expect(v({ ...base, otlp: { protocols: ['grpc', 'http/json'] }, genAiSemconv: '1.37.0' }).ok, req(R('shape'), DOC, 'genAiSemconv as semver MUST validate')).toBe(true);
+    expect(v({ ...base }).ok, req(R('shape'), DOC, 'otlp is REQUIRED')).toBe(false);
+    expect(v({ ...base, otlp: { protocols: [] } }).ok, req(R('shape'), DOC, 'protocols MUST be non-empty')).toBe(false);
+    expect(v({ ...base, otlp: { protocols: ['zipkin'] } }).ok, req(R('shape'), DOC, 'an unknown transport MUST fail')).toBe(false);
+    expect(v({ ...base, otlp: { protocols: ['grpc'] }, genAiSemconv: 'latest' }).ok, req(R('shape'), DOC, 'a non-semver genAiSemconv MUST fail')).toBe(false);
+  });
+});
+
+describe('v2 RFC 0262 — OTLP export (host, telemetry-gated)', () => {
+  it('a run exports an openwop.run span with its run and workflow ids', async () => {
+    const g = await gate(NOOP);
+    if ('skip' in g) return skipped(g);
+    const r = await noop();
+    if ('skip' in r) return skipped(r);
+    const run = r.spans.find((s) => s.name === 'openwop.run' || s.name.startsWith('openwop.run.'));
+    expect(run, req(R('run-span'), DOC, 'every run MUST produce a span named openwop.run carrying openwop.run_id')).toBeDefined();
+    expect(run?.attributes.get('openwop.workflow_id'), req(R('run-span'), DOC, 'the run span MUST carry openwop.workflow_id')).toBe(NOOP);
+  });
+
+  it('each node execution exports an openwop.node.<typeId> span with its node attributes', async () => {
+    const g = await gate(NOOP);
+    if ('skip' in g) return skipped(g);
+    const r = await noop();
+    if ('skip' in r) return skipped(r);
+    const node = r.spans.find((s) => s.name.startsWith('openwop.node.'));
+    expect(node, req(R('node-span'), DOC, 'every node execution MUST produce a span named openwop.node.<typeId>')).toBeDefined();
+    expect(typeof node?.attributes.get('openwop.node_id'), req(R('node-span'), DOC, 'the node span MUST carry openwop.node_id')).toBe('string');
+    const type = node?.attributes.get('openwop.node_type');
+    expect(typeof type === 'string' && node?.name === `openwop.node.${type}`, req(R('node-span'), DOC, 'the node span MUST carry openwop.node_type, and its name MUST be openwop.node.<typeId>')).toBe(true);
+    const attempt = node?.attributes.get('openwop.node_attempt');
+    expect(typeof attempt === 'number' && Number.isInteger(attempt) && attempt >= 0, req(R('node-span'), DOC, 'openwop.node_attempt MUST be a non-negative integer')).toBe(true);
+  });
+
+  it('a run created with a traceparent exports its spans in that trace', async () => {
+    const g = await gate(NOOP);
+    if ('skip' in g) return skipped(g);
+    const traceId = '0af7651916cd43dd8448eb211c80319c';
+    const r = await exportedRun({ workflowId: NOOP }, { traceparent: `00-${traceId}-b7ad6b7169203331-01` });
+    if ('skip' in r) return skipped(r);
+    const inTrace = r.spans.filter((s) => s.traceId.toLowerCase() === traceId);
+    expect(inTrace.length, req(R('traceparent-continued'), DOC, 'a run created with a valid W3C traceparent MUST emit its spans in that trace')).toBe(r.spans.length);
+  });
+
+  it('no exported span carries the resolved store secret', async () => {
+    const g = await gate(BYOK);
+    if ('skip' in g) return skipped(g);
+    if (!(await familyAdvertised('secrets'))) return softSkip('inapplicable', 'the secrets family is not advertised, so the store-canary fixture binds nothing');
+    const r = await exportedRun({ workflowId: BYOK });
+    if ('skip' in r) return skipped(r);
+    const snap = await http(() => driver.get(`/runs/${encodeURIComponent(r.runId)}`));
+    const poll = await http(() => driver.get(`/runs/${encodeURIComponent(r.runId)}/events/poll?timeout=1&streamMode=debug`));
+    const detectors: SecretDetector[] = [];
+    const digest = findSecretDigest([r.created.json, snap?.json, poll?.json]);
+    if (digest !== null) detectors.push(digestDetector(digest.sha256, digest.length));
+    const operator = process.env['OPENWOP_CANARY_SECRET_VALUE'];
+    if (operator && operator.length > 0) detectors.push(valueDetector(operator));
+    if (detectors.length === 0) return softSkip('inapplicable', 'the run surfaced no {secretSha256, secretLength} and OPENWOP_CANARY_SECRET_VALUE is unset — nothing can be recognised as the canary');
+    const found = leaks(spanSurfaces(r.spans), detectors);
+    expect(found, req(R('no-secret-in-spans'), DOC, 'a span name, attribute, event or resource attribute MUST NOT carry a resolved secret')).toEqual([]);
+  });
+
+  it('a host advertising genAiSemconv puts the gen_ai attributes on the model-call span', async () => {
+    const g = await gate(CALLAI);
+    if ('skip' in g) return skipped(g);
+    const version = g.record['genAiSemconv'];
+    if (typeof version !== 'string') return softSkip('inapplicable', 'telemetry.genAiSemconv is not advertised — no GenAI mapping claim');
+    const r = await exportedRun({ workflowId: CALLAI, inputs: { request: { prompt: 'conformance', maxTokens: 64 }, script: [{ kind: 'valid', outputTokens: 5 }] } });
+    if ('skip' in r) return skipped(r);
+    const call = r.spans.find((s) => s.attributes.has('gen_ai.operation.name'));
+    expect(call, req(R('gen-ai-attributes'), DOC, `with genAiSemconv ${version}, each model-call span MUST carry gen_ai.operation.name`)).toBeDefined();
+    const has = (k: string): boolean => call?.attributes.get(k) !== undefined && call?.attributes.get(k) !== null;
+    expect(has('gen_ai.provider.name') || has('gen_ai.system'), req(R('gen-ai-attributes'), DOC, 'the model-call span MUST carry the provider attribute its version names')).toBe(true);
+    expect(has('gen_ai.request.model'), req(R('gen-ai-attributes'), DOC, 'the model-call span MUST carry gen_ai.request.model')).toBe(true);
+    expect(has('gen_ai.usage.input_tokens') && has('gen_ai.usage.output_tokens'), req(R('gen-ai-attributes'), DOC, 'the model-call span MUST carry input and output token usage')).toBe(true);
+  });
+});