Module graph 

Compute-graph IR (a typed DAG) — the backend-portable representation the forge lowers to every target in one pass. See [docs/plans/dag-ir-forge.md].

Phase 1 (this slice)

Establishes the spine: the graph types, a topological lower_graph walk, the Lowerer visitor trait (one method per op-class), and the KernelSpec::to_graph bridge for the function-backed WGSL kernels (gemm/gemv/fft). The WGSL leaf emission delegates to the proven emit_*_wgsl functions, so the generated bytes are identical by construction (the certify-cache source_hash is unchanged). Native from-scratch graph templates replace the delegations in later phases.

The full op-node vocabulary is fixed here (the enum is the contract); only the seed arms have a real lowering today — the rest lower to an explicit Err, never a silent no-op.

Build-time note: the in-memory graph uses Vec (this is emit-time construction, not the runtime zero-copy NQuin ABI). The zero-copy quin encoding is Phase 6.

Structs

ComputeGraph

A directed acyclic compute graph. Acyclic by construction: ComputeGraph::push only accepts inputs that reference already-added nodes (or EXTERNAL), so insertion order is a valid topological order. nodes[i].out.producer == NodeId(i).

GraphNode

One node of a ComputeGraph: an op, its input edges, its single output edge, and a per-node Schedule.

NodeId

Arena index of a node within a ComputeGraph. NodeId::EXTERNAL marks a graph input (a TensorRef produced outside the graph).

Shape

Fixed-rank (≤4) tensor shape — no Vec, so a TensorRef stays Copy. A dim of 0 means “runtime-parameterized” (resolved from a params buffer at dispatch — e.g. GEMM’s M/N/K), which is how the dimension-independent WGSL kernels are represented.

TensorId

Identifies one output tensor of a producing node (nodes may emit more than one later).

TensorRef

A typed data-flow edge: the tensor-th output of producer, with its shape/dtype.

Enums

AccumKind

Scatter-accumulate reduction (OpNode::ScatterAccum, Phase 7).

Axis

Axis selector for reductions / softmax / stencils.

DType

Element type of a tensor edge.

EwKind

Elementwise function kinds. Phase 1 carries the affine subset; the LLM kit (Silu/Gelu/Exp/RecipSqrt/…) lands in Phase 3.

Layout

Storage layout of a tensor edge (row-major dense for now).

NbKind

Spatial-proximity query kind (OpNode::Neighbor, Phase 7 — RT-backed).

NeighborEnc

How a >3-D Neighbor query is encoded into the 3-D BVH (or refused → grid fallback).

OpNode

An op-CLASS and its compile-time payload — the node label of the compute DAG (plan §2; Slice/Rope added for the real decode layer). Seed arms (Elementwise/MatMul/Gemv/ Fft) have a real lowering today; the rest are declared so the vocabulary is fixed, and lower to an explicit Err until their phase builds them.

RedKind

Reduction kinds for OpNode::Reduce.

StencilKind

Stencil neighbourhood kind (OpNode::Stencil, Phase 7).

Constants

MAX_IN

Maximum data-flow inputs to a single node.

Traits

Lowerer

A backend code generator. lower_graph calls exactly one method per node, in topological order. Op-classes a backend has not implemented yet use the default methods, which return an explicit Err (never a silent no-op).

Functions

lower_graph

Walk the graph in topological (insertion) order and dispatch each node to its Lowerer method. The single, backend-agnostic lowering driver — every backend is a Lowerer impl, so there are no per-kernel.id branches.