@openwop/openwop-conformance 1.70.2 → 1.71.0

package/README.md

@@ -186,6 +186,26 @@ Current source tree: 411 scenario files. Use [`coverage.md`](./coverage.md) for
 
 ---
 
+## Resolving the contract: depend on this package, don't hand-copy it
+
+The published tarball vendors the canonical `schemas/` and `api/` directories. **A host validating its own discovery document, events, or manifests should read them from the installed `@openwop/openwop-conformance` package rather than copying files into its own tree.**
+
+The reason is not convenience — it is that **a hand-copied schema goes stale silently, in both directions**. A real instance: a host validated its `/.well-known/openwop` document against a vendored `capabilities.schema.json` carrying 81 properties while the corpus had 88. Its check was green, and it had been validating against a contract that predated the very declaration it was checking. Nothing warned it, and nothing could have — a file copy has no version.
+
+Depending on the package instead makes staleness a **lockfile fact**. The suite version *is* the contract version: it appears in `package.json`, in the lockfile, in `npm outdated`, and in whatever dependency bot the host runs. Falling behind stops being invisible and becomes a diff.
+
+```jsonc
+// stale and silent — the copy has no version
+import caps from './vendor/capabilities.schema.json';
+
+// stale and VISIBLE — the version is in your lockfile
+import caps from '@openwop/openwop-conformance/schemas/capabilities.schema.json';
+```
+
+**What this does not fix.** A host that keeps hand-copying gets no warning, and the corpus cannot see a host's local files — so this narrows the failure rather than eliminating it. Tracked as RFC 0145 G2.
+
+The presence of these files at stable paths in the tarball is enforced by `scripts/check-npm-pack-contents.sh`, so a packaging change cannot quietly withdraw the contract copy a host depends on.
+
 ## Repo layout
 
 ```text

package/package.json

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

package/src/scenarios/artifact-type-registration-source.test.ts

@@ -13,10 +13,14 @@
  * discovery document, and a third value is not a hint to ignore but a host claiming a
  * provenance the protocol does not define. Leg A2 pins that asymmetry.
  *
- * NOT BUILT (carried as RFC 0145 G1): a leg asserting a host's advertised
- * `registrationSource` matches what it emits on `artifact.created` (requirement 3). It needs
- * a host that advertises the facet AND emits a matching artifact; against a host advertising
- * nothing it would be vacuously green, which is the failure mode this suite keeps finding.
+ * LEG B (RFC 0145 G1) closes the gap this file originally carried open. It asserts a host's
+ * advertised `registrationSource` matches what it emits on `artifact.created` (requirement 3).
+ * It was deliberately NOT built at first: against a corpus where no host advertised the facet
+ * it would have gone green by finding nothing. A host now advertises it, so the leg has
+ * something real to compare and can no longer pass vacuously.
+ *
+ * PROFILE = 'openwop-artifact-type-store' is shared with RFC 0142 ON PURPOSE — see the gating
+ * note on leg B for why this leg deliberately does NOT add its own advertise-and-skip gate.
  *
  * @see schemas/capabilities.schema.json §artifactTypes.types
  * @see spec/v1/artifact-type-packs.md §"Per-type facets" + §"Schema distribution"
@@ -29,6 +33,9 @@ import { join } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 import { SCHEMAS_DIR, V1_DIR } from '../lib/paths.js';
+import { driver } from '../lib/driver.js';
+import { behaviorGatePresent } from '../lib/behavior-gate.js';
+import { readArtifactTypesCap } from '../lib/artifactTypes.js';
 
 const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
 const CAPS = join(SCHEMAS_DIR, 'capabilities.schema.json');
@@ -131,3 +138,83 @@ describe('artifact-type-registration-source (RFC 0145, always-on)', () => {
     ).toBe(true);
   });
 });
+
+const PROFILE = 'openwop-artifact-type-store';
+
+/** True when this type emits at all — `store` at per-type scope, else the capability default. */
+function emitsForType(cap: Record<string, unknown> | null, id: string): boolean {
+  if (!cap) return false;
+  const entry = (cap['types'] as Record<string, unknown> | undefined)?.[id];
+  if (entry && typeof entry === 'object' && 'store' in (entry as Record<string, unknown>)) {
+    return (entry as Record<string, unknown>)['store'] === true;
+  }
+  return cap['store'] === true;
+}
+
+/**
+ * First per-type id advertising `registrationSource` AND emitting, else null.
+ *
+ * BOTH conditions are required, and the second is the subtle one: `registrationSource` is
+ * meaningful on a type the host never emits for (a consumer still learns which schema-resolution
+ * regime applies), but requirement 3 is a statement about AGREEMENT BETWEEN TWO SURFACES, and a
+ * type with no emission has only one. Asserting against it would red a host that is telling the
+ * truth on every surface it actually has.
+ */
+function comparableType(cap: Record<string, unknown> | null): { id: string; advertised: string } | null {
+  const types = cap?.['types'];
+  if (!types || typeof types !== 'object') return null;
+  for (const [id, t] of Object.entries(types as Record<string, unknown>)) {
+    if (!t || typeof t !== 'object') continue;
+    const advertised = (t as Record<string, unknown>)['registrationSource'];
+    if (typeof advertised !== 'string') continue;
+    if (!emitsForType(cap, id)) continue;
+    return { id, advertised };
+  }
+  return null;
+}
+
+describe('artifact-type-registration-source: the advert agrees with the event (RFC 0145 leg B, requirement 3)', () => {
+  it('the emitted registrationSource equals the advertised one for that type', async () => {
+    const cap = await readArtifactTypesCap();
+    const target = comparableType(cap);
+    // INAPPLICABLE, not gated. `registrationSource` is OPTIONAL (requirement 2) and strict mode
+    // must not coerce a host into advertising it — the same call RFC 0142 makes for `store`.
+    if (target === null) return;
+
+    const started = await driver.post('/v1/host/sample/artifacttypes/runproduce', {
+      artifactTypeId: target.id,
+    });
+    // DELIBERATELY NOT a behaviorGate on seam presence. Reaching here means the type advertises
+    // `store`, so `store: true` + no seam is ALREADY strict-red under RFC 0142 leg B — the
+    // scenario that owns that enforcement. Gating again here would double-report one defect,
+    // and gating on the seam for a 0145 advert would coerce hosts into wiring 0142's host-sample
+    // surface in order to advertise a facet that has nothing to do with it.
+    if (started.status === 404 || started.status === 405) return; // seam absent — 0142 reports it
+    expect(
+      started.status >= 200 && started.status < 300,
+      driver.describe('coverage.md §"Open seams"', 'runproduce starts a real run producing one artifact of the requested registered type'),
+    ).toBe(true);
+    const runId = (started.json as Record<string, unknown> | undefined)?.['runId'];
+    if (!behaviorGatePresent(PROFILE, typeof runId === 'string' ? runId : null)) return;
+
+    const events = await driver.get(`/v1/runs/${runId}/events/poll?timeout=5`);
+    expect(
+      events.status,
+      driver.describe('run-events surface', 'the run event log is readable over the standard poll endpoint'),
+    ).toBe(200);
+    const list = ((events.json as Record<string, unknown>)?.['events'] ?? []) as Array<Record<string, unknown>>;
+    const created = list.filter((e) => e['type'] === 'artifact.created');
+    // Emission itself is RFC 0142's MUST, reported by its own leg. Reaching here without an
+    // event means that leg is already red; don't restate its finding as a 0145 failure.
+    if (created.length === 0) return;
+
+    const payload = (created[0]?.['payload'] ?? created[0]?.['data'] ?? {}) as Record<string, unknown>;
+    expect(
+      payload['registrationSource'],
+      driver.describe(
+        'RFC 0145 requirement 3',
+        `the host advertises registrationSource: "${target.advertised}" for ${target.id}, so that is the value it MUST emit — an advert of one provenance against an event carrying another (or carrying none, which asserts UNSPECIFIED provenance and therefore disagrees) is a false advertisement, not a permitted divergence`,
+      ),
+    ).toBe(target.advertised);
+  });
+});

package/src/scenarios/spec-corpus-validity.test.ts

@@ -35,6 +35,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { dirname, join, relative, resolve as pathResolve } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
@@ -386,7 +387,40 @@ function extractReadmeDocumentIndex(readme: string): string {
   return readme.slice(start, end);
 }
 
-function listMarkdownFilesRecursive(dir: string, repoRoot: string = dir): string[] {
+/**
+ * The set of `.md` paths git TRACKS under `repoRoot`, or `null` when git can't answer
+ * (no repo, no git binary — the published-tarball layout, a vendored corpus, a Docker
+ * stage without git).
+ *
+ * WHY THIS EXISTS. The link checker used to walk the filesystem, so its verdict depended
+ * on whatever untracked residue a working tree happened to carry. A real instance: a peer
+ * host's conformance run reported a broken link in `plans/…` — a directory DELETED in
+ * `937a9d85` and since gitignored, whose files survive as untracked leftovers in any tree
+ * that predates the removal. CI (a clean checkout) has never seen it and never could.
+ *
+ * A gate that passes in CI and fails on a developer's machine for reasons invisible to
+ * both is a gate people learn to discount, which is how a gate stops being run. Tracked
+ * files are the corpus; everything else is the developer's business.
+ */
+function listTrackedMarkdown(repoRoot: string): Set<string> | null {
+  const res = spawnSync('git', ['-C', repoRoot, 'ls-files', '-z', '--', '*.md'], {
+    encoding: 'utf8',
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  if (res.error !== undefined || res.status !== 0 || typeof res.stdout !== 'string') return null;
+  const rels = res.stdout.split('\0').filter((r) => r !== '');
+  // An empty tracked set is indistinguishable from "git answered about the wrong tree";
+  // treat it as unknown rather than as "the corpus has no Markdown", which would silently
+  // turn the whole link check into a no-op.
+  if (rels.length === 0) return null;
+  return new Set(rels.map((r) => pathResolve(repoRoot, r)));
+}
+
+function listMarkdownFilesRecursive(
+  dir: string,
+  repoRoot: string = dir,
+  tracked: Set<string> | null = null,
+): string[] {
   const ignoredDirs = new Set([
     '.git',
     'node_modules',
@@ -423,11 +457,15 @@ function listMarkdownFilesRecursive(dir: string, repoRoot: string = dir): string
       const child = join(dir, entry.name);
       const repoRelChild = relative(repoRoot, child);
       if (prunedRepoRelative.has(repoRelChild)) continue;
-      files.push(...listMarkdownFilesRecursive(child, repoRoot));
+      files.push(...listMarkdownFilesRecursive(child, repoRoot, tracked));
       continue;
     }
     if (entry.isFile() && entry.name.endsWith('.md')) {
-      files.push(join(dir, entry.name));
+      const full = join(dir, entry.name);
+      // `tracked === null` ⇒ git couldn't answer; fall back to the filesystem walk rather
+      // than skipping the check entirely. A noisier gate beats a silently absent one.
+      if (tracked !== null && !tracked.has(pathResolve(full))) continue;
+      files.push(full);
     }
   }
 
@@ -1244,7 +1282,8 @@ describe.skipIf(README_PATH === null)('spec-corpus: local Markdown links resolve
   // describe.skipIf skips test execution but still evaluates the body for registration; default
   // to '.' so dirname() never receives null in the published-tarball layout.
   const repoRoot = README_PATH === null ? '.' : dirname(README_PATH);
-  const markdownFiles = README_PATH === null ? [] : listMarkdownFilesRecursive(repoRoot);
+  const markdownFiles =
+    README_PATH === null ? [] : listMarkdownFilesRecursive(repoRoot, repoRoot, listTrackedMarkdown(repoRoot));
 
   it('finds Markdown files to check', () => {
     expect(markdownFiles.length, 'repo checkout should contain Markdown docs').toBeGreaterThan(0);