@openwop/openwop-conformance 1.72.2 → 1.98.0

package/src/scenarios/requirement-ledger.test.ts

@@ -0,0 +1,162 @@
+/**
+ * RFC 0148 §A — the requirement execution ledger, and the properties that make
+ * it non-vacuous.
+ *
+ * §A's operative sentence is negative: "A plain test return, caught exception
+ * converted to a return, or empty assertion body **MUST NOT** produce
+ * `executed-pass`." A ledger that merely *offers* five dispositions does not
+ * deliver that — it delivers it only if **absence** resolves to something other
+ * than a pass, because every vacuity found in this corpus so far reached
+ * `pass` by not running rather than by running wrong:
+ *
+ *   - `floorProven = missingFloor.length === 0 && prefixOk` over an undefined
+ *     floor — `[].every(...)` is `true`;
+ *   - a gated subtest that 404'd, soft-skipped, and left the file green;
+ *   - a scenario whose assertions never executed but whose file still counted.
+ *
+ * So these legs test the *default*, not the happy path. A ledger where an
+ * unrecorded requirement reads as `executed-pass` would pass every
+ * disposition-vocabulary check and still be the bug.
+ *
+ * Server-free and always-on.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  DISPOSITIONS,
+  CERTIFIABLE,
+  recordRequirement,
+  dispositionOf,
+  entryOf,
+  snapshot,
+  resetLedger,
+  verifyProfileRequirements,
+} from '../lib/requirement-ledger.js';
+import { allRequirements, requirementsFor } from '../lib/requirement-registry.js';
+
+describe('RFC 0148 §A — requirement execution ledger', () => {
+  beforeEach(() => resetLedger());
+
+  it('the disposition vocabulary is exactly the five §A names', () => {
+    expect([...DISPOSITIONS].sort()).toEqual(
+      ['blocked', 'executed-fail', 'executed-pass', 'inapplicable', 'skipped'].sort(),
+    );
+  });
+
+  it('an unrecorded requirement resolves to blocked, NOT to a pass', () => {
+    // The load-bearing leg. A scenario that returned early, threw and swallowed,
+    // or was never written leaves no entry — and the honest reading of no entry
+    // is "not exercised". Every vacuity in this corpus reached `pass` this way.
+    expect(
+      dispositionOf('openwop.never.recorded'),
+      'RFC 0148 §A: silence is evidence of nothing. An absent disposition MUST NOT read as executed-pass.',
+    ).toBe('blocked');
+    expect(entryOf('openwop.never.recorded').detail).toMatch(/not exercised/);
+  });
+
+  it('blocked is not certifiable, while skipped and inapplicable are', () => {
+    // "We could not check" and "we checked and it holds" are the two states this
+    // whole program exists to stop conflating.
+    expect(CERTIFIABLE).not.toContain('blocked');
+    expect(CERTIFIABLE).not.toContain('executed-fail');
+    expect([...CERTIFIABLE].sort()).toEqual(['executed-pass', 'inapplicable', 'skipped']);
+  });
+
+  it('a profile with no requirements is not certifiable', () => {
+    // This is the `[].every(...)` shape itself. An empty requirement list must
+    // not vacuously certify; callers distinguish "no floor by design" from "no
+    // floor written yet" BEFORE reaching here.
+    const verdict = verifyProfileRequirements('openwop-example', []);
+    expect(
+      verdict.certifiable,
+      'RFC 0148 §C / gap G6: an empty requirement set is exactly the vacuity that started this program.',
+    ).toBe(false);
+  });
+
+  it('one blocked requirement invalidates the whole profile', () => {
+    recordRequirement('openwop.a', 'executed-pass');
+    recordRequirement('openwop.b', 'skipped', 'profile not advertised; operator opted out');
+    const verdict = verifyProfileRequirements('openwop-example', ['openwop.a', 'openwop.b', 'openwop.c']);
+    expect(verdict.certifiable, 'RFC 0148 §A: a blocked requirement invalidates the claim').toBe(false);
+    expect(verdict.blocking.map((b) => b.requirementId)).toEqual(['openwop.c']);
+  });
+
+  it('a fully-exercised profile certifies', () => {
+    recordRequirement('openwop.a', 'executed-pass');
+    recordRequirement('openwop.b', 'inapplicable', 'host advertises no streaming surface');
+    expect(verifyProfileRequirements('openwop-example', ['openwop.a', 'openwop.b']).certifiable).toBe(true);
+  });
+
+  it('a non-pass disposition without a reason is rejected', () => {
+    // A `blocked` with no explanation is an outcome nobody can act on, and it is
+    // the shape a lazily-instrumented scenario would emit by default.
+    expect(() => recordRequirement('openwop.a', 'blocked')).toThrow(/without a reason/);
+    expect(() => recordRequirement('openwop.b', 'skipped', '   ')).toThrow(/without a reason/);
+    // A pass needs no prose — the assertion itself is the evidence.
+    expect(() => recordRequirement('openwop.c', 'executed-pass')).not.toThrow();
+  });
+
+  it('contradictory dispositions for one requirement throw rather than last-write-wins', () => {
+    // Silent overwrite would let a later soft-skip bury an earlier real failure
+    // — the same conflation running the other direction.
+    recordRequirement('openwop.a', 'executed-fail', 'assertion failed against target');
+    expect(() => recordRequirement('openwop.a', 'executed-pass')).toThrow(/already recorded/);
+    expect(dispositionOf('openwop.a')).toBe('executed-fail');
+  });
+
+  it('re-recording the same disposition is idempotent', () => {
+    recordRequirement('openwop.a', 'executed-pass');
+    recordRequirement('openwop.a', 'executed-pass');
+    expect(snapshot()).toHaveLength(1);
+  });
+});
+
+describe('RFC 0148 §A — the registry binds to the certification floor', () => {
+  beforeEach(() => resetLedger());
+
+  it('every profile with a runtime floor yields requirement IDs', () => {
+    // Guard: an empty registry would make the legs below vacuous.
+    expect(allRequirements().length, 'the floor MUST produce requirement IDs').toBeGreaterThan(10);
+    expect(allRequirements()).toContain('openwop.floor.runs-lifecycle');
+    expect(allRequirements()).toContain('openwop.floor.any.interrupt-');
+  });
+
+  it('an unwritten floor returns null, not an empty list', () => {
+    // `openwop-replay-fork` is deliberately unspecified — `profiles.md` gives it
+    // a discovery-conditional floor a flat list cannot express (gap G7). Null
+    // forces the caller to decide; an empty array would silently certify.
+    expect(
+      requirementsFor('openwop-replay-fork'),
+      'RFC 0148 §C: unspecified MUST be distinguishable from empty-by-design',
+    ).toBeNull();
+    expect(requirementsFor('openwop-does-not-exist')).toBeNull();
+  });
+
+  it('a discovery-only profile returns an empty list, which does not certify', () => {
+    // `openwop-core` has no runtime floor BY DESIGN — the predicate is the whole
+    // claim. That is a decision on record, and it is still not a runtime pass.
+    expect(requirementsFor('openwop-core')).toEqual([]);
+    expect(
+      verifyProfileRequirements('openwop-core', requirementsFor('openwop-core') ?? []).certifiable,
+      'RFC 0155 §A: an `openwop-core` badge is a statement about a document, not a running system',
+    ).toBe(false);
+  });
+
+  it('the real core-standard floor does not certify until every requirement is exercised', () => {
+    const ids = requirementsFor('openwop-core-standard');
+    expect(ids).not.toBeNull();
+    const requirements = ids as readonly string[];
+    // Nothing recorded yet: every requirement is blocked, so the profile fails.
+    expect(verifyProfileRequirements('openwop-core-standard', requirements).blocking).toHaveLength(
+      requirements.length,
+    );
+    // Record all but one — still not certifiable. Partial evidence is not evidence.
+    for (const id of requirements.slice(1)) recordRequirement(id, 'executed-pass');
+    const partial = verifyProfileRequirements('openwop-core-standard', requirements);
+    expect(partial.certifiable).toBe(false);
+    expect(partial.blocking.map((b) => b.requirementId)).toEqual([requirements[0]]);
+    // Record the last one and it certifies.
+    recordRequirement(requirements[0] as string, 'executed-pass');
+    expect(verifyProfileRequirements('openwop-core-standard', requirements).certifiable).toBe(true);
+  });
+});

package/src/scenarios/rfc-0147-self-audit.test.ts

@@ -0,0 +1,104 @@
+/**
+ * RFC 0147 §A.10 — the program audits itself, and silence is not compliance.
+ *
+ * §A states ten invariants that "apply to every workstream". §A.10 forbids using
+ * the RFC's existence or partial implementation as evidence its gaps are closed.
+ * A program that audits everything except itself has the same defect it was
+ * written to fix, one level up.
+ *
+ * This gate does NOT assert the program is compliant. It asserts that every §A
+ * invariant carries an **explicit disposition** — including the ones recorded as
+ * VIOLATED. That is the RFC 0148 §A design applied to governance: an invariant
+ * with no row is uncovered, not satisfied, and a self-audit that quietly omits
+ * its uncomfortable rows is worth less than none because it looks like coverage.
+ *
+ * Two rows are currently VIOLATED and the gate is green, which is the intended
+ * behavior. Making the gate fail on a violation would create pressure to delete
+ * the row rather than fix the program — the failure mode RFC 0149 §D measured
+ * when it declined to ship a gate that fires 69 times on its first run.
+ *
+ * Server-free.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { V1_DIR } from '../lib/paths.js';
+
+const AUDIT = V1_DIR === null
+  ? null
+  : join(resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..'), 'docs', 'RFC-0147-SELF-AUDIT.md');
+
+/** The ten §A invariants, by their heading anchor. */
+const INVARIANTS = [
+  'A.1',
+  'A.2',
+  'A.3',
+  'A.4',
+  'A.5',
+  'A.6',
+  'A.7',
+  'A.8',
+  'A.9',
+  'A.10',
+] as const;
+
+const DISPOSITIONS = /satisfied|VIOLATED|not satisfied|partially satisfied/;
+
+const AUDIT_PRESENT = AUDIT !== null && existsSync(AUDIT);
+
+describe.skipIf(!AUDIT_PRESENT)('RFC 0147 §A.10 — program self-audit', () => {
+  // `describe.skipIf` still EXECUTES this factory — it decides afterwards not to
+  // run the tests it collected. So a read here throws at collection time even
+  // when the suite is destined to skip, and one file's collection error takes
+  // the whole file down rather than skipping it. The audit lives under `docs/`,
+  // which is not bundled, so this is exactly the published-layout path.
+  const doc = AUDIT_PRESENT ? readFileSync(AUDIT as string, 'utf8') : '';
+
+  it('the audit exists and is substantive', () => {
+    // Guard: a stub file would make every leg below vacuous, and this gate's
+    // whole purpose is that an omitted row is visible.
+    expect(doc.length, 'the self-audit MUST be substantive').toBeGreaterThan(2000);
+    expect(doc).toMatch(/RFC 0147/);
+  });
+
+  it('every §A invariant carries an explicit disposition', () => {
+    const missing = INVARIANTS.filter((id) => {
+      const heading = new RegExp(`^## ${id.replace('.', '\\.')} — `, 'm');
+      const at = heading.exec(doc);
+      if (at === null) return true;
+      // The disposition must appear in that section, not merely somewhere.
+      const section = doc.slice(at.index, doc.indexOf('\n## ', at.index + 1) + 1 || undefined);
+      return !DISPOSITIONS.test(section);
+    });
+    expect(
+      missing,
+      'RFC 0147 §A.10: an invariant with no recorded disposition is UNCOVERED, not satisfied. ' +
+        'A self-audit that omits its uncomfortable rows is worth less than none, because it ' +
+        'looks like coverage.',
+    ).toEqual([]);
+  });
+
+  it('the audit records the violations it found rather than only the wins', () => {
+    // The load-bearing leg. An audit that reported nothing adverse would be
+    // indistinguishable from one nobody ran — and this program has two known
+    // violations, so a clean sheet here means the file stopped being honest.
+    expect(
+      /VIOLATED/.test(doc),
+      'RFC 0147 §A.5 and §A.6 are currently violated: four RFCs reached `Accepted` with no ' +
+        'evidence, and five high-risk RFCs had their comment windows waived by the exact ' +
+        'bootstrap mechanism §A.6 says must not shorten them. If those rows have been removed ' +
+        'rather than resolved, this leg is the thing that notices.',
+    ).toBe(true);
+  });
+
+  it('the audit does not claim the exit criteria are met', () => {
+    // §A.10, applied to the audit itself.
+    expect(
+      /exit criteria in RFC 0147 are not met|exit criteria .{0,40}not met/i.test(doc),
+      'RFC 0147 §A.10: the program MUST NOT be read as closed. Three remaining gates — external ' +
+        'audit, second maintainer, Tier-3 host — cannot be closed by work in this repository.',
+    ).toBe(true);
+  });
+});

package/src/scenarios/rfc-lifecycle-coherence.test.ts

@@ -0,0 +1,137 @@
+/**
+ * RFC 0149 §D — an `Accepted` RFC's unticked acceptance items must say why.
+ *
+ * §D asks the corpus generator to fail when an `Accepted` RFC "retains an
+ * unresolved acceptance blocker not explicitly carried to a register/known-limit".
+ * The obvious signal is the `- [ ]` boxes under §"Acceptance criteria", and the
+ * obvious gate — every box ticked before `Accepted` — was measured and rejected.
+ *
+ * `docs/RFC-LIFECYCLE-COHERENCE.md` recorded the distribution: of 141 `Accepted`
+ * RFCs, 42% ticked every box, 25% ticked none, 24% ticked some. A blanket gate
+ * fails 69 RFCs on its first run, mostly for an authoring convention, and a gate
+ * that fires 69 times on its first run gets disabled rather than fixed.
+ *
+ * The first triage hypothesis was also wrong, and correcting it produced the rule
+ * this gate actually enforces. The partially-ticked RFCs are not a blocker
+ * backlog: reading `0027`/`0028`/`0029`/`0040`/`0041` shows every trailing item
+ * deliberately unticked AND annotated with why — "(Will land alongside the first
+ * non-steward advertisement.)", "(Path-to-Accepted.)", "(Follow-up — … not
+ * normative gate-blockers.)". That inline annotation IS §D's "explicitly
+ * carried", just carried in a parenthetical rather than a register row.
+ *
+ * So the signal is **annotated vs bare, not ticked vs unticked**. An unticked
+ * item with no explanation is indistinguishable from one nobody checked; an
+ * unticked item that states its external gate is a decision on record. Ticking
+ * nothing stays legal — the RFC did not use the mechanism — but leaving a box
+ * unticked and unexplained does not.
+ *
+ * Applies from `LIFECYCLE_RULE_RFC` forward. Earlier RFCs are the dated record
+ * of a period when the convention did not exist, and rewriting them would make
+ * the record lie; the boundary is asserted here rather than assumed, so a NEW
+ * RFC cannot inherit the exemption. Same carve-out shape as RFC 0149 §B's
+ * root-layout lint.
+ *
+ * Server-free. `RFCS/` is repository-only, so this self-skips under the
+ * published tarball layout.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, resolve as pathResolve } from 'node:path';
+import { V1_DIR } from '../lib/paths.js';
+
+/** RFC 0149 §D takes effect with the RFC 0147 program's own cohort. */
+const LIFECYCLE_RULE_RFC = 147;
+
+const RFCS_DIR = V1_DIR === null ? null : pathResolve(V1_DIR, '..', '..', 'RFCS');
+
+interface BareItem {
+  readonly rfc: number;
+  readonly file: string;
+  readonly line: number;
+  readonly text: string;
+}
+
+/**
+ * An item is "carried" when it states a reason: a parenthetical, or a pointer to
+ * a gap register / known-limit / follow-up RFC. Anything else is bare.
+ */
+function isAnnotated(text: string): boolean {
+  if (/\([^)]{12,}\)/.test(text)) return true;
+  return /\b(gap register|known.limit|register row|carried|deferred|blocked on|gated on)\b/i.test(text);
+}
+
+function statusOf(doc: string): string | null {
+  const m = /^\|\s*\*\*Status\*\*\s*\|\s*`([^`]+)`/m.exec(doc);
+  return m === null ? null : m[1]!;
+}
+
+/** Unticked acceptance items lacking a stated reason, for `Accepted` RFCs at or after the cutoff. */
+function bareItems(dir: string): BareItem[] {
+  const found: BareItem[] = [];
+  for (const name of readdirSync(dir).filter((f) => /^\d{4}-.*\.md$/.test(f)).sort()) {
+    const rfc = Number.parseInt(name.slice(0, 4), 10);
+    if (!Number.isFinite(rfc) || rfc < LIFECYCLE_RULE_RFC) continue;
+    const doc = readFileSync(join(dir, name), 'utf8');
+    if (statusOf(doc) !== 'Accepted') continue;
+    const lines = doc.split('\n');
+    let inAcceptance = false;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]!;
+      if (/^##\s/.test(line)) inAcceptance = /^##\s+Acceptance criteria\s*$/.test(line);
+      if (!inAcceptance) continue;
+      if (!/^\s*-\s*\[ \]\s/.test(line)) continue;
+      const text = line.replace(/^\s*-\s*\[ \]\s*/, '');
+      if (!isAnnotated(text)) found.push({ rfc, file: name, line: i + 1, text });
+    }
+  }
+  return found;
+}
+
+describe.skipIf(RFCS_DIR === null || !existsSync(RFCS_DIR))('RFC 0149 §D — lifecycle coherence', () => {
+  const dir = RFCS_DIR as string;
+
+  it('the scan reaches Accepted RFCs in the governed range', () => {
+    // Guard: a status regex that matched nothing, or a heading regex that never
+    // entered the section, would make the assertion below vacuously true. That
+    // is the failure RFC 0148 exists to close, and it is especially easy here
+    // because the gate's PASSING state and its BROKEN state look identical.
+    const governed = readdirSync(dir)
+      .filter((f) => /^\d{4}-.*\.md$/.test(f))
+      .filter((f) => Number.parseInt(f.slice(0, 4), 10) >= LIFECYCLE_RULE_RFC)
+      .filter((f) => statusOf(readFileSync(join(dir, f), 'utf8')) === 'Accepted');
+    expect(
+      governed.length,
+      `at least one Accepted RFC numbered >= ${LIFECYCLE_RULE_RFC} MUST exist for this gate to mean anything`,
+    ).toBeGreaterThan(0);
+
+    const withBoxes = governed.filter((f) =>
+      /^##\s+Acceptance criteria\s*$/m.test(readFileSync(join(dir, f), 'utf8')),
+    );
+    expect(withBoxes.length, 'the acceptance-criteria heading MUST be found').toBeGreaterThan(0);
+  });
+
+  it('every unticked acceptance item states why it is unticked', () => {
+    const bare = bareItems(dir).map((b) => `RFCS/${b.file}:${b.line} — ${b.text}`);
+    expect(
+      bare,
+      'RFC 0149 §D: an unticked acceptance item on an `Accepted` RFC MUST carry its reason — an ' +
+        'external gate, a follow-up note, or a register / known-limit pointer. Unticked-and-' +
+        'unexplained is indistinguishable from unchecked, which is what makes the checkbox ' +
+        'signal unusable. Tick it, annotate it, or carry it to a register row.\n  ' +
+        bare.join('\n  '),
+    ).toEqual([]);
+  });
+
+  it('the rule binds the cohort that proposed it', () => {
+    // RFC 0149 is itself in the governed range. A gate whose author exempted
+    // their own RFC would be the shape RFC 0147 §A.10 forbids — citing a
+    // program's status as evidence its gaps are closed.
+    const self = readFileSync(join(dir, '0149-machine-contract-and-version-reconciliation.md'), 'utf8');
+    expect(statusOf(self), 'RFC 0149 is `Accepted`').toBe('Accepted');
+    expect(
+      149 >= LIFECYCLE_RULE_RFC,
+      'RFC 0149 MUST fall inside the range its own §D governs',
+    ).toBe(true);
+  });
+});

package/src/scenarios/semantic-digest-v2.test.ts

@@ -0,0 +1,128 @@
+/**
+ * RFC 0150 §C — the semantic request digest, and three defects in `replay.md`.
+ *
+ * **1. The exclusion list forbids exactly what §C requires.** `replay.md` §A
+ * says "Fields NOT in this set MUST NOT influence the cache key — including but
+ * not limited to: `max_tokens`, `stop`, … `seed`". §C says the digest "MUST
+ * cover the complete semantic provider request … maximum output bound, stop
+ * conditions, seed". Those are direct opposites, and §A's side is wrong: a
+ * request with `stop: ["END"]` and one without produce different completions, so
+ * a cache keyed identically for both **returns the wrong response** — not a
+ * miss, a wrong hit. Same for `seed`, whose entire purpose is to change output,
+ * and for the output bound, which decides whether a response is truncated.
+ *
+ * **2. It prescribes a normalization JCS does not perform.** Step 2 says
+ * canonicalize "via RFC 8785 JCS", then tells hosts without JCS to emit "UTF-8
+ * NFC for all strings". JCS does **not** apply NFC. So the two paths the same
+ * sentence offers produce **different bytes for the same input** whenever a
+ * string is not already NFC — which is the portability property §D claims as a
+ * normative invariant. §C: "Implementations MUST NOT add Unicode normalization
+ * outside JCS."
+ *
+ * **3. It cites a formula that no longer exists.** §C quotes the Layer-2 id as
+ * `sha256(runId ':' nodeId ':' attempt ':' providerKey)` — the composition RFC
+ * 0150 §B retired as a safety-fix, because `attempt` in the preimage guaranteed
+ * a duplicate effect on every retry. `idempotency.md` is v1.4; `replay.md` was
+ * left quoting v1.1. This one is a cross-document staleness the §B change itself
+ * introduced and did not catch.
+ *
+ * Server-free; reads the corpus. `spec/v1/` is repository-only, so it self-skips
+ * under the published tarball layout.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { V1_DIR } from '../lib/paths.js';
+
+/** Fields whose presence changes the model's output, so they change its identity. */
+const OUTCOME_AFFECTING = ['seed', 'stop', 'maxOutputTokens'];
+
+describe.skipIf(V1_DIR === null)('RFC 0150 §C — semantic request digest v2', () => {
+  const doc = V1_DIR === null ? '' : readFileSync(join(V1_DIR as string, 'replay.md'), 'utf8');
+
+  /**
+   * Normative text only. Blockquote lines are excluded because this document
+   * deliberately QUOTES the rules it retired, so a reader can see what changed
+   * and why — and a naive substring search cannot tell a live rule from a
+   * quoted-and-retired one. Same carve-out shape as RFC 0149 §B's lint, which
+   * exempts pre-0073 RFCs as the dated record of what was proposed.
+   *
+   * The exemption is narrow on purpose: it covers `>` blocks, not the body, so
+   * a retired rule cannot be resurrected into normative voice unnoticed.
+   */
+  const normative = doc
+    .split('\n')
+    .filter((l) => !/^\s*>/.test(l))
+    .join('\n');
+  const plain = normative.replace(/[`*_]/g, '').replace(/\s+/g, ' ');
+  /** Full text including quotes — used only where a quote is the thing under test. */
+  const everything = doc.replace(/[`*_]/g, '').replace(/\s+/g, ' ');
+
+  it('the digest recipe section is found at all', () => {
+    // Guard: an empty read makes every leg below vacuously true.
+    expect(doc.length, 'replay.md MUST be readable').toBeGreaterThan(1000);
+    expect(plain, 'the cache-key recipe MUST exist').toMatch(/cache key/i);
+    // The blockquote filter must not swallow the document.
+    expect(
+      plain.length / everything.length,
+      'the normative-text filter MUST retain most of the document, or every leg below is vacuous',
+    ).toBeGreaterThan(0.7);
+  });
+
+  it('outcome-affecting fields are covered, not excluded', () => {
+    for (const field of OUTCOME_AFFECTING) {
+      expect(
+        plain.includes(field),
+        `RFC 0150 §C: the digest MUST cover \`${field}\`. Excluding it means two requests that ` +
+          'produce different completions share a cache key — a wrong hit, not a miss.',
+      ).toBe(true);
+    }
+    // The v1 exclusion sentence named them as MUST NOT influence. It must be gone.
+    expect(
+      /Fields NOT in this set MUST NOT influence the cache key/.test(plain),
+      'RFC 0150 §C: the v1 exclusion list forbade the very fields §C requires. It cannot survive ' +
+        'alongside the v2 recipe — a reader following it would build the colliding digest.',
+    ).toBe(false);
+  });
+
+  it('no Unicode normalization is prescribed outside JCS', () => {
+    expect(
+      /UTF-8 NFC for all strings/.test(plain),
+      'RFC 0150 §C: "Implementations MUST NOT add Unicode normalization outside JCS." JCS does ' +
+        'not apply NFC, so offering NFC as the no-JCS fallback makes the two paths produce ' +
+        'different bytes for the same input — defeating the portability §D asserts.',
+    ).toBe(false);
+  });
+
+  it('the recipe carries a version stamp so v1 and v2 digests cannot collide', () => {
+    expect(
+      plain,
+      'RFC 0150 §C: the canonical object carries `recipe: "openwop-semantic-request-v2"`, so a ' +
+        'digest computed under the old rules is distinguishable rather than silently comparable.',
+    ).toContain('openwop-semantic-request-v2');
+  });
+
+  it('unknown provider options are carried, not dropped', () => {
+    expect(
+      /providerOptions/.test(plain),
+      'RFC 0150 §C: unknown provider options MUST go in a closed, namespaced `providerOptions` ' +
+        'object before hashing. "Silently dropping them is nonconformant" — a dropped option that ' +
+        'changes output is the collision this section exists to prevent.',
+    ).toBe(true);
+  });
+
+  it('the Layer-2 cross-reference matches the composition that actually exists', () => {
+    // Cross-document staleness introduced by RFC 0150 §B and not caught by it.
+    expect(
+      /attempt \|\| ':' \|\| providerKey|nodeId ':' attempt/.test(plain),
+      'RFC 0150 §B retired the `attempt`-bearing Layer-2 composition as a safety-fix. `replay.md` ' +
+        'MUST NOT keep quoting it — a reader following this section would rebuild the exact ' +
+        'defect §B removed, and would do so believing they were following the spec.',
+    ).toBe(false);
+    expect(
+      plain,
+      'replay.md MUST cite the current Layer-2 identity',
+    ).toContain('logicalInvocationId');
+  });
+});

package/src/scenarios/semantic-digest-vectors.test.ts

@@ -0,0 +1,140 @@
+/**
+ * RFC 0150 §C — the golden vectors, and the relationships they exist to pin.
+ *
+ * §C's acceptance criterion is that TypeScript, Python, and Go compute the same
+ * digest. Prose cannot deliver that: three independent readings of "canonicalize
+ * via JCS and hash" is precisely how three implementations disagree, and the
+ * disagreement is invisible until two hosts replay the same run and get
+ * different cache keys.
+ *
+ * So the vectors are the contract, and this gate holds the TypeScript
+ * implementation to them. An SDK in another language reproduces the same file.
+ *
+ * The vectors are not a flat list of examples. Several are **pairs**, and the
+ * relationship between the members is the actual requirement:
+ *
+ *   - tools sorted vs reversed  → MUST be equal (order is not semantic)
+ *   - message order reversed    → MUST differ (order IS semantic)
+ *   - two Unicode forms of "é"  → MUST differ, because JCS does not apply NFC
+ *
+ * That last pair is the one worth keeping. A well-meaning implementer who adds
+ * NFC "to be safe" makes those two vectors collide, and every other vector still
+ * passes — so a suite that checked only individual digests would go green on an
+ * implementation that had silently broken cross-host agreement.
+ *
+ * Server-free and always-on. The vectors ship with the conformance package.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import {
+  semanticRequestDigestV2,
+  projectSemanticRequestV2,
+  canonicalize,
+  SEMANTIC_REQUEST_RECIPE_V2,
+} from '../lib/llm-cache-key-recipe.js';
+
+interface Vector {
+  readonly id: string;
+  readonly why: string;
+  readonly input: Record<string, unknown>;
+  readonly canonical: string;
+  readonly digest: string;
+}
+
+const VECTORS_PATH = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'vectors',
+  'semantic-request-digest-v2.json',
+);
+
+const doc = JSON.parse(readFileSync(VECTORS_PATH, 'utf8')) as {
+  recipe: string;
+  vectors: readonly Vector[];
+};
+const byId = new Map(doc.vectors.map((v) => [v.id, v]));
+
+/**
+ * Recompute a vector's digest from its INPUT.
+ *
+ * Deliberately not `v.digest`. Reading the stored value would make the
+ * relationship legs below compare two constants out of the same file — they
+ * would validate that the vector SET is internally distinct and would pass
+ * unchanged against a broken implementation. That is the vacuity this whole
+ * program exists to close, and the first draft of this file had it: the NFC
+ * sabotage was caught by the per-vector reproduction leg, while the leg written
+ * specifically to catch it could not have failed.
+ */
+function digest(id: string): string {
+  const v = byId.get(id);
+  if (v === undefined) throw new Error(`vector '${id}' is missing from the golden set`);
+  return semanticRequestDigestV2(v.input);
+}
+
+/** The stored expectation, for legs that check the file rather than the code. */
+function storedDigest(id: string): string {
+  const v = byId.get(id);
+  if (v === undefined) throw new Error(`vector '${id}' is missing from the golden set`);
+  return v.digest;
+}
+
+describe('RFC 0150 §C — semantic request digest golden vectors', () => {
+  it('the vector set is present and non-trivial', () => {
+    // Guard: an empty or truncated file would make every leg below vacuous, and
+    // this gate's whole value is that it fails when an implementation drifts.
+    expect(doc.recipe).toBe(SEMANTIC_REQUEST_RECIPE_V2);
+    expect(doc.vectors.length, 'the golden set MUST cover the recipe').toBeGreaterThanOrEqual(10);
+    expect(new Set(doc.vectors.map((v) => v.id)).size).toBe(doc.vectors.length);
+    for (const v of doc.vectors) {
+      expect(v.why.length, `vector '${v.id}' MUST say what it pins`).toBeGreaterThan(20);
+    }
+  });
+
+  it.each(doc.vectors.map((v) => [v.id, v] as const))(
+    'the implementation reproduces %s',
+    (_id, v) => {
+      // The preimage is asserted as well as the hash: a mismatch on `canonical`
+      // tells an implementer WHICH field they got wrong, where a hash mismatch
+      // tells them only that something is.
+      expect(canonicalize(projectSemanticRequestV2(v.input)), v.why).toBe(v.canonical);
+      expect(semanticRequestDigestV2(v.input), v.why).toBe(v.digest);
+    },
+  );
+
+  it('tool order is not semantic — sorted and reversed agree', () => {
+    expect(digest('tools-sorted-by-name')).toBe(digest('tools-reversed-same-digest'));
+  });
+
+  it('message order IS semantic — reversing changes the digest', () => {
+    expect(
+      digest('message-order-is-semantic'),
+      'messages carry conversational sequence; sorting them would make two different conversations collide',
+    ).not.toBe(digest('message-order-reversed'));
+  });
+
+  it('the two Unicode forms do not collide, because JCS does not apply NFC', () => {
+    // The pair that catches a well-meaning "add NFC to be safe" change — and it
+    // catches it only because `digest()` RECOMPUTES from the input. Comparing
+    // stored values here would be two constants from one file.
+    expect(storedDigest('non-ascii-not-normalized')).not.toBe(storedDigest('non-ascii-composed'));
+    expect(
+      digest('non-ascii-not-normalized'),
+      'RFC 0150 §C: "Implementations MUST NOT add Unicode normalization outside JCS." An ' +
+        'implementation that normalizes makes these two collide and silently loses cross-host ' +
+        'byte agreement — the property `replay.md` §D asserts as a normative invariant.',
+    ).not.toBe(digest('non-ascii-composed'));
+  });
+
+  it('each field v1 excluded now changes the digest', () => {
+    // The defect §C fixes, stated as three inequalities. Under v1 all three of
+    // these were equal to `minimal`, so requests producing different completions
+    // shared a cache key — a wrong hit, not a miss.
+    for (const id of ['stop-changes-digest', 'seed-changes-digest', 'max-output-changes-digest']) {
+      expect(digest(id), `${id} MUST NOT equal the minimal request`).not.toBe(digest('minimal'));
+    }
+  });
+});