> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theformalera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec Keys

> How an annotation names the part of a model's compute graph a kernel implements.

A **Spec Key** names a set of nodes in the compute graph of one model at one spec version:

```text theme={"system"}
<org>/<model>@<version>:<layer-path>
```

| Part | Meaning | Example |
| - | - | - |
| `org/model` | The model, named like its Hugging Face repository | `Qwen/Qwen3.8-27B` |
| `@version` | Spec version: `major.minor`. The lock pins the exact patch version and content hash. | `@1.0` |
| `:layer-path` | One or more nodes of the compute graph | `layers[*].attn.core` |

## Layer selectors

Per-layer nodes take a layer selector. Top-level nodes (`embed`, `final_norm`, `lm_head`) take none.

| Selector | Selects | Example |
| - | - | - |
| `[*]` | Every layer **that has the node** | `layers[*].attn.core`: the 16 attention layers of Qwen3.8-27B, not the 48 Gated DeltaNet layers |
| `[a..b]` | Layers `a` to `b`, inclusive | `layers[3..15].mlp.act` |
| `[n]` | One layer | `layers[7].attn.core` |
| `[i]`, `[i+1]` | Relative layers, for fusion across a layer boundary | `{layers[i].mlp_residual, layers[i+1].input_norm}` |
| *(none)* | A top-level node | `lm_head` |

When a selector covers layers whose node has different constants (for example, sliding-window and global attention layers in Gemma 4), the kernel is verified against each variant separately.

## Common forms

```python theme={"system"}
# one node in every layer
"Qwen/Qwen3.8-27B@1.0:layers[*].input_norm"

# a node that exists only in some layers (Gated Attention: layers 3, 7, …, 63)
"Qwen/Qwen3.8-27B@1.0:layers[*].attn.core"

# one kernel fusing adjacent nodes of a layer
"Qwen/Qwen3.8-27B@1.0:layers[*].{attn_residual, post_attn_norm}"

# a kernel fusing across a layer boundary
"Qwen/Qwen3.8-27B@1.0:{layers[i].mlp_residual, layers[i+1].input_norm}"

# a top-level node
"Qwen/Qwen3.8-27B@1.0:lm_head"
```

A kernel used in several places lists several keys. Each one is verified separately:

```python theme={"system"}
@tfe.implements(["Qwen/Qwen3.8-27B@1.0:layers[*].input_norm",
                 "Qwen/Qwen3.8-27B@1.0:layers[*].post_attn_norm"], grid=("T",))
```

## Versions

* You may omit `@version`. The locked version is used.
* If you give a version, it must match the lock: `@1.0` with a lock at `1.0.4` is fine; `@1.1` is reported as UNKNOWN with "annotation asks for … but the lock pins …".
* Spec versions follow semantic versioning. Patch releases change only docs and metadata, never definitions. Minor releases add nodes or optional domains. Major releases change semantics.

## Reserved forms

| Form | Status |
| - | - |
| `layers[*]` (a whole layer) and `*` (the whole model) | Parsed, reserved for MegaKernel verification; resolving them reports that it is on the roadmap. |
| `ops/<name>@<version>` (a generic Op Spec, not bound to a model) | Parsed; bind the kernel to a model node instead for now. |

## Finding node names

The nodes of each model are listed on its [Spec Hub page](https://docs.theformalera.com/models/index.md), or from the CLI:

```bash theme={"system"}
theformalera spec show 'Qwen/Qwen3.8-27B@1.0:layers[*].mlp.act'
```

A typo in a node name is reported with the list of nodes that do exist:

```text theme={"system"}
Qwen/Qwen3.8-27B@1.0.0 has no node `mlp.actt` (nodes: embed, input_norm, gdn.in_proj, …)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.