Crate metrale_circuit 

2026-09-28: Architecture circuits. A model is a graph of ops (kernels/circuits/<arch>.toml) whose edges the fuser marks fused or materialised by applying the hardware’s fusion rules (kernels/<hw>/common/FUSIONS.toml) for one mode and row count.

Owner: metrale-circuit. Invariants:

• Pure: no GPU, no file I/O, no environment, no clock and no randomness. Callers read the TOMLs and pass their text in (load).
• A plan is deterministic, and its digest is recorded beside the closure hash.

Re-exports

pub use checkpoint::CheckpointError;

pub use checkpoint::QuantMetadata;

pub use checkpoint::ResolvedCheckpoint;

pub use checkpoint::ServePrecision;

pub use checkpoint::instantiate_from_checkpoint;

pub use checkpoint::map_checkpoint;

pub use checkpoint::recurrent_states;

pub use checkpoint::resolve_checkpoint;

pub use circuit_toml::CircuitError;

pub use circuit_toml::includes_of;

pub use format::Format;

pub use format::Scale;

pub use fuser::AvailableKernels;

pub use fuser::EdgeState;

pub use fuser::FuseError;

pub use fuser::FusionPlan;

pub use fuser::Group;

pub use fuser::Policy;

pub use fuser::fuse;

pub use fuser::fuse_table;

pub use instances::Instance;

pub use instances::InstanceError;

pub use instances::PrecisionSpec;

pub use instances::parse_instances;

pub use instantiate::instantiate;

pub use ir::ArchShape;

pub use ir::Circuit;

pub use ir::LayerKind;

pub use ir::LinearRole;

pub use ir::OpKind;

pub use ir::Section;

pub use precision::EdgePrecision;

pub use precision::LinearFormats;

pub use precision::PrecisionError;

pub use precision::PrecisionTable;

pub use rules::KernelId;

pub use rules::Mode;

pub use rules::Numerics;

pub use rules::Rule;

pub use rules::RuleError;

pub use rules::parse_rules;

pub use runs::RowTable;

pub use runs::VerifyRun;

pub use runtime::RuleSet;

pub use runtime::RuntimeRoute;

pub use runtime::parse_rule_set;

Modules

checkpoint

2026-09-30: A circuit from a checkpoint alone: its config.json and quantization metadata pick the architecture, map to an arch shape through the architecture’s declarative config map (kernels/circuits/<arch>.config.toml), and give every projection its declared formats. The model axis of met circuit plan --checkpoint --hardware.

circuit_toml

2026-09-28: The kernels/circuits/<arch>.toml schema: block templates, the layout rule that maps a model’s layer kinds to templates, and the typed load errors.

config_map

2026-09-30: The declarative config mapping of one architecture (kernels/circuits/<arch>.config.toml): how a checkpoint’s config.json becomes the arch shape a circuit instantiates under (layer kinds, dims) and the math parameters the kernels read, with every key the config carries classified.

declared_precision

2026-09-30: DeclaredPrecision, the EdgePrecision that gives every projection the formats its checkpoint DECLARES (DeclaredPrecisionPlan), before any serving policy: the weight as stored, and the input activation as the checkpoint declares it (FP8 per token, per tensor with a static scale, NVFP4 group 16, or 16-bit).

digest

2026-09-28: Two digests. plan_digest is SHA-256 over a canonical serialization of what a plan runs: its groups (members, kernels, repetition, emitter, numerics) and every edge’s stored format and state, under the plan’s arch, mode and rows. rules_digest is SHA-256 over the FUSIONS.toml text the rules were parsed from.

dims

2026-09-28: Dimension expressions: a sum of products of named dims and integer literals, e.g. q_heads*head_dim*2 or lin_qk*2+lin_v. 2026-10-02: A factor may be a dim divided by a literal, rounded up (moe_inter/128: the scale count of a 128-wide group).

display

2026-09-28: met circuit display: the human view of one fusion plan. It builds a styled document (lines of spans, each span a semantic Style) from the same circuit and plan met circuit show prints; the CLI maps styles to colours.

format

2026-09-28: Tensor formats of edges and weights, and their one text spelling.

fuser

2026-09-28: The fuser: cover a circuit’s nodes with rule groups for one mode and row count.

hardware

2026-09-30: The hardware axis of the circuit (met circuit plan --hardware <device>): point a model and a target device at it and get the fused plan the device’s kernel class can run, the gap report against that class’s kernel set ranked by the device’s roofline, decode and prefill estimates, and a memory-fit check.

instances

2026-09-28: kernels/circuits/INSTANCES.toml: which recipes have a circuit, with the arch shape, precision table, policy and plan matrix each one is shown and checked under.

instantiate

2026-09-28: Instantiate a circuit TOML against an arch shape and a precision resolver.

ir

2026-09-28: The circuit IR: a closed op vocabulary, edges with a format and a shape, nodes bound to checkpoint modules, and the instantiated graph of one model.

memory

2026-10-02: The circuit memory model (owner directive 2026-10-02): for each node, the memory it holds (weights and their load-time copies, the activations it materializes at the peak run, its kernel family’s workspace, the state it touches), for each declared state and cache its bytes as a function of the runtime parameters, and their sum against a device’s budget.

model_buffer

2026-09-30: The model buffers a circuit’s declared outputs bind to (M5, LIFECYCLE-DESIGN.md section 3.4): a block’s outputs name each edge read outside the program and the buffer it lands in, so the executor places external edges by declaration, never by guessing from the producing op.

pipeline

2026-10-02: The numeric pipeline of a node: the formats it reads, the ordered steps inside it (activation and weight preparation, the multiply’s operands, accumulation, scale application, element-wise compute, cache and state precision, routing and blending) each with its precision, and the formats it writes. One pipeline is REQUIRED per node of a plan (require: the circuit’s formats under the serving policy) and one is DECLARED per kernel family, point or kernel in KERNEL_FAMILIES.toml (declare); check refuses a plan whose kernels declare anything but exactly what the plan requires.

planner

2026-09-28: The buffer planner: an arena offset for every materialised edge of a plan, sized once for the widest padded row count, so no buffer is reallocated after boot (the CUDA-graph constraint: captured pointers must stay valid).

precision

2026-09-28: The precision a linear node runs at: the EdgePrecision resolver, and PrecisionTable, a table-driven implementation read from kernels/circuits/precision/<checkpoint>.toml.

precision_policy

2026-09-28: PolicyPrecision, the EdgePrecision the engine’s own precision answers give: the checkpoint’s declared plan (DeclaredPrecisionPlan) under the served tier (WeightQuantPolicy), plus the formats the engine chooses itself (a recipe’s lm_head, the MTP head), which the checkpoint does not declare.

render

2026-09-28: The stable text rendering of a plan: the golden files under kernels/circuits/plans/ and met circuit show.

rules

2026-09-28: Fusion rules: kernels/<hw>/common/FUSIONS.toml. Each rule names an op chain, the kernel that runs it, where it applies (rows, modes, caps, policy settings) and how its numerics relate to the reference.

runs

2026-09-30: The row table of a batched MTP verify (Mode::VerifyBatch) and the per-run launches a repeat = "per_run" rule selects. A batched verify checks n sequences together, sequence i with k_i rows, seq-major. The GatedDeltaNet layers launch once per run: a maximal group of adjacent sequences with equal k. Model-engine batched_conv_gdn_route forms the runs, and so does RowTable::from_seqs. Each run is contiguous when its sequences’ state slots are consecutive, which the batched kernels need. A table is carried when the verify runs the carried-state GDN kernels (gdn_carry_begin), which it does whenever the WY tables are staged.

runtime

2026-09-30: Runtime routes. A runtime route is a condition the engine checks at run time, not a policy setting. When it holds, a step leaves the arm its plan names and runs another. A FUSIONS.toml declares each route ([[runtime]]) with the settings its arm plans as. A plan is rendered, estimated and executed with the arm of every route that applies beside it.

state

2026-09-30: The state a circuit keeps between steps, declared per block ([[block.<name>.state]]), and the one function that sizes it (M5, LIFECYCLE-DESIGN.md section 3.3): the recurrent slots of GatedDeltaNet and Mamba2 layers with their verify intermediates and checkpoints, and the paged KV blocks of attention layers.

state_ops

2026-09-30: The state programs of a circuit (M5, LIFECYCLE-DESIGN.md section 3.5): the small programs that move recurrent state between its places around a speculative verify, and reset a slot, as nodes over the circuit’s declared states. Legacy runs them as host code that sizes each copy itself (verify_a_ssm.rs, async_chkpt.rs, ssm_pool_slots.rs), with the GatedDeltaNet conv formula, which is 0 bytes for a Mamba2 layer; here every node is sized from its state’s declaration, so a Mamba2 layer’s copies are its own.

venn

2026-09-29: The kernel Venn diagram of a target model against the models we already support (met circuit venn): every target node, in every mode and row count asked for, classified against the kernel families the compared models run, ranked by estimated share of step time.

Structs

Loaded

2026-09-28: An instance’s circuit and rules, ready to fuse.

Sources

2026-09-28: The texts one instance is built from.

Enums

LoadError

2026-09-28: Any failure between the TOML texts and a rendered plan.

Functions

display_plan

2026-09-28: Fuse, lay out and draw one plan of instance: the view met circuit display prints, over the same plan render_plan renders. 2026-10-02: Checked and drawn with each node’s pipeline, as render_plan.

header

2026-09-28: The header lines a rendering of instance carries.

load

2026-09-28: Parse and instantiate instance from src, with the precision its spec names.

load_with

2026-09-28: Parse and instantiate instance from src with precision: the executor passes the served model’s own policy here, the checked-in fixture being only the offline copy of it.

render_plan

2026-09-28: Fuse and render one plan of instance. 2026-10-02: each group line names the compute unit its kernels run on (venn::compute), from the target class’s kernel families, and each member node its pipeline; a node whose kernel declares another pipeline than the plan requires refuses the plan (pipeline::check_plan).

render_table_plan

2026-09-30: Fuse and render one batched-verify plan of instance, for table. 2026-10-02: Checked and annotated as render_plan.