# vesl — full documentation

> Verifiable Execution and Settlement Layer

Generated 2026-05-25 from zkvesl-docs 4f2c66c (vesl-nockup 6e2127c, vesl-core 11d110d).
Pages in sidebar order; cross-check source if your checkout is newer.

================================================================================
# Source: /pitch.md
================================================================================

# vesl at a glance

**Fourteen verifiable primitives, one composition command, typed at every seam.** The hard parts ship as grafts; you write the application.

Building a verifiable app means weeks of crypto code, custom state machines, replay-attack logic, and a hand-rolled HTTP server — before you ship a feature. vesl-nockup gives you all four as composable primitives. Drop in Merkle commitments, STARK proofs, RBAC, an audit log, or a settlement queue with one command. Drive the kernel from typed Rust with compile-time drift detection. Test against the real kernel, not a mock. Boot a production HTTP server out of the box.

```d2
direction: down

domain: "Your domain\napp-specific causes, peeks, Rust handlers"
vesl: "vesl\ngraft library, vesl-core SDK, vesl-hull HTTP, nockup graft CLI"
nockchain: "Nockchain\nNock, Hoon, hoonc, NockApp, JAM, tip5"

domain -- vesl
vesl -- nockchain
```

## What ships

- **14 grafts** across four families plus a placeholder. See [the graft library](#the-graft-library) below.
- **Typed Rust SDK** — `vesl-core` exports `Mint`, `Guard`, `Settle`, one `build_*_poke` per cause, and effect decoders for every cell-payload variant.
- **Real-kernel test harness** — `vesl-test` boots the same `out.jam` your app does. What you test is what your users get.
- **HTTP server out of the box** — `vesl-hull` mounts `/commit`, `/settle`, `/verify`, `/tx/{tx_id}`, `/status`, `/health`. API-key auth, body-limit, rate-limit included.
- **Live updates preserve state** — edit Hoon, recompile, restart; accumulated state survives via PMA. A new feature is a sub-minute deploy.
- **Loud failures** — `compile.sh` verifies its artifact, lints refuse to compose corrupted Hoon, `verify-jam` detects stale kernels, `assert_kernel_cause_tag!` turns hull/kernel drift into a compile error.

## Ten lines, end to end

```rust
// Example: register a Merkle root, settle a note against it.
use vesl_core::{Mint, build_settle_register_poke, build_settle_note_poke};

let mut mint = Mint::new();
let root = mint.commit(&[b"first-license"]);

app.poke(SystemWire.to_wire(), build_settle_register_poke(1, &root)).await?;
app.poke(SystemWire.to_wire(), build_settle_note_poke(1, 1, &root, b"first-license")).await?;
// %settle-registered + %settle-noted — Merkle-rooted, replay-protected.
```

## Three commands to a running verifiable kernel

```bash
nockup project init                              # scaffold from the vesl template
nockup graft inject --apply hoon/app/app.hoon    # compose the grafts in
cargo +nightly run --release                     # boot the hull
```

About 80 lines per graft. Your domain logic stays five to ten lines of Hoon per cause; everything else is composed.

## The Graft Library

Fourteen grafts ship today, organized into three families plus a placeholder. Each is a Hoon library plus a sibling TOML manifest; drop them into your kernel and they compose at injection time.

**Commitment family** — Merkle commitments and proofs.
- `mint-graft` — publish a Merkle root that future proofs verify against.
- `guard-graft` — publish a root and check whether items belong to it.
- `settle-graft` — publish a root, verify items against it, and record each settlement once (no double-counting).
- `forge-graft` — generate zero-knowledge (STARK) proofs over committed data.

**State family** — durable application state primitives.
- `kv-graft` — string-keyed key-value store.
- `counter-graft` — named integer counters.
- `queue-graft` — FIFO job queue with stable IDs.
- `rbac-graft` — public-key role and permission table.
- `registry-graft` — strict structured registry with create / update / delete.

**Behavior family** — observe or constrain how the kernel processes incoming messages.
- `validate-graft` — pre-flight checks before a message reaches domain logic.
- `log-graft` — append-only audit trail.
- `clock-graft` — deterministic event clock.
- `batch-graft` — buffer settlements and flush in batches.

Reserved: `intent-graft`, for future multi-party coordination. Not yet active. The trellis pattern (one kernel, multiple `hull=@` namespaces) layers cleanly across all three families.

[Grafts / The 5-Family Graft Taxonomy](/build/grafts/#the-5-family-graft-taxonomy) has the canonical table with priority bands and member roles. [Per-Graft Rust Snippets](/build/grafts/#per-graft-rust-snippets) shows one realistic poke per graft.

## Where vesl ends and nockchain begins

Nock is nockchain's combinator calculus. JAM serialization, tip5 hashing, the STARK proving stack, and the deterministic Nock interpreter are all nockchain's primitives — not vesl's. vesl runs a Hoon kernel inside nockchain's `NockApp` and ships a graft library plus a Rust SDK on top. It does not invent determinism, proving, or the noun model. The foundation's properties (post-quantum cryptographic primitives, transparent STARKs without trusted setup, byte-for-byte reproducible execution) are inherited — vesl makes them composable into your app surface.

## Where to start

- [Quickstart](/setup/quickstart) — three commands from empty directory to `%settle-registered` + `%settle-noted`.
- [Build a Real App](/build/real-app) — compose five grafts into a license registry, end to end.
- [NockApp Anatomy](/build/anatomy) — the conceptual layout (hull, grafts, domain) every other page assumes.
- [Grafts](/build/grafts/) — the 14-graft catalog with per-graft Rust snippets.
- [Production Checklist](/build/build-run/production-checklist) — pre-ship verification surface.
- [Glossary](/reference/glossary) — every term used on this page, defined.

::: info See Also

- [vesl-nockup on GitHub](https://github.com/zkvesl/vesl-nockup) — the canonical source repo.
- [vesl-core on GitHub](https://github.com/zkvesl/vesl-core) — the Rust SDK crate.

:::

================================================================================
# Source: /setup/quickstart.md
================================================================================

# A Quick Note

Scaffold a vesl nockapp, install fourteen verifiable primitives, compose them into one Hoon kernel, watch a Rust hull settle a Merkle-rooted note. Three commands. Five minutes.

[vesl-nockup](https://github.com/zkvesl/vesl-nockup) is the recommended starting point — a self-contained distribution that pairs with `nockup`, the project scaffolder shipped from the nockchain monorepo. The rest of this guide assumes you're using both.

## Get Started

Three commands from an empty directory to a kernel that registers a Merkle root and settles a note against it:

```bash
nockup project init                                    # fetches vesl template + zkvesl/vesl-graft
nockup graft inject --apply hoon/app/app.hoon          # composes grafts into the kernel
cargo +nightly run --release                           # builds out.jam, runs the kernel
```

If `hoonc`, `nockchain`, or `nockup` are unfamiliar, see [vesl at a glance](/pitch) or the [Glossary](/reference/glossary) first.

::: tip Why `--release`?
The nockvm runtime ships `debug_assert!`s in its stack-frame check (`is_in_frame`) that fire under debug-build assumptions and are compiled out in release. Booting a 14-graft kernel from a debug build panics on the first poke. `--release` is the supported development mode for vesl-nockup until the upstream assertion is loosened.
:::

## Prerequisites

1. **Clone the nockchain monorepo** — source for `nockup`, and for the `nockchain` binary later if you run against fakenet/dumbnet (the three-command flow below doesn't need the chain binary on `PATH`):

   ```bash
   git clone https://github.com/nockchain/nockchain.git
   ```

2. **Install `nockup`** — the project scaffolder. `nockup install` downloads `hoon`, `hoonc`, and `nockup` itself into `~/.nockup/bin/` and prepends that to your `PATH`. Either script install or build from the cloned monorepo:

   ```bash
   # Script install
   curl -fsSL https://raw.githubusercontent.com/nockchain/nockchain/refs/heads/master/crates/nockup/install.sh | bash

   # Or build from source
   cd nockchain && cargo install --path crates/nockup --locked
   ```

3. **Rust nightly** — `rustup toolchain install nightly`. Then `cargo +nightly` resolves to it.

4. **`nockup-graft`** — vesl-flavored graft composer; ships from vesl-nockup as a sidecar binary alongside `graft-inject`:

   ```bash
   cargo install --git https://github.com/zkvesl/vesl-nockup --bin nockup-graft
   ```

   Once installed, `nockup graft <subcmd>` resolves the binary via nockup's plugin discovery and dispatches to it.

Verify the toolchain:

```bash
hoonc --version && nockup --help >/dev/null && cargo +nightly --version && nockup-graft --version
```

### Shell completions (optional)

Both `nockup-graft` and `vesl-test` emit completion scripts for bash, zsh, fish, elvish, and powershell via a `completions <shell>` subcommand. One-line install per shell:

```bash
# bash — drop into the user's bash-completion dir; re-source your bashrc.
nockup-graft completions bash > ~/.local/share/bash-completion/completions/nockup-graft
vesl-test    completions bash > ~/.local/share/bash-completion/completions/vesl-test

# zsh — into the first fpath entry; rebuild compinit (`exec zsh` or `compinit`).
nockup-graft completions zsh  > "${fpath[1]}/_nockup-graft"
vesl-test    completions zsh  > "${fpath[1]}/_vesl-test"

# fish — picked up automatically on next shell start.
nockup-graft completions fish > ~/.config/fish/completions/nockup-graft.fish
vesl-test    completions fish > ~/.config/fish/completions/vesl-test.fish
```

After install, tab-complete subcommands (`nockup-graft inj<TAB>` → `inject`) and flag names (`nockup-graft inject --lib-<TAB>` → `--lib-dir`). The scripts are clap-generated, so they stay in sync with the binary on every rebuild — re-run the install line after a `cargo install --force` to pick up new subcommands.

## 1. Scaffold from the `vesl` Template

Write a `nockapp.toml` declaring the package and template source, then let `nockup` create the project:

```bash
cat > nockapp.toml <<'TOML'
[package]
name = "my-app"
version = "0.1.0"
description = "grafted NockApp"
template = "vesl"
template_git = "https://github.com/zkvesl/vesl-nockup"
template_path = "templates"

[dependencies]
"zkvesl/vesl-graft" = "latest"
TOML

nockup project init
cd my-app
```

`nockup project init` does three things:

1. Creates the `my-app/` project directory.
2. Pulls in the vesl graft library.
3. Runs the package's post-install patches — `Cargo.toml` rewrites that align Rust deps with the pinned nockchain revision, plus any scaffold-file additions the package declares. You'll see a confirmation prompt that lists every patch operation; press `y` to apply. Patches are declarative — no code runs.

::: tip Running this in a script
The confirmation prompt in step 3 blocks unattended runs. To pre-approve, pipe consent:

```bash
yes y | nockup project init
```
:::

## 2. Wire the Kernel

```bash
nockup graft inject hoon/app/app.hoon            # preview
nockup graft inject --apply hoon/app/app.hoon    # write
```

The template's `app.hoon` ships with ten `::  nockup:*` markers at fixed structural points. `nockup graft inject` discovers every `<name>-graft.toml` under `hoon/lib/`, composes their per-marker blocks, and (with `--apply`) writes the result. About 80 lines per graft.

Preview is the default. Nothing lands on disk until you pass `--apply` — this keeps a compromised `hoon/lib/` from silently composing hostile Hoon into your kernel source. See [Inject](/build/grafts/inject) for marker semantics, lint families, and the per-graft sha256 banner.

Inject also refuses to compose when the project has no `nockapp.toml` — the file you wrote in [§1](#_1-scaffold-from-the-vesl-template) is the trust anchor, per [Manifest Schema → Trust Model](/build/grafts/manifest-schema#trust-model). Without it, inject would splice arbitrary Hoon from any directory into your kernel; running from inside the scaffolded project keeps this check satisfied.

## 3. Build and Run

```bash
./compile.sh
cargo +nightly run --release
```

`compile.sh` ships in the scaffold: it runs `hoonc`, then fails loud if hoonc exited 0 without writing `out.jam` — a structural type error can cause exactly that. See [Build & Run](/build/build-run/) for `vesl-test verify-jam`, the staleness check.

First Cargo build fetches and compiles the full nockchain stack — expect 2–5 minutes.

## 4. Verify Effects

The last two lines should be:

```
  effect: %settle-registered
  effect: %settle-noted
```

Each `effect:` line is a tagged event the kernel emitted back to the hull:

- **`%settle-registered`** — the kernel accepted a Merkle root under a namespace (called a `hull`). The root is a fingerprint of a set of items; once registered, only items that hash into it can later be proven to belong.
- **`%settle-noted`** — the hull then submitted one item from that set along with a Merkle proof, and the kernel verified the proof matches the registered root. The item is now recorded as settled, and the same item can't be settled twice.

This commit-then-prove cycle is the canonical vesl pattern. The same shape powers asset registries, licensing flows, and audit logs — anywhere a kernel needs cryptographic evidence that an item belongs to a published set. The template's `src/main.rs` is a clap dispatch — the `Demo` arm walks the lifecycle once; the `Serve` arm boots the same kernel and mounts the `vesl-hull` HTTP API. See [Build / Hull → Scaffold CLI: Demo and Serve](/build/hull#scaffold-cli-demo-and-serve) for the Serve flags and endpoint catalog. You'll extend the Demo arm to your domain in [Build / Hull](/build/hull).

## 5. Exercise the Lifecycle

You've watched the binary emit two effects from a startup poke. The next step is to confirm those effects landed in kernel state and to query that state from outside the lifecycle.

### Observe both effects

Re-run the binary and capture the effect list. The two head tags emitted are:

| Effect | Full payload | Meaning |
|---|---|---|
| `%settle-registered` | `[hull=@ root=@]` | A hull was registered against the configured root; the hull is now known to settle-graft. |
| `%settle-noted` | `note=[id=@ hull=@ root=@ state=[%settled ~]]` | A note was filed against the registered hull; settle-graft updated its per-hull index. |

For the full payload shape of every shipped effect, see [Effect Catalog → settle-graft](/reference/effect-catalog#settle-graft).

### Peek the registered hull

To confirm the hull registered, ask the running kernel directly. The `vesl-test` CLI (installed once via `cargo install --path test/vesl-test --locked` from your vesl-nockup checkout) sends one-shot peeks against a compiled `out.jam`:

```bash
# hull-keyed peek: did settle-graft register hull 1?
vesl-test inspect peek out.jam --path-tag settle-registered --hull 1
```

Three outcomes:

- **unrecognized** — bare `~`. The settle-graft tag isn't composed, or the path is malformed.
- **present-but-empty** — `[~ ~]`. Path recognized; no value at that hull.
- **present** — `[~ [~ value]]`. Hull is registered.

See [Testing → The CLI → inspect peek](/build/testing/cli#inspect-peek-one-shot-kernel-inspection) for the full subcommand surface, and [Peek Catalog → settle-graft](/reference/peek-catalog#settle-graft) for every shipped peek path.

### Handcraft a second poke

To go beyond the startup pair — send your own `%settle-note` cause from a test and watch a fresh `%settle-noted` effect — see [Testing → Domain Pokes](/build/testing/domain-pokes#driving-causes). That page shows the `build_settle_note_poke` builder, the harness API, and the matching peek pattern. The same shape extends to every other shipped graft.

## Where to Go Next

- [Build a Real App](/build/real-app) — compose five grafts (rbac + registry + log + settle + batch) into a license registry, end to end.
- [NockApp Anatomy](/build/anatomy) — what the hull, grafts, and your domain are doing under the hood.
- [Customizing](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#customizing) — multi-leaf gates, signed gates, STARK gates, custom domain pokes.
- [State grafts](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#state-grafts-app-state-primitives-without-writing-hoon) — `kv-graft`, `counter-graft`, `queue-graft`, `rbac-graft`, `registry-graft`.
- [`mint_lifecycle.rs`](https://github.com/zkvesl/vesl-nockup/blob/main/tools/graft-inject/tests/mint_lifecycle.rs) — Rust-native end-to-end test that mirrors the lifecycle above.

## Troubleshooting

- **`Template 'vesl' not found at <path>`** — nockup fetched the template repo via `template_git` but couldn't find `<template_path>/<template>/` inside it. Verify the `template_git`, `template_path`, and `template` fields all line up. If you're working against a branch where the template doesn't exist yet, pin `template_commit = "<sha>"` to a known-good commit. Omitting `template_git` falls back to the channel cache populated by `nockup channel update`.

- **`unknown command: graft`** — `nockup-graft` isn't on your `$PATH`. Re-run `cargo install --git ... --bin nockup-graft` and verify with `which nockup-graft`.

================================================================================
# Source: /setup/llms.md
================================================================================

# Docs for AI Agents

This documentation is published in three machine-readable forms, so an AI agent can consume the guide directly.

## llms.txt

[`/llms.txt`](/llms.txt) is the index: every page, grouped by section, with its one-line description and a link to the page as standalone markdown. An agent fetches this once to learn what the docs cover, then follows only the links a task needs.

## Per-page markdown

Every page is mirrored at its route with a `.md` extension. [`/setup/quickstart`](/setup/quickstart) is also served at [`/setup/quickstart.md`](/setup/quickstart.md). The markdown is the page source — prose, code blocks, and D2 diagram source — with the site chrome stripped. Fetching one page costs one page of context.

## llms-full.txt

[`/llms-full.txt`](/llms-full.txt) is every page concatenated into one file, in sidebar order. Use it for bulk ingestion when an agent needs the whole guide at once; prefer per-page fetches when it does not.

## Provenance

`llms.txt` and `llms-full.txt` open with a line naming the `zkvesl-docs` commit and the vesl-nockup and vesl-core revisions the pages were written against. When an agent's checkout is newer than that revision, the source repository is authoritative; treat a mismatch as a prompt to read the code.

All three artifacts regenerate on every build, so they track the published pages exactly.

================================================================================
# Source: /for-ai-agents/cookbook.md
================================================================================

# Agent Cookbook

**After reading:** you'll know which docs to fetch first, what the typed Rust SDK gives an agent over an untyped boundary, how to drive `vesl-test watch` for closed-loop feedback, and which failure modes are recoverable in-loop vs. need human review.

This page is the working companion to [Orientation](/setup/llms), which names what's published. Orientation tells you the artifacts exist; this page tells you how to use them.

## Ingestion Order

Three fetches cover most agent tasks:

- **`/llms.txt`** first. The index lists every page with a one-line description. Fetching it once tells the agent the shape of the guide.
- **Per-page `.md` mirrors** as needed. `/setup/quickstart.md`, `/build/hull.md`, etc. — fetch only what the task requires. One page costs one page of context.
- **`/llms-full.txt`** for bulk ingestion. The whole guide concatenated in sidebar order. Use when the task spans the docs surface; prefer per-page fetches otherwise.

For source-level questions, the canonical repos are linked from every page that names a primitive. SHA-pinned cross-references in the docs (e.g. `vesl-core` at `11d110d`, `vesl-nockup` at `6e2127c`) point at the exact snapshot the docs were written against. When the agent's checkout is newer, the source is authoritative.

## What the Typed Surface Gets You

The Rust SDK at the kernel boundary is typed at every seam. An agent driving it gets feedback shapes that an untyped boundary would have to discover at runtime:

- **`PokeOutcome` enum.** Every `app.poke(...)` returns one of `Accepted { effects } | Rejected { reason } | Crashed { error }`. The agent matches on the variant; an unhandled variant is a compile error, not a silent miss.
- **`assert_kernel_cause_tag!` at compile time.** With drift-detection codegen wired (see [Hull → Hull/Kernel Drift Detection](/build/hull#hull-kernel-drift-detection)), a typo in a cause tag fails `cargo build`, not at runtime as a silent `Ok(vec![])`. Wire `nockup graft codegen kernel-cause-tags` from `build.rs` to opt in.
- **Codegen-driven harness methods.** `nockup graft codegen harness-methods` generates typed `GraftTestHarness::<verb>(...)` methods from `harness-bindings.toml`. A rename in either the manifest or the binding surfaces as a codegen-time error.
- **`build_*_poke` builders.** One per cause; the canonical 14-graft surface is on [Grafts — Per-Graft Rust Snippets](/build/grafts/#per-graft-rust-snippets). Each takes typed Rust primitives and returns a `NounSlab`. The agent doesn't construct nouns by hand.

The typed surface compresses the agent's feedback loop. Where an untyped poke surfaces a problem as `Ok(vec![])` with no effects (silent), the typed shape fails `cargo build` or returns a concrete `PokeOutcome::Rejected` variant the agent can branch on.

## Closed-Loop Development

`vesl-test watch` streams effects from a running kernel, which makes for a tight read-eval-print loop:

- **Start the loop.** Boot the kernel via `cargo run`, then in a second terminal: `vesl-test watch`. The watch stream emits one line per effect.
- **Poke and observe.** Drive a poke through the hull (or via the Serve arm's HTTP routes). The watch stream prints each emitted effect as it lands.
- **Branch on the effect.** Success effects (e.g. `%settle-noted`) confirm the path. Error effects (e.g. `%settle-error msg=@t`) carry the rejection reason as a cord.
- **Iterate.** Edit Hoon, recompile, restart. State survives via PMA-resume. Boot drops from ~15s cold to ~1s warm.

For a one-shot inspection without watch, `vesl-test inspect peek <path>` returns the current value at a peek path. Full surface: [Testing / CLI](/build/testing/cli).

## Recommended File Reads Per Task

Different tasks lean on different pages. A short map:

- **"Scaffold a new nockapp."** Start at [Setup / Quickstart](/setup/quickstart). The three-command flow there scaffolds, composes, and boots a kernel.
- **"Add a new poke verb."** [Kernel / Adding a Domain Cause](/build/kernel/causes) walks state field + cause variant + arm body for a single domain cause. The denial-shape paragraph at the end is load-bearing — bare `?>` crashes the kernel where an explicit branch returns a typed rejection.
- **"Read state without a poke."** [Kernel / Adding a Domain Peek](/build/kernel/peeks) walks the `(unit (unit *))` return convention and the peek chain.
- **"Swap the verification gate."** [Kernel / Replacing a Verification Gate](/build/kernel/gates) covers the five named gates in `vesl-gates.hoon` and the `[graft.gates]` manifest line.
- **"Wire two grafts in one arm."** [Kernel / Coordinating Multiple Grafts in One Arm](/build/kernel/multi-graft) walks the `apply-<graft>` wet-gate pattern from `domain-patterns`.
- **"Run a server in production."** [Build & Run / Serve Subcommand](/build/build-run/serve) for flags, auth, and `/status` shape; [Build & Run / Production Checklist](/build/build-run/production-checklist) for the pre-ship walk.
- **"Investigate a runtime issue."** [Troubleshooting / Common Pitfalls](/troubleshooting/common-pitfalls) names every footgun in the symptom-first format: what you see, what's happening, the fix.

## Graft Selection

The 14 shipped grafts cluster by family. A short selection guide:

- **Commitment (`settle`, `mint`, `guard`, `forge`)** — pick by lifecycle. `settle` for the full register/verify/note cycle with replay protection. `mint` for one-shot root binding without verification. `guard` for hash-leaf inclusion checks. `forge` for STARK proofs over committed data.
- **State (`kv`, `counter`, `queue`, `rbac`, `registry`)** — pick by access shape. `kv` for key-value, `counter` for atomic increments, `queue` for FIFO, `rbac` for permission grants, `registry` for structured records.
- **Behavior (`validate`, `log`, `clock`, `batch`)** — pick by wrap point. `validate` for pre-`?-`-switch input rules. `log` for append-only audit. `clock` for deterministic timestamps. `batch` for settlement-flush bundling.
- **Intent (`intent-graft`)** — placeholder, no builder. Causes crash on invocation until upstream lands.

The full taxonomy with priority bands lives on [Grafts](/build/grafts/#the-5-family-graft-taxonomy). Per-graft Rust snippets — one realistic poke per graft — live on [Grafts — Per-Graft Rust Snippets](/build/grafts/#per-graft-rust-snippets).

## Common Failure Modes

A short catalog of failure shapes an agent will see, with the recovery path:

- **`Ok(vec![])` from `app.poke(...)`.** No effects came back. Likely causes: an unknown cause tag (drift detection opt-out), a kernel crash via `?>` (bare assertion on user input — see [Kernel / Causes — Denying a Cause Without Crashing](/build/kernel/causes#denying-a-cause-without-crashing)), or a `mule`-trapped panic in a graft body. Wire drift detection, refactor `?>` to `?:`/`?.` branching, and grep `vesl-test watch` output for `mote=Exit` traces.
- **Compile error `cause tag <X> not in KERNEL_CAUSE_TAGS`.** Drift detection caught a rename. Either update the hull's poke builder call site to match the kernel's renamed tag, or rerun `nockup graft codegen kernel-cause-tags` after a manifest edit. Full surface: [Hull → Hull/Kernel Drift Detection](/build/hull#hull-kernel-drift-detection).
- **`Rejected::RbacDenied` from a peek-then-poke gate.** The caller's pubkey lacks the requested permission. The peek-then-poke pattern returns a typed rejection without sending the downstream poke. Full surface: [Hull → Peek-Then-Poke Gating](/build/hull#peek-then-poke-gating).
- **`verify-jam` reports stale.** `out.jam` predates the last Hoon source edit. Re-run `./compile.sh`. The fingerprint covers both manifest TOMLs and library `.hoon` files; either surface changing triggers staleness.
- **`/health` returns 503 with `"stage":"booting"`.** The hull hasn't finished kernel boot. Cold boot is ~15s; PMA-resume is ~1s. Wait or wire `readinessProbe` to the 200.

Failure modes with `error:` prefix from `nockup graft inject --apply` are gating lints — they refuse the write. Each one names a silent-fail surface in the composer or hoonc. See [Inject Lints](/build/grafts/inject/lints) for the per-lint shape.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

::: info See Also

- [Orientation](/setup/llms) — what's published in machine-readable form.
- [Grafts — Per-Graft Rust Snippets](/build/grafts/#per-graft-rust-snippets) — one canonical poke per graft.
- [Hull](/build/hull) — typed Rust surface, drift detection, peek-then-poke gating.
- [Testing / CLI](/build/testing/cli) — `vesl-test watch` for closed-loop feedback.
- [Common Pitfalls](/troubleshooting/common-pitfalls) — symptom-first failure mode catalog.

:::

================================================================================
# Source: /build/anatomy.md
================================================================================

# NockApp Anatomy

A nockapp is a compiled Hoon kernel (`out.jam`) booted inside a Rust hull. vesl supplies most of the kernel as a graft library and gives you a CLI that splices those grafts into the source you compile.

::: info Before We Start

Two kinds of message flow between the hull and the kernel:

- **Poke** — a write. The hull sends a tagged command (called a *cause*); the kernel may update state and emits a list of *effects* (events) back. The closest Rust analog is a method on `&mut self`.
- **Peek** — a read. The hull queries kernel state at a path; the kernel returns the value (or `~` for none) without modifying anything. The closest Rust analog is a method on `&self`.

A poke is how you *do* something to the kernel; a peek is how you *ask* it something.

Inside the kernel, one Hoon-specific term:

- **Gate** — a Hoon function. A *verification gate* takes a payload and returns true or false — the kernel uses gates to decide whether to accept something (e.g. "does this proof verify against this Merkle root?").

The rest of this page (and most of the rest of the guide) uses these words constantly.

:::

## Anatomy

```d2
direction: down

rust: Rust {
  hull: "Hull\n(your src/main.rs)"
  core: "vesl-core\npoke builders, Mint, Guard"
  hull -> core
}

hoon: "Hoon (compiled into out.jam)" {
  grafts: "Grafts\ncommitment, state, behavior"
  domain: "Your domain\ncauses, peeks, verification gates"
}

rust.hull -> hoon: "boot, poke, peek"
```

Your hull (`src/main.rs`) is the Rust binary that hosts the kernel. It imports `vesl-core` for `Mint`, `Guard`, and a poke builder per graft operation, boots the compiled kernel via `nockapp::kernel::boot::setup`, and shuttles pokes and peeks across the Rust-to-Hoon boundary. Inside the kernel sit the grafts — Hoon libraries installed into `hoon/lib/` and composed in at the `::  nockup:*` marker comments — and your domain: the cause tags, peek paths, and verification gates you write between those markers. The domain is where your app logic lives — if the grafts are the contract, the domain is the app.

## The Hull

The hull is the Rust process that hosts the kernel. It boots the compiled JAM as an embedded `NockApp`, routes inbound requests into pokes and peeks, and surfaces effects back to the caller. The kernel is pure logic; the hull does the I/O — HTTP, the chain client, the filesystem, persistent checkpoints.

In a vesl nockapp, the hull is whatever your `src/main.rs` builds with `nockapp::kernel::boot::setup`. The [Hull](/build/hull) page covers the canonical shape; for a thin reference harness, [vesl-core](https://github.com/zkvesl/vesl-core) ships a `hull/` template with kernel boot and `/commit` / `/verify` endpoints — fork it when you want a generic process around a vesl kernel.

## Grafts

Grafts are pre-written Hoon libraries that ship as `<name>-graft.hoon` plus a sibling `<name>-graft.toml` manifest. Each manifest declares blocks of Hoon code keyed to specific marker comments — imports, state fields, cause-union variants, poke arms, peek arms, effect variants. `nockup graft inject` discovers manifests under `hoon/lib/`, splices their blocks into your `app.hoon` at the markers, and writes the result.

Fourteen grafts ship today across four families plus a placeholder. [Grafts](/build/grafts/#the-5-family-graft-taxonomy) covers the canonical taxonomy: member grafts, priority bands, and family roles.

## Your Domain

Concretely, your domain is the application-specific Hoon you write into the marker slots — usually dozens of lines, not hundreds. Imagine a simple licensing app: a publisher commits to a Merkle root over a set of license IDs, and buyers later prove they hold one. The grafts do the cryptography (Merkle math, root registration, proof verification); your domain is what's left. Each piece lands at a specific marker in `app.hoon`:

```hoon
::  nockup:cause — declare a new poke variant
[%issue-license id=@ buyer=@]

::  nockup:domain-effect — declare what the kernel emits in response
[%license-issued id=@ buyer=@]

::  nockup:poke — handle the cause, mutate state, emit the effect
%issue-license
  :_  state(licenses (~(put by licenses.state) buyer.u.act id.u.act))
  ~[[%license-issued id.u.act buyer.u.act]]

::  nockup:peek — return licenses for a buyer
[%licenses-of buyer=@ ~]  ``(~(get by licenses.state) buyer)
```

You can also swap the default hash-comparison verification gate for a signature check or STARK gate by setting `[graft.gates]` in a graft manifest — that lives in a `.toml` rather than at a marker.

Anything that involves network I/O, disk persistence, environment variables, or external APIs stays in the hull. The kernel is pure logic; your domain is the small slice of that logic that's specific to your app.

More on this in [Kernel](/build/kernel/), which walks each domain pattern in detail.

## Manifest Anatomy

A graft's manifest catalogs metadata, types, and the code blocks `nockup graft inject` splices into your kernel:

```
manifest: <name>-graft.toml
├── [graft]                metadata: name · version · priority · after
├── [graft.types]          cause-type name · effect-type name
└── [graft.blocks.*]       Hoon code keyed to kernel markers
    ├── imports            → nockup:imports
    ├── state              → nockup:state
    ├── cause              → nockup:cause
    ├── peek               → nockup:peek
    ├── poke               → nockup:poke           (≥1 arms; one per cause-tag)
    ├── poke-prelude       → nockup:poke-prelude   (validate-graft only today)
    └── poke-postlude      → nockup:poke-postlude  (no shipped graft populates yet)
```

Each `[graft.blocks.*]` table carries a `sentinel` (a documentation marker) and a `body` (the Hoon to splice). The next section catalogs where each block lands in `app.hoon`.

## Anchor Markers

`templates/app.hoon` ships with ten `::  nockup:*` anchor comments at fixed structural points. They mark the slots where `nockup graft inject` splices Hoon: seven are **content markers** that hold per-graft bodies; three are **codegen markers** the composer writes itself.

Content markers — per-graft contributions stack here:

| Marker | Purpose |
|---|---|
| `nockup:imports` | `/+` and `/=` lines that pull each graft's Hoon library into scope. |
| `nockup:state` | Per-graft state fragments inside `+$ versioned-state`. Each graft adds the field that holds its state. |
| `nockup:cause` | Cause-tag variants each graft adds to the `+$ cause $%` union (one variant per poke verb the graft handles). |
| `nockup:peek` | `++ peek` arms each graft contributes. Arms join into a single peek chain across grafts. |
| `nockup:poke-prelude` | Pre-flight checks that run before the cause switch. `validate-graft`'s prelude short-circuits rule-violating causes here. |
| `nockup:poke` | The `?-` arms each graft adds to the cause switch — one arm per cause-tag the graft handles. |
| `nockup:poke-postlude` | Post-`?-` slot where a graft can rebind the switch's `[(list effect) state]` result before the gate returns. No shipped graft populates this marker today; the slot, schema, and integration tests landed in advance of the first consumer. |

Codegen markers — the composer rewrites these on every `--apply`:

| Marker | Purpose |
|---|---|
| `nockup:domain-effect` | Your app's effect variants live below this marker as `+$ domain-effect $%(...)`. The composer reads them and merges them with each graft's effects in `nockup:effect-union`. |
| `nockup:effect-union` | Below this marker, the composer writes the typed `+$ effect $%(...)` union welding your `domain-effect` variants with each graft's effect type. The kernel's `++ poke` arm returns values of this union. |
| `nockup:load-defaults` | Below this marker, the composer writes a state-shape migration overlay used inside `++ load`. Resumed snapshots get default values at any state axes the new kernel added since the snapshot was taken. |

Multiple grafts can contribute to the same content marker; their bodies stack at that slot. Composition controls (how to narrow the graft set, what `--apply` does) live in [Inject](/build/grafts/inject); the full manifest schema is in [Manifest Schema](/build/grafts/manifest-schema).

::: tip Composing across grafts
When a domain cause needs to commit a Merkle root over another graft's state — the `%snapshot-root` shape, common in Profile G/J compositions — see [vesl-core → Committing Over Graft State](/reference/vesl-core#committing-over-graft-state). When one cause needs to drive multiple grafts in one arm, see [Kernel → Coordinating Multiple Grafts in One Arm](/build/kernel/multi-graft).
:::

## How They Compose

```
my-app/
├── Cargo.toml          # path deps + [patch] blocks
├── build.rs            # runs nockup graft doctor each build
├── src/main.rs         # your hull
├── hoon/
│   ├── app/app.hoon    # marker template + grafts + your domain
│   ├── lib/            # graft libraries (.hoon + .toml manifests)
│   └── common/         # shared libs (zeke.hoon, ztd/, ...)
└── out.jam             # compiled kernel (after hoonc)
```

`nockup graft inject --apply hoon/app/app.hoon` splices graft blocks into the source file at the markers; `hoonc` compiles the result to `out.jam`; the hull loads it via `boot::setup`. The CLI is preview-by-default (the supply-chain guardrail described in [Inject](/build/grafts/inject)); nothing lands on disk until you pass `--apply`.

## What's Deterministic and Why

Nock is [nockchain](https://github.com/nockchain/nockchain)'s combinator calculus, JAM is its serialization format, and the deterministic interpreter that gives a kernel exactly one possible output for any given input is part of the nockchain runtime. STARK proving (used by `forge-graft`) is also nockchain's stack — `vesl-prover.hoon` and the constraint tables under `hoon/dat/` ride on the upstream prover. vesl runs a Hoon kernel inside the nockchain `NockApp` and ships a graft library and a CLI on top: it does not invent determinism, proving, or the noun model.

The vesl-core entry types (`Mint`, `Guard`, the four primitives) are documented at [`crates/vesl-core/src/lib.rs#L1-L40`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/lib.rs#L1-L40); start there if you want to read source.

================================================================================
# Source: /build/real-app.md
================================================================================

# Build a Real App

The [quickstart](/setup/quickstart) gets you three commands from an empty directory to `%settle-noted`. This page goes further: composing five grafts into a working license registry, end to end, in one running kernel. The graft set, the cause arms, the Rust hull, the HTTP surface, and the test harness all sit in the same project the quickstart scaffolds.

## The Problem

A license registry is a small but realistic verifiable app. The service needs to:

- Issue licenses, gated on admin signing keys.
- Suspend, revoke, and renew them.
- Record every state change in an audit trail.
- Commit each license to a Merkle root so the registry's history can be proven against a single hash.
- Flush settlements in batches so a burst of issuance doesn't fragment the chain commitment.

Five concerns, five grafts.

## Grafts Chosen

| Graft | Family | Priority | Role |
|---|---|---|---|
| `rbac-graft` | state | 80 | Track admin pubkeys and the permissions granted to each. |
| `registry-graft` | state | 90 | Strict per-license rows: put, update, delete. |
| `log-graft` | behavior | 130 | Append-only audit trail keyed by event tag. |
| `settle-graft` | commitment | 10 | Merkle-rooted attestation of issued licenses. |
| `batch-graft` | behavior | 145 | Buffer settle causes and flush them in batches. |

Inject composes manifests in priority order; the resulting `?-` switch dispatches cause-tag by cause-tag. The lower priority runs earlier, so settle-graft's poke arms (priority 10) splice in first, then state grafts, then behavior grafts.

```d2
direction: down

markers: {
  direction: right
  cause:  "::  nockup:cause"
  state:  "::  nockup:state"
  poke:   "::  nockup:poke"
  peek:   "::  nockup:peek"
}

settle:   "settle-graft\ncommitment · prio 10"
rbac:     "rbac-graft\nstate · prio 80"
registry: "registry-graft\nstate · prio 90"
log:      "log-graft\nbehavior · prio 130"
batch:    "batch-graft\nbehavior · prio 145"

settle -> markers.cause: { style.stroke: "#c084fc"; style.stroke-width: 2 }
settle -> markers.state: { style.stroke: "#c084fc"; style.stroke-width: 2 }
settle -> markers.poke:  { style.stroke: "#c084fc"; style.stroke-width: 2 }
settle -> markers.peek:  { style.stroke: "#c084fc"; style.stroke-width: 2 }

rbac -> markers.cause: { style.stroke: "#60a5fa"; style.stroke-width: 2 }
rbac -> markers.state: { style.stroke: "#60a5fa"; style.stroke-width: 2 }
rbac -> markers.poke:  { style.stroke: "#60a5fa"; style.stroke-width: 2 }
rbac -> markers.peek:  { style.stroke: "#60a5fa"; style.stroke-width: 2 }

registry -> markers.cause: { style.stroke: "#60a5fa"; style.stroke-width: 2 }
registry -> markers.state: { style.stroke: "#60a5fa"; style.stroke-width: 2 }
registry -> markers.poke:  { style.stroke: "#60a5fa"; style.stroke-width: 2 }
registry -> markers.peek:  { style.stroke: "#60a5fa"; style.stroke-width: 2 }

log -> markers.cause: { style.stroke: "#fb923c"; style.stroke-width: 2 }
log -> markers.state: { style.stroke: "#fb923c"; style.stroke-width: 2 }
log -> markers.poke:  { style.stroke: "#fb923c"; style.stroke-width: 2 }
log -> markers.peek:  { style.stroke: "#fb923c"; style.stroke-width: 2 }

batch -> markers.cause: { style.stroke: "#fb923c"; style.stroke-width: 2 }
batch -> markers.state: { style.stroke: "#fb923c"; style.stroke-width: 2 }
batch -> markers.poke:  { style.stroke: "#fb923c"; style.stroke-width: 2 }
```

Each graft contributes to four of the ten markers (cause, state, poke, peek); batch-graft skips peek. Edge color marks family — purple for commitment (settle), blue for state (rbac, registry), orange for behavior (log, batch). The cause-tag union grows by the sum of contributions; the `?-` switch grows the same way; the state record gets one field per graft. [Why splicing, not import](/build/grafts/#why-splicing-not-import) covers the mechanic.

## Manifest

The project's `nockapp.toml` declares the dep — same shape as the quickstart:

```toml
# Example: nockapp.toml — top-level project manifest
[package]
name         = "license-registry"
version      = "0.1.0"
description  = "verifiable license registry"
template     = "vesl"
template_git = "https://github.com/zkvesl/vesl-nockup"
template_path = "templates"

[dependencies]
"zkvesl/vesl-graft" = "latest"
```

`nockup project init` pulls the full graft library into `hoon/lib/`. Graft selection happens at inject time, not in the manifest.

## Kernel Composition

The vesl template ships `hoon/app/app.hoon` with the ten marker comments at their structural positions. The `--grafts` flag narrows the composer to the five names the registry uses:

```bash
# Example: filter inject to the five grafts the registry needs
nockup graft inject --grafts rbac,registry,log,settle,batch hoon/app/app.hoon            # preview
nockup graft inject --grafts rbac,registry,log,settle,batch --apply hoon/app/app.hoon    # write
```

Without `--grafts`, every manifest under `hoon/lib/` composes (the 14-graft kernel the quickstart uses). With it, only the five names land. The splice is leaner, the kernel boots faster, and `/status` reports exactly those five.

The first lines of the assembled `app.hoon` after `--apply`:

```hoon
:: Example: hoon/app/app.hoon (composed, abridged) — first ~20 lines after inject
::  Composed by nockup graft inject — do not hand-edit between banners.
::
/+  lib
::  graft-inject:imports:settle-graft:begin:f1b2c8e4
/+  *settle-graft
/+  *vesl-merkle
::  graft-inject:imports:settle-graft:end
::  graft-inject:imports:rbac-graft:begin:8d3a7c2e
/+  *rbac-graft
::  graft-inject:imports:rbac-graft:end
::  ... (registry, log, batch imports follow)
::
=>
|%
+$  versioned-state
  $:  %v1
  ::  graft-inject:state:settle-graft:begin:f1b2c8e4
      settle=settle-state
  ::  graft-inject:state:settle-graft:end
  ::  graft-inject:state:rbac-graft:begin:8d3a7c2e
      rbac=rbac-state
  ::  ... (registry, log, batch state fields follow)
  ==
```

Banner pairs (`begin:<sha>` / `end`) wrap every contribution; the sha is the manifest sha256 reported on `/status`. A `git diff` shows exactly which graft added which lines. See [Inject](/build/grafts/inject) for the marker model and lint families.

## Hoon Cause Arms

The registry's five domain causes go into the `::  nockup:cause` marker. The poke switch arms go into `::  nockup:poke`. Each arm threads through one or more grafts in the order their priorities imply.

```hoon
:: Example: hoon/app/app.hoon — domain cause variants (above the ::  nockup:cause marker)
[%license-issue admin=@ key=@uw expires=@da]
[%license-revoke admin=@ key=@uw reason=@t]
[%license-suspend admin=@ key=@uw until=@da]
[%license-renew admin=@ key=@uw new-expires=@da]
[%license-flush admin=@]
```

The `%license-issue` arm runs the rbac check, the registry put, a log append, and a batch-buffered settle in one cause:

```hoon
:: Example: hoon/app/app.hoon — %license-issue arm (in the ?- switch, above ::  nockup:poke)
%license-issue
?>  (~(has by perms.rbac.state) admin.u.act)
=/  payload  (jam [key=key.u.act expires=expires.u.act status=%active])
=^  reg-efx  registry.state
  (registry-poke registry.state [%registry-put key.u.act payload])
=^  log-efx  log.state
  (log-poke log.state [%log-append %license-issued payload])
=^  batch-efx  batch.state
  (batch-poke batch.state [%batch-add (jam [hull=1 root=*@ data=payload])])
:_  state
:(welp reg-efx log-efx batch-efx)
```

Five lines of orchestration on top of four graft calls. The full set of arms (issue, revoke, suspend, renew, flush) fits in roughly 25 lines of Hoon. [Multi-Graft Coordination](/build/kernel/multi-graft) covers the `=^` threading pattern and effect aggregation.

## Rust Hull

Each domain cause gets a typed `build_<verb>_poke` from the codegen the manifest declares. The hull binds them to HTTP routes via `serve_with_extra_routes`:

```rust
// Example: src/main.rs — Serve arm with custom routes
use axum::{routing::{post, get}, Router, Json, extract::{State, Path}};
use vesl_core::{PokeOutcome, SystemWire};
use license_registry::pokes::{
    build_license_issue_poke, build_license_revoke_poke,
    build_license_suspend_poke, build_license_renew_poke,
    build_license_flush_poke,
};

#[derive(serde::Deserialize)]
struct IssueRequest { admin: String, key: u64, expires_days: u32 }

#[derive(serde::Serialize)]
struct IssueResponse { license_id: u64, settled: bool }

async fn handle_issue(
    State(state): State<SharedState>,
    Json(req): Json<IssueRequest>,
) -> Result<Json<IssueResponse>, ApiError> {
    let poke = build_license_issue_poke(
        &req.admin,
        req.key,
        days_to_da(req.expires_days),
    );
    let outcome = state.app.lock().await
        .poke(SystemWire.to_wire(), poke).await?;
    match outcome {
        PokeOutcome::Accepted { effects } => {
            let settled = effects.iter().any(|e| e.head_tag() == "settle-noted");
            Ok(Json(IssueResponse { license_id: req.key, settled }))
        }
        PokeOutcome::Rejected { reason } => Err(ApiError::rejected(reason)),
        PokeOutcome::Crashed { error }   => Err(ApiError::crashed(error)),
    }
}

pub async fn run(state: SharedState, port: u16, bind: &str) -> anyhow::Result<()> {
    let extra: Router<SharedState> = Router::new()
        .route("/license/issue",   post(handle_issue))
        .route("/license/revoke",  post(handle_revoke))
        .route("/license/suspend", post(handle_suspend))
        .route("/license/renew",   post(handle_renew))
        .route("/license/flush",   post(handle_flush))
        .route("/license/:id",     get(handle_query));
    vesl_hull::serve_with_extra_routes(state, port, bind, extra).await?;
    Ok(())
}
```

`build_license_issue_poke` is generated by per-graft codegen; its signature comes from the `[graft.types].cause` declaration in `domain-graft.toml`. The other five handlers follow the same shape. [Composing Custom Routes](/build/build-run/serve#composing-custom-routes) covers the auth, body-limit, and rate-limit layers that wrap every route uniformly.

## Tests

The harness boots the same `out.jam` your hull does. Per-graft methods (`harness.rbac_grant`, `harness.license_issue`) come from the codegen that walks each manifest's cause types:

```rust
// Example: tests/license_registry.rs — happy-path issue + query
use vesl_test::Harness;

#[tokio::test]
async fn issue_then_query_returns_active_license() {
    let mut h = Harness::boot("out.jam").await;
    let admin = "admin-pubkey-1";

    h.rbac_grant(admin, vec!["license-admin"]).await.expect("grant");

    let outcome = h.license_issue(admin, 100, days(365)).await;
    assert!(matches!(outcome, PokeOutcome::Accepted { .. }));

    let row = h.peek_license(100).await.expect("license found");
    assert_eq!(row.status, LicenseStatus::Active);
}
```

Twelve assertions cover the surface:

- **Happy path (5):** issue, query, revoke, suspend, renew each succeed against an admin-granted key.
- **Rejection (5):** non-admin issuer (rbac denies), double-revoke (registry update on revoked row), query-missing (peek returns `~`), expired renew (new-expires earlier than current), flush with empty buffer.
- **Cross-graft (2):** `%license-issue` triggers `%log-appended`; the Nth `%license-issue` after the batch threshold triggers `%settle-noted`.

[Rust Harness](/build/testing/harness) covers the binding model. [Domain Pokes](/build/testing/domain-pokes) walks the typed builder a domain cause gets generated.

## HTTP Routes

Issue a license over HTTP:

```bash
# Example: issue one license against a running hull
curl -X POST -H "Authorization: Bearer $HULL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"admin":"admin-pubkey-1","key":100,"expires_days":365}' \
     http://localhost:3000/license/issue
```

```json
{
  "license_id": 100,
  "settled": false
}
```

`settled: false` means the issue landed in the batch buffer without flushing. Once enough issues bring the buffer to its threshold (or `POST /license/flush` is called), the batch drains and settle-graft commits a Merkle root over the batched payloads. `GET /license/100` returns the row regardless of whether the underlying batch has flushed yet.

## /status Verification

A `GET /status` after one issue + one revoke + one flush:

```json
{
  "has_tree": true,
  "field_count": 1,
  "merkle_root": "3p7q1r4u8v2w6x0y5z9a3b7c1d4e8f2g…",
  "notes_settled": 1,
  "hull_id": 1,
  "settlement_mode": "in-process",
  "gate": "default-hash",
  "grafts": [
    "batch-graft", "log-graft", "rbac-graft",
    "registry-graft", "settle-graft"
  ],
  "manifest_shas": {
    "batch-graft":    "8f3e2a1c…",
    "log-graft":      "3b7f4e8c…",
    "rbac-graft":     "8d3a7c2e…",
    "registry-graft": "f7b2e4a9…",
    "settle-graft":   "f1b2c8e4…"
  }
}
```

Five grafts in the `grafts` array (sorted), five matching `manifest_shas` entries, one note settled, one field in the Merkle tree. The same payload doubles as a runtime sanity check during deployment — a mismatched sha against the on-disk manifest means the running hull is out of date.

## What You Got

- **5 verifiable primitives composed** via `nockup graft inject --grafts ...`.
- **~25 lines of Hoon** for the five domain cause arms.
- **~80 lines of Rust** for the six HTTP handlers.
- **6 custom HTTP routes** wired via `serve_with_extra_routes`, inheriting auth + body-limit + rate-limit from `vesl-hull`.
- **12 harness assertions** running against the real compiled kernel.
- **One `/status` payload** that proves what's running.

The same recipe scales: swap rbac-graft for a stricter gate, replace registry-graft with kv-graft for looser storage, drop log-graft if you don't need an audit trail. Each graft is a substitution; the domain cause arms stay shaped the same way.

For the underlying mechanic, see [NockApp Anatomy](/build/anatomy). For the per-graft surface, [Grafts](/build/grafts/). For deeper coordination patterns, [Multi-Graft Coordination](/build/kernel/multi-graft).

================================================================================
# Source: /build/grafts/index.md
================================================================================

# Grafts

**After reading:** you'll have vesl-graft installed, know which file landed where, and recognize the 5-family taxonomy when reading manifests.

A graft is a Hoon library plus a TOML manifest that `nockup graft inject` splices into your kernel. This page covers installing the published graft catalog and mapping the 5-family taxonomy. Wiring a graft into `app.hoon` lives on [Inject](/build/grafts/inject); manual fallback paths for non-canonical setup live at the bottom.

## Anatomy of a Graft

The manifest carries metadata and code blocks; the library carries the types and helper gates those blocks call into.

```
graft
├── manifest: <name>-graft.toml
│   ├── [graft]                  name · version · priority · after
│   ├── [graft.types]            cause-type · effect-type
│   └── [graft.blocks.*]         Hoon spliced at kernel markers
│       ├── imports              /+ lines pulling the library into scope
│       ├── state                one field on versioned-state
│       ├── cause                one variant on the cause $% union
│       ├── peek                 one arm chained into the peek dispatch
│       ├── poke                 ≥1 arms in the ?- switch
│       │   └── arm              one per cause-tag the graft handles
│       │       ├── tag          %settle-register
│       │       ├── reads        cause fields off u.act
│       │       ├── reads/writes its own state field
│       │       ├── gate         swappable verify-gate (optional; commitment grafts)
│       │       ├── calls        the library's <name>-poke entrypoint
│       │       └── returns      [(list effect) new-state]
│       ├── poke-prelude         pre-?- short-circuit (validate-graft only)
│       └── poke-postlude        post-?- result transform (no shipped graft yet)
└── library: <name>-graft.hoon   state shape, types, poke/peek gates
```

Across the fourteen shipped grafts, the `poke` block carries one to four arms (most have two or three; `clock-graft`, `forge-graft`, `log-graft`, and `mint-graft` each have one). The arm shape stays consistent across all of them, and [Adding a Domain Cause](/build/kernel/causes) walks the same shape for a domain cause you write yourself.

## Why Splicing, Not Import

A Hoon kernel is a single `app.hoon` file. Hoon has no linking step; the cause-tag union, the `?-` switch, and the state record all live in one source file, and the type system checks them as a unit. Importing a graft as a module would still leave you hand-assembling those three structures from the imported pieces.

`nockup graft inject` does the composition for you. It discovers manifests under `hoon/lib/`, gathers per-marker bodies in priority order, and assembles the new `app.hoon`. By default the command is preview-only: it prints what would change and exits without touching disk. `--apply` opts in to writing the result. The on-disk Hoon stays auditable; every contribution lives between named banner comments, so a `git diff` shows exactly what each graft added.

Preview-by-default keeps the trust boundary explicit: a compromised `hoon/lib/` would otherwise splice hostile bodies before you saw them. Inspect, then write.

## Install the Package

If you scaffolded from the [quickstart](/setup/quickstart), vesl-graft is already installed — `nockup project init` saw it declared in your `nockapp.toml`'s `[dependencies]` block and pulled it in automatically. Skip ahead to [Verify the install](#verify-the-install).

If you're adding vesl to an **existing** nockapp project that doesn't yet declare the dep, add it now:

```bash
nockup package add zkvesl/vesl-graft -v latest
nockup package install
```

`-v latest` is required; nockup refuses a bare `add` without a version spec. Run `nockup package install` from the **parent** of the project dir, not from inside it (`nockup package install` walks `./<package-name>/` and errors `Project directory '<package-name>' not found` if you run it from within the project).

If you'd like the kernel file named something other than `app.hoon` to match your project domain:

```bash
nockup graft rename-kernel <new-name> --apply
```

Add `--apply` to do the rename — without it, you just see what would change. The command updates the kernel file, `nockapp.toml`, and the build commands in your README in one pass.

## What Lands on Disk

```
my-app/hoon/
├── lib/                          # graft libraries + manifests
│   ├── settle-graft.hoon
│   ├── settle-graft.toml
│   ├── mint-graft.hoon
│   ├── mint-graft.toml
│   ├── guard-graft.hoon
│   ├── guard-graft.toml
│   ├── forge-graft.hoon          # plus vesl-prover.hoon, vesl-lower.hoon
│   ├── forge-graft.toml
│   ├── ...                       # state + behavior grafts (kv, counter, queue, rbac, registry, validate, log, clock, batch)
│   └── vesl-merkle.hoon          # tip5 Merkle primitives
└── common/
    ├── zeke.hoon                 # tip5 hash chain
    └── ztd/                      # tip5 math tables (8 files)
```

`forge-graft` additionally pulls in the STARK prover tree (`hoon/common/v0-v1/`, `v2/`, `stark/`, plus `hoon/dat/softed-constraints.hoon` and the pre-jammed constraint tables under `hoon/jams/`).

## Verify the Install

`nockup package install` silently skips dependencies it can't resolve, so a clean `✓ No dependencies to install` does not mean vesl landed. Check the expected files are on disk:

```bash
ls hoon/lib/settle-graft.hoon hoon/lib/settle-graft.toml hoon/lib/vesl-merkle.hoon
```

If any of those three paths are missing, the registry didn't resolve `zkvesl/vesl-graft` — see [Fallback paths](#fallback-paths) below.

## If Your `app.hoon` Already Has Work in It

If you scaffolded from a non-vesl template and started writing causes, peeks, or state before reading this page, take one of these paths to add the markers without losing your work:

**Template-overlay (easier).** Copy `templates/vesl/hoon/app/app.hoon` over your file, then move your existing causes, peeks, and state into the marker slots. The template is 89 lines — the diff is mostly cut-and-paste, and the marker positions are already correct.

**Annotate-in-place (surgical).** Add the ten `::  nockup:*` comments at the structural points below. A marker comment is `::` followed by one or more spaces, then `nockup:<name>`; the templates use two spaces as the canonical form.

| Marker | Position |
|---|---|
| `::  nockup:imports` | Between the `/+` and `/=` import lines at the top of the file |
| `::  nockup:state` | Inside `+$ versioned-state`'s `$:` block, after the `%vN` version tag |
| `::  nockup:domain-effect` | Above your `+$ domain-effect $%(...)` declaration |
| `::  nockup:effect-union` | Above the typed `+$ effect` union (codegen rewrites the line below) |
| `::  nockup:cause` | Inside `+$ cause`'s `$%` union, after your existing variants |
| `::  nockup:load-defaults` | Inside `++ load`, on the line above the fall-through that returns `old-state` |
| `::  nockup:peek` | Inside `++ peek`, on the line above the fall-through `~` |
| `::  nockup:poke-prelude` | Immediately before the `?-` poke switch |
| `::  nockup:poke` | Inside the `?-` poke switch, on its own line above the closing `==` |
| `::  nockup:poke-postlude` | Immediately after the `?-` switch's enclosing block |

A marker no active graft needs is skipped. But if an active graft contributes a block for an absent marker, `nockup graft inject` stops with a nonzero exit — the block has nowhere to land and would otherwise be silently dropped. Add the missing markers, then re-run. One special case is auto-migrated: a bare `+$ effect *` in source is rewritten on the same `--apply` pass into the `nockup:domain-effect` + `nockup:effect-union` shape, so kernels that already have the bare effect don't need to add those two markers by hand.

## The 5-Family Graft Taxonomy

| # | Family | Priority band | Members | Role |
|---|---|---|---|---|
| 1 | Commitment | 10–40 | `settle`, `mint`, `guard`, `forge` | Hull-keyed Merkle roots, payload verification, replay-protected settlement, STARK proofs. |
| 2 | Verification gates | library (selectable) | `vesl-gates.hoon` | Named gate arms consumed by commitment grafts via `[graft.gates]`. Ships ed25519, Schnorr, manifest, set-membership, bounded-value. |
| 3 | State | 50–99 | `kv`, `counter`, `queue`, `rbac`, `registry` | Domain-keyed app-state primitives. |
| 4 | Behavior | 100–149 | `validate`, `log`, `clock`, `batch` | Runtime wrappers and observers (pre-flight rules, audit trail, deterministic clock, settlement-flush buffer). |
| 5 | Intent | 200–299 | `intent-graft` (placeholder) | Reserved for multi-party coordination; crashes on invocation until upstream lands. |

Commitment grafts share a unified `hull=@` key — `mint`, `guard`, and `settle` can address the same logical cell across primitives. State grafts are **domain-keyed**, so they layer alongside commitments without namespace collision. Behavior grafts wrap or observe poke flow via the `poke-prelude` and `poke-postlude` markers; `validate-graft`'s prelude short-circuits before the cause switch runs.

Splitting commitments across multiple `hull=@` keys for per-tenant, per-version, or per-period isolation is [the trellis pattern](/build/grafts/trellis-pattern).

The full schema (manifest fields, per-marker block keys, gate selection, the priority lattice in detail) lives on [Grafts / Manifest Schema](/build/grafts/manifest-schema).

## Per-Graft Rust Snippets

One typical poke per graft, in family order. Each snippet calls the canonical `build_*_poke` builder shipped in [`vesl-core`](https://github.com/zkvesl/vesl-core/tree/11d110d/crates/vesl-core/src/graft_pokes); the `_from_noun` variants and signature alternates live alongside.

### Commitment

```rust
// crates/vesl-core/src/graft_pokes/settle.rs
use vesl_core::{Mint, build_settle_register_poke};
let mut mint = Mint::new();
let root = mint.commit(&[b"first-license"]);
let slab = build_settle_register_poke(1, &root);
```

```rust
// crates/vesl-core/src/graft_pokes/mint.rs
use vesl_core::{Mint, build_mint_commit_poke};
let mut mint = Mint::new();
let root = mint.commit(&[b"asset-1"]);
let slab = build_mint_commit_poke(1, &root);
```

```rust
// crates/vesl-core/src/graft_pokes/guard.rs
use vesl_core::{Mint, build_guard_register_poke, build_guard_check_poke};
let mut mint = Mint::new();
let root = mint.commit(&[b"member-a"]);
let register = build_guard_register_poke(1, &root);
let check    = build_guard_check_poke(1, b"member-a");
```

```rust
// crates/vesl-core/src/graft_pokes/forge.rs
use vesl_core::build_forge_prove_poke;
let slab = build_forge_prove_poke(/*hull=*/ 1, /*note_id=*/ 42, b"payload-bytes");
```

### State

```rust
// crates/vesl-core/src/graft_pokes/kv.rs
use vesl_core::{build_kv_set_poke, build_kv_delete_poke};
let set = build_kv_set_poke("user:123", b"alice@example.com");
let del = build_kv_delete_poke("user:123");
```

```rust
// crates/vesl-core/src/graft_pokes/counter.rs
use vesl_core::{build_counter_increment_poke, build_counter_set_poke};
let inc = build_counter_increment_poke("page-views");
let set = build_counter_set_poke("page-views", 0);
```

```rust
// crates/vesl-core/src/graft_pokes/queue.rs
use vesl_core::{build_queue_push_poke, build_queue_pop_poke};
let push = build_queue_push_poke(b"job-payload-jammed");
let pop  = build_queue_pop_poke();
```

```rust
// crates/vesl-core/src/graft_pokes/rbac.rs
use vesl_core::{build_rbac_grant_poke, build_rbac_revoke_poke};
let grant  = build_rbac_grant_poke(/*pubkey=*/ 0xCAFE_BABE, &["registry-put"]);
let revoke = build_rbac_revoke_poke(0xCAFE_BABE, &["registry-put"]);
```

```rust
// crates/vesl-core/src/graft_pokes/registry.rs
use vesl_core::{build_registry_put_poke, build_registry_del_poke};
let put = build_registry_put_poke(/*key=*/ 1, /*record_jammed=*/ &record);
let del = build_registry_del_poke(1);
```

### Behavior

```rust
// crates/vesl-core/src/graft_pokes/validate.rs
use vesl_core::{build_validate_init_poke, Rule};
let rules = &[Rule::NonEmpty];
let slab  = build_validate_init_poke("issue-license", rules);
```

```rust
// crates/vesl-core/src/graft_pokes/log.rs
use vesl_core::build_log_append_poke;
let slab = build_log_append_poke("audit", b"issued license to user 42");
```

```rust
// crates/vesl-core/src/graft_pokes/clock.rs
use vesl_core::build_clock_tick_poke;
let slab = build_clock_tick_poke();
```

```rust
// crates/vesl-core/src/graft_pokes/batch.rs
use vesl_core::{build_batch_init_poke, build_batch_add_poke, build_batch_flush_poke};
let init  = build_batch_init_poke(/*threshold=*/ 100);
let add   = build_batch_add_poke(b"intent-jammed");
let flush = build_batch_flush_poke();
```

### Intent

```rust
// Example: intent-graft is a placeholder — no Rust builder ships today.
// Causes routed through it crash on invocation until upstream lands.
```

## Fallback Paths

If you scaffolded from upstream nockup's `basic` template (or any other non-vesl template), your `hoon/app/app.hoon` lacks the ten `::  nockup:*` markers `nockup graft inject` wires against. `nockup project init` with `template = "vesl"` produces them automatically; this `cp` is the manual equivalent:

```bash
cp <vesl-nockup>/templates/vesl/hoon/app/app.hoon hoon/app/app.hoon
```

The marker template is the same minimal kernel as the basic scaffold's `app.hoon`, with the markers pre-placed at the right structural points. Do not edit `app.hoon` back to the basic shape afterwards — keep the markers.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

::: info See Also

- [vesl-nockup README — Step 2](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#step-2--install-the-vesl-graft-packages) — install the vesl-graft package via nockup.
- [Reference / Library catalog](/reference/library) — per-graft one-liners and links to source for every shipped graft, support Hoon library, and Rust crate.
- [Grafts / Manifest Schema](/build/grafts/manifest-schema) — manifest TOML fields and the priority lattice in detail.

:::

================================================================================
# Source: /build/grafts/inject.md
================================================================================

# Inject

**After reading:** you'll know what `nockup graft inject` does to your `app.hoon`, why `--apply` is opt-in, and how to narrow the graft set without editing `hoon/lib/`.

`nockup graft` is the CLI that splices Hoon graft libraries into your kernel at the marker comments. It reads `<name>-graft.toml` manifests under `hoon/lib/`, composes the per-marker blocks, and writes the result back into `hoon/app/app.hoon`.

```d2
direction: right

manifests: "hoon/lib/*-graft.toml"
appin: "hoon/app/app.hoon\n(with markers)"
composer: "nockup graft inject"
stdout: "preview to stdout\n+ sha256 banner to stderr"
apply: "--apply"
appout: "hoon/app/app.hoon\n(composed)"

manifests -> composer
appin -> composer
composer -> stdout
stdout -> apply: {style.stroke-dash: 3}
apply -> appout
```

## The Composer Model

Every graft manifest declares blocks of Hoon code keyed to a marker name (`imports`, `state`, `cause`, `poke`, `peek`, etc.). The marker template in `templates/app.hoon` carries ten anchor comments at the right structural points:

```
templates/app.hoon  (89 lines; 10 anchor comments)
::  nockup:imports          ← graft /+ and /= imports
::  nockup:state            ← per-graft state fragments inside +$ versioned-state
::  nockup:domain-effect    ← your app's effect variants (you write these)
::  nockup:effect-union     ← codegen: the typed effect-union pass writes here
::  nockup:cause            ← graft cause-tag variants
::  nockup:load-defaults    ← codegen: state-shape migration overlay (resume)
::  nockup:peek             ← graft peek arms
::  nockup:poke-prelude     ← pre-flight checks (e.g. validate-graft)
::  nockup:poke             ← graft ?- arms
::  nockup:poke-postlude    ← post-flight observers (e.g. log-graft, batch-graft)
```

`nockup graft inject` walks `hoon/lib/`, reads every `<name>-graft.toml`, and splices each block at its declared marker. The composer is idempotent — re-running after `--apply` skips anything already wired.

See [NockApp Anatomy — Anchor Markers](/build/anatomy#anchor-markers) for the full per-marker purpose definitions (content markers vs. codegen anchors).

The matching manifest on disk:

```toml
# hoon/lib/settle-graft.toml (with an opt-in [graft.gates] override added)
[graft]
name     = "settle-graft"
version  = "0.1.0"
priority = 10
after    = []

[graft.types]
effect = "settle-effect"
cause  = "settle-cause"

# [graft.gates] is optional. settle-graft's poke body declares the canonical
# 4-line hash-gate splice point in each %settle-* arm; this section rewrites
# every occurrence to call a named gate from vesl-gates.hoon.
[graft.gates]
gate = "sig-verify-schnorr"

[graft.blocks.imports]
sentinel = "*settle-graft"
body     = """
/+  *settle-graft
/+  *vesl-merkle"""

[graft.blocks.state]
sentinel = "settle=settle-state"
body     = "settle=settle-state"

[graft.blocks.cause]
sentinel = "settle-cause"
body     = "settle-cause"

[graft.blocks.peek]
sentinel = "settle-peek"
body     = "(settle-peek settle.state path)"

# [graft.blocks.poke] holds the %settle-register / %settle-verify /
# %settle-note arm bodies — multi-line Hoon wrapped in TOML """ ... """
# strings.
```

The fields:

- **`[graft]`** — top-level metadata the composer reads but doesn't paste.
  - `name`: canonical identifier. Matches `--grafts <CSV>` on the CLI.
  - `version`: semver, bumped when blocks change incompatibly.
  - `priority`: injection order. The numeric band picks the family: 10–40 commitment, 50–99 state, 100–149 behavior, 200–299 intent.
  - `after`: soft ordering hints. Entries naming an absent graft are silently ignored.
- **`[graft.types]`** — opts the graft into the typed effect-union codegen. The composer synthesizes `+$ effect $%(...)` at the `nockup:effect-union` marker from every opted-in graft's `effect` declaration.
- **`[graft.gates]`** — picks a named verification gate from `vesl-gates.hoon` (`sig-verify-ed25519`, `sig-verify-schnorr`, `manifest-verify`, `set-membership-verify`, `bounded-value-verify`). Only grafts whose poke body carries the canonical 4-line hash-gate splice point accept the block; `settle-graft` is the one shipped manifest with that shape. Omitting the section keeps whatever gate the poke body already declares (the default single-leaf hash gate, for `settle-graft`).
- **`[graft.blocks.<marker>]`** — one sub-table per marker the graft contributes to. Each contains a `sentinel` (documentation-only label naming the marker target) and a `body` (the Hoon pasted at the matching `nockup:<marker>` anchor). Multi-line bodies use TOML's `""" ... """` block-string syntax. In the example, `imports` lands on the `/+` line, `state` becomes a `versioned-state` fragment, and `poke` (elided here) becomes the `?-` arms.

::: info Full schema reference

[**Manifest Schema**](/build/grafts/manifest-schema) — every field, gate-chains, stability levels, the priority lattice, and the supply-chain trust model.

:::

The shipping `settle-graft.toml` omits `[graft.gates]` (each `%settle-*` arm carries the default hash gate inline); the unabridged file is at [`hoon/lib/settle-graft.toml`](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/hoon/lib/settle-graft.toml). `mint-graft`, `guard-graft`, and `forge-graft` ship without the splice point and reject `[graft.gates]` at composition.

Each graft's splice-point status follows from what it semantically does. Only settle-graft has a verify-payload-against-registered-root lifecycle that a `verify-gate` parameterizes. Its `(settle-poke state cause veri)` signature takes the gate as a third argument, and every arm binds the gate before calling it. `%mint-commit` one-shot binds `[hull, root]` with no payload to check. `%guard-check` runs a hard-coded `hash-leaf` comparison. `%forge-prove` generates STARK proofs, not loobean predicates. The splice point is the composer's pattern-match anchor; its presence reflects whether the graft has a swappable gate slot at all.

## Cause Dispatch Semantics

When a graft's manifest declares a `[graft.blocks.poke-prelude]` block, the composed kernel runs that block **before** the kernel's `?-` switch dispatches on the cause-tag. The prelude runs for every poke — domain-written causes and graft-injected causes alike — and can short-circuit by returning `[(list effect) state]` directly, ending the gate before the switch sees the cause.

The canonical prelude is `validate-graft`'s rule check:

```hoon
=/  v-failure=(unit @t)
  (check-rules -.u.act +.u.act validate.state)
?:  ?=(^ v-failure)
  :_  state
  ^-  (list effect)
  ~[[%validate-rejected -.u.act u.v-failure]]
```

`u.act` is the noun the kernel received as the poke cause. The prelude inspects `-.u.act` (the cause-tag head) and `+.u.act` (the body after the tag) without caring which graft owns the cause. So:

- Domain causes (e.g. a hand-written `%my-app-do-thing`) hit the prelude.
- Graft-injected causes (`%queue-push`, `%batch-add`, `%settle-note`, `%rbac-grant`, etc.) **all** hit the prelude.
- The prelude only acts on causes for which rules have been installed via `%validate-init`. For causes with no installed rules, the prelude is a no-op and falls through to the `?-` switch.

### Block sentinels

Each manifest block specifies the source-line sentinel `inject` searches for in the composed kernel. The `poke-prelude` marker lives in `templates/app.hoon` (`::  nockup:poke-prelude` at the right structural point). Adding a prelude block to a new graft's manifest means injecting source between that sentinel and the kernel's `?-` switch.

## Preview by Default

```bash
nockup graft inject hoon/app/app.hoon            # preview
nockup graft inject --apply hoon/app/app.hoon    # write
```

A bare invocation prints the composed kernel to stdout and a per-manifest sha256 summary to stderr. Nothing is written until you pass `--apply`. This keeps a compromised `hoon/lib/` — pulled by sync, a bad `cp`, or a dependency bump — from silently composing hostile Hoon into your kernel source. The supply-chain trust model lives in [Manifest Schema](/build/grafts/manifest-schema).

## Removing Grafts

Every manifest under `hoon/lib/` composes by default. The vesl-graft package installs all of them; most apps need only a subset. Three ways to narrow the set, in increasing permanence:

```bash
nockup graft list                                                              # see what's available
nockup graft inject --grafts settle-graft,counter-graft --apply hoon/app/app.hoon  # one-shot allow-list
nockup graft inject --exclude intent-graft,forge-graft --apply hoon/app/app.hoon   # one-shot deny-list
```

A bare `nockup graft list` against the full `vesl-graft` install prints one row per discovered graft in priority order:

```
  settle-graft     0.1.0    priority=10  (imports, state, cause, poke, peek)
  mint-graft       0.1.0    priority=20  (imports, state, cause, poke, peek)
  guard-graft      0.1.0    priority=30  (imports, state, cause, poke, peek)
  forge-graft      0.1.0    priority=40  (imports, cause, poke)
  kv-graft         0.1.0    priority=50  (imports, state, cause, poke, peek)
  counter-graft    0.1.0    priority=60  (imports, state, cause, poke, peek)
  queue-graft      0.1.0    priority=70  (imports, state, cause, poke, peek)
  rbac-graft       0.1.0    priority=80  (imports, state, cause, poke, peek)
  registry-graft   0.1.0    priority=90  (imports, state, cause, poke, peek)
  validate-graft   0.1.0    priority=100 (imports, state, cause, poke-prelude, poke, peek)
  log-graft        0.1.0    priority=130 (imports, state, cause, poke, peek)
  clock-graft      0.1.0    priority=140 (imports, state, cause, poke, peek)
  batch-graft      0.1.0    priority=145 (imports, state, cause, poke, peek)
  intent-graft     0.1.0    priority=200 (imports, state, cause, poke, peek)
```

The `(blocks)` column names every marker the graft populates. `forge-graft` is stateless and omits `state` and `peek`. `validate-graft` lands a pre-flight check in `poke-prelude` in addition to a regular `poke` arm. Pass `--exclude <CSV>` to drop entries from the listing without touching `hoon/lib/`.

To remove a graft permanently, delete `<name>-graft.toml` from `hoon/lib/` (and the matching `.hoon` if no other graft imports it). The composer reads what's on disk; what's missing isn't discovered.

Markers in `app.hoon` are anchor points shared across the graft set. Multiple grafts can contribute to the same marker, and their bodies stack at that slot: every graft's `imports` body at `nockup:imports`, every graft's `poke` arms at `nockup:poke`, and so on. Each contribution is wrapped in a `graft-inject:<name>:<marker>:begin / :end` banner pair carrying the manifest's sha256, which is what `--apply` re-runs match against to skip already-wired blocks.

Inclusion is controlled by what `hoon/lib/` contains and by the CLI flags above. Deleting a marker removes the slot for every graft (one fewer place for any graft to land); deleting a manifest removes one graft from every slot it would have filled. A graft whose block targets an absent marker is a hard error — `nockup graft inject` stops with a nonzero exit rather than drop the block silently. Add the marker, or narrow the graft set so nothing targets it.

## Pre-Apply Linting

`nockup graft inject --apply` runs five structural lints against the composed kernel and refuses the write on any error-tier finding. The lints catch silent-fail surfaces composing would otherwise turn into corrupt output: `bare-tilde-ambiguity`, `collision`, `transitive-imports`, `internal-dupes`, `unresolved-cause-reference`, plus the advisory `weld-friction`. Each one names a specific failure mode in the composer or hoonc; the [Inject Lints](/build/grafts/inject/lints) page has the per-lint shape, sample output, and fix.

Severity is configurable per-project via the [`[lint]` table in `nockapp.toml`](/reference/nockapp-toml#lint-table); `--lint-override NAME=SEVERITY` is the one-shot CLI form. `nockup graft doctor` runs the lint pass under the resolved policy.

## What Got Composed

After `--apply`, the per-manifest sha256 summary on stderr looks like:

```
graft-inject: hoon/app/app.hoon
  settle-graft     sha256:a9c72bbe7dc1 injected 5/5 (imports, state, cause, poke, peek)
  mint-graft       sha256:4b2e...       injected 5/5 (imports, state, cause, poke, peek)
  guard-graft      sha256:c310...       injected 5/5 (imports, state, cause, poke, peek)
  forge-graft      sha256:f721...       injected 3/3 (imports, cause, poke)
  markers in source: 10
  markers populated: 5 (imports, state, cause, poke, peek)
```

`forge-graft` ships three blocks (no state, no peek — forge is stateless). The denominator is per-graft: each graft reports against the blocks *it* declares, not a fixed total.

By default, the four commitment grafts use a hash-comparison verification gate: the kernel tip5-hashes the raw payload and checks it against the registered root. That's enough for single-leaf commitments. For Merkle manifests, signatures, or STARK gates, see [Kernel — Verification Gates](/build/kernel/gates) and [Manifest Schema](/build/grafts/manifest-schema).

## Manifest SHA vs Library Edits

The per-graft sha256 in the inject banner — and the one `/status` surfaces in `manifest_shas` — is computed from `<name>-graft.toml`, **not** the sibling `<name>-graft.hoon` library file. Two consequences:

- **Editing the manifest** (block bodies, `[graft.gates]`, types) bumps the sha, and the next `inject --apply` re-emits every block carrying that graft's banner. The new digest appears in the banner and in `/status`.
- **Editing only the library** (a helper arm body, a comment, a typo in `<name>-graft.hoon`) does **not** change the manifest sha. `inject --apply` reports `injected 0/N; skipped …` against that graft — because the contribution is unchanged from the inject side's perspective. But `./compile.sh` reads the whole `hoon/lib/` tree, so hoonc picks the edit up and bakes it into `out.jam`. The change is live; the inject banner is correct that nothing about composition changed.

For local patches against a graft library, edit the `.hoon` file, re-run `./compile.sh`, and trust the recompile. To catch the gap (an edited library against an `out.jam` built before the edit), `vesl-test verify-jam` fingerprints both the manifest TOMLs and the library Hoon — so a stale jam against either surface trips it. See [Testing → CLI → verify-jam](/build/testing/cli#verify-jam-—-build-staleness-check).

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

::: info See Also

- [vesl-nockup README — Step 3](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#step-3--wire-the-kernel) — the canonical wire-the-kernel walkthrough.
- [`tools/graft-inject/src/`](https://github.com/zkvesl/vesl-nockup/tree/main/tools/graft-inject/src) — composer source: manifest loader, marker matcher, lint passes.
- [`templates/app.hoon`](https://github.com/zkvesl/vesl-nockup/blob/main/templates/app.hoon) — the marker template the composer wires against.

:::

================================================================================
# Source: /build/grafts/inject/lints.md
================================================================================

# Inject Lints

`nockup graft lint <app.hoon>` runs read-only structural validations. Exit code is `1` on any error-tier finding so CI can gate `--apply` on the lint passing. Pass `--json` for a stable machine-readable schema. Five lint families run via the `lint` subcommand. `nockup graft inject --apply` runs all five structural lints — `bare-tilde-ambiguity`, `collision`, `transitive-imports`, `internal-dupes`, and `unresolved-cause-reference` — and refuses the write on any error-tier finding, because composing the file is what turns each silent-fail surface into corrupt output. A sixth lint, `weld-friction`, runs only at compose time and defaults to `warn` (advisory). See [CLI — Lints](/reference/cli#lints).

Every finding goes through one printer, so each line begins with `  {severity}: {kind}: ` (severity is `error`, `warning`, or `note`; kind matches the JSON key — `weld-friction`, `bare-tilde-ambiguity`, `collision`, `transitive-imports`, `internal-dupes`, or `unresolved-cause-reference`). Findings of the same kind print consecutively, then the per-lint remediation hint emits once for the group. The unified shape lets `grep '<kind>:'` count findings without scraping the body and `grep '^  error:'` route only the gating findings.

Severity is configurable per-project via the [`[lint]` table in `nockapp.toml`](/reference/nockapp-toml#lint-table) — e.g. `[lint] weld-friction = "error"` promotes the advisory weld lint to a gate; `[lint] transitive-imports = "warn"` demotes it below the `--apply` gate. The `--lint-override NAME=SEVERITY` CLI flag is a one-shot override at the same precedence (CLI wins over config, config wins over default). `nockup graft doctor` runs the lint pass under the resolved policy and lists the effective severity per lint, so the same command surfaces both the active policy and the findings it produces without requiring a compose.

Lint output references Hoon constructs in the composed kernel. Vocab the sections below use:

- `?-` — exhaustive-match rune (Hoon's `match`).
- `~` — null, also the empty-list literal.
- `+$ cause $%(...)` — tagged-union declaration (like a Rust `enum`).
- `+$ versioned-state $:(...)` — record declaration (like a Rust `struct`).
- `/+` `/=` `/-` `/#` — import runes.

## `bare-tilde-ambiguity`

**What you see:** an arm in your `++poke` switch flagged because its body ends with a bare `~` on its own line. Sample:

```
graft-inject lint: 1 error(s)
  error: bare-tilde-ambiguity: hoon/app/app.hoon:147 — domain arm `%settle-register` body ends with bare `~` line
    graft-inject's chain-rebuilder may mistake this for the peek-chain
    terminator. Refactor to one of:
      `(list effect)`~
      ^- (list effect) ~
```

**Why it matters:** the composer's peek-chain rebuilder treats a lone `~` line as a chain terminator, which would corrupt `app.hoon`. `nockup graft inject --apply` runs this check and refuses to write on a finding; `nockup graft lint` reports it without composing.

**Fix:** type-annotate the empty list on a single line. Use `` `(list effect)`~ `` (cast shorthand) or `^- (list effect) ~` (cast rune).

## `collision-check`

**What you see:** lint output naming a cause-tag or state-field that two or more grafts (or a graft and your domain) both declare. Sample:

```
graft-inject lint: 2 error(s)
  error: collision: cause-tag `settle-register` declared by: settle-graft, (domain)
  error: collision: state-field `epoch` declared by: settle-graft, my-domain-graft
    duplicate names compose into one cause $% / state record.
    Disambiguate via manifest rename, profile-letter suffix, or
    domain shadowing.
```

**Why it matters:** duplicates compose into one `+$ cause $%(...)` union or one `+$ versioned-state` record. hoonc would later fail with a `nest-fail`. The lint catches this at scaffold time and attributes the conflict to specific manifests.

**Fix:** rename the offender in its manifest, suffix one with a profile letter, or shadow it in your domain.

**Coverage:** cause-tags and state-fields. Graft peek arms chain, so peek-path-head overlap is benign and falls outside the lint. `[graft.types].effect` duplicates are caught at composer discovery instead (see [CLI / Common Errors](/reference/cli#common-errors)).

## `transitive-imports`

**What you see:** lint output listing each unsatisfied `/+`, `/=`, `/-`, or `/#` import: source file, import token, expected target, and the BFS chain that reached it. Sample:

```
graft-inject lint: 1 error(s)
  error: transitive-imports: hoon/common/nock-prover.hoon: /# softed-constraints → hoon/dat/softed-constraints.hoon (NOT FOUND)
      reachable from: hoon/common/nock-prover.hoon
    hoonc eager-parses hoon/common/ regardless of import-graph
    reachability; unsatisfied edges leave hoonc exit 0 with no
    out.jam (the "no panic!" silent-fail). Either add the missing
    target file or strip the offending file from hoon/common/.
```

**Why it matters:** `hoonc` eager-parses every `.hoon` under `hoon/common/` regardless of import-graph reachability. An unsatisfied edge there causes hoonc to exit 0 with no `out.jam` written. This is the silent-fail case described in [Build & Run](/build/build-run/).

**Fix:** add the missing `.hoon` to `hoon/lib/` or `hoon/common/`, or remove the unsatisfied import.

## `internal-dupes`

**What you see:** lint output naming a duplicate variant head inside the composed `+$ cause $%(...)` or a duplicate field name inside `+$ versioned-state $:(...)`. Sample:

```
graft-inject lint: 1 error(s)
  error: internal-dupes: duplicate cause-tag `kv-set` at lines 178, 213
    literal duplicates in the composed +$ cause $%(...) or
    +$ versioned-state $:(...) — hoonc accepts whichever wins
    lexically (mint-lost) or fires nest-fail on duplicate fields.
    Rename, merge into a tagged sum, or distinguish by argument shape.
```

**Why it matters:** these duplicates only surface after composition. Two grafts with different manifest names can still contribute the same variant head or field, which `collision-check` (manifest-side) doesn't catch. hoonc would fail later with a `nest-fail`.

**Fix:** edit one of the contributing grafts' bodies in its manifest to rename the offending head or field. If one of the grafts is shipped by vesl, shadow or rename it in your local fork of the manifest.

## `unresolved-cause-reference`

**What you see:** lint output naming a sub-cause-type cited by the kernel's `+$ cause $%(...)` union that no manifest in the active set declares via `[graft.types].cause`. Sample:

```
graft-inject lint: 1 error(s)
  error: unresolved-cause-reference: hoon/app/app.hoon:54 — `+$ cause` references `settle-cause`, but no graft's [graft.types].cause declares that type
    the cause-tag codegen drops the contribution silently and
    hoonc later surfaces it as `find . <name>-cause`. Either
    add the missing manifest to --lib-dir (and ensure its
    [graft.types].cause matches the referenced name), or remove
    the reference from the kernel's `+$ cause` union.
```

**Why it matters:** the cause-tag codegen pass cross-references each `[graft.types].cause` declaration against the union's references, then emits a Rust slice driving the hull-side `assert_kernel_cause_tag!` macro. An orphan reference silently drops the contribution from the slice, and the composed kernel reaches hoonc with an undefined type name — surfacing as the unfriendly `find . <name>-cause` error with no path back to the kernel source line.

**Fix:** either add the missing manifest to `hoon/lib/` and ensure its `[graft.types].cause` matches the referenced name, or remove the reference from the kernel's `+$ cause` union.

::: info See Also

- [Inject](/build/grafts/inject) — the composer itself; this page is its lint surface.
- [CLI — Lints](/reference/cli#lints) — printer shape, JSON schema, the `--lint-override` flag.
- [nockapp.toml — `[lint]` table](/reference/nockapp-toml#lint-table) — per-project severity overrides.

:::

================================================================================
# Source: /build/grafts/manifest-schema.md
================================================================================

# Manifest Schema

A graft manifest is a TOML file that describes how `nockup graft inject` composes a Hoon library into a host kernel's `app.hoon`. One manifest per graft, sibling to the graft's `.hoon` file under `hoon/lib/`. The full source-of-truth schema lives at [`vesl-nockup/docs/graft-manifest.md`](https://github.com/zkvesl/vesl-nockup/blob/main/docs/graft-manifest.md); this page is a navigable companion.

## Layout

```
hoon/lib/
├── settle-graft.hoon      Hoon library
├── settle-graft.toml      manifest (this schema)
├── mint-graft.hoon
├── mint-graft.toml
└── ...
```

Flat — no per-graft directory. The manifest's `name` field, not its filename, is the canonical identifier the loader uses.

## Manifest Skeleton

```toml
[graft]
name      = "settle-graft"      # canonical name, matches --grafts <CSV>
version   = "0.1.0"             # semver
priority  = 10                  # injection order; band picks the family
stability = "stable"            # stable | beta | placeholder
after     = []                  # soft ordering hints

[graft.types]                   # optional — typed effect-union codegen input
effect    = "settle-effect"
cause     = "settle-cause"

[graft.gates]                   # optional — gate selection (commitment grafts)
gate      = "manifest-verify"

[graft.blocks.imports]
sentinel  = "*settle-graft"
body      = """
/+  *settle-graft
/+  *vesl-merkle"""

[graft.blocks.state]
sentinel  = "settle=settle-state"
body      = "settle=settle-state"

# ... one [graft.blocks.<marker>] per marker the graft contributes to
```

## `[graft]` — Top-Level Metadata

| Field | Type | Required | Notes |
|---|---|---|---|
| `name` | string | yes | Canonical name. Must be unique across all manifests under the discovery root. |
| `version` | string | yes | Semver. Bumped when blocks change in a backwards-incompatible way. |
| `priority` | int | yes | Injection order. Lower = injected earlier. The band picks the family. |
| `stability` | string | no | One of `stable`, `beta`, `placeholder`. Defaults to `stable`. `placeholder` marks a reserved family slot whose body crashes on invocation (see `intent-graft`). |
| `after` | string list | no | Soft ordering hints. Each entry names another graft that must inject earlier. If an entry names a graft not in the discovered set, the hint is silently ignored and priority-based ordering applies. |
| `schema_version` | int | no | Manifest-schema version this manifest targets. Absent means a pre-handshake manifest, compatible with any `nockup-graft` (the schema is append-only). A value newer than the installed `nockup-graft` supports makes `inject`, `doctor`, and `update` hard-error — update the binary. Shipped manifests do not declare it yet. |

## `[graft.blocks.<marker>]` — Injection Blocks

A graft contributes one block per marker it claims. Ten markers exist — seven content markers and three codegen markers (`domain-effect`, `effect-union`, `load-defaults`). Codegen markers are anchors for the composer's own passes; grafts don't contribute per-graft blocks at them.

| Marker | What lands here |
|---|---|
| `imports` | `/+` and `/=` import lines |
| `state` | per-graft fragments inside `+$ versioned-state` |
| `cause` | variant additions to the cause `$%` union |
| `poke-prelude` | pre-flight hook (e.g. `validate-graft`) |
| `poke` | the `?-` arms |
| `poke-postlude` | post-flight observer (e.g. `log-graft`, `batch-graft`) |
| `peek` | peek arms (joined into a chain across grafts) |
| `domain-effect` | codegen anchor (your `+$ domain-effect $%(...)` declaration) |
| `effect-union` | codegen anchor (typed effect-union written by the composer) |
| `load-defaults` | codegen anchor (state-shape migration overlay on resume) |

Each present block is a TOML sub-table with two fields:

| Field | Type | Required | Notes |
|---|---|---|---|
| `sentinel` | string | yes | Documentation-only — names the marker the block targets. The loader's idempotence runs off `::  graft-inject:<name>:<marker>:begin` banner comments the composer emits. |
| `body` | string | yes | The Hoon to paste at the marker. Stored unindented; the loader re-applies indentation from the marker's leading whitespace. Leading and trailing newlines are trimmed. |

A content block omitted from the manifest is not injected for that marker — the marker is left untouched.

## `[graft.gates]` — Gate Selection

A graft accepts `[graft.gates]` only when its poke body declares the canonical hash-gate splice point — the 4-line block gate selection rewrites:

```hoon
=/  hash-gate=verify-gate
  |=  [note-id=@ data=* expected-root=@]
  ^-  ?
  =((hash-leaf ;;(@ data)) expected-root)
```

Of the shipped manifests, only `settle-graft` declares this shape (one occurrence per arm: `%settle-register`, `%settle-verify`, `%settle-note`). `mint-graft`, `guard-graft`, and `forge-graft` don't carry the splice point — a `[graft.gates]` block on them fails composition with a splice-point mismatch error. A custom graft opts in by including the same block at each arm whose verification it wants the catalog to drive.

To swap in a named gate from `vesl-gates.hoon`:

```toml
[graft.gates]
gate = "manifest-verify"
```

Or for a chain of gates evaluated in order:

```toml
[graft.gates]
gate-chain = ["sig-verify-schnorr", "manifest-verify"]
```

Five named gates ship: `sig-verify-ed25519`, `sig-verify-schnorr`, `manifest-verify`, `set-membership-verify`, `bounded-value-verify`. A gate is a parameter, not a step in a pipeline. See [Build / Kernel — replacing a verification gate](/build/kernel/gates) for replacing a gate with a fully custom one.

### Swapping a Gate

Edit `[graft.gates]` and re-run `nockup graft inject --apply`. The composer detects manifest drift via the sha256 in each begin-banner and re-injects the new gate body.

What changes when a swap lands:

- **Poke body.** Each `%settle-*` arm's splice point is rewritten to bind the named gate (`=/  hash-gate=verify-gate  name:vesl-gates`) or, for `gate-chain`, an AND-folded predicate over each gate's call.
- **Imports.** The composer prepends `/+  vesl-gates` to the imports body once. The import is non-splat — the rewritten body uses the qualified `name:vesl-gates` form.
- **Payload shape (`data=*`).** Gate-specific. `sig-verify-{ed25519,schnorr}` expect `[data=@ sig=@ pubkey=@]`. `manifest-verify` expects `[fields=(list [name=@t value=@]) proofs=(list (list [hash=@ side=?]))]`. `set-membership-verify` expects `[elem=@ proof=(list [hash=@ side=?])]`. `bounded-value-verify` expects `[value=@ bounds=[lo=@ hi=@] proof=(list [hash=@ side=?])]`. The default expects a single atom (`;;(@ data)`). Each gate `;;`-casts internally; a malformed payload returns `%.n` (no crash).
- **Root semantics.** Default hash gate binds `expected-root = hash-leaf(payload-atom)`. `sig-verify-{ed25519,schnorr}` bind `expected-root = hash-leaf(pubkey)` — the registered root *is* the public key, and the gate enforces a signature over `data` from that key. `manifest-verify`, `set-membership-verify`, and `bounded-value-verify` verify Merkle paths against the root. Roots registered under one gate do not validate under another — a swap mid-project leaves prior registrations in state, but the new gate rejects them.
- **Rust driver.** Pick the matching `build_settle_note_*_poke`. All ship in `vesl-core`: `build_settle_note_schnorr_poke`, `build_settle_note_ed25519_poke`, `build_settle_note_manifest_poke`, `build_settle_note_membership_poke`, `build_settle_note_bounded_poke`, and the default-gate `build_settle_note_poke`. For `gate-chain`, no convenience builder exists — use `build_settle_note_poke_with_data` from vesl-core and supply a noun matching every chained gate's payload contract.

What stays the same: cause-tag union (`%settle-register`, `%settle-verify`, `%settle-note`), verify-gate signature (`[note-id=@ data=* expected-root=@]` returning `?`), state shape, and the effect tags emitted on success (`%settle-registered`, `%settle-noted`, `%settle-verified`) or failure (`%settle-error`).

## `[graft.types]` — Typed Effect-Union Input

A graft that exports a tagged effect type opts into the typed effect-union codegen by declaring it:

```toml
[graft.types]
effect = "settle-effect"
cause  = "settle-cause"
```

Names must be kebab-case (`^[a-z][a-z0-9-]*$`). Two grafts cannot declare the same `effect` (or `cause`) name — `nockup graft inject` hard-errors at discovery if they collide. The composer synthesizes a `+$ effect $%(...)` union under the `nockup:effect-union` marker; variant order matches injection order. The cause field is reserved for forward-compat cause-destructuring and not yet read.

## The 5-Family Lattice

Grafts fall into five families. The priority number both orders injection and labels the family.

| # | Family | Priority band | Role | Examples |
|---|---|---|---|---|
| 1 | Commitment | 10–40 | STARK-bearing primitives that commit data to hull-keyed roots | `settle-graft` (10), `mint-graft` (20), `guard-graft` (30), `forge-graft` (40) |
| 2 | Verification gates | n/a (library) | Parameterized decision functions consumed by commitment grafts via `[graft.gates]` | `vesl-gates.hoon` (5 named gates ship today) |
| 3 | State | 50–99 | Domain-keyed app-state primitives | `kv` (50), `counter` (60), `queue` (70), `rbac` (80), `registry` (90) |
| 4 | Behavior | 100–149 | Runtime wrappers that enforce or observe rules around other grafts | `validate` (100), `log` (130), `clock` (140), `batch` (145) |
| 5 | Intent | 200–299 | Multi-party coordination primitives (declare / match / cancel / expire) | `intent-graft` (200, placeholder) |

Bands 150–199 and 300+ are reserved for future families or user/domain grafts. Verification gates do not claim a priority band — they're library arms imported by commitment grafts.

## Trust Model

A manifest's `body` field is Hoon text pasted **verbatim** into your `app.hoon`. `nockup graft` does not sanitize, sandbox, sign-check, or verify the provenance of a manifest. Whatever Hoon a `.toml` declares becomes kernel source on the next `--apply`.

Three consequences:

- **Manifests are code.** Treat them like any other dependency: review incoming changes the way you would a PR that touches `hoon/lib/`.
- **`nockup graft` is a composition step, not a trust boundary.** Trust is managed at the distribution layer — checkout provenance, directory hygiene, what lands in `hoon/lib/`.
- **Preview by default.** `nockup graft inject` prints the composed diff and a per-manifest sha256 to stderr; nothing writes to disk until `--apply`. This keeps silent supply-chain drift impossible without explicit consent.

## Worked Example: `settle-graft.toml`

```toml
[graft]
name     = "settle-graft"
version  = "0.1.0"
priority = 10
after    = []

[graft.types]
effect = "settle-effect"
cause  = "settle-cause"

[graft.blocks.imports]
sentinel = "*settle-graft"
body     = """
/+  *settle-graft
/+  *vesl-merkle"""

[graft.blocks.state]
sentinel = "settle=settle-state"
body     = "settle=settle-state"

[graft.blocks.cause]
sentinel = "settle-cause"
body     = "settle-cause"

# [graft.blocks.poke] block contains the ?- arms.
# See the file linked below for the full body.
```

The full file is at [`hoon/lib/settle-graft.toml`](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/hoon/lib/settle-graft.toml).

::: info See Also

- [`vesl-nockup/docs/graft-manifest.md`](https://github.com/zkvesl/vesl-nockup/blob/main/docs/graft-manifest.md) — canonical source-of-truth schema document.
- [Reference / CLI (nockup graft)](/reference/cli) — the consumer of this schema.
- [Build / Inject](/build/grafts/inject) — how the schema fits into the dev workflow.

:::

================================================================================
# Source: /build/grafts/trellis-pattern.md
================================================================================

# The Trellis Pattern

**After reading:** you'll know when one settle-graft is enough and when you need a trellis — multiple `hull=@` keys, one kernel, isolated lifecycles per cell.

One kernel, one root, one replay boundary — fine, until the day an app needs two. Different tenants. Different app versions. Different audit periods. Different credential subjects. `settle-graft`'s `registered=(map @ @)` already supports it; pick a scheme for `hull-id` and use it.

A **trellis** is the shape that falls out: a grid of independent commitment buckets sharing a single kernel. Each cell is its own root, its own lifecycle, its own `%settle-register` / `%settle-verify` / `%settle-note` namespace. The kernel glues the cells together at exactly one place: a global `settled` set. Everything else stays isolated.

## Why reach for it

One hull works until the day the app needs to:

- Split commitments by tenant (each customer gets their own root)
- Split by version (app-v1 SBOM vs app-v2 SBOM — any build attests independently)
- Split by period (Q1 audit trail, Q2 audit trail, each with its own root-of-roots)
- Split by domain (license roots alongside credential roots in the same kernel)

The trellis gives the isolation of separate kernels without booting separate `NockApp`s. `hull-id` is the only axis needed.

## Shape

`settle-state` carries the two fields the pattern keys on:

```hoon
+$  settle-state
  $:  registered=(map @ @)    ::  hull-id -> merkle-root
      settled=(set @)         ::  note-ids (global across the trellis)
      ::  ... other settle-graft fields
  ==
```

The trellis lives in `registered`. Each `hull-id` keys a distinct root. `settled` is *global*: note-ids are unique kernel-wide across all hulls. When per-hull note-id namespaces are needed, key notes as `note-id = hash(hull, local-id)` on the caller side before sending them.

```
┌───────────────── kernel ──────────────────┐
│                                           │
│   ┌─ hull 1 ──────┐   ┌─ hull 2 ──────┐  │
│   │  root₁        │   │  root₂        │  │
│   │  (tenant A)   │   │  (tenant B)   │  │
│   └───────────────┘   └───────────────┘  │
│                                           │
│   ┌─ hull 3 ──────┐   ┌─ hull 4 ──────┐  │
│   │  root₃        │   │  root₄        │  │
│   │  (version v1) │   │  (version v2) │  │
│   └───────────────┘   └───────────────┘  │
│                                           │
│   settled = { 101, 201, 301, 401 }       │  ← global
│                                           │
└───────────────────────────────────────────┘
```

## Lifecycle: Two Cells in Parallel

Register, verify, and note are all keyed by `hull-id`. Running two in parallel is just two sets of calls with different hull arguments — the caller's wiring stays the same; only the hull-id varies between cells:

```rust
use vesl_core::{
    build_settle_register_poke,
    build_settle_verify_poke,
    build_settle_note_poke,
    Mint,
};
use nockapp::wire::{SystemWire, Wire};

let root_v1 = mint_v1.commit(&[sbom_v1][..]);
let root_v2 = mint_v2.commit(&[sbom_v2][..]);

app.poke(SystemWire.to_wire(), build_settle_register_poke(1, &root_v1)).await?;
app.poke(SystemWire.to_wire(), build_settle_register_poke(2, &root_v2)).await?;

app.poke(SystemWire.to_wire(), build_settle_verify_poke(101, 1, &root_v1, sbom_v1)).await?;
app.poke(SystemWire.to_wire(), build_settle_verify_poke(201, 2, &root_v2, sbom_v2)).await?;

app.poke(SystemWire.to_wire(), build_settle_note_poke(101, 1, &root_v1, sbom_v1)).await?;
app.poke(SystemWire.to_wire(), build_settle_note_poke(201, 2, &root_v2, sbom_v2)).await?;
```

Two independent lifecycles, one kernel. Swap `1` and `2` for any identifier scheme — tenant IDs, vault IDs, credential subjects, period numbers, git SHAs truncated to `u64`.

## Cross-Cell Guardrails

The graft catches cross-cell mistakes without crashing. Each check is independent per hull, except for the global `settled` set.

**Replay** — a note-id already in `settled` errors regardless of hull:

```rust
// second note of 101 — already in settled; global check fires
app.poke(SystemWire.to_wire(), build_settle_note_poke(101, 1, &root_v1, sbom_v1)).await?;
//   → effect: %settle-error   (note already settled)
```

**Root mismatch** — presenting hull 1's root under hull 2 errors because hull 2's registered root differs:

```rust
// hull 2 is registered with root_v2; presenting root_v1 under it
app.poke(SystemWire.to_wire(), build_settle_note_poke(301, 2, &root_v1, sbom_v1)).await?;
//   → effect: %settle-error   (root mismatch)
```

**Unregistered hull** — any note against a hull-id that was never registered errors cleanly:

```rust
app.poke(SystemWire.to_wire(), build_settle_note_poke(999, 99, &root_v1, sbom_v1)).await?;
//   → effect: %settle-error   (root not registered)
```

Each guard returns `%settle-error` with a diagnostic cord. None crash the kernel, and none leak state between cells.

## Layering Domain Pokes Over the Trellis

Domain pokes can read from the grafted `settle=settle-state` alongside the app's own state; there's no special bridging. A typical pattern keeps a parallel per-hull log or set that mirrors the trellis:

```hoon
+$  versioned-state
  $:  %v1
      settle=settle-state
      digests=(list [hull=@ud dig=@t])    ::  a log per hull
      verified=(set @ud)                   ::  hulls the app has blessed
  ==
```

Arms like `%record-digest hull=@ud dig=@t` append to `digests`, and `%mark-verified hull=@ud` puts into `verified`. Neither touches `settle.state`, so the graft stays hands-off. The graft arms and the domain arms coexist in the same `?-` switch; [Kernel — Adding a Domain Cause](/build/kernel/causes) walks through the per-command shape.

## When Not to Trellis

- **Single-tenant apps with one root forever.** One hull is fine; don't add ceremony.
- **Apps that need per-hull replay namespaces.** The `settled` set is global. For note-id `101` to be note-able once per hull, hash the hull-id into the note-id before calling `build_settle_note_poke`.
- **Apps near the settled-set capacity.** The `settled` set has a fixed capacity across all hulls combined; check `settle-graft`'s manifest for the current limit. Partition into separate kernels when approaching that bound.
- **Apps that want per-hull verification gates.** The gate is wired once per `%settle-*` arm; when hull 1 needs signature verification and hull 2 needs STARK verification, fork the arms or write a dispatching gate that branches on `hull`.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

================================================================================
# Source: /build/kernel/index.md
================================================================================

# Kernel

**After reading:** you'll have a Hoon cheatsheet at hand and know which subpage to open when you're writing a domain cause, a peek path, or a replacement verification gate.

Most of your kernel is composed for you by `nockup graft`: commitment, state, and behavior primitives ship as graft libraries that drop into any nockapp. The behavior unique to your app's domain is the Hoon you write between the markers — the cause that says "register an artifact" or "issue a badge," the state field that tracks it, the `?-` arm that wires the primitives together. Generic graft libraries are built for reuse across many apps; the domain-specific layer stays in your kernel so each app can shape it independently.

Typically the amount is small: one or two custom causes, the `?-` arms that handle them, optional peek paths, and (sometimes) a replacement verification gate. The subpages cover those three patterns.

::: info Heads up

This is a basic Hoon-and-kernel guide: enough syntax and patterns to write custom domain logic in a vesl kernel. For a deeper Hoon education, work through [Hoon School](https://docs.urbit.org/courses/hoon-school/). The [Hoon Cheatsheet](#hoon-cheatsheet) below is a quick reference for the runes, auras, and stdlib gates used in the worked examples.

:::

## Hoon Cheatsheet

A skim-able reference for the syntax used throughout these pages. For a fuller introduction, see [Hoon School](https://docs.urbit.org/courses/hoon-school/).

### Syntax and Semantics

| Term | Meaning |
|---|---|
| **Noun** | Hoon's universal value type. Either an *atom* or a *cell*. |
| **Atom** | A non-negative integer. The primitive scalar. |
| **Cell** | An ordered pair of nouns, written `[a b]`. Nests right: `[1 2 3]` parses as `[1 [2 3]]`. |
| **Aura** | A tag on an atom that says how to read it. Bits stay the same; the aura is metadata for the printer and parser. |
| **Tagged union** | A type with multiple variants, each marked by a head tag. Hoon's `$%(...)` constructor builds one; `?-` is the exhaustive switch over the tag. The same concept as Rust's `enum`. |
| **Loobean** | Hoon's boolean type, written `?`. Two values: `%.y` (true) and `%.n` (false). |
| **Core** | A piece of code (the *battery*) plus its closed-over data (the *payload*). Hoon's closest thing to a class. |
| **Arm** | A function on a core. Invoked via `~(arm core arg)` or dotted-axis (`arm.core`). |
| **Gate** | A function. A specialized core with one arm (`$`) and a sample slot. |
| **Sample** | A gate's argument slot. `|=  sample  body` binds the sample at call time; the body reads it by name. |
| **Wet-gate** | A polymorphic gate, declared with `|*`. Its sample type isn't fixed at declaration — each call site re-checks the body against the actual sample shape. `vesl-core`'s `domain-patterns` ships these. |
| **Door** | A core used as a module-style API; arms accessed via `~(arm door arg)`. Examples: `by` (map ops), `in` (set ops). |
| **Subject** | The lexical scope at a point in source: every name visible there. |
| **Mote** | An error class — a short `@tas` printed in stderr traces (e.g. `mote=Exit`, `mote=Fail`). Soft-cast (`;;`) and assertion (`?>`) failures raise `Exit`; `mule` catches them as `%.n`. |
| **`++poke`** | The kernel's top-level write entrypoint. Takes `(cause, state)`, returns `[effects new-state]`. |
| **`++peek`** | The kernel's top-level read entrypoint. Takes a path, returns `(unit (unit *))`. |

### Auras

The aura is a tag on an atom describing how to read its integer value. Bits stay the same; the aura changes how it prints and parses.

| Aura | Reading | Example |
|---|---|---|
| `@` | bare atom (no read-as) | `5`, `123` |
| `@ud` | unsigned decimal | `5`, `100` |
| `@ux` | unsigned hex | `0x10`, `0xdead` |
| `@t` | UTF-8 cord | `'hello'` |
| `@tas` | lowercase-and-dashes symbol | `%settle`, `%mint-graft`, `%my-action` |
| `@da` | absolute date | `~2026.5.10` |

### Syntactic Marks

The single-character and two-character marks Hoon uses for literals, punctuation, and access:

| Mark | Meaning |
|---|---|
| `::` | Line comment. Everything after the two colons to end-of-line is ignored. |
| `%name` | Symbol literal — an `@tas` atom. The `%` is the syntactic mark; the name is what follows. |
| `'text'` | Cord literal — UTF-8 text packed into a `@t` atom. |
| `0xNN` | Hex literal — `@ux` atom. |
| `~` | Null. Used as the empty unit, the end-of-list marker, and the "no result" return. |
| <code>&#96;</code> | Unit-wrap shorthand. `&#96;value` is `[~ value]`. Used to return `(unit *)` succinctly. |
| <code>&#96;&#96;</code> | Twice-unit-wrap. `&#96;&#96;value` is `[~ ~ value]`. Peek arms return `(unit (unit *))`. |
| `~YYYY.MM.DD` | Absolute date literal — `@da` atom. |
| `[a b ...]` | Cell literal. Right-associative: `[1 2 3]` parses as `[1 [2 3]]`. |
| `name.subject` | Dotted-axis access. Reach a named field inside `subject`. |
| `name=type` | Field or binding declaration. Same shape in records, gate arguments, and `=/` let-bindings. |
| `==` | Block terminator. Closes `$%`, `?-`, and `$:` blocks. |
| `--` | Core terminator. Closes `|%`. |

### Runes — The 12 vesl Hoon Uses

The runes a domain author writing 5–10 lines of Hoon per cause actually reaches for. Drawn from the rune-frequency profile across shipped graft Hoon, narrowed to what you write inside a `?-` arm or a `+$` declaration.

| Rune | Purpose | Example (from settle / kv graft) |
|---|---|---|
| `?-` | Exhaustive switch on a tagged union. The shape of every cause-arm dispatch. Closes with `==`. | `?-  -.cause  %kv-set  set-arm  %kv-delete  del-arm  ==` |
| `?:` | If-then-else. | `?:  (gte ~(wyt by store) store-cap)  reject  proceed` |
| `?.` | If-not (inverse condition). | `?.  =(root expected-root)  reject  accept` |
| `?>` | Assertion. Deterministic exit (`Exit` mote) if the test fails — the clean-deny shape for arm preconditions. | `?>  (verify-leaf root note)` |
| `^-` | Type cast (downcast). The canonical empty-effect-list cast. | `^-  [(list kv-effect) kv-state]` |
| `:_` | Cell constructor, tail-first. `:_  X  Y` is `[Y X]` — the canonical `[(list effect) new-state]` return shape. | `:_  state(store new-store)  ~[[%kv-stored key.cause]]` |
| `=/` | Typed let-binding: `=/  name=type  expr`. | `=/  new-store  (~(put by store.state) key.cause value.cause)` |
| `+$` | Type declaration. State, effects, and cause unions are declared this way. | `+$  kv-state  $:(store=(map @t @))` |
| `\|=` | Gate (function) declaration: `\|=  sample  body`. The Hoon equivalent of a function literal. | `\|=  [state=kv-state cause=kv-cause]` |
| `++` | Arm declaration in a core. Kernel `++poke` and `++peek` are arms. | `++  kv-poke  \|=  [state=kv-state cause=kv-cause]` |
| `/+` | Import a Hoon library into scope. Graft imports land here at the `nockup:imports` marker. | `/+  *kv-graft` |
| `;;` | Soft-cast / mold-check. `;;(type expr)` re-checks `expr` against `type` and exits on a shape mismatch. The standard guard for `*`-typed inputs. | `;;((map @t @) raw-store)` |

### Deeper Hoon Rune Reference

The other runes you'll encounter in shipped graft Hoon and the wider language. Less load-bearing for domain code, but useful when you read graft bodies or peek-chain plumbing.

| Rune | Purpose | Example (from settle / kv graft) |
|---|---|---|
| `=>` | Compose: evaluate the second expression with the first in scope. | `=>  zeke  (tip5 leaves)` |
| `?~` | Branch on null vs non-null `(unit)`. | `?~  found  [~ ~]  [~ ~ u.found]` |
| `?=` | Type-pattern match. | `?=  [%kv-set *]  cause` |
| `^*` | Default value of a type. | `^*  kv-state` |
| `~(arm core arg)` | Method-call shape: invoke `arm` on `core` with sample `arg`. | `(~(put by store) key value)` |
| `\|.` | Trap — a zero-argument core. `\|.  expr` is a thunk evaluated by its `$` arm. `mule` wraps a trap to catch crashes. | `(mule \|.((kv-poke state cause)))` |
| `%-` | Function call (slam). `(gate arg)` is the irregular form. | `(kv-poke kv.state cause)` |
| `%=` | Record update by name. `a(b c)` is the irregular form. | `state(store new-store)` |
| `+(x)` | Increment. | `+(note-counter.state)` |
| `~[a b c]` | List literal. | `~[[%kv-stored key.cause]]` |
| `$%` | Tagged-union type constructor. Closes with `==`. | `$%  [%kv-set key=@t value=@]  [%kv-delete key=@t]  ==` |
| `$:` | Record-type constructor. Closes with `==`. | `$:  store=(map @t @)  ==` |
| `$-` | Gate-type constructor. `$-(sample return)` is the type of a gate from `sample` to `return`. `verify-gate` is `$-([note-id=@ data=* expected-root=@] ?)`. | `$-([@t @] ?)` |

### Stdlib Gates

Hoon stdlib gates the worked examples and reference pages use. The `by` door operates on maps; `in` operates on sets.

| Gate | Call | Behavior |
|---|---|---|
| `wyt` | `~(wyt by m)` / `~(wyt in s)` | Cardinality — count of entries in a map or members in a set. |
| `gut` | `(~(gut by m) key fallback)` | Get-or-default. Returns `m[key]` if present, else `fallback`. |
| `has` | `(~(has by m) key)` / `(~(has in s) elem)` | Membership test. Returns `?`. |
| `put` | `(~(put by m) key value)` / `(~(put in s) elem)` | Insert (or overwrite). |
| `scag` | `(scag n list)` | List take — first `n` elements. |
| `slag` | `(slag n list)` | List drop — elements after position `n`. |
| `turn` | `(turn list f)` | List map — apply `f` to each element. |
| `lent` | `(lent list)` | List length. |
| `welp` | `(welp a b)` | List concatenate (type-tolerant). |
| `weld` | `(weld a b)` | List concatenate (stricter — same element type). |
| `shax` | `(shax atom)` | SHA-256 hash → atom. |
| `mule` | `(mule |. expr)` | Run a trap; `[%.y val]` on success or `[%.n trace]` on crash. The crash-catcher. |

## Writing Hoon for vesl

Three places where you'll write Hoon, in order of how often you'll touch them.

### A New Domain Cause

The kernel handles `[%my-action ...]` by adding a state field, a cause variant, and a `?-` arm. Most apps live here. Walked on [Adding a Domain Cause](/build/kernel/causes).

### A Custom Peek Path

The kernel answers `[%my-query ...]` by walking your state and returning a `(unit (unit *))`. Walked on [Adding a Domain Peek](/build/kernel/peeks).

### A Replacement Verification Gate

Swap the default hash-comparison gate when you need Merkle manifests, signatures, or STARK proofs. Walked on [Replacing a Verification Gate](/build/kernel/gates).

Each `?-` arm has the same shape:

```
domain arm in the ?- switch
├── cause-tag         %issue-badge              matched by ?-
├── reads             subject.u.act             dotted-axis off u.act
├── reads/writes      state(badges <new>)       record update by name
├── (opt) gate-call   (verify-gate arg)         swappable verify-gate (commitment causes)
├── emits             ~[[%badge-issued n]]      a list of effect variants
└── returns           :_  state(...)  ~[...]    cell, tail-first: [(list effect) new-state]
```

For domain arms that thread state through more than one graft at once, [Coordinating Multiple Grafts in One Arm](/build/kernel/multi-graft) walks the `apply-<graft>` wet-gate pattern from `domain-patterns`.

## How a Poke Updates State

A nockapp kernel handles each poke as a pure transformation: `(cause, state)` in, `[effects new-state]` out. The whole `versioned-state` value is the kernel's memory. Pokes receive it by value, compute the next version, and return it as the tail-half of an `[effects new-state]` cell. The runtime takes that returned state and uses it for the next poke; subsequent pokes see the post-update value because the runtime holds the "current" pointer for you.

`versioned-state` is the type your kernel declares at the `nockup:state` marker — a tagged record listing every field the kernel knows about. Each graft adds the fields it owns there; your domain appends its own at the bottom.

In practice, "modifying" state means constructing a copy with the fields you want different. Hoon's `state(field new-value)` record-update syntax is the shorthand: a copy of `state` with one field replaced. It plays the role of `State { field: new-value, ..state }` in Rust. The modifications go at the start of the expression and the base goes inside the parens.

## Settle-Graft

`settle-graft` is the lowest-priority graft in the commitment family, so its arms top the `?-` (exhaustive switch) block in dispatch order.

| Graft | Priority |
|---|---|
| `settle` | 10 |
| `mint` | 20 |
| `guard` | 30 |
| `forge` | 40 |

Of the four it owns the fullest lifecycle: register a hull-id to a root (`%settle-register`), verify each payload through a swappable gate (`%settle-verify`), and record settled notes for replay protection (`%settle-note`). The other three are smaller-scope tiers (`mint-graft` registers a root with no verification, `guard-graft` adds a hash-leaf check, `forge-graft` generates a STARK proof over the hashing). settle is also the only graft whose poke body declares the gate splice point that lets a manifest swap the default verification gate via `[graft.gates]`; [Replacing a Verification Gate](/build/kernel/gates) walks the swap.

Each arm has its own success effect:

- **`%settle-register`** emits `[%settle-registered hull root]`. One-shot bind of a hull-id to a Merkle root. No gate is run. The `registered=(map @ @)` field is mutated; re-registering the same hull is rejected.
- **`%settle-note`** emits `[%settle-noted note=[id hull root [%settled ~]]]`. Verifies the payload through the active gate, then records the note-id in the `settled` set for replay protection. State mutates (`settled`, `settle-count`). When `settle-count` hits the per-epoch cap, the arm also emits `[%settle-epoch-rotated old-epoch new-epoch]` and rotates the active epoch before recording the note.
- **`%settle-verify`** emits `[%settle-verified ok=?]`. Soft preflight; leaves state unchanged. Runs the same verification path as `%settle-note` and reports whether a `%settle-note` with the same payload would succeed.

All three convert failure into `[%settle-error msg=@t]` rather than crashing.

## What's Out of Scope

Hoon as a general-purpose language is documented at [docs.urbit.org/hoon](https://docs.urbit.org/hoon). The patterns covered here and on the subpages handle almost everything a typical vesl nockapp writes; for deeper Hoon — runes, generics, mark types, the Hoon compiler's type system — go upstream.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

::: info See Also

- [vesl-nockup README — Add your own domain pokes](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#add-your-own-domain-pokes) — cause/state/arm walkthrough.
- [vesl-nockup README — Add your own peek paths](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#add-your-own-peek-paths) — domain peek-arm walkthrough.
- [vesl-nockup README — Replace the default verification gate](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#replace-the-default-verification-gate) — gate-replacement walkthrough.

:::

================================================================================
# Source: /build/kernel/causes.md
================================================================================

# Adding a Domain Cause

**After reading:** you'll add a `?-` arm to handle a new poke verb — state field, cause variant, arm body — and deny bad input without crashing the kernel.

A domain cause is a poke verb you handle in the kernel: the hull sends a tagged `[%my-action ...]` command; your arm in the `?-` switch reads cause fields, mutates state, and emits effects. Each cause typically touches three Hoon blocks at the `nockup:state`, `nockup:cause`, and `nockup:poke` markers: one state field (if needed), one cause variant, one `?-` arm.

## Anatomy

A cause arm has six structural concerns:

```
domain arm in the ?- switch
├── cause-tag         %issue-badge              matched by ?-
├── reads             subject.u.act             dotted-axis off u.act
├── reads/writes      state(badges <new>)       record update by name
├── (opt) gate-call   (verify-gate arg)         swappable verify-gate (commitment causes)
├── emits             ~[[%badge-issued n]]      a list of effect variants
└── returns           :_  state(...)  ~[...]    cell, tail-first: [(list effect) new-state]
```

Every `?-` arm follows this skeleton. The cause-tag selects the arm; the body reads cause fields off `u.act`, computes the new state, and returns the `[effects state]` cell.

## Worked Example

A **badge issuer** that increments a per-subject counter and emits `%badge-issued`:

```hoon
::  in versioned-state, after `settle=settle-state`:
badges=(map @ud @ud)
```

Walking the declaration:

- `badges` is the field name you pick.
- `(map @ud @ud)` is the type: a map from `@ud` keys to `@ud` values. `(map K V)` is the parametric map type.
- The whole `name=type` shape is the standard field declaration. The line goes at the `nockup:state` marker, inside `versioned-state`, after the graft state fields.

```hoon
::  in the cause $% union, alongside settle-cause:
[%issue-badge subject=@ud]
```

Walking the variant:

- `[%issue-badge subject=@ud]` is a cell. Head is the tag (`%issue-badge`, a symbol-style `@tas` atom); tail is one named field (`subject` typed `@ud`).
- The variant goes inside the `$%` tagged-union at the `nockup:cause` marker, alongside the graft cause-variants. `$%` is the tagged-union type constructor.
- Adding a variant here is the same idea as adding a variant to a Rust `enum`; the `?-` switch in `++poke` (below) is the exhaustive match over the tag.

```hoon
::  inside ?-, alongside the vesl arms:
  %issue-badge
=/  n=@ud  +((~(gut by badges.state) subject.u.act 0))
:_  state(badges (~(put by badges.state) subject.u.act n))
^-  (list effect)
~[[%badge-issued subject.u.act n]]
```

The arm runs when the cause's tag is `%issue-badge` and returns `[effects new-state]`. The idioms it uses:

- `?-` is an exhaustive switch on the cause's tag.
- `=/  n=@ud  <expr>` is a typed let-binding: declare `n` typed `@ud`, set it to the value of `<expr>`.
- `u.act` is the unwrapped cause cell; `subject.u.act` reaches the `subject` field by dotted-axis access.
- `~(arm core arg)` is Hoon's "invoke `arm` on `core` with `arg`" shape. `~(gut by m)` reads `m` with a key and a default; `~(put by m)` returns a new map with one entry replaced.
- `+(x)` is increment-by-one.
- `state(badges <new-map>)` is record-update syntax: a copy of `state` with `badges` swapped.
- `:_  X  Y` is a cell constructor that writes the tail-half first in source. It produces `[Y X]`, which is `NockApp`'s required `[effects state]` return shape.
- `^-  (list effect)` ascribes the type of the cell head that follows.
- `~[X]` is single-element list literal syntax.

The worked example is seven lines of custom Hoon for a one-argument cause (eleven for three-argument). Two of those are pure type declarations — the state field and the cause variant. The rest is the arm body.

## More Examples

Three more domain-cause shapes, beyond the badge issuer above.

### Bounded Counter

A single atomic state field with four arms that mutate it. Demonstrates conditional logic with `?:` and bounded decrement (no underflow).

```hoon
::  in versioned-state:
count=@ud
```

```hoon
::  in the cause $% union:
[%inc ~]
[%dec ~]
[%set n=@ud]
[%reset ~]
```

```hoon
::  inside ?-:
  %inc
:_  state(count +(count.state))
~[[%count-changed +(count.state)]]
::
  %dec
=/  new=@ud  ?:((gth count.state 0) (dec count.state) 0)
:_  state(count new)
~[[%count-changed new]]
::
  %set
:_  state(count n.u.act)
~[[%count-changed n.u.act]]
::
  %reset
:_  state(count 0)
~[[%count-changed 0]]
```

`?:  cond  then  else` is if-then-else; `gth` is "greater than"; `+(x)` is increment. The `%dec` arm clamps to zero rather than underflowing.

### Hash-and-Register

A name-keyed registry of content hashes with an entry counter. Demonstrates `(map @t @)` state, the SHA-256 primitive `shax`, and a multi-field state update.

```hoon
::  in versioned-state:
registry=(map @t @)
entries=@ud
```

```hoon
::  in the cause $% union:
[%register-doc name=@t data=@]
```

```hoon
::  inside ?-:
  %register-doc
=/  hash=@  (shax data.u.act)
=/  new-reg  (~(put by registry.state) name.u.act hash)
:_  state(registry new-reg, entries +(entries.state))
~[[%doc-registered name.u.act hash]]
```

`state(registry new-reg, entries +(entries.state))` is record-update by name with two fields at once. The arm hashes the payload, stores it under the supplied name, and bumps the entry counter in the same expression.

### Atomic Transfer

Moves an amount between two account keys with an overdraft guard. Demonstrates validation, conditional rejection emit, and an atomic two-key update.

```hoon
::  in versioned-state:
balances=(map @ @ud)
```

```hoon
::  in the cause $% union:
[%transfer from=@ to=@ amount=@ud]
```

```hoon
::  inside ?-:
  %transfer
=/  src=@ud  (~(gut by balances.state) from.u.act 0)
?:  (lth src amount.u.act)
  :_  state
  ~[[%transfer-rejected from.u.act 'insufficient']]
=/  dst=@ud  (~(gut by balances.state) to.u.act 0)
=/  b1  (~(put by balances.state) from.u.act (sub src amount.u.act))
=/  b2  (~(put by b1) to.u.act (add dst amount.u.act))
:_  state(balances b2)
~[[%transferred from.u.act to.u.act amount.u.act]]
```

The early `?:` returns `:_  state  ~[<rejection>]` (state unchanged, one rejection effect) when the source balance falls below the requested amount. The success path threads two `~(put by ...)` calls to build the updated balance map, then returns the final state with one `%transferred` effect.

## Conventions & Composing

### Arms share the ?- switch

The vesl-injected arms stay in place. Domain causes occupy new variants alongside them: the grafted arms (`%settle-register`, `%mint-commit`, etc.) implement primitives the kernel depends on, while your custom cause is app-specific behavior that extends the kernel's repertoire. Both kinds of arm live in the same `?-` switch as separate tag variants, so `%settle-register` and `%issue-badge` are routed by the same match.

This is forced by Hoon's type system: `?-` is an exhaustive switch over a single tagged union, and `cause` is exactly one such union, so every variant has to be an arm of the same switch. The Rust analogue is `match e: MyEnum`, which can't be split into two `match` expressions over disjoint subsets of variants because `e` has one type and the compiler wants one exhaustive match.

### Calling From Rust

The Rust side that calls this poke lives on the [Hull](/build/hull) page. `vesl-core` ships one `build_*_poke` helper per cause (`build_settle_register_poke`, `build_mint_commit_poke`, and so on); each takes typed Rust primitives (`u64`, `&Tip5Hash`, `&[u8]`) and returns a `NounSlab` ready to feed into `app.poke(SystemWire, slab).await`. The helpers exist because the raw noun-construction API has three footguns: long-tag encoding (vesl cause tags exceed the direct-atom limit and need indirect-atom construction), the `Bytes` re-export (so callers don't add `bytes` as a separate Cargo dep just to pass byte slices), and wide `u64` atoms (which need `atom_from_u64` rather than a direct constant). Reach for the helpers; the [Hull](/build/hull) page walks through what each one builds.

### Denying a Cause Without Crashing

When an arm needs to reject user-driven input (insufficient balance, missing permission, malformed payload), return a typed `[%<name>-error reason=@t]` effect with state unchanged — the `%transfer` arm above is the canonical shape. The kernel surfaces an `Accepted` outcome carrying the rejection effect, and the Rust hull pattern-matches on the head tag.

Bare `?>  <test>` is the wrong shape for user-input rejection. A failing `?>` raises an `Exit` mote, which the kernel propagates as a crash. `app.poke(...)` then returns `Ok(vec![])` with no effects rather than a typed `PokeOutcome::Rejected`, and the hull can't tell denial from graft error from runtime panic. Use `?>` only for invariants that hold by construction; reach for an explicit `?:` or `?.` branch when the test depends on caller input.

settle-graft wraps fallible Hoon in `(mule |.(<expr>))` to catch any `Exit` and emit `[%settle-error msg=@t]` — the typed-rejection shape, routed through the crash-catcher. Use that pattern only when the failing code can't be refactored to branch cleanly; the explicit-branch form is the default.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

::: info See Also

- [vesl-core → Committing Over Graft State](/reference/vesl-core#committing-over-graft-state) — the canonical pattern for a domain cause that builds a Merkle root over another graft's state (e.g. `%snapshot-root` arms that commit a tip5 root over `kv-graft` or `counter-graft` state in one poke).
- [Kernel → Coordinating Multiple Grafts in One Arm](/build/kernel/multi-graft) — threading state through several graft pokes from one domain cause via `apply-<graft>` helpers.
- [Hull → Peek-Then-Poke Gating](/build/hull#peek-then-poke-gating) — orchestrator-side admission pattern that pairs naturally with a domain cause.

:::

================================================================================
# Source: /build/kernel/peeks.md
================================================================================

# Adding a Domain Peek

**After reading:** you'll add a read-only peek path that walks state and returns `(unit (unit *))` cleanly — value-present, value-absent, and path-unknown all distinguished.

A peek is the kernel's read-only entrypoint: the hull asks "what's at this path?" and the kernel walks state to answer, without mutating anything. `nockup graft inject` wires graft peek arms into a chain inside `++peek`; your domain arm sits at the tail.

## Anatomy

A peek arm has three structural concerns:

```
peek arm in ++peek's chain
├── path-guard   ?.  ?=([%my-tag ...] path)      match the path shape, ~ on miss
├── reads        ~(get by m.state), i.t.path     map gets, dotted-axis (no writes)
└── returns      [~ ~]  or  ``value              miss vs hit (see Conventions)
```

Every peek arm follows this skeleton. The path-guard runs first; if the path doesn't match, the arm returns `~` and the next arm in the chain tries. If it matches, the body reads state and returns one of two value shapes.

## Worked Example

A `[%artifact-by-name @t ~]` lookup against an `artifacts=(map @t artifact-meta)` state field:

```hoon
::  inside ++peek, below the vesl peek chain:
?.  ?=([%artifact-by-name @t ~] path)
  ~
=/  got  (~(get by artifacts.state) i.t.path)
?~  got  [~ ~]
``u.got
```

Walking the arm top-to-bottom:

- `?.  ?=([%artifact-by-name @t ~] path)  ~` — if `path` doesn't pattern-match `[%artifact-by-name @t ~]`, return `~` to defer to the next arm. `?=` is type-pattern match; `?.` is if-not.
- `=/  got  (~(get by artifacts.state) i.t.path)` — typed let-binding. `~(get by m)` is the map's get, returning `(unit value)`. `i.t.path` is dotted-axis access: `t.path` is the tail of `path`, `i.t.path` is the head of that tail (i.e., the `@t` name from the path).
- `?~  got  [~ ~]` — if `got` is null (key not in map), return `[~ ~]` ("path recognized, no value").
- `` ``u.got `` — value case. `u.got` unwraps the unit; the double-backtick wraps it as `[~ ~ value]`.

## More Examples

Three more peek shapes beyond the single-key lookup above.

### Bare Path

The simplest peek: a one-element path returning a scalar. Common for counters and toggle flags.

```hoon
::  inside ++peek, below the vesl peek chain:
?.  ?=([%entries ~] path)
  ~
``entries.state
```

The path matches `[%entries ~]` (one tag, then null-terminator). The double-backtick wraps `entries.state` into the `[~ ~ value]` success shape.

### List All Keys

Returns the entire key-set of a map-valued state field as a list. Useful for enumeration queries.

```hoon
::  inside ++peek:
?.  ?=([%names ~] path)
  ~
``~(tap in ~(key by artifacts.state))
```

`~(key by m)` returns the map's keys as a `set`; `~(tap in s)` flattens a set into a list. If `artifacts` is `(map @t _)`, the result is `(list @t)`.

### Multi-Arg Path

A path with two named segments, useful for state keyed by compound tuples (for example, `balances=(map [@ @tas] @ud)`).

```hoon
::  inside ++peek:
?.  ?=([%balance @ @tas ~] path)
  ~
=/  owner=@     i.t.path
=/  asset=@tas  i.t.t.path
=/  got  (~(get by balances.state) [owner asset])
?~  got  [~ ~]
``u.got
```

`i.t.path` reaches the first arg (head of tail); `i.t.t.path` reaches the second arg (head of tail-of-tail). The tuple `[owner asset]` is the compound key passed to `~(get by ...)`.

On the Rust side, multi-arg peeks don't have a shipped `build_*` helper today. You hand-roll the noun list yourself; see [vesl-core → Driving rbac-graft](/reference/vesl-core#driving-rbac-graft) for the canonical example (`[%rbac-has-perm pubkey perm ~]` constructed by hand). The three builders enumerated below in **Calling From Rust** cover the single-arg cases.

## Conventions & Composing

### The `(unit (unit *))` return shape

`++peek` returns `(unit (unit *))`: a unit wrapping a unit wrapping any noun. The double-wrap exists because two questions need separate answers:

- **Outer unit.** "Did any arm in the chain recognize this path?" `~` means no; `[~ <inner>]` means yes.
- **Inner unit.** "Did the recognizing arm find a value?" `~` (the head of `[~ ~]`) means no; `[~ <value>]` means yes.

That gives three concrete shapes:

- **`~`** — "this path is not for me, let the next arm try." Use on any path your arm doesn't recognize.
- **`[~ ~]`** — "I recognize this path, but there is no value at it." The standard map-lookup miss.
- **`` ``x ``** — shorthand for `[~ ~ x]`, "I recognize this path and the value is `x`." `x` must be a noun.

### Dispatch order

`nockup graft inject` chains every graft's peek arm via `~` fallthrough. Each `?.  ?=(...) ~` guard is one arm; if it returns `~`, control falls through to the next. Your domain arm sits at the tail, after every graft arm has had a chance to claim the path.

### Calling From Rust

vesl-core ships three peek-path builders for the Rust hull:

- `build_hull_peek_path(tag, hull)` — for hull-keyed peeks like `[%settle-registered hull ~]`.
- `build_keyed_peek_path(tag, key)` — for cord-keyed peeks against state grafts like `[%kv-value "greeting" ~]`.
- `build_keyless_peek_path(tag)` — for zero-arg peeks like `[%log-len ~]`.

Plus three decoders for the return cell:

- `peek_loobean(result)` — decodes a boolean response.
- `peek_atom_u64(result)` — decodes a numeric atom.
- `peek_unit_list<T>(result, decoder)` — decodes a unit-wrapped list.

The [Hull](/build/hull) page walks the full caller shape; builders and decoders live in `vesl-core/src/peek.rs`.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

================================================================================
# Source: /build/kernel/gates.md
================================================================================

# Replacing a Verification Gate

**After reading:** you'll swap the default hash gate for a signature, Merkle, set-membership, or bounded-value check via one `[graft.gates]` line — no Hoon edits.

A verification gate is the boolean check inside each `%settle-*` arm that decides whether a payload is acceptable. The default ships from `nockup graft inject` and tip5-hashes the payload bytes for equality against the registered root; richer checks (Merkle manifests, signatures, STARK proofs) need a replacement gate body.

## Anatomy

A gate body has six structural concerns:

```
verify-gate (inline replacement)
├── declaration     =/  gate=verify-gate                      let-binding with type
├── signature       |=  [note-id=@ data=* expected-root=@]    three named atoms
├── return cast     ^-  ?                                     loobean (%.y / %.n)
├── safe extract    ;;(<type> data) in (mule |.<body>)        crash-safe data extraction
├── (opt) binding   =((hash-leaf <key>) expected-root)        tie payload to registered key
└── verify          verify-chunk / signature / range / ..     actual verification logic
```

Every gate body follows this skeleton. The signature (`|=` plus the return cast) is fixed by the `verify-gate` type; everything else varies. The crash-safety idiom is `;;`-inside-`mule`: the soft-cast would crash on malformed `data`, and wrapping in `mule` converts that crash to `%.n`.

## Worked Example

Replace the gate body inside each `%settle-*` arm:

```hoon
=/  hash-gate=verify-gate
  |=  [note-id=@ data=* expected-root=@]
  ^-  ?
  (my-custom-verify note-id data expected-root)
```

Walking the replacement:

- `=/  hash-gate=verify-gate  <expr>` — typed let-binding: declare `hash-gate` of type `verify-gate`. `verify-gate` is `$-([note-id=@ data=* expected-root=@] ?)`, a gate that takes three named atoms and returns a loobean.
- `|=  [note-id=@ data=* expected-root=@]` — gate declaration. `|=  sample  body` defines a function whose argument tuple is `sample`. `*` (in `data=*`) is the any-noun type, so `data` accepts whatever shape the Rust side jammed into the payload.
- `^-  ?` — cast the gate's return type to `?` (Hoon's loobean: `%.y` true, `%.n` false).
- `(my-custom-verify note-id data expected-root)` — function call. Parentheses are how you invoke a gate with arguments.

Two design points the shape encodes:

- `note-id` is bound deliberately. Domain gates can enforce `note-id == deterministic-fn(data)`, closing the pre-commit race.
- `data` arrives as `*` (any noun). Cast it with `;;(<type> data)` before using (e.g., `;;(manifest data)`, `;;(my-intent data)`).

## More Examples

Three gate shapes from the named-gate catalog, simplified to show the binding pattern.

### Set Membership

The payload is `[elem proof]`; the gate verifies `elem`'s Merkle path resolves to the registered root. Used for allowlists, voter rolls, blocklists.

```hoon
::  replacement gate body in a %settle-* arm:
=/  set-gate=verify-gate
  |=  [note-id=@ data=* expected-root=@]
  ^-  ?
  =/  attempt
    %-  mule  |.
    =/  p=[elem=@ proof=(list [hash=@ side=?])]
      ;;([elem=@ proof=(list [hash=@ side=?])] data)
    (verify-chunk elem.p proof.p expected-root)
  ?:  ?=(%| -.attempt)  %.n
  p.attempt
```

`;;(<type> data)` is a soft-cast: it stamps `data` (a raw `*` noun) with the named type, crashing the gate if the shape doesn't match. The body is wrapped in `(mule |.<body>)` so a malformed `data` returns `%.n` rather than crashing the kernel.

### Bounded Value

The payload is `[value bounds proof]`; the gate confirms `value` lies in `[lo, hi]` AND its Merkle path checks against the root. Used for age gates, balance brackets, score windows.

```hoon
::  replacement gate body:
=/  range-gate=verify-gate
  |=  [note-id=@ data=* expected-root=@]
  ^-  ?
  =/  attempt
    %-  mule  |.
    =/  p=[value=@ bounds=[lo=@ hi=@] proof=(list [hash=@ side=?])]
      ;;([value=@ bounds=[lo=@ hi=@] proof=(list [hash=@ side=?])] data)
    ?&  (gte value.p lo.bounds.p)
        (lte value.p hi.bounds.p)
        (verify-chunk (jam [value.p bounds.p]) proof.p expected-root)
    ==
  ?:  ?=(%| -.attempt)  %.n
  p.attempt
```

`?&` is short-circuiting logical AND. The leaf hashed for the Merkle check is `(jam [value bounds])`. Value and bounds are committed together so a caller cannot substitute their own range over an attested value.

### Signature

The payload is `[data sig pubkey]`; the gate checks the signature is valid AND the registered root commits to that pubkey. Used for off-chain attestations, signed timestamps.

```hoon
::  replacement gate body:
=/  sig-gate=verify-gate
  |=  [note-id=@ data=* expected-root=@]
  ^-  ?
  =/  attempt
    %-  mule  |.
    =/  p=[data=@ sig=@ pubkey=@]
      ;;([data=@ sig=@ pubkey=@] data)
    ?&  =((hash-leaf pubkey.p) expected-root)
        (veri:ed:crypto sig.p data.p pubkey.p)
    ==
  ?:  ?=(%| -.attempt)  %.n
  p.attempt
```

The binding `expected-root == hash-leaf(pubkey)` is what stops the gate from degenerating into a pure oracle. The registered root IS the public key's leaf-hash, so the gate enforces that the signature came from that specific registered key.

## Conventions & Composing

### Selecting via manifest

Five named gates ship in `vesl-gates.hoon` and are selectable per-graft via `[graft.gates] gate = "..."` in a manifest: `sig-verify-ed25519`, `sig-verify-schnorr`, `manifest-verify`, `set-membership-verify`, `bounded-value-verify`. The composer splices the selected gate into each `%settle-*` arm at inject time, replacing the default hash-comparison body. To swap a selection mid-project, change the manifest line and re-run `nockup graft inject --apply`; the composer detects manifest drift via the sha256 in each begin-banner and re-injects from the new gate.

### Where gates run

The gate fires inside `%settle-note` (active verification) and `%settle-verify` (side-effect-free preflight). `%settle-register` binds a hull-id to a root without invoking a gate.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

================================================================================
# Source: /build/kernel/multi-graft.md
================================================================================

# Coordinating Multiple Grafts in One Arm

**After reading:** you'll use `apply-<graft>` wet-gates from `domain-patterns` to chain pokes through several grafts from one domain arm — three lines per step, not nine.

When a domain arm threads state through more than one graft (increment a counter, write to `kv`, append to the audit log), the hand-coded shape gets repetitive. `vesl-core` ships a small library, `domain-patterns`, with `apply-<graft>` wet-gates that bundle each graft's three-line poke shape into a single line:

```hoon
::  near the top of your app.hoon, alongside the other /+ lines:
/+  *domain-patterns
```

Walking the import:

- `/+` is Hoon's import rune: import a named library from `hoon/lib/`.
- The `*` prefix on the library name pulls all exposed names into the subject (`*domain-patterns` vs. selective import like `/+  domain-patterns`).
- `domain-patterns` is the library — it lives at `hoon/lib/domain-patterns.hoon`.

## Composing Two Graft Arms in One Domain Cause

This is the pattern `nockup graft inject` warns about when its `weld-friction` lint fires (see [CLI → weld-friction](/reference/cli#weld-friction)). When one domain cause needs to drive two grafts in a defined order — writing to `kv` then logging the change, or incrementing a counter then settling a note — you thread the post-state of one graft into the next via the `apply-<graft>` helpers in `domain-patterns`.

A worked arm that fans a single domain cause out to three grafts — assuming the cause variant is `[%record-event name=@t]`:

```hoon
::  inside ?-, a %record-event arm that increments a counter,
::  writes to kv, and appends to the audit log:
  %record-event
=^  efx-c  state  (apply-counter [%counter-increment 'events'] state)
=^  efx-k  state  (apply-kv [%kv-set name.u.act 1] state)
=^  efx-l  state  (apply-log [%log-append name.u.act] state)
:_  state
^-  (list effect)
(welp efx-c (welp efx-k efx-l))
```

Walking the arm:

- `%record-event` is the cause tag this arm matches.
- `=^  efx-c  state  (apply-counter ...)` is the threading rune. It evaluates the expression, binds the head of the returned cell to `efx-c` (the counter's effects list), and rebinds `state` to the tail (the post-counter state). The next line sees the updated `state`.
- Each `apply-<graft>` call takes the graft's cause noun and the current `state`, internally routes through the underlying `<graft>-poke` arm, and returns `[effects new-state]`.
- After three `=^` lines, `state` reflects all three graft updates and each `efx-*` binding holds that graft's effect list.
- `(welp efx-c (welp efx-k efx-l))` concatenates the three lists into the single `(list effect)` the arm returns. `welp` is list concatenation; the nested call performs a three-way concat.
- `:_  state` returns `[effects state]` in `NockApp`'s required `[effects new-state]` shape.
- `^-  (list effect)` ascribes the head's type.

Each `apply-<graft>` takes `[cause versioned-state]` and returns `[(list <graft>-effect) versioned-state]`, suitable for direct `=^` binding. See [`hoon/lib/domain-patterns.hoon`](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/hoon/lib/domain-patterns.hoon) for the full helper list.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

================================================================================
# Source: /build/hull.md
================================================================================

# Hull

**After reading:** you'll build pokes, parse effects, dodge the four noun footguns, and know when to opt into compile-time drift detection vs. hand-roll a cause without a builder.

The hull is the Rust side of your nockapp — the program in `src/main.rs` that boots `out.jam` as a `NockApp`, sends pokes, and reads effects back. Most of the noun construction is done for you by `vesl-core`'s `build_*_poke` helpers; you write the orchestration.

::: info Before We Start

Three terms used throughout:

- **Atom** — a non-negative integer. Hoon's primitive scalar type. Auras (`@t`, `@ud`, `@tas`, …) annotate how to read an atom — UTF-8 cord, decimal number, lowercase symbol — without changing the underlying value.
- **Noun** — the universal value type in Nock and Hoon. Either an atom or a *cell* (an ordered pair of two nouns). Every value a kernel handles — state, causes, effects — is a noun.
- **NounSlab** — the Rust noun container. A hull allocates nouns into a slab, builds the poke head and arguments inside it, then submits the slab to the kernel via `app.poke(...)`. Defined at `nockapp::noun::slab::NounSlab`.

All three have full entries in [Reference / Glossary](/reference/glossary).

:::

```d2
direction: right

hull1: hull {
  A: "build_*_poke(args)\n→ NounSlab (cause)"
}

kernel: kernel hop {
  B: "app.poke(SystemWire, slab).await\n→ Vec<NounSlab> (effects)"
}

hull2: hull {
  C: "effect_head_tags(&effects)\n→ [\"settle-registered\", ...]"
}

hull1.A -> kernel.B
kernel.B -> hull2.C
```

## The Shape of a Hull

A hull boots the compiled kernel via `nockapp::kernel::boot::setup`, sends pokes with `app.poke(SystemWire, slab).await`, and reads back the effect list the kernel returns. The canonical shape is walked in [Quickstart / Exercise the Lifecycle](/setup/quickstart#_5-exercise-the-lifecycle); the rest of this page covers the patterns inside it.

## Scaffold CLI: Demo and Serve

The `vesl` template's `src/main.rs` is a clap dispatch with two arms. Both boot `out.jam` and pass the booted `NockApp` to the selected arm:

- **`cargo run`** — Demo arm (default): the canonical lifecycle from the quickstart, run once.
- **`cargo run -- serve`** — Serve arm: mounts the [`vesl-hull`](https://github.com/zkvesl/vesl-nockup/tree/main/crates/vesl-hull) HTTP API on `http://127.0.0.1:3000`.

`vesl-hull` is a vesl-nockup-native lib factored from vesl-core/hull. Mount your own routes by passing them to `vesl_hull::serve_with_extra_routes` (or `vesl_hull::router_with_extra` for the assembled `axum::Router`) — not `Router::merge`, which attaches custom routes outside the hull's auth, body-size, and rate-limit layers. The hull's body-size cap runs in two layers: an upfront `Body::size_hint` precheck (catches every known-length body — in-process `Body::from(Vec<u8>)` and wire requests whose `Content-Length` axum's parser propagated into the body) plus tower-http's streaming `RequestBodyLimitLayer` (catches chunked or unknown-length bodies as the handler reads them). See [Composing Custom Routes](/build/build-run/serve#composing-custom-routes). The Serve arm's full surface — `--port` / `--bind-addr` / `--no-auth` flags, the `HULL_API_KEY` auth model, the endpoint catalog, and custom-router composition — lives on [Build & Run / Serve Subcommand](/build/build-run/serve).

These handlers assume the kernel composes settle-graft — they build `%register`, `%settle-note`, and `%settle-verify` pokes. A kernel without settle-graft will reject those pokes; either delete the unused handlers from a fork of `crates/vesl-hull/src/api/handlers/`, or merge only `/health` and `/status` into a custom router.

## Poke Builders

`vesl-core` ships one `build_*_poke` helper per shipped graft cause. Each takes typed Rust primitives in and returns a ready-to-poke `NounSlab` out:

```rust
use vesl_core::{
    Mint, Tip5Hash,
    build_settle_register_poke, build_settle_note_poke, build_settle_verify_poke,
};

let mut mint = Mint::new();
let root: Tip5Hash = mint.commit(&[b"first"]);

let register = build_settle_register_poke(1, &root);
let note     = build_settle_note_poke(1, 1, &root, b"first");
let verify   = build_settle_verify_poke(1, 1, &root, b"first");
```

The three signatures don't share an argument count: `register` is `(hull, &root)`, `note` and `verify` are both `(note_id, hull, &root, data)`. The verify path takes the same 4-arg shape as `note`; extrapolating from `register`'s 2-arg form produces a `mismatched arguments` compile error.

`Tip5Hash` is `pub type Tip5Hash = [u64; 5]`: a tip5 digest of five Goldilocks field-element limbs (each `u64` below the Goldilocks prime `2^64 - 2^32 + 1`). The shape matches Hoon's `noun-digest:tip5 = [@ @ @ @ @]`. `Mint::commit` returns one; the `build_settle_*_poke` family takes one by reference; `build_mint_commit_poke(hull, root)` drives the `%mint-commit` arm with the same digest. Convert to a 40-byte little-endian slice via `vesl_core::tip5_to_atom_le_bytes` when raw bytes are needed.

The full set covers settle, mint, guard, forge, plus state and behavior grafts (`build_kv_set_poke`, `build_counter_increment_poke`, `build_log_append_poke`, etc.). The mint family is one builder (`build_mint_commit_poke`); guard is two (`build_guard_register_poke`, `build_guard_check_poke`); settle's six per-gate variants follow the `build_settle_note_<gate>_poke` pattern. The full per-graft list is in [Domain Pokes](/build/testing/domain-pokes); the module tree under [`crates/vesl-core/src/graft_pokes/`](https://github.com/zkvesl/vesl-core/tree/11d110d/crates/vesl-core/src/graft_pokes) is the source-of-truth.

For grafts that store structured data (`registry`, `log`, `queue`, `batch`), use the paired `_from_noun` helper to jam the payload internally rather than passing a raw `&[u8]`:

```rust
let mut record = NounSlab::new();
record.set_root(your_noun);
let slab = build_registry_put_poke_from_noun(key, &record);
```

The byte-taking variants (`build_registry_put_poke(key, &jammed_bytes)`) trust the caller to have already jammed the payload.

## Sending Pokes

```rust
let effects = app.poke(SystemWire.to_wire(), slab).await?;
```

`SystemWire` is the standard wire identity for system-level pokes. The poke is async; `app.poke` returns `Vec<NounSlab>` — the kernel's effect list, one effect per element.

## Parsing Effects

```rust
for tag in vesl_core::effect_head_tags(&effects) {
    println!("  effect: %{tag}");
}
```

`effect_head_tags` walks each effect noun and pulls the head atom as a string. For typed effect decoding beyond the head tag, see `vesl_core::effect_head_tag` (singular) and the per-graft `decode_*_effect` helpers in the source.

## Decoding Effect Payloads

Once you've matched on the head tag, you have to extract the rest of the effect cell. Three payload shapes recur across shipped grafts; each has a footgun.

### Loobean tails — `%guard-checked ok=?`, `%settle-verified ok=?`

These effects ship a loobean as the second cell field. Loobean polarity is inverted relative to Rust: in Hoon, `%.y` (yes) is the atom `0` and `%.n` (no) is the atom `1`. When you destructure a `%guard-checked` or `%settle-verified` effect, the `ok=` field is an atom — flip it before treating it as a Rust `bool`.

```rust
// Effect noun: [%guard-checked hull=@ ok=@]
// ok atom == 0  →  guard passed
// ok atom == 1  →  guard rejected
let passed = ok_atom == 0;
```

The inversion is footgun #4 in [The Four Noun Footguns](#the-four-noun-footguns) below. If your decoder reads the atom and treats `1` as `true`, every passing guard will look like a failure and every failing guard will look like a pass.

### Cell payloads — `%settle-noted`, `%batch-flushed`, `%registry-updated`

Most domain-success effects carry a structured payload. The shapes are enumerated per-graft in [Effect Catalog](/reference/effect-catalog). Examples:

| Effect | Payload shape |
|---|---|
| `%settle-noted` | `note=[id=@ hull=@ root=@ state=[%settled ~]]` |
| `%batch-flushed` | `bundle=(list *) count=@ud` |
| `%registry-updated` | `[key=@ old=* new=*]` |

To extract a field, descend through the noun with `head`/`tail` axis access or pattern-matched destructuring; the catalog page gives the exact shape per effect.

### Unit returns from peeks — `[~ ~]` vs `[~ [~ value]]`

`harness.peek_handle(path)` collapses the standard two-level unit shape: `Ok(None)` for `[~ ~]`, `Ok(Some(slab))` for `[~ [~ value]]`, and `Err` for bare `~` (unknown path). A subset of peeks ship as `(unit (unit *))` — `%settle-root`, `%mint-commit`, `%kv-value`, `%registry-entry`, `%counter-value`, `%log-by-seq` — to distinguish "path recognized, value absent" from "path recognized, value present". Use `harness.peek_raw(path)` for those; see [Testing → Domain Pokes → peek_raw](/build/testing/domain-pokes#peek-raw-nested-unit-paths). The [Peek Catalog](/reference/peek-catalog) marks each path's return shape.

## Peek-Then-Poke Gating

When two grafts must coordinate at the hull layer — most commonly an rbac-graft permission check before a downstream poke — the pattern is peek-then-poke:

1. Build the peek path for the gating graft (e.g. `[%rbac-has-perm pubkey perm ~]`).
2. Send the peek; receive `Some(true)`, `Some(false)`, or `None`.
3. Branch: on `Some(true)` proceed with the downstream poke; on `Some(false)` or `None` skip the poke (or surface a denial from the hull driver, if you want the caller to see one).

```rust
use vesl_core::{build_registry_put_poke, peek_loobean};
// build_rbac_has_perm_path is hand-rolled — see vesl-core / Driving rbac-graft
// for the full noun-slab construction. Multi-arg peek paths don't have a
// shipped builder today.

let perm_slab = build_rbac_has_perm_path(caller_pubkey, "registry-put");
let result = harness.peek_slab(perm_slab).await?;

match peek_loobean(&result) {
    Some(true) => {
        let outcome = harness.poke_slab(build_registry_put_poke(key, &record)).await?;
        // proceed — outcome is a typed vesl_core::PokeOutcome
    }
    Some(false) | None => {
        // skip: caller lacks the perm. No state change, no effect.
    }
}
```

The denial is silent from the kernel's perspective — the downstream poke never lands, so no `%registry-error` is emitted. If you want the caller to see a denial, surface one from the hull driver before returning.

`peek_loobean` (not a generic unit-unwrap) is the right decoder for an `ok=?` tail; the latter collapses atom-0 (`%.y`) onto the absent-value boundary. See [vesl-core → Driving rbac-graft](/reference/vesl-core#driving-rbac-graft) for the full hand-rolled peek-path construction and [Kernel → Domain Peeks → Multi-Arg Path](/build/kernel/peeks#multi-arg-path) for the path shape.

This pattern composes: stack two peeks before a poke, or pair it with a validate-graft rule (see [Common Pitfalls → Composing Three Denials](/troubleshooting/common-pitfalls#composing-three-denials-stacked-admission)).

## The Four Noun Footguns

The four rules `nock-noun-rs` exists to handle. Read [`nock-noun-rs/README.md`](https://github.com/zkvesl/vesl-core/blob/main/crates/nock-noun-rs/README.md) for the full exposition; the short list:

- **Long tags** (> 8 bytes) panic at compile time under `D(tas!(b"…"))`. Use `Atom::from_bytes(slab, &Bytes::copy_from_slice(b"…"))` for anything from `settle-register` upward.
- **Wide `u64` values** (hashes, IDs where the top bit may be set) panic at runtime under `D(value)` with `Number is greater than DIRECT_MAX`. Route them through `atom_from_u64(slab, value)`.
- **`AtomExt::from_bytes` takes `&bytes::Bytes`**, not `&[u8]` — via the `nockapp::Bytes` re-export.
- **Loobeans are inverted relative to Rust booleans.** Hoon's `%.y` (yes) is atom `0`; `%.n` (no) is atom `1`. Convert at the boundary, not inline.

## Hull/Kernel Drift Detection

Drift detection is opt-in. From a hull's `build.rs`, run `nockup graft codegen kernel-cause-tags <PATH>` after `hoonc`. The codegen writes `kernel_cause_tags.rs` to `OUT_DIR` and exposes its path as `KERNEL_CAUSE_TAGS_PATH`. Include the file in your hull and assert each cause tag at compile time:

```rust
include!(env!("KERNEL_CAUSE_TAGS_PATH"));

fn build_settle_register_poke(hull: u64, root: &Tip5Hash) -> NounSlab {
    assert_kernel_cause_tag!("settle-register");
    // ... construct the noun ...
}
```

`assert_kernel_cause_tag!` runs at compile time. A kernel rename (e.g. `%settle-register` → `%settle-write`) regenerates the slice on the next `cargo build`; the stale `"settle-register"` literal in the hull then fails the membership check and `cargo build` halts:

```text
error[E0080]: evaluation of constant value failed
  --> src/hull.rs:12:5
   |
12 |     assert_kernel_cause_tag!("settle-register");
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |     |
   |     the evaluated program panicked at 'cause tag `settle-register` not
   |     in KERNEL_CAUSE_TAGS — re-run `nockup graft codegen kernel-cause-tags`
   |     and check the driver's poke builder against the kernel's cause $%.'
   |
   = note: this error originates in the macro `assert_kernel_cause_tag`
```

The drift is surfaced as a compile error instead of a silent `Ok(vec![])` from `app.poke(...)` at runtime.

`KERNEL_CAUSE_TAGS` is derived by parsing the `+$ cause` arm in the composed `app.hoon`. Two consequences:

- **Domain causes are covered.** Inline variants you added directly to your domain (`%submit-artifact`, `%emit-license`, etc.) show up in `KERNEL_CAUSE_TAGS`. `assert_kernel_cause_tag!("submit-artifact")` compiles. Kernel rename → hull compile error, same way as graft-side renames.
- **Inactive grafts contribute nothing.** A graft sitting under `hoon/lib/` but never referenced from `+$ cause $%(...)` doesn't pollute the slice with its tags.

The default `vesl` template's `build.rs` runs the `nockup-graft doctor` health pass, not the cause-tag codegen; the `graft-*` templates wire the codegen call and surface a `cargo:warning` when `nockup-graft` is missing or codegen fails. Either way, gate `include!(env!("KERNEL_CAUSE_TAGS_PATH"))` with `cfg(env_var = "KERNEL_CAUSE_TAGS_PATH")` so the hull stays buildable when the env var is unset; the guarded include is then skipped.

## Hand-Rolled Causes

When you have a domain cause without a builder yet, construct the noun manually:

```rust
use nockapp::{AtomExt, Bytes, NockApp, noun::slab::NounSlab, wire::{SystemWire, Wire}};
use nockvm::noun::{Atom, T};
use nock_noun_rs::atom_from_u64;

async fn issue_badge(app: &mut NockApp, subject: u64) -> anyhow::Result<()> {
    let mut slab = NounSlab::new();
    let tag  = Atom::from_bytes(&mut slab, &Bytes::copy_from_slice(b"issue-badge")).as_noun();
    let subj = atom_from_u64(&mut slab, subject);
    let noun = T(&mut slab, &[tag, subj]);
    slab.set_root(noun);
    let _ = app.poke(SystemWire.to_wire(), slab).await?;
    Ok(())
}
```

The pattern generalizes: one atom per cause field, then `T(&mut slab, &[tag, arg1, arg2, ...])`.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

::: info See Also

- [Build & Run / Serve Subcommand](/build/build-run/serve) — the Serve arm's full surface (flags, auth, endpoint catalog, custom routes).
- [vesl-nockup README — Serving over HTTP](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#serving-over-http) — scaffold-level overview of the `Serve` arm.
- [`crates/vesl-hull/`](https://github.com/zkvesl/vesl-nockup/tree/main/crates/vesl-hull) — the lib backing the `Serve` arm (factored from vesl-core/hull as a vesl-nockup-native crate).
- [`tools/graft-inject/tests/mint_lifecycle.rs`](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/tools/graft-inject/tests/mint_lifecycle.rs) — full lifecycle as a Rust integration test.
- [`crates/vesl-core/src/lib.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/lib.rs#L1-L40) — the four primitives and the poke-builder map.

:::

================================================================================
# Source: /build/catalog-gates/index.md
================================================================================

# Catalog Gates from Rust

A verification gate is a Hoon function with type signature `$-([note-id=@ data=* expected-root=@] ?)`. It returns a loobean stating whether the caller's `data` is bound to `expected-root`. Commitment grafts (settle-graft canonically) accept a gate as a parameter; the choice of gate determines what the commitment-and-verify cycle actually proves.

The default gate is a single-leaf hash comparison baked into settle-graft's poke body. Five named gates ship in [`vesl-gates.hoon`](https://github.com/zkvesl/vesl-core/blob/11d110d/protocol/lib/vesl-gates.hoon) for richer cases. This page covers driving each from Rust.

::: tip Gate selection
The gate is picked in the manifest via `[graft.gates]`. See [Grafts / Manifest Schema — Gate Selection](/build/grafts/manifest-schema#graft-gates-gate-selection) for the selection contract and the splice-point requirement.
:::

::: info Related pages
- [Gate Chains](/build/catalog-gates/gate-chains) — AND-folding multiple gates in `[graft.gates].gate-chain`.
- [Swapping a Gate](/build/catalog-gates/swapping) — manifest edit + re-inject + verification steps.
- [Custom Gates](/build/catalog-gates/custom-gates) — using a gate outside the shipped catalog.
:::

## The Default Hash Gate

With no `[graft.gates]` block, settle-graft uses a single-leaf hash gate: it treats `data` as a single atom and binds `expected-root = hash-leaf(data)`. From Rust:

```rust
// Example: default hash-gate flow
use vesl_core::{Mint, build_settle_register_poke, build_settle_note_poke};

let mut mint = Mint::new();
let payload: &[u8] = b"single-leaf payload";
let root = mint.commit(&[payload]);                // hash-leaf(payload)

let register = build_settle_register_poke(1, &root);
let note     = build_settle_note_poke(42, 1, &root, payload);
// app.poke(register) → [%settle-registered 1 root]
// app.poke(note)     → [%settle-noted note=[42 1 root [%settled ~]]]
```

The bytes registered as the root and the bytes submitted on `%settle-note` must match. Anything else makes the gate return `%.n`, the arm's `?>` crashes deterministically (preserving STARK unprovability), and the hull observes `Ok(vec![])`. The [Distinguishing Denial Paths](/troubleshooting/common-pitfalls#distinguishing-denial-paths) entry maps the surface.

## Schnorr Signing — End-to-End

`sig-verify-schnorr` binds `expected-root = hash-leaf(pubkey)` and verifies a Schnorr signature over `data` from that pubkey. The Rust driver assembles the payload, signs, registers the pubkey hash as the root, then submits a note that pre-commits to the signed bytes.

```rust
// Example: full Schnorr-signed settle cycle
use vesl_core::{build_settle_register_poke, build_settle_note_schnorr_poke};
use vesl_core::signing::{
    derive_pubkey, key_from_seed_phrase, pubkey_hash,
    schnorr_message_digest_for_data, sign,
};

// 1. Derive a Schnorr keypair.
let sk = key_from_seed_phrase("...")?;
let pk = derive_pubkey(&sk);

// 2. Register the pubkey hash as the hull's root.
let root = pubkey_hash(&pk);
let _ = app.poke(SystemWire.to_wire(), build_settle_register_poke(1, &root)).await?;

// 3. Sign the payload bytes against their tip5 digest.
let data: &[u8] = b"attested claim";
let digest = schnorr_message_digest_for_data(data);
let sig = sign(&sk, &digest)?;

// 4. Submit a %settle-note with [data sig pubkey] as the data cell.
let poke = build_settle_note_schnorr_poke(42, 1, &root, data, &sig, &pk);
let _ = app.poke(SystemWire.to_wire(), poke).await?;
// → [%settle-noted note=[42 1 root [%settled ~]]]
```

The pubkey is the trust anchor: a kernel that registered `hash-leaf(pubkey_A)` rejects any signature from pubkey_B (the gate's first AND-clause is `=((hash-leaf pubkey) expected-root)`). The signature binds the same `data` the gate `;;`-casts internally.

## ed25519

`sig-verify-ed25519` has the same shape as Schnorr but uses ed25519 signatures. vesl-core ships no ed25519 signing primitive; produce `sig` and `pubkey` with your own ed25519 stack (e.g., `ed25519-dalek`) and pass them as flat byte slices:

```rust
// Example: ed25519 settle-note (sig + pubkey from an external library)
use vesl_core::build_settle_note_ed25519_poke;

let poke = build_settle_note_ed25519_poke(
    42, 1, &root,
    data,                    // &[u8]
    sig_bytes,               // &[u8]  — 64-byte signature
    pubkey_bytes,            // &[u8]  — 32-byte pubkey
);
```

The same binding holds: `expected-root = hash-leaf(pubkey_bytes)`.

## manifest-verify — Multi-Field Merkle Proofs

`manifest-verify` AND-folds Merkle proofs over named fields. Use it when the payload is a structured document (a KYC bundle, signed JSON, a multi-field attestation) and the commitment is a Merkle root over field values.

```rust
// Example: build a manifest commitment and verify three fields
use vesl_core::{Mint, build_settle_register_poke, build_settle_note_manifest_poke};
use nockchain_tip5_rs::ProofNode;

// 1. Mint over the field values, one leaf per value.
let values: &[&[u8]] = &[b"alice@example.com", b"34", b"US"];
let mut mint = Mint::new();
let root = mint.commit(values);
let _ = app.poke(SystemWire.to_wire(), build_settle_register_poke(1, &root)).await?;

// 2. Collect a proof for each field.
let proofs: Vec<Vec<ProofNode>> = (0..values.len())
    .map(|i| mint.proof(i).unwrap())
    .collect();
let fields: Vec<(&[u8], &[u8])> = vec![
    (b"email", values[0]),
    (b"age",   values[1]),
    (b"juris", values[2]),
];

// 3. Submit a %settle-note with the (fields, proofs) cell.
let poke = build_settle_note_manifest_poke(42, 1, &root, &fields, &proofs);
let _ = app.poke(SystemWire.to_wire(), poke).await?;
```

Field names are descriptive; they aid debugging but the gate doesn't bind on them. The gate AND-folds `verify-chunk(value, proof, root)` over the (value, proof) pairs. Mismatched list lengths yield `%.n` from the gate.

## set-membership-verify

`set-membership-verify` proves an element belongs to a Merkle-committed set. Use it for allowlists, voter rolls, membership tables.

```rust
// Example: prove `alice` is in a committed roster
use vesl_core::{Mint, build_settle_register_poke, build_settle_note_membership_poke};

let roster: &[&[u8]] = &[b"alice", b"bob", b"carol"];
let mut mint = Mint::new();
let root = mint.commit(roster);
let _ = app.poke(SystemWire.to_wire(), build_settle_register_poke(1, &root)).await?;

let elem: &[u8] = b"alice";
let proof = mint.proof(0).unwrap();
let poke = build_settle_note_membership_poke(42, 1, &root, elem, &proof);
let _ = app.poke(SystemWire.to_wire(), poke).await?;
```

The payload `data` shape is `[elem=@ proof=(list [hash=@ side=?])]`.

## bounded-value-verify

`bounded-value-verify` proves a Merkle-committed numeric value falls in a committed `[lo, hi]` interval. Use it for age gates, score ranges, balance brackets.

The committed leaf is `hash-leaf(jam([value, bounds]))` — `value` and `bounds` are jammed together so an attacker cannot substitute their own range. Constructing the leaf requires the nock-noun-rs jamming helpers:

```rust
// Example: prove age=34 falls in [18, 65]
use vesl_core::{Mint, build_settle_register_poke, build_settle_note_bounded_poke};
use nock_noun_rs::{atom_from_u64, jam_to_bytes, new_stack, slab_root, NounSlab};
use nockvm::noun::T;

let value: u64 = 34;
let bounds: (u64, u64) = (18, 65);

// 1. Build the leaf bytes: jam([value bounds]).
let mut leaf_slab = NounSlab::new();
let v   = atom_from_u64(&mut leaf_slab, value);
let lo  = atom_from_u64(&mut leaf_slab, bounds.0);
let hi  = atom_from_u64(&mut leaf_slab, bounds.1);
let b   = T(&mut leaf_slab, &[lo, hi]);
let leaf = T(&mut leaf_slab, &[v, b]);
leaf_slab.set_root(leaf);
let mut stack = new_stack();
let leaf_bytes = jam_to_bytes(&mut stack, slab_root(&leaf_slab));

// 2. Mint over the leaf bytes; register the root.
let mut mint = Mint::new();
let root = mint.commit(&[&leaf_bytes[..]]);
let _ = app.poke(SystemWire.to_wire(), build_settle_register_poke(1, &root)).await?;

// 3. Submit a %settle-note with [value bounds proof].
let proof = mint.proof(0).unwrap();
let poke = build_settle_note_bounded_poke(42, 1, &root, value, bounds, &proof);
let _ = app.poke(SystemWire.to_wire(), poke).await?;
```

This is not a zero-knowledge proof. `value` is plaintext in the payload. Real ZK range proofs (Bulletproofs et al.) are out of scope for the catalog; the name `bounded-value-verify` is deliberately distinct from `range-proof-verify` for that reason.

## Hull `/settle` routing

Stock `vesl_hull::settle_handler` dispatches the `%settle-note` poke through a `SettlePayloadBuilder` trait so the JSON body shape adapts to the active gate. The hull's binary picks the impl at boot from the same gate name that `/status` reports.

| Gate | `/settle` request body | Notes |
|---|---|---|
| `default-hash` | `{}` re-mints from the first committed field, or `{"data": "<hex>"}` passes the leaf through. | The default behavior for the single-leaf hash gate. |
| `manifest-verify` | `{"fields": [{"name": "...", "value": "..."}, ...]}`. The hull re-derives proofs from the committed tree using `vesl_hull::field_to_leaf_bytes`. | Each `name`/`value` pair must match a field committed via `/commit`. |

Both shapes accept the common envelope fields `note_id` (optional, auto-increments) and `hull` (optional, defaults to the configured `hull_id`).

### Implementing a `SettlePayloadBuilder`

Each impl decodes its own JSON body and returns a `NounSlab` from one of the per-gate poke builders in `vesl_core`. `SettleContext` carries the committed tree, fields, and envelope:

```rust
use vesl_hull::{
    field_to_leaf_bytes, SettleBuilderError, SettleContext, SettlePayloadBuilder,
};

pub struct MyGatePayloadBuilder;

impl SettlePayloadBuilder for MyGatePayloadBuilder {
    fn gate_name(&self) -> &'static str { "my-gate" }

    fn build_settle_poke(
        &self,
        ctx: &SettleContext<'_>,
        body: &serde_json::Value,
    ) -> Result<nock_noun_rs::NounSlab, SettleBuilderError> {
        let hex_field = |k: &str| body.get(k).and_then(|v| v.as_str())
            .ok_or_else(|| SettleBuilderError::BadRequest(format!("missing `{k}`")))
            .and_then(|s| hex::decode(s).map_err(|e|
                SettleBuilderError::BadRequest(format!("invalid hex in `{k}`: {e}"))));
        let first = ctx.fields.first().ok_or_else(||
            SettleBuilderError::BadRequest("POST /commit first".into()))?;
        Ok(vesl_core::build_settle_note_ed25519_poke(
            ctx.note_id, ctx.hull_id, ctx.root,
            &field_to_leaf_bytes(first),
            &hex_field("sig")?,
            &hex_field("pubkey")?,
        ))
    }
}
```

Wire it into the scaffolded binary's `build_app_state`:

```rust
let settle_builder: Arc<dyn SettlePayloadBuilder> = Arc::new(MyGatePayloadBuilder);
```

Return `BadRequest` → 400, `InternalError` → 500. Kernel-side rejection still surfaces as 409 after the poke runs.

For the un-implemented catalog gates (`schnorr`, `ed25519`, `set-membership-verify`, `bounded-value-verify`), the hull warns at boot and falls back to `default-hash` — stock `/settle` will dead-deny on those, so you'll need either a `SettlePayloadBuilder` impl (above) or a custom route via [`serve_with_extra_routes`](/build/build-run/serve#composing-custom-routes). For gates not in the catalog at all, see [Custom Gates](/build/catalog-gates/custom-gates).

::: info See Also

- [Grafts / Manifest Schema — Gate Selection](/build/grafts/manifest-schema#graft-gates-gate-selection) — the manifest-side selection contract.
- [`protocol/lib/vesl-gates.hoon`](https://github.com/zkvesl/vesl-core/blob/11d110d/protocol/lib/vesl-gates.hoon) — the canonical gate catalog with per-gate binding rationale.
- [`crates/vesl-core/src/graft_pokes/settle.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/graft_pokes/settle.rs) — Rust builders for each gate.
- [`crates/vesl-core/src/signing.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/signing.rs) — Schnorr signing primitives.
- [Reference / vesl-core — Catalog Gates from Rust](/reference/vesl-core#catalog-gates-from-rust) — orientation pointer.

:::

================================================================================
# Source: /build/catalog-gates/gate-chains.md
================================================================================

# Gate Chains

`gate-chain = ["a", "b"]` in `[graft.gates]` AND-folds the listed gates: the chain accepts only when every gate returns `%.y`. The chain is AND-only; OR and short-circuit variants are not yet shipped.

The same `[note-id=@ data=* expected-root=@]` is passed to every chain element. Each gate `;;`-casts `data` internally to its own expected shape, so chains work only when every element accepts a compatible payload shape. Mixing payload shapes within a chain causes every element except the matching one to return `%.n`, and the AND-fold rejects.

No convenience builder exists for chained payloads. Use `build_settle_note_poke_with_data` and write a closure that emits a noun every chain element can accept.

::: tip Picking compatible elements
Two gates are chain-compatible when they cast `data` to the same shape *and* bind `expected-root` to the same digest. For example, `sig-verify-schnorr` and `sig-verify-ed25519` both expect `[data sig pubkey]` and both bind `hash-leaf(pubkey)` to the root — but they hash different pubkeys, so you cannot chain them against a single registered root. Chain only gates that agree on both axes.
:::

::: info See Also

- [Catalog Gates from Rust](/build/catalog-gates/) — per-gate payload shapes the chain has to agree on.
- [Grafts / Manifest Schema — Gate Selection](/build/grafts/manifest-schema#graft-gates-gate-selection) — `[graft.gates]` syntax for `gate-chain`.
- [`build_settle_note_poke_with_data`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/graft_pokes/settle.rs) — the closure-based builder for assembling arbitrary `data` cells.

:::

================================================================================
# Source: /build/catalog-gates/swapping.md
================================================================================

# Swapping a Gate

Edit `[graft.gates]` in your manifest and re-run `nockup graft inject --apply`. The composer rewrites the splice point at every `%settle-*` arm and prepends `/+  vesl-gates` to the imports body. The full deltas (root semantics, payload shape, Rust builder, behavior of pre-existing roots) are in [Grafts / Manifest Schema — Swapping a Gate](/build/grafts/manifest-schema#swapping-a-gate).

After re-compiling and restarting the hull, verify the swap landed via [`GET /status`](/build/build-run/serve#verifying-a-gate-swap-via-status) — the `gate` field reflects the new selection, and `manifest_shas` updates for any graft whose TOML body changed.

::: info See Also

- [Catalog Gates from Rust](/build/catalog-gates/) — per-gate root and payload bindings to plan the swap.
- [Grafts / Manifest Schema — Swapping a Gate](/build/grafts/manifest-schema#swapping-a-gate) — manifest-side delta walkthrough.
- [Serve — Verifying a gate swap via /status](/build/build-run/serve#verifying-a-gate-swap-via-status) — HTTP-side confirmation.

:::

================================================================================
# Source: /build/catalog-gates/custom-gates.md
================================================================================

# Custom Gates

A custom verify-gate — one that isn't in the Tier 1a catalog — currently faces three coupled obstacles. The catalog is intentionally closed; if you need a gate that isn't shipped, the path is "fork and contribute back" rather than "register a plugin."

## 1. `nockup graft inject` hard-rejects unknown gate names

The CLI validates `[graft.gates].gate` and `[graft.gates].gate-chain` entries against an allowlist (`TIER_1A_GATES`) at manifest discovery. A name outside that allowlist fails immediately:

```
[graft.gates].gate `my-custom-gate` in hoon/lib/settle-graft.toml is not a known catalog gate.
Tier 1a (currently shipping): sig-verify-ed25519, sig-verify-schnorr,
manifest-verify, set-membership-verify, bounded-value-verify
```

There is no `--allow-custom-gate` flag today. To get past this you either (a) add your name to `TIER_1A_GATES` in `tools/graft-inject/src/gates.rs` in a local fork, or (b) skip the `[graft.gates]` table entirely and hand-write your gate directly in `settle-graft`'s poke body (the composer leaves hand-written gates untouched — see the `apply_gate_selection` mismatch guard).

## 2. `vesl-gates.hoon` must contain a matching arm

The composer rewrites the default hash-gate block to `=/  hash-gate=verify-gate  <name>:vesl-gates`, so `<name>` must resolve as an arm in `vesl-gates.hoon` with the required `[note-id=@ data=* expected-root=@] -> ?` signature. A name with no matching arm produces a `hoonc` `find . <name>:vesl-gates` failure at compile time. If you forked `TIER_1A_GATES`, you must also ship the hoon arm.

## 3. `vesl_hull::payload_builder_for_gate` has no impl for your name

Stock `/settle` dispatches through `SettlePayloadBuilder`. The library's `payload_builder_for_gate(name)` only knows `default-hash` and `manifest-verify`; every other name hits the fallback arm, prints a stderr warning, and returns `DefaultHashPayloadBuilder` — which will dead-deny against your custom gate. You have two ways out:

- **Wire your impl in the template.** The scaffolded `templates/vesl/src/main.rs::build_app_state` owns the dispatch. Replace the call to `payload_builder_for_gate` with your own match:

  ```rust
  let settle_builder: Arc<dyn vesl_hull::SettlePayloadBuilder> =
      match manifest.gate.as_str() {
          "my-custom-gate" => Arc::new(MyCustomPayloadBuilder),
          _ => vesl_hull::payload_builder_for_gate(&manifest.gate),
      };
  ```

  `AppState.settle_builder` is `Arc<dyn SettlePayloadBuilder>`, so any user impl works once the template chooses it. The trait shape and an example impl are on [Catalog Gates — Implementing a `SettlePayloadBuilder`](/build/catalog-gates/#implementing-a-settlepayloadbuilder).

- **Skip stock `/settle` entirely.** Mount your own `POST /settle-my-gate` route via [`serve_with_extra_routes`](/build/build-run/serve#composing-custom-routes) and use the per-gate poke builders in `vesl-core/src/graft_pokes/settle.rs` directly (e.g. `build_settle_note_poke_with_data` for arbitrary payload shapes). The stock `/settle` will still dead-deny if anyone hits it, but your route bypasses the dispatcher.

::: tip Need a gate the catalog doesn't have?

Most "custom verify-gate" needs are actually shape-validation or authorization checks that belong in a [validate-graft prelude](/build/grafts/inject#cause-dispatch-semantics) or a separate graft's poke arm — not in the verify-gate. The verify-gate is narrow on purpose: it answers "does this payload prove authority over the registered root?" If your need doesn't fit that shape, a graft is usually the right surface.

If you do need a true custom verify-gate, open an issue describing the shape — recurring patterns are candidates for inclusion in the catalog rather than per-user forks.

:::

::: info See Also

- [Catalog Gates from Rust](/build/catalog-gates/) — the shipped gates and the `SettlePayloadBuilder` trait shape.
- [Serve — Composing Custom Routes](/build/build-run/serve#composing-custom-routes) — `serve_with_extra_routes` for the bypass path.
- [Grafts / Manifest Schema — Gate Selection](/build/grafts/manifest-schema#graft-gates-gate-selection) — `[graft.gates]` validation contract.

:::

================================================================================
# Source: /build/build-run/index.md
================================================================================

# Build & Run

Two compile steps: `hoonc` produces `out.jam` from your composed Hoon, then `cargo +nightly build --release` produces the hull binary that loads it. `cargo +nightly run --release` does both (assuming `out.jam` is already current). `--release` is non-optional — see [Quickstart → Why `--release`?](/setup/quickstart#why-release) for the underlying `nockvm::is_in_frame` debug-assertion that requires it.

```d2
direction: right

src: "hoon/app/app.hoon\n+ hoon/lib/* + hoon/common/*"
hoonc
jam: "out.jam"
check: "[ -s out.jam ]" {
  shape: diamond
}
fail: "error: silent-failed compile"
cargo: "cargo +nightly build --release"
bin: "target/.../hull"
run: "cargo +nightly run --release"

src -> hoonc -> jam -> check
check -> fail: empty
check -> cargo: present
cargo -> bin -> run
```

## Compile the Kernel

```bash
./compile.sh
```

`compile.sh` ships in the scaffold. It runs `hoonc hoon/app/app.hoon hoon/`, then checks the `out.jam` artifact — structural type errors during eager-parse can leave hoonc with no panic message, exit 0, and no `out.jam` written, so the exit code alone is not trustworthy. `compile.sh` fails loud when hoonc produced nothing, instead of letting the next step run against a stale kernel.

Run `hoonc hoon/app/app.hoon hoon/` directly to skip the wrapper; add `--new` to bypass hoonc's cache.

## verify-jam — Structured Alternative

For the silent-fail case AND the case where `out.jam` exists but is stale (kernel sources edited without recompile), pair the compile with `vesl-test verify-jam`:

```bash
./compile.sh
sha256sum hoon/app/app.hoon hoon/lib/*.hoon hoon/lib/*.toml > .out-jam-source-fingerprint
vesl-test verify-jam .   # exit 0 fresh, 1 stale, 2 no fingerprint
```

The fingerprint sidecar pins the source bytes the current `out.jam` was compiled from. Most useful right before driving a kernel that took 10+ minutes to compile.

## Build the Hull

```bash
cargo +nightly build --release
```

First build compiles the full nockchain stack — expect 2–5 minutes with path deps (faster on subsequent builds), or longer if any nockchain git deps resolve over the network.

## Run

The scaffolded binary is a clap dispatch with two arms — both boot `out.jam`, then hand the booted `NockApp` to the selected arm:

```bash
cargo +nightly run --release                # Demo arm (default): register a root, settle a note
cargo +nightly run --release -- serve       # Serve arm: HTTP API on http://127.0.0.1:3000
```

Expected Demo-arm output for the canonical [quickstart hull](/setup/quickstart#_5-exercise-the-lifecycle):

```
  effect: %settle-registered
  effect: %settle-noted
```

Each line is one effect from the kernel, parsed via `vesl_core::effect_head_tags(&effects)` in the hull. The Serve arm and its flag / endpoint catalog live on [Serve Subcommand](/build/build-run/serve).

## Settlement Modes

A nockapp can run kernel-only (no chain interaction) or with full settlement against a nockchain endpoint. Two surfaces select the mode:

- `--settlement-mode <mode>` — CLI flag on the hull binary. Per-invocation override; reach for it when you want a single run to depart from the project default.
- `settlement_mode = "<mode>"` — field in `vesl.toml`. The committed project default that applies whenever the CLI flag is absent.

The CLI flag wins over the TOML field. With neither set, `--chain-endpoint` or `--submit` infer `fakenet`; otherwise the mode is `local`. The three modes:

| Mode | What happens | Chain required | Walkthrough |
|------|-------------|----------------|-------------|
| `local` | Kernel verifies, no chain interaction. Default. | No | (this page) |
| `fakenet` | Sign, build tx, submit to a local nockchain fakenet. | Yes (local) | [Fakenet Walkthrough](/build/build-run/fakenet) |
| `dumbnet` | Same as fakenet but uses a real seed phrase for key derivation. | Yes (live) | [Dumbnet Walkthrough](/build/build-run/dumbnet) |

A minimal `vesl.toml` for local-mode runs:

```toml
nock_home = "../nockchain"
api_port = 3000
settlement_mode = "local"
```

`nock_home` points to your nockchain monorepo checkout. `api_port` is read by hulls that expose an HTTP shell (e.g. the Serve arm). The full field list lives in [Reference / vesl.toml](/reference/vesl-toml).

::: info See Also

- [Serve Subcommand](/build/build-run/serve) — flags, auth model, endpoint catalog, custom router composition.
- [Fakenet Walkthrough](/build/build-run/fakenet) — hub + miner + signing key wiring for the local testnet.
- [Dumbnet Walkthrough](/build/build-run/dumbnet) — seed-phrase resolution and live-network settings.
- [vesl-nockup README — Step 4 (compile)](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#step-4--compile-the-kernel) — hoonc invocation and the staleness guard.
- [vesl-nockup README — Step 5 (build/run)](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#step-5--build-and-run) — cargo build, run flags, settlement-mode selection.
- [Reference / vesl.toml](/reference/vesl-toml) — full field list including the `[wallet]` schema.

:::

================================================================================
# Source: /build/build-run/serve.md
================================================================================

# Serve Subcommand

The `vesl` scaffold's `src/main.rs` is a clap dispatch with two arms — `Demo` (default) and `Serve`. The Serve arm boots `out.jam`, builds an `AppState`, and hands it to [`vesl_hull::serve`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-hull/src/api/mod.rs), which mounts an `axum::Router` on the configured bind address.

```bash
cargo +nightly run --release -- serve                  # http://127.0.0.1:3000, demo signing key
cargo +nightly run --release -- serve --no-auth        # loopback dev: skip API-key auth
cargo +nightly run --release -- serve --port 8080      # custom port, still loopback
HULL_API_KEY=mysecret cargo +nightly run --release -- serve --bind-addr 0.0.0.0   # LAN
```

## Flags

| Flag | Default | Notes |
|---|---|---|
| `--port <PORT>` | `3000` | TCP listen port. |
| `--bind-addr <ADDR>` | `127.0.0.1` | Bind address. `--no-auth` is refused on any non-loopback bind. |
| `--no-auth` | off | Disable API-key auth. Honored only when `--bind-addr` is loopback (`127.0.0.1`, `::1`, `localhost`); otherwise the binary refuses to start. |

All other behavior — settlement mode, signing key, `vesl.toml` overrides — flows through the same surfaces the Demo arm uses. See [Settlement Modes](/build/build-run/#settlement-modes) for the mode-selection logic.

## Auth Model

The Serve arm checks two configuration surfaces at startup via `vesl_hull::check_auth_config_with_bind(no_auth, bind_addr)`:

1. **Non-loopback bind + `--no-auth`** → refuse to start. The combination would expose an unauthenticated kernel-poke surface to the LAN; the early-exit guard is unconditional.
2. **`HULL_API_KEY` env var** → if set and non-empty, every kernel-side endpoint requires `Authorization: Bearer <key>`. If unset, the server prints `WARNING: HULL_API_KEY not set -- API endpoints are unauthenticated` to stderr and starts anyway.

The `/health` endpoint is **always** unauthenticated regardless of `HULL_API_KEY` — it's the readiness probe and must answer for orchestrators that don't carry the bearer token. The endpoint is gated on `AppState::kernel_ready`: 200 + `{"status":"ok"}` once the hull finishes booting, 503 + `{"status":"booting","stage":"<stage>"}` until then. Wire k8s `readinessProbe` (or any load-balancer health check) to the 200, so traffic stays off the pod during the boot window.

```bash
# Loopback dev: skip auth entirely.
cargo +nightly run --release -- serve --no-auth

# LAN / shared dev: require an API key.
HULL_API_KEY=$(openssl rand -hex 32) \
  cargo +nightly run --release -- serve --bind-addr 0.0.0.0

# Then from another host:
curl -H "Authorization: Bearer $HULL_API_KEY" \
  http://<host>:3000/status
```

For production deployments where the seed phrase + bearer key + bind address all matter, lock down the host running the hull — the BIP-39/BIP-44 derivation gives the hull spend authority over any UTXO locked to the resulting pkh (see [Dumbnet Walkthrough](/build/build-run/dumbnet)).

## Rate-limit behavior

The hull's middleware stack paces requests rather than rejecting them on burst. The layer is `tower`'s `RateLimit` with a `tower::buffer::Buffer` in front:

- **Capacity**: 200 requests per 60 seconds, shared across every authenticated endpoint.
- **Buffer**: 256 in-flight requests. Excess in-flight requests are queued, not rejected.
- **Overflow**: requests beyond the 256 buffer slot return HTTP 429 via the `HandleErrorLayer` wrapper. Under the capacity ceiling, requests block until a slot frees instead of failing fast.

This is pacing, not strict rate-limiting. A 300-request burst against `/status` takes ~110 seconds to drain (~200 served, 100 paced); zero 429s under that load. A 257-deep concurrent burst (one request above the buffer ceiling) is what produces the 429.

Custom routes mounted through `serve_with_extra_routes` / `router_with_extra` inherit the same layer (the middleware stack wraps the merged Router — see [Composing Custom Routes](#composing-custom-routes)).

Swap to `tower_governor::GovernorLayer` if the deployment needs true burst-rejection semantics; the existing pacing layer is wired in `crates/vesl-hull/src/api/mod.rs` (`router_with_extra_inner`).

## Endpoint Catalog

`vesl_hull::router(state)` returns an `axum::Router` mounting six endpoints. The handlers assume the kernel composes settle-graft — a kernel without it will reject the kernel-side pokes those handlers issue.

| Method | Path | Purpose | Auth |
|---|---|---|---|
| `POST` | `/commit` | Commit key-value fields to a Merkle tree and register the root with the kernel. | `HULL_API_KEY` |
| `POST` | `/settle` | Settle a note against the current registered root. **Body shape varies by gate** — see [Catalog Gates / Hull settle routing](/build/catalog-gates/#hull-settle-routing). | `HULL_API_KEY` |
| `POST` | `/verify` | Verify a field's Merkle proof against the registered root. | `HULL_API_KEY` |
| `GET`  | `/tx/{tx_id}` | Fetch a chain-attested receipt (requires fakenet/dumbnet settlement). | `HULL_API_KEY` |
| `GET`  | `/status` | Current state snapshot — fields, tree, hull-id, note counter, settlement mode, **active gate**, **composed grafts**, **per-graft manifest sha256s**. | `HULL_API_KEY` |
| `GET`  | `/health` | Readiness probe. 200 + `{"status":"ok"}` when the hull is ready; 503 + `{"status":"booting","stage":"<stage>"}` during boot. Always unauthenticated. | — |

Each endpoint's request/response shape sits in `crates/vesl-hull/src/api/handlers/<endpoint>.rs` (one file per handler); the shared `PokeCrashError → HTTP` mapping lives in `crates/vesl-hull/src/api/error.rs`. The 409 / 4xx mappings for kernel rejections are documented in [Effect Catalog → settle-graft](/reference/effect-catalog#settle-graft).

### /status Response Shape

`GET /status` returns the operational snapshot a hull operator triages against. The full payload after one commit + one settle against a quickstart-shaped kernel:

```json
{
  "has_tree": true,
  "field_count": 1,
  "merkle_root": "5q8m7n4k2x9j6h3y8b1w7p4v2c5d8e1f9z3a6t0r4u7i2o5",
  "notes_settled": 1,
  "hull_id": 1,
  "settlement_mode": "in-process",
  "gate": "default-hash",
  "grafts": [
    "batch-graft", "clock-graft", "counter-graft", "forge-graft",
    "guard-graft", "intent-graft", "kv-graft", "log-graft",
    "mint-graft", "queue-graft", "rbac-graft", "registry-graft",
    "settle-graft", "validate-graft"
  ],
  "manifest_shas": {
    "batch-graft":    "8f3e2a1c…",
    "clock-graft":    "7b6d4f8a…",
    "counter-graft":  "2c9e1b6d…",
    "forge-graft":    "4d8a3f7c…",
    "guard-graft":    "9a3c5e2b…",
    "intent-graft":   "1f4b8d3a…",
    "kv-graft":       "6e2c1a9d…",
    "log-graft":      "3b7f4e8c…",
    "mint-graft":     "5a9d2c7b…",
    "queue-graft":    "0c4e6f1b…",
    "rbac-graft":     "8d3a7c2e…",
    "registry-graft": "f7b2e4a9…",
    "settle-graft":   "f1b2c8e4…",
    "validate-graft": "3e9d1c5b…"
  }
}
```

Field meanings:

- `has_tree` / `field_count` / `merkle_root` — current commit-graft tree state. `merkle_root` is `null` until the first `/commit`; once a tree exists, it's the tip5-formatted root.
- `notes_settled` / `hull_id` — settle-graft progress counters. `notes_settled` increments per successful `/settle`; `hull_id` is the namespace under which roots were registered.
- `settlement_mode` — `"in-process"`, `"fakenet"`, or `"dumbnet"`. Set at boot from the `--settlement` flag.
- `gate` — active verify-gate name. `"default-hash"` when no graft declares `[graft.gates]`; otherwise the selection from the highest-priority graft. Chains render as `"A&B"`.
- `grafts` — alphabetically sorted list of every graft composed into the running kernel.
- `manifest_shas` — per-graft sha256 of the raw manifest TOML. Same digest `nockup graft inject` banners on each block, so a mismatch surfaces drift between the on-disk manifest and the composed kernel.

### Verifying a gate swap via /status

`/status` snapshots the graft manifest dir at hull boot. After [swapping a gate](/build/catalog-gates/swapping), restart the hull and check:

```bash
curl -H "Authorization: Bearer $HULL_API_KEY" http://localhost:3000/status | jq '{gate, grafts, manifest_shas}'
```

```json
{
  "gate": "manifest-verify",
  "grafts": ["mint-graft", "settle-graft"],
  "manifest_shas": {
    "mint-graft": "9a3c…",
    "settle-graft": "f1b2…"
  }
}
```

The `gate` field is `"default-hash"` when no graft declares `[graft.gates]`; otherwise it's the selection from the highest-priority graft (in practice, settle-graft), with `gate-chain = [...]` selections rendered as `"A&B"`. The `manifest_shas` map mirrors the digest `nockup graft inject` banners on each block, so any drift between the on-disk manifest and the composed kernel surfaces here.

### Hull / kernel drift triage via /status

`manifest_shas` is the canonical surface for catching out-of-band drift between a running hull's `out.jam` and the on-disk graft library. The shas it returns are the same per-graft digests `nockup graft inject --apply` prints on each block — so the diff workflow is one curl, one jq, and one grep:

```bash
curl -H "Authorization: Bearer $HULL_API_KEY" http://localhost:3000/status \
  | jq '.manifest_shas'
nockup graft inject hoon/app/app.hoon 2>&1 | grep sha256
```

A mismatch points at one of three failure modes: a stale kernel (the source changed but the hull is still booted from an old `out.jam`), a manifest edit that wasn't re-injected (the inject banner shows the new sha but `/status` shows the old one), or a hull running an `out.jam` produced from a different lib tree than the one inject is reading now. Pair this check with [`vesl-test verify-jam`](/build/testing/cli#verify-jam-—-build-staleness-check) — `/status` catches hull / kernel drift, `verify-jam` catches kernel / source drift.

## Composing Custom Routes

Pass your routes to [`vesl_hull::serve_with_extra_routes`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-hull/src/api/mod.rs) (or [`vesl_hull::router_with_extra`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-hull/src/api/mod.rs) if you only need the assembled `axum::Router`). The hull merges them with its stock endpoints **before** applying the middleware stack, so auth, body limit, and rate limit cover every route uniformly:

```rust
use axum::{routing::post, Router};
use vesl_hull::SharedState;

async fn issue_badge(/* ... */) -> impl axum::response::IntoResponse {
    // your domain handler
}

pub async fn run(state: SharedState, port: u16, bind: &str) -> anyhow::Result<()> {
    let extra: Router<SharedState> = Router::new()
        .route("/issue-badge", post(issue_badge));
    vesl_hull::serve_with_extra_routes(state, port, bind, extra).await?;
    Ok(())
}
```

This is the seam for adding endpoints that drive your domain causes. The mounted Tower middleware stack wraps the merged Router, so your custom routes inherit every layer uniformly:

- **API-key auth** — bearer-token check against `HULL_API_KEY`. The `/health` exemption is wired explicitly inside the auth middleware.
- **Body-size cap (two-layer, 4 MiB)** — an upfront `Body::size_hint` precheck rejects any request whose body advertises a known length above the cap (`413 Payload Too Large`). That covers wire requests with honest `Content-Length` (axum's H1/H2 parser propagates the header into the body's size_hint) and in-process bodies built from `Vec<u8>` / `Bytes` / `String`. Chunked or unknown-length bodies fall through to tower-http's streaming `RequestBodyLimitLayer`, which fires the moment the handler polls past the cap. A handler that ignores its body still gets the upfront 413 when the size is known.
- **Rate limit** — 200 req / 60 s with a 256-deep buffer; overflow returns 429 via the `HandleErrorLayer` wrapper.

To replace stock endpoints entirely (e.g. a domain-specific `/commit` shape), fork `crates/vesl-hull/src/api/` rather than merging — `Router::merge` can't override existing route definitions, only add to them. Each stock handler is its own file under `api/handlers/`, so forking is "copy the one handler you want to replace + wire your version into a custom router."

### Worker patterns and throughput

`AppState` lives behind a single `Arc<Mutex<...>>` so any custom route that holds the lock across a multi-step kernel poke serializes against every other endpoint. Sustained throughput tops out near 20 ops/s on a held-lock workload; a 250-deep concurrent burst against a worker-style `/enqueue` route takes ~12.7 seconds to drain.

If your custom route's hot path is "lock, poke kernel, write state, unlock," the mutex is the ceiling. Two shapes that lift it:

- **mpsc to a dedicated worker task**. The route sends work over an `mpsc::Sender`; a single owner task holds the kernel handle and drains the channel. The route returns immediately with a job id, and a follow-up GET surfaces completion. Trades latency for throughput.
- **Read-mostly fast path**. Routes that only need to peek (no kernel poke) can take an `RwLock` read guard via a refactored `AppState`, leaving the write path on the mutex. Tightly scoped — most hull state mutation goes through the kernel poke, which is single-threaded by construction.

## Running multiple instances

Each `serve` process boots its own copy of `out.jam` into its own kernel. None of that kernel's state is shared between processes — every instance carries an independent state tree.

The kernel's note-`settled` set is the replay guard behind `/settle`: a second settle of an already-settled `note_id` is rejected by the kernel, which the handler maps to [409](/reference/effect-catalog#settle-graft). That set lives in one kernel's state. Two instances behind a load balancer hold two independent `settled` sets — a note settled on instance A is unknown to instance B, so the same `/settle` request routed to B settles a second time and returns no 409. Registered roots from `/commit` and any per-graft counters diverge the same way.

In [`fakenet` / `dumbnet`](/build/build-run/#settlement-modes) modes the settlement transaction also lands on-chain, so the chain — not the hull — is the cross-instance record of what settled there. The kernel's in-memory `settled` guard, and the 409 a client sees, stay per-instance regardless. `local` mode has no chain backstop at all.

Until hull state is externalized to a shared store, run a single instance, or front a fleet with sticky sessions (load-balancer affinity) so each client reaches the same kernel on every request. A fleet without one of those drops cross-instance replay rejection silently.

::: info See Also

- [Hull / Scaffold CLI: Demo and Serve](/build/hull#scaffold-cli-demo-and-serve) — entry-level overview of the Demo + Serve dispatch.
- [Build & Run](/build/build-run/) — kernel compile and Demo-arm run flow.
- [Settlement Modes](/build/build-run/#settlement-modes) — selecting `local` / `fakenet` / `dumbnet` for the booted hull.
- [Effect Catalog → settle-graft](/reference/effect-catalog#settle-graft) — kernel rejection shapes the `/commit` and `/settle` handlers map to 4xx.
- [vesl-nockup README — Serving over HTTP](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#serving-over-http) — scaffold-level overview.
- [`crates/vesl-hull/`](https://github.com/zkvesl/vesl-nockup/tree/main/crates/vesl-hull) — the lib backing the Serve arm.

:::

================================================================================
# Source: /build/build-run/production-checklist.md
================================================================================

# Production Checklist

**After reading:** you'll have a single page to walk before shipping a vesl nockapp to a non-local environment — build-artifact integrity, auth and rate-limit calibration, operational visibility through `/status` and `/health`, and the state-survival contract under recompile.

Each item points to the canonical source page for the underlying behavior. The shape is: what to check, the command, expected output. Nothing on this page replaces the source pages; it's the pre-ship walk.

## Build Artifacts

The kernel binary (`out.jam`) is the single artifact every deploy ships. Three checks confirm it's the one you intend:

- **Stale-build detection.** Run `vesl-test verify-jam` to confirm `out.jam` matches the current Hoon source tree (manifest TOMLs + library `.hoon` files). A mismatch means the kernel was compiled before the last source edit.
  ```bash
  vesl-test verify-jam
  ```
  Expected: `verify-jam: ok — out.jam matches source tree`. A mismatch reports the diverging file. Full surface: [Testing / CLI — verify-jam](/build/testing/cli#verify-jam-—-build-staleness-check).

- **Project-health pass.** Run `nockup graft doctor` to confirm schema-version handshake, Cargo `[patch]` consistency, hand-edited injected blocks, missing `nockup:load-defaults` marker, plus the resolved lint policy. Exits nonzero on any project-health finding or lint error.
  ```bash
  nockup graft doctor hoon/app/app.hoon
  ```
  Expected: `nockup-graft doctor: ok` plus per-lint effective-severity listing. Full surface: [Reference / CLI — doctor](/reference/cli#doctor).

- **Kernel-hash pin (production deploys).** Set `VESL_KERNEL_SHA256` to the expected sha256 of `out.jam` before boot. The template's `load_kernel` refuses to boot on a mismatch. Local development can leave it unset (warning prints; boot proceeds).
  ```bash
  export VESL_KERNEL_SHA256=$(sha256sum out.jam | awk '{print $1}')
  cargo +nightly run --release -- serve
  ```
  Expected at boot: no `out.jam integrity unverified` warning. A mismatch surfaces as `out.jam sha256 mismatch: expected <pin>, got <actual> — refusing to boot`.

## Auth & Rate Limits

The Serve arm mounts `vesl-hull`'s HTTP API. Three auth/rate concerns to set before exposing it:

- **API-key auth.** Set `HULL_API_KEY` to a high-entropy secret before binding the listener. If unset, the server prints `WARNING: HULL_API_KEY not set -- API endpoints are unauthenticated` and starts anyway — fine for local dev, hostile in production.
  ```bash
  HULL_API_KEY=$(openssl rand -hex 32) cargo +nightly run --release -- serve --bind-addr 0.0.0.0
  ```
  Expected: no warning at startup. Clients must carry `Authorization: Bearer <key>`. The `/health` endpoint stays unauthenticated regardless. Full surface: [Build & Run / Serve — Auth Model](/build/build-run/serve#auth-model).

- **Rate-limit pacing.** Default is 200 req/60s + 256-deep buffer, applied per-route after auth. `/health` is exempt. The combination paces sustained load; a burst above 257 concurrent requests produces 429s. Calibrate by load-testing against `/status`.
  ```bash
  hey -n 300 -c 10 -H "Authorization: Bearer $HULL_API_KEY" http://localhost:3000/status
  ```
  Expected: zero 429s under burst sizes within the buffer; controlled 429s above it. Full surface: [Build & Run / Serve — Rate-limit behavior](/build/build-run/serve#rate-limit-behavior).

- **Body-size cap.** The 4 MiB body limit runs in two layers (upfront `Body::size_hint` precheck plus tower-http's streaming layer). Custom routes mounted via `Router::merge` bypass the auth/limit/rate layers — use `serve_with_extra_routes` instead. Full surface: [Build & Run / Serve — Composing Custom Routes](/build/build-run/serve#composing-custom-routes).

## Operational Visibility

The `/status` endpoint is the single window into what's running:

- **Build provenance.** `GET /status` surfaces `gate`, `grafts[]`, `manifest_shas{}`, `settlement_mode`, `hull_id`, `notes_settled`, `has_tree`. The `manifest_shas` are the sha256s carried in each `graft-inject:<name>:<marker>` banner — they identify the exact composed kernel in production.
  ```bash
  curl -H "Authorization: Bearer $HULL_API_KEY" http://localhost:3000/status | jq '{gate, grafts, manifest_shas}'
  ```
  Expected: per-graft sha256s matching the local `nockup graft inject --apply` output. A divergence means the deployed kernel was composed from a different manifest set. Full surface: [Build & Run / Serve — /status Response Shape](/build/build-run/serve#status-response-shape).

- **Readiness probe.** `GET /health` is unauthenticated and returns 200 once the hull finishes booting, 503 + `{"status":"booting","stage":"<stage>"}` during boot. Wire k8s `readinessProbe` (or any LB health check) to the 200.
  ```bash
  curl -o /dev/null -w "%{http_code}\n" http://localhost:3000/health
  ```
  Expected: `200` once booted, `503` during the boot window. Full surface: [Build & Run / Serve — Endpoint Catalog](/build/build-run/serve#endpoint-catalog).

- **Hull/kernel drift triage.** Compare `/status`'s `grafts[]` and `manifest_shas{}` against what the hull's `assert_kernel_cause_tag!` macro statically asserts. A drift surfaces as either a build-time compile error (caught) or a runtime `Ok(vec![])` from an unknown cause (uncaught — opt into the codegen). Full surface: [Build & Run / Serve — Hull / kernel drift triage via /status](/build/build-run/serve#hull-kernel-drift-triage-via-status).

## State Management

The state survives recompile-and-restart via PMA. Three caveats determine what survives:

- **Same-composition resume.** A recompile that leaves the graft set unchanged resumes state cleanly. Pre-restart `/status` should match post-restart `/status` byte-for-byte across `has_tree`, `field_count`, `merkle_root`, `notes_settled`, `hull_id`, `manifest_shas`. Boot time drops to ~1s (vs. ~15s cold). Full surface: [State & Snapshots — Same Composition](/build/state-snapshots#same-composition).

- **Schema extension via `nockup:load-defaults`.** Adding a graft inserts new state axes. The `nockup:load-defaults` codegen emits a defaults overlay so resumed snapshots with a smaller noun shape get type defaults for the new axes instead of crashing in `mule`. Full surface: [State & Snapshots — Schema Extension](/build/state-snapshots#schema-extension).

- **Manual migration is out of scope.** Removing a graft or changing a state field's shape needs an explicit re-poke after resume — the defaults overlay doesn't unwind. Plan a migration cause if a shape change is unavoidable. Full surface: [State & Snapshots — Manual Migration](/build/state-snapshots#manual-migration).

## Verification Sequence

The pre-ship walk, in order:

```bash
# 1. Build the kernel from a clean tree.
./compile.sh

# 2. Run lints + project-health.
nockup graft doctor hoon/app/app.hoon

# 3. Confirm the artifact matches the source tree.
vesl-test verify-jam

# 4. Capture the kernel sha for pinning.
sha256sum out.jam

# 5. Boot with the pin + an API key set.
HULL_API_KEY=$(openssl rand -hex 32) \
VESL_KERNEL_SHA256=$(sha256sum out.jam | awk '{print $1}') \
cargo +nightly run --release -- serve --bind-addr 0.0.0.0

# 6. Confirm readiness + provenance.
curl -o /dev/null -w "%{http_code}\n" http://localhost:3000/health
curl -H "Authorization: Bearer $HULL_API_KEY" http://localhost:3000/status \
  | jq '{gate, grafts, manifest_shas}'
```

Each step has a one-line failure mode. Steps 1-3 fail at build time; step 4 captures the production pin; step 5 fails at boot if the pin or auth setup is wrong; step 6 surfaces what the deployed kernel reports.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

::: info See Also

- [Testing / CLI](/build/testing/cli) — `verify-jam`, `inspect peek`, `watch`.
- [Build & Run / Serve Subcommand](/build/build-run/serve) — flags, auth, endpoint catalog, rate-limit calibration, custom routes.
- [State & Snapshots](/build/state-snapshots) — PMA-resume, schema extension, manual migration.
- [Reference / CLI — doctor](/reference/cli#doctor) — project-health pass.

:::

================================================================================
# Source: /build/build-run/fakenet.md
================================================================================

# Fakenet Walkthrough

Fakenet is a local nockchain testnet — sandboxed, but the full settlement pipeline runs end-to-end (sign, build tx, submit, wait for acceptance). Reach for fakenet once kernel logic is stable in [`local` mode](/build/build-run/#settlement-modes) and you need to drive real transactions.

**Prerequisites.** Install the `nockchain` and `nockchain-wallet` binaries from your nockchain monorepo checkout:

```bash
cd $NOCK_HOME && make install-nockchain && make install-nockchain-wallet
```

**1. Set the mining pkh.** The fakenet miner mines coinbase UTXOs to the pkh in `.env`. Your hull must control the corresponding signing key, or it can't spend those UTXOs. For vesl-core's `hull/` template, the demo signing key's pkh is the canonical choice:

```bash
cd $NOCK_HOME
cp .env_example .env
# Replace MINING_PKH with the demo signing key's pkh
# (defined in vesl-core/hull/src/signing.rs::DEMO_KEY_PKH_BASE58)
sed -i 's/^MINING_PKH=.*/MINING_PKH=5pJiNWqnouxku6SvGU6XZhu98nHH5VFMaNJ4r1vtHxPJ5sHurHBfYnk/' .env
```

For a custom hull, mine to whatever pkh your hull's fakenet signing key controls.

**2. Boot the hub + miner.** Run each in its own working directory so checkpoint state stays isolated:

```bash
mkdir fakenet-hub fakenet-miner
cp .env fakenet-hub/ && cp .env fakenet-miner/

# Shell 1: hub (binds gRPC to 127.0.0.1:5555)
cd fakenet-hub && sh ../scripts/run_nockchain_node_fakenet.sh

# Shell 2: miner (mines to MINING_PKH from .env)
cd fakenet-miner && sh ../scripts/run_nockchain_miner_fakenet.sh
```

**3. Configure your hull.** In your project's `vesl.toml`:

```toml
nock_home = "../nockchain"
settlement_mode = "fakenet"
chain_endpoint = "http://127.0.0.1:5555"
tx_fee = 256                # network minimum, in nicks
coinbase_timelock_min = 1   # spendable after 1 confirmation
accept_timeout_secs = 300   # fakenet default
```

`chain_endpoint` must match the port the hub binds (`5555` per the upstream script). vesl-core's compiled-in default of `http://localhost:9090` is from a different layout — set the field explicitly to avoid silent mismatch.

**4. Run the hull:**

```bash
cargo +nightly run --release -- --settlement-mode fakenet
```

Each settled note produces `%settle-noted` followed by a `tx_id` in the effect list, and stderr shows the tx submission and acceptance. Expect a few seconds of pipeline latency per settle as the tx works through mempool and into a mined block.

::: info See Also

- [Build & Run](/build/build-run/) — kernel compile and settlement-mode selection.
- [Serve Subcommand](/build/build-run/serve) — running the same hull as an HTTP server against a fakenet endpoint.
- [Dumbnet Walkthrough](/build/build-run/dumbnet) — the live-network counterpart.
- [nockchain README — Run a testnet](https://github.com/nockchain/nockchain/blob/main/README.md#how-do-i-run-a-testnet) — upstream fakenet hub + miner setup.
- [`vesl-core/hull/src/signing.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/hull/src/signing.rs) — `demo_signing_key()` and `DEMO_KEY_PKH_BASE58`.
- [Reference / vesl.toml](/reference/vesl-toml) — full field list including the `[wallet]` schema.

:::

================================================================================
# Source: /build/build-run/dumbnet.md
================================================================================

# Dumbnet Walkthrough

Dumbnet runs the same pipeline as [fakenet](/build/build-run/fakenet) against the live network, using a real seed phrase for key derivation. Use it once your kernel is stable on fakenet — every transaction has economic stakes.

**1. Generate or reuse a key pair:**

```bash
nockchain-wallet keygen
```

Capture the seed phrase out-of-band; you'll feed it to the hull via a file flag rather than `vesl.toml`.

**2. Stash the seed phrase** in a permission-locked file:

```bash
mkdir -p ~/.config/vesl && touch ~/.config/vesl/dumbnet.seed
chmod 600 ~/.config/vesl/dumbnet.seed
$EDITOR ~/.config/vesl/dumbnet.seed
```

The file form keeps the value out of `ps` output. Resolution order is: `--seed-phrase-file <path>` > `--seed-phrase <phrase>` > `VESL_SEED_PHRASE` > `[wallet] seed_phrase = "..."` in `vesl.toml`. Avoid the last form for production — it pins live key material in a file that may end up in source control.

**3. Configure your hull:**

```toml
nock_home = "../nockchain"
settlement_mode = "dumbnet"
chain_endpoint = "https://your-nockchain-rpc.example"   # required
tx_fee = 256
coinbase_timelock_min = 1
accept_timeout_secs = 900   # dumbnet default; blocks land every ~10 min

[wallet]
account = 0
```

`chain_endpoint` is required for dumbnet — there is no compiled-in default. `accept_timeout_secs = 900` matches the live-network block cadence; a settle that triggers a tx won't return its effect until the network accepts.

**4. Run the hull**, supplying the seed phrase via the file flag:

```bash
cargo +nightly run --release -- \
  --settlement-mode dumbnet \
  --seed-phrase-file ~/.config/vesl/dumbnet.seed
```

For deployment, lock down both the seed file and the host running the hull — the BIP-39/BIP-44 derivation gives the hull spend authority over any UTXO locked to the resulting pkh.

::: info See Also

- [Build & Run](/build/build-run/) — kernel compile and settlement-mode selection.
- [Serve Subcommand](/build/build-run/serve) — running the dumbnet-configured hull as an HTTP server; the same seed-resolution rules apply to the Serve arm.
- [Fakenet Walkthrough](/build/build-run/fakenet) — the local-testnet counterpart; iterate there before pointing at dumbnet.
- [Reference / vesl.toml](/reference/vesl-toml) — full field list including the `[wallet]` schema.

:::

================================================================================
# Source: /build/testing/index.md
================================================================================

# Testing

`vesl-test` ships with vesl-nockup as both a Rust library (for `cargo test` integration tests) and a CLI (for ad-hoc kernel inspection). The vesl template wires the Rust dependency into `[dev-dependencies]` and lands a starter `tests/graft_lifecycle.rs` you can extend.

::: tip Quiet test output

`cargo test` inherits the kernel's `INFO`-level tracing (PMA durability sync, snapshot writes, event-log appends — hundreds of lines per test). The `--quiet` flag on the CLIs raises the log floor for one-shot CLI runs but does not propagate to the test harness. For a readable `cargo test` run, prepend `RUST_LOG=warn`:

```bash
RUST_LOG=warn cargo +nightly test --release
```

`RUST_LOG` (if set) wins over the default; `warn` is the same floor `--quiet` uses on the CLI side.

:::

## The Rust Library

Three pages cover the `vesl-test` crate.

### The Rust Harness

`GraftTestHarness` boots a compiled `out.jam` and runs the standard 8-op settle-graft suite. Walked on [The Rust Harness](/build/testing/harness).

### Domain Pokes

For grafts beyond settle-graft, the harness ships typed `harness.<verb>(...)` methods per poke arm (generated from `hoon/lib/harness-bindings.toml`) plus the universal `harness.poke_slab` escape hatch for unbound builders. `harness.peek_handle` reads state back. Walked on [Domain Pokes](/build/testing/domain-pokes).

### Slog Diagnostics

When the effect list alone can't tell a gate-deny from a cause-shape rejection, `poke_slab_report` captures the slogs the kernel emitted during the poke. Walked on [Slog Diagnostics](/build/testing/slog-diagnostics).

## The CLI

The `vesl-test` binary boots a compiled `out.jam` and exposes `inspect peek`, `watch`, and `verify-jam` for inspection without writing a Rust hull. Walked on [The CLI](/build/testing/cli).

::: info See Also

- [vesl-nockup README — Testing with vesl-test](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#testing-with-vesl-test) — harness API and standard-suite walkthrough.
- [`test/vesl-test/src/lib.rs`](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/test/vesl-test/src/lib.rs) — `GraftTestHarness` API, the standard-suite definition, `PokeReport` and slog parsing.

:::

================================================================================
# Source: /build/testing/harness.md
================================================================================

# The Rust Harness

After `nockup project init`, the project ships `tests/graft_lifecycle.rs`: a `#[tokio::test]` that boots the kernel via `GraftTestHarness` and runs the standard suite.

Compile the kernel first (`./compile.sh`), then `cargo test`. `run_standard_suite()` reports per-op pass/fail without panicking — `report.is_success()` is the gate.

## The Standard Suite

Of every graft vesl ships, only settle-graft gets a pre-baked **lifecycle** suite. Two reasons:

- **settle-graft is the foundation.** Every vesl-template kernel composes it, and its 8-op lifecycle is identical regardless of what domain you build on top. A single suite works against all of them.
- **Every other graft varies too much.** `kv-graft` keys state by cord. `counter-graft` carries the new value in its effect. `queue-graft`'s grammar differs by push vs. pop. `rbac-graft` is permission-bearing. A unified end-to-end suite would either reduce to "does the kernel boot" (useless) or balloon into per-graft branches (a maintenance trap).

What every graft *does* ship — generated from `hoon/lib/harness-bindings.toml` — is a typed `harness.<verb>(...)` method per poke arm and a typed `<Graft>Outcome` enum for pattern-matching the kernel's reply. See [Typed Per-Graft Methods](#typed-per-graft-methods) below; the standard 8-op suite remains settle-graft's only pre-baked end-to-end walkthrough.

`run_standard_suite()` exercises settle-graft's 8-op lifecycle. It uses three fixtures the crate exposes as public constants so your own tests can build on the state the suite leaves behind:

```rust
// test/vesl-test/src/lib.rs:30-32
pub const TEST_HULL_A: u64 = 1;
pub const TEST_HULL_B: u64 = 2;
pub const TEST_PAYLOAD: &[u8] = b"vesl-test fixture payload";
```

A [hull](/reference/glossary#hull) is a `u64` namespace key in settle-graft's state. Each hull keys its own registered Merkle root, independent from other hulls. Any `u64` is a valid hull id; an application uses as many distinct hulls as its domain needs (see [the trellis pattern](/build/grafts/trellis-pattern) for multi-hull designs).

The standard suite registers both `TEST_HULL_A` and `TEST_HULL_B` to cover trellis-pattern testing. Registering hull A doesn't affect hull B's state, and a note targeted at B lands in B's lifecycle. A single-hull app needs only `TEST_HULL_A`; importing `TEST_HULL_B` anyway is harmless, since it's just an unused `u64` constant. Your tests can import these constants to assert against state the suite populated.

`TEST_PAYLOAD` is the byte string the suite commits to and replays; using a fixed value keeps the Merkle root deterministic across runs.

Internally the suite mints a single-leaf Merkle root over `TEST_PAYLOAD` with `vesl_core::Mint`, then walks every settle-graft path:

| Op | Inputs | Expected effect |
|----|--------|-----------------|
| `register` | hull A, root | `%settle-registered` |
| `duplicate-register` | hull A, root (again) | `%settle-error` |
| `verify` | fresh note-id, hull A, root | `%settle-verified` |
| `register-b` | hull B, root | `%settle-registered` |
| `note` | fresh note-id, hull B, root | `%settle-noted` |
| `replay-note` | same note-id as `note` | `%settle-error` |
| `unregistered-hull` | hull 99,999 (never registered) | `%settle-error` |
| `root-mismatch` | hull A, payload root ≠ registered | `%settle-error` |

A `note-id` is the unique-identifier dimension settle-graft tracks for replay protection — every settled note within a hull's lifetime must carry an id no prior note used. The actual values the suite picks for its verify and note ops are inline fixtures (`1` and `42`); pick any unused id for your own follow-up pokes.

When the suite returns success the kernel state is fully determined:

- `TEST_HULL_A` and `TEST_HULL_B` are both registered against the same root.
- Note-id `1` is verified under hull A.
- Note-id `42` is settled under hull B.

Any kernel composed with `settle-graft` and the default single-leaf hash gate passes the standard suite as-is.

settle-graft's verify and note arms call whichever gate is installed as a Hoon function. settle-graft itself is gate-agnostic: it doesn't know which gate shape (single-leaf hash, multi-leaf, signed, STARK, or custom) is in the slot.

Only one gate is installed at a time, set at composition time via `[graft.gates]` in the manifest. The standard suite's payloads are shaped for the default single-leaf gate. If you replace the gate, write a custom lifecycle test with payloads shaped for your gate instead of relying on `run_standard_suite()`.

Each shipped gate has a matching poke builder:

- `build_settle_note_poke` — default single-leaf hash. (vesl-core)
- `build_settle_note_manifest_poke` — multi-leaf (manifest-verify). (vesl-core)
- `build_settle_note_membership_poke` — set membership. (vesl-core)
- `build_settle_note_ed25519_poke` — ed25519 signature. (vesl-core)
- `build_settle_note_schnorr_poke` — Schnorr signature. (vesl-core)
- `build_settle_note_bounded_poke` — bounded gate. (vesl-core)

Pick the builder for your gate and pass its gate-specific arguments (e.g., signature and pubkey for Schnorr, Merkle proof for manifest), then feed the resulting slab to `harness.poke_slab`. See [Build / Kernel — replacing a verification gate](/build/kernel/gates) for the replacement mechanics.

## Extending the Suite

The three fixtures are `pub` so a follow-up test can assert against suite-populated state, or drive more pokes against the same hulls without re-deriving the root. The tools you'll reach for:

- **`vesl_core::Mint`** — rebuilds the same Merkle root when fed `TEST_PAYLOAD`.
- **`vesl_core::build_graft_single_leaf_payload_jammed(note_id, hull, root, data)`** — builds the `[note=[id hull root [%pending ~]] data expected-root]` shape settle-graft expects.
- **`harness.register(hull, root)`**, **`harness.verify(payload)`**, **`harness.note(payload)`** — pre-typed-harness shortcuts that take pre-jammed payloads. The typed `harness.settle_register(hull, root)` / `harness.settle_note(note_id, hull, root, data)` / `harness.settle_verify(...)` methods (generated; see below) take primitive args and build the payload for you.

```rust
// tests/graft_lifecycle.rs (extending the starter test)
use vesl_core::{build_hull_peek_path, Mint, PokeOutcome};
use vesl_test::{TEST_HULL_A, TEST_PAYLOAD};

// ... after run_standard_suite() ...

// 1. Confirm hull A is registered.
let path = build_hull_peek_path("settle-registered", TEST_HULL_A);
let registered = harness.peek_handle(path).await?;
assert!(registered.is_some(), "hull A should be registered after the suite");

// 2. Add a new note (id 7) against the same hull and root via the
//    typed method — no manual payload build, returns a typed PokeOutcome.
let mut mint = Mint::new();
let root = mint.commit(&[TEST_PAYLOAD]);
let outcome = harness.settle_note(7, TEST_HULL_A, &root, TEST_PAYLOAD).await?;
assert!(matches!(outcome, PokeOutcome::Accepted { .. }));
```

The harness method returns a typed [`vesl_core::PokeOutcome`](https://github.com/zkvesl/vesl-core/blob/main/crates/vesl-core/src/poke.rs) — match on the variant to distinguish acceptance, deterministic rejection (gate-deny, kernel-error, replay), and driver-level crash. For the per-graft typed refinement (`SettleOutcome::RegisterRejected { ... }`, `CounterOutcome::Error { msg }`, etc.) see [Typed Per-Graft Methods](#typed-per-graft-methods) below.

## Typed Per-Graft Methods

`hoon/lib/harness-bindings.toml` declares one Rust method per poke arm across every shipped graft. `nockup-graft codegen harness-methods` materializes them into `test/vesl-test/src/generated_harness.rs`, which is committed and verified against the sidecar by `tools/graft-inject/tests/harness_codegen.rs` (CI fails if a contributor edits the sidecar without regenerating). The result: every graft has the same typed `harness.<verb>(...)` surface, not just settle.

```rust
// counter-graft lifecycle through the generated typed methods
use vesl_core::PokeOutcome;
use vesl_test::{GraftTestHarness, CounterOutcome, CounterOutcomeExt};

let mut harness = GraftTestHarness::boot(&jam_path).await?;

// Each method takes the same args its build_*_poke counterpart would
// take, delegates to that builder, and returns Result<PokeOutcome>.
let outcome = harness.counter_set("clicks", 41).await?;
assert!(matches!(outcome, PokeOutcome::Accepted { .. }));

let outcome = harness.counter_increment("clicks").await?;
assert!(matches!(outcome, PokeOutcome::Accepted { .. }));

// Trigger saturation. The kernel emits
// [%counter-error msg='counter-graft: counter saturated at 2^64'];
// the typed CounterOutcome::Error variant decodes the cord.
let _ = harness.counter_set("max", u64::MAX).await?;
let outcome = harness.counter_increment("max").await?;
match outcome.as_counter_outcome() {
    CounterOutcome::Error { msg } => {
        assert!(msg.contains("saturated"));
    }
    other => panic!("expected CounterOutcome::Error, got {other:?}"),
}
```

The generated surface, per graft, is:

- **`harness.<verb>(...) -> Result<PokeOutcome>`** — one method per `[[graft.pokes]]` entry. Method name and arg types come from the sidecar; the body delegates to the existing `vesl_core::build_*_poke` builder.
- **`<Graft>Outcome`** — typed enum with `Accepted`, `Error { msg }` (for `%<graft>-error msg=@t`), typed struct variants per `[[graft.rejected]]` entry, `Denied { reason }` (for `%<graft>-denied reason=@t`), `Unknown`, and `Crashed`.
- **`<Graft>OutcomeExt`** — extension trait on `vesl_core::PokeOutcome` with `as_<graft>_outcome(&self) -> <Graft>Outcome`. Routes by the kernel-emitted cord's `<graft>-graft:` prefix so a counter-graft error doesn't get misread as a settle error.

Match on `<Graft>Outcome::<Variant>` when a test cares about the specific rejection reason; match on `PokeOutcome::Accepted { effects }` directly when you only need the success effects. Both are valid surfaces.

::: warning Typed-rejection field decoding is partial in 3b(1)

Typed-rejection variants like `SettleOutcome::RegisterRejected { hull, existing_root }` match the variant correctly, but the bound field values are zero/empty in this cut — real decoding from `raw_effects` is queued as `vesl-nockup-v2.0` item G4. Tests can pattern-match on the variant for routing; consumers that need the field values reach for `raw_effects` until G4 lands.

:::

The full bound set today: counter (3), kv (2), rbac (2), batch (3), clock (1), forge (1), guard (2), log (1+1), mint (1), queue (3+1), registry (3+2), settle (3), validate (2). 32 methods across 13 grafts. settle's per-gate convenience builders (`build_settle_note_schnorr_poke` etc.) are NOT bound — their argument types come from `nockchain-types` which isn't re-exported by vesl-core; use `harness.poke_slab(build_settle_note_schnorr_poke(...))` for those.

================================================================================
# Source: /build/testing/domain-pokes.md
================================================================================

# Domain Pokes

For grafts beyond settle-graft, the harness gives you two layered surfaces:

1. **Typed methods** — `harness.<verb>(...)` per poke arm, generated from `hoon/lib/harness-bindings.toml`. Returns a typed [`vesl_core::PokeOutcome`](https://github.com/zkvesl/vesl-core/blob/main/crates/vesl-core/src/poke.rs). Use this when the graft has a bound method (every shipped graft does for its primary arms).
2. **`harness.poke_slab`** — the universal escape hatch. Takes a fully-built `NounSlab` and returns the same `PokeOutcome`. Use this for unbound builders (the settle convenience variants, domain pokes you build by hand) or when you want the raw control.

The matching read surfaces are `harness.peek_handle(path)` for the standard unit-collapsed shape and `harness.peek_raw(path)` for nested-unit paths. Asserting on the effect head tag or the typed outcome variant proves the cause landed; peeking confirms the side effect did.

## Driving Causes — Typed Methods

Every poke arm in every shipped graft has a typed method on `GraftTestHarness`. The method name matches the snake-case form of the cause tag (e.g. `%counter-set` → `counter_set`); arg types match the underlying `build_*_poke` builder. The body returns `Result<PokeOutcome>`.

```rust
// counter-graft increment via the typed method
use vesl_core::PokeOutcome;
use vesl_test::GraftTestHarness;

let outcome = harness.counter_increment("requests").await?;
assert!(matches!(outcome, PokeOutcome::Accepted { .. }));
```

For typed routing on the specific rejection variant, use the per-graft extension trait:

```rust
use vesl_test::{CounterOutcome, CounterOutcomeExt};

// Trigger saturation and route on the typed Error variant.
let _ = harness.counter_set("max", u64::MAX).await?;
let outcome = harness.counter_increment("max").await?;
match outcome.as_counter_outcome() {
    CounterOutcome::Error { msg } => assert!(msg.contains("saturated")),
    other => panic!("expected counter saturation, got {other:?}"),
}
```

`<Graft>OutcomeExt` is generated alongside the typed methods; see [Harness → Typed Per-Graft Methods](/build/testing/harness#typed-per-graft-methods) for the full surface (32 bound methods + 13 outcome enums + 13 extension traits across the shipped grafts).

## Driving Causes — `poke_slab` Escape Hatch

When a builder isn't bound to a typed method — the settle per-gate convenience builders (`build_settle_note_schnorr_poke` and siblings, whose arg types come from `nockchain-types` which isn't re-exported by vesl-core), or a domain poke you constructed by hand — drop down to `harness.poke_slab(slab)`. Same `Result<PokeOutcome>` return; same typed match on the result.

```rust
// settle-graft Schnorr-gate note — no typed method (skipped per
// harness-bindings.toml rationale); use the SDK builder directly.
use vesl_core::{PokeOutcome, build_settle_note_schnorr_poke};

let slab = build_settle_note_schnorr_poke(note_id, hull, &root, data, &sig, &pubkey);
let outcome = harness.poke_slab(slab).await?;
assert!(matches!(outcome, PokeOutcome::Accepted { .. }));
```

The naming convention covers both surfaces: builders are `build_<graft>_<verb>_poke`, effect tags are `<graft>-<verb-past-tense>`, and each graft also emits `<graft>-error` (with `msg=@t`) for any failure path. counter-graft's increment builds via `build_counter_increment_poke`, emits `%counter-incremented` on success and `%counter-error` on saturation or capacity.

The full shipping set. Every row (except the settle per-gate variants and the intent placeholder) is also reachable as `harness.<method>(...)` per `hoon/lib/harness-bindings.toml`; method names match the snake-case form of the cause tag (`%counter-set` → `counter_set`). See [Harness → Typed Per-Graft Methods](/build/testing/harness#typed-per-graft-methods) for the typed-outcome variants.

| Graft | Builder | Cause | Success effect | Error effect |
|---|---|---|---|---|
| **settle** | `build_settle_register_poke(hull, root)` | `%settle-register` | `%settle-registered` | `%settle-error` |
|   | `build_settle_verify_poke(note_id, hull, root, payload)` | `%settle-verify` | `%settle-verified ok=?` | `%settle-error` |
|   | `build_settle_note_poke(note_id, hull, root, payload)` | `%settle-note` | `%settle-noted` (+ `%settle-epoch-rotated` on epoch boundary) | `%settle-error` |
| **settle** (per-gate `note` variants) | `build_settle_note_schnorr_poke` | `%settle-note` | `%settle-noted` | `%settle-error` |
|   | `build_settle_note_ed25519_poke` | `%settle-note` | `%settle-noted` | `%settle-error` |
|   | `build_settle_note_manifest_poke` | `%settle-note` | `%settle-noted` | `%settle-error` |
|   | `build_settle_note_membership_poke` | `%settle-note` | `%settle-noted` | `%settle-error` |
|   | `build_settle_note_bounded_poke` | `%settle-note` | `%settle-noted` | `%settle-error` |
| **mint** | `build_mint_commit_poke(hull, root)` | `%mint-commit` | `%mint-committed` | `%mint-error` |
| **guard** | `build_guard_register_poke(hull, root)` | `%guard-register` | `%guard-registered` | `%guard-error` |
|   | `build_guard_check_poke(hull, data)` | `%guard-check` | `%guard-checked ok=?` | `%guard-error` |
| **forge** | `build_forge_prove_poke(hull, note_id, data)` | `%forge-prove` | `%forge-proved` | `%forge-error` |
| **kv** | `build_kv_set_poke(key, value)` | `%kv-set` | `%kv-stored` | `%kv-error` |
|   | `build_kv_delete_poke(key)` | `%kv-delete` | `%kv-deleted` | `%kv-error` |
| **counter** | `build_counter_increment_poke(name)` | `%counter-increment` | `%counter-incremented` | `%counter-error` |
|   | `build_counter_set_poke(name, value)` | `%counter-set` | `%counter-set` | `%counter-error` |
|   | `build_counter_reset_poke(name)` | `%counter-reset` | `%counter-reset` | `%counter-error` |
| **queue** | `build_queue_push_poke(payload)` | `%queue-push` | `%queue-pushed` | `%queue-error` |
|   | `build_queue_pop_poke()` | `%queue-pop` | `%queue-popped` | `%queue-error` |
|   | `build_queue_clear_poke()` | `%queue-clear` | `%queue-cleared` | `%queue-error` |
| **rbac** | `build_rbac_grant_poke(pubkey, perms)` | `%rbac-grant` | `%rbac-granted` | `%rbac-error` |
|   | `build_rbac_revoke_poke(pubkey, perms)` | `%rbac-revoke` | `%rbac-revoked` | `%rbac-error` |
| **registry** | `build_registry_put_poke(key, record)` | `%registry-put` | `%registry-stored` | `%registry-error` |
|   | `build_registry_update_poke(key, record)` | `%registry-update` | `%registry-updated` | `%registry-error` |
|   | `build_registry_del_poke(key)` | `%registry-del` | `%registry-deleted` | `%registry-error` |
| **validate** | `build_validate_init_poke(cause_tag, rules)` | `%validate-init` | `%validate-rules-installed` | `%validate-error` |
|   | `build_validate_clear_poke(cause_tag)` | `%validate-clear` | `%validate-rules-cleared` | `%validate-error` |
|   | (prelude rejection — no Rust builder) | (fires from `poke-prelude`) | `%validate-rejected` | (silent denial) |
| **log** | `build_log_append_poke(tag, data)` | `%log-append` | `%log-appended` | `%log-error` |
| **clock** | `build_clock_tick_poke()` | `%clock-tick` | `%clock-ticked` | `%clock-error` |
| **batch** | `build_batch_init_poke(threshold)` | `%batch-init` | `%batch-initialized` | `%batch-error` |
|   | `build_batch_add_poke(intent)` | `%batch-add` | `%batch-added` | `%batch-error` |
|   | `build_batch_flush_poke()` | `%batch-flush` | `%batch-flushed` | `%batch-error` |
| **intent** (placeholder) | (no Rust builders shipped) | `%intent-declare` / `%intent-match` / `%intent-cancel` / `%intent-expire` | `%intent-declared` / `%intent-matched` / `%intent-cancelled` / `%intent-expired` | `%intent-error` |

The `_from_noun` variants exist for grafts that take pre-jammed payloads (registry, log, queue, batch); pass a `&NounSlab` instead of a `&[u8]`. The `_with_data` variants (settle only) take a closure that writes the payload directly into the slab. The source-of-truth module tree is [`crates/vesl-core/src/graft_pokes/`](https://github.com/zkvesl/vesl-core/tree/11d110d/crates/vesl-core/src/graft_pokes).

## Reading State

`harness.peek_handle(path)` reads kernel state without modifying it. It returns `Result<Option<NounSlab>>`:

- **`Err`** — kernel returned bare `~`; either the path is malformed or the graft owning the tag isn't composed.
- **`Ok(None)`** — path is recognized but the value is absent (`[~ ~]`).
- **`Ok(Some(slab))`** — value is present (`[~ [~ value]]`).

Build the path via one of three helpers in `vesl-core`, depending on the peek's keying scheme:

| Path shape | Builder | When grafts use it |
|------------|---------|--------------------|
| `[%<tag> ~]` (keyless) | `build_keyless_peek_path("log-len")` | Singletons (counts, epochs) |
| `[%<tag> hull ~]` (hull-keyed) | `build_hull_peek_path("settle-registered", hull)` | Per-hull state (commitment grafts) |
| `[%<tag> @t %<key> ~]` (cord-keyed) | `build_keyed_peek_path("counter-value", "requests")` | Per-name state (kv, counter, queue) |

For the counter increment above, the matching peek:

```rust
// Example: matching peek for the counter increment above
use vesl_core::build_keyed_peek_path;

let path = build_keyed_peek_path("counter-value", "requests");
let value = harness.peek_handle(path).await?;
assert!(value.is_some(), "counter should be present after increment");
```

## `peek_raw` — Nested-Unit Paths

A few peek paths return `(unit (unit *))` instead of flattening to `Option`. settle-graft's `%settle-root` is the canonical example: it returns `[~ [~ (unit @)]]` so the outer wrapper signals path-recognized vs. unrecognized while the inner unit lets the value itself be absent (a registered hull that doesn't have a root yet).

`harness.peek_raw(path)` returns the raw shape without unwrapping. Pattern-match on the inner unit yourself when you need that level of detail.

================================================================================
# Source: /build/testing/slog-diagnostics.md
================================================================================

# Slog Diagnostics

When the effect list alone can't distinguish gate-deny from cause-shape-reject, swap [`poke_slab`](/build/testing/domain-pokes#driving-causes) for `poke_slab_report`. It runs the same poke but also captures every slog emitted at `target: "slogger"` during the call into a `PokeReport`:

```rust
// Example: asserting on slog diagnostics in your test
use vesl_test::{decode_cause_tag, SlogWarning};

let report = harness.poke_slab_report(slab).await?;

// Bare "did the kernel reject the cause shape?" check.
assert!(report.rejected_cause(), "kernel should have rejected the cause");

// Or assert on which tag the kernel saw before rejecting.
for warning in &report.slog_warnings {
    if let SlogWarning::InvalidCause { noun } = warning {
        assert_eq!(
            decode_cause_tag(noun).as_deref(),
            Some("my-typo"),
            "rejected cause tag should match the hull-side typo",
        );
    }
}
```

`PokeReport` fields:

- **`effect_tags: Vec<String>`** — same as `poke_slab`'s return.
- **`slog_warnings: Vec<SlogWarning>`** — slogs captured during the poke. Each is one of:
  - **`InvalidCause { noun }`** — kernel's `(soft cause)` rejected the cause shape.
  - **`Other(String)`** — any other slog emitted at `target: "slogger"`.

Helper: **`decode_cause_tag(noun) -> Option<String>`** parses the leading tag from Hoon's printed-noun format. It handles both the cord-decoded `[%foo ...]` shape and the dotted-decimal fallback.

See [Troubleshooting — distinguishing denial paths](/troubleshooting/common-pitfalls#distinguishing-denial-paths) for which slog shape maps to which failure mode.

================================================================================
# Source: /build/testing/cli.md
================================================================================

# The CLI

The `vesl-test` binary boots a compiled `out.jam` and exposes three subcommands for inspection without writing a Rust hull, plus a `completions` subcommand for shell tab-completion.

## Installing `vesl-test`

The binary is bundled in the vesl-nockup repo at `test/vesl-test/`. It depends on nockchain crates via sibling-path deps, so install it from a local vesl-nockup checkout with a sibling `nockchain/` clone (the layout the [quickstart](/setup/quickstart) describes):

```bash
cd vesl-nockup
cargo install --path test/vesl-test --locked
```

`cargo install --git` does not work for this binary because the sibling-path deps don't resolve from cargo's git cache.

## `inspect peek` — One-Shot Kernel Inspection

```bash
# keyless: [%log-len ~]
vesl-test inspect peek out.jam --path-tag log-len

# hull-keyed: [%settle-registered hull=1 ~]
vesl-test inspect peek out.jam --path-tag settle-registered --hull 1

# cord-keyed: [%kv-value @t %greeting ~]
vesl-test inspect peek out.jam --path-tag kv-value --key greeting

# stable JSON for downstream tooling
vesl-test inspect peek out.jam --path-tag log-len --json
```

Each peek returns one of three states:

- **unrecognized** — `++peek` returned bare `~`. Either the path is malformed or the graft owning the tag isn't composed.
- **present-but-empty** — `[~ ~]`. Path is recognized; no value at that key.
- **present** — `[~ [~ value]]`. Atoms render as both Hoon-style decimal-with-dots and (when LE bytes form printable UTF-8) ASCII.

Hoon-literal paths (e.g. `[%kv-value @t %my-key]` typed directly) are out of scope; the `--path-tag` + `--hull` / `--key` form covers every shape the shipped grafts use.

## `watch` — Live-Trace REPL

`inspect peek` is one-shot. When you need to see the kernel reacting to a sequence of pokes — what cause came in, what effects went out, which slogs fired — `vesl-test watch <out.jam>` is the live-trace surface:

```bash
# interactive: type pokes at the prompt, watch effects render below
vesl-test watch out.jam

# pipe a script of pokes
cat pokes.txt | vesl-test watch out.jam --json

# filter by cause-tag
vesl-test watch out.jam --filter cause=settle-register
```

Stdin grammar covers tag-only pokes (`poke-tag <tag>`), hex-encoded pre-jammed pokes (`poke-jam <hex> [tag=<name>]`), keyless / hull-keyed / cord-keyed peeks, a `state` heartbeat, and `quit` for clean shutdown. The README has the full table and the JSON event schema.

When the spawned `app.run()` task panics or returns an error, `watch` prints a `kernel-died: <reason>` row instead of crashing itself. That kernel-died case is the main reason to reach for `watch` over `inspect peek`. Any time you can't tell from a bare poke return whether the kernel saw what you sent, `watch` puts the cause and effect-list on the wire.

## `verify-jam` — Build Staleness Check

Confirm `out.jam` is fresh against the source files it was compiled from:

```bash
vesl-test verify-jam .        # exit 0 fresh, 1 stale, 2 no fingerprint
vesl-test verify-jam . --json # structured output for CI
```

The fingerprint sidecar (`.out-jam-source-fingerprint`) is a `sha256sum` listing of `hoon/app/app.hoon`, each `hoon/lib/*.hoon` graft library, and each `hoon/lib/*.toml` manifest. Generate it after a clean compile; check it before booting a long-built kernel. See [Build / Build & Run — verify-jam](/build/build-run/#verify-jam-structured-alternative) for the full compile + fingerprint pipeline.

## `completions` — Shell Tab-Completion

Emit a clap-generated completion script to stdout. One-line install per shell — see [quickstart → Shell completions](/setup/quickstart#shell-completions-optional) for the matching `nockup-graft` lines.

```bash
vesl-test completions bash > ~/.local/share/bash-completion/completions/vesl-test
vesl-test completions zsh  > "${fpath[1]}/_vesl-test"
vesl-test completions fish > ~/.config/fish/completions/vesl-test.fish
```

Re-run after a `cargo install --force` so the script tracks the binary's current subcommand and flag set.

================================================================================
# Source: /build/state-snapshots.md
================================================================================

# State & Snapshots

**After reading:** you'll know which kernel changes survive PMA-resume, which need an explicit snapshot, and what `nockup:load-defaults` does when the shape changes.

Kernel state lives inside the compiled `out.jam` and changes one poke at a time. When you need to upgrade the kernel — adding a graft, fixing a transition bug, retuning a verification gate — you snapshot the current state, recompile, and rehydrate.

```d2
direction: right

start: "" {
  shape: circle
  width: 24
  height: 24
  style.fill: "#00ffa3"
}
end: "" {
  shape: circle
  width: 24
  height: 24
  style.fill: "#00ffa3"
}
running: Running
snapshotted: Snapshotted
resumed: Resumed

start -> running
running -> snapshotted: "snapshot(app, dir, app.hoon)"
snapshotted -> resumed: "resume(out.jam, &snap, name)"
resumed -> running: "poke / peek"
running -> end: drop
```

## State Lives in the Kernel

Each graft contributes one or more fields to `+$ versioned-state` at the `::  nockup:state` marker. Your domain adds its own fields between or after them. The kernel reads/writes `state` inside every `?-` arm; nothing else holds it.

For commitment grafts the canonical state shape is `settle-state`:

```hoon
+$  settle-state
  $:  epoch=@                     ::  current epoch number
      registered=(map @ @)        ::  hull-id -> merkle-root
      settled=(set @)             ::  current-epoch note-ids (replay protection)
      settle-count=@              ::  notes settled in current epoch
      prior-settled=(set @)       ::  previous epoch's set (kept for lookback)
  ==
```

The `epoch` / `settle-count` / `prior-settled` fields support count-based rotation — the settled set rotates after 1M settles per epoch, keeping a two-epoch lookback window for replay detection.

## Snapshot a Kernel

The vesl template wires `vesl-checkpoint` into `[dev-dependencies]` alongside `vesl-test`. Move it to `[dependencies]` if the snapshot path runs in production.

```rust
use vesl_checkpoint::{snapshot, resume};

let mut harness = GraftTestHarness::boot("out.jam").await?;
harness.register(1, &root).await?;

let snap_dir = std::path::Path::new("snapshots/before-mint-graft");
let snap = snapshot(harness.app(), snap_dir, "hoon/app/app.hoon").await?;
drop(harness);
```

Bundle layout written to disk:

```
snapshots/before-mint-graft/
├── state.jam   (bincode-encoded ExportedState — same format
│                that nockapp::Cli::state_jam accepts on import)
└── meta.toml   ([snapshot] source_sha256, timestamp,
                 vesl_checkpoint_version)
```

## Resume a Kernel

`resume` boots a fresh `NockApp` from `out.jam` (typically the kernel you just recompiled) with the snapshot's state imported. It sets nockapp's `Cli::state_jam` to the bundle's `state.jam` and runs the standard boot path, so the new kernel rehydrates state on top of its own definition. Whether that state survives a changed composition depends on what changed — the next section covers the three cases.

```rust
let resumed = resume("out.jam", &snap, "after-mint-graft").await?;

let peek_path = vesl_core::build_hull_peek_path("settle-root", 1);
let result = resumed.peek(peek_path).await?;
let stored_root = vesl_core::unwrap_triple_unit_atom(&result);
assert_eq!(stored_root.as_deref(), Some(&root_bytes[..]));
```

## Resume Across Composition Changes

### Same Composition

The new kernel has the same set of grafts as the snapshot. State roundtrips cleanly — the snapshot's data is preserved, and both pre- and post-resume pokes emit effects. There are no new graft axes, so the defaults overlay does not run and nothing is reset.

### Schema Extension

The new kernel adds grafts that weren't in the snapshot. `nockup graft` codegen at the `::  nockup:load-defaults` marker emits a `=/ defaults ^*(versioned-state)` + `%_ defaults <field> ^*(<field>-state) ... ==` overlay so resumed snapshots with a smaller noun shape get type defaults at the new graft axes instead of panicking inside the wrapper's mule guard.

The earlier identity-load placeholder silently dropped effects on every graft past the first added priority band; the defaults-overlay codegen replaces that placeholder.

### Manual Migration

Snapshots are tied to a kernel composition. Adding a graft is handled by the defaults overlay; removing one or changing a state field's shape is not. The schema-migration helper is intentionally out of scope — you re-poke after resume to set up the desired state, or migrate state out of the old kernel and into the new via a domain peek/poke round-trip.

::: info Stuck?

Something broken? The breakage is probably already in [Common Pitfalls](/troubleshooting/common-pitfalls).

:::

::: info See Also

- [vesl-core → Committing Over Graft State](/reference/vesl-core#committing-over-graft-state) — committing a Merkle root over a graft's state shape from inside a domain cause. The temporal-staleness footgun (snapshot reflects post-poke state, not pre-poke) is documented there.
- [vesl-nockup README — State checkpoints](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#state-checkpoints) — snapshot + resume operator guide.
- [`tools/graft-inject/tests/checkpoint_lifecycle.rs`](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/tools/graft-inject/tests/checkpoint_lifecycle.rs) — state survives same-composition resume modulo the defaults overlay.
- [`crates/vesl-checkpoint/tests/end_to_end.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-checkpoint/tests/end_to_end.rs) — full snapshot + resume lifecycle in vesl-core.

:::

================================================================================
# Source: /build/updating.md
================================================================================

# Updating a Project

A built project is a frozen snapshot. vesl-nockup reaches it through several independent channels, and none of them auto-propagate — an update is pulled, not pushed. `Cargo.lock` freezes the Rust graph, the template files are your copies, and `app.hoon` is yours. A vesl-nockup release changes nothing in a built project until you reinstall the `nockup-graft` binary, run `nockup package install`, or run `cargo update`.

## What an update reaches

| Channel | Carries | Reaches the project via |
|---|---|---|
| `nockup-graft` binary | the graft composer | re-running `cargo install --git … --bin nockup-graft` |
| `zkvesl/vesl-graft` package | the Hoon graft library under `hoon/lib/` | `nockup package install` |
| `vesl` template | scaffold files (`Cargo.toml`, `build.rs`, `main.rs`, `app.hoon`) | only `nockup project init` — never an existing project |
| Bundled crates (`vesl-core`, `vesl-hull`, `vesl-test`) | the Rust SDK | git-deps in `Cargo.toml`, frozen by `Cargo.lock` until `cargo update` |
| Pins (`NOCK_PIN`, `VESL_CORE_PIN`, `VESL_WALLET_PIN`) | the nockchain and vesl-core revs baked into a scaffold | template `Cargo.toml` revs, set once at scaffold time |

The `vesl` template channel never re-touches a project once it is scaffolded. The `nockup-graft` binary and the `vesl-graft` package update on separate schedules and are not version-locked — update both in the same pass so the composer and the manifests it reads stay in step.

## The update sequence

Run from the project root, in order.

1. **Commit or stash all work.** `nockup graft update` rewrites `app.hoon`; an isolated diff is reviewable, a mixed one is not.
2. **Snapshot live state.** For a running deployment, `vesl-checkpoint::snapshot` the kernel before recompiling. See [State & Snapshots](/build/state-snapshots).
3. **Update the composer:**
   ```bash
   cargo install --git https://github.com/zkvesl/vesl-nockup --bin nockup-graft --force
   ```
   Do this first — `nockup graft update` cannot replace its own running binary, and stops with this instruction if the refreshed library needs a newer one.
4. **Run the update:**
   ```bash
   nockup graft update hoon/app/app.hoon
   ```
   One verb for the recomposition: it runs `nockup package install`, previews the recomposition with the `nockup graft doctor` health report, prompts for confirmation, then writes via `inject --apply`. Read the preview before pressing `y` — a `hand-edited-block` finding means a customization inside a banner pair is about to be overwritten. `--yes` skips the prompt for CI.
5. **Reconcile `Cargo.toml`.** A pin bump changes the nockchain and vesl-core revs the project should resolve to. The `nockup package install` that step 4 runs re-applies vesl-graft's `[[patches]]`; confirm the `[patch]` block agrees, then `cargo update -p vesl-core` rather than a blanket `cargo update`.
6. **Recompile:**
   ```bash
   ./compile.sh
   ```
   `compile.sh` wraps `hoonc` and fails loud if hoonc [exits 0 with no jam written](/troubleshooting/common-pitfalls).
7. **Rebuild:** `cargo +nightly build`. The scaffold's `build.rs` re-runs `nockup graft doctor`, so a residual finding shows up in the build output.
8. **Resume.** After a snapshot, `vesl-checkpoint::resume` from the new `out.jam`, then re-poke to restore state — resume reinitializes graft state to per-graft defaults.
9. **Re-run the lifecycle suite** with `vesl-test` to confirm the kernel still behaves.

`nockup graft update` absorbs the old install/preview/apply trio. Driving `nockup graft inject --apply` by hand still works when you want composition without the orchestrator.

## Re-injection is not a merge

`nockup graft inject` owns the region between each `::  graft-inject:<graft>:<marker>:begin` and `:end` banner pair. Every `--apply` — and every `nockup graft update` — strips that region and re-emits it from the manifest. It does not merge.

::: warning Edits inside a banner pair are discarded
Domain code added at the `::  nockup:*` markers but outside any banner pair — causes, peeks, `?-` arms — survives a re-inject untouched. Code typed *between* a graft's `begin` and `end` banners does not: the next re-injection overwrites it, whether or not the manifest changed.

The common trap is replacing a verification gate by editing the gate body inside a `%settle-*` arm. That arm lives inside the `settle-graft:poke` block, so the next re-injection reverts it to the default hash gate. Change the gate through `[graft.gates]` in the manifest instead — see [Swapping a Gate](/build/catalog-gates/swapping).
:::

`nockup graft doctor` flags a hand-edited block before it is lost — it runs on every `cargo build` (the scaffold's `build.rs` invokes it) and in `nockup graft update`'s preview.

The inverse case — a local edit to a graft *library* file (`<name>-graft.hoon`) that leaves `inject` reporting `injected 0/N; skipped …` but `./compile.sh` still bakes the edit into `out.jam` — is covered in [Inject → Manifest SHA vs Library Edits](/build/grafts/inject#manifest-sha-vs-library-edits). Manifest TOML edits drive re-inject; library Hoon edits drive re-compile only.

## When an update breaks the build

Update-time failures are catalogued in [Common Pitfalls](/troubleshooting/common-pitfalls). The ones an update specifically provokes:

| Symptom | Cause |
|---|---|
| `hoonc` exits 0, no `out.jam` | a newer graft library pulled a Hoon import the project's frozen `hoon/common`, `hoon/dat`, or `hoon/jams` subset doesn't satisfy — refresh those trees from a vesl-nockup checkout |
| `hoonc` fails `mint-lost` / `-lost %<tag>` | the composer and the manifests are out of step — re-run steps 3 and 4 together |
| `cargo build` fails on `ibig` / `UBig` | a pin moved; the `[patch]` block no longer matches the nockchain rev `vesl-core` resolves to — realign it (step 7) |
| poke returns `Ok(vec![])`, stderr `slog: invalid cause` | the kernel re-composed with a renamed cause-tag the hull still calls by its old name — update the hull, and guard future renames with `assert_kernel_cause_tag!` |
| post-resume pokes emit nothing | the snapshot predates a graft-composition change — see [Manual Migration](/build/state-snapshots#manual-migration) |
| `nockup graft inject` / `update` errors `manifest schema too new` | the graft library declares a newer manifest schema than the installed `nockup-graft` — update the binary (step 3) and re-run |

::: info See Also

- [vesl-nockup README — Updating an existing project](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#updating-an-existing-project) — the procedure's source of truth.
- [State & Snapshots](/build/state-snapshots) — snapshot and resume across a composition change.
- [Inject](/build/grafts/inject) — marker semantics and the per-graft sha256 banner.
- [Common Pitfalls](/troubleshooting/common-pitfalls) — symptom-led catalogue of build and runtime failures.

:::

================================================================================
# Source: /reference/glossary.md
================================================================================

# Glossary

Two sections, each alphabetized. **Building blocks** covers the project artifacts, files, and tools you assemble — what your directory contains and which CLI runs over what. **Hoon** covers the language constructs you write into your kernel — the arms, types, and utilities that make up the kernel source. Hoon entries also appear (with worked examples) on [Build / Kernel](/build/kernel/); the duplication is intentional.

## Building Blocks

### Block

A snippet of Hoon a graft contributes at a single marker. `[graft.blocks.<marker>]` in the manifest declares the block's contents; `nockup graft inject` splices it into `app.hoon` at the matching `::  nockup:<marker>` anchor. See [Grafts / Manifest Schema](/build/grafts/manifest-schema).

### Driver

Synonym for *hull* in vesl docs — see [Hull](#hull). Note that nockchain itself uses *driver* for I/O subcomponents inside `NockApp` (`nockapp::driver::*`, `nockapp/src/drivers/{file,http,timer,...}.rs`); those run inside the hull and aren't surfaced through the SDK.

### Family

One of the priority bands in vesl's graft taxonomy. The priority number orders graft injection and labels the family. See [Build / Grafts / The 5-Family Graft Taxonomy](/build/grafts/#the-5-family-graft-taxonomy) for the bands, their priority ranges, and members.

### Graft

A composable unit shipped as `<name>-graft.hoon` (the Hoon library) plus a sibling `<name>-graft.toml` (the manifest). `nockup graft inject` discovers manifests under `hoon/lib/` and splices their declared blocks into your kernel. See [Build / Grafts](/build/grafts/).

### nockup graft

The CLI that composes grafts into a kernel. Discovers manifests, splices per-marker blocks into `app.hoon`, runs lint families, and emits per-graft sha256 banners. Preview by default; `--apply` writes to disk. The underlying binary is `nockup-graft` (sidecar to `nockup`'s plugin discovery); error output and on-disk banner comments still identify it as `graft-inject` since that's the source-of-truth name. See [Reference / CLI](/reference/cli).

### Hoon

Nockchain's source language. Compiles to Nock; kernel source files are Hoon. See [Build / Kernel](/build/kernel/).

### hoonc

The Hoon compiler. Reads `hoon/app/app.hoon` (plus the library tree) and produces `out.jam` — the kernel bytes the hull loads. Ships in the [nockchain](https://github.com/nockchain/nockchain) toolchain.

### Hull

In vesl: the Rust process that hosts the kernel — the Rust harness in your `src/main.rs` that boots `out.jam` as a `NockApp`, sends pokes, and reads effects. Also the `hull=@` keying scheme that commitment grafts use to address logical cells. See [Build / NockApp Anatomy](/build/anatomy).

### JAM

Nockchain's serialization format for nouns. `jam` produces a deterministic byte sequence from a noun; `cue` reads the bytes back into a noun. JAM is part of the nockchain runtime, not vesl.

### Kernel

The compiled `out.jam` running inside `NockApp`. Logic-only (no I/O), pure functions over nouns, deterministic. The hull does the I/O and the kernel does the math.

### Manifest

A graft's `<name>-graft.toml` file. Declares per-marker blocks of Hoon, gate selection, type names, and metadata (priority, version, stability). See [Grafts / Manifest Schema](/build/grafts/manifest-schema).

### Marker

One of the ten `::  nockup:*` anchor comments in `templates/app.hoon`. `nockup graft inject` splices graft blocks at the markers; the codegen markers (`domain-effect`, `effect-union`, `load-defaults`) are anchors for the composer's own passes. See [Build / NockApp Anatomy — Anchor Markers](/build/anatomy#anchor-markers) for the per-marker definitions.

### nockchain

The upstream runtime. Provides Nock, Hoon, the `NockApp` harness, JAM, and tip5. vesl runs a Hoon kernel inside a `NockApp` and ships a graft library on top.

### nockup

Nockchain's developer CLI. `nockup project init` scaffolds a NockApp project; `nockup package add` installs grafts. vesl-nockup will eventually ship as a package within it.

### NounSlab

The Rust noun container. The hull allocates nouns into a slab, builds a poke head and arguments inside it, and submits the slab to the kernel via `app.poke(...)`. Defined in `nockapp::noun::slab`. See [Build / Hull](/build/hull).

### Panic

A runtime crash. In the hull, a Rust `panic!` aborts the spawned `app.run()` task — `vesl-test watch` surfaces this as `kernel-died: <reason>` rather than crashing itself. In the kernel, `mule` traps panics so a single bad cause doesn't terminate the kernel; deliberate `?>` exits surface as `Ok(vec![])` from `app.poke(...)` with a `mule`-trace on stderr. See [Troubleshooting / Common Pitfalls](/troubleshooting/common-pitfalls).

### Settle

In vesl: the canonical commitment-family graft (priority 10). Registers Merkle roots per `hull=@`, verifies payloads against a gate, settles notes with replay protection and epoch rotation. The heaviest commitment primitive; what most apps reach for first.

### Snapshot

A serialized kernel-state checkpoint. Lets a kernel resume without replaying every poke since boot. See [Build / State & Snapshots](/build/state-snapshots).

### tip5

Nockchain's hash function — a custom Merkle hash optimized for STARK-friendliness. ~100 constraints per call vs. ~30k for SHA-256. Used by `vesl-merkle.hoon` and `zeke.hoon`. tip5 is part of the nockchain runtime.

### Trellis

A pattern: one kernel split across multiple `hull=@` namespaces, each with its own root and lifecycle. Gives the isolation of separate kernels without booting separate `NockApp`s. See [Build / Grafts — The Trellis Pattern](/build/grafts/trellis-pattern).

### vesl

Verifiable Execution and Settlement Layer. A Rust SDK (`vesl-core`) plus a Hoon graft library that runs inside nockchain's `NockApp`. See [vesl at a glance](/pitch).

### vesl-core

vesl's Rust SDK crate: `Mint`, `Guard`, builder helpers, and poke constructors for every shipped graft. See [Reference / vesl-core](/reference/vesl-core).

### vesl-nockup

The recommended development environment for building nockapps; the subject of this guide. Ships the templates, the `nockup graft` CLI, and the example apps.

### vesl.toml

Runtime config file — settlement modes, key derivation, chain settings. See [Reference / vesl.toml](/reference/vesl-toml).

## Hoon

### Arm

A function on a Hoon core. The kernel's two top-level arms are `++poke` (write) and `++peek` (read); each cause-tag in `nockup:poke` is an arm of the `?-` switch. See [Build / Kernel](/build/kernel/).

### Atoms and Auras

A Hoon atom is a non-negative integer. Auras (`@t`, `@ud`, `@tas`, `@da`, `@`) are tags on atoms that record how to read the integer — UTF-8 cord, decimal number, lowercase symbol, absolute date, or untyped — without changing the underlying value. See [Build / Kernel](/build/kernel/).

### Cause

The input shape to a kernel `++poke` arm. A cause is a tagged tuple — `[%settle-register hull root]`, `[%my-action arg1 arg2]` — pattern-matched by the `?-` arm and dispatched to its handler. See [Build / Inject](/build/grafts/inject).

### Cell

A noun built from two other nouns — an ordered pair `[a b]`. Cells nest right-associatively, so `[1 2 3]` is `[1 [2 3]]`. With atoms, cells compose every noun a kernel handles.

### Cue

The JAM deserializer — the inverse of `jam`. Reads a noun back out of a byte buffer the kernel previously wrote with `jam`. JAM and cue are nockchain primitives, not vesl ones.

### Domain

The cause tags, peek paths, and verification gates you write between the markers. Distinct from grafts, which are pre-written and composed in for you. See [Build / Kernel](/build/kernel/).

### Effect

The output shape from a kernel `++poke` arm — a `(list effect)` of tagged nouns the hull receives back from `app.poke(...).await`. The hull parses heads via `vesl_core::effect_head_tags`. See [Build / Hull](/build/hull).

### Gate

A Hoon function. Takes one or more sample arguments, returns a value computed from its body. Distinct from a [verification gate](#verification-gate) — that is vesl's parameterized decision function consumed by commitment grafts, not the language-level construct.

### Mule

The Hoon crash-isolation wrapper. Catches a downstream panic and returns it as a value rather than terminating the kernel. The `wrapper.hoon` library wraps every `++poke` arm so a single bad cause doesn't take down the kernel.

### Noun

The universal value type in Nock and Hoon. Either an atom (a non-negative integer) or a cell (an ordered pair of two nouns). Everything in a kernel — state, causes, effects — is a noun.

### Peek

The read arm of a kernel. Takes a path noun, returns `(unit (unit *))` — three shapes encoding "not for me", "recognized but absent", "recognized and here is the value". See [Build / Kernel](/build/kernel/).

### Poke

The write arm of a kernel. Takes a cause noun, returns `[(list effect) state]` — a list of effects for the hull to consume plus the new kernel state. See [Build / Kernel](/build/kernel/).

### Verification Gate

A parameterized decision function consumed by commitment grafts. Default is hash-comparison; named gates (`sig-verify-ed25519`, `sig-verify-schnorr`, `manifest-verify`, `set-membership-verify`, `bounded-value-verify`) ship in `vesl-gates.hoon` and are selected per-graft via `[graft.gates]`. A gate is a parameter, not a step in a pipeline. See [Build / Kernel — replacing a verification gate](/build/kernel/gates).

### Versioned-State

The kernel's state type. Declared as `+$ versioned-state` in `app.hoon` at the `nockup:state` marker: a tagged record with a head version (`%v0`, `%v1`, ...) followed by per-graft state fields and any state your domain adds. Each `++poke` arm receives it by value and returns the new version as the tail of `[effects new-state]`. Bumping the head tag triggers `++load`'s migration path on resumed snapshots — see `nockup:load-defaults` in [Build / NockApp Anatomy — Anchor Markers](/build/anatomy#anchor-markers).

================================================================================
# Source: /reference/vesl-core.md
================================================================================

# vesl-core

`vesl-core` is the Rust SDK that ships under [zkvesl/vesl-core](https://github.com/zkvesl/vesl-core). vesl-nockup re-exports the parts a typical app uses through the `vesl-core` Cargo dep; this page is for when you want to drop below that and read or fork the SDK directly.

::: tip Scope
This page is a navigable orientation, not a full vesl-core reference. The canonical API surface lives in rustdoc; the canonical worked examples live in the vesl-core README and the four crate READMEs linked below.
:::

::: tip Building rustdoc locally
From a vesl-core or vesl-nockup checkout, `cargo doc --open -p vesl-core` builds and opens the SDK's rustdoc. Use `-p vesl-checkpoint`, `-p vesl-signing`, `-p nockchain-tip5-rs`, or `-p nock-noun-rs` for the sibling crates. No hosted-docs URL ships today.
:::

## What's in the Crate

Four primitives, each a different weight class. The lib.rs module-level comment names them and is the authoritative entry point:

- **Mint** — Data commitment. Pure math, zero async. Commit chunks, get a root.
- **Guard** — Verification. Prove chunks and manifests against trusted roots.
- **Settle** — Settlement. Kernel boot + chain access for note state transitions.
- **Forge** — STARK proof. Everything Settle does, plus proof generation.

Read [`crates/vesl-core/src/lib.rs#L1-L40`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/lib.rs#L1-L40) for the entry-point list and the top-level re-exports.

## When You Reach for vesl-core Directly

Most vesl-nockup users never touch vesl-core directly — the `build_*_poke` helpers in `vesl-core::graft_pokes` are re-exported as the high-level API. You drop into vesl-core when:

- Contributing a fix or feature to the SDK itself.
- Embedding `Mint` or `Guard` without booting a kernel (pure-math use cases).
- Writing a custom verification gate that needs the noun marshalling primitives.
- Using snapshot/resume across more than the canonical defaults overlay.
- Driving an alternative settlement flow against `chain-client-rs`.

If you're staying in vesl-nockup, you almost never need this page — go to [Build / Hull](/build/hull) instead.

## The Four Sibling Crates

```d2
direction: right

core: "vesl-core\nMint, Guard, Settle, Forge"
nn: "nock-noun-rs\nnoun construction, atom helpers"
tip5: "nockchain-tip5-rs\ntip5 hash + Merkle"
client: "nockchain-client-rs\ngRPC chain + wallet"
cp: "vesl-checkpoint\nsnapshot / resume"

core -> nn
core -> tip5
core -> client
core -> cp
```

```
vesl-core/crates/
├── vesl-core/                 # the SDK facade — Mint, Guard, Settle, Forge
├── nock-noun-rs/              # noun construction (the four footguns)
├── nockchain-tip5-rs/         # tip5 Merkle primitives
├── nockchain-client-rs/       # gRPC chain client + wallet
└── vesl-checkpoint/           # snapshot/resume bundle types
```

Crate READMEs (each is the authoritative single-page intro for that crate):

- [`vesl-core/README.md`](https://github.com/zkvesl/vesl-core/blob/main/README.md) — workspace overview, the EVM ↔ Nockchain mapping, settlement modes, quick-start branching.
- [`nock-noun-rs/README.md`](https://github.com/zkvesl/vesl-core/blob/main/crates/nock-noun-rs/README.md) — the four noun footguns (loobeans inverted, cords are atoms, lists null-terminated, `DIRECT_MAX` panic) and the memory model.
- [`nockchain-tip5-rs/README.md`](https://github.com/zkvesl/vesl-core/blob/main/crates/nockchain-tip5-rs/README.md) — alignment, leaf vs. pair hashing, cross-runtime guarantees, test vectors.
- [`nockchain-client-rs/README.md`](https://github.com/zkvesl/vesl-core/blob/main/crates/nockchain-client-rs/README.md) — gRPC architecture, balance queries, NoteData encoding.
- [`vesl-checkpoint/README.md`](https://github.com/zkvesl/vesl-core/blob/main/crates/vesl-checkpoint/README.md) — snapshot bundle layout, same-composition vs. schema-extension resume.

## The Poke-Builder Family

`vesl-core::graft_pokes` ships one `build_*_poke` helper per shipped graft cause. The full set covers settle (`build_settle_register_poke`, `build_settle_verify_poke`, `build_settle_note_poke`), mint, guard, forge, plus state and behavior grafts (`build_kv_set_poke`, `build_counter_increment_poke`, `build_log_append_poke`, `build_queue_push_poke`, `build_rbac_grant_poke`, `build_registry_put_poke`, `build_validate_init_poke`, `build_clock_tick_poke`, `build_batch_add_poke`).

For grafts that store structured data (`registry`, `log`, `queue`, `batch`), each builder also has a `_from_noun` paired form that jams the payload internally. See [Build / Hull — poke builders](/build/hull#poke-builders).

## Typed Poke Outcomes

`vesl_core::poke` ships a typed wrapper over `NockApp::poke`'s raw `Result<Vec<NounSlab>, NockAppError>`. The wrapper collapses the five things an empty effect list used to mean (gate-deny, idempotent no-op, RBAC pre-check denied, kernel-emitted cord, kernel-emitted typed rejection) into three top-level variants:

- **`PokeOutcome::Accepted { effects }`** — kernel emitted at least one non-error effect. Caller dispatches on tags via `effects` / `effect_head_tags()`.
- **`PokeOutcome::Rejected { reason }`** — kernel deterministically refused. `reason` is a `RejectionReason` enum carrying typed sub-classes: `KernelError { cord, raw_effects }`, `KernelRejected { tag, raw_effects }`, `GateDenied { reason, raw_effects }`, `RbacDenied { pubkey, perm }`, `Unknown`.
- **`PokeOutcome::Crashed { error }`** — driver-level failure (`Timeout`, `KernelPoke(NockAppError)`, `UnexpectedTag { tag, raw_effects }`).

The top-level helper:

```rust
use vesl_core::{classify_effects, PokeOutcome, RejectionReason};

// Wrap the raw NockApp::poke result.
let outcome = match app.poke(SystemWire.to_wire(), slab).await {
    Ok(effects) if !effects.is_empty() => classify_effects(effects),
    Ok(_) => PokeOutcome::Rejected { reason: RejectionReason::Unknown },
    Err(e) => PokeOutcome::Crashed { error: vesl_core::PokeCrashError::KernelPoke(e) },
};
```

The vesl-hull SDK (`vesl_hull::poke_kernel_with_timeout`) and the test harness (`vesl_test::GraftTestHarness::poke_slab` + the typed per-graft methods) both return `PokeOutcome` directly — most callers reach for those rather than wrapping `app.poke` by hand.

For the per-graft typed refinement — `SettleOutcome::RegisterRejected { hull, existing_root }`, `CounterOutcome::Error { msg }`, etc. — the test harness extension traits live on top of `PokeOutcome` and route by the kernel-emitted cord's `<graft>-graft:` prefix. See [Harness → Typed Per-Graft Methods](/build/testing/harness#typed-per-graft-methods).

The `vesl_core::peek` module ships matching atom decoders for the `raw_effects` cells the typed variants carry: `decode_effect_cord(slab) -> Option<String>` for `*-error` and `*-denied` reason cords, `decode_effect_loobean(slab) -> Option<bool>` for `*-verified ok=?` shapes, plus the existing `effect_head_tag` / `effect_head_tags`.

## Catalog Gates from Rust

The five named verification gates in `vesl-gates.hoon` (ed25519, Schnorr, manifest, set-membership, bounded-value) are selectable per-graft via `[graft.gates]` in a manifest, but the Rust side that drives them needs to construct cryptographically-valid payloads. [Build / Catalog Gates from Rust](/build/catalog-gates/) walks the Schnorr signing flow end-to-end (build a payload, sign with `vesl-core::signing`, hash via tip5, register the root, settle a note that pre-commits to the signed payload).

## Guard Lifecycle

`Guard` is the pure-math verification surface — register trusted roots, then check chunks or full manifests against them. No kernel involvement.

```rust
// Example: register a root, verify a leaf, manifest-check a bundle
use vesl_core::{Mint, Guard};

let mut mint = Mint::new();
let chunks: &[&[u8]] = &[b"alpha", b"beta", b"gamma"];
let root = mint.commit(chunks);
let proof = mint.proof(0).unwrap();

let mut guard = Guard::new();
guard.register_root(root)?;

assert!(guard.check(b"alpha", &proof, &root));
assert!(!guard.check(b"tampered", &proof, &root));
```

The full API:

- `Guard::new() -> Self` — empty, no trusted roots.
- `register_root(&mut self, root: Tip5Hash) -> Result<(), GuardError>` — trust a root. Errors with `CapacityExceeded` past `MAX_ROOTS` (10,000).
- `revoke_root(&mut self, root: &Tip5Hash) -> bool` — drop a root; returns whether it was present.
- `is_registered(&self, root: &Tip5Hash) -> bool` — membership check.
- `check(&self, data: &[u8], proof: &[ProofNode], root: &Tip5Hash) -> bool` — verify one chunk.
- `check_with_reason(...) -> Result<(), String>` — same as `check` with a human-readable error on failure.

Vesl-core's Guard is generic; it doesn't know about manifests. Manifest-aware verification lives in downstream hulls — `hull-llm`, the verified-RAG hull built on vesl-core, bundles per-chunk `check()` with prompt reconstruction in `hull-llm/src/rag_verifier.rs::RagVerifier::verify`.

The source is at [`crates/vesl-core/src/guard.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/guard.rs).

## Signing Helpers

`vesl-core::signing` ships the Schnorr key derivation and signing primitives the catalog gates expect on payloads:

- `derive_pubkey(sk: &[Belt; 8]) -> SchnorrPubkey` — public key from a secret key.
- `pubkey_hash(pk: &SchnorrPubkey) -> Hash` — `hash-leaf(pubkey)`, the `expected-root` shape `sig-verify-{schnorr,ed25519}` enforces.
- `pubkey_canonical_bytes(pk: &SchnorrPubkey) -> Vec<u8>` — serialized affine point (`ser-a-pt:cheetah`), the wallet-export shape.
- `pack_schnorr_signature(sig: &SchnorrSignature) -> Vec<u8>` — wire-form `(chal << 256) | s`.
- `schnorr_message_digest_for_data(data: &[u8]) -> [Belt; 5]` — tip5 digest of payload bytes, the canonical message for `sign`.
- `sign(sk: &[Belt; 8], message: &[Belt; 5]) -> Result<SchnorrSignature, SigningError>` — Schnorr sign over the message digest.
- `key_from_seed_phrase(phrase: &str) -> Result<[Belt; 8], SigningError>` — BIP-39 mnemonic to secret key.

These compose end-to-end with `build_settle_note_schnorr_poke`, which takes the `SchnorrSignature` and `SchnorrPubkey` directly. The end-to-end gate-driving walkthrough is on [Build / Catalog Gates from Rust](/build/catalog-gates/). Source is at [`crates/vesl-core/src/signing.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/signing.rs).

## Driving rbac-graft

rbac-graft maps `pubkey:@ → list<perm:@t>` in kernel state. Two pokes mutate it:

```rust
// Example: grant + revoke
use vesl_core::{build_rbac_grant_poke, build_rbac_revoke_poke};

let grant  = build_rbac_grant_poke(42, &["publish", "approve"]);
let revoke = build_rbac_revoke_poke(42, &["approve"]);
```

The `%rbac-has-perm` peek is a two-arg path (`[%rbac-has-perm pubkey=@ perm=@t ~]`). The shipped peek-path helpers cover one-arg shapes only, so build the slab by hand:

```rust
// Example: hand-rolled rbac peek path
use nock_noun_rs::{atom_from_u64, make_tag_in, NounSlab};
use nockvm::noun::{D, T};

fn build_rbac_has_perm_path(pubkey: u64, perm: &str) -> NounSlab {
    let mut slab = NounSlab::new();
    let tag = make_tag_in(&mut slab, "rbac-has-perm");
    let pk = atom_from_u64(&mut slab, pubkey);
    let p = make_tag_in(&mut slab, perm);
    let path = T(&mut slab, &[tag, pk, p, D(0)]);
    slab.set_root(path);
    slab
}
```

Decode the result with `peek_loobean(&result) -> Option<bool>`, not with `unwrap_triple_unit_atom` — the latter collapses atom-0 (`%.y`) onto the absent-value boundary.

The typical orchestrator-side shape peeks `%rbac-has-perm` before submitting a downstream poke; a `Some(false)` short-circuits the request before any kernel work. The denial is silent (no poke means no effect). [Troubleshooting / Distinguishing Denial Paths](/troubleshooting/common-pitfalls#distinguishing-denial-paths) covers how this reads against gate-deny, gate-crash, and validate-prelude denials.

The path is a multi-arg list, hand-constructed (no `build_*` helper today). See [Kernel → Domain Peeks → Multi-Arg Path](/build/kernel/peeks#multi-arg-path) for the kernel side of the same pattern and [Hull → Peek-Then-Poke Gating](/build/hull#peek-then-poke-gating) for the orchestrator-side use as an admission check.

## Driving validate-graft

validate-graft is a runtime-configured pre-flight rule checker. Rules install per cause-tag via `%validate-init`; the prelude block shorts every poke whose cause-tag has installed rules that fail.

```rust
// Example: install a non-empty rule on %counter-set, then clear it
use vesl_core::{build_validate_init_poke, build_validate_clear_poke, ValidateRule};

let install = build_validate_init_poke("counter-set", &[ValidateRule::NonEmpty]);
let clear   = build_validate_clear_poke("counter-set");
// app.poke(install) emits [%validate-rules-installed cause-tag=counter-set count=1]
// app.poke(clear)   emits [%validate-rules-cleared cause-tag=counter-set]
```

The v0.1 `Rule` enum ships one variant: `NonEmpty` (cause body must not be `~`). Additional variants (Length, InSet, Range, UniqueIn) are reserved tags in the Hoon-side union for v0.2 and will appear on `ValidateRule` as the corresponding Hoon support lands.

A poke whose cause-tag has rules and fails any rule short-circuits at the prelude and emits `[%validate-rejected cause-tag=@ta reason=@t]`. Pokes whose rules pass (or whose cause-tag has no installed rules) flow through to the normal arm.

## Committing Over Graft State

When a domain arm anchors a Merkle root over another graft's state (e.g. snapshot `registry-graft`'s vault map for off-kernel proof), the pattern is: read the graft state, jam each entry to a leaf, mint a root, then drive `%mint-commit` against the result.

```hoon
::  Example: a %snapshot-vault arm in your kernel
  %snapshot-vault
=/  vault  ~(tap by registry.state)
=/  leaves
  %+  turn  vault
  |=([key=@ payload=@] (jam [key payload]))
::  Hand `leaves` back to the hull via a pending effect; the hull mints
::  the root and re-pokes %mint-commit.
:_  state
~[[%domain-snapshot-pending ~]]
```

```rust
// Example: hull side, receive %domain-snapshot-pending then commit
use vesl_core::{Mint, build_mint_commit_poke};

let leaves: Vec<&[u8]> = jammed_entries.iter().map(|e| e.as_slice()).collect();
let mut mint = Mint::new();
let root = mint.commit(&leaves);
let poke = build_mint_commit_poke(hull, &root);
let _ = app.poke(SystemWire.to_wire(), poke).await?;
```

**Snapshot temporal staleness.** The root commits to registry state at the moment `~(tap by registry.state)` runs. Pokes that mutate `registry` between commit and a consumer's verification observe a different state. Treat the root as a *snapshot* identifier, not a *current-state* identifier: queries against the committed leaves answer "this entry was present when the snapshot was minted," not "this entry is present now." Operators who need fresh roots commit again after each batch of mutations.

## Where to Read Source

The directory tour for someone diving in:

- [`crates/vesl-core/src/lib.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/src/lib.rs#L1-L40) — module map and re-exports.
- `crates/vesl-core/src/graft_pokes/` — one file per shipped graft's poke builders.
- `crates/vesl-core/src/poke.rs` — `PokeOutcome`, `RejectionReason`, `PokeCrashError`, `classify_effects`.
- `crates/vesl-core/src/peek.rs` — `effect_head_tags`, `unwrap_triple_unit_atom`, `build_hull_peek_path`, and the typed-effect decoders.
- `crates/vesl-core/src/signing.rs` — `[Belt; 8]`-flavored shim: delegates Schnorr-over-Cheetah primitives to `vesl-signing` and BIP-39/BIP-44 seed-to-key derivation to `vesl-wallet`. Both live outside the vesl-core workspace.
- `crates/vesl-core/src/types.rs` — `Tip5Hash`, `ProofNode`, `Note`, `NoteState`, `MerkleTree`, `CommitmentVerifier` trait, `GraftPayload`, the chain config types. (RAG-specific `Manifest`/`Retrieval`/`Chunk` moved to `hull-llm/src/manifest.rs` in the 2026-05-19 architectural cleanup.)
- `kernels/{guard,mint,settle,forge}/` — thin crates that `include_bytes!` the committed `.jam` and sha256-verify at boot to detect tampering between build and link. (forge relocated in from hull-llm in the cleanup; vesl-kernel + vesl.jam stay in hull-llm where the RAG-specific kernel lives.)

## Snapshot / Resume

`vesl-checkpoint::snapshot()` and `resume()` wrap the underlying `nockapp` export/import path with a typed snapshot bundle (state.jam + meta.toml). [Build / State & Snapshots](/build/state-snapshots) covers the workflow; the canonical end-to-end is at [`crates/vesl-checkpoint/tests/end_to_end.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-checkpoint/tests/end_to_end.rs).

## TOML Role-Toggle

A pattern the SDK uses internally: one TOML file with multiple role sections (e.g., `[wallet]`, `[hull]`); the same code path reads a different section by role to derive a different key or config. The canonical test is [`crates/vesl-core/tests/wallet_toml_e2e.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/tests/wallet_toml_e2e.rs) — read it when designing config splits across roles in a domain hull.

::: info See Also

- [Build / Hull](/build/hull) — how vesl-core is consumed from a vesl-nockup project.
- [Grafts / Manifest Schema](/build/grafts/manifest-schema) — the manifest format vesl-core's `graft_pokes` builders generate causes for.
- [vesl-core README](https://github.com/zkvesl/vesl-core/blob/main/README.md) — the canonical longer-form orientation.

:::

================================================================================
# Source: /reference/library.md
================================================================================

# Library Catalog

vesl-nockup ships three layers of code: grafts (a Hoon library plus a TOML manifest, spliced into your kernel by `nockup graft inject`), support Hoon libraries (imported by grafts and reusable from your own kernel code), and Rust crates (linked by your driver, harness, or tooling). This page indexes all three.

## Grafts

Family-level orientation, priority bands, and composition rules live at [Grafts](/build/grafts/). Each row links to the library's source; the matching `<name>-graft.toml` manifest sits next to it on disk.

| Graft | Family | Role |
|---|---|---|
| [`mint-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/mint-graft.hoon) | Commitment | Root-only commitment per hull. One-shot per `hull=@`; no verification, no settlement. |
| [`guard-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/guard-graft.hoon) | Commitment | Register a root, then verify `hash-leaf(data) == root`. No replay protection. |
| [`settle-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/settle-graft.hoon) | Commitment | Gate-driven verification with epoch-rotated replay protection; one-shot registration per hull. |
| [`forge-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/forge-graft.hoon) | Commitment | Leaf hashing plus a nockchain STARK proof bound to `hull` and `root` via Fiat-Shamir. Stateless. |
| [`kv-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/kv-graft.hoon) | State | Opaque atom values. Overwrite on set; noop on delete-missing. |
| [`counter-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/counter-graft.hoon) | State | Named counters. Init-on-touch; saturates at 2^64 so Rust `u64` callers can represent every value. |
| [`queue-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/queue-graft.hoon) | State | FIFO with monotonic IDs. Mule-wraps `cue` on push so malformed jam returns `%queue-error` instead of crashing the kernel. |
| [`rbac-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/rbac-graft.hoon) | State | Pubkey → permission-set table. Two-level capacity caps: 10M entries in the outer roles map, 1000 perms per role. Overflow on either cap emits `%rbac-error 'rbac-graft: roles map at capacity'` or `'rbac-graft: perms-per-role at capacity'`. Auto-clears a pubkey from the map when revoke leaves it with zero perms. |
| [`registry-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/registry-graft.hoon) | State | Strict structured records. Errors on duplicate `put`, missing `update`, missing `del`. |
| [`validate-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/validate-graft.hoon) | Behavior | Cause-level rule checks via `poke-prelude`. On rule failure, short-circuits with `%validate-rejected` and leaves state untouched. |
| [`log-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/log-graft.hoon) | Behavior | Append-only audit trail with monotonic seq. 100k entry retention. |
| [`clock-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/clock-graft.hoon) | Behavior | Deterministic event-counter clock advanced by explicit `%clock-tick`. No host wall-clock. |
| [`batch-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/batch-graft.hoon) | Behavior | Buffer caller intents and emit `%batch-flushed` once a count trigger fires. Pairs with downstream settlement orchestration. |
| [`intent-graft`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/intent-graft.hoon) | Intent | Family-5 placeholder. Every arm crashes until upstream publishes a canonical intent shape. |

## Support Hoon Libraries

Plain Hoon libraries (no TOML manifest, no `nockup graft inject` codegen). Grafts import these; your own kernel code can too.

| Library | Used by | Role |
|---|---|---|
| [`vesl-merkle`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/vesl-merkle.hoon) | mint, guard, settle, forge | tip5 Merkle primitives: `hash-leaf`, `hash-leaf-digest`, `hash-pair`, `verify-chunk`, root construction. |
| [`vesl-gates`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/vesl-gates.hoon) | settle (selectable) | Named verification-gate arms: ed25519, Schnorr-over-Cheetah, manifest, set-membership, bounded-value. Selected via `[graft.gates]` in a settle manifest. |
| [`vesl-prover`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/vesl-prover.hoon) | forge | nockchain STARK prover, forked from `nock-prover.hoon` to accept `[subject formula root hull]` directly. |
| [`vesl-lower`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/vesl-lower.hoon) | forge | Nock formula lowering pass — opcodes 9/10/11 rewritten to 0–8 so `fink:fock` can execute the formula under STARK. |
| [`domain-patterns`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/domain-patterns.hoon) | your kernel | Wet-gate helpers. One `apply-<graft>` arm per shipped data/behavior graft, plus `audit-write` (bundles delegate-to-storage + `%log-append`). |

## Rust Crates

Workspace members under `crates/` (and `test/` for the harness). Link from your driver, wallet, or test crate.

| Crate | Role |
|---|---|
| [`vesl-core`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-core/src/lib.rs) | High-level Vesl SDK. Four primitives (Mint, Guard, Settle, Forge), each a different weight class on a shared API. Mint users never touch a kernel; Forge users get the full pipeline. |
| [`vesl-signing`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-signing/src/lib.rs) | Schnorr-over-Cheetah signing, Tip5 domain separators, SIWN (CAIP-122 sign-in). Foundation primitive for `vesl-wallet`; usable standalone. |
| [`vesl-wallet`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-wallet/src/lib.rs) | BIP-39 mnemonic ↔ seed, a BIP-32 analog over Tip5 (`vesl-hd-v1` domain separator), BIP-44 5-level role layout. |
| [`vesl-wallet-spec`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-wallet-spec/src/lib.rs) | Role-number constants and typed `DerivationPath` only. No curve, no seed handling, no signing API. |
| [`vesl-checkpoint`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-checkpoint/src/lib.rs) | Snapshot / resume wrapper for live NockApps. `snapshot()` writes a `state.jam` plus a `meta.toml` carrying the source `app.hoon` SHA-256; `resume()` parses the meta and boots from the snapshot. |
| [`vesl-test`](https://github.com/zkvesl/vesl-nockup/blob/main/test/vesl-test/src/lib.rs) | Rust harness plus a standard lifecycle suite for grafted kernels. Reuses poke shapes from `vesl-core` and `nock-noun-rs`; no kernel knowledge required from the caller. |
| [`nockchain-client-rs`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/nockchain-client-rs) | Client bindings to nockchain. |
| [`nockchain-tip5-rs`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/nockchain-tip5-rs) | tip5 hash primitive for Rust. |
| [`nock-noun-rs`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/nock-noun-rs) | Nock noun encoding and decoding (`jam` / `cue`, cells, atoms). |

### Hull helpers

`vesl-hull` exports a small set of leaf-encoding and dispatch helpers usable from any custom route or test that needs to interoperate with the stock `/commit` Merkle layout or the active verify gate.

| Helper | Source | Shape |
|---|---|---|
| [`field_to_leaf_bytes`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-hull/src/verify.rs) | `vesl_hull::field_to_leaf_bytes` | `Field { key, value } → format!("{key}:{value}").into_bytes()`. The stock `/commit` handler maps every field through this before Merkle-minting. Any custom `/settle-*` route that re-derives the registered root must encode leaves byte-for-byte the same way — a mismatch produces the same root-mismatch deny path as a tampered payload. |
| [`SettlePayloadBuilder`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-hull/src/settle_builder.rs) | `vesl_hull::SettlePayloadBuilder` | Trait the stock `/settle` handler dispatches through. See [Catalog Gates — Implementing a `SettlePayloadBuilder`](/build/catalog-gates/#implementing-a-settlepayloadbuilder) for the impl pattern. |
| [`ManifestSummary`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-hull/src/manifest_summary.rs) | `vesl_hull::ManifestSummary` | Boot-time snapshot of the graft manifest dir; surfaces the active gate, the composed grafts, and per-graft TOML sha256s through `/status`. |

## On-Disk Layout

```
vesl-nockup/
├── hoon/lib/                # grafts (library + manifest) and support Hoon libraries
├── crates/                  # Rust crates
├── test/vesl-test/          # Rust harness for grafted kernels
└── tools/graft-inject/      # nockup-graft CLI sidecar
```

## Known Limits (v0.1)

The behavior-graft band (validate, log, clock, batch) shipped with a deliberately small v0.1 surface. The state grafts have hard capacity caps that the audit-acknowledged tech debt list also tracks. Knowing where the edges are saves a profile run of friction.

### validate-graft

- **Only `%non-empty` is shipped.** Four other rule shapes are reserved in the `validate-rule` type union (`length`, `in-set`, `range`, `unique-in`) but the v0.1 graft only carries the `%non-empty` arm. Calls to `%validate-init` with an unrecognized rule head fail at composition time, not at runtime.
- **`%non-empty` checks `+.u.act` for sig only.** Multi-field cause bodies (e.g. `%registry-put key=@ payload=@`) have cell bodies, never `~`, so the rule always passes silently for them. To validate fields inside a cell body, wait for v0.2 field-level rule shapes — or open-code a Hoon prelude in a domain graft. See [Grafts → Inject → Cause Dispatch Semantics](/build/grafts/inject#cause-dispatch-semantics).
- **Rule maps cap at 10,000 cause-tags** and **64 rules per cause-tag**. Saturation emits `%validate-error 'validate-graft: rules map at capacity'` or `'validate-graft: too many rules per cause'`.

### log-graft

- **Retention cap is 100,000 entries, FIFO eviction.** Entries are stored newest-first; each `%log-append` prepends, and when the list exceeds the cap, `scag retention-cap` trims to the first 100k — silently dropping the oldest entry off the tail. No `%log-error` is emitted on rotation; the append succeeds and the eviction is invisible to the caller.
- **No saturation peek.** `[%log-len ~]` returns the current entry count; compare against 100,000 yourself.

### clock-graft

- **Event-counter only.** `clock-graft` increments a single `@ud` counter per `%clock-tick` poke and exposes it cast as `@da`. There is no host wall-clock, no boot stamp, no environmental input — determinism is the whole point for STARK soundness.
- `[%clock-now ~]` returns the counter (always present), not Unix time. The `boot-offset` and `block-time` sources are deferred; the latter waits on a future chain bridge.
- This is why batch-graft's `time` trigger (below) ships deferred — there's no monotonic time source to fire on yet.

### batch-graft

- **Only the `count` trigger is shipped.** Once the pending intent list meets or exceeds the configured threshold, the next `%batch-add` flushes (a flush emits `[%batch-flushed bundle=(list *) count=@ud]` and resets the buffer). The `time` trigger (clock-driven) and `pages` trigger (kernel-event-counter delta) are reserved but ship in v0.2.
- **`threshold=0` disables auto-flush.** Only manual `%batch-flush` pokes drain the buffer. `threshold=1` flushes on every add (no batching).
- **Pending list growth is O(n).** See [Common Pitfalls → High-Throughput Latency on queue-graft / batch-graft](/troubleshooting/common-pitfalls#high-throughput-latency-on-queue-graft-batch-graft).

::: info See Also

- [Grafts](/build/grafts/) — 5-family taxonomy with priority bands and composition rules.
- [Grafts / Manifest Schema](/build/grafts/manifest-schema) — manifest TOML fields and the priority lattice.
- [Reference / CLI (nockup graft)](/reference/cli) — subcommands the sidecar exposes.

:::

================================================================================
# Source: /reference/peek-catalog.md
================================================================================

# Peek Catalog

This page enumerates every peek path exposed by a shipped graft. Each section is one graft. For the teaching version of how peek arms compose (path shape, three keying schemes, multi-arg paths), see [Kernel → Domain Peeks](/build/kernel/peeks). For how the harness decodes the wrapped return, see [Testing → Domain Pokes → Reading State](/build/testing/domain-pokes#reading-state).

## Rust Builders for Single-Arg Paths

The three builders that cover the single-arg cases. They construct a `NounSlab` ready for `harness.peek_handle(path)`:

| Path shape | Builder | When grafts use it |
|---|---|---|
| `[%<tag> ~]` (keyless) | `build_keyless_peek_path("<tag>")` | Singletons (counts, epochs, the clock) |
| `[%<tag> hull ~]` (hull-keyed) | `build_hull_peek_path("<tag>", hull)` | Per-hull state (commitment grafts) |
| `[%<tag> @t %<key> ~]` (cord-keyed) | `build_keyed_peek_path("<tag>", key)` | Per-name state (kv, counter) |

Multi-arg paths (rbac's `[%rbac-has-perm pubkey perm ~]`) are hand-rolled — there's no shipped builder. See [vesl-core → Driving rbac-graft](/reference/vesl-core#driving-rbac-graft) for the canonical pattern and [Kernel → Domain Peeks → Multi-Arg Path](/build/kernel/peeks#multi-arg-path) for the kernel side.

## Return-Shape Cheat Sheet

`harness.peek_handle(path)` unwraps the standard two-level `(unit (unit *))`:

- `Err` — kernel returned bare `~`; path malformed or graft not composed.
- `Ok(None)` — path recognized, value absent (kernel returned `[~ ~]`).
- `Ok(Some(slab))` — path recognized, value present (kernel returned `[~ [~ value]]`); `slab` contains the inner `value`.

A subset of shipped peeks return `(unit (unit (unit *)))` — three levels — because the inner `(unit *)` carries its own present/absent signal. For those, `peek_handle`'s `Ok(Some(_))` always fires (because the path is always recognized + the outer wrap is always present), but the inner unit still has to be inspected. Use `harness.peek_raw(path)` or `vesl_core::unwrap_triple_unit_atom(&result)` (which collapses both layers onto `Option<&[u8]>`).

The tables below tag each peek's return shape as **flat** (2-level: `peek_handle` returns the value directly) or **nested** (3-level: caller must unwrap the inner unit).

---

## settle-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%settle-registered hull=@ ~]` | `build_hull_peek_path("settle-registered", hull)` | flat — loobean | `peek_loobean(&result)` |
| `[%settle-noted note-id=@ ~]` | `build_hull_peek_path("settle-noted", note_id)` | flat — loobean (in-current-or-prior-epoch) | `peek_loobean(&result)` |
| `[%settle-root hull=@ ~]` | `build_hull_peek_path("settle-root", hull)` | nested — `(unit @)` (root present or absent) | `unwrap_triple_unit_atom(&result)` or `peek_raw` |
| `[%settle-epoch ~]` | `build_keyless_peek_path("settle-epoch")` | flat — `@ud` | `peek_atom_u64(&result)` |
| `[%settle-count ~]` | `build_keyless_peek_path("settle-count")` | flat — `@ud` | `peek_atom_u64(&result)` |

`%settle-registered` and `%settle-noted` both surface as loobeans because their underlying state operations are `~(has by ...)` (registration check) and `~(has in ...)` (membership check). `%settle-root` is the only one whose inner value can be absent (the hull is registered but holds no root yet during the registration race window).

## mint-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%mint-commit hull=@ ~]` | `build_hull_peek_path("mint-commit", hull)` | nested — `(unit @)` (committed root, or absent) | `unwrap_triple_unit_atom(&result)` |

## guard-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%guard-root hull=@ ~]` | `build_hull_peek_path("guard-root", hull)` | nested — `(unit @)` (registered root, or absent) | `unwrap_triple_unit_atom(&result)` |

## forge-graft

forge-graft is stateless — it generates a STARK proof from a single `%forge-prove` poke and emits the proof as `%forge-proved`. There is no state to peek.

## kv-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%kv-value key=@t ~]` | `build_keyed_peek_path("kv-value", key)` | nested — `(unit @)` (atom value, or absent) | `unwrap_triple_unit_atom(&result)` |

## counter-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%counter-value name=@t ~]` | `build_keyed_peek_path("counter-value", name)` | nested — `(unit @ud)` (counter value, or absent if name never touched) | `unwrap_triple_unit_atom(&result)` + `u64::from_le_bytes` |

`counter-value` returns `None` (in the nested-unit sense) only for names that have never been incremented, reset, or set. Init-on-touch means any prior poke against `name` makes the peek return a value.

## queue-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%queue-len ~]` | `build_keyless_peek_path("queue-len")` | nested — `[~ @ud]` (always-present sentinel; never absent) | `peek_raw` + flatten, or `unwrap_triple_unit_atom` |

The always-present sentinel pattern (the `[~ ...]` literal inside the wrap) keeps `len=0` from being mis-decoded as "queue not composed" by the standard two-level unwrap. The inner unit is *always* `Some` for `queue-len`.

## rbac-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%rbac-perm-count pubkey=@ ~]` | `build_hull_peek_path("rbac-perm-count", pubkey)` | nested — `[~ @ud]` (always-present; 0 for unregistered pubkeys) | `unwrap_triple_unit_atom(&result)` |
| `[%rbac-has-perm pubkey=@ perm=@t ~]` | **hand-rolled** (multi-arg) — see [vesl-core → Driving rbac-graft](/reference/vesl-core#driving-rbac-graft) | nested — `[~ ?]` (always-present loobean; `%.n` for unregistered) | `peek_loobean(&result)` |

The auto-clear invariant on `%rbac-revoke` (a revoke that empties the perms set deletes the pubkey entry) means "zero perms" and "unregistered pubkey" are the same observable state. `perm-count` returns 0 for both; `has-perm` returns `%.n` for both.

## registry-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%registry-entry key=@ ~]` | `build_hull_peek_path("registry-entry", key)` | nested — `(unit *)` (opaque record noun, or absent) | `peek_raw` (caller `;;` to its schema) |

Records are returned as opaque nouns. The Rust caller is expected to `;;` against their domain schema (or destructure manually) after the peek.

## validate-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%validate-rules cause-tag=@ta ~]` | `build_keyed_peek_path("validate-rules", cause_tag)` | nested — `(unit (list rule))` (rule list, or absent for cause-tags with no installed rules) | `peek_raw` + walk list |

Returned for debugging which rules are currently active on a given cause-tag. The shipped `+$ rule` union has one variant (`%non-empty`); see [Library Catalog → Known Limits → validate-graft](/reference/library#validate-graft).

## log-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%log-by-seq seq=@ud ~]` | `build_keyless_peek_path` form: caller must pass a fully-built path (no shipped builder) | nested — `(unit log-entry)` (entry or absent if seq evicted) | `peek_raw` |
| `[%log-tail count=@ud ~]` | (caller-built path, like above) | nested — `[~ (list log-entry)]` (always-present, possibly empty) | `peek_raw` |
| `[%log-len ~]` | `build_keyless_peek_path("log-len")` | nested — `[~ @ud]` (always-present) | `unwrap_triple_unit_atom(&result)` |

`%log-by-seq` walks the entries list — O(retention), bounded by the 100k cap. A seq that's been evicted (rotated out by the FIFO trim — see [Library Catalog → Known Limits → log-graft](/reference/library#log-graft)) returns `None`. The audit-log invariant is that `log-len` answers "how many entries are live" without revealing which seqs were evicted.

## clock-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%clock-now ~]` | `build_keyless_peek_path("clock-now")` | nested — `[~ @da]` (always-present; cast `@ud` event-counter as `@da`) | `unwrap_triple_unit_atom(&result)` |

`@da` here is a thin cast over the underlying `@ud` event counter; there's no host wall-clock translation. See [Library Catalog → Known Limits → clock-graft](/reference/library#clock-graft).

## batch-graft

| Path | Rust builder | Return shape | Decoder |
|---|---|---|---|
| `[%batch-pending-len ~]` | `build_keyless_peek_path("batch-pending-len")` | nested — `[~ @ud]` (always-present; 0 if empty) | `unwrap_triple_unit_atom(&result)` |
| `[%batch-threshold ~]` | `build_keyless_peek_path("batch-threshold")` | nested — `[~ @ud]` (always-present; 0 = auto-flush disabled) | `unwrap_triple_unit_atom(&result)` |

`%batch-threshold` returns 0 when `%batch-init` hasn't been called (or was called with `threshold=0`); manual `%batch-flush` is then the only drain.

## intent-graft

intent-graft is a family-5 placeholder. Every cause-arm crashes with `%intent-graft-placeholder` (see [intent-graft.hoon](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/intent-graft.hoon)); the peek arm returns `~` for every path so the host kernel's peek chain falls through to the next graft. No peek paths are live in v0.1.

---

::: info See Also

- [Kernel → Domain Peeks](/build/kernel/peeks) — how to write a peek arm in Hoon.
- [Effect Catalog](/reference/effect-catalog) — the matching effect surface for each graft.
- [Hull → Decoding Effect Payloads](/build/hull#decoding-effect-payloads) — Rust-side decoding patterns including the unit-shape footgun.
- [Testing → Domain Pokes → Reading State](/build/testing/domain-pokes#reading-state) — using `peek_handle` and `peek_raw` from the harness.

:::

================================================================================
# Source: /reference/effect-catalog.md
================================================================================

# Effect Catalog

This page enumerates every effect head tag and its full payload shape across the shipped grafts. Each section is one graft, with two tables: success effects (cell shapes) and error effects (verbatim message strings from the Hoon source). For the teaching version of how effects are emitted, see [Kernel → Domain Causes](/build/kernel/causes). For Rust-side decoding patterns (the loobean-inversion footgun, cell payload extraction, unit returns), see [Hull → Decoding Effect Payloads](/build/hull#decoding-effect-payloads).

The matching read surface is [Peek Catalog](/reference/peek-catalog).

::: tip Typed Rust mapping

Every effect class on this page has a matching variant on a typed per-graft outcome enum the test harness ships. `%<graft>-error msg=@t` decodes to `<Graft>Outcome::Error { msg }`, `%<graft>-denied reason=@t` to `Denied { reason }`, and each typed rejection (e.g. `%settle-register-rejected`) to a named struct variant. The kernel's success effects collapse to `Accepted { effect_tags }`. See [Harness → Typed Per-Graft Methods](/build/testing/harness#typed-per-graft-methods) for the generated surface; tests match on the variant via `outcome.as_<graft>_outcome()`.

:::

---

## settle-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%settle-registered` | `[hull=@ root=@]` | `%settle-register` lands; hull is now registered against `root`. |
| `%settle-noted` | `note=[id=@ hull=@ root=@ state=[%settled ~]]` | `%settle-note` lands and the verify gate accepted the payload. |
| `%settle-verified` | `ok=?` | `%settle-verify` runs (a pure preflight; no state transition). `ok` is loobean — atom `0` = passed, atom `1` = failed. |
| `%settle-epoch-rotated` | `[old-epoch=@ new-epoch=@]` | Emitted alongside `%settle-noted` when `settle-count` hits `epoch-cap` (1M settles per epoch) and the settled set rotates. |

**Typed rejections** (cell payload, not a `%settle-error` cord):

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%settle-register-rejected` | `[hull=@ existing-root=@]` | `%settle-register` against a hull that already has a root (registration is one-shot per hull). `existing-root` is the currently-registered root atom — callers can pattern-match the typed tag instead of parsing the legacy `%settle-error` cord. (Audit L-09; post-`settle-graft 0.2.0`.) |

**Errors** (all emit `[%settle-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'settle-graft: registered map at capacity'` | `~(wyt by registered)` reached the 10M-entry cap. |
| `'settle-graft: malformed payload'` | `%settle-note` or `%settle-verify` payload atom failed to `cue` (mule-wrapped at the boundary). |
| `'settle-graft: root not registered'` | Payload references a hull that has no registered root. |
| `'settle-graft: root mismatch'` | Payload's `expected-root` doesn't match the registered root for the hull. |
| `'settle-graft: note root does not match expected root'` | Payload's `note.root` doesn't match `expected-root` (cross-check H-04). |
| `'settle-graft: note already settled'` | `note.id` is already in the current-epoch `settled` set. |
| `'settle-graft: note already settled (prior epoch)'` | `note.id` is in `prior-settled` — the rotated lookback set. |
| `'settle-graft: verify gate crashed'` | Verify gate panicked inside `mule` (caught crash, vs. a clean `?>` deterministic Exit). |

A clean `?>` rejection from the gate emits **zero** effects, not `%settle-error`; see [Common Pitfalls → Distinguishing Denial Paths](/troubleshooting/common-pitfalls#distinguishing-denial-paths).

## mint-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%mint-committed` | `[hull=@ root=@]` | `%mint-commit` lands. |

**Errors** (all emit `[%mint-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'mint-graft: hull already committed'` | `%mint-commit` against a hull that already has a root (commitments are one-shot). |
| `'mint-graft: commits map at capacity'` | `~(wyt by commits)` reached the 10M-entry cap. |

## guard-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%guard-registered` | `[hull=@ root=@]` | `%guard-register` lands. |
| `%guard-checked` | `[hull=@ ok=?]` | `%guard-check` runs; `ok` is loobean — atom `0` = `hash-leaf(data) == registered-root`, atom `1` = mismatch. |

**Errors** (all emit `[%guard-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'guard-graft: hull already registered'` | `%guard-register` re-applied to a registered hull. |
| `'guard-graft: roots map at capacity'` | `~(wyt by roots)` reached the 10M-entry cap. |
| `'guard-graft: hull not registered'` | `%guard-check` against a hull with no registered root. |

## forge-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%forge-proved` | `[hull=@ note-id=@ proof=*]` | `%forge-prove` succeeded; `proof` is the opaque STARK proof noun bound to `hull` and `root = hash-leaf(data)` via the Fiat-Shamir transcript. |

**Errors** (all emit `[%forge-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'forge-graft: prove-computation crashed'` | The prover bombed inside `mule` (e.g. malformed `data`, internal `;;` rejection). |

## kv-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%kv-stored` | `key=@t` | `%kv-set` lands (overwrite-on-existing; bypasses the capacity cap on overwrite). |
| `%kv-deleted` | `key=@t` | `%kv-delete` lands. Always emits, even for missing keys (noop is silent on the state side but visible on the effect side). |

**Errors** (all emit `[%kv-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'kv-graft: store map at capacity'` | `~(wyt by store)` reached the 10M-entry cap on a **new-key** insertion. |

## counter-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%counter-incremented` | `[name=@t value=@ud]` | `%counter-increment` advanced `name`. `value` is the post-increment value. |
| `%counter-reset` | `name=@t` | `%counter-reset` set `name` to 0 (init-on-touch). |
| `%counter-set` | `[name=@t value=@ud]` | `%counter-set` overwrote `name`. Note the head-tag collision: `%counter-set` (past-participle) and the cause `%counter-set` (imperative) read identically; spec keeps them. |

**Errors** (all emit `[%counter-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'counter-graft: counter saturated at 2^64'` | `%counter-increment` would push the counter past `2^64 - 1`. State unchanged; caller must `%counter-reset` first. |
| `'counter-graft: counters map at capacity'` | New-name insertion would push `~(wyt by counters)` past the 10M cap. |

## queue-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%queue-pushed` | `id=@ud` | `%queue-push` appended; `id` is the monotonic id assigned. |
| `%queue-popped` | `job=(unit [id=@ud body=*])` | `%queue-pop` ran. `job=~` if the queue was empty; `job=[~ [id body]]` if a job was dequeued. |
| `%queue-cleared` | `~` | `%queue-clear` ran (idempotent; emits even for already-empty queues). |

**Errors** (all emit `[%queue-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'queue-graft: malformed payload'` | The jammed body atom failed to `cue` (C1 mule-wrap boundary). |
| `'queue-graft: pending list at capacity'` | `(lent pending)` reached the 10M-entry cap. |

## rbac-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%rbac-granted` | `[pubkey=@ added=(list @t)]` | `%rbac-grant` ran. `added` is the **set difference** (asked − held) — only the newly-added perms, not the full post-state. |
| `%rbac-revoked` | `[pubkey=@ removed=(list @t)]` | `%rbac-revoke` ran. `removed` is the **intersection** (asked ∩ held) — only the perms that were actually present and got dropped. |

**Errors** (all emit `[%rbac-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'rbac-graft: roles map at capacity'` | New-pubkey insertion would push `~(wyt by roles)` past the 10M outer cap. |
| `'rbac-graft: perms-per-role at capacity'` | The post-grant perms set would exceed the 1000-perm inner cap. Applies to overwrites too, not just new pubkeys. |

Two-level capacity is load-bearing — the inner cap stops a single attacker pubkey from fanning out perms unbounded inside one row. See [Library Catalog → rbac-graft](/reference/library#grafts).

## registry-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%registry-stored` | `key=@` | `%registry-put` lands (strict create — errors on duplicate key, not overwrite). |
| `%registry-updated` | `[key=@ old=* new=*]` | `%registry-update` lands. Both old and new records surface in the effect, so audit-style callers don't need a peek round-trip. |
| `%registry-deleted` | `key=@` | `%registry-del` lands (strict — errors on missing key). |

**Errors** (all emit `[%registry-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'registry-graft: key already present'` | `%registry-put` against an existing key. Use `%registry-update` to overwrite. |
| `'registry-graft: entries map at capacity'` | `~(wyt by entries)` reached the 10M-entry cap. |
| `'registry-graft: malformed payload'` | The jammed record atom failed to `cue` (both `%registry-put` and `%registry-update`). |
| `'registry-graft: key not present; use put'` | `%registry-update` against a missing key. |
| `'registry-graft: key not present'` | `%registry-del` against a missing key. |

## validate-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%validate-rules-installed` | `[cause-tag=@ta count=@ud]` | `%validate-init` lands. `count` is the number of rules in the installed list (post-replace). |
| `%validate-rules-cleared` | `cause-tag=@ta` | `%validate-clear` drops the rules for `cause-tag`. Idempotent. |
| `%validate-rejected` | `[cause-tag=@ta reason=@t]` | The `poke-prelude` block short-circuited a poke before the `?-` switch. State is untouched. Fires for **any** poke whose cause-tag has installed rules and at least one rule fails. |

**Errors** (all emit `[%validate-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'validate-graft: too many rules per cause'` | `(lent rules)` exceeds the 64-rule per-cause cap. |
| `'validate-graft: rules map at capacity'` | New cause-tag insertion would push `~(wyt by state)` past the 10k cap. |

The `%validate-rejected` effect is the prelude-driven denial signal; see [Grafts → Inject → Cause Dispatch Semantics](/build/grafts/inject#cause-dispatch-semantics) for prelude semantics.

## log-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%log-appended` | `seq=@ud` | `%log-append` prepended an entry. `seq` is the monotonic id assigned. Eviction of an oldest entry past the 100k retention cap is silent (no error emitted). |

**Errors** (all emit `[%log-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'log-graft: malformed payload'` | The jammed `data` atom failed to `cue`. |

## clock-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%clock-ticked` | `now=@da` | `%clock-tick` advanced the counter by 1. `now` is the post-tick value cast as `@da`. |

**Errors** (`[%clock-error msg=@t]`):

The `%clock-error` variant is declared in the effect union but no current arm emits it — reserved for future config-validation needs. `%clock-tick` has no payload to cue and no capacity to exceed, so there is no v0.1 failure path.

## batch-graft

**Success effects:**

| Effect | Payload shape | Emitted when |
|---|---|---|
| `%batch-initialized` | `threshold=@ud` | `%batch-init` set the count trigger. `threshold=0` disables auto-flush. |
| `%batch-added` | `id=@ud` | `%batch-add` accepted an intent and assigned `id`. |
| `%batch-flushed` | `[bundle=(list *) count=@ud]` | The buffer drained. Two triggers: (a) `%batch-add` pushed the pending length to `>= threshold` (auto-flush, emitted **alongside** the `%batch-added`); (b) `%batch-flush` was poked manually (always emits, even for empty buffers — observers can mark the boundary). |

**Errors** (all emit `[%batch-error msg=@t]`):

| `msg` cord | Emitted when |
|---|---|
| `'batch-graft: threshold exceeds pending cap'` | `%batch-init threshold=X` with `X > 10_000_000` — a threshold higher than the buffer cap can never fire. |
| `'batch-graft: malformed intent payload'` | The jammed intent atom failed to `cue` (C1 mule-wrap boundary). |
| `'batch-graft: pending list at capacity'` | `(lent pending)` reached the 10M-entry cap before threshold could trigger. |

## intent-graft

intent-graft is the family-5 placeholder. The effect union reserves `%intent-declared id=@ hull=@`, `%intent-matched id=@`, `%intent-cancelled id=@`, `%intent-expired id=@`, and `%intent-error msg=@t`, but every poke-arm crashes with `~|  %intent-graft-placeholder  !!`. Composing the graft is supported (so callers don't trip up on the namespace); driving it is not. Watch the [`hoon/lib/intent-graft.hoon`](https://github.com/zkvesl/vesl-nockup/blob/main/hoon/lib/intent-graft.hoon) header for when upstream lands the canonical primitive.

---

::: info See Also

- [Kernel → Domain Causes](/build/kernel/causes) — how to emit an effect from a graft arm.
- [Hull → Decoding Effect Payloads](/build/hull#decoding-effect-payloads) — Rust-side decoding patterns including loobean inversion and cell-payload extraction.
- [Peek Catalog](/reference/peek-catalog) — the matching read surface.
- [Testing → Domain Pokes](/build/testing/domain-pokes) — driving causes and watching effects from a test harness.
- [Common Pitfalls → Distinguishing Denial Paths](/troubleshooting/common-pitfalls#distinguishing-denial-paths) — gate clean-deny vs. gate crash vs. pre-gate failure vs. rbac vs. validate-prelude — and how the effect list tells them apart.

:::

================================================================================
# Source: /reference/cli.md
================================================================================

# CLI (`nockup graft`)

`nockup graft` is the kernel-composition tool. It discovers `<name>-graft.toml` manifests under a library directory and composes their blocks into a host `app.hoon`. One call writes imports, state fields, cause branches, poke arms, and peek chains for every graft it picks up.

The user-facing invocation is `nockup graft <subcommand>` — `nockup`'s plugin discovery dispatches to the `nockup-graft` sidecar on PATH. Sample output and on-disk banner comments still identify the tool as `graft-inject`.

## Subcommands

| Subcommand | Purpose |
|---|---|
| `inject <PATH>` | Compose grafts into the target `app.hoon`. Documented in detail below — the primary command. |
| `list` | List discovered grafts, their priority, and the blocks each ships. |
| `lint <PATH>` | Pre-apply structural validation (five lint families plus the advisory `weld-friction`). See [Inject Lints](/build/grafts/inject/lints). |
| `doctor <PATH>` | Project-health check (schema-version handshake, Cargo `[patch]` consistency, hand-edited injected blocks, missing `nockup:load-defaults` marker) plus the Hoon-side lint pass under the resolved per-lint policy. Exits nonzero on a project-health finding or a lint error. See [`doctor`](#doctor) below. |
| `update <PATH>` | Refresh the graft library and recompose: `nockup package install` → preview → confirm → `inject --apply`. Preview-by-default; `--yes` skips the prompt. See [`update`](#update) below. |
| `codegen kernel-cause-tags <PATH>` | Emit a Rust slice of the kernel's cause-tag set. Wire from your own `build.rs` to opt into compile-time hull/kernel drift assertions. See [Hull — Hull/Kernel Drift Detection](/build/hull#hull-kernel-drift-detection). |
| `codegen harness-methods [BINDINGS]` | Emit typed `GraftTestHarness` methods + per-graft outcome enums from `harness-bindings.toml` (positional; defaults to `hoon/lib/harness-bindings.toml`). Cross-checks each `(graft, tag)` pair against the matching `*-graft.toml` poke body so a rename in either surface fails at codegen time rather than as a runtime empty effect list. See [Testing — The Rust Harness](/build/testing/harness). |
| `rename-kernel <new-name>` | Rename `hoon/app/<from>.hoon` plus references in `nockapp.toml` and `README.md`. |
| `completions <shell>` | Emit a shell-completion script to stdout (bash / zsh / fish / elvish / powershell). See [quickstart → Shell completions](/setup/quickstart#shell-completions-optional) for the per-shell install line. |

Pass `--help` to any subcommand for its current flag set.

## Usage

```
nockup graft inject [OPTIONS] [PATH]
```

`PATH` is the target `app.hoon`.

## `inject` Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--grafts <CSV>` | (auto-discover all) | Comma-separated graft names to compose, in the order listed. Overrides auto-discovery. Unknown names hard-error. |
| `--exclude <CSV>` | (none) | Graft names to skip. Subtracts from either the auto-discovered set or `--grafts`. |
| `--lib-dir <DIR>` | `./hoon/lib/` | Where to look for `*-graft.toml` manifests. |
| `--apply` | — | Write the composed output to `PATH`. Without this flag, `nockup graft inject` is preview-only (see below). |
| `--no-migrate` | — | Skip the auto-migration of legacy `+$ effect *` to the marker shape. Default behavior is to migrate transparently; this flag is the paranoid-review opt-out. |
| `--lint-override <NAME=SEVERITY>` | — | One-shot per-lint severity override (`error` / `warn` / `note`). Repeatable. Wins over the [`[lint]` table in `nockapp.toml`](/reference/nockapp-toml#lint-table). Unknown lint names or invalid severities hard-error so a typo doesn't silently no-op. Also accepted by `lint` and `doctor`. |

`nockup graft list` also accepts `--lib-dir`, `--exclude`, and `--json` (machine-readable schema; see below).

## Preview-by-Default

A bare invocation with `PATH` set prints the composed kernel to stdout and a per-manifest sha256 summary to stderr. Nothing is written to disk until `--apply` is passed. This is the trust boundary: manifest `body` fields paste verbatim into the composed kernel, so seeing the diff — and the sha256 of each manifest that contributed to it — before the write lands is the only way to catch a compromised `hoon/lib/` directory (pulled via `sync.sh`, a stray `cp`, a tampered dependency) before hostile Hoon becomes kernel source.

CI pipelines and scripted deployments should pass `--apply` explicitly.

## Injection Report

Invocation with `--apply` against a four-graft kernel:

```
graft-inject: hoon/app/app.hoon
  settle-graft     sha256:a9c72bbe7dc1 injected 5/5 (imports, state, cause, poke, peek)
  mint-graft       sha256:4b2e1c8930f2 injected 5/5 (imports, state, cause, poke, peek)
  guard-graft      sha256:c310a56e47bd injected 5/5 (imports, state, cause, poke, peek)
  forge-graft      sha256:f72193ac2018 injected 3/3 (imports, cause, poke)
  markers in source: 10 (imports, state, cause, poke-prelude, poke, poke-postlude, peek, domain-effect, effect-union, load-defaults)
  markers populated: 5 (imports, state, cause, poke, peek)
  effect-union codegen: inserted (5 variants: settle-effect, mint-effect, guard-effect, forge-effect, domain-effect)
```

The denominator is per-graft: each primitive declares which blocks it ships in its manifest. Forge is stateless and reports 3/3 (no state, no peek). A second run reports every line as `skipped: …` — `nockup graft inject` is idempotent; re-running against an already-wired kernel is a no-op (the codegen line reports `unchanged`). Without `--apply` the same report prints to stderr, followed by `(preview only — pass --apply to write <PATH>)`.

The `effect-union codegen` line surfaces the typed effect-union pass. Status is one of `inserted` (first run on a kernel that already has the `nockup:effect-union` marker), `replaced` (graft set changed since the last run; the union body was rewritten), `unchanged` (idempotent re-run), or `skipped` (kernel has no `nockup:effect-union` marker — the cast/weld friction at multi-graft `weld` sites remains; see [Grafts / Manifest Schema](/build/grafts/manifest-schema)).

## `list` Output

A bare `nockup graft list` prints one row per discovered graft in priority order:

```
  settle-graft     0.1.0    priority=10  (imports, state, cause, poke, peek)
  mint-graft       0.1.0    priority=20  (imports, state, cause, poke, peek)
  guard-graft      0.1.0    priority=30  (imports, state, cause, poke, peek)
  forge-graft      0.1.0    priority=40  (imports, cause, poke)
```

The trailing `(blocks)` column names every marker the graft populates. Grafts that ship fewer blocks (forge omits `state` and `peek`) report only what they declare. An empty `--lib-dir` prints `(no grafts discovered)`. Pass `--exclude <CSV>` to drop grafts from the listing without touching `hoon/lib/` on disk.

## `doctor`

`nockup graft doctor <PATH>` runs four project-health checks against a composed kernel and its project:

| Check | Flags |
|---|---|
| schema-version handshake | a graft manifest declaring a `schema_version` newer than the installed `nockup-graft` supports |
| Cargo `[patch]` consistency | a `Cargo.toml` pinning more than one nockchain rev — the partial-update state behind the `ibig` / `UBig` build failure |
| hand-edited block | a banner-bounded graft block whose body no longer matches what its manifest renders, while the banner sha still matches the manifest — a local edit the next `inject --apply` overwrites |
| missing `nockup:load-defaults` marker | a grafted kernel without the marker, where a schema-extension resume would silently drop effects |

Plus the full Hoon-side lint pass — `transitive-imports`, `collision`, `bare-tilde-ambiguity`, `internal-dupes`, `unresolved-cause-reference`, and the advisory `weld-friction` — under the same resolved policy printed at the bottom. Doctor is the one-stop pre-commit check: a kernel that passes `doctor` also passes `inject --apply`'s structural gates.

`doctor` exits nonzero on any project-health finding or any lint error (lint warnings surface but don't gate, matching `lint`'s standalone behavior), so CI can gate on a single command. `--json` emits a stable document with two top-level keys: `findings` (project-health findings, same shape as before) and `lint` (the per-kind report `lint --json` already emits, so consumers reuse their decoder). `--format build-warnings` emits one `doctor: <message>` line per project-health finding plus one `doctor: lint:<kind> (<severity>)` line per lint finding to stdout and always exits 0 — the form the `vesl` scaffold's `build.rs` consumes, forwarding each line as a `cargo:warning=` so findings surface on every `cargo build` without a separate command to run.

The `human` format prints in order: project-health findings (or a `no project-health findings` line), then a `lint findings` section if any fired (with the same per-finding output the standalone `lint` command emits, including the remediation hints), then a `resolved lint policy` block — one line per lint kind, showing the effective severity and whether it matches the per-variant default or an override is active. The block reflects the [`[lint]` table in `nockapp.toml`](/reference/nockapp-toml#lint-table) folded with any `--lint-override NAME=SEVERITY` flags on the `doctor` invocation, so an operator can sanity-check the active policy without running a compose.

## `update`

`nockup graft update <PATH>` is the graft-library update orchestrator — one verb for the safe-update sequence (see [Updating a Project](/build/updating)):

1. **Schema preflight** — stop if a graft needs a newer `nockup-graft`. `update` cannot replace its own running binary; it prints the `cargo install --force` instruction instead.
2. **`nockup package install`** — refresh the graft library.
3. **Re-check** the refreshed library's schema.
4. **Preview** the recomposition alongside the `doctor` health report.
5. **Confirm** — a `y/N` prompt, unless `--yes`.
6. **`inject --apply`** — recompose the kernel.

Preview-by-default is preserved: the preview prints before the prompt, and the kernel is rewritten only after a `y` (or `--yes`). `update` does not compile — the recompile and the cause-tag codegen are the next `cargo build`'s job. The `nockup` binary resolves from `NOCKUP_BIN` when set, otherwise from `PATH`.

## Priority Lattice

Grafts are injected in priority order (lower = earlier). Manifests can declare `after = ["<graft>"]` for soft ordering hints that resolve priority ties when both grafts are present. If the named graft isn't in the active cp set, the hint is silently ignored (a one-line note prints on stderr); priority-based ordering applies.

Hard ordering requirements aren't expressible — we deliberately keep all dependencies soft so subsetting works. If a graft structurally requires another graft's state shape, surface that through documentation, not a manifest field.

| Range | Class | Examples |
|---|---|---|
| 10–40 | Commitment | settle, mint, guard, forge |
| 50–99 | State | kv, counter, queue, rbac, registry |
| 100–149 | Behavior | validate, log, clock, batch |
| 150–199 | (reserved for user/domain grafts) | — |
| 200–299 | Intent | intent-graft (placeholder) |

## JSON Schema (`nockup graft list --json`)

```json
[
  {
    "name": "settle-graft",
    "version": "0.1.0",
    "priority": 10,
    "blocks": ["imports", "state", "cause", "poke", "peek"],
    "applicable": 5,
    "deferred": false,
    "sha256": "a9c72bbe…",
    "types": { "effect": "settle-effect", "cause": "settle-cause" }
  }
]
```

`sha256` is the hex sha256 of the manifest's raw TOML bytes — exposed so supply-chain reviewers can pin expected digests. Version bumps append fields, never reshape. Downstream crates can hard-fail at boot if a required graft is missing or its digest drifts.

`types` is the manifest's `[graft.types]` table — typed effect-union codegen input. Omitted on grafts that don't declare the table. `effect` is consumed by the codegen pass; `cause` is parsed forward-compat for cause destructuring and not yet read.

## `[graft.types]` Codegen Schema

A graft that exports a tagged effect type opts in by declaring it in `[graft.types]`:

```toml
[graft.types]
effect = "settle-effect"
cause  = "settle-cause"
```

Names must be kebab-case (`^[a-z][a-z0-9-]*$`). Two grafts cannot declare the same `effect` (or `cause`) name — `nockup graft inject` hard-errors at discovery with both manifest paths, mirroring the existing duplicate-graft-name guard. Hoon's `$%` would otherwise reject the synthesized union as `not a fork` with no manifest attribution.

The codegen pass synthesizes a banner-bounded block beneath the `nockup:effect-union` marker:

```hoon
::  nockup:effect-union
::  graft-inject:effect-union:begin
+$  effect
  $%  settle-effect
      mint-effect
      guard-effect
      forge-effect
      domain-effect
  ==
::  graft-inject:effect-union:end
```

Variant order matches the composer's input order (priority-sorted by default). `domain-effect` is appended when the `nockup:domain-effect` marker is present — the developer's `+$ domain-effect $%(...)` declaration there is left untouched. An empty union falls back to `[%effect-placeholder ~]` so Hoon's `$%` stays non-empty.

REPLACE-IF-PRESENT semantics: removing a graft from `--grafts` shrinks the union; adding one grows it; same-input reruns are byte-identical (Unchanged status).

## Lints

Every lint produces the same finding type with one variant per lint (`weld-friction`, `bare-tilde-ambiguity`, `collision`, `transitive-imports`, `internal-dupes`, `unresolved-cause-reference`). The unified printer prefixes each finding line with `  {severity}: {kind}: ` so `grep '<kind>:'` counts findings by kind without scraping bodies and `grep '^  error:'` routes only the gating findings. Findings of the same kind print consecutively; the per-lint remediation hint emits once for the group.

`nockup graft inject --apply` runs the five structural lints (`bare-tilde-ambiguity`, `collision`, `transitive-imports`, `internal-dupes`, `unresolved-cause-reference`) and refuses the write on any error-tier finding. `weld-friction` defaults to `warn` and surfaces in stderr without gating the write. Per-project severity overrides live in the [`[lint]` table of `nockapp.toml`](/reference/nockapp-toml#lint-table); `--lint-override NAME=SEVERITY` is the matching one-shot CLI flag (CLI wins over config, config wins over default). Pre-apply lints from `nockup graft lint` are documented separately on [Inject Lints](/build/grafts/inject/lints).

### `weld-friction`

Scans developer code (lines outside the `graft-inject:<X>:begin / :end` banner regions) for narrow `(list <X>-effect)` bindings where `<X>-effect` is a variant in the typed effect union. Sample output:

```
  warning: weld-friction: line 106: =/  [efx-c=(list counter-effect) new-counter=counter-state]
  warning: weld-friction: line 108: =/  [efx-k=(list kv-effect) new-kv=kv-state]
    cross-graft `(weld a b)` over these bindings will nest-fail. widen each
    to `(list effect)` so the typed union absorbs each graft's effect.
    see zkvesl-docs §"Composing two graft arms in one domain cause"
    (/guides/grafting#composing-two-graft-arms-in-one-domain-cause)
```

**Why it fires:** `weld` requires monomorphic lists — `(list X)` and `(list Y)` won't unify even when both `X` and `Y` are arms of the typed `+$ effect $%(...)` union. Two patterns work: cast each list at the weld site (`` `(list effect)`efx-c ``), or widen each binding to `(list effect)` upstream so the bare `(weld efx-c efx-k)` operates on a monomorphic list. The composer's typed-union codegen makes the latter the simpler default.

**Why the composer can't auto-fix it:** the binding lives in the developer's domain arm, between markers. Rewriting it would require parsing Hoon in Rust — explicitly out of scope for `nockup graft`. The lint surfaces the friction; the developer chooses Pattern A (cast at weld) or Pattern B (widen at binding).

**When it doesn't fire:**
- The kernel has no `nockup:effect-union` marker → codegen Skipped → no typed union to widen toward → lint short-circuits.
- All bindings already use `(list effect)` (Pattern B).
- The narrow type sits inside a graft-inject banner region (graft-injected poke bodies legitimately bind narrowly; the lint ignores those).

See [Build / Kernel — coordinating multiple grafts in one arm](/build/kernel/multi-graft) and [Grafts / Manifest Schema](/build/grafts/manifest-schema) for the worked patterns.

## Common Errors

- `warning — markers not found: ...` — your `app.hoon` is missing one of the ten `::  nockup:<name>` markers, or a marker is mistyped. See `vesl-nockup/templates/vesl/hoon/app/app.hoon` for canonical placement.
- `unknown graft: <name>` — `--grafts` named a manifest not in `--lib-dir`. Run `nockup graft list` to see what's installed.
- `duplicate [graft.types].effect` (or `.cause`) `<name>` in `<a.toml>` and `<b.toml>` — two manifests declared the same exported type name. Pick one; rename the other.
- `orphan graft-inject:effect-union:begin/end at line N` — the codegen banner pair under `nockup:effect-union` is corrupted (one banner without its mate). Restore the pair manually or remove both and let codegen re-insert on the next run.
- Subsequent `hoonc` failure with `mint-lost` / `-lost %<tag>` on a composed `?-` — stale manifest. Re-install vesl-graft (or re-run `sync.sh` in a dev checkout) to pick up the current cause-union shape.
- Subsequent `hoonc` `nest-fail` at a `(weld efx-a efx-b)` site — narrow bindings (`(list <graft>-effect)`); the [`weld-friction` lint](#weld-friction) above flags this at compose time. Widen each binding to `(list effect)` or cast at the weld with `` `(list effect)` ``.

::: info See Also

- [`tools/graft-inject/src/`](https://github.com/zkvesl/vesl-nockup/tree/main/tools/graft-inject/src) — composer source: manifest loader, marker matcher, lint passes.
- [Grafts / Manifest Schema](/build/grafts/manifest-schema) — TOML field definitions for what `nockup graft inject` consumes.
- [Build / Inject](/build/grafts/inject) — the workflow this CLI sits inside.

:::

================================================================================
# Source: /reference/nockapp-toml.md
================================================================================

# `nockapp.toml`

The project manifest `nockup` reads to scaffold or rebuild a project. Lives at the root of a nockapp directory. Consumed by `nockup project init` (initial scaffold) and re-read by `nockup package install` (dependency resolution). All `[package]` fields except `name` are optional.

## Worked Example

```toml
[package]
name = "my-app"
version = "0.1.0"
description = "grafted NockApp"
authors = ["Alice <alice@example.com>"]
license = "MIT OR Apache-2.0"
template = "vesl"
template_git = "https://github.com/zkvesl/vesl-nockup"
template_path = "templates"
template_commit = "6e2127c"   # optional pin

[dependencies]
"zkvesl/vesl-graft" = "latest"
"someorg/somedep" = { git = "https://github.com/someorg/somedep", commit = "abc123" }
```

## `[package]` Fields

| Field | Type | Default | Description |
|---|---|---|---|
| `name` | string | — | Project name. Required. Used as the project directory name on `nockup project init`. |
| `version` | string | — | Semver version of the project itself. Optional metadata. |
| `description` | string | — | One-line description. Optional metadata. |
| `authors` | list of strings | — | Author list. Optional metadata. |
| `license` | string | — | SPDX license identifier or expression. Optional metadata. |
| `template` | string | `"basic"` | Template directory name. Resolves to `<template_git>/<template_path>/<template>/` when `template_git` is set; otherwise to `~/.nockup/templates/<template>/`. |
| `template_git` | string | — | Git URL of a repo containing template directories. Accepts `https://`, `git@`, and `file://` (the last is useful for local testing). When unset, nockup uses its channel-managed template cache. |
| `template_path` | string | — | Subdirectory inside `template_git` that holds the templates root. Defaults to the repo root when omitted. Leading and trailing slashes are stripped during resolution. |
| `template_commit` | string | — | Pinned git commit (full or short SHA) for `template_git`. Without a pin, nockup pulls the default branch's tip on first init and caches it. |

## `[dependencies]` Schema

Each entry maps a package name to one of three forms:

```toml
# Form 1: simple version string (most common)
"zkvesl/vesl-graft" = "latest"

# Form 2: explicit version field
"zkvesl/vesl-graft" = { version = "0.1.0" }

# Form 3: full spec with git, commit, tag, branch, path, files, or kelvin
"zkvesl/vesl-graft" = { git = "https://github.com/zkvesl/vesl-nockup", commit = "6e2127c" }
"my-local-graft"    = { path = "../local-graft" }
"strict-pin"        = { git = "https://...", tag = "v1.0" }
```

The full-spec fields:

| Field | Description |
|---|---|
| `version` | Semver constraint or a channel literal like `"latest"`. |
| `git` | Git URL (HTTPS, SSH, or `file://`). |
| `commit` | Pinned commit SHA. |
| `tag` | Git tag. Resolved at install to a commit and written to `nockapp.lock`. |
| `branch` | Git branch. Resolved at install to a commit and written to `nockapp.lock`. |
| `path` | Filesystem path. For local development; not portable. |
| `files` | List of file patterns to symlink. When unset, the entire package is symlinked. |
| `kelvin` | Kelvin version constraint (Urbit dependency convention). |

`nockup project init` resolves every entry, fetches the source, symlinks it into the new project, applies any declarative `[[patches]]` declared in the package's own manifest, and writes the resolved commit hashes to `nockapp.lock` next to `nockapp.toml`.

## `[lint]` Table

Optional table that overrides per-lint severity for `nockup graft inject --apply` and `nockup graft lint`. Each key is a lint kind label, each value is a severity (`"error"`, `"warn"`, or `"note"`):

```toml
[lint]
weld-friction = "error"        # promote the advisory weld lint to a gate
transitive-imports = "warn"    # demote — keep the warning but allow the write
```

Valid keys: `weld-friction`, `bare-tilde-ambiguity`, `collision`, `transitive-imports`, `internal-dupes`, `unresolved-cause-reference`.

Resolution order: `--lint-override NAME=SEVERITY` on the CLI wins over the `[lint]` table, which wins over the per-lint default. An unknown lint name in `[lint]` (e.g. a typo like `transitive-importss`) hard-errors at config load so the override doesn't silently no-op. `nockup graft doctor` runs the lint pass under the resolved policy and lists the effective severity per lint, so the same command surfaces both the active policy and the findings it produces without requiring a compose.

See [Inject Lints](/build/grafts/inject/lints) for the per-lint surfaces and [CLI — Lints](/reference/cli#lints) for the printer shape.

## What `nockup project init` Does

1. **Read** `nockapp.toml` in the current directory.
2. **Resolve the template** — fetch `template_git` (pinned to `template_commit` if set) into `~/.nockup/templates/`, or fall back to the channel cache when `template_git` is unset.
3. **Copy and render** — copy `<template>/` into `./<package.name>/`, rendering Handlebars placeholders against the manifest fields.
4. **Save the canonical manifest** — write `nockapp.toml` into the new project directory.
5. **Install dependencies** — invoke `package install` against the new project. Each `[dependencies]` entry is resolved and symlinked; declarative `[[patches]]` from each package's own manifest are applied with a y/N consent prompt (skip the prompt with `--accept-patches` for CI).
6. **Write the lockfile** — `nockapp.lock` records `[[package]]` entries with resolved commit hashes and applied-patch hashes; later runs of `nockup package install` re-confirm against these.

::: info See Also

- [Setup / Your first nockapp](/setup/quickstart) — the workflow this schema sits inside.
- [`crates/nockup/src/manifest.rs`](https://github.com/nockchain/nockchain/blob/main/crates/nockup/src/manifest.rs) — source-of-truth schema definition.
- [Reference / vesl.toml](/reference/vesl-toml) — runtime config for vesl-based hulls (sibling file, different purpose).

:::

================================================================================
# Source: /reference/vesl-toml.md
================================================================================

# `vesl.toml`

Config file for any vesl-based hull. All fields are optional; environment variables and CLI flags override config file values. Precedence: CLI flag > env var > `vesl.toml` > defaults.

## Worked Example

```toml
# Path to the nockchain monorepo (required for `make setup`)
# Default matches the standard sibling layout: ~/projects/nockchain/{vesl-core,nockchain}
nock_home = "../nockchain"

# Hull HTTP API port (default: 3000)
# api_port = 3000

# Settlement mode: "local" (default), "fakenet", or "dumbnet"
# settlement_mode = "local"

# Chain settings (fakenet/dumbnet only)
# chain_endpoint = "http://localhost:9090"
# tx_fee = 256                # network minimum is 256 nicks
# coinbase_timelock_min = 1
# accept_timeout_secs = 300   # fakenet default; dumbnet default is 900
```

## Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `nock_home` | string | — | Path to the nockchain monorepo. Required for `make setup`. |
| `api_port` | integer | `3000` | HTTP API port for the `serve` subcommand. |
| `settlement_mode` | string | `"local"` | One of `local`, `fakenet`, `dumbnet`. |
| `chain_endpoint` | string | `"http://localhost:9090"` | Nockchain gRPC endpoint. Only used in fakenet/dumbnet. |
| `tx_fee` | integer | `256` | Transaction fee in nicks. |
| `coinbase_timelock_min` | integer | `1` | Minimum confirmations before a coinbase UTXO is spendable. |
| `accept_timeout_secs` | integer | `300` / `900` | Seconds to wait for tx acceptance. Fakenet: 300, dumbnet: 900. |

## Key Derivation

For `dumbnet` mode the hull needs a signing key. Resolution order, highest priority first:

1. `--seed-phrase-file <path>` — reads one line from a file (recommended; keeps the value out of `ps` output).
2. `--seed-phrase <phrase>` — passed on the CLI (visible in process table).
3. `VESL_SEED_PHRASE` environment variable.

Domain hulls may add their own fields. The TOML role-toggle pattern (the same code reads different sections of one TOML for different roles) is exercised in [`crates/vesl-core/tests/wallet_toml_e2e.rs`](https://github.com/zkvesl/vesl-core/blob/11d110d/crates/vesl-core/tests/wallet_toml_e2e.rs).

::: info See Also

- [`vesl-core/vesl.toml.example`](https://github.com/zkvesl/vesl-core/blob/main/vesl.toml.example) — copy-and-edit starting point.
- [Build / Build & Run — settlement modes](/build/build-run/#settlement-modes) — how the settlement modes are exercised at run time.

:::

================================================================================
# Source: /troubleshooting/common-pitfalls.md
================================================================================

# Common Pitfalls

Each entry leads with the symptom you'd see (or fail to see) at the terminal, then the cause, then the fix.

## `hoonc` Exits 0 but `out.jam` Is Missing

`hoonc` eager-parses every `.hoon` under `hoon/common/`, touching files there regardless of import-graph reachability. A type error in any of those files (including a library no marker imports directly) can leave hoonc with no panic message, exit 0, and no `out.jam` written. Without a check you walk into the next step against a stale kernel from the previous compile. The scaffold's `compile.sh` runs `hoonc` and then verifies the `out.jam` artifact, so it catches this:

```bash
./compile.sh
```

`nockup graft lint`'s [`transitive-imports`](/build/grafts/inject/lints#transitive-imports) catches the unsatisfied-import subset of this class before hoonc runs. Wire it into CI ahead of compile to fail fast with a named target rather than a silent-fail.

For a structured alternative that also catches the "stale jam against edited sources" case, use `vesl-test verify-jam`. See [Build / Build & Run — verify-jam structured alternative](/build/build-run/#verify-jam-structured-alternative).

## `hoonc` Fails with `mint-lost` / `-lost %<tag>` on a Multi-Graft Compose

The composed `?-` over `-.u.act` isn't exhaustive — usually because one of the graft manifests is stale. Re-install vesl-graft (or re-run `sync.sh` in a dev checkout) to pick up the latest arm set. If the missing tag was renamed in a recent vesl release, re-syncing the manifest is the fix.

## `nockup graft inject` or `update` Errors with `manifest schema too new`

The graft library in `hoon/lib/` declares a `schema_version` newer than your installed `nockup-graft` understands. The composer refuses rather than mis-compose a schema it cannot model — see [CLI — `doctor`](/reference/cli#doctor) for the schema-version handshake.

Update the binary and re-run:

```bash
cargo install --git https://github.com/zkvesl/vesl-nockup --bin nockup-graft --force
```

## `hoonc` Fails with `missing dependency /jams/constraints-0-1.jam`

`forge-graft` pulls in the STARK prover tree, which depends on pre-jammed constraint tables. Copy `hoon/dat/` and `hoon/jams/` from your `vesl-nockup` checkout into your project to satisfy the dependency.

## `cargo build` Fails on `ibig` with "expected `UBig`, found `ibig::ubig::UBig`"

vesl-core's transitive `vesl-signing` dep declares `ibig = "0.3"` from crates.io while vesl-core's signing module uses the nockchain-vendored `ibig`. Same upstream code, but Cargo treats the two as distinct crates and signing.rs fails to type-check.

If you scaffolded from the `vesl` template (see [Get started](/setup/quickstart)), vesl-graft's `[[patches]]` already added the necessary `[patch.crates-io]` block to your `Cargo.toml` — this error means you ejected the patches (`nockup patches eject zkvesl/vesl-graft`), declined the y/N prompt during `nockup project init`, or are adding vesl to an existing nockup project that doesn't pull vesl-graft. In any of those cases, add the patch manually using the same nockchain rev your other deps resolve to (visible in `nockapp.lock` or `Cargo.lock`):

```toml
[patch.crates-io]
ibig = { git = "https://github.com/nockchain/nockchain.git", rev = "<NOCK_PIN>" }
```

A path form (`path = "../../nockchain/crates/nockvm/rust/ibig"`) works equivalently if you have a sibling `nockchain/` checkout. Whichever shape you pick, the source must match what the rest of your nockchain crates resolve to — Cargo will not unify two different sources.

## `cargo test` Fails with `unresolved import \`vesl_test\``

The `vesl` template wires `vesl-test` into `[dev-dependencies]` during `nockup project init`. If you're adding tests to a project that didn't go through that path, or you removed the entry, add it back manually:

```toml
[dev-dependencies]
vesl-test = { git = "https://github.com/zkvesl/vesl-nockup" }
```

See [Build / Testing — Rust Harness](/build/testing/harness) for what the harness exposes once the import resolves.

## `Number is greater than DIRECT_MAX` Panic

A `u64` you're feeding into `D()` has its top bit set. Use `nock_noun_rs::atom_from_u64(slab, value)` instead of `D(value)` for hashed IDs, hull IDs, and any wide integer. All vesl-core poke builders already route hull-ids through `atom_from_u64` internally; this only bites when you're hand-rolling causes. See [Build / Hull — hand-rolled causes](/build/hull#hand-rolled-causes).

## `%settle-note` Returns No Effects, stderr Shows `DETERMINISTIC error mote=Exit`

The verify gate returned `%.n`. The `?>` in `lib/settle-graft.hoon`'s `%settle-note` arm crashes on gate failure by design — a rejected payload must remain an unprovable STARK state rather than an emitted error. From the Rust side, `app.poke(...).await` resolves `Ok(effects)` with `effects.len() == 0`; treat that as a gate rejection and inspect stderr for the `mule`-trace.

The most common cause is committing multiple leaves with the default single-leaf hash gate. Switch to `manifest-verify` via `[graft.gates]` if your payload has multiple leaves, or replace the gate body. See [Build / Kernel — replacing a verification gate](/build/kernel/gates).

## `%settle-note` Clean-Denies After a `[graft.gates]` Swap

A root registered under one verification gate cannot be re-verified under another. After [swapping a gate](/build/catalog-gates/swapping), treat the new gate as a fresh hull — register a new root that matches the new gate's binding (`hash-leaf(pubkey)` for the signature gates, a multi-leaf Merkle root for `manifest-verify`, and so on). Old roots stay readable via `/status` and the kernel state, but any `%settle-note` against them under the new gate clean-denies through the same surface as the previous entry.

Register fresh roots after the swap; do not replay old notes against pre-swap roots.

## Poke Resolves `Ok(vec![])` and stderr Shows `slog: invalid cause [%<tag> ...]`

The hull emitted a cause-tag the kernel's `+$ cause` union doesn't accept, so `(soft cause)` returned `~` and the wrapper short-circuited before any arm ran. The bracketed `[%<tag> ...]` is the cord-decoded head of the rejected cause; the trailing `(full: <noun>)` is the complete cell. If the head shows `%unknown`, the cause was either an atom or a cell whose head is itself a cell — both are malformed shapes for `[%tag args...]` causes.

Common causes:

- Typo in the hull-side bytestring.
- Kernel rename without a corresponding hull update.
- New graft installed but the kernel hasn't been re-composed with `nockup graft inject --apply`.

To catch this at compile time, use `assert_kernel_cause_tag!` — see [Build / Hull — drift detection](/build/hull#hull-kernel-drift-detection).

## `%non-empty` validate-graft Rule Passes a Multi-Field Cause Through

The only validate-graft rule shape shipped in v0.1, `%non-empty`, checks whether the cause body `+.u.act` is exactly `~` (sig). It does not descend into multi-field cause bodies. A cause like `%registry-put key=@ payload=@` has `+.u.act = [key payload]`, a cell — `=(~ body)` is false, the rule passes, and the prelude lets the poke through to the `?-` switch even when you expected `%validate-rejected`.

For field-level validation against `key` or `payload`, you need a v0.2 rule shape (`length` / `in-set` / `range` / `unique-in` — reserved in the type union but not yet shipped). See [Library Catalog → Known Limits (v0.1)](/reference/library#known-limits-v0-1).

## validate-graft Rule Installed on an Unknown Cause-Tag Never Fires

The validate-graft prelude only runs after the kernel's soft-cast (`;;`) accepts the poke into the composed `+$ cause` union. A rule installed against a cause-tag *outside* that union — a typo, a graft that was removed but whose rules are still in state, a cause-tag from an un-injected graft — silently never fires. The soft-cast fails first, the kernel logs `invalid cause` and emits zero effects, and the prelude block doesn't get a chance to run.

From the hull side this is indistinguishable from a clean gate-deny: empty effects, no `%validate-rejected`, just `Ok(vec![])`. Confirm the cause-tag is in the composed `+$ cause` union before chasing the rule logic.

## Peek Returns `~` on What Looks Like a Valid Path

`settle-graft`'s peek paths are **namespaced**: `[%settle-registered hull ~]`, `[%settle-noted note-id ~]`, `[%settle-root hull ~]`, `[%settle-epoch ~]`, `[%settle-count ~]`. Older unprefixed forms (`%registered`, `%settled`, etc.) are retired. Rust callers going through `vesl-core::build_*_peek_path` are unaffected; the helpers construct the namespaced shape.

If your manual peek path uses an old form, update it to the `%settle-*` prefix — or use the helper.

## Peek Decoder Reads the Wrong Axis After `peek_handle`

`peek_loobean`, `peek_atom_u64`, and `peek_unit_list` decode the raw `(unit (unit *))` envelope that `app.peek(path)` returns. `app.peek_handle(path)` pre-unwraps the outer unit, so its result needs a different decoder (or a manual head/tail descent). The test-harness equivalents follow the same split: `harness.peek_slab` returns the raw envelope; `harness.peek_handle` returns the pre-unwrapped form.

Passing a `peek_handle` result into `peek_loobean` silently mis-types — no compile-time check, and the loobean read lands on the wrong axis. The [Peek Catalog](/reference/peek-catalog) marks each path's return shape; pick the decoder by matching the catalog row to the call site.

## `out.jam` Changed but `nockup graft` Reported Nothing

A comment-only or whitespace edit in a transitively-parsed `.hoon` library (anything under `hoon/lib/`, including helpers like `domain-patterns.hoon` that no marker imports directly) can shift `out.jam` even when `nockup graft inject`'s per-graft summary reports `injected 0/N; skipped` across the board. The cause is hoonc-side, not the composer; something position-sensitive in the source bleeds into the jammed output. `nockup graft inject` is **manifest-keyed**: it re-injects only when a `<graft>.toml` digest changes, so library `.hoon` edits slip past it.

If you need byte-stable `out.jam`, treat any `.hoon` edit as material — bump the corresponding `.toml`'s body to force a re-inject pass, even if you intended only a comment.

## `nockup graft inject` Warns `markers not found` but the Marker Comments Look Right

The composer enforces a two-space law: every anchor must be `::` + two spaces + `nockup:<name>`. A one-space variant is a plain Hoon comment to the matcher and is silently skipped; the per-graft summary then reports `warning — markers not found: <list>` because nothing matched.

```hoon
::nockup:imports    :: zero spaces, not matched
:: nockup:imports   :: one space, not matched
::  nockup:imports  :: two spaces, matched
```

Fix: insert the missing space. The rule is enforced by `MARKER_PREFIX` and the matcher in [`tools/graft-inject/src/marker.rs`](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/tools/graft-inject/src/marker.rs#L142-L156).

## Distinguishing Denial Paths

A write that doesn't land surfaces as a typed [`vesl_core::PokeOutcome`](https://github.com/zkvesl/vesl-nockup/blob/main/crates/vesl-core/src/poke.rs) — match on the variant to identify the denial path without scraping stderr:

| Denial path | Where it fires | `PokeOutcome` variant | Effect list | Recovery |
|---|---|---|---|---|
| Gate clean-deny | Verify-gate returns `%.n` (e.g. `set-membership-verify` rejects, `sig-verify-schnorr` finds an invalid signature). settle-graft catches the `%.n` and emits a typed `%settle-denied` effect. | `Rejected { reason: GateDenied { reason, raw_effects } }` | `[%settle-denied reason=@t]` | Cause was rejected by policy; user must re-submit with valid input. The `reason` cord identifies which gate denied. |
| Gate crash | Gate panicked inside `mule`; settle-graft wraps the crash. | `Rejected { reason: KernelError { cord, raw_effects } }` (cord = `'settle-graft: verify gate crashed'`) | `[%settle-error msg='settle-graft: verify gate crashed']` | Gate has a bug; investigate the gate body or the data shape. |
| Pre-gate failure | Replay (note-id reused), root mismatch, unregistered hull, malformed payload, capacity. | `Rejected { reason: KernelError { cord, raw_effects } }` | `[%settle-error msg='<reason>']` | Pre-gate guard rejected the poke; check note-id uniqueness, registered-root match, or payload shape per the cord. |
| Rbac denial | Hull-side: `[%rbac-has-perm pubkey perm ~]` peek returned `%.n`; the poke is never sent to the kernel. Enabled when `[rbac] enabled = true` is set in the hull's TOML config. | `Rejected { reason: RbacDenied { pubkey, perm } }` | (none — never reaches the kernel) | Acting pubkey lacks the required perm; grant first or reject the request. HTTP 403 from `/commit` and `/settle`. |
| Validate-prelude rejection | `poke-prelude` rule returned a `(unit @t)` failure for the cause before the arm ran. | `Accepted { effects }` with head `%validate-rejected` (the prelude emits a typed effect rather than a denial) | `[%validate-rejected cause-tag=@ta reason=@t]` | Cause failed an installed domain rule; inspect `reason` and either resubmit a different cause or update the rule via `%validate-init`. |

**Multi-graft caveat.** In kernels with ≥10 active grafts, a Hoon `?>` crash (e.g. from a custom graft that still uses the pre-typed-denial pattern) emits a `mule`-trace large enough to terminate the hull process. The typed `%settle-denied` path does not crash and is safe to continue against; treat any remaining `?>`-based deny as terminal for the kernel session and restart.

### Composing Three Denials: Stacked Admission

Three of the rows above can stack in one request path. A "stacked admission" graft composition layers them so the cheapest check fails first:

1. **Rbac peek** at the hull (peek-then-poke) — `Rejected::RbacDenied` if the caller lacks the perm; the poke is never sent. See [Hull → Peek-Then-Poke Gating](/build/hull#peek-then-poke-gating) for the orchestrator-side shape.
2. **Validate prelude** — emits `%validate-rejected cause-tag reason` (an `Accepted` outcome with that head tag) if installed rules reject `+.u.act`. Runs for every poke including graft-injected ones; see [Grafts → Inject → Cause Dispatch Semantics](/build/grafts/inject#cause-dispatch-semantics).
3. **Verification gate** — `Rejected::GateDenied { reason }` on a clean-deny (`%settle-denied`), `Rejected::KernelError { cord }` on a gate crash (`%settle-error`).

A request that fails at layer 1 yields `Rejected::RbacDenied` from the hull — the kernel is never poked. A request that passes layer 1 but fails layer 2 yields `Accepted { effects: [%validate-rejected …] }`. A request that passes both but fails the gate yields the gate's typed `Rejected` variant per the table above.

The order matters for two reasons: (a) cheaper checks first avoids paying for the expensive gate evaluation when the caller wasn't authorized anyway; (b) each layer emits a distinct `PokeOutcome` variant so a test harness or operator can route on the typed match without scraping logs.

For tests that want to narrow further than the top-level `PokeOutcome` — e.g. assert specifically that settle's gate-deny carries the expected reason cord, or that counter-graft saturated rather than hit some other error — the harness ships per-graft extension traits (`SettleOutcomeExt::as_settle_outcome`, `CounterOutcomeExt::as_counter_outcome`, ...) that route by the `<graft>-graft:` cord prefix and decode into a typed `<Graft>Outcome` enum. See [Harness → Typed Per-Graft Methods](/build/testing/harness#typed-per-graft-methods).

## Kernel-Died — The Spawned Task Panicked or Returned an Error

`vesl-test watch` prints a `kernel-died: <reason>` row when the spawned `app.run()` task fails, instead of crashing itself. Reach for `watch` over `inspect peek` any time you can't tell from a bare poke return whether the kernel saw what you sent. The cause goes on the wire and the effect-list is structured. See [Build / Testing — watch](/build/testing/cli#watch-live-trace-repl).

## Snapshot Recovery — Schema Mismatch on Resume

`vesl-checkpoint::resume()` works for **same-composition** (the new kernel has the same graft set as the snapshot) and for **schema-extension** (the new kernel adds grafts the snapshot didn't have, handled by the codegen at the `nockup:load-defaults` marker). It does **not** work for graft removal or state-field reshape — the schema-migration helper is intentionally out of scope.

If you remove a graft or change a state field's shape, re-poke after resume to set up the desired state, or migrate state through a domain peek/poke round-trip before the recompile. See [Build / State & Snapshots — Manual Migration](/build/state-snapshots#manual-migration).

## Custom Route Skips Auth / Rate-Limit After `Router::merge`

`Router::merge(vesl_hull::router(state), my_routes)` looks symmetric but silently drops the middleware stack on the merged-in routes: axum's flat merge attaches your routes outside the layer set already applied to the hull's router. The custom route answers without API-key auth, without the body-size limit, and outside the rate-limit budget — none of which surfaces as an error.

Use `vesl_hull::serve_with_extra_routes` or `vesl_hull::router_with_extra` instead, so the auth, body-limit, and rate-limit layers wrap the final Router. See [Build & Run / Serve — Composing Custom Routes](/build/build-run/serve#composing-custom-routes).

## High-Throughput Latency on queue-graft / batch-graft

Both grafts back their pending list with Hoon's standard list `snoc`, which is O(n) per append. A queue or batch holding `k` pending items pays `O(k)` for the `k+1`-th push.

The symptom: linear-then-quadratic latency growth on bulk pushes. A test that pushes 100 jobs runs fine; 1k jobs starts to crawl; 10k jobs hits a multi-second cliff per push. The hard cap (`pending-cap = 10_000_000` on both grafts) bounds the worst case but doesn't help a workload that hits the cliff well before it.

The mitigation in v0.1 is operational: drain the queue (or flush the batch) regularly so `k` stays small. For batch, set `threshold` to the largest bundle size you can settle in one go — flushing fires automatically on the threshold-th add. For queue, pop in lock-step with push.

A switch to an O(1)-append structure (gap-buffer, deque-of-chunks, or a list-with-tail-pointer) is v0.2 work.

::: info See Also

- [vesl-nockup README — Troubleshooting](https://github.com/zkvesl/vesl-nockup/blob/main/README.md#troubleshooting) — upstream troubleshooting table.
- [vesl-nockup README — Operator triage table](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/README.md#L875-L884) — the canonical 4-row denial-path table.
- [`test/vesl-test/src/lib.rs`](https://github.com/zkvesl/vesl-nockup/blob/6e2127c/test/vesl-test/src/lib.rs) — `inspect peek` and `watch` source.

:::