# FablePool milestone-2 conformance suite

This directory contains the wire-format test vectors from milestone 2 and a
runner that checks an implementation against them. The goal is that a second,
independent implementation of the FablePool protocol can prove byte-level
compatibility with the reference node without sharing any code.

## Layout

```
conformance/
  vectors/
    canonicalization.json   # deterministic JSON encoding, byte-exact
    signing.json            # Ed25519 seeds + messages, deterministic signing
    op_scenarios.json       # signed-operation integrity (accept/reject)
  run_conformance.py        # the runner
  recorded.json             # reference outputs (generated, see below)
  results/                  # report.json is written here (not committed)
```

## What each vector set tests

1. **Canonicalization.** Every signed operation is hashed and signed over its
   canonical encoding, so two implementations must agree on every byte:
   UTF-8 output, object keys sorted by Unicode code point, no insignificant
   whitespace, minimal escaping (non-ASCII characters emitted raw, not as
   `\uXXXX`), arrays kept in source order. Each vector gives an input value
   and the exact expected canonical text.

2. **Signing.** Each vector gives a fixed 32-byte Ed25519 seed and a message.
   The implementation must derive the RFC 8032 public key from the seed, sign
   deterministically, verify its own signature, and reject tampered messages
   and tampered signatures.

3. **Operation scenarios.** The runner builds an operation envelope
   `{v, type, author, ts, prev, payload}` with a fixed seed key and timestamp,
   signs it through the implementation under test, applies scripted mutations
   (zeroed signature, tampered payload, swapped id, flipped type, deleted
   fields, rewritten `prev` links), and asserts the verifier accepts or
   rejects as specified. Every mutation of a signed operation MUST be
   rejected; the unmutated operations MUST verify.

## Running

Self-check the reference implementation (also run automatically by the
pytest suite):

```sh
python conformance/run_conformance.py
```

Record the reference outputs (public keys, signatures, canonical digests,
operation ids) so other implementations have fixed expected values:

```sh
python conformance/run_conformance.py --record
git add conformance/recorded.json
```

`recorded.json` is generated rather than hand-written because hash and
signature bytes cannot be authored by hand. Once committed from a verified
reference run, it becomes the cross-implementation ground truth: every later
run (and every second implementation) is compared against it, and any drift
in canonical encoding, key derivation, signing, or id computation fails the
run.

A machine-readable report is written to `conformance/results/report.json`
on every run. The runner exits non-zero if any check fails.

## For second implementations

You do not need Python. Reimplement the three behaviors above, parse the
JSON vector files, and compare your outputs against `recorded.json`. The
semantics of the envelope fields and the id/signature computation are
specified in `INTEROP.md` at the repository root.