@openwop/openwop-conformance 2.33.1 → 2.33.2

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # `@openwop/openwop-conformance` Changelog
 
+## [2.33.2] — 2026-09-21 — `v2-run-snapshot-etag` took its tag from a run that was still moving
+
+- **The scenario slept a fixed 1 s after `POST /runs`, took the snapshot's `ETag`, and demanded `304`.** A host whose ETag tracks the run's event-log sequence — the strong tag `runs.md` §Snapshot asks for — is still appending while a noop executes, so between the two GETs the representation **changes** and `200` with a new tag is the only correct answer; a `304` there would be a stale-cache bug. **Measured on a tier-2 production host, 4 of 4:** immediately after create `etag1 ≠ etag2` and the conditional GET answers `200`; after the run settles the same request answers `304` every time. The row had passed three earlier cuts of that host and failed the fourth — a timing lottery, won whenever the run finished inside the sleep.
+- **It now waits for the run to be terminal, and the violation is stated exactly:** a `200` whose `ETag` **equals** the `If-None-Match` that was sent. A `200` carrying a *different* tag means the representation moved and the tag sent was honestly stale, so the scenario takes the new tag and retries (up to four reads); a terminal run whose snapshot never holds still records `blocked`, not fail.
+- A host with a **constant** ETag passed the old row for the wrong reason whenever it won the lottery; the non-matching control (`If-None-Match: "…no-such-tag"` MUST answer `200`) still catches a host that answers `304` to everything.
+- False FAIL only. Found by the MyndHyve host session, reproduced by hand on production before being reported.
+- Suite patch: corpus release stays `2.33.0`.
+
 ## [2.33.1] — 2026-09-21 — two false fails: a race between two reads, and a subscription nobody unregistered
 
 - **`v2-durability-recovery`: the "completed without re-execution" latch was decided from two non-atomic reads in the wrong order.** Each iteration read the LOG, then the STATUS, and latched when the status said `completed` and the — older — log showed no resumption. A host that re-dispatched between the two requests read as "completed un-re-executed" while being neither. `conformance-noop` re-executes in milliseconds, so the window is real: per run roughly (gap between the requests) / (500 ms poll), a few percent. **Measured on a tier-1 host:** after a genuine SIGKILL and a correct recovery by lease expiry (727 s inside a declared 750 s bound) the row failed with *"read status completed with 2 run.started"* — printing the re-execution it was denying, because the message used a later read than the latch. The same host and code had passed the two previous runs.

package/README.md

@@ -11,7 +11,7 @@
 # --legacy-peer-deps is REQUIRED, not optional: the exact peer pin is what npm's
 # default resolver refuses. npm 10.9 fails outright with
 # "Cannot read properties of null (reading 'edgesOut')" — use npm >= 11.
-npm install --legacy-peer-deps @openwop/openwop-conformance@2.33.1 @openwop/spec-artifacts@2.33.1
+npm install --legacy-peer-deps @openwop/openwop-conformance@2.33.2 @openwop/spec-artifacts@2.33.2
 # or run without install:
 npx @openwop/openwop-conformance --base-url https://api.example.com --api-key hk_test_...
 ```

package/dist/spec-artifacts.lock.json

@@ -1,5 +1,5 @@
 {
   "package": "@openwop/spec-artifacts",
-  "version": "2.33.1",
-  "stampSha256": "132270b1cd8c97bed21d57a5b08c9abe89d10a56ff1aadf9ff3119edafb4d121"
+  "version": "2.33.2",
+  "stampSha256": "005732c466b247dadf5ee3d8c68186c6ce4f586febbaa260b7906fd496153965"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop-conformance",
-  "version": "2.33.1",
+  "version": "2.33.2",
   "description": "Production-ready black-box conformance suite for OpenWOP v1.0 compliant servers.",
   "repository": {
     "type": "git",
@@ -56,6 +56,6 @@
     "@openwop/spec-artifacts": "file:../spec-artifacts"
   },
   "peerDependencies": {
-    "@openwop/spec-artifacts": "2.33.1"
+    "@openwop/spec-artifacts": "2.33.2"
   }
 }

package/requirements.json

@@ -28985,7 +28985,7 @@
     {
       "id": "openwop.it.v2-run-snapshot-etag.a-matching-if-none-match-receives-304-with-no-body-and-the-version-header-a-non",
       "file": "v2-run-snapshot-etag.test.ts",
-      "line": 34,
+      "line": 35,
       "title": "a matching If-None-Match receives 304 with no body and the version header; a non-matching one receives 200",
       "explicitId": "openwop.requirement.0170.run-snapshot-etag",
       "citations": [

package/schemas/CORPUS-STAMP.json

@@ -1,7 +1,7 @@
 {
   "_comment": "Provenance of @openwop/spec-artifacts (RFC 0168 §D.2). files: SHA-256 per file; the conformance suite compares the installed peer against dist/spec-artifacts.lock.json at start.",
   "package": "@openwop/spec-artifacts",
-  "version": "2.33.1",
+  "version": "2.33.2",
   "corpusTag": "v2.33.0",
   "files": {
     "api/.redocly.lint-ignore.yaml": "bf5a8350b88a72fa43f59605ed8d903ed24b6cfccda5e45509c9f6ed9ee4e712",
@@ -201,7 +201,7 @@
     "schemas/workspace-file.schema.json": "464de85c2a068243084ee9c1d969bc7cd5d8f7948574e58450d6493c38a0e1e4",
     "spec/v1/alias-detectors.json": "40069d5976eeb6ba1384a648e57e5cfd673db3fce36175115fb8293bee9664d4",
     "spec/v1/capability-declaration-classes.json": "e7729aed5c4b4e1dd02abab0530f14cc95f5d4070fe51fb139e7f5cccefa00c6",
-    "spec/v1/core-standard-manifest.json": "71c38c738496eaac1d144561a7f6e752600f8afd71f938eb483c0c76b8a5263a",
+    "spec/v1/core-standard-manifest.json": "65a8576c2e5ea9deb9d463be5b02a8bfb0e125a8dcbe3fe2cf286a4fd6d5d53e",
     "spec/v1/deprecations.json": "307083ce29c23fd406015951f99a30d78d6187ff061d38dc9732f62191b40f3f",
     "spec/v1/deprecations.schema.json": "18c87e78bedc210431f795ae44c5b5d202f2f3317850d5cf86867d4f1fa1cdfb",
     "spec/v1/event-codemap.json": "3da60d884157793a360da532a9fcbbfb5285636db325a74cec94b34622186d97",
@@ -282,5 +282,5 @@
     "spec/v2/release.json": "94a3ea302324d9f7df87ce62a186b0b98936de6ce5ac5ec01a3fb3208c38efc3",
     "spec/v2/retention-floors.json": "eaf3722d95c79947af1d4269ef85117e126518c588cfcf1a2b21b97269f51624"
   },
-  "corpusCommit": "b9afb25c0bdfbbd2f11efad6f984df51e50344e5"
+  "corpusCommit": "65e40d60fbf43b1a0cd95a58e63d7464ed944ddb"
 }

package/src/scenarios/v2-run-snapshot-etag.test.ts

@@ -16,6 +16,7 @@
  * @see spec/v2/core/versioning.md §1.4
  */
 
+import { pollUntilTerminal, scaledTimeoutMs } from '../lib/polling.js';
 import { describe, it, expect } from 'vitest';
 import { driver, type OpenWOPResponse } from '../lib/driver.js';
 import { v2Discovery } from '../lib/v2.js';
@@ -38,15 +39,39 @@ describe('v2 run-snapshot-etag (runs.md §Snapshot)', () => {
     const runId = (created.json as { runId?: unknown } | null)?.runId;
     if (created.status !== 201 || typeof runId !== 'string') return softSkip('blocked', `POST /runs answered ${created.status} ${readErrorCode(created.json) ?? ''} — create refused`.trim());
     const path = `/runs/${encodeURIComponent(runId)}`;
-    // Let the noop settle so the tag is stable across the two conditional reads.
-    await new Promise((r) => setTimeout(r, 1_000));
-    const first = await http(() => driver.get(path));
-    if (first === null || first.status !== 200) return softSkip('blocked', `GET /runs/{runId} answered ${first?.status ?? 'no response'}`);
-    const etag = first.headers.get('etag');
-    if (!etag) return softSkip('inapplicable', 'the snapshot carries no ETag — runs.md §Snapshot makes the ETag a SHOULD; the 304 rule applies only when it is present');
-    const hit = await http(() => driver.get(path, { headers: { 'If-None-Match': etag } }));
-    if (hit === null) return softSkip('blocked', 'conditional GET unreachable (fetch failed)');
-    expect(hit.status, req(ID, DOC, `a request whose If-None-Match matches the ETag MUST receive 304 — got ${hit.status}`)).toBe(304);
+    // The tag MUST be taken from a representation that has stopped moving. Until
+    // 2.33.2 this slept a fixed 1 s and hoped. A host whose ETag tracks the run's
+    // event-log sequence (RFC 0115 — the strong tag the SHOULD asks for) is still
+    // appending while a noop executes, so between the two GETs the representation
+    // CHANGES and `200` with a new tag is the only correct answer; a `304` there
+    // would be a stale-cache bug. Measured on a tier-2 production host, 4 of 4:
+    // immediately after create etag1 != etag2 and the conditional GET answers 200;
+    // after the run settles the same request answers 304 every time. The row had
+    // passed three earlier cuts of that host — a timing lottery, won when the run
+    // happened to finish inside the sleep. It also let a host with a CONSTANT tag
+    // pass for the wrong reason, which the control below still catches.
+    await pollUntilTerminal(runId, { timeoutMs: scaledTimeoutMs(30_000) });
+    let etag: string | null = null;
+    let hit: OpenWOPResponse | null = null;
+    // A terminal run should be still, but "should" is not the claim under test:
+    // if the tag moves again, take the NEW tag and retry. The violation is a 200
+    // whose ETag EQUALS the If-None-Match that was sent — never a 200 per se.
+    for (let attempt = 0; attempt < 4; attempt++) {
+      const first = await http(() => driver.get(path));
+      if (first === null || first.status !== 200) return softSkip('blocked', `GET /runs/{runId} answered ${first?.status ?? 'no response'}`);
+      etag = first.headers.get('etag');
+      if (!etag) return softSkip('inapplicable', 'the snapshot carries no ETag — runs.md §Snapshot makes the ETag a SHOULD; the 304 rule applies only when it is present');
+      const sent = etag;
+      hit = await http(() => driver.get(path, { headers: { 'If-None-Match': sent } }));
+      if (hit === null) return softSkip('blocked', 'conditional GET unreachable (fetch failed)');
+      if (hit.status !== 200 || hit.headers.get('etag') === sent) break; // 304, or the real violation: decided below
+      await new Promise((r) => setTimeout(r, 500)); // 200 with a DIFFERENT tag: the representation moved; the tag sent was honestly stale
+    }
+    if (hit === null || etag === null) return softSkip('blocked', 'no conditional GET was made');
+    if (hit.status === 200 && hit.headers.get('etag') !== etag) {
+      return softSkip('blocked', `the snapshot of a TERMINAL run kept changing across four reads (last tag sent ${etag}, answered 200 with ${String(hit.headers.get('etag'))}) — the 304 rule cannot be witnessed against a representation that never holds still`);
+    }
+    expect(hit.status, req(ID, DOC, `a request whose If-None-Match matches the CURRENT ETag MUST receive 304 — got ${hit.status} while the response still carried the same tag ${etag}`)).toBe(304);
     expect(hit.text.length, req(ID, DOC, `the 304 MUST carry no body (got ${hit.text.length} byte(s))`)).toBe(0);
     expect(hit.headers.get('openwop-version'), req(ID, 'spec/v2/core/versioning.md §1.4', 'every response carries OpenWOP-Version, the 304 included')).not.toBeNull();
     const miss = await http(() => driver.get(path, { headers: { 'If-None-Match': '"openwop-conformance-no-such-tag"' } }));