open-standards/wai/ops-conformance/README.md

# ops-conformance — the integer operator set

Vectors for `wai-ops/1`, the integer operator set
([`extensions/integer-operators.md`](../extensions/integer-operators.md)): its graph
operators (§5), its stage operators (§5E), the `WHG1` graph form (§10), and the
canonical lowerings of the registered integer network forms (§13).

**Provenance.** Generated here by `wai-ops vectors gen` from fixed SplitMix64
sequences: every graph, parameter, input and stream under `vectors/`, `stage/`,
`graphs/` and `sets/` is generated integers, with no media. The lowered graphs under
`certificates/` are those of the sets this corpus generates and of the parameter sets
other corpora commit, which keep their own provenance (`certificates/index.json`
names each one's corpus).

**Equivalence.** An operator implementation of a profile (§7) conforms when it
reproduces every vector tagged with that profile, refusals included: the same `load`
outcome, and for every decode the same output integers or the same refusal code. A
lowering conforms when it writes every lowered graph byte for byte.

## Layout

- `vectors/<operator>.jsonl` — graph vectors whose graph has one operator (§14.1).
- `stage/<operator>.jsonl` — stage-operator vectors (§14.1).
- `graphs/<name>.jsonl` — graph vectors whose graph has several operators (§14.2):
  - `phase` — a transposed convolution and the same computed as phase convolutions,
    interleaved by `pixel_shuffle` and cropped (§9.3), as the graph's two outputs;
  - `state` — state inputs carried across decodes (§10.3), a refused decode among
    them;
  - `load` — a graph refused at each load check of §10.5, steps 1–7, and a `crop`
    planned at load (§5.10);
  - `run` — a decode refused at each step of §4's run, and the order between them
    and within step 3 (the caps, then the shape rule, then `max_elems`);
  - `lower_<form>` — each lowering of §13 on a small set from `sets/`.
- `sets/<name>/` — the small parameter sets the `lower_*` vectors lower, one per
  lowering, in their registered forms.
- `certificates/<capability>/<set digest>/<role>.whg1` — each lowered graph (§14.3).
- `certificates/index.json` — every set lowered here: its capability, its lowering,
  its members (the name in the set and the file, relative to `wai/`, that holds it),
  its digest, and the path of each lowered graph, in §13.0's role order.

Files are compared as bytes; `.gitattributes` turns off line-ending conversion.

This corpus has no `sha256.json` sidecar (SPEC §7 *Digests*). Every vector states its
output integers in full, or its refusal code, and never a digest of them. The only
digest in `certificates/` is each set's SHA-256, which identifies a parameter set. The
output digests that a capability reproduces through its lowering (integer-operators §14.4)
stay in that capability's own corpus.

## The vector files

Every file follows integer-operators §14.1, which is normative for every field: the
graph vector and its decodes, the stage vector with its `modes`, each operator's
`in` and `expect` (the predictors' layouts included), and the refusal index `at`.
In short:

- Every file is JSON Lines: one canonical JSON value per line (§8.5's rules), each
  line ending with one line feed.
- A graph vector's decodes list the graph's **data** inputs only; the decodes of one
  vector are one sequence, and a refused decode changes no state (§10.3).
- `load` is the outcome of load steps 1–8 (§10.5); every vector here loads or is
  refused at steps 1–7 (see below). A vector whose load is refused has no decodes and
  lists both profiles; one that loads lists exactly the profiles its verdict meets.
- `at` is −1 for a refusal before any symbol or element, the symbol's index for
  `rans64_decode` (the number of symbols for a refusal after the last one), and, for
  `mans_decode`, the position whose step refuses, or, for a flush that belongs to no
  single position, the last position whose `in` step ran.
- A vector of `graphs/lower_<form>.jsonl` has the id `<file>/<set>/<role>/…`: its
  graph is that role of the set `sets/<set>/` as lowered.

## What this corpus does not cover yet

Load step 8 has no implementation in `wai-ops` yet: its bounds pass and verdict land
with the certifier. Until then the `uncertified` switch skips it, and the generator
writes no vector whose outcome depends on it; a generated case whose graph meets no
profile is dropped, and `vectors gen` reports the count. So these coverage classes
of §14.1 item 6, each a load refusal at step 8, are not here yet:

- `sigmoid` and `elu` on an input range that reaches `−2^63`, refused at load (the
  corpus has the decoding side, ranges that stop at `−(2^63 − 1)`);
- an `rq` whose `q` passes 64 bits while `y` fits, refused at load under `acc64`
  (`conv`, `conv_transpose`, `rescale`, `chscale`, `mul`, `gram`, `apply`);
- a `lut16` whose input range passes `[−32767, 32767]`, and a `check` range that no
  value of its producer can meet (§8.1);
- a graph refused at step 8 in `graphs/load.jsonl`.

The independent checker already runs step 8 and recomputes every vector's
`profiles` from its own bounds pass, so these vectors are checked the day they land.

## The lowered sets

`certificates/index.json` lists every set. A set of one file is identified by its
file's SHA-256, and a set of several files by the SHA-256 of its `wai.prior.set`
listing over the member names the index gives (SPEC §3.1). `wai.world.model` has no
registered set yet: its two networks are named `T.whm` and `g_s.whm` here, and its
lowering's latent channel count, which the initial latent fixes, is the entry's `c`.

## Generation and verification

    cd wai/wai-ops
    cargo run --release --features uncertified --bin wai-ops -- vectors gen ..

writes every file here but this README and `.gitattributes`.

    cargo run --release --features uncertified --bin wai-ops -- vectors verify ..

recomputes every vector file from its inputs, re-lowers every set, and regenerates
the corpus, and requires every byte to equal the committed one. The same check runs
built for `wasm32-wasip2` under a WASI runtime, and, for the vector files,
`wai-ops/node/verify.mjs` runs the recomputation as a `wasm32-unknown-unknown`
module under a browser's engine.

    python3 -I tools/wai_ops_check.py ops-conformance

is the independent checker: Python standard library only, sharing no code with
`wai-ops`, and held to the extension's text: where the two disagree, the text
decides, and the disagreement is a bug in one of them. It rewrites every vector file
from its inputs, `load` (steps 1–8) and `profiles` from its own bounds pass and
verdict (§8.1–§8.5) included; re-lowers every set and requires each lowered graph,
and that each loads; and requires each lowering vector's graph to be the role its id
names. Every byte must equal the committed one.