@getbourdon/conformance

@getbourdon/conformance

Language-neutral cross-implementation parity fixtures for Bourdon.

Python (pip install bourdon) is the oracle. The @getbourdon/* TypeScript mirror is conformant iff it reproduces the oracle's output on these exact fixtures — byte-for-byte where the contract is bytes (redaction, recognition strings, MCP wire), value-for-value where it's structured (F1, schema validity, tool I/O).

Who mints fixtures

The Python repository mints fixtures; this package is a runner and consumer, never a producer. Every fixture is generated by the Python repo's tools/gen_conformance.py (the single writer, which imports the live oracle and emits its actual output). This package vendors a reviewed snapshot of that output under fixtures/ and ships it with typed loaders. No fixture is ever authored or edited here — a change always starts oracle-side and arrives through the re-pin ritual below.

import { loadRedactionBattery, assembleSecret } from "@getbourdon/conformance";

const battery = loadRedactionBattery();
for (const secret of battery.secrets) {
  // a faithful TS redaction port must produce battery's expected output:
  expect(redactText(assembleSecret(secret))).toBe(secret.expect_redacted);
}

The pin

fixtures.pin.json records which contract the vendored snapshot is (conformance_version) and the sha256 fixtures/manifest.json must hash to. The test suite asserts both and prints them, and separately verifies every fixture file against the sha256 its manifest stamps — so a stale, partial, or hand-edited fixture tree cannot pass quietly. A mutation test corrupts a temp copy and asserts the hash gate goes red, proving the gate itself is live.

Re-pin ritual (per contract bump)

• Oracle side: regenerate (python tools/gen_conformance.py), review the diff, land it there first.
• Here: BOURDON_CONFORMANCE_DIR=<oracle>/conformance pnpm --filter @getbourdon/conformance sync-fixtures
• Update fixtures.pin.json with the new conformance_version and the sha256 of the new fixtures/manifest.json.
• Run the workspace test suite; fix whatever the new contract flushes out in the mirror packages, never by editing a fixture.

Resolution order: BOURDON_CONFORMANCE_DIR, else the vendored fixtures/ snapshot, else the sibling Python checkout ../bourdon/conformance.

License: Apache-2.0 (the wire-contract surface is permissive so third parties can build conformant implementations). The Bourdon engine is BUSL-1.1.