@openwop/openwop-conformance 1.18.1 → 1.20.0

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 { createHash } from 'node:crypto';
 import { dirname, join, relative, resolve as pathResolve } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
@@ -53,6 +54,7 @@ import {
   TYPESCRIPT_RUN_HELPERS_PATH,
   V1_DIR,
 } from '../lib/paths.js';
+import { verifyBundle, PROFILE_FLOOR_SCENARIOS } from '../lib/profiles.js';
 
 // Layout-aware paths come from `lib/paths.ts`. Three layouts:
 //   - Repo (github.com/openwop/openwop): schemas/api at repo root,
@@ -721,6 +723,51 @@ describe('spec-corpus: OpenAPI 3.1 spec is structurally valid', () => {
     }
   });
 
+  // ── Reserved-route disambiguation (RFC 0086/0087 + audit PR #495) ──────────
+  // The literal collection routes /v1/agents/roster and /v1/agents/org-chart
+  // share a prefix with the parameterized /v1/agents/{agentId}. The mitigation
+  // excludes the reserved literals from the {agentId} path param via a
+  // negative-lookahead pattern, AND the agent-manifest agentId pattern requires
+  // a dotted-tier form the bare literals can't satisfy. These guard both halves
+  // from silently regressing (the external standards-readiness audit asked the
+  // reserved-route mitigation be bound to a test).
+  it('declares both the literal /v1/agents/{roster,org-chart} routes and the {agentId} param route', () => {
+    const { raw } = readYamlHeader(openapiPath);
+    expect(raw).toContain('/v1/agents/{agentId}:');
+    expect(raw).toContain('/v1/agents/roster:');
+    expect(raw).toContain('/v1/agents/org-chart:');
+  });
+
+  it('every /v1/agents/{agentId} param excludes the reserved literals (roster, org-chart)', () => {
+    const { raw } = readYamlHeader(openapiPath);
+    const paramRoutes = (raw.match(/\/v1\/agents\/\{agentId\}/g) ?? []).length;
+    const exclusions = (raw.match(/\(\?!roster\$\|org-chart\$\)/g) ?? []).length;
+    expect(paramRoutes, 'expected ≥2 /v1/agents/{agentId...} routes (base + /deployments)').toBeGreaterThanOrEqual(2);
+    expect(
+      exclusions,
+      'each /v1/agents/{agentId} param schema MUST exclude the reserved literals via a (?!roster$|org-chart$) lookahead',
+    ).toBeGreaterThanOrEqual(2);
+  });
+
+  it('the reserved-literal exclusion pattern rejects roster/org-chart and accepts a real agentId', () => {
+    const re = /^(?!roster$|org-chart$).+$/;
+    expect(re.test('roster'), 'roster MUST NOT match the {agentId} param').toBe(false);
+    expect(re.test('org-chart'), 'org-chart MUST NOT match the {agentId} param').toBe(false);
+    expect(re.test('core.example.pack.agent')).toBe(true);
+  });
+
+  it('the agent-manifest agentId pattern can never produce a reserved literal (defense in depth)', () => {
+    const manifest = readJson(join(SCHEMAS_DIR, 'agent-manifest.schema.json')) as {
+      properties?: { agentId?: { pattern?: string } };
+    };
+    const pattern = manifest.properties?.agentId?.pattern;
+    expect(typeof pattern, 'agent-manifest.schema.json MUST constrain agentId with a pattern').toBe('string');
+    const re = new RegExp(pattern as string);
+    expect(re.test('roster'), 'manifest agentId MUST NOT permit the reserved literal `roster`').toBe(false);
+    expect(re.test('org-chart'), 'manifest agentId MUST NOT permit the reserved literal `org-chart`').toBe(false);
+    expect(re.test('core.example.pack.agent')).toBe(true);
+  });
+
   it('typed error specializations compose the canonical Error schema', () => {
     const { raw } = readYamlHeader(openapiPath);
 
@@ -1351,3 +1398,139 @@ describe.skipIf(FIXTURES_DOC_PATH === null)('spec-corpus: fixtures.json catalog
     }
   });
 });
+
+// RFC 0089 — conformance certification bundle. The schema itself is compiled +
+// $id-checked by the "JSON Schemas compile under Ajv2020" block above; here we
+// assert a sample bundle validates AND that the §B binding rule (verifyBundle)
+// correctly accepts a valid claim and rejects both a not-derivable claim and a
+// missing-floor-scenario one.
+describe('spec-corpus: RFC 0089 conformance certification bundle + binding rule', () => {
+  // A discovery document that derives `openwop-core-standard`
+  // (isCore ∧ isInterrupts ∧ a transport — supportedTransports omitted ⇒ rest).
+  const coreStandardDiscovery = {
+    protocolVersion: '1.0',
+    supportedEnvelopes: ['final', 'clarification.request'],
+    schemaVersions: { 'workflow-definition': '1.0' },
+    limits: { clarificationRounds: 3, schemaRounds: 2, envelopesPerTurn: 8 },
+  };
+  const coreStandardFloorPassed = [
+    ...PROFILE_FLOOR_SCENARIOS['openwop-core-standard']!.required,
+    'interrupt-resume.test.ts',
+  ];
+  const sampleBundle = {
+    bundleVersion: '1',
+    generatedAt: '2026-06-02T00:00:00Z',
+    generator: { name: '@openwop/openwop-conformance --certify', version: '1.18.1' },
+    suite: { package: '@openwop/openwop-conformance', version: '1.18.1' },
+    host: { name: 'openwop-host-sqlite', version: '1.0.0' },
+    discovery: {
+      url: 'https://example.test/.well-known/openwop',
+      sha256: 'a'.repeat(64),
+      document: coreStandardDiscovery,
+    },
+    claimedProfiles: ['openwop-core-standard'],
+    results: {
+      totals: { passed: coreStandardFloorPassed.length, failed: 0, skipped: 0, total: coreStandardFloorPassed.length },
+      passed: coreStandardFloorPassed,
+      failed: [],
+      skipped: [],
+    },
+  };
+
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const bundleSchema = readJson(join(SCHEMAS_DIR, 'conformance-certification-bundle.schema.json')) as Record<string, unknown>;
+
+  it('a sample bundle validates against conformance-certification-bundle.schema.json', () => {
+    const validate = ajv.compile(bundleSchema);
+    const ok = validate(sampleBundle);
+    expect(ok, JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it('verifyBundle ACCEPTS a claim that is discovery-derivable AND floor-proven (§B)', () => {
+    const r = verifyBundle(sampleBundle);
+    expect(r.valid).toBe(true);
+    expect(r.verdicts[0]?.derivable).toBe(true);
+    expect(r.verdicts[0]?.floorProven).toBe(true);
+  });
+
+  it('verifyBundle REJECTS a profile its discovery document does not derive (§B(1))', () => {
+    const notDerivable = {
+      ...sampleBundle,
+      discovery: { ...sampleBundle.discovery, document: { ...coreStandardDiscovery, supportedEnvelopes: ['final'] } },
+    };
+    const r = verifyBundle(notDerivable);
+    expect(r.valid).toBe(false);
+    expect(r.verdicts[0]?.derivable).toBe(false);
+  });
+
+  it('verifyBundle REJECTS a bundle missing a floor scenario (§B(2))', () => {
+    const missingFloor = {
+      ...sampleBundle,
+      results: { ...sampleBundle.results, passed: coreStandardFloorPassed.filter((s) => s !== 'auth.test.ts') },
+    };
+    const r = verifyBundle(missingFloor);
+    expect(r.valid).toBe(false);
+    expect(r.verdicts[0]?.floorProven).toBe(false);
+    expect(r.verdicts[0]?.missingFloor).toContain('auth.test.ts');
+  });
+});
+
+// RFC 0089 — the committed REAL reference-host bundle, generated by
+// `openwop-conformance --certify` against the in-memory reference host
+// (examples/hosts/in-memory). This is the at-`Accepted` "reference host commits
+// a real generated bundle" evidence: it must (a) validate against the schema and
+// (b) pass the §B binding rule — every profile it CLAIMS must re-derive from its
+// own captured discovery document AND be floor-proven. The bundle lives in
+// `examples/`, which is NOT bundled into the published tarball, so this skips
+// cleanly under the published layout (V1_DIR === null).
+describe.skipIf(V1_DIR === null)('spec-corpus: RFC 0089 committed reference-host certification bundle', () => {
+  const repoRoot = V1_DIR === null ? '' : pathResolve(V1_DIR, '..', '..');
+  const bundlePath = join(repoRoot, 'examples', 'hosts', 'in-memory', 'certification-bundle.json');
+
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const bundleSchema = readJson(join(SCHEMAS_DIR, 'conformance-certification-bundle.schema.json')) as Record<
+    string,
+    unknown
+  >;
+
+  it('the committed bundle file exists (generated by --certify)', () => {
+    expect(existsSync(bundlePath), `expected a committed reference bundle at ${bundlePath}`).toBe(true);
+  });
+
+  it('the committed reference bundle validates against the bundle schema (§A)', () => {
+    const bundle = readJson(bundlePath);
+    const validate = ajv.compile(bundleSchema);
+    const ok = validate(bundle);
+    expect(ok, JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it('verifyBundle ACCEPTS the committed reference bundle — every claimed profile re-derives + is floor-proven (§B)', () => {
+    const bundle = readJson(bundlePath) as Parameters<typeof verifyBundle>[0];
+    const r = verifyBundle(bundle);
+    // The host honestly claims ONLY profiles its discovery document derives, none
+    // of which it fails a floor scenario for — so verifyBundle MUST accept it.
+    const offending = r.verdicts.filter((v) => !v.valid);
+    expect(
+      r.valid,
+      `verifyBundle rejected claimed profile(s): ${JSON.stringify(offending)}`,
+    ).toBe(true);
+  });
+
+  it('discovery.sha256 is the canonical-JSON SHA-256 of the captured discovery.document', () => {
+    const bundle = readJson(bundlePath) as {
+      discovery: { sha256: string; document: unknown };
+    };
+    // Mirror the generator's canonical serialization (sorted keys at every level).
+    const canonical = (value: unknown): string => {
+      if (value === null || typeof value !== 'object') return JSON.stringify(value);
+      if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+      const obj = value as Record<string, unknown>;
+      const keys = Object.keys(obj).sort();
+      return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(',')}}`;
+    };
+    const recomputed = createHash('sha256').update(canonical(bundle.discovery.document)).digest('hex');
+    expect(bundle.discovery.sha256).toBe(recomputed);
+  });
+});