@openwop/openwop-conformance 2.44.9 → 2.45.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # `@openwop/openwop-conformance` Changelog
 
+## [2.45.0] — 2026-09-29 — a host that grants an origin admits the contract's request headers in preflight
+
+- **New scenario `v2-cors-preflight`: `openwop.requirement.headers.cors-preflight-admits`** (#1763; minor, since a scenario is added). It witnesses the new `headers.md` §Cross-origin preflight (Class 3).
+  - **Probe.** For every operation in `spec/v2/path-manifest.json` it sends `OPTIONS <path>` with `Origin`, `Access-Control-Request-Method`, and `Access-Control-Request-Headers`. The headers requested are that operation's declared request headers, plus `authorization` when authenticated and `content-type` with a body.
+  - **Reading.** It reads the answer as the Fetch standard's CORS-preflight check does. A CORS-safelisted method needs no listing. `*` admits nothing once credentials are allowed, and never admits `authorization`.
+  - **Gate.** It is self-gated on the host's grant: an operation whose preflight does not grant the origin is not judged, and the row is `inapplicable` when none is. The origin is `OPENWOP_CORS_ORIGIN` (default `https://conformance.invalid`), so an allowlisting host's operator can name an allowed one.
+  - **Verdicts.** Fails naming each granted operation and the missing names. Passes with an `observed:` detail (granted count).
+  - **Measured on stub hosts.** A copy of openwop-app's current middleware (reflect any origin, explicit list) records `executed-fail` on four operations: `getCapabilities` and `getRun` (`If-None-Match`), `createRun` (`OpenWOP-Force-Engine-Version`), `getContentPage` (`Accept-Language`). A host that reflects the request headers passes. A host that answers no CORS is `inapplicable`.
+  - **The per-operation sets come from the manifest.** `spec/v2/path-manifest.json` now carries `requestHeaders`, `authenticated` and `requestBody` per operation, written by `derive-v2-api.py` from `api/v2/openapi.yaml`, so the suite reads them without a YAML parser.
+
 ## [2.44.9] — 2026-09-29 — a floor gated on a withheld fixture records `blocked`, not nothing
 
 - **Nine v1 floor files no longer skip at describe level** (#1686). Each of the following gated every test with `describe.skipIf(!isFixtureAdvertised(…))`: `eventOrdering`, `failure-path`, `idempotency`, `interrupt-clarification`, `replay-fork`, `runs-lifecycle`, `stream-modes`, `stream-modes-buffer` and `stream-modes-mixed`. When every test in a file is describe-skipped, vitest runs none of `setup.ts`'s hooks for it, so the file's floor requirement got no ledger row. `--certify` then counted the floor unclassified and rejected the whole certification, not just the profile. `byok-roundtrip` hit this on openwop-app's 2026-09-28 major-1 cut (`certified: none`) and was fixed in #1708. Each test in the nine files now opens with `if (SKIP) return softSkip('blocked', NO_FIXTURE_REASON)`, so a withheld fixture records `blocked` with the fixture named. That denies only the affected profile. It is `blocked`, not `inapplicable`: the host advertises the capability the floor witnesses, so the requirement applies to the captured discovery, and a withheld fixture is exactly RFC 0148 §A's `blocked` ("a required seam, fixture … was unavailable"). `byok-roundtrip`'s `blocked` (#1708) stands for the same reason. Measured against a stub host that advertises no fixtures, with the ledger on: before, `runs-lifecycle` wrote no ledger row; after, `openwop.floor.runs-lifecycle` is `blocked` with the reason. A test that passed before still passes: the gates are unchanged, only where they sit.

package/README.md

@@ -135,7 +135,8 @@ Exit code is non-zero on any failed assertion. `--certify` distinguishes: `0`
 
 ## What's Covered
 
-The current suite has 574 scenario files under `src/scenarios/`.
+The current suite has 575 scenario files under `src/scenarios/`.
+- 2026-09-29 (suite 2.45.0, openwop#1763): NEW `v2-cors-preflight.test.ts` — `headers.md` §Cross-origin preflight. For every operation it preflights with `Origin`, the method, and the operation's declared request headers (plus `authorization` / `content-type` where they apply, from `spec/v2/path-manifest.json`), and reads the answer as the Fetch standard's CORS-preflight check does. Self-gated: `inapplicable` when no operation's preflight grants `OPENWOP_CORS_ORIGIN` (default `https://conformance.invalid`).
 - 2026-09-23 (suite 2.37.0 cycle, RFC 0213): NEW `v2-sse-last-event-id-cursor.test.ts` (a `Last-Event-ID` past the log is an exclusive cursor; a malformed id, when refused, is `400 validation_error`; the cursor never changes the answer for an unknown or foreign-tenant run — public test of `event-cursor-after-authorization`), `v2-idempotency-in-flight.test.ts` (five concurrent same-key creates yield one run; each loser is a marked replay or `409 idempotency_in_flight` with no retry timing in `details`; `partial-witness` when no loser was refused in flight) and `v2-interrupt-resolve-terminal.test.ts` (a run-scoped resolve after cancel or completion is `409 interrupt_already_resolved`, never `interrupt_cancelled`). All three sit off the core-standard floor until measured on the three bundle hosts.
 - 2026-09-03 (suite `1.157.0 -> 1.158.0`, gap G17): NEW `idempotency-concurrent-claim.test.ts` — drives the new `host-sample-test-seams.md` §25 concurrent duplicate-delivery seam for the RFC 0150 §B / `idempotency.md` §"Concurrent duplicates (Layer 2)" atomic-claim MUST, which is unconditional and had no witness of any kind. Asserts every executor mints the SAME `logicalInvocationId` **before** asserting `delivered === 1` — without the identity check a host passes by minting different ids and never colliding, one effect because nothing raced. Not profile-gated and so not opt-out-able (the obligation is unconditional); an unmounted seam records `blocked`, which is not certifiable. Graduates `layer2-invocation-claim-atomic` reference-impl -> protocol.
 - 2026-08-19 (suite `1.137.0 → 1.138.0`): NEW `durability-poison-exhaustion.test.ts` — RFC 0158 §C.8, the FIRST row of that RFC's conformance table to land. Asserts what `failure-path.test.ts` cannot: not just that deterministically failing work reaches terminal, but that attempts STOP — counted on the log, re-counted after a scaled quiet window, asserted unchanged. A host still redelivering records more. Seam-gated on the existing event-log seam (`blocked` = unobservable, not unmet) and outside every profile floor.
@@ -481,7 +482,7 @@ Server-required (added in 1.7.0):
 | ------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Redaction** | [`capabilities.md`](../spec/v1/capabilities.md) §"Secrets" + NFR-7 + §"aiProviders" | Vendor-neutral assertions that the server doesn't leak secret material. Three scenario groups: (a) discovery shape contract — `secrets` + `aiProviders` advertisements are well-formed regardless of `secrets.supported`; when `supported === true`, scopes MUST be non-empty + `resolution === 'host-managed'`; `byok ⊆ supported`. (b) bearer-token redaction — invalid Bearer canary in `Authorization` header is not echoed in the 401 response body. (c) credentialRef echo control — gated on `secrets.supported === true`; canary planted in `configurable.ai.credentialRef` MUST NOT appear in any RunEvent payload (poll-based capture; transport-agnostic). Uses runtime-built canary fixtures (`lib/canaries.ts`) that defeat static secret scanners. 6 scenarios. |
 
-Current source tree: 574 scenario files. Use [`coverage.md`](./coverage.md) for current grade/gap tracking.
+Current source tree: 575 scenario files. Use [`coverage.md`](./coverage.md) for current grade/gap tracking.
 
 ## Remaining Gaps
 

package/dist/spec-artifacts.lock.json

@@ -1,5 +1,5 @@
 {
   "package": "@openwop/spec-artifacts",
-  "version": "2.44.9",
-  "stampSha256": "7803a5db18abdf8649235a2665ae9bb801aea6ee7584cdd13ada047fd25a8993"
+  "version": "2.45.0",
+  "stampSha256": "f4646a61110c8c6132dfc23c78868cdfaaa6e18cda1d8247fac0b123f29c693e"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop-conformance",
-  "version": "2.44.9",
+  "version": "2.45.0",
   "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.44.9"
+    "@openwop/spec-artifacts": "2.45.0"
   }
 }

package/requirements.json

@@ -2,11 +2,11 @@
   "$comment": "GENERATED by conformance/scripts/generate-requirement-registry.mjs — do not edit. One record per it()/test() in src/scenarios. Ids: openwop.it.<file-stem>.<title-slug>[~n] (src/lib/requirement-ids.ts). A record with id null has an interpolated title; its run-time row is keyed by the rendered title and maps here by file+line only. Renamed ids need a row in requirement-aliases.json.",
   "generatedFrom": "src/scenarios/*.test.ts",
   "counts": {
-    "files": 649,
-    "tests": 2495,
-    "withStableId": 2495,
+    "files": 650,
+    "tests": 2496,
+    "withStableId": 2496,
     "interpolatedTitles": 0,
-    "explicitIds": 2374
+    "explicitIds": 2375
   },
   "records": [
     {
@@ -28995,6 +28995,20 @@
         }
       ]
     },
+    {
+      "id": "openwop.it.v2-cors-preflight.every-operation-a-granted-origin-preflights-admits-its-method-and-every-request",
+      "file": "v2-cors-preflight.test.ts",
+      "line": 110,
+      "title": "every operation a granted origin preflights admits its method and every request header the contract declares for it",
+      "explicitId": "openwop.requirement.headers.cors-preflight-admits",
+      "citations": [
+        {
+          "section": "spec/v2/core/headers.md §Cross-origin preflight",
+          "requirement": null,
+          "interpolated": true
+        }
+      ]
+    },
     {
       "id": "openwop.it.v2-created-run-readable.a-run-created-at-this-base-is-readable-and-pollable-at-this-base-by-the-id-it-re",
       "file": "v2-created-run-readable.test.ts",

package/scenario-majors.json

@@ -1,9 +1,9 @@
 {
   "$comment": "GENERATED by conformance/scripts/generate-scenario-majors.mjs (RFC 0168 §D.3). Do not edit; add a file to BOTH_MAJORS in the generator to target both majors.",
   "counts": {
-    "files": 574,
+    "files": 575,
     "v1": 452,
-    "v2": 137
+    "v2": 138
   },
   "majors": {
     "a2a-1-0-agent-card.test.ts": [
@@ -1347,6 +1347,9 @@
     "v2-conversation-turn-parts.test.ts": [
       2
     ],
+    "v2-cors-preflight.test.ts": [
+      2
+    ],
     "v2-created-run-readable.test.ts": [
       2
     ],

package/schemas/CORPUS-STAMP.json

@@ -1,17 +1,17 @@
 {
   "_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.44.9",
-  "corpusTag": "v2.44.9",
+  "version": "2.45.0",
+  "corpusTag": "v2.45.0",
   "files": {
     "api/.redocly.lint-ignore.yaml": "bf5a8350b88a72fa43f59605ed8d903ed24b6cfccda5e45509c9f6ed9ee4e712",
     "api/asyncapi.yaml": "d5ecb9ee6114582be3b1f662c84bfac9ae96dae7bacb853e461168f70a8e1c7d",
     "api/grpc/openwop.proto": "c3e72bb17cba514ee98feb6434e6c9b6ea6795bfd086489ec69fd882dd1ad977",
     "api/openapi.yaml": "69464bc0e1e71ef3b543a73d4fa4f67202343d2603c80af8033f6c3619ef1b30",
     "api/redocly.yaml": "b0604c89b2ca6d5076ec25725c539dad44a741a811fe524439ee6daef8baa09f",
-    "api/seams-v2.yaml": "57cf1d472f2bf9bf61bcd2239b9fd43277072d02a367d7a85725aea0e01300db",
-    "api/v2/asyncapi.yaml": "40cb3ee66657a736b92c6f79241169e3669486058a65e143d99509d41d691d67",
-    "api/v2/openapi.yaml": "08581315aa90da54f9a1c56f8b972a801eec99bda752d92c3ea2b16113b33a92",
+    "api/seams-v2.yaml": "92744ab58f83798c63b96700475bd55c201e7af14c3fd230c31ab0bbd86f6a60",
+    "api/v2/asyncapi.yaml": "4f00d2847c3ffb526af9c294f9e318b762f197e86cfd607934e677f12a1fc8bc",
+    "api/v2/openapi.yaml": "396fe10fc350cbae59190c4bd0e4cd24e18b16b4aac9db2f6c78e54344db4709",
     "api/v2/redocly.yaml": "1e66b60e6118ad11a823bb620678be464d99dfe50a40e3e6f93ec9429b88b34c",
     "schemas/README.md": "0c0b737ffcf8f30e7d2809cec8a498232de710f41443212922ad8337cdde0b51",
     "schemas/a2a-task-state.schema.json": "75d5049dea8bd873ff0e7546f1c60c8d36c219bec7084264360be54a8be30ae1",
@@ -204,13 +204,13 @@
     "schemas/workspace-file.schema.json": "464de85c2a068243084ee9c1d969bc7cd5d8f7948574e58450d6493c38a0e1e4",
     "spec/v1/alias-detectors.json": "0b2f28808ffe0b9d98a187775038c3406bb70919747a788a6e4f866e293ae6d3",
     "spec/v1/capability-declaration-classes.json": "e7729aed5c4b4e1dd02abab0530f14cc95f5d4070fe51fb139e7f5cccefa00c6",
-    "spec/v1/core-standard-manifest.json": "cdc802f553a24b2ea8288370a54a9cf9a88d65bb80ec33c258c8fe2d2737edd1",
+    "spec/v1/core-standard-manifest.json": "684dff535d3536673129ef594b97717cbc30fd066a6ea4d2c52d9fbbde69836d",
     "spec/v1/deprecations.json": "a3293072ea951857395d05f0437264e88965f1e9019ff61c55bacfa9c1aaa17c",
     "spec/v1/deprecations.schema.json": "3e393c405d2a41b467d8c5e3c468549078df1ce6a6d2588fc488097b95d9b55b",
     "spec/v1/event-codemap.json": "3da60d884157793a360da532a9fcbbfb5285636db325a74cec94b34622186d97",
     "spec/v1/event-codemap.schema.json": "d05933b2e88103aff51a2f774df97b9bda065e0fc88dbd9b114cc47a32189174",
     "spec/v1/extensions.json": "79a60754aa16cbdbdb604f8e5c00038af535a1690a4d07bd5ff7c38f0256a7bc",
-    "spec/v1/gaps.json": "7ba482a850d94e185f12b69929e35054d24b72131a997d0ef70d59c10b83f7eb",
+    "spec/v1/gaps.json": "5be0fd0a8055f5cac76346fc2a98c44553f73d3f28a39ce12dcf1979d55d1409",
     "spec/v1/gaps.schema.json": "8fd83259f556553c9df0f53e7a82ca8c2a4771d471197f69b4e2ae0ceeacfd66",
     "spec/v1/migrations.json": "4c50760be70cb644d02427bcaf5749606700edf4513f423903cf3b1d12f5c300",
     "spec/v1/migrations.schema.json": "886779aa6c22e646db097f5df210adb018a4dd14a7b815465a18c8a7056c8f72",
@@ -226,7 +226,7 @@
     "spec/v2/core/events.md": "c1a20e3aa6736119ea07aa2cf66faa808a1874d2cde4933033b65506d1742883",
     "spec/v2/core/execution.md": "8a0c9db1bbfb97c008ab9328b7333c1cc3318196e78bfbefb49e781bdf4f9d44",
     "spec/v2/core/form-content-packs.md": "02931227899676fd4581a27017be2a6c4953904717be9b81c29d12f87ab3917d",
-    "spec/v2/core/headers.md": "5cb1624fa63acc81992b6a6d842ec392cf7271aaf2f65d1f83c8c4fa286e6730",
+    "spec/v2/core/headers.md": "21d6c8220c3ac75b10e31c4cf6179abb539e2558af5006e40228d8c383ed5c92",
     "spec/v2/core/host-services.md": "18389b55286875922c26e13fbcd6c787fca2568f68b7e6f65176f1938404a218",
     "spec/v2/core/i18n.md": "882904b7d59f992ab1e5f7346167161a54cf665b8fee47e64a3862cf9133a580",
     "spec/v2/core/idempotency.md": "adbd317a6ebb57c2759c076297b31f67def9e391576bccd0bbea787b13e85872",
@@ -300,12 +300,12 @@
     "spec/v2/interop-map.schema.json": "0017c882df34ee215e2e0729de051490e09d43aac3d2c949285698ed51832f12",
     "spec/v2/migrations.json": "651954938a1e154c0b6f1e3dd6e105889d30de3bb65789f21de7f77a12869e9e",
     "spec/v2/migrations.schema.json": "b91ade6320ad1b1185c9495b9424f3aa63438ed8e412c45171c227d82c0afd86",
-    "spec/v2/path-manifest.json": "17298a245c5da9a70aa7ab0b7f2db4277e06209d6fcdd7187a8b4cea179c08f3",
+    "spec/v2/path-manifest.json": "27c2307b84376b2f22bea4e2213fc7e33ef3bf8fd1d18039f7955edb00dc9c9a",
     "spec/v2/peer-dependency-aliases.json": "d10299280abee08258502925bc327293ee413e0108cd6e6ec75ff6110653308d",
     "spec/v2/profiles.json": "180beb9ef2d161766fa23b2987e7e829851e3d316273147cf6a4a3f324befd6b",
-    "spec/v2/release.json": "0219a1874302b4f3f2e8494d3c972cb649483838f53076e612c04bdf298c56dd",
+    "spec/v2/release.json": "89c093ee04d4aaceef641782e53fbc368e21123e244246f1727fa8ac3b151101",
     "spec/v2/retention-floors.json": "eaf3722d95c79947af1d4269ef85117e126518c588cfcf1a2b21b97269f51624",
-    "spec/v2/surface-baseline.json": "88e9e211ec1c8d532c413b7407a15f15a3001099b9cda77f2bcc694028a72544"
+    "spec/v2/surface-baseline.json": "85c44cc57bfc9f8242e77dc27d7b28a1b239c694ef761cce4748ab15d6a3290f"
   },
-  "corpusCommit": "16a175bf4ad0485d8c1eefe97a83bfbc8d1057bc"
+  "corpusCommit": "1ac68fd60069d0b9729312976de4946171281f87"
 }

package/src/scenarios/v2-cors-preflight.test.ts

@@ -0,0 +1,141 @@
+/**
+ * `headers.md` §Cross-origin preflight — a host that grants an origin admits
+ * what a conforming browser client sends (suite 2.45.0, target major 2;
+ * openwop#1763; self-gated on the host's own grant).
+ *
+ * A browser client MUST send `OpenWOP-Version` and `OpenWOP-Client-Version` on
+ * every request (versioning.md §1.3, §1.5), `Authorization` on an
+ * authenticated operation and `Content-Type: application/json` with a body.
+ * None of them is CORS-safelisted, so the browser preflights. When the host
+ * grants the origin but leaves one out of `Access-Control-Allow-Headers`, the
+ * browser never sends the request: the operation is unreachable from that
+ * origin and the host's logs show nothing. Both production hosts shipped that
+ * outage with explicit lists: openwop-app on `OpenWOP-Version` (2026-09-18) and
+ * both on `OpenWOP-Client-Version` at the SDK 2.5.0 release (RFC 0219 G8).
+ *
+ * The admitted set per operation comes from `spec/v2/path-manifest.json`, which
+ * `derive-v2-api.py` writes from `api/v2/openapi.yaml`: the declared header
+ * parameters, plus `Authorization` when authenticated and `Content-Type` when
+ * the operation takes a body. For each operation the leg sends
+ * `OPTIONS <path>` (path parameters filled with a placeholder) with `Origin`,
+ * `Access-Control-Request-Method` and `Access-Control-Request-Headers`, and
+ * reads the answer the way the Fetch standard's CORS-preflight check does:
+ *
+ *   - granted: `Access-Control-Allow-Origin` is the origin or `*`. Anything
+ *     else and the host does not serve that origin: that operation is not
+ *     judged (a host MAY grant no origin at all; the rule is conditional).
+ *   - method: a CORS-safelisted method (GET, HEAD, POST) is admitted without
+ *     listing; any other must be listed, or `*` when credentials are not
+ *     allowed. Compared case-sensitively, as Fetch does.
+ *   - headers: every requested name listed (case-insensitive), or `*` when
+ *     credentials are not allowed, and `*` never admits `authorization`.
+ *
+ * The row passes when at least one operation was granted and every granted one
+ * admits its set, fails when any granted one does not (naming the operation and
+ * the missing names), and is `inapplicable` when no operation was granted. The
+ * origin is `OPENWOP_CORS_ORIGIN` (default `https://conformance.invalid`): a
+ * host with an allowlist is inapplicable at the default, and its operator sets
+ * an allowlisted origin to be witnessed. A pass carries an `observed:` detail.
+ *
+ * @see spec/v2/core/headers.md §Cross-origin preflight
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadEnv } from '../lib/env.js';
+import { v2Discovery } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { noteObservation } from '../lib/row-observation.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const ID = 'openwop.requirement.headers.cors-preflight-admits';
+const DOC = 'spec/v2/core/headers.md §Cross-origin preflight';
+const ORIGIN_ENV = 'OPENWOP_CORS_ORIGIN';
+const DEFAULT_ORIGIN = 'https://conformance.invalid';
+/** Fetch standard: a CORS-safelisted method passes the preflight method check without being listed. */
+const SAFELISTED_METHODS = new Set(['GET', 'HEAD', 'POST']);
+const PLACEHOLDER = 'conformance-cors-probe';
+
+interface ManifestOp { readonly method: string; readonly path: string; readonly operationId: string; readonly requestHeaders?: readonly string[]; readonly authenticated?: boolean; readonly requestBody?: boolean }
+interface Preflight { readonly status: number | null; readonly allowOrigin: string | null; readonly allowMethods: string | null; readonly allowHeaders: string | null; readonly allowCredentials: string | null }
+
+function operations(): ManifestOp[] | null {
+  try {
+    const manifest = JSON.parse(readFileSync(join(SCHEMAS_DIR, '..', 'spec', 'v2', 'path-manifest.json'), 'utf8')) as { operations?: ManifestOp[] };
+    const ops = manifest.operations ?? [];
+    return ops.length > 0 && ops.every((o) => Array.isArray(o.requestHeaders) && typeof o.authenticated === 'boolean' && typeof o.requestBody === 'boolean') ? ops : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The names a conforming browser client puts in Access-Control-Request-Headers for this operation, lowercased. */
+export function requestedHeaders(op: ManifestOp): string[] {
+  const names = new Set((op.requestHeaders ?? []).map((h) => h.toLowerCase()));
+  if (op.authenticated === true) names.add('authorization');
+  if (op.requestBody === true) names.add('content-type');
+  return [...names].sort();
+}
+
+const tokens = (v: string | null): string[] => (v ?? '').split(',').map((t) => t.trim()).filter((t) => t.length > 0);
+
+/** What the preflight answer fails to admit, per the Fetch standard's CORS-preflight check; empty when it admits everything. */
+export function unadmitted(op: ManifestOp, p: Preflight): { method: string | null; headers: string[] } {
+  const credentials = p.allowCredentials === 'true';
+  const methods = tokens(p.allowMethods);
+  const methodOk = SAFELISTED_METHODS.has(op.method) || methods.includes(op.method) || (!credentials && methods.includes('*'));
+  const listed = new Set(tokens(p.allowHeaders).map((h) => h.toLowerCase()));
+  const star = !credentials && listed.has('*');
+  const headers = requestedHeaders(op).filter((h) => !listed.has(h) && !(star && h !== 'authorization'));
+  return { method: methodOk ? null : op.method, headers };
+}
+
+async function preflight(baseUrl: string, op: ManifestOp, origin: string): Promise<Preflight> {
+  const path = op.path.replace(/\{[^}]+\}/g, PLACEHOLDER);
+  try {
+    const res = await fetch(`${baseUrl.replace(/\/$/, '')}${path}`, {
+      method: 'OPTIONS',
+      headers: { Origin: origin, 'Access-Control-Request-Method': op.method, 'Access-Control-Request-Headers': requestedHeaders(op).join(',') },
+    });
+    await res.arrayBuffer().catch(() => undefined);
+    const h = res.headers;
+    return { status: res.status, allowOrigin: h.get('access-control-allow-origin'), allowMethods: h.get('access-control-allow-methods'), allowHeaders: h.get('access-control-allow-headers'), allowCredentials: h.get('access-control-allow-credentials') };
+  } catch {
+    return { status: null, allowOrigin: null, allowMethods: null, allowHeaders: null, allowCredentials: null };
+  }
+}
+
+describe('headers.md §Cross-origin preflight (self-gated on the host granting the origin)', () => {
+  it('every operation a granted origin preflights admits its method and every request header the contract declares for it', async () => {
+    if (!(await v2Discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const ops = operations();
+    if (ops === null) return softSkip('blocked', 'spec/v2/path-manifest.json carries no per-operation requestHeaders / authenticated / requestBody (a corpus older than openwop#1763), so the admitted sets cannot be derived');
+    const origin = process.env[ORIGIN_ENV]?.trim() || DEFAULT_ORIGIN;
+    const { baseUrl } = loadEnv();
+
+    const granted: string[] = [];
+    const failures: string[] = [];
+    for (const op of ops) {
+      const p = await preflight(baseUrl, op, origin);
+      if (p.allowOrigin !== origin && p.allowOrigin !== '*') continue;
+      granted.push(op.operationId);
+      const miss = unadmitted(op, p);
+      if (miss.method !== null || miss.headers.length > 0) {
+        const parts = [
+          ...(miss.method === null ? [] : [`method ${miss.method} not in Access-Control-Allow-Methods (${JSON.stringify(p.allowMethods)})`]),
+          ...(miss.headers.length === 0 ? [] : [`${miss.headers.join(', ')} not in Access-Control-Allow-Headers (${JSON.stringify(p.allowHeaders)}${p.allowCredentials === 'true' ? ', credentials allowed so * admits nothing' : ''})`]),
+        ];
+        failures.push(`${op.operationId} (${op.method} ${op.path}): ${parts.join('; ')}`);
+      }
+    }
+    noteObservation(`origin ${origin}: ${granted.length}/${ops.length} operation(s) granted, ${failures.length} not admitting their set`);
+    if (granted.length === 0) {
+      return softSkip('inapplicable', `no operation's preflight granted origin ${origin} (Access-Control-Allow-Origin neither it nor *): the host does not serve that origin cross-origin, which is host policy. An operator whose host allowlists origins sets ${ORIGIN_ENV} to one of them to be witnessed`);
+    }
+    expect(
+      failures,
+      req(ID, DOC, `a host that grants an origin MUST admit, per operation, its method and every request header api/v2/openapi.yaml declares for it, Authorization when authenticated and Content-Type with a body; a browser that is refused never sends the request. ${failures.length} of ${granted.length} granted operation(s) do not: ${failures.join(' | ')}`),
+    ).toEqual([]);
+  });
+});