@openwop/openwop-conformance 1.139.0 → 1.141.0

package/README.md

@@ -79,6 +79,8 @@ Run `npm run test` for normal CI cadence; `npm run test:strict` when claiming fu
 | `OPENWOP_OTEL_COLLECTOR_GRPC_PORT=4317`   | Bind the OTLP/gRPC collector on a specific port (default `4317`, OTLP/gRPC convention). The host MUST be configured with `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:<port>` AND `OTEL_EXPORTER_OTLP_PROTOCOL=grpc`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `OPENWOP_OTEL_COLLECTOR_PORT=14318`       | Bind the OTel collector on a specific port (default `4318`). The host MUST be configured with `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:<port>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true`      | Relaxes the webhook egress guard for the loopback test receiver used by `webhook-signed-delivery.test.ts`, `webhook-negative.test.ts`, and `replay-fanout-suppression.test.ts`. **The receiver is `http://127.0.0.1:{port}/`, which `webhooks.md` forbids three separate times, and the opt-in MUST relax all three to be witnessable:** (1) the **scheme** check — §"SSRF protection" bullet 1 rejects non-`https://`, and this gate fires FIRST on a host that validates scheme before address; (2) the **registration-time** address check — §"SSRF protection"; and (3) **delivery-time re-resolution** — §"Delivery-time egress validation (RFC 0093)". Gates 2 and 3 are independent MUSTs at different layers, so an opt-in reaching only one layer **cannot** produce a witness: delivery-only leaves registration returning `400 webhook_url_rejected`, registration-only leaves the dispatcher refusing to connect. A host whose opt-in reaches one layer is **not** non-conformant — it cannot witness these scenarios, which is a property of the test posture and not of its webhook signing. The scheme gate went unstated here until 2026-08-25; a tier-2 host validating scheme-then-address was blocked by a gate the documented contract never named. Relaxing gates 2 and 3 is **test-only posture** — see `SECURITY/threat-model-secret-leakage.md` §4.9 for why a registration-time relaxation is the more dangerous of the two. When the host rejects, the scenario records `blocked` (RFC 0148 §A), not a pass.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `OPENWOP_WEBHOOK_RECEIVER_URL=<https-url>` | **The route to a webhook witness that relaxes nothing.** A host refusing the loopback receiver on *two* independent grounds — private address **and** non-`https:` — cannot be unblocked by `OPENWOP_WEBHOOK_ALLOW_PRIVATE`, because the scheme arm still stands. This supplies **the public `https:` front for THIS SUITE'S OWN receiver** (tunnel / TLS-terminating proxy), never an arbitrary endpoint: the scenario asserts on what *this process* received, so pointing registration elsewhere makes every header assertion vacuous while the row turns green. Zero deliveries with it set is a **hard failure**, never a skip. Preferred over the flag — it waives nothing and writes no durable subscription row aimed at a private address (`SECURITY/threat-model-secret-leakage.md` §4.9). Pair with `OPENWOP_WEBHOOK_RECEIVER_PORT`. |
+| `OPENWOP_WEBHOOK_RECEIVER_PORT=<port>`     | Pins the in-process webhook receiver to a known port instead of an ephemeral one. Required in practice by `OPENWOP_WEBHOOK_RECEIVER_URL`: a tunnel must be aimed at a port known **in advance**, and the receiver binds `0` by default. Unset ⇒ ephemeral, as before. |
 | `OPENWOP_MCP_FAKE_SERVER=true`            | Boots the synthetic MCP peer for `mcp-tool-roundtrip.test.ts`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `OPENWOP_MCP_REAL_SERVER_URL=<base-url>`  | Points the MCP wire-shape probe at a real MCP server. The probe POSTs JSON-RPC and reads a single-JSON response — matches MCP's `streamable-http` transport in single-response mode. **Does NOT support** stdio transport (which is what most `modelcontextprotocol/servers` references default to) or SSE-streamed responses; an operator collecting interop evidence today runs a custom `StreamableHTTPServerTransport`-style server that returns a single JSON body per request. Adding SSE-frame parsing is tracked in `docs/PROTOCOL-GAP-CLOSURE-PLAN.md` Track 6. Assertions relax to shape-only. When both this and `OPENWOP_MCP_FAKE_SERVER` are set, the real URL wins. Phase 3 T3.4 interop-evidence path.                                                                                                               |
 | `OPENWOP_A2A_FAKE_PEER=true`              | Boots the synthetic A2A peer for `a2a-task-roundtrip.test.ts`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

package/dist/lib/scenario-disposition.js

@@ -28,6 +28,7 @@
 import { PROFILE_FLOOR_SCENARIOS } from './profiles.js';
 import { requirementIdForScenario, requirementIdForPrefix, requirementsFor } from './requirement-registry.js';
 import { UNCLASSIFIED_RETURN_DETAIL } from './soft-skip.js';
+import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL } from './spec-coherence.js';
 import { CERTIFIABLE } from './requirement-ledger.js';
 /** All scenario basenames that appear in some profile's runtime floor. */
 export function floorScenarioFiles() {
@@ -100,7 +101,19 @@ export function fileDisposition(states, gateReason, assertionCount) {
  *   - every test `ctx.skip()`ped ⇒ the file's noted reason if it wrote one
  *     BEFORE skipping (`ctx.skip()` throws), else `blocked` + the marker.
  */
-export function resolveFileRecord(states, gateReason, assertionCount, noted) {
+export function resolveFileRecord(states, gateReason, assertionCount, noted, specCoherenceFile) {
+    // A scenario whose subject is the CORPUS, skipped because the published
+    // tarball does not bundle spec/v1/. RFC 0148 §A: `blocked` is defined over
+    // ADVERTISED BEHAVIOUR, and there is none here — nothing about the host was
+    // ever going to be exercised. `inapplicable` is the honest label, and it is
+    // CERTIFIABLE, so these rows stop counting against a host that cannot affect
+    // them. See lib/spec-coherence.ts for why not a new disposition value.
+    if (specCoherenceFile !== undefined
+        && SPEC_COHERENCE_SCENARIOS.has(specCoherenceFile)
+        && !states.includes('fail')
+        && assertionCount === 0) {
+        return { disposition: 'inapplicable', detail: SPEC_COHERENCE_DETAIL };
+    }
     let { disposition, detail } = fileDisposition(states, gateReason, assertionCount);
     if (disposition === 'executed-pass' && assertionCount === 0) {
         if (noted !== null) {

package/dist/lib/spec-coherence.js

@@ -0,0 +1,103 @@
+/**
+ * Scenarios that measure the SPEC, not the host (RFC 0148 §A).
+ *
+ * ## The defect
+ *
+ * 28 scenarios read `spec/v1/*.md` to check the corpus is internally coherent —
+ * that the `protocolVersion` grammar in the schema matches RFC 0149, that error
+ * envelopes are the shape `error-envelope.schema.json` declares, that every
+ * normative example extracts and validates. They assert nothing whatever about
+ * a host.
+ *
+ * `spec/v1/` is deliberately NOT bundled in the published tarball (`paths.ts`
+ * says so), so in a published-layout run `V1_DIR` is null and they
+ * `describe.skipIf` at COLLECTION time. No test body runs, so no `softSkip`
+ * note is recorded, and `resolveFileRecord` resolves an all-skipped file with no
+ * reason to **`blocked`** carrying "every test returned early … no recorded
+ * reason".
+ *
+ * That row then lands in a HOST's certification bundle. A host operator reads
+ * `blocked` and cannot tell it from a real gap in their implementation. A
+ * tier-2 host measured 13 such rows — **a third of their undiagnosed set** —
+ * and only discovered what they were by pointing `OPENWOP_CONFORMANCE_ROOT` at
+ * a spec checkout and watching 85 assertions pass in about a second, 59 of them
+ * against a dead `localhost:9`.
+ *
+ * ## Why `inapplicable`, and why not the other four
+ *
+ * RFC 0148 §A defines the two candidates precisely, and the definitions decide
+ * it:
+ *
+ *   - `blocked` — "**advertised behavior** could not be exercised because a
+ *     required seam, fixture, credential, or dependency was unavailable."
+ *     There is no advertised behaviour here. Nothing about the host was ever
+ *     going to be exercised, so nothing about the host failed to be.
+ *   - `inapplicable` — "the requirement does not apply to the captured
+ *     discovery/profile set." A requirement about the spec corpus does not
+ *     apply to any host's discovery set. This is the honest label.
+ *
+ * `executed-pass` is wrong for the obvious reason: in a run where the corpus is
+ * absent, nothing executed, and claiming a pass for an unrun scenario is the
+ * defect this whole disposition system exists to prevent. A NEW disposition
+ * value was considered and rejected — `certification-bundle-v2.schema.json`
+ * enumerates the five, and `verifyBundleV2` is a published consumer contract,
+ * so a sixth is a wire break for every existing verifier. Correct use of an
+ * existing value costs nothing and breaks no one.
+ *
+ * `inapplicable` is in `CERTIFIABLE`, which is the point: these rows stop
+ * counting against a host that has no way to affect them.
+ *
+ * ## Why a list and not a predicate
+ *
+ * The property is static — "gates on `V1_DIR` and never touches `driver`" — and
+ * cannot be evaluated from `setup.ts` at runtime. So it is a list, and a list
+ * drifts. `spec-coherence-registry.test.ts` re-derives it from source on every
+ * run and fails when the two disagree, which is the only thing that makes a
+ * hand-maintained set trustworthy.
+ *
+ * ## What is deliberately NOT here
+ *
+ * Seven scenarios gate on `V1_DIR` **and** drive the host
+ * (`replay-side-effect-suppression`, `data-residency-admission`,
+ * `profile-discovery-core-alias`, `workflow-variable-format`,
+ * `workflow-chain-deferred-parameters`, `artifact-type-store-emission`,
+ * `artifact-type-registration-source`). Those assert advertised host behaviour
+ * that could not be exercised because a dependency was unavailable — which is
+ * `blocked`, exactly as §A defines it. Classifying them `inapplicable` would
+ * tell a host "this does not apply to you" about a requirement that does.
+ */
+/** Scenarios whose subject is the corpus. Kept honest by `spec-coherence-registry.test.ts`. */
+export const SPEC_COHERENCE_SCENARIOS = new Set([
+    'artifact-schema-compile-bounded.test.ts',
+    'artifact-type-legacy-ids.test.ts',
+    'capability-example-root-layout.test.ts',
+    'certification-floor-enforcement.test.ts',
+    'chain-subchain-unsupported-refused.test.ts',
+    'compensation-profile.test.ts',
+    'core-manifest-and-extension-registry.test.ts',
+    'discovery-canonical-family-no-shadow.test.ts',
+    'edge-condition-truthy-falsy.test.ts',
+    'effect-identity-composition.test.ts',
+    'effect-identity-cross-scope.test.ts',
+    'error-envelope-canonical-shape.test.ts',
+    'form-content-packs.test.ts',
+    'multi-region-effect-vocabulary.test.ts',
+    'normative-example-extraction.test.ts',
+    'openapi-asyncapi-sdk-parity.test.ts',
+    'pack-manifest-extensions.test.ts',
+    'protocol-version-grammar.test.ts',
+    'registry-declarative-kinds.test.ts',
+    'rfc-0147-self-audit.test.ts',
+    'rfc-lifecycle-coherence.test.ts',
+    'semantic-digest-v2.test.ts',
+    'spec-corpus-validity.test.ts',
+    'spec-section-citations.test.ts',
+    'tool-result-trust-monotone.test.ts',
+    'versioned-composition-profiles.test.ts',
+    'workflow-chain-internal-flag.test.ts',
+    'workload-identity-profile.test.ts',
+]);
+/** The reason recorded on such a row, written for the host operator reading it. */
+export const SPEC_COHERENCE_DETAIL = 'inapplicable to any host: this scenario reads spec/v1/ to check the SPEC corpus is internally coherent and asserts nothing about a host. '
+    + 'The published tarball does not bundle spec/v1/ (see lib/paths.ts), so it does not run here. '
+    + 'Set OPENWOP_CONFORMANCE_ROOT to a spec checkout to run it; it needs no host.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop-conformance",
-  "version": "1.139.0",
+  "version": "1.141.0",
   "description": "Production-ready black-box conformance suite for OpenWOP v1.0 compliant servers.",
   "repository": {
     "type": "git",

package/schemas/CORPUS-STAMP.json

@@ -1,5 +1,5 @@
 {
   "_comment": "Provenance of this vendored schemas/ copy. See conformance/README.md \u00a7\"Resolving the contract\". Compare against the stamp in your installed @openwop/openwop-conformance to detect a stale hand-copied contract.",
-  "suiteVersion": "1.139.0",
-  "corpusCommit": "f34a41ac4c1737ca8af34d0f7f17876268f58e69"
+  "suiteVersion": "1.141.0",
+  "corpusCommit": "de70377b76d34fdec3b1f4b7e27b8ade95a9ba27"
 }

package/src/lib/scenario-disposition.ts

@@ -29,6 +29,7 @@
 import { PROFILE_FLOOR_SCENARIOS } from './profiles.js';
 import { requirementIdForScenario, requirementIdForPrefix, requirementsFor } from './requirement-registry.js';
 import { UNCLASSIFIED_RETURN_DETAIL } from './soft-skip.js';
+import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL } from './spec-coherence.js';
 import { CERTIFIABLE, type Disposition, type LedgerEntry } from './requirement-ledger.js';
 
 /** All scenario basenames that appear in some profile's runtime floor. */
@@ -112,7 +113,22 @@ export function resolveFileRecord(
   gateReason: 'inapplicable' | 'skipped' | undefined,
   assertionCount: number,
   noted: { kind: 'inapplicable' | 'skipped' | 'blocked'; reason: string } | null,
+  specCoherenceFile?: string,
 ): { disposition: Disposition; detail?: string } {
+  // A scenario whose subject is the CORPUS, skipped because the published
+  // tarball does not bundle spec/v1/. RFC 0148 §A: `blocked` is defined over
+  // ADVERTISED BEHAVIOUR, and there is none here — nothing about the host was
+  // ever going to be exercised. `inapplicable` is the honest label, and it is
+  // CERTIFIABLE, so these rows stop counting against a host that cannot affect
+  // them. See lib/spec-coherence.ts for why not a new disposition value.
+  if (
+    specCoherenceFile !== undefined
+    && SPEC_COHERENCE_SCENARIOS.has(specCoherenceFile)
+    && !states.includes('fail')
+    && assertionCount === 0
+  ) {
+    return { disposition: 'inapplicable', detail: SPEC_COHERENCE_DETAIL };
+  }
   let { disposition, detail } = fileDisposition(states, gateReason, assertionCount);
   if (disposition === 'executed-pass' && assertionCount === 0) {
     if (noted !== null) {

package/src/lib/spec-coherence-registry.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Keeps `SPEC_COHERENCE_SCENARIOS` honest by re-deriving it from source.
+ *
+ * A hand-maintained list of filenames is a claim that decays silently: a new
+ * spec-coherence scenario lands and reports `blocked` in every host's bundle
+ * forever, or one grows a `driver` call and starts telling hosts a requirement
+ * about their own behaviour does not apply to them. Neither shows up as a
+ * failure anywhere — which is the whole reason the original defect survived.
+ *
+ * The membership rule is mechanical, so the check can be too:
+ *   gates on `V1_DIR === null`  AND  never calls `driver.get/post/delete`.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL } from './spec-coherence.js';
+import { resolveFileRecord } from './scenario-disposition.js';
+
+const SCENARIOS = new URL('../scenarios/', import.meta.url).pathname;
+
+function derive(): { pure: string[]; hostTouching: string[] } {
+  const pure: string[] = [];
+  const hostTouching: string[] = [];
+  for (const f of readdirSync(SCENARIOS)) {
+    if (!f.endsWith('.test.ts')) continue;
+    const src = readFileSync(join(SCENARIOS, f), 'utf8');
+    if (!/V1_DIR\s*===?\s*null/.test(src)) continue;
+    (/\bdriver\.(get|post|delete)\b/.test(src) ? hostTouching : pure).push(f);
+  }
+  return { pure: pure.sort(), hostTouching: hostTouching.sort() };
+}
+
+describe('SPEC_COHERENCE_SCENARIOS is derivable, not asserted', () => {
+  it('matches every scenario that reads spec/v1 and never drives a host', () => {
+    const { pure } = derive();
+    const listed = [...SPEC_COHERENCE_SCENARIOS].sort();
+    // Named diffs rather than a bare inequality: a failure here should say
+    // which file to add or drop, not that two sets differ.
+    expect(pure.filter((f) => !SPEC_COHERENCE_SCENARIOS.has(f)), 'reads spec/v1, drives no host, NOT in the registry — it will report `blocked` in every host bundle').toEqual([]);
+    expect(listed.filter((f) => !pure.includes(f)), 'in the registry but no longer qualifies — it now drives a host, or stopped reading spec/v1').toEqual([]);
+  });
+
+  it('excludes the host-touching ones, which are honestly `blocked`', () => {
+    // These assert ADVERTISED behaviour that a missing dependency prevented
+    // exercising — RFC 0148 §A's definition of `blocked`, verbatim. Calling
+    // them `inapplicable` would tell a host a requirement about its own
+    // behaviour does not apply to it.
+    const { hostTouching } = derive();
+    expect(hostTouching.length, 'expected some V1_DIR-gated scenarios to also drive the host').toBeGreaterThan(0);
+    for (const f of hostTouching) {
+      expect(SPEC_COHERENCE_SCENARIOS.has(f), `${f} drives a host and must NOT be classified inapplicable`).toBe(false);
+    }
+  });
+
+  it('the registry is non-empty — an empty set would silently disable the fix', () => {
+    expect(SPEC_COHERENCE_SCENARIOS.size).toBeGreaterThan(20);
+  });
+});
+
+describe('resolveFileRecord classifies a corpus scenario as inapplicable, not blocked', () => {
+  // A published-layout run: describe.skipIf fires at COLLECTION, so vitest
+  // reports the file's tests as skipped, nothing notes a reason, and before
+  // this change resolveFileRecord returned `blocked` with the unclassified
+  // marker — the row a host operator could not tell from a real gap.
+  const CORPUS = 'protocol-version-grammar.test.ts';
+
+  it('a corpus scenario that never ran is inapplicable, with a reason aimed at the host operator', () => {
+    const r = resolveFileRecord(['skip', 'skip'], undefined, 0, null, CORPUS);
+    expect(r.disposition).toBe('inapplicable');
+    expect(r.detail).toBe(SPEC_COHERENCE_DETAIL);
+    expect(r.detail).toContain('asserts nothing about a host');
+    expect(r.detail).toContain('OPENWOP_CONFORMANCE_ROOT');
+  });
+
+  it('WITHOUT the registry it would still be blocked — the branch is what changes it', () => {
+    // Same inputs, filename withheld: the pre-change behaviour. This is the
+    // negative control; if it ever returns `inapplicable`, the branch is not
+    // what is doing the work and the test above proves nothing.
+    const r = resolveFileRecord(['skip', 'skip'], undefined, 0, null);
+    expect(r.disposition).toBe('blocked');
+  });
+
+  it('a non-corpus scenario is untouched', () => {
+    const r = resolveFileRecord(['skip', 'skip'], undefined, 0, null, 'webhook-signed-delivery.test.ts');
+    expect(r.disposition).toBe('blocked');
+  });
+
+  it('a corpus scenario that FAILED is never laundered into inapplicable', () => {
+    // The guard that matters: if the corpus IS present and an assertion fails,
+    // that is a real spec-coherence defect and must stay executed-fail.
+    const r = resolveFileRecord(['pass', 'fail'], undefined, 12, null, CORPUS);
+    expect(r.disposition).toBe('executed-fail');
+  });
+
+  it('a corpus scenario that RAN and passed stays executed-pass', () => {
+    const r = resolveFileRecord(['pass'], undefined, 40, null, CORPUS);
+    expect(r.disposition).toBe('executed-pass');
+  });
+});

package/src/lib/spec-coherence.ts

@@ -0,0 +1,106 @@
+/**
+ * Scenarios that measure the SPEC, not the host (RFC 0148 §A).
+ *
+ * ## The defect
+ *
+ * 28 scenarios read `spec/v1/*.md` to check the corpus is internally coherent —
+ * that the `protocolVersion` grammar in the schema matches RFC 0149, that error
+ * envelopes are the shape `error-envelope.schema.json` declares, that every
+ * normative example extracts and validates. They assert nothing whatever about
+ * a host.
+ *
+ * `spec/v1/` is deliberately NOT bundled in the published tarball (`paths.ts`
+ * says so), so in a published-layout run `V1_DIR` is null and they
+ * `describe.skipIf` at COLLECTION time. No test body runs, so no `softSkip`
+ * note is recorded, and `resolveFileRecord` resolves an all-skipped file with no
+ * reason to **`blocked`** carrying "every test returned early … no recorded
+ * reason".
+ *
+ * That row then lands in a HOST's certification bundle. A host operator reads
+ * `blocked` and cannot tell it from a real gap in their implementation. A
+ * tier-2 host measured 13 such rows — **a third of their undiagnosed set** —
+ * and only discovered what they were by pointing `OPENWOP_CONFORMANCE_ROOT` at
+ * a spec checkout and watching 85 assertions pass in about a second, 59 of them
+ * against a dead `localhost:9`.
+ *
+ * ## Why `inapplicable`, and why not the other four
+ *
+ * RFC 0148 §A defines the two candidates precisely, and the definitions decide
+ * it:
+ *
+ *   - `blocked` — "**advertised behavior** could not be exercised because a
+ *     required seam, fixture, credential, or dependency was unavailable."
+ *     There is no advertised behaviour here. Nothing about the host was ever
+ *     going to be exercised, so nothing about the host failed to be.
+ *   - `inapplicable` — "the requirement does not apply to the captured
+ *     discovery/profile set." A requirement about the spec corpus does not
+ *     apply to any host's discovery set. This is the honest label.
+ *
+ * `executed-pass` is wrong for the obvious reason: in a run where the corpus is
+ * absent, nothing executed, and claiming a pass for an unrun scenario is the
+ * defect this whole disposition system exists to prevent. A NEW disposition
+ * value was considered and rejected — `certification-bundle-v2.schema.json`
+ * enumerates the five, and `verifyBundleV2` is a published consumer contract,
+ * so a sixth is a wire break for every existing verifier. Correct use of an
+ * existing value costs nothing and breaks no one.
+ *
+ * `inapplicable` is in `CERTIFIABLE`, which is the point: these rows stop
+ * counting against a host that has no way to affect them.
+ *
+ * ## Why a list and not a predicate
+ *
+ * The property is static — "gates on `V1_DIR` and never touches `driver`" — and
+ * cannot be evaluated from `setup.ts` at runtime. So it is a list, and a list
+ * drifts. `spec-coherence-registry.test.ts` re-derives it from source on every
+ * run and fails when the two disagree, which is the only thing that makes a
+ * hand-maintained set trustworthy.
+ *
+ * ## What is deliberately NOT here
+ *
+ * Seven scenarios gate on `V1_DIR` **and** drive the host
+ * (`replay-side-effect-suppression`, `data-residency-admission`,
+ * `profile-discovery-core-alias`, `workflow-variable-format`,
+ * `workflow-chain-deferred-parameters`, `artifact-type-store-emission`,
+ * `artifact-type-registration-source`). Those assert advertised host behaviour
+ * that could not be exercised because a dependency was unavailable — which is
+ * `blocked`, exactly as §A defines it. Classifying them `inapplicable` would
+ * tell a host "this does not apply to you" about a requirement that does.
+ */
+
+/** Scenarios whose subject is the corpus. Kept honest by `spec-coherence-registry.test.ts`. */
+export const SPEC_COHERENCE_SCENARIOS: ReadonlySet<string> = new Set([
+  'artifact-schema-compile-bounded.test.ts',
+  'artifact-type-legacy-ids.test.ts',
+  'capability-example-root-layout.test.ts',
+  'certification-floor-enforcement.test.ts',
+  'chain-subchain-unsupported-refused.test.ts',
+  'compensation-profile.test.ts',
+  'core-manifest-and-extension-registry.test.ts',
+  'discovery-canonical-family-no-shadow.test.ts',
+  'edge-condition-truthy-falsy.test.ts',
+  'effect-identity-composition.test.ts',
+  'effect-identity-cross-scope.test.ts',
+  'error-envelope-canonical-shape.test.ts',
+  'form-content-packs.test.ts',
+  'multi-region-effect-vocabulary.test.ts',
+  'normative-example-extraction.test.ts',
+  'openapi-asyncapi-sdk-parity.test.ts',
+  'pack-manifest-extensions.test.ts',
+  'protocol-version-grammar.test.ts',
+  'registry-declarative-kinds.test.ts',
+  'rfc-0147-self-audit.test.ts',
+  'rfc-lifecycle-coherence.test.ts',
+  'semantic-digest-v2.test.ts',
+  'spec-corpus-validity.test.ts',
+  'spec-section-citations.test.ts',
+  'tool-result-trust-monotone.test.ts',
+  'versioned-composition-profiles.test.ts',
+  'workflow-chain-internal-flag.test.ts',
+  'workload-identity-profile.test.ts',
+]);
+
+/** The reason recorded on such a row, written for the host operator reading it. */
+export const SPEC_COHERENCE_DETAIL =
+  'inapplicable to any host: this scenario reads spec/v1/ to check the SPEC corpus is internally coherent and asserts nothing about a host. '
+  + 'The published tarball does not bundle spec/v1/ (see lib/paths.ts), so it does not run here. '
+  + 'Set OPENWOP_CONFORMANCE_ROOT to a spec checkout to run it; it needs no host.';

package/src/lib/webhook-receiver.test.ts

@@ -12,13 +12,14 @@
  * @see webhook-receiver.ts, spec/v1/webhooks.md §"Delivery headers"
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 import { createHmac } from 'node:crypto';
 import {
   SIGNATURE_PREFIX,
   createReceiverState,
   verifyWebhookDelivery,
   signPayload,
+  resolveRegistrationUrl,
 } from './webhook-receiver.js';
 
 const SECRET = 'shhh-not-a-real-secret';
@@ -74,3 +75,70 @@ describe('webhook-receiver: the X-openwop-Signature prefix follows the spec', ()
     expect(algorithmHeader).toBe('v1');
   });
 });
+
+/**
+ * `OPENWOP_WEBHOOK_RECEIVER_URL` validation.
+ *
+ * Each case names the gate it is about, taken from `webhooks.md`, rather than
+ * restating the implementation: the point of the variable is to clear all three
+ * SSRF gates honestly, so a value that cannot clear one of them is an operator
+ * error the suite must refuse LOUDLY. A skip here would hide a
+ * misconfiguration behind a disposition that reads as "the host could not be
+ * exercised", which is a claim about the host and would be false.
+ */
+describe('resolveRegistrationUrl — OPENWOP_WEBHOOK_RECEIVER_URL', () => {
+  const LOCAL = 'http://127.0.0.1:54321/';
+  const saved = process.env.OPENWOP_WEBHOOK_RECEIVER_URL;
+  const set = (v: string | undefined) => {
+    if (v === undefined) delete process.env.OPENWOP_WEBHOOK_RECEIVER_URL;
+    else process.env.OPENWOP_WEBHOOK_RECEIVER_URL = v;
+  };
+  afterEach(() => set(saved));
+
+  it('unset ⇒ registers the local receiver unchanged, not tunnelled', () => {
+    set(undefined);
+    expect(resolveRegistrationUrl(LOCAL)).toEqual({ url: LOCAL, tunnelled: false });
+  });
+
+  it('whitespace-only is treated as unset rather than as a malformed URL', () => {
+    set('   ');
+    expect(resolveRegistrationUrl(LOCAL)).toEqual({ url: LOCAL, tunnelled: false });
+  });
+
+  it('a public https front is used for registration and marked tunnelled', () => {
+    set('https://tunnel.example.com/hook');
+    expect(resolveRegistrationUrl(LOCAL)).toEqual({
+      url: 'https://tunnel.example.com/hook',
+      tunnelled: true,
+    });
+  });
+
+  it('rejects http: — cannot clear gate 1 (webhooks.md §"Register": url MUST be https)', () => {
+    set('http://tunnel.example.com/hook');
+    expect(() => resolveRegistrationUrl(LOCAL)).toThrow(/MUST be https/i);
+  });
+
+  it.each([
+    ['loopback name', 'https://localhost/hook'],
+    ['loopback v4', 'https://127.0.0.1/hook'],
+    ['RFC1918 10/8', 'https://10.1.2.3/hook'],
+    ['RFC1918 192.168/16', 'https://192.168.1.9/hook'],
+    ['RFC1918 172.16/12', 'https://172.20.0.5/hook'],
+    ['link-local', 'https://169.254.169.254/hook'],
+  ])('rejects %s — cannot clear gate 2 (registration-time address check)', (_label, url) => {
+    set(url);
+    expect(() => resolveRegistrationUrl(LOCAL)).toThrow(/publicly-resolvable/i);
+  });
+
+  it('rejects a value that is not a URL at all', () => {
+    set('not a url');
+    expect(() => resolveRegistrationUrl(LOCAL)).toThrow(/not a valid URL/i);
+  });
+
+  it('does not reject a public host that merely LOOKS private (172.32 is public)', () => {
+    // 172.16.0.0/12 ends at 172.31.255.255. A naive /^172\./ check would
+    // reject this and send an operator hunting a nonexistent misconfiguration.
+    set('https://172.32.0.1/hook');
+    expect(resolveRegistrationUrl(LOCAL).tunnelled).toBe(true);
+  });
+});

package/src/lib/webhook-receiver.ts

@@ -184,3 +184,73 @@ export async function discoverOwnedTenant(
   // Pre-S29 hosts that copied the suite's misnamed field: tolerated, never asserted.
   return typeof owner?.tenantId === 'string' && owner.tenantId.length > 0 ? owner.tenantId : undefined;
 }
+
+/**
+ * The public `https:` front for the conformance webhook receiver, when the operator
+ * has wired one (`OPENWOP_WEBHOOK_RECEIVER_URL`).
+ *
+ * This does NOT point the host at some third-party endpoint. The delivery must
+ * still land on the local `startReceiver()` server, because every assertion in
+ * the scenario reads `receiver.received` — an IN-PROCESS array. Registering an
+ * arbitrary URL would send the delivery somewhere the suite cannot observe, and
+ * the row would turn green while every header and HMAC assertion went vacuous.
+ * That is the precise defect this suite exists to catch, so the variable is
+ * specified as "a tunnel or TLS-terminating proxy in front of THIS receiver",
+ * never "an endpoint of your choosing".
+ *
+ * The suite cannot verify that the tunnel actually fronts this process — that
+ * is the operator's contract. What it CAN do is refuse to let a mis-wired
+ * tunnel look like a pass: with the variable set, zero observed deliveries is a
+ * hard assertion failure, never a soft-skip (see the delivery assertion below).
+ *
+ * Validation is deliberately strict and fails LOUDLY rather than skipping: a
+ * malformed value is an operator error, and turning it into a `blocked` row
+ * would hide the misconfiguration behind a disposition that reads as
+ * "the host could not be exercised".
+ */
+export function resolveRegistrationUrl(localUrl: string): { url: string; tunnelled: boolean } {
+  const raw = process.env.OPENWOP_WEBHOOK_RECEIVER_URL?.trim();
+  if (!raw) return { url: localUrl, tunnelled: false };
+
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(
+      `OPENWOP_WEBHOOK_RECEIVER_URL is not a valid URL: ${JSON.stringify(raw)}`,
+    );
+  }
+
+  // Must clear gate 1 (scheme). An `http:` front cannot satisfy a host that
+  // validates scheme before address, which is the ordering that made the
+  // ALLOW_PRIVATE flag insufficient in the first place.
+  if (parsed.protocol !== 'https:') {
+    throw new Error(
+      `OPENWOP_WEBHOOK_RECEIVER_URL MUST be https: (got ${parsed.protocol}). ` +
+        'A plain-http front cannot clear the scheme gate, so it cannot witness this scenario.',
+    );
+  }
+
+  // Must clear gate 2 (registration-time address check). A loopback or private
+  // hostname here is just the local URL wearing a different scheme — it would
+  // be rejected for the same reason, and the operator would read the resulting
+  // failure as a host defect rather than as their own misconfiguration.
+  const host = parsed.hostname.toLowerCase();
+  const isLoopback =
+    host === 'localhost' || host === '::1' || host.startsWith('127.');
+  const isPrivate =
+    /^10\./.test(host) ||
+    /^192\.168\./.test(host) ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+    /^169\.254\./.test(host) ||
+    /^(fc|fd)/.test(host);
+  if (isLoopback || isPrivate) {
+    throw new Error(
+      `OPENWOP_WEBHOOK_RECEIVER_URL MUST be a publicly-resolvable host (got ${parsed.hostname}). ` +
+        'It is the PUBLIC front for the local receiver — a tunnel or TLS-terminating proxy — ' +
+        'not the receiver address itself.',
+    );
+  }
+
+  return { url: raw, tunnelled: true };
+}

package/src/scenarios/webhook-signed-delivery.test.ts

@@ -63,6 +63,32 @@
  * writes a durable subscription row that survives the flag being turned
  * back off.
  *
+ * `OPENWOP_WEBHOOK_RECEIVER_URL` — the route that relaxes NOTHING (added
+ * 2026-08-28). Set it to a public `https:` tunnel or TLS-terminating proxy
+ * standing in front of this scenario's own local receiver. Registration then
+ * uses that URL and all three gates are satisfied honestly: the scheme is
+ * `https:`, the registered address is public, and delivery-time re-resolution
+ * resolves a public address it is entitled to connect to. No guard is waived,
+ * no durable private-address row is written, and §4.9's hazard does not arise.
+ *
+ * This exists because the ALLOW_PRIVATE contract above is unsatisfiable for a
+ * host whose guard is strongest at registration time: reported by a tier-2
+ * host (2026-08-25) whose `classifyUrl` rejects on scheme AND address as two
+ * independent grounds returning one code, so relaxing the address check leaves
+ * the scheme check standing and the row `blocked` either way. Such a host is
+ * conformant and was simply unmeasurable. It is now measurable.
+ *
+ * Two things it deliberately does NOT do. It is not "register any endpoint":
+ * the assertions read an in-process array, so a third-party destination would
+ * turn the row green while every assertion went vacuous — see
+ * `resolveRegistrationUrl`. And it does not soften a rejection into a skip: a
+ * host that refuses a legitimate public https destination FAILS, because
+ * `blocked` would let it record a missing precondition forever instead of the
+ * finding it earned.
+ *
+ * Paired with a positive control (bottom of this file) so the tunnelled pass
+ * is attributable to a guard that works rather than to a guard that is absent.
+ *
  * When the host rejects with `400 webhook_url_rejected`, this scenario
  * records `blocked` (RFC 0148 §A) — NOT a pass. Under a plain
  * `vitest run` the console still prints "1 passed", because that is
@@ -81,7 +107,7 @@ import { driver } from '../lib/driver.js';
 import { discoveryFamilies } from '../lib/discovery-capabilities.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
-import { discoverOwnedTenant } from '../lib/webhook-receiver.js';
+import { discoverOwnedTenant, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
 
 interface DeliveredRequest {
   readonly headers: Record<string, string>;
@@ -105,7 +131,16 @@ async function startReceiver(): Promise<{ server: Server; url: string; received:
       res.end();
     });
   });
-  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+  // Port 0 (ephemeral) by default — nothing outside this process needs to find
+  // it. But OPENWOP_WEBHOOK_RECEIVER_URL fronts THIS receiver through a tunnel,
+  // and a tunnel has to be pointed at a port the operator knows in ADVANCE. An
+  // ephemeral port makes that variable unusable by anyone not reading the port
+  // out of a running process — a gap found by standing up a real TLS front and
+  // trying to use the feature, not by reading the code. OPENWOP_WEBHOOK_RECEIVER_PORT
+  // pins it so `ngrok http <port>` (or a proxy) has a stable target.
+  const pinned = Number(process.env['OPENWOP_WEBHOOK_RECEIVER_PORT'] ?? '');
+  const bindPort = Number.isInteger(pinned) && pinned > 0 && pinned < 65536 ? pinned : 0;
+  await new Promise<void>((resolve) => server.listen(bindPort, '127.0.0.1', () => resolve()));
   const addr = server.address();
   if (typeof addr !== 'object' || addr === null) throw new Error('receiver address unavailable');
   return { server, url: `http://127.0.0.1:${addr.port}/`, received };
@@ -150,23 +185,43 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     // tenantId is 403'd by a host that scopes subscriptions by membership
     // (RFC 0093). Single-tenant hosts return undefined ⇒ omit tenantId.
     const ownedTenant = await discoverOwnedTenant(driver);
+    const registration = resolveRegistrationUrl(receiver.url);
     const reg = await driver.post('/v1/webhooks', {
-      url: receiver.url,
+      url: registration.url,
       events: ['run.completed'],
       ...(ownedTenant ? { tenantId: ownedTenant } : {}),
     });
 
-    // SSRF guard skip: if the host rejects loopback destinations,
-    // honor the operator contract and skip rather than fail.
+    // SSRF guard: if the host rejects the destination, what that MEANS depends
+    // on which URL was registered.
+    //
+    //   * No tunnel wired (loopback URL): the host is refusing a private
+    //     address, which webhooks.md REQUIRES it to do. That is correct
+    //     behaviour and the scenario is unwitnessable here — `blocked`.
+    //   * Tunnel wired (public https URL): the host refused a destination the
+    //     spec makes legitimate. RFC 0093 does not permit rejecting a public
+    //     https host, so this is a FINDING, not a missing precondition. Fail.
+    //
+    // Soft-skipping the second case would let a host that rejects everything
+    // record `blocked` forever instead of the failure it earned.
     if (reg.status === 400) {
       const body = reg.json as { error?: string };
       if (body.error === 'webhook_url_rejected') {
-        // eslint-disable-next-line no-console
-        console.warn(
-          '[webhook-signed-delivery] host SSRF guard rejected the loopback receiver; ' +
-            'set OPENWOP_WEBHOOK_ALLOW_PRIVATE=true on the host (or equivalent) to run',
+        if (!registration.tunnelled) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            '[webhook-signed-delivery] host SSRF guard rejected the loopback receiver; ' +
+              'set OPENWOP_WEBHOOK_RECEIVER_URL to a public https tunnel in front of it ' +
+              '(preferred — relaxes no guard), or OPENWOP_WEBHOOK_ALLOW_PRIVATE=true on the host',
+          );
+          return softSkip('blocked', 'precondition not met — `body.error === \'webhook_url_rejected\'` returned early (seam, prior step, or fixture unavailable)');
+        }
+        expect.fail(
+          `host rejected the operator-supplied public https receiver (${registration.url}) with ` +
+            'webhook_url_rejected. A public https destination is legitimate under ' +
+            'webhooks.md §"SSRF protection" and RFC 0093 §"Delivery-time egress validation"; ' +
+            'rejecting it is a host defect, not an unmet precondition.',
         );
-        return softSkip('blocked', 'precondition not met — `body.error === \'webhook_url_rejected\'` returned early (seam, prior step, or fixture unavailable)');
       }
     }
 
@@ -216,9 +271,19 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
         return false;
       }
     });
+    // With a tunnel wired this is the assertion that keeps a mis-wired front
+    // from reading as a pass. Registration succeeded, so the host believes it
+    // has a subscriber; if nothing arrived HERE, the delivery went somewhere
+    // this process cannot see and every assertion below it would be vacuous.
+    // It fails — it must never soft-skip.
     expect(ourDeliveries.length, driver.describe(
       'webhooks.md §"Delivery"',
-      'host MUST POST at least one event for THIS run to a registered subscriber after run.completed',
+      registration.tunnelled
+        ? 'host MUST POST at least one event for THIS run to the registered subscriber. ' +
+          'Registration was accepted, so zero deliveries observed on the local receiver means ' +
+          'either the host did not deliver, or OPENWOP_WEBHOOK_RECEIVER_URL does not actually ' +
+          'front this process. Both are failures; neither is a skip.'
+        : 'host MUST POST at least one event for THIS run to a registered subscriber after run.completed',
     )).toBeGreaterThan(0);
 
     // Validate the FIRST delivery's signature contract. Other deliveries
@@ -268,4 +333,62 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     expect(del.status).toBeGreaterThanOrEqual(200);
     expect(del.status).toBeLessThan(300);
   });
+
+  /**
+   * POSITIVE CONTROL for the tunnel path.
+   *
+   * Without this, the tunnel run passes identically on two very different
+   * hosts: one whose SSRF guard is intact and was cleared by a legitimate
+   * public destination, and one that has NO GUARD AT ALL and would have
+   * accepted the loopback URL just as happily. The green would be reporting on
+   * the operator's tunnel rather than on the host's behaviour, and the
+   * variable would be doing no work.
+   *
+   * So: with the tunnel wired, re-register the LOOPBACK url and require that
+   * the host still refuses it. That is what makes the sibling test's pass
+   * attributable to the guard being cleared rather than absent.
+   *
+   * A host that ACCEPTS loopback here is not necessarily non-conformant — it
+   * may be running with `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true`. But in that
+   * configuration the tunnel is demonstrating nothing, and saying so is the
+   * control's whole job.
+   */
+  it('control: with a tunnel wired, the host still refuses the loopback receiver', async () => {
+    if (!(await isWebhookSupported())) {
+      return softSkip('inapplicable', '[webhook-signed-delivery] host does not advertise webhook support; skipping');
+    }
+    if (!process.env.OPENWOP_WEBHOOK_RECEIVER_URL?.trim()) {
+      // No tunnel wired ⇒ the sibling test already registers loopback directly
+      // and this control has nothing to add.
+      return softSkip('inapplicable', 'control applies only when OPENWOP_WEBHOOK_RECEIVER_URL is set');
+    }
+
+    const receiver = await startReceiver();
+    activeServer = receiver.server;
+
+    const ownedTenant = await discoverOwnedTenant(driver);
+    const reg = await driver.post('/v1/webhooks', {
+      url: receiver.url, // deliberately the raw loopback URL, NOT the tunnel
+      events: ['run.completed'],
+      ...(ownedTenant ? { tenantId: ownedTenant } : {}),
+    });
+
+    if (reg.status >= 200 && reg.status < 300) {
+      // Clean up the subscription we just created before failing, so a failed
+      // control does not leave a live loopback subscriber behind.
+      const created = reg.json as { webhookId?: string };
+      if (created?.webhookId) {
+        await driver.delete(`/v1/webhooks/${encodeURIComponent(created.webhookId)}`);
+      }
+    }
+
+    expect(reg.status, driver.describe(
+      'webhooks.md §"SSRF protection"',
+      'the server MUST reject loopback subscription URLs at registration time. ' +
+        'It was accepted here, so this run cannot attribute the tunnelled test\'s pass to ' +
+        'a working guard: a host with no guard produces the same result. Either the guard is ' +
+        'absent (a finding) or OPENWOP_WEBHOOK_ALLOW_PRIVATE is set (in which case drop the ' +
+        'tunnel — it is not doing anything).',
+    )).toBe(400);
+  });
 });

package/src/setup.ts

@@ -278,7 +278,7 @@ afterAll(({}, suite) => {
   // the marker detail — never to a pass. Floors still REJECT that row, so the
   // honest bundle row and the pressure to say why both survive. The rule is
   // `resolveFileRecord` (pinned by conformance-execution-witness.test.ts).
-  const { disposition, detail } = resolveFileRecord(states, gateReason, assertionCount, softSkipDisposition(file));
+  const { disposition, detail } = resolveFileRecord(states, gateReason, assertionCount, softSkipDisposition(file), file);
   const fileRequirementId = requirementIdForFile(file);
   // A scenario that classified ITSELF wins outright — including its `detail` and
   // its `assertionCount`.