This page is for anyone who wants to run the repository's checks, rebuild its examples or load a document into a database. Newcomers get each term defined where it first appears. Implementers get the commands and the traps.

These programs are the repository's reference implementation. They apply every rule of the specification, so the rest of the repository can be checked against them. Two build and check the repository, and one loads packages into SQLite, a database stored in a single file. They use only the Python standard library (Python 3.10 or later [CHECK: stated in README.md; pixi.toml pins 3.14 and I could only run on 3.13]) and are licensed Apache-2.0.

A package is the folder of files that holds one document, such as fixtures/packages/hale2026harmonic. A vector is a test case: an input and the exact output every implementation must compute (see the vectors). A fixture is an example file or package under fixtures/.

Program	Does
`check.py`	Checks everything: schemas, records, packages, the broken packages, every vector, a byte-for-byte rebuild, the SQL (a database query language) round trip and the prose. `--quick` skips the rebuild.
`build.py`	Builds `fixtures/` and `vectors/` from the hand-written sources in `fixtures/src/` and the cases it defines. `--out DIR` builds into another folder.
`load.py`	Loads packages into a SQLite database with the tables of `sql/`: `python3 tools/load.py --sqlite lab.db PACKAGE [PACKAGE ...]`.
`oracle/`	A compact implementation of every rule. `build.py` uses it to compute expected values, and `check.py` uses it to recompute them.

When to run what

Each program is also a pixi task. Pixi sets up a pinned Python and the other packages the repository uses. The commands pixi run check, pixi run quick, pixi run build and pixi run load then work from anywhere in the repository [CHECK: pixi is not installed here, so the pixi forms were not run]. pixi run check lints the Markdown first.

Run the programs directly from the repository root if you do not use pixi:

python3 tools/check.py            # everything
python3 tools/check.py --quick    # everything except the rebuild
python3 tools/build.py --out /tmp/rebuilt
python3 tools/load.py --sqlite lab.db fixtures/packages/hale2026harmonic

A passing check ends with All checks pass. The load command prints hale2026harmonic: 75 nodes, one line per package, and writes lab.db with a folder lab.db.assets/ beside it for files that have no table of their own. build.py has no help option and ignores flags it does not know, so it rebuilds fixtures/ and vectors/ in place unless you pass --out.

Run pixi run check before every commit. Run pixi run build after you change a fixture source, a rule in oracle/ or a case in build.py, and commit the regenerated files with the change. The check rebuilds into a temporary folder and compares every file byte for byte, so it fails on out-of-date files.

About the oracle

An oracle is a reference computation: a slow, plain program whose answers count as the expected ones. It is not a production reader or writer. The oracle exists so that no expected value in this repository is typed by hand.

It favors clarity over speed. Its Ed25519 (a digital signature scheme) is the slow reference code of RFC 8032. Its validator for JSON Schema (a format that describes the shape of JSON data) supports exactly the keyword subset the schemas use and refuses any schema that uses more.

Do not build on it as a library. Implementations follow the specification and test themselves against the vectors.