Module layout 

2026-09-26: Which files a (hardware, model, quant) kernel target is compiled from.

The kernels build script (crates/kernels/build_resolve.rs) compiles what it returns, the benchmark gate (metrale-bench’s gate::taxon) reads its inputs, and crates/kernels/tests/kernels_structure.rs grades the tree through it. scripts/lib/kernel_layout.py mirrors it for the Python checkers, and crates/kernels/tests/layout_mirror.rs holds the two to the same answer on the real tree.

Layers

A target reads up to four directories, each a layer:

role	tier	directory
leaf	own	kernels/<hw>/<source model>/<quant>/
leaf	parent	kernels/<parent>/<source model>/<quant>/
common	own	kernels/<hw>/common/
common	parent	kernels/<parent>/common/

<parent> is [hardware] inherits in the tree’s HARDWARE.toml; a tree that inherits nothing has two layers. <source model> is the model itself unless its MODEL.toml redirects with [model] kernel_source. A layer’s entries are the kernel sources and headers its directory holds plus what its KERNEL.toml [sources] use brings in.

Within a role the own tier wins by file name; the leaf role wins over the common role by source file stem. Every such win must be declared in [shadow] of the winner’s KERNEL.toml, with a reason: an undeclared one is an error, and so is a declaration with nothing to shadow.

Module identity is the file stem (Layout::modules), whichever layer the file came from.

Materialisation

Entries are compiled in their role directory, not where the file lives: the compiler resolves a quoted #include against the including file’s directory, so a used source must see the headers of the layer that uses it. The build script stages each role into OUT_DIR before compiling (crates/kernels/build_stage.rs); Layout::leaf and Layout::common are those two directories’ contents.

Owner: metrale-closure (kernel layout). Invariants:

• In a Layout that discover returns, every win of one layer over another is in shadows with its declared reason, and every [shadow] key names a win.
• No entry’s file is a symlink.

Structs

Entry

2026-09-26: One file a target compiles or stages beside what it compiles.

Hardware

2026-09-26: kernels/<hw>/HARDWARE.toml, the part resolution reads.

KernelManifest

2026-09-26: The resolution-relevant part of one KERNEL.toml.

Layer

2026-09-26: One of a target’s directories, whether or not it exists.

Layout

Shadow

2026-09-26: A declared, verified shadow.

Target

2026-09-26: One compiled unit: (hardware, model, quant).

Enums

LayoutError

Role

Tier

Constants

HEADER_EXTS

2026-09-26: Header extensions that are entries of every layer beside the sources, so a source’s headers are staged with it.

Functions

discover

2026-09-26: Resolve one target.

hardware

2026-09-26: kernels/<hw>/HARDWARE.toml, with inherits checked: the parent must exist, must not be the tree itself, must not inherit in turn, and must compile the same source extension.

kernel_manifest

2026-09-26: Parse <dir>/KERNEL.toml if it exists.

kernel_source_dir

2026-09-26: [model] kernel_source of <model_dir>/MODEL.toml, validated: the referent is a sibling model directory holding a MODEL.toml that does not redirect. Returns the source model directory (the model’s own when there is no redirect). A model directory with no MODEL.toml owns its own sources.

source_ext

2026-09-26: Kernel-source extension for a [hardware] vendor, or None for an unknown vendor, which hardware refuses.

stem_of

2026-09-26: The stem of a kernel-source file name: w4a16_gemm.cu -> w4a16_gemm.

symlinks

2026-09-26: Every symlink under kernels/, sorted. The structure test (kernels_structure.rs) refuses any.

walk

2026-09-26: Every target in the tree: each kernels/<hw> with a HARDWARE.toml, each model directory under it with a MODEL.toml, and every quant directory its source model owns in the tree or in the tree it inherits.