Loam Development Guide

Loam compiles an ONNX graph into Wado source through Kiln. Its design is in design.md, which names the documents it builds on. The roadmap and the known gaps are in TODO.md. loam gen, loam dump, the onnxruntime oracles and the benchmarks are in tools.md.

WEP: Loam is complete, and nothing edits it any more. A design that changes one of its decisions is written in this directory and names the WEP's section.

The documents here sketch a design and describe what exists; they decide nothing. Correctness and speed come first.

Sources

• Do not read the code of an ML framework, runtime, exporter or kernel library.
• Published papers and specifications may be read: ONNX's operator definitions, the StableHLO specification.
• ONNX's own source may not be read: the code under vendor/onnx/onnx/, its reference implementation among it, vendor/onnx/tools/ and vendor/onnx/docs/docsgen/. Its headers, .proto files, docs and tests may be read, and the tests are vendor/onnx/tests/, vendor/onnx/onnx/backend/test/ and the fuzzers in vendor/onnx/onnx/fuzz/. permissions.deny enforces this for the Read tool, and .claude/hooks/vendor-license-guard.mts for Bash, which also refuses a search of a directory holding that source: name the doc to search.
• An interface may be read, as a specification: any .proto file, and xla/pjrt/c/pjrt_c_api.h, the PJRT plugin's. The rest of XLA may not.
• onnxruntime's operator documentation may be read, for the operators it defines beyond ONNX, such as com.microsoft::GroupQueryAttention (docs/ContribOperators.md). Its code may not. Where the documentation leaves a behavior open, onnxruntime is run as an oracle for it.
• Test data and models may be copied in and read, each directory carrying its source and license, as tests/onnx/ and tests/models/ do.

Testing a change

Each semantics is written once per device: Cpu, WebGpuBackend, and PjrtBackend. Generated code reaches all of them, so a change can break code it never touched. Test outward from the change, as tools.md lists, and run the whole package once, last.

CI tests the logic on every device with very small programs, which should reach as many operations and paths as they can. A real model such as Gemma 3 runs by hand, and its figures go in a measurement table.

Oracles

A case in conformance/operators_test.wado or semantics_test.wado where Loam does not match onnxruntime yet is a #[TODO] test, so the run lists where the two part.