@openwop/openwop-conformance 1.136.7 → 1.136.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop-conformance",
-  "version": "1.136.7",
+  "version": "1.136.9",
   "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.136.7",
-  "corpusCommit": "b71c4c7c3a3d368c98ef97fd4bed097d16a3fbdd"
+  "suiteVersion": "1.136.9",
+  "corpusCommit": "6d2c33ba0be0e4d6934f5f9471600c66e8c5c183"
 }

package/src/scenarios/compensation-behavior.test.ts

@@ -40,6 +40,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
+import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { capabilityFamily } from '../lib/discovery-capabilities.js';
@@ -224,4 +225,74 @@ describe('RFC 0151 §C — compensation lifecycle (capability-gated behavior)',
       }
     }
   });
+
+  it('a healthy run that DECLARES a compensator reports compensationStatus `none` (SP-11a)', async () => {
+    if (!behaviorGate(PROFILE, await advertised())) return;
+
+    // The rollup folds over the PLAN, and no plan exists until a trigger fires
+    // (`compensation.md` §"Run rollup"). So a run that completes successfully while
+    // declaring compensable nodes reads `none` — it has nothing to unwind.
+    //
+    // Nothing observed this. Every other leg of the §21 seam drives a FAILURE, so a
+    // host that derived the rollup from the existence of obligation rows — minted per
+    // compensable node, healthy or not — reported `pending` on every successful run
+    // that declared a compensator and passed all of them. A tier-1 host shipped exactly
+    // that (SP-11a / their AP-03). This leg is the healthy case, and it needs no failure:
+    // `fail: false` on the unwind seam runs the same compensator-declaring workflow to
+    // completion.
+    const seam = await driver.post('/v1/host/sample/test/compensation/unwind', { fail: false });
+    if (seam.status === 404) {
+      return softSkip('blocked', 'the §21 unwind seam is not wired — the healthy-run rollup has no black-box witness');
+    }
+    if (seam.status >= 400) {
+      // The host mounts the seam but rejects `fail: false`. That is the pre-extension
+      // shape, not a pass: without it the healthy-run rollup stays unobservable.
+      return softSkip(
+        'blocked',
+        `the §21 unwind seam does not honour \`fail: false\` (HTTP ${seam.status}) — the healthy-run ` +
+          'rollup is unobservable until it does (host-sample-test-seams.md §21)',
+      );
+    }
+
+    const body = seam.json as { runId?: string; events?: { type: string }[] };
+    expect(
+      typeof body.runId === 'string' && body.runId.length > 0,
+      driver.describe('host-sample-test-seams.md §21', '`fail: false` MUST still return the runId it created'),
+    ).toBe(true);
+
+    // Positive control: the seam really did run a healthy compensator-declaring
+    // workflow. If it emitted a `compensation.requested`, it failed the node anyway and
+    // this is not the healthy case — say so rather than assert `none` against a run
+    // that legitimately has a plan.
+    const types = (body.events ?? []).map((e) => e.type);
+    if (types.includes('compensation.requested')) {
+      return softSkip(
+        'blocked',
+        `the seam emitted ${JSON.stringify(types)} under \`fail: false\` — a trigger fired, so this run ` +
+          'is not the healthy case the leg needs',
+      );
+    }
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(body.runId ?? '')}`);
+    expect(snap.status, driver.describe('rest-endpoints.md', 'GET /v1/runs/{runId} for the healthy seam run')).toBe(200);
+    const snapshot = snap.json as { status?: unknown; compensationStatus?: unknown };
+
+    expect(
+      snapshot.compensationStatus,
+      driver.describe(
+        'compensation.md §"Run rollup: compensationStatus"',
+        'a host advertising `compensation` MUST carry the field on EVERY snapshot — presence is the wire witness of the advert',
+      ),
+    ).toBeDefined();
+
+    expect(
+      snapshot.compensationStatus,
+      driver.describe(
+        'compensation.md §"Run rollup: compensationStatus"',
+        'a run that completed while declaring compensable nodes has nothing to unwind: no `compensation.requested` ' +
+          'was recorded, so the fold is `none`. `pending` here means the rollup was derived from obligation ROWS ' +
+          `rather than from plan state — got \`${String(snapshot.compensationStatus)}\``,
+      ),
+    ).toBe('none');
+  });
 });

package/src/scenarios/spec-section-citations.test.ts

@@ -0,0 +1,132 @@
+/**
+ * spec-section-citations — server-free. A citation of the form
+ * `<doc>.md §"<Section>"` MUST resolve to a heading that exists in that doc.
+ *
+ * SP-04 (2026-08-18): `storage-adapters.md §"Claim acquisition"` was cited by
+ * FOUR artifacts — `production-profile.md` §Durability, RFC 0009's
+ * scenario-citation table, and the docstrings of `staleClaim.test.ts` and
+ * `restart-during-run.test.ts` — and the section did not exist. Nothing was
+ * checking, so a normative `MUST` ("Storage adapters MUST satisfy
+ * `storage-adapters.md` lease and event-log invariants") pointed at nothing for
+ * the life of RFC 0009.
+ *
+ * Scope is deliberately narrow. A corpus-wide sweep of this citation form finds
+ * ~1400 citations and ~260 that do not resolve under a heading-only matcher —
+ * a mix of genuinely dangling anchors and legitimate informal references to
+ * table rows and capability keys rather than headings. Triaging those is its own
+ * work item; gating the whole corpus on an untriaged sweep would either fail
+ * immediately or need an allowlist so large it would stop meaning anything.
+ * So this pins the docs whose section citations are load-bearing for the
+ * durability contract, and grows as other docs are triaged.
+ *
+ * @see spec/v1/storage-adapters.md §"Claim acquisition"
+ * @see spec/v1/production-profile.md §Durability
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { V1_DIR, SCENARIOS_DIR } from '../lib/paths.js';
+
+/** Docs whose `§"Section"` citations are checked. Add a doc once its citations are triaged. */
+const CHECKED_DOCS = ['storage-adapters.md', 'production-profile.md'] as const;
+
+/** `<doc>.md §"Quoted Section"` or `<doc>.md §BareToken`. */
+const CITATION = /([A-Za-z0-9._-]+)\.md\s*§\s*(?:"([^"\n]+)"|([A-Za-z][A-Za-z0-9.-]*))/g;
+
+/**
+ * Strip decoration, a leading `§` (headings in this corpus carry their own), and
+ * trailing sentence punctuation — a docstring legitimately ends a sentence
+ * inside the quotes (`… §"Claim acquisition."`) and still names that section.
+ */
+const normalize = (t: string): string =>
+  t
+    .replace(/[`*_"]/g, '')
+    .replace(/^§\s*/, '')
+    .replace(/[.,;:]+$/, '')
+    .trim()
+    .toLowerCase();
+
+/** A heading matches its full text, or its lead token before an em-dash / period. */
+function headingKeys(raw: string): string[] {
+  const h = normalize(raw);
+  const keys = new Set<string>([h]);
+  const dash = h.split(/\s+[—–-]\s+/)[0]?.trim();
+  if (dash) keys.add(dash);
+  const dot = h.split(/\.\s+/)[0]?.trim();
+  if (dot) keys.add(dot);
+  return [...keys];
+}
+
+function walk(dir: string, keep: (n: string) => boolean, out: string[] = []): string[] {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, keep, out);
+    else if (keep(e.name)) out.push(p);
+  }
+  return out;
+}
+
+describe.skipIf(V1_DIR === null)('spec-section-citations (SP-04)', () => {
+  it('every cited section of a checked doc exists as a heading in that doc', () => {
+    const v1 = V1_DIR as string;
+    // `V1_DIR` is `<repo>/spec/v1` in a checkout; RFCS/ sits two levels up.
+    // Both are absent from the published tarball, which is why the whole file
+    // is `skipIf(V1_DIR === null)`.
+    const rfcsDir = join(v1, '..', '..', 'RFCS');
+
+    const sources = [
+      ...walk(v1, (n) => n.endsWith('.md')),
+      ...(existsSync(rfcsDir) ? walk(rfcsDir, (n) => n.endsWith('.md')) : []),
+      ...(SCENARIOS_DIR !== null ? walk(SCENARIOS_DIR, (n) => n.endsWith('.test.ts')) : []),
+    ];
+
+    const headings = new Map<string, Set<string>>();
+    for (const doc of CHECKED_DOCS) {
+      const text = readFileSync(join(v1, doc), 'utf8');
+      const keys = new Set<string>();
+      for (const m of text.matchAll(/^#{1,6}\s+(.+?)\s*$/gm)) {
+        for (const k of headingKeys(m[1] ?? '')) keys.add(k);
+      }
+      headings.set(doc, keys);
+    }
+
+    const dangling: string[] = [];
+    let checked = 0;
+    for (const src of sources) {
+      const text = readFileSync(src, 'utf8');
+      for (const m of text.matchAll(CITATION)) {
+        const doc = `${m[1]}.md`;
+        const keys = headings.get(doc);
+        if (!keys) continue;
+        const section = (m[2] ?? m[3] ?? '').trim();
+        if (!section) continue;
+        checked++;
+        const want = normalize(section);
+        // A MULTI-WORD citation must match a heading key exactly: prefix
+        // matching would let `§"Claim acquisition"` be satisfied by a heading
+        // named `Claim acquisition considered harmful`, which is how a renamed
+        // section slips past a gate like this (caught while sabotage-testing
+        // this very leg). A single-token citation — `§B`, `§C.2`,
+        // `§host.aiProviders` — legitimately prefixes a longer heading
+        // (`## §B — Channel resolution …`), so prefix matching stays for those.
+        const hit = keys.has(want)
+          || (!want.includes(' ') && [...keys].some((k) => k.startsWith(want)));
+        if (!hit) dangling.push(`${src.split('/').slice(-2).join('/')} → ${doc} §"${section}"`);
+      }
+    }
+
+    // Non-vacuity: these docs ARE cited. A zero here means the matcher stopped
+    // matching, not that the corpus got clean — the failure mode this file exists
+    // to prevent, one level up.
+    expect(
+      checked,
+      'spec-section-citations: no citations of the checked docs were found — the matcher is broken, not the corpus clean',
+    ).toBeGreaterThan(0);
+
+    expect(
+      dangling,
+      `dangling section citations (the cited heading does not exist):\n  ${dangling.join('\n  ')}`,
+    ).toEqual([]);
+  });
+});