@openwop/openwop-conformance 2.46.43 → 2.47.0

package/src/scenarios/v2-bounded-loopback.test.ts

@@ -0,0 +1,231 @@
+/**
+ * v2 — a declared, bounded loopback from an approval gate back to the node it
+ * reviews (RFC 0258; the rules are `$defs/EdgeLoopback` in
+ * `schemas/v2/workflow-definition.schema.json`, `$defs/nodeCompleted.loopback`
+ * and `$defs/workflowLoopbackLimit` in `run-event-payloads.schema.json`,
+ * `$defs/ApprovalData.loopback` in `suspend-request.schema.json`, and the
+ * `loopback` family in `spec/v2/facets/loopback.schema.json`).
+ *
+ * Server-free (always on):
+ *   1. `0258.shape` — `EdgeLoopback` requires `on` and `maxIterations >= 1`,
+ *      admits only `on: "refine"`, and a loopback edge carries no condition,
+ *      port or trigger rule; the marker, `ApprovalData.loopback`, the new
+ *      `cap.breached` kind and the facet floor (`maxHistoryEntryBytes >= 4096`)
+ *      validate as declared.
+ *
+ * Host legs — gated on the `loopback` family and on each fixture in discovery
+ * `fixtures[]` (unadvertised → `inapplicable`); judges in
+ * `lib/bounded-loopback-witness.ts`. One `conformance-loopback-refine` run is
+ * driven through two refines, a refused third refine and an accept, and legs
+ * 2–5 read it at the points they name.
+ *   2. `0258.refine-rearms` — after one refine: the marker, a second visit of
+ *      `draft`, a second request under a new key, `apply` not started.
+ *   3. `0258.history-from-log` — `draft` (core.identity, echoes its inputs)
+ *      shows `rounds`: `[]`, then one exact entry per round, oldest first.
+ *   4. `0258.approval-data-loopback` — the three requests read `{0,2,false}`,
+ *      `{1,2,false}`, `{2,2,true}`.
+ *   5. `0258.withdraw-refine` — the exhausted visit omits `refine`, a refine
+ *      resume answers `400 validation_error` with the run still waiting, and
+ *      accept completes the run with `apply` run once.
+ *   6. `0258.fail-on-exhausted` — `conformance-loopback-refine-fail`: a refine
+ *      on the exhausted visit emits `workflow.loopback-limit`, `cap.breached`
+ *      and `run.failed` (`loop_limit_exceeded`, `failedNodeId: gate`).
+ *   7. `0258.replay-rearms` — gated also on `replay.modes ∋ replay`: a replay
+ *      fork whose prefix ends at round 1's marked completion asks the gate
+ *      again without deciding round 1 again.
+ *
+ * §B's admission refusals are not legs: v2 has no operation through which a
+ * client submits a definition (no workflow registration, no inline definition
+ * on createRun), so a host's refusal is not observable on the wire (RFC 0258
+ * §Falsifiability).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { gateFamily, v2RefValidator } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.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 { judgeApprovalData, judgeFailExhausted, judgeHistory, judgeRearm, judgeReplayRearm, judgeWithdrawn, markersOf, requestsOf, type Ev, type LoopFinding } from '../lib/bounded-loopback-witness.js';
+
+const DOC = 'workflow-definition.schema.json $defs/EdgeLoopback; run-event-payloads.schema.json $defs/nodeCompleted.loopback (RFC 0258)';
+const R = (slug: string): string => `openwop.requirement.0258.${slug}`;
+const REFINE = 'conformance-loopback-refine';
+const FAIL = 'conformance-loopback-refine-fail';
+const GATE = 'gate';
+const REARM = { gate: GATE, target: 'draft', edgeId: 'again', region: ['draft', 'gate'], forward: 'apply' };
+const FB = [{ scope: 'whole', text: 'conformance round one: shorter' }, { scope: 'whole', text: 'conformance round two: darker' }];
+
+const enc = (id: string): string => encodeURIComponent(id);
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+
+async function logOf(runId: string): Promise<Ev[]> {
+  const res = await http(() => driver.get(`/runs/${enc(runId)}/events/poll?timeout=1`));
+  const events = (res?.json as { events?: unknown } | null)?.events;
+  return Array.isArray(events) ? (events as Ev[]).filter((e) => typeof e.sequence === 'number').sort((a, b) => (a.sequence as number) - (b.sequence as number)) : [];
+}
+const TERMINAL = /^run\.(completed|failed|cancelled)$/;
+
+/** Poll until `done(log)` holds, or the bound passes; the log either way. */
+async function until(runId: string, done: (log: Ev[]) => boolean): Promise<{ log: Ev[]; ok: boolean }> {
+  const deadline = Date.now() + scaledTimeoutMs(20_000);
+  for (;;) {
+    const log = await logOf(runId);
+    if (done(log)) return { log, ok: true };
+    if (Date.now() > deadline || log.some((e) => typeof e.type === 'string' && TERMINAL.test(e.type))) return { log, ok: done(log) };
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+const asked = (n: number) => (log: Ev[]): boolean => requestsOf(log, GATE).length >= n;
+const resolve = (runId: string, resumeValue: unknown): Promise<OpenWOPResponse | null> => http(() => driver.post(`/runs/${enc(runId)}/interrupts/${enc(GATE)}`, { resumeValue }));
+const refine = (runId: string, i: number): Promise<OpenWOPResponse | null> => resolve(runId, { action: 'refine', refineFeedback: FB[i] });
+
+type Gate = { skip: ['inapplicable', string] } | { maxIterations: number };
+async function gateLoopback(fixture: string, needIterations: number): Promise<Gate> {
+  if (!isFixtureAdvertised(fixture)) return { skip: ['inapplicable', `fixture ${fixture} is not advertised`] };
+  const fam = await gateFamily('loopback');
+  if (!fam) return { skip: ['inapplicable', 'loopback family not advertised (gate recorded under openwop.family.loopback)'] };
+  const max = fam['maxIterations'];
+  if (typeof max !== 'number' || max < needIterations) return { skip: ['inapplicable', `loopback.maxIterations ${String(max)} is below the fixture's ${needIterations}`] };
+  return { maxIterations: max };
+}
+
+interface Drive { runId: string; afterOne: Ev[]; atExhausted: Ev[]; refusedStatus: number | undefined; refusedCode: string | undefined; statusAfterRefusal: unknown; final: Ev[] }
+let shared: Promise<Drive | { reason: string }> | undefined;
+/** The one `conformance-loopback-refine` run legs 2–5 read. */
+function drive(): Promise<Drive | { reason: string }> {
+  shared ??= (async () => {
+    const created = await http(() => driver.post('/runs', { workflowId: REFINE }));
+    const runId = (created?.json as { runId?: unknown } | null)?.runId;
+    if (created === null || created.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs (${REFINE}) answered ${created?.status ?? 'nothing'} ${readErrorCode(created?.json) ?? ''}`.trim() };
+    if (!(await until(runId, asked(1))).ok) return { reason: `the ${REFINE} run never asked its gate` };
+    const r1 = await refine(runId, 0);
+    if (r1?.status !== 200) return { reason: `the first refine answered ${r1?.status ?? 'nothing'} ${readErrorCode(r1?.json) ?? ''}`.trim() };
+    const one = await until(runId, asked(2));
+    if (!one.ok) return { reason: 'the gate was not asked a second time after one refine (no re-arm)' };
+    const r2 = await refine(runId, 1);
+    if (r2?.status !== 200) return { reason: `the second refine answered ${r2?.status ?? 'nothing'} ${readErrorCode(r2?.json) ?? ''}`.trim() };
+    const two = await until(runId, asked(3));
+    if (!two.ok) return { reason: 'the gate was not asked a third time after two refines' };
+    const r3 = await resolve(runId, { action: 'refine', refineFeedback: { scope: 'whole', text: 'conformance: past the cap' } });
+    const snap = await http(() => driver.get(`/runs/${enc(runId)}`));
+    const status = (snap?.json as { status?: unknown } | null)?.status;
+    const acc = await resolve(runId, { action: 'accept' });
+    if (acc?.status !== 200) return { reason: `accept answered ${acc?.status ?? 'nothing'} ${readErrorCode(acc?.json) ?? ''}`.trim() };
+    const end = await until(runId, (log) => log.some((e) => typeof e.type === 'string' && TERMINAL.test(e.type)));
+    return { runId, afterOne: one.log, atExhausted: two.log, refusedStatus: r3?.status, refusedCode: readErrorCode(r3?.json), statusAfterRefusal: status, final: end.log };
+  })();
+  return shared;
+}
+
+function expectAll(id: string, findings: readonly LoopFinding[]): void {
+  for (const x of findings) expect(x.ok, req(id, DOC, x.message)).toBe(true);
+}
+
+describe('v2 RFC 0258 — bounded loopback wire shape (server-free)', () => {
+  it('EdgeLoopback, the marker, ApprovalData.loopback, the cap kind and the facet validate as declared', () => {
+    const edge = v2RefValidator('workflow-definition.schema.json#/$defs/WorkflowEdge');
+    const base = { id: 'again', sourceNodeId: 'gate', targetNodeId: 'draft' };
+    expect(edge({ ...base, loopback: { on: 'refine', maxIterations: 3, historyInput: 'rounds' } }).ok, req(R('shape'), DOC, 'a loopback edge MUST validate')).toBe(true);
+    expect(edge({ ...base, loopback: { on: 'refine' } }).ok, req(R('shape'), DOC, 'maxIterations is required')).toBe(false);
+    expect(edge({ ...base, loopback: { on: 'refine', maxIterations: 0 } }).ok, req(R('shape'), DOC, 'maxIterations has minimum 1')).toBe(false);
+    expect(edge({ ...base, loopback: { on: 'reject', maxIterations: 2 } }).ok, req(R('shape'), DOC, 'on admits only refine')).toBe(false);
+    expect(edge({ ...base, loopback: { on: 'refine', maxIterations: 2, onExhausted: 'retry' } }).ok, req(R('shape'), DOC, 'onExhausted is withdraw or fail')).toBe(false);
+    for (const extra of [{ condition: { type: 'truthy', left: 'approved' } }, { sourceOutput: 'output' }, { targetInput: 'input' }, { triggerRule: 'all_success' }]) {
+      expect(edge({ ...base, ...extra, loopback: { on: 'refine', maxIterations: 2 } }).ok, req(R('shape'), DOC, `a loopback edge MUST NOT carry ${Object.keys(extra)[0]}`)).toBe(false);
+    }
+    expect(edge({ ...base, condition: { type: 'truthy', left: 'approved' } }).ok, req(R('shape'), DOC, 'a plain edge with a condition still validates')).toBe(true);
+    const done = v2RefValidator('run-event-payloads.schema.json#/$defs/nodeCompleted');
+    expect(done({ nodeId: 'gate', loopback: { edgeId: 'again', targetNodeId: 'draft', round: 1, rearmed: ['draft', 'gate'] } }).ok, req(R('shape'), DOC, 'the marker MUST validate')).toBe(true);
+    expect(done({ nodeId: 'gate', loopback: { edgeId: 'again', targetNodeId: 'draft', round: 0, rearmed: ['draft', 'gate'] } }).ok, req(R('shape'), DOC, 'round has minimum 1')).toBe(false);
+    expect(done({ nodeId: 'gate', loopback: { edgeId: 'again', targetNodeId: 'draft', round: 1, rearmed: ['gate'] } }).ok, req(R('shape'), DOC, 'rearmed holds at least the target and the gate')).toBe(false);
+    const approval = v2RefValidator('suspend-request.schema.json#/$defs/ApprovalData');
+    const data = { artifactId: 'a', artifactType: 'text', title: 't', actions: ['accept', 'refine'] };
+    expect(approval({ ...data, loopback: { round: 0, maxIterations: 2, exhausted: false } }).ok, req(R('shape'), DOC, 'ApprovalData.loopback MUST validate')).toBe(true);
+    expect(approval({ ...data, loopback: { round: 0, maxIterations: 2 } }).ok, req(R('shape'), DOC, 'exhausted is required')).toBe(false);
+    const cap = v2RefValidator('run-event-payloads.schema.json#/$defs/capBreached');
+    expect(cap({ kind: 'loopback-iterations', limit: 2, observed: 3 }).ok, req(R('shape'), DOC, 'cap.breached admits kind loopback-iterations')).toBe(true);
+    const facet = v2RefValidator('capabilities.schema.json#/properties/loopback');
+    const rec = { status: 'stable', since: '2.46', witness: 'witnessable-gated', maxIterations: 3 };
+    expect(facet({ ...rec, maxHistoryEntryBytes: 65536 }).ok, req(R('shape'), DOC, 'the loopback record MUST validate')).toBe(true);
+    expect(facet({ ...rec, maxHistoryEntryBytes: 1 }).ok, req(R('shape'), DOC, 'maxHistoryEntryBytes has minimum 4096')).toBe(false);
+    expect(facet(rec).ok, req(R('shape'), DOC, 'maxHistoryEntryBytes is required')).toBe(false);
+  });
+});
+
+describe('v2 RFC 0258 — bounded loopback (host)', () => {
+  it('a refine re-arms the region: the marker, a new visit of the target, a new key, nothing released forward', async () => {
+    const g = await gateLoopback(REFINE, 2);
+    if ('skip' in g) return softSkip(...g.skip);
+    const d = await drive();
+    if ('reason' in d) return softSkip('blocked', d.reason);
+    expectAll(R('refine-rearms'), judgeRearm(d.afterOne, REARM));
+  }, 120_000);
+
+  it('the target receives the round history rebuilt from the log, with no run-scoped bytes', async () => {
+    const g = await gateLoopback(REFINE, 2);
+    if ('skip' in g) return softSkip(...g.skip);
+    const d = await drive();
+    if ('reason' in d) return softSkip('blocked', d.reason);
+    expectAll(R('history-from-log'), judgeHistory(d.atExhausted, { target: 'draft', port: 'rounds', feedback: FB }));
+  }, 120_000);
+
+  it('each visit of the gate carries ApprovalData.loopback {round, maxIterations, exhausted}', async () => {
+    const g = await gateLoopback(REFINE, 2);
+    if ('skip' in g) return softSkip(...g.skip);
+    const d = await drive();
+    if ('reason' in d) return softSkip('blocked', d.reason);
+    expectAll(R('approval-data-loopback'), judgeApprovalData(d.atExhausted, GATE, [
+      { round: 0, maxIterations: 2, exhausted: false }, { round: 1, maxIterations: 2, exhausted: false }, { round: 2, maxIterations: 2, exhausted: true },
+    ]));
+  }, 120_000);
+
+  it('the exhausted visit withdraws refine, refuses a refine resume, and accept completes the run', async () => {
+    const g = await gateLoopback(REFINE, 2);
+    if ('skip' in g) return softSkip(...g.skip);
+    const d = await drive();
+    if ('reason' in d) return softSkip('blocked', d.reason);
+    expectAll(R('withdraw-refine'), judgeWithdrawn(d.atExhausted, GATE));
+    expect(d.refusedStatus, req(R('withdraw-refine'), DOC, 'a refine resume on the exhausted visit MUST answer 400')).toBe(400);
+    expect(d.refusedCode, req(R('withdraw-refine'), DOC, 'the refusal MUST carry validation_error')).toBe('validation_error');
+    expect(d.statusAfterRefusal, req(R('withdraw-refine'), DOC, 'the refused refine MUST leave the run waiting-approval')).toBe('waiting-approval');
+    expect(d.final.some((e) => e.type === 'run.completed'), req(R('withdraw-refine'), DOC, 'accept MUST complete the run')).toBe(true);
+    expect(d.final.filter((e) => e.type === 'node.started' && (e.nodeId ?? e.payload?.['nodeId']) === 'apply').length, req(R('withdraw-refine'), DOC, 'apply MUST run exactly once, after accept')).toBe(1);
+  }, 120_000);
+
+  it('under onExhausted: fail, a refine on the exhausted visit fails the run with loop_limit_exceeded', async () => {
+    const g = await gateLoopback(FAIL, 1);
+    if ('skip' in g) return softSkip(...g.skip);
+    const created = await http(() => driver.post('/runs', { workflowId: FAIL }));
+    const runId = (created?.json as { runId?: unknown } | null)?.runId;
+    if (created === null || created.status !== 201 || typeof runId !== 'string') return softSkip('blocked', `POST /runs (${FAIL}) answered ${created?.status ?? 'nothing'} ${readErrorCode(created?.json) ?? ''}`.trim());
+    if (!(await until(runId, asked(1))).ok) return softSkip('blocked', `the ${FAIL} run never asked its gate`);
+    const r1 = await refine(runId, 0);
+    if (r1?.status !== 200) return softSkip('blocked', `the first refine answered ${r1?.status ?? 'nothing'}`);
+    if (!(await until(runId, asked(2))).ok) return softSkip('blocked', 'the gate was not asked again after one refine (no re-arm)');
+    await refine(runId, 1);
+    const end = await until(runId, (log) => log.some((e) => typeof e.type === 'string' && TERMINAL.test(e.type)));
+    if (!end.ok) return softSkip('blocked', `the ${FAIL} run logged no terminal event within the bound`);
+    expectAll(R('fail-on-exhausted'), judgeFailExhausted(end.log, GATE, 1));
+  }, 120_000);
+
+  it('a replay fork at round 1\'s marked completion re-arms and asks the gate again', async () => {
+    const g = await gateLoopback(REFINE, 2);
+    if ('skip' in g) return softSkip(...g.skip);
+    const replay = await gateFamily('replay');
+    if (!replay) return softSkip('inapplicable', 'replay family not advertised (gate recorded under openwop.family.replay)');
+    if (!(Array.isArray(replay['modes']) && replay['modes'].includes('replay'))) return softSkip('inapplicable', 'replay.modes does not list replay');
+    const d = await drive();
+    if ('reason' in d) return softSkip('blocked', d.reason);
+    const mark = markersOf(d.final, GATE)[0];
+    if (typeof mark?.sequence !== 'number') return softSkip('blocked', 'the source run logged no marked gate completion to fork from');
+    const fromSeq = mark.sequence + 1;
+    const fork = await http(() => driver.post(`/runs/${enc(d.runId)}:fork`, { mode: 'replay', fromSeq }));
+    const forkId = (fork?.json as { runId?: unknown } | null)?.runId;
+    if (fork === null || fork.status !== 201 || typeof forkId !== 'string') return softSkip('blocked', `POST /runs/{runId}:fork answered ${fork?.status ?? 'nothing'} ${readErrorCode(fork?.json) ?? ''} — forkRun owns that contract`.trim());
+    const k = await until(forkId, (log) => requestsOf(log, GATE).some((e) => typeof e.sequence === 'number' && e.sequence >= fromSeq));
+    expectAll(R('replay-rearms'), judgeReplayRearm(k.log, GATE, fromSeq));
+  }, 120_000);
+});

package/src/scenarios/v2-interrupt-resolved-via.test.ts

@@ -0,0 +1,257 @@
+/**
+ * v2 — `interrupt.resolved` records the instrument of a token resolution
+ * (RFC 0259; the rules are `$defs/interruptResolved.resolvedBy` and
+ * `.resolvedVia` in `schemas/v2/run-event-payloads.schema.json`, and the
+ * `interrupt.resolvedVia` facet in `spec/v2/facets/interrupt.schema.json`).
+ *
+ * Server-free (always on):
+ *   1. `0259.shape` — `resolvedVia` is a closed object with a REQUIRED
+ *      `scheme` from a closed vocabulary; `tokenRef` is opaque; `boundTo` is a
+ *      Subject of kind `user` or `agent` with a non-legacy issuer.
+ *
+ * Host legs — each needs the resume token, which v2 gives no unaided way to
+ * read (interrupt.md: the signed-token surface is a SHOULD and the suite cannot
+ * mint a token). They are gated on the seams profile and the
+ * `readInterruptToken` seam (RFC 0259 §C.1): unadvertised → `inapplicable`; an
+ * advertised profile with the seam unwired → `blocked`.
+ *   2. `0259.token-resolve-names-no-subject` — UNCONDITIONAL (§A.1): an
+ *      unauthenticated `POST /interrupts/{token}` records no `resolvedBy`.
+ *   3. `0259.resolved-via-recorded` — gated on `interrupt.resolvedVia: true`:
+ *      the same resolution records `resolvedVia.scheme: "interrupt-token"`
+ *      and, with no binding asked for, no `boundTo`.
+ *   4. `0259.token-ref-opaque` — gated as 3, and on `tokenRef` being present:
+ *      it is not the token, contains no segment of it, and is not a prefix of
+ *      a digest of the token or a segment in hex, base64 or base64url.
+ *   5. `0259.run-resolve-no-via` — gated as 3: a run-scoped resolution
+ *      records no `resolvedVia`.
+ *   6. `0259.bound-to-caller` — gated as 3, and on the seam returning
+ *      `resumeValueMembers` for `bind: true`: `boundTo` deep-equals the
+ *      `run.started.owner.subject` of the run the caller created.
+ *   7. `0259.forged-binding-binds-no-one` — gated as 6: the same binding with
+ *      every returned member altered by one character (a token bound to the
+ *      caller, presented as bound to someone else) records no `boundTo`; the
+ *      host may refuse the resolution instead.
+ *
+ * Fork copying `resolvedVia` verbatim (§A.5) is not a leg here: it is the
+ * general rule that a fork copies the recorded resolution, witnessed for
+ * `decision` / `action` / `reason` by `v2-approval-reject-disposition` leg 9.
+ *
+ * @see RFCS/0259-interrupt-resolved-via.md
+ * @see spec/v2/core/interrupt.md §Resolve surfaces
+ */
+
+import { createHash } from 'node:crypto';
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2RefValidator } from '../lib/v2.js';
+import { SEAMS_PREFIX, seamsProfileAdvertised } from '../lib/seams.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { seamAbsent, softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { scaledTimeoutMs } from '../lib/polling.js';
+
+const DOC = 'run-event-payloads.schema.json $defs/interruptResolved.resolvedBy + .resolvedVia (RFC 0259)';
+const R = (slug: string): string => `openwop.requirement.0259.${slug}`;
+const FIXTURE = 'conformance-approval';
+const NODE_ID = 'gate';
+const SEAM = `${SEAMS_PREFIX}/sample/interrupts/token`;
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+interface Ev { type?: string; nodeId?: string; sequence?: number; payload?: Record<string, unknown> }
+
+const enc = (id: string): string => encodeURIComponent(id);
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const obj = (x: unknown): Record<string, unknown> | undefined => (x !== null && typeof x === 'object' && !Array.isArray(x) ? (x as Record<string, unknown>) : undefined);
+
+async function snapshot(runId: string): Promise<Record<string, unknown> | null> {
+  const res = await http(() => driver.get(`/runs/${enc(runId)}`));
+  return res?.status === 200 ? (obj(res.json) ?? null) : null;
+}
+async function waitStatus(runId: string, wanted: ReadonlySet<string>): Promise<Record<string, unknown> | null> {
+  const deadline = Date.now() + scaledTimeoutMs(10_000);
+  for (;;) {
+    const s = await snapshot(runId);
+    if (s !== null && wanted.has(String(s['status']))) return s;
+    if (Date.now() > deadline) return s;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+async function logOf(runId: string): Promise<Ev[]> {
+  const res = await http(() => driver.get(`/runs/${enc(runId)}/events/poll?timeout=1`));
+  const events = obj(res?.json)?.['events'];
+  return Array.isArray(events) ? (events as Ev[]) : [];
+}
+async function resolvedPayload(runId: string): Promise<Record<string, unknown> | undefined> {
+  const deadline = Date.now() + scaledTimeoutMs(10_000);
+  for (;;) {
+    const e = (await logOf(runId)).find((x) => x.type === 'interrupt.resolved' && x.nodeId === NODE_ID);
+    if (e) return obj(e.payload);
+    if (Date.now() > deadline) return undefined;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+/** A suspended `conformance-approval` run, or why there is none. */
+async function suspended(): Promise<{ runId: string } | { reason: string }> {
+  const res = await http(() => driver.post('/runs', { workflowId: FIXTURE }));
+  const runId = obj(res?.json)?.['runId'];
+  if (res === null || res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs (${FIXTURE}) answered ${res?.status ?? 'nothing'} ${readErrorCode(res?.json) ?? ''}`.trim() };
+  const s = await waitStatus(runId, new Set(['waiting-approval', ...TERMINAL]));
+  if (s?.['status'] !== 'waiting-approval') return { reason: `the ${FIXTURE} run did not suspend on its approval gate (status ${String(s?.['status'])})` };
+  return { runId };
+}
+
+type Gate = { inapplicable: string } | { blocked: string } | { ok: true; doc: Record<string, unknown> | null };
+async function seamGate(): Promise<Gate> {
+  if (!isFixtureAdvertised(FIXTURE)) return { inapplicable: `fixture ${FIXTURE} is not advertised` };
+  const d = await v2Discovery().catch(() => null);
+  if (!seamsProfileAdvertised(d)) return { inapplicable: 'seams profile not advertised — v2 gives the suite no unaided way to read a resume token (interrupt.md §Resolve surfaces), so a token resolution is seam-gated' };
+  return { ok: true, doc: d };
+}
+const facetOn = (doc: Record<string, unknown> | null): boolean => obj(doc?.['interrupt'])?.['resolvedVia'] === true;
+
+/** Suspend, read the token (and a binding when asked), resolve accept through the token surface unauthenticated. */
+const alter = (v: unknown): unknown => (typeof v === 'string' && v.length > 0 ? `${v.slice(0, -1)}${v.endsWith('x') ? 'y' : 'x'}` : v);
+
+async function tokenResolution(bind: boolean, forge = false): Promise<{ runId: string; token: string; bound: boolean; refused: boolean; payload: Record<string, unknown> | undefined } | { blocked: string } | { inapplicable: string }> {
+  const s = await suspended();
+  if ('reason' in s) return { blocked: s.reason };
+  const seam = await http(() => driver.post(SEAM, { runId: s.runId, nodeId: NODE_ID, ...(bind ? { bind: true } : {}) }));
+  const token = obj(seam?.json)?.['token'];
+  if (seam === null || seam.status !== 200 || typeof token !== 'string') return { blocked: `the readInterruptToken seam answered ${seam?.status ?? 'nothing'} (RFC 0259 §C.1) — the token resolution is unobserved` };
+  const members = obj(obj(seam.json)?.['resumeValueMembers']);
+  if (bind && members === undefined) return { inapplicable: 'the host returned no resumeValueMembers for bind: true — it binds no presentation to this caller' };
+  const presented = forge && members !== undefined ? Object.fromEntries(Object.entries(members).map(([k, v]) => [k, alter(v)])) : members;
+  const res = await http(() => driver.post(`/interrupts/${enc(token)}`, { resumeValue: { action: 'accept', ...(presented ?? {}) } }, { authenticated: false }));
+  if (forge && res !== null && (res.status === 400 || res.status === 403)) return { runId: s.runId, token, bound: false, refused: true, payload: undefined };
+  if (res === null || res.status < 200 || res.status >= 300) return { blocked: `POST /interrupts/{token} answered ${res?.status ?? 'nothing'} ${readErrorCode(res?.json) ?? ''} — interrupt resolution owns that contract` };
+  return { runId: s.runId, token, bound: members !== undefined, refused: false, payload: await resolvedPayload(s.runId) };
+}
+
+let unbound: ReturnType<typeof tokenResolution> | undefined;
+const unboundResolution = (): ReturnType<typeof tokenResolution> => (unbound ??= tokenResolution(false));
+
+/** sha256 of `s` in hex, base64 and base64url — the bare digests a token-derived tokenRef would carry. */
+function digests(s: string): string[] {
+  const d = createHash('sha256').update(s).digest();
+  return [d.toString('hex'), d.toString('base64').replace(/=+$/, ''), d.toString('base64url')];
+}
+/**
+ * Why `tokenRef` is not opaque, if it is not. A tokenRef carrying a bare digest
+ * of the token, or any prefix of one, shares an 8-character run with that
+ * digest; for an independent value the chance of that is negligible (an
+ * 8-character run over a 64-symbol alphabet), so the test has no practical
+ * false positive and catches the truncated-hash convention.
+ */
+function tokenRefFindings(tokenRef: string, token: string): string[] {
+  const out: string[] = [];
+  const segments = [token, ...token.split('.').filter((x) => x.length >= 8)];
+  const windows = Array.from({ length: Math.max(0, tokenRef.length - 7) }, (_, i) => tokenRef.slice(i, i + 8));
+  for (const seg of segments) {
+    if (tokenRef.includes(seg)) out.push('tokenRef MUST NOT equal or contain the token or any of its segments');
+    if (digests(seg).some((d) => windows.some((w) => d.includes(w)))) out.push('tokenRef MUST NOT be computable from the token without a host-held secret: it shares a run with a bare sha256 of the token or a segment');
+  }
+  return out;
+}
+
+describe('v2 RFC 0259 — resolvedVia wire shape (server-free)', () => {
+  it('resolvedVia is a closed object with a registered scheme; boundTo is a non-legacy user or agent Subject', () => {
+    const v = v2RefValidator('run-event-payloads.schema.json#/$defs/interruptResolved');
+    const base = { nodeId: 'gate', interruptId: 'acme/0123456789abcdef', kind: 'approval', decision: 'granted', action: 'accept' };
+    const person = { issuer: 'urn:example:session', subjectId: 'u_7f3a9c1e', tenant: 'acme', lane: 'session', kind: 'user' };
+    expect(v(base).ok, req(R('shape'), DOC, 'interrupt.resolved without resolvedVia MUST validate')).toBe(true);
+    expect(v({ ...base, resolvedVia: { scheme: 'interrupt-token' } }).ok, req(R('shape'), DOC, 'a bare token resolution (no resolvedBy) with resolvedVia MUST validate')).toBe(true);
+    expect(v({ ...base, resolvedVia: { scheme: 'interrupt-token', tokenRef: 'tr_0000synthetic0000', boundTo: person } }).ok, req(R('shape'), DOC, 'tokenRef and a user boundTo MUST validate')).toBe(true);
+    expect(v({ ...base, resolvedVia: {} }).ok, req(R('shape'), DOC, 'scheme is REQUIRED')).toBe(false);
+    expect(v({ ...base, resolvedVia: { scheme: 'share-link' } }).ok, req(R('shape'), DOC, 'an unregistered scheme MUST fail')).toBe(false);
+    expect(v({ ...base, resolvedVia: { scheme: 'interrupt-token', token: 'ow2.hs256.k.p.m' } }).ok, req(R('shape'), DOC, 'resolvedVia is closed: a token member MUST fail')).toBe(false);
+    expect(v({ ...base, resolvedVia: { scheme: 'interrupt-token', tokenRef: 'ow2.hs256.k.p.m' } }).ok, req(R('shape'), DOC, 'tokenRef is opaque: a dotted token-shaped value MUST fail the grammar')).toBe(false);
+    expect(v({ ...base, resolvedVia: { scheme: 'interrupt-token', boundTo: { ...person, kind: 'anonymous', lane: 'anonymous' } } }).ok, req(R('shape'), DOC, 'boundTo of kind anonymous MUST fail')).toBe(false);
+    expect(v({ ...base, resolvedVia: { scheme: 'interrupt-token', boundTo: { ...person, kind: 'workload', lane: 'workload' } } }).ok, req(R('shape'), DOC, 'boundTo of kind workload MUST fail')).toBe(false);
+    expect(v({ ...base, resolvedVia: { scheme: 'interrupt-token', boundTo: { ...person, issuer: 'urn:openwop:legacy' } } }).ok, req(R('shape'), DOC, 'boundTo with the legacy issuer MUST fail')).toBe(false);
+  });
+});
+
+describe('v2 RFC 0259 — token resolutions (host, seam-gated)', () => {
+  it('an unauthenticated token resolution records no resolvedBy', async () => {
+    const g = await seamGate();
+    if ('inapplicable' in g) return softSkip('inapplicable', g.inapplicable);
+    if ('blocked' in g) return seamAbsent(g.blocked);
+    const r = await unboundResolution();
+    if ('inapplicable' in r) return softSkip('inapplicable', r.inapplicable);
+    if ('blocked' in r) return seamAbsent(r.blocked);
+    expect(r.payload, req(R('token-resolve-names-no-subject'), DOC, 'the token resolution logged no interrupt.resolved for the gate')).toBeDefined();
+    expect(r.payload?.['resolvedBy'], req(R('token-resolve-names-no-subject'), DOC, 'a resolution whose request authenticated nothing MUST NOT record resolvedBy (§A.1)')).toBeUndefined();
+  });
+
+  it('a host advertising interrupt.resolvedVia records scheme interrupt-token and no boundTo on an unbound token resolution', async () => {
+    const g = await seamGate();
+    if ('inapplicable' in g) return softSkip('inapplicable', g.inapplicable);
+    if ('blocked' in g) return seamAbsent(g.blocked);
+    if (!facetOn(g.doc)) return softSkip('inapplicable', 'interrupt.resolvedVia is not advertised');
+    const r = await unboundResolution();
+    if ('inapplicable' in r) return softSkip('inapplicable', r.inapplicable);
+    if ('blocked' in r) return seamAbsent(r.blocked);
+    const via = obj(r.payload?.['resolvedVia']);
+    expect(via?.['scheme'], req(R('resolved-via-recorded'), DOC, 'a host advertising interrupt.resolvedVia MUST record resolvedVia.scheme "interrupt-token" on a token resolution')).toBe('interrupt-token');
+    expect(via?.['boundTo'], req(R('resolved-via-recorded'), DOC, 'boundTo MUST be absent when the host bound the presentation to no one')).toBeUndefined();
+  });
+
+  it('tokenRef, when present, is not the token and not computable from it', async () => {
+    const g = await seamGate();
+    if ('inapplicable' in g) return softSkip('inapplicable', g.inapplicable);
+    if ('blocked' in g) return seamAbsent(g.blocked);
+    if (!facetOn(g.doc)) return softSkip('inapplicable', 'interrupt.resolvedVia is not advertised');
+    const r = await unboundResolution();
+    if ('inapplicable' in r) return softSkip('inapplicable', r.inapplicable);
+    if ('blocked' in r) return seamAbsent(r.blocked);
+    const tokenRef = obj(r.payload?.['resolvedVia'])?.['tokenRef'];
+    if (typeof tokenRef !== 'string') return softSkip('inapplicable', 'the host records no tokenRef (OPTIONAL)');
+    expect(tokenRefFindings(tokenRef, r.token), req(R('token-ref-opaque'), DOC, 'tokenRef MUST NOT equal, contain or be a bare digest of the token or its segments (§A.3)')).toEqual([]);
+  });
+
+  it('a run-scoped resolution records no resolvedVia', async () => {
+    const g = await seamGate();
+    if ('inapplicable' in g) return softSkip('inapplicable', g.inapplicable);
+    if ('blocked' in g) return seamAbsent(g.blocked);
+    if (!facetOn(g.doc)) return softSkip('inapplicable', 'interrupt.resolvedVia is not advertised');
+    const s = await suspended();
+    if ('reason' in s) return seamAbsent(s.reason);
+    const res = await http(() => driver.post(`/runs/${enc(s.runId)}/interrupts/${enc(NODE_ID)}`, { resumeValue: { action: 'accept' } }));
+    if (res === null || res.status < 200 || res.status >= 300) return seamAbsent(`the run-scoped resolve answered ${res?.status ?? 'nothing'} — interrupt resolution owns that contract`);
+    const payload = await resolvedPayload(s.runId);
+    expect(payload, req(R('run-resolve-no-via'), DOC, 'the run-scoped resolution logged no interrupt.resolved for the gate')).toBeDefined();
+    expect(payload?.['resolvedVia'], req(R('run-resolve-no-via'), DOC, 'resolvedVia MUST NOT be recorded on a resolution that presented no token')).toBeUndefined();
+  });
+
+  it('a binding the host made to the caller is recorded as boundTo, equal to the caller\'s owner subject', async () => {
+    const g = await seamGate();
+    if ('inapplicable' in g) return softSkip('inapplicable', g.inapplicable);
+    if ('blocked' in g) return seamAbsent(g.blocked);
+    if (!facetOn(g.doc)) return softSkip('inapplicable', 'interrupt.resolvedVia is not advertised');
+    const r = await tokenResolution(true);
+    if ('inapplicable' in r) return softSkip('inapplicable', r.inapplicable);
+    if ('blocked' in r) return seamAbsent(r.blocked);
+    const owner = obj(obj((await logOf(r.runId)).find((e) => e.type === 'run.started')?.payload?.['owner'])?.['subject']);
+    if (owner === undefined) return seamAbsent('run.started carried no owner.subject to compare boundTo against');
+    expect(obj(r.payload?.['resolvedVia'])?.['boundTo'], req(R('bound-to-caller'), DOC, 'boundTo MUST be the Subject the host bound the presentation to, built with the owner.subject mapping (§A.4)')).toEqual(owner);
+    expect(r.payload?.['resolvedBy'], req(R('bound-to-caller'), DOC, 'a bound but unauthenticated presentation still MUST NOT record resolvedBy (§A.1)')).toBeUndefined();
+  });
+
+  it('a binding altered to claim someone else binds no one', async () => {
+    const g = await seamGate();
+    if ('inapplicable' in g) return softSkip('inapplicable', g.inapplicable);
+    if ('blocked' in g) return seamAbsent(g.blocked);
+    if (!facetOn(g.doc)) return softSkip('inapplicable', 'interrupt.resolvedVia is not advertised');
+    const r = await tokenResolution(true, true);
+    if ('inapplicable' in r) return softSkip('inapplicable', r.inapplicable);
+    if ('blocked' in r) return seamAbsent(r.blocked);
+    if (r.refused) {
+      expect(r.refused, req(R('forged-binding-binds-no-one'), DOC, 'refusing a presentation whose binding does not verify satisfies §A.4')).toBe(true);
+    } else {
+      expect(obj(r.payload?.['resolvedVia'])?.['boundTo'], req(R('forged-binding-binds-no-one'), DOC, 'a host MUST NOT set boundTo from a binding it did not make (§A.4)')).toBeUndefined();
+      expect(r.payload?.['resolvedBy'], req(R('forged-binding-binds-no-one'), DOC, 'and MUST NOT record the claimed name in resolvedBy (§A.1)')).toBeUndefined();
+    }
+  });
+});