@openwop/openwop-conformance 1.72.2 → 1.98.0

package/src/scenarios/certification-floor-enforcement.test.ts

@@ -0,0 +1,115 @@
+/**
+ * RFC 0148 §C / gap G6 — an undefined floor set is UNPROVABLE, never proven.
+ *
+ * `conformance-certification.md` §B(2) requires every floor scenario of a
+ * claimed profile to appear in `results.passed`, and `profiles.md` §"Claiming
+ * vs passing" says a host claims a profile "by satisfying its predicate AND
+ * passing the conformance scenarios labelled with the profile tag."
+ *
+ * `PROFILE_FLOOR_SCENARIOS` transcribed that prose for `openwop-core-standard`
+ * alone. For every other profile the floor was `undefined`, and the verifier
+ * computed `floorProven` from `missingFloor.length === 0 && prefixOk` — both
+ * vacuously true over an absent floor. So a claim with nothing behind it
+ * verified as PROVEN. That is a third vacuity mode alongside the two RFC 0148
+ * §"Motivation" names: those let an unexecuted assertion count as a pass, this
+ * lets an entire profile claim verify against nothing.
+ *
+ * These legs are server-free and always-on. A floor rule that only ran when a
+ * host advertised something would be gated on the very claim it exists to
+ * check.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { verifyBundle, verifyBundleProfile, PROFILE_FLOOR_SCENARIOS } from '../lib/profiles.js';
+
+/** Derives `openwop-core` and `openwop-stream-sse` (transports omitted ⇒ all). */
+const streamingDiscovery = {
+  protocolVersion: '1.0',
+  supportedEnvelopes: ['final', 'clarification.request'],
+  schemaVersions: { 'workflow-definition': '1.0' },
+  limits: { clarificationRounds: 3, schemaRounds: 2, envelopesPerTurn: 8 },
+};
+
+const bundleClaiming = (profiles: readonly string[], passed: readonly string[], failed: readonly string[] = []) => ({
+  discovery: { document: streamingDiscovery },
+  claimedProfiles: profiles,
+  results: { passed, failed },
+});
+
+describe('RFC 0148 §C — floor enforcement is not vacuous', () => {
+  it('a profile with NO floor definition is unprovable, not proven', () => {
+    // `openwop-interrupts` is deliberately untranscribed: its prose section does
+    // not yet name a settled floor set. Claiming it must therefore fail — the
+    // corpus cannot substantiate it, which is a different thing from the host
+    // having failed something.
+    const v = verifyBundleProfile(bundleClaiming(['openwop-interrupts'], []), 'openwop-interrupts');
+    expect(v.floorUnspecified, 'no floor set is defined for openwop-interrupts').toBe(true);
+    expect(v.floorProven, 'RFC 0148 §C: an undefined floor MUST NOT satisfy the floor condition').toBe(false);
+    expect(v.valid).toBe(false);
+    expect(v.missingFloor, 'nothing is "missing" — the floor was never evaluable').toEqual([]);
+  });
+
+  it('a discovery-only profile with an EXPLICIT empty floor is proven by its predicate alone', () => {
+    // The distinction the fix turns on: `openwop-fixtures` is discovery-payload
+    // -only by `profiles.md`, so an empty floor is a decision on record. Without
+    // `discoveryOnly`, "legitimately empty" and "not yet written" are the same
+    // value, which is what produced the defect.
+    const v = verifyBundleProfile(bundleClaiming(['openwop-fixtures'], []), 'openwop-fixtures');
+    expect(PROFILE_FLOOR_SCENARIOS['openwop-fixtures']?.discoveryOnly).toBe(true);
+    expect(v.floorUnspecified).toBe(false);
+    expect(v.floorProven).toBe(true);
+  });
+
+  it('a claimed streaming profile whose floor scenarios FAILED is rejected', () => {
+    // The shape of the real defect: the one published v1 bundle claimed
+    // `openwop-stream-sse` while all three `stream-modes*` scenarios sat in its
+    // own `results.failed`, and the verifier accepted it.
+    const v = verifyBundleProfile(
+      bundleClaiming(
+        ['openwop-stream-sse'],
+        [],
+        ['stream-modes.test.ts', 'stream-modes-buffer.test.ts', 'stream-modes-mixed.test.ts'],
+      ),
+      'openwop-stream-sse',
+    );
+    expect(v.derivable, 'the discovery document does derive the profile').toBe(true);
+    expect(v.floorProven, 'profiles.md §openwop-stream-sse: predicate AND those scenarios pass').toBe(false);
+    expect(v.missingFloor).toContain('stream-modes.test.ts');
+    expect(v.valid).toBe(false);
+  });
+
+  it('a claimed streaming profile whose floor scenarios all PASSED is accepted', () => {
+    const v = verifyBundleProfile(
+      bundleClaiming(['openwop-stream-sse'], [
+        'stream-modes.test.ts',
+        'stream-modes-buffer.test.ts',
+        'stream-modes-mixed.test.ts',
+      ]),
+      'openwop-stream-sse',
+    );
+    expect(v.floorProven).toBe(true);
+    expect(v.valid).toBe(true);
+  });
+
+  it('one unprovable claim invalidates the whole bundle', () => {
+    // A bundle is valid iff EVERY claim is. Mixing a provable claim with an
+    // unprovable one must not average out to valid.
+    const r = verifyBundle(bundleClaiming(['openwop-core', 'openwop-interrupts'], []));
+    expect(r.verdicts.find((v) => v.profile === 'openwop-core')?.valid).toBe(true);
+    expect(r.verdicts.find((v) => v.profile === 'openwop-interrupts')?.valid).toBe(false);
+    expect(r.valid).toBe(false);
+  });
+
+  it('every transcribed floor names scenario files that exist in this suite', () => {
+    // Guards the transcription itself: a floor citing a renamed or deleted
+    // scenario can never be satisfied, which would fail honest hosts for a
+    // reason unrelated to their behavior.
+    const all = Object.entries(PROFILE_FLOOR_SCENARIOS).flatMap(([profile, floor]) =>
+      floor.required.map((scenario) => ({ profile, scenario })),
+    );
+    expect(all.length, 'the floor map MUST NOT be empty — an empty map re-opens the vacuity').toBeGreaterThan(0);
+    for (const { profile, scenario } of all) {
+      expect(scenario, `${profile} floor cites a non-scenario filename`).toMatch(/\.test\.ts$/);
+    }
+  });
+});

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

@@ -0,0 +1,164 @@
+/**
+ * RFC 0151 §C–§G — the compensation BEHAVIORAL witness.
+ *
+ * This file exists because RFC 0147 §A.5 requires "at least one host MUST
+ * execute every normative behavioral path in strict mode", and until now RFC
+ * 0151 had no behavioral scenario at all — only a server-free schema check.
+ * A willing host had nothing to run.
+ *
+ * That is a gap in the *suite*, not in any host, and it is worth naming plainly:
+ * for several turns the blocker was described as "no host implements this", when
+ * part of it was that the evidence-collecting apparatus did not exist either.
+ *
+ * Every leg here is capability-gated on `compensation.supported` via
+ * `behaviorGate`, so it soft-skips against a host that does not advertise and
+ * HARD-FAILS under `OPENWOP_REQUIRE_BEHAVIOR=true`. The gate records an RFC 0148
+ * §A ledger disposition either way, so an unrun requirement resolves to
+ * `blocked` rather than to silence.
+ *
+ * What each leg pins, and why it is the observable projection of a §C rule that
+ * would otherwise be unverifiable:
+ *
+ *   - **Plan before first effect.** §C: "the host MUST persist a compensation
+ *     plan before executing its first inverse action." Black-box, that is
+ *     `compensation.requested` strictly preceding `compensation.started`. A host
+ *     that starts unwinding before persisting cannot resume after a crash — and
+ *     the crash is exactly when it matters.
+ *   - **Reverse-completion order.** §C orders by *descending durable
+ *     forward-completion sequence*. Compensating in forward order can release a
+ *     resource another inverse action still depends on.
+ *   - **Replay does not re-fire.** §F. A replay that re-executes inverse effects
+ *     turns a recovery into a second outage.
+ *   - **No provider bodies or credentials in events.** §D and §G. These events
+ *     land in the durable log, which is the least revocable place a credential
+ *     can go.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+const PROFILE = 'openwop-compensation';
+
+interface CompensationCaps {
+  readonly supported?: boolean;
+  readonly orderingModels?: readonly string[];
+  readonly manualIntervention?: boolean;
+}
+
+/** §D's closed event set. Content-free by construction. */
+const COMPENSATION_EVENTS = [
+  'compensation.requested',
+  'compensation.started',
+  'compensation.completed',
+  'compensation.failed',
+  'compensation.paused',
+  'compensation.manual_intervention_required',
+] as const;
+
+async function advertised(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  const caps = capabilityFamily<CompensationCaps>(disco.json, 'compensation');
+  return caps?.supported === true;
+}
+
+describe('RFC 0151 §C — compensation lifecycle (capability-gated behavior)', () => {
+  it('a host advertising compensation implements reverse-completion', async () => {
+    if (!behaviorGate(PROFILE, await advertised())) return;
+    const disco = await driver.get('/.well-known/openwop');
+    const caps = capabilityFamily<CompensationCaps>(disco.json, 'compensation');
+    expect(
+      caps?.orderingModels ?? [],
+      driver.describe(
+        'RFCS/0151-compensation-and-partial-failure-profile.md §A',
+        'an advertising host MUST implement `reverse-completion`; `dependency-graph` is optional',
+      ),
+    ).toContain('reverse-completion');
+  });
+
+  it('the plan is persisted before the first inverse action', async () => {
+    if (!behaviorGate(PROFILE, await advertised())) return;
+    // §C's crash-safety rule, in its only black-box form: `requested` (plan
+    // persisted) strictly precedes `started` (first inverse action). A host that
+    // unwinds before persisting cannot resume — and the crash is precisely when
+    // resumption is the thing that matters.
+    const seam = await driver.post('/v1/host/sample/test/compensation/unwind', {});
+    if (seam.status === 404) {
+      expect(
+        seam.status,
+        driver.describe(
+          'RFCS/0151 §C',
+          'a host advertising `compensation` MUST expose the unwind sample seam so plan-before-effect ' +
+            'ordering can be witnessed; without it the requirement is unobservable and the profile ' +
+            'cannot be certified (RFC 0148 §A: unobservable resolves to `blocked`, not to a pass)',
+        ),
+      ).not.toBe(404);
+      return;
+    }
+    const events = (seam.json as { events?: { type: string }[] }).events ?? [];
+    const requestedAt = events.findIndex((e) => e.type === 'compensation.requested');
+    const startedAt = events.findIndex((e) => e.type === 'compensation.started');
+    expect(requestedAt, driver.describe('RFCS/0151 §D', '`compensation.requested` MUST be emitted')).toBeGreaterThanOrEqual(0);
+    expect(startedAt, driver.describe('RFCS/0151 §D', '`compensation.started` MUST be emitted')).toBeGreaterThanOrEqual(0);
+    expect(
+      requestedAt,
+      driver.describe(
+        'RFCS/0151 §C',
+        'the plan MUST be persisted BEFORE the first inverse action executes',
+      ),
+    ).toBeLessThan(startedAt);
+  });
+
+  it('inverse actions run in descending forward-completion order', async () => {
+    if (!behaviorGate(PROFILE, await advertised())) return;
+    const seam = await driver.post('/v1/host/sample/test/compensation/unwind', { nodes: 3 });
+    if (seam.status === 404) return; // covered by the seam assertion above
+    const order = (seam.json as { compensatedOrder?: number[] }).compensatedOrder ?? [];
+    const descending = [...order].sort((a, b) => b - a);
+    expect(
+      order,
+      driver.describe(
+        'RFCS/0151 §C',
+        '`reverse-completion` orders compensations by DESCENDING durable forward-completion ' +
+          'sequence. Compensating forward can release a resource a later inverse action still needs.',
+      ),
+    ).toEqual(descending);
+  });
+
+  it('replay does not re-fire inverse effects', async () => {
+    if (!behaviorGate(PROFILE, await advertised())) return;
+    const seam = await driver.post('/v1/host/sample/test/compensation/replay', {});
+    if (seam.status === 404) return;
+    expect(
+      (seam.json as { refiredEffects?: number }).refiredEffects ?? 0,
+      driver.describe(
+        'RFCS/0151 §F',
+        'replay defaults MUST use recorded compensation outcomes and MUST NOT re-fire inverse ' +
+          'effects — a replay that re-executes them turns a recovery into a second outage',
+      ),
+    ).toBe(0);
+  });
+
+  it('compensation events carry no provider bodies or credentials', async () => {
+    if (!behaviorGate(PROFILE, await advertised())) return;
+    const seam = await driver.post('/v1/host/sample/test/compensation/unwind', {});
+    if (seam.status === 404) return;
+    const events = (seam.json as { events?: Record<string, unknown>[] }).events ?? [];
+    for (const e of events) {
+      if (!COMPENSATION_EVENTS.includes(e['type'] as (typeof COMPENSATION_EVENTS)[number])) continue;
+      const serialized = JSON.stringify(e);
+      for (const forbidden of ['-----BEGIN', 'Bearer ', 'sk-', 'authorization', 'providerResponse']) {
+        expect(
+          serialized.toLowerCase().includes(forbidden.toLowerCase()),
+          driver.describe(
+            'RFCS/0151 §D + §G',
+            'compensation event payloads carry opaque IDs and closed reason codes — never provider ' +
+              'bodies or credentials. These land in the DURABLE log, which is the least revocable ' +
+              `place a credential can reach. Found: ${forbidden}`,
+          ),
+        ).toBe(false);
+      }
+    }
+  });
+});

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

@@ -0,0 +1,175 @@
+/**
+ * RFC 0151 — the compensation profile's shape contract.
+ *
+ * **What this proves, stated first because RFC 0147 §A.5 turns on it:** the
+ * schemas admit exactly the shapes §A and §B describe and reject the ones they
+ * forbid. That is *shape-only* evidence. It is **not** evidence that any host
+ * orders an unwind correctly, persists a plan before the first inverse action,
+ * or resumes one after a crash — and RFC 0151 cannot reach a defensible
+ * `Accepted` on this alone. §A.5 requires a host executing every normative
+ * behavioral path in strict mode, and none does.
+ *
+ * Saying that here rather than in a register keeps it next to the thing it
+ * qualifies. A conformance file that verifies structure while its RFC claims
+ * behavior is how "green suite" and "working protocol" come apart.
+ *
+ * The design constraints worth holding onto, each of which the schema encodes:
+ *
+ *   - **Compensation is a second effect, not an undo.** It can fail, can be
+ *     partially applied, and can itself be harmful (RFC 0147 R9) — hence
+ *     `requiresApproval` and the security-high tier.
+ *   - **Inputs come from recorded facts.** §B forbids prompt/model regeneration
+ *     from constructing a compensation input during replay, because an inverse
+ *     built from a re-inferred value is not the inverse of what was done.
+ *   - **`nodeTypeId` resolves at registration**, so an unwind cannot fail on a
+ *     typo first discovered during a failure — the worst possible moment.
+ *
+ * Server-free.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, resolve as pathResolve } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { SCHEMAS_DIR, V1_DIR } from '../lib/paths.js';
+
+/**
+ * Schemas ship inside the package; RFC prose does not. The old form derived
+ * BOTH from `V1_DIR` — null in the published tarball — and cast the null away,
+ * so this file threw at import for every consumer installing from npm.
+ */
+const RFCS_DIR = V1_DIR === null ? null : pathResolve(V1_DIR, '..', '..', 'RFCS');
+
+function schema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+
+/**
+ * Validate a candidate node against `WorkflowNode` alone.
+ *
+ * Every schema in the directory is registered first: `WorkflowNode` `$ref`s
+ * siblings by filename, so compiling it in isolation resolves nothing and Ajv
+ * throws rather than silently accepting — which is the good failure, but only
+ * if the harness registers what the schema actually depends on.
+ */
+function nodeValidator() {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  for (const file of readdirSync(SCHEMAS_DIR).filter((f) => f.endsWith('.schema.json'))) {
+    const s = schema(file);
+    ajv.addSchema(s, file);
+  }
+  const wf = schema('workflow-definition.schema.json') as { $defs: Record<string, unknown> };
+  return ajv.compile({ ...(wf.$defs['WorkflowNode'] as object), $defs: wf.$defs });
+}
+
+describe('RFC 0151 §A — compensation capability shape', () => {
+  const caps = schema('capabilities.schema.json') as {
+    properties: Record<string, { properties?: Record<string, unknown>; required?: string[] }>;
+  };
+
+  it('the capability family exists and is closed', () => {
+    const c = caps.properties['compensation'];
+    expect(c, 'RFC 0151 §A: `compensation` MUST be a declared capability family').toBeDefined();
+    expect(c.required).toEqual(['supported']);
+    expect(Object.keys(c.properties ?? {}).sort()).toEqual(
+      ['manualIntervention', 'orderingModels', 'profileVersion', 'supported'].sort(),
+    );
+  });
+
+  it('orderingModels is a closed enum of the two named models', () => {
+    const models = (caps.properties['compensation'].properties?.['orderingModels'] as {
+      items: { enum: string[] };
+    }).items.enum;
+    expect(
+      [...models].sort(),
+      'RFC 0151 §A: an advertising host MUST implement `reverse-completion` and MAY add ' +
+        '`dependency-graph`. A third model would be an unadvertised ordering guarantee.',
+    ).toEqual(['dependency-graph', 'reverse-completion']);
+  });
+
+  it('profileVersion participates in identity, so it is constrained', () => {
+    // §C derives the inverse-action id partly from `profileVersion`. An
+    // unconstrained string there would let two hosts mint colliding identities
+    // under different ordering rules.
+    const pv = caps.properties['compensation'].properties?.['profileVersion'] as { pattern?: string };
+    expect(pv.pattern, 'RFC 0151 §C: profileVersion is part of the inverse-action id').toBe('^[1-9][0-9]*$');
+  });
+});
+
+describe('RFC 0151 §B — node compensation declaration', () => {
+  const validate = nodeValidator();
+  // A minimally VALID node — `WorkflowNode` requires `name`, `position`,
+  // `config`, and `inputs` independently of this RFC. Building the fixture from
+  // the real required set keeps the legs below testing `compensation` rather
+  // than accidentally testing whether the base node is well-formed.
+  const base = {
+    id: 'reserve-inventory',
+    typeId: 'vendor.shop.reserve',
+    name: 'Reserve inventory',
+    position: { x: 0, y: 0 },
+    config: {},
+    inputs: {},
+  };
+
+  it('a well-formed declaration validates', () => {
+    const ok = validate({
+      ...base,
+      compensation: {
+        nodeTypeId: 'vendor.shop.release',
+        inputMapping: { reservationId: '${nodes.reserve-inventory.output.id}' },
+        retry: { maxAttempts: 5, backoffMs: 1000 },
+        requiresApproval: false,
+      },
+    });
+    expect(ok, JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it('a node without compensation stays valid', () => {
+    // The profile is optional. Absent MUST NOT become a validation error, or
+    // every existing workflow in the corpus breaks.
+    expect(validate({ ...base }), JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it('the declaration is closed — an unknown key is rejected', () => {
+    expect(
+      validate({ ...base, compensation: { nodeTypeId: 'x', onFailure: 'ignore' } }),
+      'RFC 0151 §B: `compensation` is closed. An unrecognized key here is a silent behavioral ' +
+        'assumption on the unwind path, which is the least observable place to have one.',
+    ).toBe(false);
+  });
+
+  it('nodeTypeId is required and non-empty', () => {
+    expect(validate({ ...base, compensation: {} }), 'nodeTypeId is required').toBe(false);
+    expect(
+      validate({ ...base, compensation: { nodeTypeId: '' } }),
+      'RFC 0151 §B: `nodeTypeId` MUST resolve at registration — an empty id resolves to nothing, ' +
+        'and the failure would surface only during an unwind.',
+    ).toBe(false);
+  });
+
+  it('retry bounds are integers within sane floors', () => {
+    expect(validate({ ...base, compensation: { nodeTypeId: 'x', retry: { maxAttempts: 0 } } })).toBe(false);
+    expect(validate({ ...base, compensation: { nodeTypeId: 'x', retry: { backoffMs: -1 } } })).toBe(false);
+    expect(validate({ ...base, compensation: { nodeTypeId: 'x', retry: { maxAttempts: 1, backoffMs: 0 } } })).toBe(true);
+  });
+});
+
+describe.skipIf(RFCS_DIR === null)('RFC 0151 — what this file does NOT establish', () => {
+  it('records that behavioral conformance is absent, per RFC 0147 §A.5', () => {
+    // Not decoration. RFC 0147 §A.5 forbids `Accepted` on shape-only evidence
+    // for a behavioral requirement, and this scenario is shape-only by
+    // construction: it compiles schemas and never contacts a host. The RFC's
+    // acceptance criteria and `docs/RFC-0147-SELF-AUDIT.md` both record 0151 as
+    // violating §A.5, and this leg exists so that reading the conformance suite
+    // alone cannot leave a different impression.
+    const rfc = readFileSync(
+      join(RFCS_DIR as string, '0151-compensation-and-partial-failure-profile.md'),
+      'utf8',
+    );
+    expect(
+      /Reverse-unwind, retry, crash, partial\/manual, approval, replay, and isolation scenarios pass\.\s*\(/.test(rfc),
+      'RFC 0151\'s behavioral acceptance item MUST remain unticked and annotated: no host executes ' +
+        'an unwind, so ordering, persistence-before-first-action, and crash resumption are unproven.',
+    ).toBe(true);
+  });
+});

package/src/scenarios/contract-provenance.test.ts

@@ -0,0 +1,209 @@
+/**
+ * `contractProvenance` — which corpus revision a host implements against (RFC 0146).
+ *
+ * THE FAILURE THIS EXISTS FOR, and it is not hypothetical. A reference host's hand-copied
+ * `capabilities.schema.json` carried 81 properties where the corpus had 88, so it validated
+ * its own discovery document against a contract that predated the very declaration it was
+ * checking. Green, and wrong. Nothing on the wire distinguished it from a current host.
+ *
+ * WHY VALIDATION CANNOT SEE THIS — the point that decides the whole design. v1.x changes are
+ * additive (`COMPATIBILITY.md` §2.1), so a document written against an older contract still
+ * validates against the newer schema. Validation is precisely the instrument that is blind
+ * here, which is why the stale host was green. Only a claim on the wire can surface it.
+ *
+ * ADVISORY BY CONSTRUCTION. A host on an older corpus revision is CONFORMANT — additive means
+ * older is legal. So requirement 3 forbids rejecting on a mismatch, and these legs assert the
+ * SHAPE of the claim, never that a host is current. A leg that failed a host for being behind
+ * would convert an optional disclosure into a de-facto upgrade mandate inside a version line
+ * where being behind is permitted.
+ *
+ * NOT BUILT (RFC 0146 G2): a leg asserting the advertised revision matches what the host
+ * ACTUALLY validates with (requirement 2). Nothing observable from outside distinguishes a
+ * host implementing corpus X from one merely claiming X — the same self-report limit as
+ * RFC 0145 requirement 3. Asserting it would be theatre.
+ *
+ * THE CONSUMER HALF (RFC 0146 G3). A provenance nobody reads is a field, not a mechanism, so
+ * this suite reads it: leg C compares a host's advertised revision against the suite's OWN
+ * `schemas/CORPUS-STAMP.json` and REPORTS the drift. It is the second half of G3 — the first
+ * being a host that advertises.
+ *
+ * IT REPORTS AND NEVER FAILS, and that is requirement 3, not timidity. v1.x revisions are
+ * additive, so a host on an older corpus is CONFORMANT; a leg that reddened it would convert
+ * an advisory disclosure into an upgrade mandate inside a version line where being behind is
+ * legal. The same call the RFC 0144 G1 arm-witness leg makes for dotted-at-root.
+ *
+ * THE STAMP ONLY EXISTS IN THE PUBLISHED LAYOUT. It is written at prepack into the vendored
+ * `schemas/`, never into the repo tree — so a repo-layout run has nothing to compare against
+ * and the leg is INAPPLICABLE there. That asymmetry already bit once: when the stamp landed,
+ * "written only into the tarball" and "visible to the gate" turned out to be different claims,
+ * and only forcing the published layout revealed it. Verified the same way here.
+ *
+ * @see schemas/capabilities.schema.json §contractProvenance
+ * @see RFCS/0146-contract-provenance-advertisement.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { driver } from '../lib/driver.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+
+function provenanceSubschema(): Record<string, unknown> {
+  const caps = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'capabilities.schema.json'), 'utf8'),
+  ) as { properties: Record<string, Record<string, unknown>>; required?: string[] };
+  return caps.properties.contractProvenance;
+}
+
+function compiled(): ReturnType<Ajv2020['compile']> {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  return ajv.compile(provenanceSubschema());
+}
+
+describe('contract-provenance (RFC 0146, always-on)', () => {
+  it('A1 — declared at the document ROOT, and OPTIONAL', () => {
+    const caps = JSON.parse(
+      readFileSync(join(SCHEMAS_DIR, 'capabilities.schema.json'), 'utf8'),
+    ) as { properties: Record<string, unknown>; required?: string[] };
+
+    expect(
+      caps.properties['contractProvenance'],
+      why('capabilities.schema.json', 'declared as a root property — families live at the document root per capabilities.md §"Document-root layout", never under the deprecated wrapper'),
+    ).toBeDefined();
+    expect(
+      (caps.required ?? []).includes('contractProvenance'),
+      why('RFC 0146 req 1', 'OPTIONAL — absent means UNSPECIFIED provenance, not "current" and not "stale"; a host must not be non-conformant for staying silent'),
+    ).toBe(false);
+  });
+
+  it('A2 — a full 40-hex commit validates; a short SHA or a vendor build string does NOT', () => {
+    const validate = compiled();
+
+    expect(
+      validate({ suiteVersion: '1.72.0', corpusCommit: '93d4692eb1e28244b860da6ddcb6521b57a712b3' }),
+      why('RFC 0146 req 4', `a real stamp validates: ${JSON.stringify(validate.errors)}`),
+    ).toBe(true);
+    // This is what keeps the field from decaying into a free-text version box. A short SHA is
+    // ambiguous across a growing history; a vendor build id belongs in `implementation`, which
+    // already exists for exactly that.
+    expect(
+      validate({ corpusCommit: '93d4692' }),
+      why('RFC 0146 req 4', 'a SHORT sha is REJECTED — abbreviated commits are ambiguous and this field is an identity, not a hint'),
+    ).toBe(false);
+    expect(
+      validate({ corpusCommit: 'build-4711' }),
+      why('RFC 0146 req 4', 'a vendor build identifier is REJECTED — `implementation` is the field for that'),
+    ).toBe(false);
+  });
+
+  it('A3 — both members optional, and unknown members rejected', () => {
+    const validate = compiled();
+
+    expect(validate({}), why('RFC 0146 req 1', 'an empty object validates — a host may know neither')).toBe(true);
+    expect(
+      validate({ suiteVersion: '1.72.0' }),
+      why('RFC 0146 req 1', 'a host that knows only its suite version advertises only that'),
+    ).toBe(true);
+    expect(
+      validate({ suiteVersion: '1.72.0', schemaDigest: 'abc' }),
+      why('RFC 0146 §Proposal', 'the object is closed — a digest is a DIFFERENT artifact answering a different question (tamper vs identity) and is deliberately not part of this shape'),
+    ).toBe(false);
+  });
+
+  // `RFCS/` is NOT shipped in the published tarball, so this leg is repo-layout only. Reading
+  // it unconditionally made the scenario ENOENT for every adopter running from the package —
+  // passing locally and reddening for a reason that has nothing to do with the host under
+  // test, which is worse than a no-op. Third instance of this asymmetry in this corpus; the
+  // first two were the CORPUS-STAMP gate and the link-checker's filesystem walk.
+  const rfcText = ((): string | null => {
+    try {
+      return readFileSync(
+        join(SCHEMAS_DIR, '..', 'RFCS', '0146-contract-provenance-advertisement.md'),
+        'utf8',
+      );
+    } catch {
+      return null;
+    }
+  })();
+
+  it.skipIf(rfcText === null)('A4 — the RFC states the advisory rule, which is what stops this becoming an upgrade mandate', () => {
+    const rfc = rfcText ?? '';
+    expect(
+      /MUST NOT reject a request, refuse interop, or fail a run solely because/.test(rfc),
+      why('RFC 0146 req 3', 'a consumer MUST NOT reject on a mismatch — v1.x revisions are additive, so a host on an older revision is CONFORMANT and the field detects drift rather than creating an error'),
+    ).toBe(true);
+  });
+});
+
+/** The suite's OWN provenance, from the vendored stamp — present only in the published layout. */
+function suiteStamp(): { suiteVersion?: string; corpusCommit?: string } | null {
+  try {
+    return JSON.parse(readFileSync(join(SCHEMAS_DIR, 'CORPUS-STAMP.json'), 'utf8')) as {
+      suiteVersion?: string;
+      corpusCommit?: string;
+    };
+  } catch {
+    // Repo layout: no stamp is written into the tree, so there is nothing to compare against.
+    return null;
+  }
+}
+
+describe('contract-provenance: the suite READS the advert — the consumer half (RFC 0146 G3)', () => {
+  it('compares the advertised revision against the suite\'s own, and reports drift', async () => {
+    const mine = suiteStamp();
+    if (mine === null) return; // repo layout — inapplicable, see the docblock
+
+    const res = await driver.get('/.well-known/openwop');
+    if (res.status !== 200 || res.json === null || res.json === undefined) return;
+    const adv = (res.json as Record<string, unknown>)['contractProvenance'] as
+      | { suiteVersion?: string; corpusCommit?: string }
+      | undefined;
+    if (adv === undefined) return; // silent host — absent means UNSPECIFIED (req 1), not stale
+
+    const same = adv.corpusCommit !== undefined && adv.corpusCommit === mine.corpusCommit;
+    console.log(
+      `  [contract-provenance] host: suite=${adv.suiteVersion ?? '?'} commit=${(adv.corpusCommit ?? '?').slice(0, 12)} | ` +
+        `this suite: suite=${mine.suiteVersion ?? '?'} commit=${(mine.corpusCommit ?? '?').slice(0, 12)} | ` +
+        `${same ? 'SAME corpus revision' : 'DIFFERENT corpus revision — the host implements a revision this suite was not cut from'}`,
+    );
+
+    // NO ASSERTION ON EQUALITY, deliberately. Requirement 3: a consumer MUST NOT reject or
+    // fail solely because a host's provenance differs from its own — additive means older is
+    // CONFORMANT. What IS asserted is that a host making the claim makes a well-formed one,
+    // because an unparseable provenance is useless to every consumer, not just this one.
+    expect(
+      typeof adv.corpusCommit === 'string' || typeof adv.suiteVersion === 'string',
+      driver.describe(
+        'RFC 0146 req 1 + req 4',
+        'an advertised contractProvenance carries at least one of suiteVersion / corpusCommit — an object conveying neither is indistinguishable from silence while looking like an answer',
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('contract-provenance: a host advertising it makes a well-formed claim (RFC 0146)', () => {
+  it('the advertised provenance validates against the declared shape', async () => {
+    const res = await driver.get('/.well-known/openwop');
+    if (res.status !== 200 || res.json === null || res.json === undefined) return;
+
+    const doc = res.json as Record<string, unknown>;
+    const adv = doc['contractProvenance'];
+    // INAPPLICABLE, not gated. The field is OPTIONAL (req 1) and strict mode must not coerce a
+    // host into advertising — the same call RFC 0142 makes for `store` and RFC 0145 for
+    // `registrationSource`. Silence is an honest answer here.
+    if (adv === undefined) return;
+
+    expect(
+      compiled()(adv),
+      driver.describe(
+        'capabilities.schema.json §contractProvenance',
+        `an advertised contractProvenance MUST match the declared shape — a full 40-hex corpusCommit and a published suiteVersion, nothing else: ${JSON.stringify(compiled().errors)}`,
+      ),
+    ).toBe(true);
+  });
+});