@openwop/openwop-conformance 2.46.42 → 2.46.44

package/src/lib/bounded-loopback-witness.ts

@@ -0,0 +1,125 @@
+/**
+ * RFC 0258 — judges for `v2-bounded-loopback.test.ts`. Pure functions over a
+ * run's event log, so each can be shown to fail on a sabotaged log
+ * (`bounded-loopback-witness.test.ts`). Rules: `$defs/EdgeLoopback` in
+ * `schemas/v2/workflow-definition.schema.json`, `$defs/nodeCompleted.loopback`
+ * in `run-event-payloads.schema.json`, `$defs/ApprovalData.loopback` in
+ * `suspend-request.schema.json`.
+ */
+
+export interface Ev { type?: string; sequence?: number; nodeId?: string; payload?: Record<string, unknown> }
+export interface LoopFinding { ok: boolean; message: string }
+
+const ok = (cond: boolean, message: string): LoopFinding => ({ ok: cond, message });
+const nodeOf = (e: Ev): string | undefined => (typeof e.nodeId === 'string' ? e.nodeId : (e.payload?.['nodeId'] as string | undefined));
+const of = (log: readonly Ev[], type: string, nodeId?: string): Ev[] => log.filter((e) => e.type === type && (nodeId === undefined || nodeOf(e) === nodeId));
+
+/** Every `interrupt.requested` raised by `gate`, in log order. */
+export function requestsOf(log: readonly Ev[], gate: string): Ev[] { return of(log, 'interrupt.requested', gate); }
+
+/** The `ApprovalData.loopback` of one request, or undefined. */
+export function approvalLoopback(e: Ev | undefined): Record<string, unknown> | undefined {
+  const data = e?.payload?.['data'] as Record<string, unknown> | undefined;
+  const lb = data?.['loopback'];
+  return lb && typeof lb === 'object' ? (lb as Record<string, unknown>) : undefined;
+}
+
+/** The gate's `node.completed` events that carry the §C.1 marker. */
+export function markersOf(log: readonly Ev[], gate: string): Ev[] {
+  return of(log, 'node.completed', gate).filter((e) => e.payload?.['loopback'] !== undefined);
+}
+
+/**
+ * `0258.refine-rearms` — after one refine: the gate's completion carries the
+ * marker for round 1 naming every region node, the target starts again, the
+ * gate is asked again under a different key, and the gate's forward target
+ * never started.
+ */
+export function judgeRearm(log: readonly Ev[], o: { gate: string; target: string; edgeId: string; region: readonly string[]; forward: string }): LoopFinding[] {
+  const marks = markersOf(log, o.gate);
+  const m = marks[0]?.payload?.['loopback'] as Record<string, unknown> | undefined;
+  const reqs = requestsOf(log, o.gate);
+  const keys = reqs.map((e) => e.payload?.['key']);
+  return [
+    ok(marks.length === 1, `the gate's node.completed MUST carry loopback after one refine (found ${marks.length} marked completion(s))`),
+    ok(m?.['edgeId'] === o.edgeId && m?.['targetNodeId'] === o.target && m?.['round'] === 1, `the marker MUST read {edgeId: ${o.edgeId}, targetNodeId: ${o.target}, round: 1} (got ${JSON.stringify(m)})`),
+    ok(JSON.stringify(m?.['rearmed']) === JSON.stringify(o.region), `rearmed MUST list the region in nodes[] order, ${JSON.stringify(o.region)} (got ${JSON.stringify(m?.['rearmed'])})`),
+    ok(of(log, 'node.started', o.target).length === 2, `the target MUST start again as a new visit (node.started ×${of(log, 'node.started', o.target).length}, want 2)`),
+    ok(reqs.length === 2 && typeof keys[0] === 'string' && typeof keys[1] === 'string' && keys[0] !== keys[1], `the gate MUST be asked again under a different key (interrupt.requested ×${reqs.length}, keys ${JSON.stringify(keys)})`),
+    ok(of(log, 'node.started', o.forward).length === 0, `nothing leaves the region on a refine: ${o.forward} MUST NOT start before accept`),
+  ];
+}
+
+/**
+ * `0258.history-from-log` — the target (an input-echoing node) shows the round
+ * history it received: `[]` on its first visit, then one entry per round
+ * holding exactly `round`, the target's own outputs from that round, and the
+ * refine feedback. No other key, so no timestamp, principal, run id or key.
+ */
+export function judgeHistory(log: readonly Ev[], o: { target: string; port: string; feedback: readonly unknown[] }): LoopFinding[] {
+  const done = of(log, 'node.completed', o.target).map((e) => (e.payload?.['outputs'] ?? {}) as Record<string, unknown>);
+  const out: LoopFinding[] = [ok(done.length === o.feedback.length + 1, `the target MUST complete once per visit (${done.length} completion(s), want ${o.feedback.length + 1})`)];
+  done.forEach((outputs, visit) => {
+    const h = outputs[o.port];
+    if (!Array.isArray(h)) { out.push(ok(false, `visit ${visit}: the ${o.port} input MUST be an array (got ${JSON.stringify(h)})`)); return; }
+    out.push(ok(h.length === visit, `visit ${visit}: history MUST hold ${visit} entr${visit === 1 ? 'y' : 'ies'} (got ${h.length})`));
+    h.forEach((entry: unknown, i: number) => {
+      const en = (entry ?? {}) as Record<string, unknown>;
+      const extra = Object.keys(en).filter((k) => !['round', 'outputs', 'refineFeedback'].includes(k));
+      out.push(ok(en['round'] === i + 1, `visit ${visit} entry ${i}: round MUST be ${i + 1}, oldest first (got ${JSON.stringify(en['round'])})`));
+      out.push(ok(JSON.stringify(en['outputs']) === JSON.stringify(done[i]), `visit ${visit} entry ${i}: outputs MUST be the target's own round-${i + 1} outputs`));
+      out.push(ok(JSON.stringify(en['refineFeedback']) === JSON.stringify(o.feedback[i]), `visit ${visit} entry ${i}: refineFeedback MUST be round ${i + 1}'s (got ${JSON.stringify(en['refineFeedback'])})`));
+      out.push(ok(extra.length === 0, `visit ${visit} entry ${i}: an entry MUST carry no other key (found ${JSON.stringify(extra)})`));
+    });
+  });
+  return out;
+}
+
+/** `0258.approval-data-loopback` — each visit's `ApprovalData.loopback` reads the expected triple. */
+export function judgeApprovalData(log: readonly Ev[], gate: string, want: ReadonlyArray<{ round: number; maxIterations: number; exhausted: boolean }>): LoopFinding[] {
+  const got = requestsOf(log, gate).map(approvalLoopback);
+  const out: LoopFinding[] = [ok(got.length === want.length, `the gate MUST be asked ${want.length} time(s) (got ${got.length})`)];
+  want.forEach((w, i) => out.push(ok(JSON.stringify(got[i]) === JSON.stringify(w), `visit ${i}: ApprovalData.loopback MUST be ${JSON.stringify(w)} (got ${JSON.stringify(got[i])})`)));
+  return out;
+}
+
+/** `0258.withdraw-refine` — the exhausted visit omits `refine` from `actions`. */
+export function judgeWithdrawn(log: readonly Ev[], gate: string): LoopFinding[] {
+  const last = requestsOf(log, gate).at(-1);
+  const actions = (last?.payload?.['data'] as Record<string, unknown> | undefined)?.['actions'];
+  return [
+    ok(approvalLoopback(last)?.['exhausted'] === true, 'the last visit MUST read exhausted: true'),
+    ok(Array.isArray(actions) && !actions.includes('refine') && actions.length > 0, `the exhausted visit MUST omit refine from actions and keep the others (got ${JSON.stringify(actions)})`),
+  ];
+}
+
+/** `0258.fail-on-exhausted` — a refine on the exhausted visit, under `onExhausted: fail`. */
+export function judgeFailExhausted(log: readonly Ev[], gate: string, maxIterations: number): LoopFinding[] {
+  const limit = of(log, 'workflow.loopback-limit')[0];
+  const cap = of(log, 'cap.breached').find((e) => e.payload?.['kind'] === 'loopback-iterations');
+  const failed = of(log, 'run.failed')[0];
+  const err = (failed?.payload?.['error'] ?? {}) as Record<string, unknown>;
+  const seq = (e: Ev | undefined): number => (typeof e?.sequence === 'number' ? e.sequence : Number.NaN);
+  return [
+    ok(limit?.payload?.['nodeId'] === gate && limit?.payload?.['iterations'] === maxIterations && limit?.payload?.['limit'] === maxIterations, `workflow.loopback-limit MUST read {nodeId: ${gate}, iterations: ${maxIterations}, limit: ${maxIterations}} (got ${JSON.stringify(limit?.payload)})`),
+    ok(cap !== undefined && cap.payload?.['limit'] === maxIterations && cap.payload?.['observed'] === maxIterations + 1, `cap.breached {kind: loopback-iterations, limit: ${maxIterations}, observed: ${maxIterations + 1}} MUST be emitted (got ${JSON.stringify(cap?.payload)})`),
+    ok(seq(limit) < seq(cap) && seq(cap) < seq(failed), 'the order MUST be workflow.loopback-limit, then cap.breached, then run.failed'),
+    ok(err['code'] === 'loop_limit_exceeded', `run.failed MUST carry loop_limit_exceeded (got ${JSON.stringify(err['code'])})`),
+    ok(failed?.payload?.['failedNodeId'] === gate, `run.failed.failedNodeId MUST name the gate (got ${JSON.stringify(failed?.payload?.['failedNodeId'])})`),
+  ];
+}
+
+/**
+ * `0258.replay-rearms` — a replay fork whose prefix ends at the marked
+ * completion reaches the gate's second visit: a new request for the gate after
+ * the fork point, and no resolution of the gate after it (round 1 is not
+ * decided again).
+ */
+export function judgeReplayRearm(fork: readonly Ev[], gate: string, fromSeq: number): LoopFinding[] {
+  const after = fork.filter((e) => typeof e.sequence === 'number' && e.sequence >= fromSeq);
+  return [
+    ok(of(after, 'interrupt.requested', gate).length === 1, `the fork MUST re-arm and ask the gate again after the marker (requests after fromSeq: ${of(after, 'interrupt.requested', gate).length})`),
+    ok(of(after, 'interrupt.resolved', gate).length === 0, 'the fork MUST NOT decide round 1 again (no interrupt.resolved for the gate after fromSeq)'),
+    ok(!after.some((e) => e.type === 'run.completed' || e.type === 'run.failed'), 'the fork MUST wait at the gate, not settle the run'),
+  ];
+}

package/src/scenarios/fixtures-valid.test.ts

@@ -41,6 +41,13 @@ describe('fixtures: workflow-definition schema validity', () => {
   }
   // The root schema is already registered under its $id above; compile via getSchema.
   const validate = ajv.getSchema('workflow-definition.schema.json') ?? ajv.compile(JSON.parse(readFileSync(SCHEMA_PATH, 'utf8')));
+  // The v2 tree, for fixtures tagged `v2-only` (below). Loaded here rather than
+  // through lib/v2.ts, which imports the driver and would make this file host-bound.
+  const ajv2 = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv2);
+  const V2_DIR = join(SCHEMAS_DIR, 'v2');
+  for (const file of readdirSync(V2_DIR).filter((f) => f.endsWith('.schema.json'))) ajv2.addSchema(JSON.parse(readFileSync(join(V2_DIR, file), 'utf8')) as Record<string, unknown>);
+  const validateV2 = ajv2.getSchema('https://openwop.dev/spec/v2/workflow-definition.schema.json');
 
   const files = readdirSync(FIXTURES_DIR)
     .filter((f) => f.endsWith('.json')) // top-level only — sub-dirs hold non-workflow fixtures
@@ -53,8 +60,13 @@ describe('fixtures: workflow-definition schema validity', () => {
   for (const file of files) {
     it(`${file} validates against workflow-definition.schema.json`, () => {
       const data = JSON.parse(readFileSync(join(FIXTURES_DIR, file), 'utf8'));
-      const ok = validate(data);
-      const errors = (validate.errors ?? [])
+      // A fixture tagged `v2-only` uses a construct the frozen v1 wire cannot
+      // carry (RFC 0258's `WorkflowEdge.loopback`), so it is judged by the v2
+      // schema instead. v1 is end-of-support (RFC 0234) and is never edited.
+      const v2Only = Array.isArray(data?.metadata?.tags) && data.metadata.tags.includes('v2-only');
+      const judge = v2Only && validateV2 ? validateV2 : validate;
+      const ok = v2Only && !validateV2 ? false : judge(data);
+      const errors = (judge.errors ?? [])
         .map((e: ErrorObject) => `${e.instancePath || '/'}: ${e.message}`)
         .join('\n');
       expect(ok, req('openwop.it.fixtures-valid.validates-against-workflow-definition-schema-json', 'fixtures-valid.test.ts (no spec citation in file)', `Fixture ${file} fails workflow-definition schema:\n${errors}`)).toBe(true);

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);
+});