@openwop/openwop-conformance 1.139.0 → 1.140.0

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.140.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.140.0",
+  "corpusCommit": "8fe8053bfa7436a9c9a2dbbebd304095ecd29b16"
 }

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/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`.