@openwop/openwop-conformance 2.33.2 → 2.34.1

package/src/scenarios/v2-durability-recovery.test.ts

@@ -74,6 +74,7 @@ import { pollUntilTerminal, scaledTimeoutMs } from '../lib/polling.js';
 import { req } from '../lib/requirement-ids.js';
 import { receiverBinding, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
 import { watchForResumption, type Observation, type Watch } from '../lib/durability-watch.js';
+import { noteEvidence, parseRecoveryBounds, EVIDENCE_NAME_PATTERN } from '../lib/durability-evidence.js';
 
 const FIXTURE = 'conformance-noop';
 const FAILURE_FIXTURE = 'conformance-failure';
@@ -186,6 +187,32 @@ const KILL_ROW_TIMEOUT_MS = OBSERVATION_CEILING_MS + 120_000;
 /** Used only when the host serves no bound to read; named in the row's detail. */
 const UNDECLARED_BOUND_FALLBACK_MS = 60_000;
 
+/**
+ * The declared recovery bounds, PER CLASS, read off the seam and normalised.
+ *
+ * Three response shapes are accepted, because the seam is non-normative and two
+ * hosts built it before this was written down:
+ *   { classes: [{ class, bound, terms[] }] }          — the preferred shape
+ *   { classes: { <name>: { bound, terms[] } } }       — a map keyed by class
+ *   { bound, terms[], class? }                        — one class; named `class`
+ *                                                       or, absent that, `default`
+ * A top-level scalar `bound` beside `classes` is IGNORED: Unresolved Question 1
+ * resolved per class, and a convenience total is the aggregation it rejects.
+ * Only `{ name, ms }` survives from a term — free text a host attaches (the
+ * reference host's `enforcedBy`) never reaches a published bundle.
+ */
+function readClasses(json: unknown): unknown[] | null {
+  const body = (json as { classes?: unknown; class?: unknown; bound?: unknown; terms?: unknown } | null) ?? {};
+  const strip = (cls: unknown, e: { bound?: unknown; terms?: unknown }): unknown => ({
+    class: cls, bound: e.bound,
+    terms: Array.isArray(e.terms) ? (e.terms as Array<{ name?: unknown; ms?: unknown }>).map((t) => ({ name: t?.name, ms: t?.ms })) : e.terms,
+  });
+  if (Array.isArray(body.classes)) return (body.classes as Array<{ class?: unknown; bound?: unknown; terms?: unknown }>).map((e) => strip(e?.class, e ?? {}));
+  if (body.classes !== null && typeof body.classes === 'object') return Object.entries(body.classes as Record<string, { bound?: unknown; terms?: unknown }>).map(([k, e]) => strip(k, e ?? {}));
+  if (body.bound !== undefined || body.terms !== undefined) return [strip(typeof body.class === 'string' ? body.class : 'default', body)];
+  return null;
+}
+
 /**
  * How long to keep observing: the host's OWN declared recovery bound.
  *
@@ -199,19 +226,21 @@ const UNDECLARED_BOUND_FALLBACK_MS = 60_000;
  * bound is used as a CEILING FOR WAITING only; it is never asserted as a
  * scalar here (`bound-is-derived` owns the arithmetic).
  */
-async function declaredBoundMs(fired: unknown): Promise<{ ms: number; declared: boolean }> {
+async function declaredBoundMs(fired: unknown): Promise<{ ms: number; declared: boolean; recoveryClass: string | null }> {
+  const named = (fired as { recoveryClass?: unknown } | null)?.recoveryClass;
+  const recoveryClass = typeof named === 'string' && EVIDENCE_NAME_PATTERN.test(named) ? named : null;
   // A host whose bound is PER CLASS (Unresolved Question 1: unleased work waits
   // out an outbox lease, leased work a dispatch lease — 65 s against 750 s on
   // one measured host) names the figure that governs THIS work on the seam's
   // own response. The bare read below returns one class and would report the
   // interval against a bound that does not govern the staged run.
   const governing = (fired as { recoveryBoundMs?: unknown } | null)?.recoveryBoundMs;
-  if (typeof governing === 'number' && Number.isFinite(governing) && governing > 0) return { ms: governing, declared: true };
+  if (typeof governing === 'number' && Number.isFinite(governing) && governing > 0) return { ms: governing, declared: true, recoveryClass };
   const r = await driver.get('/host/durability/bound');
   const bound = (r.json as { bound?: unknown } | null)?.bound;
   return r.status === 200 && typeof bound === 'number' && Number.isFinite(bound) && bound > 0
-    ? { ms: bound, declared: true }
-    : { ms: UNDECLARED_BOUND_FALLBACK_MS, declared: false };
+    ? { ms: bound, declared: true, recoveryClass }
+    : { ms: UNDECLARED_BOUND_FALLBACK_MS, declared: false, recoveryClass };
 }
 
 /**
@@ -294,6 +323,15 @@ describe('v2-durability-recovery (RFC 0158 §B.4, §D.9, §E — the durable-sin
       w.resumedAfterMs !== null,
       req('openwop.requirement.0158.kill-after-accept', 'RFC 0158 §B.4', `work accepted before a real process death MUST dispatch on resume within the declared recovery bound — service answered again after ${backIn}ms, then observed for ${w.waitedMs}ms against a ${bound.declared ? `declared ${bound.ms}ms bound` : `${bound.ms}ms fallback (the host serves no /host/durability/bound)`}: ${w.last.runStarted} run.started, ${w.last.nodeStarted} node.started, ${w.last.restored} restored${w.resumedAfterMs !== null ? `; dispatch first observed ${backIn + w.resumedAfterMs}ms after the kill` : ''}`),
     ).toBe(true);
+    // RFC 0158 §E, 2.34.0: the interval this row MEASURED is evidence, and until
+    // now it existed only inside a failure message — a passing row recorded
+    // nothing, so a bundle could not show what was observed or against which
+    // class. Recorded only when the seam NAMED the class it exercised: without
+    // that the bundle cannot bind this exercise to a declared bound, the rung is
+    // not derivable, and saying so is more honest than guessing a class.
+    if (bound.declared && bound.recoveryClass !== null && w.resumedAfterMs !== null) {
+      noteEvidence({ recovery: { class: bound.recoveryClass, boundMs: Math.round(bound.ms), observedMs: backIn + w.resumedAfterMs } });
+    }
   }, KILL_ROW_TIMEOUT_MS);
 
   it('work executing at a real process death is never reported complete, and resumes', async () => {
@@ -341,6 +379,15 @@ describe('v2-durability-recovery (RFC 0158 §B.4, §D.9, §E — the durable-sin
       w.resumedAfterMs !== null,
       req('openwop.requirement.0158.kill-during-execution', 'RFC 0158 §B.4 / §E item 11', `work executing at a real process death MUST resume within the declared recovery bound; §B.4 measures kill → RESUMPTION, never kill → terminal — service answered again after ${backIn}ms, then observed for ${w.waitedMs}ms against a ${bound.declared ? `declared ${bound.ms}ms bound` : `${bound.ms}ms fallback (the host serves no /host/durability/bound)`}: ${w.last.runStarted} run.started, ${w.last.restored} restored${w.resumedAfterMs !== null ? `; resumption first observed ${backIn + w.resumedAfterMs}ms after the kill` : ''}`),
     ).toBe(true);
+    // RFC 0158 §E, 2.34.0: the interval this row MEASURED is evidence, and until
+    // now it existed only inside a failure message — a passing row recorded
+    // nothing, so a bundle could not show what was observed or against which
+    // class. Recorded only when the seam NAMED the class it exercised: without
+    // that the bundle cannot bind this exercise to a declared bound, the rung is
+    // not derivable, and saying so is more honest than guessing a class.
+    if (bound.declared && bound.recoveryClass !== null && w.resumedAfterMs !== null) {
+      noteEvidence({ recovery: { class: bound.recoveryClass, boundMs: Math.round(bound.ms), observedMs: backIn + w.resumedAfterMs } });
+    }
   }, KILL_ROW_TIMEOUT_MS);
 
   it('the same accepted work delivered twice fires each effect exactly once', async () => {
@@ -427,24 +474,25 @@ describe('v2-durability-recovery (RFC 0158 §B.4, §D.9, §E — the durable-sin
     if (terms.status === 404 || terms.status === 405) {
       return softSkip('blocked', 'the host exposes the durability seam but serves no recovery-bound terms — §E puts the per-class arithmetic in the RFC 0148 evidence bundle where a reader can recompute it, and there is nothing here to recompute');
     }
-    const body = (terms.json as { bound?: unknown; terms?: unknown } | null) ?? {};
-    const bound = typeof body.bound === 'number' ? body.bound : null;
-    const parts = Array.isArray(body.terms) ? (body.terms as unknown[]) : null;
-    if (bound === null || parts === null || parts.length === 0) {
-      return softSkip('blocked', 'the recovery-bound response names no { bound, terms[] } — §E asks for the per-class arithmetic, not a single total (Unresolved Question 1), and a total alone cannot be recomputed');
+    const classes = readClasses(terms.json);
+    if (classes === null) {
+      return softSkip('blocked', 'the recovery-bound response names no classes and no { bound, terms[] } — §E asks for the per-class arithmetic, not a single total (Unresolved Question 1), and a total alone cannot be recomputed');
     }
-    const summed = parts.reduce<number>((acc, t) => acc + (typeof (t as { ms?: unknown }).ms === 'number' ? (t as { ms: number }).ms : Number.NaN), 0);
     // THIS ROW IS A PAPER CHECK BY CONSTRUCTION AND THE RFC SAYS SO. It checks
-    // that the declared number follows from the stated mechanism. It cannot
+    // that each declared number follows from the stated mechanism. It cannot
     // check that the mechanism RUNS: a host whose sweeper wedges has a
     // derivation that stays perfectly correct while the bound is not produced
     // at all — a run sat unclaimed for 16 minutes against a derived bound of
     // 12.5 with every isolated check of the mechanism passing. Only the kill
     // rows above witness liveness, and this row MUST NOT be cited for it.
+    const parsed = parseRecoveryBounds(classes);
     expect(
-      Number.isFinite(summed) && Math.abs(summed - bound) <= 1,
-      req('openwop.requirement.0158.bound-is-derived', 'RFC 0158 §B.5', `the declared recovery bound MUST follow from the per-class terms that produce it — declared ${bound}, terms sum to ${summed}. A host that states a bound it cannot produce fails; a host whose sweeper wedges still passes, which is why this row MUST NOT be read as evidence that the mechanism runs`),
+      parsed.ok,
+      req('openwop.requirement.0158.bound-is-derived', 'RFC 0158 §B.5', `every declared recovery bound MUST follow from the per-class terms that produce it, each term { name, ms } — ${parsed.ok ? '' : parsed.why}. A host that states a bound it cannot produce fails; this checks the ARITHMETIC only, never that the mechanism runs`),
     ).toBe(true);
+    // The derivation goes INTO THE BUNDLE, per class, where a reader can
+    // recompute it (§E) — until 2.34.0 it lived only on this seam route.
+    if (parsed.ok) noteEvidence({ recoveryBounds: parsed.bounds });
   }, 120_000);
 
   it('deterministically failing work reaches a terminal state and stops being retried', async () => {

package/src/scenarios/v2-webhook-durable-delivery.test.ts

@@ -34,8 +34,9 @@ import { v2Discovery, gateFamily } from '../lib/v2.js';
 import { projectBoundId } from '../lib/bound-id.js';
 import { receiverBinding, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
 import { readErrorCode } from '../lib/error-envelope.js';
-import { softSkip } from '../lib/soft-skip.js';
+import { blockedDespiteAssertions, softSkip } from '../lib/soft-skip.js';
 import { req } from '../lib/requirement-ids.js';
+import { retryWaitCapMs, retryWaitFor, windowClosedNote } from '../lib/webhook-retry-window.js';
 
 const FIXTURE = 'conformance-noop';
 const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
@@ -167,14 +168,14 @@ function advertisedRetryPolicy(doc: Record<string, unknown>): { maxAttempts?: nu
  * which covers a 30 s first attempt with room for the second. The cap is
  * deliberate: unbounded waiting would let a host that never retries hold the
  * suite open instead of failing.
+ *
+ * 2.34.1: and 90 s was the same defect again, one schedule further out — see
+ * `lib/webhook-retry-window.ts`. The cap is now operator-RAISABLE through
+ * `OPENWOP_WEBHOOK_RETRY_WAIT_MS` and never lowerable; still bounded.
  */
-const RETRY_WAIT_FLOOR_MS = 20_000;
-const RETRY_WAIT_CAP_MS = 90_000;
+const RETRY_WAIT_CAP_MS = retryWaitCapMs();
 function retryWaitMs(doc: Record<string, unknown>): number {
-  const policy = advertisedRetryPolicy(doc);
-  if (policy === null) return RETRY_WAIT_FLOOR_MS;
-  const backoff = String(policy.backoff ?? '');
-  return backoff === 'exponential' || backoff === 'fixed' ? RETRY_WAIT_CAP_MS : RETRY_WAIT_FLOOR_MS;
+  return retryWaitFor(advertisedRetryPolicy(doc), RETRY_WAIT_CAP_MS);
 }
 
 /**
@@ -330,8 +331,26 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     const sub = await register(receiver.url);
     if (sub === null) return softSkip('blocked', 'registration refused (reason recorded above)');
 
+    // The row id is the FIRST thing this leg names: `register()` asserts under
+    // the base `0173.webhook-durable-delivery` id, and a leg that returned before
+    // any `.dead-letter` req() ran recorded its outcome under THAT id, leaving
+    // `.dead-letter` with no row in the bundle at all (measured, 2.34.1 draft).
+    req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'webhooks.md §Durability', 'an exhausted delivery MUST be routed to the sink, not dropped');
     const create = await driver.post('/runs', { workflowId: FIXTURE });
-    expect(create.status, req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    // 2.34.1 — NO OBLIGATION IS ASSERTED UNTIL THE WINDOW QUESTION IS ANSWERED. A leg
+    // that asserts and THEN soft-skips records `executed-pass` with a
+    // `partial-witness:` detail (`resolveItRecord`), which certifies. The first
+    // draft of this fix asserted `create.status` and the retry, then
+    // soft-skipped `blocked` on a closed window, and so turned a false FAIL into
+    // a pass that never looked at the sink — caught by measuring it: five rows
+    // `executed-pass`, 106 s, on a host whose first delivery exhausts at 225 s.
+    // So everything is OBSERVED first, the one inconclusive case returns with
+    // zero assertions (a real `blocked`, which denies certification), and only
+    // then are the obligations asserted, in their original order. A failure the
+    // observations already show still fails: the create check fires at once.
+    if (create.status !== 201) {
+      expect(create.status, req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    }
     const runId = (create.json as { runId: string }).runId;
     await waitTerminal(runId, 10_000);
     // Filter by the delivery's own SUBSCRIPTION, not just its run. A host that
@@ -344,19 +363,11 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     const ours = () => receiver.attempts.filter((a) => a.runId === runId && a.webhookId === sub.webhookId);
     await waitFor(() => ours().length > 1, retryWaitMs(doc));
     const attempts = ours();
-    expect(
-      attempts.length,
-      req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'webhooks.md §Durability', 'a delivery that keeps failing MUST be retried before it can be exhausted (one attempt is a drop)'),
-    ).toBeGreaterThan(1);
     const policy = advertisedRetryPolicy(doc);
-    if (policy?.maxAttempts !== undefined) {
+    if (policy?.maxAttempts !== undefined && attempts.length > 1) {
       // Give the policy time to exhaust, then the host MUST stop.
       await waitFor(() => ours().length >= policy.maxAttempts!, retryWaitMs(doc));
       await new Promise((r) => setTimeout(r, 1_000));
-      expect(
-        ours().length,
-        req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'webhooks.md §Durability', `retries MUST stop at the advertised retryPolicy.maxAttempts (${policy.maxAttempts}) — exhaustion routes to the dead-letter sink, not to an unbounded loop`),
-      ).toBeLessThanOrEqual(policy.maxAttempts);
     }
     // The sink itself. Until RFC 0188 this was an UNCONDITIONAL soft-skip on
     // every host — `webhooks.md` §Durability said the sink was "inspectable for
@@ -364,14 +375,41 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     // every bundle recorded "exhaustion was observed, routing to the sink was
     // not". The read exists now; read it before deleting the subscription.
     const fam = await gateFamily('webhooks');
-    if (!fam?.['deadLetter']) {
-      await driver.delete(`/webhooks/${encodeURIComponent(sub.webhookId)}`);
-      return softSkip('inapplicable', 'host does not advertise the webhooks.deadLetter facet — RFC 0188 §A.5 makes the read a 404 rather than an obligation, so the sink half of §Durability is unwitnessable here (the retry half above passed)');
+    let inSink: boolean | null = null;
+    if (fam?.['deadLetter']) {
+      const sink = await driver.get(`/webhooks/${projectBoundId(sub.webhookId)}/dead-letters`);
+      inSink = sink.status === 200 && ((sink.json as { deliveries?: unknown[] } | null)?.deliveries ?? []).some((r) => (r as Record<string, unknown>)['runId'] === runId);
     }
-    const sink = await driver.get(`/webhooks/${projectBoundId(sub.webhookId)}/dead-letters`);
     await driver.delete(`/webhooks/${encodeURIComponent(sub.webhookId)}`);
+    // "Routed to the sink, not dropped" is a claim about an EXHAUSTED delivery,
+    // and until 2.34.1 it was asserted whether or not exhaustion had been
+    // observed: a host retrying at 15 / 30 / 60 / 120 s had made 4 of its 5
+    // attempts when the 90 s window closed, and this row said it had dropped a
+    // delivery still in flight. Retried, fewer attempts than advertised, and
+    // nothing in the sink is a window that closed early OR a host that stopped
+    // retrying — indistinguishable without an interval on the wire — so it is
+    // `blocked`, never a conviction. Reached maxAttempts with nothing in the
+    // sink still FAILS below; so does a delivery that was never retried.
+    const seen = ours().length;
+    if (inSink === false && policy?.maxAttempts !== undefined && attempts.length > 1 && seen < policy.maxAttempts) {
+      return blockedDespiteAssertions(windowClosedNote(seen, policy.maxAttempts, retryWaitMs(doc), RETRY_WAIT_CAP_MS));
+    }
+    expect(create.status, req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    expect(
+      attempts.length,
+      req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'webhooks.md §Durability', 'a delivery that keeps failing MUST be retried before it can be exhausted (one attempt is a drop)'),
+    ).toBeGreaterThan(1);
+    if (policy?.maxAttempts !== undefined) {
+      expect(
+        ours().length,
+        req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'webhooks.md §Durability', `retries MUST stop at the advertised retryPolicy.maxAttempts (${policy.maxAttempts}) — exhaustion routes to the dead-letter sink, not to an unbounded loop`),
+      ).toBeLessThanOrEqual(policy.maxAttempts);
+    }
+    if (inSink === null) {
+      return softSkip('inapplicable', 'host does not advertise the webhooks.deadLetter facet — RFC 0188 §A.5 makes the read a 404 rather than an obligation, so the sink half of §Durability is unwitnessable here (the retry half above passed)');
+    }
     expect(
-      sink.status === 200 && ((sink.json as { deliveries?: unknown[] } | null)?.deliveries ?? []).some((r) => (r as Record<string, unknown>)['runId'] === runId),
+      inSink,
       req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'webhooks.md §Durability', 'an exhausted delivery MUST be routed to the sink, not dropped — the half no bundle could witness before RFC 0188 served a read'),
     ).toBe(true);
   }, DEAD_LETTER_TEST_TIMEOUT_MS);
@@ -424,10 +462,14 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     active = receiver.server;
     const sub = await register(receiver.url);
     if (sub === null) return softSkip('blocked', 'registration refused (reason recorded above)');
+    // Same two traps as the leg above (2.34.1): `register()` asserts under the base
+    // id, so name this row first; and every `blocked` after it must STAND rather
+    // than fold into a partial-witness pass that certifies.
+    req('openwop.requirement.0188.dead-letter-content-free', 'RFC 0188 §B.1', 'a dead-letter record MUST NOT carry the delivered body, headers or subscription secret');
     const create = await driver.post('/runs', { workflowId: FIXTURE });
     if (create.status !== 201) {
       await driver.delete(`/webhooks/${encodeURIComponent(sub.webhookId)}`);
-      return softSkip('blocked', `POST /runs answered ${create.status} — no delivery to exhaust`);
+      return blockedDespiteAssertions(`POST /runs answered ${create.status} — no delivery to exhaust`);
     }
     const runId = (create.json as { runId: string }).runId;
     await waitTerminal(runId, 10_000);
@@ -441,12 +483,16 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
 
     const sink = await driver.get(`/webhooks/${projectBoundId(sub.webhookId)}/dead-letters`);
     await driver.delete(`/webhooks/${encodeURIComponent(sub.webhookId)}`);
-    if (sink.status !== 200) return softSkip('blocked', `the dead-letter read answered ${sink.status}`);
+    if (sink.status !== 200) return blockedDespiteAssertions(`the dead-letter read answered ${sink.status}`);
     const rows = ((sink.json as { deliveries?: Array<Record<string, unknown>> } | null)?.deliveries ?? []);
     // An empty sink is NOT a pass. Recording one as a pass is exactly the
     // vacuous witness this leg used to produce; say so instead.
     if (rows.length === 0) {
-      return softSkip('blocked', 'the exhausted delivery did not reach the sink inside the retry window — §B.1 is a claim about a real record and there is none here to read');
+      const seen = ours().length;
+      const why = policy?.maxAttempts !== undefined && seen < policy.maxAttempts
+        ? windowClosedNote(seen, policy.maxAttempts, retryWaitMs(doc), RETRY_WAIT_CAP_MS)
+        : `the delivery made ${seen} attempt(s) and is not in the sink`;
+      return blockedDespiteAssertions(`§B.1 is a claim about a real record and there is none here to read — ${why}`);
     }
     expect(
       rows.every((r) => r['body'] === undefined && r['headers'] === undefined && r['secret'] === undefined),

package/src/setup.ts

@@ -43,6 +43,7 @@ import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL } from './lib/spec-cohe
 import type { DiscoveryPayload } from './lib/profiles.js';
 import { targetMajor } from './lib/seams.js';
 import { softSkip } from './lib/soft-skip.js';
+import { takeNotedEvidence } from './lib/durability-evidence.js';
 
 // 20 s, not 5: a Cloud Run cold start routinely exceeds 5 s, and a discovery
 // fetch that aborted at init used to turn every fixture-gated scenario into a
@@ -457,7 +458,8 @@ afterEach(({ task }) => {
     detail = rec.detail;
   }
   try {
-    recordRequirement(itId, disposition, detail, { assertionCount: calls, scenarioFile: file });
+    const evidence = takeNotedEvidence();
+    recordRequirement(itId, disposition, detail, { assertionCount: calls, scenarioFile: file, ...(evidence === null ? {} : { evidence }) });
   } catch {
     /* never fail a test for bookkeeping */
   }