# Kleisli.IO Documentation — Full Content

# cairn

## Learn

### Quickstart

#### Install cairn


cairn ships as an extension for kli, the runtime it was built for, and kli serves it to any client that speaks the Model Context Protocol. In this tutorial you install cairn one of two ways, point an agent at it, and confirm the tool surface is live. By the end you have a working cairn that an agent can plan in and resume into. You do not have to adopt kli as your main agent to use cairn; any MCP client works.

You need kli built and a project directory to work in. The directory you launch from selects the project whose task graph cairn opens, so run these steps inside the repository you want the graph to track.

## Install with kli

There are two ways to install. Bake cairn into the kli image declaratively, or install it at runtime from a running session. Pick one.

### Declaratively

Take cairn as a flake input and name it in your kli configuration. kli's Home Manager and NixOS modules compile the listed extensions into the image. cairn needs SQLite on its library path, because its observation store is built on SQLite FTS5.

```nix
{ inputs.cairn.url = "github:kleisli-io/cairn"; }
```

```nix
programs.kli = {
  enable = true;
  extensions = [ inputs.cairn.packages.${system}.default ];
  blessedNativeLibs = [ pkgs.sqlite ];
};
```

Rebuild, and cairn is in the image. Anything baked in this way stays put until you edit your configuration and rebuild again.

### At runtime

Each cairn [release page](https://github.com/kleisli-io/cairn/releases) carries the exact install command for that version: the url of the published bundle and the git tree hash it is pinned to. For v0.1.1:

```text
kli install https://github.com/kleisli-io/cairn/releases/download/v0.1.1/cairn.bundle 1b92b2928de8de87711c299d7353f1e0b602068e
```

kli fetches the bundle, recomputes the tree hash over its contents, and refuses to install on a mismatch, so what loads is exactly the bytes the release names. It shows what it is about to add and asks first; pass `--yes` in scripts and other non-interactive runs. The install is durable: the next `kli` or `kli mcp-serve` launch finds cairn without installing again.

The same install runs from inside a kli session as `/install <url> <git-tree-sha1>`, loading cairn live with no rebuild. The companion commands manage what you have installed: `/extensions` lists them, `/enable` and `/disable` toggle one, and `/uninstall` removes a runtime-installed extension.

cairn releases are also signed. To require the signature rather than the pin alone, add the Kleisli.IO release key to [`trustRoots`](/kli/config/settings#trustroots); the key is published on each release page and committed at [`release/trust/cairn-release.pub`](https://github.com/kleisli-io/cairn/blob/main/release/trust/cairn-release.pub). [Sharing extensions](/kli/extend/sharing-extensions) walks the full trust flow.

To load a local build for a single run instead of installing it, start kli with `--extension`:

```text
kli --extension <path>
```

That extension lives only for the life of that run.

## Serve to any MCP client

The same kli, built with cairn, serves the extension to any other client over stdio. One command does it:

```text
kli mcp-serve cairn
```

Wire a client to that command. Claude Code, Claude Desktop, and Cursor all read the same `mcpServers` block, so a single server entry connects any of them:

```json
{
  "mcpServers": {
    "cairn": {
      "command": "kli",
      "args": ["mcp-serve", "cairn"]
    }
  }
}
```

The client launches kli in your project directory, and that working directory picks the project whose task graph cairn opens. Once connected, the client lists all fourteen of cairn's tools, with the bundled workflow prompts and the `cairn-method` skill exposed as MCP prompts and resources.

The slash commands, the per-turn context injection, and the compaction folding stay behind, because kli provides those as the host rather than over the tool protocol. That is why kli is the fuller home for cairn. See [the mcp-serve reference](/cairn/cli/mcp-serve) for the full client matrix, exactly what travels, and the exposed surface in full.

## Confirm it is live

Connect your agent and have it call one read-only tool to confirm cairn answers. `task_bootstrap` orients on the current task in a single call; in a fresh project with no current task set, it answers with a clear message instead of crashing:

```text
No task to bootstrap; pass task_id or select a task first.
```

That message comes back as a tool result, not a protocol error, and it means the tool surface is wired and the graph is empty, which is exactly the state a first session starts from.

From here, run [your first cairn session](/cairn/get-started/your-first-cairn-session) to create a task, record an observation, write a handoff, and bootstrap back into the work.


#### Your first cairn session


This tutorial walks cairn's continuity loop once so you can see how your agent keeps work alive across a reset. The agent creates a task, records an observation on it, scaffolds a handoff, then resumes that task in a fresh session with one call. Those are the three writes that make up the heartbeat: `task_create`, `observe`, and `handoff`, all read back with `task_bootstrap`. The returned text after each call is explained, so you can tell what the agent reads back.

cairn has to be installed and reachable over MCP first; if it is not, see [Install cairn](/cairn/get-started/install-cairn). Each call below is shown the way the agent issues it over MCP, and the text after it is what cairn sends back.

## Create a task

A task is a node in the graph: a slug-addressed unit of work that carries a status, a description, edges, metadata, and its observations. The agent creates one by calling `task_create` with a `name`:

```text
task_create(name="wire up the export endpoint")
```

cairn mints a slug from the name, stamps today's UTC date as its namespace, and returns:

```text
Created 2026-06-22-wire-up-the-export-endpoint.
```

The date prefix is system-owned, so the agent passes a plain name and cairn handles the namespacing. `task_create` also adopts the new task as the [current task](/cairn/concepts/the-current-task-pointer), but only when none is set yet. Nothing was selected before this call, so the agent is now pointed at `2026-06-22-wire-up-the-export-endpoint`, and the writes that follow act on it without naming it again.

## Record an observation

An observation is the cheapest write cairn has, and the heartbeat of the loop: a freeform note the agent appends to a task as it works. It records one with `observe`:

```text
observe(text="export route returns 500 when the date filter is absent; needs a default range")
```

The note writes against the current task and returns:

```text
Observed on 2026-06-22-wire-up-the-export-endpoint.
```

The agent leans on `observe`. It does not move the current pointer and it never blocks, so leaving a trail of what the agent found, decided, and ruled out costs almost nothing, and that trail is what a later session reads back. To write against a different task without switching, the agent passes `task_id`. For the discipline behind the heartbeat, see [The cairn-method](/cairn/concepts/the-cairn-method).

## Write a handoff

A handoff is a resumable summary of where a task stands, and the `summary` is its load-bearing field. The agent scaffolds one with `handoff`:

```text
handoff(summary="export endpoint half-built; 500 on missing date filter, default range still TODO")
```

cairn writes a skeleton note (frontmatter, a state snapshot, and empty sections to overwrite with the rich body), records the event, and returns the path it wrote to:

```text
Handoff scaffolded for 2026-06-22-wire-up-the-export-endpoint at /…/2026-06-22_14-03-09_export-endpoint-half-built.md
```

There is no trailing period after the path. The tool is deterministic: it lays down a skeleton and returns the path, nothing more. It never drives an authoring turn; that is what the `/handoff` slash command does, and a person types that one. See [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) for the tool-versus-command split.

## Resume

Close the MCP client and reopen it. The graph survives the reset; the conversation does not. That is the whole point: the plan lives outside the chat, so a fresh session reloads it.

In the new session the current pointer is empty, so the agent names the task explicitly and orients on it with `task_bootstrap`:

```text
task_bootstrap(task_id="2026-06-22-wire-up-the-export-endpoint")
```

One call returns the task's computed state and its open handoffs:

```text
2026-06-22-wire-up-the-export-endpoint  [open]
  recent:
    - export route returns 500 when the date filter is absent; needs a default range
  handoffs:
    - export endpoint half-built; 500 on missing date filter, default range still TODO (/…/2026-06-22_14-03-09_export-endpoint-half-built.md)
```

The observation and the handoff summary are both back, reloaded into a session that knew nothing a moment ago. `task_bootstrap` records no event; it is a read. Because the agent passed `task_id`, the call switched the current pointer to that task, so the writes it makes next land there. For the no-id and unset-pointer cases, see [The current-task pointer](/cairn/concepts/the-current-task-pointer).

That is the full heartbeat: the agent created a task, left an observation, scaffolded a handoff, and resumed the whole thing from a clean session with one call. From here, [Plan and resume](/cairn/get-started/plan-and-resume) builds a small plan as a graph of phases and runs the same loop across it, and [The cairn-method](/cairn/concepts/the-cairn-method) explains the discipline this heartbeat is part of.


#### Plan and resume


This tutorial turns a single task into a small plan, works one phase, and resumes the plan from cold, so you can see how your agent holds a multi-step plan together across a reset. The agent forks three phases off a root task, orders them with `depends-on` edges, asks cairn which phase is ready, marks a phase `completed`, watches the ready set move, then bootstraps back into the plan as a fresh session would. By the end the plan lives in the graph, not in the conversation, so a context reset reloads it instead of losing it.

You need cairn installed and reachable over MCP, and your agent should have run the [bootstrap-observe-handoff loop](/cairn/get-started/your-first-cairn-session) at least once. This tutorial assumes you know what a task, an observation, and a handoff are; if not, read [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) first. Each call below is shown the way the agent issues it over MCP, and the text after it is what cairn returns.

## Create the root task

A plan in cairn is a root task with phases hanging off it, not a markdown file. The agent creates the root first:

```text
task_create(name="ship the export feature")
```

```text
Created 2026-06-22-ship-the-export-feature.
```

The slug is date-prefixed and minted from the name. `task_create` adopts the new task as the [current task](/cairn/concepts/the-current-task-pointer) because none was set, so every following call that omits `task_id` acts on it.

## Fork the phases

A phase is a child task joined to its parent by a `phase-of` edge. `task_fork` mints the child, records both `task.create` and `task.fork`, and, unlike `task_create`, always switches the current pointer to the new child.

The parent argument is `from`. When the agent omits it, `task_fork` forks from the current task. Here it forks three phases, passing `from` so each hangs off the root rather than off the previous child:

```text
task_fork(name="design the export schema", from="2026-06-22-ship-the-export-feature")
```

```text
Forked 2026-06-22-design-the-export-schema from 2026-06-22-ship-the-export-feature (phase-of).
```

```text
task_fork(name="implement the writer", from="2026-06-22-ship-the-export-feature")
```

```text
Forked 2026-06-22-implement-the-writer from 2026-06-22-ship-the-export-feature (phase-of).
```

```text
task_fork(name="add the download button", from="2026-06-22-ship-the-export-feature")
```

```text
Forked 2026-06-22-add-the-download-button from 2026-06-22-ship-the-export-feature (phase-of).
```

The default `edge_type` is `phase-of`, so it was not passed. **A fork with no `from` and no current task fails** with `No parent task; pass from or select a task first.`

The current pointer now sits on the last child forked. That is fine; the next steps address tasks by slug, which never disturbs the pointer.

## Order the phases

The phases are siblings under one parent. Nothing yet says the writer waits on the schema, or that the button waits on the writer. A `depends-on` edge says exactly that. `task_link` draws a typed edge from a source task to a target; the agent passes `task_id` to set the source explicitly rather than rely on wherever the pointer happens to be.

The writer depends on the schema:

```text
task_link(task_id="2026-06-22-implement-the-writer", target_id="2026-06-22-design-the-export-schema", edge_type="depends-on")
```

```text
Linked 2026-06-22-implement-the-writer -> 2026-06-22-design-the-export-schema (depends-on).
```

The download button depends on the writer:

```text
task_link(task_id="2026-06-22-add-the-download-button", target_id="2026-06-22-implement-the-writer", edge_type="depends-on")
```

```text
Linked 2026-06-22-add-the-download-button -> 2026-06-22-implement-the-writer (depends-on).
```

`edge_type` is required for `task_link` and must be one of `phase-of`, `depends-on`, or `related`. `phase-of` is the structural backbone the forks already built; `depends-on` is lateral ordering between siblings. The plan is now described: three phases, with a chain of dependencies running schema → writer → button.

## Ask what is ready

The frontier is the ready subset of a plan: the phases that are not done and whose dependencies are all settled. cairn computes it; the agent does not work it out by hand. The agent sets the pointer back to the root first, because `plan-frontier` is current-scoped: it reads the phases of the current task and keeps the ones with no unsettled `depends-on` target.

```text
task_bootstrap(task_id="2026-06-22-ship-the-export-feature")
```

That orients on the root and makes it current, which is what the `plan` and `plan-frontier` views read from. Now the agent queries the frontier. The query argument is a single TQ form, and a named view is run by wrapping its name as `(query "plan-frontier")`:

```text
task_query(query="(query \"plan-frontier\")")
```

```text
1 task:
- 2026-06-22-design-the-export-schema (active) obs=0 edges=2
```

Only the schema phase comes back. The writer is blocked behind the schema and the button behind the writer, so neither is ready yet. The `obs=0 edges=2` suffix is enrichment the `plan-frontier` view carries: an observation count and an edge count. Here that edge count is the one `phase-of` link up to the root plus the one incoming `depends-on` from the writer.

## Complete a phase and re-query

Once the schema work is done, the agent marks the phase complete. `task_update_status` takes a `status` from the closed set `open`, `active`, `completed`, `abandoned`, `blocked`, and is idempotent.

```text
task_update_status(task_id="2026-06-22-design-the-export-schema", status="completed")
```

```text
2026-06-22-design-the-export-schema is now completed.
```

The agent asks the frontier again. The root is still current, so no re-orientation is needed:

```text
task_query(query="(query \"plan-frontier\")")
```

```text
1 task:
- 2026-06-22-implement-the-writer (active) obs=0 edges=3
```

The frontier moved. The schema dropped out because it is settled, and the writer surfaced because its one dependency is now `completed`. The button is still held back behind the writer. The writer's `edges=3` counts its `phase-of` link to the root, its outgoing `depends-on` to the schema, and the incoming `depends-on` from the button. No plan document was edited; one status changed and the ready set recomputed from the graph. This is how the agent finds the next thing to do without re-reading the whole plan: [Views](/cairn/reference/views) documents the other built-in views, `plan`, `leaf-tasks`, and `stale-phases`, that answer related questions.

## Resume the plan in a new session

Now simulate what happens after a context reset, a `/clear`, or a colleague's agent picking up the work tomorrow. The plan is in the graph; one call reloads it. `task_bootstrap` returns computed state, neighbors, open handoffs, and recent observations, and records no event, so orienting never mutates the log.

```text
task_bootstrap(task_id="2026-06-22-ship-the-export-feature")
```

```text
2026-06-22-ship-the-export-feature  [active]
  children: 2026-06-22-add-the-download-button, 2026-06-22-design-the-export-schema, 2026-06-22-implement-the-writer
```

The whole plan came back from the slug alone: the root, its status, and the three phases hanging off it as children. The `phase-of` backbone is what the `children:` line reports; the lateral `depends-on` edges live between the phases, so they surface when the agent queries the frontier rather than in the root's neighbor readout. From here the agent re-runs `(query "plan-frontier")` to find the writer waiting, and the work resumes with no memory of the previous session required.

That is the cairn method end to end: one status change moved the frontier from the schema to the writer, and a single `task_bootstrap` reloaded the whole plan from the slug. To go deeper, read [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) for the readiness rule, and [The cairn-method](/cairn/concepts/the-cairn-method) for the working discipline a real plan runs inside.


### Concepts

#### What cairn is


cairn is continuity for agents. It is a durable task graph an agent plans into and resumes from: tasks joined by typed edges, freeform observations attached as the work happens, and handoffs that carry a session forward. An agent is sharp for the length of one session, and then the context resets. The plan, the half-finished step, the reason the last decision went the way it did — all of it lived in the conversation, so when the conversation ends, it is gone. cairn keeps that plan outside the conversation. After a reset, the agent reloads it from the graph instead of reconstructing it from a transcript.

## What "continuity" means here

Continuity is the property that work survives the boundary between sessions. Without it, an agent that loses its context redoes finished steps, or stalls to ask you where things stand. cairn gives the agent somewhere durable to put the plan, and a way to read it back.

The plan is a graph the agent queries, not a markdown file it re-reads top to bottom. A single `task_bootstrap` call returns the current task's state, its neighbors, its open handoffs, and recent observations. From there the agent asks the graph real questions — which phases are ready to start, what depends on a given task, what has gone stale — rather than scrolling old chat. The plan lives where a context reset cannot reach it, and the graph answers in the same terms the agent used to write it.

Three nouns carry the continuity. A **task** is a node, addressed by a date-prefixed slug like `2026-06-20-ship-the-thing`, holding status, description, edges, and metadata. An **observation** is the cheapest write — a freeform note appended to a task as the work happens, the heartbeat of a session. A **handoff** is a resumable summary written for whoever picks up next, its summary load-bearing. See [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) for how each one behaves.

## Why a cairn

A cairn is a pile of stones raised to mark a route across ground that holds no path of its own — a ridge, a snowfield, a stretch of moor where one direction looks like the next. A walker adds a stone and goes on. The pile stays, and shows whoever comes after which way the route ran. The word is Scottish Gaelic, *càrn*, a heap of stones.

The tool keeps that habit. Each session leaves a little more on the graph and moves on, and the next one reads the stones instead of guessing the way. The stone outlasts the walker who set it, and the graph outlasts the session that wrote it.

## A continuity subsystem, shipped as an extension

cairn began as the continuity subsystem inside kli, the agent runtime it was built for, and it ships as exactly the kind of extension kli exists to host. kli is a host for agent extensions; cairn is the one that handles memory across sessions. Run inside kli, cairn is at its fullest. The agent gets the tools, and the host adds three things on top: slash commands for steering by hand, per-turn folding of the current task's live state into the model's view, and folding of your observations and handoffs into the summary when a long conversation is compacted. That is why kli is the fuller home for cairn. See [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities) for how the host enforces the boundary between what an agent can read and what it can change.

## Works with any MCP client

cairn does not require you to adopt kli as your main agent. Pointed at a serving process, an MCP client — Claude Code, Claude Desktop, Cursor — sees cairn's fourteen tools as MCP tools, with its workflow prompts and the `cairn-method` skill exposed as MCP prompts and readable resources. Capability gating carries over the wire, so the read / write / observe split still holds. What does not travel is the part kli provides as the host: the slash commands, context injection, and compaction folding named above stay behind. A plain MCP client still gets a complete, useful surface.

One command — `kli mcp-serve cairn` — serves the extension to anything that speaks the Model Context Protocol. The command, its client configuration, and the exposed surface are documented in [mcp-serve](/cairn/cli/mcp-serve).

## The recursive loop

These docs are written to be read by a machine mid-task as readily as by a person at a desk. So the pages lead with what a thing *is*, keep their anchors stable, and quote tool names and return strings verbatim — an agent cannot paraphrase a wrong string into a working call. These pages were themselves produced by an agent dogfooding the [cairn-method](/cairn/concepts/the-cairn-method), the same bootstrap, observe, and handoff loop that keeps any plan across resets.

## Where cairn earns its weight, and where it does not

cairn pays off when work spans more sessions than a single context holds, when a plan has phases and dependencies worth tracking, or when more than one session might touch the same work and needs to see the others. It is a poor fit for a one-shot task you will finish in the session you start it, or a single-agent flow short enough to keep entirely in context. For those, the graph is overhead — a plain note to yourself wins. cairn tracks what you are doing without prescribing how you do it, which means the judgment of when to reach for it stays yours.

## Related

- [The task graph](/cairn/concepts/the-task-graph) — the two stores and the typed-edge model underneath everything here
- [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) — the three nouns and how each write behaves
- [The cairn-method](/cairn/concepts/the-cairn-method) — the working loop and the disciplines that wrap it
- [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile) — why a write survives a rebuild
- [Install cairn](/cairn/get-started/install-cairn) — bake it into kli or serve it to another client
- [Your first cairn session](/cairn/get-started/your-first-cairn-session) — the bootstrap, observe, handoff loop made concrete


#### The task graph


A new agent session knows nothing about the work it inherited. It has a fresh context window, a goal, and no memory of the decisions that led here. The task graph is what it reads instead of remembering: a durable, queryable structure that holds the shape of the work — which task is which, which phase blocks which, what was tried and learned — outside any one conversation. cairn keeps that structure in two stores, and they exist because the work poses two different questions.

## Two stores, two questions

cairn answers two different questions, so it keeps two different stores.

**The task store** answers *what is the structure of the work?* It holds tasks as nodes and the typed relationships between them as edges. A task is a node addressed by a slug, a date-prefixed identifier minted at creation like `2026-06-22-add-fts-index`, carrying a status, a description, edges to other tasks, and open metadata. Edges are typed: a phase belongs to a plan, one task depends on another, two tasks are related. This is a directed graph, and the query language ([TQ](/cairn/reference/tq-language)) walks it.

**The observation store** answers *what happened, and what was learned?* It holds observations, the freeform notes an agent appends as it works, indexed for full-text search. Where the task store is structured and typed, the observation store is prose. An observation is the cheapest write cairn offers, and over a session there are many of them. You do not navigate them by edge; you [search](/cairn/reference/tools#task-search) them by content.

The split is the point. Structure is small, slow-changing, and worth typing strictly. Notes are voluminous, fast-flowing, and worth indexing loosely. Forcing both into one shape would make the structure noisy or the notes rigid. Keeping them apart lets each store do one job well. An agent can ask a structural question (`what is ready to work on?`) without wading through prose, or a textual question (`where did we hit the FTS5 tokenizer issue?`) without walking edges.

## Tasks are slug-addressed nodes

Every task has a slug, and the slug is its address everywhere: in edges, in queries, in handoffs, in the current-task pointer. Slugs are date-prefixed, so `2026-06-22-` orders the day's work and the suffix names it. Because the address is a stable string rather than a numeric id, an agent can refer to a task by name across sessions without holding a handle, and a handoff written today still points at the right node tomorrow.

A task carries a small fixed set of fields the graph queries against, plus open metadata read as text. The fixed fields a [TQ](/cairn/reference/tq-language) query can name are these eleven — six textual, two numeric, and three timestamps (universal-time, numeric-comparable and date-queryable):

| Type | Fields |
| --- | --- |
| text | `slug`, `status`, `description`, `depot`, `parent`, `display-name` |
| number | `obs-count`, `edge-count` |
| timestamp | `created-ts`, `updated-ts`, `status-ts` |

Anything else you set with [`task_set_metadata`](/cairn/reference/tools#task-set-metadata) is open metadata. It rides along on the node and reads as text, but it is not a typed field the query language type-checks. Status is a closed enum (`open`, `active`, `completed`, `abandoned`, `blocked`) split by the query layer into an active half (`open`, `active`, `blocked`) and a dormant half (`completed`, `abandoned`), which is how a source like `(active)` knows what to return.

## Edges come in two classes

The graph has two kinds of edge, and the difference is not cosmetic: they are stored in different places and traversed differently.

**Structural edges carry the fibration.** A `phase-of` edge says one task is a phase of another, and it is folded into the child's parent pointer rather than stored as a separate edge row. [`task_fork`](/cairn/reference/tools#task-fork) writes exactly such a `phase-of` edge, its default `edge_type`, when it splits a child off a parent. The store recognizes a second structural type, `forked-from`, as an internal alias of that same parent pointer. Once folded, `phase-of` and `forked-from` are indistinguishable, which is why a task has exactly one structural parent. `forked-from` is not a value any tool accepts as `edge_type`; it exists only as a classification the graph reports. The backbone these types carry is the parent pointer, the plan-to-phase tree, while the order among sibling phases is tracked on a separate link. So "one structural parent" is a claim about ownership, not ordering.

**Lateral edges are relations the backbone does not carry.** `depends-on` and `related` live in a separate edge table, each a real row from a source task to a destination task. `depends-on` orders work: a phase that depends on another is not ready until the other settles. `related` is the catch-all link between two tasks that belong together without one owning the other. A task can have many lateral edges in either direction, and they are the cross-links over the structural tree. The store does not enforce acyclicity on them: a row from src to dst is rejected only when the two are the same task, so two tasks may each depend on the other. Traversal is built to tolerate that, which is why the `(:closure)` step is cycle-safe.

The closed edge vocabulary a tool accepts is exactly `phase-of`, `depends-on`, `related`. That is the set [`task_link`](/cairn/reference/tools#task-link) and [`task_fork`](/cairn/reference/tools#task-fork) validate against, and an `edge_type` outside it is refused. The graph self-describes this split: the `(edges)` source returns each edge type tagged with its class, `structural` or `lateral`, so an agent can read the taxonomy off the graph rather than memorizing it.

```lisp
(-> (edges) (:select :class))
```

```text
4 tasks:
- depends-on  class=lateral
- forked-from  class=structural
- phase-of  class=structural
- related  class=lateral
```

A query that traverses an edge validates the edge type before it touches any data; an unknown edge type is a structured error, not a silent empty result. That distinction matters to a model. An empty result means *nothing matched*; an error means *you asked the wrong question*. cairn never lets one look like the other.

## Observations index the prose

Observations are stored in their own table and mirrored into a full-text index built on SQLite's FTS5. The tokenizer keeps identifiers and `file:line` spans whole, treating underscores, colons, hyphens, and dots as token characters rather than separators, so a search for `obs_fts` or `store.lisp:89` finds the note that mentions it. There is no stemming and there are no stopwords; what you wrote is what is indexed.

This is why the observation store is searched, not walked. An agent re-entering a task does not traverse to its observations; it queries them by content with [`task_search`](/cairn/reference/tools#task-search), which compiles its input into an FTS5 `MATCH`. The structured graph and the searched index meet at the task: each observation belongs to a task node, so `obs-count` is a queryable field on the node, and an agent can move from *which task is busiest* (a graph query) to *what was said on it* (a search) in two calls.

## How the two stores stay one truth

Both stores are projections of a single append-only event log, not independent databases that could disagree. Every write, whether a task created, an edge linked, or an observation recorded, appends one event, and the task store and the observation store are folds of that same log. The graph you query is materialized state; the log is the truth it is derived from, and the projection can be rebuilt from the log at any time. That is the subject of [events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile), and it is why the two-store split never becomes a consistency problem: there is one source, and two views of it.

## Related

- [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) — the three nouns the graph is built from
- [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) — how `phase-of` and `depends-on` edges make a plan you can query
- [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields) — the closed enums and the eleven queryable fields, in full
- [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile) — why both stores are folds of one durable log
- [The TQ language](/cairn/reference/tq-language) — how a query walks the typed-edge graph


#### Tasks, observations, and handoffs


A cairn graph is built from three nouns. A **task** is a node: a date-prefixed slug with a status, a description, edges to other tasks, open metadata, and a stream of observations. An **observation** is the cheapest write you can make, one line of freeform text appended to a task. A **handoff** is a resumable summary: a scaffolded document whose one-line summary is the first thing the next session reads. These three are all you write. Everything else cairn shows you, from the frontier to the timeline, is computed from them.

Each noun maps to a verb you call and an event the call records. That is the shape of the whole system: a small, closed vocabulary of writes, each one durable, each one replayable. Understanding what each noun is, and what it is *not*, tells you when to reach for which.

## The task: a node with a date-prefixed slug

A task is identified by a slug minted from the name you give it. `task_create` over the name `wire up auth` yields a slug of the form `<today>-wire-up-auth` (the UTC date stamp followed by the slugified name) and returns `Created <slug>.`. The date namespace is system-owned. If you hand `task_create` a name that already carries a leading `YYYY-MM-DD-` prefix, it strips that before stamping today's, so the prefix never doubles and minting the same name twice in a day is idempotent. A name that recovers nothing descriptive is rejected before any event is recorded.

The slug is the address. Every other write names a task by slug or operates on the current one. A task carries:

- **a status** — one of `open`, `active`, `completed`, `abandoned`, `blocked`, moved with `task_update_status` (`<task> is now <status>.`);
- **a description** — the freeform line set at creation;
- **edges** — typed links to other tasks (`phase-of`, `depends-on`, `related`), added with `task_link` and removed with `task_sever`;
- **metadata** — open key/value pairs set with `task_set_metadata` (`Set <key> on <task>.`);
- **observations** — the append-only text stream described below.

`task_get` renders all of this for one slug: status, description, parent, children, edges, metadata, and the five most recent observations. Past five, it appends a one-line pointer to the rest — read a task's full observation history with `timeline(full=true, types=observation)`. None of it is a file you edit. The task is a projection of the events recorded against its slug, so the rendered node is always whatever the log replays to. See [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile).

Creating the first task adopts it as current when no current task is set; after that, `task_create` leaves the pointer alone. Forking with `task_fork` always switches the pointer to the child. The difference matters when you are building a plan, and it is covered in [The current task pointer](/cairn/concepts/the-current-task-pointer).

## The observation: the cheapest write, the heartbeat

An observation is one line of freeform text appended to a task. You call `observe` with `text`, it records an `observation` event, and it returns `Observed on <task>.`. That is the entire transaction. `observe` changes nothing but the observation stream and leaves your focus where it was.

This cheapness is the point. Because an observation costs nothing, the design assumes you record one whenever you learn something: a dead end you ruled out, the file and line where the real bug lives, a decision and the reason behind it. They are the running record of why the task moved the way it did. The store indexes them for full-text search, so an observation written today is what a future session retrieves with `task_search` when it asks "did anyone already look at this?" See [The cairn-method](/cairn/concepts/the-cairn-method) for the discipline and [`task_search`](/cairn/reference/tools#task-search) for the retrieval side.

An observation resolves to the current task unless you pass `task_id` to scope it elsewhere. Because it does not move the pointer, you can annotate a neighboring task mid-flow and stay on your own.

## The handoff: a resumable summary, summary first

A handoff is a document that lets a fresh session pick up where you stopped. You call `handoff` with a one-line `summary`; it mints a path under the task scratchpad, writes a skeleton document, records a `handoff.create` event, and returns `Handoff scaffolded for <task> at <path>`. The skeleton is deterministic: frontmatter, a `State` snapshot computed from the task, and empty `Recent work` and `Next steps` sections. The tool never drives an authoring turn. It hands you a valid file and a path; you read the scaffold and overwrite it with the rich body.

The `summary` is load-bearing: a resuming session reads it first and can often act on it without opening the file, so its precision matters more than the body's. It is also what `task_bootstrap` surfaces in its `handoffs:` block when you orient on the task.

Two surfaces write handoffs, and they are not the same:

- **The `handoff` tool** scaffolds the skeleton and records the event. It is deterministic and never authors prose.
- **The `/handoff` command**, under a kli host, is an authoring turn: it composes the one-line summary, calls the tool to scaffold and record, reads the scaffold, then overwrites it with a thorough document — task status, critical references, recent changes in `file:line` form, learnings, artifacts, graph state, and numbered next steps.

The tool gives you the durable record and the file; the command gives you the writing. Either way the summary comes first. See [Slash commands](/cairn/cli/slash-commands) for the `/handoff` authoring command and [the `handoff` tool](/cairn/reference/tools#handoff) for the scaffold it builds on.

## Three nouns, three events

Every write you make against the graph reduces to one of these nouns appending one event:

| Noun | Verb | Event recorded | Returns |
| --- | --- | --- | --- |
| Task | `task_create` | `task.create` | `Created <slug>.` |
| Task | `task_fork` | `task.create` + `task.fork` | `Forked <child> from <parent> (<edge>).` |
| Task | `task_link` | `task.link` | `Linked <src> -> <target> (<edge>).` |
| Task | `task_sever` | `task.sever` | `Severed <src> -> <target> (<edge>).` |
| Task | `task_set_metadata` | `task.set-metadata` | `Set <key> on <task>.` |
| Task | `task_update_status` | `task.update-status` | `<task> is now <status>.` |
| Observation | `observe` | `observation` | `Observed on <task>.` |
| Handoff | `handoff` | `handoff.create` | `Handoff scaffolded for <task> at <path>` |

Reads — `task_get`, `timeline`, `task_search`, `task_query`, and `task_bootstrap` — record no event. They project the log; they do not extend it. `task_bootstrap` in particular looks like a write because it can move the current pointer, but it records nothing: it switches focus and reads back state. The boundary between what extends the log and what merely reads it is enforced by capability, not by which tools are visible. See [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities).

## Why this shape

The three nouns are deliberately uneven in cost. A task is a commitment: it has a slug, a status, a place in the graph. An observation is nearly free, one line with no ceremony, because the friction of recording what you learned is the thing that loses knowledge between sessions. A handoff sits in between: more than a note, less than a meeting, a single document whose summary a tired or truncated reader can act on without opening it.

Keeping the write vocabulary this small is what makes a cairn graph durable and replayable. There is no rich task object to migrate, no handoff schema to version. There is a log of `task.create`, `observation`, `handoff.create`, and a handful of edge and status events, and the task you see is what that log folds to.

## Related

- [The task graph](/cairn/concepts/the-task-graph) — how tasks and their typed edges form the durable DAG these nouns live in
- [The current task pointer](/cairn/concepts/the-current-task-pointer) — which task an unscoped `observe` or `handoff` resolves to, and what moves the pointer
- [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile) — how each recorded event folds into the task you read back
- [The cairn method](/cairn/concepts/the-cairn-method) — the bootstrap → observe → handoff loop these nouns were built for
- [Slash commands](/cairn/cli/slash-commands) — the `/handoff` authoring command and the `handoff` tool it scaffolds with


#### Plans, phases, and the frontier


A plan in cairn is a graph of tasks, not a document. There is no `plan.md` that an agent reads, edits, and re-reads until it drifts from the work. The plan is the root task, the phases are its children, and the ordering between phases is an edge type the query language understands. Because the plan is structure rather than prose, cairn can answer a question a markdown file never could: of everything left to do, which tasks are ready *right now*. That answer is the frontier, and it is the single question an agent asks at the top of every working session.

This matters because the reader resuming a plan is usually a fresh context. A flat checklist forces that fresh context to re-derive what blocks what; a graph carries the dependencies as data, so the next task is computed, not remembered.

## A plan is a root task with phase children

The plan is a [task](/cairn/concepts/tasks-observations-handoffs#the-task-a-node-with-a-date-prefixed-slug) — a node in the [task graph](/cairn/concepts/the-task-graph) — that you grow phases beneath. You create the root with `task_create`, then break it into phases with `task_fork`. Each fork records a `phase-of` edge from the child up to the parent, so the plan's shape lives in the graph the moment you build it.

`task_create` takes one required argument, `name`, and mints the slug from it; the slug carries today's date as a prefix.

```text
task_create(name="Migrate the auth service to the new token format")
-> Created 2026-06-22-migrate-auth-service.
```

`task_fork` carves a phase off whatever task it forks `from` (the parent slug; it defaults to the current task), and its `edge_type` defaults to `phase-of`. The parent argument is `from` — there is no `parent` or `parent_id`.

```text
task_fork(name="Add the new token codec", from="2026-06-22-migrate-auth-service")
-> Forked 2026-06-22-add-the-new-token-codec from 2026-06-22-migrate-auth-service (phase-of).
```

A phase is a phase because of its `phase-of` edge, not because of anything in its description. `phase-of` is a *structural* edge: in the store it is folded into the parent foreign key, so every task has at most one parent and the phase backbone is always a tree. That single-parent rule is what lets the plan view start from one task and walk straight down to its phases. See [The task graph](/cairn/concepts/the-task-graph#edges-come-in-two-classes) for why structural and lateral edges are stored differently.

A phase is meant to be an independently verifiable unit of work — something that can move from `open` to `completed` on its own, with its own acceptance, while the rest of the plan stays put. Phases that bundle three unrelated outcomes are hard to mark done and harder to resume into. Forking one phase per checkable result keeps the frontier honest.

## depends-on edges order the phases

Phase-of says *what belongs to the plan*. It says nothing about *what comes first*. Ordering is a separate, lateral edge: `depends-on`, added with `task_link`.

```text
task_link(target_id="2026-06-22-add-the-new-token-codec", edge_type="depends-on", task_id="2026-06-22-cut-over-the-verifier")
-> Linked 2026-06-22-cut-over-the-verifier -> 2026-06-22-add-the-new-token-codec (depends-on).
```

Read `A depends-on B` as "A cannot proceed until B is settled." A `depends-on` edge is lateral — it lives in the edges table, not the parent key — so a phase can depend on any number of others without disturbing the phase-of tree. The two edge types compose: phase-of builds the plan's spine, depends-on threads ordering across it. The closed edge vocabulary accepted by `task_link` is `phase-of`, `depends-on`, and `related`; see [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields#edge-types).

Keeping the backbone and the ordering on different edge types is deliberate. You can restructure the plan (re-parent a phase) without touching the dependency order, and you can re-order work without re-parenting anything. Neither operation forces a rewrite of a prose plan, because there is no prose plan to rewrite.

## The frontier is the ready subset

Two named [views](/cairn/reference/views) answer the two questions a plan poses. `plan` returns the whole plan scoped to where you are standing. `plan-frontier` returns the subset of that plan that is ready to work.

The `plan` view is current-scoped: it reads from the [current task pointer](/cairn/concepts/the-current-task-pointer) and walks one hop down the phase-of backbone to the phases, falling back to your sibling phases when the current task is itself a phase.

```lisp
(-> (current) (:follow :phase-of) (:or-else (-> (current) (:back :phase-of) (:follow :phase-of))) (:enrich))
```

`plan-frontier` filters `plan` down to the tasks that are both unfinished and unblocked:

```lisp
(-> (query "plan")
    (:where (and (not (or (= :status "completed") (= :status "abandoned")))
                 (all (:follow :depends-on)
                      (or (= :status "completed") (= :status "abandoned"))))))
```

Read that predicate as the frontier rule, in two clauses:

- **Not yet settled.** The task's own status is not `completed` or `abandoned`. A settled task is behind you, not ahead. (`completed` and `abandoned` are the *dormant* half of the status enum; `open`, `active`, and `blocked` are the *active* half — see [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields#statuses).)
- **Every dependency settled.** Walking each `depends-on` edge forward, *all* the tasks it points to are `completed` or `abandoned`. A phase with one unfinished dependency is not on the frontier yet — its turn comes when that dependency settles.

A task with no `depends-on` edges trivially satisfies the second clause: `all` over an empty set is true. So the frontier of a fresh plan is exactly its unblocked entry points. As you complete phases, the frontier advances to the phases they unblocked. You never compute this by hand; you ask for it.

`frontier` is an alias — the view `frontier` is defined as `(query "plan-frontier")`, so either name returns the same ready subset.

## The shape of working a plan

With the plan in the graph, an agent's session has a fixed shape, and the shape is the point. The loop is a frontier query, a completion, and a re-query: ask which tasks are ready, settle one of them, and ask again. Nothing in between edits a list. The loop runs over [task_query](/cairn/reference/tools#task-query).

The frontier query inherits `plan`'s enrichment, so each line carries its inline counts — `obs=N edges=N` — after the status:

```text
task_query(query="(query \"plan-frontier\")")
-> 2 tasks:
- 2026-06-22-add-the-new-token-codec (open) obs=0 edges=1
- 2026-06-22-write-the-migration-guide (open) obs=2 edges=0
```

A completion is a single `task_update_status` against any task on the frontier:

```text
task_update_status(status="completed", task_id="2026-06-22-add-the-new-token-codec")
-> 2026-06-22-add-the-new-token-codec is now completed.
```

The re-query is the same call as before, and the phase that depended on the one just settled now appears — the frontier moved without anyone editing a list. This is the same heartbeat the [cairn-method](/cairn/concepts/the-cairn-method) wraps in research, plan, implement, and validate discipline. For the step-by-step version on a toy plan, see [Plan and resume](/cairn/get-started/plan-and-resume).

## When a plan graph is overkill

A plan graph earns its keep when work outlives one context: many phases, real ordering between them, and a resume that has to recompute what is ready. For a single task you will finish in one sitting, that machinery is friction. Create the task, observe against it, and skip the phases — a one-node "plan" has a frontier of one, which is just the task itself. Reach for `task_fork` and `depends-on` when the ordering is something a future context would otherwise have to reconstruct from memory.

## Related

- [Plan and resume](/cairn/get-started/plan-and-resume) — build the root, fork phases, order them with `depends-on`, and resume the plan
- [The task graph](/cairn/concepts/the-task-graph) — the two stores and the structural-vs-lateral edge split
- [The current task pointer](/cairn/concepts/the-current-task-pointer) — why `plan` and `plan-frontier` are current-scoped
- [Views](/cairn/reference/views) — the built-in views `plan`, `plan-frontier`, `leaf-tasks`, and `stale-phases` with their TQ source text
- [The TQ language](/cairn/reference/tq-language) — the query language the frontier rule is written in


#### The current-task pointer


The current-task pointer is a single task slug cairn holds for your session and resolves against whenever a tool omits an explicit task. You call `observe` with a line of text and no slug, and cairn knows where to file it; you call `handoff` with a summary and no slug, and it scaffolds under the right task. Nothing in those calls named a task, yet every write landed on one — the pointer supplied the target. It is the difference between an agent that has to repeat its own slug on every call and one that can plan, observe, and hand off in a flow because cairn already knows what it is working on.

## What the pointer is

The current-task pointer is one task slug, stored per session, that names the task in focus right now. It is not a property of the [task graph](/cairn/concepts/the-task-graph) — the graph does not have a "current" node. The pointer lives next to the session, alongside the open database handle, and it is what makes a slugless tool call meaningful. Without a pointer, "this task" has no referent and a current-scoped write fails rather than guessing.

Two sessions never share a pointer. The pointer is keyed in the active protocol's own storage, so a serving cairn over MCP keeps a separate current task for each connected client. One agent forking into a new phase does not move another agent's focus. Concurrency is real, and each session carries its own answer to "what am I on."

## How a tool finds its task

The write tools that target a task — `observe`, `task_link`, `task_sever`, `task_set_metadata`, `task_update_status`, `handoff` — resolve their target the same way. The tool takes the `task_id` argument when you pass one; otherwise it falls back to the current pointer; and if neither names a task, it fails with:

```text
No current task; create or select one first.
```

That fallback is the whole point. In the common case you set the pointer once and then write against it without repeating the slug. When you need to touch a different task without leaving the one you are on, you pass `task_id` — and that is the second half of the rule, the part that surprises people.

## Acting on a task does not make it current

A `task_id` argument scopes one call. It does not move the pointer. You can drop an observation on a sibling task, read another task's state, or flip a blocker to `completed`, all while the pointer stays exactly where it was.

```text
observe(text: "the parser handles the empty case", task_id: "2026-06-22-parser-edge-cases")
→ Observed on 2026-06-22-parser-edge-cases.
```

After that call, the current task is still whatever it was before. The observation went where you aimed it; your focus did not follow. This separation lets an agent record a quick note on a related task and return to its own work without an explicit switch-back step. The slug you passed is a one-shot address, not a new home.

Two surfaces deliberately break this rule, because their job is to move you.

## What moves the pointer

Three operations set the current task. Each is explicit about it.

**Creating the first task adopts it.** `task_create` mints a date-prefixed slug and records the task. If — and only if — no task is current, it adopts the new one as current, so a fresh session that creates a task is immediately working on it. Create a second task and the pointer does not move; you are still on the first until you say otherwise. This is the gentle case: adoption fills an empty pointer, never overwrites a full one.

```text
task_create(name: "rework the search backend")
→ Created 2026-06-22-rework-the-search-backend.
```

**Forking always switches.** `task_fork` spawns a child task and unconditionally makes the child current. Forking is how you descend into a [phase of a plan](/cairn/concepts/plans-phases-and-the-frontier), and the assumption is that you want to work in the phase you just opened. The parent comes from the `from` argument — a parent slug — and defaults to the current task when you omit it. Pass neither a `from` nor have a current task, and the fork fails:

```text
No parent task; pass from or select a task first.
```

So `task_fork` reads the pointer (as the default parent) and then overwrites it (with the new child) in a single call. After a fork you are one level deeper, on the phase, with the parent recorded as the edge source.

```text
task_fork(name: "migrate the index schema", from: "2026-06-22-rework-the-search-backend")
→ Forked 2026-06-22-migrate-the-index-schema from 2026-06-22-rework-the-search-backend (phase-of).
```

**Bootstrapping orients and may switch.** `task_bootstrap` is the set-current surface for resumption — the one call you make to re-enter work. Its pointer behavior splits on whether you name a task:

- With an explicit `task_id`, it switches the pointer to that task. Orienting on a task makes it current, so any session you spawn and the [per-turn context cairn injects](/cairn/concepts/events-projection-and-reconcile) agree on which task is in focus.
- With no `task_id`, it orients on the current task and leaves the pointer untouched; if no task is current, there is nothing to orient on and the call fails.

Either way, `task_bootstrap` records no event and switches the pointer only after it confirms the task exists. If you name a task that is not there, the pointer does not move; you get a not-found result and a list of recent slugs to aim at instead. With nothing to orient on at all:

```text
No task to bootstrap; pass task_id or select a task first.
```

| Operation | Effect on the pointer |
| --- | --- |
| `task_create` | Adopts the new task only when none is current |
| `task_fork` | Always switches to the child |
| `task_bootstrap` with `task_id` | Switches to the named task (after it is found) |
| `task_bootstrap` without `task_id` | Orients on the current task; never moves the pointer (fails if none is current) |
| Any tool's `task_id` argument | None — scopes one call, leaves the pointer alone |

## Why the pointer feeds every turn

The pointer does more than route writes. Each model turn, cairn reads the current pointer live, renders that task's computed state and its open handoffs, and splices the block in as ephemeral context — present for that turn, never written to the durable log. The agent sees what it is working on without being told, and the block always reflects live state because it is rebuilt from the pointer and the store every turn rather than cached.

This is the recursive payoff of a per-session pointer. Move it with `task_fork` and the very next turn's injected context is the new phase. Resume a task with `task_bootstrap` and the context block follows your focus. The pointer is the one piece of session state that decides both where writes land and what the model is reminded of. That is why moving it is always explicit, never a side effect of touching another task.

## When the pointer is more than you need

A single-task, single-session run barely exercises the pointer: you create one task, it is adopted, and every slugless call lands on it for the life of the session. The rules above earn their keep when work fans out — multiple phases, multiple sessions, a `task_id` aimed sideways while focus stays put. For one linear thread of observations, walk through [your first session](/cairn/get-started/your-first-cairn-session) and let adoption do the work; the switch-versus-scope distinction can wait until you fork.

## Related

- [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) — how `task_fork` descends into the phase the pointer then follows
- [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) — the writes that resolve against the pointer
- [The cairn-method](/cairn/concepts/the-cairn-method) — where bootstrap sits in the orient, record, hand off loop
- [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile) — the per-turn context block the pointer drives
- [Tools reference](/cairn/reference/tools#task-bootstrap) — the exact signatures of `task_create`, `task_fork`, and `task_bootstrap`


#### Events, projection, and reconcile


cairn stores no state you cannot reconstruct. Every write is one event appended to a durable, append-only log; everything you query — the task graph, observations, handoffs, metadata, even the views you define — is a projection folded from those events. The log is the truth. The database is a cache of the log, and it can be thrown away and rebuilt. This is why a cairn store survives a crash mid-write, moves between machines as plain text, and resumes the same way every time: the answer to "what happened?" is always the events, replayed in the same order.

You do not call any of this. There is no commit, no flush, no migration step in the tool surface. Understanding the model tells you why cairn's writes are cheap, why two agents writing the same store do not corrupt it, and why the durable artifact on disk is a file you can read.

## The event log is the source of truth

Each task owns a log: a single `events.ndjson` file, one JSON event per line. That file is canonical. Every observation, status change, link, fork, and handoff is appended to it as an event before anything else happens, and an event, once written, is never edited or deleted. To know the full history of a task, you read its log top to bottom.

The line format is deterministic. cairn encodes each event with its keys sorted and its `data` payload nested as a canonical object, so the same event always serializes to the same bytes — the encoder and decoder are exact inverses, and a line decoded on one machine folds into the same state on another. An event carries its identity and provenance: `event_id` is a portable ULID, the stable id that travels with the event; `event_key` is the de-duplication key; `task_id`, `type`, `ts`, and the session that wrote it ride along too. The local row number is the only field the line does not carry, because it is local.

Because the log is append-only NDJSON, it is durable and portable for free. There is no binary format to corrupt, no schema to migrate in place. Copy the directory and you have copied the history.

## The projection is a fold over events

You never query the log directly. cairn folds the events into a SQLite projection — the materialized view your reads run against — and that projection holds the shapes you actually ask about: the `tasks` table, the `edges` between them, the full-text `observations` index, `handoffs`, `task_metadata`, and `named_views`. Every one of these is derived. Apply the events in order and the projection appears; the same events always produce the same projection.

Two consequences matter. First, the projection is disposable: it is a cache, and cairn can rebuild it from the logs at any time. Second, replay is **portable**, not local. cairn folds the log by `(ts, event_id)` — timestamp, then ULID as tiebreaker — not by the local row number a given database happened to assign. The local `seq` orders one database's storage; the portable order reproduces the *same* state on any store, regardless of the order rows landed locally. That distinction is what lets a store rebuilt on a fresh machine match the original exactly.

User-defined views are not special. When you call `define!` to name a query (see [Built-in and user-defined views](/cairn/reference/views)), cairn records a view-definition event and folds it into the `named_views` table. `undefine!` records the inverse. Replay reproduces your view vocabulary along with everything else, because a view is just more events in the log — there is no separate place your customizations live and could be lost.

## Reconcile unions the log and the cache

The two stores can drift. A database row gets committed but the matching append to the log never lands — the crash gap between a write and its mirror. Or you copy fresh logs into a store whose cache predates them. cairn closes both gaps on store-open with **reconcile**, which unions the per-task logs (the truth) with the SQLite cache (rebuildable) and brings them back into agreement.

Reconcile runs in three moves:

**Ingest log lines the cache lacks.** cairn replays every log into the database, skipping events it already holds — de-duplication is keyed on `event_key`, so re-ingesting the same event is a no-op. If any new event enters the cache, cairn re-folds the whole projection in portable order, so the materialized state reflects the full log rather than a partial splice.

**Export cache rows the logs lack.** For the reverse gap — a committed row whose append never reached the file — cairn appends those events back to the right task's log. This is the only path that writes the log during open, and it writes only what is missing, comparing by `event_key`. After this step, every event in the cache is also on disk.

**Refresh the watermarks.** cairn stamps each log's current watermark so the next open sees an unchanged store and skips it.

That last move is the efficiency story. A watermark is a content hash and byte length of a log file, stored in the database's `schema_meta`. On open, cairn compares each log's current watermark against the stored one; a file that has not moved is skipped in both directions. An unchanged store reconciles to a no-op — reconcile is cheap precisely because most logs do not change between opens. A store with no backing file (an in-memory store) reconciles to a no-op as well.

## Why the order is append-then-project

The durable append happens first, and the cache update rides only after it. cairn appends the event to the log, then folds it into the projection — never the other way around. During ingest, cairn deliberately suppresses the mirror-write step, because the events it is replaying are already on disk; mirroring them again would be redundant work against the file it is reading from.

This ordering is what makes the crash gap recoverable rather than fatal. If cairn crashes after the log append but before the cache catches up, the next open's ingest step replays the missing line and the projection heals. If it crashes after a cache write but before the mirror append — the rarer gap — the export step writes the line back. Whichever side is ahead, reconcile pulls the other forward, and because both directions key on `event_key`, neither can double-apply.

## Where this model earns its keep, and where it does not

Event sourcing is not free. The projection is a second copy of state that must be kept in step, replay has a cost proportional to history, and reasoning about a fold is more work than reasoning about a row you overwrote. cairn takes that cost on purpose, because its whole job is continuity: an agent must be able to resume into the exact state a prior session left, on a machine that may not be the one that wrote it, after a context reset or a crash. A durable, portable, replayable log is the mechanism that delivers it, and the [current-task pointer](/cairn/concepts/the-current-task-pointer) is the one piece of state deliberately kept *outside* this log, because it is per-session, not part of the shared history.

If your work is a single throwaway task in one session, you will never see reconcile do anything and the projection will never need rebuilding — the model is overkill, and that is fine; it stays out of your way. The model pays off the moment work outlives a session or is shared across more than one agent. That is the case cairn is built for.

## Related

- [The task graph](/cairn/concepts/the-task-graph) — the typed-edge graph and observation index that the projection materializes
- [Tasks, observations, handoffs](/cairn/concepts/tasks-observations-handoffs) — the three nouns that become events
- [The current-task pointer](/cairn/concepts/the-current-task-pointer) — the per-session state kept outside the event log
- [Views](/cairn/reference/views) — how `define!` records a view event that replay reproduces


#### Reads, writes, and capabilities


A capability is a tag on a tool that says what kind of effect the tool can have on the store. cairn stamps every tool with one of three: `:cairn/read`, `:cairn/write`, or `:cairn/observe`. The boundary between reading and writing is drawn by those tags, in the tool's `:metadata`, not by which tools a client happens to expose. A host that grants a session `:cairn/read` but withholds `:cairn/write` gets a session that can query, inspect, and orient, and cannot change a single edge — no matter what it calls.

This matters because cairn is one durable graph that many sessions touch at once, and an agent that can plan freely should not be able to overwrite another session's plan by accident. The split is coarse on purpose: three capabilities, not fourteen, so a host reasons about a session by the class it granted rather than by the tool list it exposed.

## Three capabilities, one per effect class

Every tool declares its capability in its registration. The classes partition the fourteen tools cleanly.

`:cairn/observe` covers exactly one tool: `observe`. An observation is the cheapest write cairn has — it appends one freeform note and moves nothing else — so it gets its own capability. A host can hand a session the right to record observations without the right to restructure the graph.

`:cairn/write` covers the eight tools that change graph structure or state: `task_create`, `task_fork`, `task_link`, `task_sever`, `task_set_metadata`, `task_update_status`, `handoff`, and `task_query_write`. These create tasks, draw and cut edges, move status, set metadata, scaffold handoffs, and run the mutating query forms. Each appends an event through the same durable boundary; see [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile).

`:cairn/read` covers the five tools that compute over the store and return text without touching it: `task_search`, `task_get`, `timeline`, `task_query`, and `task_bootstrap`. A read tool resolves a target, hydrates state, renders it, and returns. `task_bootstrap` switches the current-task pointer as a side effect of orienting, but it records no event and writes nothing to the graph — the [pointer is per-session](/cairn/concepts/the-current-task-pointer), not part of the durable task graph, so moving it is a read-class act.

The full per-tool capability column lives in [the tools reference](/cairn/reference/tools).

## The query language carries the gate as one dynamic variable

The two query tools are the interesting case, because both run the same language — TQ — over the same store, and the only difference between them is whether writes are allowed. cairn does not give the read tool a smaller language and the write tool a bigger one. It gives them the identical interpreter and flips one dynamic variable.

`task_query` runs TQ with mutation refused. `task_query_write` runs TQ with mutation allowed. When the gate is closed, any form whose head ends in `!` — a mutating step like `(:set-status! "completed")` or a write source like `(define! ...)` — is refused before it can record anything. The refusal is a structured error, not a crash:

```text
Query error: Mutations need the task_query_write surface; task_query is read-only.
```

One variable being the entire gate has a useful consequence: the read surface is *provably* non-mutating. You do not audit fourteen runners to trust that `task_query` cannot write; you audit one branch. Two guards back that branch. The append is gated by the flag the read tool binds shut, so a mutating step is refused before it reaches the durable boundary. And the read tool withholds the write context entirely — it binds the event sink to nothing — so even a step that somehow slipped the flag would have no boundary to append through. The check fires on a step's internal `:mutation` kind tag, the one `(-> (schema) (:select :kind))` projects as `kind=mutation`, not on registry membership, so a new mutating step is gated the moment it is tagged, with no second list to keep in sync.

## Set-operation operands stay read-only on both surfaces

There is a subtler rule inside `task_query_write`. The set-algebra steps — `(:union Q)`, `(:intersect Q)`, `(:minus Q)`, `(:or-else Q)` — and the operand of `(define! "name" Q)` evaluate their sub-query `Q` with the write gate shut, even when the outer query runs on the write surface. You combine and define *over* selections; you do not mutate *inside* them. So any `!`-form inside an operand is refused — it is an error, not a silently skipped step.

This is a legal write-surface query: the operand `(dormant)` is read-only, and the outer `(:set-status! "completed")` runs against everything `(active)` keeps after the minus:

```lisp
(-> (active) (:minus (dormant)) (:set-status! "completed"))
```

The mutation step returns the set it touched — each node now carrying the written status — so the call renders that set, and a trailing `(:count)` would report how many tasks it moved:

```text
2 tasks:
- 2026-06-20-wire-the-cache (completed)
- 2026-06-21-link-check-gate (completed)
```

Now move the mutation *into* the operand. The operand is evaluated with the gate bound shut, so the `(:set-status! "open")` inside `(:minus ...)` hits the same refusal as a write on the read surface:

```lisp
(-> (active) (:minus (-> (dormant) (:set-status! "open"))) (:set-status! "completed"))
```

Because the refusal is a structured `cairn-query-error` and the only handler is at the top of the runner, the *whole call* fails: it returns `isError:true`, the outer `(:set-status! "completed")` never executes, and nothing is touched. There is no per-step recovery — one refused operand mutation aborts the entire query. "Operands are read-only" means a write inside an operand aborts the call, not that the inner write is dropped while the outer write proceeds. A query that builds a target set by composing other queries can never have one of those building-block queries quietly change the data it selects from, and it can never half-apply either.

## A capability is not a promise that the tool was exposed

The capability tag describes what a tool *would* do if called; it does not by itself decide whether a client can see the tool. Exposure is the host's job. A kli host reads the `:capabilities` metadata and decides, per session, which tools to register and which to deny. Each read tool, for instance, carries the same shape the host inspects:

```lisp
:metadata '(:capabilities (:cairn/read))
```

The host never executes the tool to learn its class; it reads that tag and routes on it. Over plain MCP — [`kli mcp-serve cairn`](/cairn/cli/mcp-serve) — the same metadata travels with each tool so any MCP client can reason about it the same way.

This is why the boundary is enforced by capability and not by tool-name exposure. Hiding `task_query_write` from a client's tool list is a presentation choice; refusing `!`-forms at the interpreter is the enforcement. The first can be reconfigured per host; the second holds wherever TQ runs. The second is the load-bearing one: an agent holding only `:cairn/read` that sends a mutation through `task_query` meets the refusal above, because the gate lives at the interpreter rather than in whatever tool list the host chose to expose. The write surface is `task_query_write`, reachable only when the host has granted it.

## When the split is more than you need

For a single agent on a one-off task, the read/write/observe distinction is invisible — you hold all three and never think about which class a tool falls in. The capability model earns its keep when more than one session shares a store, or when a host wants to grant a constrained session (a reviewer, a watcher, a search-only helper) the ability to look without the ability to touch. If that is not your situation, treat this page as background: the tools behave the same whether or not you ever think about the tag they carry.

## Related

- [The tools reference](/cairn/reference/tools) — every tool with its capability gate in the parameter header
- [The TQ language](/cairn/reference/tq-language) — the read-versus-write gate inside the query grammar, step by step
- [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile) — the durable boundary every write passes through
- [The current task pointer](/cairn/concepts/the-current-task-pointer) — why moving it is a read-class act
- [Serve cairn over MCP](/cairn/cli/mcp-serve) — how capability metadata travels over MCP


#### The cairn-method


The cairn-method is a working discipline, not a feature. cairn gives an agent a durable place to keep work; the cairn-method is how an agent uses that place so a fresh session can pick the work back up. It is a loop with four phases: research, plan, implement, validate. Two heartbeat writes hold the phases together — `observe` and `handoff` — and one orienting read, `task_bootstrap`, re-enters the loop after a reset. The method ships as a skill (`cairn-method`) and six bundled prompts, so the agent reading this page can load the same discipline that authored it.

## Why a method and not just tools

A model can call [the fourteen tools](/cairn/reference/tools) without any method and get nothing durable. The graph fills with tasks that have no observations, plans whose phases never settle, handoffs that summarize nothing a next session can act on. The tools are necessary but insufficient on their own. What makes the work resumable is the order the agent writes in — what it records, when, and against which task.

The cairn-method names that order. It says: orient before writing, record findings as they surface, structure the plan as a graph the frontier can read, advance only on a real gate, and leave a summary the next session reads first. Each rule maps onto a tool or a query that already exists. The method is the contract between the agent and its future self.

## The loop

The method runs as a loop across sessions, not a script inside one. A session enters by orienting, does one kind of work, and leaves a trail. The next session — the same agent after a context reset, or a different one — enters the same way and continues. This section is the cross-session heartbeat — orient, record, hand off; the four work phases (next section) run inside it.

**Orient.** A session begins with [`task_bootstrap`](/cairn/reference/tools#task-bootstrap). One call returns the task's state, its neighbors, any open handoffs, and the recent observations. An explicit `task_id` switches the [current-task pointer](/cairn/concepts/the-current-task-pointer) to that task; with no `task_id`, it orients on the current task and adopts it only when one is not yet set. Called with neither a `task_id` nor a current task, it returns `No task to bootstrap; pass task_id or select a task first.` `task_bootstrap` records no event, so re-entering costs nothing — the call repeats freely whenever the thread is lost.

**Record.** Throughout the work, [`observe`](/cairn/reference/tools#observe) is the heartbeat — the cheapest write cairn has. It appends one freeform observation to the current task and returns `Observed on <task>.` It does not move the pointer and it does not need a status change to justify it. The cairn-method favors liberal observation over a mandated cadence: a research finding, a red-then-green test, a constraint hit, a decision made. These observations are what [`task_search`](/cairn/reference/tools#task-search) later retrieves, so a finding written once need never be re-derived.

**Hand off.** When the work spans sessions, [`handoff`](/cairn/reference/tools#handoff) scaffolds a resumable note. The one-line summary comes first and is the load-bearing field a resuming session reads before anything else; the tool returns `Handoff scaffolded for <task> at <path>` and writes a skeleton, which a rich body then overwrites. The summary is the contract; the file supplements the live timeline and observations, and never contradicts them. When the two disagree, the live stream wins.

This loop is recursive: the page you are reading was produced by an agent running it — see [What cairn is](/cairn/concepts/what-cairn-is) for that story in full.

## The four phases

Inside the loop, the work itself moves through four phases. Each ships as a prompt — `research`, `plan`, `implement`, `validate` — and each leans on the `cairn-method` skill for the discipline rather than restating it. Two more prompts, `handoff` and `resume`, wrap the loop's heartbeat and re-entry. Six prompts in total.

**Research documents what is.** Before anything changes, research documents the codebase as it stands — findings, not prescriptions. Every claim carries a `file:line` or a source URL; hypotheses stay phrased as hypotheses until a root cause is reproduced. The method requires a current task before any current-scoped write, because `observe` and the `knowledge` query both resolve against it, and every finding then sinks through `observe`. It also expects a `task_search` before re-investigation, since the answer may already be in the graph.

**Plan structures the work as a graph.** A plan in cairn is a task DAG, not a markdown file — [the graph is the source of truth](/cairn/concepts/plans-phases-and-the-frontier). Phases are child tasks created with [`task_fork`](/cairn/reference/tools#task-fork) (default edge `phase-of`); real prerequisite ordering is a `depends-on` edge added with [`task_link`](/cairn/reference/tools#task-link). Because `task_fork` makes the new child current unconditionally, the method always names the parent with `from=<parent>`. Each phase carries its own acceptance and is independently verifiable. There is no scaffold tool; the edges are built with the tools above.

**Implement advances on real gates.** Work moves through the DAG one ready phase at a time, asking `(query "plan-frontier")` for the next phase whose every `depends-on` predecessor is settled. A phase can be advanced without moving the pointer: passing `task_id=<phase>` to `observe` and [`task_update_status`](/cairn/reference/tools#task-update-status) targets it while the plan stays current. The gate is irreducible — no phase reaches `completed` until its build, tests, and typecheck actually pass. The passing output advances the DAG, not vibes.

**Validate is independent and skeptical.** A separate pass runs the gates itself rather than trusting a self-reported result, reviews the code against the DAG, and reports honestly. It reads `(query "plan")` for completion status, `(query "stale-phases")` for phases active under a finished parent, and `timeline` to reconstruct what was actually done. It classifies findings as matches, deviations, or potential issues, each with a `file:line`, and refuses to green-light advancement while build or test failures remain.

These phases are documentarian and test-first by design. The method documents what is, not what should be; it writes the failing test first, for the right reason; it leaves zero `TODO`/`FIXME`/`HACK` in shipped code. It treats honest deviation as content — when reality differs from the plan, the agent pauses, surfaces the gap, gets a decision, and records it with `observe`.

## Where the method is overkill

The cairn-method earns its weight when work outlives a single context window — multi-session efforts, plans with real phase ordering, or several agents touching the same tree. It is overkill for a one-off task finished in one sitting and never resumed. For a single quick change, a `task_create` and one `observe` is the whole method; forking phases and writing a handoff for work that ends in the same turn is ceremony, not continuity. The full loop is for the case where a reset would otherwise cost the context — that is what cairn exists for. When it would not, a plainer note wins.

## Related

- [What cairn is](/cairn/concepts/what-cairn-is) — continuity for agents, and the recursive loop in depth
- [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) — why a plan is a DAG and how the frontier picks the ready work
- [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) — the three nouns the loop writes
- [The current-task pointer](/cairn/concepts/the-current-task-pointer) — what `task_bootstrap` and `task_fork` move, and what `task_id` leaves alone
- [Serve cairn over MCP](/cairn/cli/mcp-serve) — exposing the tools, the six prompts, and the cairn-method skill over MCP


## Reference

### Tools & Query Language

#### MCP tools


cairn provides fourteen MCP tools. They are the wire surface an agent calls to plan in the task graph and resume into it: one observe tool, eight writes, and five reads. Each entry below mirrors the tool's registered schema, so the page tracks the served surface and does not drift from it.

Every tool carries a capability gate in its metadata: `:cairn/observe`, `:cairn/write`, or `:cairn/read`. The gate is the boundary, not the tool name — read and write are decided by capability, not by which tools are exposed (see [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities)). A call whose gate is not granted runs nothing.

Errors travel on two channels. Protocol faults — malformed JSON-RPC, an unknown tool, a missing required argument the schema rejects — surface as transport-level errors. Tool-execution failures surface as a normal tool result with `isError: true`, carrying the verbatim text the model reads and self-corrects from: `name is required.`, `No current task; create or select one first.`, and the rest quoted in the entries below. Every returned and error string on this page is copied from source; treat the punctuation as load-bearing.

Most tools resolve a target task the same way: the `task_id` argument when given, otherwise the [current task pointer](/cairn/concepts/the-current-task-pointer). When neither names a task, a current-scoped call fails with `No current task; create or select one first.` Task arguments accept a bare slug or a depot-prefixed one; the depot prefix is stripped before lookup.

## Tools by capability

| Tool | Capability | One line |
| --- | --- | --- |
| [`observe`](#observe) | `:cairn/observe` | Record a freeform observation on the current task. |
| [`task_create`](#task-create) | `:cairn/write` | Create a top-level task. |
| [`task_fork`](#task-fork) | `:cairn/write` | Create a child task and make it current. |
| [`task_link`](#task-link) | `:cairn/write` | Add a typed edge to a target task. |
| [`task_sever`](#task-sever) | `:cairn/write` | Remove a typed edge to a target task. |
| [`task_set_metadata`](#task-set-metadata) | `:cairn/write` | Set a free key/value on a task. |
| [`task_update_status`](#task-update-status) | `:cairn/write` | Set a task's status. |
| [`handoff`](#handoff) | `:cairn/write` | Scaffold a resumable handoff. |
| [`task_query_write`](#task-query-write) | `:cairn/write` | Run a TQ query that may mutate or define views. |
| [`task_search`](#task-search) | `:cairn/read` | Full-text search over observations. |
| [`task_get`](#task-get) | `:cairn/read` | Read computed task state. |
| [`timeline`](#timeline) | `:cairn/read` | Recent events for a task. |
| [`task_query`](#task-query) | `:cairn/read` | Run a read-only TQ query. |
| [`task_bootstrap`](#task-bootstrap) | `:cairn/read` | Orient on a task in one call. |

## Tool reference

The entries below run observe, then the write tools, then the reads. Each one uses the same field order: summary, capability gate, signature, parameters, returns, semantics, example, see also.

### observe

Record a freeform observation on the current task. This is the cheapest call and the work heartbeat.

Capability gate: `:cairn/observe`.

Signature: `observe(text, task_id?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | yes | The observation. Blank text fails with `text is required.` |
| `task_id` | string | no | Task to observe on. Defaults to the current task. |

Returns: `Observed on <task>.` Records one `observation` event.

Semantics: an observation never moves the current pointer; it appends to the task you are already on (or to `task_id`). Observations are the corpus [`task_search`](#task-search) ranks over.

Example: `observe(text="bm25 ranking confirmed against t/cairn-search.lisp")` on task `2026-06-22-tune-search` → `Observed on 2026-06-22-tune-search.`

See also: [The cairn-method](/cairn/concepts/the-cairn-method) — [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs).

### task_create

Create a top-level task. Adopts the new task as current only when no current task is set.

Capability gate: `:cairn/write`.

Signature: `task_create(name, description?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Descriptive task name. Blank fails with `name is required.` Slugified and stamped with today's UTC date; a name too thin to slugify is rejected. |
| `description` | string | no | Longer description stored on the task. |

Returns: `Created <slug>.` Records one `task.create` event.

Semantics: the slug is `YYYY-MM-DD-<slugified-name>`. Minting is idempotent over the date prefix — a name you already date-prefixed is stripped back to its core before today's prefix is stamped, so the prefix stays singular. The task becomes current only if none was set; an existing pointer is left undisturbed.

Example: `task_create(name="tune search ranking")` with no current task → `Created 2026-06-22-tune-search-ranking.`

See also: [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) — [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs).

### task_fork

Create a child task linked to a parent and make the child current. The default edge is `phase-of`, so forking builds a plan's phase backbone.

Capability gate: `:cairn/write`.

Signature: `task_fork(name, from?, edge_type?, description?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | Child task name. Blank fails with `name is required.` |
| `from` | string | no | Parent slug. Defaults to the current task; with neither, fails with `No parent task; pass from or select a task first.` The parent argument is `from`. |
| `edge_type` | string | no | One of `phase-of`, `depends-on`, `related`. Defaults to `phase-of`. An out-of-enum value fails with `"<value>" is not a valid edge type; expected one of phase-of, depends-on, related.` |
| `description` | string | no | Longer description for the child. |

Returns: `Forked <child> from <parent> (<edge>).` Records `task.create` for the child and `task.fork` on the parent.

Semantics: `task_fork` always switches the current pointer to the new child. A task cannot fork from itself; that fails with `A task cannot fork from itself.`

Example: `task_fork(name="add prefix query support")` while current on `2026-06-22-tune-search` → `Forked 2026-06-22-add-prefix-query-support from 2026-06-22-tune-search (phase-of).`

See also: [Plan and resume](/cairn/get-started/plan-and-resume) — [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) — [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields).

### task_link

Create a typed edge from the current task to a target task.

Capability gate: `:cairn/write`.

Signature: `task_link(target_id, edge_type, task_id?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `target_id` | string | yes | Edge destination slug. Blank fails with `target_id is required.` |
| `edge_type` | string | yes | One of `phase-of`, `depends-on`, `related`. An out-of-enum value fails with `"<value>" is not a valid edge type; expected one of phase-of, depends-on, related.` |
| `task_id` | string | no | Edge source. Defaults to the current task. |

Returns: `Linked <src> -> <target> (<edge>).` Records one `task.link` event.

Semantics: links the resolved source to `target_id`. A task cannot link to itself; that fails with `A task cannot link to itself.` Use `depends-on` for lateral ordering inside a plan and `related` for cross-references; `phase-of` names structural parentage. See [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields) for the closed enum.

Example: `task_link(target_id="2026-06-22-tokenizer-fix", edge_type="depends-on")` on `2026-06-22-add-prefix-query-support` → `Linked 2026-06-22-add-prefix-query-support -> 2026-06-22-tokenizer-fix (depends-on).`

See also: [`task_sever`](#task-sever) — [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields) — [The task graph](/cairn/concepts/the-task-graph).

### task_sever

Remove a typed edge from the current task to a target task.

Capability gate: `:cairn/write`.

Signature: `task_sever(target_id, edge_type, task_id?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `target_id` | string | yes | Edge destination slug. Blank fails with `target_id is required.` |
| `edge_type` | string | yes | One of `phase-of`, `depends-on`, `related`. An out-of-enum value fails with `"<value>" is not a valid edge type; expected one of phase-of, depends-on, related.` |
| `task_id` | string | no | Edge source. Defaults to the current task. |

Returns: `Severed <src> -> <target> (<edge>).` Records one `task.sever` event.

Semantics: the inverse of [`task_link`](#task-link) — it removes the named edge. Severing is recorded as its own event, so the graph's history shows when an edge was dropped.

Example: `task_sever(target_id="2026-06-22-tokenizer-fix", edge_type="depends-on")` on `2026-06-22-add-prefix-query-support` → `Severed 2026-06-22-add-prefix-query-support -> 2026-06-22-tokenizer-fix (depends-on).`

See also: [`task_link`](#task-link) — [The task graph](/cairn/concepts/the-task-graph).

### task_set_metadata

Set a free key/value on a task — for example `display-name`, `phase`, `objective`, `acceptance`, or `tags`.

Capability gate: `:cairn/write`.

Signature: `task_set_metadata(key, value, task_id?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | yes | Metadata key. Blank fails with `key is required.` |
| `value` | string | yes | Value to store. Required by the schema; a null value is coerced to the empty string rather than rejected. |
| `task_id` | string | no | Task to annotate. Defaults to the current task. |

Returns: `Set <key> on <task>.` Records one `task.set-metadata` event.

Semantics: metadata is open — any key is accepted, and setting an existing key overwrites it. Most keys are read back as open text. A handful map to typed [queryable fields](/cairn/reference/edges-statuses-and-fields) (for instance `display-name`); the rest stay free-form.

Example: `task_set_metadata(key="acceptance", value="prefix queries return ranked snippets")` on `2026-06-22-add-prefix-query-support` → `Set acceptance on 2026-06-22-add-prefix-query-support.`

See also: [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields) — [Tasks, observations, handoffs](/cairn/concepts/tasks-observations-handoffs).

### task_update_status

Set a task's status. Idempotent.

Capability gate: `:cairn/write`.

Signature: `task_update_status(status, task_id?, reopen?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | yes | One of `open`, `active`, `completed`, `abandoned`, `blocked`. Missing fails with `status is required.`; out of enum fails with `"<status>" is not a valid status; expected one of open, active, completed, abandoned, blocked.` |
| `task_id` | string | no | Task to update. Defaults to the current task. |
| `reopen` | boolean | no | When true and `status` is omitted, sets the status to `active` to revive a completed task. |

Returns: `<task> is now <status>.` Records one `task.update-status` event.

Semantics: status is lower-cased before validation. Re-applying the same status is a no-op event-wise but still returns the line. Marking a phase `completed` is what advances the plan frontier (see [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier)).

Example: `task_update_status(status="completed")` on `2026-06-22-tokenizer-fix` → `2026-06-22-tokenizer-fix is now completed.`

See also: [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields) — [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier).

### handoff

Scaffold a resumable handoff for the current task. The summary is the load-bearing field; an optional path points at a written note.

Capability gate: `:cairn/write`.

Signature: `handoff(summary, path?, task_id?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `summary` | string | yes | One-line summary of where the work stands. Blank fails with `summary is required.` |
| `path` | string | no | File path for the note. Defaults to a timestamped file under the task scratchpad. |
| `task_id` | string | no | Task to hand off. Defaults to the current task. |

Returns: `Handoff scaffolded for <task> at <path>` — no trailing period. Records one `handoff.create` event.

Semantics: `handoff` is deterministic. It mints a path, writes a skeleton (frontmatter, a computed state snapshot, and empty `## Recent work` / `## Next steps` sections), records the event, and returns the path. It never drives an authoring turn — the caller overwrites the skeleton with the rich body. An existing file at the path is left in place. The richer, interactive authoring flow is the [`/handoff` slash command](/cairn/cli/slash-commands), which is separate from this tool.

Example: `handoff(summary="prefix queries land; tokenizer fix is next")` on `2026-06-22-add-prefix-query-support` → `Handoff scaffolded for 2026-06-22-add-prefix-query-support at <scratchpad>/2026-06-22_14-30-05_prefix-queries-land-tokenizer-fix-is-next.md`

See also: [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) — [Slash commands](/cairn/cli/slash-commands).

### task_query_write

The write surface for the TQ query language, accepting the `!`-forms that [`task_query`](#task-query) refuses.

Capability gate: `:cairn/write`.

Signature: `task_query_write(query)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | A single TQ s-expression. Accepts mutating steps (`:set-status!`, `:set!`, `:link!`, `:unlink!`) and the view forms `define!` / `undefine!`. |

Returns: the rendered query result as text. A mutation step records one append-only event per task it touches and returns the set, so a trailing `(:count)` reports how many tasks were affected. `define!` records the named view in the durable log.

Semantics: mutations converge on re-run — the same query applied twice reaches the same state. Sub-query operands inside set operations always evaluate read-only, even on this surface. `(define! "name" Q)` records `Q` as a reusable named view resolvable as `(query "name")`; a user view shadows a built-in of the same name. Read-only queries also run here, but prefer [`task_query`](#task-query) for them.

Example: `task_query_write(query="(-> (query \"plan-frontier\") (:set-status! \"active\"))")` → marks every ready phase `active` and returns the set.

See also: [The TQ language](/cairn/reference/tq-language) — [Views](/cairn/reference/views) — [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities).

### task_search

Full-text ranked search over observations. Returns matching tasks with a snippet.

Capability gate: `:cairn/read`.

Signature: `task_search(query, limit?, task_id?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Free-text search. Blank fails with `query is required.` Sanitized into an FTS5 MATCH expression. |
| `limit` | integer | no | Maximum results. Defaults to 10, clamped to a maximum of 50. |
| `task_id` | string | no | Restrict the search to one task's observations. |

Returns: ranked rows (task slug plus a snippet), or `No matching observations for "<query>".` when nothing matches. A query the engine cannot parse fails with `Could not parse the search query "<query>".` Records no event.

Semantics: results are BM25-ranked. The sanitizer is forgiving so identifiers and paths search literally: a token carrying any of the special characters `" ( ) : - . / ^ * +` is phrase-quoted (so `tools.lisp:45-78` and `depends-on` match as written), a trailing `*` stays a prefix query, and tokens join with implicit AND. A query that sanitizes to nothing usable returns the no-match line rather than erroring.

Example: `task_search(query="prefix query*")` → ranked observations across tasks whose text contains a token starting with `prefix` and the token `query`.

**Deferred scope.** A `scope` parameter exists in the runner (defaulting to observations) but is not in the registered wire schema, so tool-call search is deferred. Treat observation search as the advertised contract.

See also: [The task graph](/cairn/concepts/the-task-graph) — [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs).

### task_get

Read computed task state: status, description, parent, children, edges, metadata, and recent observations.

Capability gate: `:cairn/read`.

Signature: `task_get(task_id?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | string | no | Task to read. Defaults to the current task. |

Returns: a rendered state block, or `No task <slug>.` when the slug is unknown. Records no event.

Semantics: the state is computed from the event log, not stored as a row of flags. The block carries the slug and status, then any description, parent, children, outgoing edges, metadata pairs, and up to five most recent observations. When more than five observations exist, a final pointer line — `… N earlier observations — call timeline with full=true, types=observation to read them all` — names how to read the rest. Each edge line prints the edge type first, then the destination slug. It is the same snapshot embedded at the top of [`task_bootstrap`](#task-bootstrap).

Example: `task_get(task_id="2026-06-22-add-prefix-query-support")` →

```text
2026-06-22-add-prefix-query-support  [active]
  add prefix query support
  parent: 2026-06-22-tune-search
  edges:
    depends-on 2026-06-22-tokenizer-fix
  recent:
    - prefix queries land; tokenizer fix is next
```

See also: [`timeline`](#timeline) — [`task_bootstrap`](#task-bootstrap) — [The task graph](/cairn/concepts/the-task-graph).

### timeline

Recent events for a task, most recent first.

Capability gate: `:cairn/read`.

Signature: `timeline(task_id?, types?, full?, before_seq?, after_seq?, limit?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | string | no | Task to read. Defaults to the current task. |
| `types` | string | no | Comma-separated event-type filter, validated against the live vocabulary. Omitted or blank means every type. |
| `full` | boolean | no | When true, render each event verbatim — a header line plus the untruncated multi-line body — instead of the one-line digest. Defaults to false. |
| `before_seq` | integer | no | Exclusive upper seq bound; also the page-back cursor printed when output is truncated. |
| `after_seq` | integer | no | Exclusive lower seq bound. |
| `limit` | integer | no | Number of events. Defaults to 20. |

Returns: a header line `<task> — last <N> events` followed by one line per event (sequence number, event type, and a one-line digest of its payload). With `full=true`, each event instead renders as a header `<seq>  <type>  (<YYYY-MM-DD HH:MM> UTC)` and its verbatim body, block-indented when multi-line. Output is capped at a soft character ceiling: when the next event would exceed it, emission stops and prints `… truncated at <N> chars; <M> events remaining; pass before_seq=<seq> to continue`. Records no event.

Semantics: where [`task_get`](#task-get) shows computed state, `timeline` shows the raw event stream that produced it — `observation`, `task.create`, `task.fork`, `task.link`, `task.sever`, `task.update-status`, `task.set-metadata`, `handoff.create`, and so on. By default each digest is collapsed to a single line and truncated; `full=true` renders bodies verbatim, making `timeline` the way to read a task's complete observation history. Filter to one or more event types with `types` — an unknown type errors with a nearest-match suggestion rather than silently returning nothing. Window or page with `before_seq` (exclusive) and `after_seq` (exclusive): feeding the `before_seq` cursor from a truncated page back into the next call returns the older events with no gap and no overlap. Read it to reconstruct how a task got where it is.

Example: `timeline(task_id="2026-06-22-add-prefix-query-support", limit=3)` →

```text
2026-06-22-add-prefix-query-support — last 3 events
  7  handoff.create  prefix queries land; tokenizer fix is next → ...
  6  task.update-status  → active
  5  observation  bm25 ranking confirmed against t/cairn-search.lisp
```

Example: `timeline(types="observation", full=true)` renders every observation on the current task verbatim — full multi-line bodies, no 140-character digest cut — newest first.

See also: [`task_get`](#task-get) — [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile).

### task_query

Run a read-only query over the task graph and return text. The query is a single s-expression in cairn's query language (TQ).

Capability gate: `:cairn/read`.

Signature: `task_query(query)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | One TQ s-expression. A Lisp form, not a bare word — names and probes are wrapped in parens. |

Returns: the rendered query result as text. Every form yields a value or a structured error, never a crash or a silent no-op. Records no event.

Semantics: a query is a `SOURCE` optionally threaded through `STEP`s with `->`, for example `(-> (current) (:follow :phase-of) (:ids))`. Transformer steps compose node-set to node-set; shaper steps such as `(:select :slug :status)`, `(:count)`, and `(:ids)` terminate into a value. Pass a reflective form on its own to learn the surface: `(schema)` lists the sources, steps, predicates, and write forms, with steps and predicates carrying their kinds and argument signatures — call it first; `(views)` lists named views, `(fields)` the queryable fields, `(edges)` the edge types. These are sources that list names, so project with `(:select …)`. An unknown field, predicate, step, source, or edge errors with a nearest-match suggestion rather than a silent miss. Timestamps (`created-ts`, `updated-ts`, `status-ts`) are universal-time, so a date intent is one predicate — `(on :updated-ts "2026-06-24")`, `(since …)`, `(before …)` — and an integer operand to a numeric comparison against a timestamp is read as Unix seconds. Run a named view by wrapping it as `(query "plan")` or `(query "plan-frontier")`; a bare word like `plan` is a query error, since it is not a source form. The `!`-forms — mutations and view definitions — are refused here; use [`task_query_write`](#task-query-write).

Example: `task_query(query="(-> (current) (:follow :phase-of) (:select :slug :status))")` → the current task's phase-of children with their statuses.

See also: [The TQ language](/cairn/reference/tq-language) — [Views](/cairn/reference/views).

### task_bootstrap

Orient on a task in one call: its computed state, neighbors, open handoffs, and recent observations.

Capability gate: `:cairn/read`.

Signature: `task_bootstrap(task_id?)`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | string | no | Task to orient on. Defaults to the current task; with neither, fails with `No task to bootstrap; pass task_id or select a task first.` An unknown slug fails with `No task <slug>.` and lists recent slugs. |

Returns: the [`task_get`](#task-get) state block, then any open handoffs. Records no event.

Semantics: `task_bootstrap` is the single-call session-start read. An explicit `task_id` switches the current pointer to that task — orienting on a task makes it current, so spawned sessions and the injected context agree on what is in focus. With no `task_id`, it orients on the current task and adopts it only when none is set; the pointer switches only after the task is found.

Example: `task_bootstrap(task_id="2026-06-22-add-prefix-query-support")` → the task's state block and its open handoffs.

See also: [The current task pointer](/cairn/concepts/the-current-task-pointer) — [The cairn-method](/cairn/concepts/the-cairn-method).


#### The TQ query language


TQ is the S-expression query language cairn evaluates over the [task graph](/cairn/concepts/the-task-graph). A query is one source form, or a source threaded through pipeline steps with `->`. It is read with `*read-eval*` disabled and walked, never evaluated, then lowered onto SQL over the task projection plus a few in-memory folds. Every result renders to text before it leaves the runner, so nothing but a string crosses the tool boundary, and every failure is a structured `Query error:` or `Parse error:` rather than a backtrace.

Two tools run TQ: [`task_query`](/cairn/reference/tools#task-query) reads, and [`task_query_write`](/cairn/reference/tools#task-query-write) reads and writes. The language is the same on both; one dynamic gate decides whether a mutation form is allowed.

## Synopsis

```text
QUERY  := SOURCE | (-> SOURCE STEP...)
SOURCE := (all) | (active) | (dormant) | (current)
        | (node "<substr>") | (query "<name>")
        | (schema) | (views) | (fields) | (edges)
        | (define! "<name>" QUERY) | (undefine! "<name>")   # write surface only
STEP   := (<keyword> ARG...)
```

A query is exactly one S-expression. The bare `->` head opens a pipeline whose first element is a source and whose rest are steps applied left to right. A step is a keyword form like `(:follow :phase-of)`; a bare keyword such as `:ids` is rejected — every operator is a form. A source carrying the wrong arity or an empty string argument errors rather than returning an empty set.

## Read versus write

The `!`-suffix marks every mutation. `task_query` binds the gate off, so any `!`-form — a `(:set-status! ...)` step or a `(define! ...)` source — is refused:

```text
Query error: Mutations need the task_query_write surface; task_query is read-only.
```

`task_query_write` binds the gate on and accepts them. The gate keys on the `!`-suffix and the step's `:mutation` kind, not on which tool is registered, so a write can never slip through the read surface. Inside set-operation operands and inside `(define! "name" Q)` the gate is forced off regardless of surface: you combine and define over selections, you do not mutate inside them. A mutation form within an operand is refused even under `task_query_write`. See [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities).

## Sources

A source is a nullary producer of a node-set. A node is a slug paired with its hydrated properties. The four broad sources exclude the reserved `@`-prefixed namespace (the `@cairn` view node); real task slugs are date-prefixed, so nothing a user created is dropped, and `(node ...)` and `(current)` still address reserved nodes.

| Form | Yields | Notes |
| --- | --- | --- |
| `(all)` | Every task. | Excludes the reserved namespace. |
| `(active)` | Tasks with status `open`, `active`, or `blocked`. | The live half of the status enum. |
| `(dormant)` | Tasks with status `completed` or `abandoned`. | The settled half. |
| `(current)` | The current task. | Errors when no task is selected: `This query needs a current task; select one first.` |
| `(node "substr")` | Tasks whose slug contains the substring. | Case-insensitive; a non-empty pattern is required. |
| `(query "name")` | The named view resolved to its node-set. | An unknown name errors and enumerates the available views. |
| `(schema)` | The source/step/write grammar as a node-set. | Reflective; see below. |
| `(views)` | The named views, built-in and user, as a node-set. | Reflective. |
| `(fields)` | The queryable fields and their value types. | Reflective. |
| `(edges)` | The edge vocabulary and each type's class. | Reflective. |
| `(define! "name" Q)` | Records `Q` as a named view; returns `Q`'s tasks. | Write surface only. |
| `(undefine! "name")` | Removes a user view, restoring any built-in; returns nothing. | Write surface only. |

`recent` is a **view**, not a source: reach it with `(query "recent")`. There is no `(recent)` source form. The list of resolvable view names lives in [Views](/cairn/reference/views).

## Steps

A step transforms or shapes the running node-set. Transformers map a node-set to a node-set and compose; shapers terminate the pipeline into a final value (a projection, a group, a slug list, or a count); mutations write and return their input so they keep composing. A shaper must be last — a transformer after a terminal value errors with `This step expects a set of tasks, but the previous step produced a final value.`

**Transformers** map a node-set to a node-set, so they chain.

### `(:follow EDGE)`

The tasks one `EDGE` hop forward. Structural edges (`phase-of`, `forked-from`) traverse the parent foreign key; lateral edges (`depends-on`, `related`) traverse the edges table. The edge is validated first, so an unknown type errors even over an empty input — the edge is a property of the query, not of the data.

```lisp
(-> (node "auth") (:follow :phase-of) (:ids))
```

### `(:back EDGE)`

The tasks one `EDGE` hop backward — the inverse of `:follow`. From a forked child, `(:back :phase-of)` reaches its parent.

```lisp
(-> (node "phase-3") (:back :phase-of) (:ids))
```

### `(:where PRED)`

The tasks satisfying predicate `PRED`. A predicate that references a non-local field auto-enriches the set on demand; a predicate over a base field reads it directly without enrichment. See [Predicates](#predicates).

```lisp
(-> (active) (:where (= :status "blocked")) (:ids))
```

### `(:sort FIELD [:asc|:desc])`

The node-set ordered by `FIELD` — numeric when the field holds numbers, lexical otherwise. The direction is optional and defaults to `:desc`; pass `:asc` to ascend. A direction that is neither `:asc` nor `:desc` is a structured error with a suggestion, not a silently ignored argument.

```lisp
(-> (active) (:sort :updated-ts))         ; most-recent first — the default
(-> (active) (:sort :slug :asc) (:ids))   ; A→Z by slug
```

```text
Query error: :sort needs :asc or :desc; did you mean :asc?
```

### `(:take N)`

The first `N` tasks. `N` must be an integer; a negative `N` clamps to zero.

```lisp
(-> (active) (:sort :obs-count) (:take 10))
```

### `(:enrich)`

Add counts and promoted metadata (`:obs-count`, `:edge-count`, and any metadata keys) to each node, so fields beyond the hydrated base become readable and printable.

```lisp
(-> (current) (:enrich))
```

### `(:union Q)`

Tasks in the pipeline or in sub-query `Q`, deduplicated by slug. `Q` must itself yield a node-set, evaluated read-only.

```lisp
(-> (active) (:union (dormant)) (:count))
```

### `(:intersect Q)`

Tasks in both the pipeline and sub-query `Q`.

```lisp
(-> (all) (:intersect (active)) (:count))
```

### `(:minus Q)`

Pipeline tasks not in sub-query `Q`.

```lisp
(-> (all) (:minus (active)) (:ids))
```

### `(:or-else Q)`

The pipeline if it holds any task, else sub-query `Q`. Used by the `plan` view to fall back from a root's children to its siblings.

```lisp
(-> (current) (:follow :phase-of) (:or-else (active)))
```

### `(:closure EDGE...)`

The forward transitive closure over one or more edge types, cycle-safe and bounded to depth 5. The starting nodes are excluded unless a cycle leads back to one. Each edge is validated eagerly. The `knowledge` view is `(:closure :phase-of :depends-on :related)`.

```lisp
(-> (current) (:closure :phase-of :depends-on :related) (:enrich))
```

**Shapers** end the pipeline in a final value and must come last. The text below each shaper is exactly what the runner returns.

### `(:select FIELD...)`

Project the named fields; at least one field is required. Every selected field is validated against the [field vocabulary](/cairn/reference/edges-statuses-and-fields), so an unknown field is a structured error with a nearest-match suggestion rather than a silently dropped column:

```lisp
(-> (all) (:select :updated-at))
```

```text
Query error: Unknown field :updated-at; did you mean :updated-ts?
```

A projected field that is not already on the node — a count or a promoted metadata key — is enriched on demand, so it shows its value instead of nothing. The result is rectangular: every selected field prints on every row, an absent value as the empty-set glyph `∅`, and a [timestamp field](/cairn/reference/edges-statuses-and-fields#fields) as its raw universal-time integer followed by the decoded UTC date.

```lisp
(-> (node "auth") (:select :display-name :status))
```

```text
1 task:
- 2026-04-02-auth-rework  display-name=Auth rework  status=active
```

```lisp
(-> (node "rate-limit") (:select :slug :obs-count :updated-ts :parent))
```

```text
1 task:
- 2026-04-05-rate-limit  slug=2026-04-05-rate-limit  obs-count=4  updated-ts=3984388200 (2026-04-05)  parent=∅
```

### `(:group-by FIELD)`

Bucket the node-set by `FIELD` value, largest bucket first.

```lisp
(-> (active) (:group-by :status))
```

```text
2 groups:

## active (2)
- 2026-04-02-auth-rework [Auth rework] (active)
- 2026-04-05-rate-limit (active)

## blocked (1)
- 2026-03-30-token-store (blocked)
```

### `(:ids)`

The slugs only, one per line, under a count line.

```lisp
(-> (active) (:ids))
```

```text
3 tasks:
- 2026-03-30-token-store
- 2026-04-02-auth-rework
- 2026-04-05-rate-limit
```

The count line pluralizes: a one-task result reads `1 task:`, and an empty result is the single line `No matching tasks.`

### `(:count)`

The cardinality, as a bare number with no surrounding text.

```lisp
(-> (all) (:count))
```

```text
2
```

**Mutations** are transformers that also write. A mutation records one event per real task through the durable [event log](/cairn/concepts/events-projection-and-reconcile) and returns its input set, so `(:count)` after it reports the size of the set it ran over — equal to the number of real tasks touched when no synthesized nodes are present. A synthesized node — a grammar node from a reflective source — carries no task id and is passed over, never minting a phantom, yet stays in the returned set. Events are append-only and their projection effects converge, so re-running a mutation is safe. Every mutation requires the `task_query_write` surface.

### `(:set-status! STATUS)`

Set each task's status. `STATUS` must be one of `open`, `active`, `completed`, `abandoned`, `blocked`.

```lisp
(-> (active) (:set-status! "completed") (:count))
```

```text
3
```

### `(:set! :key "value")`

Set a metadata field on each task. The key is a field keyword; it refuses `:slug` and `:status` (status has its own step).

```lisp
(-> (current) (:set! :objective "ship it"))
```

### `(:link! :edge "target")`

Add an edge from each task to the constant `target` slug. `:edge` is one of `phase-of`, `depends-on`, or `related` — the same closed enum the [`task_link`](/cairn/reference/tools) tool takes. A `depends-on` or `related` link lands in the edges table; a `phase-of` link is structural and folds into the parent foreign key rather than the lateral table, exactly as the [edges reference](/cairn/reference/edges-statuses-and-fields) describes. A task equal to the target is skipped — a task does not edge to itself.

```lisp
(-> (node "phase-2") (:link! :depends-on "phase-1"))
```

### `(:unlink! :edge "target")`

Remove the edge from each task to `target`. `:edge` is one of `phase-of`, `depends-on`, or `related`, matching `(:link!)`.

```lisp
(-> (node "phase-2") (:unlink! :depends-on "phase-1"))
```

## Predicates

A predicate is the argument to `(:where ...)` and to quantifiers. It is a form of `(slug props)` and composes with boolean combinators.

| Form | Meaning |
| --- | --- |
| `(= LHS v)` | `LHS` equals literal `v`. `LHS` is a field keyword or `(count TRAV)`. |
| `(has :field)` | `:field` is present and non-null on the node. |
| `(matches :field "substr")` | `:field`'s value contains the case-insensitive substring. |
| `(> LHS n)` | `LHS` is greater than real number `n`. |
| `(< LHS n)` | `LHS` is less than `n`. |
| `(>= LHS n)` | `LHS` is at least `n`. |
| `(on :ts "YYYY-MM-DD")` | timestamp field `:ts` falls on the given UTC day. |
| `(since :ts "YYYY-MM-DD")` | `:ts` is on or after the given UTC day. |
| `(before :ts "YYYY-MM-DD")` | `:ts` is before the given UTC day. |
| `(and P...)` | Every sub-predicate holds. |
| `(or P...)` | Some sub-predicate holds. |
| `(not P)` | `P` does not hold. |
| `(all TRAV P)` | `P` holds for every task one `TRAV` hop away. |
| `(any TRAV P)` | `P` holds for some task one `TRAV` hop away. |
| `(none TRAV P)` | `P` holds for no task one `TRAV` hop away. |

In a quantifier, `TRAV` is `(:follow EDGE)` or `(:back EDGE)`. The traversal's edge is validated eagerly, so an ill-typed quantifier errors even over an empty focus set. Over a focus node with no neighbours, `all` and `none` are vacuously true and `any` is false.

Numeric comparisons are type-checked. The left side of `>`, `<`, or `>=` must be a numeric field (one of `created-ts`, `updated-ts`, `status-ts`, `obs-count`, `edge-count`) or `(count TRAV)`, and the operand a real number; comparing a text field numerically is an error, not a silent empty match. `(count TRAV)` is the cardinality of a relative traversal, usable wherever a numeric left side is.

```lisp
(-> (node "release") (:where (> (count (:follow :depends-on)) 1)) (:ids))
```

The full field vocabulary and which fields are textual versus numeric is in [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields).

### Dates and timestamps

`created-ts`, `updated-ts`, and `status-ts` are `:timestamp` fields: CL universal-time, an integer count of seconds since `1900-01-01 UTC`. They order as integers and read as dates. The `on` / `since` / `before` predicates window the clock by a calendar day so a date intent is one predicate, not a reverse-engineered range. Each parses a strict `YYYY-MM-DD` operand at UTC midnight; `on` matches the 24-hour day `[day, day+1)`, `since` matches `≥ day`, and `before` matches `< day`.

```lisp
(-> (active) (:where (on :updated-ts "2026-06-24")) (:ids))
(-> (active) (:where (since :created-ts "2026-06-01")) (:count))
```

A date predicate is gated to timestamp fields, and a malformed date is a structured error rather than a silent empty result:

```text
Query error: on needs a timestamp field; :status is text.
Query error: "not-a-date" is not a YYYY-MM-DD date.
```

Because a timestamp orders as an integer, the numeric predicates compare it too. An **integer** operand to `>`, `<`, or `>=` against a timestamp field is read as Unix seconds and lifted onto the same universal-time clock the write path uses, so a Unix-epoch literal lands where you mean it instead of below every value. `(< :updated-ts 2500000000)` compares against the lifted instant, not the raw integer.

### Unknown names suggest a fix

Every dispatched name — a field, a predicate, a step, a source, an edge type — is validated against its vocabulary, and an unknown one is a structured error carrying the nearest match within a small edit distance, or the full list when nothing is close. The query never silently misfires on a typo.

```text
Query error: Unknown predicate matchez; did you mean matches?
Query error: Unknown step :zelect; did you mean :select?
Query error: Unknown source recent; known: active, all, current, dormant, edges, fields, node, query, schema, views.
```

## Reflective forms

`(schema)`, `(fields)`, `(edges)`, and `(views)` are sources that render the language's own vocabularies as node-sets in the same carrier task queries produce, so every step composes over them. The slugs are bare names, never date-prefixed, so they never collide with a task, and a task traversal over a grammar node is an honest empty set rather than an error. Each list is generated from the registry the interpreter dispatches on, so the description cannot drift from behaviour.

| Source | Each node carries |
| --- | --- |
| `(schema)` | `:category` (`source`/`step`/`predicate`/`write`); `:kind` on steps (`transformer`/`shaper`/`mutation`) and predicates (`leaf`/`combinator`/`quantifier`); `:signature` (the machine-readable argument contract) on steps and predicates; and `:doc`. |
| `(fields)` | `:origin` (`declared` or `metadata`), `:type` (`text`, `number`, or `timestamp`), and on a timestamp field `:unit` and `:epoch`. |
| `(edges)` | `:class` (`structural` or `lateral`). |
| `(views)` | `:origin` (`builtin` or `user`) and `:source` (the view's TQ text). |

`(schema)` lists predicates alongside sources and steps, so the predicate vocabulary — including the date predicates and their signatures — is discoverable from the one call. There is no `(help)` source; `(schema)` is the canonical entry point to the grammar.

Probe the grammar with the algebra:

```lisp
(-> (schema) (:where (= :kind "shaper")) (:ids))
(-> (schema) (:where (= :category "predicate")) (:select :kind :signature))
(-> (fields) (:where (= :type "timestamp")) (:ids))
(-> (edges) (:where (= :class "structural")) (:ids))
(-> (views) (:where (= :origin "builtin")) (:ids))
```

The first lists the shapers by their bare names, sorted with the rest of the carrier:

```text
4 tasks:
- count
- group-by
- ids
- select
```

The second reads the predicate vocabulary with its kinds and signatures — for example the three date predicates share the signature `field-ts lit-date`, so `(-> (schema) (:where (= :signature "field-ts lit-date")) (:ids))` recovers `before`, `on`, and `since`.

Reflective sources run on the read surface — they describe, never mutate — and stay total. Use `(:select ...)` to project a field, for example `(-> (schema) (:where (= :category "step")) (:select :doc))`.

## Worked examples

Each program is one full query. Read-surface examples run under either tool; write-surface examples require [`task_query_write`](/cairn/reference/tools#task-query-write). The text fence under each query is the runner's actual output.

```lisp
(-> (active) (:where (not (has :parent))))
```

```text
2 tasks:
- 2026-04-02-auth-rework [Auth rework] (active)
- 2026-04-05-rate-limit (active)
```

Read. Active tasks with no parent — the `active-roots` view: every live root in the graph. With no `(:ids)` or `(:select ...)` shaper the result is the node-set itself, one `- slug [display] (status)` line per task; `:parent` is a base field, so the predicate reads it without enrichment and the lines carry no `obs=`/`edges=` counts. Add `(:enrich)` before the implicit render to print them.

```lisp
(-> (current) (:follow :phase-of) (:ids))
```

```text
3 tasks:
- 2026-04-02-auth-rework-phase-1
- 2026-04-02-auth-rework-phase-2
- 2026-04-02-auth-rework-phase-3
```

Read. The phases directly under the current task.

```lisp
(query "plan-frontier")
```

Read. The phases of the current plan that are not done and whose every `depends-on` dependency is settled — the ready work. `(query "frontier")` is an alias.

```lisp
(-> (node "auth") (:where (matches :description "oauth")) (:ids))
```

Read. Tasks whose slug contains `auth` and whose description mentions `oauth`.

```lisp
(-> (active) (:union (dormant)) (:count))
```

```text
2
```

Read. The size of the whole task set, by the status partition.

```lisp
(-> (current) (:closure :phase-of :depends-on :related) (:enrich))
```

Read. The transitive neighbourhood of the current task across every edge — the `knowledge` view.

```lisp
(-> (active) (:set-status! "completed") (:count))
```

```text
3
```

Write. Complete every active task and report how many were touched; re-running over the now-empty active set touches nothing and returns `0`.

```lisp
(-> (node "phase-2") (:link! :depends-on "phase-1"))
```

Write. Add a `depends-on` edge from each `phase-2` task to `phase-1`. The link step returns its input set, so the rendered output is the touched `phase-2` nodes.

```lisp
(define! "blocked-work" (-> (active) (:where (= :status "blocked"))))
```

Write. Record a user view named `blocked-work`; it then resolves on the read surface via `(query "blocked-work")` and shadows any built-in of the same name. `(undefine! "blocked-work")` removes it.

## Related

- [Tools](/cairn/reference/tools#task-query) — the `task_query` and `task_query_write` tool surface that runs TQ.
- [Views](/cairn/reference/views) — the built-in named views, each with its TQ source text.
- [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields) — the closed enums TQ predicates and steps validate against.
- [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities) — why the `!`-gate is one dynamic boundary.


#### Built-in and user-defined views


A view is a named query: a label bound to a piece of [TQ source text](/cairn/reference/tq-language) that resolves to a set of tasks when you call `(query "name")`. cairn ships ten built-in views, expressed in TQ itself. They are the language's shipped vocabulary — `plan-frontier`, `leaf-tasks`, `stale-phases`, and the rest — and you read them on the read surface through [`task_query`](/cairn/reference/tools#task-query) or define your own through [`task_query_write`](/cairn/reference/tools#task-query-write).

Each built-in is data, not tool surface. The view's body is ordinary TQ, so you can read the definition with `(-> (views) (:where (= :origin "builtin")) (:select :source))`, copy it, and adapt it. A view defined under your own name shadows the built-in of the same name; remove the user view and the built-in reappears.

## Reading a view

Resolve any view by name with the `(query "name")` source:

```text
task_query  (query "plan-frontier")
```

The result renders as a task list — one line per task, slug first, then display name, status, and any counts the view enriched:

```text
2 tasks:
- 2026-06-20-write-the-parser (open) obs=3 edges=2
- 2026-06-20-wire-the-cli (open) obs=1 edges=1
```

`(query "name")` is a read. A view defined on the write surface still resolves on the read surface, because reading a view is a read regardless of how the view was created. Naming a view that does not exist is a structured error that enumerates every resolvable name — both built-in and user-defined:

```text
Query error: Unknown named query plan-fronteir. Available: active-roots, orphans, leaf-tasks, stale-phases, plan, plan-frontier, frontier, recent, busy, hub-tasks, knowledge.
```

## The ten built-in views

The table lists every shipped view with its TQ source text exactly as cairn defines it. `frontier` is an alias — its body is `(query "plan-frontier")` — so the eleven accepted names resolve to ten distinct queries.

| View | TQ source | Yields |
| --- | --- | --- |
| `active-roots` | `(-> (active) (:where (not (has :parent))))` | Live tasks with no parent — the roots of every open plan. |
| `orphans` | `(-> (all) (:where (= :edge-count 0)))` | Tasks with no edges in any direction: unparented, unlinked, unforked. |
| `leaf-tasks` | `(-> (active) (:where (= (count (:follow :phase-of)) 0)))` | Live tasks with no phase children — the bottom of the plan tree. |
| `stale-phases` | `(-> (active) (:where (any (:back :phase-of) (or (= :status "completed") (= :status "abandoned")))))` | Live phases whose parent has already settled, a sign the plan moved on without them. |
| `plan` | `(-> (current) (:follow :phase-of) (:or-else (-> (current) (:back :phase-of) (:follow :phase-of))) (:enrich))` | The phases of the current task's plan, enriched with counts. Current-scoped. |
| `plan-frontier` | `(-> (query "plan") (:where (and (not (or (= :status "completed") (= :status "abandoned"))) (all (:follow :depends-on) (or (= :status "completed") (= :status "abandoned"))))))` | The ready subset of `plan`: unsettled phases whose every `depends-on` dependency is settled. |
| `frontier` | `(query "plan-frontier")` | Alias for `plan-frontier`. |
| `recent` | `(-> (active) (:sort :updated-ts) (:take 20))` | The twenty most recently touched live tasks. |
| `busy` | `(-> (active) (:sort :obs-count) (:take 20))` | The twenty live tasks with the most observations. |
| `hub-tasks` | `(-> (active) (:sort :edge-count) (:take 20))` | The twenty live tasks with the most edges — the connectors in the graph. |
| `knowledge` | `(-> (current) (:closure :phase-of :depends-on :related) (:enrich))` | The transitive neighborhood of the current task across all three edge types, cycle-safe and depth-bounded. |

Three of these views read the `(current)` source — `plan`, `frontier`/`plan-frontier`, and `knowledge` — so they resolve against [the current task pointer](/cairn/concepts/the-current-task-pointer) and error when no task is selected. The rest range over `(active)` or `(all)` and resolve the same way in every session. The [TQ sources](/cairn/reference/tq-language#sources) table defines each producer.

### Built-in source forms in TQ

Each built-in is a complete TQ program, and every piece it draws on is documented in the [TQ language reference](/cairn/reference/tq-language). The [sources](/cairn/reference/tq-language#sources) are `(active)`, `(all)`, and `(current)`. The [steps](/cairn/reference/tq-language#steps) are `(:where)`, `(:follow)`, `(:back)`, `(:sort)`, `(:take)`, `(:or-else)`, `(:closure)`, and `(:enrich)`. Inside a predicate they reach across edges with the `(any TRAV P)` and `(all TRAV P)` quantifiers and count with the `(count TRAV)` field-expression. `plan-frontier` composes over `plan` by name, and `frontier` composes over `plan-frontier` by name, so a view defined in terms of another view resolves transitively.

A view defined in terms of itself is a structured error, not an unbounded loop. Define a view named `self` whose body is `(query "self")` and resolving it reports the cycle rather than recursing — `self` in the error text is the offending view name:

```text
Query error: View self is defined in terms of itself.
```

## `recent` is a view, not a source

`recent` is a view name, so you read it with `(query "recent")`. `(recent)` is not a source form. The query language has exactly ten sources — `(all)`, `(active)`, `(dormant)`, `(current)`, `(node "substr")`, `(query "name")`, `(schema)`, `(views)`, `(fields)`, `(edges)` — and `recent` is not among them. Calling `(recent)` as if it were a source is an unknown-source error that lists the ten known sources:

```text
Query error: Unknown source recent; known: active, all, current, dormant, edges, fields, node, query, schema, views.
```

The same holds for every other view name: `(plan)`, `(orphans)`, and `(busy)` are not sources. Reach a view only through `(query "name")`.

## Defining your own views

`define!` and `undefine!` are write forms — they record an event and are accepted only on the [`task_query_write`](/cairn/reference/tools#task-query-write) surface. The read surface refuses them:

```text
Query error: Mutations need the task_query_write surface; task_query is read-only.
```

### `define!`

```text
task_query_write  (define! "blocked-phases" (-> (active) (:where (= :status "blocked"))))
```

`(define! "name" Q)` validates `Q` read-only, records its source text as a `view.define` event, and returns `Q`'s tasks — so `define!` is interchangeable with the query it names. The view name must be a non-empty string. The query `Q` is evaluated read-only even on the write surface: you define over a selection, you do not mutate inside the definition. After the call, `(query "blocked-phases")` resolves on either surface.

### `undefine!`

```text
task_query_write  (undefine! "blocked-phases")
```

`(undefine! "name")` records a `view.undefine` event and returns no tasks. It removes the user view of that name. If a built-in of the same name exists, that built-in becomes visible again.

### Shadowing a built-in

A user view of a built-in's name shadows it in the one resolver. Define `orphans` over `(dormant)`, and `(query "orphans")` now returns settled tasks instead of edgeless ones; `undefine!` it and the built-in `(-> (all) (:where (= :edge-count 0)))` resolves again:

```text
task_query_write  (define! "orphans" (dormant))
task_query        (query "orphans")          # now resolves to your definition
task_query_write  (undefine! "orphans")
task_query        (query "orphans")          # the built-in is back
```

A view is a fold of `view.define`/`view.undefine` events, so a rebuild reconstructs your views exactly. See [events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile) for how the view vocabulary replays from the durable log.

## Listing every view

The `(views)` [source](/cairn/reference/tq-language#sources) produces every resolvable view as a queryable node-set. Each view node carries an `:origin` of `builtin` or `user` and a `:source` field holding its TQ text, so you can filter and project the catalogue with the algebra itself:

```text
task_query  (-> (views) (:where (= :origin "builtin")) (:ids))
```

```text
task_query  (-> (views) (:where (= :origin "user")) (:select :source))
```

A built-in shadowed by a user view of the same name reports once, as `user` — `(views)` reflects what resolves, not what ships.

## Related

- [TQ language](/cairn/reference/tq-language) — the sources, steps, and predicates every view is written in.
- [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) — why the frontier is the ready subset of a plan.
- [Tools](/cairn/reference/tools#task-query) — the `task_query` and `task_query_write` wire surface.


#### Edges, statuses, and fields


cairn's task graph is built from three closed vocabularies: the edge types that connect tasks, the statuses a task moves through, and the fields a query reads. Each is a small fixed set defined in one place in the source, so a tool, a query predicate, and a stored `CHECK` constraint can never disagree about what is legal. This page is the catalogue of those sets. It also covers the reflective sources — `(edges)`, `(fields)`, `(schema)`, `(views)` — that let a query read the catalogue back from the running store.

A field absent from the typed set is not an error: it is open metadata, set with [`task_set_metadata`](/cairn/reference/tools#task-set-metadata) and read as text. The closed sets below are the ones the language understands well enough to validate, classify, and type-check.

## Edge types

An edge connects two tasks. cairn stores edges two ways, and which way an edge is stored decides how a query traverses it.

A **lateral** edge lives in the `edges` table as an explicit row from a source task to a target task. A **structural** edge names the task fibration — a child's single parent — and folds into the child's `parent_task_id`, never the `edges` table. A query traverses a lateral edge by joining the `edges` table and a structural edge by walking the parent foreign key. The surface verb is the same ([`:follow`](/cairn/reference/tq-language#steps) / `:back`); the storage and the cardinality differ. The [task graph](/cairn/concepts/the-task-graph) page covers why the two are stored apart.

| Edge type | Class | Accepted by tools | Notes |
| --- | --- | --- | --- |
| `phase-of` | structural | yes | A phase belongs to its parent plan. Folded into the child's `parent_task_id`; a task has at most one parent. Default `edge_type` for [`task_fork`](/cairn/reference/tools#task-fork). |
| `depends-on` | lateral | yes | This task waits on its target. The ordering edge the frontier reads to decide readiness. |
| `related` | lateral | yes | A loose association with no ordering or ownership meaning. |
| `forked-from` | structural | no | A structural alias of the parent pointer that the traversal layer recognizes; in the store it is indistinguishable from `phase-of` (both fold into `parent_task_id`). It is never the edge a fork writes — a fork records `phase-of` by default — and never a value you pass as `edge_type`. |

### The tool-accepted vocabulary

[`task_link`](/cairn/reference/tools#task-link), [`task_sever`](/cairn/reference/tools#task-sever), and [`task_fork`](/cairn/reference/tools#task-fork) accept exactly three `edge_type` values: `phase-of`, `depends-on`, `related`. The check is case-insensitive — `Depends-On` is accepted and lowercased — and anything outside the set is refused before the write:

```text
"blocks" is not a valid edge type; expected one of phase-of, depends-on, related.
```

`blocks` and `blocked-by` look like they should work, and they read cleanly, but they are **not** part of the tool-accepted vocabulary. Internally cairn projects both onto `depends-on` while preserving the original name in a tag; that projection is an implementation detail of how a raw edge is normalized, not a value the tools advertise. Pass `depends-on` directly.

### Traversal classes

A query traversal classifies its edge keyword the same way before it runs, and an unrecognized edge is a structured error rather than a silently empty result — the edge is a property of the query, not of the data. The error carries the nearest known type, or the full list when nothing is close:

```text
Unknown edge type spawned-by; known: :depends-on, :forked-from, :phase-of, :related.
```

Note the traversal vocabulary is wider than the tool vocabulary: a query may traverse `forked-from` (and `phase-of`) because both name the structural fibration, even though only `phase-of` is a tool-accepted `edge_type`. The mutation steps [`:link!`](/cairn/reference/tq-language#steps) / `:unlink!` narrow back to the three tool-accepted edge_type values (`phase-of`, `depends-on`, `related`), mirroring the write tools.

## Statuses

Every task carries exactly one of five statuses. The set is closed and the SQLite `CHECK` constraint mirrors it, so an invalid status cannot reach the store.

| Status | Half | Meaning |
| --- | --- | --- |
| `open` | active | Created, not yet started. |
| `active` | active | In progress. |
| `blocked` | active | Stalled on an external condition; still live work. |
| `completed` | dormant | Finished and settled. |
| `abandoned` | dormant | Settled without completion; will not be resumed. |

The status enum partitions into an **active** half (`open`, `active`, `blocked`) and a **dormant** half (`completed`, `abandoned`). This is the partition the query sources read: [`(active)`](/cairn/reference/tq-language#sources) yields the live half and `(dormant)` yields the settled half. A plan's [frontier](/cairn/concepts/plans-phases-and-the-frontier) is then ready precisely when a phase is not dormant and all of its `depends-on` targets are. The partition is checked at load time against the full enum, so a status can never be live and settled at once, nor fall outside both halves.

[`task_update_status`](/cairn/reference/tools#task-update-status) lowercases its `status` argument and validates it against the set; anything else is refused:

```text
"done" is not a valid status; expected one of open, active, completed, abandoned, blocked.
```

`completed` and `abandoned` are not terminal in the data — a task is reopened by setting it `active` again, and the `reopen` flag on `task_update_status` is shorthand for exactly that. They are terminal only in the sense that the dormant half drops out of the active sources until you move it back.

## Fields

A field is a named, typed value a query reads off a task. Eleven fields are declared with a type; the type is what lets a numeric predicate refuse a textual field instead of comparing garbage, and a date predicate refuse anything but a clock.

| Field | Type | Source |
| --- | --- | --- |
| `slug` | text | The task's date-prefixed identifier; the node's own name. |
| `status` | text | The current status (see above). |
| `description` | text | The freeform description set at creation. |
| `depot` | text | The depot the task belongs to. |
| `parent` | text | The slug of the structural parent, or absent for a root. |
| `display-name` | text | A human-readable label; defaults to the slug. |
| `created-ts` | timestamp | Creation time, universal-time seconds. |
| `updated-ts` | timestamp | Last-touched time, universal-time seconds. |
| `status-ts` | timestamp | Time of the last status change. |
| `obs-count` | number | Number of observations recorded on the task. |
| `edge-count` | number | Number of edges incident to the task (lateral plus structural). |

The six **text** fields are `slug`, `status`, `description`, `depot`, `parent`, `display-name`. The two **number** fields are `obs-count` and `edge-count`. The three **timestamp** fields are `created-ts`, `updated-ts`, and `status-ts`.

The type drives predicate type-checking: `(> :obs-count 3)` compiles because `obs-count` is numeric, while `(> :status 1)` is rejected as ill-typed before it touches a row:

```lisp
(-> (active) (:where (> :status 1)))
```

```text
Query error: > needs a numeric field; :status is text.
```

A **timestamp** is CL universal-time — an integer count of seconds since the epoch `1900-01-01 UTC`. It is numeric-comparable, so it orders and compares as an integer (`(> :updated-ts 0)` is well-typed), and it is the only type the [date predicates](/cairn/reference/tq-language#dates-and-timestamps) `on` / `since` / `before` accept, letting `(on :updated-ts "2026-06-24")` express a calendar-day intent directly. When projected with [`:select`](/cairn/reference/tq-language#steps), a timestamp renders as its raw integer and its decoded UTC date — `updated-ts=3984388200 (2026-04-05)` — so the integer clock stays legible. The unit and epoch are not buried in this page: `(fields)` carries them on every timestamp field, below.

Any field not in this table is **open metadata** — a key written with `task_set_metadata` or the [`:set!`](/cairn/reference/tq-language#steps) step. It is read on demand and treated as text, so `(matches :owner "mika")` works against a metadata key cairn has never heard of; only the declared eleven get a numeric or timestamp type. The counts `obs-count` and `edge-count`, and any promoted metadata, are added by enrichment ([`:enrich`](/cairn/reference/tq-language#steps)), which a query inserts automatically when a step references a field that is not already local.

## Reflective sources

The three vocabularies above are queryable from the running store, not only documented here. Four sources synthesize the catalogue into the same node-set carrier that task queries produce, so every [TQ](/cairn/reference/tq-language) step composes over them for free. The names they yield are bare (never date-prefixed), so they never collide with a real task. Each source is generated from the registry the interpreter dispatches on, so the readout cannot drift from behavior.

| Source | Yields | Per-node props |
| --- | --- | --- |
| `(edges)` | The edge vocabulary, one node per type | `:class` — `structural` or `lateral` |
| `(fields)` | The declared fields plus any live metadata keys | `:origin` (`declared` / `metadata`), `:type` (`text` / `number` / `timestamp`), and `:unit` + `:epoch` on a timestamp |
| `(views)` | The named [views](/cairn/reference/views), built-in and user | `:origin` (`builtin` / `user`), `:source` (TQ text) |
| `(schema)` | The combinator grammar: every source, step, predicate, and write form | `:category` (`source` / `step` / `predicate` / `write`), `:kind` (on steps and predicates), `:signature` (on steps and predicates), `:doc` |

`(edges)` lists all four known edge types — the three tool-accepted plus `forked-from` — because the traversal surface understands all four. To recover only the tool-accepted lateral set, filter on the class:

```lisp
(-> (edges) (:where (= :class "lateral")) (:ids))
```

```text
2 tasks:
- depends-on
- related
```

The same algebra reads the fields. List every numeric field, or every timestamp field:

```lisp
(-> (fields) (:where (= :type "number")) (:ids))
```

```text
2 tasks:
- edge-count
- obs-count
```

```lisp
(-> (fields) (:where (= :type "timestamp")) (:ids))
```

```text
3 tasks:
- created-ts
- status-ts
- updated-ts
```

The clock is self-describing: project a timestamp field's `:unit` and `:epoch` instead of reverse-engineering them from raw values.

```lisp
(-> (fields) (:where (= :type "timestamp")) (:select :type :unit :epoch))
```

```text
3 tasks:
- created-ts  type=timestamp  unit=seconds  epoch=1900-01-01 UTC (CL universal-time)
- status-ts  type=timestamp  unit=seconds  epoch=1900-01-01 UTC (CL universal-time)
- updated-ts  type=timestamp  unit=seconds  epoch=1900-01-01 UTC (CL universal-time)
```

`(fields)` also lists the **open metadata** keys live in the store, each tagged `:origin "metadata"` (declared fields are `:origin "declared"`), so a query discovers the metadata vocabulary it can filter and project without reading any code — `(-> (fields) (:where (= :origin "metadata")) (:ids))`.

`(schema)` describes the grammar itself, including the reflective sources — it lists `edges`, `fields`, `views`, and `schema` among its source nodes, and it lists the predicate vocabulary (each predicate tagged `:category "predicate"` with its `:kind` and `:signature`) alongside the sources and steps. That makes the language self-documenting: an agent that has the `(schema)` source can discover the rest of the surface without leaving the query, which is the same loop these docs serve for a human reader. There is no `(statuses)` source; the status partition is documented above and surfaces through `(active)` / `(dormant)` rather than a reflective list.

## Related

- [Tools](/cairn/reference/tools) — the writers that consume these enums: `task_link`, `task_fork`, `task_update_status`, `task_set_metadata`.
- [The TQ language](/cairn/reference/tq-language) — the sources, steps, and predicates that read fields and traverse edges.
- [Views](/cairn/reference/views) — the built-in named queries phrased over these vocabularies.
- [The task graph](/cairn/concepts/the-task-graph) — why structural and lateral edges are stored differently.
- [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) — how `phase-of`, `depends-on`, and the status partition combine into readiness.


### Commands & Serving

#### Slash commands


cairn registers six slash commands when it loads under a kli host: `/observe`, `/handoff`, `/task`, `/tasks`, `/workon`, and `/where`. They are the hand-typed surface over the same task graph the [MCP tools](/cairn/reference/tools) reach over the wire: a line you type at the prompt instead of a tool the model calls. Two of them, `/observe` and `/handoff`, do something an agent can also do for itself. The other four are operator conveniences the model never sees.

The commands depend on a host that offers a command surface. cairn registers them only against a `:commands/v1` provider. A headless run with no such provider registers nothing, so there are no slash commands when cairn is served straight over [`kli mcp-serve cairn`](/cairn/cli/mcp-serve). For that path, use the tools directly.

A command's first word names it; everything typed after the first word is one free-text tail passed to the runner. `/where` takes no tail.

## The six commands

| Command | Syntax | Effect | Model-visible | MCP analogue |
| --- | --- | --- | --- | --- |
| `/observe` | `/observe <text>` | Record an observation on the current task. | yes | [`observe`](/cairn/reference/tools#observe) |
| `/handoff` | `/handoff [guidance]` | Compose and record a resumable handoff for the current task. | yes | [`handoff`](/cairn/reference/tools#handoff) (the turn authors the body; the tool only scaffolds) |
| `/task` | `/task [id]` | Show the current task, or select one by id. | no | partial — pointer read/set, like [`task_bootstrap`](/cairn/reference/tools#task-bootstrap) without the open-handoffs readout |
| `/tasks` | `/tasks [query]` | List recent tasks, or run a task-graph query. | no | [`task_query`](/cairn/reference/tools#task-query) |
| `/workon` | `/workon [id]` | Select a task and seed a re-entry turn. | no | none |
| `/where` | `/where` | Show the resolved database path, project, and how it was resolved. | no | none |

**Model visibility** is the `:model-visible` metadata on each command. `/observe` and `/handoff` carry no such metadata, so their effect rides in the conversation the model reads. `/task`, `/tasks`, `/workon`, and `/where` are registered with `:model-visible nil`: they run and print to you, but their echo is hidden from the model. That split lets an operator inspect or steer the graph without spending the readout as context. See [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities) for the boundary the operator surfaces sit behind.

A command and its MCP analogue are not the same call. `/observe` invokes the `observe` tool unchanged. `/handoff` and `/workon` do work the tools cannot: `/handoff` drives an authoring turn and `/workon` injects a deterministic block, and both patch the transcript. The other operator surfaces — `/task`, `/tasks`, and `/where` — have their own output shapes. The sections below give each command's exact behavior and the verbatim text it prints. In the example blocks, a leading `>` marks the line you type; every other line is what cairn prints back.

## /observe

Record an observation on the current task.

Syntax: `/observe <text>`

`/observe` is a thin wrapper over the [`observe`](/cairn/reference/tools#observe) tool: it passes your tail as the `text` argument, invokes the tool, and returns the tool's result unchanged. The observation lands on the current task; it does not move the current-task pointer. On success the result is the tool's own line:

```text
> /observe rotation test still red at the 30-day boundary
Observed on 2026-06-22-auth-rotation.
```

With no tail, the command fails before reaching the tool:

```text
> /observe
Usage: /observe <text>
```

`/observe` is model-visible, so the observation and its confirmation enter the conversation. From a non-kli MCP client, call the [`observe`](/cairn/reference/tools#observe) tool directly — same effect, same return text.

## /handoff

Compose and record a resumable handoff for the current task.

Syntax: `/handoff [guidance]`

`/handoff` is richer than the [`handoff`](/cairn/reference/tools#handoff) tool, but the command itself does little. Its only deterministic act is to start one interactive authoring turn and reply `Composing a handoff...`. The session is then handed an instruction to compose a one-line summary, call the `handoff` tool to scaffold and record the document, read the scaffold back, and overwrite it with a rich body. Those steps are what the turn is told to do, not guarantees the command performs. The tool, by contrast, only scaffolds a deterministic skeleton and records the event; it never writes prose. Any tail you pass is guidance threaded into that authoring instruction:

```text
> /handoff
Composing a handoff...

> /handoff focus on the rotation regression; the refresh path is done
Composing a handoff...
```

Because it drives an authoring turn, `/handoff` needs an interactive session. Headless, with no agent-session service, it declines and writes nothing:

```text
Handoff authoring needs an interactive session.
```

From a non-kli MCP client, the [`handoff`](/cairn/reference/tools#handoff) tool is the right call: it scaffolds the skeleton and you supply the body yourself.

## /task

Show the current task, or select one by id.

Syntax: `/task [id]`

With no tail, `/task` prints the current task's computed state: its status, description, parent, children, edges, metadata, and recent observations. With no current task set, it says so and offers recent slugs:

```text
> /task
No current task. Recent: 2026-06-22-auth-rotation, 2026-06-21-search-index
```

With a tail, `/task <id>` sets the current-task pointer to that slug and prints the task's state. An unknown id leaves the pointer untouched and lists recent slugs instead:

```text
> /task 2026-06-22-auth-rotation
Current task set to 2026-06-22-auth-rotation.
2026-06-22-auth-rotation  [active]
  …computed task state…

> /task no-such-task
No task no-such-task. Recent: 2026-06-22-auth-rotation, 2026-06-21-search-index
```

`/task` is hidden from the model: it reads or moves the pointer without entering the conversation. The model's own way to orient and adopt a task is [`task_bootstrap`](/cairn/reference/tools#task-bootstrap), which adds open handoffs; `/task` is the bare pointer surface. See [The current task pointer](/cairn/concepts/the-current-task-pointer).

## /tasks

List recent tasks, or run a task-graph query.

Syntax: `/tasks [query]`

`/tasks` runs the [TQ query language](/cairn/reference/tq-language) against the live graph and renders the result. With no tail, it runs the built-in `recent` view. With a tail, it interprets your tail as a TQ program, read with `*read-eval*` disabled so the form is walked and never evaluated. The query runs scoped to the current task, so current-relative forms like the `(current)` source and the current-scoped views `(query "plan")` and `(query "plan-frontier")` resolve against the pointer.

```text
> /tasks
…the recent view…

> /tasks (-> (query "plan-frontier") (:ids))
…ready phases…
```

Three failure channels carry the underlying message verbatim, which is what lets you correct the query in place:

```text
Parse error: <message>
Query error: <message>
The query could not be executed.
```

`/tasks` is hidden from the model. It is read-only: it runs the read query engine, so it does not accept TQ's `!`-forms — the write source `define!` and the mutation steps such as `:set-status!`. To define a view or mutate the graph through TQ, use the [`task_query_write`](/cairn/reference/tools#task-query-write) tool.

## /workon

Select a task and seed a re-entry turn.

Syntax: `/workon [id]`

`/workon` has no MCP analogue. It does something only a host with a transcript can. It selects the target task — your tail, or the single most recent task when you pass none — sets the current-task pointer, records a `resume` event on the task, and injects a resume block straight into the durable transcript so the model re-enters the work with state in hand. The injected block opens with a fixed line, then the task's computed state and its open handoffs:

```text
Following the cairns - resuming 2026-06-22-auth-rotation.

2026-06-22-auth-rotation  [active]
  …computed task state…
  …open handoffs, newest first…
```

The command itself replies with a short confirmation, hidden from the model:

```text
Working on 2026-06-22-auth-rotation.
```

When there is no task to work on — no tail and no recent task — it says so and writes nothing:

```text
No task to work on.
```

An unknown id lists recent slugs and leaves the pointer untouched, the same shape `/task` uses for a miss. The transcript injection is a one-shot context patch. Headless, or when no agent context is bound, the selection and the event still happen but no block is written. Under a kli host, `/workon` is the operator counterpart to the model calling [`task_bootstrap`](/cairn/reference/tools#task-bootstrap) on re-entry.

## /where

Show the resolved database path, project, and how it was resolved.

Syntax: `/where`

`/where` takes no tail and has no MCP analogue. It reports which store the session is talking to and how that store was chosen. The output is a fixed template:

```text
Database: /…/cairn.db
Resolved by: project
Project: proj-1a2b3c4d5e6f (auth-service)
Source: kli-dir
```

`Resolved by` is the precedence step that won — `override`, `db-path`, `data-dir`, `project`, or `global`, highest first. `Project` is the content-addressed project id and its display name. `Source` is how the project root was found: `setting`, `kli-dir`, `repo`, or `scratch`. When the session falls back to the reserved scratch project, a final line is appended:

```text
Scratch: yes
```

`/where` is hidden from the model. See [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile) for how the store behind that path is built and rebuilt.

## Related

- [Tools](/cairn/reference/tools) — the fourteen MCP tools these commands sit over, with full parameter tables and return text.
- [Serve cairn over MCP](/cairn/cli/mcp-serve) — the headless surface, where the tools travel but the slash commands do not.
- [The current task pointer](/cairn/concepts/the-current-task-pointer) — what `/task` and `/workon` move, and the adopt-when-unset rule.
- [TQ language](/cairn/reference/tq-language) — the query language `/tasks` runs, including why it refuses `!`-forms.
- [`handoff` tool](/cairn/reference/tools#handoff) — the deterministic scaffold `/handoff` authors on top of.


#### Serving over MCP


`kli mcp-serve cairn` runs a kli built with the cairn extension as a Model Context Protocol server over stdio. The process exposes one extension's surface to a single client: cairn's fourteen tools, seven prompts, and seven readable resources. A client connected this way plans, observes, queries, and resumes against the same durable task graph it would reach inside kli, without adopting kli as its agent.

This page documents the command, its client configuration, and the exact surface it carries. For the install paths behind the `kli` binary, see [Install cairn](/cairn/get-started/install-cairn).

## The command

```text
kli mcp-serve cairn
```

The invocation is `kli mcp-serve <extension>`, where `<extension>` is the name of an extension built into the kli image — here, `cairn`. The process speaks MCP over stdio, reading requests on stdin and writing responses on stdout — the transport every MCP client uses to launch a server. On launch it prints no banner to stdout; stdout carries JSON-RPC only, every diagnostic goes to stderr, and the process blocks waiting for the first request — a clean start goes quiet rather than printing anything. It serves until the client closes the connection.

| Element | Value | Notes |
| --- | --- | --- |
| Binary | `kli` | The same `kli` you install the extension into. See [Install cairn](/cairn/get-started/install-cairn). |
| Subcommand | `mcp-serve` | Runs the named extensions as an MCP server. |
| Argument | `cairn` | The extension to expose. One process serves only the extensions you name. |
| Transport | stdio | Requests on stdin, responses on stdout; diagnostics on stderr. |
| Scope | one client | One `mcp-serve` process serves a single client. |

The working directory the client launches `kli` in selects the project whose task graph cairn opens. There is no separate database flag; the project is the directory.

## Client configuration

Claude Code, Claude Desktop, and Cursor read the same `mcpServers` block. The canonical entry is:

```json
{
  "mcpServers": {
    "cairn": {
      "command": "kli",
      "args": ["mcp-serve", "cairn"]
    }
  }
}
```

| Field | Value | Meaning |
| --- | --- | --- |
| `command` | `kli` | The binary the client spawns. |
| `args` | `["mcp-serve", "cairn"]` | The subcommand and the extension to expose. |

The client spawns this process, lists its tools, and routes tool calls to it, picking up a newly added entry on its next restart.

## Exposed surface

`mcp-serve` exposes one extension's surface and nothing else. Naming `cairn` gives the client cairn's surface alone; no other extension's tools, prompts, or resources travel on the same process. The surface is the same regardless of which client connects.

### Tools

The fourteen cairn tools appear as MCP tools, each gated by the capability it declares. The full per-tool reference — parameters, return text, and semantics — is in [Tools](/cairn/reference/tools).

| Capability | Tools |
| --- | --- |
| `:cairn/observe` | `observe` |
| `:cairn/write` | `task_create`, `task_fork`, `task_link`, `task_sever`, `task_set_metadata`, `task_update_status`, `handoff`, `task_query_write` |
| `:cairn/read` | `task_search`, `task_get`, `timeline`, `task_query`, `task_bootstrap` |

The serve subject holds exactly the capabilities its exposed tools declare, so the `:cairn/read` / `:cairn/write` / `:cairn/observe` split applies over MCP just as it does in kli. The capability each tool declares is the gate; the tool name is not. A read-only client never reaches `task_query_write` or any other write tool. See [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities).

### Prompts

Seven MCP prompts travel on the process: the six cairn-method workflow prompts plus the `cairn-method` skill, which the serve loop lists as a prompt as well as a resource. They carry the documentarian-and-TDD discipline of the cairn-method into the client's prompt picker.

| Prompt | Stage of the loop |
| --- | --- |
| `research` | Read the ground before changing it. |
| `plan` | Structure the work as a graph of phases. |
| `implement` | Do one phase with the discipline it asks for. |
| `validate` | Check the phase against its acceptance. |
| `handoff` | Write the resumable summary. |
| `resume` | Read the stones and pick the work back up. |
| `cairn-method` | The whole method, expanded as a prompt. |

The six workflow prompts are the named loop; see [The cairn-method](/cairn/concepts/the-cairn-method) for how they compose. The seventh, `cairn-method`, is the bundled skill surfaced in the prompt list.

### Resources

Every prompt and the skill are also served as readable MCP resources — seven in all, each a markdown body the model reads straight off the prebuilt prompt or skill. The workflow prompts are advertised at `cairn://prompts/<name>` (for example `cairn://prompts/research`), and the skill at `cairn://skills/cairn-method`; the scheme is the extension name. A client that reads the skill resource gets the method in full — the bootstrap-observe-handoff heartbeat and the discipline wrapped around it — as text the model can consult mid-task.

## What stays kli-only

Three things kli provides do not travel over the tool protocol, because kli supplies them as the host rather than as MCP surface. A plain MCP client does not get them.

- **Slash commands.** `/observe`, `/handoff`, `/task`, `/tasks`, `/workon`, and `/where` are registered under a kli command provider, not as MCP tools, so an MCP client cannot invoke them. See [Slash commands](/cairn/cli/slash-commands).
- **Per-turn context injection.** Inside kli, the current task's live state — its status and its open handoffs — is folded into the model's view on every turn. Over MCP the client calls `task_bootstrap` itself to stay oriented.
- **Compaction folding.** When kli compacts a long conversation, the observations and handoffs from the dropped span are folded into the summary so the durable markers survive the cut. An MCP client manages its own context window, and its compaction does not know about those markers.

The data surface is identical either way: writes append events and fold into the same queryable projection no matter which client made them, so a graph built over MCP reads back exactly as one built inside kli.

## What a connected server reports

A connected server advertises the fourteen tools listed above, among them `task_bootstrap`, `task_create`, `observe`, `task_query`, and `task_search`.

`task_bootstrap` reads the live graph. In a fresh project with no current task set, it reports that there is nothing to orient on rather than failing:

```text
No task to bootstrap; pass task_id or select a task first.
```

That message means the tool surface is wired and the project's graph is empty — the state a first session starts from. In a project that already has tasks, `task_bootstrap` returns state, neighbors, open handoffs, and recent observations. Either result means the server is connected and reading the right project.

## Related

- [Install cairn](/cairn/get-started/install-cairn) — the declarative and runtime install ledgers behind the `kli` binary.
- [Tools](/cairn/reference/tools) — the full per-tool reference for the fourteen exposed tools.
- [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities) — the capability boundary that carries over MCP.
- [Slash commands](/cairn/cli/slash-commands) — the kli-host steering surface that does not travel over the protocol.


## Additional pages (including unstable internal surfaces)

### Commands & Serving


cairn reaches the world outside the [MCP tools](/cairn/reference/tools) through two surfaces, one for each reader: the slash commands a person types at a kli prompt, and the `kli mcp-serve cairn` server that carries the tools to any MCP client an agent runs in.

## Pages

- [Slash commands](/cairn/cli/slash-commands) — the six commands cairn registers under a kli host (`/observe`, `/handoff`, `/task`, `/tasks`, `/workon`, `/where`), with syntax, model visibility, and how each relates to the MCP tools (`/workon` and `/where` have none).
- [Serving over MCP](/cairn/cli/mcp-serve) — `kli mcp-serve cairn`, the stdio invocation, the `mcpServers` block clients read, and the tools, prompts, and resources it carries.

The two surfaces share one task graph and read back identically; they differ only in the conveniences the kli host adds on top. Both sit behind one capability boundary; see [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities).


### Concepts


Start with the one-paragraph definition in [What cairn is](/cairn/concepts/what-cairn-is);
from there the section moves out to the graph and the three nouns you write, then
to how plans and the current pointer move over that graph, and finally to the
event log and capability boundary underneath it all.

These pages are for the person who wants to understand how cairn works before
trusting it with a plan; they explain, they do not instruct. When you want to run
the loop yourself, go to the [Quickstart](/cairn/get-started); for exact values, go
to [Reference](/cairn/reference).

- [What cairn is](/cairn/concepts/what-cairn-is) — continuity for agents, the
  stones that name a route, and why the plan lives outside the conversation.
- [The task graph](/cairn/concepts/the-task-graph) — the two stores: a typed-edge
  graph of slug-addressed tasks, and a full-text index of observations.
- [Tasks, observations, and handoffs](/cairn/concepts/tasks-observations-handoffs) —
  the three nouns you write, and the events each one records.
- [Plans, phases, and the frontier](/cairn/concepts/plans-phases-and-the-frontier) —
  why a plan is a task DAG, not a markdown file, and how the frontier finds ready work.
- [The current-task pointer](/cairn/concepts/the-current-task-pointer) — the
  per-session slug cairn resolves slugless writes against, and what moves it.
- [Events, projection, and reconcile](/cairn/concepts/events-projection-and-reconcile) —
  why every write is an event in a durable log, and the database a rebuildable cache.
- [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities) —
  how the read/write/observe boundary is drawn by capability, not by tool name.
- [The cairn-method](/cairn/concepts/the-cairn-method) — the loop, the heartbeat
  writes, and the discipline an agent uses to leave work a next session can resume.

The order is dependency order: each page names a thing the pages below it lean on,
so reading top to bottom never asks you to take a term on faith.


### Quickstart


This is the tutorial track for a person setting cairn up and running it through an agent: the linear path from an empty install to a plan you can resume from a clean session. cairn keeps that plan in a durable task graph outside the conversation, so a context reset reloads it instead of losing it.

Read these in order. Each page builds on the one before it.

- [Install cairn](/cairn/get-started/install-cairn) — add cairn to kli declaratively or at runtime, serve it to any MCP client, and confirm the tool surface is live.
- [Your first cairn session](/cairn/get-started/your-first-cairn-session) — run the bootstrap-observe-handoff loop once, end to end, and learn what each returned string means.
- [Plan and resume](/cairn/get-started/plan-and-resume) — fork phases, order them with `depends-on`, ask the frontier what is ready, complete a phase, and bootstrap back into the plan.

When you have run the loop and want to understand why the graph behaves as it does, [Concepts](/cairn/concepts) explains the task graph, the current pointer, the event log, and the capability boundary. The full surface lives in the [Reference](/cairn/reference): the fourteen MCP tools, the TQ query language, the built-in views, and the closed edge, status, and field enums.


### Reference


This section is the precise spec an agent executes against — the catalogue of cairn's wire surface. cairn provides fourteen MCP tools and one query language, and everything an agent can ask or change goes through them. Because an agent consumes it directly, the site serves these pages as Markdown and an llms.txt index as well as HTML; each tool, operator, view, and enum has a stable anchor, every returned and error string is copied from source, and the pages are written to be read out of order and deep-linked.

Every call carries a capability gate in its metadata — `:cairn/observe`, `:cairn/write`, or `:cairn/read` — and this section tells you which gate each tool sits behind. [Reads, writes, and capabilities](/cairn/concepts/reads-writes-and-capabilities) explains why the boundary is drawn at the capability rather than the tool name.

## Pages

- [MCP tools](/cairn/reference/tools) — the fourteen tools (one observe, eight writes, five reads), each with its parameters, capability gate, returned text, and verbatim errors.
- [The TQ query language](/cairn/reference/tq-language) — TQ's sources, pipeline steps, predicates, set algebra, reflection, and the one dynamic gate that separates [`task_query`](/cairn/reference/tools#task-query) from [`task_query_write`](/cairn/reference/tools#task-query-write).
- [Built-in and user-defined views](/cairn/reference/views) — the ten named views cairn ships, each with its exact TQ source text, and how a user view shadows a built-in until you `(undefine!)` it.
- [Edges, statuses, and fields](/cairn/reference/edges-statuses-and-fields) — the closed vocabularies: three edge types, five statuses, eleven typed fields, and the reflective sources that read them back from the store.

For the command-line surface — the six slash commands under a kli host and serving cairn over [`kli mcp-serve cairn`](/cairn/cli/mcp-serve) — see [Commands & Serving](/cairn/cli). For what the nouns mean before you call them, start at [Concepts](/cairn/concepts).


# kli

## Learn

### Get started

#### Teaching kli Your Project


By default kli knows your code only by reading it. Anything not in the code — the test
command, the project's name, a convention the team keeps — kli has to ask about or
infer. An `AGENTS.md` at the repository root fixes that: kli reads it into the system
prompt at startup, before your first message reaches the model.

## Write an AGENTS.md

Put plain, true facts in `AGENTS.md` at the repo root — the things you would tell a new
contributor on day one:

```md
# Acme Parser

A command-line tool that parses Acme log files into JSON.

## Commands

- Run the test suite with `make test`.
- Build the binary with `make build`.

## Conventions

- Source lives under `src/`. Tests mirror it under `tests/`.
- We use tabs, not spaces.
```

kli reads this verbatim, so a wrong fact becomes a wrong assumption later. The filename
is exact: `AGENTS.md`.

## Pick it up

A running session has already built its system prompt, so it will not see a file you
just wrote. Start a fresh session from the same directory and the new one reads
`AGENTS.md` as it boots. Ask something only the file knows:

```
How do I run the tests in this project?
```

The answer comes back as `make test`, drawn from the file rather than from searching
the tree — kli already had it before you typed.

## Where context comes from

`AGENTS.md` is the cheapest lever, but it is one input among several the system prompt
is assembled from. [The agent loop](/kli/concepts/the-agent-loop) and [Context and the
system prompt](/kli/concepts/context-and-the-system-prompt) show the rest, and [Inspect
and edit context](/kli/guides/inspect-and-edit-context) shows how to see and change what
the model is actually working from.


### Guides

#### Choose and Switch Models


kli runs against whichever model you select. You change that model in the running session with a command, and you make a choice stick across sessions by writing it into `settings.json`. This page covers both.

A model is named by its provider and id together, written `provider/model` (for example `anthropic/claude-opus-4-8`). For the full list of providers, see [Models & Providers](/kli/models/providers-and-transports). Before a provider's models appear, that provider needs a credential. See [Connect a Provider](/kli/guides/connect-a-provider) for that step.

## See which models you can use

Run `/models` to list every model you are authenticated for:

```
/models
```

Each line shows the `provider/model` reference and the model's display name. A line marked with `*` is the current selection. A line can also include a compact options marker, for example `options reasoning-effort`, naming the semantic options that model accepts. Pass a word to filter the list by provider id, model id, display name, or full reference:

```
/models opus
```

When nothing matches, the command says so rather than listing everything.

To see the providers themselves and their authentication state, run `/providers`:

```
/providers
```

Each line gives the provider id, its auth status (`yes` when a credential is available, `no` when it is missing, `local` when the provider needs none), and the count of models it offers. A provider with `auth no` registers no usable models, so its models will not appear in `/models`.

## Switch the model for this session

Give `/model` a reference to switch to it:

```
/model anthropic/claude-opus-4-8
```

The reference does not have to be exact. If the text you type matches exactly one available model by id or substring, kli selects it; you can drop the provider when the model id alone is unambiguous:

```
/model claude-opus-4-8
```

If your text matches more than one model, kli lists the candidates and changes nothing, so you can retype a longer reference. If it matches none, kli says so.

In the terminal UI, bare `/model` opens a menu over the available models with the current one marked. Running `/model` bare without the UI prints the current selection followed by the model list.

After a successful switch, kli prints a `Model:` system line confirming the new selection. The change applies from the next turn; it does not alter any earlier messages in the session.

## Set reasoning effort

`reasoning-effort` is the semantic option behind model thinking. Models whose `/models` line includes `options reasoning-effort` accept the levels `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Set one with `/thinking`:

```
/thinking high
```

Run `/thinking` with no argument to print the current level. In the terminal UI, bare `/thinking` opens a menu over the levels when the current model supports `reasoning-effort`. `/thinking off` turns reasoning off for the current model.

You can also set the level in the same step as the model by appending it to a `/model` reference, separated by a space:

```
/model anthropic/claude-opus-4-8 high
```

Setting a non-`off` level on a model that does not support `reasoning-effort` is an error, and so is setting a level when no model is selected. Other semantic options are configured up front in `providers.json` model schemas and `settings.json` `defaultOptions`; `/thinking` is the interactive command for the option users change most often.

## Make a choice persist

The commands above change only the running session. To start every session on a chosen model and option set, write the choice into `settings.json`:

```json
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-opus-4-8",
  "defaultOptions": {
    "reasoning-effort": "high"
  }
}
```

`defaultProvider` and `defaultModel` take effect together: kli looks up that exact model at startup and selects it. `defaultOptions` is an object keyed by semantic option id. Each option must be supported by the selected model; unsupported options and invalid values are ignored with warnings rather than failing startup.

Set it in `settings.json` (global `~/.config/kli/settings.json`, project `<repo>/.kli/settings.json`; project wins) — see [Settings](/kli/config/settings). Put your usual default in the global file, then override it per repository when a particular codebase wants a different model or option set. A `/model` or `/thinking` command run during a session always takes precedence over these defaults for the rest of that session.

For the full set of `settings.json` keys, see the [settings reference](/kli/config/settings). For where the model selection sits in a turn, see [The Agent Loop](/kli/concepts/the-agent-loop).


#### Connect a Provider


A model provider needs a credential before kli can call it. The `/auth` command registers that credential and reports whether the provider is now available. There are three ways to supply one: point at an environment variable, store a static API key, or run an OAuth login. You run these from inside a kli session.

To see what is already registered, run `/auth` with no arguments. It lists each provider and reference and whether the credential resolves.

## Reference an environment variable

Use this when the key already lives in your shell environment and you do not want kli to keep a copy.

```
/auth env <provider> <ENV_VAR>
```

For example:

```
/auth env anthropic ANTHROPIC_API_KEY
```

kli registers a reference to the named variable and reads it fresh on every request. The value is never copied into kli's credential file, so it lives only as long as the variable does in the process environment. If the variable is unset, the provider reports as unavailable until you set it.

## Store a static API key

Use this when you have a key string and want kli to keep it.

```
/auth key <provider> <KEY>
```

For example:

```
/auth key openai sk-...
```

The key is written to the credential file and reused on later runs. kli does not echo the key back in its reply; it confirms only the provider and whether the credential is available.

## Run an OAuth login

Some providers authenticate with OAuth instead of a key. kli uses PKCE and never runs a local callback server: it gives you a URL, you authorize in a browser, then you paste the result back.

Start the login:

```
/auth login <provider>
```

For example:

```
/auth login openai-codex
```

If a stored OAuth credential already exists for that provider, kli restores it and reports the provider as available. Otherwise it prints an authorization URL. Open the URL, complete the sign-in, and the provider's page hands you an authorization code (or a redirect URL containing one).

Paste that back to finish:

```
/auth code <pasted code or redirect URL>
```

`/auth code` accepts the bare code, a `code#state` pair, a `code=...` query string, or the full redirect URL; kli pulls the code out of whichever form you paste. It exchanges the code for tokens, stores them, and reports the provider as available. The pasted input is never echoed.

`/auth code` completes the single pending login. Run one `/auth login` at a time: if more than one is in flight, kli asks you to finish them individually before it will accept a code.

## Remove a credential

```
/auth logout <provider>
```

This deletes the provider's stored credential from the credential file. An environment-variable reference is not stored, so there is nothing to delete for one; unset the variable instead.

## Where credentials are stored

Stored API keys and OAuth tokens persist to `~/.config/kli/credentials.json`, written with file mode `0600` (owner read/write only). Environment-variable references are not written there — they resolve from the live environment each time. `/auth` itself is hidden from the model, because its argument can carry a raw key.

For the providers kli ships and which auth mode each uses, see [Models & Providers](/kli/models/providers-and-transports). Once a provider authenticates, its models become selectable. See [Switch Models](/kli/guides/choose-and-switch-models) to choose one, and [Settings Reference](/kli/config/settings) for configuration that is set up front rather than in a session.


#### Add a Custom OpenAI-Compatible Provider


The `compatible` provider reads `~/.config/kli/providers.json` and registers one entry per OpenAI-compatible endpoint you define there — a local server (Ollama, llama.cpp, vLLM), a self-hosted gateway, or any third-party service that speaks the OpenAI Chat Completions or Responses wire format. For the rest of kli's providers, see [Models & Providers](/kli/models/providers-and-transports).

This guide writes that file and connects the result.

## Create providers.json

Create `~/.config/kli/providers.json`. The file is a single JSON object keyed by provider id. Each key becomes a provider name you select against; each value describes one endpoint.

A minimal entry for a local Chat Completions server:

```json
{
  "local-llama": {
    "base-url": "http://localhost:11434/v1",
    "key-env": "LOCAL_LLAMA_KEY",
    "models": [
      { "id": "llama3.1:70b", "context-window": 131072 }
    ]
  }
}
```

The key `local-llama` is the provider id. kli sends requests to the endpoint built from `base-url`, and reads the API key from the environment variable named in `key-env`.

## Set the request URL

kli builds the request URL from `base-url` plus a fixed path determined by `api`. Set `base-url` to the root your server exposes, with no trailing path component:

- For the Chat Completions API (the default), kli appends `/chat/completions`. A `base-url` of `http://localhost:11434/v1` yields `http://localhost:11434/v1/chat/completions`.
- For the Responses API, kli appends `/responses`. Set `url-path` to append a different segment instead.

Any trailing slash on `base-url` is trimmed before the path is joined.

## Choose the wire format

Set `api` to match the format your endpoint speaks. The default is `openai-completions`.

```json
{
  "my-gateway": {
    "base-url": "https://gateway.example.net",
    "api": "openai-responses",
    "url-path": "/v1/responses",
    "key-env": "GATEWAY_KEY",
    "models": [
      { "id": "gpt-oss-120b", "context-window": 131072 }
    ]
  }
}
```

The entry above sends requests to `https://gateway.example.net/v1/responses`: kli trims any trailing slash from `base-url` and joins `url-path` onto it. `url-path` only takes effect when `api` is `openai-responses`. With `openai-completions` it is ignored and the path is always `/chat/completions`.

A value of `api` other than `openai-completions` or `openai-responses` is an error and the entry fails to load.

## Provide the API key

A `compatible` entry never holds a secret. The `key-env` field names an environment variable; kli reads the key from that variable's value at request time. Set it in the shell or service unit that launches kli:

```sh
export LOCAL_LLAMA_KEY="sk-..."
```

For a local server that ignores authentication, name an env var and set it to any non-empty placeholder.

If you omit `key-env`, the entry registers with no environment credential. You can then persist a static key for that provider id from inside a session:

```
/auth key local-llama sk-...
```

The static key is stored and reused; it is not echoed back.

## List the models

Each entry needs a `models` array. An entry with an empty array registers the provider but offers nothing to select. Each model is an object:

```json
{ "id": "llama3.1:70b", "name": "Llama 3.1 70B", "context-window": 131072 }
```

- `id` — the model id sent to the endpoint, and the id you select against. Required.
- `name` — the display label. Defaults to `id` when omitted.
- `context-window` — the context size in tokens, used for budgeting.
- `options` — optional semantic model option schemas for this model. See [Add semantic options](#add-semantic-options).

For where this file sits among kli's config paths, see [Files and paths](/kli/config/files-and-paths).

## Add semantic options

Semantic options describe model capabilities in kli terms. They are not raw request fields. The selected transport lowers them to the wire shape it supports: for example, `reasoning-effort` becomes OpenAI `reasoning_effort` or Responses `reasoning.effort`, while Anthropic maps it to its `thinking` request object.

Add an `options` object at the provider level to give every model the same option schema:

```json
{
  "my-gateway": {
    "base-url": "https://gateway.example.net/v1",
    "api": "openai-responses",
    "key-env": "GATEWAY_KEY",
    "options": {
      "reasoning-effort": {
        "values": ["off", "low", "medium", "high"],
        "default": "off"
      },
      "text-verbosity": {
        "values": ["low", "medium", "high"]
      }
    },
    "models": [
      { "id": "fast-model", "context-window": 65536 },
      {
        "id": "plain-model",
        "context-window": 32768,
        "options": { "reasoning-effort": null }
      }
    ]
  }
}
```

A model-level `options` object merges over the provider-level object. Re-declaring an option replaces that option's schema for just that model. Setting an inherited option to `null` removes it from that model.

Each option schema may carry:

| Field | Type | Effect |
| --- | --- | --- |
| `type` | string | Option type. Usually omitted for built-in semantic options, whose type is known globally. |
| `values` | array | Admitted enum values. Required for enum options. |
| `default` | scalar | Default value when the model is selected without an explicit value. |
| `min` | number | Minimum for numeric option types. |
| `max` | number | Maximum for numeric option types. |

The schema type can be `enum`, `boolean`, `integer`, `number`, or `string`. Built-in semantic option ids are `reasoning-effort`, `text-verbosity`, `service-tier`, and `prompt-cache-retention`; their enum universes and transport lowering are documented in [Providers and Transports](/kli/models/providers-and-transports#semantic-options).

## Add extra headers

To send headers on every request to an endpoint — a routing tag, an org id, a gateway token — add a `headers` object. Each name and value is appended to the outgoing request, alongside the `Authorization: Bearer` header kli sets from the resolved key.

```json
{
  "my-gateway": {
    "base-url": "https://gateway.example.net/v1",
    "key-env": "GATEWAY_KEY",
    "headers": {
      "x-org-id": "acme",
      "x-route": "fast"
    },
    "models": [{ "id": "fast-model", "context-window": 65536 }]
  }
}
```

## Use the provider

kli reads `providers.json` when the `compatible` provider installs, so start a fresh session after editing the file. Each entry appears under its provider id, with its models available to select. See [/kli/guides/connect-a-provider](/kli/guides/connect-a-provider) for switching providers and models inside a session.


#### Run Commands and Eval Lisp


kli has two tools for executing code in a session: `bash` runs a shell command in a child process, and `eval` evaluates Common Lisp forms inside the running kli image. The agent calls them while it works, and you can call either one directly with a slash command.

Both tools are gated behind capabilities. They run only when the session grants them: `bash` needs `process/exec` and `eval` needs `image/eval`. With the default settings (no `capabilities` key) every tool is allowed. See [Restrict Tools With Capabilities](/kli/guides/restrict-what-kli-can-do) to deny one.

## Run a shell command

Type `/bash` followed by the command:

```
/bash ls -la src
```

Everything after `/bash` is the command line, passed to `sh -c`. So pipes, redirects, globs, and `&&` work as written:

```
/bash grep -rn TODO src | head -20
```

The tool returns stdout on success. When the command exits non-zero, the result is marked an error and includes stderr. An empty result means the command produced no output and exited zero.

## Set the working directory or pass stdin

The agent can run a command in a specific directory or feed it input. These are tool parameters, not shell syntax, so the agent supplies them on the tool call rather than you typing them after `/bash`. The `bash` tool accepts:

| Parameter   | Required | Effect                                             |
|-------------|----------|----------------------------------------------------|
| `command`   | yes      | The command line to run.                           |
| `directory` | no       | Working directory for the child process.           |
| `input`     | no       | Text written to the command's stdin.               |
| `shell`     | no       | Shell to invoke. Defaults to `sh`.                 |

From the `/bash` slash command, only the command line is available; the rest take their defaults. To change the working directory yourself, `cd` inside the command itself.

## Evaluate Common Lisp

Type `/eval` followed by one or more forms:

```
/eval (+ 1 2 3)
```

The forms are read and evaluated in order. The result is whatever the forms printed, followed by the value of the last form. Several forms in one call run left to right:

```
/eval (defparameter *x* 10) (* *x* *x*)
```

Forms read and evaluate in the `CL-USER` package by default. The agent can target another package through the tool's `package` parameter; unqualified symbols then intern there. Values print under bounded printer control: `*print-length*` is 100, `*print-level*` is 20, and `*print-circle*` is on, so a long or circular value prints a bounded representation instead of running away.

The forms run in the same image kli runs in, so they reach live state and can inspect or change kli mid-session. For what that image is and why it matters, see [The Live Image](/kli/concepts/the-live-image).

## Stay inside the timeouts

Both tools time out at 30 seconds by default. The hard maximum is 300 seconds; a longer request is clamped to it. There is no way to extend a single call past 300 seconds.

When a `bash` command times out, kli kills its whole process group (SIGTERM, then SIGKILL) and returns the output captured so far, marked as a timeout error. When an `eval` form times out, kli interrupts the evaluating thread. An interrupted form can leave image state partially modified, since it stops wherever it was, so the result says so.

To run something longer than 300 seconds, start it in the background from a `bash` command and poll its progress with later commands, rather than waiting inside one call.

## Know the output cap

Each tool caps its captured output at 1 MiB (1,048,576 characters):

- `bash` caps stdout and stderr at 1 MiB **each**. Past the cap the stream is truncated and the result notes `[stdout truncated at ... characters]`.
- `eval` caps total output at 1 MiB across everything the forms print. The cap applies as output is written, so even a non-terminating printing loop stops adding to the result at the cap.

When you expect a large result, narrow it before it reaches the tool: pipe a `bash` command through `head`, `tail`, or `grep`, and have `eval` return a count or a slice rather than a whole collection.

## Commands bash refuses

The `bash` tool runs to completion and returns captured output; it has no terminal to drive. So it refuses commands whose first word is an interactive program and returns an error instead of hanging:

```
vi  vim  nvim  nano  emacs
less  more  man
top  htop  watch
ssh  mosh
tmux  screen
```

The check looks past leading variable assignments and wrappers (`env`, `command`, `exec`, `time`, `sudo`, `doas`) to find the real command, so `sudo vim file` is refused too. Reach for non-interactive equivalents: read a file with `cat` instead of `less`, search with `grep` instead of opening an editor, run a remote command through whatever your environment exposes rather than an interactive `ssh` session.


#### Persist and Resume Sessions


By default kli keeps the session log in memory and discards it when you quit. To carry a conversation across runs, point kli at a directory to write session files into, then reopen a saved session by id or resume the newest one on boot.

## Persist sessions to disk

Set `sessionDir` in your settings so kli writes each session to a file instead of holding it in memory.

Set it in `settings.json` (global `~/.config/kli/settings.json`, project `<repo>/.kli/settings.json`; project wins) — see [Settings](/kli/config/settings):

```json
{
  "sessionDir": "~/.config/kli/sessions"
}
```

A leading `~` expands to your home directory; a relative path resolves against the directory you start kli in. The directory is created on first write.

Restart kli for the change to take effect. From then on, kli writes one file per session, named `<session-id>.session`, under that directory. Each file is a header followed by one record per turn, appended as the conversation grows.

To check whether the current session is being written, run `/session`. It reports the session id, the file path backing it, the active model, and the token count. A session with no `sessionDir` configured shows `file: (memory)`.

For the full settings schema, see [Settings](/kli/config/settings).

## Resume a saved session

Resuming switches the current session onto a stored one. There are three ways in, depending on whether you know the id and whether you are at the terminal UI.

**Resume the newest session on boot.** Pass `-c` (or `--continue`) when you start kli:

```sh
kli -c
```

kli resumes the most recently stored loadable session. With no stored sessions, it starts fresh.

**Pick from a list in a running session.** Run `/resume` with no argument. In the terminal UI this opens a menu over your stored sessions, newest first. Without the UI, `/resume` prints the list as text rows, each marked with `*` for the active session and showing the id, name, message count, and a preview of the opening prompt.

**Resume a specific session.** Pass an id or a search term:

```text
/resume session-12
/resume refactor
```

An exact id resumes that session. Otherwise kli searches ids, names, and previews: a single match resumes, several matches print the narrowed list to choose from.

To name a session so it is easy to find later, run `/name <text>`. To remove a stored session, run `/resume delete <id>` — you cannot delete the session you are currently in.

## Branch and rewind through past turns

Rewinding steps the conversation back to an earlier point. kli does not overwrite history when you do this: it branches the session before the chosen prompt and switches onto the new branch, so the turns you stepped back from remain on the original session.

**Step back the latest turn.** Run `/rewind` with no argument to undo the most recent user turn.

**Step back several turns.** Pass a count:

```text
/rewind 3
```

This rewinds to before the third-newest prompt. If the session has fewer turns than the count, kli reports nothing to rewind. In the terminal UI, bare `/rewind` opens a menu over the session's user turns.

**See and switch between branches.** Run `/branches` to view the tree of sessions that rewinding has produced. In the terminal UI this opens a selection menu over the tree; accepting a row switches onto that branch. Without the UI, `/branches` prints the tree as indented rows, marking the active session with `*` and labelling each branch by the prompt it diverged from.

Branching and rewinding only persist across restarts when `sessionDir` is set. In memory the branches still work, but they vanish on exit along with the rest of the log.

## Related

- [/kli/cli/installation](/kli/cli/installation) — install kli and start it in a project.
- [Settings](/kli/config/settings) — every settings key, with types and defaults.
- [Sessions as a Tree](/kli/concepts/sessions-as-a-tree) — what a session is and how the log is structured.


#### Manage Long Conversations


A long session fills the model's context window. kli summarizes older history to make room, on demand or automatically, and keeps the recent part of the conversation intact. Compact when you want, let kli compact on its own near the limit, and label a session so you can find it later.

## Compact the session now

Run `/compact` to summarize the conversation's older history immediately:

```
/compact
```

kli runs one summarizer model call over everything except the most recent turns, replaces that history with a structured summary, and keeps the recent turns verbatim. The summary records the goal, constraints, progress, key decisions, next steps, and critical context (file paths, function names, error messages), so the agent continues from a checkpoint rather than from raw transcript.

Compact when the session is idle. If a turn is still running, the command reports that the session is busy; wait for the turn to finish and run it again. When there is nothing older than the recent window to summarize, `/compact` reports that there is nothing to compact.

## Focus the summary

Pass a tail to `/compact` to add a focus line to the summarizer's instructions:

```
/compact keep the database migration details and drop the UI styling discussion
```

The focus rides along with the standard summary format. Use it when one thread of the conversation matters more than the rest and you want the summary to preserve it.

## Let kli compact automatically

You do not have to run `/compact` yourself. At the end of each turn, kli checks token usage against the context window. When usage reaches a configured fraction of the model's context window, kli compacts on its own: it keeps the recent tokens and summarizes everything older, the same operation `/compact` performs.

Automatic compaction stays quiet when there is nothing older than the recent window to summarize. A manual `/compact` is the way to summarize before the threshold, for instance right before handing the session a large new task.

To see current usage at any time, run `/session`, which prints the active session's id, file, model, and token count.

## Name the session

Run `/name` with a label to set the session's display name:

```
/name fourier-series refactor
```

The name is written to the session header and persists to disk, so it identifies the session in `/resume` and `/branches` listings. Run `/name` with no argument to print the current name, or report that none is set.

## Related

- [Sessions](/kli/concepts/sessions-as-a-tree) — what a session is and how it is stored
- [The Agent Loop](/kli/concepts/the-agent-loop) — how a turn runs and when usage is measured
- [Session Commands](/kli/commands/slash-commands) — the full reference for `/compact`, `/name`, `/session`, `/resume`, and `/rewind`


#### Inspect and Edit Context


The model only ever sees a projection of your session: the ordered list of messages kli builds and sends on the next turn. The `/context` command shows you that projection and lets you change it. Edits are staged first and applied as a group, so you can review or discard them before they reach the model.

This guide covers `inspect`, `stage`, `diff`, `commit`, and `revert`.

## View the current projection

Run `/context inspect` to see what the model would receive right now:

```
/context inspect
```

The header reports three numbers:

```
Context epoch 4, 12 messages, 0 staged.
```

The **epoch** counts how many times you have committed edits to this context; it starts at 0 and increments by one per commit. The **message count** is the length of the projection. The **staged** count is how many edits are waiting to be applied. When edits are staged, `inspect` lists them under a `Staged:` block.

Positions are zero-based; target a message by index for removal or replacement.

## Stage an edit

`/context stage` takes one of three subcommands as its first word. Staging records the edit but does not change the projection yet.

Add a message to the end of the projection:

```
/context stage append <text>
```

The text becomes a user message appended after the current last message.

Remove the message at a given index:

```
/context stage remove <index>
```

Replace the message at a given index with new text:

```
/context stage replace <index> <text>
```

Each stage command confirms the running total, for example `Staged append-message patch (2 total).` Stage as many edits as you need; they accumulate in order.

## Review staged edits

Before applying anything, see exactly what is pending:

```
/context diff
```

This lists every staged edit without committing. An append shows the text to be added, a remove shows the target index, and a replace shows the new text. With nothing staged, it reports `No pending context changes.`

## Apply the edits

When the staged set is what you want, commit it:

```
/context commit
```

Commit applies all staged edits to the projection as a single group, clears the staging area, and bumps the epoch by one. It reports the count and the new epoch, for example `Committed 3 patches (epoch 5).` If nothing is staged, it reports `No staged patches to commit.`

A commit is recorded in the session log, so the edited projection survives across saves and resumes. Removal and replacement match the message sitting at the given index when the commit rebuilds the projection. If no message sits at that index, the edit applies to nothing and the projection is unchanged, so use `/context inspect` first to read off the index you mean.

## Discard staged edits

To throw away everything you have staged without applying it:

```
/context revert
```

This clears the staging area and reports how many edits it discarded. It does not touch already-committed changes; only the pending set is affected. With nothing staged, it reports `No staged patches to revert.`

## Capabilities these commands need

Inspecting, staging, and committing each need a capability; `diff` is ungated and always runs. With the default settings the `capabilities` key is absent, so every subcommand is allowed. If you restrict tools through the `capabilities` array in `settings.json`, list the ones you want:

| Subcommand | Capability |
| --- | --- |
| `inspect` | `context/read` |
| `stage`, `revert` | `context/stage-edit` |
| `commit` | `context/commit-edit` |

See [Restrict Tool Capabilities](/kli/guides/restrict-what-kli-can-do) for how the `capabilities` array works, and [The Agent Loop](/kli/concepts/the-agent-loop) for where the projection sits in a turn.


#### Steer a Running Turn


kli keeps reading your input while a turn is in flight. You do not have to wait for the model to finish before you correct its course, add a constraint, or stop it. This page covers the three ways to redirect a turn that is already running: steering, follow-up, and aborting with Esc.

## Steer: inject guidance at the next tool boundary

Type a message and press Enter while kli is working. The turn keeps running, and your message is queued as steering. kli delivers it at the next tool boundary: after the current tool call returns, before the model issues the next one. The remaining tool calls in that batch are skipped, your message lands in the conversation, and the model reacts to it on the following turn.

A turn that makes no tool calls has no mid-turn boundary. A steer queued during such a turn is delivered when the turn ends, so it runs as the next turn rather than waiting for a boundary that never comes.

Steering is the default for anything you submit while a turn is in flight. You do not press a special key or prefix the message; an ordinary Enter during a running turn steers.

## Follow-up: queue a message for after the run

A follow-up message is held until the whole turn completes, then delivered as the next turn. Unlike steering, it never interrupts tool calls or cuts a batch short. Use it when the current work is correct and you want to add the next instruction without disturbing what kli is already doing.

## Set the delivery mode

Both queues default to delivering everything you have submitted in one pass when their boundary arrives. If you submit three steering messages while kli works, all three land together at the next tool boundary. You can switch either queue to deliver one message per boundary instead.

Set these in `settings.json` (global `~/.config/kli/settings.json`, project `<repo>/.kli/settings.json`; project wins) — see [Settings](/kli/config/settings):

```json
{
  "steeringMode": "one-at-a-time",
  "followUpMode": "all"
}
```

`steeringMode` controls how many queued steering messages drain per tool boundary; `followUpMode` does the same for follow-up messages after the turn ends. Set either to `"one-at-a-time"` to deliver exactly one queued message per boundary, leaving the rest to drain at later boundaries. The default, `"all"`, drains every queued message in that queue at once. Leave a key out to take the default; an unrecognized value is ignored with a warning, and the default applies.

For the full settings reference, see [Settings](/kli/config/settings).

## Abort or rewind with Esc

Esc does one of two things depending on whether a turn is running.

**While a turn is in flight, Esc aborts it.** The first press arms and shows `Press Esc again to interrupt.`; a second press within about 1.5 seconds stops the turn. A lone Esc does nothing, so a misclick cannot interrupt your work. If the window lapses, the next Esc re-arms.

What the abort leaves behind depends on how far the turn had progressed:

- If the model had not yet streamed any reply, the prompt you sent is un-sent: the row is removed from the transcript and your text is restored to the editor, so you can revise and resend it. If turn entries have already been committed, the prompt stays sent and kli shows an `Interrupted.` notice instead.
- If the reply was already streaming, kli marks that reply as aborted in place and stops the turn.

**At an idle prompt with a conversation behind you, Esc rewinds.** The first press shows `Press Esc again to rewind.`; a second press within the window opens a menu of your past prompts. Move with Up and Down, press Enter to rewind to the state before the chosen prompt, and Esc to dismiss the menu. Rewinding to before a prompt restores that prompt's text to the editor.

On an empty conversation, or when there is nothing to rewind, Esc is a no-op.

## Related

- [/kli/concepts/the-agent-loop](/kli/concepts/the-agent-loop) — why a turn has tool boundaries to steer at
- [/kli/guides/persist-and-resume-sessions](/kli/guides/persist-and-resume-sessions) — the session log a rewind steps back through
- [Settings](/kli/config/settings) — the full settings reference


#### Restrict What kli Can Do


By default kli can read, write, and edit your files and run shell commands. There is no per-action prompt to approve. You restrict it up front by listing, in `settings.json`, the exact set of permissions kli is allowed to hold. This guide shows how to write that list and confirm it took effect.

The list is the `capabilities` key. Its value is an array of capability name strings. kli grants the agent exactly those capabilities (plus any they imply) and denies everything else.

## Decide where to put the setting

Set it in `settings.json` (global `~/.config/kli/settings.json`, project `<repo>/.kli/settings.json`; project wins) — see [Settings](/kli/config/settings). Use the project file when you want one repository locked down without changing how kli behaves elsewhere.

## List the capabilities you want to grant

Each gated tool checks for one capability before it runs. The everyday ones:

| Capability | Lets kli use |
|---|---|
| `file/read` | the `read`, `find`, and `search` tools |
| `file/write` | the `write` tool |
| `file/edit` | the `edit` tool |
| `process/exec` | the `bash` tool |

Write the names of the capabilities you want into the array. Anything you leave out is denied. To let kli read files and run commands but never write or edit them:

```json
{
  "capabilities": ["file/read", "process/exec"]
}
```

Under this setting kli can read, search, and run shell commands. Calls to `write` or `edit` are denied, the agent is told so, and the operation does not run.

Granting one capability can grant others. `tools/standard` is shorthand for all four of the file and process capabilities above, so this grants the same access as listing them individually:

```json
{
  "capabilities": ["tools/standard"]
}
```

For the full list of capability names, what each one gates, and which capabilities imply which, see [Capabilities](/kli/config/capabilities).

## Deny everything gated

An empty array grants nothing. Every gated tool is then denied:

```json
{
  "capabilities": []
}
```

This is the strictest setting. kli can still do work that checks no capability, but it cannot touch files, run commands, change its own extensions, or read credentials.

## Allow everything

Omit the `capabilities` key entirely and kli runs with full access — the default. Removing the key from your settings file is how you lift a restriction:

```json
{
}
```

## Apply the change

The `capabilities` key is read when settings load. Restart kli, or switch the active profile, so the new array takes effect. After that, a tool whose capability is not in your list returns a denial instead of running, with no prompt to override it.

If you write a value that is not an array of strings, kli ignores it with a warning and falls back to full access, so a typo never silently locks the agent down. Check kli's startup output for that warning if a restriction does not seem to apply.

The `capabilities` array limits which tools an agent may reach; it does not isolate the kli process from the host. A granted shell command or file write still runs with your full privileges. To bound that, run `kli --print-authority` to see what a session will hold and put kli inside a sandbox — see [Security model and sandboxing](/kli/concepts/security-model-and-sandboxing).


#### Work in the TUI


You talk to kli through one editor at the bottom of the terminal. You type a prompt, send it, and the conversation scrolls above. This guide covers the keys you use every session, how to complete file paths and skill names as you type, how to fold and unfold tool output, and how to set the color theme. For the exhaustive key table see [Keymap](/kli/commands/keymap); for every color token see [Themes](/kli/commands/themes).

## Send, edit, and quit

`Enter` sends the prompt. For a multi-line prompt, insert a line break with `Ctrl+J` or `Shift+Enter`, keep typing, and send the whole thing with `Enter`.

The editor takes standard readline keys; see [Keymap](/kli/commands/keymap) for the full table and rebinding.

`Ctrl+L` clears the screen. `Ctrl+C` takes two presses to quit: the first prints `Press Ctrl+C again to quit.`, the second exits.

`Esc` depends on what kli is doing. While a turn is streaming, press it twice within about 1.5 seconds to interrupt the turn. At an idle prompt, press it twice to open the rewind menu over your earlier prompts; accept one to send the conversation back to before it.

## Complete a file path with @

Type `@` at the start of a token to reference a file. A menu of paths under the working directory opens as you type, ranked against what you have entered. In every completion menu, `Up`/`Down` move the selection, `Tab` or `Enter` accepts, and `Esc` dismisses. Hidden files stay out of the menu unless your text starts with a dot.

Selecting a directory keeps the menu open and steps into it, so you can walk down a tree one segment at a time. Selecting a file inserts the path and a trailing space. `Esc` closes the menu and leaves what you typed.

## Complete a skill with $

Type `$` at the start of a token to run a skill. The menu lists the skills available in this session; each row shows the skill name and its description.

Slash commands complete the same way. Type `/` and the command menu opens, then accepting a command offers help or candidates for its arguments. See [Commands](/kli/commands) for what is available.

## Complete a bare path with Tab

When no completion menu is open, `Tab` completes the path token directly before the cursor — no `@` needed. One match is inserted at once; several open the menu to choose from. With a menu already open, `Tab` accepts the current selection instead.

## Fold and unfold tool output with Ctrl+O

When kli runs a tool, the result is shown as a card in the transcript: a shell command's output, a file you asked it to read, the diff of an edit. By default these cards are collapsed so the conversation stays readable.

Press `Ctrl+O` to expand every committed tool card to its full output, including the full diff of each edit. Press `Ctrl+O` again to collapse them. The toggle reprints the transcript, so it applies to the whole session at once rather than one card at a time.

## Let kli pick the theme

kli ships a `dark` and a `light` theme. By default it reads your terminal's background color at startup and selects the matching one, so a light terminal gets the light theme without any configuration. Detection happens once per session and is skipped under GNU `screen`.

If you do nothing, auto-detection stays on. To return to it after pinning a theme, set `theme` to `"auto"` or remove the key.

## Pin a theme

To always use one theme regardless of the terminal background, set the `theme` key in `settings.json` to `"dark"` or `"light"`:

```json
{
  "theme": "dark"
}
```

Set it in `settings.json` (global `~/.config/kli/settings.json`, project `<repo>/.kli/settings.json`; project wins) — see [Settings](/kli/config/settings).

A pinned theme turns off background detection for the session. An unknown name is ignored with a warning and the previous theme stays in effect. The setting is read at startup, so restart kli for a change to take hold.

## Rebind a key

Bind a key through the `keybindings` object in `settings.json`. The keys are key-id strings like `ctrl+r`; the values are action names like `delete-to-line-start`:

```json
{
  "keybindings": {
    "ctrl+r": "delete-to-line-start"
  }
}
```

Each entry sets one key and leaves the rest of the defaults in place. An unknown action name is skipped with a warning. For every key-id, action name, and the default binding of each key, see [Keymap](/kli/commands/keymap).


#### Run kli Headless or Piped


You can drive kli without typing into a live terminal. Pipe a prompt in and kli runs one turn and prints the result. Redirect a file in and kli runs each line as its own turn. For longer-lived unattended work, you can also boot a profile that brings up kli without the terminal UI at all.

## Feed a prompt over a pipe

Run kli the same way you always do, but connect its standard input to something other than a terminal:

```sh
echo "summarize the changes in the last commit" | kli
```

kli starts in the default profile and brings up the agent, but instead of the interactive editor it detects that standard input is not a terminal and switches to a line loop. The line loop reads one line, submits it as a turn, waits for the agent to finish that turn, then reads the next line. When input reaches end of file, kli exits.

Run kli from inside a project directory so it reads and edits that project's files, exactly as in an interactive session.

## Feed many turns from a file

Because the line loop runs one turn per line, a file of prompts runs as a sequence of turns in one session, each turn seeing the results of the ones before it:

```sh
kli < turns.txt
```

Each line in `turns.txt` is submitted in order, and the session ends at end of file.

Keep one instruction per line. A blank line is submitted as an empty turn, so strip blank lines from the file if you do not want them.

## Resume a session in a piped run

A piped run starts a fresh session by default. To continue the most recently stored session instead, pass `--continue` (or `-c`):

```sh
echo "now run the test suite" | kli --continue
```

kli resumes the newest loadable stored session, then runs the piped line as the next turn in it. This lets a script pick up where an earlier interactive or piped run left off. See [Persist and Resume Sessions](/kli/guides/persist-and-resume-sessions) for how sessions are stored.

## Use kli inside a script

The piped form composes with the rest of your shell. Build the prompt from other commands and pipe it in:

```sh
git diff --staged | {
  echo "Write a one-paragraph commit message for this diff."
  cat
} | kli
```

kli's own output goes to standard output, so you can capture or pipe it onward. Errors and boot diagnostics go to standard error, so redirect each stream where you want it:

```sh
echo "list every TODO comment in src/" | kli > result.txt 2> kli.log
```

When stripping kli's reply down to a value a script can use, prefer prompts that ask for exactly the output you want and nothing else.

## Pick a boot profile

A profile is the set of extensions kli installs at boot. The default profile, `interactive-terminal`, is the one a normal interactive session uses, and it is also the one the piped line loop above runs under. kli selects a profile from, in order:

1. the `--profile NAME` flag,
2. the `KLI_PROFILE` environment variable,
3. the `profile` key in `settings.json`,
4. the default, `interactive-terminal`.

So a script can set the profile per invocation:

```sh
kli --profile headless
```

or for a block of commands at once:

```sh
export KLI_PROFILE=headless
```

For unattended runs, kli ships the `headless` and `autonomous` profiles, both of which boot without the terminal UI; the next two sections describe each. For the full roster and how to define your own, see [Switch and customize profiles](/kli/guides/switch-and-customize-profiles).

## Boot the headless profile

The `headless` profile installs kli's baseline extensions and nothing else: no terminal UI and no model providers. It boots the kernel, holds it alive, and does not enter an interactive loop or read prompts from standard input.

```sh
kli --profile headless
```

Use this profile to bring up kli as a long-running process you drive by other means rather than by typing or piping prompts. It is not the profile for running a one-shot prompt; for that, pipe into the default profile as shown above. Boot diagnostics that an interactive session would show in the transcript are printed to standard error instead.

## Boot the autonomous profile

The `autonomous` profile installs the baseline extensions and the model providers, then declares a set of extension points it expects you to fill: `planner`, `scheduler`, `watchdog`, and `recovery`. Like `headless`, it boots without the terminal UI.

```sh
kli --profile autonomous
```

The profile names those four points but does not provide them. It is a starting point for an unattended agent that you complete by installing extensions that supply a planner, a scheduler, a watchdog, and a recovery strategy. Without those, the profile boots the baseline agent and the providers but has no driver of its own. See [Install a Remote Extension](/kli/extend/sharing-extensions) for how extensions are added.

## Related

- [The Agent Loop](/kli/concepts/the-agent-loop) — what one turn does.
- [Connect a Provider](/kli/guides/connect-a-provider) — a model credential the default and autonomous profiles need.
- [Persist and Resume Sessions](/kli/guides/persist-and-resume-sessions) — how `--continue` finds a session.
- [Installation](/kli/cli/installation) — getting the `kli` binary onto the machine running your script.


#### Switch and Customize Profiles


A profile is the set of extensions kli installs at boot: which model providers load, whether the terminal UI comes up, which tools are present. kli ships these builtins:

- `interactive-terminal` — the default. Boots the terminal UI with all the model providers and the full tool set.
- `headless` — the baseline kernel and tools with no terminal UI and no provider extensions. Holds the process open for a programmatic driver.
- `human-in-loop` — the interactive profile, declaring an `approval` seam for an extension you supply.
- `autonomous` — providers and tools without the terminal UI, declaring `planner`, `scheduler`, `watchdog`, and `recovery` seams.

This guide shows how to choose one at startup, switch while kli runs, and define your own.

## Choose a profile at startup

Name a profile on the command line:

```sh
kli --profile headless
```

Or set it in the environment, which kli reads when `--profile` is absent:

```sh
export KLI_PROFILE=headless
kli
```

To make the choice stick without a flag or env var, set the `profile` key in `settings.json`:

```json
{
  "profile": "headless"
}
```

kli resolves the boot profile in this order, taking the first that names one:

1. `--profile <name>`
2. `KLI_PROFILE`
3. the `profile` key in `settings.json`
4. the default, `interactive-terminal`

Set it in `settings.json` (global `~/.config/kli/settings.json`, project `<repo>/.kli/settings.json`; project wins) — see [Settings](/kli/config/settings).

A name that resolves to nothing warns and boots the default profile instead. The warning lands in the transcript as a boot diagnostic.

## Switch profiles while kli runs

Run `/profile` with no argument to list every profile, builtins first, then the ones you defined. The active one carries a `*`:

```
Profiles:
* interactive-terminal
  headless
  human-in-loop
  autonomous
  review
```

Pass a name to switch:

```
/profile review
```

A live switch re-bases your own extensions onto the target profile: kli installs the ones the target enables that are not yet present, and retracts the ones present that the target disables. The reply names what changed:

```
Switched to review. Installed: my-linter.
```

The delta is computed against what is actually installed, so any manual `/enable` and `/disable` you ran since boot re-bases too.

Two switches do not apply:

- Naming the active profile reports that it is already active and changes nothing.
- A profile whose builtin base differs from the running one cannot apply live, because the base set installs only at boot. The builtins each have a distinct base, so a live switch between them always lands here. kli tells you to restart, for example `Restart with --profile autonomous`.

## Define your own profile

Add a `profiles` block to `settings.json`. Each key is a profile name; each value describes how it differs from a builtin:

```json
{
  "profiles": {
    "review": {
      "extends": "interactive-terminal",
      "enable": ["my-linter"],
      "disable": ["scratch-notes"],
      "settings": {
        "defaultProvider": "anthropic",
        "defaultModel": "claude-opus-4-6"
      }
    }
  }
}
```

The fields:

- `extends` — the profile this one builds on, a builtin or another profile you defined. Omit it and the profile builds on `interactive-terminal`. The chain must bottom out at a builtin; a cycle or a dangling target is reported and the profile is skipped.
- `enable` — ids of your own extensions to install that the base would leave out.
- `disable` — ids of your own extensions to keep out that the base would install. Within one profile `disable` wins over `enable` for the same id. `enable` and `disable` gate the extensions kli discovers in `~/.config/kli/extensions/` and `<repo>/.kli/extensions/`, not the builtin tools.
- `settings` — a settings object that overlays the merged files while this profile is active. Use it to bind a profile to a default provider and model, a set of capabilities, or any other setting.

A profile may not reuse a builtin name (`interactive-terminal`, `headless`, `human-in-loop`, `autonomous`). kli warns and ignores any entry that does.

Once defined, a profile is selectable everywhere a builtin is: `--profile review`, `KLI_PROFILE=review`, the `profile` key, and `/profile review`. It also appears in the `/profile` list and in `/profile` tab completion.

For how `enable` and `disable` sit against the per-extension `/enable` and `/disable` commands, see [Restrict What kli Can Do](/kli/guides/restrict-what-kli-can-do) and the [settings reference](/kli/config/settings). For what an extension is and why retracting one mid-session is safe, see [The Live Image](/kli/concepts/the-live-image).


#### Update kli


`kli update` replaces your installed binary with a newer release built from [github.com/kleisli-io/kli](https://github.com/kleisli-io/kli). It downloads the release for your platform, verifies it against the release checksums, and swaps it into place. If the new binary fails to run, kli restores the previous one before it returns.

This applies to a binary you installed with the install script (`curl -fsSL https://kli.kleisli.io | sh`). If you installed through Nix, update through Nix instead; see [Refuses a Nix-managed binary](#refuses-a-nix-managed-binary).

## Update to the latest release

Run:

```sh
kli update
```

kli queries GitHub for the latest release tag, compares it to the running version, and shows what it found:

```
  current: v0.3.1
  new:     v0.4.0

Proceed? [Y/n]
```

Press Enter or `y` to continue. An empty line counts as yes. When the update finishes, kli prints:

```
kli updated to v0.4.0.
```

If you are already on the latest release, kli prints `Already up to date (v0.4.0).` for that version and exits without downloading anything. If you decline the prompt, it prints `Update cancelled.`

## Update without the prompt

Pass `--yes` (or `-y`) to skip the confirmation. This is the form to use in a script or a `cron` job:

```sh
kli update --yes
```

The version check still runs, so an up-to-date binary stays untouched.

## Install a specific version

Pass `--version` with a release tag to install that release instead of the latest:

```sh
kli update --version v0.3.0
```

The tag must match a published release on [github.com/kleisli-io/kli](https://github.com/kleisli-io/kli); kli validates it against the releases endpoint before downloading and fails if no such release exists. This works for both upgrades and downgrades. Combine it with `--yes` to install a pinned version unattended:

```sh
kli update --version v0.3.0 --yes
```

## What an update does

`kli update` keeps your current install in a `.bak` sibling directory while it activates the new release, so a failure rolls back to it:

1. It downloads the release archive for your platform and checks it against the release `checksums.txt`. A mismatch aborts the update with the bytes left untouched.
2. It moves your current install aside to a `.bak` directory and moves the new files into place.
3. It runs the freshly installed binary's `version` command. On success, it deletes the `.bak` backup.
4. If the new binary does not run, kli deletes the broken install, renames the `.bak` backup back into place, and reports `the updated binary failed to run; rolled back`.

You keep a working kli whether the update succeeds or fails. There is no half-installed state to clean up.

## Refuses a Nix-managed binary

A kli installed through Nix lives under a read-only store path, and the package, not the updater, owns that file. `kli update` refuses such a binary and prints:

```
kli is managed by Nix; update through your Nix configuration instead.
```

Bump the version in your Nix configuration and rebuild to update a Nix-managed kli. See [Installation](/kli/cli/installation) for the install methods and which one you have.


#### Log Observability Events


kli emits an event for everything that happens in a session: model changes, session branches and resets, committed patches, notifications, and faults. This guide turns those events into a durable record. You set one path, kli appends each event to that file as a JSON line, and `/observability` tells you the sink is live.

The sink is off until you give it a path. Nothing is recorded by default.

## Point the sink at a file

Add an `observability` section to your settings and set `path` to where the log should be written. Set it in `settings.json` (global `~/.config/kli/settings.json`, project `<repo>/.kli/settings.json`; project wins) — see [Settings](/kli/config/settings).

```json
{
  "observability": {
    "path": "~/.local/state/kli/events.jsonl"
  }
}
```

A leading `~` expands against your home directory. A relative path resolves against the working directory kli was started in. An absolute path is used as-is. kli creates the parent directories on the first write, so the file does not need to exist beforehand.

Settings load at startup. Start kli in your project, or restart it if it is already running, for the new path to take effect.

The sink stays disabled when `path` is absent or an empty string. That is the off switch: remove the key (or set it to `""`) to stop recording without deleting the rest of your `observability` section.

## Record only some events

By default the sink records every event. Add an `events` array to record only the types you care about. Each entry is a prefix matched against the event type name, so one entry can select a whole family.

```json
{
  "observability": {
    "path": "~/.local/state/kli/events.jsonl",
    "events": ["session", "model-change", "fault"]
  }
}
```

This records every type whose name starts with `session` (`session-switch`, `session-branch`, `session-reset`, `session-rewind`, `session-cleared`, and the rest), plus `model-change` and `fault`. An event is recorded when any prefix in the array matches; an event matching none is dropped.

Matching is case-insensitive and prefix-based, so `session` catches the whole session family while `session-reset` catches just that one type. An empty array records every event, the same as omitting the key.

## Check the sink

Run `/observability` in a session to see the current state.

When the sink is enabled, it reports the resolved path, the active filter, the number of events written so far, and the last write error if one occurred:

```
observability: enabled
path: /home/you/.local/state/kli/events.jsonl
filter: session, model-change, fault
events-written: 42
```

The filter line reads `(all)` when no `events` array is set. When the sink is off, the command reports `observability: disabled`. Use this to confirm your `path` resolved to where you expected and that events are reaching the file.

## Read the log

kli appends one event per line. Each line is a JSON object with four fields:

- `timestamp` — the wall-clock time the event occurred, as a Lisp universal time integer (seconds since 1900-01-01 UTC).
- `type` — the event type name, downcased (for example `model-change`, `session-branch`, `fault`).
- `source` — the originator of the event, present only when the event carries one.
- `payload` — the event's data, present only when the event carries one. Keyword-keyed data renders as a JSON object with downcased keys; other data renders as an array or a string.

A `fault` event, for instance, looks like this:

```json
{"timestamp":3958372800,"type":"fault","source":"tool-call","payload":{"seam":"tool-call","unit":"read-file","condition":"file not found","dispatch":"contained"}}
```

Each line is independent JSON, so pipe the file through `jq`, `grep`, or any line-oriented tool. Each write is appended under a lock and flushed, so a `tail -f` of a running session never shows a half-written line.

A failed write does not interrupt the session. The sink records the error, drops that one line, and keeps running; the error then shows up on the `last-error` line of `/observability`.

## Related

- [Configure kli with settings.json](/kli/config/settings)
- [The Agent Loop](/kli/concepts/the-agent-loop)


### Concepts

#### The Live Image


You can add a tool, change a command, swap a model provider, or remove a piece
of behavior without restarting kli. The running session keeps going: your
context, your session log, and the model connection all survive the change. That
follows from how kli is built, which is what this page explains.

## A small kernel, everything else an extension

kli is one running program. At its center is a small kernel: a registry of live
objects and a single protocol that knows three operations — install a protocol,
switch to it, and roll back to the previous one. That is nearly all the kernel
does. It holds no model provider, no tool, no command, no rendering code.

Everything you interact with is an extension installed on top of the kernel. The
model providers (anthropic, openai, openai-codex, and compatible), the tools
that read and edit your files, the session log, the slash commands, and the
terminal interface are all extensions. They were installed at startup the same
way you would install one yourself, and they can be removed the same way.

An extension is a value before it is an effect. It declares what it requires and
what it provides, and installing it runs through one step that records every
piece it added to the protocol. Each kind of contribution has a matching
retractor: a tool, a capability provider, a generic-function method, and a raw
effect each install and drain through their own paired operations. Because
installing was recorded, removing is possible, and removing an extension drains
exactly the pieces it installed and nothing else. A slash command is one such
extension: it registers through a capability provider and retracts with it.

## What "while it runs" means

kli runs inside a live image. The image is a running Lisp process that holds the
program and its state in memory at once, and that program can be redefined while
it is running. This is the mechanism. It is why the kernel can install, retract,
and replace extensions in a live session instead of regenerating a binary and
starting over.

Replacing an extension is its own operation. The kernel deactivates the old
version, draining its contributions, then activates the new source. If the new
version fails to come up, the kernel reactivates the old one and reports the
error, so a botched change leaves you where you started rather than in a broken
state. The same holds for switching the whole protocol: a switch validates and
smoke-tests the candidate first, and any failure rolls back to what was active
before.

## What this lets you do

The arrangement turns "change kli" from a build-and-restart cycle into an
in-session action.

- **Add behavior.** A new tool or command is an extension; installing it makes
  it available in the current session.
- **Change behavior.** Redefining an extension's source replaces the running
  version, with automatic fallback to the previous version if the new one
  fails.
- **Remove behavior.** Deactivating an extension retracts its tools, commands,
  providers, and methods together, leaving the rest of the session untouched.
- **Recover.** Because every change is a recorded transaction, a failed switch
  or a failed recode returns the session to its prior working state instead of
  killing it.

You can also pull an extension from outside your machine. The in-session
`/install <url> <git-tree-sha1>` command fetches a remote extension, shows a
trust card describing what it is, verifies it against the git tree sha1 you
pinned, and installs it only after you confirm. That consent step is separate
from installing the kli application itself, which is the one-time
`curl -fsSL https://kli.kleisli.io | sh`.

## Why it is built this way

Making the kernel small and everything else a retractable extension lets you bend
kli to a project — a tool that knows your build, a provider pointed at an endpoint
you run — in the session that needed it, with no source edit or rebuild.

The kernel stays small on purpose. The fewer things it does, the fewer things
can break when an extension is added or removed, and the more of kli can be
treated as replaceable parts rather than fixed structure. The model providers
themselves follow this rule — each one is an extension that installs a provider
and retracts it cleanly, interchangeable parts rather than one wired-in default.

## Related

- [Profiles](/kli/concepts/profiles) — how groups of extensions are bundled and
  selected.
- [Permissions and capabilities](/kli/concepts/capabilities-and-fault-barriers) —
  the capability set that gates installing, retracting, and recoding behavior.
- [Connect a provider](/kli/guides/connect-a-provider) — installing and
  configuring a model provider extension.
- [Installation](/kli/cli/installation) — installing the kli application.


#### Extensions All the Way Down


kli runs inside its own live SBCL image. The boot kernel knows only how to install,
switch, and roll back protocols. The extension system is itself a protocol installed on
that kernel, and every contribution carries a retractor, so retraction drains exactly
what it added. Extensions all the way down.

That sentence is the whole design. The kernel is small on purpose (see
[The live image](/kli/concepts/the-live-image)); everything you interact with is a
contribution installed against a protocol, paired with a retractor that undoes it. The
kind vocabulary the contributions are written in is contributed the same way, which is
where "all the way down" stops being a slogan (see
[Defining a contribution kind](/kli/extend/lisp-extensions/defining-a-contribution-kind)).

The arrangement buys three things. Each is the same install/retract mechanism seen at a
different reach into the running program.

## Specialize the running program.

A `:method` contribution adds a method to any generic function in the live image; its
retractor is `remove-method`. You change the
program's own dispatch and roll it back, with no rebuild. The kind compiler turns the
clause into a `make-method-contribution` carrying the generic-function name, qualifiers,
specializers, and body; install adds the method, retract removes that exact method. This
is the mechanism at its sharpest: the unit you install and drain is a method on kli's own
code.

## Rewrite without restarting, keep the state.

A hot patch swaps a function's code while keeping its closed-over state, so the session
keeps its buffers and its scrollback across the change. cairn does this in tree: its
context effect calls `recode-context-transform-policy` to splice live task context into
every turn, saving the previous `extra-messages-fn` and handing its retractor the saved
value to restore. The recode is reversible because the contribution recorded what it
replaced, not merely what
it added. It runs behind the capability and fault-barrier machinery (see
[Capabilities and fault barriers](/kli/concepts/capabilities-and-fault-barriers)), so a
hot-patched function that throws degrades rather than killing the session.

## Switch the whole world, safely.

A protocol switch validates, smoke-tests, swaps, and rolls back on any error. This sits
at the kernel altitude, not the extension-authoring one. kli's control plane exposes
`control-install-protocol`, `control-switch-protocol`, and `control-rollback-protocol`,
each gated on its own capability (`:protocol/create`, `:protocol/switch`,
`:protocol/rollback`). An extension does not
switch the world; the kernel does. What an extension supplies is the retractor that makes
a switch clean: because every contribution drains exactly what it added, the kernel can
tear down one protocol and stand up another with no residue. The safety of the switch is
the reversibility of the pillars beneath it, used by the kernel.

## Where this goes

The pillars are the *why*. The mechanics of writing and installing the contributions
behind them are the *how*:

- [Lisp extension anatomy](/kli/extend/lisp-extensions/anatomy) — `defextension`, the
  manifest as a value, install as a recorded transaction.
- [Defining a contribution kind](/kli/extend/lisp-extensions/defining-a-contribution-kind)
  — how the kernel defines `:method`, `:effect`, and the rest, and how you add a kind.
- [Recoding live](/kli/extend/lisp-extensions/recoding-live) — the hot-patch path behind
  the second pillar.
- [The live image](/kli/concepts/the-live-image) — the running-image mechanism all three
  pillars rest on.


#### The Agent Loop


A turn is one model call plus the tool calls it makes; kli runs turns back to back until the model replies without asking for a tool. That is the agent loop: each turn ends by deciding, from the model's own reply, whether to run another. It is why a chain of reads, runs, and edits is not one model call, and why a tool that fails rarely stops the whole task.

## A turn, step by step

A turn is the unit kli repeats. Each turn runs five steps in order.

**Seal the context projection.** Before kli calls the model, it takes an immutable snapshot of the conversation so far. The live session can change while a request is in flight; the snapshot cannot. The model always sees a fixed view of the messages, frozen at the moment the request went out. The turn can also carry ephemeral context that rides this one snapshot and is never written back, so per-turn information reaches the model without becoming part of the permanent log.

**Stream the model response.** kli sends the sealed snapshot and reads the reply as it arrives. Text and reasoning come back incrementally. When the stream ends, kli has the full assistant message: prose, and zero or more tool calls the model wants to make.

**Execute the tool calls serially.** Tool calls run one at a time, in order, not in parallel. After each call kli checks two things: whether you asked it to stop, and whether you typed a new instruction while it worked. Serial execution keeps the order of effects predictable, so a write that a later call depends on has already happened.

**Append to the session log.** The assistant message goes into the log, and so does each tool's result. The log is the conversation: it is what the next snapshot is built from. By the time the turn ends, the model's request and every answer to it are recorded together.

**Loop until there are no tool calls.** This is the decision that makes kli autonomous. If the response asked for at least one tool call, kli runs another turn so the model can react to the results it just got. If the response asked for none, the model is done, and the loop stops and goes idle. The model controls its own length: it keeps the loop alive by calling tools, and ends it by answering in plain text.

## Why the loop, and not a single call

A single model call can plan an edit, but it cannot see whether the edit worked. The loop closes that gap. The model calls a tool, the result lands in the log, and the next turn shows the model what actually happened. A failed test becomes input, not a dead end. This is why kli can run a build, read the real error, and fix the line that caused it: each turn feeds the last turn's results back in.

The snapshot-then-stream order matters here. Because the context is sealed before the call, anything that happens during the call — a tool result appended, an edit you make on the side — does not change the request already in flight. It lands in the log and enters the *next* snapshot instead. Every request the model sees is internally consistent, and new information always arrives at a turn boundary rather than mid-thought.

## Why a failed tool comes back as a result

When a tool fails, kli does not abort the turn. It turns the failure into a tool result marked as an error and appends it to the log like any other result. The next turn shows that error to the model, which can read it and try something else.

There is a hard reason this is the only safe choice. The model's request to call a tool is already in the log before the tool runs. A tool call with no answer leaves the conversation in a broken shape that model providers reject: once a tool call is recorded, the request that follows it must contain that call's result, or the provider refuses every further turn over that conversation. So an exception escaping a tool would not just lose one result — it would wedge the whole session. kli closes that by guaranteeing every tool call gets a result, even when the tool throws, even when the model invents a tool that does not exist. The error is recorded as the result, and the loop continues.

The same rule covers the case where the model calls a tool with arguments that are not valid JSON. Rather than invoke the tool with empty arguments and let it fail as a missing-parameter error — which would mislead the model about what went wrong — kli returns a result that names the real cause: the arguments did not parse. The model gets an accurate error and can correct it on the next turn.

The model wrote the tool call, so the model is the party that can fix it. By feeding errors back as results instead of unwinding the turn, kli lets the model debug its own work the same way it does anything else: read what happened, decide what to do next.

## What stops a loop

Three things end a run. The model can stop it by returning a turn with no tool calls — the normal finish. You can stop it: if you ask kli to abort, the in-flight request is cancelled and the agent settles without starting another turn. And a turn that hits an error the loop cannot turn into a tool result (a failure in the model call itself, not in a tool) ends the run in an error state, where a higher layer can retry it or surface it to you. A failed tool is none of these. It is data the model gets to act on.

## Related

- [Sessions as a Tree](/kli/concepts/sessions-as-a-tree) — the append-only record each snapshot is built from
- [Steer a Running Turn](/kli/guides/steer-a-running-turn) — typing to kli while a turn is running
- [Capabilities and Fault Barriers](/kli/concepts/capabilities-and-fault-barriers) — how a tool call can be denied, which also comes back as a result


#### Sessions as a Tree


A kli session is an append-only tree of entries, each one pointing at its parent.

## What a session is

A session is an append-only collection of entries. Once an entry is written, it is never edited and never removed. Each entry carries the id of its parent, the entry that came before it on the same line of conversation. Follow those parent links from any entry back toward the start and you trace a single path; that path is a *branch*. The session also tracks one entry as its *leaf*: the current tip, the entry the next one will attach to.

So "the conversation right now" is not the whole table of entries. It is the branch from the leaf back to the root, read in order. Everything kli sends to the model on a turn is built by walking that branch. Entries that are not on it are still in the table; they just are not part of what the model sees.

Entries are typed, and the type says what the entry is. A message entry holds one message: your prompt, the assistant's reply, or a tool result. A model-change entry records that you switched providers or models mid-conversation. An option-change entry records a change to a semantic model option such as `reasoning-effort`. A compaction entry holds a summary that stands in for older history. A branch-summary entry records what happened on a path you left. Walking a branch and keeping only the entries that enter model context is how kli turns the tree back into a prompt.

## Why a tree, and not a list

A flat list can only grow at the end. To go back, it would have to delete what came after, and then the alternative you abandoned is gone. A tree never deletes. Going back means pointing the leaf at an earlier entry; the entries past it stay in the table, off the current branch but intact. That single property is what makes the next three behaviors possible, and it is why each of them leaves the path you came from intact.

### Rewind

When you rewind, kli steps the conversation back to before one of your earlier prompts. It does this by branching at that prompt's parent and moving the session onto the new branch. The prompts you can rewind past are the user prompts on the current branch, newest first; the rewind menu lists them by what you typed. The original branch is untouched, so the path you rewound away from is still there to return to. (Rewinding your very first prompt has no parent to branch at, so it starts a fresh session instead.)

### Branches

A branch shares a prefix and then diverges. When kli branches a session at an entry, it makes a new session whose entries are the chain from that entry back to the root, with the leaf set to the chosen entry. The two sessions now share every entry up to the fork and own their continuations separately. Rewind is built on exactly this: it is a branch at a chosen prompt's parent. The shared prefix is the same entries, not a copy of them, however long the shared history is.

### Compaction summaries as nodes

A long conversation eventually carries more history than is useful to resend on every turn. Compaction handles this without throwing anything away. kli picks a cut point in the branch, summarizes everything older than it, and appends a *compaction entry* holding that summary together with the id of the first entry it kept. The cut snaps forward to a prompt or reply so the kept window never begins on a tool result with no call before it.

The summary is a node like any other, on the branch, with a parent. When kli builds the messages for the next turn and finds a compaction entry on the branch, it sends the summary in place of everything before the cut and then the kept entries after it. The older entries are not deleted; they are simply no longer on the path the model reads. A later rewind or branch can still reach them.

Compaction is also why kli keeps a token estimate per entry: it sums the recent entries to decide where the cut should fall, keeping roughly the last stretch of conversation and summarizing the rest.

## One readable record per line

Every entry serializes to a single self-describing record. An entry's record names its type and lists its fields by name: its id, its parent's id, a timestamp, and the type-specific contents. The parent link is right there in the record, so the tree is reconstructed by reading the records and following the ids. Records are read back with evaluation disabled, so loading a session never runs code, and message content that contains newlines round-trips because a record is read as one form, not split on line breaks.

## Persistence is opt-in

By default a session lives only in memory. Start kli, work, quit, and the tree is gone when the process ends. Nothing is written to disk unless you ask for it.

You opt in with a session directory. Point the `sessionDir` setting at a folder and kli swaps the in-memory store for one backed by files. Each session becomes a file: a versioned header, then one entry record per line, in the order the entries were appended. A new entry is appended to the file as it is written, so the file grows with the conversation rather than being rewritten each time. A crash mid-write can leave a torn record at the end of the file; on reload kli drops that trailing fragment and keeps everything before it, so an interrupted write costs you at most the last entry. With a session directory configured, past sessions show up under `/resume`, where the branch structure is rendered as a forest so you can see which conversations forked from which.

The in-memory store and the file store are the same tree behind the same operations. Persistence changes where the entries live, not what they are or how branches, rewind, and compaction work over them.

## Related

- [The Agent Loop](/kli/concepts/the-agent-loop) — the turn that appends to the tree and reads the current branch
- [Context and the System Prompt](/kli/concepts/context-and-the-system-prompt) — how a branch becomes the messages the model sees
- [Configuration](/kli/config) — where `sessionDir` and other settings live


#### Context and the System Prompt


kli assembles the system prompt from per-directory context files (`AGENTS.md`, `CLAUDE.md`) and two override files, rebuilt on each turn — so what the model knows is what you edit into those files, not what you re-explain in chat.

The system prompt is the standing instruction block at the top of every request, the part the model reads before your message. kli assembles it from three layers: a base prompt it ships with, your project context files, and two override files. This page is about where each layer comes from and how they combine.

## The base prompt

kli builds a base system prompt for every session. It states the agent's identity (you are kli, an interactive coding assistant in a terminal), lists the tools currently registered on the running session, carries a few tool-agnostic guidelines, and reports the current date and working directory as authoritative environment facts. The tool list is read live from the session, so a tool added by an extension appears in the prompt without a restart.

This base is the starting point. The other layers extend it or replace it.

## Project context files

kli discovers per-directory context files and renders them into a `# Project Context` section appended to the system prompt. Each discovered file appears under a `## <path>` heading followed by its contents, so the model sees both the instructions and where they came from.

In any one directory, kli looks for these names in order and takes the first that exists:

1. `AGENTS.md`
2. `AGENTS.MD`
3. `CLAUDE.md`
4. `CLAUDE.MD`

One file wins per directory. An `AGENTS.md` next to a `CLAUDE.md` means the `CLAUDE.md` is not read for that directory.

### The discovery walk

Discovery starts at the working directory kli is running in and walks up the directory tree, stopping at the repository root. A directory holding `.git` (whether a directory or a worktree file) is the root, and the walk includes it. Outside a git repository, the walk continues up the full ancestor chain.

The walk gives you layered instructions. A context file at the repository root states project-wide conventions; a context file in a subpackage states conventions for that subpackage; both reach the model when you work inside the subpackage. kli orders the rendered section outermost first, so the root file comes before the deeper one, and the closest file is read last. A file that the global config directory contributes (`~/.config/kli/`) comes first of all, ahead of the repository chain. Files are deduplicated by path, so a single file reached two ways appears once.

## Overriding the system prompt

Two files change the base prompt directly rather than adding a section.

`SYSTEM.md` replaces the base prompt entirely. When kli finds it, the shipped identity-and-tools prompt is dropped and your file's contents take its place. The project context section still renders after it, so `AGENTS.md` and `CLAUDE.md` instructions remain in effect under a custom base.

`APPEND_SYSTEM.md` appends to the prompt. Its contents are added after the base (or after your `SYSTEM.md`, when both are present) and before the project context section. Use it to add standing instructions without discarding the identity and live tool list the base prompt carries.

kli reads these two override files from the project config directory `<repo>/.kli/` first, then the global config directory `~/.config/kli/`, and takes the first that has content. A blank or whitespace-only file is treated as absent, so an empty `SYSTEM.md` does not silently erase the base prompt.

The assembled order, top to bottom, is:

1. the base prompt, or your `SYSTEM.md` in full when present
2. `APPEND_SYSTEM.md`
3. the `# Project Context` section from `AGENTS.md` / `CLAUDE.md`

## The 2 MiB cap

kli reads a context or override file only when it is at most 2 MiB. A larger file is treated as absent: not truncated, not partially read, just skipped, and for context files the next candidate name in the directory is tried. The cap is a guard against a pathological file, a checked-in binary or a runaway log that happens to match a candidate name, not a budget on how much you can write. It sits at or beyond what a model can ingest in its context window, so a real instruction file does not approach it.

## How it stays current

The system prompt is rebuilt from these files on each submission, not cached at startup. Editing an `AGENTS.md` or a `SYSTEM.md` while kli is running changes what the model reads on your next message; there is nothing to reload. Each rebuild first removes the append block and project context section it composed last time, then composes fresh ones, so neither stacks up across turns.

## Related

- [The agent loop](/kli/concepts/the-agent-loop) — how the assembled prompt and your message become a model request
- [Files and paths](/kli/config/files-and-paths) — what lives under `<repo>/.kli/` and `~/.config/kli/`
- [Settings reference](/kli/config/settings) — the keys that configure a session


#### Tools and Hashline Edits


kli ties every edit to the exact lines the model last read. If those lines no longer match what is on disk, the edit is refused and nothing is written. This page explains how that works and why it is the default.

## What a read returns

When kli reads a file, it does not hand the model raw text. Each line comes back prefixed with an anchor: the line number, a short content hash, and the line itself, in the form `LINE:HH|content`. A read of a three-line file looks like this:

```
1:a3|def greet(name):
2:7f|    return f"hello {name}"
3:00|
```

The number is the line's position. The `HH` is two lowercase hex digits, a fold of an FNV hash over that line's raw text. It is short on purpose: it is a fingerprint of the line's content, not a checksum you read. Two lines with the same text get the same hash; change one character and the hash changes.

The model uses these anchors to refer to lines when it edits. An anchor names both where a line is and what it contained at read time.

## What an edit is

An edit in kli is a patch made of operations against anchors, not a new copy of the file. The patch groups operations under a file path and addresses lines by anchor. To replace lines 1 through 2 of the file above, the patch carries the anchors `1:a3` and `2:7f` together with the replacement text. To insert after a line, it names that one line's anchor. To delete a range, it names the start and end anchors.

Every anchor in the patch repeats the hash the model saw. That repetition is the safety mechanism, and it is the reason an edit is small. The model sends only the lines it wants to touch, each one carrying proof of which version it is touching.

## How an edit is validated

Before kli writes anything, it checks the patch against the file as it exists on disk right now. Two checks run, in order.

First, read-before-edit. kli keeps a per-file record of what the model last saw, keyed by the file's resolved path. If a patch names a file the model has not read in this session, the patch is rejected with a message telling the model to read the file first. The model cannot edit a file it has never seen.

Second, anchor re-hashing. For every file the patch touches, kli reads the current contents from disk, splits them into lines, and re-computes each line's hash. For each anchor in the patch, it checks two things: that the anchor's line number is in range, and that the anchor's hash equals the freshly computed hash of the line now at that position. If the line number points past the end of the file, the anchor is rejected. If the hash does not match, the anchor is stale and is rejected. The rejection message names the line and tells the model to re-read around it and resend.

The hash check compares against disk, not against the cached record of what the model saw. The cache only answers "did the model read this file." It cannot answer "is this anchor still good," because the file may have changed on disk since the read, from a build step, a formatter, another tool, or you. Only re-hashing the live file can catch that.

## Why a stale anchor rejects the whole patch

Validation is all-or-nothing per call. kli gathers every problem across every file in the patch first. If there is even one problem, it raises an error with all the problems listed and writes nothing. Files are written only after the entire patch validates clean.

This is the difference between an anchor-validated patch and a blind overwrite. A blind overwrite takes the new contents and replaces the file, whatever the file now holds. If the file changed under it, the overwrite erases that change without noticing. The damage is silent: the write succeeds, the file looks edited, and the lost change surfaces later as a confusing regression.

An anchored patch cannot do that. The hashes pin the edit to a specific version of each line. If line 2 was `return f"hello {name}"` when the model read it but is now something else, the anchor `2:7f` no longer matches, the patch is rejected, and the file keeps its current contents. The model gets back a precise message: anchor `2:7f` is stale, re-read around line 2. It re-reads, gets fresh anchors, and resends a patch built against the current file. The conflict turns into a retry instead of a lost edit.

The drift does not have to land on a line the patch edits. Because anchors carry line numbers and the file is re-split fresh, an insertion or deletion earlier in the file shifts every later line's number. An anchor that still has the right hash but the wrong line, or the right line number holding different text, fails the check. The patch only applies when its view of the file still holds.

## How this fits the rest of kli

This anchored read-then-edit cycle is one tool family among several, all of which run with full permission by default; kli has no per-action approval prompt. The safety here is not a gate you click through. It is a property of the edit format: an edit that does not match the file it claims to edit cannot be applied. For how kli decides what a tool may touch at all, see [Capabilities and fault barriers](/kli/concepts/capabilities-and-fault-barriers). For what happens when a tool call comes back as a problem the model has to resolve, see [The agent loop](/kli/concepts/the-agent-loop).


#### Capabilities and Fault Barriers


Out of the box, kli reads, runs, and edits your code without stopping to ask. There is no "allow this action?" prompt to clear, no per-command gate to babysit. You start kli in a project and it works on your code the way you would: it opens files, runs the shell, and applies edits directly. When you do want a session held back from some of that, you say so once, in writing, before the session starts. And when a piece of kli misbehaves, the failure is confined to that piece instead of taking down the program you are working in.

Two mechanisms produce that behavior: a capability subject that decides what a caller is allowed to do, and fault barriers that decide what happens when a caller breaks.

## Why there is no approval prompt

Every gated operation in kli runs under a *subject* — the capability-bearing identity of whoever is calling. Before a tool reads a file, runs a process, edits the context, or installs an extension, it asks the current subject whether it holds the matching capability. If it does, the call proceeds. If it does not, the call is denied.

The default subject is the *system subject*, and the system subject passes every check. It is the value in force at startup and for a normal boot. So under the default, every capability question gets the same answer — yes — which is why a fresh session does its work without ever interrupting you. There is no approval workflow because there is nothing to approve against: the default identity is already trusted with everything.

This is a deliberate choice, not a missing feature. An interactive prompt trains you to click "yes" without reading it, and a tool that asks before every file write is a tool you stop trusting to do real work. kli's position is that the decision about what an agent may touch belongs to you, made once, ahead of time, rather than to a dialog box in the middle of a task.

## Restricting a session with capabilities

You narrow what a session can do through the `capabilities` key in settings — `~/.config/kli/settings.json` for your global default, or `<repo>/.kli/settings.json` for one project. The key is an array of capability names, and its presence is what switches a session from "trusted with everything" to "trusted with exactly this list."

The three states are distinct:

- **Key absent.** The session keeps the system subject. Every gated tool is allowed. This is the default.
- **Key present, non-empty.** The session runs under a restricted subject that holds exactly the capabilities you named, and nothing else. A tool whose capability is not on the list is denied when it runs.
- **Key present, empty array (`[]`).** The session holds no capabilities at all. Every gated tool is denied. This is the most restrictive setting and the one to reach for when you want a read-nothing, run-nothing session.

A capability name implies the finer-grained capabilities it depends on. Granting `tools/standard`, for instance, grants the file read, file write, file edit, and process-execution capabilities that the standard toolset is built from — you do not have to enumerate each one. The set you write is closed under these implications before the session uses it, so naming a coarse capability is enough to admit everything it covers.

A malformed value — anything that is not an array of strings — is not treated as "deny all." kli warns that the setting was ignored and falls back to the system subject. The restriction has to be a well-formed list to take effect; a typo does not silently lock you out, and it does not silently grant you nothing either. (The warning surfaces in the transcript as a boot diagnostic, since the terminal takeover would otherwise wipe it.)

For the capability names you can put in the array and the tools each one gates, see [Capabilities](/kli/config/capabilities).

## How a fault stays contained

kli is one running program with everything else installed as a retractable extension — the model providers, the tools, the commands, the terminal UI. That design lets you change kli while it runs, and it also means a fault in one extension is, structurally, a fault inside the program you are using. Without containment, an extension that threw an error mid-render could crash the whole session and lose your work.

Crash barriers are what keep that from happening. A barrier wraps a *seam* — a place where extension or hot-patched code runs — and catches errors that escape it. (It catches ordinary errors only; it never swallows the serious conditions that signal the process itself is unsound.) When a fault crosses a barrier, three things can happen, and each barrier picks its policy for the seam it guards:

- **continue** — unwind the failed unit and return a fallback value. The fault is recorded; the session carries on as if that unit produced nothing.
- **reify** — do everything `continue` does, and additionally surface the fault to you, typically as an event in the transcript, so you see that something failed and where.
- **escalate** — decline to contain. The error keeps propagating outward, toward the next barrier or the process boundary. This is how a fault that should be loud stays loud.

Every contained fault is written to a per-seam log under the cache directory regardless of policy, so a failure is never silently lost even when the session continues. The diagnostic goes to a file, never to the terminal, because writing to the terminal would corrupt the live UI that the barrier is trying to protect — and a failure in the logging path itself loses the line and nothing else. Containment is the one job a barrier may not break, so reporting a fault can never cause one.

The result you feel is graceful degradation. A widget in the status bar that errors contributes no line that frame instead of breaking the bar. A render that faults skips the frame and tells you in the transcript. A misbehaving extension fails in place and the rest of the session keeps going.

Degradation is not unconditional, though. A seam that keeps faulting is a seam that is genuinely broken, and continuing to paper over it just hides the problem. The render barrier, for example, runs `continue` until its faults pile into a streak, then switches to `escalate` so a persistently broken renderer surfaces as a real failure rather than an endless run of skipped frames. The point of a barrier is to keep one fault from killing the app, not to pretend a fault never happened.

## How the two relate

Capabilities decide what a caller is *allowed* to do; barriers decide what happens when a caller *fails*. They are independent, and together they set the shape of a kli session: trusted by default and held back only on your explicit instruction, and able to survive the failure of any single part because no single part can take the whole down.

To put a restriction in place, see [Restrict what kli can do](/kli/guides/restrict-what-kli-can-do). For the live-kernel design that makes extensions — and therefore seams — the unit of both trust and containment, see [The live image](/kli/concepts/the-live-image). Capabilities bound what an agent is *allowed* to do, not what the kli process can *reach* on the host; for that boundary, see [Security model and sandboxing](/kli/concepts/security-model-and-sandboxing).


#### Security Model and Sandboxing


kli draws a hard line between two questions that are easy to confuse. *What is an
agent allowed to do?* is the authority question, and kli answers it precisely
through the capability lattice. *What can the kli process touch on this machine?*
is the containment question, and kli does not answer it at all. The process runs
with your privileges, and so does everything it does on your behalf.

> kli enforces **authority** — which capabilities an agent may exercise — not
> **containment**. By default nothing kli runs is isolated from the host: a
> granted shell command, file write, or `eval` acts with the full privileges of
> the kli process. For autonomous or untrusted use, run kli inside your own
> confinement (bwrap, a container, or a VM). The sandbox is the boundary; kli is
> not.

## Authority is not containment

Authority is decidable and kli enforces it. Every gated tool asks the current
subject whether it holds the matching capability before it acts, and a capability
the subject lacks is denied. You shape that authority up front through the
`capabilities` array — see [Capabilities and fault
barriers](/kli/concepts/capabilities-and-fault-barriers) for how the subject
decides, [Restrict what kli can do](/kli/guides/restrict-what-kli-can-do) for the
steps, and [Capabilities](/kli/config/capabilities) for the full vocabulary.

Containment is a different mechanism living in a different place: the operating
system, not kli. A capability decides whether the `bash` tool may run a command;
it does not and cannot decide what that command, once running, may read or write
on disk or send over the network. A shell granted `process/exec` runs `curl`,
`make`, and `rm` with the full reach of the kli process. Narrowing the capability
set reduces which *tools* the agent can reach; it never shrinks the *blast radius*
of the ones it can. That second job belongs to a sandbox you put around the whole
process.

## Why the boundary is the process, not the tool

It is tempting to want a sandbox bolted onto the `bash` tool alone — confine
shell-outs and leave the rest. That boundary is theatre. The `eval` tool runs
Common Lisp inside the live image, and the file tools (`read`, `write`, `edit`)
act on the host filesystem directly; both wield the process's full authority
without ever spawning a subprocess. A wrapper around `bash` would confine
shell-outs while `write` and `eval` kept unrestricted host access — a boundary
with a hole exactly where it matters.

The one boundary that contains every tool at once is the process boundary. A jail
around the kli process contains `bash`, `eval`, and the file tools together,
because all three draw on the same process privileges. So kli builds no per-tool
sandbox and instead makes whole-process confinement easy to stand up around it.

## See the authority a run will hold

Before you size a sandbox, see exactly what a run could do inside it. `kli
--print-authority` resolves the subject a session would hold — the configured
capabilities under the resolved profile — and prints its atoms and constraints,
then exits without reading a prompt or running an agent:

```sh
kli --print-authority
```

It defaults to the same profile `-p` uses; `--profile <name>` inspects another.
The headless attenuation flags apply here too, so you can preview a narrowed run:
`--read-only` drops `file/write`, `file/edit`, and `process/exec`; `--no-bash`
drops `process/exec`. Add `--json` for one machine-readable object:

```sh
kli --print-authority --read-only --json
```

The report tells you whether the run is universal (every capability), bounded to a
listed set, or holds nothing — the information you need to decide how tight the
surrounding confinement must be.

## Confine the kli process

The recipes below all do the same thing: bind the working directory writable,
mount the rest of the filesystem read-only, drop into isolated namespaces, and run
kli inside. They differ only in the mechanism your platform already has.

### The Nix sandbox option

If you build kli through the flake's producer, confinement is one option. It wraps
a fixed store entrypoint, so the wrapper lives *outside* the binary it confines —
nothing the model or a repo-local setting can switch off:

```nix
programs.kli = {
  enable = true;
  sandbox = {
    network = true;                 # set false to unshare the network namespace
    writablePaths = [ "${config.home.homeDirectory}/.cache/kli" ];
    denyRead = [ "${config.home.homeDirectory}/.aws" ];
    denyEnv = [ "AWS_SECRET_ACCESS_KEY" ];
  };
};
```

The same `sandbox` set is accepted by `mkConfiguredKli` in a dev shell and by the
NixOS module. The wrapper binds `$PWD` writable and `--chdir`s into it at run time,
`--ro-bind`s `/` for everything else, mounts a private `/dev`, `/proc`, and
`/tmp`, and sets `--unshare-pid --unshare-ipc` (bwrap drops the ability to gain
new privileges on its own — there is no `--no-new-privs` flag). `writablePaths`
adds extra writable binds; `network = false` adds `--unshare-net`; `denyRead`
masks paths and `denyEnv` unsets environment variables (both below).

### bwrap

The same confinement by hand, for any install:

```sh
bwrap \
  --ro-bind / / \
  --dev /dev --proc /proc --tmpfs /tmp \
  --unshare-pid --unshare-ipc \
  --bind "$PWD" "$PWD" --chdir "$PWD" \
  -- kli
```

Append `--unshare-net` to cut the network (read the network note below first).

### Docker or Podman

Run kli from an image that has it installed, mounting only the project:

```sh
docker run --rm -it \
  -v "$PWD:/work" -w /work \
  kli-image kli
```

The container is the filesystem boundary; nothing outside the mount is visible.
Add `--network none` to cut the network.

### systemd-run

Wrap a single transient unit with systemd's own sandboxing:

```sh
systemd-run --user --pty \
  -p ProtectSystem=strict \
  -p ReadWritePaths="$PWD" \
  kli
```

`ProtectSystem=strict` makes the filesystem read-only except `ReadWritePaths`; add
`PrivateNetwork=yes` to cut the network. Leave the path holding kli's config and
credentials readable, or the model API client cannot authenticate.

### A dev container

A `.devcontainer` that runs kli inside the container makes the container the
boundary for every session opened in it, with the container runtime governing what
the workspace can reach.

## Hide secret files from the agent

A capability cannot hide one file: `file/read` is all-or-nothing, so a session that
can read the project can read a secret sitting in it. The place to hide a specific
path is the mount namespace, where the mask covers `bash`, `read`, and `eval`
uniformly because it is in the kernel, not a per-tool filter.

With the Nix option, list the paths under `denyRead`. A file there reads as empty,
a directory reads as empty:

```nix
sandbox.denyRead = [
  "${config.home.homeDirectory}/.aws"
  "${config.home.homeDirectory}/.config/gh"
];
```

By hand, overlay the same masks after the read-only root — a file with `/dev/null`,
a directory with a tmpfs. Launched from a repo root, this hides a project-local
secret and your cloud credentials:

```sh
bwrap \
  --ro-bind / / \
  --dev /dev --proc /proc --tmpfs /tmp \
  --unshare-pid --unshare-ipc \
  --bind "$PWD" "$PWD" --chdir "$PWD" \
  --bind /dev/null "$PWD/.envrc.local" \
  --tmpfs "$HOME/.aws" \
  -- kli
```

This is the at-rest boundary: it takes the secret off *disk*. Its in-environment
twin is `denyEnv`, which keeps named variables out of every tool's *environment*
(next section). `denyRead` masks files; `denyEnv` unsets variables — both act at
the process boundary, so both cover `bash`, the file tools, and `eval` at once.

## Keep secret variables out of the environment

A secret often lives in the environment, not just on disk: a token exported into
the shell that launched kli is inherited by every shell-out. kli does not filter
the environment per tool — `eval` can read any variable through `posix-getenv`,
and a shell command can read `/proc/self/environ`, so a bash-only scrub is
theatre the same way a bash-only filesystem jail is. The place to drop a variable
is the process boundary, where the unset covers `bash`, the file tools, and
`eval` together.

With the Nix option, name the variables under `denyEnv`. Each is unset before the
confined process starts:

```nix
sandbox.denyEnv = [ "AWS_SECRET_ACCESS_KEY" "GH_TOKEN" ];
```

By hand, add an `--unsetenv` per variable to the same bwrap invocation:

```sh
bwrap \
  --ro-bind / / \
  --dev /dev --proc /proc --tmpfs /tmp \
  --unshare-pid --unshare-ipc \
  --bind "$PWD" "$PWD" --chdir "$PWD" \
  --unsetenv AWS_SECRET_ACCESS_KEY \
  --unsetenv GH_TOKEN \
  -- kli
```

`denyEnv` is a blocklist of names to remove, not an allowlist of names to keep: it
shrinks the inherited environment by the secrets you name and leaves the rest
intact, so command lookups and tool configuration still work.

## Network is all or nothing

Whole-process confinement makes the network all-or-nothing, because kli's model
API client shares the process with the tools. Cutting the network namespace cuts
the API along with everything else, so net-off is usable only with a model that
runs locally. There is no built-in per-destination filter: allowing the API while
blocking exfiltration to elsewhere is a filtering proxy you run in front of kli,
not a control kli provides. The headline protection of the easy sandbox is
therefore filesystem and process isolation, not network policy.

## Residual risks

A sandbox bounds the blast radius; it does not make autonomous execution safe. Name
these and plan for them:

- **Destruction inside the writable workspace.** Nothing distinguishes `rm -rf .`
  from legitimate work within the directory you bound writable. Version control and
  backups bound this; the sandbox does not.
- **Exfiltration over an allowed channel.** With the network on, an agent can send
  data anywhere it can reach. A filtering proxy in front of kli bounds this; kli
  does not.
- **Credential read-at-rest.** `file/read` is coarse, so any readable secret is
  readable. `denyRead` masks the paths you name; a broader mount or LSM policy
  covers the ones you forget.
- **A self-sandbox would be widenable.** A confinement the binary applied to itself
  could be loosened by injecting config. Keeping the wrapper external — a fixed
  entrypoint around the binary — is why the Nix option cannot be switched off from
  inside a session.

The throughline: kli is honest about being a non-provider of containment, tells you
the exact authority a run will hold, and makes the real boundary — a jail around
the whole process — easy to put in place. The sandbox is the boundary; kli is not.


#### Profiles


A profile is a named group of extensions kli boots with.

## A profile is a named group of extensions

kli is a small kernel with everything else installed on top as an extension: the
model providers, the tools, the commands, the terminal UI. A profile is the list
that says which of those to install at boot, under one name.

The list is built from groups of extension manifests. Three carry the substance:

- A **baseline** group every profile installs. It holds the parts kli needs to
  be an agent at all: the event system, the session log, the config layer, the
  agent loop, and the file, search, and shell tools.
- A **model-provider** group: the `anthropic`, `openai`, `openai-codex`, and
  `compatible` providers. A profile that talks to a model installs this; one that
  does not, leaves it out.
- A **terminal-UI** group: the chat view, the input editor, markdown rendering,
  the slash commands, completion. Only a profile meant to be driven by a person
  at a terminal installs this.

Every profile also carries a **nix-declared** group, spliced in right after the
baseline. It is empty in plain kli and holds whatever a Nix-configured image
declares at boot, so those extensions boot as baseline children. The
[profiles reference](/kli/config/profiles) lists exactly what each group installs.

A profile names the groups it wants and they install together as a unit. A
profile is nothing more than that explicit list, which is why the built-ins
differ only in which groups they include. The kernel itself never learns what a
profile is; it sees the install requests and nothing more. For why installing
and retracting extensions on a running kernel works at all, see
[The Live Image](/kli/concepts/the-live-image).

## The four built-in profiles

Each built-in is a fixed combination of those groups, plus a declaration of any
capabilities the profile expects you to supply.

- **`interactive-terminal`** installs the baseline, model-provider, and
  terminal-UI groups. This is the default — what you get when
  you run kli with no profile selected. It is the profile for sitting at a
  terminal and working with the agent.
- **`headless`** installs the baseline group only. No model providers, no
  terminal UI. It is the minimal agent core, the starting point for a profile or
  an embedding that wires its own providers and front end.
- **`human-in-loop`** installs the same groups as `interactive-terminal` and
  declares an `approval` seam — a named point a human-approval extension is meant
  to fill. The profile itself does not provide approval; it states that the slot
  exists so an extension can complete it.
- **`autonomous`** installs the baseline and the model providers but not the
  terminal UI, and declares `planner`, `scheduler`, `watchdog`, and `recovery`
  seams. It is the shape for an agent that runs without a person watching: it can
  talk to a model and use tools, with the supervision pieces left as seams for
  you to fill.

A seam is a capability a profile declares but does not provide. It is how a
profile names its own extension points without pretending to satisfy them. What
fills a seam is a separate extension, governed by the
[capabilities array](/kli/config/capabilities) and your installed extensions.

## How precedence picks the active profile

At boot kli resolves one profile name from the first of these that is set:

1. The `--profile <name>` command-line flag.
2. The `KLI_PROFILE` environment variable.
3. The `profile` key in your merged settings, where a project's
   `<repo>/.kli/settings.json` wins over the global `~/.config/kli/settings.json`.
4. The default, `interactive-terminal`, when none of the above names a profile.

The flag wins over the environment variable, which wins over settings, which
wins over the default. If the resolved name is neither a built-in nor a profile
declared in settings, kli warns and boots the default rather than failing. The
warning surfaces in the session, so a typo in a profile name does not leave you
guessing why you got the terminal you did not ask for.

## Profiles you define in settings

Beyond the four built-ins you can declare your own profile under the `profiles`
object in `settings.json`. A declared profile is a delta on top of a built-in,
with four fields:

- `extends` — the profile it builds on. With no `extends`, it bottoms out at
  `interactive-terminal`.
- `enable` — extension ids to add to the active set.
- `disable` — extension ids to remove from it.
- `settings` — a settings overlay that rides along while the profile is active.

Resolution walks the `extends` chain down to a built-in base, then folds the
deltas from the base up: a later profile in the chain has the last word on any
given extension id, and its settings merge over the earlier ones. A declared
profile cannot reuse a built-in name; that is reserved, and an entry that tries
to shadow one is ignored with a warning. A malformed entry is skipped the same
way, so one bad profile does not stop the rest from loading.

The `enable` and `disable` deltas gate your user extensions, the optional ones
you install yourself. They do not gate the built-in groups, which arrive with
the base. Whether a given user extension is installed at boot comes down to its
own configuration and the active profile's deltas together.

## Switching profile while kli runs

The `/profile` command lists the available profiles and live-switches between
them. A switch re-bases your user extensions onto the target profile's set —
installing the ones it wants that are absent, retracting the ones it does not —
and swaps in the target's settings overlay. Because the switch operates on a
running kernel, your context and session log carry across it.

One thing does not switch live: the built-in base. The base group is installed
once at boot, so switching to a profile with a different base (from
`interactive-terminal` to `headless`, say) cannot take effect in place. kli tells
you so and points you at restarting with `--profile <name>`. Everything that is
a delta on the same base switches in the running session.


#### Models, Providers, and Transports


kli does not bind a model to its wire protocol or its credentials. Three parts stay separate: a registry that lists what you can select, the providers that put entries in that list, and the transports that turn a selection into an HTTP call. That split is why you can run two providers side by side, switch between them mid-conversation, and add an OpenAI-compatible endpoint without touching the others.

## The registry: what you can select

There is one model registry in a running kli. It holds two kinds of entries. A **provider** entry records how to reach a vendor: an API style, a base URL, header and metadata config, and which credentials it needs. A **model definition** entry records a single model you can pick, keyed by its provider and model id, with its context window and whether it reasons. The model definition also carries the API style, so picking a model is enough to know how its call will be shaped.

The registry does not hold secrets and does not open sockets. It answers one question: given the credentials present right now, which models can you select? When you list models, the registry walks its definitions and keeps each one whose provider has a usable credential. A model whose key is not set never appears, so the list reflects what will actually run rather than the full catalogue.

Selecting a model records a current selection on the registry and, if a session is active, appends a model-change entry to the session log. Selection is plain state, so switching providers mid-conversation is the same operation as picking a model at the start.

## Providers: extensions that fill the registry

A provider is not built into the registry. It is an extension that, when it loads, registers its catalogue: an auth-provider, a credential reference, one provider entry, the model definitions, and the transport adapter for its API. The shipped providers:

- **anthropic** — Claude models on the Messages API. Reads the key from `ANTHROPIC_API_KEY`.
- **openai** — GPT models on the Responses API. Reads the key from `OPENAI_API_KEY`.
- **openai-codex** — GPT models through a ChatGPT account on the Responses API. Authenticates by OAuth rather than an API key.
- **compatible** — model entries you define for any OpenAI-compatible endpoint, declared in `~/.config/kli/providers.json`.

Because every provider registers through the same path, the registry treats them uniformly: a Claude entry and a self-hosted entry are the same kind of object, differing only in their recorded API and credentials. Adding a provider adds rows to the list and one transport adapter; it changes nothing about the providers already there.

The same uniformity runs in reverse. A provider is retractable: removing it drains exactly what it registered — its models, its provider entry, its credential reference, its auth-provider, and a reference to its transport adapter — and leaves the rest of the registry intact. Two providers that share a transport (openai and openai-codex both use the Responses API) share one adapter through a reference count, so retracting one keeps the other's transport in place.

The compatible provider reads its entries from a JSON file keyed by provider id. Each entry names a base URL, an API (`openai-completions` by default, or `openai-responses`), the environment variable that holds its key, and its models. Secrets stay out of the file; only the variable name lives there. A compatible entry registers through the same installer as the built-in providers, so a model you define behaves like a built-in one once it is in the registry.

## Transports: how a selection becomes a call

A transport is the adapter that streams one API shape. There are three, keyed by API style, not by vendor:

- **anthropic-messages** — the Claude Messages format. Sends the key in an `x-api-key` header.
- **openai-responses** — the OpenAI Responses format. Sends a bearer token, and for a ChatGPT account adds the account header.
- **openai-completions** — the OpenAI chat-completions format, for compatible endpoints that speak it. Sends a bearer token.

When you select a model and the agent needs a turn, the runtime reads the API from the provider, finds the registered adapter for that API, resolves the credential, and hands the request to the adapter to stream. The adapter converts kli's messages and tool descriptors into that API's JSON, opens the stream, and emits a normalized sequence of deltas — assistant text, reasoning, tool calls, usage, stop reason — that the rest of kli consumes without caring which vendor produced them.

Keying transports by API rather than by vendor is why one adapter serves more than one provider. openai and openai-codex are distinct providers with distinct base URLs and distinct credentials, but both register the `openai-responses` API, so both stream through the same Responses adapter. A new OpenAI-compatible endpoint reuses an existing transport by declaring an API the registry already knows, so it registers no adapter of its own.

## Why auth modes differ by provider

The credential mechanism is a property of the provider, not the model and not the transport. A provider declares its credential when it registers, and the auth layer holds a reference of the matching kind:

- **Environment key** (anthropic, openai, and most compatible entries) — the key is read from a named environment variable at call time. The reference stores the variable name, never the secret.
- **OAuth** (openai-codex) — kli runs a login flow and persists the tokens; the reference refreshes an expired access token before the call. There is no API key because a ChatGPT account does not issue one.
- **Static, persisted key** — a key you set once and kli stores, for providers without an environment variable.

The registry uses this only to decide availability — an environment provider is available when its variable is set, an OAuth provider when a usable token is on file — so the model list stays honest without reading any secret. The transport uses it to build the right header: the resolved credential becomes `x-api-key` for Messages and a bearer token for the OpenAI APIs. Different auth modes coexist in one session because each provider carries its own; an OAuth ChatGPT model and an environment-keyed Claude model are both selectable at the same time, and switching between them changes nothing about how the other is authenticated.

## Putting a provider to work

To add credentials and pick a model, see [Connect a Provider](/kli/guides/connect-a-provider). To define an OpenAI-compatible endpoint, see [Add a Compatible Provider](/kli/guides/add-a-custom-openai-compatible-provider). For the full list of shipped models, providers, and config keys, see the [model reference](/kli/models). For how a selection drives a turn, see [The Agent Loop](/kli/concepts/the-agent-loop).


## Extend

### Extend kli

#### Choosing an Altitude


kli extends at three altitudes. They differ by what they can do and how much of the
contribution you write, not by a cost you minimize. A few lines of Markdown give you a
slash command. A short instruction file gives the model a procedure it reaches for on
its own. Lisp gives you tools the model calls, interface changes, and behavior that
fires on events. Lisp is the native floor you can always reach, the same kind of object
kli itself is built from, not a last resort you fall back to. This page says what each
altitude can and cannot do, so you pick by what the task needs.

## Prompt templates

A prompt template is a Markdown file that becomes a slash command. The file's name is the command name, and its body is the text sent to the model when you run it. Drop `review.md` in `~/.config/kli/prompts/` (every session) or `<project>/.kli/prompts/` (one project), and `/review` types its body into the conversation as your message.

The body is a template, not a fixed string. Placeholders fill in from what you type after the command: `$1` and `$2` for positional arguments, `${@:2}` for everything from the second word on, `$ARGUMENTS` for the whole line. A frontmatter `description` and `argument-hint` show up in command listings. That is the entire feature.

Reach for a prompt template when you keep retyping the same instruction. A code-review prompt, a commit-message format, a "explain this file" request with your house conventions: anything you would otherwise paste from a notes file. You decide when it runs, because you type the command.

What it cannot do: a template cannot run code, call a tool, read a file on its own, or decide for itself when to act. It is one message, expanded and sent. The model never sees the command itself, only the text it expands to. When you want the model to pull in a procedure without being told, the next altitude does that.

See [Prompt Templates](/kli/extend/prompt-templates) for the full placeholder syntax.

## Skills

A skill is a `SKILL.md` file with a name and a description. The description is the load-bearing part: kli shows every skill's name and description to the model, and the model reads the skill's body itself, on its own initiative, when a task matches that description. You write the procedure once; the model decides when it applies.

That is the difference from a prompt template. A prompt template fires when you type its command. A skill fires when the model judges it relevant, so you do not have to remember it exists at the moment it would help. Put skills in `~/.config/kli/skills/<name>/SKILL.md` for every session or `<project>/.kli/skills/<name>/SKILL.md` for one project. kli also discovers `.agents/skills/` directories on the way up to the repository root, so skills you already keep for other agent tools are visible too.

A skill is still no code. The body is instructions: how to run a migration, the steps your test harness expects, the conventions a reviewer should apply. Files next to `SKILL.md` are referenced by relative path, and the model resolves them against the skill's own directory, so a skill can carry checklists, examples, or scripts the instructions point at. Skills can also be invoked deliberately, as a `/skill:<name>` command or by writing `$name` inside a prompt, and a skill marked `disable-model-invocation: true` is reachable only those ways and never offered to the model automatically.

Reach for a skill when the trigger is the task, not the keystroke: when you want a procedure followed whenever it fits, without you naming it each time. The work beyond a prompt template is writing a description sharp enough that the model loads the skill at the right moments and leaves it alone otherwise.

What it cannot do: a skill is still text the model reads. It cannot add a tool the model can call, change the terminal UI, bind a key, or run when an event happens. It can only describe what to do with the tools and commands kli already has.

See [Skills](/kli/extend/skills) for the `SKILL.md` format and discovery order.

## Lisp extensions

A Lisp extension is code. It can add a tool the model calls, a slash command backed by a function, a theme, a keybinding, a status-bar widget, a handler that fires on an event like a tool call, or a new method on existing behavior. kli itself is built out of these contributions, and an extension you write is the same kind of object as the program's own parts.

Extensions load from `~/.config/kli/extensions/` and `<project>/.kli/extensions/` as plain Lisp files, and `/reload` re-reads them into the running program. Because kli runs as one live image rather than a fixed binary, an extension installs into the program while it is running and retracts again without a restart. That is what lets you change a tool's behavior and try it in the same session, and it is why a contribution here is reversible rather than permanent: every contribution an extension adds carries a retractor that removes exactly what it installed. A command that replies with text is a handful of lines; you do not need the install/retract machinery in your head to write the first one.

Reach for a Lisp extension when Markdown hits its wall: you need the model to call something that does real work (hit an API, query a database, run a computation), you want behavior triggered by events rather than by the model or by you, or you want to change kli's interface, the themes, keys, and status line. It is the only altitude that adds capability rather than text, and it is where everything kli ships already lives.

Writing one is programming, in Common Lisp, against kli's extension vocabulary. The built-in `creating-extensions` skill walks through it, and the model can write an extension for you from a description, then reload and test it in the session with you.

See [Lisp Extensions](/kli/extend/lisp-extensions) and [The Live Image](/kli/concepts/the-live-image) for how extensions install and retract.

## Picking an altitude

Match the altitude to what the task needs:

1. **You retype the same instruction and want a command for it.** Prompt template. Markdown, no code, fires when you type it.
2. **You want a procedure followed whenever a task fits, without naming it.** Skill. Markdown plus a sharp description, no code, the model loads it on its own.
3. **You need a new tool, an event handler, or a change to the interface.** Lisp extension. Code, installed live, the only altitude that adds capability.

The altitudes compose rather than rank. A project commonly carries a few prompt templates, a couple of skills, and one extension that adds the tool those skills tell the model to use. Pick the altitude that can do the job, and reach for more than one when the job spans them.


#### Prompt Templates


You type `/review` in a session and kli sends a long, specific code-review
prompt to the model as if you had written it yourself. You wrote that prompt
once, in a file. That file is a prompt template.

A prompt template is a Markdown file. Its name, minus the `.md`, becomes the
slash command; its body is the text kli submits as your message. When you run
the command, the body enters the conversation as user input and reaches the
agent. The transcript still shows the short command line you typed, while the
model sees the full body. No code and no config schema: a file with a name and
some text.

This is the zero-code altitude of [extending kli](/kli/extend), and it is itself an
extension. The builtin `prompt-templates` extension scans your prompts directories
and registers one slash command per file, with a retractor that unregisters them on
reload; you supply the Markdown, it writes the effect.
Reach for it whenever you find yourself retyping the same instructions.

## Where templates live

kli reads templates from two places:

- `~/.config/kli/prompts/` — global, available in every session.
- `<repo>/.kli/prompts/` — per project, available only in that project.

A file named `review.md` in either directory gives you a `/review` command.
Project templates extend the global set and shadow a global template of the same
name, so a project can override `/review` with its own version. Discovery is not
recursive: kli reads `*.md` directly in those directories, not in
subdirectories.

## What the body can do

The body is plain Markdown, sent verbatim. It can also take arguments. When you
run `/review src/parser.lisp`, placeholders in the body expand from what you
typed after the command: `$1` becomes the first argument, `$ARGUMENTS` becomes
all of them. A template that needs no arguments simply omits the placeholders.

An optional frontmatter block at the top sets a `description` (shown in the
command list) and an `argument-hint`. Leave the frontmatter out and kli derives
the description from the first non-empty line of the body.

The full placeholder syntax and frontmatter keys live in the
[reference](/kli/extend/prompt-templates/anatomy). To make one now, follow
[Write a prompt template](/kli/extend/prompt-templates/write-your-first).


#### Prompt Template Anatomy


Drop a Markdown file named `review.md` into a `prompts/` directory and `/review` becomes a command you can run inside a session. Type it, and kli takes the file's body, fills in any arguments you passed, and submits the result as your next message to the model. A prompt template is a saved message you give a name. This page explains the parts of that file and how kli reads them, so you know exactly what `/review` will send before you run it.

## The file is the command

kli discovers prompt templates by scanning two directories for `*.md` files:

- `~/.config/kli/prompts/` — global templates, available in every project.
- `<repo>/.kli/prompts/` — project templates, available only when you start kli inside that project.

The scan is non-recursive. Only files directly in `prompts/` are read; subdirectories are ignored. The global directory is scanned first, then the project directory, so project templates extend the global set and a project file can shadow a global one of the same name.

The command name is the filename with `.md` removed. `review.md` is `/review`; `fix-ci.md` is `/fix-ci`. There is no name field in the file and no registry to edit. To rename the command, rename the file. To add one, add a file. This is why a template needs no installation step: putting it in the directory *is* the registration, and removing it unregisters the command.

## What the frontmatter carries

A template may open with a YAML frontmatter block — a `---` line, key/value pairs, a closing `---`. kli reads two keys from it, and only two.

**`description`** is the one-line summary shown when you list commands. It tells you and your collaborators what `/review` does without opening the file. If you omit it, kli derives a description from the first non-empty line of the body, truncated past 60 characters. A written description is worth the line, because the fallback is whatever happens to be your opening sentence.

**`argument-hint`** is the usage string shown beside the command, the part that reminds you what to type after the name — `<file>` or `[branch] [base]`, for instance. It is documentation for the human running the command. It does not validate or parse anything; the body decides how arguments are actually used.

Every other frontmatter key is ignored. The frontmatter is read as flat key/value pairs, and surrounding quotes on a value are stripped. If the file has no complete `---` … `---` fence, kli treats the whole file as body and the frontmatter as empty — so a template with no frontmatter at all still works, it just has a derived description and no hint.

## The body is the message, not a note to the model

Everything after the frontmatter is the template body. When you run the command, the body (with arguments substituted in) is submitted as your user message and enters the conversation exactly as if you had typed it. The model sees the expanded text. It does not see the file, the filename, or the frontmatter.

The command record itself is marked not model-visible. This is deliberate, not an oversight. The expansion already arrives as the user message through the normal submit path, so a visible command record would prepend a second, duplicate copy of the same text onto the very message the template just sent. Hiding the record keeps one message in the log: the expanded body, attributed to you. The transcript still shows the command line you typed, so you can see that `/review src/parser.ts` is what produced the message.

The practical consequence: write the body as the message you want the model to receive, not as instructions about the message. "Review the changes in $1 for correctness and style" is what the model reads. There is no separate layer where you describe the prompt to the agent; the body and the prompt are the same text.

## Loading is fail-soft, and bounded

kli reads templates at startup, and a bad file does not break the set. If one template is unreadable or malformed, loading it yields nothing and that file is skipped; the rest of your templates still register. A typo in one file's frontmatter costs you that one command, not all of them.

One file can be rejected on size. A template body flows verbatim into the model's context, so a single oversized file read at discovery could exhaust the space the conversation needs. kli caps a prompt template at 2 MiB; a file over the limit is skipped like any other unreadable one. Prompt templates are short messages, so the cap sits far above any reasonable template and exists to contain accidents, not to constrain real use.

## Related

- [Write a prompt template](/kli/extend/prompt-templates/write-your-first) — a recipe for creating one.
- [Argument substitution](/kli/extend/prompt-templates/using-arguments) — how `$1`, `$ARGUMENTS`, and slices expand in the body.
- [Run commands and eval Lisp](/kli/guides/run-commands-and-eval-lisp) — running commands inside a session.


#### Write Your First Prompt Template


A prompt template is a Markdown file that becomes a slash command. You type `/name` in a session, and kli sends the file's text to the model as your message. In this tutorial you'll write one template and run it. No code, just a file.

We'll build a `/review` command that asks kli to review the changes you've staged in git.

## Create the prompts directory

kli reads prompt templates from a `prompts/` folder inside your project's `.kli/` directory. Move into the root of any git project and create it:

```sh
mkdir -p .kli/prompts
```

## Write the template

Create the file `.kli/prompts/review.md`:

```sh
$EDITOR .kli/prompts/review.md
```

Put this in it:

```markdown
---
description: Review my staged changes
argument-hint: [focus]
---

Run `git diff --staged` and review the changes.

Look for bugs, missing error handling, and anything that would
break existing behavior. If I gave a focus area, pay attention
to it: $ARGUMENTS

Report what you find. Don't change any files yet.
```

The filename sets the command name: `review.md` becomes `/review`. Everything below the closing `---` is the body, the text kli sends to the model when you run the command.

Two things in the frontmatter shape how the command shows up:

- `description` is the one-line summary kli displays next to the command.
- `argument-hint` is the placeholder kli shows for whatever you type after `/review`.

`$ARGUMENTS` is a placeholder in the body. kli replaces it with whatever you type after the command name. Run `/review` with nothing and it expands to an empty string; run `/review error handling` and it expands to `error handling`.

Save the file.

## Run it

Start kli from the project root:

```sh
kli
```

kli finds your template at startup and registers `/review`. Type a single `/` in the prompt, and the completion list appears with `review` among the commands, your description beside it and `[focus]` as the hint.

Stage a change first so there's something to review:

```sh
git add -A
```

Back in the session, run the command:

```text
/review
```

kli expands the template body and sends it as your message. The model runs `git diff --staged`, reads the changes, and reports what it found. You wrote no code, and the diff review is now one command away.

Try it with a focus:

```text
/review concurrency
```

This time `$ARGUMENTS` expands to `concurrency`, and the model weights its review toward that.

## What you built

You have a working slash command in `.kli/prompts/review.md`. It lives in the project, so anyone who clones the repo and runs kli gets the same `/review`. Edit the file and start a fresh session to change what the command does.

From here, put the same file under `~/.config/kli/prompts/` to get the command in every project. For the full placeholder syntax, including arguments by position, see [Prompt Template Arguments](/kli/extend/prompt-templates/using-arguments).


#### Using Arguments


A prompt template is a Markdown file under `~/.config/kli/prompts/` or `<repo>/.kli/prompts/` that you run in a session as `/<name> ...`. Whatever you type after the command name becomes the template's arguments. This page shows how to read those arguments inside the template body. For the file format and frontmatter, see [Prompt template anatomy](/kli/extend/prompt-templates/anatomy).

Before substitution, kli splits the text after the command name into arguments: whitespace separates them, and single or double quotes group text into one argument and are dropped. So `/review src/auth.lisp "the login path"` produces two arguments: `src/auth.lisp` and `the login path`. There is no escape handling, and empty arguments never appear.

## Read one argument by position

Use `$N` to insert the Nth argument, counting from 1. The placeholder is replaced in place, so you can put it anywhere in a sentence.

```markdown
Review the file $1 and focus on $2.
```

Run with `/review src/auth.lisp "error handling"` and the body expands to:

```
Review the file src/auth.lisp and focus on error handling.
```

A position past the end of the supplied arguments expands to an empty string rather than an error. `$0` also expands to empty.

## Read a range of arguments

Use `${@:start:len}` to insert a slice of the arguments, joined by single spaces. `start` is the 1-based position of the first argument to take; `len` is how many to take.

```markdown
Compare these files: ${@:2:3}
```

Run with `/diff base.lisp a.lisp b.lisp c.lisp d.lisp` and the slice takes three arguments starting at the second, expanding to:

```
Compare these files: a.lisp b.lisp c.lisp
```

`len` is optional. Drop it to take everything from `start` to the end:

```markdown
Remaining paths: ${@:2}
```

If `len` runs past the end, the slice stops at the last argument.

## Read all arguments

`$ARGUMENTS` and `$@` both expand to every argument joined by single spaces. They are equivalent; use whichever reads better in the body.

```markdown
Run the test suite for $ARGUMENTS and report failures.
```

Run with `/test parser evaluator` and the body expands to:

```
Run the test suite for parser evaluator and report failures.
```

Because arguments are joined with single spaces, runs of whitespace and the quotes you typed do not survive here. `/test "the parser"` expands `$ARGUMENTS` to `the parser` without quotes.

## Read the unsplit text

`$RAW_ARGUMENTS` expands to everything you typed after the command name, verbatim. It is not split into arguments and not re-joined, so original spacing, quotes, and any characters that look like placeholders are kept literally.

```markdown
Commit message:
$RAW_ARGUMENTS
```

Run with `/commit fix:  handle "empty input" in $1 path` and the body expands to:

```
Commit message:
fix:  handle "empty input" in $1 path
```

The double space, the quotes, and the literal `$1` all survive. `$RAW_ARGUMENTS` is substituted after the positional, slice, and all-argument placeholders, so a `$1` sitting inside the raw text is never expanded a second time.

Reach for `$RAW_ARGUMENTS` when the body needs the input exactly as typed, such as a commit message or a free-form instruction. Reach for `$1`, `${@:start:len}`, `$ARGUMENTS`, or `$@` when you want the input split into discrete arguments.


#### Prompt Template Examples


Copy any file below into a prompts directory and it becomes a slash command. The filename minus `.md` is the command name, and the body is the prompt sent to the agent when you run it.

kli reads templates from two directories, both non-recursive:

- `~/.config/kli/prompts/` for commands available in every project.
- `<repo>/.kli/prompts/` for commands scoped to one repository.

The global directory is read first, so a project file with the same name extends or shadows the global set. The command registers when the prompts extension loads. For the full placeholder grammar and frontmatter fields, see [Prompt template anatomy](/kli/extend/prompt-templates/anatomy).

## Write a code review command

Save this as `~/.config/kli/prompts/review.md`. It runs as `/review`.

```markdown
---
description: Review the staged diff for bugs and unclear code
---

Review the currently staged changes.

Run `git diff --staged` and read the result. For each change, check for:

- Logic errors, off-by-one mistakes, and unhandled edge cases.
- Error paths that swallow or misreport failures.
- Names and comments that no longer match the code.

Report findings grouped by file, most serious first. If a change is
correct, say so briefly rather than padding the review. Do not edit
any files; this is a read-only review.
```

The `description` line is what appears next to `/review` in the command list. Without frontmatter, kli falls back to the first non-empty body line (truncated past 60 characters), so an explicit description keeps the listing readable.

## Write a commit-message command

Save this as `~/.config/kli/prompts/commit.md`. It runs as `/commit`.

```markdown
---
description: Draft a Conventional Commits message for the staged diff
---

Read the staged changes with `git diff --staged --stat` and
`git diff --staged`.

Write one Conventional Commits message for them:

- A `type(scope): summary` subject line, imperative mood, under 72
  characters.
- A body that explains why the change was made, wrapped at 72 columns,
  only when the diff needs it.

Print the message in a fenced block. Do not run `git commit` yourself.
```

Both commands above are fixed prompts: they take no input from the command line. Running `/review` sends the whole body to the agent verbatim.

## Pass arguments to a template

Trailing text after the command name becomes arguments. Whitespace separates them, and single or double quotes group text into one argument (the quotes are dropped). Reference positional arguments in the body with `$1`, `$2`, and so on, counted from 1. To pass every argument as one string, use `$ARGUMENTS`. The reference covers the rest of the placeholder grammar.

Save this template as `~/.config/kli/prompts/explain.md`. The `argument-hint` field shows the expected input next to the command name in the listing.

```markdown
---
description: Explain a symbol and where it is used
argument-hint: <symbol> [path]
---

Explain the symbol `$1` in this codebase.

Search for its definition and its call sites (limit the search to `$2`
if that path is given). Then describe, in two or three sentences:

- What `$1` does and what it returns.
- Who calls it and what would break if it changed.

Keep the explanation concrete and tied to the code you found.
```

Run it with arguments after the command name:

```text
/explain parseFrontmatter src/config
```

Here `$1` expands to `parseFrontmatter` and `$2` to `src/config`. A positional placeholder with no matching argument expands to an empty string, so `/explain parseFrontmatter` leaves the path clause empty rather than erroring.

When you want the trailing text passed through with no parsing, use `$RAW_ARGUMENTS`, which expands to the exact text after the command name. It is substituted last, so any placeholder-looking content inside it stays literal.

When you run any of these commands, the agent receives the expanded body as your message. Your transcript keeps the command line you typed (`/review`), while the model sees only the expansion.

Next steps:

- [Prompt template anatomy](/kli/extend/prompt-templates/anatomy) for the complete placeholder grammar and frontmatter fields.
- [/kli/extend/skills](/kli/extend/skills) for reusable instructions the agent loads on its own rather than commands you invoke.


#### Skills


You ask kli to cut a release. Without being told which file to look at, it reads
your release checklist, follows the steps in order, and stops where the
checklist says to stop. You wrote that checklist once as a `SKILL.md`. kli found
it, decided your request matched it, and loaded it. You never typed a command.

That is what a skill buys you over a prompt template. A skill is a `SKILL.md`
file the model can load by itself when the task at hand matches the skill's
stated purpose. You install the procedure once; the model reaches for it when it
is relevant, with no command from you.

This is still the zero-code altitude of [extending kli](/kli/extend), and like
prompt templates it is itself an extension: the builtin `skills` extension scans
your skills directories and registers each one as a command, retracting them on
reload. Like a prompt template, a skill is plain
Markdown with no code. The difference is who decides to use it.

## How the model finds a skill

At the start of a session kli scans for skills and advertises each one to the
model: its name, its description, and where the file is. The description is the
whole pitch. When the model judges that the task in front of it matches a
description, it reads the file and follows the body. So the description is not a
caption — it is the trigger. Write it to say plainly what the skill is for and
when it applies, because that sentence is what the model matches against.

The body stays on disk until it is needed. kli advertises the short description
always, and the model pulls in the full instructions only when a task calls for
them. A session that never touches the skill never reads its body, so the
length of the procedure does not weigh on the rest of your work.

## A skill is a folder

The unit is a directory whose name is the skill name and that holds a
`SKILL.md`:

```
release-checklist/
  SKILL.md
  template.md
  scripts/verify.sh
```

The `SKILL.md` body can point the model at the other files in the folder. When
it loads the skill, kli tells the model where the folder is and that references
resolve against it, so the body can say "run `scripts/verify.sh`" or "fill in
`template.md`" and the model knows where those live. A skill is therefore a
small bundle: the procedure plus whatever the procedure needs to hand to the
model.

A single `SKILL.md` with no companion files is also a skill. The folder is the
general shape; the lone file is the simple case of it.

## What goes in SKILL.md

The file opens with a YAML frontmatter block, and two keys carry the weight. A
`name` gives the skill its identity and its command; leave it out and kli uses
the folder name, which is the usual practice. A `description` is the text the
model matches against, so write it to say concretely what the skill does and
the situation it fits.

The description is the one key a skill cannot omit. A skill with no description
is dropped from the session, because the model would have nothing to match it
on. Everything after the frontmatter is the body the model reads once it loads
the skill: the procedure itself, in whatever Markdown you like. The exact
limits on each field live in the [reference](/kli/extend/skills/anatomy).

## When a skill beats a prompt template

The two split on one question: who decides to invoke the instructions.

A [prompt template](/kli/extend/prompt-templates) fires when you type its slash
command. You are in control, and you reach for it deliberately. That fits a
prompt you re-send on purpose — a code review you kick off, a commit message you
ask for.

A skill fires when the model recognizes the task, whether or not you mention it.
That fits a procedure that should apply whenever its situation comes up, even
when you did not think to name it: the house style for migrations, the steps for
filing a bug, the way this repo wants its changelog written. You encode the
knowledge once and let the model apply it in context.

Two more facts follow from this. A skill carries a folder of supporting files,
where a prompt template is a single Markdown file submitted as your message. And
a skill can hold a much longer body without weighing on every session, because
the model loads it only when it is relevant — a template's body is sent in full
every time you run it.

If you want a procedure you trigger on demand, write a prompt template. If you
want a procedure the model should apply on its own when the moment arrives,
write a skill.

## You can still invoke a skill yourself

A skill the model can reach is also a command you can reach. Each discovered
skill registers as `/skill:<name>`, so you can load `release-checklist`
yourself with `/skill:release-checklist` when you want it now rather than
waiting for the model to match it. You can also drop `$release-checklist` into a
message and kli expands that skill's body inline before sending. The skill is
the same either way; these are extra doors into it.

## Where skills live

kli discovers skills from several roots and merges them, with project skills
taking precedence over global ones, and a name seen twice keeping the first
copy. User-facing roots include `<repo>/.kli/skills/` for skills that belong to
one project and `~/.config/kli/skills/` for skills you want in every session.
kli ships a small set of built-in skills as well, and any skill of yours that
shares a name shadows the built-in one. The full discovery order and the rules
for what is skipped live in the [reference](/kli/extend/skills/anatomy).

To write one now, follow [Write a skill](/kli/extend/skills/write-your-first).


#### Skill Anatomy


A skill puts a set of instructions in front of the model at the moment a task
calls for them. You write the instructions once in a file. The model reads a one-
line summary of every skill on every turn, and when a task matches a summary it
loads the full file on its own. You can also load a skill yourself, by name. The
shape of the file is what makes both work.

A skill is a directory with a `SKILL.md` inside it. The file has a small YAML
frontmatter block and a Markdown body. The frontmatter is how kli finds and
advertises the skill; the body is the instruction text the model reads once the
skill is loaded. Everything that decides whether and how a skill reaches the
model lives in those few frontmatter keys.

## The frontmatter

Three keys appear in the frontmatter. One is required.

`description` is required. kli puts it in the list of skills it shows the model
each turn, so this is the text the model reads when it decides whether a task
matches. Write it to say what the skill is for and when to reach for it, not how
it works. A skill with no description is dropped at discovery and never reaches
the model. The description is capped at 1024 characters.

`name` is the identifier kli uses everywhere it refers to the skill: in the
advertised list, in the `$name` sigil, and in the `skill:<name>` command. It must
be lowercase, made of `a-z`, `0-9`, and hyphens, with no leading or trailing
hyphen and no two hyphens in a row, and at most 64 characters. It must match the
name of the directory that holds the `SKILL.md`. If you leave `name` out, kli
uses the directory name as the name. Setting it to anything that disagrees with
the directory is a validation warning, so in practice the directory name is the
name.

`disable-model-invocation` is optional. Set it to `true` and kli keeps the skill
out of the list it shows the model, so the model never loads it on its own. The
skill stays reachable by you, through the `$name` sigil and the `skill:<name>`
command. Use it for a skill you want on hand but never auto-loaded.

A `SKILL.md` is read whole, and its body lands in the model's context verbatim,
so kli reads at most 2 MiB of it. A file over that limit is refused at discovery
and refused again if it has grown past the limit by the time the skill is
loaded. Keep the body to instructions and link out to anything large.

## How kli finds a skill

kli discovers skills by walking a fixed list of directories. A directory that
holds a `SKILL.md` is a skill, and its own subdirectories are not searched
further. Directories without a `SKILL.md` are searched for nested skills.
Dotfiles, `node_modules`, and paths matched by a `.gitignore`, `.ignore`, or
`.fdignore` in the tree are skipped.

The directories are walked in a set order, and the first skill of a given name
wins. Later directories cannot replace a name already taken:

1. The project skills directory, `<repo>/.kli/skills/`.
2. `.agents/skills/` directories from the project outward to the repository root.
3. The global skills directory, `~/.config/kli/skills/`.
4. The user agents directory, `~/.agents/skills/`.
5. The skills that ship with kli.

Because the built-in skills come last, a skill of the same name in any of your
own directories takes precedence over the one kli ships. A second skill that
resolves to the same name as an earlier one is dropped and reported as a name
collision, so two skills cannot share a name.

## How a skill is invoked

A discovered skill reaches the model three ways.

The model loads it on its own. Each turn kli appends the list of advertised
skills to the system prompt, each as a name, a description, and a location. When
a task matches a description, the model reads the file at that location and works
from it. This is the path `description` is written for, and the one
`disable-model-invocation` turns off.

You write `$name` in your message. Typing `$review` puts the body of the `review`
skill in front of the model along with your message, before the turn runs. The
sigil only triggers at a word boundary and only for a name that matches a
discovered skill; `$total` in ordinary prose stays prose. When two skill names
share a prefix, the longer match wins.

You run `skill:<name>` as a command. Every discovered skill registers a
`skill:<name>` command whose description is the skill's. Running it submits the
skill body as your message, so the transcript keeps the command line you typed
while the model sees the full body. Anything you type after the name is passed
along after the body.

The first two paths read the description and the name straight from the
frontmatter; the third uses the name to build the command. A `SKILL.md` with a
clear name and a description that says when to use it is reachable all three ways
at once.

## Where to go next

Skills are the zero-code altitude of [extending kli](/kli/extend); see
[choosing an altitude](/kli/extend/choosing-an-altitude) for how they sit beside prompt
templates and Lisp extensions. To write one, follow
[Write a skill](/kli/extend/skills/write-your-first).


#### Write Your First Skill


A skill is a Markdown file of instructions kli hands to the model when a task calls for them. You write the instructions once; the model reaches for them on its own when your request matches what the skill is for. In this tutorial you'll write one skill and trigger it two ways. No code, just a file.

We'll build a skill that tells the model how to write a git commit message the way you like them: a short subject line, then a body that explains why the change was made.

## Create the skill directory

A skill is a directory holding a file named `SKILL.md`. The directory name is the skill's name, so kli reads the two together. Move into the root of any git project and make the directory:

```sh
mkdir -p .kli/skills/commit-message
```

`commit-message` is the name you'll use to call the skill. Keep skill names lowercase, with hyphens between words and no spaces.

## Write the skill

Create the file `.kli/skills/commit-message/SKILL.md`:

```sh
$EDITOR .kli/skills/commit-message/SKILL.md
```

Put this in it:

```markdown
---
name: commit-message
description: Write a git commit message for staged changes, following our subject-then-body format.
---

Run `git diff --staged` to see what changed.

Write a commit message with:

- A subject line under 50 characters, in the imperative mood
  ("Add", not "Added"), with no trailing period.
- A blank line.
- A body that explains why the change was made, wrapped at 72
  columns. Describe the reason, not a restatement of the diff.

Print the message. Don't commit anything yet.
```

The frontmatter is two lines that kli reads:

- `name` is how you call the skill. Match it to the directory name.
- `description` is one sentence saying what the skill is for and when to use it. This is the line the model reads to decide whether the skill fits the task in front of it, so write it as a trigger, not a label.

Everything below the closing `---` is the body: the instructions kli gives the model when the skill is invoked. Save the file.

## Start kli and confirm the skill loaded

Start kli from the project root:

```sh
kli
```

At startup kli walks `.kli/skills/`, finds your `SKILL.md`, and registers the skill. From here, the same skill triggers two different ways.

## Trigger it by name with `$`

Write `$` immediately followed by the skill's name anywhere in your message:

```text
$commit-message
```

kli sees `$commit-message`, matches it to the skill you wrote, and prepends the skill's body to your message before the model reads it. The model runs `git diff --staged`, then writes the message in your format. Stage a change first so there's something to describe:

```sh
git add -A
```

The `$name` sigil is for when you already know which skill you want. You're naming it on purpose. It also works mid-sentence, so you can fold it into a longer request:

```text
Stage the auth fix and then $commit-message for it.
```

kli expands `$commit-message` into the skill's instructions and leaves the rest of your sentence untouched. The model follows the skill and applies it to the auth fix you named.

## Trigger it by description

You don't have to name the skill. kli also shows the model every skill's `name` and `description` at the start of the session. When your request matches a skill's description, the model loads the skill itself. Ask for the thing the skill is for, without the `$`:

```text
Write a commit message for what I've staged.
```

The model reads its list of skills, sees that `commit-message` is described as writing a commit message for staged changes, and loads the body on its own. You get the same formatted message, and you never typed the skill's name. The `description` you wrote is the line the model matched against.

## What you built

You have a working skill at `.kli/skills/commit-message/SKILL.md`. It lives in the project, so anyone who clones the repo and runs kli gets the same skill. Edit `SKILL.md` and start a fresh session to change what the model does.

To see how the `description` advertisement and the `$name` sigil work, the directories kli searches beyond the project, and the rest of the frontmatter you can set, read [Skill anatomy](/kli/extend/skills/anatomy).


#### Authoring and Discovery


A skill is a `SKILL.md` file in its own directory. kli finds skills by name from a fixed set of locations, makes each one runnable as `skill:<name>`, and expands a `$name` sigil in your prompt into that skill's content. This page covers where to put a skill so kli finds it, how to override a builtin, and how to invoke a skill once it is found.

## Place a skill where kli looks

kli searches these locations, in this order, and stops at the first skill it finds for any given name:

1. The project skills directory: `<repo>/.kli/skills/`
2. `.agents/skills/` in each directory from the working directory up to the repo root, nearest first
3. The global skills directory: `~/.config/kli/skills/`
4. `~/.agents/skills/`
5. The skills shipped inside kli (the builtins)

To add a skill to one project, create its directory and `SKILL.md` under `.kli/skills/`:

```
<repo>/.kli/skills/run-migrations/SKILL.md
```

To make a skill available in every project, put it under `~/.config/kli/skills/` instead. The two `.agents/skills/` locations are read the same way kli reads its own skills, so a skill written for another agent that follows the Agent Skills layout is discovered without changes.

A skill's name comes from the `name` field in its `SKILL.md` frontmatter; with no `name` field, kli uses the directory holding the file. Names are lowercase letters, digits, and hyphens. The `.kli/skills/` and `~/.config/kli/skills/` directories also load a plain `.md` file placed directly in them as a single skill; the `.agents/skills/` and builtin locations load skills only from subdirectories that contain a `SKILL.md`.

The repo root bounds the upward walk. kli treats a directory holding `.git` as the root and does not look above it. Dot-directories and `node_modules` are skipped during the search, and `.gitignore`, `.ignore`, and `.fdignore` rules under a skills directory exclude matching paths.

## Override a builtin by name

The builtins sit last in the search order, so any skill you write with the same name takes precedence. kli keeps the first skill it finds for a name and drops every later one. To replace a builtin named `creating-extensions` for one project, create a skill with that name in the project directory:

```
<repo>/.kli/skills/creating-extensions/SKILL.md
```

The project skill now answers to `skill:creating-extensions` and to the `$creating-extensions` sigil; the builtin no longer loads. The same rule shadows a global skill from a project, or a builtin from `~/.config/kli/skills/`. A name that collides between two locations is reported as a diagnostic at startup so the shadowing is visible.

## Reference a skill with the $name sigil

Write `$` immediately followed by a skill name anywhere in a prompt, and kli prepends that skill's content before the prompt is sent. The reference itself stays in your text. To pull in the `run-migrations` skill:

```
$run-migrations against the staging database
```

kli reads the longest skill name that matches at the `$`. If you have both `run` and `run-migrations`, `$run-migrations` resolves to `run-migrations`, not `run`. The match must end at a boundary: the character after the name must be something other than a letter, digit, or hyphen (end of line counts). So `$run-migrations` matches but `$run-migrationsx` does not, because the name would have to continue.

A `$` only opens a reference when the character before it is not a letter, digit, or another `$`. This keeps `cost$run` and `$$run` from being read as skill references. A `$name` that matches no discovered skill stays as ordinary text, so `$5` is left alone unless you have a skill whose name starts with `5`. Each referenced skill is added once, in the order the references first appear.

## Run a skill with skill:name

Every discovered skill registers a command named `skill:<name>`. Run it from the session to load that skill's content as input:

```
skill:run-migrations
```

Anything you type after the name is passed to the skill as arguments:

```
skill:run-migrations --dry-run
```

The command reads the `SKILL.md` body fresh each time it runs, so editing a skill takes effect on the next invocation without a restart. The transcript keeps the command line you typed while the model receives the skill content.

## Related

- [Skill anatomy](/kli/extend/skills/anatomy) for the `SKILL.md` format and frontmatter.
- [Commands](/kli/commands/slash-commands) for how `skill:<name>` fits alongside other session commands.


#### Skill Examples


Each section below is a complete `SKILL.md` you can drop into a skills directory
and use. Pick the one whose shape matches what you want, copy it, and edit the
frontmatter and body. Put the file at `<repo>/.kli/skills/<name>/SKILL.md` for a
skill that belongs to one project, or `~/.config/kli/skills/<name>/SKILL.md` for
one you want in every session. Leave `name` out and kli uses the folder name; set
it to something other than the folder name and kli keeps your `name` but warns.

For the discovery rules these examples rely on, see the
[skills reference](/kli/extend/skills/anatomy). For why skills exist and how the model
reaches them, see [Skills](/kli/extend/skills).

## A domain-knowledge skill

This is the common case: a procedure or house rule the model should follow on
its own whenever a matching task comes up, without you naming it. The body is
the knowledge; the description is what the model matches your request against, so
it states plainly what the skill covers and when it applies.

Put this at `<repo>/.kli/skills/writing-migrations/SKILL.md`:

```markdown
---
name: writing-migrations
description: House rules for database migrations in this repo - file naming, the up/down structure, and the backfill-then-constraint ordering. Use when writing, reviewing, or editing a schema migration.
---

# Writing migrations

Every migration is reversible and lands as one file under `db/migrate/`.

## File and naming

- One change per file. Name it `<utc-timestamp>_<verb>_<subject>.sql`,
  e.g. `20260619T0930_add_email_to_users.sql`.
- Each file has an `-- up` section and a `-- down` section. The down section
  must return the schema to its prior state exactly.

## Ordering rules

- Add a column nullable first, backfill it in a separate statement, then add
  the `NOT NULL` constraint. Never add a non-null column with a default to a
  large table in one step.
- Create an index `CONCURRENTLY`. A plain `CREATE INDEX` locks the table.

## Before you finish

- Confirm the down section drops exactly what the up section created.
- Note the expected row count touched by any backfill in a comment above it.
```

The model loads this only when the description matches the task in front of it,
so the body can be as long as the procedure needs.

## A tool-recipe skill

A tool recipe is a step list for using a command-line tool the right way: the
flags that matter, the order to run things in, what to check after. It packages
operational knowledge the model would otherwise have to guess at.

Put this at `~/.config/kli/skills/profiling-with-perf/SKILL.md`:

```markdown
---
name: profiling-with-perf
description: Recipe for CPU-profiling a running process with perf and turning the result into a flamegraph. Use when asked to profile, find a hot path, or explain where time goes in a process.
---

# Profiling with perf

Sample a running process, fold the stacks, and render a flamegraph.

1. Find the target pid: `pgrep -f <process-name>`.
2. Record for ten seconds at 99 Hz, capturing call graphs:

   ```sh
   perf record -F 99 -p <pid> -g -- sleep 10
   ```

3. Collapse the samples and render:

   ```sh
   perf script | stackcollapse-perf.pl | flamegraph.pl > flame.svg
   ```

4. Read the widest frames in `flame.svg` from the bottom up. The widest box
   that is not a scheduler or idle frame is the hot path.

If `perf record` reports no samples, the process is mostly idle or blocked on
I/O; switch to `perf record -e sched:sched_switch` to see where it waits.
```

A tool recipe often pairs with companion files. If the body says to run
`scripts/setup.sh`, put that script beside `SKILL.md` in the folder; kli tells
the model the folder location and that references resolve against it.

## A sigil-invoked skill

You can pull any skill into a message yourself by writing `$<name>` in the
prompt. kli expands that skill's body inline before sending, so a sigil is the
way to reach for a skill on the spot. To make a skill *only* reachable that way
and by command, and keep it out of the model's automatic matching, add
`disable-model-invocation: true` to the frontmatter. The skill then never shows
up in the advertised list, so the model will not load it on its own; you invoke
it with `$<name>` or `/skill:<name>`.

Put this at `~/.config/kli/skills/explain-like-staff/SKILL.md`:

```markdown
---
name: explain-like-staff
description: Rewrite an explanation for a staff-level engineer - lead with the tradeoff, drop the basics, name the failure modes. Invoke by hand when you want this lens applied.
disable-model-invocation: true
---

# Explain like staff

Rewrite the explanation that follows for a staff-level engineer.

- Open with the decision and its tradeoff, not with background.
- Assume fluency in the domain. Cut definitions of standard terms.
- Name the failure modes and the conditions that trigger each one.
- State what you would measure to know the choice was right.
```

In a message you would then write:

```
$explain-like-staff Here is the draft of the caching section: ...
```

kli prepends the skill body to your message before it reaches the model. A
`$name` that matches no discovered skill stays as plain text, so ordinary prose
containing a dollar sign is untouched.

## A skill that shadows a built-in

kli ships a small set of built-in skills, and they sit last in discovery order.
Any skill of yours that has the same name as a built-in wins, because the first
skill found under that name is the one kept and your directories are searched
first. Give your skill the built-in's exact name to replace its body with yours.

To shadow the built-in `creating-extensions` skill with your own house version,
put this at `~/.config/kli/skills/creating-extensions/SKILL.md`:

```markdown
---
name: creating-extensions
description: Author kli user extensions in Common Lisp - commands, event handlers, and tools loaded from ~/.config/kli/extensions/ with hot reload via /reload. Use when asked to create, modify, or debug a kli extension. Adds our team's conventions on top of the basics.
---

# Creating kli extensions (team conventions)

Follow the standard extension shape, with these additions for our codebase.

- Name every extension `<team>-<purpose>`, e.g. `payments-deploy-guard`.
- Project-specific extensions go in `<repo>/.kli/extensions/`. Only
  cross-project tools go in `~/.config/kli/extensions/`.
- Every `effect` contribution must pair an installer with a real retractor.
  Reverting must drain exactly what installing created.

## The minimal shape

```lisp
(defextension payments-greet
  (:provides
   (command "pay-greet"
     :description "Greet the payments on-call."
     :arguments '(:tail :name)
     :handler (lambda (command arguments context &key call-id on-update)
                (declare (ignore command context call-id on-update))
                (reply (format nil "Hi ~A, you are on call."
                               (or (rest-arg arguments) "there")))))))
```

After writing the file, run `/reload`, then check `/extensions` shows it enabled.
```

Because your file is found before the shipped one, the model and the
`/skill:creating-extensions` command both load your version. If you remove your
copy, the built-in returns on the next discovery pass. Naming must be exact: a
different name does not shadow, it adds a second skill.

## Verify a skill loaded

After you add or edit any of these files, kli re-discovers skills on the next
session start. Confirm the result by invoking the skill yourself with
`/skill:<name>` — every discovered skill registers under that command, so a
skill that runs there is one kli found and parsed. A skill with no `description`
is dropped silently, so if `/skill:<name>` is missing, check the frontmatter
first.


#### Lisp Extensions


A Lisp extension lets you give the model a tool it can call, back a slash command with a function, bind a key, change the theme, change how a tool's output is drawn, or run code when something happens in the session. This is where you stop describing what kli should do and add behavior it did not have, and where you can change that behavior and try it in the same session, without restarting.

The zero-code altitudes are text. A prompt template is a message you send; a skill is a procedure the model reads. Neither can run code, call out to a system, or touch the interface. When you need any of those, you write an extension. This is not a fallback for when Markdown runs out: it is the native floor, the same kind of object kli itself is built from.

## What an extension adds

An extension is a list of contributions. Each contribution is one named thing the extension installs into the running program, and each kind of contribution is a different thing the model, the session, or the interface gains. The kinds you reach for:

- **Tool.** A function the model can call by name, with a description, a parameter schema, and a runner that does the work. This is how the model hits an API you have, queries your database, runs a computation, or drives a system kli does not know about. The runner returns content the model reads back, and the tool can carry a renderer that controls how its call shows up in the terminal.
- **Command.** A slash command backed by a function rather than a Markdown body. Where a prompt template expands to text, a command runs code when you type it — inspect the session, write a file, call into the program, print a result.
- **Keybinding.** A key bound to an action in the terminal interface.
- **Theme.** A palette the interface draws with.
- **Renderer.** Code that decides how a message or a tool call is drawn in the terminal, so you can change what you see without changing what the model does.
- **Status-bar slot and widget.** A piece of the interface that shows your own state.
- **Event handler.** A function that fires when something happens — a tool call, a turn boundary, an event your own code emits — so behavior can be triggered by the session rather than by you or the model.
- **Method.** A new method on an existing generic function, which is how you adjust behavior kli already has instead of adding something beside it.

You are not working with a separate plugin API bolted onto the side of kli. kli itself is built out of these same contributions: the model providers, the tools that read and edit your files, the slash commands, and the terminal interface are all extensions, installed at startup the same way yours installs. An extension you write is the same kind of object as the program's own parts, which is why it can reach the same places they do.

## Where extensions live and how they load

Extensions are plain Lisp files. kli reads them from `~/.config/kli/extensions/` for every session and from `<project>/.kli/extensions/` for one project. A file declares an extension with a name, what it requires, and what it provides, and kli installs it on startup.

`/reload` re-reads those files into the running program. It retracts every user extension currently installed, re-indexes the files on disk, and installs them again — so the loop is edit the file, run `/reload`, use the change, with no rebuild and no restart. A file that fails to load is reported and skipped; the rest keep working, and you fix it and reload again.

## Recoding while it runs

The thing this tier gives you beyond capability is that the capability is editable in place. kli runs as one live program rather than a fixed binary, so an extension installs into the session while it is running and can be replaced or removed without ending it.

Replacing an extension is a single operation. kli deactivates the running version — draining the tools, commands, keybindings, and methods it had installed — then activates the new source. If the new version fails to come up, kli brings the old one back and reports the error, so a broken edit leaves you where you started instead of in a half-applied state. This is why you can change a tool's behavior, reload, and call it again in the same conversation, watching the difference turn by turn.

Removal is the same symmetry from the other side. Every contribution an extension adds has a matching way to remove it, and deactivating an extension takes out exactly the pieces it installed and nothing else. Your context, your session log, and your model connection are untouched by adding or removing an extension. [The Live Image](/kli/concepts/the-live-image) covers the mechanism behind this; you do not need it to write an extension, but it is the reason the edit-reload-try loop exists.

## What it costs

Writing an extension is programming, in Common Lisp, against kli's extension vocabulary. A command that replies with a fixed string is a few lines; a tool that does real work is as much code as the work takes. The altitudes compose rather than rank: a project commonly carries a few prompt templates, a couple of skills, and one extension that adds the tool those skills tell the model to use. [Choosing an altitude](/kli/extend/choosing-an-altitude) lays out what each can and cannot do.

You do not have to write the Lisp yourself. The built-in `creating-extensions` skill walks the model through authoring one, so you can describe the tool or command you want and have the model write, reload, and test it in the session with you.

Adding a tool means the model can now call it, which is also something you may want to restrict. A tool can declare the capabilities it needs, and kli refuses the call if the current session does not hold them. See [Capabilities and fault barriers](/kli/concepts/capabilities-and-fault-barriers) for how that gating works.

## Related

- [Choosing an altitude](/kli/extend/choosing-an-altitude) — what a Lisp extension can do that a template or skill cannot, and when each is enough.
- [The Live Image](/kli/concepts/the-live-image) — how extensions install, retract, and recode without a restart.
- [Sharing extensions](/kli/extend/sharing-extensions) — handing an extension to someone else, including the `/install <url> <git-tree-sha1>` consent flow.
- [Tools](/kli/commands/tools), [Slash commands](/kli/commands/slash-commands), [Themes](/kli/commands/themes), [Keymap](/kli/commands/keymap) — the built-in contributions an extension extends.


#### Lisp Extension Anatomy


You write one `defextension` form, drop it in an extensions directory, and run
`/reload`. Your command, tool, or event handler is live in the running session,
and `/disable` takes it out again with nothing left behind. That round trip —
add it, use it, remove it cleanly — is what an extension's structure is built to
guarantee. This page explains the structure that makes the guarantee hold.

## The form

An extension is a `defextension` form with a name and clauses:

```lisp
(defextension my-extension
  (:requires ...)
  (:provides ...)
  (:metadata ...))
```

`:requires` lists what must already be present for the extension to install —
capabilities, providers, other extensions, tools. `:provides` lists what this
extension adds: its contributions. `:metadata` is an optional plist for
properties like `(:autoload nil)`. Most extensions need only `:provides`;
requirements for the common contribution kinds are derived automatically, so a
`command` clause already carries its dependency on the commands capability
without you naming it.

The name matters beyond labeling. `defextension greet` binds a variable named
`*greet-extension-manifest*`. That variable does not hold an installed
extension. It holds a function of no arguments that, each time you call it,
builds a fresh extension value.

## Manifest as value

The function bound to `*greet-extension-manifest*` is the manifest. Calling it
returns an `extension` value: a record carrying the id, the list of
requirements, and the list of contributions, with each contribution still inert
data. Nothing has touched the running session yet. You can build this value,
inspect it, pass it around, and discard it, and the session is exactly as it
was.

A thunk rather than a single prebuilt value is deliberate. Each call materializes
new contribution objects with their own storage, so the same manifest installs
into many protocols — a REPL, the production boot, a test, an agent's
sub-session — without sharing mutable state between them. The manifest is the
recipe; calling it bakes a fresh batch.

This is the same shape everywhere in kli. The model providers, the tools, the
slash commands, the terminal interface — each is a manifest bound to a
`*...-extension-manifest*` variable, and each is installed the same way you
would install your own. There is no privileged built-in path. You can read these
as real `defextension` forms: the builtin `bash` tool extension, the builtin theme
extension, and cairn as a full external one, a single manifest with a store-opening
effect, its model tools, a live context hot-patch, and its own slash commands, each
carrying a retractor.

## The one step that mutates

Turning the value into running behavior is a single operation:

```lisp
(install-manifest manifest protocol context)
```

`install-manifest` calls the thunk to get a fresh extension, then activates it
against the protocol. Activation is where every effect happens, and it happens in
a recorded way. It first checks the extension's requirements and errors if any
are unmet. Then it walks the contributions in order and installs each one,
pushing every installed contribution onto the protocol's record as it goes. If
any contribution fails midway, activation retracts the ones that already
installed and re-signals the error, so a failed install leaves the protocol where
it started rather than half-changed.

`install-manifest` returns the activated extension. That return value is the
handle you keep, because it is what removal takes:

```lisp
(deactivate-extension protocol extension context)
```

Deactivation reads back the contributions this extension installed and retracts
each one, then forgets the extension. These two calls are the entire lifecycle.
Everything else — `/install`, `/reload`, `/enable`, profile bundles, the boot
sequence — drives these same two operations underneath.

## Contributions and their retractors

A contribution is one unit of behavior an extension provides. The closed kinds
the protocol knows directly are a model-callable tool, a capability provider, a
provider contract, a generic-function method, a live object, and a raw effect.
Other kinds — commands, event handlers, event types, keybindings, themes, message
renderers, status slots, widgets, profiles, settings declarations — are themselves
contributed by extensions that teach the protocol a new kind. A command, for one, is its own
kind: installing it registers a slash command against the commands provider, and
retracting it unregisters that command. The kind taxonomy is extensible the same
way everything else is.

Every kind, without exception, pairs an installer with a retractor. Installing a
tool registers it and makes it callable; retracting it removes it from the
registry. Installing a capability provider files it under its name; retracting it
removes that entry. A method contribution installs a real method on the named
generic function and removes it with `remove-method` on retraction. The pairing
is not a convention you opt into — it is how each kind is defined, so there is no
kind that can be installed but not removed.

The `effect` kind is the general case for behavior that does not fit a named
kind:

```lisp
(effect "my-effect" installer retractor)
```

The installer and the retractor are both functions of `(protocol contribution
context)`. The installer's return value is stored as the contribution's state,
and the retractor reads it back through `(kli/ext:contribution-state
contribution)` to undo precisely what the installer did. The retractor is
required. When an effect genuinely has nothing to clean up you pass `:no-op`
explicitly, which records the choice rather than letting it pass silently. The
duty an effect author carries is symmetry: the retractor must drain exactly what
the installer created — unregister what it registered, restore what it replaced —
because the protocol will call it expecting the session to return to its prior
state.

## Why reversibility is total

Removing an extension drains every contribution it installed and nothing else.
That holds because of how the two halves fit together. Installation records each
contribution as it lands, so removal has an exact list to work from rather than a
guess. Each kind defines its own retractor, so there is no contribution the
remover does not know how to undo. And state lives in per-protocol storage keyed
by the extension, not in global variables, so dropping the protocol drops the
state with it. A global `defvar` for extension state breaks this — a second
protocol overwrites it, and retraction cannot reach it — which is why it is
treated as a bug.

The payoff is the round trip you started with. Because installing is a recorded
transaction and every kind is reversible, `/disable` and `/reload` can take an
extension out mid-session and leave the rest of the session — your context, your
log, your model connection — untouched.

## Where extensions load from

User extensions are plain Lisp files on disk. kli reads them from several roots.
Files under `~/.config/kli/extensions/` load in every session; files under
`<project>/.kli/extensions/` load only in the project kli was launched in. Extra
roots come from the `"extension-dirs"` list in `~/.config/kli/config.json`, and
`kli --extension PATH` loads one file or directory for a single run.

A single `.lisp` file is one extension. A directory containing
`extension.lisp` is one extension unit, loading its files in order with
`extension.lisp` last. A directory without `extension.lisp` is a group: its loose
files are single-file units and its subdirectories recurse. Exactly one
`defextension` per unit; zero or two is an error and the unit is skipped.

When kli loads a source file, it binds the defining protocol so the
`defextension` form not only binds its manifest variable but registers the
manifest for that protocol, which is what lets `/reload` re-index from disk and
reinstall the enabled set. Loading is fail-soft: a broken file warns and is
isolated while the rest keep working, so one bad extension does not take down the
others.

## Related

- [The Live Image](/kli/concepts/the-live-image) — why behavior is editable while
  kli runs, the mechanism this anatomy rests on.
- [Capabilities and Fault Barriers](/kli/concepts/capabilities-and-fault-barriers)
  — the capability set that gates installing, retracting, and recoding.
- [Profiles](/kli/concepts/profiles) — how groups of extensions are bundled and
  selected.


#### Write Your First Lisp Extension


By the end of this page you will have a working slash command, `/greet`, that you wrote, loaded into a running kli, edited, reloaded without restarting, and switched off. You will do all of it against one live session.

You write an extension as a Common Lisp file on disk. kli reads the file and installs the command it declares. There is no build step and no restart.

## Create the file

Extensions in `~/.config/kli/extensions/` load in every session. Create that directory if it does not exist, then write a file named `greet.lisp` inside it.

```lisp
(defextension greet
  (:provides
   (command "greet"
     :description "Greet someone by name."
     :arguments '(:tail :name)
     :handler (lambda (command arguments context &key call-id on-update)
                (declare (ignore command context call-id on-update))
                (reply (format nil "Hello ~A!"
                               (or (rest-arg arguments) "world")))))))
```

That is the whole extension. Reading it line by line:

- `defextension greet` names the extension `greet`.
- `(command "greet" ...)` declares the slash command. The string is the name you type after the slash.
- `:arguments '(:tail :name)` captures everything typed after `/greet` as one free-text tail.
- The handler signature `(command arguments context &key call-id on-update)` is fixed; declare-ignore the parameters you do not use.
- `(rest-arg arguments)` returns that captured tail, or `nil` when you typed nothing after the command name.
- `(reply text)` builds the result kli shows.

A single `.lisp` file loads in the `kli/author` package, so `defextension`, `command`, `reply`, and `rest-arg` are available unqualified. You import nothing.

## Load it into the running session

Switch to your kli session and run:

```
/reload
```

`/reload` re-reads every extension file on disk and installs what it finds. kli prints the list of user extensions it now knows about; `greet` is among them, marked enabled.

Now run the command:

```
/greet Ada
```

kli answers `Hello Ada!`. Run it with no argument:

```
/greet
```

kli answers `Hello world!`, because `(rest-arg arguments)` returned `nil` and the `or` fell through to the default.

## Edit it and reload live

You can change the command against the same running session. Open `greet.lisp` and change the greeting.

```lisp
(reply (format nil "Welcome, ~A."
               (or (rest-arg arguments) "stranger")))
```

Save the file, return to kli, and run `/reload` again. `/reload` retracts every installed user extension, re-reads the files, and reinstalls them, so your edit replaces the old command in place. Run `/greet Ada` and kli now answers `Welcome, Ada.`.

If a file has an error, loading is fail-soft: kli warns about that one file and isolates it while every other extension keeps working. Fix the file and `/reload` again.

## Switch it off

To take the command out of the session without deleting the file, disable it by name:

```
/disable greet
```

kli answers `Disabled greet.`, and `/greet` no longer runs. The file stays on disk, so a later `/reload` (or the next session) brings it back. To list what is available and which extensions are currently enabled, run:

```
/extensions
```

## What you did

You wrote a slash command in a Lisp file, loaded it with `/reload`, edited it and reloaded it against the same live session, and disabled it with `/disable`. Edit, `/reload`, repeat: that is how you build a kli extension.

From here:

- Add a command that reacts to session events, or one the model can call as a tool: see [Lisp extensions](/kli/extend/lisp-extensions).
- Understand why a running kli can change itself this way: see [The live image](/kli/concepts/the-live-image).
- See the full `defextension` grammar, every contribution kind, and the author DSL: see [Extension reference](/kli/extend/lisp-extensions/anatomy).


#### Contribution Kinds


An extension is a bundle of contributions. Each contribution is one clause inside a `(:provides ...)` block, and each one installs when the extension loads and retracts when it unloads. This page shows the clause for each kind you are likely to write, and what its retraction undoes. Pick the kind that matches what you want to add.

Every clause shown here goes in a `defextension`:

```lisp
(defextension my-extension
  (:provides
   ;; one or more contribution clauses
   ))
```

A single-file extension loads in the `kli/author` package, so the clause heads below (`command`, `on`, `tool`, and the rest) are available unqualified. After editing a file, run `/reload` to retract and reinstall. For the surrounding mechanics, see [Write your first Lisp extension](/kli/extend/lisp-extensions/write-your-first); for the complete grammar and every clause, see [Extension reference](/kli/extend/lisp-extensions/anatomy).

Requirements are derived from the clauses you write. A `command` clause, for example, derives the requirement for the commands capability, so an extension that needs nothing beyond what its clauses imply omits `:requires` entirely.

## Add a slash command

A `command` clause adds a `/name` the user can type.

```lisp
(command "greet"
  :description "Greet someone by name."
  :arguments '(:tail :name)
  :handler (lambda (command arguments context &key call-id on-update)
             (declare (ignore command context call-id on-update))
             (reply (format nil "Hello ~A!"
                            (or (rest-arg arguments) "world")))))
```

The handler signature is fixed: `(command arguments context &key call-id on-update)`. `(reply text)` builds the result shown to the user; `(rest-arg arguments)` returns the free-text tail after the command name, or `nil`. Keys you can pass: `:label`, `:description`, `:arguments`, `:handler`, `:completer`, `:metadata`.

Retraction unregisters the command from the per-session command provider. After unload, typing `/greet` does nothing.

## Add an event handler

An `on` clause runs a function each time an event of a given type is dispatched.

```lisp
(on :tool/call
    (lambda (event context)
      (declare (ignore event))
      (notify context "A tool ran." :level :info)))
```

The handler signature is `(event context)`. `(notify context text :level :info)` surfaces text to the user as a notification, and is a no-op when no event provider is installed. Handlers for the same event type fire in install order.

An event handler carries no requirement of its own: it sits inert in per-session handler storage until the event system dispatches its type. Retraction removes the handler from that storage, so the function stops firing.

## Add a tool

A `tool` clause adds a tool the model can call during the agent loop.

```lisp
(tool word-count
  :label "Word Count"
  :description "Count the words in a string."
  :parameters '(:object (:text :string))
  :runner #'my-word-count
  :metadata '())
```

The runner signature is `(tool parameters context &key call-id on-update)` and returns a tool result. Keys: `:label`, `:description`, `:parameters`, `:runner`, `:renderer`, `:metadata`. Use `:metadata '(:capabilities (...))` to declare the capabilities the tool needs, and `:renderer` to control how its result appears in the transcript.

The tool registers as a live object in the session and joins the set the model sees. Retraction removes the live object and drops the tool from that set, so the model can no longer call it.

## Bind a key

A `keybinding` clause maps a key to an editor action in the terminal UI.

```lisp
(keybinding "ctrl+x" :clear-screen)
```

The first argument is the key id, a string like `"ctrl+l"`, `"alt+b"`, or `"enter"`. The second is the action keyword it should run, drawn from the editor's action set (for example `:clear-screen`, `:move-word-left`, `:delete-word-backward`, `:undo`). Installing a binding records whatever action that key previously held.

Retraction restores the previous binding if the key had one, or unbinds the key if it did not. When two extensions both touch a key, retraction unwinds in reverse, so the original binding returns.

## Add a theme

A `theme` clause registers a named theme the user can switch to.

```lisp
(theme "solarized"
  (kli/tui/style:load-theme #p"~/.config/kli/themes/solarized.json"))
```

The first argument is the theme name; the second is a theme value. `kli/tui/style:load-theme` reads a theme from a pathname, a JSON string, or a parsed object, resolving its color tokens once at load time. Registering a theme does not make it active; the user selects it.

Retraction unregisters the theme by name. After unload it no longer appears in the list of available themes.

## Add a status slot

A `status-slot` clause reserves a named slot in the status line that your code can write to.

```lisp
(status-slot :build :initial "idle")
```

The first argument is the slot id; `:initial` sets the starting text (default empty). The slot holds whatever text you put in it and renders in the status line.

Retraction unregisters the slot, removing it from the status line.

## Render a message kind

A `message-renderer` clause controls how a transcript event of a given kind is drawn.

```lisp
(message-renderer :build/progress
  (lambda (event theme width)
    (declare (ignore width))
    (list (kli/tui/style:style
           theme "accent"
           (format nil "build: ~A"
                   (getf (kli/event:event-payload event) :stage))))))
```

The first argument is the event kind; the second is a function `(event theme width)` returning the lines to draw. `(kli/tui/style:style theme token text)` colors a span by a theme token; `(kli/event:event-payload event)` reads the event's payload plist. A renderer is a method keyed on the event kind, so it takes effect only for events of that kind.

Retraction removes the method, and the kind falls back to default rendering.

## Declare a settings subtree

A `settings` clause declares your extension's subtree of the top-level `extensions` object in `settings.json`: the key names it accepts and the schema each value must satisfy.

```lisp
(settings my-extension
  (:object
   ("greeting" (:string :default "hello"))
   ("retries" (:integer :min 0 :max 5))
   ("mode" (:enum ("fast" "careful") :default "fast"))))
```

The clause is `(settings NAME SCHEMA)`. A symbol NAME downcases to the JSON key (`my-extension` above owns `extensions.my-extension`); pass a string when the key needs exact casing. The schema is quoted data:

| Spec | Accepts |
| --- | --- |
| `(:object ("key" SPEC) ...)` | An object with the listed keys, each validated by its spec. Keys not listed diagnose as unknown. |
| `(:string)` | A string. |
| `(:boolean)` | `true` or `false`. |
| `(:integer :min N :max M)` | An integer, optionally bounded. |
| `(:number :min N :max M)` | A number, optionally bounded. |
| `(:enum ("a" "b"))` | One of the listed strings. |
| `(:or SPEC SPEC ...)` | A value matching any alternative. |

Every leaf takes `:default`, and every declared key is optional in the files. Read values back with `(kli/config:declared-settings-value context "my-extension" "retries")`; it returns the configured value, or the declared default when the files omit the key, and a second value saying which (`:settings`, `:default`, or `nil` for neither).

Declaring buys three things. The subtree is validated when your extension activates, and every mismatch warns with the exact path — boot diagnostics the user sees instead of a silently ignored key. `/settings` lists the subtree, whether the files carry it, and its current diagnostics. And the subtree tiers like every built-in key: global under project under profile overlay, deep-merged key by key. See [settings.json](/kli/config/settings#extensions) for the user-side view.

A malformed schema signals when the extension loads — that is an authoring error. A malformed *value* in the user's files only warns: settings never break boot. And declaration describes, never grants — no key in your subtree can confer authority; what your tools may do is governed by [capabilities](/kli/config/capabilities) alone.

Retraction removes the declaration from the registry. The JSON stays in the user's files; `/settings` then lists that subtree as undeclared.

## Anything else: an effect

When no kind above fits, an `effect` clause runs arbitrary paired install-and-revert logic. This is the general escape hatch: you write both halves, and you own the symmetry.

```lisp
(effect mirror-log
  ;; installer
  (lambda (protocol contribution context)
    (declare (ignore protocol contribution context))
    (open #p"/tmp/kli-mirror.log" :direction :output
                                  :if-exists :append
                                  :if-does-not-exist :create))
  ;; retractor
  (lambda (protocol contribution context)
    (declare (ignore protocol context))
    (close (kli/ext:contribution-state contribution))))
```

The clause is positional: `(effect NAME installer retractor)`. Both functions take `(protocol contribution context)`. The installer's return value is stored as the contribution's state; the retractor reads it back with `(kli/ext:contribution-state contribution)` to undo exactly what was installed. The example stores the open stream on install and closes it on retract.

The retractor is required, because retraction must drain whatever install created: unregister what was registered, restore what was replaced, close what was opened. When an effect genuinely has nothing to undo, pass `:no-op` as the retractor rather than omitting it.

```lisp
(effect announce
  (lambda (protocol contribution context)
    (declare (ignore protocol contribution))
    (notify context "Extension loaded." :level :info))
  :no-op)
```

State that must survive a turn but die with the extension belongs in protocol storage, not in a global. Reach it with `(kli/ext:ensure-protocol-storage protocol KEY constructor)`; a global outlives retraction and leaks across reloads.

The clause heads above are matched by name, so they work unqualified from any package. The helper functions you call inside a clause are different: a single-file extension gets only the easy-tier names unqualified (`defextension`, `kli-extension`, `command`, `on`, `reply`, `rest-arg`, `notify`). Everything else, including the `kli/ext`, `kli/event`, and `kli/tui/style` names shown here, must be package-qualified.

## These kinds in tree

The clauses above are minimal on purpose. Every kind also ships in kli's own builtin extensions, where you can read it doing production work:

- **Tool** — the builtin `bash`, `filesystem`, and `lisp` tool extensions.
- **Slash command** — the builtin `install`, `settings`, and `profile` commands.
- **Theme** — the builtin theme extension registers the `:dark` and `:light` themes with `(theme :dark (load-theme ...))`.
- **Effect** — the builtin `prompt-templates` and `skills` extensions, and cairn, each register commands or open state through an `effect` with a paired retractor.
- **Keybinding, status slot, widget, message renderer** — defined and contributed by the keymap and terminal-UI subsystems.

cairn is a full external extension to read end to end: one manifest with a store-opening effect, its model tools, a live context hot-patch, and its own slash commands, each contribution carrying a retractor. To add a kind that none of these cover, see [Defining a contribution kind](/kli/extend/lisp-extensions/defining-a-contribution-kind).

## Next

- The full `defextension` grammar and every contribution kind: [Extension reference](/kli/extend/lisp-extensions/anatomy).
- Why a running kli can install and retract these live: [The live image](/kli/concepts/the-live-image).


#### Defining a Contribution Kind


The contribution kinds are not a fixed enum. A kind is a compile-time function from a
`(:provides ...)` clause to a contribution value, registered under a keyword. The
kernel defines its entire vocabulary this way, with the same macro you would use to add
one. There is no privileged set of built-in kinds and a separate plugin path for the
rest; `:tool` and a kind you write yesterday are registered identically.

## The macro

```lisp
(defcontribution-kind kind (extension-id form) &body body)
```

The body is a quasiquote returning the form that constructs your contribution;
`defcontribution-kind` registers it as the form-compiler for `kind`. When `defextension`
parses a `(:provides ...)` block it dispatches on each clause head to the matching
compiler. A clause whose head has no registered compiler signals
`unknown-contribution-kind`, so a kind exists exactly when its compiler is registered.

The compiler runs at macroexpansion of `defextension`, not at install. Its job is
narrow: read the clause syntax, return code that builds one contribution object. The
installing and retracting happen later, through methods on that object.

## The shape

A kind is three pieces: a contribution class, an install/retract method pair
specialized on it, and the `defcontribution-kind` compiler that builds it from a
clause. A synthetic `:banner` kind that registers a startup line:

```lisp
(defclass banner-contribution (kli/ext:contribution)
  ((text :initarg :text :reader banner-text)))

(defmethod kli/ext:install-contribution
    ((protocol kli/ext:extension-protocol) (c banner-contribution) context)
  (declare (ignore context))
  (register-banner protocol (banner-text c))
  (push c (kli/ext:protocol-installed-contributions protocol))
  c)

(defmethod kli/ext:retract-contribution
    ((protocol kli/ext:extension-protocol) (c banner-contribution) context)
  (declare (ignore context))
  (unregister-banner protocol (banner-text c))
  (setf (kli/ext:protocol-installed-contributions protocol)
        (remove c (kli/ext:protocol-installed-contributions protocol)))
  c)

(kli/ext:defcontribution-kind :banner (extension-id form)
  (destructuring-bind (_ text) form
    (declare (ignore _))
    `(make-instance 'banner-contribution
                    :kind :banner :text ,text :source ',extension-id)))
```

Once those three forms load, a `(banner ...)` clause compiles inside any extension:

```lisp
(defextension welcome
  (:provides
   (banner "kli ready.")))
```

The clause head is matched by name, so `banner` works unqualified in the author
package; the helpers it expands into (`register-banner`, the `kli/ext` symbols) are
ordinary functions and stay package-qualified.

## The kernel does exactly this

`:theme` is the same five-part shape, in tree:

```lisp
(defcontribution-kind :theme (extension-id form)
  (destructuring-bind (_ name theme-form) form
    (declare (ignore _))
    `(make-theme-contribution
      :name ',(normalize-extension-id name)
      :theme ,theme-form
      :source ',extension-id)))
```

The `:theme` kind ships with its own `theme-contribution` class, a constructor, and the
install/retract pair beside it. Nothing about it is special: it is a self-contained
domain kind that a subsystem registers when it loads.

The core kinds the protocol appears to "know" are the same. They are
`defcontribution-kind` forms too: `:effect`, `:method`, `:tool`, `:capability`,
`:live-object`, `:contract`, and `:grant`. `:method` compiles to a
`make-method-contribution` that carries a generic-function name, qualifiers,
specializers, and body; its retractor is `remove-method`. `:tool` compiles to a
`make-tool` wrapped in a contribution. The kernel reaches for the macro you do.

The set stays open across the tree. Each subsystem registers its own kinds at load:
`:command`, `:keybinding`, `:event-type` and `:event-handler`, and the terminal-UI kinds
`:message-renderer`, `:status-slot`, and `:widget`. A kind lives wherever its domain
lives, not in a central registry of permitted types.

## The reversibility contract

A kind is real only when its `install-contribution` and `retract-contribution` are
symmetric on `(extension-protocol, your-contribution)`. The `:theme` pair is the
minimal correct form: install registers the theme and pushes the contribution onto
`protocol-installed-contributions`; retract unregisters by name and removes the
contribution by identity. That symmetry is not decoration. Deactivation walks the
contributions an extension recorded at install and calls `retract-contribution` on each
(see [Lisp extension anatomy](/kli/extend/lisp-extensions/anatomy)), so a kind whose
retract does not undo its install leaks on every `/disable` and `/reload`.

Three rules keep a custom kind honest:

- **Register and unregister the same name.** Whatever install files under a key, retract
  removes under that key.
- **Record the contribution, drop it by identity.** Push on install, `remove` the same
  object on retract, so deactivation has an exact list rather than a guess.
- **Keep state with the contribution or in protocol storage, never in a global.** A
  slot on the contribution (`banner-text` above) or
  `(kli/ext:ensure-protocol-storage protocol KEY constructor)` dies with the protocol; a
  `defvar` outlives retraction and leaks across reloads.

The `:effect` kind threads its state through `contribution-state` because it has no
class of its own; a kind with a class keeps state in slots, as `:banner` does.

## Related

- [Contribution kinds](/kli/extend/lisp-extensions/contribution-kinds) — the kinds you
  reach for before defining one of your own.
- [Lisp extension anatomy](/kli/extend/lisp-extensions/anatomy) — install as a recorded
  transaction, and why every kind retracts.
- [Extensions all the way down](/kli/concepts/extensions-all-the-way-down) — why the kind
  vocabulary being contributed the same way is the whole point.
- [The live image](/kli/concepts/the-live-image) — why a running kli can register a new
  kind and start compiling clauses against it without a restart.


#### Recoding Live


You can change kli's behavior in the session you are already in, without restarting it. The recode operations below are ordinary functions: one swaps a whole extension, two hot-patch a single behavior in place. Each takes the running `context` and the object it acts on, and each is gated by a capability, so a restricted session can deny it.

This page assumes you have written or loaded the extension you want to change. For the extension shape itself, see [Write your first Lisp extension](/kli/extend/lisp-extensions/write-your-first). For why a running kli can do this at all, see [The live image](/kli/concepts/the-live-image).

## Where the recode call runs

A recode needs the live `context` and `protocol`. Both arrive as arguments wherever your extension's code already runs: a command handler is called as `(command arguments context &key call-id on-update)`, and an effect installer as `(protocol contribution context)`. Call the recode functions from inside one of those, where the objects are already in hand. The examples below show a command handler that does the recode when the user types its command.

To reach the active protocol from a context, use `(kli:active-protocol context)`; to find a live object by its id, use `(kli:find-live-object (kli:context-registry context) id)`.

## Swap a whole extension

Use `recode-extension` to replace one extension with a new version while everything else keeps running. It deactivates the old extension, then activates the new source. If activation fails, it re-activates the original, so the session is left on the version that worked rather than in a half-installed state.

```lisp
(command "swap-greeter"
  :description "Replace the greeter extension with its next version."
  :handler (lambda (command arguments context &key call-id on-update)
             (declare (ignore command arguments call-id on-update))
             (let* ((protocol (kli:active-protocol context))
                    (extension (kli:find-live-object
                                (kli:context-registry context)
                                :greeter)))
               (kli/ext:recode-extension protocol extension
                                         #'greeter-v2 context)
               (reply "Greeter swapped."))))
```

The third argument is the new source: the same kind of value you would activate an extension from, such as a manifest thunk or a `defextension` name. Deactivation retracts the old extension's tools, commands, providers, and methods together; activation installs the new one's. A consumer of the extension sees the swap as a single step.

`recode-extension` requires the `image/recode` capability. Granting `image/recode` also grants `manifest/install` and `manifest/retract`, because a recode is a retract followed by an install. A session whose `capabilities` array omits `image/recode` cannot swap extensions; see [Restrict what kli can do](/kli/guides/restrict-what-kli-can-do).

## Hot-patch a behavior cell

When you want to change one function rather than a whole extension, patch a behavior cell. A behavior cell holds a single function behind a fault barrier, and `recode-behavior` swaps that function in place. The cell keeps its identity, its version counter increments, and callers go on calling the same cell.

```lisp
(let ((cell (kli:find-live-object
             (kli:context-registry context)
             :my-behavior)))
  (kli/tui/core:recode-behavior cell :function #'my-new-function))
```

`recode-behavior` takes the cell and keyword arguments:

- `:function` — the new function to run.
- `:version` — set the version explicitly; omit it to increment by one.
- `:state` — replace the cell's state.
- `:metadata` — replace the cell's metadata.
- `:capabilities` — replace the capability list the cell declares.

`recode-behavior` requires the `behavior/hotpatch` capability. Passing `:state` additionally requires `behavior/state`, because changing live state is a stronger act than swapping the function; a session can be allowed to patch functions while still being denied state edits. The cell's fault policy and fault fallback are set when the cell is built and a recode cannot touch them, so a patched function that throws is still contained by the barrier it was installed behind.

### Patch a terminal-UI behavior

Terminal-UI components expose their behaviors through `recode-tui-behavior`, a generic that dispatches on what you hand it. Given a behavior cell, it delegates to `recode-behavior` with the same keyword arguments. Given a concrete UI object — an editor, the transcript, the input decoder, a frame renderer — the owning extension specializes it to find the right cell and patch that.

```lisp
(kli/tui/core:recode-tui-behavior
 (kli:find-live-object (kli:context-registry context) :editor)
 :function #'my-editor-input-handler)
```

The gating is the same: `behavior/hotpatch`, plus `behavior/state` when you pass `:state`. The UI behaviors that ship — editor input and paste, transcript scrollback, input decoding, frame rendering — each declare `behavior/hotpatch` and `behavior/state`, so a restricted session can permit or deny patching them as a group.

## Recode a policy in place

Some behavior is not a whole extension or a single behavior cell but a field of a policy on a live service. The session's context transform, which decides what extra messages are spliced into each turn, is one such policy. `kli/agent/session:recode-context-transform-policy` rebuilds that policy with one field replaced and leaves the rest intact. The new function runs behind the session fault barrier, so a transform that throws yields no extra messages rather than breaking the turn.

cairn uses this in tree to splice live task context into every turn. Its `cairn-context` effect reads the service's current `extra-messages-fn`, saves it, and recodes the policy to a function that appends cairn's task messages onto whatever the previous one returned:

```lisp
(let ((service (kli:find-live-object (kli:context-registry context)
                                     :agent-session-service)))
  (when service
    (let ((previous (getf (funcall (kli/agent/session:session-context-transform-policy
                                    service)
                                   :inspect)
                          :extra-messages-fn)))
      (kli/agent/session:recode-context-transform-policy
       service
       :extra-messages-fn
       (lambda ()
         (append (and previous (funcall previous))
                 (cairn-extra-messages context))))
      (list :service service :previous-fn previous))))
```

The effect's retractor reverses it exactly, recoding the same field back to the saved `previous-fn`. The session never restarts and never loses its scrollback: one field of a live policy is swapped, and swapped back on retract. This is the second pillar in production, [rewrite without restarting, keep the state](/kli/concepts/extensions-all-the-way-down). Unlike the kernel recodes above, it is a plain function on the agent-session service rather than a capability-gated kernel op; an extension reaches it through the live object and keeps the saved state on its own contribution.

## Snapshot the active protocol

A snapshot captures the active protocol as durable data: the list of installed extensions in activation order, the protocol's storage, and the serializable slot state of every contributed live object. Take one before a recode you are unsure about, or to move a session's state to another image.

```lisp
(let ((snapshot (kli/ext:provider-call
                 (kli/ext:require-capability-provider
                  (kli:active-protocol context)
                  :runtime/snapshot)
                 :snapshot-context context)))
  snapshot)
```

A snapshot is honest about what it cannot carry. A value it cannot serialize is named, not encoded lossily: an extension with no reconstructable manifest is listed under `:unrestorable-extensions`, storage entries it skipped under `:skipped-storage`, and per-object slots it dropped under `:skipped-slots`. What it skips is code-derived structure that reinstalling the manifests rebuilds, so the snapshot records the names rather than the bytes.

To restore, call `:restore-active-protocol` with a snapshot. A still-registered protocol is rehydrated in place; a protocol that was discarded, or one absent because the image restarted, is rebuilt from scratch by installing the captured manifests in order and rehydrating the captured storage and slot state.

```lisp
(kli/ext:provider-call
 (kli/ext:require-capability-provider
  (kli:active-protocol context)
  :runtime/snapshot)
 :restore-active-protocol context snapshot)
```

`snapshot-context` requires `protocol/snapshot` and `restore-active-protocol` requires `protocol/restore`. A session can be allowed to capture state without being allowed to overwrite it.

## The capabilities each step needs

A session that omits one of these from its `capabilities` array is denied that step; a session with the key absent runs fully permissioned and can do all of them. For the full model and how to set the array, see [Permissions and capabilities](/kli/concepts/capabilities-and-fault-barriers).

| Operation | Capability | Notes |
| --- | --- | --- |
| Evaluate a form ad hoc | `image/eval` | Gates the `/eval` command and `eval` tool, the way to run a recode form without writing an extension. |
| Swap an extension | `image/recode` | Implies `manifest/install` and `manifest/retract`. |
| Patch a behavior function | `behavior/hotpatch` | Covers `recode-behavior` and `recode-tui-behavior`. |
| Change a behavior's state | `behavior/state` | Required in addition when you pass `:state`. |
| Capture a snapshot | `protocol/snapshot` | — |
| Restore a snapshot | `protocol/restore` | — |

## Next

- The capability names and the tools each one gates: [Capabilities](/kli/config/capabilities).
- How a faulting recode stays contained instead of killing the session: [Permissions and capabilities](/kli/concepts/capabilities-and-fault-barriers).
- The full `defextension` grammar: [Extension reference](/kli/extend/lisp-extensions/anatomy).


#### Loading and Managing Extensions


This page covers how a Lisp extension reaches a running kli and how you turn one on or off without restarting. For writing the extension itself, see [Write your first Lisp extension](/kli/extend/lisp-extensions/write-your-first); for the full `defextension` grammar, see [Extension reference](/kli/extend/lisp-extensions/anatomy).

An extension comes from a file or directory on disk. kli reads that source, indexes what it declares as an available extension, and installs the enabled ones into the session. Four things decide which extensions a session has: where kli looks, what `config.json` says, the `--extension` flag, and the in-session commands.

## Drop a file in a discovery directory

kli scans two directories on every launch, in this order:

1. `~/.config/kli/extensions/` — loaded in every session.
2. `<project>/.kli/extensions/` — loaded only when kli runs in that project. Project files extend the global set; they do not replace it.

A directory that does not exist is skipped, not an error. To add an extension, write its `.lisp` file (or its unit directory) into one of these and start kli, or run `/reload` in a session already open.

## Load a one-off file with --extension

To load a file or directory that is not in a discovery directory, name it on the command line:

```
kli --extension ./scratch/greet.lisp
```

The flag is repeatable, and each value is either a file or a directory:

```
kli --extension ./scratch/greet.lisp --extension ./team-extensions/
```

A path that is a directory is discovered as a unit (or a group of units); any other path loads as a single file. Extensions named with `--extension` are added on top of whatever the discovery directories and `config.json` already contribute, for that one session only. Nothing is written to disk and the next launch forgets them.

## Add extra roots in config.json

`~/.config/kli/config.json` is an optional file. Three keys control loading:

| Key | Type | Effect |
|-----|------|--------|
| `enabled` | array of names | Force these extensions on, overriding their default. |
| `disabled` | array of names | Force these extensions off. |
| `extension-dirs` | array of paths | Extra directories to scan, in addition to the two discovery directories. |

```json
{
  "enabled": ["greet"],
  "disabled": ["noisy-extension"],
  "extension-dirs": ["/srv/shared/kli-extensions"]
}
```

Names are matched case-insensitively, so `"Greet"` and `"greet"` name the same extension. A directory under `extension-dirs` that does not exist is skipped. If `config.json` is missing or malformed, kli warns and proceeds as though it were absent rather than failing to start.

## Which extensions are enabled

An indexed extension is installed unless something turns it off. Settle a name by walking these checks in order and taking the first that names it:

1. The active profile's disable list (if a profile is active) turns it off.
2. The active profile's enable list turns it on.
3. `disabled` in `config.json` turns it off.
4. `enabled` in `config.json` turns it on.
5. The extension's own `:autoload` metadata, if it set one.
6. Otherwise, on.

To override an extension that ships off by default, add its name to `enabled`. To override an extension that ships on, add it to `disabled`. A profile wins over `config.json`, so a profile's lists can flip either way for that profile only. For profiles, see [Profiles](/kli/config/profiles).

## Reload after an edit

In a running session, `/reload` re-reads every extension file on disk:

```
/reload
```

It retracts every installed user extension, clears the indexed registry and the diagnostics from the previous pass, re-indexes from the current files, and installs the enabled set again. An edit to a file takes effect in place, with no rebuild and no restart. kli replies with the list of user extensions it now knows about and their state.

Loading is fail-soft: a file that errors warns and is isolated under a `[diagnostics]` entry while every other extension keeps working. Fix the file and run `/reload` again.

## Toggle one extension live

`/enable` and `/disable` switch a single extension without touching disk:

```
/enable greet
```

`/enable NAME` installs an indexed extension that is currently off. kli replies `Enabled greet.`, or `greet is already enabled.` if it was already on, or `No such extension: greet.` if no extension by that name was indexed.

```
/disable greet
```

`/disable NAME` retracts an installed extension from the session. kli replies `Disabled greet.`, or `greet is not enabled.` if it was not installed. The file stays on disk, so a later `/reload` or the next session brings the extension back unless `config.json` disables it.

## List what is available

`/extensions` reports every indexed extension and whether it is currently installed:

```
/extensions
```

Each line is marked `[enabled]` or `[disabled]`. When no user extensions were found, kli says so. To see which files failed to load, run `/reload`, which appends a `[diagnostics]` line for each failed unit; `/extensions` lists state only.


#### Lisp Extension Examples


Each section below is one self-contained extension you can drop into `~/.config/kli/extensions/`, load with `/reload`, and use. They cover five contribution kinds: a tool the model can call, a slash command you run, a widget that draws under the prompt, a color theme, and a renderer that restyles a kind of transcript message. Pick the one that matches what you want to add.

Every example is a single `.lisp` file holding exactly one `defextension`. Single-file extensions load in the `kli/author` package, where `defextension`, `command`, `reply`, and `rest-arg` are available unqualified. Clause heads like `tool`, `theme`, and `status-slot` are matched by name, so they work unqualified too. Functions you call inside a clause that live in another package must be written with their package prefix; each example below shows the prefixes it needs. For the full grammar and the complete list of contribution kinds, see [Contribution kinds](/kli/extend/lisp-extensions/contribution-kinds) and the [Extension reference](/kli/extend/lisp-extensions/anatomy).

After writing any file, run `/reload` in your session, then `/extensions` to confirm it loaded enabled. If a file has an error, `/reload` warns about that one file and keeps every other extension working.

## Add a tool the model can call

A tool is a function the model invokes during a turn. Declare it with a name, a description the model reads, a parameter schema, and a `:runner`. This one reverses a string.

`~/.config/kli/extensions/reverse-tool.lisp`:

```lisp
(defextension reverse-tool
  (:provides
   (tool reverse
     :label "Reverse"
     :description "Reverse the characters of a string."
     :parameters '(:object (:text :string))
     :runner (lambda (tool parameters context &key call-id on-update)
               (declare (ignore tool context call-id on-update))
               (reverse (kli/ext:tool-parameter parameters :text))))))
```

- `:parameters` is an `:object` schema. Each entry is `(NAME :TYPE)`; add `:optional t` to make one optional, as in `(:directory :string :optional t)`.
- The runner signature `(tool parameters context &key call-id on-update)` is fixed. Declare-ignore what you do not use.
- `(kli/ext:tool-parameter parameters :text)` reads one argument by name.
- A runner may return a plain string, which kli wraps into a tool result. For a result with structured details or an error flag, return `(kli/ext:make-tool-result :content (list (kli/ext:make-tool-text-content "...")) :error-p t)`.

After `/reload`, the `reverse` tool is in the model's tool set and the model can call it.

## Add a slash command

A command runs when you type `/name` at the prompt. The handler returns a `(reply ...)` result. This one echoes the system clock.

`~/.config/kli/extensions/now.lisp`:

```lisp
(defextension now
  (:provides
   (command "now"
     :description "Print the current time."
     :handler (lambda (command arguments context &key call-id on-update)
                (declare (ignore command arguments context call-id on-update))
                (multiple-value-bind (s m h) (get-decoded-time)
                  (reply (format nil "~2,'0D:~2,'0D:~2,'0D" h m s)))))))
```

- The string after `command` is the name typed after the slash.
- The handler signature `(command arguments context &key call-id on-update)` is fixed.
- To read free text the user typed after the command name, add `:arguments '(:tail :name)` and call `(rest-arg arguments)`, which returns the tail or `nil`.
- `(reply text)` builds the result kli shows.

After `/reload`, `/now` prints the time.

## Add a status-line widget

A widget draws lines in the footer under the prompt on every frame. Declare it with `widget` and a factory taking `(protocol theme width)` that returns a list of lines. This one shows the current working directory.

`~/.config/kli/extensions/cwd-widget.lisp`:

```lisp
(defextension cwd-widget
  (:provides
   (widget cwd
     (lambda (protocol theme width)
       (declare (ignore protocol))
       (let ((text (format nil "cwd: ~A"
                           (uiop:getcwd))))
         (list (if theme
                   (kli/tui/style:style theme "muted"
                     (kli/text:pad-right text width))
                   (kli/text:pad-right text width))))))))
```

- The factory returns a list of strings, one per footer line. Return `nil` for no lines.
- `width` is the terminal width. `(kli/text:pad-right text width)` pads a line to fill it.
- `theme` is the active theme, or `nil` when none is resolved. `(kli/tui/style:style theme TOKEN text)` colors `text` with a theme token such as `"muted"` or `"accent"`. Guard the no-theme case as shown.
- A widget that errors or returns a non-list contributes no lines and is isolated; the rest of the footer keeps drawing.

For a one-line value you set imperatively rather than recompute every frame, use a `status-slot` instead:

```lisp
(defextension build-status
  (:provides
   (status-slot build :initial "build: idle")))
```

A slot registers a named footer segment seeded with `:initial`. Update it from a command or event handler with `(kli/tui/status:set-status protocol :build "build: passing")`, where `protocol` is `(active-protocol context)`. An empty slot draws nothing.

After `/reload`, the footer shows the new line.

## Add a theme

A theme is a named color palette. Declare it with `theme` and a theme value built from JSON by `kli/tui/style:load-theme`. The JSON has a `name`, a `vars` map of reusable color values, and a `colors` map from token names to either a hex color or a `vars` key. An empty token value means the terminal default.

`~/.config/kli/extensions/solarized.lisp`:

```lisp
(defextension solarized
  (:provides
   (theme solarized
     (kli/tui/style:load-theme
      "{
         \"name\": \"solarized\",
         \"vars\": { \"base\": \"#268bd2\", \"red\": \"#dc322f\" },
         \"colors\": {
           \"accent\": \"base\",
           \"error\": \"red\",
           \"text\": \"\",
           \"mdHeading\": \"base\"
         }
       }"))))
```

- `load-theme` accepts a JSON string, as here, or a pathname to a `.json` file.
- The `name` in the JSON is how you select the theme; it does not have to match the `defextension` name.
- Tokens you omit fall back to the active built-in palette. The full set of token names (such as `accent`, `error`, `mdHeading`, `toolSuccessBg`, `syntaxKeyword`) is in the [Themes reference](/kli/commands/themes).

After `/reload`, the theme is registered and available to select.

## Add a message renderer

A message renderer replaces how one kind of transcript event draws. Declare it with `message-renderer`, a transcript-event kind to key on, and a function taking `(event theme width)` that returns a list of lines. This one tags every assistant `:message` with a marker line above it.

`~/.config/kli/extensions/reply-marker.lisp`:

```lisp
(defextension reply-marker
  (:provides
   (message-renderer :message
     (lambda (event theme width)
       (let* ((text (kli/tui/transcript:event-text event))
              (marker "<<< reply")
              (body (loop for line in (kli/text:wrap-text text width)
                          collect (kli/text:pad-right line width))))
         (cons (if theme
                   (kli/tui/style:style theme "accent"
                     (kli/text:pad-right marker width))
                   (kli/text:pad-right marker width))
               body))))))
```

- The renderer keys on the event kind, `:message` here. It runs for every transcript event of that kind, replacing the default rendering for it.
- `(kli/tui/transcript:event-text event)` reads the message text. `event-role` (`:assistant`, `:user`) and `event-kind` are also available; branch on `event-role` inside the function if you want to leave one role untouched by returning the default rendering for it.
- Lines are strings sized to `width`. `(kli/text:wrap-text text width)` wraps long text, and `kli/text:pad-right` fills each line.

After `/reload`, assistant replies render with the marker.

## The same kinds, in tree

These are small on purpose. The same kinds ship in kli's own builtins, where they do production work:

- The **tool** kind: the builtin `bash`, `filesystem`, and `lisp` tool extensions.
- The **command** kind: the builtin `install` and `settings` commands.
- The **theme** kind: the builtin theme extension, with its `:dark` and `:light` palettes.
- The **widget**, **status-slot**, and **message-renderer** kinds: contributed by the terminal-UI status and transcript subsystems.

For one extension that uses many kinds at once, read cairn: a manifest with a store-opening effect, its model tools, a live context hot-patch, and its own slash commands, each contribution carrying a retractor.

## Next steps

- The shared structure under all five — the `defextension` grammar, requirements, metadata, and the imperative `kli-extension` builder: see [Anatomy of an extension](/kli/extend/lisp-extensions/anatomy).
- Loading order, project-local extensions, and the `enabled`/`disabled` config: see [Loading and managing extensions](/kli/extend/lisp-extensions/loading-and-managing).
- How a running kli installs and retracts these without a restart: see [The live image](/kli/concepts/the-live-image).


#### Sharing Extensions


This page is the receiving side. To install an extension someone published at a URL, you name the URL and the git object id it is pinned to, confirm two trust cards, and kli loads only bytes that hash to that id. There are two entry points for the same install:

- **In a running session**, `/install <url> <git-tree-sha1>` loads the extension live into the current image.
- **From a shell or a script**, `kli install <url> <git-tree-sha1>` places it durably for the next session without needing one running.

Both run the identical verification and the same two cards; they differ only in whether the code activates immediately or on the next launch. This is a remote *extension* install, not the command that installs kli itself — that is the one-time shell install in [Installation](/kli/cli/installation). For the other side of this exchange — packaging, pinning, and signing an extension to publish — see [Publishing extensions](/kli/extend/publishing-extensions). Nix users have a third option that skips runtime install entirely: bake the extension into the image with [`programs.kli`](/kli/config/nix-module).

## Get the URL and the pin

The publisher gives you two things: the URL the extension is served from, and the git object id it is pinned to. For a single-file extension the pin is the git blob id of the file, what `git hash-object <file>` prints; for a directory extension it is the git tree id over the whole unpacked tree, what `git write-tree` produces. Either way it is an identity no two different contents can share. If the publisher hands you only a URL, ask for the pin; an install with no pin, or with the wrong pin, is refused rather than loaded.

A published extension is a single Lisp file or a directory bundle — a multi-file unit packaged as one blob — the same kinds you write as a [Lisp extension](/kli/extend/lisp-extensions). kli detects which shape it fetched and verifies the matching pin. When it loads it gains eval authority in your session, so the pin is what lets you install code you did not write and still know exactly which bytes ran.

## Install in a running session

In an interactive session, type:

```
/install https://example.com/path/to/extension.lisp 3f8a1c2e9b7d4f60a51e8c2d9f0b4a7c6e1d3b85
```

The command needs exactly the URL and the hash, two whitespace-separated tokens. Anything else prints `Usage: /install <url> <git-tree-sha1>`. This slash command runs in an interactive session and loads the extension live; to install without a running session, use the [`kli install` command line](#install-from-the-command-line).

## Confirm the consent-to-load card

kli shows a first card before fetching anything. It states the plain fact that author-provided Lisp is about to load into the running image with eval authority, names the URL, and shows the hash you pinned:

```
Install from https://example.com/path/to/extension.lisp. This loads
author-provided Lisp code into the running image with eval authority,
pinned to git 3f8a1c2e9b7d4f60a51e8c2d9f0b4a7c6e1d3b85.
```

A two-row menu opens under it: pick `install` to proceed or `cancel` to stop. `Esc` dismisses with no action. Nothing has been fetched at this point, so cancelling here makes no request and loads nothing.

## Confirm the verification card

On the first confirm, kli fetches the bytes from the URL and hashes them as a git blob. If that id does not equal the hash you supplied, verification fails and the install stops with a `verification failed` line naming the URL and reason; no code is placed or loaded. A wrong or missing hash is a hard failure, never a skip.

When the bytes match, a second card reports the verified identity and the trust level, then opens the same `install` / `cancel` menu:

```
Verified bytes match git 3f8a1c2e9b7d4f60a51e8c2d9f0b4a7c6e1d3b85.
Unsigned: integrity-pinned only.
```

`Unsigned: integrity-pinned only` is the default state: kli verified that the bytes are the ones the hash names, and nothing more. It does not vouch for who wrote them. If you have configured publisher signing keys, this card instead reads `Signed by trusted key <fingerprint>` and a download missing or carrying an untrusted signature is refused at this step. Signing is opt-in and off by default; you turn it on by listing keys in [`trustRoots`](/kli/config/settings#trustroots).

Confirm the second card and kli places the verified file under `~/.config/kli/extensions/`, installs it into the running session, and prints `Installed <id>.` The extension's tools, commands, and keybindings are live immediately, with no restart. Picking `cancel` at either card prints `Install cancelled.`; a verified install that fails to index prints `Install of <id> rejected (<reason>).`

## Install from the command line

`kli install` is the same install as a subcommand of the `kli` program, for a shell or a script rather than a running session:

```
kli install https://example.com/path/to/extension.lisp 3f8a1c2e9b7d4f60a51e8c2d9f0b4a7c6e1d3b85 --yes
```

It takes the URL and the pin as its two positional arguments and runs the identical verification — the git-object pin, then the opt-in signature check when you have configured trust roots. What differs is the result: rather than loading into a running image, it places the verified files durably under `~/.config/kli/extensions/` without activating them, and the next `kli` session — or `kli mcp-serve <id>` for a served extension like cairn — discovers them from disk. This is the path a headless install or a provisioning script takes.

The two trust cards print to stderr. `--yes` (or `-y`) confirms both stages without prompting; without it, an interactive terminal prompts once per stage, and a non-terminal run refuses rather than blocking on a prompt no one can answer. On success the declared extension id prints to stdout, so a script can capture it cleanly, and `Installed <id>.` prints to stderr.

The exit code reports the outcome: `0` installed; `2` a malformed invocation, which also prints `Usage: kli install <url> <git-tree-sha1> [--yes]`; and `3` a refusal, a cancellation, or a verification failure, in which case nothing was placed.

## What persists

A confirmed install is recorded as a pin: its URL, the git tree sha1, and the trust level. Later sessions re-fetch the file from its URL and re-verify it against the same hash before loading. If the bytes no longer match the pin, or a previously signed pin comes back unsigned, kli declines to load it and records the refusal rather than running changed code under your old consent. The pin travels with your session, the verification does not weaken on restore, and you confirm the trust cards once, not every session.

## Related

- [Publishing extensions](/kli/extend/publishing-extensions) — the sending side: packaging, pinning, and signing an extension so others can install it.
- [`trustRoots`](/kli/config/settings#trustroots) — the setting that turns the signature check from optional into required.
- [Lisp Extensions](/kli/extend/lisp-extensions) — what a published extension is and how to write your own.
- [Installation](/kli/cli/installation) — installing the kli app, which is a different `/install`.
- [Capabilities and fault barriers](/kli/concepts/capabilities-and-fault-barriers) — gating what an installed extension's tools can do, and the opt-in signing keys.
- [The Live Image](/kli/concepts/the-live-image) — why an extension can install and run without a restart.


#### Publishing Extensions


This page is the publishing side. To let someone install your extension with `kli install`, you host the code at a URL and hand out two things: the URL and a **pin** — the git object id of the exact bytes you published. kli refuses to load anything whose content does not hash to that pin, so the pin is what lets a stranger install your code and still know exactly which bytes ran. Signing is an optional layer on top that also proves who published them. If your recipients are Nix users, you can instead distribute the extension as a flake package they bake into their image — see [Distribute as a Nix package](#distribute-as-a-nix-package).

For the receiving side — running `kli install` and confirming the trust cards — see [Sharing extensions](/kli/extend/sharing-extensions).

## Decide the shape

An extension is published in one of two shapes, and the pin is a different git object id for each.

- A **single Lisp file** is the common case: one `.lisp` file, one blob, pinned by its git blob id. Publish the file as-is.
- A **directory extension** is a multi-file unit — several source files, a load order, usually an `.asd`. It is published as one *bundle* blob whose pin is the git tree id over its unpacked tree. cairn ships this way.

If your extension is a single file, skip to [Publish a single file](#publish-a-single-file). If it is a directory, see [Structure a directory extension](#structure-a-directory-extension) first.

## Publish a single file

Host the `.lisp` file at a stable URL that returns its raw bytes. Compute the pin with git:

```
git hash-object extension.lisp
```

That prints the git blob object id — git's sha-1 over the blob header and the file content, the same id git stores the file under. Hand out the URL and this pin. A recipient installs it with:

```
kli install https://example.com/extension.lisp <pin>
```

kli fetches the bytes, hashes them the same way, and refuses the install if the result does not equal the pin. Serve the file over HTTPS from a location whose bytes do not change under the same URL; if you edit the file, its pin changes and you publish a new pin.

## Structure a directory extension

A directory becomes a single loadable unit when it carries **either** an `extension.lisp` marker file **or** exactly one `.asd` system definition. kli then treats the whole top-level directory as one extension and does not descend into it.

Load order is decided as follows:

- With an `.asd`, the `:components` order in the system definition governs. kli loads the unit by running `asdf:load-asd` then `asdf:load-system`, so ASDF's declared order is honored exactly.
- Without an `.asd`, the convention governs: `package.lisp` loads first, `extension.lisp` loads last, and the remaining files load in alphabetical order.

If your files have dependencies that alphabetical order would break — a store file that must load before the model that uses it, say — author an `.asd` and declare the order. A minimal one:

```lisp
(defsystem "my-extension"
  :serial t
  :components ((:file "src/package")
               (:file "src/store")
               (:file "src/model")
               (:file "src/extension")))
```

`:serial t` loads the components in the listed order. The unit is rooted at the directory holding the `.asd`; the marker and package conventions from [Loading and managing extensions](/kli/extend/lisp-extensions/loading-and-managing) still describe how a local directory is discovered.

## Bundle a directory extension

A directory is published as one **bundle** blob: a JSON envelope that carries every file, so it fetches, verifies, and signs exactly like a single file does. The envelope is:

```json
{
  "format": "kli-dir-bundle-v1",
  "files": {
    "my-extension.asd": "<base64 of the file bytes>",
    "src/package.lisp": "<base64 of the file bytes>",
    "src/store.lisp":   "<base64 of the file bytes>"
  }
}
```

Each key is a path relative to the extension root; each value is the base64 of that file's raw bytes. Sort the paths and emit compact JSON so the bytes are a deterministic function of the source — the same input always produces the same bundle, and therefore the same pin.

The pin for a bundle is the **git tree id** over the unpacked files, which is what `git write-tree` produces for the same file set:

```
git init -q tree && cd tree
# copy the extension's files into place, preserving relative paths
git add -A && git write-tree
```

That id verifies the whole tree at once. Host the bundle blob at a URL and hand out the URL and this pin; kli detects the envelope, unpacks it, verifies the tree, and places the directory unit under the recipient's extensions directory.

## Sign a release

The pin proves *integrity* — that the bytes are the ones the pin names. A signature proves *authenticity* — that you published them. Signing is opt-in: a recipient who has configured no trust roots verifies the pin only, and one who trusts your key requires a valid signature from it or refuses the install. See [`trustRoots`](/kli/config/settings#trustroots) for the recipient side.

To sign, mint an ed25519 keypair, keep the private seed secret, and publish the public key as hex. Sign the **raw bytes of the published artifact** — the exact file or bundle blob you serve — producing a detached ed25519 signature over those bytes (ed25519 hashes the message internally, so the bytes are signed unhashed). Host the signature next to the artifact at `<url>.sig`: for `extension.lisp` that is `extension.lisp.sig`. kli fetches the signature by this convention only when the recipient has configured trust roots.

Because the signature is over the served bytes, re-sign whenever you re-serialize the artifact. Rotating your key means publishing the new public key; recipients update their trust roots to match.

## What you hand out

A published extension is fully described by:

- the **URL** the artifact is served from,
- the **pin** — `git hash-object` for a single file, `git write-tree` for a directory bundle,
- your **public key** hex, if you signed it, for recipients to add to their trust roots.

A checksums file listing the artifact's sha-256 is a courtesy for out-of-band verification, but the pin, not the checksum, is what kli enforces. With those in hand, a recipient runs `kli install <url> <pin>` and, for a directory extension like cairn, serves it afterward with `kli mcp-serve <id>`.

## Distribute as a Nix package

The URL-and-pin channel above is per-user and runtime: a recipient runs `kli install` and the extension lands in their config directory. The other way to hand out an extension is as a **Nix package** a recipient bakes into their kli image with [`programs.kli`](/kli/config/nix-module). Nothing is fetched or pinned at install time — the extension is compiled into the image, and trust rides on the recipient's flake inputs and Nix hashing. This is the channel Nix users prefer, and it is how cairn ships. You can offer both from one source: a URL-and-pin build for runtime installs, and a flake package for image builds.

To distribute this way, expose your extension as a flake package that is a **buildLisp library** carrying two `passthru` fields:

- `passthru.name` — the extension id.
- `passthru.manifestSymbol` — the package-qualified symbol naming your manifest, the `*…-extension-manifest*` variable [`defextension`](/kli/extend/lisp-extensions/anatomy) binds. kli fails the image build if the compiled result does not export it, so a mislabelled package cannot ship silently.

kli composes that package into the image as a build dependency, so it must be built with the same `buildLisp` kli uses. The plug-and-play way to get `buildLisp` and a batteries-included set of Common Lisp libraries is the public **cl-deps** flake — the exact dependency set kli itself is built from:

```nix
{
  inputs.cl-deps.url = "github:kleisli-io/cl-deps";
}
```

`cl-deps.lib.<system>.buildLisp` builds your library, and `cl-deps.lib.<system>.lisp.*` supplies common dependencies. A minimal extension package:

```nix
cl-deps.lib.${system}.buildLisp.library {
  name = "greet";
  srcs = [ ./src/package.lisp ./src/greet.lisp ];
  deps = [ cl-deps.lib.${system}.lisp.alexandria ];
  passthru = {
    name = "greet";
    manifestSymbol = "greet:*greet-extension-manifest*";
  };
}
```

Expose that as `packages.<system>.default`, and a recipient adds `inputs.greet.packages.${system}.default` to `programs.kli.extensions`.

If cl-deps does not already package a Lisp library you depend on, fork it and add the definition — its README shows the one place to declare a new library, and native C dependencies use the `native` attribute. cl-deps is one of several ways to build Common Lisp under Nix; you are free to use another for your own code, but the package you hand to `programs.kli.extensions` must be a buildLisp library so it can compile into the image.

## Related

- [The programs.kli module](/kli/config/nix-module) — the recipient side of the Nix-package channel: baking your extension into an image.
- [Sharing extensions](/kli/extend/sharing-extensions) — the receiving side: `kli install`, the two trust cards, and what persists.
- [Loading and managing extensions](/kli/extend/lisp-extensions/loading-and-managing) — how a directory unit is discovered and ordered on disk.
- [Write your first Lisp extension](/kli/extend/lisp-extensions/write-your-first) — authoring the extension you are publishing.
- [`trustRoots`](/kli/config/settings#trustroots) — the recipient-side setting that turns signature verification on.


## Reference

### CLI & Install

#### Installation


kli installs on Linux and macOS. The canonical route is a prebuilt binary fetched by the install script; Nix and a from-source build are also supported.

## Install command

```sh
curl -fsSL https://kli.kleisli.io | sh
```

The script is served at the site root. There is no `/install` route.

The script detects the platform, downloads the matching release tarball, verifies the checksum when one is published, extracts the payload, and writes a `kli` wrapper. When the install directory's `bin` is not on `PATH`, it prints the `export PATH=…` line to add.

## Installer environment variables

Set these in the environment of the `curl … | sh` invocation.

| Variable | Default | Effect |
|---|---|---|
| `KLI_VERSION` | latest published release | Pin a version tag, e.g. `v0.1.0`. When unset, the script resolves the latest tag from the GitHub releases API. |
| `KLI_INSTALL_DIR` | `~/.local`; `/usr/local` when run as root | Install root. The payload goes under `<root>/lib/kli` and the wrapper at `<root>/bin/kli`. |
| `KLI_DOWNLOAD_BASE` | the GitHub release for the resolved version | Override the download origin wholesale: a private mirror, an air-gapped copy, or a local server. When set, version resolution is skipped and the artifact and `checksums.txt` are fetched from this base. |

A pinned-version invocation:

```sh
KLI_VERSION=v0.1.0 curl -fsSL https://kli.kleisli.io | sh
```

## On-disk layout

The installer lays out the payload under `<root>/lib/kli` and puts a small wrapper on `PATH`.

| Path | Contents |
|---|---|
| `<root>/lib/kli/bin/kli` | The relocatable image launcher. It self-locates from its own directory, sets the data directory and dynamic-library search path, and execs the image. |
| `<root>/lib/kli/lib/` | Bundled runtime libraries (dynamic loader and shared objects) the image loads. |
| `<root>/lib/kli/share/kli/` | Runtime resource roots (built-in skills, TUI themes). |
| `<root>/bin/kli` | The wrapper on `PATH`. It execs `<root>/lib/kli/bin/kli` by absolute path. |

The wrapper invokes the launcher by absolute path, not a symlink: the launcher roots its lookups off its own directory, so a symlinked entry would mis-root.

Checksum verification is best-effort. The script fetches `checksums.txt` from the same base and compares against `sha256sum` or `shasum`. A mismatch aborts the install. When neither tool is present and no checksum file is published, verification is skipped.

Re-running the script over an existing install removes the previous `bin`, `lib`, `share`, and `VERSION` under `<root>/lib/kli` before extracting, so an upgrade is clean.

## Supported targets

Prebuilt binaries are published for three targets:

| OS | Architecture | Prebuilt binary |
|---|---|---|
| Linux | x86_64 | yes |
| Linux | aarch64 (arm64) | yes |
| macOS | aarch64 (Apple Silicon) | yes |
| macOS | x86_64 (Intel) | no |

Intel macOS has no prebuilt binary. Install via Nix or from source.

## Nix

The flake at `github:kleisli-io/kli` builds for `x86_64-linux`, `aarch64-linux`, and `aarch64-darwin`. Two entry points run or install the program:

```sh
nix run github:kleisli-io/kli
nix profile install github:kleisli-io/kli
```

| Output | Contents |
|---|---|
| `overlays.default` | Adds `kli` to a nixpkgs overlay; the package is then `pkgs.kli`. |
| `packages.<system>.kli` (and `.default`) | The `kli` program derivation. |

The overlay and package, wired into a NixOS or home configuration:

```nix
{
  inputs.kli.url = "github:kleisli-io/kli";

  # nixpkgs.overlays = [ inputs.kli.overlays.default ];
  # environment.systemPackages = [ pkgs.kli ];
}
```

That installs kli itself. To bake extensions and settings into the image, use [the `programs.kli` module](/kli/config/nix-module) instead.

## From source

A source build needs SBCL and [qlot](https://github.com/fukamachi/qlot). The external Common Lisp systems are pinned in `qlfile`.

```sh
qlot install
qlot exec sbcl --script build.lisp
./bin/kli
```

`qlot install` resolves the pinned systems. `build.lisp` loads the `kli` system and dumps a standalone image to `bin/kli` in the working directory.


#### Environment Variables


kli reads environment variables in two places: the installer script (`curl -fsSL https://kli.kleisli.io | sh`) reads them once, while it downloads and unpacks a release; the running app reads them on each launch. The two sets do not overlap. A variable read by the installer has no effect once kli is installed, and a variable read by the app has no effect during installation.

## Provider credentials

The app reads provider API keys from the environment at the moment it resolves a credential, not at boot. Changing the variable's value changes the credential the next time a request is made; there is no cached copy to clear.

Both variables back a credential reference that names the variable rather than storing its value. The reference is what kli persists; the secret stays in the environment. A provider whose default credential names a variable that is unset or empty is treated as unavailable until the variable holds a non-empty value, or until you register a different credential with `/auth`.

| Variable | Read by | Default | Effect |
|---|---|---|---|
| `ANTHROPIC_API_KEY` | app | unset | API key for the `anthropic` provider (the Anthropic Messages API). Resolved live on each request. |
| `OPENAI_API_KEY` | app | unset | API key for the `openai` provider (the OpenAI Responses API). Resolved live on each request. |

The `openai-codex` provider authenticates through OAuth and reads no environment variable. A `compatible` provider (a user-defined OpenAI-compatible endpoint declared in `~/.config/kli/providers.json`) reads the variable named by that entry's `key-env` field; the field is per-provider, so the variable name is whatever you set it to. See [Connect a provider](/kli/guides/connect-a-provider) for registering credentials.

## Boot profile

| Variable | Read by | Default | Effect |
|---|---|---|---|
| `KLI_PROFILE` | app | `interactive-terminal` | Names the boot profile to install at launch. |

The app resolves the boot profile in order: the `--profile` flag, then `KLI_PROFILE`, then the `profile` key in `settings.json`, then the built-in default `interactive-terminal`. The first source that names a profile wins, so `KLI_PROFILE` overrides the settings key but yields to an explicit `--profile`. A name that resolves to neither a built-in nor a declared data profile falls back to the default and records a boot diagnostic. See [Profiles](/kli/concepts/profiles).

## Docs origin

| Variable | Read by | Default | Effect |
|---|---|---|---|
| `KLI_DOCS_BASE` | app | `https://docs.kleisli.io` | Origin the `kli docs` subcommand fetches documentation from. Point it at a private mirror or a local docs server; a trailing slash is ignored. |
| `KLEISLI_BASE_URL` | app | unset | Fallback docs origin for `kli docs`, used only when `KLI_DOCS_BASE` is unset. |

`kli docs` resolves the origin in order: `KLI_DOCS_BASE`, then `KLEISLI_BASE_URL`, then the default. The subcommand always fetches the `kli` project's docs. See [Reading the docs](/kli/cli/docs).

## Installer variables

The installer reads these once, before download. They take effect when set in the same command that runs the installer, for example `KLI_VERSION=v0.1.0 curl -fsSL https://kli.kleisli.io | sh`.

| Variable | Read by | Default | Effect |
|---|---|---|---|
| `KLI_VERSION` | installer | latest release | Pins the version to install, as a release tag (for example `v0.1.0`). When unset, the installer queries the GitHub API for the latest release tag. Ignored when `KLI_DOWNLOAD_BASE` is set. |
| `KLI_INSTALL_DIR` | installer | `~/.local` (`/usr/local` when run as root) | Install root. The binary lands in `<dir>/lib/kli` and a launcher wrapper in `<dir>/bin/kli`. |
| `KLI_DOWNLOAD_BASE` | installer | GitHub release URL | Origin to download the release artifact and `checksums.txt` from, instead of the GitHub release: a private mirror, an air-gapped copy, or a local server. When set, version resolution is skipped and `KLI_VERSION` is ignored. |

The installer downloads `kli-<os>-<arch>.tar.gz` from the resolved origin and verifies it against `checksums.txt` when that file is present. The download base is a directory URL; the installer appends the artifact and checksum filenames to it. See [Installation](/kli/cli/installation) for platform coverage and the from-source path.


#### Reading the Docs


`kli docs` prints kli documentation straight to your terminal, fetched live as Markdown from the docs site. It always addresses the kli project, and what it prints is whatever the published docs currently say: there is no copy bundled with your installed kli, so the text never goes stale.

## Subcommands

| Invocation | Effect |
|---|---|
| `kli docs` | Print the kli docs index — the list of pages. |
| `kli docs <section>/<page>` | Print one page as Markdown, e.g. `kli docs extend/lisp-extensions/anatomy`. |
| `kli docs search <query>` | Print ranked search hits for `<query>`, each with the page path to fetch. |
| `kli docs help` (`--help`, `-h`) | Print usage and exit. |

A page path is the part of a docs URL after the project, with no leading slash and no `.md` suffix. The page at `docs.kleisli.io/kli/config/capabilities` is `kli docs config/capabilities`. Search hits print their paths in the same form, so a hit feeds straight back into `kli docs <path>`.

## Where it fetches from

`kli docs` reads from `https://docs.kleisli.io` by default. The project is always `kli`; the subcommand never addresses another project's docs.

| Variable | Default | Effect |
|---|---|---|
| `KLI_DOCS_BASE` | `https://docs.kleisli.io` | Origin to fetch the index, pages, and search from instead of the default — a private mirror or a local docs server. A trailing slash is ignored. |
| `KLEISLI_BASE_URL` | unset | Honoured as a fallback origin when `KLI_DOCS_BASE` is unset. |

The docs are fetched on demand, so they track the published site rather than the version of kli you have installed. A failed fetch — an unknown path, an unreachable origin, a non-200 response — reports the problem on standard error and exits non-zero, leaving standard output empty.


### Commands, Tools & TUI

#### Slash Commands


A line typed at the kli prompt that begins with `/` is a slash command. The first word names the command; the rest is its argument tail. This page lists every command kli registers, grouped by area.

Commands come from extensions, so the set is not fixed: a profile that omits an extension omits its commands, and a loaded extension can add its own. Two families are registered dynamically from files on disk — prompt templates and skills (see [Prompt and skill commands](#prompt-and-skill-commands)). Run `/commands` to see what is registered in the current session, and `/help <command>` for one command's details.

Most commands report their result as a system line in the transcript. Commands marked below as menu-backed open a selection menu in the terminal UI when run with no argument; run with an argument, or run outside the terminal UI, they act directly and print text.

## Basic

| Command | Effect |
| --- | --- |
| `/commands` | List every registered command. |
| `/help [command]` | Show the command list, or details for one command. |
| `/clear` | Clear the terminal display. The conversation is unchanged. |
| `/reset` | Start a new conversation in the current session, clearing history. |
| `/redraw` | Repaint the terminal display. |
| `/quit` | Stop kli and exit. |

`/clear` and `/redraw` act only on the display; the model never sees them.

## Session

A session is the durable record of a conversation: its history, name, model selection, and stored file. These commands inspect and manipulate it. See [Sessions](/kli/concepts/sessions-as-a-tree) for the model.

| Command | Effect |
| --- | --- |
| `/name [text]` | Set the session display name to `text`, or show the current name. |
| `/session` | Show the active session: id, file, model, and token count. |
| `/resume [selector]` | List stored sessions; with a selector, resume the matching one. Menu-backed. |
| `/resume delete <selector>` | Delete the matching stored session. The active session cannot be deleted. |
| `/compact [instructions]` | Summarize the history into a shorter context, optionally focused by `instructions`. |
| `/rewind [n]` | Step the conversation back `n` user turns (default 1), branching the session. Menu-backed. |
| `/branches` | Show the tree of sessions created by rewind-branching, and switch between them. Menu-backed. |

A bare `/resume` selector matches against a session id, name, or message preview; an unambiguous match resumes, several matches re-list. `/compact` and `/rewind` are refused while a turn is running.

## Context

The agent context is the projected message list sent to the model. These commands stage edits to it, then commit or discard them as a set. See [Context lens](/kli/guides/inspect-and-edit-context).

| Command | Effect |
| --- | --- |
| `/context inspect` | Show the context epoch, projected message count, and staged patches. |
| `/context stage append <text>` | Stage a patch appending a user message with `text`. |
| `/context stage remove <index>` | Stage a patch removing the message at `index`. |
| `/context stage replace <index> <text>` | Stage a patch replacing the message at `index` with `text`. |
| `/context diff` | Show staged patches without applying them. |
| `/context commit` | Apply all staged patches to the context, advancing the epoch. |
| `/context revert` | Discard all staged patches. |

Each subcommand is a separate registered command resolved from the `/context <subcommand>` prefix. Staging never changes the context; only `/context commit` does.

## Model and providers

These commands choose the model, set reasoning effort, and manage provider credentials. See [Connect a provider](/kli/guides/connect-a-provider).

| Command | Effect |
| --- | --- |
| `/model [provider/model [level]]` | Select the current model, optionally with a `reasoning-effort` level; bare, show and list. Menu-backed. |
| `/models [search]` | List auth-available models, optionally filtered by `search`; option-capable models show compact `options ...` markers. |
| `/providers` | List model providers with their auth status and model counts. |
| `/thinking [level]` | Set the `reasoning-effort` option for the selected model, or show the current level. Menu-backed. |
| `/auth` | Show registered providers and credential references. |

A model reference is `provider/model`, for example `anthropic/claude-sonnet-4-5`. The `/thinking` level is one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, accepted only for a model that declares `reasoning-effort`. kli ships the providers `anthropic`, `openai`, `openai-codex`, and `compatible` (user-defined OpenAI-compatible endpoints).

`/auth` takes a subcommand to register or remove credentials:

| Command | Effect |
| --- | --- |
| `/auth env <provider> <ENV_VAR>` | Read the provider's credential from environment variable `ENV_VAR`. |
| `/auth key <provider> <KEY>` | Store `KEY` as the provider's static API key. |
| `/auth login <provider>` | Start an OAuth login and print the authorization URL. |
| `/auth code <pasted code or redirect URL>` | Complete the pending OAuth login. |
| `/auth logout <provider>` | Forget the provider's stored credential. |

`/auth` is hidden from the model, since its tail can carry a raw API key.

## Configuration

| Command | Effect |
| --- | --- |
| `/settings` | Show config directories, the global and project settings files, registered resource kinds, and the merged settings. |

kli merges settings from `~/.config/kli/settings.json` and `<repo>/.kli/settings.json`, project over global. See [Settings](/kli/config/settings).

## Profiles

A profile is a named set of extensions and settings. See [Profiles](/kli/config/profiles).

| Command | Effect |
| --- | --- |
| `/profile [name]` | List profiles, or live-switch to profile `name`. |

A live switch installs the extensions the target profile wants and retracts the ones it does not. A profile whose builtin base differs from the running one cannot be switched live; kli reports the `--profile` flag to restart with instead.

## Extensions

These commands control user extensions discovered from `~/.config/kli/extensions/` and `<repo>/.kli/extensions/`, plus any passed with `--extension`. See [Extensions](/kli/extend/lisp-extensions).

| Command | Effect |
| --- | --- |
| `/extensions` | List discovered user extensions and whether each is enabled. |
| `/enable <extension>` | Install (enable) a discovered extension by id. |
| `/disable <extension>` | Retract (disable) an installed extension by id. |
| `/reload` | Retract, re-discover, and re-install user extensions, picking up edits on disk. |
| `/uninstall <extension>` | Remove a runtime-installed extension and its pin. Nix-declared extensions cannot be uninstalled this way. |

## App

| Command | Effect |
| --- | --- |
| `/install <url> <git-tree-sha1>` | Install a remote extension from `url`, pinned to the git tree object `git-tree-sha1`. |

`/install` here is the in-session command to add a remote **extension**. It is distinct from installing the kli application itself, which is `curl -fsSL https://kli.kleisli.io | sh` and has nothing to do with this command. The in-session `/install` runs a two-step consent flow in the terminal UI: it shows a trust card for the URL and pin, verifies the artifact against the pinned git tree sha1 without loading it, then installs on a second confirmation. The pin makes the install reproducible: the same `git-tree-sha1` always resolves the same code. `/install` requires the terminal UI.

## Diagnostics

| Command | Effect |
| --- | --- |
| `/bash <command>` | Run `command` in a shell and show its output. |
| `/eval <form>` | Evaluate a Common Lisp `form` in the running image and show the result. |
| `/observability` | Report the observability sink: whether it is enabled, its file path, event filter, and event count. |

`/bash` and `/eval` run the same tools the agent uses, invoked by hand. The observability sink is configured under the `observability` section of `settings.json`; `/observability` reports its live state.

## Prompt and skill commands

Two command families are registered from files at startup, so their names depend on what is on disk.

| Command | Effect |
| --- | --- |
| `/<template>` | Expand the prompt template named `<template>` and submit it as your next message. |
| `/skill:<name>` | Expand the skill named `<name>` and submit it as your next message. |

Prompt templates are `*.md` files in the `prompts/` resource directories; each file `name.md` registers as `/name`, and the argument tail substitutes into the template body. Skills are discovered from the `skills/` resource directories and register as `/skill:<name>`. Both are hidden from the model as commands, because the expansion itself enters the conversation as your message. Run `/commands` to see the ones currently registered.


#### Tools


kli ships the tools the agent calls during a turn. Two run code: `bash` runs a shell command, `eval` runs Common Lisp in the live image. The rest are the file surface: `read`, `find`, and `search` look at files; `write` and `edit` change them.

Every tool carries a capability gate. A gate is a capability name the tool requires before it runs. By default kli grants every capability, so every tool runs. The `capabilities` array in `settings.json` overrides that: an empty array denies all gated tools, and an array of capability names grants exactly those (see [Capabilities](/kli/config/capabilities)). Each tool below lists its gate. A call whose gate is not granted returns an error and runs nothing.

## bash

Run a shell command in a child process. The command runs through `sh -c`, with stdout and stderr captured separately.

Capability gate: `process/exec`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `command` | string | yes | The shell command to run. |
| `directory` | string | no | Working directory for the command. Defaults to the process working directory. |
| `input` | string | no | Text fed to the command's stdin. Defaults to empty. |
| `shell` | string | no | Shell binary invoked with `-c`. Defaults to `sh`. |
| `timeout` | integer | no | Wall-clock limit in seconds. Defaults to 30, clamped to a maximum of 300. |

Output limits and behavior:

- A command that runs past its timeout is killed (its whole process group when possible) and the call returns an error naming the timeout.
- stdout and stderr are each capped at 1 MiB (1048576 characters). Output past the cap is dropped and the result notes the truncation.
- The exit code rides in the result details. A non-zero exit returns an error result.
- Interactive programs are rejected before the command runs. kli inspects the first effective command word (skipping `env`, `command`, `exec`, `time`, `sudo`, `doas`, leading assignments, and their options) and refuses these names: `vi`, `vim`, `nvim`, `nano`, `emacs`, `less`, `more`, `man`, `top`, `htop`, `watch`, `ssh`, `mosh`, `tmux`, `screen`. The rejection returns an error and runs nothing.

## eval

Read and evaluate Common Lisp forms in the running kli image. The forms run on a dedicated thread under the requested package. The value of each form, and anything the forms print, comes back in the result.

Capability gate: `image/eval`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `form` | string | yes | Common Lisp source. All forms in the string are read and evaluated in order. |
| `package` | string | no | Package the forms read and run in. Defaults to `CL-USER`. An unknown package name is an error. |

Output limits and behavior:

- Evaluation has the same time budget as `bash`: 30 seconds by default, 300 maximum. A form running past the deadline is interrupted, and the result notes that the interrupted form may have left image state partially modified.
- Captured output is capped at 1 MiB (1048576 characters), counted and dropped at the stream so a printing loop cannot exhaust the heap.
- Printed values are bounded: `*print-length*` is 100, `*print-level*` is 20, and `*print-circle*` is on, so a large or circular value prints to a finite string.

## read

Read a file and return its lines with anchors. Each line comes back as `LINE:HH|content`, where `LINE` is the 1-based line number and `HH` is a two-hex-digit hash of the line's content. These anchors are what `edit` references.

Capability gate: `file/read`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `path` | string | yes | File to read. |
| `start` | integer | no | First line of an inclusive 1-based range. A start past end-of-file is an error. |
| `end` | integer | no | Last line of the range. An end past end-of-file clamps to the last line. |
| `raw` | boolean | no | When true, return line content with no `LINE:HH|` prefix. Defaults to false. |

A read over a file larger than 2 MiB is an error, and the error names `search` as the way to inspect a file that large. An empty file reads as `(empty file)`. Reading a file records its current line hashes for the session, which is the read-before-edit state `edit` requires.

## find

List file paths matching a glob pattern. Returns paths only, no file content.

Capability gate: `file/read`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `pattern` | string | yes | Glob pattern, for example `src/**/*.lisp`. `*` spans a run of characters within one path segment; a bare `**` segment spans any depth, including zero. |

Symlinks to files match; symlinked directories are not descended. At most 1000 paths are reported, sorted, with any overflow counted in the output. The walk stops and returns a partial result if it visits 100000 entries or runs longer than 10 seconds; the stop is surfaced in the text.

## search

Search file contents with a regular expression across one file or a glob. Match lines come back as `*LINE:HH|content`, surrounding context lines as ` LINE:HH|content` (space-prefixed). Each matching file is read whole, so its anchors are recorded and ready for `edit` with no separate `read`.

Capability gate: `file/read`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `pattern` | string | yes | Regular expression matched against each line. |
| `path` | string | yes | A single file or a glob, for example `src/**/*.lisp`. |
| `context` | integer | no | Number of surrounding lines to show around each match. Defaults to 0. |

Files that fail to read as text are skipped. Files over 2 MiB are skipped, with the count surfaced in the result. The result is capped at 100 matching files and 1000 rendered match lines; the same 100000-entry and 10-second walk bounds as `find` apply.

## write

Write content to a file, replacing it whole. Missing parent directories are created. The file's prior content rides in the result details so the change can render as a diff.

Capability gate: `file/write`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `path` | string | yes | File to write. |
| `content` | string | yes | Full new content of the file. |

## edit

Apply a hashline patch to one or more files, or accept a pending Common Lisp repair preview. A patch is whole-or-nothing: every anchor is validated against current disk content before any file is written, and a single stale or unread anchor rejects the entire patch. No file is partially modified.

Capability gate: `file/edit`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `input` | string | mode-specific | A hashline patch (grammar below). Required unless accepting a repair preview. |
| `repair` | string | no | Common Lisp repair policy for unbalanced patch output: `safe` (default), `preview`, or `reject`. |
| `accept_repair` | string | mode-specific | Candidate id returned by a repair preview. Required only when accepting a preview. |
| `path` | string | with `accept_repair` | Target path for the candidate; used for authority gating and stale-content checks. |

A patch is one or more sections, each opened by a `@@ PATH` header and followed by ops:

| Line | Effect |
| --- | --- |
| `@@ PATH` | Section header. One or more sections per patch. |
| `+ LINE:HH` | Insert the following payload after the anchored line. |
| `+` | Insert payload at end of file (bare `+`). |
| `< LINE:HH` | Insert the following payload before the anchored line. |
| `<` | Insert payload at beginning of file (bare `<`). |
| `- A:HH..B:HH` | Delete the inclusive line range. |
| `= A:HH..B:HH` | Replace the range with the payload; no payload deletes the range. |
| `~content` | A payload line. Everything after `~` is verbatim. |

Anchor validation:

- The target file must have been read this session (by `read` or by a `search` that matched it). An unread file rejects the patch with a prompt to read it first.
- Each `LINE:HH` anchor is re-hashed against current disk content at edit time. A hash that no longer matches is stale and rejects the whole patch instead of overwriting changed content; the error names the file and line to re-read.
- Overlapping range ops, and an insert that falls inside a range op, are rejected, and the error names both spans.

On success the result reports each file as `Edited PATH (+added -removed)` and prints fresh `LINE:HH|content` anchors for the changed regions. Those anchors are valid for a follow-up edit with no intervening read. Edited files end with a trailing newline.

For Common Lisp source, `edit` checks the patched file for balanced delimiters before writing. Balanced output writes normally. Unbalanced output is repaired in memory according to `repair`: `reject` errors without writing, `preview` returns a candidate without writing, and `safe` writes only repairs classified as local to the edited range with a stable top-level form count. Unsafe repairs return a preview and must be accepted with `accept_repair` plus `path`; acceptance rechecks that the file has not changed since the preview.


#### Keymap


The kli terminal UI binds keys to editor, navigation, and app actions. Bindings are looked up by a key-id string. A key-id is the key's base name, prefixed by any modifiers in `modifier+...+base` form, all lowercase: `ctrl+z`, `alt+left`, `shift+tab`. The base name alone is the key-id for an unmodified key: `enter`, `escape`, `home`.

The tables below list every default binding. Lookups consult a user override layer first, then these defaults, so any binding here can be replaced through the [keybindings setting](#rebinding-keys).

## Session control

Two keys act on the running session rather than the editor. Each takes effect on a second press, with a hint between presses.

| Key | First press | Second press |
| --- | --- | --- |
| `Ctrl+C` | Arms quit, prints `Press Ctrl+C again to quit.` | Quits kli |
| `Esc` | While a turn is running, prints `Press Esc again to interrupt.` At an idle prompt with a turn to step past, prints `Press Esc again to rewind.` | While a turn is running, interrupts the turn. At an idle prompt, opens the rewind menu |

`Ctrl+C` interrupts in every terminal encoding; it is fixed and not part of the rebindable keymap.

`Esc` is bound to the `abort` action, and its effect depends on session state. During a running turn, the first press arms an abort and a second press within about 1.5 seconds interrupts the turn; a later second press re-arms instead, so a single stray press cannot interrupt. At an idle prompt, the first press arms a rewind and a second press within the same window opens the rewind menu over the session's user turns. In the rewind menu, Up/Down move the selection, Enter rewinds to before the chosen turn, and Esc dismisses the menu. On an empty conversation `Esc` does nothing.

## App actions

| Key | Action | Effect |
| --- | --- | --- |
| `Ctrl+L` | `clear-screen` | Clears the screen |
| `Ctrl+O` | `tool-output` | Toggles expansion of tool output, then reprints the transcript |
| `Enter` | `submit` | Submits the prompt |
| `Ctrl+J`, `Shift+Enter` | `newline` | Inserts a newline in the editor |

## Editing

| Key | Action | Effect |
| --- | --- | --- |
| `Backspace` | `backspace` | Deletes the character before the cursor |
| `Delete`, `Ctrl+D` | `delete-char-forward` | Deletes the character after the cursor |
| `Ctrl+U` | `delete-to-line-start` | Deletes from the cursor to the start of the line |
| `Ctrl+K` | `delete-to-line-end` | Deletes from the cursor to the end of the line |
| `Ctrl+W`, `Alt+Backspace` | `delete-word-backward` | Deletes the word before the cursor |
| `Alt+D`, `Alt+Delete` | `delete-word-forward` | Deletes the word after the cursor |
| `Ctrl+Z` | `undo` | Undoes the last edit |
| `Tab` | `insert-tab` | Inserts a tab |
| `Space` | `insert-space` | Inserts a space |

## Navigation

| Key | Action | Effect |
| --- | --- | --- |
| `Left`, `Ctrl+B` | `move-char-left` | Moves the cursor one character left |
| `Right`, `Ctrl+F` | `move-char-right` | Moves the cursor one character right |
| `Up`, `Ctrl+P` | `move-line-up` | Moves the cursor up one line |
| `Down`, `Ctrl+N` | `move-line-down` | Moves the cursor down one line |
| `Home`, `Ctrl+A` | `move-line-start` | Moves the cursor to the start of the line |
| `End`, `Ctrl+E` | `move-line-end` | Moves the cursor to the end of the line |
| `Alt+B`, `Alt+Left`, `Ctrl+Left` | `move-word-left` | Moves the cursor one word left |
| `Alt+F`, `Alt+Right`, `Ctrl+Right` | `move-word-right` | Moves the cursor one word right |

## Inert keys

These keys are recognized so they never insert literal text, and otherwise do nothing.

| Key | Action |
| --- | --- |
| `Insert`, `Shift+Tab` | `swallow` |
| `Page Up`, `Page Down` | `ignore` |

## Rebinding keys

The `keybindings` setting in `settings.json` maps key-id strings to action names. Each entry overrides the default for that key-id; the default keymap is untouched and stays in effect for every key you do not name.

```json
{
  "keybindings": {
    "ctrl+r": "delete-to-line-start",
    "alt+z": "undo"
  }
}
```

Keys are key-id strings as described above (lowercase, `modifier+...+base`). Values are action names. Hyphens and underscores are interchangeable in an action name, so `delete-to-line-start` and `delete_to_line_start` both resolve. An entry whose value is not a known action is skipped with a warning; the rest of the table still applies. A `keybindings` value that is not an object is ignored with a warning.

kli reads `settings.json` from two locations and merges them, project over global:

- Global: `~/.config/kli/settings.json`
- Project: `<repo>/.kli/settings.json`

A project `keybindings` entry overrides the global entry for the same key-id, key by key. See [Settings](/kli/config/settings) for the full settings layering.

### Bindable actions

A `keybindings` value must be one of these action names.

| Action | Effect |
| --- | --- |
| `clear-screen` | Clears the screen |
| `tool-output` | Toggles tool-output expansion |
| `submit` | Submits the prompt |
| `newline` | Inserts a newline |
| `backspace` | Deletes the character before the cursor |
| `move-char-left` | Moves the cursor one character left |
| `move-char-right` | Moves the cursor one character right |
| `move-line-up` | Moves the cursor up one line |
| `move-line-down` | Moves the cursor down one line |
| `move-line-start` | Moves the cursor to the start of the line |
| `move-line-end` | Moves the cursor to the end of the line |
| `move-word-left` | Moves the cursor one word left |
| `move-word-right` | Moves the cursor one word right |
| `delete-char-forward` | Deletes the character after the cursor |
| `delete-to-line-start` | Deletes from the cursor to the start of the line |
| `delete-to-line-end` | Deletes from the cursor to the end of the line |
| `delete-word-backward` | Deletes the word before the cursor |
| `delete-word-forward` | Deletes the word after the cursor |
| `insert-tab` | Inserts a tab |
| `insert-space` | Inserts a space |
| `abort` | Interrupts the running turn, or arms the rewind menu at an idle prompt; takes effect on a second press |
| `undo` | Undoes the last edit |
| `swallow` | Consumes the key with no effect |
| `ignore` | Consumes the key with no effect |


#### Themes


A theme maps named color tokens to RGB values. The terminal UI styles every span — message text, tool cards, diffs, markdown, syntax highlighting — by looking up a token in the active theme. kli ships two built-in themes, `dark` and `light`, and chooses between them by reading the terminal background unless you pin one.

## Selecting a theme

The `theme` key in `settings.json` sets the active theme. Settings are read from `~/.config/kli/settings.json` (global) and `<repo>/.kli/settings.json` (project); the project value overrides the global one.

| Value | Effect |
| --- | --- |
| `"auto"` | Detect the terminal background at startup and select `dark` or `light`. |
| absent | Same as `"auto"`. |
| `"dark"` | Pin the dark theme. No detection. |
| `"light"` | Pin the light theme. No detection. |
| any registered theme name | Pin that theme. No detection. |

An unknown name is ignored with a warning, and the previous active theme stays in effect. A pinned theme suppresses background detection for the rest of the session.

```json
{
  "theme": "dark"
}
```

## Background detection

When `theme` is `"auto"` or absent, kli resolves `dark` or `light` at startup from the terminal background color. Detection runs only when standard input is a TTY and the `STY` environment variable is unset (it is skipped under GNU `screen`).

Resolution proceeds in order:

1. **OSC 11 query.** kli writes the OSC 11 background-color query followed by a DA1 (Device Attributes) request, then reads the reply with a 150 ms deadline. A reply of the form `rgb:RRRR/GGGG/BBBB` (8-bit or 16-bit channels, BEL- or ST-terminated) yields an RGB triple. The DA1 reply arriving first marks the terminal as not supporting the query.
2. **Luminance classification.** An RGB triple is converted to WCAG relative luminance after undoing sRGB gamma. Luminance below `0.5` classifies as `dark`; at or above `0.5` classifies as `light`.
3. **COLORFGBG fallback.** When the OSC 11 query returns no color (unsupported or timed out), the trailing background index of the `COLORFGBG` environment variable decides. Indices `0`–`6` and `8` read as `dark`; `7` and `9`–`15` read as `light`; any other value is treated as unset.
4. **Default.** With no usable signal from either source, the background resolves to `dark`.

Keystrokes typed during the query window are buffered and replayed after detection, so the handshake does not drop input.

## Token inventory

Every built-in theme defines the same set of tokens. A token whose value is empty resolves to the terminal default foreground (no color emitted). Tokens ending in `Bg` are background colors; the rest are foreground colors.

### Core

| Token | Role |
| --- | --- |
| `text` | Default message text. |
| `accent` | Accent color for emphasis. |
| `muted` | De-emphasized text. |
| `dim` | Further de-emphasized text. |
| `border` | Default border. |
| `borderAccent` | Accented border. |
| `borderMuted` | De-emphasized border. |
| `success` | Success state. |
| `error` | Error state. |
| `warning` | Warning state. |
| `selectedBg` | Background of the selected item. |
| `thinkingText` | Thinking-stream text. |
| `bashMode` | Bash-mode indicator. |

### Messages

| Token | Role |
| --- | --- |
| `userMessageBg` | User message background. |
| `userMessageText` | User message text. |
| `customMessageBg` | Custom message background. |
| `customMessageText` | Custom message text. |
| `customMessageLabel` | Custom message label. |

### Tool cards

| Token | Role |
| --- | --- |
| `toolPendingBg` | Pending tool-call background. |
| `toolSuccessBg` | Succeeded tool-call background. |
| `toolErrorBg` | Failed tool-call background. |
| `toolTitle` | Tool-call title. |
| `toolOutput` | Tool output text. |
| `toolDiffAdded` | Added line in a diff. |
| `toolDiffRemoved` | Removed line in a diff. |
| `toolDiffContext` | Unchanged context line in a diff. |

### Markdown

| Token | Role |
| --- | --- |
| `mdHeading` | Heading. |
| `mdLink` | Link text. |
| `mdLinkUrl` | Link URL. |
| `mdCode` | Inline code. |
| `mdCodeBlock` | Code block body. |
| `mdCodeBlockBorder` | Code block border. |
| `mdQuote` | Blockquote text. |
| `mdQuoteBorder` | Blockquote border. |
| `mdHr` | Horizontal rule. |
| `mdListBullet` | List bullet. |

### Syntax highlighting

| Token | Role |
| --- | --- |
| `syntaxComment` | Comment. |
| `syntaxKeyword` | Keyword. |
| `syntaxFunction` | Function name. |
| `syntaxVariable` | Variable. |
| `syntaxString` | String literal. |
| `syntaxNumber` | Numeric literal. |
| `syntaxType` | Type name. |
| `syntaxOperator` | Operator. |
| `syntaxPunctuation` | Punctuation. |

### Thinking levels

| Token | Role |
| --- | --- |
| `thinkingOff` | Thinking disabled. |
| `thinkingMinimal` | Minimal thinking. |
| `thinkingLow` | Low thinking. |
| `thinkingMedium` | Medium thinking. |
| `thinkingHigh` | High thinking. |
| `thinkingXhigh` | Extra-high thinking. |

## Color rendering

Token colors are RGB and render according to the detected terminal color mode. With `COLORTERM` set to `truecolor` or `24bit`, kli emits 24-bit color. With `256color` in `TERM`, each color is mapped to the nearest xterm-256 index by a redmean perceptual distance over the 6×6×6 color cube and the 24-step gray ramp. Otherwise no color is emitted and text renders plain.

## Related

- [Configuration reference](/kli/config/settings) — every `settings.json` key.
- [Keymap](/kli/commands/keymap) — default key bindings.


### Settings & Files

#### settings.json


`settings.json` configures kli's defaults: theme, key bindings, the model it starts on, where it writes session logs to, what its tools may do, which profile it boots, model option defaults, automatic compaction, and the observability sink. It is a single JSON object. Every key is optional.

kli reads two files and merges a profile overlay on top:

| Layer | Path | Precedence |
| --- | --- | --- |
| Global | `~/.config/kli/settings.json` | lowest |
| Project | `<repo>/.kli/settings.json` | over global |
| Profile overlay | the active profile's `settings` block | over both |

The project file is the nearest `.kli/settings.json` at or above the working directory, bounded by the repository root. The global path follows `$XDG_CONFIG_HOME`; `~/.config/kli/` is the default.

A kli image built with the [`programs.kli`](/kli/config/nix-module) Nix module can carry one more layer *below* the global file: the keys baked in through `programs.kli.settings`. They act as image defaults, and the global and project files always override them.

## Merge behavior

The layers deep-merge. For any key whose value is a JSON object, the higher layer's object merges into the lower layer's object key by key; for any other type the higher layer's value replaces the lower one. So a project file can override one nested key (a single `keybindings` entry, one `defaultOptions` entry, one `observability` field) without restating the rest, while a scalar like `defaultModel` is replaced outright.

The profile overlay applies last. Selecting a profile whose `settings` block sets a key wins over both files for that key. See [Profiles](/kli/config/profiles).

## Fail-soft

A settings file that does not exist, does not parse as JSON, or whose top level is not an object is reported as a warning and skipped; the other layers still load. A key whose value has the wrong type is reported and ignored, and kli keeps the default for that key. Malformed input never aborts startup. Warnings raised during boot surface in the session transcript rather than the terminal, because the UI takeover would otherwise erase them.

## Keys

| Key | Type | Default | Effect |
| --- | --- | --- | --- |
| `theme` | string | `"auto"` | Active color theme. `"auto"` resolves a light or dark theme from the terminal background. An unknown name is ignored with a warning. |
| `keybindings` | object | none | Map of key id to action name. See [Key bindings](#keybindings). |
| `defaultProvider` | string | none | Model provider kli selects at startup. One of `anthropic`, `openai`, `openai-codex`, or a custom provider id from `providers.json`. Takes effect only with `defaultModel`. |
| `defaultModel` | string | none | Model id within `defaultProvider` to select at startup. Takes effect only with `defaultProvider`. An unknown provider/model pair is ignored with a warning. |
| `defaultOptions` | object | none | Semantic model option defaults applied to the selected default model. Unsupported or invalid options are ignored with warnings. |
| `compaction` | object | automatic compaction enabled at 85% | Controls automatic session compaction. Disabling it does not disable manual `/compact`. See [compaction](#compaction). |
| `sessionDir` | string | session extension default | Directory kli writes session logs to. A leading `~` expands to the home directory; a relative path resolves against the working directory. |
| `capabilities` | array of strings | none | Capability names the agent's tools may exercise. See [Capabilities](/kli/config/capabilities). |
| `trustRoots` | array of strings | none (integrity only) | Hex ed25519 public keys a remote install's signature must verify under. Empty checks the git pin only; setting keys requires a trusted signature. See [trustRoots](#trustroots). |
| `profile` | string | `interactive-terminal` | Profile kli boots. Overridden by `--profile` and `KLI_PROFILE`. See [Profiles](#profile-profiles). |
| `profiles` | object | none | User-defined profile specs, keyed by name. See [Profiles](#profile-profiles). |
| `observability` | object | none | JSONL event sink. See [Observability](#observability). |
| `extensions` | object | none | Per-extension settings subtrees, keyed by extension. A declared subtree validates against its extension's schema. See [extensions](#extensions). |

### theme

A theme name pins that theme. `"auto"`, or the key absent, leaves kli to read the terminal background and pick a light or dark theme at boot. A name kli does not recognize is ignored with a warning, and the prior theme stands.

### keybindings

An object mapping a key id to an action name:

```json
{
  "keybindings": {
    "ctrl+z": "undo"
  }
}
```

Entries merge into the override layer over the built-in bindings. An action name kli does not recognize is skipped with a warning. A `keybindings` value that is not an object is ignored with a warning. The full action list is in [Key bindings](/kli/commands/keymap).

### defaultProvider, defaultModel, defaultOptions

`defaultProvider` and `defaultModel` together select the model kli starts on. Both must be present and name a registered model; otherwise the selection is skipped and the warning names the rejected pair. Built-in provider ids are `anthropic`, `openai`, and `openai-codex`; custom OpenAI-compatible endpoints use the provider ids declared in `~/.config/kli/providers.json`.

`defaultOptions` is a JSON object keyed by semantic model option id. It applies only when `defaultProvider` and `defaultModel` select a model, and each key must be supported by that model's option schema. Unsupported keys and invalid values are ignored with warnings. Accepted values are canonicalized before the session starts.

```json
{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-opus-4-8",
  "defaultOptions": {
    "reasoning-effort": "high"
  }
}
```

Built-in semantic option ids are documented in [Providers and Transports](/kli/models/providers-and-transports#semantic-options). A model must declare an option schema before the option can be set. `/thinking` is the command UI for the `reasoning-effort` option, so a later `/thinking` command overrides `defaultOptions.reasoning-effort` for the rest of that session.

### compaction

`compaction` is a JSON object that controls automatic session compaction after a model turn. It does not control manual compaction: `/compact` still works when `compaction.enabled` is `false`.

| Field | Type | Default | Effect |
| --- | --- | --- | --- |
| `enabled` | boolean | `true` | Whether kli automatically compacts when usage reaches the threshold. |
| `thresholdRatio` | number | `0.85` | Positive usage ratio of the selected model's context window that triggers automatic compaction after a turn. |
| `reserveTokens` | integer | derived from context window | Positive token count to keep verbatim when compacting. When absent, kli derives a recent window from the model context size. |

```json
{
  "compaction": {
    "enabled": false,
    "thresholdRatio": 0.9,
    "reserveTokens": 30000
  }
}
```

Set only the fields you need; object merge behavior lets project settings override one field without restating the rest.

### sessionDir

The directory kli writes its session log to. A leading `~` expands to the home directory; a relative path resolves against the working directory; an absolute path is used as written. When absent, the session extension's own default location applies.

### capabilities

The authority every agent's tools run under. kli is fully permissioned by default: when the key is absent, the default subject applies and passes every capability check. There is no interactive approval prompt; restriction is configured here, up front.

The value is an array of capability name strings. A present array grants exactly those capabilities, transitively closed over their implications, and denies every gated operation outside that closure. An empty array denies all gated operations. A value that is not an array of strings is ignored with a warning, and the default subject applies.

```json
{
  "capabilities": ["file/read"]
}
```

The capability names, the implication rules that let a coarse name like `tools/standard` grant finer ones, and the full table of gated operations are in [Capabilities](/kli/config/capabilities).

### trustRoots

`trustRoots` opts in to signature verification for extensions installed from a URL with `kli install` or `/install`. It is an array of hex-encoded ed25519 public keys — the publishers you choose to trust.

When the array is absent or empty, a remote install verifies the **integrity floor** only: the fetched bytes must match their git-object pin, and anyone may publish. When the array holds one or more keys, kli additionally requires that the artifact carry a detached ed25519 signature — fetched from `<url>.sig` — that verifies under one of these keys over the exact bytes served. A missing signature, or one from a key you do not list, is refused rather than downgraded, and the check does not weaken when a later session restores the install.

```json
{
  "trustRoots": [
    "3f8a1c2e9b7d4f60a51e8c2d9f0b4a7c6e1d3b850a51e8c2d9f0b4a7c6e1d3b85"
  ]
}
```

Each entry is the 64-character hex of a 32-byte ed25519 public key. A malformed or empty entry is dropped with a warning while the remaining keys stand, so one bad line never silently disables the ceiling; a `trustRoots` value that is not an array is ignored with a warning and leaves the integrity floor in place. For the publisher side — minting a key, signing an artifact, and handing out the public half — see [Publishing extensions](/kli/extend/publishing-extensions).

### profile, profiles

`profile` names the profile kli boots. Resolution order is the `--profile` flag, then the `KLI_PROFILE` environment variable, then this key, then the default `interactive-terminal`. The other built-in profiles are `headless`, `human-in-loop`, and `autonomous`.

`profiles` declares user-defined profiles, an object keyed by profile name. Each entry may carry `extends`, `enable`, `disable`, and a `settings` overlay. A name that shadows a built-in profile is ignored with a warning, as is a malformed entry. Both keys are documented in [Profiles](/kli/config/profiles).

### observability

A nested object configuring a JSONL event sink:

| Field | Type | Default | Effect |
| --- | --- | --- | --- |
| `path` | string | none | File the sink appends events to. A leading `~` expands to the home directory; a relative path resolves against the working directory. Absent or empty leaves the sink off. |
| `events` | array of strings | none | Event-type name prefixes to record. A non-string member is dropped. Absent records every event. |

```json
{
  "observability": {
    "path": "~/.kli-events.jsonl",
    "events": ["tool", "model"]
  }
}
```

### extensions

A top-level object whose keys are per-extension settings subtrees. Each installed extension may declare its subtree — the key names and value schemas it accepts — as a [`settings` contribution](/kli/extend/lisp-extensions/contribution-kinds#declare-a-settings-subtree). Declaring buys the extension the same treatment every built-in key gets:

- **Validation with boot diagnostics.** When the extension activates, its subtree is checked against the declared schema, and every mismatch — a wrong type, a value outside its bounds, an enum member the schema does not list, a key the schema does not know — is reported as a warning naming the exact path (`extensions.skar.cairn.granularity: expected one of "stage", "run", got "leaf"`). Fail-soft as everywhere in settings: diagnostics never abort startup.
- **`/settings` introspection.** The command lists each declared subtree, whether the files carry it, and its current diagnostics — plus any keys under `extensions` that no installed extension declares.
- **Declared defaults.** A key the schema declares a default for reads as that default when the files omit it, so an extension's documented defaults hold without the user writing them out.
- **Tiering.** The `extensions` object deep-merges like every other key: a project file overrides one nested key of one extension's subtree without restating the rest, and a profile overlay wins over both files.

```json
{
  "extensions": {
    "skar": {
      "models": { "big": "anthropic/claude-opus-4-8" },
      "toolResultCap": 4096,
      "cairn": { "granularity": "run" }
    }
  }
}
```

Describes, never grants: no key under `extensions` confers authority. An extension's settings configure its defaults and sinks; what its tools may do is governed by [`capabilities`](#capabilities) alone.

## Reload

The merged view re-reads both files when settings reload, and the active profile overlay re-merges on top of the fresh files. A profile switch reverts the standing overlay and applies the new one, so `theme`, `keybindings`, the default model, `defaultOptions`, `compaction`, `sessionDir`, and `capabilities` all follow the switch.


#### config.json


`config.json` controls extension discovery. kli reads one copy, at
`~/.config/kli/config.json`. There is no project-local `config.json`: the file is
global only.

It is a separate file from `settings.json`. `settings.json` configures behavior
(theme, model, capabilities, profiles, and the rest); `config.json` holds nothing
but the three keys below. If the file is absent, kli discovers extensions from its
default directories alone. If it is present but malformed, kli reports the problem
and ignores the file rather than stopping.

All three keys are optional. Each is a JSON array; an absent key is the empty
array.

## Keys

| Key | Type | Default | Effect |
| --- | --- | --- | --- |
| `enabled` | array of strings | `[]` | Extension ids to install at boot. An id here is installed even when the extension's own metadata sets it to load off by default. |
| `disabled` | array of strings | `[]` | Extension ids to keep off at boot. An id here is not installed, whatever its default. |
| `extension-dirs` | array of strings | `[]` | Extra directories kli scans for extensions, in addition to its default discovery directories. |

## `enabled` and `disabled`

Each entry is an extension id, the same name shown by the `/extensions` command
and used with `/enable` and `/disable`. Ids are matched case-insensitively:
`my-ext` and `MY-EXT` name the same extension.

The two lists feed the boot decision for each discovered extension. The decision
resolves in this order, stopping at the first rule that applies:

1. The active profile disables the id.
2. The active profile enables the id.
3. `disabled` lists the id.
4. `enabled` lists the id.
5. The extension's own `autoload` metadata.
6. Enabled.

Profile entries take precedence over `config.json`, and `config.json` takes
precedence over an extension's own default. An id in both `enabled` and
`disabled` is disabled, since `disabled` is checked first. These keys change only
what is installed at boot; `/enable` and `/disable` change the running session
without editing the file. For profile precedence, see
[Profiles](/kli/config/profiles).

## `extension-dirs`

Each entry is a directory path. kli scans every listed directory for extensions
and adds what it finds to its default discovery (the global
`~/.config/kli/extensions/` directory and the project's `<repo>/.kli/extensions/`
directory). A listed directory that does not exist is skipped. The
`enabled`/`disabled` decision then applies to every discovered extension,
wherever it was found.

## Example

```json
{
  "enabled": ["my-ext"],
  "disabled": ["noisy-ext"],
  "extension-dirs": ["~/code/kli-extensions"]
}
```

For the discovery directories and the rest of the paths kli reads, see
[Files and paths](/kli/config/files-and-paths).


#### The programs.kli Module


kli adds an extension one of two ways. Imperatively, `kli install <url> <pin>` fetches and verifies one at runtime, per user, with no rebuild. Declaratively, `programs.kli` compiles a kli image with your extensions and settings baked in, so they are present at every launch. This page is the declarative surface: a Home Manager module and a NixOS module, both from the kli flake. Trust comes from your flake inputs and Nix hashing — there is no per-URL pin and nothing installs at runtime.

## Enable the module

Add the kli flake as an input:

```nix
{
  inputs.kli.url = "github:kleisli-io/kli";
}
```

Import the module for your system and turn it on. Home Manager:

```nix
{
  imports = [ inputs.kli.homeManagerModules.default ];

  programs.kli.enable = true;
}
```

NixOS:

```nix
{
  imports = [ inputs.kli.nixosModules.default ];

  programs.kli.enable = true;
}
```

With `enable` alone the module installs a plain kli image with no extensions baked in. The Home Manager module installs it into `home.packages`; the NixOS module into `environment.systemPackages`.

## Bake in an extension

List a flake package in `extensions` and it is compiled into the image. cairn, for instance, is a flake input whose package you name; it needs SQLite on the library path for its FTS5-backed store:

```nix
programs.kli = {
  enable = true;
  extensions = [ inputs.cairn.packages.${system}.default ];
  blessedNativeLibs = [ pkgs.sqlite ];
  settings.defaultModel = "claude-opus-4-8";
};
```

Rebuild and the extension is part of the image. It loads at every launch with no runtime install and no pin, and stays put until you edit the configuration and rebuild.

## Options

| Option | Type | Default | Effect |
| --- | --- | --- | --- |
| `enable` | boolean | `false` | Install a kli image built from these options. |
| `extensions` | list of packages | `[]` | Extensions compiled into the image. Each is a Nix package following the [extension contract](#extensions). |
| `settings` | attribute set | `{}` | `settings.json` keys baked as the [lowest settings layer](#settings). |
| `registries` | list | `[]` | Registry entries baked into the image's configuration. |
| `blessedNativeLibs` | list of packages | `[]` | Native libraries placed on the image's library search path. See [blessedNativeLibs](#blessednativelibs). |
| `dataDir` | null or string | `null` | Project-local data directory. `null` resolves it from the runtime environment. |
| `sandbox` | null or submodule | `null` | Whole-process bwrap confinement. `null` leaves the binary unwrapped. See [sandbox](#sandbox). |
| `package` | package | image built from the options above | The package to install. Set it to install an image of your own. See [package](#package). |

### extensions

An extension you list here is a Nix package, not a URL. kli composes it into the image as a build dependency, so it must be a buildLisp library — the builder kli itself is built with — carrying two `passthru` fields:

- `passthru.name` — the extension id.
- `passthru.manifestSymbol` — the package-qualified symbol naming the extension's manifest. The build fails if the compiled image does not export it, so a mislabelled package cannot ship silently.

The list must not include the core `kli` library; the module asserts against it. As a consumer you take the author's flake as an input and add its package:

```nix
programs.kli.extensions = [ inputs.some-extension.packages.${system}.default ];
```

Producing such a package — the buildLisp library, where `buildLisp` comes from, and the `passthru` contract — is the author side, covered in [Distribute as a Nix package](/kli/extend/publishing-extensions#distribute-as-a-nix-package).

### settings

`settings` bakes the same `settings.json` keys the on-disk files use, as the **lowest-precedence** layer. The merge order is baked < global < project, with the active profile overlay applied last, so a user's `~/.config/kli/settings.json` always overrides what you bake. Use it to ship image defaults — a default model, theme, or capability set — that a user can still override without editing your configuration. The keys and their merge rules are in [settings.json](/kli/config/settings).

### blessedNativeLibs

Native shared libraries added to the image's library search path. An extension that binds a C library names it here so the symbol resolves at load: cairn needs `pkgs.sqlite` for its FTS5 store. Extensions with no native dependency leave this empty.

### sandbox

Whole-process confinement via bwrap — confinement the binary cannot switch off. `null` leaves the binary unwrapped. An attribute set wraps the entrypoint so the working directory is the writable root and the rest of the filesystem is read-only, with the process and IPC namespaces unshared.

| Field | Type | Default | Effect |
| --- | --- | --- | --- |
| `network` | boolean | `true` | Keep network access. `false` unshares the network namespace, which also cuts the model API — usable only with a local model. |
| `writablePaths` | list of strings | `[]` | Extra paths bound writable, beyond the working directory. |
| `denyRead` | list of strings | `[]` | Paths hidden from the confined process: a file reads as empty, a directory as empty. The at-rest mask for secrets such as credential files. |
| `denyEnv` | list of strings | `[]` | Environment variable names unset before the process starts. The in-environment twin of `denyRead`. |
| `nestedUserns` | boolean | `false` | Set when the image runs inside an outer unprivileged user namespace whose `/proc` is masked, such as a systemd-nspawn or OCI container. |

The sandbox model, and how it relates to the capability layer, is in [Security model and sandboxing](/kli/concepts/security-model-and-sandboxing).

### package

The module builds `package` from the options above by default. Set it to install an image you built yourself — with the flake's `lib.<system>.mkConfiguredKli` (below) or any override — and the other build options no longer describe what gets installed.

## Without a module

Outside a Home Manager or NixOS configuration, the flake exposes `lib.<system>.mkConfiguredKli`. It takes the same options and returns the image derivation, for a `nix build` target or a devShell:

```nix
inputs.kli.lib.${system}.mkConfiguredKli {
  extensions = [ inputs.cairn.packages.${system}.default ];
  blessedNativeLibs = [ pkgs.sqlite ];
}
```

The module's `package` default is exactly this call over your options.

## Declarative or imperative

The two channels coexist, and you can use both in one setup:

- **Declarative** — this module. Extensions are compiled into the image at build time, reproducible, trusted through your flake inputs and Nix hashing, present at every launch. Preferred for Nix users.
- **Imperative** — `kli install <url> <pin>` at runtime, per user, verified by a git-object pin and an opt-in signature, no rebuild. See [Sharing extensions](/kli/extend/sharing-extensions).

Bake the extensions you always want into the image, and install the occasional one at runtime.

## Related

- [Distribute as a Nix package](/kli/extend/publishing-extensions#distribute-as-a-nix-package) — the author side: building an extension into a Nix package this module can consume.
- [Sharing extensions](/kli/extend/sharing-extensions) — the runtime install, the imperative alternative to baking in.
- [settings.json](/kli/config/settings) — the keys `programs.kli.settings` bakes.
- [Installation](/kli/cli/installation#nix) — installing kli itself via the flake.
- [Security model and sandboxing](/kli/concepts/security-model-and-sandboxing) — the confinement `sandbox` configures.


#### Capabilities


A capability is a named permission. Gated operations call for a capability before
they run; the call proceeds only if the current subject holds it.

kli is fully permissioned by default. The default subject passes every capability
check, so every gated operation runs. There is no interactive approval prompt.
Restriction is configured up front through the `capabilities` array in
`settings.json` (see [Restricting with settings](#restricting-with-settings)
below).

## Capability vocabulary

Capability names are lowercase strings with a slashed namespace, for example
`file/read` or `manifest/install`. The names below make up the vocabulary the
shipped tools and operations draw on.

### Tools

| Capability | Gates |
|---|---|
| `file/read` | The `read`, `find`, and `search` tools. |
| `file/write` | The `write` tool. |
| `file/edit` | The `edit` tool. |
| `process/exec` | The `bash` tool. |
| `image/eval` | The `eval` tool, which evaluates Common Lisp in the running image. |
| `tools/standard` | Convenience name for the four file and process capabilities. See [Implication rules](#implication-rules). |

### Extension lifecycle

| Capability | Gates |
|---|---|
| `manifest/install` | Activating an extension (installing its contributions). |
| `manifest/retract` | Deactivating an extension (retracting its contributions). |
| `image/recode` | Replacing an extension's source in place (deactivate then reactivate). |
| `manifest/install-remote` | Installing a remote extension with `/install`. |
| `image/load-dep` | A grant in the dependency-load implication chain. No shipped operation checks it directly. |
| `image/load-native` | The native-load grant carried by a remote install. No shipped operation checks it directly. |

### Credentials

| Capability | Gates |
|---|---|
| `auth/register-reference` | Recording a credential for a provider. |
| `auth/resolve-secret` | Reading a stored secret value. |
| `auth/read-metadata` | Inspecting the credential store (provider list, reference metadata; never secret values). |
| `auth/forget-secret` | Deleting a stored credential. |

## Implication rules

A coarse capability implies finer ones. Granting a capability grants its full
closure, computed transitively at subject construction. Holding any capability in
the table below grants every capability it implies.

| Capability | Implies |
|---|---|
| `tools/standard` | `file/read`, `file/write`, `file/edit`, `process/exec` |
| `image/recode` | `manifest/install`, `manifest/retract` |
| `manifest/install-remote` | `manifest/install`, `image/eval` |
| `image/load-native` | `image/load-dep`, `image/eval` |
| `image/load-dep` | `image/eval` |

Implications compose. Granting `manifest/install-remote` also grants
`manifest/install` and `image/eval`; granting `image/load-native` grants
`image/load-dep` and, through it, `image/eval`.

## Gated operations

| Operation | Required capability |
|---|---|
| Invoke a tool | Each capability listed in the tool's metadata (the table above). |
| Activate an extension | `manifest/install` |
| Deactivate an extension | `manifest/retract` |
| Recode an extension | `image/recode` (implies `manifest/install` and `manifest/retract`) |
| Install a remote extension (`/install`) | `manifest/install-remote` |
| Register a credential | `auth/register-reference` |
| Resolve a credential | `auth/resolve-secret` |
| Inspect the credential store | `auth/read-metadata` |
| Forget a credential | `auth/forget-secret` |

A gated operation whose capability the subject lacks signals an error and does
not run.

## Restricting with settings

The `capabilities` key in `settings.json` sets the authority of every agent. Its
value is an array of capability name strings.

| Value | Effect |
|---|---|
| Key absent | The default subject applies. Every capability check passes. |
| Array of capability names | The subject holds exactly the implication-closure of those names. Capabilities outside the closure are denied. |
| Empty array `[]` | The subject holds nothing. Every gated operation is denied. |
| Any non-array value | The value is ignored with a warning, and the default subject applies. |

A restricting array denies only gated operations. Operations that check no
capability run regardless.

```json
{
  "capabilities": ["file/read", "process/exec"]
}
```

This subject can run the `read`, `find`, `search`, and `bash` tools. It cannot
write or edit files, evaluate Lisp, change extensions, or read credentials.
Granting `tools/standard` instead would grant all four file and process
capabilities through the implication rules above.

The `capabilities` key is read under the active profile overlay like every other
setting; see [Settings](/kli/config/settings) and
[Profiles](/kli/config/profiles).


#### Profiles


A profile is a named, ordered group of extension manifests that kli installs as a
unit at boot. It determines which extensions are present before any user
extension loads: whether the terminal UI is built, which model providers are
available, and which tools and commands exist. kli boots exactly one profile.

The kernel never learns about profiles. A profile installs through the same
manifest primitives as any other extension group, and its activation record
lives in per-protocol storage.

## Built-in profiles

kli ships four built-in profiles. Each composes one or more of the manifest
groups below and may declare seams (see [Seams](#seams)).

| Profile | Manifest groups | Declared seams | Terminal UI |
|---|---|---|---|
| `interactive-terminal` | baseline, nix-declared, model-provider, tui-app | — | yes |
| `human-in-loop` | baseline, nix-declared, model-provider, tui-app | `approval` | yes |
| `autonomous` | baseline, nix-declared, model-provider | `planner`, `scheduler`, `watchdog`, `recovery` | no |
| `headless` | baseline, nix-declared | — | no |

`interactive-terminal` is the default. A profile that omits the `tui-app` group
builds no TUI and runs no terminal loop; boot holds the main thread instead, and
boot diagnostics print to standard error rather than into a transcript.

### interactive-terminal

The default profile. Installs the baseline, the model providers, and the
terminal-UI extensions. This is the full interactive agent: a TUI with the
transcript, input editor, status widgets, completion, slash commands, and the
session bound for chat on boot. Declares no seam.

### human-in-loop

The same manifest groups as `interactive-terminal` — baseline, model providers,
and the terminal UI — and additionally declares the `approval` seam. The
`approval` seam is declared, not implemented: the profile names the extension
point but supplies nothing for it, and kli ships no `approval` provider. Booting
`human-in-loop` today gives you the same running extensions as
`interactive-terminal`. The seam marks where an approval extension would attach.

### autonomous

Installs the baseline and the model providers, and omits the `tui-app` group, so
it builds no terminal UI. Declares four seams: `planner`, `scheduler`,
`watchdog`, and `recovery`. As with `approval`, these are declared extension
points, not implemented behavior; kli ships no provider for any of them. Booting
`autonomous` brings up the agent substrate without a TUI and holds the main
thread.

### headless

The baseline group only: no model providers and no terminal UI. The minimal
substrate. Provider and UI extensions are absent, so the session is not bound for
chat on boot. The agent substrate stays alive without a terminal loop.

## Manifest groups

The groups each built-in profile composes from.

| Group | Contents |
|---|---|
| baseline | The kernel-facing substrate present in every profile: object and event extensions, the command and config services, the session log, the context lens, auth and OAuth, the model registry and runtime, the agent loop and session, the `eval`, `bash`, read, write, edit, find, and search tools, the filesystem-anchor lifecycle, and the runtime control, journal, snapshot, history, and introspection extensions. |
| nix-declared | Extensions a Nix-configured image declares present at boot. Empty in plain kli; only a configured image's boot shim populates it. Each profile splices it in directly after the baseline, so declared extensions boot as baseline children. |
| model-provider | The four model providers: `openai-codex`, `openai`, `anthropic`, and `compatible`. See [Providers](/kli/concepts/models-providers-and-transports). |
| tui-app | The terminal UI and everything bound to it: style, keymap, status, views, input, editor, terminal, markdown, transcript, and the TUI app itself; the basic and session commands; the `eval`, `bash`, and model commands; config commands; prompt templates; context-file commands; skills; completion; settings wiring; and observability. |

## Seams

A seam is a capability a profile declares as an extension point but does not
provide itself. It names where a user (or a future extension) is expected to
attach a provider to complete the profile. A profile carries its declared seams
in its activation record; declaring a seam installs nothing and runs nothing.

No built-in seam has an implementation in kli today. The `approval` seam declared
by `human-in-loop` and the `planner`, `scheduler`, `watchdog`, and `recovery`
seams declared by `autonomous` are markers only. In particular, `human-in-loop`
does not gate tool execution behind an approval step: kli is
[fully permissioned by default](/kli/concepts/capabilities-and-fault-barriers), and no profile
changes that.

## Selection precedence

kli resolves the boot profile name from the first source that supplies one, in
this order:

1. The `--profile <name>` command-line flag.
2. The `KLI_PROFILE` environment variable, when set and non-empty.
3. The `profile` key in settings (a non-empty string). The merged settings put
   the project file over the global file, so a project `.kli/settings.json` value
   overrides the one in `~/.config/kli/settings.json`.
4. The default, `interactive-terminal`.

A name that resolves to neither a built-in profile nor a declared data profile
warns and falls back to `interactive-terminal`. The warning surfaces as a boot
diagnostic.

The name is matched case- and separator-insensitively (normalized to a keyword),
so `human-in-loop` and `HUMAN_IN_LOOP` name the same profile.

## Custom data profiles

A data profile is a profile declared as data in settings rather than as a
built-in. It lives under a `profiles` object in `settings.json`, keyed by
profile name:

```json
{
  "profiles": {
    "review": {
      "extends": "interactive-terminal",
      "enable": ["my-review-helper"],
      "disable": ["some-noisy-extension"],
      "settings": {
        "model": "anthropic/claude-..."
      }
    }
  }
}
```

Each entry accepts these fields. All are optional.

| Field | Type | Effect |
|---|---|---|
| `extends` | string | Name of the profile this one builds on: another data profile or a built-in. The extends chain is walked until it bottoms at a built-in, which supplies the manifest groups. An entry with no `extends` bottoms at `interactive-terminal`. |
| `enable` | array of strings | User-extension ids to add to the effective set. A later entry in the chain has the last word over an earlier one for a given id. |
| `disable` | array of strings | User-extension ids to remove from the effective set. `enable` and `disable` for the same id resolve to whichever the chain states last. |
| `settings` | object | A settings overlay recorded for this profile. It merges over the chain's earlier overlays and is applied as the topmost settings layer (`global < project < overlay`) when the profile is active. |

A data profile is resolved into a base built-in plus effective `enable` and
`disable` delta sets and a merged settings overlay. The base built-in's manifest
groups install at boot; the deltas then gate which user extensions load on top.
Data profiles change the user-extension set and settings, not the built-in
manifest groups: a data profile cannot add a manifest group its base does not
already include.

Resolution is fail-soft. A malformed entry warns and is skipped. An entry whose
name collides with a built-in profile warns and is skipped — built-in names
cannot be shadowed. An unknown `extends` target or a cyclic `extends` chain warns
and the profile fails to resolve. Each warning surfaces as a boot diagnostic.

## Live switching

While kli is running, `/profile` with no argument lists the available profiles
with the active one marked, and `/profile <name>` switches to a named profile by
re-basing the user-extension pool onto the target's effective set and swapping
its settings overlay. A switch that would change the built-in base does not take
effect live; the base applies only at boot, and kli tells you to restart with
`--profile <name>`. See the [CLI reference](/kli/cli) for boot-time selection.


#### Files and Paths


kli reads and writes files under two roots: a global directory shared across every project, and a per-project directory inside the repository you run in. A third set of paths under the cache directory holds diagnostic output. This page lists every path, what kli stores there, and how it is resolved.

## Roots

| Root | Path | Resolution |
| --- | --- | --- |
| Global config | `~/.config/kli/` | `$XDG_CONFIG_HOME/kli/`; `~/.config/kli/` is the default. |
| Project config | `<repo>/.kli/` | The nearest `.kli/` directory at or above the working directory, bounded by the repository root (the directory holding `.git`). None outside a configured project. |
| Cache | `~/.cache/kli/` | `$XDG_CACHE_HOME/kli/`; `~/.cache/kli/` is the default. Diagnostic sinks only. |

The project root is found by walking up from the working directory to the repository root. A `.kli/` in an ancestor directory applies to every project under it; a `.kli/` deeper down extends and shadows it.

Where both roots hold the same kind of file, the global file loads first and the project file layers over it. For settings the two deep-merge; for discovery directories the project entries extend and shadow the global set.

## Configuration files

| Path | Purpose |
| --- | --- |
| `~/.config/kli/settings.json` | Global settings: theme, key bindings, default model, session directory, capabilities, profile, observability. See [settings.json](/kli/config/settings). |
| `<repo>/.kli/settings.json` | Project settings. Deep-merges over the global file, key by key. |
| `~/.config/kli/config.json` | Extension control: which user extensions are enabled or disabled, and extra directories to discover extensions from. See [config.json](/kli/config/config-json). |
| `~/.config/kli/providers.json` | User-defined OpenAI-compatible providers, keyed by provider id. Holds endpoint and model definitions; never a key, only the name of an environment variable to read it from. See [Connect a provider](/kli/guides/connect-a-provider). |

A configuration file that is absent, does not parse as JSON, or whose top level is not the expected shape is reported as a warning and skipped. The other files still load. Malformed input never aborts startup.

## Credentials

| Path | Purpose |
| --- | --- |
| `~/.config/kli/credentials.json` | Stored provider credentials, keyed by provider id. Each record is a static API key or an OAuth token set (access, refresh, expiry, account id). |

kli writes this file with mode `0600` (owner read and write only). The write goes to a same-directory temporary file created under umask `077`, then renames it over the target, so a crash mid-write cannot truncate the stored credentials and no world-readable window opens. The file lives in the global directory; there is no per-project credentials file.

## Discovery directories

Each root holds optional subdirectories kli scans for resources. The global directory loads first, then the project directory, so project entries extend and shadow global ones by name.

| Subdirectory | Global path | Project path | Holds |
| --- | --- | --- | --- |
| Prompts | `~/.config/kli/prompts/` | `<repo>/.kli/prompts/` | Prompt templates. |
| Skills | `~/.config/kli/skills/` | `<repo>/.kli/skills/` | Skills. Project skills also load root markdown files; ancestor `.agents/skills/` directories and the built-in skills shipped with the image are scanned too. |
| Extensions | `~/.config/kli/extensions/` | `<repo>/.kli/extensions/` | User extensions. A directory holding `extension.lisp` is one extension; an unmarked directory is a group whose files and subdirectories each contribute. See [Extensions](/kli/extend). |

Extra extension directories named under `extension-dirs` in `config.json` are scanned in addition to these, as is any path passed with `--extension` on the command line.

## Context files

kli reads per-directory context files into the system prompt. In each directory it checks these names in order and takes the first that exists.

| Name | Role |
| --- | --- |
| `AGENTS.md` | Per-directory project context. Checked first. |
| `CLAUDE.md` | Per-directory project context. Checked when no `AGENTS.md` is present. |

Context files are collected from the global directory first, then from each directory on the walk from the repository root down to the working directory. A file over 2 MiB is treated as absent.

Two further files in either config root replace or extend the system prompt rather than add project context. The project copy wins over the global one; a blank file is treated as absent.

| Name | Role |
| --- | --- |
| `SYSTEM.md` | Replaces the base system prompt. |
| `APPEND_SYSTEM.md` | Appended to the system prompt. |

## Session logs

By default kli keeps the session log in memory. Set `sessionDir` in `settings.json` to a directory and kli persists each session to disk there.

| Path | Purpose |
| --- | --- |
| `<sessionDir>/<id>.session` | One stored session. A readable record file: a versioned header followed by one record per session entry. The file name is the session id. |

`sessionDir` resolves a leading `~` against the home directory and a relative path against the working directory. Each rewrite goes through a same-directory `.tmp` file and a rename, so a crash mid-write cannot truncate a stored session. The `.tmp` files are not listed as sessions.

## Cache: fault and fatal logs

kli writes diagnostics under the cache directory. These are append-only and exist only when something is written to them.

| Path | Purpose |
| --- | --- |
| `~/.cache/kli/<seam>-faults.log` | Contained faults, one line each, for the named seam. A fault caught at an extension boundary is logged here instead of reaching the terminal. Each file is truncated when it passes a 1 MiB soft cap. |
| `~/.cache/kli/last-fatal.log` | The condition and a backtrace for a fatal error that ended the process. Appended to on each fatal exit; the path is printed to standard error as it exits. |

The fault log file name carries the seam, so different boundaries write to different files (for example `model-faults.log`). A failure while writing a diagnostic loses that line and nothing else.

## Observability sink

kli can append every dispatched event to a JSON Lines file. The sink is off until `observability.path` is set in `settings.json`.

| Setting | Effect |
| --- | --- |
| `observability.path` | File the sink appends to, one JSON object per line. A leading `~` expands against the home directory; a relative path resolves against the working directory. Absent or empty leaves the sink disabled. |
| `observability.events` | Array of event-type name prefixes to record. Absent records every event. |

Each line carries the event timestamp, type, and an optional source and payload. A write failure is recorded on the sink and dropped, never breaking the action that emitted the event. The `/observability` command reports the sink's current path, filter, and write count.


### Models & Providers

#### Providers and Transports


A provider is a named catalogue of models that share a base URL, a credential, and one wire transport. kli's built-in providers resolve credentials through env-var, stored-key, and OAuth modes; each provider speaks exactly one transport.

Models are addressed as `<provider-id>/<model-id>` in `/model`. The `/providers` command lists registered providers with their auth status; `/models` lists the models you currently have credentials for, with compact option markers for models that declare semantic options.

## Providers

| Provider id | Display name | Transport | Auth | Base URL |
|---|---|---|---|---|
| `anthropic` | Anthropic | `anthropic-messages` | env var, stored key | `https://api.anthropic.com` |
| `openai` | OpenAI | `openai-responses` | env var, stored key | `https://api.openai.com/v1` |
| `openai-codex` | ChatGPT (Codex) | `openai-responses` | OAuth | `https://chatgpt.com/backend-api` |
| `compatible` | (per-entry id) | `openai-completions` or `openai-responses` | env var, stored key | declared per entry |

`anthropic` and `openai` register a default environment-variable credential reference (`ANTHROPIC_API_KEY` and `OPENAI_API_KEY`); either can also resolve a stored static key. `openai-codex` authenticates only through OAuth and carries a ChatGPT account id on its requests; it has no environment credential. `compatible` is not a single provider but every user-defined entry in `~/.config/kli/providers.json`, each registered under its own id.

### compatible entries

Each key in `~/.config/kli/providers.json` is a provider id mapping to an object:

| Field | Type | Default | Effect |
|---|---|---|---|
| `base-url` | string | — | Endpoint root the transport posts to. |
| `api` | string | `openai-completions` | Transport. One of `openai-completions` or `openai-responses`; any other value is an error. |
| `key-env` | string | absent | Environment variable holding the API key. When absent, the entry resolves a stored key only. |
| `url-path` | string | `/responses` | Request path, used only when `api` is `openai-responses`. |
| `headers` | object | none | Extra request headers, sent verbatim. |
| `options` | object | none | Provider-level semantic option schemas inherited by every model. |
| `models` | array | empty | Model entries: `id` (required), `name` (defaults to `id`), `context-window`, and optional model-level `options`. |

Secrets never live in `providers.json`. The file names the key's environment variable; the value comes from that variable or a stored static key.

A provider-level `options` object is inherited by each model. A model-level `options` object merges over it: redeclaring an option replaces just that option's schema, and `null` removes an inherited option from that model. This lets one provider declare common OpenAI-family options once while excluding or narrowing them for models that do not support them.

## Transports

A transport is the request shape and stream decoder for one model API. The transport is fixed by the provider, not chosen per request.

| Transport | API | Request path | Used by |
|---|---|---|---|
| `anthropic-messages` | Anthropic Messages | `/v1/messages` | `anthropic` |
| `openai-responses` | OpenAI Responses | `/responses` (or `url-path`) | `openai`, `openai-codex`, `compatible` (opt-in) |
| `openai-completions` | OpenAI Chat Completions | `/chat/completions` | `compatible` (default) |

Providers that share a transport share one stream adapter. Removing one such provider leaves the others working.

## Auth modes

Credentials resolve in one mode per provider. The `/auth` command registers and inspects them; stored credentials persist to `~/.config/kli/credentials.json`.

| Mode | Registered by | Source of the key | Persisted |
|---|---|---|---|
| Environment variable | `/auth env <provider> <ENV_VAR>` | the named environment variable, read at request time | no — only the variable name is recorded |
| Stored key | `/auth key <provider> <KEY>` | a static string in the credential store | yes, in `credentials.json` |
| OAuth | `/auth login <provider>` then `/auth code <code-or-url>` | access and refresh tokens from the provider's token endpoint | yes, in `credentials.json` |

Availability is presence, not a secret read. An environment reference is available when its variable is set and non-empty; a stored key when the string is non-empty; an OAuth credential when it holds a refresh or access token. An expired OAuth access token with a refresh token is still available and refreshes on the next request. `/auth logout <provider>` forgets a stored credential.

The built-in providers register a default credential reference at install: `anthropic` and `openai` an environment reference, `openai-codex` an OAuth restore. A `compatible` entry registers an environment reference only when it names `key-env`.

## Semantic options

Semantic model options are kli-level capability settings on a model selection. They are stored by semantic id in the session, shown by `/models` as compact `options ...` markers, and configured at startup with `settings.json` `defaultOptions`. They are not raw provider request fields; the selected transport lowers each option to the provider-specific wire shape it supports.

Built-in semantic option ids:

| Option id | Values | Supported transports | Wire lowering |
|---|---|---|---|
| `reasoning-effort` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` | `anthropic-messages`, `openai-responses`, `openai-completions` | OpenAI-family transports send reasoning effort fields; Anthropic sends a `thinking` config using either effort hints or token budgets. `off` disables or omits reasoning according to the transport. |
| `text-verbosity` | `low`, `medium`, `high` | `openai-responses`, `openai-completions` | Responses sends `text.verbosity`; Chat Completions sends `verbosity`. |
| `service-tier` | `auto`, `default`, `flex`, `priority` | `openai-responses`, `openai-completions` | Sends `service_tier`. |
| `prompt-cache-retention` | `off`, `in-memory`, `24h` | `openai-responses`, `openai-completions` | Sends `prompt_cache_retention` for retaining prompt-cache state; `off` omits the retention field. |

A model must declare an option schema before that option can be set. Schema values may narrow the global enum values, and a default may be supplied. For `compatible` providers, schemas are declared in `providers.json`; built-in provider catalogues declare their own schemas.

### Reasoning effort and `/thinking`

`/thinking <level>` is the interactive command for `reasoning-effort`. It sets that semantic option on the current model selection, or shows the current value when called without an argument. `/model provider/model high` is shorthand for selecting the model and setting `reasoning-effort` at the same time.

The word `thinking` still appears in UI text and Anthropic wire docs because those are the user-facing command name and provider API terms. The stored/session-facing option id is `reasoning-effort`.

### Option schema fields

A `providers.json` option schema may carry these fields:

| Field | Type | Effect |
|---|---|---|
| `type` | string | One of `enum`, `boolean`, `integer`, `number`, or `string`. Usually omitted for built-in semantic ids because their global type is known. |
| `values` | array | Allowed enum values. Required for enum schemas. |
| `default` | scalar | Default value when selecting the model without an explicit assignment. |
| `min` | number | Lower bound for `integer` and `number` schemas. |
| `max` | number | Upper bound for `integer` and `number` schemas. |

## See also

- [Connect a Provider](/kli/guides/connect-a-provider)
- [Models](/kli/models)
- [Settings Reference](/kli/config/settings)


## Additional pages (including unstable internal surfaces)

### CLI & Install


This section is the reference for the `kli` program and how it gets onto your
machine.

## The `kli` command

`kli` dispatches on its first argument. Some tokens are subcommands; anything
else starts the terminal app.

| Invocation | Effect |
|---|---|
| `kli` | Start the interactive terminal app in the current directory. |
| `kli version` (`--version`, `-V`) | Print the version line and exit. |
| `kli update` | Update kli in place from a published release. |
| `kli docs` | Print kli documentation, fetched live from the docs site. |
| `kli mcp-serve <id>` | Serve a named extension's tools to an MCP client over stdio. |
| `kli install <url> <git-tree-sha1>` | Install an extension from a URL, pinned to its git object id. `--yes` confirms without prompting. |
| `kli help` (`--help`, `-h`) | Print usage and exit. |
| `kli <flags…>` | Any other arguments start the app with the flags passed through. |

Flags the app understands include `--profile <name>`, `-c` / `--continue`
(resume the most recent stored session), and `--extension <path>` (load an extra
extension on boot; repeatable). A fatal error exits with status `2`.

`kli --print-authority` is a one-shot introspection flag: it prints the
capabilities a session would hold under the resolved profile, then exits without
running an agent. `--profile <name>` inspects another profile, `--read-only` and
`--no-bash` preview the narrowed authority those flags produce, and `--json` emits
one object. Use it to size the confinement you run kli inside — see [Security
model and sandboxing](/kli/concepts/security-model-and-sandboxing).

`kli install <url> <git-tree-sha1>` installs a remote extension without a running
session: it verifies the pinned bytes and places them durably for the next
launch, exiting `0` on success, `2` on a malformed invocation, and `3` on a
refusal or verification failure. The declared extension id prints to stdout. This
is the headless form of the in-session `/install`; both are covered in [Sharing
extensions](/kli/extend/sharing-extensions), and the publishing side in
[Publishing extensions](/kli/extend/publishing-extensions).

## Pages

- [Installation](/kli/cli/installation) — the install one-liner, the variables
  that steer it, the on-disk layout, supported targets, and the Nix and
  from-source routes.
- [Reading the docs](/kli/cli/docs) — the `kli docs` subcommand: print the docs
  index, any page, or a search straight from your terminal.
- [Environment variables](/kli/cli/environment-variables) — every variable kli
  and its installer read.


### Commands, Tools & TUI


This section catalogues what you use to drive kli from inside a running session.

- [Slash commands](/kli/commands/slash-commands) — every `/command`, grouped by
  what it controls.
- [Tools](/kli/commands/tools) — the tools the agent calls: bash, eval, and
  the file surface of read, find, search, write, and edit.
- [Keymap](/kli/commands/keymap) — the default key bindings and how to rebind
  them.
- [Themes](/kli/commands/themes) — the color tokens, the dark and light palettes,
  and how kli chooses one.


### Concepts


kli is a small live kernel; everything else — model providers, tools, the session
log, the commands, the terminal interface — is an extension installed on it. For
steps, go to [Guides](/kli/guides); for exact values, go to [Reference](/kli/cli).

- [The live image](/kli/concepts/the-live-image) — what it means that kli is one
  running image you can change without restarting it.
- [Extensions all the way down](/kli/concepts/extensions-all-the-way-down) — the
  mechanism said once: a small kernel, a retractable protocol, and the three
  pillars it buys you.
- [The agent loop](/kli/concepts/the-agent-loop) — what happens during one turn,
  and why a failed tool call comes back as a result the model can fix.
- [Sessions as a tree](/kli/concepts/sessions-as-a-tree) — why a session is an
  append-only tree you can branch, rewind, and resume.
- [Context and the system prompt](/kli/concepts/context-and-the-system-prompt) —
  how your project files shape what the model sees.
- [Tools and hashline edits](/kli/concepts/tools-and-hashline-edits) — why edits
  are anchored patches that refuse to clobber a drifted file.
- [Capabilities and fault barriers](/kli/concepts/capabilities-and-fault-barriers) —
  how kli decides what a tool may do, and how it contains a misbehaving part.
- [Security model and sandboxing](/kli/concepts/security-model-and-sandboxing) —
  why kli enforces authority but not containment, and how to run it in a sandbox.
- [Profiles](/kli/concepts/profiles) — how a profile selects the set of
  extensions kli boots with.
- [Models, providers, and transports](/kli/concepts/models-providers-and-transports) —
  how kli talks to different model APIs.


### Settings & Files


kli reads two configuration files, and they hold different things.

- `settings.json` configures behavior: theme, keybindings, default model and
  provider, session storage, capabilities, profiles, and observability. kli reads
  a global copy under `~/.config/kli/` and a project copy under `<repo>/.kli/`,
  deep-merges the project over the global, then applies the active profile's
  overlay on top.
- `config.json` is global-only and holds three keys for extension discovery:
  `enabled`, `disabled`, and `extension-dirs`.

Both are forgiving: a malformed file is reported and skipped rather than stopping
kli.

## Pages

- [Settings](/kli/config/settings) — every `settings.json` key, with its type,
  default, and merge behavior.
- [config.json](/kli/config/config-json) — the extension discovery file.
- [Capabilities](/kli/config/capabilities) — the capability vocabulary and what
  each one gates.
- [Profiles](/kli/config/profiles) — the built-in profiles and how precedence is
  resolved.
- [Files and paths](/kli/config/files-and-paths) — every path kli reads and
  writes.


### Extend kli


kli is a live image. A small boot kernel installs the extension protocol. Everything
above it (the model providers, the tools, the slash commands, the terminal UI) is an
extension installed into that protocol with a retractor. You extend kli by installing
more of the same: there is no privileged built-in path, only contributions and the
two operations that add and remove them.

## One mechanism, three altitudes

The mechanism is constant. A contribution installs against the protocol and carries a
retractor that undoes exactly what it installed. What changes between altitudes is how
much of the contribution you write yourself.

1. **Feed a builtin extension a resource.** The `prompt-templates` and `skills`
   extensions ship in the image. Drop a Markdown file in an extensions directory and
   the builtin's effect registers a slash command for it, with a retractor that
   unregisters it on unload. You write no Lisp; you hand data to the builtin
   `prompt-templates` and `skills` extensions, which someone already wrote.
2. **Write a contribution.** A `defextension` form adds tools, commands, themes, event
   handlers, or methods. Requirements for the common kinds are derived from the clauses
   you write, and each kind retracts. See [Lisp extension anatomy](/kli/extend/lisp-extensions/anatomy)
   and [Contribution kinds](/kli/extend/lisp-extensions/contribution-kinds).
3. **Define a new contribution kind.** The kernel's own vocabulary (`:tool`, `:method`,
   `:effect`, `:theme`) is built with `defcontribution-kind`. When no existing kind
   fits a domain, you add one and `defextension` learns to compile its clause. See
   [Defining a contribution kind](/kli/extend/lisp-extensions/defining-a-contribution-kind).

## Extensions all the way down

The altitudes are not tiers of a ladder; they are the same install/retract shape seen
at three depths. `prompt-templates` and `skills` are not a no-code layer bolted under
the Lisp one. Each is a `defextension` whose `(:provides ...)` is a single `effect`
that registers commands against the `commands/v1` capability and pairs an unregister
retractor:

```lisp
(defextension prompt-templates
  (:requires
   (capability commands :contract commands/v1)
   (capability config :contract config/v1))
  (:provides
   (effect prompt-templates
     #'register-prompt-template-commands
     #'unregister-prompt-template-commands)))
```

cairn, a separate tool, contributes its slash commands with the same shape: a
`cairn-commands` effect that registers them against `commands/v1` with a retractor. The
Markdown-prompt path and the kernel's command
machinery run the same mechanism; one writes the effect for you, the other hands you
the macros to write your own. The protocol does not distinguish them.

For the same idea stated as the design's spine and the three pillars it buys you, see
[Extensions all the way down](/kli/concepts/extensions-all-the-way-down).

## Where to go

- [Lisp extension anatomy](/kli/extend/lisp-extensions/anatomy) — `defextension`, the
  manifest as a value, install as a recorded transaction.
- [Contribution kinds](/kli/extend/lisp-extensions/contribution-kinds) — the clause for
  each kind you are likely to write, and what its retraction undoes.
- [Defining a contribution kind](/kli/extend/lisp-extensions/defining-a-contribution-kind)
  — how the kernel defines its own vocabulary, and how you add to it.
- [Extensions all the way down](/kli/concepts/extensions-all-the-way-down) — the spine
  and the three pillars the mechanism buys you.
- [The live image](/kli/concepts/the-live-image) — why installing and retracting is safe
  while kli runs.


### Get started


This page gets you from nothing to a running session and names the things a kli session
does differently from other agents. It assumes you are comfortable in a terminal and
with git.

## Install and run

```sh
curl -fsSL https://kli.kleisli.io | sh
```

The installer drops a prebuilt binary under `~/.local` and a `kli` on your `PATH`
(Linux x86_64 and aarch64, macOS aarch64). On an Intel Mac, or for the Nix and
from-source paths, see [Installation](/kli/cli/installation).

kli reads an Anthropic key from `ANTHROPIC_API_KEY`; export it and the bundled
Anthropic provider is live. Other providers, OAuth, and credential files are in
[Connect a provider](/kli/guides/connect-a-provider).

```sh
export ANTHROPIC_API_KEY=sk-ant-...
cd path/to/your/repo
kli
```

Choose a model with `/model`, then type a request naming a file. 

## What a kli session does differently

- **It is fully permissioned by default.** There is no approval prompt. A tool call —
  bash, a file write, `eval` — runs the moment the model emits it, with the privileges
  of the kli process. Decide your confinement before you point it at anything you care
  about: [Restrict what kli can do](/kli/guides/restrict-what-kli-can-do) and the
  [security model](/kli/concepts/security-model-and-sandboxing).
- **A diff card is a change already on disk.** kli does not stage an edit for you to
  accept; the card is the receipt for a write that already happened. Keep it by doing
  nothing, drop it with git. Edits are anchored to line-and-content hashes, so a patch
  against a file that has drifted is rejected, not misapplied.
- **The session is a live image you can rewrite.** Behavior is CLOS cells over pandoric
  closures, so you can hot-patch the running agent from `/eval` without dropping the
  session — see [The live image](/kli/concepts/the-live-image).

## Next

- [Teach kli your project](/kli/get-started/teaching-kli-your-project) — an `AGENTS.md`
  kli reads at startup so it stops guessing your conventions.
- [Concepts](/kli/concepts) — the agent loop, sessions as a tree, the live image, and
  how authority is decided.
- [Extend kli](/kli/extend) — everything above the kernel is an extension, and this is
  the part you will live in.


### Guides


These guides are short, goal-named recipes. Each one assumes kli is installed and
running, and takes you straight to a single outcome. For the reasoning behind a
recipe, follow the links into [Concepts](/kli/concepts); for exact flags and keys,
see [Reference](/kli/cli).

## Models and auth

- Switch between models and reasoning options — [Choose and switch models](/kli/guides/choose-and-switch-models)
- Sign in to a provider — [Connect a provider](/kli/guides/connect-a-provider)
- Point kli at a local or self-hosted endpoint — [Add a custom OpenAI-compatible provider](/kli/guides/add-a-custom-openai-compatible-provider)

## Running a session

- Run shell commands and evaluate Lisp — [Run commands and eval Lisp](/kli/guides/run-commands-and-eval-lisp)
- Redirect kli while a turn is in flight — [Steer a running turn](/kli/guides/steer-a-running-turn)
- Get comfortable in the interface — [Work in the TUI](/kli/guides/work-in-the-tui)
- Script kli or pipe input into it — [Run kli headless or piped](/kli/guides/run-kli-headless-or-piped)

## Sessions and context

- Save your work and reopen it later — [Persist and resume sessions](/kli/guides/persist-and-resume-sessions)
- Keep a long conversation under control — [Manage long conversations](/kli/guides/manage-long-conversations)
- See and edit what the model sees — [Inspect and edit context](/kli/guides/inspect-and-edit-context)

## Customizing and operating

- Switch or define a profile — [Switch and customize profiles](/kli/guides/switch-and-customize-profiles)
- Gate the tools kli may use — [Restrict what kli can do](/kli/guides/restrict-what-kli-can-do)
- Record an event log — [Log observability events](/kli/guides/log-observability-events)
- Move to a newer build — [Update kli](/kli/guides/update-kli)


### Models & Providers


kli ships the model providers `anthropic`, `openai`, `openai-codex`, and
`compatible`. All but `compatible` carry a fixed catalogue of model ids, registered
when the provider extension installs. The `compatible` provider has no built-in
models; you define its providers, models, and semantic options in `~/.config/kli/providers.json`.

Each model id below is the selection value for that model. A model is available
only when its provider's credential is present. For credential keys, transports,
semantic option lowering, and the OAuth flow, see
[Providers and Transports](/kli/models/providers-and-transports).

<!-- KLI_MODEL_CATALOGUE:BEGIN -->

## anthropic

Transport: Messages API (`anthropic-messages`). Credential: `ANTHROPIC_API_KEY`.
Base URL: `https://api.anthropic.com`. All models declare `reasoning-effort`.

| Model id | Context window | Max output | Options |
|---|---|---|---|
| `claude-opus-4-8` | 1,000,000 | 128,000 | `reasoning-effort` |
| `claude-opus-4-7` | 1,000,000 | 128,000 | `reasoning-effort` |
| `claude-opus-4-6` | 1,000,000 | 128,000 | `reasoning-effort` |
| `claude-sonnet-4-6` | 1,000,000 | 64,000 | `reasoning-effort` |
| `claude-sonnet-4-5` | 200,000 | 64,000 | `reasoning-effort` |
| `claude-haiku-4-5` | 200,000 | 64,000 | `reasoning-effort` |

## openai

Transport: Responses API (`openai-responses`). Credential: `OPENAI_API_KEY`.
Base URL: `https://api.openai.com/v1`. All models declare `reasoning-effort`.

| Model id | Context window | Max output | Options |
|---|---|---|---|
| `gpt-5.1` | 272,000 | 128,000 | `reasoning-effort` |
| `gpt-5.2` | 272,000 | 128,000 | `reasoning-effort` |
| `gpt-5.4` | 272,000 | 128,000 | `reasoning-effort` |
| `gpt-5.5` | 272,000 | 128,000 | `reasoning-effort` |

## openai-codex

Transport: Responses API (`openai-responses`) against the ChatGPT backend.
Credential: OAuth only — there is no environment key; you sign in with a ChatGPT
account. Base URL: `https://chatgpt.com/backend-api`. All models declare `reasoning-effort`.

The catalogue is the ChatGPT-account allowlist. The endpoint rejects any other id.

| Model id | Context window | Max output | Options |
|---|---|---|---|
| `gpt-5.3-codex-spark` | 128,000 | 128,000 | `reasoning-effort` |
| `gpt-5.4` | 272,000 | 128,000 | `reasoning-effort` |
| `gpt-5.4-mini` | 272,000 | 128,000 | `reasoning-effort` |
| `gpt-5.5` | 272,000 | 128,000 | `reasoning-effort` |

<!-- KLI_MODEL_CATALOGUE:END -->

## compatible

User-defined OpenAI-compatible providers, read from `~/.config/kli/providers.json`.
This provider registers nothing of its own; each entry in the file becomes a
provider with its own id, models, credential, and semantic option schemas. The file
is a JSON object keyed by provider id. Secrets never live in the file — `key-env`
names the environment variable that holds the key. If `key-env` is absent, the
provider registers without a credential reference.

Per-provider fields:

| Field | Type | Default | Effect |
|---|---|---|---|
| `base-url` | string | — | Endpoint base URL. |
| `api` | string | `openai-completions` | Transport: `openai-completions` or `openai-responses`. |
| `key-env` | string | none | Environment variable holding the API key. |
| `url-path` | string | none | Request path appended to `base-url`; applied only when `api` is `openai-responses`. |
| `headers` | object | none | Extra request headers as a string-to-string map. |
| `options` | object | none | Provider-level semantic option schemas inherited by every model. |
| `models` | array | empty | Model entries for this provider. |

Per-model fields under `models`:

| Field | Type | Default | Effect |
|---|---|---|---|
| `id` | string | — | Model id passed to the endpoint and used for selection. |
| `name` | string | value of `id` | Display name. |
| `context-window` | integer | none | Context window size. |
| `options` | object | provider-level options | Model-level semantic option schemas; entries replace inherited schemas, and `null` removes an inherited option. |

Example `~/.config/kli/providers.json`:

```json
{
  "my-endpoint": {
    "base-url": "https://api.example.com/v1",
    "api": "openai-completions",
    "key-env": "MY_ENDPOINT_API_KEY",
    "options": {
      "reasoning-effort": {
        "values": ["off", "low", "medium", "high"],
        "default": "off"
      }
    },
    "models": [
      { "id": "model-a", "context-window": 128000 },
      {
        "id": "model-b",
        "name": "Model B",
        "context-window": 32000,
        "options": { "reasoning-effort": null }
      }
    ]
  }
}
```


# metaBuilder

## Manual

### Introduction


Nix builders are often ordinary functions that return derivations. That is a
useful interface for building, but it hides much of the builder's structure.
Which inputs matter, which tools are required, which steps run, what outputs are
promised, and what runtime shape the artifact has are all left implicit.

metaBuilder makes that structure explicit. A builder is written as typed data,
the data is read as a program, and the program can be interpreted several ways.
That is the central idea. One build, many views.

## What A Builder Describes

A metaBuilder builder describes the parts a build author usually cares about.

- parameters that configure the build
- source inputs
- dependency requirements
- tools used by build steps
- operations that define the build workflow
- declared outputs
- evidence about checks or expected behavior
- descriptors for artifacts and runtime surfaces

Those pieces are written once and reused by the views that validate, explain,
debug, and materialize the build.

## One Program Over Fixed Operations

The operations are the heart of the builder. They are drawn from a fixed
signature with two families. Build-time operations cover reading sources,
declaring and running tools, writing files, emitting descriptors, and producing
derivations. Runtime operations cover declaring services, protocols,
capabilities, and units. Every builder, however domain-specific, produces a
program over those same operations, which is why one set of views can interpret
all of them.

## Why This Is Different From A Function

A function answers one question. Given these arguments, what value is returned.

A metaBuilder program answers several questions at once.

- Is the build shape valid?
- Which tools and dependencies does it require?
- What would it do without building anything?
- What plan would materialization execute?
- How does the builder describe itself?
- What artifact or runtime declaration is produced?

The build result still matters. metaBuilder adds the surrounding structure that
makes the builder easier to inspect and evolve.

## Where Examples Fit

The examples are complete tours of concrete builders.

- [Node service example](/metaBuilder/examples/node-service)
- [C code generation example](/metaBuilder/examples/c-codegen)
- [IDL example](/metaBuilder/examples/idl)

Read the manual for the model. Read the examples to see the model applied to
complete artifacts.


### Getting Started


This chapter shows the smallest useful shape. Define a builder spec, turn it into
a program, and ask the program for several views.

## Getting metaBuilder

As a flake input:

```nix
{
  inputs.metaBuilder.url = "github:kleisli-io/metaBuilder";

  outputs = { nixpkgs, metaBuilder, ... }:
    let
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      mb = metaBuilder.lib.mkMb pkgs;
    in {
      # use mb here
    };
}
```

`mkMb` builds the library against your `pkgs` and supplies the
nix-effects library from the flake's own input. Pin your own
nix-effects with `inputs.metaBuilder.inputs.nix-effects.follows`.

Without flakes, import the source tree with explicit arguments:

```nix
let
  fx = import nix-effects-src { inherit pkgs; lib = pkgs.lib; };
  mb = import metaBuilder-src { inherit pkgs fx; lib = pkgs.lib; };
in ...
```

The rest of this chapter assumes `mb` and `pkgs` are in scope.

```nix
let
  schema = mb.operations.localSource {
    name = "schema.proto";
    path = ./schema.proto;
  };

  protoc = mb.operations.tool {
    name = "protoc";
    package = pkgs.protobuf;
  };

  output = mb.operations.output {
    name = "cpp";
    path = "$out/cpp";
    format = "tree";
  };

  spec = {
    _con = "MetaBuilderSpec";
    name = "example-idl";
    parameters = [ ];
    inputs = [ schema ];
    dependencies = [ ];
    tools = [ protoc ];
    operations = [
      (mb.operations.readSource {
        name = "schema.proto";
        source = schema;
      })
      (mb.operations.declareTool { tool = protoc; })
      (mb.operations.runTool {
        name = "generate-cpp";
        tool = protoc;
        args = [ "--cpp_out=$out/cpp" (toString schema.path) ];
      })
      (mb.operations.transformOutput { inherit output; })
      (mb.operations.materializeDerivation {
        name = "example-idl-generated";
      })
    ];
    outputs = [ output ];
    evidence = [ ];
  };

  program = mb.program.fromSpec spec;
in {
  validation = mb.program.validate.run program;
  dryRun = mb.program."dry-run".run program;
  planView = mb.program."plan-view".run program;
  selfView = mb.program.introspect.run program;
  materialize = mb.program.materialize.run program;
}
```

The same `program` is reused by every view. You do not write one builder for
validation, another for documentation, and another for materialization. You
write the spec once and choose the view that answers the current question.

## First Checks

Start with validation. It returns a record with an `ok` flag and a list of
`diagnostics`, and an empty list means the shape is clean.

```nix
(mb.program.validate.run program).ok
```

Use dry-run when you want to understand the build without producing an artifact.
It returns the ordered `steps` the build would take.

```nix
(mb.program."dry-run".run program).steps
```

Use plan-view to inspect the concrete commands and file writes materialization
will perform.

```nix
(mb.program."plan-view".run program).steps
```

Use materialization when you want the derivation. It returns the derivation
together with the declared outputs.

```nix
(mb.program.materialize.run program).derivation
```

Use introspect to get every view at once as a single self-report.

```nix
mb.program.introspect.run program
```

The important habit is to treat the program as the stable object and choose the
view that answers the current question.


### Builder Specs


A builder spec is the public shape of a build. It gathers the pieces a builder
author wants to make explicit before materialization happens.

The base shape is `MetaBuilderSpec`. Every spec is a typed value, and the `_con`
field names which description constructor the value inhabits. A spec is checked
against its description before it becomes a program, so a missing or wrong-shaped
field is reported up front.

```nix
{
  _con = "MetaBuilderSpec";
  name = "example";
  parameters = [ ];
  inputs = [ ];
  dependencies = [ ];
  tools = [ ];
  operations = [ ];
  outputs = [ ];
  evidence = [ ];
}
```

The fields are populated with smart constructors from `mb.operations`. A smart
constructor builds a well-typed value for a field, so you rarely write raw
records by hand beyond the top-level spec.

## Name

The `name` identifies the build in views and materialized artifacts. Choose a
name that describes the artifact rather than the implementation technique.

## Parameters

Parameters are the configuration surface. They should represent choices the
builder user can understand, such as language target, runtime version, feature
flags, artifact kind, or service port.

## Inputs

Inputs are source values the build consumes. Naming inputs makes dry-run,
dependency, and plan views understandable, because the build is no longer a black
box around anonymous paths.

## Dependencies

Dependencies describe package requirements that are part of the build design.
They give dependency views a place to report what the builder needs.

## Tools

Tools describe commands used by operations. A tool is more than a string name. It
connects a build step to the package that provides it, so a plan never relies on
a command from the user's ambient shell.

## Operations

Operations are the workflow. They are the build-time and runtime steps the
builder performs, and they are the field the program is sequenced from. Reading
inputs, declaring tools, generating files, running commands, emitting
descriptors, declaring outputs, declaring runtime structure, and materializing
artifacts all appear here as operation values.

## Outputs

Outputs are promises about what the build produces. A named output can be shown
in documentation, checked in plans, and returned from materialization.

## Evidence

Evidence records checks or expected behavior. It is useful when a builder wants
to say why an artifact should be trusted, not only how it is built.


### Operations


Operations are the steps of a build expressed as data. They keep the build
workflow visible to validation, dry-run, plan-view, self-documentation, and
materialization.

An operation states intent at the builder level. The materialized command is one
view of that intent, not the only meaning of the operation.

Operations come from a fixed signature with two families. Build-time operations
shape the derivation. Runtime operations describe how an artifact runs. A program
is a sequence drawn from both families, and every operation is one or the other.

## Build-Time Operations

The build-time family covers the work that produces a derivation.

- `readSource` names a file or tree the build consumes
- `resolveDependency` records a required package
- `declareTool` introduces a tool before it is used
- `runTool` runs a declared tool with arguments
- `writeFile` writes generated content
- `copyPath` copies a path into the build
- `transformOutput` declares an intended result shape
- `validateValue` checks a value during the build
- `emitDescriptor` attaches structured metadata
- `materializeDerivation` marks where the program becomes a derivation

## Reading Inputs

Use source operations to name files or trees the build consumes.

```nix
mb.operations.readSource {
  name = "schema";
  source = schemaInput;
}
```

The view layer can then report that the build uses `schema` instead of only
showing a later command line.

## Declaring And Running Tools

Declare a tool before running it, then connect a named step to it.

```nix
mb.operations.declareTool { tool = compiler; }

mb.operations.runTool {
  name = "compile";
  tool = compiler;
  args = [ "-c" "$out/generated.c" "-o" "$out/generated.o" ];
}
```

Dependency analysis can show the edge from the tool to the operation, and
plan-view can show the concrete command.

## Writing Files

Generated files should be explicit where possible.

```nix
mb.operations.writeFile {
  output = configHeader;
  text = "#define FEATURE 1\n";
}
```

This is useful for builders that generate metadata, config headers, manifests, or
service descriptors.

## Emitting Descriptors And Transforming Outputs

Descriptors attach structured metadata for downstream tools or documentation to
read without parsing shell scripts. Output transformations declare the intended
result shape, such as a tree, an archive, an ELF binary, JSON, text, or a header
directory.

## Runtime Operations

The runtime family describes how an artifact runs rather than how it is built.

- `declareCapability` records a lifecycle or query capability
- `declareProtocol` records a transport and serialization
- `declareService` records a service the artifact provides
- `materializeUnit` marks where the program produces a runtime unit

A builder that produces a service uses these alongside the build-time operations,
so one program describes both the store artifact and the way it should run.

## Materializing

Materialization operations mark where the program becomes a concrete result.
`materializeDerivation` produces a derivation, and `materializeUnit` produces a
runtime unit. They are the boundary between a described build and a build that
can be realized.


### Programs And Views


A builder spec becomes a program. The program is the reusable value that
different views interpret.

Common entry points are the following.

```nix
mb.program.fromSpec spec
mb.program.fromOrnamentedSpec builderType spec
mb.program.sequence operations
```

Use `fromSpec` when you already have a base builder spec. Use
`fromOrnamentedSpec` when a domain builder extends the base shape. Use `sequence`
when the program is already expressed as operations.

Each view below is a reading of the same `program`. None of them rebuilds it.

## Validation

Validation answers whether the program is structurally acceptable. It returns a
record with an `ok` flag and a list of `diagnostics`.

```nix
mb.program.validate.run program
```

Use it before relying on any other view.

## Dependency Graph

Dependency analysis answers which tools, dependencies, services, and operations
are involved. It returns a graph of `nodes` and `edges`.

```nix
mb.program.deps.run program
```

This view is useful when a builder grows and you need to see whether it still
says what it depends on.

## Dry-Run

Dry-run answers what would happen without materializing the artifact. It returns
the ordered `steps` of the workflow.

```nix
mb.program."dry-run".run program
```

Use it as a fast explanation of the builder's workflow.

## Plan View

Plan-view answers what materialization would execute. It returns the typed plan
steps and the rendered commands.

```nix
mb.program."plan-view".run program
```

Use it when you need to inspect command order, generated file writes, and the
shape of the materialization plan.

## Describe

Describe answers how the builder program documents itself. It returns a rendered,
operation-level explanation of the builder.

```nix
mb.program.describe.run program
```

## Introspect

Introspect composes the main views into one self-view, so a single call returns
validation, dependencies, dry-run, plan, documentation, and materialization
together.

```nix
mb.program.introspect.run program
```

Use it when you want the complete one build, many views report.

## Materialize

Materialization returns the build artifact. The result carries the `derivation`
along with the declared outputs and any runtime declarations.

```nix
mb.program.materialize.run program
```

Use materialization only after the views show the build says what you intend.


### Designing Builder Surfaces


A good builder surface starts from the domain, not from the generic build
machinery.

For a service builder, the domain might include runtime, entrypoint, port, health
path, and service protocol. For a native code generator, the domain might include
schema, compiler, defines, artifact kind, and generated outputs. The public
constructor should ask for those domain concepts and lower them into the shared
builder program.

## Start From The Artifact

Ask what the builder promises to produce. A runnable package, a generated source
tree, a static library, a CLI, a service unit, or a descriptor bundle each imply
different outputs, operations, tools, and runtime descriptors. The artifact tells
you which of those the builder needs.

## Name The Vocabulary

Use domain names in the public API and avoid exposing generic mechanics when a
domain term is clearer. A service builder should ask for a `port` or a
`healthPath` before it asks the user to construct a low-level runtime protocol
value.

## Keep The Constructor Small

A constructor should accept the smallest set of choices that define the build.
Everything derived from those choices should be generated by the builder. This
keeps the user-facing API stable while the internal program becomes more capable.

## Lower Into Operations

The constructor is responsible for lowering domain choices into operations. That
lowering is where tools, generated files, descriptors, output declarations, and
materialization steps enter the program. The domain fields capture what the user
said, and the operations capture what the build does.

## Expose Standard Views

A production builder should expose the same standard views during development.
Validation, dependency graph, dry-run, plan-view, describe, introspect, and
materialize together become the builder's debugging and documentation surface.

## Use Ornaments For Domain Shape

An ornament extends the base builder spec with domain-specific fields. Use one
when a builder needs a typed domain shape but should still behave like a normal
metaBuilder program. The ornament adds data only. It never extends the operation
alphabet, and a typed forget map projects the ornamented builder back to the
shared shape while keeping its program intact. That is what lets a domain builder
stay fully compatible with every standard view.


### Outputs, Evidence, And Runtime Artifacts


Builders need to communicate more than the fact that a derivation exists. A user
often needs to know what the artifact contains, how it was checked, and how it
should run. metaBuilder gives those concerns explicit places in the build
description.

## Outputs

Outputs name the results a build promises. A generated source tree, a static
library, a CLI binary, a JSON manifest, package metadata, or a service tree are
typical examples. An output should have a name, a path, and a format, which lets
views explain what the build returns without executing it.

## Descriptors

Descriptors are structured metadata. Use them when a builder wants to report
facts about the artifact, such as compiler identity, runtime version, protocol,
generated files, package manager, or artifact kind. Descriptors are better than
conventions hidden in filenames because they are part of the program's data.

## Evidence

Evidence records checks or claims about the artifact. A syntax-check command, a
smoke-test expectation, a generated-artifact invariant, or a compatibility
assertion can each be recorded as evidence. Evidence does not replace tests. It
gives the builder a typed place to report why a produced artifact should be
trusted.

## Runtime Artifacts

Some builders produce things that run as services. For those builders the runtime
shape should be explicit, and it is expressed with the runtime operations for
services, protocols, lifecycle capabilities, and runtime units. These runtime
declarations are kept structure. They survive into the materialized result, so
the same builder describes both build-time and runtime behavior and returns both
from one program.


### Materialization Model


Materialization turns a builder program into an artifact. It is one
interpretation of the program, not the whole meaning of the builder.

The materialization view is useful because it keeps the executable plan visible
before and after a derivation exists.

## Plans

A plan is the materializable shape of the program. It records the steps that
write files, run tools, transform outputs, and produce final artifacts. Plans let
you inspect order and intent before asking Nix to build.

Materialization works by walking the program and building up a plan state as it
goes. The plan state carries working bookkeeping, such as which tools and
services have been declared so far, so that later steps can be checked against
earlier ones.

## From Plan State To Build Plan

When the walk finishes, the plan state is projected into the final build plan.
This projection forgets the working bookkeeping and keeps what the artifact
needs, which is the outputs, the derivation, and the runtime declarations the
builder promised. The bookkeeping existed only to validate the build as it was
assembled.

## Tool References

Tool references connect command steps to packages. This matters because a plan
should not rely on ambient commands from the user's shell. If a step runs `gcc`,
the program should know which package provides `gcc`.

## Generated Commands

Plan-view exposes command snippets so users can inspect what materialization will
execute. Use this view for debugging. The builder API should still be expressed
in domain terms rather than asking users to manage every command directly.

## Derivation Outputs

Materialization returns derivations and output declarations. The result should
match the outputs the builder promised earlier in the spec.

## Runtime Artifacts

When the program declares runtime services or units, materialization carries
those declarations alongside the derivation result. A builder can therefore
produce both a store artifact and a runtime description from the same program.


### Authoring Production Builders


Production builders should grow from a small domain surface into a reliable
program, not from a large compatibility wrapper. Start with the artifact, name the
domain concepts, then expose the standard views that make the builder
inspectable.

## Begin With The Smallest Useful Constructor

A first constructor should accept only the choices needed to produce the artifact.
More options can be added when the builder has a real domain reason for them.

## Add Typed Configuration Deliberately

Typed configuration is valuable when it clarifies the build vocabulary. Avoid
adding fields only because an underlying command happens to have many flags. A
field earns its place when a view becomes more meaningful for having it.

## Prefer Descriptors Over Hidden Conventions

If downstream users need to know something, put it in a descriptor. Do not make
them infer important facts from path names or shell snippets.

## Keep Views In The Contract

Validation, dependency graph, dry-run, plan-view, describe, introspect, and
materialize are not only development helpers. They are part of how users learn and
trust the builder, so treat their output as a public contract.

## Test The Views That Matter

Tests should pin the views that define the builder's public contract. Useful
anchors are that validation succeeds for supported specs, that the dependency
graph includes the expected tools and operations, that dry-run explains the
intended workflow, that plan-view includes the expected materialization shape, and
that materialization produces the promised outputs.

## Avoid Compatibility Before Release

Do not add compatibility shims before there is a public compatibility problem.
Early builders should be shaped around the model you want users to learn.


## Theory

### Builders As Descriptions


The central move in metaBuilder is to treat a builder as a description before it
is treated as an executable artifact.

A description is typed data. Parameters, sources, dependencies, tools,
operations, outputs, evidence, and runtime declarations are all generated
datatypes with named constructors and fields. A builder spec is an inhabitant of
the base description type, and it is checked against that type before anything is
built. A spec that is missing a required field or carries the wrong shape is
rejected at description time, not at build time.

Because the builder is data, its parts are available to inspect and reinterpret.
A description says which parts exist and how they relate without committing to
the single thing that could be done with them. That separation is what makes
multiple views possible.

## Functions And Descriptions

A function gives an answer when it is called. It can hide everything that
happened on the way to the answer.

A description can be read before any answer is produced. It can be checked,
summarized, documented, or interpreted into a build. The description is not less
precise than a function. It is precise in a form that supports more than one use.

## Typed All The Way Down

The types are not decoration. They are the same descriptions the views read and
the same descriptions the documentation and schemas are generated from. A field
added to a description becomes visible to validation, to dependency analysis, to
the rendered docs, and to materialization at once, because all of them read the
one typed source.

## Structure Before Execution

When a builder is described structurally, its components become available to
generic interpretations. Validation inspects the shape. Dependency analysis
inspects tools and operations. Dry-run summarizes intent. Plan-view renders an
executable plan. Materialization produces the artifact.

The build still happens. metaBuilder adds the structure around it that makes the
builder inspectable before it runs.


### Internalized Programs


An internalized program is a build workflow represented as a value. The value is
not a script and not a derivation. It is typed data that records the steps of a
build and the order they run in.

This is the object every view shares. Validation, dependency analysis, dry-run,
plan-view, documentation, introspection, and materialization are all readings of
the same program value.

## Operations As A Signature

A program is built from operations, and the operations are not an open-ended set
of arbitrary effects. They come from a fixed signature with two families.
Build-time operations read sources, declare tools, write files, run commands,
emit descriptors, and produce derivations. Runtime operations declare services,
protocols, capabilities, and units.

The signature is the sum of those two families. Every operation in a program is
either a build-time operation or a runtime operation and nothing else. Because
the alphabet is fixed and total, a view always knows the full set of cases it
must handle, and a builder can never smuggle in an effect the views do not
understand.

## Programs Are Free

The program is the free sequencing of operations over that signature. Free means
the program records only which operations occur and in what order. It does not
decide what they mean. Meaning is supplied later by a view.

This is why one program supports many readings. The program commits to the
build's structure and leaves interpretation open. A function would have collapsed
that structure into a single answer the moment it was called.

## Meaning By Interpretation

A view gives the program meaning by handling each operation. Validation handles
an operation by checking it. Dependency analysis handles it by recording what it
mentions. Materialization handles it by turning it into part of a derivation.

No view owns the program. Each one walks the same sequence of operations and
answers a different question. The final derivation is one such answer, not the
whole meaning of the builder.


### Ornaments And Domain Surfaces


An ornament enriches a base description with domain-specific structure.

For metaBuilder the base description is the shared builder shape. A domain
builder adds fields for its own vocabulary while keeping the ability to become an
ordinary builder program. A service ornament can add a runtime, a port, and a
health path. A code-generator ornament can add a compiler identity, a set of
defines, and a generated artifact kind.

## Refining Data, Not Operations

An ornament refines the data of a description. It does not change the operation
alphabet. The shared signature of build-time and runtime operations stays fixed
for every builder, ornamented or not. A domain builder still produces a program
over the same operations, so every view that understands the base program
understands the ornamented one without modification.

This is the discipline that keeps domains from fragmenting the model. New
vocabulary enters as new fields, and those fields are lowered into the shared
operations by the builder's constructor. The operation alphabet is never extended
per domain.

## Preserving The Base Shape

The enriched builder still carries the shared pieces. Those pieces are inputs,
tools, operations, outputs, and evidence. The common views know how to read
exactly those pieces, which is why they keep working across domains.

## Adding Domain Meaning

The added fields should be meaningful in the domain. Service protocol, health
path, compiler identity, generated artifact kind, and language target are good
examples. They let a builder author speak in domain terms without giving up the
shared program model.

## Surface And Forgetting

The domain surface is what users write. The shared builder shape is what the
views understand.

Moving between them is a real, typed map called forgetting. It projects an
ornamented builder onto the shared shape by dropping the domain-only fields and
keeping the shared pieces. Those shared pieces are inputs, tools, operations,
outputs, and evidence. Because the operations live in the shared shape,
forgetting preserves them. The program you get from a forgotten spec is the same
program the ornamented spec describes. Nothing the build needs is lost by
speaking in domain terms.

This forget map is checked, not informal. The projection is certified to land in
the base builder type, so an ornamented builder always forgets to a genuine
shared builder.

Forgetting recurs later in the pipeline. Materialization carries a working plan
state with derived bookkeeping, and the final build plan forgets that bookkeeping
while keeping only the outputs and runtime declarations the builder promised.
Each stage forgets exactly what the next stage does not need.


### Interpretation And Views


A view is an interpretation of a program. The program is a sequence of operations
and says nothing about their meaning on its own. A view supplies the meaning by
handling each operation as the sequence is walked.

Because every view reads the same program over the same fixed operation alphabet,
the views agree by construction. They differ only in how each operation is
handled, not in which operations exist.

## Validation

Validation interprets the program as a shape to check. It walks the operations
and collects diagnostics, then reports whether the program is acceptable before
any artifact is produced. An empty diagnostic list means the build shape is
clean.

## Dependency Graph

Dependency analysis interprets the program as a graph of requirements and uses.
It records nodes for tools, dependencies, services, and operations, and edges for
how they relate, so a grown builder can be checked against what it claims to
need.

## Dry-Run

Dry-run interprets the program as a user-facing summary. It turns each operation
into a short statement of intent and produces the ordered list of steps the build
would take, without performing them.

## Plan-View

Plan-view interprets the program as an executable plan. It builds the same typed
plan that materialization uses and renders the concrete commands and file writes,
so command order and shape can be inspected before Nix is asked to build.

## Documentation

Documentation interprets the program as an explanation. It reads the operations
and the declared outputs and renders a description of how the build presents
itself to a user.

## Materialization

Materialization interprets the program as an artifact-producing plan. It handles
build-time operations into a derivation and runtime operations into runtime
declarations, returning the derivation together with the outputs and runtime
descriptions the builder promised.

## One Program, Many Answers

The views are different, and their agreement comes from sharing one program. The
final derivation is one interpretation among several. A builder that reads well
under validation, dependency analysis, dry-run, and documentation is a builder
whose meaning is understood before it is built.


### Evidence, Descriptors, And Runtime Structure


Build systems often treat metadata as something outside the build. metaBuilder
treats important metadata as part of the description, because a builder's meaning
is not exhausted by its store path.

## Evidence

Evidence gives checks and claims a place in the description. A smoke test, an
expected behavior, or an invariant can be represented as data that views surface.
Evidence does not replace tests. It gives the builder a typed place to say why a
produced artifact should be trusted.

## Descriptors

Descriptors carry structured facts about an artifact. Compiler identity, runtime
version, protocol, generated files, and artifact kind are facts a builder should
state directly rather than hide in path names or shell scripts. Because a
descriptor is part of the program's data, downstream tools and documentation can
read it without parsing conventions.

## Runtime Structure

Some artifacts are meant to run. Runtime services, protocols, capabilities, and
units describe that operational shape. These come from the runtime half of the
operation signature, so a builder declares its runtime structure with the same
program it uses to build.

The runtime declarations are kept structure, not forgotten bookkeeping. They
survive into the materialized result, which is why the same program can produce a
store artifact and a runtime description together.

## Why They Belong Together

Evidence, descriptors, and runtime declarations all answer questions about the
artifact beyond whether it built. They belong in the same descriptive model
because users need them to evaluate, compose, and operate builders.


## Examples

### Node service example


This tour builds a tiny HTTP service from `server.js`. The point is not
to mimic a full Node packaging API; it is to show how a builder can name
its domain concepts and then expose several views of the same build.

The worked artifact is a runnable package with a copied service source,
generated package metadata, a wrapper script, an HTTP service descriptor,
a runtime unit declaration, and a materialization plan.

## Start from the artifact

The source fixture is one file: `node-service/server.js`. The builder
turns that file into a runnable tree:

- `bin/node-service-demo` starts the service with Node.
- `lib/node-service-demo/server.js` contains the copied source.
- `share/node-service-demo/package.json` is generated from the typed
  builder spec.
- the runtime view describes the service as HTTP on port 3000 with a
  `/health` endpoint.

## Source files

These pages are the complete source for the worked example: the builder module plus the files it consumes.

- [Node service builder module](/metaBuilder/examples/node-service/source/builder.nix) - Source for the Node service builder constructor and worked demo program.
- [server.js](/metaBuilder/examples/node-service/source/server.js) - HTTP service fixture copied into the materialized Node demo package.

## Builder vocabulary

`NodeServiceBuilder` ornaments the generic `BuilderSpec` with the
fields a service builder cares about: runtime version, entrypoint,
package manager, script table, test command, service descriptor, and
runtime operations. The constructor keeps the public surface small.

```nix
nodeService {
  name = "node-service-demo";
  source = ./node-service/server.js;
}
```

## Program walkthrough

The constructor lowers the service spec into an internalized program.
The builder-facing operations read the source, declare `node` and
`bash`, generate `package.json`, run a syntax check, install the
runnable tree, emit metadata, and declare the materialized outputs.

The runtime operations are part of the same program. They declare the
lifecycle capability set, the HTTP protocol, the concrete service, and
the runtime unit. That is why dependency analysis, dry-run output,
plan-view output, and self-documentation all see the service shape.

## One build, many views

The section below is generated from `mb.program.introspect.run
program`. It is not a hand-written summary. It validates the program,
extracts the dependency graph, renders dry-run and plan-view output,
includes service descriptors, and reports the materialized outputs.

The same internalized program is interpreted several ways.

### Validation

- result: `ok`

### Dependency Graph

- nodes: `5`
- edges: `2`
- services: `1`
- node `tool:node` (tool) package `nodejs`
- node `tool:bash` (tool) package `bash-interactive`
- node `operation:syntax-check` (operation) via `node`
- node `operation:install-service` (operation) via `bash`
- node `service:node-service-demo-service` (service) package `nodejs`
- edge `tool:node` -> `operation:syntax-check` (uses-tool)
- edge `tool:bash` -> `operation:install-service` (uses-tool)

### Dry Run - Builder

- source `server.js`
- tool `node`
- tool `bash`
- write `share/node-service-demo/package.json`
- run `syntax-check` with `node`
- run `install-service` with `bash`
- descriptor `node-service-demo-metadata`
- transform `service-tree` (tree)
- transform `package-json` (json)
- materialize `node-service-demo-artifact` with `runCommand`
- evidence `self-test`

### Dry Run - Runtime

- runtime capability `lifecycle`
- runtime protocol `http`
- runtime service `node-service-demo-service`
- runtime unit `node-service-demo-service`

### Plan View

- write `write:share/node-service-demo/package.json`
- run `syntax-check`
- run `install-service`
- `write:share/node-service-demo/package.json`: `mkdir -p "$(dirname "$out/share/node-service-demo/package.json")"`
- `syntax-check`: `node --check "$pathMap_85e860eb67550a011692fa61e2a4543318fcdb72bf6de38c7f85842029ee99ae"`
- `install-service`: `bash -c 'set -eu`

### Plan Shell Excerpt

```sh
pathMap_85e860eb67550a011692fa61e2a4543318fcdb72bf6de38c7f85842029ee99ae=<source:server.js>
mkdir -p "$(dirname "$out/share/node-service-demo/package.json")"
cat > "$out/share/node-service-demo/package.json" <<'METABUILDER_HEREDOC_83625931feff0ed1f14d2f61a28aea1a87b63276765f4ca0cc2bceddf130aeed'
{"main":"server.js","name":"node-service-demo","private":true,"scripts":{"start":"node server.js","test":"node --check server.js"},"type":"module","version":"0.1.0"}
METABUILDER_HEREDOC_83625931feff0ed1f14d2f61a28aea1a87b63276765f4ca0cc2bceddf130aeed
node --check "$pathMap_85e860eb67550a011692fa61e2a4543318fcdb72bf6de38c7f85842029ee99ae"
bash -c 'set -eu
src="$1"
mkdir -p "'"$out"'/bin" "'"$out"'/lib/node-service-demo" "'"$out"'/share/node-service-demo"
cp "$src" "'"$out"'/lib/node-service-demo/server.js"
```

### Runtime Services

- service `node-service-demo-service` exposes `http/TCP/JSON PORT:3000`; capabilities `start`, `stop`, `health`

### Descriptors

- descriptor `node-service-demo-metadata` (payload keys `entrypoint`, `healthPath`, `kind`, `packageManager`, `port`, `runtimeVersion`)

### Builder Self-Documentation

- documented operations: `15`
- runtime services: `1`

### Materialized Outputs

- service-tree -> $out (tree)
- package-json -> share/node-service-demo/package.json (json)

### Materialization

- derivation: `node-service-demo-artifact`
- outputs: `2`
- runtime artifacts: `1`
- service `node-service-demo-service`

### Substrates

- dockerfile: `supported`
- shell: `supported`



### Source files


These files are the complete source for Node service example: the
builder module plus the fixtures it consumes.

- [Node service builder module](/metaBuilder/examples/node-service/source/builder.nix) - Source for the Node service builder constructor and worked demo program.
- [server.js](/metaBuilder/examples/node-service/source/server.js) - HTTP service fixture copied into the materialized Node demo package.


### Node service builder module


This module defines the `NodeServiceBuilder` ornament, the
`nodeService` constructor, the concrete `node-service-demo` spec, and
the exported views used by the tour page.

Source path: [`examples/node-service/builder.nix`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/node-service/builder.nix).

```nix
{ mb, fx, lib, pkgs, ... }:

let
  H = fx.types.hoas;
  G = fx.types.generic;
  ops = mb.operations;
  eff = mb.program.eff;

  NodeServiceBuilder = H.ornament mb.descriptions.BuilderSpec {
    name = "MetaBuilderNodeService";
    constructors.MetaBuilderSpec.fields = [
      { insert = "runtimeVersion"; type = H.string; }
      { insert = "entrypoint"; type = H.string; }
      { insert = "packageManager"; type = H.string; }
      { insert = "scripts"; type = H.attrs; }
      { insert = "testCommand"; type = H.string; }
      { insert = "service"; type = mb.descriptions.ServiceSpec.T; }
      { keep = "name"; }
      { keep = "parameters"; }
      { keep = "inputs"; }
      { keep = "dependencies"; }
      { keep = "tools"; }
      { keep = "operations"; }
      { keep = "outputs"; }
      { keep = "evidence"; }
    ];
  };

  nodeService =
    { name
    , source
    , version ? "0.1.0"
    , runtimePackage ? pkgs.nodejs
    , runtimeVersion ? runtimePackage.version or "node"
    , entrypoint ? baseNameOf (toString source)
    , packageManager ? "npm"
    , port ? 3000
    , healthPath ? "/health"
    }:
    let
      sourceFile = ops.localSource {
        name = entrypoint;
        path = source;
      };

      nodeTool = ops.tool {
        name = "node";
        package = runtimePackage;
      };
      bashTool = ops.tool {
        name = "bash";
        package = pkgs.bash;
      };

      lifecycleSet = ops.capabilitySet {
        categories = [ mb.ornaments.capabilities.builtins.lifecycle ];
      };
      protocol = ops.protocol {
        name = "http";
        description = "HTTP service protocol";
        transport = ops.transports.TCP;
        serialization = ops.serializations.JSON;
        defaultPort = port;
        portEnvVar = "PORT";
        capabilities = lifecycleSet;
        options = {
          inherit healthPath;
        };
      };
      service = ops.service {
        name = "${name}-service";
        description = "Runnable Node service artifact";
        package = runtimePackage;
        capabilities = lifecycleSet;
        protocols = [ protocol ];
        config = [
          (ops.param {
            name = "port";
            description = "TCP port for the HTTP server";
            type = ops.runtimeTypes.RTInt;
            required = false;
          })
          (ops.param {
            name = "healthPath";
            description = "HTTP path used for health checks";
            type = ops.runtimeTypes.RTString;
            required = false;
          })
        ];
      };

      scripts = {
        start = "node ${entrypoint}";
        test = "node --check ${entrypoint}";
      };
      testCommand = scripts.test;

      appOutput = ops.output {
        name = "service-tree";
        path = "$out";
        format = "tree";
      };
      packageOutput = ops.output {
        name = "package-json";
        path = "share/${name}/package.json";
        format = "json";
      };

      packageJson = builtins.toJSON {
        inherit name version;
        type = "module";
        main = entrypoint;
        private = true;
        inherit scripts;
      };

      installScript = ''
        set -eu
        src="$1"
        mkdir -p "$out/bin" "$out/lib/${name}" "$out/share/${name}"
        cp "$src" "$out/lib/${name}/${entrypoint}"
        cat > "$out/bin/${name}" <<EOF
        #!${pkgs.runtimeShell}
        exec ${runtimePackage}/bin/node "$out/lib/${name}/${entrypoint}" "$@"
        EOF
        chmod +x "$out/bin/${name}"
      '';

      # Builder and runtime operations share one ordered carrier over the
      # full signature: builder ops first, then the runtime declarations.
      operations =
        [
          (eff.builder.readSource {
            name = entrypoint;
            source = sourceFile;
          })
          (eff.builder.declareTool { tool = nodeTool; })
          (eff.builder.declareTool { tool = bashTool; })
          (eff.builder.writeFile {
            output = packageOutput;
            text = packageJson;
          })
          (eff.builder.runTool {
            name = "syntax-check";
            tool = nodeTool;
            args = [ "--check" (toString source) ];
          })
          (eff.builder.runTool {
            name = "install-service";
            tool = bashTool;
            args = [ "-c" installScript "install-node-service" (toString source) ];
          })
          (eff.builder.emitDescriptor {
            descriptor = ops.descriptor {
              name = "${name}-metadata";
              payload = {
                kind = "node-service";
                inherit entrypoint packageManager runtimeVersion port healthPath;
              };
            };
          })
          (eff.builder.transformOutput { output = appOutput; })
          (eff.builder.transformOutput { output = packageOutput; })
          (eff.builder.materializeDerivation {
            name = "${name}-artifact";
            builder = "runCommand";
          })
        ]
        ++ map (category: eff.runtime.declareCapability { inherit category; })
          lifecycleSet.categories
        ++ [
          (eff.runtime.declareProtocol { inherit protocol; })
          (eff.runtime.declareService { inherit service; })
          (eff.runtime.materializeUnit { name = service.name; })
        ];
    in
    {
      _con = "MetaBuilderSpec";
      inherit name runtimeVersion entrypoint packageManager scripts testCommand service operations;
      parameters = [
        (ops.parameter { name = "port"; value = port; })
        (ops.parameter { name = "healthPath"; value = healthPath; })
      ];
      inputs = [ sourceFile ];
      dependencies = [ ];
      tools = [ nodeTool bashTool ];
      outputs = [ appOutput packageOutput ];
      evidence = [
        (ops.evidence {
          name = "self-test";
          payload = {
            command = testCommand;
          };
        })
      ];
    };

  spec = nodeService {
    name = "node-service-demo";
    source = ./server.js;
  };

  program = mb.program.fromOrnamentedSpec NodeServiceBuilder.T spec;

  shellScript = mb.program.backends.shell.run program;

  value = {
    builder = {
      inherit NodeServiceBuilder nodeService;
      descriptor = G.derive.deriveDescriptor NodeServiceBuilder;
      schema = G.derive.deriveSchema NodeServiceBuilder;
    };
    inherit spec program;
    specValidation = fx.types.validateValue [ ] NodeServiceBuilder.T spec;
    validation = mb.program.validate.run program;
    deps = mb.program.deps.run program;
    dryRun = mb.program."dry-run".run program;
    planView = mb.program."plan-view".run program;
    docs = mb.program.describe.run program;
    selfView = mb.program.introspect.run program;
    materialize = mb.program.materialize.run program;
    materializeShell = shellScript;
    materializeShellCheck = mb.program.backends.shell.shellcheckFor shellScript;
    materializeDockerfile = mb.program.backends.dockerfile.run program;
    planExport = mb.program."plan-export".json program;
  };

in
{
  scope = {
    inherit NodeServiceBuilder nodeService spec program value;
  };
}
```


### server.js


This is the full service source consumed by the builder. The
materialization plan copies it into the package tree and wraps it with
a generated executable.

Source path: [`examples/node-service/server.js`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/node-service/server.js).

```javascript
import { createServer } from "node:http";

const port = Number.parseInt(process.env.PORT ?? "3000", 10);
const version = process.env.SERVICE_VERSION ?? "0.1.0";

let requestsTotal = 0;

const server = createServer((request, response) => {
  requestsTotal += 1;

  if (request.url === "/health") {
    response.writeHead(200, { "content-type": "application/json" });
    response.end(JSON.stringify({ ok: true }));
    return;
  }

  if (request.url === "/version") {
    response.writeHead(200, { "content-type": "application/json" });
    response.end(JSON.stringify({ version }));
    return;
  }

  if (request.url === "/metrics") {
    response.writeHead(200, { "content-type": "text/plain; version=0.0.4" });
    response.end(
      [
        "# HELP node_service_requests_total Total HTTP requests handled.",
        "# TYPE node_service_requests_total counter",
        `node_service_requests_total ${requestsTotal}`,
        "# HELP node_service_uptime_seconds Process uptime in seconds.",
        "# TYPE node_service_uptime_seconds gauge",
        `node_service_uptime_seconds ${process.uptime()}`,
        "",
      ].join("\n"),
    );
    return;
  }

  response.writeHead(200, { "content-type": "application/json" });
  response.end(JSON.stringify({ service: "node-service-demo" }));
});

server.listen(port, "127.0.0.1", () => {
  console.log(`node-service-demo listening on ${port}`);
});
```


### C code generation example


This tour builds a small native artifact from a message schema. The
example is intentionally compact: one schema file, one hand-written
`main.c`, generated C sources, a static library, and a CLI that proves the
generated library links and runs.

The point is to show how a native builder can expose generated files,
toolchain steps, descriptors, outputs, and the materialization plan as
views of one typed program.

## Start from the artifact

The source fixture is `c-codegen/messages.def`, a tiny key/value
schema. The builder generates:

- `include/config.h` from typed configuration defines.
- `include/generated_messages.h` and `generated/generated_messages.c`
  from the schema.
- `lib/libmessages-demo.a` from the generated object.
- `bin/messages-demo`, linked against the generated library.
- `lib/pkgconfig/messages-demo.pc` as metadata for downstream users.

## Source files

These pages are the complete source for the worked example: the builder module plus the files it consumes.

- [C codegen builder module](/metaBuilder/examples/c-codegen/source/builder.nix) - Source for the C codegen builder constructor and worked native demo program.
- [messages.def](/metaBuilder/examples/c-codegen/source/messages.def) - Schema fixture consumed by the C code generator in the native demo.
- [main.c](/metaBuilder/examples/c-codegen/source/main.c) - Small CLI source linked against the generated static library.

## Builder vocabulary

`CCodegenBuilder` ornaments `BuilderSpec` with the native-builder
fields that matter here: compiler identity, schema input, config
defines, and artifact kind. The public constructor keeps the domain
surface focused on the source inputs and leaves the internal program
to spell out the build mechanics.

```nix
cCodegen {
  name = "messages-demo";
  schema = ./c-codegen/messages.def;
  main = ./c-codegen/main.c;
}
```

## Program walkthrough

The constructor lowers the spec into a sequence of operations:
read the schema and `main.c`, declare `bash`, `gcc`, and `ar`, write
the config header, generate C sources, compile the generated source,
archive the static library, link the demo CLI, run a smoke test, emit
pkg-config metadata, and declare each output.

Because those steps are data, metaBuilder can interpret them without
rebuilding the builder by hand. Dependency analysis sees the tool-use
edges, dry-run shows the build actions, plan-view exposes the shell
plan, and materialization turns the same plan into a derivation.

## One build, many views

The section below is generated from `mb.program.introspect.run
program`. It is the internalized view of the native build: validation,
dependency graph, dry-run, plan-view, descriptors, outputs, and
materialization.

The same internalized program is interpreted several ways.

### Validation

- result: `ok`

### Dependency Graph

- nodes: `8`
- edges: `5`
- services: `0`
- node `tool:bash` (tool) package `bash-interactive`
- node `tool:gcc` (tool) package `gcc-wrapper`
- node `tool:ar` (tool) package `binutils-wrapper`
- node `operation:generate-c-sources` (operation) via `bash`
- node `operation:compile-generated-object` (operation) via `gcc`
- node `operation:archive-library` (operation) via `ar`
- node `operation:link-demo-cli` (operation) via `gcc`
- node `operation:smoke-test` (operation) via `bash`
- edge `tool:bash` -> `operation:generate-c-sources` (uses-tool)
- edge `tool:gcc` -> `operation:compile-generated-object` (uses-tool)
- edge `tool:ar` -> `operation:archive-library` (uses-tool)
- edge `tool:gcc` -> `operation:link-demo-cli` (uses-tool)
- edge `tool:bash` -> `operation:smoke-test` (uses-tool)

### Dry Run - Builder

- source `messages.def`
- source `main.c`
- tool `bash`
- tool `gcc`
- tool `ar`
- write `include/config.h`
- run `generate-c-sources` with `bash`
- run `compile-generated-object` with `gcc`
- run `archive-library` with `ar`
- run `link-demo-cli` with `gcc`
- run `smoke-test` with `bash`
- write `lib/pkgconfig/messages-demo.pc`
- descriptor `messages-demo-metadata`
- transform `cli` (elf)
- transform `static-library` (archive)
- transform `headers` (directory)
- transform `pkg-config` (text)
- materialize `messages-demo-artifact` with `runCommand`
- evidence `smoke-test`

### Dry Run - Runtime

None.

### Plan View

- write `write:include/config.h`
- run `generate-c-sources`
- run `compile-generated-object`
- run `archive-library`
- run `link-demo-cli`
- run `smoke-test`
- write `write:lib/pkgconfig/messages-demo.pc`
- `write:include/config.h`: `mkdir -p "$(dirname "$out/include/config.h")"`
- `generate-c-sources`: `bash -c 'set -eu`
- `compile-generated-object`: `gcc -I"$out"/include -c ''"$out"/generated/generated_messages.c -o ''"$out"/generated/generated_messages.o`
- `archive-library`: `ar rcs ''"$out"/lib/libmessages-demo.a ''"$out"/generated/generated_messages.o`
- `link-demo-cli`: `gcc -I"$out"/include "$pathMap_45f70a987ef70685ad13cc6283095c8504a3d4d95f23567a890bb52427d3338d" ''"$out"/lib/libmessages-demo.a -o ''"$out"/bin/messages-demo`
- `smoke-test`: `bash -c 'set -eu`
- `write:lib/pkgconfig/messages-demo.pc`: `mkdir -p "$(dirname "$out/lib/pkgconfig/messages-demo.pc")"`

### Plan Shell Excerpt

```sh
pathMap_301f316e1baa45459961d7b5c3f4a9881e17adfe67b148a8295231c6d567d78f=<source:messages.def>
pathMap_45f70a987ef70685ad13cc6283095c8504a3d4d95f23567a890bb52427d3338d=<source:main.c>
mkdir -p "$(dirname "$out/include/config.h")"
cat > "$out/include/config.h" <<'METABUILDER_HEREDOC_856398558058b5929d6076680e5c3cd22f31adde4a8117afd770ec6dc55cfd7d'
#define DEMO_FEATURE 1
#define MESSAGE_LIMIT 8

METABUILDER_HEREDOC_856398558058b5929d6076680e5c3cd22f31adde4a8117afd770ec6dc55cfd7d
bash -c 'set -eu
schema="$1"
```

### Runtime Services

None.

### Descriptors

- descriptor `messages-demo-metadata` (payload keys `artifactKind`, `compiler`, `configDefines`, `generated`, `kind`)

### Builder Self-Documentation

- documented operations: `19`
- runtime services: `0`

### Materialized Outputs

- cli -> $out/bin/messages-demo (elf)
- static-library -> $out/lib/libmessages-demo.a (archive)
- headers -> $out/include (directory)
- pkg-config -> lib/pkgconfig/messages-demo.pc (text)

### Materialization

- derivation: `messages-demo-artifact`
- outputs: `4`
- runtime artifacts: `0`

### Substrates

- dockerfile: `supported`
- shell: `supported`



### Source files


These files are the complete source for C code generation example: the
builder module plus the fixtures it consumes.

- [C codegen builder module](/metaBuilder/examples/c-codegen/source/builder.nix) - Source for the C codegen builder constructor and worked native demo program.
- [messages.def](/metaBuilder/examples/c-codegen/source/messages.def) - Schema fixture consumed by the C code generator in the native demo.
- [main.c](/metaBuilder/examples/c-codegen/source/main.c) - Small CLI source linked against the generated static library.


### C codegen builder module


This module defines the `CCodegenBuilder` ornament, the `cCodegen`
constructor, the concrete `messages-demo` spec, and the exported views
used by the tour page.

Source path: [`examples/c-codegen/builder.nix`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/c-codegen/builder.nix).

```nix
{ mb, fx, lib, pkgs, ... }:

let
  H = fx.types.hoas;
  G = fx.types.generic;
  ops = mb.operations;
  eff = mb.program.eff;

  CCodegenBuilder = H.ornament mb.descriptions.BuilderSpec {
    name = "MetaBuilderCCodegen";
    constructors.MetaBuilderSpec.fields = [
      { insert = "compiler"; type = H.string; }
      { insert = "schema"; type = H.any; }
      { insert = "configDefines"; type = H.attrs; }
      { insert = "artifactKind"; type = H.string; }
      { keep = "name"; }
      { keep = "parameters"; }
      { keep = "inputs"; }
      { keep = "dependencies"; }
      { keep = "tools"; }
      { keep = "operations"; }
      { keep = "outputs"; }
      { keep = "evidence"; }
    ];
  };

  cCodegen =
    { name
    , schema
    , main
    , compilerPackage ? pkgs.gcc
    , binutilsPackage ? pkgs.binutils
    , compiler ? compilerPackage.pname or "gcc"
    , configDefines ? {
        DEMO_FEATURE = 1;
        MESSAGE_LIMIT = 8;
      }
    , artifactKind ? "static-library-with-cli"
    }:
    let
      schemaSource = ops.localSource {
        name = baseNameOf (toString schema);
        path = schema;
      };
      mainSource = ops.localSource {
        name = baseNameOf (toString main);
        path = main;
      };

      gccTool = ops.tool {
        name = "gcc";
        package = compilerPackage;
      };
      arTool = ops.tool {
        name = "ar";
        package = binutilsPackage;
      };
      bashTool = ops.tool {
        name = "bash";
        package = pkgs.bash;
      };

      cliOutput = ops.output {
        name = "cli";
        path = "$out/bin/${name}";
        format = "elf";
      };
      libraryOutput = ops.output {
        name = "static-library";
        path = "$out/lib/lib${name}.a";
        format = "archive";
      };
      headerOutput = ops.output {
        name = "headers";
        path = "$out/include";
        format = "directory";
      };
      pkgConfigOutput = ops.output {
        name = "pkg-config";
        path = "lib/pkgconfig/${name}.pc";
        format = "text";
      };

      defineLines = lib.concatStringsSep "\n"
        (lib.mapAttrsToList
          (key: value: "#define ${key} ${toString value}")
          configDefines);

      codegenScript = ''
        set -eu
        schema="$1"
        mkdir -p "$out/generated" "$out/include" "$out/lib" "$out/bin" "$out/share/${name}" "$out/lib/pkgconfig"
        header="$out/include/generated_messages.h"
        source="$out/generated/generated_messages.c"
        printf '%s\n' '#pragma once' '#include "config.h"' > "$header"
        printf '%s\n' '#include "generated_messages.h"' > "$source"
        while IFS=: read key text; do
          if [ -z "$key" ]; then
            continue
          fi
          printf 'const char *message_%s(void);\n' "$key" >> "$header"
          printf 'const char *message_%s(void) { return "%s"; }\n' "$key" "$text" >> "$source"
        done < "$schema"
      '';

      smokeScript = ''
        set -eu
        mkdir -p "$out/share/${name}"
        "$out/bin/${name}" > "$out/share/${name}/smoke.txt"
      '';

      packageConfig = ''
        prefix=$out
        exec_prefix=$out
        libdir=$out/lib
        includedir=$out/include

        Name: ${name}
        Description: generated C demo library
        Version: 0.1.0
        Libs: -L$out/lib -l${name}
        Cflags: -I$out/include
      '';

      operations = [
        (eff.builder.readSource {
          name = schemaSource.name;
          source = schemaSource;
        })
        (eff.builder.readSource {
          name = mainSource.name;
          source = mainSource;
        })
        (eff.builder.declareTool { tool = bashTool; })
        (eff.builder.declareTool { tool = gccTool; })
        (eff.builder.declareTool { tool = arTool; })
        (eff.builder.writeFile {
          output = ops.output {
            name = "config-header";
            path = "include/config.h";
            format = "c-header";
          };
          text = "${defineLines}\n";
        })
        (eff.builder.runTool {
          name = "generate-c-sources";
          tool = bashTool;
          args = [ "-c" codegenScript "generate-c-sources" (toString schema) ];
        })
        (eff.builder.runTool {
          name = "compile-generated-object";
          tool = gccTool;
          args = [
            "-I$out/include"
            "-c"
            "$out/generated/generated_messages.c"
            "-o"
            "$out/generated/generated_messages.o"
          ];
        })
        (eff.builder.runTool {
          name = "archive-library";
          tool = arTool;
          args = [
            "rcs"
            "$out/lib/lib${name}.a"
            "$out/generated/generated_messages.o"
          ];
        })
        (eff.builder.runTool {
          name = "link-demo-cli";
          tool = gccTool;
          args = [
            "-I$out/include"
            (toString main)
            "$out/lib/lib${name}.a"
            "-o"
            "$out/bin/${name}"
          ];
        })
        (eff.builder.runTool {
          name = "smoke-test";
          tool = bashTool;
          args = [ "-c" smokeScript "smoke-test" ];
        })
        (eff.builder.writeFile {
          output = pkgConfigOutput;
          text = packageConfig;
        })
        (eff.builder.emitDescriptor {
          descriptor = ops.descriptor {
            name = "${name}-metadata";
            payload = {
              kind = "c-codegen";
              inherit artifactKind compiler configDefines;
              generated = [
                "include/generated_messages.h"
                "generated/generated_messages.c"
                "lib/lib${name}.a"
                "bin/${name}"
              ];
            };
          };
        })
        (eff.builder.transformOutput { output = cliOutput; })
        (eff.builder.transformOutput { output = libraryOutput; })
        (eff.builder.transformOutput { output = headerOutput; })
        (eff.builder.transformOutput { output = pkgConfigOutput; })
        (eff.builder.materializeDerivation {
          name = "${name}-artifact";
          builder = "runCommand";
        })
      ];
    in
    {
      _con = "MetaBuilderSpec";
      inherit name compiler schema configDefines artifactKind operations;
      parameters = [
        (ops.parameter { name = "artifactKind"; value = artifactKind; })
      ];
      inputs = [ schemaSource mainSource ];
      dependencies = [ ];
      tools = [ bashTool gccTool arTool ];
      outputs = [ cliOutput libraryOutput headerOutput pkgConfigOutput ];
      evidence = [
        (ops.evidence {
          name = "smoke-test";
          payload = {
            command = "$out/bin/${name}";
            expectedOutput = "hello from generated C";
          };
        })
      ];
    };

  spec = cCodegen {
    name = "messages-demo";
    schema = ./messages.def;
    main = ./main.c;
  };

  program = mb.program.fromOrnamentedSpec CCodegenBuilder.T spec;

  shellScript = mb.program.backends.shell.run program;

  value = {
    builder = {
      inherit CCodegenBuilder cCodegen;
      descriptor = G.derive.deriveDescriptor CCodegenBuilder;
      schema = G.derive.deriveSchema CCodegenBuilder;
    };
    inherit spec program;
    validation = mb.program.validate.run program;
    deps = mb.program.deps.run program;
    dryRun = mb.program."dry-run".run program;
    planView = mb.program."plan-view".run program;
    docs = mb.program.describe.run program;
    selfView = mb.program.introspect.run program;
    materialize = mb.program.materialize.run program;
    materializeShell = shellScript;
    materializeShellCheck = mb.program.backends.shell.shellcheckFor shellScript;
    # node-service is excluded: its launcher embeds /nix/store paths.
    materializeShellEquality = mb.program.backends.shell.executionCheckFor program;
    materializeDockerfile = mb.program.backends.dockerfile.run program;
    planExport = mb.program."plan-export".json program;
  };

in
{
  scope = {
    inherit CCodegenBuilder cCodegen spec program value;
  };
}
```


### messages.def


This schema is the generator input. The build plan reads each
`key:value` row and emits declarations plus C functions returning the
configured text.

Source path: [`examples/c-codegen/messages.def`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/c-codegen/messages.def).

```text
hello:hello from generated C
health:ok
```


### main.c


This hand-written CLI proves the generated header and static library
can be consumed by ordinary C code.

Source path: [`examples/c-codegen/main.c`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/c-codegen/main.c).

```c
#include <stdio.h>

#include "config.h"
#include "generated_messages.h"

int main(void) {
  printf("%s\n", message_hello());
  return DEMO_FEATURE ? 0 : 1;
}
```


### Bridge example


The shipped builder kinds are related by proof objects checked through
the nix-effects kernel. For each of the four example builders — Node
service, C code generation, OCI image, and IDL — the bridge proves how
the ornament refines its base, how its forget map computes, and how
program compilation factors through forget. It also pins the shared
effect language, internalizes the materialize and dry-run step folds,
and proves their tag agreement for every program.

## What is proven

The bridge relates all four example builders — Node service, C code
generation, OCI image, and IDL — through the common `BuilderSpec`
surface and the shared builder effect language. Each kind carries
the same theorem family: ornament membership, forget codomain and
computation, and program compilation factoring through forget with
no bypass. The IDL theorems track the two-level forget through
`CodeGenBuilder` down to `BuilderSpec`. The final group internalizes
the materialize and dry-run step folds and proves they agree on
step tags for every program; the Node and C builders additionally
carry intersection theorems over their actual tool and
output-format lists.

### `node-spec-inhabits-node-ornament`

$$
\mathsf{node.spec} : \mathsf{NodeServiceBuilder.T}
$$

- Type: $\mathsf{NodeServiceBuilder.T}$
- Proof: $\mathsf{review}_{\mathsf{NodeServiceBuilder.T}}(\mathsf{node.spec})$
- Kernel result: `desc-con`


### `c-spec-inhabits-c-ornament`

$$
\mathsf{c.spec} : \mathsf{CCodegenBuilder.T}
$$

- Type: $\mathsf{CCodegenBuilder.T}$
- Proof: $\mathsf{review}_{\mathsf{CCodegenBuilder.T}}(\mathsf{c.spec})$
- Kernel result: `desc-con`


### `node-forget-has-builder-spec-codomain`

$$
\mathsf{forget}_{Node} : \mathsf{NodeServiceBuilder.T} \to \mathsf{BuilderSpec.T}
$$

- Type: $\Pi(\mathsf{spec} : \mathsf{NodeServiceBuilder.T}).\, \mathsf{BuilderSpec.T}$
- Proof: $\mathsf{forgetHoas}(\mathsf{NodeServiceBuilder})$
- Kernel result: `ann`


### `c-forget-has-builder-spec-codomain`

$$
\mathsf{forget}_{C} : \mathsf{CCodegenBuilder.T} \to \mathsf{BuilderSpec.T}
$$

- Type: $\Pi(\mathsf{spec} : \mathsf{CCodegenBuilder.T}).\, \mathsf{BuilderSpec.T}$
- Proof: $\mathsf{forgetHoas}(\mathsf{CCodegenBuilder})$
- Kernel result: `ann`


### `node-forget-computes-base-builder-spec`

$$
\mathsf{forget}_{Node}(\mathsf{node.spec}) = \mathsf{node.baseSpec} : \mathsf{BuilderSpec.T}
$$

- Type: $\operatorname{Eq}_{\mathsf{BuilderSpec.T}}(\mathsf{forget}_{Node}(\mathsf{node.spec}), \mathsf{node.baseSpec})$
- Proof: $\mathsf{refl}$
- Kernel result: `desc-con`


### `c-forget-computes-base-builder-spec`

$$
\mathsf{forget}_{C}(\mathsf{c.spec}) = \mathsf{c.baseSpec} : \mathsf{BuilderSpec.T}
$$

- Type: $\operatorname{Eq}_{\mathsf{BuilderSpec.T}}(\mathsf{forget}_{C}(\mathsf{c.spec}), \mathsf{c.baseSpec})$
- Proof: $\mathsf{refl}$
- Kernel result: `desc-con`


### `node-program-compilation-factors-through-forget`

$$
\mathsf{program}_{Node} \equiv \mathsf{fromSpec}\big(\mathsf{forget}_{Node}(\mathsf{node.spec})\big)
$$

- Type: $\mathsf{program}_{Node} \equiv \mathsf{fromSpec}\big(\mathsf{forget}_{Node}(\mathsf{node.spec})\big)$
- Proof: $\operatorname{conv}\big(\mathsf{program}_{Node},\ \mathsf{fromSpec}(\mathsf{forget}_{Node}(\mathsf{node.spec}))\big)$
- Kernel result: `definitional-equality`


### `c-program-compilation-factors-through-forget`

$$
\mathsf{program}_{C} \equiv \mathsf{fromSpec}\big(\mathsf{forget}_{C}(\mathsf{c.spec})\big)
$$

- Type: $\mathsf{program}_{C} \equiv \mathsf{fromSpec}\big(\mathsf{forget}_{C}(\mathsf{c.spec})\big)$
- Proof: $\operatorname{conv}\big(\mathsf{program}_{C},\ \mathsf{fromSpec}(\mathsf{forget}_{C}(\mathsf{c.spec}))\big)$
- Kernel result: `definitional-equality`


### `node-program-is-from-ornamented-spec-no-bypass`

$$
\mathsf{program}_{Node} \equiv \mathsf{fromSpec}(\mathsf{NodeServiceBuilder.T},\ \mathsf{node.spec})
$$

- Type: $\mathsf{program}_{Node} \equiv \mathsf{fromSpec}(\mathsf{NodeServiceBuilder.T},\ \mathsf{node.spec})$
- Proof: $\operatorname{conv}\big(\mathsf{program}_{Node},\ \mathsf{fromSpec}(\mathsf{NodeServiceBuilder.T},\ \mathsf{node.spec})\big)$
- Kernel result: `definitional-equality`


### `c-program-is-from-ornamented-spec-no-bypass`

$$
\mathsf{program}_{C} \equiv \mathsf{fromSpec}(\mathsf{CCodegenBuilder.T},\ \mathsf{c.spec})
$$

- Type: $\mathsf{program}_{C} \equiv \mathsf{fromSpec}(\mathsf{CCodegenBuilder.T},\ \mathsf{c.spec})$
- Proof: $\operatorname{conv}\big(\mathsf{program}_{C},\ \mathsf{fromSpec}(\mathsf{CCodegenBuilder.T},\ \mathsf{c.spec})\big)$
- Kernel result: `definitional-equality`


### `oci-spec-inhabits-oci-ornament`

$$
\mathsf{oci.spec} : \mathsf{OciImageBuilder.T}
$$

- Type: $\mathsf{OciImageBuilder.T}$
- Proof: $\mathsf{review}_{\mathsf{OciImageBuilder.T}}(\mathsf{oci.spec})$
- Kernel result: `desc-con`


### `oci-forget-has-builder-spec-codomain`

$$
\mathsf{forget}_{Oci} : \mathsf{OciImageBuilder.T} \to \mathsf{BuilderSpec.T}
$$

- Type: $\Pi(\mathsf{spec} : \mathsf{OciImageBuilder.T}).\, \mathsf{BuilderSpec.T}$
- Proof: $\mathsf{forgetHoas}(\mathsf{OciImageBuilder})$
- Kernel result: `ann`


### `oci-forget-computes-base-builder-spec`

$$
\mathsf{forget}_{Oci}(\mathsf{oci.spec}) = \mathsf{oci.baseSpec} : \mathsf{BuilderSpec.T}
$$

- Type: $\operatorname{Eq}_{\mathsf{BuilderSpec.T}}(\mathsf{forget}_{Oci}(\mathsf{oci.spec}), \mathsf{oci.baseSpec})$
- Proof: $\mathsf{refl}$
- Kernel result: `desc-con`


### `oci-program-compilation-factors-through-forget`

$$
\mathsf{program}_{Oci} \equiv \mathsf{fromSpec}\big(\mathsf{forget}_{Oci}(\mathsf{oci.spec})\big)
$$

- Type: $\mathsf{program}_{Oci} \equiv \mathsf{fromSpec}\big(\mathsf{forget}_{Oci}(\mathsf{oci.spec})\big)$
- Proof: $\operatorname{conv}\big(\mathsf{program}_{Oci},\ \mathsf{fromSpec}(\mathsf{forget}_{Oci}(\mathsf{oci.spec}))\big)$
- Kernel result: `definitional-equality`


### `oci-program-is-from-ornamented-spec-no-bypass`

$$
\mathsf{program}_{Oci} \equiv \mathsf{fromSpec}(\mathsf{OciImageBuilder.T},\ \mathsf{oci.spec})
$$

- Type: $\mathsf{program}_{Oci} \equiv \mathsf{fromSpec}(\mathsf{OciImageBuilder.T},\ \mathsf{oci.spec})$
- Proof: $\operatorname{conv}\big(\mathsf{program}_{Oci},\ \mathsf{fromSpec}(\mathsf{OciImageBuilder.T},\ \mathsf{oci.spec})\big)$
- Kernel result: `definitional-equality`


### `idl-spec-inhabits-idl-ornament`

$$
\mathsf{idl.spec} : \mathsf{IdlBuilder.T}
$$

- Type: $\mathsf{IdlBuilder.T}$
- Proof: $\mathsf{review}_{\mathsf{IdlBuilder.T}}(\mathsf{idl.spec})$
- Kernel result: `desc-con`


### `idl-forget-has-code-gen-codomain`

$$
\mathsf{forget}_{Idl} : \mathsf{IdlBuilder.T} \to \mathsf{CodeGenBuilder.T}
$$

- Type: $\Pi(\mathsf{spec} : \mathsf{IdlBuilder.T}).\, \mathsf{CodeGenBuilder.T}$
- Proof: $\mathsf{forgetHoas}(\mathsf{IdlBuilder})$
- Kernel result: `ann`


### `idl-composite-forget-has-builder-spec-codomain`

$$
\mathsf{forget}_{CG} \circ \mathsf{forget}_{Idl} : \mathsf{IdlBuilder.T} \to \mathsf{BuilderSpec.T}
$$

- Type: $\Pi(\mathsf{spec} : \mathsf{IdlBuilder.T}).\, \mathsf{BuilderSpec.T}$
- Proof: $\lambda \mathsf{spec}.\, \mathsf{forgetHoas}(\mathsf{CodeGenBuilder})\,(\mathsf{forgetHoas}(\mathsf{IdlBuilder})\,\mathsf{spec})$
- Kernel result: `lam`


### `idl-forget-computes-code-gen-spec`

$$
\mathsf{forget}_{Idl}(\mathsf{idl.spec}) = \mathsf{idl.cgSpec} : \mathsf{CodeGenBuilder.T}
$$

- Type: $\operatorname{Eq}_{\mathsf{CodeGenBuilder.T}}(\mathsf{forget}_{Idl}(\mathsf{idl.spec}), \mathsf{idl.cgSpec})$
- Proof: $\mathsf{refl}$
- Kernel result: `desc-con`


### `idl-forget-computes-base-builder-spec`

$$
\mathsf{forget}_{CG}(\mathsf{forget}_{Idl}(\mathsf{idl.spec})) = \mathsf{idl.baseSpec} : \mathsf{BuilderSpec.T}
$$

- Type: $\operatorname{Eq}_{\mathsf{BuilderSpec.T}}(\mathsf{forget}_{CG}(\mathsf{forget}_{Idl}(\mathsf{idl.spec})), \mathsf{idl.baseSpec})$
- Proof: $\mathsf{refl}$
- Kernel result: `desc-con`


### `idl-program-compilation-factors-through-forget`

$$
\mathsf{program}_{Idl} \equiv \mathsf{fromSpec}\big(\mathsf{forget}_{CG}(\mathsf{forget}_{Idl}(\mathsf{idl.spec}))\big)
$$

- Type: $\mathsf{program}_{Idl} \equiv \mathsf{fromSpec}\big(\mathsf{forget}_{CG}(\mathsf{forget}_{Idl}(\mathsf{idl.spec}))\big)$
- Proof: $\operatorname{conv}\big(\mathsf{program}_{Idl},\ \mathsf{fromSpec}(\mathsf{forget}_{CG}(\mathsf{forget}_{Idl}(\mathsf{idl.spec})))\big)$
- Kernel result: `definitional-equality`


### `idl-program-is-from-ornamented-spec-no-bypass`

$$
\mathsf{program}_{Idl} \equiv \mathsf{fromSpec}(\mathsf{IdlBuilder.T},\ \mathsf{idl.spec})
$$

- Type: $\mathsf{program}_{Idl} \equiv \mathsf{fromSpec}(\mathsf{IdlBuilder.T},\ \mathsf{idl.spec})$
- Proof: $\operatorname{conv}\big(\mathsf{program}_{Idl},\ \mathsf{fromSpec}(\mathsf{IdlBuilder.T},\ \mathsf{idl.spec})\big)$
- Kernel result: `definitional-equality`


### `builder-effect-language-is-builder-plus-runtime`

$$
\mathsf{BuilderEff} \equiv \mathsf{BuilderOp.T} + \mathsf{RuntimeOp.T}
$$

- Type: $\mathsf{BuilderEff} \equiv \mathsf{BuilderOp.T} + \mathsf{RuntimeOp.T}$
- Proof: $\operatorname{conv}(\mathsf{BuilderEff}, \mathsf{BuilderOp.T} + \mathsf{RuntimeOp.T})$
- Kernel result: `definitional-equality`


### `shared-tools-normalize-from-actual-tool-lists`

$$
\operatorname{filter}(\lambda x.\, x \in \mathsf{c.tools})(\mathsf{node.tools}) = \mathsf{sharedTools}
$$

- Type: $\operatorname{Eq}_{\operatorname{List}(\mathsf{String})}(\operatorname{filter}(\lambda x.\, x \in \mathsf{c.tools})(\mathsf{node.tools}), \mathsf{sharedTools})$
- Proof: $\mathsf{refl}$
- Kernel result: `desc-con`


### `shared-output-formats-normalize-from-actual-output-lists`

$$
\operatorname{filter}(\lambda x.\, x \in \mathsf{c.outputFormats})(\mathsf{node.outputFormats}) = \mathsf{sharedOutputFormats}
$$

- Type: $\operatorname{Eq}_{\operatorname{List}(\mathsf{String})}(\operatorname{filter}(\lambda x.\, x \in \mathsf{c.outputFormats})(\mathsf{node.outputFormats}), \mathsf{sharedOutputFormats})$
- Proof: $\mathsf{refl}$
- Kernel result: `desc-con`


### `matfoldk-internalizes-materialize-step-emission`

$$
\mathsf{matFoldK} : \operatorname{List}(\mathsf{BuilderEff}) \to \operatorname{List}(\mathsf{BuildPlanStep})
$$

- Type: $\Pi(\_ : \operatorname{List}(\mathsf{BuilderEff})).\, \operatorname{List}(\mathsf{BuildPlanStep})$
- Proof: $\operatorname{fold}(\operatorname{matchSum}\,(\operatorname{matchData}\,\mathsf{BuilderOp})\,(\operatorname{matchData}\,\mathsf{RuntimeOp}))$
- Kernel result: `ann`


### `mattagfoldk-projects-step-fold-to-tags`

$$
\mathsf{matTagFoldK} : \operatorname{List}(\mathsf{BuilderEff}) \to \operatorname{List}(\mathsf{StepTag})
$$

- Type: $\Pi(\_ : \operatorname{List}(\mathsf{BuilderEff})).\, \operatorname{List}(\mathsf{StepTag})$
- Proof: $\operatorname{map}\,\mathsf{tagOf} \circ \mathsf{matFoldK}$
- Kernel result: `ann`


### `drytagfoldk-internalizes-dryrun-tag-emission`

$$
\mathsf{dryTagFoldK} : \operatorname{List}(\mathsf{BuilderEff}) \to \operatorname{List}(\mathsf{StepTag})
$$

- Type: $\Pi(\_ : \operatorname{List}(\mathsf{BuilderEff})).\, \operatorname{List}(\mathsf{StepTag})$
- Proof: $\operatorname{fold}(\operatorname{matchSum}\,(\operatorname{matchData}\,\mathsf{BuilderOp}\to\mathsf{StepTag}))$
- Kernel result: `ann`


### `mattagfoldk-agrees-with-drytagfoldk-forall-p`

$$
\forall p.\ \mathsf{matTagFoldK}\,p = \mathsf{dryTagFoldK}\,p : \operatorname{List}(\mathsf{StepTag})
$$

- Type: $\Pi(p:\operatorname{List}(\mathsf{BuilderEff})).\,\operatorname{Eq}(\mathsf{matTagFoldK}\,p,\ \mathsf{dryTagFoldK}\,p)$
- Proof: $\mathsf{listElim}\,(\mathsf{sumElim}\,(\mathsf{elimData}\,\mathsf{J}/\mathsf{ih}))$
- Kernel result: `skipped` (long normalization; verified in the heavy test suite)

## Source files

These pages are the complete source for the worked example: the builder module plus the files it consumes.

- [Bridge proof module](/metaBuilder/examples/bridge/source/bridge.nix) - Source for the kernel-checked bridge theorem set.

## Normal forms

The list-intersection theorems run over the Node and C builders'
actual lists. The bridge derives these values from the loaded
builder specs:

- BuilderSpec fields: `name`, `parameters`, `inputs`, `dependencies`, `tools`, `operations`, `outputs`, `evidence`
- Node base name: `node-service-demo`
- C base name: `messages-demo`
- Node tools: `node`, `bash`
- C tools: `bash`, `gcc`, `ar`
- Shared tools: `bash`
- Node output formats: `tree`, `json`
- C output formats: `elf`, `archive`, `directory`, `text`
- Shared output formats: `[]`

## Proof boundary

The checked bridge covers the relationships currently resident in the
kernel: ornament membership, forget maps, the common effect carrier,
derived list computations over strings, and the internalized
materialize and dry-run tag folds together with their agreement
theorem. The self-views remain documentation views over the
resulting builder programs; they consume these facts but are not
themselves proof terms.



### Source files


These files are the complete source for Bridge example: the
builder module plus the fixtures it consumes.

- [Bridge proof module](/metaBuilder/examples/bridge/source/bridge.nix) - Source for the kernel-checked bridge theorem set.


### Bridge proof module


This module checks the bridge theorems and exposes their normal
forms.

Source path: [`examples/bridge.nix`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/bridge.nix).

```nix
{ lib, self, mb, fx, ... }:

let
  H = fx.types.hoas;
  V = fx.types.generic.value;
  G = fx.types.generic;
  v = fx.types.verified;
  E = fx.tc.eval;
  C = fx.tc.conv;

  node = self.node-service.value;
  c = self.c-codegen.value;
  oci = self."oci-image".value;
  idl = self.idl.value;

  NodeBuilder = node.builder.NodeServiceBuilder;
  CBuilder = c.builder.CCodegenBuilder;
  OciBuilder = oci.builder.OciImageBuilder;
  IdlBuilder = idl.builder.IdlBuilder;
  CodeGenBuilder = mb.ornaments."code-gen".CodeGenBuilder;
  BuilderSpec = mb.descriptions.BuilderSpec;

  nodeSpecH = V.review NodeBuilder.T node.spec;
  cSpecH = V.review CBuilder.T c.spec;
  ociSpecH = V.review OciBuilder.T oci.spec;
  idlSpecH = V.review IdlBuilder.T idl.spec;

  nodeBaseSpec = G.ornaments.forget NodeBuilder node.spec;
  cBaseSpec = G.ornaments.forget CBuilder c.spec;
  ociBaseSpec = G.ornaments.forget OciBuilder oci.spec;
  nodeBaseSpecH = V.review BuilderSpec.T nodeBaseSpec;
  cBaseSpecH = V.review BuilderSpec.T cBaseSpec;
  ociBaseSpecH = V.review BuilderSpec.T ociBaseSpec;

  # IdlBuilder ornaments CodeGenBuilder, which ornaments BuilderSpec, so
  # reaching the common base takes two forget steps.
  idlCgSpec = G.ornaments.forget IdlBuilder idl.spec;
  idlBaseSpec = G.ornaments.forget CodeGenBuilder idlCgSpec;
  idlCgSpecH = V.review CodeGenBuilder.T idlCgSpec;
  idlBaseSpecH = V.review BuilderSpec.T idlBaseSpec;

  # forget keeps `operations` and `evidence` — everything compileSpec
  # reads — so compiling the forgotten base spec rebuilds the same
  # program as the ornamented spec: compilation factors through forget.
  nodeBaseProgram = mb.program.fromSpec nodeBaseSpec;
  cBaseProgram = mb.program.fromSpec cBaseSpec;
  ociBaseProgram = mb.program.fromSpec ociBaseSpec;
  idlBaseProgram = mb.program.fromSpec idlBaseSpec;

  # The compiled effect lists (operations + lowered evidence): the same
  # input the live interpreters fold, so the kernel fold and the drift
  # check exercise every constructor the live path sees.
  nodeCompiledOps = mb.program.compileSpec BuilderSpec.T nodeBaseSpec;
  cCompiledOps = mb.program.compileSpec BuilderSpec.T cBaseSpec;
  ociCompiledOps = mb.program.compileSpec BuilderSpec.T ociBaseSpec;
  idlCompiledOps = mb.program.compileSpec BuilderSpec.T idlBaseSpec;

  # The canonical program for each example, recomputed from its spec.
  nodeFromSpec = mb.program.fromOrnamentedSpec NodeBuilder.T node.spec;
  cFromSpec = mb.program.fromOrnamentedSpec CBuilder.T c.spec;
  ociFromSpec = mb.program.fromOrnamentedSpec OciBuilder.T oci.spec;
  idlFromSpec = mb.program.fromOrnamentedSpec IdlBuilder.T idl.spec;

  evalHoas = term: E.eval [ ] (H.elab term);

  phrase = text: math: { inherit text math; };
  term = text: math: value: { inherit text math value; };

  # heavy: the check normalizes large concrete terms (minutes of kernel
  # evaluation); its test lands in the heavy suite instead of the default.
  kernelCheck = { name, statement, type, proof, heavy ? false }:
    let result = H.checkHoas type.value proof.value;
    in {
      inherit name heavy;
      statement = statement.text;
      statementMath = statement.math;
      type = type.text;
      typeMath = type.math;
      proof = proof.text;
      proofMath = proof.math;
      kind = "kernel-check";
      ok = !(result ? error);
      resultTag = result.tag or "error";
      # Lazy: reading statement fields must not force the kernel check.
      error = result.error or null;
    };

  kernelConversion = { name, statement, type, proof, lhs, rhs }:
    let ok = C.conv 0 (evalHoas lhs) (evalHoas rhs);
    in {
      inherit name ok;
      statement = statement.text;
      statementMath = statement.math;
      type = type.text;
      typeMath = type.math;
      proof = proof.text;
      proofMath = proof.math;
      kind = "kernel-conversion";
      resultTag = if ok then "definitional-equality" else "mismatch";
    };

  builderEffSum = H.sum mb.descriptions.BuilderOp.T mb.descriptions.RuntimeOp.T;

  noError = result: !(result ? error);

  # The renderer ρ : BuildPlanStep → String as a kernel term. opaqueLam carries
  # the live renderStep as an unverified trust boundary; String is axiomatised so
  # ρ never reduces. Structural step-fold coherence only needs both folds to apply
  # this same ρ, so the renderer body stays opaque.
  rhoTy = H.forall "_" mb.descriptions.BuildPlanStep.T (_: H.string);
  rho = H.opaqueLam mb.program.materialize.renderStep rhoTy;
  rhoCheck =
    let typeChecks = noError (H.checkHoas rhoTy rho);
    in { inherit typeChecks; ok = typeChecks; };

  # `mb.descriptions.BuildPlanStep.T` is the kernel step carrier directly
  # (descriptions.nix). Steps are born finalized: runStep's tool is
  # FinalizedToolSpec (all-string fields). The remaining opaque leaves —
  # SourceSpec.T's `any`, env's `attrs` — are axiomatised kernel primitives,
  # so the structural step-fold threads eliminator-bound payloads through it
  # with no fabricated literals. This gate confirms the carrier forms and its
  # emitting constructors inhabit with payloads threaded as bound variables
  # (exactly matFoldK's usage), and the param-instantiated
  # `args : listOf string` field checks.
  planStep =
    let
      BPS = mb.descriptions.BuildPlanStep;
      FinalizedToolSpec = mb.descriptions.FinalizedToolSpec;
      SourceSpec = mb.descriptions.SourceSpec;
      app3 = f: a: b: c: H.app (H.app (H.app f a) b) c;
      app4 = f: a: b: c: d: H.app (H.app (H.app (H.app f a) b) c) d;

      typeForms = noError (H.checkHoas (H.u 0) BPS.T);

      # The threading case matFoldK's runTool branch produces: name/tool/args/env
      # all arrive as bound variables at the constructor's field types.
      runThreadTy =
        H.forall "name" H.string (_:
        H.forall "tool" FinalizedToolSpec.T (_:
        H.forall "args" (H.listOf H.string) (_:
        H.forall "env" H.attrs (_: BPS.T))));
      runThreadTm =
        H.lam "name" H.string (name:
        H.lam "tool" FinalizedToolSpec.T (tool:
        H.lam "args" (H.listOf H.string) (args:
        H.lam "env" H.attrs (env:
          app4 BPS.runStep name tool args env))));
      runStepThreads = noError (H.checkHoas runThreadTy runThreadTm);

      # The param-instantiated literal: args built as a `cons` literal checked
      # against `listOf string` (the ann-strip target), tool/env threaded as vars.
      runLitTy = H.forall "tool" FinalizedToolSpec.T (_: H.forall "env" H.attrs (_: BPS.T));
      runLitTm =
        H.lam "tool" FinalizedToolSpec.T (tool:
        H.lam "env" H.attrs (env:
          app4 BPS.runStep (H.stringLit "n") tool
            (H.cons (H.stringLit "a") H.nil) env));
      runStepLitArgs = noError (H.checkHoas runLitTy runLitTm);

      writeStepInhabits = noError (H.checkHoas BPS.T
        (app3 BPS.writeStep (H.stringLit "w") (H.stringLit "/out/f") (H.stringLit "txt")));

      # copyStep threads source : SourceSpec.T as a bound variable.
      copyTy = H.forall "source" SourceSpec.T (_: BPS.T);
      copyTm = H.lam "source" SourceSpec.T (source:
        app3 BPS.copyStep (H.stringLit "c") source (H.stringLit "/out/d"));
      copyStepThreads = noError (H.checkHoas copyTy copyTm);
    in
    {
      inherit typeForms runStepThreads runStepLitArgs writeStepInhabits copyStepThreads;
      ok = typeForms && runStepThreads && runStepLitArgs && writeStepInhabits && copyStepThreads;
    };

  # matFoldK : listOf BuilderEff → listOf BuildPlanStep — the kernel
  # internalisation of materialize's step emission. v.matchSum splits the
  # sum-injected ops; v.matchData runs the per-op BuilderOp/RuntimeOp
  # eliminators, consing each emitted step into the fold accumulator.
  matFold =
    let
      BPS = mb.descriptions.BuildPlanStep;
      BOp = mb.descriptions.BuilderOp;
      ROp = mb.descriptions.RuntimeOp;
      OutputSpec = mb.descriptions.OutputSpec;
      ToolSpec = mb.descriptions.ToolSpec;
      FinalizedToolSpec = mb.descriptions.FinalizedToolSpec;
      stepsTy = H.listOf BPS.T;
      app2 = f: a: b: H.app (H.app f a) b;
      app3 = f: a: b: c: H.app (H.app (H.app f a) b) c;
      app4 = f: a: b: c: d: H.app (H.app (H.app (H.app f a) b) c) d;
      outName = output: v.field OutputSpec.T "name" output;
      outPath = output: v.field OutputSpec.T "path" output;

      # materialize finalizes the tool at emission (finalizeTool : ToolSpec →
      # FinalizedToolSpec); its package projection forces a live derivation —
      # a trust boundary the kernel cannot compute. The internalised emitter
      # threads the ρ-visible `name` through both string fields; `package` is
      # trust-boundary payload, reattached from the live step at the render
      # comparison (renderableStep).
      finalizeK = H.ann
        (H.lam "tool" ToolSpec.T (tool:
          app2 FinalizedToolSpec.MetaBuilderFinalizedTool
            (v.field ToolSpec.T "name" tool)
            (v.field ToolSpec.T "name" tool)))
        (H.forall "_" ToolSpec.T (_: FinalizedToolSpec.T));

      # Per-op emitter, fold-fused: each branch conses its step into `ih`
      # or passes `ih` through. matchData ann-wraps every body at stepsTy.
      matStepF = op: ih:
        v.matchSum BOp.T ROp.T stepsTy op {
          left = bop: v.matchData BOp stepsTy bop {
            readSource = name: source: ih;
            resolveDependency = dependency: ih;
            declareTool = tool: ih;
            runTool = name: tool: args: env:
              H.cons (app4 BPS.runStep name (H.app finalizeK tool) args env) ih;
            writeFile = output: text:
              H.cons (app3 BPS.writeStep (outName output) (outPath output) text) ih;
            copyPath = source: output:
              H.cons (app3 BPS.copyStep (outName output) source (outPath output)) ih;
            transformOutput = output: ih;
            validateValue = validation: ih;
            emitDescriptor = descriptor: ih;
            materializeDerivation = name: builder: ih;
            declareEvidence = evidence: ih;
          };
          right = rop: v.matchData ROp stepsTy rop {
            declareCapability = category: ih;
            declareProtocol = protocol: ih;
            declareService = service: ih;
            materializeUnit = name: ih;
          };
        };

      foldTy = H.forall "_" (H.listOf builderEffSum) (_: stepsTy);
      matFoldK = H.ann
        (H.lam "p" (H.listOf builderEffSum) (p:
          v.fold builderEffSum stepsTy H.nil
            (H.lam "op" builderEffSum (op: H.lam "ih" stepsTy (ih: matStepF op ih)))
            p))
        foldTy;

      nodeOpsH = V.review (H.listOf builderEffSum) nodeCompiledOps;
      cOpsH = V.review (H.listOf builderEffSum) cCompiledOps;

      # The catamorphism across the Pi extraction boundary: a Nix function
      # that elaborates its argument (raw operations, no prior review),
      # runs the verified closure, and extracts the step list back.
      matFoldX = fx.tc.elaborate.verifyAndExtract foldTy matFoldK;

      # Tag projection: the ρ-invisible structural skeleton of a step list.
      # The two interpreters differ on payloads (materialize synthesises a
      # name dry-run drops), so the honest agreement is at the tag level.
      StepTag = H.datatype "MetaBuilderStepTag" [
        (H.con "RunT" [ ])
        (H.con "WriteT" [ ])
        (H.con "CopyT" [ ])
        (H.con "MkdirT" [ ])
      ];
      tagsTy = H.listOf StepTag.T;

      # tagOf : BuildPlanStep → StepTag.
      tagOf = H.lam "s" BPS.T (s: v.matchData BPS StepTag.T s {
        runStep = name: tool: args: env: StepTag.RunT;
        writeStep = name: path: text: StepTag.WriteT;
        copyStep = name: source: path: StepTag.CopyT;
        mkdirStep = path: StepTag.MkdirT;
      });

      tagFoldTy = H.forall "_" (H.listOf builderEffSum) (_: tagsTy);

      # matTagFoldK = tagSeq ∘ matFoldK — the tag projection of the real
      # step catamorphism (mapped over its output, no refold).
      matTagFoldK = H.ann
        (H.lam "p" (H.listOf builderEffSum) (p:
          v.map BPS.T StepTag.T tagOf (H.app matFoldK p)))
        tagFoldTy;

      # dryTagFoldK internalises dry-run's tag-all + the dryRunStepCons
      # filter+rename to {run,write,copy}: a fold-fused emitter consing one
      # tag per emitting op, passing ih through otherwise.
      dryTagStepF = op: ih:
        v.matchSum BOp.T ROp.T tagsTy op {
          left = bop: v.matchData BOp tagsTy bop {
            readSource = name: source: ih;
            resolveDependency = dependency: ih;
            declareTool = tool: ih;
            runTool = name: tool: args: env: H.cons StepTag.RunT ih;
            writeFile = output: text: H.cons StepTag.WriteT ih;
            copyPath = source: output: H.cons StepTag.CopyT ih;
            transformOutput = output: ih;
            validateValue = validation: ih;
            emitDescriptor = descriptor: ih;
            materializeDerivation = name: builder: ih;
            declareEvidence = evidence: ih;
          };
          right = rop: v.matchData ROp tagsTy rop {
            declareCapability = category: ih;
            declareProtocol = protocol: ih;
            declareService = service: ih;
            materializeUnit = name: ih;
          };
        };
      dryTagFoldK = H.ann
        (H.lam "p" (H.listOf builderEffSum) (p:
          v.fold builderEffSum tagsTy H.nil
            (H.lam "op" builderEffSum (op: H.lam "ih" tagsTy (ih: dryTagStepF op ih)))
            p))
        tagFoldTy;

      tagConName = builtins.listToAttrs (lib.imap0
        (i: c: { name = "con${toString i}"; value = c.name; })
        (fx.tc.generic.datatype.datatypeInfo StepTag).constructors);
      extractTags = foldK: ops:
        map (s: tagConName.${s._con})
          (fx.tc.elaborate.verifyAndExtract tagsTy (H.app foldK ops));
      matTagCons = extractTags matTagFoldK;
      dryTagCons = extractTags dryTagFoldK;

      # ∀p structural agreement of the two tag folds, proved in the kernel:
      # map/fold fusion by induction on p. Under the induction binder the
      # cons head is neutral, so each step case-splits it (sumElim, then
      # elimData on the op payload) to expose a canonical constructor and
      # let ι-reduction fire through both folds. Emitting ops discharge by
      # J-congruence on the tag cons; the others pass the induction
      # hypothesis through unchanged; nil is refl.
      #
      # Construction constraints (each load-bearing):
      # - The folds are let_-bound once and every motive references the
      #   bound variables: eliminator wrappers ann-wrap each branch body
      #   against a meta-level copy of the motive, so embedding the fold
      #   terms directly multiplies them per branch and exhausts memory.
      # - The congruence step is a raw J with the function application
      #   already reduced in the motive; H.cong's motive embeds an
      #   unannotated meta-lam that does not elaborate in this position.
      # - cons literals are ann'd: polymorphic-constructor implicits do
      #   not solve in type position.
      # - Injections use the explicit forms at levelZero to match sumElim's
      #   internal construction (opt-in internal surface).
      inlOp = b: H._internal._indexed.inlAtExplicit H.levelZero BOp.T ROp.T b;
      inrOp = r: H._internal._indexed.inrAtExplicit H.levelZero BOp.T ROp.T r;
      consEff = h: t: H.ann (H.cons h t) (H.listOf builderEffSum);
      consTags = h: t: H.ann (H.cons h t) tagsTy;
      agreeAtF = matF: dryF: q: H.eq tagsTy (H.app matF q) (H.app dryF q);

      stepCongF = matF: dryF: t: ih: tag:
        H.j tagsTy (H.app matF t)
          (H.lam "w" tagsTy (w:
           H.lam "_p" (H.eq tagsTy (H.app matF t) w) (_:
             H.eq tagsTy
               (consTags tag (H.app matF t))
               (consTags tag w))))
          H.refl
          (H.app dryF t)
          ih;

      elimBopF = matF: dryF: t: ih: bop:
        v.elimData 0 BOp
          (H.lam "b" BOp.T (b: agreeAtF matF dryF (consEff (inlOp b) t)))
          bop
          {
            readSource = name: source: ih;
            resolveDependency = dependency: ih;
            declareTool = tool: ih;
            runTool = name: tool: args: env: stepCongF matF dryF t ih StepTag.RunT;
            writeFile = output: text: stepCongF matF dryF t ih StepTag.WriteT;
            copyPath = source: output: stepCongF matF dryF t ih StepTag.CopyT;
            transformOutput = output: ih;
            validateValue = validation: ih;
            emitDescriptor = descriptor: ih;
            materializeDerivation = name: builder: ih;
            declareEvidence = evidence: ih;
          };
      elimRopF = matF: dryF: t: ih: rop:
        v.elimData 0 ROp
          (H.lam "r" ROp.T (r: agreeAtF matF dryF (consEff (inrOp r) t)))
          rop
          {
            declareCapability = category: ih;
            declareProtocol = protocol: ih;
            declareService = service: ih;
            materializeUnit = name: ih;
          };

      sumSplitF = matF: dryF: t: ih: h:
        H.sumElim 0 BOp.T ROp.T
          (H.lam "hh" builderEffSum (hh: agreeAtF matF dryF (consEff hh t)))
          (H.lam "bop" BOp.T (bop: elimBopF matF dryF t ih bop))
          (H.lam "rop" ROp.T (rop: elimRopF matF dryF t ih rop))
          h;

      tagAgreeTy = H.forall "p" (H.listOf builderEffSum) (p:
        H.eq tagsTy (H.app matTagFoldK p) (H.app dryTagFoldK p));
      tagAgreeProof =
        H.let_ "matF" tagFoldTy matTagFoldK (matF:
        H.let_ "dryF" tagFoldTy dryTagFoldK (dryF:
          H.lam "p" (H.listOf builderEffSum) (p:
            H.listElim 0 builderEffSum
              (H.lam "q" (H.listOf builderEffSum) (q: agreeAtF matF dryF q))
              H.refl
              (H.lam "h" builderEffSum (h:
               H.lam "t" (H.listOf builderEffSum) (t:
               H.lam "ih" (agreeAtF matF dryF t) (ih:
                 sumSplitF matF dryF t ih h))))
              p)));
    in
    {
      inherit matFoldK foldTy nodeOpsH cOpsH matFoldX;
      inherit StepTag tagFoldTy matTagFoldK dryTagFoldK matTagCons dryTagCons;
      inherit tagAgreeTy tagAgreeProof;
      typeChecks = noError (H.checkHoas foldTy matFoldK);
    };

  # ρ across the extraction boundary: the opaque lambda gives back the
  # Nix function it carries — the live renderer itself. Rendering both
  # sides of the drift check through rhoX keeps the renderer single.
  rhoX = fx.tc.elaborate.verifyAndExtract rhoTy rho;

  # Extracted datatype values are positionally named (con<i> / _field<j>);
  # rename through datatype metadata to declared constructor/field names.
  # Field values stay lazy, so opaque payloads are renamed without force.
  renameByDatatype = dt: s:
    let
      ctors = (fx.tc.generic.datatype.datatypeInfo dt).constructors;
      byCon = builtins.listToAttrs (lib.imap0
        (i: ctor: { name = "con${toString i}"; value = ctor; }) ctors);
      ctor = byCon.${s._con};
    in
    { _con = ctor.name; } // builtins.listToAttrs (lib.imap0
      (i: f: { name = f.name; value = s."_field${toString i}"; }) ctor.fields);

  # Rebuild a renderable step from an extracted one. env (attrs) and the
  # source payload are axiomatised-opaque in the kernel — extraction cannot
  # carry them, so they reattach from the live step (the designed trust
  # boundary). Every ρ-visible representable field (tool.name, args, path,
  # text) comes from the extracted step.
  renderableStep = live: s:
    let named = renameByDatatype mb.descriptions.BuildPlanStep s; in
    if named._con == "runStep" then
      named // {
        tool = renameByDatatype mb.descriptions.FinalizedToolSpec named.tool;
        env = live.env;
      }
    else if named._con == "copyStep" then named // { source = live.source; }
    else named;

  extractedNodeSteps = matFold.matFoldX nodeCompiledOps;
  extractedCSteps = matFold.matFoldX cCompiledOps;
  extractedOciSteps = matFold.matFoldX ociCompiledOps;
  extractedIdlSteps = matFold.matFoldX idlCompiledOps;
  extractedStepCons =
    map (s: (renameByDatatype mb.descriptions.BuildPlanStep s)._con);

  # The extraction drift-check: matFoldK crosses the Pi extraction boundary
  # as a runnable Nix function, consumes the live operations directly, and
  # must reproduce live materialize — same constructor sequence (which pins
  # the length, so the zipped render comparison cannot truncate away extra
  # steps) and same rendered commands through ρ. Both sides render through
  # rhoX, and rhoIsLiveRenderer pins rhoX to the live renderer, so renderer
  # drift is excluded; what remains is genuine fold drift. Step names are
  # ρ-invisible and differ by design; env/source reattach (renderableStep).
  #
  # Coverage split: the constructor-sequence facets cover all four shipped
  # examples; the rendered-command facets apply only to node and c, the
  # examples that render shells.
  extractionCheck =
    let
      renderLive = map mb.program.materialize.renderStep;
      renderX = xs: lives:
        lib.zipListsWith (s: live: rhoX (renderableStep live s)) xs lives;
      checks = {
        nodeNonEmpty = builtins.length extractedNodeSteps > 0;
        ociNonEmpty = builtins.length extractedOciSteps > 0;
        idlNonEmpty = builtins.length extractedIdlSteps > 0;
        hasRunStep = builtins.elem "runStep"
          (extractedStepCons (extractedNodeSteps ++ extractedCSteps));
        nodeCons = extractedStepCons extractedNodeSteps
          == materializeStepCons node.materialize;
        cCons = extractedStepCons extractedCSteps
          == materializeStepCons c.materialize;
        ociCons = extractedStepCons extractedOciSteps
          == materializeStepCons oci.materialize;
        idlCons = extractedStepCons extractedIdlSteps
          == materializeStepCons idl.materialize;
        nodeRender = renderX extractedNodeSteps node.materialize.plan.steps
          == renderLive node.materialize.plan.steps;
        cRender = renderX extractedCSteps c.materialize.plan.steps
          == renderLive c.materialize.plan.steps;
        rhoIsLiveRenderer =
          let s = builtins.head node.materialize.plan.steps;
          in rhoX s == mb.program.materialize.renderStep s;
      };
    in
    checks // { ok = builtins.all (n: checks.${n}) (builtins.attrNames checks); };

  nodeTools = map (tool: tool.name) node.spec.tools;
  cTools = map (tool: tool.name) c.spec.tools;
  sharedTools = lib.intersectLists nodeTools cTools;

  nodeOutputs = map (output: output.format) node.spec.outputs;
  cOutputs = map (output: output.format) c.spec.outputs;
  sharedOutputFormats = lib.intersectLists nodeOutputs cOutputs;

  stringList = H.listOf H.string;
  nodeToolsH = V.review stringList nodeTools;
  cToolsH = V.review stringList cTools;
  sharedToolsH = V.review stringList sharedTools;
  nodeOutputsH = V.review stringList nodeOutputs;
  cOutputsH = V.review stringList cOutputs;
  sharedOutputFormatsH = V.review stringList sharedOutputFormats;

  intersectByKernel = left: right:
    v.filter H.string
      (v.fn "candidate" H.string
        (candidate: v.strElem candidate right))
      left;

  builderSpecFields =
    map
      (field: field.name)
      ((builtins.head (G.derive.deriveDescriptor BuilderSpec).constructors).fields);

  # dry-run tags every op; materialize records a step only for
  # runTool/writeFile/copyPath. Filtering dry-run to those kinds and renaming
  # reproduces materialize's step constructors in order.
  stepKindToCon = { run = "runStep"; write = "writeStep"; copy = "copyStep"; };
  dryRunStepCons = dry:
    map (s: stepKindToCon.${s.kind})
      (builtins.filter (s: stepKindToCon ? ${s.kind}) dry.steps);
  materializeStepCons = mat: map (s: s._con) mat.plan.steps;
  stepConToTag = { runStep = "RunT"; writeStep = "WriteT"; copyStep = "CopyT"; mkdirStep = "MkdirT"; };

  theoremList = [
    (kernelCheck {
      name = "node-spec-inhabits-node-ornament";
      statement = phrase "node.spec : NodeServiceBuilder.T"
        "\\mathsf{node.spec} : \\mathsf{NodeServiceBuilder.T}";
      type = term "NodeServiceBuilder.T"
        "\\mathsf{NodeServiceBuilder.T}"
        NodeBuilder.T;
      proof = term "V.review NodeServiceBuilder.T node.spec"
        "\\mathsf{review}_{\\mathsf{NodeServiceBuilder.T}}(\\mathsf{node.spec})"
        nodeSpecH;
    })
    (kernelCheck {
      name = "c-spec-inhabits-c-ornament";
      statement = phrase "c.spec : CCodegenBuilder.T"
        "\\mathsf{c.spec} : \\mathsf{CCodegenBuilder.T}";
      type = term "CCodegenBuilder.T"
        "\\mathsf{CCodegenBuilder.T}"
        CBuilder.T;
      proof = term "V.review CCodegenBuilder.T c.spec"
        "\\mathsf{review}_{\\mathsf{CCodegenBuilder.T}}(\\mathsf{c.spec})"
        cSpecH;
    })
    (kernelCheck {
      name = "node-forget-has-builder-spec-codomain";
      statement = phrase "forget_Node : NodeServiceBuilder.T -> BuilderSpec.T"
        "\\mathsf{forget}_{Node} : \\mathsf{NodeServiceBuilder.T} \\to \\mathsf{BuilderSpec.T}";
      type = term "Pi(spec : NodeServiceBuilder.T). BuilderSpec.T"
        "\\Pi(\\mathsf{spec} : \\mathsf{NodeServiceBuilder.T}).\\, \\mathsf{BuilderSpec.T}"
        (H.forall "spec" NodeBuilder.T (_: BuilderSpec.T));
      proof = term "G.ornaments.forgetHoas NodeServiceBuilder"
        "\\mathsf{forgetHoas}(\\mathsf{NodeServiceBuilder})"
        (G.ornaments.forgetHoas NodeBuilder);
    })
    (kernelCheck {
      name = "c-forget-has-builder-spec-codomain";
      statement = phrase "forget_C : CCodegenBuilder.T -> BuilderSpec.T"
        "\\mathsf{forget}_{C} : \\mathsf{CCodegenBuilder.T} \\to \\mathsf{BuilderSpec.T}";
      type = term "Pi(spec : CCodegenBuilder.T). BuilderSpec.T"
        "\\Pi(\\mathsf{spec} : \\mathsf{CCodegenBuilder.T}).\\, \\mathsf{BuilderSpec.T}"
        (H.forall "spec" CBuilder.T (_: BuilderSpec.T));
      proof = term "G.ornaments.forgetHoas CCodegenBuilder"
        "\\mathsf{forgetHoas}(\\mathsf{CCodegenBuilder})"
        (G.ornaments.forgetHoas CBuilder);
    })
    (kernelCheck {
      name = "node-forget-computes-base-builder-spec";
      statement = phrase "forget_Node node.spec = node.baseSpec : BuilderSpec.T"
        "\\mathsf{forget}_{Node}(\\mathsf{node.spec}) = \\mathsf{node.baseSpec} : \\mathsf{BuilderSpec.T}";
      type = term "Eq BuilderSpec.T (forget_Node node.spec) node.baseSpec"
        "\\operatorname{Eq}_{\\mathsf{BuilderSpec.T}}(\\mathsf{forget}_{Node}(\\mathsf{node.spec}), \\mathsf{node.baseSpec})"
        (H.eq BuilderSpec.T
          (G.ornaments.forget NodeBuilder nodeSpecH)
          nodeBaseSpecH);
      proof = term "H.refl" "\\mathsf{refl}" H.refl;
    })
    (kernelCheck {
      name = "c-forget-computes-base-builder-spec";
      statement = phrase "forget_C c.spec = c.baseSpec : BuilderSpec.T"
        "\\mathsf{forget}_{C}(\\mathsf{c.spec}) = \\mathsf{c.baseSpec} : \\mathsf{BuilderSpec.T}";
      type = term "Eq BuilderSpec.T (forget_C c.spec) c.baseSpec"
        "\\operatorname{Eq}_{\\mathsf{BuilderSpec.T}}(\\mathsf{forget}_{C}(\\mathsf{c.spec}), \\mathsf{c.baseSpec})"
        (H.eq BuilderSpec.T
          (G.ornaments.forget CBuilder cSpecH)
          cBaseSpecH);
      proof = term "H.refl" "\\mathsf{refl}" H.refl;
    })
    (kernelConversion {
      name = "node-program-compilation-factors-through-forget";
      statement = phrase "node.program = fromSpec (forget_Node node.spec)"
        "\\mathsf{program}_{Node} \\equiv \\mathsf{fromSpec}\\big(\\mathsf{forget}_{Node}(\\mathsf{node.spec})\\big)";
      type = phrase "Definitional equality of Free(BuilderEff) programs"
        "\\mathsf{program}_{Node} \\equiv \\mathsf{fromSpec}\\big(\\mathsf{forget}_{Node}(\\mathsf{node.spec})\\big)";
      proof = phrase "C.conv 0 (evalHoas node.program) (evalHoas (fromSpec (forget_Node node.spec)))"
        "\\operatorname{conv}\\big(\\mathsf{program}_{Node},\\ \\mathsf{fromSpec}(\\mathsf{forget}_{Node}(\\mathsf{node.spec}))\\big)";
      lhs = node.program;
      rhs = nodeBaseProgram;
    })
    (kernelConversion {
      name = "c-program-compilation-factors-through-forget";
      statement = phrase "c.program = fromSpec (forget_C c.spec)"
        "\\mathsf{program}_{C} \\equiv \\mathsf{fromSpec}\\big(\\mathsf{forget}_{C}(\\mathsf{c.spec})\\big)";
      type = phrase "Definitional equality of Free(BuilderEff) programs"
        "\\mathsf{program}_{C} \\equiv \\mathsf{fromSpec}\\big(\\mathsf{forget}_{C}(\\mathsf{c.spec})\\big)";
      proof = phrase "C.conv 0 (evalHoas c.program) (evalHoas (fromSpec (forget_C c.spec)))"
        "\\operatorname{conv}\\big(\\mathsf{program}_{C},\\ \\mathsf{fromSpec}(\\mathsf{forget}_{C}(\\mathsf{c.spec}))\\big)";
      lhs = c.program;
      rhs = cBaseProgram;
    })
    (kernelConversion {
      name = "node-program-is-from-ornamented-spec-no-bypass";
      statement = phrase "node.program = fromOrnamentedSpec NodeServiceBuilder.T node.spec"
        "\\mathsf{program}_{Node} \\equiv \\mathsf{fromSpec}(\\mathsf{NodeServiceBuilder.T},\\ \\mathsf{node.spec})";
      type = phrase "Definitional equality of Free(BuilderEff) programs"
        "\\mathsf{program}_{Node} \\equiv \\mathsf{fromSpec}(\\mathsf{NodeServiceBuilder.T},\\ \\mathsf{node.spec})";
      proof = phrase "C.conv 0 (evalHoas node.program) (evalHoas (fromOrnamentedSpec NodeServiceBuilder.T node.spec))"
        "\\operatorname{conv}\\big(\\mathsf{program}_{Node},\\ \\mathsf{fromSpec}(\\mathsf{NodeServiceBuilder.T},\\ \\mathsf{node.spec})\\big)";
      lhs = node.program;
      rhs = nodeFromSpec;
    })
    (kernelConversion {
      name = "c-program-is-from-ornamented-spec-no-bypass";
      statement = phrase "c.program = fromOrnamentedSpec CCodegenBuilder.T c.spec"
        "\\mathsf{program}_{C} \\equiv \\mathsf{fromSpec}(\\mathsf{CCodegenBuilder.T},\\ \\mathsf{c.spec})";
      type = phrase "Definitional equality of Free(BuilderEff) programs"
        "\\mathsf{program}_{C} \\equiv \\mathsf{fromSpec}(\\mathsf{CCodegenBuilder.T},\\ \\mathsf{c.spec})";
      proof = phrase "C.conv 0 (evalHoas c.program) (evalHoas (fromOrnamentedSpec CCodegenBuilder.T c.spec))"
        "\\operatorname{conv}\\big(\\mathsf{program}_{C},\\ \\mathsf{fromSpec}(\\mathsf{CCodegenBuilder.T},\\ \\mathsf{c.spec})\\big)";
      lhs = c.program;
      rhs = cFromSpec;
    })
    (kernelCheck {
      name = "oci-spec-inhabits-oci-ornament";
      statement = phrase "oci.spec : OciImageBuilder.T"
        "\\mathsf{oci.spec} : \\mathsf{OciImageBuilder.T}";
      type = term "OciImageBuilder.T"
        "\\mathsf{OciImageBuilder.T}"
        OciBuilder.T;
      proof = term "V.review OciImageBuilder.T oci.spec"
        "\\mathsf{review}_{\\mathsf{OciImageBuilder.T}}(\\mathsf{oci.spec})"
        ociSpecH;
    })
    (kernelCheck {
      name = "oci-forget-has-builder-spec-codomain";
      statement = phrase "forget_Oci : OciImageBuilder.T -> BuilderSpec.T"
        "\\mathsf{forget}_{Oci} : \\mathsf{OciImageBuilder.T} \\to \\mathsf{BuilderSpec.T}";
      type = term "Pi(spec : OciImageBuilder.T). BuilderSpec.T"
        "\\Pi(\\mathsf{spec} : \\mathsf{OciImageBuilder.T}).\\, \\mathsf{BuilderSpec.T}"
        (H.forall "spec" OciBuilder.T (_: BuilderSpec.T));
      proof = term "G.ornaments.forgetHoas OciImageBuilder"
        "\\mathsf{forgetHoas}(\\mathsf{OciImageBuilder})"
        (G.ornaments.forgetHoas OciBuilder);
    })
    (kernelCheck {
      name = "oci-forget-computes-base-builder-spec";
      statement = phrase "forget_Oci oci.spec = oci.baseSpec : BuilderSpec.T"
        "\\mathsf{forget}_{Oci}(\\mathsf{oci.spec}) = \\mathsf{oci.baseSpec} : \\mathsf{BuilderSpec.T}";
      type = term "Eq BuilderSpec.T (forget_Oci oci.spec) oci.baseSpec"
        "\\operatorname{Eq}_{\\mathsf{BuilderSpec.T}}(\\mathsf{forget}_{Oci}(\\mathsf{oci.spec}), \\mathsf{oci.baseSpec})"
        (H.eq BuilderSpec.T
          (G.ornaments.forget OciBuilder ociSpecH)
          ociBaseSpecH);
      proof = term "H.refl" "\\mathsf{refl}" H.refl;
    })
    (kernelConversion {
      name = "oci-program-compilation-factors-through-forget";
      statement = phrase "oci.program = fromSpec (forget_Oci oci.spec)"
        "\\mathsf{program}_{Oci} \\equiv \\mathsf{fromSpec}\\big(\\mathsf{forget}_{Oci}(\\mathsf{oci.spec})\\big)";
      type = phrase "Definitional equality of Free(BuilderEff) programs"
        "\\mathsf{program}_{Oci} \\equiv \\mathsf{fromSpec}\\big(\\mathsf{forget}_{Oci}(\\mathsf{oci.spec})\\big)";
      proof = phrase "C.conv 0 (evalHoas oci.program) (evalHoas (fromSpec (forget_Oci oci.spec)))"
        "\\operatorname{conv}\\big(\\mathsf{program}_{Oci},\\ \\mathsf{fromSpec}(\\mathsf{forget}_{Oci}(\\mathsf{oci.spec}))\\big)";
      lhs = oci.program;
      rhs = ociBaseProgram;
    })
    (kernelConversion {
      name = "oci-program-is-from-ornamented-spec-no-bypass";
      statement = phrase "oci.program = fromOrnamentedSpec OciImageBuilder.T oci.spec"
        "\\mathsf{program}_{Oci} \\equiv \\mathsf{fromSpec}(\\mathsf{OciImageBuilder.T},\\ \\mathsf{oci.spec})";
      type = phrase "Definitional equality of Free(BuilderEff) programs"
        "\\mathsf{program}_{Oci} \\equiv \\mathsf{fromSpec}(\\mathsf{OciImageBuilder.T},\\ \\mathsf{oci.spec})";
      proof = phrase "C.conv 0 (evalHoas oci.program) (evalHoas (fromOrnamentedSpec OciImageBuilder.T oci.spec))"
        "\\operatorname{conv}\\big(\\mathsf{program}_{Oci},\\ \\mathsf{fromSpec}(\\mathsf{OciImageBuilder.T},\\ \\mathsf{oci.spec})\\big)";
      lhs = oci.program;
      rhs = ociFromSpec;
    })
    (kernelCheck {
      name = "idl-spec-inhabits-idl-ornament";
      statement = phrase "idl.spec : IdlBuilder.T"
        "\\mathsf{idl.spec} : \\mathsf{IdlBuilder.T}";
      type = term "IdlBuilder.T"
        "\\mathsf{IdlBuilder.T}"
        IdlBuilder.T;
      proof = term "V.review IdlBuilder.T idl.spec"
        "\\mathsf{review}_{\\mathsf{IdlBuilder.T}}(\\mathsf{idl.spec})"
        idlSpecH;
    })
    (kernelCheck {
      name = "idl-forget-has-code-gen-codomain";
      statement = phrase "forget_Idl : IdlBuilder.T -> CodeGenBuilder.T"
        "\\mathsf{forget}_{Idl} : \\mathsf{IdlBuilder.T} \\to \\mathsf{CodeGenBuilder.T}";
      type = term "Pi(spec : IdlBuilder.T). CodeGenBuilder.T"
        "\\Pi(\\mathsf{spec} : \\mathsf{IdlBuilder.T}).\\, \\mathsf{CodeGenBuilder.T}"
        (H.forall "spec" IdlBuilder.T (_: CodeGenBuilder.T));
      proof = term "G.ornaments.forgetHoas IdlBuilder"
        "\\mathsf{forgetHoas}(\\mathsf{IdlBuilder})"
        (G.ornaments.forgetHoas IdlBuilder);
    })
    (kernelCheck {
      name = "idl-composite-forget-has-builder-spec-codomain";
      statement = phrase "forget_CG . forget_Idl : IdlBuilder.T -> BuilderSpec.T"
        "\\mathsf{forget}_{CG} \\circ \\mathsf{forget}_{Idl} : \\mathsf{IdlBuilder.T} \\to \\mathsf{BuilderSpec.T}";
      type = term "Pi(spec : IdlBuilder.T). BuilderSpec.T"
        "\\Pi(\\mathsf{spec} : \\mathsf{IdlBuilder.T}).\\, \\mathsf{BuilderSpec.T}"
        (H.forall "spec" IdlBuilder.T (_: BuilderSpec.T));
      proof = term "lam spec. forgetHoas CodeGenBuilder (forgetHoas IdlBuilder spec)"
        "\\lambda \\mathsf{spec}.\\, \\mathsf{forgetHoas}(\\mathsf{CodeGenBuilder})\\,(\\mathsf{forgetHoas}(\\mathsf{IdlBuilder})\\,\\mathsf{spec})"
        (H.lam "spec" IdlBuilder.T (s:
          H.app (G.ornaments.forgetHoas CodeGenBuilder)
            (H.app (G.ornaments.forgetHoas IdlBuilder) s)));
    })
    (kernelCheck {
      name = "idl-forget-computes-code-gen-spec";
      statement = phrase "forget_Idl idl.spec = idl.cgSpec : CodeGenBuilder.T"
        "\\mathsf{forget}_{Idl}(\\mathsf{idl.spec}) = \\mathsf{idl.cgSpec} : \\mathsf{CodeGenBuilder.T}";
      type = term "Eq CodeGenBuilder.T (forget_Idl idl.spec) idl.cgSpec"
        "\\operatorname{Eq}_{\\mathsf{CodeGenBuilder.T}}(\\mathsf{forget}_{Idl}(\\mathsf{idl.spec}), \\mathsf{idl.cgSpec})"
        (H.eq CodeGenBuilder.T
          (G.ornaments.forget IdlBuilder idlSpecH)
          idlCgSpecH);
      proof = term "H.refl" "\\mathsf{refl}" H.refl;
    })
    (kernelCheck {
      name = "idl-forget-computes-base-builder-spec";
      statement = phrase "forget_CG (forget_Idl idl.spec) = idl.baseSpec : BuilderSpec.T"
        "\\mathsf{forget}_{CG}(\\mathsf{forget}_{Idl}(\\mathsf{idl.spec})) = \\mathsf{idl.baseSpec} : \\mathsf{BuilderSpec.T}";
      type = term "Eq BuilderSpec.T (forget_CG (forget_Idl idl.spec)) idl.baseSpec"
        "\\operatorname{Eq}_{\\mathsf{BuilderSpec.T}}(\\mathsf{forget}_{CG}(\\mathsf{forget}_{Idl}(\\mathsf{idl.spec})), \\mathsf{idl.baseSpec})"
        (H.eq BuilderSpec.T
          (G.ornaments.forget CodeGenBuilder (G.ornaments.forget IdlBuilder idlSpecH))
          idlBaseSpecH);
      proof = term "H.refl" "\\mathsf{refl}" H.refl;
    })
    (kernelConversion {
      name = "idl-program-compilation-factors-through-forget";
      statement = phrase "idl.program = fromSpec (forget_CG (forget_Idl idl.spec))"
        "\\mathsf{program}_{Idl} \\equiv \\mathsf{fromSpec}\\big(\\mathsf{forget}_{CG}(\\mathsf{forget}_{Idl}(\\mathsf{idl.spec}))\\big)";
      type = phrase "Definitional equality of Free(BuilderEff) programs"
        "\\mathsf{program}_{Idl} \\equiv \\mathsf{fromSpec}\\big(\\mathsf{forget}_{CG}(\\mathsf{forget}_{Idl}(\\mathsf{idl.spec}))\\big)";
      proof = phrase "C.conv 0 (evalHoas idl.program) (evalHoas (fromSpec (forget_CG (forget_Idl idl.spec))))"
        "\\operatorname{conv}\\big(\\mathsf{program}_{Idl},\\ \\mathsf{fromSpec}(\\mathsf{forget}_{CG}(\\mathsf{forget}_{Idl}(\\mathsf{idl.spec})))\\big)";
      lhs = idl.program;
      rhs = idlBaseProgram;
    })
    (kernelConversion {
      name = "idl-program-is-from-ornamented-spec-no-bypass";
      statement = phrase "idl.program = fromOrnamentedSpec IdlBuilder.T idl.spec"
        "\\mathsf{program}_{Idl} \\equiv \\mathsf{fromSpec}(\\mathsf{IdlBuilder.T},\\ \\mathsf{idl.spec})";
      type = phrase "Definitional equality of Free(BuilderEff) programs"
        "\\mathsf{program}_{Idl} \\equiv \\mathsf{fromSpec}(\\mathsf{IdlBuilder.T},\\ \\mathsf{idl.spec})";
      proof = phrase "C.conv 0 (evalHoas idl.program) (evalHoas (fromOrnamentedSpec IdlBuilder.T idl.spec))"
        "\\operatorname{conv}\\big(\\mathsf{program}_{Idl},\\ \\mathsf{fromSpec}(\\mathsf{IdlBuilder.T},\\ \\mathsf{idl.spec})\\big)";
      lhs = idl.program;
      rhs = idlFromSpec;
    })
    (kernelConversion {
      name = "builder-effect-language-is-builder-plus-runtime";
      statement = phrase "BuilderEff == BuilderOp + RuntimeOp"
        "\\mathsf{BuilderEff} \\equiv \\mathsf{BuilderOp.T} + \\mathsf{RuntimeOp.T}";
      type = phrase "Definitional equality judgment"
        "\\mathsf{BuilderEff} \\equiv \\mathsf{BuilderOp.T} + \\mathsf{RuntimeOp.T}";
      proof = phrase "C.conv 0 (evalHoas mb.program.BuilderEff) (evalHoas (H.sum BuilderOp.T RuntimeOp.T))"
        "\\operatorname{conv}(\\mathsf{BuilderEff}, \\mathsf{BuilderOp.T} + \\mathsf{RuntimeOp.T})";
      lhs = mb.program.BuilderEff;
      rhs = builderEffSum;
    })
    (kernelCheck {
      name = "shared-tools-normalize-from-actual-tool-lists";
      statement = phrase "filter (member c.tools) node.tools = sharedTools"
        "\\operatorname{filter}(\\lambda x.\\, x \\in \\mathsf{c.tools})(\\mathsf{node.tools}) = \\mathsf{sharedTools}";
      type = term "Eq (List String) (filter (member c.tools) node.tools) sharedTools"
        "\\operatorname{Eq}_{\\operatorname{List}(\\mathsf{String})}(\\operatorname{filter}(\\lambda x.\\, x \\in \\mathsf{c.tools})(\\mathsf{node.tools}), \\mathsf{sharedTools})"
        (H.eq stringList
          (intersectByKernel nodeToolsH cToolsH)
          sharedToolsH);
      proof = term "H.refl" "\\mathsf{refl}" H.refl;
    })
    (kernelCheck {
      name = "shared-output-formats-normalize-from-actual-output-lists";
      statement = phrase "filter (member c.outputFormats) node.outputFormats = sharedOutputFormats"
        "\\operatorname{filter}(\\lambda x.\\, x \\in \\mathsf{c.outputFormats})(\\mathsf{node.outputFormats}) = \\mathsf{sharedOutputFormats}";
      type = term "Eq (List String) (filter (member c.outputFormats) node.outputFormats) sharedOutputFormats"
        "\\operatorname{Eq}_{\\operatorname{List}(\\mathsf{String})}(\\operatorname{filter}(\\lambda x.\\, x \\in \\mathsf{c.outputFormats})(\\mathsf{node.outputFormats}), \\mathsf{sharedOutputFormats})"
        (H.eq stringList
          (intersectByKernel nodeOutputsH cOutputsH)
          sharedOutputFormatsH);
      proof = term "H.refl" "\\mathsf{refl}" H.refl;
    })
    (kernelCheck {
      name = "matfoldk-internalizes-materialize-step-emission";
      statement = phrase "matFoldK : listOf BuilderEff → listOf BuildPlanStep"
        "\\mathsf{matFoldK} : \\operatorname{List}(\\mathsf{BuilderEff}) \\to \\operatorname{List}(\\mathsf{BuildPlanStep})";
      type = term "H.forall _ (listOf BuilderEff) (_: listOf BuildPlanStep.T)"
        "\\Pi(\\_ : \\operatorname{List}(\\mathsf{BuilderEff})).\\, \\operatorname{List}(\\mathsf{BuildPlanStep})"
        matFold.foldTy;
      proof = term "v.fold over v.matchSum → v.matchData per-op step emitters"
        "\\operatorname{fold}(\\operatorname{matchSum}\\,(\\operatorname{matchData}\\,\\mathsf{BuilderOp})\\,(\\operatorname{matchData}\\,\\mathsf{RuntimeOp}))"
        matFold.matFoldK;
    })
    (kernelCheck {
      name = "mattagfoldk-projects-step-fold-to-tags";
      statement = phrase "matTagFoldK : listOf BuilderEff → listOf StepTag"
        "\\mathsf{matTagFoldK} : \\operatorname{List}(\\mathsf{BuilderEff}) \\to \\operatorname{List}(\\mathsf{StepTag})";
      type = term "H.forall _ (listOf BuilderEff) (_: listOf StepTag.T)"
        "\\Pi(\\_ : \\operatorname{List}(\\mathsf{BuilderEff})).\\, \\operatorname{List}(\\mathsf{StepTag})"
        matFold.tagFoldTy;
      proof = term "v.map tagOf ∘ matFoldK"
        "\\operatorname{map}\\,\\mathsf{tagOf} \\circ \\mathsf{matFoldK}"
        matFold.matTagFoldK;
    })
    (kernelCheck {
      name = "drytagfoldk-internalizes-dryrun-tag-emission";
      statement = phrase "dryTagFoldK : listOf BuilderEff → listOf StepTag"
        "\\mathsf{dryTagFoldK} : \\operatorname{List}(\\mathsf{BuilderEff}) \\to \\operatorname{List}(\\mathsf{StepTag})";
      type = term "H.forall _ (listOf BuilderEff) (_: listOf StepTag.T)"
        "\\Pi(\\_ : \\operatorname{List}(\\mathsf{BuilderEff})).\\, \\operatorname{List}(\\mathsf{StepTag})"
        matFold.tagFoldTy;
      proof = term "v.fold over per-op {run,write,copy} tag emitters"
        "\\operatorname{fold}(\\operatorname{matchSum}\\,(\\operatorname{matchData}\\,\\mathsf{BuilderOp}\\to\\mathsf{StepTag}))"
        matFold.dryTagFoldK;
    })
    (kernelCheck {
      name = "mattagfoldk-agrees-with-drytagfoldk-forall-p";
      heavy = true;
      statement = phrase "∀p. matTagFoldK p = dryTagFoldK p : listOf StepTag"
        "\\forall p.\\ \\mathsf{matTagFoldK}\\,p = \\mathsf{dryTagFoldK}\\,p : \\operatorname{List}(\\mathsf{StepTag})";
      type = term "∀p:listOf BuilderEff. Eq (listOf StepTag) (matTagFoldK p) (dryTagFoldK p)"
        "\\Pi(p:\\operatorname{List}(\\mathsf{BuilderEff})).\\,\\operatorname{Eq}(\\mathsf{matTagFoldK}\\,p,\\ \\mathsf{dryTagFoldK}\\,p)"
        matFold.tagAgreeTy;
      proof = term "listElim induction; cons-head case-split; J-congruence on emitting ctors, ih on the rest"
        "\\mathsf{listElim}\\,(\\mathsf{sumElim}\\,(\\mathsf{elimData}\\,\\mathsf{J}/\\mathsf{ih}))"
        matFold.tagAgreeProof;
    })
  ];

  normalForms = {
    inherit builderSpecFields sharedTools sharedOutputFormats;
    node = {
      name = node.spec.name;
      baseName = nodeBaseSpec.name;
      tools = nodeTools;
      outputFormats = nodeOutputs;
      baseFields = builtins.attrNames nodeBaseSpec;
    };
    c = {
      name = c.spec.name;
      baseName = cBaseSpec.name;
      tools = cTools;
      outputFormats = cOutputs;
      baseFields = builtins.attrNames cBaseSpec;
    };
  };

  value = {
    inherit theoremList normalForms planStep rhoCheck extractionCheck;
  };

in
{
  scope.bridgeModel = {
    inherit value;

    # One test per theorem: streaming results, failures name the theorem.
    tests = builtins.listToAttrs
      (map
        (theorem: {
          name = "${lib.optionalString (theorem.heavy or false) "heavy-"}bridge-theorem-${theorem.name}";
          value = { expr = theorem.ok; expected = true; };
        })
        theoremList)
    // {
      "bridge-base-field-normal-forms-match-builder-spec" = {
        expr =
          let expected = builtins.sort builtins.lessThan ([ "_con" ] ++ builderSpecFields);
          in value.normalForms.node.baseFields == expected
          && value.normalForms.c.baseFields == expected;
        expected = true;
      };

      "bridge-shared-tools-are-derived-from-actual-specs" = {
        expr = value.normalForms.sharedTools == lib.intersectLists nodeTools cTools;
        expected = true;
      };

      "bridge-shared-output-formats-are-derived-from-actual-specs" = {
        expr = value.normalForms.sharedOutputFormats == lib.intersectLists nodeOutputs cOutputs;
        expected = true;
      };

      "bridge-examples-build-operations-without-bypass" = {
        expr = builtins.all (src: !lib.hasInfix "operations ++" src) [
          (builtins.readFile ./node-service/builder.nix)
          (builtins.readFile ./c-codegen/builder.nix)
          (builtins.readFile ./oci-image/builder.nix)
          (builtins.readFile ./idl/builder.nix)
        ];
        expected = true;
      };

      # dry-run is a separately written fold that never calls materialize, so
      # agreement of their step constructors is genuine cross-interpreter
      # content a refactor can break. Non-vacuity guards against empty steps.
      "bridge-dry-run-and-materialize-step-constructors-agree" = {
        expr = {
          nodeNonEmpty = builtins.length node.materialize.plan.steps > 0;
          cNonEmpty = builtins.length c.materialize.plan.steps > 0;
          nodeCons = dryRunStepCons node.dryRun == materializeStepCons node.materialize;
          cCons = dryRunStepCons c.dryRun == materializeStepCons c.materialize;
        };
        expected = {
          nodeNonEmpty = true;
          cNonEmpty = true;
          nodeCons = true;
          cCons = true;
        };
      };

      # The tag projection of matFoldK agrees with the dry-run tag fold on
      # both examples (structural agreement), and both reproduce the tags of
      # live materialize's emitted step constructors. The kernel theorem
      # mattagfoldk-agrees-with-drytagfoldk-forall-p proves the agreement
      # ∀p; this gates the two concrete instances. heavy: each fold
      # application runs verifyAndExtract (typecheck + kernel normalization)
      # over a full example op list.
      "heavy-bridge-matfoldk-tag-fold-agrees-with-dryrun" = {
        expr =
          let toTags = mat: map (con: stepConToTag.${con}) (materializeStepCons mat);
          in {
            nodeNonEmpty = builtins.length (matFold.matTagCons matFold.nodeOpsH) > 0;
            nodeAgree = matFold.matTagCons matFold.nodeOpsH == matFold.dryTagCons matFold.nodeOpsH;
            cAgree = matFold.matTagCons matFold.cOpsH == matFold.dryTagCons matFold.cOpsH;
            nodeFaithful = matFold.matTagCons matFold.nodeOpsH == toTags node.materialize;
            cFaithful = matFold.matTagCons matFold.cOpsH == toTags c.materialize;
          };
        expected = {
          nodeNonEmpty = true;
          nodeAgree = true;
          cAgree = true;
          nodeFaithful = true;
          cFaithful = true;
        };
      };

      # BuildPlanStep.T is the kernel carrier for the structural step-fold,
      # reused directly from descriptions.nix. This gates that the carrier forms
      # (BuildPlanStep.T : U0) and that its emitting constructors inhabit with
      # payloads threaded as eliminator-bound variables — exactly matFoldK's
      # usage — plus the param-instantiated args : listOf string field.
      "bridge-buildplanstep-carrier-inhabits-under-threading" = {
        expr = value.planStep;
        expected = {
          typeForms = true;
          runStepThreads = true;
          runStepLitArgs = true;
          writeStepInhabits = true;
          copyStepThreads = true;
          ok = true;
        };
      };

      # ρ is the renderer the coherence theorem applies to both step-folds. It
      # wraps the live renderStep as an opaque kernel lambda; this gates that it
      # checks against its declared type BuildPlanStep → String.
      "bridge-rho-renderer-typechecks-against-buildplanstep-to-string" = {
        expr = value.rhoCheck;
        expected = { typeChecks = true; ok = true; };
      };
    }
    # One test per extraction drift-check facet; see extractionCheck.
    // builtins.listToAttrs
      (map
        (facet: {
          name = "bridge-extraction-${facet}";
          value = { expr = value.extractionCheck.${facet}; expected = true; };
        })
        [
          "nodeNonEmpty"
          "ociNonEmpty"
          "idlNonEmpty"
          "hasRunStep"
          "nodeCons"
          "cCons"
          "ociCons"
          "idlCons"
          "nodeRender"
          "cRender"
          "rhoIsLiveRenderer"
        ]);
  };
}
```


### IDL example


This tour shows the built-in IDL ornament. It starts from a protobuf-style
builder spec and asks for generated outputs in two languages. The example
is smaller than the Node and C tours because the builder vocabulary already
lives in `mb.ornaments.idl`; the useful part is seeing how that ornament
still produces the same internalized program views.

## Start from the artifact

The IDL builder describes a generated artifact named
`example-idl-generated`. The spec declares protobuf as the IDL format
and asks for C++ and Java outputs. Materialization records both output
trees in the build plan.

## Source files

These pages are the complete source for the worked example: the builder module plus the files it consumes.

- [IDL builder module](/metaBuilder/examples/idl/source/builder.nix) - Source for the built-in IDL ornament demo and its worked program.
- [schema.proto](/metaBuilder/examples/idl/source/schema.proto) - Small protobuf schema fixture consumed by the IDL demo.

## Builder vocabulary

`mb.ornaments.idl.fromProtobuf` is the public constructor. It produces
an `IdlBuilder` value with IDL format, proto sources, language targets,
generated outputs, and tool-backed operations.

```nix
mb.ornaments.idl.fromProtobuf {
  name = "example-idl";
  protos = [ ./idl/schema.proto ];
  languages = [ "cpp" "java" ];
}
```

## Program walkthrough

The ornament lowers the IDL spec into a program that declares the
protobuf tool, runs one generation step per language, and materializes
the generated output tree. The same program can be validated, rendered
as a dry-run, shown as a shell plan, documented, and materialized.

## One build, many views

The section below is generated from `mb.program.introspect.run
program`. It shows the same interpretation surface as the greenfield
examples, but for a built-in ornament.

The same internalized program is interpreted several ways.

### Validation

- result: `ok`

### Dependency Graph

- nodes: `3`
- edges: `2`
- services: `0`
- node `tool:protoc` (tool) package `protobuf`
- node `operation:protoc-cpp-schema.proto` (operation) via `protoc`
- node `operation:protoc-java-schema.proto` (operation) via `protoc`
- edge `tool:protoc` -> `operation:protoc-cpp-schema.proto` (uses-tool)
- edge `tool:protoc` -> `operation:protoc-java-schema.proto` (uses-tool)

### Dry Run - Builder

- source `schema.proto`
- tool `protoc`
- run `protoc-cpp-schema.proto` with `protoc`
- run `protoc-java-schema.proto` with `protoc`
- transform `cpp` (tree)
- transform `java` (tree)
- descriptor `example-idl-idl`
- materialize `example-idl-generated` with `runCommand`

### Dry Run - Runtime

None.

### Plan View

- run `protoc-cpp-schema.proto`
- run `protoc-java-schema.proto`
- `protoc-cpp-schema.proto`: `protoc '--cpp_out='"$out"/cpp "$pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4"`
- `protoc-java-schema.proto`: `protoc '--java_out='"$out"/java "$pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4"`

### Plan Shell Excerpt

```sh
pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4=<source:schema.proto>
protoc '--cpp_out='"$out"/cpp "$pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4"
protoc '--java_out='"$out"/java "$pathMap_57a673735cdae15dcb45e8e52911d34adcbe149b4a6d67b6eea62b6804511ed4"
```

### Runtime Services

None.

### Descriptors

- descriptor `example-idl-idl` (payload keys `format`, `kind`, `languages`, `sources`)

### Builder Self-Documentation

- documented operations: `8`
- runtime services: `0`

### Materialized Outputs

- cpp -> $out/cpp (tree)
- java -> $out/java (tree)

### Materialization

- derivation: `example-idl-generated`
- outputs: `2`
- runtime artifacts: `0`

### Substrates

- dockerfile: `supported`
- shell: `supported`



### Source files


These files are the complete source for IDL example: the
builder module plus the fixtures it consumes.

- [IDL builder module](/metaBuilder/examples/idl/source/builder.nix) - Source for the built-in IDL ornament demo and its worked program.
- [schema.proto](/metaBuilder/examples/idl/source/schema.proto) - Small protobuf schema fixture consumed by the IDL demo.


### IDL builder module


This module constructs the `example-idl` spec with
`mb.ornaments.idl.fromProtobuf`, then exposes the same interpreter
views used by the tour page.

Source path: [`examples/idl/builder.nix`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/idl/builder.nix).

```nix
{ mb, ... }:

let
  idl = mb.ornaments.idl;

  spec = idl.fromProtobuf {
    name = "example-idl";
    protos = [ ./schema.proto ];
    languages = [ "cpp" "java" ];
  };

  program = mb.program.fromOrnamentedSpec
    idl.IdlBuilder.T spec;

  value = {
    builder = {
      inherit (idl) IdlBuilder fromProtobuf descriptor schema;
    };
    inherit spec program;
    # Verdict only: the validated program value is already in scope.
    validation = { inherit (mb.program.validate.run program) ok diagnostics; };
    deps = mb.program.deps.run program;
    dryRun = mb.program."dry-run".run program;
    planView = mb.program."plan-view".run program;
    docs = mb.program.describe.run program;
    selfView = mb.program.introspect.run program;
    materialize = mb.program.materialize.run program;
    schemas = mb.reference.schemas;
    datatypes = mb.reference.datatypes;
  };

in
{
  scope = {
    inherit spec program value;
  };
}
```


### schema.proto


This schema is the source artifact consumed by the IDL builder. The
builder asks for C++ and Java generated views from the same input.

Source path: [`examples/idl/schema.proto`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/idl/schema.proto).

```protobuf
syntax = "proto3";

package metabuilder.example;

message Greeting {
  string text = 1;
  string language = 2;
}

service GreetingService {
  rpc SayHello (Greeting) returns (Greeting);
}
```


### OCI image example


This tour builds a runnable OCI image layout from one static busybox
layer. The builder vocabulary lives in the `oci-image` ornament; this
example only supplies the image fields and shows the resulting views.

The worked artifact is a spec-conformant OCI layout (`oci-layout`,
`index.json`, `blobs/sha256/*`) plus an `image.oci.tar` archive of the
layout, all assembled at build time with the digests computed in the
build sandbox.

## Start from the artifact

The payload is `pkgsStatic.busybox` — a single musl-static layer
with no runtime closure. The build produces:

- `oci-layout` and `index.json`, the layout entry points.
- `blobs/sha256/<digest>` for the layer tar, the image config, and
  the manifest — each blob named by its own sha256.
- `image.oci.tar`, a deterministic tar of the layout for transports
  that want a single file.

## Source files

These pages are the complete source for the worked example: the builder module plus the files it consumes.

- [OCI image example module](/metaBuilder/examples/oci-image/source/builder.nix) - Source for the worked busybox image spec and the exported views.

## Builder vocabulary

`OciImageBuilder` ornaments the generic `BuilderSpec` with the image
fields (layers, entrypoint, cmd, env, exposedPorts, labels,
architecture, os). The `ociImage` constructor compiles those fields
into the assembly program, so the example stays at the domain
surface.

```nix
ociImage {
  name = "busybox-shell";
  layers = [
    { name = "busybox"; source = pkgs.pkgsStatic.busybox; }
  ];
  entrypoint = [ "/bin/sh" ];
}
```

## Program walkthrough

The constructor lowers the image spec into named steps in
digest-chain order: assemble the layer rootfs, tar it
deterministically, render the config (embedding layer diff_ids),
render the manifest (embedding config and layer digests and sizes),
write the index last, re-hash every blob against its filename,
clean the scratch directory, and archive the layout.

Because the steps are data, every fold renders them by name:
dependency analysis, dry-run, plan-view, and self-documentation all
show the same assembly. The smoke-test evidence travels with the
spec and renders under the documentation's Evidence section.

## One build, many views

The section below is generated from `mb.program.introspect.run
program`. It is the internalized view of the image build:
validation, dependency graph, dry-run, plan-view, descriptors,
outputs, and materialization.

The same internalized program is interpreted several ways.

### Validation

- result: `ok`

### Dependency Graph

- nodes: `11`
- edges: `8`
- services: `0`
- node `tool:bash` (tool) package `bash-interactive`
- node `tool:tar` (tool) package `gnutar`
- node `tool:coreutils` (tool) package `coreutils`
- node `operation:assemble-rootfs-busybox` (operation) via `bash`
- node `operation:tar-layer-busybox` (operation) via `bash`
- node `operation:write-config` (operation) via `bash`
- node `operation:write-manifest` (operation) via `bash`
- node `operation:write-index` (operation) via `bash`
- node `operation:verify-blobs` (operation) via `bash`
- node `operation:clean-scratch` (operation) via `bash`
- node `operation:archive-layout` (operation) via `bash`
- edge `tool:bash` -> `operation:assemble-rootfs-busybox` (uses-tool)
- edge `tool:bash` -> `operation:tar-layer-busybox` (uses-tool)
- edge `tool:bash` -> `operation:write-config` (uses-tool)
- edge `tool:bash` -> `operation:write-manifest` (uses-tool)
- edge `tool:bash` -> `operation:write-index` (uses-tool)
- edge `tool:bash` -> `operation:verify-blobs` (uses-tool)
- edge `tool:bash` -> `operation:clean-scratch` (uses-tool)
- edge `tool:bash` -> `operation:archive-layout` (uses-tool)

### Dry Run - Builder

- tool `bash`
- tool `tar`
- tool `coreutils`
- write `oci-layout`
- run `assemble-rootfs-busybox` with `bash`
- run `tar-layer-busybox` with `bash`
- run `write-config` with `bash`
- run `write-manifest` with `bash`
- run `write-index` with `bash`
- run `verify-blobs` with `bash`
- run `clean-scratch` with `bash`
- run `archive-layout` with `bash`
- descriptor `busybox-shell-oci-image`
- transform `oci-layout` (json)
- transform `index` (json)
- transform `blobs` (tree)
- transform `oci-archive` (tar)
- materialize `busybox-shell-oci-image` with `runCommand`
- evidence `smoke-test`

### Dry Run - Runtime

None.

### Plan View

- write `write:oci-layout`
- run `assemble-rootfs-busybox`
- run `tar-layer-busybox`
- run `write-config`
- run `write-manifest`
- run `write-index`
- run `verify-blobs`
- run `clean-scratch`
- run `archive-layout`
- `write:oci-layout`: `mkdir -p "$(dirname "$out/oci-layout")"`
- `assemble-rootfs-busybox`: `bash -c 'set -euo pipefail`
- `tar-layer-busybox`: `bash -c 'set -euo pipefail`
- `write-config`: `bash -c 'set -euo pipefail`
- `write-manifest`: `bash -c 'set -euo pipefail`
- `write-index`: `bash -c 'set -euo pipefail`
- `verify-blobs`: `bash -c 'set -euo pipefail`
- `clean-scratch`: `bash -c 'set -euo pipefail`
- `archive-layout`: `bash -c 'set -euo pipefail`

### Plan Shell Excerpt

```sh
mkdir -p "$(dirname "$out/oci-layout")"
cat > "$out/oci-layout" <<'METABUILDER_HEREDOC_18f0797eab35a4597c1e9624aa4f15fd91f6254e5538c1e0d193b2a95dd4acc6'
{"imageLayoutVersion":"1.0.0"}
METABUILDER_HEREDOC_18f0797eab35a4597c1e9624aa4f15fd91f6254e5538c1e0d193b2a95dd4acc6
bash -c 'set -euo pipefail
mkdir -p "'"$out"'/.scratch/rootfs-busybox"
cp -a "$1"/. "'"$out"'/.scratch/rootfs-busybox/"
chmod -R u+w "'"$out"'/.scratch/rootfs-busybox"
' assemble-rootfs-busybox /nix/store/mm0g0g122n6pi28759dkkx8cfb2724by-busybox-static-x86_64-unknown-linux-musl-1.37.0
bash -c 'set -euo pipefail
```

### Runtime Services

None.

### Descriptors

- descriptor `busybox-shell-oci-image` (payload keys `architecture`, `entrypoint`, `exposedPorts`, `kind`, `labels`, `os`)

### Builder Self-Documentation

- documented operations: `19`
- runtime services: `0`

### Materialized Outputs

- oci-layout -> oci-layout (json)
- index -> $out/index.json (json)
- blobs -> $out/blobs (tree)
- oci-archive -> $out/image.oci.tar (tar)

### Materialization

- derivation: `busybox-shell-oci-image`
- outputs: `4`
- runtime artifacts: `0`

### Substrates

- dockerfile: `supported`
- shell: `supported`



### Source files


These files are the complete source for OCI image example: the
builder module plus the fixtures it consumes.

- [OCI image example module](/metaBuilder/examples/oci-image/source/builder.nix) - Source for the worked busybox image spec and the exported views.


### OCI image example module


This module instantiates the `oci-image` ornament's `ociImage`
constructor with a static busybox layer and exports the views used
by the tour page.

Source path: [`examples/oci-image/builder.nix`](https://github.com/kleisli-io/metaBuilder/blob/main/examples/oci-image/builder.nix).

```nix
{ mb, pkgs, ... }:

let
  ops = mb.operations;
  oci = mb.ornaments."oci-image";

  spec = oci.ociImage {
    name = "busybox-shell";
    layers = [
      { name = "busybox"; source = pkgs.pkgsStatic.busybox; }
    ];
    entrypoint = [ "/bin/sh" ];
    evidence = [
      (ops.evidence {
        name = "smoke-test";
        payload = {
          command = "/bin/sh -c 'echo oci-smoke-ok'";
          expectedOutput = "oci-smoke-ok";
        };
      })
    ];
  };

  program = mb.program.fromOrnamentedSpec oci.OciImageBuilder.T spec;

  value = {
    builder = {
      inherit (oci) OciImageBuilder ociImage descriptor schema;
    };
    inherit spec program;
    validation = mb.program.validate.run program;
    deps = mb.program.deps.run program;
    dryRun = mb.program."dry-run".run program;
    planView = mb.program."plan-view".run program;
    docs = mb.program.describe.run program;
    selfView = mb.program.introspect.run program;
    materialize = mb.program.materialize.run program;
  };

in
{
  scope = {
    inherit spec program value;
  };
}
```


## API Reference

### Core API

#### Descriptions


`BuilderSpec` and `BuilderOp` are generated datatypes. They are the
typed backing for validation, schemas, docs, dependency views, and
program interpretation.

Domain datatypes keep payloads typed before programs interpret them:
sources, dependencies, tools, outputs, evidence, validations,
descriptors, and parameters.



#### Operations


Constructors build typed operation records. Execution is handled by
the internalized `mb.program` desc-interp signature.



### Program

#### Validate


Validation interpreter for typed builder programs.



#### Deps


Dependency graph interpreter for typed builder programs.



#### Dry-run


Dry-run interpreter for typed builder programs.



#### Plan-view


Returns a diagnostic view of a builder program: the typed plan
fields, each step with its rendered shell command, runtime artifact
summaries, and the combined shell transcript. No derivation is
produced.



#### Describe


Builds a documentation model from the builder's own operation program.
This is distinct from `mkDocsContent`, which documents metaBuilder's
public API.



#### Introspect


`introspect.run program` returns every standard view of one builder
program — validation, dependencies, dry-run, plan, documentation,
materialization, substrate support — plus a rendered markdown
summary.



#### Materialize


Builds typed `BuildPlan` step records, validates tool and service
declarations, renders shell commands, and produces a `runCommand`
derivation for the finalized plan. `runState` exposes the typed
pre-finalize plan state that `plan-export` serializes.



#### Backends


Backends translate a validated `BuildPlan` into an artifact for another
build substrate. Unlike the program interpreters they do not fold over
the operation alphabet — they consume the plan that `materialize`
produces, so the interpreter coverage grid does not apply. Each backend
declares the plans it cannot honor through `unsupportedReasons`; nothing
is miscompiled silently.

## `dockerfile`

_dockerfile backend: emits a Dockerfile from a substrate-neutral BuildPlan._

Translates a validated `BuildPlan` into a Dockerfile over a
parameterizable base image: tool preflight by name, local inputs
copied from the build context, and one RUN per rendered step. Plans
it cannot honor are rejected with explicit reasons.

## `shell`

_shell backend: emits a standalone bash script from a substrate-neutral BuildPlan._

Translates a validated `BuildPlan` into a standalone bash script:
tool preflight by name, pathMap exports, library-path export, and the
rendered step commands. Plans it cannot honor are rejected with
explicit reasons.



#### Former


`mkBuilderKind { name, base, builderOps, runtimeOps, stateSpec }`
derives the operation coproduct surface (`Eff`, `Resp`, `reviewOp`,
`opNames`, `injectorsWith`, `dispatch`) and the state ornament
(`State`, `forget`, `forgetWith`) from one argument tuple, so the
op side and the state side cannot drift. The derived `forget` is
op-blind: it never depends on the operation datatypes, so it is
operations-preserving by construction.



#### Plan-export


Serializes a builder program's pre-finalize plan state: `export`
yields a JSON-safe attrset with the `BuildPlan` fields, `json` the
corresponding string. Live derivations never appear in the output —
boxed derivation fields are omitted, and bare boxed positions show
as `null`.



### Reference

#### Schemas


Exposes generated schemas for builder and runtime datatypes without
interpreting a program.



#### Datatypes


Exposes datatype descriptors used by the docs content generator and schema
derivation. Rendered project documentation is produced by
`mb.mkDocsContent`.



### Ornaments

#### Project-builder


`ProjectBuilder` ornaments `BuilderSpec` with a single `langName`
field, marking a spec as belonging to a language-specific project.
Downstream ornaments (`implementations`, `vendoring`, `testing`)
refine `ProjectBuilder` further; `dependencies` ornaments
`BuilderSpec` directly since it is language-agnostic.



#### Dependencies


Two surfaces live on this ornament: a **typed-shape** layer
(constructors + dispatcher + spec ctor) and a **resolver
eliminators** layer (uniform resolution + the resolved-deps marker).

## Typed-shape layer

A `DependencyShape` selects the resolution strategy by
constructor:

- `Uniform { langName }` — single-typed, identical treatment
  across all packages.
- `Partitioned { langName; pathField }` — custom-vs-bundled split
  driven by a sentinel path field.
- `MultiTyped { types : list DependencyType }` — N-type mix; each
  `DependencyType` declares its own transitive / toposort flags.

`matchShape { uniform = …; partitioned = …; multiTyped = …; }
shape` is the typed dispatcher: constructor-driven pattern match
over the three modes.

`define { dependencyShape; … }` produces a `DependenciesBuilder`
spec; consumers fold the spec into the surrounding builder
pipeline downstream.

## Resolver eliminators

`resolveUniform { langName; deps }` walks the transitive closure of
`deps` via the `${langName}Deps` field on each package, then
toposorts so dependencies precede dependents. Throws on cycles.

`markResolved deps` wraps an already-resolved list in a
sentinel-tagged record. `isResolved x` answers the marker check;
`unwrapDeps x` extracts the list (or returns plain inputs as-is).
Together they centralise the inline `if ? __resolvedDeps then
.deps else x` pattern that legacy consumers spelled at every call
site.



#### Implementations


Two complementary surfaces live on this ornament: a **typed-spec**
layer and a **consumer-coordination** layer.

## Typed-spec layer

A `define` call describes a project that supports multiple
interchangeable implementations under a single `langName`. Each
`ImplementationDescriptor` carries a `name` and an open
`capabilities` attrset for impl-specific metadata (e.g. invocation
flags, version range, supported targets).

`select spec implName` returns the descriptor or throws if absent.
`available spec excluded` filters out broken/excluded impls.
`perImpl spec f` evaluates `f` against each impl and returns the
results keyed by impl name — the typed analog of dynamic
`.${implName}` projections.

## Consumer-coordination layer

`defineSystem { langName; implementations; defaultImpl;
makeOverridable; allowUserExtensions ? false }` returns
`{ impls; withExtras; filterByName }` (plus `extend` when
extensions are allowed). The `implementations` argument is an
attrset (`{ impl-a = {...}; impl-b = {...}; ... }`) so consumers
can produce the coordination record without re-shaping input.

`withExtras builderFunction args` projects per-impl variants under
`result.${implName}` attributes, injects `passthru.repl` when an
impl exposes `replWith`, and populates `passthru.meta.ci.targets`
with the implementations minus the current one and `brokenOn`.

`filterByName impl xs` resolves implementation-specific
sources/dependencies — plain values pass through; non-derivation
attrsets are treated as per-impl selectors with optional `default`.

`makeBuilder { implsSystem; createPublicAPI; baseToolEnv }`
recursively wraps a `createPublicAPI` projection with `extend`
and `withTools` so downstream consumers receive the full builder
surface (not just an impls-system) after extension or tool
augmentation. Cross-ornament dependency on `mb.ornaments.toolEnv`.



#### ToolEnv


Typed tool-environment vocabulary. The underlying `ToolEnvSpec`
lives in `mb.descriptions` and carries only a `tools : [ToolSpec]`
list — no bash-string fragments leak into the spec.

- **Smart constructors**:
  - `toolEnv.define { tools }` proxies to `mb.operations.toolEnv`
    (eager structural validation).
  - `toolEnv.create { name = package; ... }` builds the spec from
    a `{ name = package | null; }` attrset (legacy ergonomic shape;
    `null` entries are dropped).
  - `toolEnv.empty` is the zero element.
  - `toolEnv.merge a b` combines two environments; tool name
    collisions resolve B-wins.

- **Eliminators** (pure functions of the typed spec):
  - `toolInputs : ToolEnvSpec → [Derivation]` — deduplicated
    package list for `nativeBuildInputs`.
  - `toolBinPath : ToolEnvSpec → String` — `lib.makeBinPath` view.
  - `toExportSnippet : ToolEnvSpec → String` — heredoc-style
    `export PATH=...` snippet (empty for empty envs).
  - `toInlineSnippet : ToolEnvSpec → String` — indented variant.
  - `toWrapPrefix : ToolEnvSpec → String` — `wrapProgram --prefix`
    fragment.
  - `toolPackages : ToolEnvSpec → { name = Derivation; }` —
    legacy-shaped attrset view, useful for `passthru` round-trip.
  - `isEmpty : ToolEnvSpec → Bool`.

The spec is the single source of truth; every derived view comes
from an eliminator. Shell snippets live in eliminator outputs, not
in spec fields.



#### Testing


A `TestSuite` is a typed list of named `TestCase` records. Each
case carries an opaque `body` — the framework stops typing at the
case boundary so consumers can stash pure-Nix booleans, derivation
builders, or arbitrary runner specs.

`runPure suite` evaluates every case whose body is a boolean and
reports per-case `PASS` / `FAIL` / `SKIP` / `ERROR` classification
plus a `passed` / `failed` / `skipped` tally and an `allPass`
flag. Non-boolean bodies are skipped — that path is for
derivation-driven or runner-driven tests handled downstream.



#### Vendoring


`mkContract { required; optional; description; }` builds a typed
`VendoringContract` declaring the structural requirements a
vendored package must satisfy. `defaultContract` is the framework's
standard contract (`name`, `deps` required; `version`, `path`,
source/registry markers optional).

`checkRequired contract metadata` returns the list of contract-
required fields missing from `metadata` (empty list ⇒ valid).

`define { langName; contract; … }` produces a typed
`VendoringBuilder` spec for downstream composition.



#### Code-gen


`CodeGenBuilder` refines `BuilderSpec` with `generator` and
`languages` so multi-language generators (protoc, openapi-generator,
graphql-codegen) carry their target metadata in the type.

The `codeGen` smart constructor expands a single config record into
a fully-typed spec: per-language outputs, read-source / declare-tool
/ resolve-dependency / run-tool / transform-output / emit-descriptor
/ materialize-derivation operations.



#### Idl


`IdlBuilder` refines `CodeGenBuilder` with `idlFormat` and
`idlSource`, encoding "this generator is driven by an IDL document"
in the type.

`fromProtobuf { name; protos; languages; options?; languageConfigs?; }`
builds a fully-typed `IdlBuilder` spec for `protoc`. The default
language config covers the standard protoc backends; pass
`languageConfigs` to override or extend.



#### Capabilities


Typed capability vocabulary built on the `runtime.*` effect
algebra. The underlying datatypes (`CapabilitySchema`,
`CapabilityCategory`, `CapabilitySet`) live in
`mb.descriptions`; this ornament adds three things consumers
actually reach for:

- **Smart constructors** as terse aliases:
  `capabilities.capability { name; description?; params?; returns?; }`
  `capabilities.category { name; description?; capabilities?; }`
  `capabilities.set { categories?; custom?; }`

- **Built-in categories** as typed values addressable as
  `capabilities.builtins.{lifecycle,crud,streaming}`. Each is a
  fully-typed `CapabilityCategory`. Consumer extension goes
  through `H.ornament` on the closed kernel sum, not through
  string-keyed attrset merge.

- **Schema eliminator** `schema : CapabilitySchema → AttrSet`
  produces a JSON-Schema-shaped attrset suitable for MCP/API
  tooling. `setSchemas : CapabilitySet → AttrSet` flattens an
  entire set, attaching a `category` tag to each entry.



#### Protocol


Typed communication protocols over the closed kernel sums
`Transport` (TCP/Unix/Stdio) and `Serialization`
(JSON/Protobuf/Sexp/MsgPack). Both sums are defined in
`mb.descriptions` and re-exported here as
`protocol.Transport` / `protocol.Serialization`.

- **Smart constructor** `protocol.define { name; description?;
  transport; serialization; defaultPort?; portEnvVar?;
  capabilities; options?; }` proxies to
  `mb.operations.protocol` (eager structural validation against
  `ProtocolSpec.T`).

- **Built-in protocols** as typed values addressable as
  `protocol.builtins.{rpc,jsonRpc,dbus,grpc}`. Each carries a
  `CapabilitySet` drawn from `capabilities.builtins`.

- **`satisfies : ProtocolSpec → CapabilitySet → Bool`** is the
  capability cross-check (proxy to
  `mb.descriptions.runtime.protocolSatisfies`).

Consumer extension is through `H.ornament` on the kernel sums.
There is no `withTransports`/`withSerializations`/`withProtocols`
surface — extension via string-keyed attrset merge was a legacy
idiom and is intentionally absent.



#### Service


`define { name; description?; package; capabilities; protocols?; config?; }`
builds a typed `ServiceSpec` and attaches an `operations` field
holding the runtime-op program that materializes the service:

```
declareCapability(c1) … declareCapability(cN)   # one per category
declareProtocol(p1)   … declareProtocol(pM)     # one per protocol
declareService(svc)
materializeUnit(svc.name)
```

The eager compatibility check fires inside the underlying
`mb.operations.service` smart constructor — invalid services
cannot be constructed. `compatibility` and `descriptor` are
re-exported from `mb.descriptions.runtime` for consumer convenience.

`program` is a shortcut: pass either a service value or the
arguments to `define`, and receive an internalized builder program.



#### ReplServer


Typed REPL-server vocabulary built on the locked runtime.* algebra.

- **Smart constructor** `replServer.define { protocol; mode;
  registration?; port?; portEnvVar?; interface?; lifecycle?;
  enable?; shortLivedFlags?; extra?; }` proxies to
  `mb.operations.replServer`. Port and `portEnvVar` default from
  the protocol's `defaultPort`/`portEnvVar`. Registration defaults
  from `mode` via the inference rule
  `Foreground → ServiceSpec`, `Background → XDG`.
  Lifecycle defaults to `LongRunning`.

- **Closed-sum re-exports** for consumer ergonomics:
  `Mode = Foreground | Background`,
  `Registration = XDG | Global | ServiceSpec | None`,
  `Lifecycle = LongRunning | OneShot`.

- **Built-in protocols** as typed `ProtocolSpec` values:
  `protocols.{swank,nrepl,dap}`. Each carries a baseline
  `CapabilitySet` of `lifecycle` only; consumers extend via
  `capabilitySet { categories = [...] }`. The legacy string-keyed
  taxonomy (`universal`/`common`/`discovery`/...) is intentionally
  absent.

Registration backend names map to runtime conventions:
`XDG` → `$XDG_RUNTIME_DIR/repl/<protocol>/<name>.json`,
`Global` → `$XDG_RUNTIME_DIR/repl/<protocol>/shared/<name>.json`,
`ServiceSpec` → discovery via NixOS configuration,
`None` → no automatic registration.



#### Sandbox


Typed declarative sandbox profile. The profile is the single source
of truth; four enforcement backends — bubblewrap, Landlock, seccomp
BPF, and systemd hardening — consume the same declaration and
produce backend-specific configuration.

Three-layer defense:
  1. **bwrap**: mount namespace, PID namespace, seccomp stage-1.
  2. **Landlock**: path-based filesystem access (applied from inside
     the process post-init).
  3. **seccomp stage-2**: self-applied filter blocking `execve`
     post-init when the profile is sealed.

- **Smart constructor** `sandbox.define { readOnlyPaths?;
  readWritePaths?; tmpfs?; listenTcp?; connectTcp?; display?;
  stdio?; unixSockets?; allowExecve?; allowFork?; lifecycle?;
  daemonMode?; dns?; sourceAccess?; sourceWritePaths?;
  coordinationWritePaths?; storeAccess?; }` proxies to
  `mb.operations.sandboxProfile` (eager structural validation
  against `SandboxProfile.T`).

- **Built-in profiles** as typed `SandboxProfile` values:
  `profiles.sealed` (the empty default), `profiles.effectful`
  (sealed + execve + fork). Anything host- or workload-specific
  composes downstream.

- **Eliminators**:
  - `toBwrap : SandboxProfile → [String]` — bubblewrap argument
    list. DNS handling routes through `profile.dns` when present.
  - `toLandlock : SandboxProfile → LandlockProfile` — path-list +
    port-list view.
  - `toSeccomp : SandboxProfile → SeccompStage → Thunk Derivation` —
    BPF filter; stage `Bwrap` includes `processExec`, stage `Self`
    respects `allowExecve`.
  - `toSystemd : SandboxProfile → SystemdHardening` — directives
    suitable for `systemd.services.<name>.serviceConfig`.

- **Closed-sum re-exports**: `SeccompStage = Bwrap | Self`,
  `Lifecycle = LongRunning | OneShot`.

- **Combinators** in `sandbox.combinators`: `compose`, base
  profiles (`sealed`/`effectful`), network (`listen`/`connectTo`),
  filesystem (`readonly`/`readwrite`), execution
  (`allowExec`/`allowFork`), lifecycle (`daemon`), and a `defer`
  meta-combinator for two-pass composition. Each carries `{ sig;
  doc; impl }` metadata.

- **Seccomp compiler**: `syscallSets` exposes 12 generic syscall
  categories. `mkFilter`/`mkAllowlist`/`flattenPolicy` compose them
  into BPF filters via the bundled `gen-seccomp-bpf` tool. The
  compiler is a standalone C program (single source file) that
  reads a newline-separated allowlist and emits a BPF blob.



#### Transform


`transform` builds a typed `BuilderSpec` for a sequential
transformation pipeline. Each `step` is a `{ name; tool; args ?
[]; env ? {}; }` record carrying a tool (raw or pre-constructed
via `mb.operations.tool`). Tools are deduplicated and emitted as
`declareTool` operations; steps become `runTool` operations; the
`outputs` list expands to `transformOutput` operations.

The constructor wraps the `transform-output` effect of the new
framework — no new effect tags are introduced.



#### Oci-image


`OciImageBuilder` refines `BuilderSpec` with image metadata (layers,
entrypoint, cmd, env, exposedPorts, labels, architecture, os) so OCI
images carry their runtime contract in the type.

The `ociImage` smart constructor compiles a single config record into
a typed spec whose operations assemble a spec-conformant OCI image
layout (`oci-layout`, `index.json`, `blobs/sha256/*`) entirely at
build time: per-layer rootfs assembly and deterministic tar, then
config/manifest/index rendering in digest-chain order, a blob
self-check, scratch cleanup, and an `image.oci.tar` archive of the
layout — each as a named step so every fold renders the assembly
legibly.



### Library Helpers

#### Tool-env


`create { tools = [...] }` builds a typed `ToolEnvSpec` from a list
of raw `{ name; package }` records; each is wrapped via
`mb.operations.tool` so `package` is carried as a typed
`Thunk Derivation`.

`merge a b` composes two envs — `b` overrides any `a` tool whose
`name` matches. `empty` is the identity.



#### Toolchain


`select` resolves an implementation from prioritized hint evaluators
and returns a typed `ToolchainSelection`. An explicit override
short-circuits the hint pipeline.

`mkManifest` builds a typed `ToolchainManifest` whose `matrix` maps
each spec name to its sanitized, default-applied field set.
Builder-specific extension fields pass through unchanged.



#### Passthru


`create` builds a typed `PassthruSpec` from `{ langName; baseName;
baseDeps; extensions ? {} }`. The spec is the canonical structured
representation of language-tagged package metadata.

Hash stability invariant: a `PassthruSpec` depends only on its
constructor arguments. Two `create` calls with equal inputs produce
equal specs; no ambient state, no derivation references at the
spec level.



#### Bundled


`create` builds a typed `BundledSpec` from `{ langName; packageName;
extraAttrs ? {} }`. The typed record's constructor tag
(`_con = "MetaBuilderBundled"`) is the discriminator that
distinguishes bundled descriptors from anything else; callers
can check membership via `isBundled`.



#### Dashboard


`mkMetrics` produces a typed `sanitize` projection that pulls
`lockHash` and `toolchainSpec` out of raw lock-file metrics, filters
the toolchain spec by an optional whitelist of fields, and returns
a flattened attr-set of the remaining metric fields.

`mkWorkspaceSummary` produces a typed `summarize` that walks a
workspace member map, sanitizes each member, discovers the first
non-null `lockHash`, optionally collects stats, and returns the
summary record.



#### ContentAddress


`contentAddress drv` returns `drv` with floating content-addressing: its
output store path is the realised NAR content hash, not the input hash.

```nix
final = contentAddress wrappedPackage;
```

Wins over input-addressed caching: early cutoff (unchanged output stops a
rebuild cascade) and cross-machine sharing (a realisation built on one
machine substitutes on another, given nix >= 2.35 + harmonia >= 3.1.0).

Only wrap byte-reproducible derivations (`nix build --rebuild`). A
non-reproducible CA drv flaps its output hash and mismatches across
machines. Per-derivation opt-in; never `contentAddressedByDefault`.



## Additional pages (including unstable internal surfaces)

### Examples


metaBuilder examples are builder definitions with source
fixtures, self-documentation, tests, materialization plans, and
generated artifacts.

- [Node service example](/metaBuilder/examples/node-service) - Guided Node service builder tour: runnable package, HTTP service descriptor, runtime unit, dependency graph, and materialization plan.
- [C code generation example](/metaBuilder/examples/c-codegen) - Guided C codegen builder tour: schema input, generated C sources, static library, CLI, descriptors, dependency graph, and materialization plan.
- [Bridge example](/metaBuilder/examples/bridge) - Relates the shipped builder kinds — Node service, C code generation, OCI image, and IDL — through kernel-checked ornament, effect, and list-computation theorems.
- [IDL example](/metaBuilder/examples/idl) - IDL example: multi-language protobuf code generation via the IdlBuilder ornament and internalized program interpreters.
- [OCI image example](/metaBuilder/examples/oci-image) - Guided OCI image builder tour: busybox layer, digest-chain assembly steps, image descriptor, smoke-test evidence, and materialization plan.


### Manual


metaBuilder is a library for writing builders as typed descriptions. A builder
names the structure of a build. That structure includes inputs, tools,
operations, outputs, runtime shape, and evidence, so the same build can be
validated, inspected, explained, and materialized.

Use this manual when you want to design or consume a metaBuilder builder. It
keeps the focus on the public model. You will see which values you write, which
views you ask for, and how those views make a builder easier to understand.

## Path Through The Manual

Start with [Introduction](/metaBuilder/manual/introduction) for the overall
model. Then read [Getting Started](/metaBuilder/manual/getting-started) for the
smallest complete flow.

The middle chapters explain the reusable pieces.

- [Builder Specs](/metaBuilder/manual/builder-specs)
- [Operations](/metaBuilder/manual/operations)
- [Programs And Views](/metaBuilder/manual/programs-and-views)
- [Designing Builder Surfaces](/metaBuilder/manual/designing-builder-surfaces)

The final chapters explain how to return useful artifacts and grow a small
builder into a production builder.

- [Outputs, Evidence, And Runtime Artifacts](/metaBuilder/manual/outputs-evidence-runtime)
- [Materialization Model](/metaBuilder/manual/materialization-model)
- [Authoring Production Builders](/metaBuilder/manual/authoring-production-builders)

For complete guided examples, read the examples section after the manual.


### Theory


The theory section explains the ideas behind metaBuilder. It is a companion to
the manual and not a prerequisite for using the library.

The practical claim is short. A build can be written as typed data, that data
can be read as a program, and the program can be interpreted in more than one
way. The theory chapters make each part of that claim precise.

A builder is a typed description rather than a function. The description becomes
a program over a fixed signature of build-time and runtime operations. Domain
builders refine the description with extra data through ornaments, and a typed
forget map projects them back to the shared shape without losing the program.
Every view is an interpretation of that one program.

- [Builders As Descriptions](/metaBuilder/theory/builders-as-descriptions)
- [Internalized Programs](/metaBuilder/theory/internalized-programs)
- [Ornaments And Domain Surfaces](/metaBuilder/theory/ornaments-and-domain-surfaces)
- [Interpretation And Views](/metaBuilder/theory/interpretation-and-views)
- [Evidence, Descriptors, And Runtime Structure](/metaBuilder/theory/evidence-descriptors-runtime)

Read this section when you want to understand why metaBuilder can support one
build with many views.


# nix-effects

## Manual

### Guide

#### Introduction


Nix libraries often grow into small languages. A user declares entities,
reusable aspects, target classes, dependencies, and policies; a pipeline
turns that declarative graph into concrete Nix modules, files, packages,
or checks. Without a shared structure, every layer writes its own walker:
one for validation, one for documentation, one for dependency ordering,
one for rendering, one for diagnostics.

nix-effects is a typed, description-backed programming substrate for
pure Nix. Effects are the execution model; generated descriptions are
the shared structure; the kernel checks boundaries; generic tools,
diagnostics, proofs, and ornaments reuse the same shape. Everything runs
at `nix eval` time, before anything builds or ships.

The unusual part is that the kernel is hosted inside Nix evaluation
itself. Nix normally gives libraries functions, attrsets, assertions,
and module option types. nix-effects adds typed descriptions that generic
programs can inspect. Validation is therefore not a hand-written walker:
it is one interpretation of a type description, next to schemas,
documentation, dependency extraction, and DSL interpretation.

The type layer is backed by a Martin-Löf dependent type checker in
`src/tc/` with Pi, Sigma, identity types with J, explicit universe
levels, HOAS elaboration, generated datatypes, and verified extraction
of plain Nix functions from proof terms. Descriptions provide reusable
datatype shapes, so domain DSLs can be validated, interpreted,
documented, transformed, or extracted by generic tools instead of
one-off traversals.
The bidirectional checker sends `typeCheck` effects carrying a
field-path context, so type errors in deeply nested terms come back
localized to the field that broke.

## What it looks like

A target class is one of a small set of strings. In nix-effects, that is
a refinement type:

```nix
let
  inherit (fx.types) String refined;

  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);
in {
  ok  = TargetClass.check "module";   # true
  bad = TargetClass.check "fleet";    # false
}
```

Behind the scenes, `.check` runs the MLTT kernel's decision procedure
for the base type, then evaluates the refinement predicate. For a
refinement type like `TargetClass`, this is fast: the kernel confirms a
string, the guard confirms membership in the known target classes. You
write normal Nix and the kernel runs behind the scenes.

But checking individual values is only the starting point. The same
kernel-backed structure supports derived validation for compound shapes
and can also verify entire functions, then extract them as ordinary Nix
functions.

## Verified functions over real data

Write an implementation in HOAS (Higher-Order Abstract Syntax), the
kernel type-checks it, and `v.verify` extracts a callable Nix function.

Here is a small aspect declaration predicate. The kernel verifies a
function that takes a record with `name`, `target`, and `requires`
fields, then checks that the target is one of the classes this pipeline
knows how to render. The check uses string comparison inside the kernel
— `strEq` is a kernel primitive, not a Nix-level hack.

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  AspectDecl = H.record [
    { name = "name";     type = H.string; }
    { name = "target";   type = H.string; }
    { name = "requires"; type = H.listOf H.string; }
  ];

  targets =
    H.cons H.string (v.str "module")
      (H.cons H.string (v.str "file")
        (H.cons H.string (v.str "package")
          (H.cons H.string (v.str "check") (H.nil H.string))));

  validateAspect = v.verify (H.forall "a" AspectDecl (_: H.bool))
    (v.fn "a" AspectDecl (a:
      v.strElem (v.field AspectDecl "target" a) targets));
in {
  ok = validateAspect {
    name = "workspace-shell";
    target = "module";
    requires = [ "toolchain" ];
  };   # true

  bad = validateAspect {
    name = "workspace-aspect";
    target = "fleet";
    requires = [ ];
  };   # false
}
```

`validateAspect` is a plain Nix function. You call it with a plain Nix
attrset. But the implementation was verified by the MLTT kernel before
extraction — the kernel confirmed that the function matches its type
(`AspectDecl → Bool`), that field projections are well-typed, and that
the string membership check composes correctly. If you made a type error
in the implementation — say, compared a `Bool` where a `String` was
expected — the kernel would reject it at `nix eval` time.

The record type (`H.record`) elaborates to nested Sigma in the kernel.
`v.field` desugars to the right chain of first/second projections.
`v.strEq` is a kernel primitive that reduces `strEq "foo" "foo"` to
`true` during normalization. `v.strElem` folds over a list with `strEq`.
None of this is Nix-level string comparison — it's computation inside
the proof checker.

## Proofs as programs

The same kernel that verifies functions also checks mathematical
proofs. Both are the same judgment — `Γ ⊢ t : T` — applied
differently. A verified function proves that an implementation inhabits
its type. An equality proof proves that two expressions reduce to the
same normal form.

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  # Verified addition: Nat → Nat → Nat by structural recursion
  add = v.verify (H.forall "m" H.nat (_: H.forall "n" H.nat (_: H.nat)))
    (v.fn "m" H.nat (m: v.fn "n" H.nat (n:
      v.match H.nat m {
        zero = n;
        succ = _k: ih: H.succ ih;
      })));

in {
  five = add 2 3;     # 5

  # Prove 3 + 5 = 8: the kernel normalizes both sides, Refl witnesses equality
  proof = (H.checkHoas (H.eq H.nat (add (H.natLit 3) (H.natLit 5)) (H.natLit 8))
                       H.refl).tag == "refl";    # true
}
```

The `add` function is extracted exactly like `validateAspect` — write in
HOAS, kernel checks, extract a Nix function. The equality proof goes
one step further: the kernel normalizes `add(3, 5)` by running the
structural recursion, arrives at `8`, and confirms `Refl` witnesses
`8 = 8`. This is computational proof — the kernel computes the answer
and verifies that computation agrees with the claim.

## The effect system

The "effects" in nix-effects are algebraic effects implemented via a
freer monad (Kiselyov & Ishii 2015). A computation is a tree of
effects with continuations. A handler walks the tree, interpreting
each effect:

```nix
let
  inherit (fx) pure bind run;
  inherit (fx.effects) get put;

  # Read state, double it, write it back
  doubleState = bind get (s: bind (put (s * 2)) (_: pure s));

  result = run doubleState fx.effects.state.handler 21;
  # result.value = 21, result.state = 42
in result
```

This matters for type checking because it separates *what* to check
from *how* to report. When `DepRecord.validate` finds a type error,
it sends a `typeCheck` effect. The handler decides the policy:

- **Strict** — abort on the first error
- **Collecting** — gather all errors, keep checking
- **Logging** — record every check, pass or fail

Same validation logic, different handler. The checker reports through
the same effect substrate, so validation policy composes with the rest
of the effect system.

## The verification spectrum

Not everything needs proofs. nix-effects supports four levels of
assurance, and you pick the one that fits:

**Level 1 — Contract.** Write normal Nix. Types check values via
`.check`. The kernel runs behind the scenes. Zero cost to adopt.

```nix
TargetClass = refined "TargetClass" String
  (x: builtins.elem x [ "module" "file" "package" "check" ]);
TargetClass.check "module"    # true
```

**Level 2 — Boundary.** Data is checked by the kernel at module
interfaces. Every type has a `kernelType` and `.check` is derived from
the kernel's `decide` procedure. This is what all built-in types do by
default — `(ListOf String).check ["a" "b"]` elaborates the list into a
kernel term and type-checks it.

**Level 3 — Property.** Write proof terms in HOAS that the kernel
verifies. Prove that `3 + 5 = 8`, or that double negation on booleans
is the identity, or that `append([1,2], [3]) = [1,2,3]`.

**Level 4 — Full.** The implementation IS the proof term. Write in
HOAS, the kernel verifies, `extract` produces a Nix function correct by
construction. The `validateAspect` example above is Level 4 — the kernel
verified the validator before extracting it as a callable function.

Most users will stay at levels 1 and 2. The kernel is there when you
need it. With record types and string comparison now in the kernel,
Level 4 handles real-world validation — not just arithmetic on natural
numbers.

## How this document is organized

The rest of the guide builds up from here:

- **[Getting Started](/nix-effects/guide/getting-started)** sets up the library and
  shows the first type, effect, and generated datatype.
- **[Effects and Handlers](/nix-effects/guide/effects-and-handlers)** explains the
  execution model: computations send operations, handlers choose policy.
- **[Typed Validation](/nix-effects/guide/typed-validation)** covers primitive,
  refined, structured, and dependent validation boundaries.
- **[Generated Datatypes](/nix-effects/guide/generated-datatypes)** introduces
  description-backed data as the shared structure.
- **[Generic Programming](/nix-effects/guide/generic-programming)** shows how schemas,
  dependency graphs, diagnostics, and views derive from that structure.
- **[Ornaments and Description-Backed Data](/nix-effects/guide/ornaments)** refines
  generated shapes while preserving forgetful maps.
- **[Proof Guide](/nix-effects/guide/proof-guide)** builds proofs and verified
  implementations from kernel-checked HOAS terms.
- **[Theory](/nix-effects/concepts/theory)** explains the ideas behind the model.
- The internals chapters document the trampoline, architecture, kernel
  implementation, and formal specification for contributors.

## References

1. Martin-Lof, P. (1984). *Intuitionistic Type Theory*. Bibliopolis.

2. Kiselyov, O., & Ishii, H. (2015). *Freer Monads, More Extensible
   Effects*. Haskell Symposium 2015.
   [[pdf](https://okmij.org/ftp/Haskell/extensible/more.pdf)]

3. Plotkin, G., & Pretnar, M. (2009). *Handlers of Algebraic Effects*.
   ESOP 2009.
   [[doi](https://doi.org/10.1007/978-3-642-00590-9_7)]

4. Findler, R., & Felleisen, M. (2002). *Contracts for Higher-Order
   Functions*. ICFP 2002.
   [[doi](https://doi.org/10.1145/581478.581484)]


#### Getting Started


## Installation

Add nix-effects as a flake input:

```nix
{
  inputs.nix-effects.url = "github:kleisli-io/nix-effects";

  outputs = { nix-effects, nixpkgs, ... }:
    let
      fx = nix-effects.lib;
    in {
      # fx.types, fx.run, fx.send, fx.bind, fx.effects, fx.stream ...
    };
}

```

Or import directly without flakes:

```nix
let fx = import ./path/to/nix-effects { lib = nixpkgs.lib; };
in ...

```

## Your first type

Define a type with `fx.types.refined`:

```nix
let
  inherit (fx.types) String refined;

  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);
in {
  # Kernel decision procedure — fast boolean check
  ok  = TargetClass.check "module";   # true
  bad = TargetClass.check "fleet";    # false

  # Effectful validate — runs through the trampoline, produces blame context
  result = fx.run (TargetClass.validate "fleet")
    fx.effects.typecheck.collecting [];
  # result.state = [ { context = "TargetClass"; ... } ]
}

```

## Your first dependent type

One field's type depends on another field's value — this is a genuine
dependent type, checked by the MLTT proof-checking kernel:

```nix
let
  inherit (fx.types) Bool String ListOf DepRecord refined;

  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);

  AspectDecl = DepRecord [
    { name = "generated"; type = Bool; }
    { name = "target"; type = self:
        if self.generated then TargetClass else String; }
    { name = "requires"; type = _: ListOf String; }
  ];
in {
  ok = AspectDecl.checkFlat {
    generated = true;
    target = "module";
    requires = [ "toolchain" ];
  };  # true

  bad = AspectDecl.checkFlat {
    generated = true;
    target = "fleet";
    requires = [ ];
  };  # false
}

```

## Your first effect

Write a computation, then choose the handler:

```nix
let
  inherit (fx) pure bind run;
  inherit (fx.effects) get put;

  # Double the state
  doubleState = bind get (s: bind (put (s * 2)) (_: pure s));

  result = run doubleState fx.effects.state.handler 21;
  # result.value = 21  (old state returned)
  # result.state = 42  (state doubled)
in result

```

## A first generated datatype

Generated datatypes are the next step after validation. They give a DSL
its constructors, its type, and reusable structural metadata:

```nix
let
  H = fx.types.hoas;

  Aspect = H.datatype "Aspect" [
    (H.con "aspect" [
      (H.field "name" H.string)
      (H.field "target" H.string)
      (H.field "requires" (H.listOf H.string))
    ])
  ];
in Aspect
```

The generated `Aspect` shape can be checked, viewed, reviewed,
documented, traversed for dependencies, interpreted by handlers, and
ornamented with derived fields.

## Running checks

The repo includes runnable tests and examples:

```bash
git clone https://github.com/kleisli-io/nix-effects
cd nix-effects

# Run all tests
nix flake check

```

## The kernel behind every type

Every `.check` call runs the MLTT type-checking kernel. When you write
`TargetClass.check "module"`, the kernel elaborates `"module"` into a
term, type-checks it, and returns a boolean. This is not a separate
system — it is what `.check` does.

You can also write verified implementations using HOAS combinators:

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  # Write a function in HOAS, kernel type-checks it, extract as Nix function
  succ = v.verify (H.forall "x" H.nat (_: H.nat))
                   (v.fn "x" H.nat (x: H.succ x));
in
  succ 5    # 6 — a certified Nix function
```

The kernel checks the implementation against its type at `nix eval` time.
If the types don't match, you get an error before anything builds.
See the [Kernel Architecture](/nix-effects/internals/kernel-architecture)
chapter for the full pipeline.

## What's in the box

The `fx` attrset is the entire public API:

| Namespace | Contents |
|-----------|---------|
| `fx.pure`, `fx.bind`, `fx.send`, `fx.map`, `fx.seq` | Freer monad kernel |
| `fx.run`, `fx.handle` | Trampoline interpreter |
| `fx.adapt`, `fx.adaptHandlers` | Handler composition |
| `fx.types.*` | Type system (primitives, constructors, dependent, refinement, universe) |
| `fx.types.hoas` | HOAS surface combinators for the kernel |
| `fx.types.elaborateType`, etc. | Elaboration bridge: fx.types ↔ kernel |
| `fx.types.verified` | Convenience combinators for writing verified implementations |
| `fx.effects.*` | Built-in effects (state, error, reader, writer, acc, choice, conditions, typecheck, linear) |
| `fx.stream.*` | Effectful lazy sequences |


#### Effects and Handlers


nix-effects separates program intent from execution policy. A program
sends operations such as "read state", "write state", or "report a type
error". A handler decides what those operations mean.

That split is the execution model for the rest of the library. Typed
validation, diagnostics, streams, resource tracking, and the checker all
use the same effect substrate. The validator does not decide whether an
error aborts immediately or gets collected with the next ten errors. The
handler decides.

## Computations

A computation is either finished or waiting for a handler:

```nix
Pure value
Impure effect continuation
```

The public constructors are `pure`, `send`, and `bind`:

```nix
let
  inherit (fx) pure bind send;
in
  bind (send "get" null) (state:
    bind (send "put" (state + 1)) (_:
      pure state))
```

Most code uses effect modules rather than raw `send`:

```nix
let
  inherit (fx) pure bind run;
  inherit (fx.effects) state;

  increment =
    bind state.get (n:
      bind (state.put (n + 1)) (_:
        pure n));
in
  run increment state.handler 41
```

The result contains the returned value and final handler state:

```nix
{ value = 41; state = 42; }
```

## Handlers are policy

A handler is an attrset of operations. Each operation receives the
effect parameter, the current handler state, and the continuation
protocol. It can resume the computation or abort it:

```nix
{
  get = { param, state }: {
    resume = state;
    inherit state;
  };

  put = { param, state }: {
    resume = null;
    state = param;
  };
}
```

The computation above never mentions how state is represented. It only
sends `get` and `put`. That is why the same validation logic can run
under a strict handler in CI, a collecting handler in a documentation
test, or a logging handler in a development shell.

## Type checking as an effect

Validation uses the same shape. A type can expose both:

- `.check value` for a fast boolean boundary.
- `.validate value` for an effectful check with diagnostics.

```nix
let
  inherit (fx.types) String refined;
  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);
in
  fx.run (TargetClass.validate "fleet")
    fx.effects.typecheck.collecting []
```

The type sends a `typeCheck` request with context. The handler turns
that request into an error list, a thrown exception, or a trace. The
type does not need separate implementations for each policy.

## Composition

Handlers compose because computations are ordinary values. `adapt` and
`adaptHandlers` let a local computation run under a different handler
view without rewriting the computation itself. Streams use the same
substrate to request the next value lazily. Linear resources use it to
count consumption. The kernel uses it to report type errors without
placing diagnostics inside the trusted evaluator.

The implementation details live in the
[Trampoline](/nix-effects/internals/trampoline) chapter. For day-to-day
use, the rule is simple: write computations in
terms of operations, then choose the handler that matches the boundary
where the computation runs.


#### Typed Validation


Typed validation is the first user-facing layer built on the effect
model. A type describes the values a boundary accepts. The same type can
answer a fast yes/no question or produce structured diagnostics through
a handler.

The point is not only that validation exists. In nix-effects, validation
is derived from the type description. Users write the shape and any
domain refinements; they do not write a recursive validator for every
record, list, variant, or generated datatype. That derive-style
capability is hosted inside Nix itself, not delegated to an external
schema engine or macro system.

This chapter uses value-level types. Later chapters show how generated
datatypes carry reusable descriptions that the same checker, diagnostic
tools, interpreters, and generic derivations consume.

## Primitive and refined types

Primitive types wrap Nix value predicates with kernel-backed type
information:

```nix
let inherit (fx.types) Int String Bool;
in {
  okInt = Int.check 3;
  okString = String.check "aspect";
  badBool = Bool.check "true";
}
```

Refinement types narrow an existing type with a predicate:

```nix
let
  inherit (fx.types) String refined;
  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);
in {
  ok = TargetClass.check "module";
  bad = TargetClass.check "fleet";
}
```

Use refinements for named boundary conditions: target classes,
non-empty names, supported dialects, allowed protocol versions, and
similar concrete constraints.

## Structured values

Records and lists compose types into larger boundaries:

```nix
let
  inherit (fx.types) Record String ListOf refined;
  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);

  AspectDecl = Record {
    name = String;
    target = TargetClass;
    requires = ListOf String;
  };
in
  AspectDecl.check {
    name = "workspace-shell";
    target = "module";
    requires = [ "toolchain" ];
  }
```

The check is structural and derived. Each field is checked with its own
type, and the composed type preserves enough context for diagnostics to
point at the field that failed. Adding another field or nesting another
record changes the type description; the validator follows automatically.

## Dependent records

Some fields depend on earlier fields. `DepRecord` evaluates field types
left to right, so later field types can inspect earlier values:

```nix
let
  inherit (fx.types) Bool String ListOf DepRecord refined;

  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);

  AspectDecl = DepRecord [
    { name = "generated"; type = Bool; }
    { name = "target"; type = self:
        if self.generated then TargetClass else String; }
    { name = "requires"; type = _: ListOf String; }
  ];
in {
  ok = AspectDecl.checkFlat {
    generated = true;
    target = "module";
    requires = [ "toolchain" ];
  };

  bad = AspectDecl.checkFlat {
    generated = true;
    target = "fleet";
    requires = [ ];
  };
}
```

The dependent field type is never evaluated until the fields it depends
on have passed. That ordering keeps diagnostics local and avoids running
domain logic on malformed input.

## Check vs validate

Use `.check` when you need a boolean:

```nix
AspectDecl.checkFlat value
```

Use `.validate` when the caller needs diagnostics:

```nix
fx.run (AspectDecl.validate value)
  fx.effects.typecheck.collecting []
```

The validation path reports through effects, so choosing a handler
chooses policy. A CLI can collect every field error. CI can abort on the
first fatal error. Tests can inspect the emitted diagnostics as data.

This separates two concerns that are often mixed together in Nix DSLs:
the type describes the accepted shape, while the handler decides whether
a failed check becomes an exception, a list of diagnostics, or a trace.

## Where the kernel fits

Every public type carries a kernel representation. Primitive and
first-order types can use fast decidable checks. Higher-order and proof
oriented boundaries use HOAS terms that the kernel checks directly.

This is one model, not two. Value-level validation is the practical
entry point; generated datatypes and verified functions reuse the same
kernel-backed structure when the boundary needs more evidence than a
predicate can provide.


#### Generated Datatypes


Generated datatypes make structure explicit. A datatype is not only a
constructor API; it also carries the description and metadata that the
kernel, generic walkers, diagnostics, schemas, dependency extraction,
and ornaments reuse.

Use generated datatypes when a domain value should be more than an
untyped attrset. The generated value has constructors for building data,
a type for checking data, and public structural evidence for tools.

## A first datatype

```nix
let
  H = fx.types.hoas;

  Aspect = H.datatype "Aspect" [
    (H.con "aspect" [
      (H.field "name" H.string)
      (H.field "target" H.string)
      (H.field "requires" (H.listOf H.string))
    ])
  ];
in Aspect
```

The generated `Aspect` object exposes:

- `Aspect.D` — the description used by the kernel.
- `Aspect.T` — the generated type.
- `Aspect.aspect` — the constructor.
- `_dtypeMeta` — constructor and field metadata.

The description is the important part. It is the common shape that lets
multiple consumers agree on what an aspect declaration is.

## View and review

Application code usually works with named constructor records:

```nix
let
  G = fx.types.generic;

  aspect = G.value.review Aspect.T {
    _con = "aspect";
    name = "workspace-shell";
    target = "module";
    requires = [ "toolchain" ];
  };
in
  G.value.view Aspect.T aspect
```

`review` turns a constructor record into the generated value. `view`
turns the generated value back into a constructor record. This is the
bridge between ergonomic Nix data and the description-backed
representation the kernel can inspect.

## Generated families

The datatype layer supports several shapes:

- `datatype` for ordinary generated datatypes.
- `datatypeP` when constructors are parameterized.
- `datatypeI` when the family is indexed.
- `datatypePI` when both parameters and indices are needed.

The more indexed the family, the more precisely the type can state what
the value means. The public model is still the same: a description, a
generated type, constructors, and metadata.

## Stack-safe elaboration

Generated constructor trees can be large. nix-effects elaborates them
through the same stack-safe machinery used by the effect interpreter and
kernel normalizer. Deep values should remain ordinary data, not a reason
to avoid the generated layer.

That is why generated datatypes are suitable for infrastructure DSLs:
they give the checker real structure without moving the user out of
pure Nix evaluation.

## What comes next

The next chapter shows what the metadata buys. Once a datatype carries a
description, generic tools can derive schemas, dependency graphs,
diagnostics, and ornaments without each tool inventing its own walker.


#### Generic Programming


Generic programming is the payoff for description-backed data. Once a
datatype exposes its constructors, fields, and description, tools can
consume that structure directly instead of maintaining hand-written
walkers for every domain shape.

The same generated datatype can feed a checker, a documentation surface,
a dependency extractor, a schema generator, and an ornament. Those tools
agree because they read the same metadata.

This is the consequence of hosting the typed description language inside
Nix. There is no separate schema file to keep synchronized with the DSL,
and no per-datatype validator to write. A new user datatype participates
because the generic programs consume the levitated description, not a
closed set of special cases known in advance.

## Inspecting metadata

```nix
let
  G = fx.types.generic;
  info = G.datatype.datatypeInfo Aspect.T;
in {
  name = info.name;
  constructors = map (c: c.name) info.constructors;
}
```

`datatypeInfo` is the stable entry point for generated datatype
metadata. It returns the public structure: datatype name, constructors,
field names, field types, and description data needed by derivations.

## Deriving descriptors

`deriveDescriptor` turns datatype metadata into a neutral structural
description suitable for tools that do not want to depend on the HOAS
representation directly:

```nix
let
  G = fx.types.generic;
in
  G.derive.deriveDescriptor Aspect.T
```

A descriptor is not a second source of truth. It is a view of the
datatype's existing structure.

## Deriving schemas

Schema derivation uses the same fields and constructor tags:

```nix
G.derive.deriveSchema Aspect.T
```

Use this for external validation surfaces, generated documentation, or
tooling that needs to explain the shape to systems outside the kernel.
The schema follows the datatype; changing the datatype changes the
derived schema.

## Deriving dependencies

Dependency extraction is another consumer of the same shape:

```nix
G.derive.deriveDeps Aspect.T aspect
```

This is useful when a domain value references other values by name or
path. For an aspect declaration, the `requires` field can become the
dependency edge list for a topological interpreter. The generic walker
handles traversal; domain-specific metadata decides which fields count
as references.

## Diagnostics from shape

Structured diagnostics become easier when every field has a stable path.
The validator can report:

```nix
[ "constructors" "aspect" "fields" "requires" 0 ]
```

instead of a string-only error. That path is reusable in CLI output,
HTML documentation, editor integrations, and test assertions.

The path is not guessed by a custom recursive function. It is produced
by the same generic descent that reads constructor and field metadata.

## Avoid ad hoc walkers

The design rule is direct: if a tool needs to traverse a generated
datatype, start from `datatypeInfo`, `view`, `review`, and the derive
helpers. Do not duplicate the datatype's shape in a separate hand-written
walker. The description is already the shared structure.

The ornaments chapter builds on this. An ornament refines one generated
shape into another while preserving a forgetful map, and functional
ornaments add a canonical way to rebuild the enriched value.


#### Ornaments and Description-Backed Data


Generated datatypes in nix-effects are description-backed. A datatype is
not only a bundle of constructors; it also carries a `Desc` tree and
metadata that generic tools can inspect. That is what makes the same
datatype usable by the checker, value walkers, schema derivation,
dependency extraction, and ornaments.

An ornament refines one generated datatype into another while preserving a
forgetful map back to the base datatype. Use it when one layer needs more
information than another layer, but the enriched value should still be
usable wherever the base value was expected.

## Description-backed datatypes

Start with an ordinary generated datatype:

```nix
let
  fx = import ./nix/nix-effects {};
  H = fx.types.hoas;
  G = fx.types.generic;

  Aspect = H.datatype "Aspect" [
    (H.con "aspect" [
      (H.field "name" H.string)
      (H.field "target" H.string)
      (H.field "requires" (H.listOf H.string))
    ])
  ];
in Aspect
```

`Aspect` exposes:

- `Aspect.D`: the description used by the kernel.
- `Aspect.T`: the generated type.
- `Aspect.aspect`: the constructor.
- `_dtypeMeta`: constructor and field metadata used by generic tools.

The generic layer is the usual interface for description-backed
programming:

```nix
let
  info = G.datatype.datatypeInfo Aspect.T;
  value = G.value.review Aspect.T {
    _con = "aspect";
    name = "workspace-shell";
    target = "module";
    requires = [ "toolchain" ];
  };
in {
  constructors = map (c: c.name) info.constructors;
  roundtrip = G.value.view Aspect.T value;
}
```

`review` turns a constructor record into a HOAS value. `view` turns the
HOAS value back into a named constructor record. Derivation helpers such
as `G.derive.deriveDescriptor`, `G.derive.deriveSchema`, and
`G.derive.deriveDeps` consume the same metadata.

## Plain ornaments

A plain ornament adds fields while retaining enough structure to forget
back to the base datatype:

```nix
let
  ResolvedAspect = G.ornaments.ornament Aspect {
    name = "ResolvedAspect";
    constructors.aspect.fields = [
      { keep = "name"; }
      { keep = "target"; }
      { keep = "requires"; }
      { insert = "resolvedPath"; type = H.string; }
    ];
  };

  resolved = G.value.review ResolvedAspect.T {
    _con = "aspect";
    name = "workspace-shell";
    target = "module";
    requires = [ "toolchain" ];
    resolvedPath = "modules/workspace-shell.nix";
  };
in G.value.view Aspect.T (G.ornaments.forget ResolvedAspect resolved)
```

The result is:

```nix
{
  _con = "aspect";
  name = "workspace-shell";
  target = "module";
  requires = [ "toolchain" ];
}
```

The important property is one-way. Many resolved aspects may forget to the
same aspect. The ornament says how to drop the inserted structure without
changing the base shape.

Plain ornaments are useful when the enriched value already exists. They
give you checked forgetful maps, composition, and pullback transport:

```nix
G.ornaments.forget ResolvedAspect resolved
G.ornaments.compose Outer Inner
G.ornaments.pullback ResolvedAspect baseFunction resolved
```

## Functional ornaments

A functional ornament adds the forward direction: a section of the
forgetful map.

```nix
section : base -> ornamented
forget (section x) = x
```

In the generic API, build a functional ornament from a base datatype, an
ornament spec, and explicit synthesis functions for inserted fields:

```nix
let
  ResolvedAspect = G.ornaments.functional {
    base = Aspect;
    spec = {
      name = "ResolvedAspect";
      constructors.aspect.fields = [
        { keep = "name"; }
        { keep = "target"; }
        { keep = "requires"; }
        { insert = "resolvedPath"; type = H.string; }
      ];
    };
    synth.constructors.aspect.fields.resolvedPath =
      ctx: "modules/${ctx.baseRecord.name}.nix";
  };

  aspect = G.value.review Aspect.T {
    _con = "aspect";
    name = "workspace-shell";
    target = "module";
    requires = [ "toolchain" ];
  };

  resolved = G.ornaments.build ResolvedAspect aspect;
in {
  enriched = G.value.view ResolvedAspect.meta.ornamented.T resolved;
  forgotten = G.value.view Aspect.T (G.ornaments.forget ResolvedAspect resolved);
}
```

The enriched record contains the synthesized resolvedPath:

```nix
{
  _con = "aspect";
  name = "workspace-shell";
  target = "module";
  requires = [ "toolchain" ];
  resolvedPath = "modules/workspace-shell.nix";
}
```

The forgotten record is the original aspect. This gives a practical
workflow: construct the small base value first, then let the functional
ornament add canonical metadata.

## Composing enrichments

Functional ornaments compose when the outer ornament starts from the
inner ornament's generated datatype:

```nix
let
  MaterializedAspect = G.ornaments.functional {
    base = ResolvedAspect.meta.ornamented;
    spec = {
      name = "MaterializedAspect";
      constructors.aspect.fields = [
        { keep = "name"; }
        { keep = "target"; }
        { keep = "requires"; }
        { keep = "resolvedPath"; }
        { insert = "order"; type = H.nat; }
      ];
    };
    synth.constructors.aspect.fields.order = _ctx: 1;
  };

  Materialized = G.ornaments.composeFunctional MaterializedAspect ResolvedAspect;
in G.ornaments.build Materialized aspect
```

The composed section builds the final enriched value directly from the
base aspect. Forgetting the result through the composed ornament returns
the base aspect.

## Lifting producers and transforms

Producer lifting runs a base producer, then enriches its output through
the functional section:

```nix
let
  makeAspect =
    H.ann
      (H.lam "aspect" Aspect.T (_:
        G.value.review Aspect.T {
          _con = "aspect";
          name = "workspace-shell";
          target = "module";
          requires = [ "toolchain" ];
        }))
      (H.forall "_" Aspect.T (_: Aspect.T));

  lifted = G.ornaments.liftProducer Materialized makeAspect aspect;
in G.value.view MaterializedAspect.meta.ornamented.T lifted
```

The base function still only knows about `Aspect`. The lifted producer
returns the canonical materialized aspect. Forgetting the lifted result gives
the base producer's result.

Transform lifting is similar, but starts from an ornamented input:

```nix
G.ornaments.liftTransform {
  input = ResolvedAspect;
  output = MaterializedAspect;
  fn = baseTransform;
} resolved
```

The input is forgotten to the base, `fn` runs on the base value, and the
output section rebuilds the canonical enriched result.

## Obligations and diagnostics

Inserted fields must have a builder, a declared measure, or an explicit
proof builder. Validation is total and returns structured diagnostics:

```nix
G.ornaments.validateFunctional {
  base = Aspect;
  spec = {
    name = "BrokenResolvedAspect";
    constructors.aspect.fields = [
      { keep = "name"; }
      { keep = "target"; }
      { keep = "requires"; }
      { insert = "resolvedPath"; type = H.string; }
    ];
  };
  synth = {};
}
```

The diagnostic identifies the missing field builder:

```nix
{
  ok = false;
  diagnostics = [{
    code = "functional.missing-builder";
    path = [ "functional" "constructors" "aspect" "fields" "resolvedPath" ];
    message = "inserted field needs builder";
    severity = "error";
  }];
}
```

Proof-marked inserted fields use `proof = true` or `role = "proof"` and
report `functional.unresolved-proof` until a proof builder is supplied.
Measure-derived inserted fields use `measure = "<name>"` and require a
matching entry under `measures`.

## Algebraic ornaments

Algebraic ornaments are the case where inserted indices or fields are
computed from a fold over the base value. The canonical example is
ornamenting a list into a vector by inserting its length.

The public helper is `G.ornaments.algOrn`. It validates the supported
description/algebra fragment before constructing the ornament. The
current supported fragment covers `ret`, `arg`, `rec`, keep-only `pi`,
and `plus`. Unsupported function-domain aggregation remains explicit:
validation reports a shape diagnostic instead of guessing an algebra.

Use algebraic ornaments when the extra information is determined by the
base structure itself. Use functional ornaments when the extra
information comes from a user-provided synthesis function, proof builder,
or declared measure.

## Ornament composition

Plain, functional, and algebraic ornaments all refine a single base
datatype at the whole-type level. Three additional constructions
refine ornaments themselves, so the refinement *at one field position*
can be an ornament rather than the identity:

- **Leaf functional ornaments** lift a Nix-meta function `f : B → A`
  into an ornament of a primitive HOAS type former. They are the
  base case for refinements on non-μ types (`H.string`, `H.derivation`,
  `H.thunk`, …) where there is no constructor structure to walk.
- **Functorial container lifts** carry an ornament `O : Ornament A A'`
  through a strictly-positive container functor (`List`, `Attrs`,
  `Maybe`, or a single record field) to produce an ornament between the
  lifted containers, with forget defined by the standard functorial
  action.
- **Sub-ornament composition at `keep`** is the spec verb
  `{ keep = "x"; sub = O; }` inside a `G.ornaments.ornament` call. It
  declares that the kept field carries the *refined* type at the
  source and forgets through `O.forget` at that field on the way to
  the base.

These compose: a `keep + sub` may use a `lift.list` of a
`thunkOrnament`, and so on.

### Leaf functional ornaments

A leaf functional ornament refines a primitive HOAS type former by
attaching a Nix-meta function pair `(forget, section)`. Construction
requires the primitive to satisfy `_htag ≠ "mu"`; μ-encoded bases use
`H.ornament` or `H.functionalOrnament` instead.

```nix
let
  fx = import ./nix/nix-effects {};
  H = fx.types.hoas;

  IdString = H.leafOrnament {
    primitive = H.string;
    forget = x: x;
    section = x: x;
  };
in IdString.forget "hello"
```

The identity is the trivial case; the construction earns its keep when
`forget` is a non-trivial Nix function such as `forceThunk`. The
literature anchor is Dagand and McBride, *Transporting Functions
across Ornaments* (JFP 2014), which gives the general construction of
a functional ornament over `A` induced by a function `f : B → A`. The
leaf case specialises that construction to primitive type formers.

The derived constructor `H.thunkOrnament` packages the lift of
`forceThunk : Thunk a → a` and its section `mkThunk : a → Thunk a`:

```nix
H.thunkOrnament inner
≡ H.leafOrnament {
    primitive = H.thunk inner;
    forget = fx.state.thunk.forceThunk;
    section = fx.state.thunk.mkThunk;
    meta = { name = "Thunk"; baseHtag = "thunk"; inner = inner; };
  }
```

The `Thunk` carrier is the kernel's deepSeq-safe wrapper for transport
of cyclic or otherwise force-unsafe values through handler state; see
`src/state/thunk.nix` for the carrier shape and discipline. `H.thunk`
is the leaf functional ornament whose forget is `forceThunk` — the
ornament algebra is the principled home for the `Thunk → a` story
that the runtime already follows.

### Functorial container lifts

Given an ornament `O : Ornament A A'`, each strictly-positive
container functor `F` extends `O` to an ornament `F(O) : Ornament
F(A) F(A')` whose forget is `F`'s functorial action on `O.forget`.
The kernel exposes four lifts under `G.ornaments.lift`:

```nix
G.ornaments.lift.list  : Ornament A A' -> Ornament (List A) (List A')
G.ornaments.lift.attrs : Ornament A A' -> Ornament (Attrs A) (Attrs A')
G.ornaments.lift.maybe : Ornament A A' -> Ornament (Maybe A) (Maybe A')
G.ornaments.lift.field : String -> Ornament A A' -> Ornament Record Record'
```

Forget is `map o.forget`, `mapAttrs (_: o.forget)`, the null-passthrough
of `o.forget`, and the single-field rewrite `r // { ${name} = o.forget
r.${name}; }` respectively. Section mirrors forget on the dual side.

```nix
let
  fx = import ./nix/nix-effects {};
  H = fx.types.hoas;
  G = fx.types.generic;

  drvA = { type = "derivation"; name = "a"; outPath = "/nix/store/a"; };
  drvB = { type = "derivation"; name = "b"; outPath = "/nix/store/b"; };

  thunked = H.thunkOrnament H.derivation;
  paths   = G.ornaments.lift.list thunked;
in paths.forget [ (thunked.section drvA) (thunked.section drvB) ]
# ≡ [ drvA drvB ]
```

The literature anchor is Dagand, *A Cosmology of Datatypes* (PhD
thesis, Strathclyde 2013), chapter 6 "Functoriality of refinements." The
four lifts are siblings, not derived from one another at the kernel
boundary: each is the functorial action of an ornament along the
corresponding container functor. `lift.field` is the elementary
product-component move; the other three are the analogous moves for
`List`, `Attrs`, and `Maybe`. The container lifts decompose through
`lift.field` via the μ-encoding of containers, but the kernel ships
them all directly so consumers do not pay μ-unfolding cost at every
use site.

### Sub-ornament composition at `keep`

The spec language of `G.ornaments.ornament` recognises
`{ keep = "fieldName"; sub = O; }` as a directive that the named
field carries `O`'s *refined* type on the ornamented side and
forgets through `O.forget` at that field. The plain `{ keep =
"fieldName"; }` form remains the categorical identity at the kept
position; the `sub` verb adds the refinement.

```nix
let
  fx = import ./nix/nix-effects {};
  H = fx.types.hoas;
  G = fx.types.generic;

  drv = { type = "derivation"; name = "x"; outPath = "/nix/store/x"; };

  Box = H.datatype "Box" [
    (H.con "box" [ (H.field "value" H.derivation) ])
  ];

  TaggedThunkBox = G.ornaments.ornament Box {
    name = "TaggedThunkBox";
    constructors.box.fields = [
      { keep = "value"; sub = H.thunkOrnament H.derivation; }
      { insert = "tag"; type = H.bool; }
    ];
  };

  state = {
    _con = "box";
    value = (H.thunkOrnament H.derivation).section drv;
    tag = true;
  };
in G.ornaments.forget TaggedThunkBox state
# ≡ { _con = "box"; value = drv; }
```

The forget walker copies plain `keep` fields, drops `insert` fields,
and dispatches `keep + sub` fields through the sub-ornament's forget.
Constructor `_con` is preserved because the kernel reuses the base
constructor's name for the refined branch.

Sub-type agreement is checked at spec time. A `sub` whose forward
type disagrees with the kept field's type produces an
`ornament.sub-type-mismatch` diagnostic; a `sub` that is not a
recognised ornament produces `ornament.sub-not-ornament`.

### A single forget, two evaluations

`G.ornaments.forget : Ornamented → Value → Value` is one morphism. The
HOAS-term path and the Nix-meta path are two evaluations of the same
morphism; the commutation `eval (forgetHoas t) ≡ forgetMeta (eval t)`
is a theorem of the framework. Dispatch is structural on the
well-formed sum `_htag` (HOAS term) ⊕ `_con` (Nix-meta μ-value):

```nix
G.ornaments.forget ornamented value
# value._htag  -> HOAS-term path (returns HOAS-applied forget)
# value._con   -> Nix-meta path  (returns Nix attrset)
# both / neither / non-attrset -> throws
```

Both internal paths are reachable as
`G.ornaments._internal.{forgetHoas, forgetMeta}` for tests that need
to pin the evaluator, but application code calls `G.ornaments.forget`
and lets the dispatcher pick.

## API summary

HOAS layer:

```nix
H.ornament base spec
H.ornDesc ornament
H.ornForget ornament
H.ornCompose outer inner
H.ornPullback ornament resultTy baseFn
H.ornLiftFold ornament resultTy baseFold

H.functionalOrnament { ornament; chooseIndex; section; ... }
H.ornBuild functional index baseValue
H.ornLiftProducer functional baseFn index baseInput
H.ornLiftTransform { input; output; fn; } outputIndex inputIndex ornamentedInput

H.leafOrnament { primitive; forget; section; sectionProof?; meta?; }
H.thunkOrnament inner
```

Generic layer:

```nix
G.ornaments.ornament base spec
G.ornaments.forget ornamented value
G.ornaments.compose outer inner
G.ornaments.pullback ornamented baseFn value

G.ornaments.functional { base; spec; synth; ... }
G.ornaments.validateFunctional { base; spec; synth; ... }
G.ornaments.build functional baseValue
G.ornaments.composeFunctional outer inner
G.ornaments.liftProducer functional baseFn baseInput
G.ornaments.liftTransform { input; output; fn; } ornamentedInput

G.ornaments.lift.list  o
G.ornaments.lift.attrs o
G.ornaments.lift.maybe o
G.ornaments.lift.field name o
```

The generic layer is the best default for application code. Drop to HOAS
when you need direct indexed terms, explicit proof terms, or kernel-level
transport.


#### Proof Guide


Nix DSL values are concrete at eval time. Every declaration, field, and
dependency edge is known before anything builds. The nix-effects
dependent type checker exploits this: it normalizes both sides of an
equation via NbE, and if they reduce to the same value, `Refl` proves
them equal. No symbolic reasoning, no induction over unknowns — just
computation on concrete data, checked through the freer-monad effect
layer in pure Nix.

This chapter builds proofs incrementally, from `0 + 0 = 0` through
the J eliminator to verified extraction of plain Nix functions from
kernel-checked HOAS terms. Every example is runnable. The code comes
from three files in the repository:
[`proof-basics.nix`](https://github.com/kleisli-io/nix-effects/blob/main/examples/proof-basics.nix),
[`equality-proofs.nix`](https://github.com/kleisli-io/nix-effects/blob/main/examples/equality-proofs.nix), and
[`verified-functions.nix`](https://github.com/kleisli-io/nix-effects/blob/main/examples/verified-functions.nix).

**Prerequisites.** You should know what a function is and what `let`
bindings do in Nix. Familiarity with the Getting Started chapter helps
but isn't required. You do not need to know type theory.

## Your first proof

A proof in nix-effects is a term that type-checks against an equality
type. The simplest equality type is `Eq(Nat, 0+0, 0)` — the claim
that adding zero to zero produces zero. The proof term is `Refl`, which
says "both sides are the same." The kernel checks this by normalizing
`0 + 0`, arriving at `0`, and confirming that `Refl` witnesses `0 = 0`.

```nix
let
  H = fx.types.hoas;
  inherit (H) nat eq zero refl checkHoas;

  # Addition by structural recursion on the first argument
  add = m: n:
    H.ind (H.lam "_" nat (_: nat)) n
      (H.lam "k" nat (_: H.lam "ih" nat (ih: H.succ ih))) m;
in
  # Prove: 0 + 0 = 0
  (checkHoas (eq nat (add zero zero) zero) refl).tag == "refl"
  # → true
```

`checkHoas` is the kernel's entry point. It takes a type and a term,
runs bidirectional type checking with normalization by evaluation, and
returns a result. If the result's `tag` is `"refl"`, the proof was
accepted. If it has an `error` field, the kernel rejected it.

The kernel doesn't pattern-match on `0 + 0 = 0` as a special case. It
evaluates `add(zero, zero)` by running the generated natural eliminator
behind `H.ind` — the base case fires, returns `n` (which is `zero`),
and the kernel sees `Eq(Nat, zero, zero)`. `Refl` witnesses any
`Eq(A, x, x)`, so the proof goes through.

Larger numbers work the same way. The kernel unrolls the recursion:

```nix
# 3 + 5 = 8
(checkHoas (eq nat (add (H.natLit 3) (H.natLit 5)) (H.natLit 8)) refl).tag == "refl"

# 10 + 7 = 17
(checkHoas (eq nat (add (H.natLit 10) (H.natLit 7)) (H.natLit 17)) refl).tag == "refl"
```

Both reduce to `true`. The kernel normalizes `add(3, 5)` step by
step — three `succ` peels, then the base case returns `5`, then three
`succ` wrappers are reapplied — and confirms the result is `8`.

## Dependent witnesses

A computational equality says "these two things are the same." A
dependent witness says "here is a value, and here is evidence that
it has a property." The Sigma type `Σ(x:A).P(x)` packages both: a
value `x` of type `A`, and a proof that `P(x)` holds.

```nix
let
  H = fx.types.hoas;
  inherit (H) nat eq sigma zero pair refl checkHoas;
in {
  # "There exists x : Nat such that x = 0" — witnessed by (0, Refl)
  witness = let
    ty = sigma "x" nat (x: eq nat x zero);
    tm = pair zero refl;
  in (checkHoas ty tm).tag == "pair";
  # → true
}
```

The type `Σ(x:Nat). Eq(Nat, x, 0)` says "a natural number equal to
zero." The term `(0, Refl)` inhabits it: `0` for the value, `Refl` for
the proof that `0 = 0`. The kernel checks both components — it
confirms `0 : Nat` and `Refl : Eq(Nat, 0, 0)`.

Witnesses get more interesting when the property involves computation:

```nix
# "There exists x such that 3+5 = x" — witnessed by (8, Refl)
witnessAdd = let
  add = m: n:
    H.ind (H.lam "_" nat (_: nat)) n
      (H.lam "k" nat (_: H.lam "ih" nat (ih: H.succ ih))) m;
  ty = sigma "x" nat (x: eq nat (add (H.natLit 3) (H.natLit 5)) x);
  tm = pair (H.natLit 8) refl;
in (checkHoas ty tm).tag == "pair";
```

The kernel normalizes `add(3, 5)` to `8`, checks that `8` matches the
witness value, and accepts the proof. If you claimed the witness was
`7`, the kernel would reject it — `Refl` can't witness `8 = 7`.

## Eliminators

Eliminators are how you compute over inductive types in type theory.
Where Nix uses `if`/`else` and list folds, the kernel uses eliminators:
structured recursion with a *motive* that declares what type the result
has. The motive is what makes these dependently typed — the return type
can vary based on the input.

### Booleans

`H.boolElim k motive trueCase falseCase scrutinee` — case analysis on
a derived boolean. `H.bool` is `μ ⊤ (plus (retI tt) (retI tt)) tt`,
and `H.boolElim` is defined in terms of `desc-ind` on that
description (see `src/tc/hoas/combinators.nix`). The user-facing
behavior is the standard boolean eliminator: with a constant motive
(return type doesn't depend on the boolean), it's equivalent to an
if/else.

```nix
let
  H = fx.types.hoas;
  inherit (H) nat bool eq zero refl boolElim checkHoas;
in {
  # if true then 42 else 0 = 42
  trueCase = let
    result = boolElim 0 (H.lam "_" bool (_: nat)) (H.natLit 42) zero H.true_;
  in (checkHoas (eq nat result (H.natLit 42)) refl).tag == "refl";

  # if false then 42 else 0 = 0
  falseCase = let
    result = boolElim 0 (H.lam "_" bool (_: nat)) (H.natLit 42) zero H.false_;
  in (checkHoas (eq nat result zero) refl).tag == "refl";
}
```

### Natural numbers

`H.ind k motive base step n` — structural recursion over the generated
natural datatype. The base case handles zero, the step case takes the
predecessor `k` and the inductive hypothesis `ih` (the result for `k`)
and produces the result for `S(k)`:

```nix
let
  H = fx.types.hoas;
  inherit (H) nat eq refl checkHoas;

  # double(n): double(0) = 0, double(S(k)) = S(S(double(k)))
  double = n: H.ind (H.lam "_" nat (_: nat)) H.zero
    (H.lam "k" nat (_: H.lam "ih" nat (ih: H.succ (H.succ ih)))) n;
in
  # double(4) = 8
  (checkHoas (eq nat (double (H.natLit 4)) (H.natLit 8)) refl).tag == "refl"
```

The kernel unrolls four steps: `double(4) = S(S(double(3))) = ... = 8`.

### Lists

`H.listElim k elemType motive nilCase consCase list` — structural
recursion over the generated list datatype. The nil case provides the
base value, the cons case takes the head, tail, and inductive
hypothesis:

```nix
let
  H = fx.types.hoas;
  inherit (H) nat eq refl checkHoas;

  list123 = H.cons nat (H.natLit 1) (H.cons nat (H.natLit 2)
              (H.cons nat (H.natLit 3) (H.nil nat)));

  # sum(xs): fold with addition
  sumList = xs: H.listElim nat (H.lam "_" (H.listOf nat) (_: nat)) H.zero
    (H.lam "h" nat (h: H.lam "t" (H.listOf nat) (_:
      H.lam "ih" nat (ih:
        H.ind (H.lam "_" nat (_: nat)) ih
          (H.lam "k" nat (_: H.lam "ih2" nat (ih2: H.succ ih2))) h)))) xs;
in
  # sum([1, 2, 3]) = 6
  (checkHoas (eq nat (sumList list123) (H.natLit 6)) refl).tag == "refl"
```

### Sums (coproducts)

`H.sumElim k L R motive leftCase rightCase scrutinee` — case analysis
over the generated sum datatype:

```nix
let
  H = fx.types.hoas;
  inherit (H) nat bool sum eq zero refl checkHoas;
in {
  # case Left(5) of { Left n → n; Right _ → 0 } = 5
  leftCase = let
    scrut = H.inl nat bool (H.natLit 5);
    result = H.sumElim nat bool (H.lam "_" (sum nat bool) (_: nat))
      (H.lam "n" nat (n: n))
      (H.lam "b" bool (_: zero))
      scrut;
  in (checkHoas (eq nat result (H.natLit 5)) refl).tag == "refl";
}
```

## The J eliminator

Everything above uses `Refl` on equalities that the kernel verifies
by computation — normalize both sides, confirm they match. But what if
you want to reason *about* equalities? Prove that equality is
symmetric, or that applying a function to equal inputs gives equal
outputs? That requires the J eliminator, the fundamental proof
principle for identity types in Martin-Löf type theory [1].

J says: if you can prove something about `x = x` (the reflexive case),
you can prove it about any `x = y` where the equality is witnessed.

```
J(A, a, P, pr, b, eq)
  A  : type
  a  : left side of the equality
  P  : λ(y:A). λ(_:Eq(A,a,y)). Type    — the motive
  pr : P(a, refl)                       — the base case (when y = a)
  b  : right side
  eq : Eq(A, a, b)                      — proof that a = b
  Returns: P(b, eq)

Computation rule: J(A, a, P, pr, a, refl) = pr
```

When the equality proof is `Refl`, J returns the base case directly.
The kernel reduces `J(..., refl)` to `pr`, and the proof goes through.

### Congruence

If `x = y`, then `f(x) = f(y)` for any function `f`. This is the
standard *cong* combinator, derived from J:

```nix
let
  H = fx.types.hoas;
  inherit (H) nat eq u forall refl checkHoas;

  congType =
    forall "A" (u 0) (a:
      forall "B" (u 0) (b:
        forall "f" (forall "_" a (_: b)) (f:
          forall "x" a (x:
            forall "y" a (y:
              forall "_" (eq a x y) (_:
                eq b (H.app f x) (H.app f y)))))));

  congTerm = H.lam "A" (u 0) (a:
    H.lam "B" (u 0) (b:
      H.lam "f" (forall "_" a (_: b)) (f:
        H.lam "x" a (x:
          H.lam "y" a (y:
            H.lam "p" (eq a x y) (p:
              H.j a x
                (H.lam "y'" a (y':
                  H.lam "_" (eq a x y') (_:
                    eq b (H.app f x) (H.app f y'))))
                refl y p))))));
in
  (checkHoas congType congTerm).tag == "lam"
```

The derivation: J eliminates the proof `p : Eq(A, x, y)`. The motive
says "given `y'` equal to `x`, produce `Eq(B, f(x), f(y'))`." In the
base case, `y' = x`, so the goal is `Eq(B, f(x), f(x))` — which
`Refl` proves. J then transports this to `Eq(B, f(x), f(y))`.

This generic combinator type-checks with abstract variables `A`, `B`,
`f`, `x`, `y` — the kernel verifies the reasoning is valid for all
inputs. On concrete data, J receives `Refl` (since concrete equalities
reduce by computation), and the kernel simplifies:

```nix
# Concrete: from add(2,1) = 3, derive succ(add(2,1)) = succ(3)
congConcrete = let
  add21 = add (H.natLit 2) (H.succ H.zero);
  three = H.natLit 3;
in (checkHoas
    (eq nat (H.succ add21) (H.succ three))
    (H.j nat add21
      (H.lam "y" nat (y:
        H.lam "_" (eq nat add21 y) (_:
          eq nat (H.succ add21) (H.succ y))))
      refl three refl)).tag == "j";
```

### Symmetry

If `x = y`, then `y = x`. The motive is `λy'.λ_. Eq(A, y', x)` —
when `y' = x`, the goal is `Eq(A, x, x)`, proved by `Refl`:

```nix
# sym : Π(A:U₀). Π(x:A). Π(y:A). Eq(A,x,y) → Eq(A,y,x)
symTerm = H.lam "A" (u 0) (a:
  H.lam "x" a (x:
    H.lam "y" a (y:
      H.lam "p" (eq a x y) (p:
        H.j a x
          (H.lam "y'" a (y': H.lam "_" (eq a x y') (_: eq a y' x)))
          refl y p))));
```

### Transitivity

If `x = y` and `y = z`, then `x = z`. Fix `p : Eq(A, x, y)`, then
eliminate `q` with J. The motive is `λz'.λ_. Eq(A, x, z')` — when
`z' = y`, the goal is `Eq(A, x, y)`, proved by `p`:

```nix
# trans : Π(A:U₀). Π(x:A). Π(y:A). Π(z:A). Eq(A,x,y) → Eq(A,y,z) → Eq(A,x,z)
transTerm = H.lam "A" (u 0) (a:
  H.lam "x" a (x:
    H.lam "y" a (y:
      H.lam "z" a (z:
        H.lam "p" (eq a x y) (p:
          H.lam "q" (eq a y z) (q:
            H.j a y
              (H.lam "z'" a (z': H.lam "_" (eq a y z') (_: eq a x z')))
              p z q))))));
```

### Transport

The most general form. If `x = y` and `P(x)` holds, then `P(y)` holds.
Congruence, symmetry, and transitivity are all special cases.

```nix
# transport : Π(A:U₀). Π(P:A→U₀). Π(x:A). Π(y:A). Eq(A,x,y) → P(x) → P(y)
transportTerm = H.lam "A" (u 0) (a:
  H.lam "P" (forall "_" a (_: u 0)) (bigP:
    H.lam "x" a (x:
      H.lam "y" a (y:
        H.lam "p" (eq a x y) (p:
          H.lam "px" (H.app bigP x) (px:
            H.j a x
              (H.lam "y'" a (y': H.lam "_" (eq a x y') (_: H.app bigP y')))
              px y p))))));
```

### Chaining proofs

J applications compose. Here we chain congruence (lift through `succ`)
with symmetry (reverse the equality) — two J applications, the output
of the first feeding as the equality proof to the second:

```nix
# From Eq(Nat, add(2,1), 3):
#   Step 1 (cong succ): Eq(Nat, S(add(2,1)), S(3))
#   Step 2 (sym):       Eq(Nat, S(3), S(add(2,1)))
combinedProof = let
  add21 = add (H.natLit 2) (H.succ H.zero);
  three = H.natLit 3;
  sadd21 = H.succ add21;
  sthree = H.succ three;
  # Step 1: cong succ
  congStep = H.j nat add21
    (H.lam "y" nat (y: H.lam "_" (eq nat add21 y) (_: eq nat sadd21 (H.succ y))))
    refl three refl;
  # Step 2: sym on the cong result
in (checkHoas (eq nat sthree sadd21)
    (H.j nat sadd21
      (H.lam "y" nat (y: H.lam "_" (eq nat sadd21 y) (_: eq nat y sadd21)))
      refl sthree congStep)).tag == "j";
```

## Verified extraction

Proofs establish that properties hold. Verified extraction goes
further: write an implementation in HOAS, the kernel type-checks it
against a specification, and `v.verify` extracts a callable Nix
function. The result is an ordinary Nix value — an integer, a boolean,
a function, a list — but one whose implementation was machine-checked
before use.

### The simplest case

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  # Kernel-verified successor: Nat → Nat
  succFn = v.verify (H.forall "x" H.nat (_: H.nat))
                    (v.fn "x" H.nat (x: H.succ x));
in
  succFn 5    # → 6
```

`v.verify` does three things: elaborates the HOAS into kernel terms,
type-checks the implementation against the type, and extracts the
result as a Nix value. The extracted function is plain Nix — no kernel
overhead at call time.

`v.fn` is a convenience wrapper around `H.lam` that threads the
extraction metadata. You could write raw `H.lam` instead, but `v.fn`
handles the plumbing for multi-argument functions and pattern matching.

### Pattern matching

`v.match` builds an `H.ind` with a constant motive. You provide the
result type, the scrutinee, and branches for `zero` and `succ`:

```nix
# Verified addition: Nat → Nat → Nat
addFn = v.verify (H.forall "m" H.nat (_: H.forall "n" H.nat (_: H.nat)))
  (v.fn "m" H.nat (m: v.fn "n" H.nat (n:
    v.match H.nat m {
      zero = n;
      succ = _k: ih: H.succ ih;
    })));

addFn 2 3    # → 5
addFn 0 7    # → 7
```

The `succ` branch receives two arguments: `k` (the predecessor) and
`ih` (the inductive hypothesis — the result for `k`). For addition,
`ih` is `add(k, n)`, so wrapping it with `succ` gives `add(S(k), n)`.

### Boolean and cross-type elimination

`v.if_` elaborates to `H.boolElim` on the derived `H.bool`:

```nix
# Verified not: Bool → Bool
notFn = v.verify (H.forall "b" H.bool (_: H.bool))
  (v.fn "b" H.bool (b:
    v.if_ H.bool b { then_ = v.false_; else_ = v.true_; }));

notFn true     # → false
notFn false    # → true
```

Cross-type elimination — scrutinize one type, return another — works
by specifying a different result type:

```nix
# Verified isZero: Nat → Bool
isZeroFn = v.verify (H.forall "n" H.nat (_: H.bool))
  (v.fn "n" H.nat (n:
    v.match H.bool n {
      zero = v.true_;
      succ = _k: _ih: v.false_;
    }));

isZeroFn 0    # → true
isZeroFn 5    # → false
```

### List operations

`v.map`, `v.filter`, and `v.fold` are verified list combinators. Each
takes HOAS terms, not Nix functions — the kernel verifies the entire
pipeline:

```nix
# Composed pipeline: filter zeros, then sum
# Input: [0, 3, 0, 2, 1] → Filter: [3, 2, 1] → Sum: 6
composedResult = let
  input = H.cons H.nat (v.nat 0) (H.cons H.nat (v.nat 3)
    (H.cons H.nat (v.nat 0) (H.cons H.nat (v.nat 2)
      (H.cons H.nat (v.nat 1) (H.nil H.nat)))));
  nonZero = v.fn "n" H.nat (n:
    v.match H.bool n {
      zero = v.false_;
      succ = _k: _ih: v.true_;
    });
  addCombine = v.fn "a" H.nat (a: v.fn "acc" H.nat (acc:
    v.match H.nat a {
      zero = acc;
      succ = _k: ih: H.succ ih;
    }));
in v.verify H.nat (v.fold H.nat H.nat (v.nat 0) addCombine
                     (v.filter H.nat nonZero input));
# → 6
```

The kernel verifies the filter predicate (`Nat → Bool`), the fold
combinator (`Nat → Nat → Nat`), and their composition before extracting
the result. A type error in any component — say, returning a `Nat`
where the filter expects a `Bool` — fails at `nix eval`, not at runtime.

### Aspect declarations and string operations

The kernel supports record types (elaborated as nested Sigma) and
string equality (`strEq` is a kernel primitive). Together they verify
functions over the same aspect declarations introduced earlier:

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  AspectDecl = H.record [
    { name = "name";     type = H.string; }
    { name = "target";   type = H.string; }
    { name = "requires"; type = H.listOf H.string; }
  ];

  targets =
    H.cons H.string (v.str "module")
      (H.cons H.string (v.str "file")
        (H.cons H.string (v.str "package")
          (H.cons H.string (v.str "check") (H.nil H.string))));

  validateAspect = v.verify (H.forall "a" AspectDecl (_: H.bool))
    (v.fn "a" AspectDecl (a:
      v.strElem (v.field AspectDecl "target" a) targets));
in {
  ok = validateAspect {
    name = "workspace-shell";
    target = "module";
    requires = [ "toolchain" ];
  };   # → true

  bad = validateAspect {
    name = "workspace-aspect";
    target = "fleet";
    requires = [ ];
  };   # → false
}
```

`v.field` desugars to the right chain of `fst`/`snd` projections for
the field's position in the Sigma chain. `v.strEq` reduces in the
kernel via the `StrEq` primitive — it compares string literals during
normalization, producing `true` or `false` as kernel values. `v.strElem`
folds that primitive over a generated list of allowed target classes.

## What the kernel can and cannot prove

The nix-effects kernel implements Martin-Löf type theory with
universes, dependent functions, dependent pairs, identity types,
natural numbers, lists, sums, unit, the empty type, an indexed-
description family (`Desc I`, `μ`, `desc-ind`), and seven axiomatized
Nix primitives (String, Int, Float, Attrs, Path, Function, Any).
Booleans are derived — `H.bool` as `μ ⊤ (plus (retI tt) (retI tt)) tt`
with eliminator `H.boolElim` via `desc-ind`. `Empty` is a kernel
primitive (the initial-object dual of `Unit`) with eliminator
`H.absurd : Π(P:U(k)). Empty → P`.
The kernel can prove any property that reduces to a comparison of
normal forms.

**It can prove:**

- Equalities between computed values: `add(3, 5) = 8`,
  `length([1,2,3]) = 3`, `append([1,2], [3]) = [1,2,3]`
- Properties of concrete data: "this declaration field is in the
  allowed set," "this target class is valid," "these two strings match"
- Generic combinators: `cong`, `sym`, `trans`, and `transport`
  type-check with abstract variables
- Verified function extraction: any function expressible with the
  kernel's eliminators can be verified and extracted

**It cannot prove automatically by conversion:**

- **Symbolic induction by `refl`.** `forall n, n + 0 = n` requires
  induction over an abstract variable. The generated natural eliminator
  reduces on concrete generated constructor values, so `3 + 0 = 3` and
  `100 + 0 = 100` are witnessed by `refl`. For a bound `n`, `n + 0`
  stays neutral because addition recurses on its first argument; it is
  not definitionally equal to `n`. The universal statement is still
  provable as propositional equality with an explicit induction proof.
  See `examples/category-theory/arithmetic.nix` for `addRightZero`.

- **Properties of Nix builtins.** The kernel axiomatizes `String`,
  `Int`, `Float`, etc. as opaque types. The kernel has `strEq`
  (equality) and `strLen` (length) for strings, plus list membership,
  but operations beyond these — `builtins.substring`, `builtins.match`,
  concatenation — are not kernel functions, so their properties are not
  provable.

- **Eta-expansion.** The kernel does not identify `f` with `λx.f(x)`.
  Functions that are extensionally equal but intensionally different are
  not convertible.

- **User-defined recursive types.** The kernel has an indexed-description
  family (`Desc I` / `μ` / `desc-ind`) that the macro layer uses to
  build public inductives such as `Nat`, `List`, `Sum`, `Bool`, `Fin`,
  `Vec`, and `Eq`-as-description. Arbitrary user-defined inductive
  families (binary trees, red-black trees, etc.) use the same
  description-macro layer; they are not written directly against
  primitive per-type kernel nodes.

  The macro layer exposes four user-facing entry points for defining
  inductive types. `H.datatype name cons` compiles a monomorphic,
  ⊤-indexed datatype from a list of `H.con name fields` specs
  (`H.field`, `H.fieldD`, `H.recField`, `H.piField`, `H.piFieldD` for
  the field shapes). `H.datatypeP name params mkCtors` adds a
  parameter layer, threading each parameter through an outer Π
  binder. `H.datatypeI name I consList` adds an arbitrary index type
  `I : U`; constructors use `H.conI name fields targetIdx` to specify
  their target index as a function of earlier field markers, and
  recursive fields at non-default indices use `H.recFieldAt name
  idxFn` (plain `H.recField` is rejected at `I ≠ ⊤`). `H.datatypePI
  name params indexFn mkCtors` combines parameters and indexing — the
  index type itself may depend on parameters, which is what
  `Eq A a : A → U` requires. Each macro returns a record exposing
  `.D : Desc I`, `.T : Π(i:I). U` (or `μ ⊤ D tt` at the ⊤-sugar
  path), per-constructor fields, and `.elim` built on `desc-ind`. The
  prelude's `FinDT`, `VecDT`, and `EqDT` are the canonical indexed
  instances and drive the surface `H.fin` / `H.vec` / `H.eqDT`
  bindings as thin forwarders.

For Nix, the "concrete data" restriction is less of a limitation than
it sounds. Nix evaluates declarations completely before building —
every aspect, generated module, dependency edge, and package attribute
is a concrete value at eval time. The kernel verifies all computable
properties of that concrete data. What it gives up is proving things
about *all possible* declarations generically. In practice, you prove
properties of the specific graph being built, which is the one that
matters.

## Quick reference

| Pattern | Type | Proof term |
|---------|------|------------|
| Computational equality | `Eq(A, x, y)` where `x`, `y` normalize to same value | `Refl` |
| Dependent witness | `Σ(x:A). P(x)` | `(value, proof)` |
| Case analysis (bool, derived) | `H.boolElim k motive true_case false_case b` | Result of elimination |
| Structural recursion (nat) | `H.ind k motive base step n` | Result of elimination |
| List recursion | `H.listElim k elem motive nil_case cons_case xs` | Result of elimination |
| Sum dispatch | `H.sumElim k L R motive left_case right_case s` | Result of elimination |
| Congruence | `Eq(A,x,y) → Eq(B, f(x), f(y))` | `J(A, x, λy'.λ_. Eq(B,f(x),f(y')), Refl, y, p)` |
| Symmetry | `Eq(A,x,y) → Eq(A,y,x)` | `J(A, x, λy'.λ_. Eq(A,y',x), Refl, y, p)` |
| Transitivity | `Eq(A,x,y) → Eq(A,y,z) → Eq(A,x,z)` | `J(A, y, λz'.λ_. Eq(A,x,z'), p, z, q)` |
| Transport | `Eq(A,x,y) → P(x) → P(y)` | `J(A, x, λy'.λ_. P(y'), px, y, p)` |
| Ex falso (derived `H.void = Fin 0`) | `H.void → A` | `H.absurd A x` (routes through `absurdFin0`) |
| Verified function | `v.verify type impl` | Extracted Nix function |

## References

1. Martin-Löf, P. (1984). *Intuitionistic Type Theory*. Bibliopolis.

2. The Univalent Foundations Program (2013). *Homotopy Type Theory:
   Univalent Foundations of Mathematics*. Institute for Advanced Study.
   [[pdf](https://homotopytypetheory.org/book/)]

3. Norell, U. (2007). *Towards a practical programming language based
   on dependent type theory*. PhD thesis, Chalmers.
   [[pdf](https://www.cse.chalmers.se/~ulfn/papers/thesis.pdf)]


#### Sugar


nix-effects ships an opt-in syntax layer. The kernel doesn't import it,
nothing in the effect interpreter depends on it, and removing it leaves
the library unchanged. What it buys is readability. A three-step state
computation without sugar:

```nix
bind state.get (n:
  bind (state.put (n + 1)) (_:
    bind state.get (n2:
      pure n2)))
```

and with sugar, two forms:

```nix
# Combinator (sequence effects, discard intermediates)
steps [ (_: state.get) (n: state.put (n + 1)) (_: state.get) ]

# Operator
state.get / (n: state.put (n + 1)) / (_: state.get)
```

Both evaluate to the same value under the state handler. `do` is the
companion combinator: rather than producing a `Comp` directly it
returns a Kleisli arrow `(a -> M b)` that you apply to a seed —
trading one keystroke (`(... ) null`) for composability,
point-free use, and auto-lifting of plain functions. The two are
covered side-by-side in [Effect combinators](#effect-combinators).

A third form — `letM` — applies to parallel effects whose results
you want under named bindings:

```nix
# Without sugar
bind (reader.asks (e: e.host)) (host:
  bind (reader.asks (e: e.port)) (port:
    pure "${host}:${toString port}"))

# With letM
letM {
  host = reader.asks (e: e.host);
  port = reader.asks (e: e.port);
} (b: pure "${b.host}:${toString b.port}")
```

`letM` evaluates its attrs independently and passes the result attrset
to the continuation. Use it when the effects don't depend on each
other's values.

## Opting in

Sugar is a hybrid namespace. Effect combinators sit at the top level
of `fx.sugar`, so `with fx.sugar;` brings `do`, `steps`, `letM`,
`pure`, `bind`, `run`, and `handle` into scope immediately. Division
and types are one level deeper, under `operators` and `types`
respectively.

```
fx.sugar
  ├── do, steps, letM
  ├── pure, bind, map, seq, pipe, kleisli
  ├── run, handle
  ├── operators
  │     └── __div
  └── types
        ├── wrap
        └── Int, String, Bool, Float, Path, Null, Unit, Any
```

The combinator-only form is safe under every Nix dialect. No operator
magic, no `with`, no chance of surprising anyone:

```nix
let inherit (fx.sugar) steps letM;
in steps [
  (_: state.get)
  (n: state.put (n * 3))
  (_: state.get)
]
```

Adding `/` as left-associative bind turns long `bind` chains into
pipelines:

```nix
let inherit (fx.sugar.operators) __div;
in state.get / (s: state.put (s + 7)) / (_: state.get)
```

For a file that's mostly computation, reach for `with fx.sugar;` and
pair it with the `__div` inherit:

```nix
let
  inherit (fx.sugar.operators) __div;
in with fx.sugar;
  state.get / (s: state.put (s * 2)) / (_: state.get)
```

The division operator is always nested under `operators`. `with
fx.sugar;` alone will not activate `/` — you have to reach for
`operators` explicitly. That nesting is the entire reason the
namespace is hybrid.

## Effect combinators

### `do`: composable Kleisli arrow

`do` takes a list of functions and returns a Kleisli arrow
`(a -> M b)`. Apply it to a seed value to obtain the computation:

```nix
(do [
  (x: x + 1)            # plain function — auto-lifted via `pure`
  (x: pure (x * 10))    # already monadic — passes through
]) 1
# runs to 20
```

Three properties follow from returning an arrow rather than a `Comp`
directly.

**Composable.** Two pipelines glue via `kleisli` without re-wrapping:

```nix
kleisli (do [ f g ]) (do [ h i ])  ==  do [ f g h i ]
```

**Data-last.** The seed is the final argument, so `do` slots into
`map` point-free:

```nix
map (do [ validate enrich ]) userIds
```

**Auto-lifting.** Each step may be plain `(a -> b)` or monadic
`(a -> M b)`. The runtime dispatches via `isComp`: a `Comp` result
passes through `bind`, anything else is wrapped in `pure`. Pure and
effectful steps mix freely without manual lifting.

The empty list gives the identity arrow `x: pure x`; the singleton
list applies its single step.

### `steps`: sequence of effects

`steps` is the original `do` semantics, renamed. It takes a list of
functions, threads each through `bind`, and returns a `Comp` directly:

```nix
steps [
  (_: state.get)
  (n: state.put (n + 1))
  (_: state.get)
]
```

The seed is `pure null`, so the first step receives `null`. Empty
lists produce `pure null`. Use `steps` when the intent is "sequence
these effects" rather than "thread a value through a pipeline" —
analogous to Haskell's `sequence_`. When the first step is producer-
shaped (`_: pure x`), the leading `null` is harmless boilerplate; for
anything more elaborate, reach for `do` so the seed is explicit.

### `letM`: named results

`letM` collects an attrset of computations, evaluates each one, and
hands the result attrset to a continuation. The Reader-pattern example
from the test suite:

```nix
letM {
  host = reader.asks (e: e.host);
  port = reader.asks (e: e.port);
} (b: pure "${b.host}:${toString b.port}")
# runs to "example.com:443"
```

The continuation receives `{ host; port; }`. When a computation and
its continuation don't need sequencing by intermediate values but do
need named results in scope, `letM` is cleaner than nested `bind`.

### `__div`: operator-style bind

`__div` is a magic attribute name. When both operands of `/` are
non-numeric and `__div` is lexically in scope, Nix dispatches the
operator through it. `fx.sugar.operators.__div` is `fx.bind` under
another name.

```nix
let inherit (fx.sugar.operators) __div;
in state.get / (n: pure (n + 1)) / (n: pure (n * 2))
```

The form is left-associative: `a / f / g` is `bind (bind a f) g`.
This matches the usual reading of a pipeline.

### Re-exports

For convenience, `fx.sugar` re-exports `pure`, `bind`, `map`, `seq`,
`pipe`, `kleisli`, `run`, and `handle` verbatim from `fx`. `with
fx.sugar;` gives you everything the effect layer exposes without
a second `inherit` line.

## Type sugar

### Primitives and refinement

`fx.sugar.types` pre-wraps the eight zero-ary primitives —
`Int`, `String`, `Bool`, `Float`, `Path`, `Null`, `Unit`, `Any` —
with a `__functor` that builds a refinement when you apply a
predicate. A target class, written without sugar:

```nix
let inherit (fx.types) String refined;
in refined "TargetClass" String
  (x: builtins.elem x [ "module" "file" "package" "check" ])
```

and with sugar:

```nix
let inherit (fx.sugar.types) String;
in String (x: builtins.elem x [ "module" "file" "package" "check" ])
```

Both produce a kernel-identical type. The difference is readability
when you're composing several predicates.

### Name cascading

Every refinement appends a `?` to the base type's name. Repeated
refinement cascades:

```nix
let inherit (fx.sugar.types) Int;
  P0 = Int;                       # "Int"
  P1 = Int (x: x >= 0);           # "Int?"
  P2 = Int (x: x >= 0) (x: x < 10); # "Int??"
in builtins.toString P2
# "Int??"
```

The name is what shows up in error messages. If `Int??` isn't
descriptive enough, drop back to `fx.types.refined` and give the type
an explicit name:

```nix
let inherit (fx.types) refined String;
in refined "RendererClass" String
  (x: builtins.elem x [ "module" "file" "package" "check" ])
```

### `wrap` for user-defined types

Types built with `fx.types.mkType` don't get sugar by default. Wrap
them with `fx.sugar.types.wrap` to opt in:

```nix
let
  inherit (fx.types) mkType hoas;
  inherit (fx.sugar.types) wrap;

  UserInt = mkType { name = "UserInt"; kernelType = hoas.int_; };
  Sugared = wrap UserInt;
in
  (Sugared (x: x > 0)).check 5   # true
```

Wrapping is purely additive. It only adds `__functor` (for refinement
application) and `__toString` (for the name). The base type's kernel,
check, description, universe, and every other field stay untouched —
so a sugared type is interchangeable with the desugared original
everywhere the kernel looks at it.

### Sugar inside Record fields

Constructors like `Record`, `ListOf`, `Maybe`, and `Either` already
consume a first argument — their schema. Wrapping them with
`__functor` would collide with that call shape, so `fx.sugar.types`
doesn't wrap them. It doesn't need to: a sugared field-type inside a
Record schema composes for free, because Record reads only the
kernel, which sugar preserves:

```nix
let inherit (fx.types) Record;
    inherit (fx.sugar.types) Int String Bool;
in Record {
  age = Int (x: x >= 0);
  name = String (s: builtins.stringLength s > 0);
  active = Bool;
}
```

This Record has the same `_kernel` as the hand-refined version. The
sugar is pushed *into* the schema, where it needs no special support
from the constructor.

## Caveats

A few details worth knowing before you reach for sugar.

### `+` can't be overloaded

Nix's `+` operator is `ExprConcatStrings` in the parser <sup>1</sup>.
The runtime dispatches on operand types (string, path, number) without
consulting any magic attribute. There's no `__plus` to implement.
Applied to two types, `+` will either concatenate (if they're
strings), add (if they're numbers), or error out. It is not a hook.

For the same reason, there's no way to overload `==`, `<`, or most
other operators. Sugar uses what Nix already dispatches through:
`__functor` for callable attrsets, `__toString` for string coercion,
and `__div` for `/`.

### `with` does not activate `__div`

Nix's `/` operator looks up `__div` by name in the enclosing lexical
scope. It does not search `with`-scoped values. This surprises people
who expect the two forms to be interchangeable:

```nix
# Works:
let inherit (fx.sugar.operators) __div; in (state.get / f)

# Does NOT work — raises an arithmetic division error at runtime:
with fx.sugar.operators; (state.get / f)
```

The reason is that `with` only extends the free-variable lookup
chain — it does not introduce `__div` as a bound name in the scope
that `/` consults. The full-sugar form above wraps `inherit
(fx.sugar.operators) __div;` in the same `let` that brings in the
combinators for exactly this reason.

A witness test lives at `tests/sugar-effects-test.nix` under
`withOperatorsDoesNotActivateDiv`. It asserts that `with
fx.sugar.operators; (6 / 2) == 3` — plain arithmetic, not `__div`
dispatch.

### Lix 2.92+ rejects `__div` shadow

Lix <sup>2</sup> deprecated the pattern of binding a name prefixed
with `__` that shadows a builtin-reserved operator slot. As of Lix
2.92, `let inherit (ops) __div; in ...` produces
`shadow-internal-symbols` errors during parse. If your codebase
targets Lix, stick to `do`, `steps`, and `letM` — they don't touch this
mechanism.

This is not a CppNix limitation. `__div` works under CppNix 2.18+ and
2.31 (the release we test against). The Lix deprecation is a
deliberate policy choice in that fork.

### Scope pollution with `with`

`with fx.sugar.operators;` brings `__div` into the lookup chain as a
value, not as an operator hook. As just noted, it won't make `/`
dispatch to it. But it does make the name `__div` available for
reference — a minor footgun if you were relying on shadowing.
Prefer `inherit` over `with` for operator opt-in.

### Name cascading versus explicit names

Chained refinements produce names like `Int??`. That's intentional
("you refined this twice") but not always helpful in error messages.
If your domain has a real name, use `fx.types.refined` directly:

```nix
let inherit (fx.types) refined Int;
    Even = refined "Even" Int (x: builtins.bitAnd x 1 == 0);
    Positive = refined "Positive" Int (x: x > 0);
    EvenPositive = refined "EvenPositive" Even (x: x > 0);
in EvenPositive.name   # "EvenPositive"
```

Sugar is for in-place predicates, not named types that outlive their
definition.

## Forward-compat notes

Sugar is strictly additive and never references anything the type
system marks for retirement. Three commitments hold across future
changes to the kernel and type modules.

**Kernel preservation.** A sugared type has the same `_kernel` as its
base. Constructors (`Record`, `ListOf`, `Maybe`, `Either`, `Variant`)
read only `_kernel` — so a sugared field is indistinguishable from a
desugared one to every kernel consumer.

**Refinement delegation.** Sugar never constructs refined types
directly. Every `sugared T (pred)` call goes through
`fx.types.refined`, which is the user-facing API point guaranteed to
survive kernel-internal reorganizations. If `refined` changes shape,
sugar follows automatically.

**No diagnostic emission.** Sugar never builds values from
`src/diag/positions.nix` or `src/diag/error.nix`. Error annotation
happens via the base type's `description` and `name`, which
propagate through `refined` without sugar-specific code. When the
diagnostic layer gains structure, sugar will inherit it.

Active witness tests for each of these live in
`tests/sugar-compat-test.nix`. Running the test file as part of
`nix flake check` keeps the commitments observable.

## When to reach for which form

`steps` is the default for "run these effects, in order, for their
side effects." `do` is the default when a pipeline threads a value
through several steps, when the pipeline needs to compose with another
pipeline, or when you want point-free use under `map` and friends.
`letM` covers the case where bound values are siblings rather than a
left-to-right pipeline. Reach for `__div` when a pipeline has three or
more obvious-effect steps and the parentheses are hurting readability.
Reach for `with fx.sugar;` when you're writing a file that's mostly
computation, not mostly plumbing.

For types, use `fx.sugar.types` for one-off refinements inside Record
schemas. Drop back to `fx.types.refined` when the type deserves a
name you'll reference elsewhere.

---

<sup>1</sup> `src/libexpr/parser.y` in the Nix source, handling
`ExprConcatStrings`.

<sup>2</sup> Lix is a community fork of Nix. Relevant deprecation:
`shadow-internal-symbols` in Lix 2.92 release notes.


### Concepts

#### Theory


Several papers shaped nix-effects. Here's how each one maps to code.

## Algebraic effects and the freer monad

A computation is a tree of effects with continuations. A handler walks the
tree, interpreting each effect — either resuming the continuation with a
value or aborting it. That's the handler model from Plotkin & Pretnar
(2009), and nix-effects implements it directly.

A computation is either:

- `Pure value` — finished, returning a value
- `Impure effect continuation` — suspended, waiting for a handler to
  interpret `effect` and feed the result to `continuation`

`send` creates an `Impure` node:

```nix
send "get" null
# Impure { effect = { name = "get"; param = null; }; queue = [k]; }

```

`bind` appends to the continuation queue:

```nix
bind (send "get" null) (s: pure (s * 2))
# Impure { effect = get; queue = [k1, k2] }  — O(1) per bind

```

Handlers provide the interpretation:

```nix
handlers = {
  get = { param, state }: { resume = state; inherit state; };
  put = { param, state }: { resume = null; state = param; };
};

```

`resume` feeds a value to the continuation. `abort` discards it and halts.

## FTCQueue: O(1) bind

Naïve free monads have O(n²) bind chains. The problem is reassociation:

```
(m >>= f) >>= g  ≡  m >>= (f >=> g)

```

Each reassociation traverses the whole tree. Kiselyov & Ishii (2015)
solved this by storing continuations in a catenable queue (FTCQueue)
instead of a list. `snoc` is O(1); queue application (`qApp`) amortizes
the reassociation across traversal.

Total cost: O(n) for n bind operations, regardless of nesting depth. This
matters in practice — a `DepRecord` with 100 fields sends 100 effects, each
of which binds. Without the queue, validation time would be quadratic in
the number of fields.

The interpreter that processes these queued continuations uses
defunctionalization (Reynolds 1972): the recursive handler becomes a data
structure — effect name, parameter, handler result — and a worklist loop
(`builtins.genericClosure`) iterates over steps instead of recursing. This
is the pattern Van Horn & Might (2010) identified in *Abstracting Abstract
Machines*: store-allocated continuations plus worklist iteration give you
bounded stack depth. The
[Trampoline](/nix-effects/internals/trampoline) chapter covers the
implementation: how `genericClosure` becomes a trampoline, why
`deepSeq` prevents thunk accumulation, and which automated tests pin
stack-safety behavior.

## Value-dependent types

Martin-Löf (1984) is where types that depend on values come from. In
nix-effects, all types bottom out in the MLTT kernel (`src/tc/`), which
handles type checking, universe level computation, and proof verification.
The user-facing API provides convenience constructors on top.

**Sigma (Σ)** — the dependent pair. The second component's type is a
function of the first component's value:

```nix
Σ(generated : Bool). if generated then TargetClass else String

```

In nix-effects:

```nix
Sigma { fst = Bool; snd = b: if b then TargetClass else String; }

```

`Sigma.validate` decomposes the check: validate `fst` first, then — only
if it passes — evaluate `snd fst-value` and validate that. The dependent
expression is never evaluated on a wrong-typed input. That ordering is
the whole point.

**Pi (Π)** — dependent function type. The return type depends on the
argument:

```nix
Pi { domain = String; codomain = _: Int; }

```

The kernel's decision procedure checks `isFunction` — closures are
opaque, so that's all it can verify at introduction. Full verification
happens at elimination via the kernel's type-checking judgment.

**Universe hierarchy.** Types themselves have types, stratified from
`Type_0` through `Type_4` to guard against Russell's paradox:

```nix
(typeAt 0).check Int  # true — Int lives at universe 0
level String           # 0
(typeAt 1).check (typeAt 0)  # true — Type_0 lives at universe 1

```

Universe levels are computed by the kernel's `checkTypeLevel`: `level(Pi(A,B))
= max(level(A), level(B))`, `level(U(i)) = i+1`. Self-containing universes
(`U(i) : U(i)`) are rejected — `level(U(i)) = i+1 > i`, so the check
fails. This prevents both accidental and adversarial paradoxes for every
kernel-backed type.

## Refinement types

Sometimes you need a type that's narrower than `String` but wider than
an enum hard-coded into every caller. Freeman & Pfenning (1991)
introduced the refinement type: given a base type T and a predicate P,
the type {x:T | P(x)} admits only values of T that satisfy P.
`refined` is the direct implementation — `refined "TargetClass" String
(x: builtins.elem x [ "module" "file" "package" "check" ])` is a string
whose value is one of the renderer classes, with a name attached. Rondon
et al. (2008) later scaled the idea with SMT-based inference under the
name *Liquid Types*. We skip the solver and use runtime predicate
checking:

```nix
TargetClass = refined "TargetClass" String
  (x: builtins.elem x [ "module" "file" "package" "check" ]);
NonEmpty = refined "NonEmpty" String (s: builtins.stringLength s > 0);
Nat      = refined "Nat" Int (x: x >= 0);

```

`TargetClass.check` composes the kernel's decision (`String`) with the
refinement predicate.
Combinators for building compound predicates:

```nix
allOf [ pred1 pred2 ]  # conjunction
anyOf [ pred1 pred2 ]  # disjunction
negate pred            # negation

```

## Soundness and what Nix provides

The kernel's soundness is standard MLTT metatheory. Martin-Löf (1984)
set out the rules, and the Mini-TT lineage (Coquand et al. 2009, Kovács
2022, and the elaboration-zoo and pi-forall tutorials) gives the
bidirectional elaboration and normalization-by-evaluation recipe the
kernel follows. Nothing in the kernel is novel on the metatheory side,
and none of the soundness argument routes through anything Nix-specific.

What Nix contributes is a faithful runtime for definitional equality.
NbE requires that reducing open terms is deterministic and side effect
free, and pure Nix evaluation gives you exactly that. `builtins.trace`
and `builtins.throw` are not observable through definitional equality,
so they cannot perturb conversion checking.

The effect layer sits above the kernel as meta-level freer monad data.
`Impure` and `Pure` attrsets are values walked by pure handlers. They
are not object-language effects in the kernel's grammar, and the kernel
has no constructor for them. This is how the effect layer can surface
kernel errors as `typeCheck` effects carrying context paths without
widening the trusted core.

## Graded linear types

Orchard, Liepelt & Eades (2019) introduced a type system where each
variable carries a usage grade from a resource semiring. We implement
three points on that spectrum: `Linear` (exactly one use), `Affine` (at
most one), and `Graded` (exactly n uses).

In practice, the handler maintains a resource map counting each `consume`
call against a `maxUses` bound. At handler exit, a finalizer checks that
every resource was consumed the expected number of times. The grade
discipline is enforced at runtime through the effect system, not
statically — so you get usage tracking without a custom type checker, but
violations show up at eval time rather than before it. That's a real
trade-off, and for eval-time DSL validation we're comfortable with it.

## Higher-order contracts and blame

Findler & Felleisen (2002) solved a problem that shows up immediately
when you try to check function types: you can't test a function contract
at the point of definition. A function is a closure — opaque. The only
way to check it is to wrap it and verify at application boundaries.

In nix-effects, this is exactly what happens. `decide(H.forall ..., f)`
can only confirm `builtins.isFunction f` — the kernel can't look inside
a Nix closure. For full verification, you write the implementation in
HOAS, the kernel type-checks the term, and `extract` wraps the result as
a Nix function that elaborates its arguments at every call boundary. The
contract is enforced at application, not definition. That's Findler &
Felleisen.

Their other contribution is blame tracking. When a check fails, the error
needs to say *which* contract was violated and *where*. In nix-effects,
`.validate` sends `typeCheck` effects carrying blame context — type name,
field path, rejected value — and the handler decides the error policy:
`strict` throws immediately, `collecting` accumulates all failures,
`logging` records every check. Same kernel judgment, different reporting
strategy — the handler pattern (Plotkin & Pretnar) composes with the
contract pattern (Findler & Felleisen) to separate what to check from
how to report.

## References

1. Plotkin, G., & Pretnar, M. (2009). *Handlers of Algebraic Effects*.
   ESOP 2009. [[doi](https://doi.org/10.1007/978-3-642-00590-9_7)]

2. Kiselyov, O., & Ishii, H. (2015). *Freer Monads, More Extensible Effects*.
   Haskell Symposium 2015. [[pdf](https://okmij.org/ftp/Haskell/extensible/more.pdf)]

3. Martin-Löf, P. (1984). *Intuitionistic Type Theory*. Bibliopolis.

4. Rondon, P., Kawaguchi, M., & Jhala, R. (2008). *Liquid Types*.
   PLDI 2008. [[doi](https://doi.org/10.1145/1375581.1375602)]

5. Findler, R., & Felleisen, M. (2002). *Contracts for Higher-Order Functions*.
   ICFP 2002. [[doi](https://doi.org/10.1145/581478.581484)]

6. Van Horn, D., & Might, M. (2010). *Abstracting Abstract Machines*.
   ICFP 2010. (See [Trampoline](/nix-effects/internals/trampoline))

7. Freeman, T., & Pfenning, F. (1991). *Refinement Types for ML*.
   PLDI 1991. [[doi](https://doi.org/10.1145/113445.113468)]

8. Orchard, D., Liepelt, V., & Eades, H. (2019). *Quantitative Program
   Reasoning with Graded Modal Types*. ICFP 2019.
   [[doi](https://doi.org/10.1145/3341714)]

## Prior art

- Borja, V. (2026). *nfx: Nix Algebraic Effects System with Handlers*.
  [[github](https://github.com/vic/nfx)] — Implements algebraic effects
  in pure Nix using a context-passing model with `immediate`/`pending`
  constructors. nix-effects adopted nfx's `adapt` handler combinator,
  `mk { doc, value, tests }` API pattern, and effect module vocabulary
  (`state`, `acc`, `conditions`, `choice`, streams), while building a
  new core on the freer monad encoding from Kiselyov & Ishii (2015)
  and adding value-dependent types and a type-checking kernel that nfx
  does not attempt.


### Internals

#### Trampoline


The trampoline is how nix-effects interprets freer monad computations
with O(1) stack depth in a language with no iteration primitives and no
tail-call optimization.

## The problem

Nix is a pure, lazy, functional language. It has no loops. Every
"iteration" is recursion. A naïve free monad interpreter using mutual
recursion would build a call stack proportional to the computation length:

```
run (bind (bind (bind ... (send "get" null) ...) ...) ...)
  → run step1
    → run step2
      → run step3
        → ...  (N frames deep)

```

For validation of a large DSL value — say, an aspect graph with hundreds
of declarations — this would blow the stack.

## The solution: `builtins.genericClosure`

Nix's `builtins.genericClosure` is the only built-in iterative primitive.
It implements a worklist algorithm:

```
genericClosure {
  startSet = [ initialNode ];
  operator = node -> [ ...nextNodes ];
}

```

`operator` is called on each node. New nodes returned by `operator` are
added to the worklist if their `key` hasn't been seen before. The result
is the set of all reachable nodes.

nix-effects repurposes this as a trampoline: each step of computation is
a node. The `operator` function handles one effect and produces the next
step as a singleton list. The computation terminates when `operator`
returns `[]` (i.e., when we reach a `Pure` node).

```nix
steps = builtins.genericClosure {
  startSet = [{ key = 0; _comp = comp; _state = initialState; }];
  operator = step:
    if isPure step._comp
    then []          # halt
    else [ nextStep ]; # one more step
};

```

Stack depth: **O(1)**. `genericClosure` handles its own iteration
internally; the `operator` function is never deeply nested.

## The thunk problem and `deepSeq`

`genericClosure` only forces the `key` field of each node (for
deduplication). All other fields — including `_state` and `_comp` — are
lazy thunks.

Without intervention, after N steps the `_state` field would be:

```
f(f(f(... f(initialState) ...)))  # N thunks deep

```

Forcing the final `_state` would then rebuild the entire call stack in
thunk evaluation, defeating the purpose.

The fix: make `key` depend on `builtins.deepSeq newState`:

```nix
key = builtins.deepSeq newState (step.key + 1)

```

Since `genericClosure` forces `key`, it also forces `deepSeq newState`,
which eagerly evaluates the state at each step. No thunk chain builds up.

The test suite validates deep effect chains and pure bind chains so the
stack-safety contract stays covered by automated checks.

### State-shape contract

`builtins.deepSeq newState` imposes a contract on handler-state shape: every
value reachable through state must be deepSeq-tolerant. Scalars, finite
records, and lists of scalars satisfy this trivially. Functions are also
safe — `deepSeq` on a closure forces it to WHNF and stops, never recursing
into the captured environment.

`builtins.deepSeq` detects cycles by object identity: `forceValueDeep` keeps a
seen-set of already-forced values, so a self-referential attrset terminates.
That guard has two gaps. A lazy graph that regenerates a fresh object on each
force — as a derivation's `passthru` can — is never recognized as seen and
overflows. And a traversal that keeps no seen-set at all — `builtins.toJSON`,
or the `api.extractValue` walker — descends any cyclic value until the
evaluator overflows. Deep-forcing a real derivation's full attribute closure at
every step is also prohibitively expensive even where it terminates. None of
these failures is recoverable: a stack overflow and `toJSON`'s "cannot convert
a function to JSON" both escape `tryEval`; only `throw` and `assert false` are
catchable, which is why a fuel-bounded walker that throws on exhaustion is the
one usable divergence signal.

This behavior is identical on every evaluator probed — Nix 2.3.18, 2.18.8,
2.24.8, Lix 2.91.1, and 2.35pre — so the contract rests on stable language
semantics, not an evaluator-specific quirk.

For this case the library ships `fx.state.mkThunk` / `forceThunk`
(`src/state/thunk.nix`). The carrier wraps any value as
`{ _tag = "Thunk"; _force = _: value; }` — a closure shields the value
from deepSeq. The companion kernel type former `H.thunk : Hoas → Hoas`
is decided by a *lazy structural* walker: it verifies `is attrset ∧ has
_force closure` and does NOT recurse into `_force`. Inner-type validation
runs at forget time, post-forced. Forcing in the validator would defeat
the deepSeq-shielding the whole construct exists for.

Effect descriptions that carry derivations through state type their payload
fields as `H.thunk H.derivation`, not `H.derivation`, so `fx.send`-time
validation rejects unwrapped drvs before they reach the trampoline. The
inner type is parametric: any value category that needs trampoline transit
can ride through `H.thunk a` with no bespoke primitive.

## Defunctionalization

The interpreter defunctionalizes (**Reynolds 1972**) the recursive handler:
the continuation moves from the call stack into an explicit data structure
(the FTCQueue). The worklist loop processes these continuations iteratively
rather than recursively — the same pattern identified by **Van Horn & Might
(2010)** in *Abstracting Abstract Machines*.

**Gibbons (2022)** *Continuation-Passing Style, Defunctionalization,
Accumulations, and Associativity* shows the hidden precondition: this transformation is valid
when the accumulated operation is associative. For nix-effects, the
handler state transformations compose associatively because function
composition is associative.

## References

- Reynolds, J. C. (1972). *Definitional Interpreters for Higher-Order Programming Languages*. ACM Annual Conference.
- Van Horn, D., & Might, M. (2010). *Abstracting Abstract Machines*. ICFP 2010.
- Gibbons, J. (2022). *Continuation-Passing Style, Defunctionalization, Accumulations, and Associativity*. The Art, Science, and Engineering of Programming, 6(2). [[doi](https://doi.org/10.22152/programming-journal.org/2022/6/7)]
- Kiselyov, O., & Ishii, H. (2015). *Freer Monads, More Extensible Effects*.


#### Kernel Architecture


This chapter describes the type-checking kernel: its pipeline, its
primitives, and how to write verified implementations that the kernel
checks and extracts back to usable Nix functions.

## Two kernels

nix-effects combines an effects kernel with a type-checking kernel:

- The **effects kernel** (`src/kernel.nix`, `src/comp.nix`,
  `src/queue.nix`) implements the freer monad with FTCQueue. It
  defines the `Computation` ADT (`Pure a | Impure (Effect x)
  (FTCQueue x a)`) and the monadic operations `pure`, `impure`,
  `send`, `bind`, `map`, `seq`, `pipe`, `kleisli`.
- The **type-checking kernel** (`src/tc/`) implements Martin-Löf
  type theory with normalization by evaluation and bidirectional
  checking. Core modules define terms, values, evaluation, quotation,
  conversion, and checking; adjacent HOAS, elaboration, generic, and
  ornament modules provide the user-facing structure.

The type-checking kernel's higher layers use the effects kernel for
error reporting. When `check` or `infer` rejects a term, it does not
throw — it calls `send "typeError" { msg; expected; got; term; }`,
producing an `Impure` computation. Handlers in
`src/effects/typecheck.nix` (`strict`, `collecting`, and others)
interpret that request with different strategies: `strict` throws on
the first error, `collecting` accumulates errors into handler state.
The TCB (`eval`, `quote`, `conv`) never sends effects — it only
throws on kernel-invariant violations.

```
Type system API (src/types/)
  Record, ListOf, DepRecord, refined, Pi, Sigma, ...
       |
       | elaboration (src/tc/elaborate/, src/tc/hoas/)
       v
Type-checking kernel (MLTT, src/tc/)
       |
       | typeError sent as effect request
       v
Effects kernel (freer monad + FTCQueue, src/kernel.nix)
       |
       | handler (strict / collecting / ...) interprets effects
       v
Pure Nix
```

Every `fx.types` type carries a `_kernel` field — a HOAS tree that
elaborates to a kernel type. `.check` is derived from
`decide(_kernel, v)`; `.validate` wraps `decide` in a `typeCheck`
effect so handlers can do blame-annotated reporting; `.prove`
type-checks HOAS proof terms; `verifyAndExtract` runs the full
pipeline (check → eval → extract) to produce a Nix value from a HOAS
implementation. Refinement types add a `guard` predicate that runs
alongside the kernel check (`check = kernelDecide(v) ∧ guard(v)`),
handling constraints the kernel cannot express.

## The kernel pipeline

The kernel implements normalization by evaluation (NbE) with
bidirectional type checking. The core pipeline has one responsibility
per module family:

```
term.nix --> eval/ --> value.nix
                              |
                          quote.nix --> term.nix
                              |
                          conv.nix
                              |
                          check/
```

| Module | Function | Signature |
|--------|----------|-----------|
| `term.nix` | Term constructors | `mkVar`, `mkPi`, `mkLam`, `mkApp`, ... |
| `eval/` | Evaluation | `Env × Tm -> Val` |
| `value.nix` | Value constructors | `VLam`, `VPi`, `VPair`, `VMu`, ... |
| `quote.nix` | Quotation | `ℕ × Val -> Tm` |
| `conv.nix` | Conversion checking | `ℕ × Val × Val -> Bool` |
| `check/` | Type checking | `Ctx × Tm × Val -> Tm` / `Ctx × Tm -> Tm × Val` |

**Terms** (`Tm`) are the syntax — de Bruijn indexed expressions with
explicit binding structure. **Values** (`Val`) are the semantics —
fully normalized forms where lambdas carry defunctionalized closures.
The TCB does not use Nix lambdas as semantic closures. **Evaluation**
converts terms to values. **Quotation** reads values back to terms.
**Conversion** checks whether two values are definitionally equal by
comparing their semantic structure.

The type checker is bidirectional:

- `check(Γ, t, T)` — check that term `t` has type `T` (type-directed)
- `infer(Γ, t)` — infer the type of term `t` (term-directed)
- `checkTypeLevel(Γ, T)` — compute the universe level of a type

### Trust model

The kernel has three layers with decreasing trust requirements:

**Layer 0 — Trusted Computing Base.** `eval`, `quote`, `conv`. Pure
functions. No side effects. No imports from the effect system. Bugs
here compromise soundness.

**Layer 1 — Semi-trusted.** `check`, `infer`, `checkTypeLevel`. Uses
the TCB and sends effects for error reporting. Bugs may produce wrong
error messages or reject valid terms, but cannot cause unsoundness.

**Layer 2 — Untrusted.** The elaborator (`hoas/`, `elaborate/`).
Translates surface syntax to core terms. Can have arbitrary bugs
without compromising safety — the kernel verifies the output.

## Axiomatized primitives

The kernel understands eight Nix primitive types as axioms. Each has a
type former, a literal constructor, and a typing rule. None have
eliminators — the kernel says "String is a type at level 0" and "a
string literal inhabits String" but cannot structurally decompose
these values.

| Nix type | Kernel type | Literal | Level |
|----------|-------------|---------|-------|
| `string` | `String` | `StringLit(s)` | 0 |
| `int` | `Int` | `IntLit(n)` | 0 |
| `float` | `Float` | `FloatLit(f)` | 0 |
| `set` | `Attrs` | `AttrsLit` | 0 |
| `path` | `Path` | `PathLit` | 0 |
| `derivation` | `Derivation` | `DerivationLit` | 0 |
| `lambda` | `Function` | `FnLit` | 0 |
| (any) | `Any` | `AnyLit` | 0 |

`Path` is decided by `builtins.isPath`; `Derivation` is decided by
`(v: builtins.isAttrs v && (v.type or null) == "derivation")`. The two
share no values: `Path` rejects attrsets, `Derivation` rejects strings
and non-derivation attrsets.

The structural type formers with kernel introduction and elimination
rules are `Unit`, `Sigma`, `Pi`, bootstrap identity/coproduct
infrastructure, propositional truncation (`Squash`), universe lifting,
function extensionality as an axiom, and the indexed-description family
(`Desc I`, `μ`, `interpD`, `allD`, `everywhereD`, `desc-ind`). Public
`Nat`, `List`, `Sum`, `Bool`, `Eq`, `Fin`, `Vec`, and `W` are generated
through descriptions and the datatype macro. Their eliminators are
generated adapters over `desc-ind`.

This gives the kernel enough structure to compute with generated
inductive families, pairs, and functions, while treating strings,
integers, and other Nix-native types as opaque tokens.

Axiomatized primitives are critical for real-world use. Without them,
verified modules can only work over `Nat`/`Bool`/`List`/`Sigma`/`Sum`.
With them, modules can handle target classes (`String`), dependency
counts (`Int`), declaration records (nested `Sigma`/`Attrs`), and so on.

## HOAS: the surface API

Writing de Bruijn indexed terms by hand is error-prone. The HOAS
(Higher-Order Abstract Syntax) layer lets you use Nix lambdas for
variable binding. The public API is `fx.types.hoas`.

### Type combinators

```nix
H = fx.types.hoas;

H.nat                         # Nat
H.bool                        # Bool
H.string                      # String
H.int_                        # Int
H.float_                      # Float
H.unit                        # Unit (nullary product)
H.void                        # Void (empty type)
H.listOf H.nat                # List Nat
H.sum H.nat H.bool            # Nat + Bool
H.forall "x" H.nat (_: H.bool)  # Π(x : Nat). Bool
H.sigma "x" H.nat (_: H.bool)   # Σ(x : Nat). Bool
H.u 0                         # U₀ (universe of small types)
```

### Term combinators

```nix
# Lambda: λ(x : Nat). x
H.lam "x" H.nat (x: x)

# Application
H.app f arg

# Natural number literals
H.zero                        # 0
H.succ H.zero                 # 1
H.natLit 42                   # 42 (sugar for 42 succs)

# Boolean literals
H.true_
H.false_

# Pairs
H.pair fst snd

# Projections
H.fst_ p
H.snd_ p

# Sum injections
H.inl leftTy rightTy term
H.inr leftTy rightTy term

# String / Int / Float literals
H.stringLit "hello"
H.intLit 42
H.floatLit 3.14

# Type annotation
H.ann term type
```

### Eliminators

```nix
# Natural number induction
H.ind motive base step scrut

# Boolean elimination (k : Level is the motive's universe level)
H.boolElim k motive onTrue onFalse scrut

# List elimination
H.listElim elemType motive onNil onCons scrut

# Sum elimination
H.sumElim leftTy rightTy motive onLeft onRight scrut

# Equality elimination (J)
H.j type lhs motive base rhs eq
```

### How HOAS compiles

Binding combinators produce HOAS markers — lightweight attrsets that
stand for bound variables at a specific depth. The `elaborate`
function (in `hoas.nix`) converts these to de Bruijn indexed `Tm`
terms:

```
H.lam "x" H.nat (x: H.succ x)
  │
  │ HOAS: x is a marker { _hoas = true; level = 0; }
  │
  ▼ elaborate (depth=0)
  │
  │ marker at level 0 -> T.mkVar(0 - 0 - 1) = T.mkVar(0)
  │
  ▼
Lam("x", Nat, Succ(Var(0)))   ← de Bruijn term
```

The elaboration of nested binding forms is trampolined via
`builtins.genericClosure` for stack safety on deeply nested terms.

## The elaboration bridge

The elaboration bridge (`elaborate.nix`) connects the user-facing type
system to the kernel. It has six operations:

| Operation | Signature | Direction |
|-----------|-----------|-----------|
| `elaborateType` | `FxType -> HoasTree` | type system -> kernel |
| `elaborateValue` | `HoasTree × NixVal -> HoasTree` | Nix value -> kernel term |
| `extract` | `HoasTree × Val -> NixValue` | kernel value -> Nix value |
| `decide` | `HoasTree × NixVal -> Bool` | decision procedure |
| `decideType` | `FxType × NixVal -> Bool` | elaborate type, then decide |
| `verifyAndExtract` | `HoasTree × HoasTree -> NixValue` | full pipeline |

### elaborateType

Converts an `fx.types` type into a HOAS tree. Dispatches on three
things, in order:

1. The `_kernel` field (types built via `mkType` with `kernelType`)
2. Structural fields (Pi: `domain`/`codomain`, Sigma: `fstType`/`sndFamily`)
3. Name convention (`"Bool"` -> `H.bool`, `"String"` -> `H.string`, etc.)

### elaborateValue

Converts a Nix value into a HOAS term, guided by a HOAS type. For
example, given `H.nat` and the Nix integer `3`, produces
`H.succ (H.succ (H.succ H.zero))`. Given `H.string` and `"hello"`,
produces `H.stringLit "hello"`.

### extract — the reverse direction

`extract` converts kernel values back to Nix values. It is the reverse
of `elaborateValue`. This is where the verification story becomes
interesting: you write an implementation as a HOAS term, the kernel
verifies it, `eval` produces a kernel value, and `extract` converts
the result to a usable Nix value.

```nix
# extract : HoasTree -> Val -> NixValue
extract H.nat (VDescCon ... <succ payload>)        # -> 2
extract H.bool (VDescCon ... <true payload>)       # -> true
                                                     # H.bool is derived
extract H.string (VStringLit "hi")                 # -> "hi"
extract (H.listOf H.nat) (VDescCon ... <cons ...>) # -> [1 2 3]
extract (H.forall "x" ...) (VLam ...)              # -> Nix function (!)
```

The Pi case is the most important. Extracting a verified function
produces a Nix function that:

1. Elaborates its argument into a kernel value (Nix -> kernel)
2. Applies the kernel-verified closure
3. Extracts the result back (kernel -> Nix)

Correct by construction — the kernel verified the term, `eval`
produced the closure, `extract` wraps with value conversion at the
boundaries.

### decide

The decision procedure. Returns `true` iff both elaboration and
kernel type-checking succeed:

```nix
decide = hoasTy: value:
  let
    result = builtins.tryEval (
      let
        hoasVal = elaborateValue hoasTy value;
        checked = H.checkHoas hoasTy hoasVal;
      in !(checked ? error)
    );
  in result.success && result.value;
```

This is the function that `mkType` uses to derive `.check`. Every
type's `.check` is `v: decide(kernelType, v)` — no hand-written
predicates.

### verifyAndExtract — the full pipeline

Type-check a HOAS term against a HOAS type, then extract the result:

```nix
verifyAndExtract = hoasTy: hoasImpl:
  let
    checked = H.checkHoas hoasTy hoasImpl;
  in if checked ? error
    then throw "verifyAndExtract: type check failed"
    else
      let
        tm = H.elab hoasImpl;         # HOAS -> de Bruijn
        val = E.eval [] tm;           # evaluate to Val
      in extract hoasTy val;          # Val -> Nix value
```

## Convenience combinators

Raw HOAS is verbose. The convenience combinator layer (`fx.types.verified`,
accessed as `v`) provides sugar that produces valid HOAS term trees:

```nix
v = fx.types.verified;
H = fx.types.hoas;
```

### Literals

```nix
v.nat 5          # H.natLit 5
v.str "hello"    # H.stringLit "hello"
v.int_ 42        # H.intLit 42
v.float_ 3.14    # H.floatLit 3.14
v.true_          # H.true_
v.false_         # H.false_
v.null_          # H.tt (unit)
```

### Binding forms

```nix
# Lambda: λ(x : Nat). body
v.fn "x" H.nat (x: body)

# Let: let x : Nat = 5 in body
v.let_ "x" H.nat (v.nat 5) (x: body)
```

### Eliminators with inferred motives

The convenience combinators construct the required motive automatically
from the result type. The motive is always constant (non-dependent):
`λ_. resultTy`.

```nix
# Boolean: if b then 1 else 0
v.if_ H.nat v.true_ { then_ = v.nat 1; else_ = v.nat 0; }

# Natural number: pattern match on n
v.match H.nat n {
  zero = v.nat 42;
  succ = k: ih: H.succ ih;
}

# List: fold over elements
v.matchList H.nat H.nat list {
  nil = v.nat 0;
  cons = h: t: ih: H.succ ih;   # count elements
}

# Sum: case split
v.matchSum H.nat H.bool H.nat scrut {
  left = x: H.succ x;
  right = _: v.nat 0;
}
```

### Derived combinators

```nix
# Map: apply f to each element
v.map H.nat H.nat succFn myList

# Fold: combine elements with accumulator
v.fold H.nat H.nat (v.nat 0) addFn myList

# Filter: keep elements matching predicate
v.filter H.nat isZeroFn myList
```

### Pairs and sums

```nix
v.pair fstTerm sndTerm sigmaType
v.fst p
v.snd p
v.inl leftTy rightTy term
v.inr leftTy rightTy term
v.app f arg
```

### The verify pipeline

`v.verify` wraps `verifyAndExtract` — type-check and extract in one
call:

```nix
v.verify type implementation
# = verifyAndExtract type implementation
```

## Writing verified implementations

The key insight: instead of writing Nix functions and trying to
elaborate them into kernel terms (which fails for closures), write
implementations as HOAS terms and **extract** Nix functions out. This
is the approach taken by Coq (extraction), Idris (compilation), and
F\*.

### Example: verified addition

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  addTy = H.forall "m" H.nat (_: H.forall "n" H.nat (_: H.nat));
  addImpl = v.fn "m" H.nat (m: v.fn "n" H.nat (n:
    v.match H.nat m {
      zero = n;
      succ = _k: ih: H.succ ih;
    }));

  # Kernel verifies: addImpl : Π(m:Nat). Π(n:Nat). Nat
  # Then extracts a 2-argument Nix function
  add = v.verify addTy addImpl;
in
  add 2 3    # -> 5
```

What happens step by step:

1. `v.verify` calls `H.checkHoas addTy addImpl` — the kernel
   type-checks the HOAS term against the HOAS type
2. `H.elab addImpl` converts HOAS to de Bruijn indexed `Tm`
3. `E.eval [] tm` evaluates to a `VLam` value (a Nix closure via NbE)
4. `extract addTy val` wraps the `VLam` as a Nix function that
   elaborates arguments at call boundaries

The resulting `add` is an ordinary Nix function. Call it with Nix
integers. At each call, the argument is elaborated into a kernel
value, the verified closure runs, and the result is extracted back.

### Example: verified list operations

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  # Successor function: Nat -> Nat
  succFn = v.fn "x" H.nat (x: H.succ x);

  # Map successor over a list
  input = H.cons H.nat (v.nat 0)
    (H.cons H.nat (v.nat 1)
      (H.cons H.nat (v.nat 2) (H.nil H.nat)));

  result = v.verify (H.listOf H.nat) (v.map H.nat H.nat succFn input);
in
  result    # -> [1 2 3]
```

### Example: verified filter

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  # isZero : Nat -> Bool
  isZero = v.fn "n" H.nat (n:
    v.match H.bool n {
      zero = v.true_;
      succ = _k: _ih: v.false_;
    });

  input = H.cons H.nat (v.nat 0)
    (H.cons H.nat (v.nat 1)
      (H.cons H.nat (v.nat 0)
        (H.cons H.nat (v.nat 2) (H.nil H.nat))));

  result = v.verify (H.listOf H.nat) (v.filter H.nat isZero input);
in
  result    # -> [0 0]
```

## The verification spectrum

The architecture supports a spectrum of assurance levels. Each level
offers a different trade-off between verification strength and
implementation cost.

### Level 1: Contract

The baseline. Types check values at introduction via `.check` (which
calls `decide` under the hood). No HOAS, no proof terms — just write
normal Nix code and let the type system validate data at boundaries.

```nix
let
  inherit (fx.types) String refined;

  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);

  # Refinement with string guard — kernel checks String, guard checks membership
  LogLevel = refined "LogLevel" String
    (x: builtins.elem x [ "debug" "info" "warn" "error" ]);
in {
  module = TargetClass.check "module"; # true
  fleet = TargetClass.check "fleet"; # false

  info  = LogLevel.check "info";    # true
  trace = LogLevel.check "trace";   # false — not in the allowed set

  # Effectful validation with blame context
  result = fx.run (TargetClass.validate "fleet")
    fx.effects.typecheck.collecting [];
  # result.state = [ { context = "TargetClass"; ... } ]
}
```

**Cost:** Zero — write normal Nix. The kernel runs behind the scenes.
Refinement types compose: `ListOf TargetClass` checks that every element
is a known renderer class. The kernel elaborates the list, the guard
runs per element.

### Level 2: Boundary

Data values are checked by the kernel at module interfaces. Types
carry `kernelType` and `.check` is derived from the kernel's `decide`
procedure. This is what every type does by default.

```nix
let
  inherit (fx.types) Bool String ListOf DepRecord refined;

  TargetClass = refined "TargetClass" String
    (x: builtins.elem x [ "module" "file" "package" "check" ]);

  # Dependent record: generated aspects must target a known renderer class.
  # The kernel elaborates the record to a Sigma chain, checks each field's type
  # against its kernelType, and the guard on TargetClass validates membership.
  AspectDecl = DepRecord [
    { name = "generated"; type = Bool; }
    { name = "target"; type = self:
        if self.generated then TargetClass else String; }
    { name = "requires"; type = _: ListOf String; }
  ];
in {
  ok = AspectDecl.checkFlat {
    generated = true;
    target = "module";
    requires = [ "toolchain" ];
  };   # true

  bad = AspectDecl.checkFlat {
    generated = true;
    target = "fleet";
    requires = [ ];
  };   # false

  external = AspectDecl.checkFlat {
    generated = false;
    target = "external-renderer";
    requires = [ ];
  };   # true
}
```

**Cost:** Low — add `kernelType` to custom types (built-in types
already have it). The dependent record pattern shows how boundary
checking scales: the kernel handles structural verification, guards
handle domain predicates, and the dependency between fields is
resolved at check time.

### Level 3: Property

Universal properties verified via proof terms. Write proofs in HOAS
that the kernel checks. The proof term is separate from the
implementation — you write separate Nix code alongside, and the
kernel verifies that the stated property holds.

```nix
let
  H = fx.types.hoas;
  inherit (H) nat bool eq forall refl checkHoas;

  # Define addition by structural recursion on the first argument
  add = m: n:
    H.ind (H.lam "_" nat (_: nat)) n
      (H.lam "k" nat (_: H.lam "ih" nat (ih: H.succ ih))) m;

  not_ = b:
    H.boolElim 0 (H.lam "_" bool (_: bool)) H.false_ H.true_ b;
in {
  # Prove: 3 + 5 = 8
  # The kernel normalizes add(3,5) via generated natural induction,
  # then confirms Refl witnesses Eq(Nat, 8, 8).
  arithmetic = (checkHoas
    (eq nat (add (H.natLit 3) (H.natLit 5)) (H.natLit 8))
    refl).tag == "refl";

  # Prove: not(not(true)) = true
  # The kernel evaluates two BoolElim steps and confirms the result.
  doubleNeg = (checkHoas
    (eq bool (not_ (not_ H.true_)) H.true_)
    refl).tag == "refl";

  # Prove: append([1,2], [3]) = [1,2,3]
  # Generated list induction unfolds the first list onto [3].
  listAppend = let
    list12  = H.cons nat (H.natLit 1) (H.cons nat (H.natLit 2) (H.nil nat));
    list3   = H.cons nat (H.natLit 3) (H.nil nat);
    list123 = H.cons nat (H.natLit 1) (H.cons nat (H.natLit 2)
                (H.cons nat (H.natLit 3) (H.nil nat)));
    append = xs: ys:
      H.listElim nat (H.lam "_" (H.listOf nat) (_: H.listOf nat)) ys
        (H.lam "h" nat (h: H.lam "t" (H.listOf nat) (_:
          H.lam "ih" (H.listOf nat) (ih: H.cons nat h ih)))) xs;
  in (checkHoas (eq (H.listOf nat) (append list12 list3) list123) refl).tag == "refl";
}
```

**Cost:** Medium — write proofs in HOAS. The proofs are separate from
production code, so you can add them incrementally to an existing
codebase without rewriting anything.

### Level 4: Full

The implementation IS the proof term. Write the entire implementation
in HOAS, the kernel verifies it, and `extract` produces a Nix
function that is correct by construction. The extracted function is
plain Nix — no kernel overhead at call time.

```nix
let
  H = fx.types.hoas;
  v = fx.types.verified;

  AspectDecl = H.record [
    { name = "name";     type = H.string; }
    { name = "target";   type = H.string; }
    { name = "requires"; type = H.listOf H.string; }
  ];

  targets =
    H.cons H.string (v.str "module")
      (H.cons H.string (v.str "file")
        (H.cons H.string (v.str "package")
          (H.cons H.string (v.str "check") (H.nil H.string))));

  # Verified aspect validator: checks that the target class is supported.
  # The kernel type-checks the implementation against AspectDecl -> Bool,
  # verifies field projections, and confirms strElem composes correctly.
  validateAspect = v.verify (H.forall "a" AspectDecl (_: H.bool))
    (v.fn "a" AspectDecl (a:
      v.strElem (v.field AspectDecl "target" a) targets));

  # Verified addition: structural recursion extracted as Nix function
  add = v.verify (H.forall "m" H.nat (_: H.forall "n" H.nat (_: H.nat)))
    (v.fn "m" H.nat (m: v.fn "n" H.nat (n:
      v.match H.nat m {
        zero = n;
        succ = _k: ih: H.succ ih;
      })));
in {
  sum   = add 2 3;    # -> 5, correct by construction
  ok    = validateAspect {
    name = "workspace-shell";
    target = "module";
    requires = [ "toolchain" ];
  };   # -> true
  bad   = validateAspect {
    name = "workspace-aspect";
    target = "fleet";
    requires = [ ];
  };   # -> false
}
```

**Cost:** High — write the implementation in HOAS. Best reserved for
code where the cost is justified by the assurance. See the
[Proof Guide](/nix-effects/guide/proof-guide) for a progressive
tutorial from simple proofs through the J eliminator to verified
extraction of plain Nix functions.

## How mkType derives .check

Every type is built by `mkType` (in `foundation.nix`). The kernel
type IS the type. `.check` is its decision procedure, derived
mechanically:

```
_kernel : HoasType        ← the type IS this
check : Value -> Bool       ← derived from decide(kernelType, value)
kernelCheck : Value -> Bool ← same as check (legacy alias)
prove : HoasTerm -> Bool    ← kernel proof checking
universe : Int             ← computed from checkTypeLevel(kernelType)
```

For refinement types, an optional `guard` adds a runtime predicate
on top of the kernel check: `check = decide(kernelType, v) && guard(v)`.
The guard handles predicates the kernel cannot express — for example,
`x >= 0` for natural numbers, or membership in a finite set for
validated strings.

## Limitations

**Nix closures are opaque.** `decide(H.forall ..., f)` can only
check `builtins.isFunction f`. For full function verification, write
the function in HOAS and use `v.verify` to extract.

**Refinement predicates are opaque.** The kernel cannot represent
`x >= 0` as a type-level assertion. Refinement types always need a
hand-written guard predicate.

**`builtins.tryEval` is limited.** It only catches `throw` and
`assert false`. Cross-type comparison errors, boolean coercion errors,
and missing attribute access crash Nix uncatchably. This affects
`decide` for types whose elaboration might trigger such errors.

**Dependent extraction is limited.** Extracting a dependent Pi or
Sigma requires a sentinel test to detect non-dependence. If the
type family is truly dependent, extraction throws and requires
explicit type annotation.

**Opaque types cannot be extracted.** `Attrs`, `Path`, `Derivation`,
`Function`, and `Any` are axiomatized — the kernel knows they exist
but discards their payloads. Extracting a value of these types throws.
They work for type-checking (deciding membership) but not for the full
verify-and-extract pipeline.

**Extraction has boundary cost.** Extracted functions elaborate their
arguments at every call (Nix -> kernel value -> apply -> extract -> Nix).
For hot paths, the contract layer's `.check` fast path is more
efficient.


#### Kernel Formal Specification


This document is the contract the implementation must satisfy. Every
typing rule, compute rule, and conversion rule is stated precisely.
Every test is derived from this spec. Every invariant the kernel must
maintain is listed.

The spec uses standard type-theoretic notation. No Nix code appears
here — this document is reviewable by anyone who reads dependent type
theory, regardless of implementation language.

---

## 1. Trust Model

The kernel has three layers with strictly decreasing trust requirements.

**Layer 0 — Trusted Computing Base (TCB).** The evaluator, quotation,
and conversion checker. Pure functions. No side effects. No imports
from the effect system. Bugs here compromise soundness. Every line
must be auditable.

- `eval : Env × Tm → Val`
- `quote : ℕ × Val → Tm`
- `conv : ℕ × Val × Val → Bool`

**Layer 1 — Semi-trusted.** The bidirectional type checker. Uses the
TCB and sends effects for error reporting. Bugs here may produce wrong
error messages or reject valid terms, but cannot cause unsoundness
(the TCB rejects ill-typed terms independently).

- `check : Ctx × Tm × Val → Tm`
- `infer : Ctx × Tm → Tm × Val`
- `checkTypeLevel : Ctx × Tm → Tm × ℕ`

**Layer 2 — Untrusted.** The elaborator. Translates surface syntax
(named variables, implicit arguments, level inference, eta-insertion)
into fully explicit core terms. Can have arbitrary bugs without
compromising safety — the kernel verifies the output.

### Failure modes

| Condition | Response | Rationale |
|-----------|----------|-----------|
| Kernel invariant violation | `throw` (crash) | TCB may be buggy; cannot trust own output |
| User type error | Effect `typeError` | Normal operation; handler decides policy |
| Normalization budget exceeded | `throw` (crash) | Layer 0 has no effect access; `tryEval` catches it |
| Unknown term tag | `throw` (crash) | Exhaustiveness violation = kernel bug |

---

## 2. Syntax

### 2.1 Terms (Tm)

The core term language. All binding uses de Bruijn indices. Name
annotations are cosmetic (for error messages only).

```
Tm ::=
  -- Variables and binding
  | Var(i : ℕ)                             -- de Bruijn index
  | Let(n : Name, A : Tm, t : Tm, u : Tm)  -- let n : A = t in u

  -- Functions
  | Pi(n : Name, A : Tm, B : Tm)       -- Π(n : A). B
  | Lam(n : Name, A : Tm, t : Tm)      -- λ(n : A). t
  | App(t : Tm, u : Tm)                -- t u

  -- Pairs
  | Sigma(n : Name, A : Tm, B : Tm)     -- Σ(n : A). B
  | Pair(a : Tm, b : Tm)                -- (a, b)
  | Fst(t : Tm)                         -- π₁ t
  | Snd(t : Tm)                         -- π₂ t

  -- Unit
  | Unit                                -- ⊤
  | Tt                                  -- tt

  -- Empty
  | Empty                               -- ⊥
  | Absurd(P : Tm, x : Tm)              -- empty-type eliminator

  -- Bootstrap coproduct, private to descPlus interpretation
  | BootSum(A : Tm, B : Tm)             -- A + B
  | BootInl(A : Tm, B : Tm, t : Tm)     -- inl t
  | BootInr(A : Tm, B : Tm, t : Tm)     -- inr t
  | BootSumElim(A : Tm, B : Tm, P : Tm, l : Tm, r : Tm, s : Tm)
    -- private eliminator for descPlus payloads

  -- Bootstrap identity, private to descRet/Lift/index transport
  | BootEq(A : Tm, a : Tm, b : Tm)      -- internal Id_A(a, b)
  | BootRefl                            -- internal refl
  | BootJ(A : Tm, a : Tm, P : Tm, pr : Tm, b : Tm, eq : Tm)
    -- private identity eliminator
  | Funext                              -- function extensionality axiom

  -- Propositional truncation
  | Squash(A : Tm)                      -- proof-irrelevant truncation
  | SquashIntro(a : Tm)                 -- introduction into Squash
  | SquashElim(A : Tm, B : Tm, f : Tm, x : Tm)
    -- recTrunc: A -> Squash B, Squash A -> Squash B

  -- Levels (Tarski-style sort of universe levels — see §6.6, §8.5)
  | Level                               -- the Level sort itself, lives at U(0)
  | LevelZero                           -- 0
  | LevelSuc(k : Tm)                    -- successor: k+1
  | LevelMax(a : Tm, b : Tm)            -- join in the level semilattice

  -- Universes (level-indexed, k : Level)
  | U(k : Tm)                           -- Type_k

  -- Descriptions (universe-polymorphic; see §7.6)
  | Desc(K : Tm, I : Tm)                -- Desc^K I — descriptions over index type I
  | DescRet(j : Tm)                     -- ret(j) — leaf returning at index j
  | DescArg(K : Tm, S : Tm, T : Tm)     -- arg^K S T — non-recursive Π over S : U(K)
  | DescRec(j : Tm, D : Tm)             -- rec(j) D — recursive child at index j, then D
  | DescPi(K : Tm, S : Tm, f : Tm, D : Tm)
                                        -- π^K S f D — recursive Π over S : U(K), indexed by f
  | DescPlus(A : Tm, B : Tm)            -- A + B — first-class binary coproduct of descriptions
  | DescDescApp(I : Tm, L : Tm)         -- canonical descDesc I L reference
  | InterpD(level : Tm, I : Tm, D : Tm, X : Tm, i : Tm)
                                        -- interpretation of D at index i
  | AllD(level : Tm, I : Tm, D : Tm, K : Tm, X : Tm, M : Tm, i : Tm, d : Tm)
                                        -- all recursive positions satisfy M
  | EverywhereD(level : Tm, I : Tm, D : Tm, K : Tm, X : Tm, M : Tm,
                ih : Tm, i : Tm, d : Tm)
                                        -- builds AllD evidence from ih
  | DescInd(D : Tm, motive : Tm, step : Tm, i : Tm, scrut : Tm)
                                        -- generic μ-induction over D at index i

  -- μ-types (description-induced datatypes)
  | Mu(I : Tm, D : Tm, i : Tm)          -- μ I D i — the i-th type in the family classified by D
  | DescCon(D : Tm, i : Tm, payload : Tm)
                                        -- introduction at index i with payload : interp(D, i)

  -- Annotations
  | Ann(t : Tm, A : Tm)                -- (t : A); may carry trusted/label sidecars

  -- Lift
  | Lift(l : Tm, m : Tm, eq : Tm, A : Tm)
  | LiftIntro(l : Tm, m : Tm, eq : Tm, A : Tm, a : Tm)
  | LiftElim(l : Tm, m : Tm, eq : Tm, A : Tm, x : Tm)

  -- Axiomatized primitive types
  | String                              -- string type
  | Int                                 -- integer type
  | Float                               -- float type
  | Attrs                               -- attribute set type
  | Path                                -- path type
  | Derivation                          -- derivation attrset type
  | Function                            -- opaque function type
  | Any                                 -- dynamic/any type

  -- String operations
  | StrEq(lhs : Tm, rhs : Tm)          -- string equality: lhs == rhs → H.bool (derived)

  -- Primitive literals
  | StringLit(s)                        -- string literal
  | IntLit(n)                           -- integer literal
  | FloatLit(f)                         -- float literal
  | AttrsLit                            -- attribute set literal
  | PathLit                             -- path literal
  | DerivationLit                       -- derivation attrset literal
  | FnLit                               -- opaque function literal
  | AnyLit                              -- any literal

  -- Opaque lambda trust boundary for extracted Nix functions
  | OpaqueLam(fnBox, piTy : Tm)

  -- Closed-Val splice (two-level TT reflection)
  | LitVal(v : Val)                     -- opaque carrier; eval is identity on v

```

Public `Nat`, `List`, `Sum`, `Bool`, `Fin`, `Vec`, `Eq`, and `W` are
not primitive core syntax.
The HOAS prelude generates them as descriptions:

```
H.nat        = Mu(Unit, NatDT.D, Tt)
H.listOf A   = Mu(Unit, ListDT.D A, Tt)
H.sum A B    = Mu(Unit, SumDT.D 0 A B, Tt)
H.eq A a b   = Mu(A, EqDT.D A a, b)

```

Their constructors and eliminators elaborate to `DescCon` and
`DescInd` applications through the datatype macro layer. The kernel
therefore exposes one public induction principle for data: `DescInd`.
The bootstrap coproduct and bootstrap identity above remain internal
support for description interpretation, `DescRet`, `Lift`, and index
transport.

### 2.2 Binding convention

In `Pi(n, A, B)`, `Lam(n, A, t)`, `Sigma(n, A, B)`, and `Let(n, A, t, u)`:
the body (`B`, `t`, or `u`) binds one variable. Index 0 in the body
refers to the bound variable. All other indices shift by 1.

Eliminators take their motives as ordinary function terms, not as
implicit binders. Generated public eliminators build typed HOAS
applications to datatype-specific eliminator functions; the core
eliminator underneath is `DescInd`.

### 2.3 De Bruijn index conventions

Indices count inward from the use site: 0 = most recent binder.

Example: `λ(x : A). λ(y : B). x` is `Lam(x, A, Lam(y, B, Var(1)))`.

---

## 3. Values (Semantic Domain)

Values are the result of evaluation. They use de Bruijn **levels**
(counting outward from the top of the context) instead of indices.

```
Val ::=
  -- Functions
  | VPi(n : Name, A : Val, cl : Closure)   -- Π type
  | VLam(n : Name, A : Val, cl : Closure)  -- λ abstraction

  -- Pairs
  | VSigma(n : Name, A : Val, cl : Closure) -- Σ type
  | VPair(a : Val, b : Val)                  -- pair value

  -- Unit
  | VUnit
  | VTt

  -- Empty
  | VEmpty

  -- Bootstrap coproduct, private to descPlus interpretation
  | VBootSum(A : Val, B : Val)
  | VBootInl(A : Val, B : Val, v : Val)
  | VBootInr(A : Val, B : Val, v : Val)

  -- Bootstrap identity, private to descRet/Lift/index transport
  | VBootEq(A : Val, a : Val, b : Val)
  | VBootRefl
  | VFunext

  -- Propositional truncation
  | VSquash(A : Val)
  | VSquashIntro(a : Val)

  -- Levels (Tarski-style sort of universe levels — see §6.6, §8.5)
  | VLevel                                -- the Level sort itself
  | VLevelZero                            -- 0
  | VLevelSuc(pred : Val)                 -- successor
  | VLevelMax(lhs : Val, rhs : Val)       -- join

  -- Universes (level-indexed, k : VLevel)
  | VU(k : Val)

  -- Descriptions (universe-polymorphic; see §7.6)
  | VDesc(K : Val, I : Val)                -- Desc^K I
  -- Description constructors are encoded as VDescCon inhabitants of
  -- μ Unit (descDesc I K) tt. Evaluation projects them through the private
  -- DViewRet/DViewArg/DViewRec/DViewPi/DViewPlus semantic view.

  -- μ-types
  | VMu(I : Val, D : Val, i : Val)          -- μ I D i
  | VDescCon(D : Val, i : Val, d : Val)     -- introduction at index i with payload d
  | VInterpD(level : Val, I : Val, D : Val, X : Val, i : Val)
  | VAllD(level : Val, I : Val, D : Val, K : Val, X : Val, M : Val, i : Val, d : Val)
  | VEverywhereD(level : Val, I : Val, D : Val, K : Val, X : Val, M : Val,
                 ih : Val, i : Val, d : Val)

  -- Lift
  | VLift(l : Val, m : Val, eq : Val, A : Val)
  | VLiftIntro(l : Val, m : Val, eq : Val, A : Val, a : Val)

  -- Axiomatized primitive types
  | VString | VInt | VFloat | VAttrs | VPath | VDerivation | VFunction | VAny

  -- Primitive literal values
  | VStringLit(s) | VIntLit(n) | VFloatLit(f)
  | VAttrsLit | VPathLit | VDerivationLit | VFnLit | VAnyLit
  | VOpaqueLam(fnBox, piTy : Val)

  -- Neutrals (stuck computations)
  | VNe(level : ℕ, spine : [Elim])

Elim ::=
  | EApp(v : Val)
  | EFst
  | ESnd
  | EBootSumElim(A : Val, B : Val, P : Val, l : Val, r : Val)
  | EBootJ(A : Val, a : Val, P : Val, pr : Val, b : Val)
  | EStrEq(arg : Val)
  | EAbsurd(P : Val)
  | EDescInd(D : Val, motive : Val, step : Val, i : Val)
  | EInterpD(level : Val, I : Val, X : Val, i : Val)
  | EAllD(level : Val, I : Val, K : Val, X : Val, M : Val, i : Val, d : Val)
  | EEverywhereD(level : Val, I : Val, K : Val, X : Val, M : Val,
                 ih : Val, i : Val, d : Val)
  | ELiftElim(l : Val, m : Val, eq : Val, A : Val)
  | ESquashElim(A : Val, B : Val, f : Val)

Closure ::= (env : Env, body : Tm)
Env     ::= [Val]          -- list indexed by de Bruijn index

```

### 3.1 Level/index relationship

De Bruijn levels count from the outermost binder: 0 = first-ever
bound variable. Levels are stable under context extension.

Conversion between index and level:

```
index = depth - level - 1
level = depth - index - 1

```

where `depth` is the current binding depth (length of the context).

### 3.2 Fresh variables

A fresh variable at depth `d` is `VNe(d, [])` — a neutral with
level `d` and empty spine. Used in conversion checking to compare
under binders.

### 3.3 Closure instantiation

```
instantiate((env, body), v) = eval([v] ++ env, body)

```

---

## 4. Evaluation Rules

`eval(ρ, t)` interprets term `t` in environment `ρ`, producing
a value. All rules are deterministic.

### 4.1 Variables and let

```
eval(ρ, Var(i))           = ρ[i]
eval(ρ, Let(n, A, t, u))  = eval([eval(ρ, t)] ++ ρ, u)
eval(ρ, Ann(t, A))        = eval(ρ, t)

```

### 4.2 Functions

```
eval(ρ, Pi(n, A, B))   = VPi(n, eval(ρ, A), (ρ, B))
eval(ρ, Lam(n, A, t))  = VLam(n, eval(ρ, A), (ρ, t))
eval(ρ, App(t, u))     = vApp(eval(ρ, t), eval(ρ, u))

```

where `vApp` performs beta reduction or accumulates:

```
vApp(VLam(n, A, cl), v)  = instantiate(cl, v)
vApp(VNe(l, sp), v)      = VNe(l, sp ++ [EApp(v)])
vApp(_, _)               = THROW "kernel bug: vApp on non-function"

```

### 4.3 Pairs

```
eval(ρ, Sigma(n, A, B))  = VSigma(n, eval(ρ, A), (ρ, B))
eval(ρ, Pair(a, b))      = VPair(eval(ρ, a), eval(ρ, b))
eval(ρ, Fst(t))          = vFst(eval(ρ, t))
eval(ρ, Snd(t))          = vSnd(eval(ρ, t))

```

where:

```
vFst(VPair(a, b))   = a
vFst(VNe(l, sp))    = VNe(l, sp ++ [EFst])
vFst(_)             = THROW "kernel bug: vFst on non-pair"

vSnd(VPair(a, b))   = b
vSnd(VNe(l, sp))    = VNe(l, sp ++ [ESnd])
vSnd(_)             = THROW "kernel bug: vSnd on non-pair"

```

### 4.4 Generated data families

Natural numbers, lists, public sums, and public equality are prelude
datatypes generated from descriptions. Their types evaluate to
`VMu I D i`; their constructors evaluate to `VDescCon D i payload`;
their eliminators elaborate to `DescInd` over the generated description.

```text
H.nat              == μ Unit NatDT.D tt
H.zero             == descCon NatDT.D tt <zero payload>
H.succ n           == descCon NatDT.D tt <succ payload n>
H.listOf A         == μ Unit (ListDT.D A) tt
H.nil A            == descCon (ListDT.D A) tt <nil payload>
H.cons A h t       == descCon (ListDT.D A) tt <cons payload h t>
H.sum A B          == μ Unit (SumDT.D 0 A B) tt
H.eq A a b         == μ A (EqDT.D A a) b
```

The generated constructor payloads still use private bootstrap
coproduct/identity values where the description interpretation requires
them. These are representation details, not public eliminators.

Deep generated natural/list values are stack-safe through the constructor
flattening and `desc-con` trampoline paths, rather than through primitive
nat/list evaluator cases.

### 4.5 Description interpretation, Lift, Squash, and Funext

The current kernel includes several small primitives used by generated
datatypes and proof-oriented APIs:

```text
eval(ρ, DescDescApp(I,L))              = tagged descDesc value
eval(ρ, InterpD(level,I,D,X,i))        = vInterpD(level,I,D,X,i)
eval(ρ, AllD(level,I,D,K,X,M,i,d))     = vAllD(level,I,D,K,X,M,i,d)
eval(ρ, EverywhereD(level,I,D,K,X,M,ih,i,d)) =
  vEverywhereD(level,I,D,K,X,M,ih,i,d)

eval(ρ, Lift(l,m,eq,A))                = vLiftF(l,m,eq,A)
eval(ρ, LiftIntro(l,m,eq,A,a))         = vLiftIntroF(l,m,eq,A,a)
eval(ρ, LiftElim(l,m,eq,A,x))          = vLiftElimF(l,m,eq,A,x)

eval(ρ, Squash(A))                     = VSquash(eval(ρ,A))
eval(ρ, SquashIntro(a))                = VSquashIntro(eval(ρ,a))
eval(ρ, SquashElim(A,B,f,x))           = vSquashElim(eval(ρ,A), eval(ρ,B), eval(ρ,f), eval(ρ,x))

eval(ρ, Funext)                        = VFunext
eval(ρ, OpaqueLam(fnBox, piTy))        = VOpaqueLam(fnBox, eval(ρ,piTy))
eval(ρ, LitVal(v))                     = v
```

`LitVal v` is the splice operator of two-level type theory (Kovács,
"Staged Compilation with Two-Level Type Theory", POPL 2024;
Annenkov–Capriotti–Kraus–Sattler 2019): a closed semantic value
reflected into the syntactic domain. The eval rule discards the
environment, so the carried `v` must be closed (free de Bruijn levels
would never resolve). Quotation reads through to the underlying value
— `LitVal` is invisible at the Val layer, so conv, quote, and the
ι/β/η rules operate on `v` directly without any new transparency rule.

The kernel uses `LitVal` as the canonical Val→Tm lift on paths that
would otherwise call `quote 0 v` on a value destined for re-evaluation
(notably the effect-handler bridge in
`src/experimental/desc-interp/trampoline.nix`). Reflection avoids
the O(size v) structural walk of `quote`, which would compound across
iterated bridge steps.

`Lift l m eq A` collapses definitionally to `A` when `l` and `m` are
level-convertible; nested Lifts compose; `lower (lift a)` reduces to
`a`; and `lift (lower x)` eta-reduces on stuck neutrals. The `eq`
witness is irrelevant for conversion once the levels and underlying
type match.

`Squash A` is proof-irrelevant. Any two `SquashIntro` inhabitants at a
shared `Squash A` type are definitionally equal, and neutral inhabitants
of `Squash A` convert against introductions by the shared-type invariant.

`DescDescApp` stamps a canonical reference on the generated
`descDesc I L` value so quotation and conversion can avoid descending
into the self-describing universe spiral. `InterpD`, `AllD`, and
`EverywhereD` are the kernel primitives behind description
interpretation and the generated `desc-ind` iota rule.

### 4.6 Unit

```
eval(ρ, Unit)  = VUnit
eval(ρ, Tt)    = VTt

```

Unit has no eliminator in the core. The kernel implements ⊤-η: any
neutral of type ⊤ converts against `VTt` (see §6.3). Sound in the
type-free conv because conv is always called on values sharing a type;
if one side is `VTt`, the shared type is ⊤ and the neutral's only
inhabitant is `Tt`.

### 4.6′ Empty

```
eval(ρ, Empty) = VEmpty
```

Empty has no introduction. The eliminator `Absurd` (§4.6″) discharges
any neutral of type Empty.

### 4.6″ Absurd

```
eval(ρ, Absurd(P, x)) = vAbsurd(eval(ρ, P), eval(ρ, x))

vAbsurd(P, VNe(l, sp)) = VNe(l, sp ++ [EAbsurd(P)])
vAbsurd(P, _)          = THROW "kernel bug: vAbsurd on non-neutral"
```

`Absurd(P, x)` is the unique map from the initial object to any type
`P` at any universe level. It is well-typed only when `x : Empty`;
since `Empty` has no canonical inhabitants, `x` is always neutral in
sound code. The non-neutral case is a kernel invariant violation —
THROW rather than silently propagate, matching `vFst`/`vBootJ`
hygiene.

There is no β-rule for `Absurd`: it only fires on neutrals, and no
canonical inhabitant of `Empty` exists to trigger reduction. Two
`Absurd` redexes on the same neutral with definitionally equal `P`
are conv-equal via the `EAbsurd` spine frame (§6.4).

### 4.7 Bootstrap coproduct

```
eval(ρ, BootSum(A, B))        = VBootSum(eval(ρ, A), eval(ρ, B))
eval(ρ, BootInl(A, B, t))     = VBootInl(eval(ρ, A), eval(ρ, B), eval(ρ, t))
eval(ρ, BootInr(A, B, t))     = VBootInr(eval(ρ, A), eval(ρ, B), eval(ρ, t))
eval(ρ, BootSumElim(A,B,P,l,r,s)) =
  vBootSumElim(eval(ρ,A), eval(ρ,B), eval(ρ,P), eval(ρ,l), eval(ρ,r), eval(ρ,s))

```

where:

```
vBootSumElim(A, B, P, l, r, VBootInl(_, _, v))  = vApp(l, v)
vBootSumElim(A, B, P, l, r, VBootInr(_, _, v))  = vApp(r, v)
vBootSumElim(A, B, P, l, r, VNe(k, sp))         =
  VNe(k, sp ++ [EBootSumElim(A, B, P, l, r)])
vBootSumElim(_, _, _, _, _, _)                  =
  THROW "kernel bug: vBootSumElim on non-boot-sum"

```

This coproduct is private to `descPlus` interpretation. Public `H.sum`,
`H.inl`, `H.inr`, and `H.sumElim` route through generated `SumDT`.

### 4.8 Bootstrap identity

```
eval(ρ, BootEq(A, a, b))        = VBootEq(eval(ρ, A), eval(ρ, a), eval(ρ, b))
eval(ρ, BootRefl)               = VBootRefl
eval(ρ, BootJ(A, a, P, pr, b, eq)) =
  vBootJ(eval(ρ,A), eval(ρ,a), eval(ρ,P), eval(ρ,pr), eval(ρ,b), eval(ρ,eq))

```

where:

```
vBootJ(A, a, P, pr, b, VBootRefl)    = pr
vBootJ(A, a, P, pr, b, VNe(l,sp)) =
  VNe(l, sp ++ [EBootJ(A, a, P, pr, b)])
vBootJ(_, _, _, _, _, _)             = THROW "kernel bug: vBootJ on non-refl"

```

This identity substrate is private to `descRet`, Lift witnesses, index
transport, and no-confusion helpers. Public `H.eq`, `H.refl`, and `H.j`
route through generated `EqDT`.

### 4.9 Universes

```
eval(ρ, U(i)) = VU(i)

```

### 4.10 Axiomatized primitives

Type formers evaluate to their corresponding values. Literals
carry their payload through. No computation, no recursion — these
are axiomatized constants.

```
eval(ρ, String)       = VString
eval(ρ, Int)          = VInt
eval(ρ, Float)        = VFloat
eval(ρ, Attrs)        = VAttrs
eval(ρ, Path)         = VPath
eval(ρ, Derivation)   = VDerivation
eval(ρ, Function)     = VFunction
eval(ρ, Any)          = VAny

eval(ρ, StringLit(s)) = VStringLit(s)
eval(ρ, IntLit(n))    = VIntLit(n)
eval(ρ, FloatLit(f))  = VFloatLit(f)
eval(ρ, AttrsLit)     = VAttrsLit
eval(ρ, PathLit)      = VPathLit
eval(ρ, DerivationLit) = VDerivationLit
eval(ρ, FnLit)        = VFnLit
eval(ρ, AnyLit)       = VAnyLit

```

Most primitives have no eliminators. They exist to integrate
Nix's native types into the kernel's type system as opaque,
axiomatized constants. The exception is String, which has
`StrEq` (§4.11).

### 4.11 String equality (StrEq)

```
eval(ρ, StrEq(lhs, rhs)) = vStrEq(eval(ρ, lhs), eval(ρ, rhs))

```

where:

```
-- trueV / falseV are the plus-encoded derived booleans:
--   trueV  = VDescCon boolDescV VTt (VBootInl eqTtV eqTtV VBootRefl)
--   falseV = VDescCon boolDescV VTt (VBootInr eqTtV eqTtV VBootRefl)
-- where boolDescV is the generated encoded BoolDT description.

vStrEq(VStringLit(s₁), VStringLit(s₂)) = if s₁ == s₂ then trueV else falseV
vStrEq(VNe(l, sp),     rhs)            = VNe(l, sp ++ [EStrEq(rhs)])
vStrEq(lhs,            VNe(l, sp))     = VNe(l, sp ++ [EStrEq(lhs)])
vStrEq(_, _)                           = THROW "kernel bug: vStrEq on non-string"

```

`StrEq` is a binary predicate on strings. Both arguments must be of
type `String`. The result type is the derived `H.bool` —
`μ ⊤ (plus (retI tt) (retI tt)) tt` — which is the kernel
representation of booleans after their retirement as primitives.
Unlike other eliminators, StrEq has no motive: it always returns
`H.bool`, not a dependent type.

When both arguments are concrete string literals, `vStrEq` reduces
to the plus-encoded `true_` or `false_` value by Nix-level string
comparison. When either argument is neutral, the neutral's spine is
extended with `EStrEq` carrying the other argument. This is sound
because `StrEq` is symmetric: `StrEq(a, b) ≡ StrEq(b, a)` for all
`a, b : String`.

---

## 5. Quotation Rules

`quote(d, v)` converts a value back to a term, converting levels to
indices. `d` is the current binding depth.

```
quote(d, VPi(n, A, cl))    = Pi(n, quote(d, A), quote(d+1, instantiate(cl, fresh(d))))
quote(d, VLam(n, A, cl))   = Lam(n, quote(d, A), quote(d+1, instantiate(cl, fresh(d))))
quote(d, VSigma(n, A, cl)) = Sigma(n, quote(d, A), quote(d+1, instantiate(cl, fresh(d))))
quote(d, VPair(a, b))      = Pair(quote(d, a), quote(d, b), _)
quote(d, VUnit)            = Unit
quote(d, VTt)              = Tt
quote(d, VEmpty)           = Empty
quote(d, VBootSum(A, B))       = BootSum(quote(d, A), quote(d, B))
quote(d, VBootInl(A, B, v))    = BootInl(quote(d, A), quote(d, B), quote(d, v))
quote(d, VBootInr(A, B, v))    = BootInr(quote(d, A), quote(d, B), quote(d, v))
quote(d, VBootEq(A, a, b))     = BootEq(quote(d, A), quote(d, a), quote(d, b))
quote(d, VBootRefl)            = BootRefl
quote(d, VU(i))            = U(i)
quote(d, VString)          = String
quote(d, VInt)             = Int
quote(d, VFloat)           = Float
quote(d, VAttrs)           = Attrs
quote(d, VPath)            = Path
quote(d, VDerivation)      = Derivation
quote(d, VFunction)        = Function
quote(d, VAny)             = Any
quote(d, VStringLit(s))    = StringLit(s)
quote(d, VIntLit(n))       = IntLit(n)
quote(d, VFloatLit(f))     = FloatLit(f)
quote(d, VAttrsLit)        = AttrsLit
quote(d, VPathLit)         = PathLit
quote(d, VDerivationLit)   = DerivationLit
quote(d, VFnLit)           = FnLit
quote(d, VAnyLit)          = AnyLit
quote(d, VNe(l, sp))       = quoteSp(d, Var(d - l - 1), sp)

quoteSp(d, head, [])                      = head
quoteSp(d, head, [EApp(v) | rest])        = quoteSp(d, App(head, quote(d, v)), rest)
quoteSp(d, head, [EFst | rest])           = quoteSp(d, Fst(head), rest)
quoteSp(d, head, [ESnd | rest])           = quoteSp(d, Snd(head), rest)
quoteSp(d, head, [EBootSumElim(A,B,P,l,r) | rest]) =
  quoteSp(d, BootSumElim(quote(d,A), quote(d,B), quote(d,P), quote(d,l), quote(d,r), head), rest)
quoteSp(d, head, [EBootJ(A,a,P,pr,b) | rest]) =
  quoteSp(d, BootJ(quote(d,A), quote(d,a), quote(d,P), quote(d,pr), quote(d,b), head), rest)
quoteSp(d, head, [EStrEq(arg) | rest]) =
  quoteSp(d, StrEq(head, quote(d, arg)), rest)
quoteSp(d, head, [EAbsurd(P) | rest]) =
  quoteSp(d, Absurd(quote(d, P), head), rest)

fresh(d) = VNe(d, [])

```

---

## 6. Conversion Rules

`conv(d, v₁, v₂)` checks definitional equality of two values at
binding depth `d`. Returns boolean. **No type information is used** —
conversion is purely structural on normalized values.

### 6.1 Structural rules

```
conv(d, VU(i),    VU(j))    = (i == j)
conv(d, VUnit,    VUnit)    = true
conv(d, VTt,      VTt)      = true
conv(d, VEmpty,   VEmpty)   = true
conv(d, VBootRefl, VBootRefl) = true
conv(d, VString,      VString)      = true
conv(d, VInt,         VInt)         = true
conv(d, VFloat,       VFloat)       = true
conv(d, VAttrs,       VAttrs)       = true
conv(d, VPath,        VPath)        = true
conv(d, VDerivation,  VDerivation)  = true
conv(d, VFunction,    VFunction)    = true
conv(d, VAny,         VAny)         = true
conv(d, VStringLit(s₁), VStringLit(s₂)) = (s₁ == s₂)
conv(d, VIntLit(n₁),    VIntLit(n₂))    = (n₁ == n₂)
conv(d, VFloatLit(f₁),  VFloatLit(f₂))  = (f₁ == f₂)
conv(d, VAttrsLit,    VAttrsLit)    = true
conv(d, VPathLit,     VPathLit)     = true
conv(d, VDerivationLit, VDerivationLit) = true
conv(d, VFnLit,       VFnLit)       = true
conv(d, VAnyLit,      VAnyLit)      = true

```

### 6.2 Binding forms

To compare under binders, generate a fresh variable and instantiate:

```
conv(d, VPi(_, A₁, cl₁), VPi(_, A₂, cl₂)) =
  conv(d, A₁, A₂) ∧ conv(d+1, instantiate(cl₁, fresh(d)), instantiate(cl₂, fresh(d)))

conv(d, VLam(_, _, cl₁), VLam(_, _, cl₂)) =
  conv(d+1, instantiate(cl₁, fresh(d)), instantiate(cl₂, fresh(d)))

conv(d, VLam(_, _, cl), v) =                                        -- Π-η
  conv(d+1, instantiate(cl, fresh(d)), vApp(v, fresh(d)))
  -- only fires when v is not a VLam

conv(d, v, VLam(_, _, cl)) =                                        -- Π-η
  conv(d+1, vApp(v, fresh(d)), instantiate(cl, fresh(d)))
  -- only fires when v is not a VLam

conv(d, VSigma(_, A₁, cl₁), VSigma(_, A₂, cl₂)) =
  conv(d, A₁, A₂) ∧ conv(d+1, instantiate(cl₁, fresh(d)), instantiate(cl₂, fresh(d)))

```

The two Π-η rules fire when exactly one side is a VLam; both sides being
VLam falls through to the symmetric VLam/VLam rule above. Sound because
conv is always called on values sharing a type — if one side is VLam,
that type is VPi, and the other side's only inhabitants up to
definitional equality are its η-expansions. Termination: each rule
strictly decreases VLam-depth on the side it fires on, so no nested
firing can loop.

### 6.3 Compound values

```
conv(d, VPair(a₁, b₁), VPair(a₂, b₂)) =
  conv(d, a₁, a₂) ∧ conv(d, b₁, b₂)

conv(d, VPair(a, b), VNe(l, sp)) =
  conv(d, a, vFst(VNe(l, sp))) ∧ conv(d, b, vSnd(VNe(l, sp)))    -- Σ-η

conv(d, VNe(l, sp), VPair(a, b)) =
  conv(d, vFst(VNe(l, sp)), a) ∧ conv(d, vSnd(VNe(l, sp)), b)    -- Σ-η

conv(d, VTt, VNe(_, _)) = true                                    -- ⊤-η
conv(d, VNe(_, _), VTt) = true                                    -- ⊤-η

conv(d, VBootSum(A₁, B₁), VBootSum(A₂, B₂)) =
  conv(d, A₁, A₂) ∧ conv(d, B₁, B₂)
conv(d, VBootInl(A₁, B₁, v₁), VBootInl(A₂, B₂, v₂)) =
  conv(d, A₁, A₂) ∧ conv(d, B₁, B₂) ∧ conv(d, v₁, v₂)
conv(d, VBootInr(A₁, B₁, v₁), VBootInr(A₂, B₂, v₂)) =
  conv(d, A₁, A₂) ∧ conv(d, B₁, B₂) ∧ conv(d, v₁, v₂)

conv(d, VBootEq(A₁, a₁, b₁), VBootEq(A₂, a₂, b₂)) =
  conv(d, A₁, A₂) ∧ conv(d, a₁, a₂) ∧ conv(d, b₁, b₂)

```

### 6.4 Neutrals

```
conv(d, VNe(l₁, sp₁), VNe(l₂, sp₂)) =
  (l₁ == l₂) ∧ convSp(d, sp₁, sp₂)

convSp(d, [], [])         = true
convSp(d, [e₁|r₁], [e₂|r₂]) = convElim(d, e₁, e₂) ∧ convSp(d, r₁, r₂)
convSp(d, _, _)           = false    -- different lengths

convElim(d, EApp(v₁),   EApp(v₂))   = conv(d, v₁, v₂)
convElim(d, EFst,        EFst)        = true
convElim(d, ESnd,        ESnd)        = true
convElim(d, EBootSumElim(A₁,B₁,P₁,l₁,r₁), EBootSumElim(A₂,B₂,P₂,l₂,r₂)) =
  conv(d, A₁, A₂) ∧ conv(d, B₁, B₂) ∧ conv(d, P₁, P₂) ∧ conv(d, l₁, l₂) ∧ conv(d, r₁, r₂)
convElim(d, EBootJ(A₁,a₁,P₁,pr₁,b₁), EBootJ(A₂,a₂,P₂,pr₂,b₂)) =
  conv(d, A₁, A₂) ∧ conv(d, a₁, a₂) ∧ conv(d, P₁, P₂) ∧ conv(d, pr₁, pr₂) ∧ conv(d, b₁, b₂)
convElim(d, EStrEq(arg₁), EStrEq(arg₂)) = conv(d, arg₁, arg₂)
convElim(d, EAbsurd(P₁), EAbsurd(P₂)) = conv(d, P₁, P₂)
convElim(_, _, _) = false

```

### 6.5 Catch-all

```
conv(d, _, _) = false

```

Any pair of values not matching the above rules is not definitionally
equal. **Π-eta, Σ-eta, and ⊤-eta are applied** (see §6.2 for Π-η, §6.3
for Σ-η and ⊤-η): `f` converts against `λx. f x` under a fresh binder;
a pair `⟨a, b⟩` converts against a neutral `x : Σ` by projecting both
sides; and any neutral of type `⊤` converts against `tt`. All three
η-rules are sound in the type-free conv because conv is always called
on two values sharing a type — the side carrying the canonical form
(VLam, VPair, VTt) witnesses the shared type's shape (VPi, VSigma, ⊤),
and the other side's η-expansion is its only inhabitant up to
definitional equality.

**Π-η rationale.** Π-η matches the standard semantic models of MLTT
(PER, presheaf, simplicial sets) and is the η-rule consistent with
funext: `f ≡ λx. f x` definitionally. Without it, definitional equality
on Pi-typed values diverges from the equality the surface language
must reason about — every elaborator that produces a function value
would have to maintain its own η-normal form before submitting to
conv. With it, conv handles the canonical-vs-neutral case by descending
under one binder and continues structurally; subsequent ⊤-η, Σ-η, and
neutral-vs-neutral rules fire as usual on the body. This composition
in particular is what closes assemblies that pair a surface
`descPi k S (λ_:S. tt) D` (a 3-arg combinator that fills the kernel's
`f : S → ⊤` slot with a constant lambda) against a kernel-reconstructed
`descPi k S f D` whose `f` is a case-bound variable.

### 6.6 Level conversion (convLevel)

Level expressions form a join-semilattice with `zero` as bottom and
`max` as join. `convLevel(d, k₁, k₂)` checks definitional equality of
two Level values modulo the semilattice laws.

**Fast path** (syntactic equality):

```
convLevel(d, k, k) = true

```

When the same Level value reaches both sides of conv (e.g. a
description's level is reused unchanged across recursive children),
the syntactic-equality check skips the normaliser entirely.
Allocations from re-normalising structurally-identical levels
dominate hot CHECK loops, so this short-circuit is non-optional.

**Normalisation.** Each Level value is reduced to its canonical form
before structural comparison:

- `max(k, zero) = max(zero, k) = k` (zero absorption)
- `max(k, k) = k` (idempotence)
- `suc(max(a, b)) = max(suc(a), suc(b))` (suc distributes over max)
- `max` operands are sorted to a canonical order

The canonical form is `max(s₁, …, sₙ)` where each `sᵢ = sucᵐ(zero)`
or `sᵢ = sucᵐ(VNe(_, _))`, sorted lexicographically. After
normalisation the comparison is structural:

```
convLevel(d, k₁, k₂) = (normLevel(k₁) ≡_struct normLevel(k₂))

```

Used by description and universe CHECK rules (§7.6) to verify that
two level expressions denote the same level.

---

## 7. Typing Rules (Bidirectional)

### 7.1 Contexts

```
Ctx ::= {
  env   : Env,           -- values for evaluation
  types : [Val],         -- types of bound variables (indexed by de Bruijn)
  depth : ℕ              -- current binding depth
}

emptyCtx = { env = [], types = [], depth = 0 }

extend(Γ, n, A) = {
  env   = [fresh(Γ.depth)] ++ Γ.env,
  types = [A] ++ Γ.types,
  depth = Γ.depth + 1
}

lookupType(Γ, i) = Γ.types[i]
  -- THROW if i >= length(Γ.types)

```

### 7.2 Notation

```
Γ ⊢ t ⇐ A  ↝  t'     checking mode:  check(Γ, t, A) = t'
Γ ⊢ t ⇒ A  ↝  t'     synthesis mode: infer(Γ, t) = (t', A)
Γ ⊢ T type  ↝  T'     type formation: checkType(Γ, T) = T'
Γ ⊢ T type@i  ↝  T'   type + level:  checkTypeLevel(Γ, T) = (T', i)

```

The output `t'` is the elaborated core term (fully annotated).

### 7.3 Synthesis rules (infer)

**Var**

```
                lookupType(Γ, i) = A
                ──────────────────────
                Γ ⊢ Var(i) ⇒ A  ↝  Var(i)

```

**Ann** (annotation)

```
                Γ ⊢ A type  ↝  A'
                Â = eval(Γ.env, A')
                Γ ⊢ t ⇐ Â  ↝  t'
                ──────────────────────
                Γ ⊢ Ann(t, A) ⇒ Â  ↝  Ann(t', A')

```

**App** (application)

```
                Γ ⊢ f ⇒ fTy  ↝  f'
                whnf(fTy) = VPi(n, A, cl)
                Γ ⊢ u ⇐ A  ↝  u'
                B = instantiate(cl, eval(Γ.env, u'))
                ──────────────────────
                Γ ⊢ App(f, u) ⇒ B  ↝  App(f', u')

```

**CRITICAL**: `whnf(fTy)` must normalize `fTy` to weak head normal
form before pattern matching. If `fTy` is a let-unfolding or a
neutral that reduces further, the match will fail spuriously.

In this kernel, `eval` already produces WHNF, so `whnf(v) = v` for
all values. But this invariant must be maintained if the value
representation changes.

**Fst** (first projection)

```
                Γ ⊢ t ⇒ tTy  ↝  t'
                whnf(tTy) = VSigma(n, A, cl)
                ──────────────────────
                Γ ⊢ Fst(t) ⇒ A  ↝  Fst(t')

```

**Snd** (second projection)

```
                Γ ⊢ t ⇒ tTy  ↝  t'
                whnf(tTy) = VSigma(n, A, cl)
                B = instantiate(cl, vFst(eval(Γ.env, t')))
                ──────────────────────
                Γ ⊢ Snd(t) ⇒ B  ↝  Snd(t')

```

**Eliminator motive checking (checkMotive).**
All eliminators require a motive `P : domTy → U(k)` for some `k`.
The implementation provides a shared `checkMotive` helper that
handles two forms:

- Lambda motives (`P = λx. body`): extend the context with `x : domTy`
  and verify `body` is a type via `checkType`.
- Non-lambda motives: infer the type and verify it has shape
  `VPi(_, domTy, _ → VU(k))` for some `k`.

The `k` is not fixed — motives may target any universe level,
enabling **large elimination** (eliminators whose return type is a
type, not a value). Generated datatype eliminators use this same
motive checker through `DescInd`.

**Generated eliminators.** Public eliminators for natural numbers,
lists, sums, equality, vectors, finite sets, W-types, and user-defined
datatypes are generated as applications of `DescInd` to their datatype
description. The checker validates the generated motive and branch
terms against the generic indexed-description eliminator.

**Public identity elimination.** `H.j A a P pr b eq` is a HOAS adapter
that preserves the usual J-shaped arguments, but elaborates to
`EqDT.elim`. The adapter checks `pr` against `P a (EqDT.refl A a)` and
checks `eq` against `EqDT.T A a b` before emitting the generated
eliminator spine.

**Bootstrap identity elimination.** Internal description machinery may
still use `BootJ`:

```
                Γ ⊢ A type  ↝  A'    Â = eval(Γ.env, A')
                Γ ⊢ a ⇐ Â  ↝  a'    â = eval(Γ.env, a')
                Γ ⊢ P ⇐ <Π(y : A). Π(e : BootEq A a y). U(k)>  ↝  P'
                P̂ = eval(Γ.env, P')
                Γ ⊢ pr ⇐ vApp(vApp(P̂, â), VBootRefl)  ↝  pr'
                Γ ⊢ b ⇐ Â  ↝  b'    b̂ = eval(Γ.env, b')
                Γ ⊢ eq ⇐ VBootEq(Â, â, b̂)  ↝  eq'
                ──────────────────────
                Γ ⊢ BootJ(A, a, P, pr, b, eq) ⇒ vApp(vApp(P̂, b̂), eval(Γ.env, eq'))
                   ↝  BootJ(A', a', P', pr', b', eq')

```

**Bootstrap J motive verification.** For non-lambda motives, the
implementation structurally verifies all three components:

1. Outer Pi domain matches `A` (conversion check)
2. Inner Pi domain matches `BootEq(A, a, y)` (conversion check)
3. Innermost codomain is `VU(k)` for some `k`

For lambda motives (`P = λy. body`), the body is checked via
`checkMotive` against `BootEq(A, a, y)`, which performs the same
verification on the inner structure. This catches motive errors
at the motive itself rather than deferring to the base case.

**Axiomatized primitive type formers** (synthesis)

Primitive type formers are synthesized directly — they infer as
inhabitants of `U(0)`:

```
                ──────────────────────
                Γ ⊢ String ⇒ VU(0)  ↝  String

                ──────────────────────
                Γ ⊢ Int ⇒ VU(0)  ↝  Int

```

(Similarly for Float, Attrs, Path, Derivation, Function, Any — all at level 0.)

**Primitive literals** (synthesis)

Literals synthesize their corresponding type:

```
                ──────────────────────
                Γ ⊢ StringLit(s) ⇒ VString  ↝  StringLit(s)

                ──────────────────────
                Γ ⊢ IntLit(n) ⇒ VInt  ↝  IntLit(n)

                ──────────────────────
                Γ ⊢ FloatLit(f) ⇒ VFloat  ↝  FloatLit(f)

```

(Similarly for AttrsLit → VAttrs, PathLit → VPath,
DerivationLit → VDerivation, FnLit → VFunction, AnyLit → VAny.)

**StrEq** (string equality)

```
                boolDescV = eval [] (elab BoolDT.D)
                boolV = VMu VUnit boolDescV VTt
                Γ ⊢ lhs ⇐ VString  ↝  lhs'
                Γ ⊢ rhs ⇐ VString  ↝  rhs'
                ──────────────────────
                Γ ⊢ StrEq(lhs, rhs) ⇒ boolV  ↝  StrEq(lhs', rhs')

```

Both arguments are checked against `VString`. The result type is
the derived `H.bool` — `μ ⊤ (plus (retI tt) (retI tt)) tt` —
written `boolV` above. StrEq is not a dependent eliminator: it has
no motive parameter.

### 7.4 Checking rules (check)

**Lam** (lambda introduction)

```
                whnf(A) = VPi(n, dom, cl)
                Γ' = extend(Γ, n, dom)
                cod = instantiate(cl, fresh(Γ.depth))
                Γ' ⊢ t ⇐ cod  ↝  t'
                ──────────────────────
                Γ ⊢ Lam(n, _, t) ⇐ A  ↝  Lam(n, quote(Γ.depth, dom), t')

```

**Pair** (pair introduction)

```
                whnf(T) = VSigma(n, A, cl)
                Γ ⊢ a ⇐ A  ↝  a'
                B = instantiate(cl, eval(Γ.env, a'))
                Γ ⊢ b ⇐ B  ↝  b'
                ──────────────────────
                Γ ⊢ Pair(a, b, _) ⇐ T  ↝  Pair(a', b', quote(Γ.depth, T))

```

**Generated datatype constructors.** Public constructors such as
`H.zero`, `H.succ`, `H.nil`, `H.cons`, `H.inl`, `H.inr`, and
user-defined datatype constructors check as `DescCon` introductions
against their generated `VMu` type. Their payloads are checked against
the interpretation of the constructor's description. Deep generated
natural/list constructor chains are handled by flat constructor
elaboration and `desc-con` trampolines.

**Tt**

```
                whnf(A) = VUnit
                ──────────────────────
                Γ ⊢ Tt ⇐ A  ↝  Tt

```

**BootRefl**

```
                whnf(T) = VBootEq(A, a, b)
                conv(Γ.depth, a, b) = true
                ──────────────────────
                Γ ⊢ BootRefl ⇐ T  ↝  BootRefl

```

If `conv(Γ.depth, a, b) = false`, this is a **type error**: the
two sides of the equation are not definitionally equal, and
`BootRefl` cannot prove the equation. Public `H.refl` is resolved by
HOAS check mode against generated `EqDT.T A a a`, elaborating to
`EqDT.refl A a`; unrestricted inference for bare public `refl` is
rejected.

**Primitive literals** (checked against their corresponding types)

```
                whnf(A) = VString
                ──────────────────────
                Γ ⊢ StringLit(s) ⇐ A  ↝  StringLit(s)

                whnf(A) = VInt
                ──────────────────────
                Γ ⊢ IntLit(n) ⇐ A  ↝  IntLit(n)

                whnf(A) = VFloat
                ──────────────────────
                Γ ⊢ FloatLit(f) ⇐ A  ↝  FloatLit(f)

                whnf(A) = VAttrs
                ──────────────────────
                Γ ⊢ AttrsLit ⇐ A  ↝  AttrsLit

                whnf(A) = VPath
                ──────────────────────
                Γ ⊢ PathLit ⇐ A  ↝  PathLit

                whnf(A) = VDerivation
                ──────────────────────
                Γ ⊢ DerivationLit ⇐ A  ↝  DerivationLit

                whnf(A) = VFunction
                ──────────────────────
                Γ ⊢ FnLit ⇐ A  ↝  FnLit

                whnf(A) = VAny
                ──────────────────────
                Γ ⊢ AnyLit ⇐ A  ↝  AnyLit

```

**Let**

```
                Γ ⊢ A type  ↝  A'
                Â = eval(Γ.env, A')
                Γ ⊢ t ⇐ Â  ↝  t'
                t̂ = eval(Γ.env, t')
                Γ' = { env = [t̂] ++ Γ.env, types = [Â] ++ Γ.types, depth = Γ.depth + 1 }
                Γ' ⊢ u ⇐ B  ↝  u'
                ──────────────────────
                Γ ⊢ Let(n, A, t, u) ⇐ B  ↝  Let(n, A', t', u')

```

Note: `Let` in checking mode — the expected type `B` is for the
body `u`, not for the definition `t`.

**Sub** (mode switch: fall through to synthesis)

```
                Γ ⊢ t ⇒ A  ↝  t'
                conv(Γ.depth, A, B) = true
                ──────────────────────
                Γ ⊢ t ⇐ B  ↝  t'

```

This is the catch-all. If no other checking rule applies, try
synthesis and verify the inferred type matches the expected type.

### 7.5 Type formation (checkType / checkTypeLevel)

The implementation provides two variants: `checkType(Γ, T)` returns
only the elaborated term, while `checkTypeLevel(Γ, T)` returns both
the elaborated term and the universe level. `checkType` is a thin
wrapper: `checkType(Γ, T) = checkTypeLevel(Γ, T).term`. Universe
levels are computed structurally during the type formation check
(see §8.2), not by post-hoc inspection of evaluated values.

```
                ──────────────────────
                Γ ⊢ Unit type  ↝  Unit

                ──────────────────────
                Γ ⊢ Empty type  ↝  Empty

                Γ ⊢ P type  ↝  P'    level(P') = k
                Γ ⊢ x ⇐ Empty  ↝  x'
                ──────────────────────
                Γ ⊢ Absurd(P, x) ⇒ P̂      (P̂ = eval(Γ.env, P'))
                  ↝  Absurd(P', x')

                ──────────────────────
                Γ ⊢ String type  ↝  String

                (Similarly for Int, Float, Attrs, Path, Derivation, Function, Any)

                ──────────────────────
                Γ ⊢ U(i) type  ↝  U(i)

                Γ ⊢ A type  ↝  A'
                Γ ⊢ B type  ↝  B'
                ──────────────────────
                Γ ⊢ BootSum(A, B) type  ↝  BootSum(A', B')

                Γ ⊢ A type  ↝  A'     Â = eval(Γ.env, A')
                Γ ⊢ a ⇐ Â  ↝  a'
                Γ ⊢ b ⇐ Â  ↝  b'
                ──────────────────────
                Γ ⊢ BootEq(A, a, b) type  ↝  BootEq(A', a', b')

                Γ ⊢ A type  ↝  A'
                Â = eval(Γ.env, A')
                Γ' = extend(Γ, n, Â)
                Γ' ⊢ B type  ↝  B'
                ──────────────────────
                Γ ⊢ Pi(n, A, B) type  ↝  Pi(n, A', B')

                Γ ⊢ A type  ↝  A'
                Â = eval(Γ.env, A')
                Γ' = extend(Γ, n, Â)
                Γ' ⊢ B type  ↝  B'
                ──────────────────────
                Γ ⊢ Sigma(n, A, B) type  ↝  Sigma(n, A', B')

                -- Fallback: infer and check it's a universe
                Γ ⊢ T ⇒ A  ↝  T'
                whnf(A) = VU(i)
                ──────────────────────
                Γ ⊢ T type  ↝  T'

```

Public generated data types enter this judgment through the fallback:
their expanded `Mu(...)` terms infer a universe.

### 7.6 Descriptions: typing rules

Descriptions classify strictly-positive datatype signatures over an
index type `I`. A description `D : Desc^k I` quantifies over at most
universe level `k`: `descArg^k S T` requires `S : U(k)`, and
`descPi^k S f D` requires `S : U(k)` and `f : S → I`. The
description's level `k` is recovered from the surrounding `μ` (via
`mu I D i`) at elaboration time; CHECK rules thread `k` through
recursive children without re-synthesising it ("homogeneity by
typing", below).

**Notation.** `Desc^k I` is the kernel value `VDesc(K, Î)` where
`K : Level` (§8.5). `μ I D i` is the kernel value `VMu(Î, D̂, î)`,
the `i`-th type in the family classified by `D`.

#### 7.6.1 Description eliminators are encoded at the HOAS layer

There is no `DescElim` core term in the current kernel. The HOAS
surface exposes description elimination by applying the generated
`encodeDescElim` program to a `descDesc I K` value. The trusted core
operations involved are `DescDescApp`, `InterpD`, `AllD`,
`EverywhereD`, and `DescInd`.

The level agreement once handled by a primitive `DescElim` rule is now
checked by the ordinary typing rules for `Desc I K`, `interpD`, and the
encoded eliminator's Pi type. `DescDescApp(I, K)` carries a canonical
reference so quotation and conversion can recognize the self-describing
description universe without forcing the recursive encoding.

#### 7.6.2 Homogeneity by typing (desc CHECK rules)

When CHECKing a description against `Desc^K I`, recursive sub-checks
inherit `K` directly from the surrounding type rather than
synthesising their own. The principle:

> A description's recursive children inhabit the same description type
> as the parent. Reconstructing `VDesc(K, Î)` per recursive call to
> thread the type — only to have the recursive CHECK pattern-match
> it back open — is wasted allocation.

The CHECK rules pass the surrounding type directly:

```
                whnf(ty) = VDesc(K, Î)
                Γ ⊢ S ⇐ VU(K)  ↝  S'    Ŝ = eval(Γ.env, S')
                Γ ⊢ T ⇐ VPi(_, Ŝ, ([], ty))  ↝  T'   -- recursive, same ty
                ──────────────────────
                Γ ⊢ DescArg(K, S, T) ⇐ ty  ↝  DescArg(K, S', T')

                whnf(ty) = VDesc(K, Î)
                Γ ⊢ S ⇐ VU(K)  ↝  S'    Ŝ = eval(Γ.env, S')
                Γ ⊢ f ⇐ VPi(_, Ŝ, ([], Î))  ↝  f'
                Γ ⊢ D ⇐ VPi(_, Ŝ, ([], ty))  ↝  D'   -- recursive, same ty
                ──────────────────────
                Γ ⊢ DescPi(K, S, f, D) ⇐ ty  ↝  DescPi(K, S', f', D')

                whnf(ty) = VDesc(K, Î)
                Γ ⊢ A ⇐ ty  ↝  A'                    -- recursive, same ty
                Γ ⊢ B ⇐ ty  ↝  B'                    -- recursive, same ty
                ──────────────────────
                Γ ⊢ DescPlus(A, B) ⇐ ty  ↝  DescPlus(A', B')

                whnf(ty) = VDesc(K, Î)
                Γ ⊢ j ⇐ Î  ↝  j'
                Γ ⊢ D ⇐ ty  ↝  D'                    -- recursive, same ty
                ──────────────────────
                Γ ⊢ DescRec(j, D) ⇐ ty  ↝  DescRec(j', D')

                whnf(ty) = VDesc(K, Î)
                Γ ⊢ j ⇐ Î  ↝  j'
                ──────────────────────
                Γ ⊢ DescRet(j) ⇐ ty  ↝  DescRet(j')

```

The `K` and `Î` are recovered once at the outermost CHECK, then
reused unchanged by every recursive sub-check. The rules' written
shape mirrors the implementation: `ty` (the surrounding `VDesc`
value) flows into recursive positions verbatim, and `convLevel` on
the inner description's level reduces to `convLevel(K, K)` — the
syntactic-equality fast-path of §6.6 fires.

#### 7.6.3 desc-con CHECK with checkDescAtAnyLevel

A `μ I D i` introduction `descCon D i d` checks the description `D`
against `Desc^K I`, where `K` is recovered from the surrounding
`μ`'s classifier. Because `μ` at indexed positions is checked
against `VMu(Î, D̂, î)` whose `D̂` field carries no externally-visible
level, the CHECK rule infers the level from the type-of-`D̂` at
elaboration:

```
                whnf(ty) = VMu(Î, D̂, î)
                checkDescAtAnyLevel(Γ, D) = (D', K)
                conv(Γ.depth, eval(Γ.env, D'), D̂) = true
                Γ ⊢ i ⇐ Î  ↝  i'
                conv(Γ.depth, eval(Γ.env, i'), î) = true
                Γ ⊢ payload ⇐ <interp(D̂, î) at level K>  ↝  payload'
                ──────────────────────
                Γ ⊢ DescCon(D, i, payload) ⇐ ty
                  ↝  DescCon(D', i', payload')

```

`checkDescAtAnyLevel(Γ, D)` is the bidirectional bridge: it
elaborates `D` at the most specific admissible level synthesised
from `D`'s structure, returning both the elaborated term and the
inferred `K`. Equivalent to `∃K. Γ ⊢ D ⇐ Desc^K Î`. The bidirectional
discipline at index positions is preserved: canonical intros (`tt`,
`zero`, `refl`, …) at the index slot remain checkable-only.

---

## 8. Universe Rules

### 8.1 Universe formation

```
U(i) : U(i + 1)                for all i ≥ 0

```

### 8.2 Type former levels

Universe levels are computed by `checkTypeLevel`, which returns
`{ term; level; }` from the **typing derivation**, not from
post-hoc value inspection. This avoids the problem of unknown
levels for neutral type variables. We write `level(A)` as shorthand
for `checkTypeLevel(Γ, A).level`.

```
checkTypeLevel(Γ, Unit)        = { Unit,    0 }
checkTypeLevel(Γ, Empty)       = { Empty,   0 }
checkTypeLevel(Γ, String)      = { String,  0 }
checkTypeLevel(Γ, Int)         = { Int,     0 }
checkTypeLevel(Γ, Float)       = { Float,   0 }
checkTypeLevel(Γ, Attrs)       = { Attrs,   0 }
checkTypeLevel(Γ, Path)        = { Path,    0 }
checkTypeLevel(Γ, Derivation)  = { Derivation, 0 }
checkTypeLevel(Γ, Function)    = { Function, 0 }
checkTypeLevel(Γ, Any)         = { Any,     0 }
checkTypeLevel(Γ, BootSum(A,B))= { BootSum(A',B'), max(level(A), level(B)) }
checkTypeLevel(Γ, Pi(n, A, B)) = { Pi(n,A',B'), max(level(A), level(B)) }
checkTypeLevel(Γ, Sigma(n,A,B))= { Sigma(n,A',B'), max(level(A), level(B)) }
checkTypeLevel(Γ, BootEq(A,a,b)) = { BootEq(A',a',b'), level(A) }
checkTypeLevel(Γ, U(i))        = { U(i),   i + 1 }
-- Fallback: infer type, require VU(i), extract i
checkTypeLevel(Γ, T)           = { T', i }  where Γ ⊢ T ⇒ VU(i)

```

The fallback handles neutral type expressions (variables,
applications) by inferring their type and requiring it to be a
universe. This correctly propagates levels through type variables:
if `B : U(1)`, then `checkTypeLevel` on `B` infers `VU(1)` and
returns level 1.

### 8.3 Non-cumulativity

The kernel is non-cumulative: a type `A` at level `i` is **not**
automatically a type at any level `j > i`. The Sub rule (§7.4) compares
the inferred universe against the expected one with the ordinary
structural `conv`, which decides `VU(i)` against `VU(j)` by exact level
equality — `convLevel(i, j)` modulo the §6.6 semilattice laws, never by
`i ≤ j`.

To move a type up the hierarchy you apply the explicit `Lift` former
(§4.5); there is no implicit subsumption. Conversion therefore stays a
decidable equivalence rather than a preorder, and the bidirectional
discipline keeps a single CHECK-to-INFER bridge (the `conv` round-trip)
with no cumulativity side-channel.

### 8.4 Universe consistency

The kernel MUST reject `U(i) : U(i)`. This is guaranteed by the
level computation: `level(U(i)) = i + 1`, so `U(i)` lives at level
`i + 1`, not `i`. Self-containing universes cannot be constructed.

This prevents Girard's paradox (Girard 1972), which requires a type
that contains itself. Hurkens (1995) gives the compact MLTT rendering
of the inconsistency proof. Universe stratification is the standard
fix, and it is why the kernel enforces `level(U(i)) = i + 1`.

### 8.5 Level sort

`Level` is a Tarski-style sort of universe levels, with constructors
`zero`, `suc`, and `max`. It inhabits the lowest universe:

```
                ──────────────────────
                Γ ⊢ Level type  ↝  Level

                ──────────────────────
                Γ ⊢ Level ⇒ VU(0)  ↝  Level

                ──────────────────────
                Γ ⊢ LevelZero ⇐ Level  ↝  LevelZero

                Γ ⊢ k ⇐ Level  ↝  k'
                ──────────────────────
                Γ ⊢ LevelSuc(k) ⇐ Level  ↝  LevelSuc(k')

                Γ ⊢ a ⇐ Level  ↝  a'
                Γ ⊢ b ⇐ Level  ↝  b'
                ──────────────────────
                Γ ⊢ LevelMax(a, b) ⇐ Level  ↝  LevelMax(a', b')

```

Conversion modulo the semilattice laws (idempotence of `max`, `suc`
distribution over `max`, zero absorption) is delegated to `convLevel`
(§6.6); structural conversion on Level values without normalisation
would be too coarse (e.g. `max(zero, k)` and `k` would not compare
equal).

The `Level` sort enables predicative universe polymorphism: the
description type `Desc^k I` and universe `U(k)` quantify over
arbitrary levels via `Π(k:Level). …`. Rank-1 only — `Level` itself
has no eliminator, and admitting one would break parametricity over
the semilattice quotient (any eliminator would be observably
sensitive to the canonical form chosen by `convLevel`).

---

## 9. Fuel Mechanism

### 9.1 Evaluation fuel

Every call to `evalF` receives a fuel parameter and decrements it
by one before evaluating the term. When fuel reaches 0:

```
evalF(fuel=0, ρ, t) = THROW "normalization budget exceeded"

```

The kernel aborts via `throw`. Layer 0 (TCB) has no access to the
effect system by design, so fuel exhaustion and kernel invariant
violations both manifest as Nix-level throws caught by `tryEval`.
Callers should treat any throw from the evaluator as "term not
verified" — the distinction between fuel exhaustion and a kernel bug
is in the error message text, not the failure mechanism.

### 9.2 Default budget

The default fuel budget is 10,000,000 reduction steps. This is
configurable by the caller via `evalF`. No minimum is enforced —
callers may pass arbitrarily low fuel, which will cause immediate
`throw` on the first eval step.

### 9.3 Fuel accounting

Fuel is **per-path**, not a global counter. Each call to `evalF`
captures `f = fuel - 1` and passes `f` to all sub-evaluations of
that term. When evaluating `App(t, u)`, both `evalF(f, ρ, t)` and
`evalF(f, ρ, u)` receive the same `f`. This means fuel bounds the
**depth** of any single evaluation path, not the total work across
all paths.

For a balanced binary tree of N applications, the total work is
O(2^depth × fuel), not O(fuel). This is inherent to pure Nix —
there is no mutable global counter. The fuel mechanism guarantees
termination (every path eventually hits 0) but does not bound total
computation time.

All fuel consumption flows through `evalF`:

- Direct term evaluation (each `evalF` call decrements fuel by 1)
- Beta-reduction in `vApp` consumes fuel indirectly via
  `instantiateF`, which calls `evalF`
- Iota-reduction in generated recursive eliminators consumes fuel
  through `vDescIndF`, `vAllDF`, `vEverywhereDF`, and `vAppF`

`BootJ` completes in O(1) on `BootRefl`. `BootSumElim` is
non-recursive, but branch selection calls `vAppF` on the selected
branch. Structural operations (building values, pattern matching on
tags) do not consume fuel.

### 9.4 Fuel threading in generated eliminators

Generated natural/list eliminators route through datatype-specific
wrappers and the generic `DescInd` evaluator. Deep constructor chains
are not handled by hard-coded nat/list cases: `DescCon` evaluation
recognizes homogeneous linear recursive payloads from the description
profile and flattens them into `builtins.foldl'` loops. Each fold step
threads fuel through the accumulator:

```
foldl'(λ{acc, fuel}. λi.
  if fuel ≤ 0 then THROW "normalization budget exceeded"
  else { acc = step(fuel, acc, chain[i]); fuel = fuel - 1; })
  {acc = base; fuel = fuel}
  [1..n]

```

This ensures that an N-element chain consumes N units of fuel from
the fold, plus whatever fuel each step application consumes
internally. Without this threading, each step would get the
original fuel budget, giving an effective budget of N × fuel.

The worst-case complexity of a threaded fold is O(fuel²): at step
*i*, the inner `vAppF` receives `fuel - i` as its own per-path
budget. Summing over all steps gives Σ(fuel - i) ≈ fuel²/2. To
achieve O(fuel), `vAppF` would need to return remaining fuel — an
invasive signature change. The quadratic residual is inherent to
per-path fuel semantics and is a strict improvement over the
pre-threading O(N × fuel) with unbounded N.

### 9.5 Fuel consumption in constructor chains

Generated constructor evaluation flattens chains of n `DescCon`
layers when the description's linear profile proves the recursion is
structurally homogeneous. The evaluator deducts n fuel units from the
budget before rebuilding the semantic value. Generated natural and
list constructors are instances of this generic path, so the 5000-deep
stress tests are evidence for the description-level trampoline rather
than for datatype-specific hard-coding.

---

## 10. Properties the Implementation Must Satisfy

### 10.1 Soundness (non-negotiable)

If the kernel accepts `Γ ⊢ t : A`, then `t` is a valid term of
type `A` in MLTT with the specified type formers and universe
hierarchy. Formally:

**If `check(Γ, t, A)` succeeds, then `Γ ⊢ t : A` is derivable
in the declarative typing rules of MLTT.**

Equivalently: the kernel never accepts an ill-typed term.

### 10.2 Determinism

For any input `(Γ, t, A)`, the kernel produces the same result
on every invocation. There is no randomness, no system-dependent
behavior, no sensitivity to evaluation order (beyond fuel
exhaustion, which always rejects).

### 10.3 Termination

For any input `(Γ, t, A)`, the kernel terminates. It either:
- Accepts (returns the elaborated term)
- Rejects with a type error (via effect)
- Rejects with fuel exhaustion
- Crashes with a kernel bug diagnostic (throw)

It never loops. The fuel mechanism guarantees this.

### 10.4 Evaluation roundtrip

For any well-typed term `t` and environment `ρ` consistent with
the context:

```
quote(d, eval(ρ, quote(d, eval(ρ, t)))) = quote(d, eval(ρ, t))

```

Evaluation followed by quotation is idempotent. The result is a
normal form.

### 10.5 Conversion reflexivity

For any value `v`:

```
conv(d, v, v) = true

```

### 10.6 Conversion symmetry

For any values `v₁, v₂`:

```
conv(d, v₁, v₂) = conv(d, v₂, v₁)

```

### 10.7 Conversion transitivity

For any values `v₁, v₂, v₃`:

```
conv(d, v₁, v₂) ∧ conv(d, v₂, v₃)  ⟹  conv(d, v₁, v₃)

```

### 10.8 Type preservation under evaluation

If `Γ ⊢ t : A` and `eval(Γ.env, t) = v`, then `v` represents a
value of type `A`. This is not directly testable (values don't
carry types) but is ensured by the correctness of the evaluation
rules.

### 10.9 Strong normalization (for well-typed terms)

For any well-typed term `t`, `eval` terminates without exhausting
fuel for a sufficiently large fuel budget. The fuel mechanism is
a practical safeguard, not a theoretical necessity for well-typed
terms.

---

## 11. Derived Test Cases

Every rule in this spec generates at least one positive test (the
rule applies and succeeds) and one negative test (the rule's
premises are violated and the kernel rejects).

### 11.1 Required positive tests (kernel must ACCEPT)

```
-- Public generated identity
⊢ H.refl : H.eq H.nat H.zero H.zero

-- Function type
⊢ Lam(x, H.nat, Var(0)) : Pi(x, H.nat, H.nat)

-- Application
f : Pi(x, H.nat, H.nat) ⊢ App(f, H.zero) : H.nat

-- Dependent function
⊢ Lam(A, U(0), Lam(x, Var(0), Var(0))) : Pi(A, U(0), Pi(x, A, A))

-- Sigma pair
⊢ Pair(H.zero, Tt, Sigma(x, H.nat, Unit)) : Sigma(x, H.nat, Unit)

-- Generated natural induction: 0 + 0 = 0
⊢ H.refl : H.eq H.nat (H.ind ... H.zero) H.zero

-- List
⊢ H.cons H.nat H.zero (H.nil H.nat) : H.listOf H.nat

-- Sum injection
⊢ H.inl H.nat Unit H.zero : H.sum H.nat Unit

-- Universe hierarchy
⊢ U(0) : U(1)
⊢ U(1) : U(2)
⊢ H.nat : U(0)
⊢ Pi(x, H.nat, H.nat) : U(0)

-- Let binding
⊢ Let(x, H.nat, H.zero, Var(0)) : H.nat

-- StrEq: type inference returns the derived H.bool
--   (= μ ⊤ (plus (retI tt) (retI tt)) tt; see §4.11)
⊢ StrEq(StringLit("a"), StringLit("b")) : H.bool

-- StrEq reduction: equal strings reduce to the derived true_ value;
-- unequal strings reduce to false_. Both witnessed via H.refl over the
-- derived-bool form. Expressing this rule at the Tm level requires
-- the plus/μ machinery; see the examples/verified-functions.nix
-- fixture `recordStrEqMatch` for an executable test.

```

### 11.2 Required negative tests (kernel must REJECT)

```
-- Type mismatch
⊢ H.zero : Unit                        REJECT

-- Universe violation
⊢ U(0) : U(0)                          REJECT

-- Non-cumulativity: a U(0) type is not accepted at U(1)
⊢ H.nat : U(1)                         REJECT  (no subsumption; use Lift, §8.3)

-- H.refl on unequal terms
⊢ H.refl : H.eq H.nat H.zero (H.succ H.zero)  REJECT

-- Application of non-function
⊢ App(H.zero, H.zero)                  REJECT

-- Projection of non-pair
⊢ Fst(H.zero)                          REJECT

-- Wrong eliminator scrutinee
⊢ H.ind ... Tt                         REJECT  (Tt : Unit, not H.nat)

-- Unbound variable
⊢ Var(0)  (in empty context)           REJECT

-- StrEq on non-string
⊢ StrEq(H.zero, StringLit("foo"))     REJECT  (lhs is H.nat, expected String)

-- Ill-typed pair under expected Sigma
⊢ Pair(H.zero, H.zero) ⇐ Sigma(x, H.nat, Unit)  REJECT

```

### 11.3 Required stress tests

```
-- Large H.nat: H.succ^5000(H.zero) : H.nat        ACCEPT (trampoline)
-- Large H.listOf: H.cons^5000 : H.listOf H.nat    ACCEPT (trampoline)
-- H.ind on H.succ^5000(H.zero)                    ACCEPT (trampoline)
-- H.listElim on H.cons^5000                       ACCEPT (trampoline)
-- Succ elaboration: elab-succ-5000               ACCEPT (trampoline)
-- Cons elaboration: elab-cons-5000               ACCEPT (trampoline)
-- Deeply nested Pi: Pi(x₁, ..., Pi(xₙ, H.nat, H.nat)...) for n=500  ACCEPT
-- Fuel exhaustion: artificially low fuel on complex term    REJECT (fuel)
-- Fuel threading: generated natural fold decrements fuel per step  ACCEPT
-- Fuel threading: generated list fold decrements fuel per step     ACCEPT

```

### 11.4 Required roundtrip tests

For each value form, verify:

```
quote(d, eval(ρ, t)) = normal_form(t)

```

where `normal_form(t)` is the expected normal form.

---

## 12. Notation Index

| Symbol | Meaning |
|--------|---------|
| Γ | Typing context |
| ρ | Value environment |
| d | Binding depth (for levels ↔ indices) |
| ⊢ | Typing judgment |
| ⇐ | Checking mode |
| ⇒ | Synthesis mode |
| ↝ | Elaborates to |
| ≡ | Definitional equality |
| Π | Dependent function type |
| Σ | Dependent pair type |
| ℕ | Natural numbers |
| 𝔹 | Booleans (derived: `μ ⊤ (plus (retI tt) (retI tt)) tt`) |
| ⊤ | Unit type |
| ⊥ | Empty type |
| U(i) | Universe at level i |
| Id_A(a,b) | Identity type |
| TCB | Trusted computing base |
| WHNF | Weak head normal form |
| NbE | Normalization by evaluation |
| THROW | Kernel invariant violation (crash) |
| REJECT | Term rejected (via effect or fuel) |

---

## 13. Known Limitations

The following are documented implementation choices or limitations,
not bugs. They are recorded here so auditors do not rediscover them.

### 13.1 Trusted annotation sidecars are semantically erased

`Ann` terms may carry implementation sidecars such as `trusted`,
`_descRef`, `_label`, and `_conLabel`. Evaluation may propagate those
sidecars to values for performance, source maps, or generated datatype
metadata, but conversion ignores them. They must never affect
definitional equality.

### 13.2 Lambda domain annotations discarded in checking mode

When checking `Lam(n, A, t)` against `VPi(n, dom, cl)`, the lambda's
domain annotation `A` is discarded and replaced by `dom` from the
Pi type. This is standard bidirectional type checking (Dunfield &
Krishnaswami 2021, §4): in checking mode, the expected type provides
the domain, not the term. The elaborated output uses `quote(d, dom)`,
making the original annotation unrecoverable.

### 13.3 Term constructors do not validate argument types

Term constructors (`mkVar`, `mkApp`, etc.) accept arbitrary Nix
values without type validation. `mkVar "hello"` produces
`{ tag = "var"; idx = "hello"; }`, which crashes at eval time.
The trust boundary is the HOAS layer (`src/tc/hoas/`), which is the
public API — direct term construction is internal to the kernel.

### 13.4 `tryEval` only catches `throw` and `assert false`

`builtins.tryEval` in the elaborator's `isConstantFamily` sentinel
detection only catches explicit `throw` and `assert false`. Nix
coercion errors (e.g., "cannot convert a function to JSON"),
missing attribute access, and type comparison errors are uncatchable.
The elaborator uses `builtins.typeOf` in error paths to avoid
triggering coercion errors.

### 13.5 HOAS sentinel comparison

The `isConstantFamily` sentinel test in the elaborator applies two
distinct sentinel values and compares the results to detect whether
a binding body is dependent. Both Pi and Sigma paths compare
**elaborated kernel terms** (`H.elab r1.value == H.elab r2.value`)
rather than raw HOAS trees. This avoids false negatives from Nix's
function identity comparison (`==` on lambdas). However, if `H.elab`
itself produces structurally different terms for semantically
equivalent types (e.g., through different elaboration paths), false
negatives remain possible. This is a safe failure mode — the kernel
still type-checks correctly, but elaboration may require explicit
`_kernel` annotations unnecessarily.

### 13.6 StrEq neutral canonicalization

When one argument to `vStrEq` is neutral and the other is a literal,
the neutral's spine is extended with `EStrEq(literal)`. When both
arguments are neutral, the **left** neutral's spine is extended with
`EStrEq(right)`. This means `StrEq(x, y)` and `StrEq(y, x)` (where
both are neutral) produce different normal forms: `VNe(x, [EStrEq(y)])`
vs `VNe(y, [EStrEq(x)])`. Therefore `conv` will report them as
**not** definitionally equal, even though `StrEq` is semantically
symmetric. This is a safe conservatism: the kernel may reject some
provable equalities but never accepts a false one.

### 13.7 Extract uses type value threading (not sentinels)

The `extract` function threads kernel type values (`tyVal`) through
recursive extraction, rather than using sentinel-based non-dependence
tests. For Pi extraction, the codomain type is computed per-invocation
via `instantiate(tyVal.closure, kernelArg)`, supporting both dependent
and non-dependent function extraction. For Sigma extraction (records),
the second component's type is computed via
`instantiate(tyVal.closure, val.fst)`. A `reifyType : Val → HoasTree`
fallback converts kernel type values back to HOAS when the HOAS body
cannot be applied (e.g., when the body accesses record fields from a
neutral). `reifyType` loses sugar (VSigma → `H.sigma`, not
`H.record`) so the HOAS body is preferred when available.

### 13.8 Spine comparison complexity

`convSp` uses `builtins.elemAt` in a fold to compare neutral spines.
In Nix, `builtins.elemAt` on lists is O(1) (Nix lists are internally
vectors/arrays), so the actual complexity is O(n), not O(n²). This
was incorrectly flagged in an earlier audit.

---

## References

1. Coquand, T. et al. (2009). *A simple type-theoretic language: Mini-TT.*
2. Dunfield, J. & Krishnaswami, N. (2021). *Bidirectional Typing.* ACM Computing Surveys.
3. Kovács, A. (2022). *Generalized Universe Hierarchies.* CSL 2022.
4. Abel, A. & Chapman, J. (2014). *Normalization by Evaluation in the Delay Monad.*
5. Girard, J.-Y. (1972). *Interprétation fonctionnelle et élimination des coupures de l'arithmétique d'ordre supérieur.* Thèse d'État, Université Paris 7.
6. Hurkens, A. J. C. (1995). *A Simplification of Girard's Paradox.* TLCA 1995.
7. de Bruijn, N. (1972). *Lambda Calculus Notation with Nameless Dummies.*
8. Martin-Löf, P. (1984). *Intuitionistic Type Theory.* Bibliopolis.
9. Felicissimo, T. (2023). *Generic Bidirectional Typing for Dependent Type Theories.*


## Examples

### Overview

### Proofs

#### Proof Basics


The first proof examples stay close to computation. You write a HOAS
proposition, give `refl` as evidence, and let the kernel normalize both
sides. When the normal forms match, the checker accepts the proof.

Later sections use the same checker with dependent pairs and eliminators.
The full source lives at `examples/proof-basics.nix`.

## Computational equality

Addition, boolean negation, list length, and append are defined with
eliminators. The equality proof is still `refl`; the work happens in
normalization.

```nix
add = m: n:
  ind 0 (lam "_" nat (_: nat)) n
    (lam "k" nat (_: lam "ih" nat (ih: succ ih)))
    m;

addThreeFive =
  (checkHoas (eq nat (add (natLit 3) (natLit 5)) (natLit 8)) refl)
    .tag == "desc-con";

doubleNegTrue =
  (checkHoas (eq bool (not_ (not_ true_)) true_) refl).tag == "desc-con";
```

## Dependent witnesses

A sigma value packages a witness with proof that the witness has the
requested property. These examples use concrete witnesses whose proof
component reduces to reflexivity.

```nix
witnessAddResult =
  let
    ty = sigma "x" nat (x: eq nat (add (natLit 3) (natLit 5)) x);
    tm = pair (natLit 8) refl;
  in
  (checkHoas ty tm).tag == "pair";
```

## Eliminators as programs

Natural, boolean, list, and sum eliminators let the proof examples
define small programs inside HOAS. Each checked assertion ties the
computed result back to an equality.

```nix
listSum =
  let
    sumList = xs: listElim 0 nat (lam "_" (listOf nat) (_: nat)) zero
      (lam "h" nat (h: lam "t" (listOf nat) (_:
        lam "ih" nat (ih: add h ih))))
      xs;
  in
  (checkHoas (eq nat (sumList list123) (natLit 6)) refl).tag == "desc-con";
```

## Polymorphism and impossibility

The final examples leave concrete computation and check reusable
functions: a universe-polymorphic identity and the eliminator from
`Void`.

```nix
polyId =
  let
    ty = forall "A" (u 0) (a: forall "x" a (_: a));
    tm = lam "A" (u 0) (a: lam "x" a (x: x));
  in
  (checkHoas ty tm).tag == "lam";

exFalso =
  let
    ty = forall "A" (u 0) (a: forall "x" void (_: a));
    tm = lam "A" (u 0) (a: lam "x" void (x: absurd a x));
  in
  (checkHoas ty tm).tag == "lam";
```



#### Equality Proofs


The J eliminator is the primitive way to reason from equality. These
examples build the familiar combinators by checking generic theorem
terms, then apply the same shapes to concrete values that reduce by
computation.

## Congruence

Congruence says that equal inputs stay equal after applying the same
function. The generic term is checked for arbitrary `A`, `B`, `f`,
`x`, and `y`; the concrete term exercises the same pattern after
normalizing arithmetic.

```nix
congType =
  let
    ty = forall "A" (u 0) (a:
      forall "B" (u 0) (b:
        forall "f" (forall "_" a (_: b)) (f:
          forall "x" a (x:
            forall "y" a (y:
              forall "_" (eq a x y) (_:
                eq b (app f x) (app f y)))))));
    tm = lam "A" (u 0) (a:
      lam "B" (u 0) (b:
        lam "f" (forall "_" a (_: b)) (f:
          lam "x" a (x:
            lam "y" a (y:
              lam "p" (eq a x y) (p:
                j a x
                  (lam "y'" a (y':
                    lam "_" (eq a x y') (_: eq b (app f x) (app f y'))))
                  refl
                  y
                  p))))));
  in
  (checkHoas ty tm).tag == "lam";
```

## Symmetry and transitivity

Symmetry flips an equality. Transitivity composes two equalities by
eliminating over the second proof and carrying the first proof as the
base case.

```nix
symType =
  let
    ty = forall "A" (u 0) (a:
      forall "x" a (x:
        forall "y" a (y:
          forall "_" (eq a x y) (_:
            eq a y x))));
    tm = lam "A" (u 0) (a:
      lam "x" a (x:
        lam "y" a (y:
          lam "p" (eq a x y) (p:
            j a x
              (lam "y'" a (y': lam "_" (eq a x y') (_: eq a y' x)))
              refl
              y
              p))));
  in
  (checkHoas ty tm).tag == "lam";
```

## Transport

Transport moves evidence through an equality in a dependent family.
The concrete example uses a boolean-indexed family that chooses
between `Nat` and `Bool`.

```nix
transportConcrete =
  let
    motiveP = b: boolElim 1 (lam "_" bool (_: u 0)) nat bool b;
    proofTm = j bool true_
      (lam "y" bool (y: lam "_" (eq bool true_ y) (_: motiveP y)))
      zero
      true_
      refl;
  in
  (checkHoas nat proofTm).tag == "app";
```

## Combining proof steps

The final example feeds a congruence proof into symmetry. It is a
small proof pipeline, and the useful invariant is that both
intermediate proof terms are still checked by the same kernel.

```nix
combinedProof =
  let
    add21 = add (natLit 2) (succ zero);
    three = natLit 3;
    sadd21 = succ add21;
    sthree = succ three;
    congStep = j nat add21
      (lam "y" nat (y: lam "_" (eq nat add21 y) (_: eq nat sadd21 (succ y))))
      refl
      three
      refl;
    proofTy = eq nat sthree sadd21;
    proofTm = j nat sadd21
      (lam "y" nat (y: lam "_" (eq nat sadd21 y) (_: eq nat y sadd21)))
      refl
      sthree
      congStep;
  in
  (checkHoas proofTy proofTm).tag == "app";
```



#### Verified Functions


`fx.types.verified.verify` checks a HOAS implementation against a type,
evaluates it, and extracts a Nix value. The result can be called like an
ordinary function, but it first passed through the kernel.

## First functions

The smallest verified programs are ordinary unary functions. The
type says what the extracted Nix function accepts and returns; the
implementation is written with verified HOAS constructors.

```nix
succFn = v.verify (H.forall "x" H.nat (_: H.nat))
  (v.fn "x" H.nat (x: H.succ x));

succApply5 = succFn 5 == 6;

notFn = v.verify (H.forall "b" H.bool (_: H.bool))
  (v.fn "b" H.bool (b:
    v.if_ H.bool b { then_ = v.false_; else_ = v.true_; }));
```

## Recursion over naturals

`v.match` builds the eliminator for naturals. Addition uses the
first argument as the scrutinee and returns a function awaiting the
second argument.

```nix
addFn = v.verify (H.forall "m" H.nat (_: H.forall "n" H.nat (_: H.nat)))
  (v.fn "m" H.nat (m: v.fn "n" H.nat (n:
    v.match H.nat m {
      zero = n;
      succ = _k: ih: H.succ ih;
    })));

add2and3 = addFn 2 3 == 5;
```

## Lists and pipelines

List combinators remain checked HOAS terms until extraction. The
composed example filters zeros out of a list and folds the remaining
values into a sum.

```nix
mapSuccResult = v.verify (H.listOf H.nat)
  (v.map H.nat H.nat
    (v.fn "x" H.nat (x: H.succ x))
    (H.cons (v.nat 0) (H.cons (v.nat 1)
      (H.cons (v.nat 2) H.nil))));

composedResult =
  let
    input = H.cons (v.nat 0) (H.cons (v.nat 3)
      (H.cons (v.nat 0) (H.cons (v.nat 2)
        (H.cons (v.nat 1) H.nil))));
    nonZero = v.fn "n" H.nat (n:
      v.match H.bool n {
        zero = v.false_;
        succ = _k: _ih: v.true_;
      });
  in
  v.verify H.nat (v.fold H.nat H.nat (v.nat 0) addCombine
    (v.filter H.nat nonZero input));
```

## Sums, lets, pairs, and records

Verified extraction also covers the richer HOAS constructors used by
nix-effects types: coproduct elimination, local bindings, sigma
pairs, and record field projection.

```nix
sumLeftResult = v.verify H.nat
  (v.matchSum H.nat H.bool H.nat (v.inl H.nat H.bool (v.nat 5)) {
    left = x: H.succ x;
    right = b: v.if_ H.nat b { then_ = v.nat 1; else_ = v.nat 0; };
  });

recordGetX = v.verify
  (H.forall "r"
    (H.record [{ name = "x"; type = H.nat; } { name = "y"; type = H.bool; }])
    (_: H.nat))
  (v.fn "r"
    (H.record [{ name = "x"; type = H.nat; } { name = "y"; type = H.bool; }])
    (r: v.field
      (H.record [{ name = "x"; type = H.nat; } { name = "y"; type = H.bool; }])
      "x"
      r));
```

## Strings and records

The final examples use kernel-verified string predicates directly
and then combine them with record projection.

```nix
strEqFn = v.verify (H.forall "a" H.string (_: H.forall "b" H.string (_: H.bool)))
  (v.fn "a" H.string (a: v.fn "b" H.string (b: v.strEq a b)));

recordStrEqFn =
  let
    recTy = H.record [
      { name = "name"; type = H.string; }
      { name = "target"; type = H.string; }
    ];
  in
  v.verify (H.forall "r" recTy (_: H.bool))
    (v.fn "r" recTy (r:
      v.strEq (v.field recTy "name" r) (v.field recTy "target" r)));
```



### Effects and Validation

#### Handler-Swap Validation


The computation is built once from a typed record validator. Only the
handler changes. That makes the effect boundary visible: collecting
accumulates every validation error, logging records each check, and
strict aborts at the first failure.

## Define a typed boundary

The type describes a network configuration with positive numeric
fields. `badConfig` intentionally violates multiple checks.

```nix
Pos = refined "Pos" Int (x: x > 0);
Network = Record {
  hostName = String;
  port = Pos;
  interfaces = ListOf (Record { name = String; mtu = Pos; });
};

badConfig = {
  hostName = "kleisli.io";
  port = (-1);
  interfaces = [
    { name = "eth0"; mtu = (-50); }
    { name = 42; mtu = 1500; }
    { name = "eth2"; mtu = "big"; }
  ];
};
```

## Swap the handler

`Network.validate badConfig` returns an effectful computation. The
same computation can be interpreted by collecting, logging, or strict
handlers without rebuilding the validator.

```nix
comp = Network.validate badConfig;
runWith = handlers: state: fx.handle { inherit handlers state; } comp;

collecting =
  let
    r = runWith fx.effects.typecheck.collecting [ ];
    line = e: "  ${renderPath e} :: expected ${e.typeName}, got ${e.actual}";
  in
  "${toString (builtins.length r.state)} error(s):\n"
  + builtins.concatStringsSep "\n" (map line r.state);

logging =
  let
    r = runWith fx.effects.typecheck.logging [ ];
    line = e: "  ${if e.passed then "pass" else "fail"}  ${renderPath e} : ${e.typeName}";
  in
  builtins.concatStringsSep "\n" (map line r.state);
```



### Surface Languages

#### Surface STLC


The STLC examples build a source language incrementally over the HOAS
checker. Each child page introduces one extension, with the full source
available under `examples/stlc/`.

## Layered surfaces

The core surface defines functions and application. Later examples
import that vocabulary and extend it with products, sums, recursive
lists, refinements, and diagnostics.

```nix
core = import ./core.nix { inherit fx lib; };
sumsProducts = import ./sums-products.nix { inherit fx lib core; };
recursiveLists = import ./recursive-lists.nix { inherit fx lib core; };
refinementsDiagnostics = import ./refinements-diagnostics.nix {
  inherit fx lib core;
};
```

## More walkthroughs

- [STLC Core Surface](/nix-effects/surface-examples/stlc/core)
- [STLC Sums and Products](/nix-effects/surface-examples/stlc/sumsProducts)
- [STLC Recursive Lists](/nix-effects/surface-examples/stlc/recursiveLists)
- [STLC Refinements and Diagnostics](/nix-effects/surface-examples/stlc/refinementsDiagnostics)



#### STLC Core Surface


This example builds a small source language over the existing HOAS
checker. The surface adds syntax and source positions; the kernel still
owns typing and normalization.

## Define the surface

`defineSurface` maps each source constructor to a HOAS expression.
The core STLC fragment has Pi types, lambdas, annotations, and
applications.

```nix
surface = S.defineSurface {
  name = "STLC";
  description = "Small typed lambda-calculus surface example.";
  constructors = {
    lam = {
      tag = "stlc.lam";
      handler = { depth, h, lower, hoas, ... }:
        lower depth (hoas.lam h.name h.domain h.body);
    };

    app = {
      tag = "stlc.app";
      handler = { depth, h, lower, hoas, ... }:
        lower depth (hoas.app h.fn h.arg);
    };
  };
};
```

## Smart constructors

Users construct source terms with small Nix functions. The values are
surface nodes until `check` elaborates them into HOAS.

```nix
arrow = domain: codomain: pi "_" domain (_: codomain);
lam = name: domain: body: surface.mk "lam" { inherit name domain body; };
ann = term: type: surface.mk "ann" { inherit term type; };
app = fn: arg: surface.mk "app" { inherit fn arg; };

idNatTy = arrow H.nat H.nat;
idNat = lam "x" H.nat (x: var x);
idNatAnn = ann idNat idNatTy;
```

## Expected-type holes

`holeLam` omits a lambda domain. The handler reads the expected type,
solves a surface implicit metavariable with the Pi domain, and then
elaborates an ordinary typed lambda.

```nix
holeLambdaFromExpected = { context, name, body, hoas ? H }:
  let
    implicit = context.implicitMeta {
      type = { ctx = C.emptyCtx; ty = V.vU V.vLevelZero; };
      label = "stlc.lambda-domain";
    };
    expectedType = context.expectedType or null;
    domain = if expectedType == null then null else piDomain expectedType;
  in
  if expectedType == null
  then S.unsolvedImplicitError { metas = [{ id = implicit.id; }]; }
  else if domain == null
  then expectedFunctionError context
  else {
    term = hoas.lam name domain body;
    solvedState = M.solveMeta implicit.id (E.eval [ ] (hoas.elab domain)) implicit.state;
  };
```

## Implicit insertion

Plicity-style implicit binders are carried as sidecars on Pi and
lambda nodes. During application, the elaborator inserts fresh metas
for implicit arguments and solves them from explicit arguments or
the expected residual type.

```nix
polyIdTy = implicitPi "A" universe0 (A: arrow A A);
polyId = implicitLam "A" universe0 (A: lam "x" A (x: var x));
polyIdAnn = ann polyId polyIdTy;

stlcPolyIdAppliedSolvesImplicit =
  let
    position = { path = [ "poly" "id" "zero" ]; };
    r = check (app polyIdAnn H.zero) H.nat position;
  in
  !(r ? error) && r.tag == "app";
```



#### STLC Sums and Products


This extension adds ordinary product and coproduct forms. The surface
layer still only translates syntax: products elaborate to Sigma, sums
elaborate to the generated sum datatype, and case analysis elaborates to
`sumElim`.

## Products

A product type is a non-dependent Sigma. Pair introduction and
projections reuse the existing HOAS pair, fst, and snd terms.

```nix
sigma = name: fst: snd: surface.mk "sigma" { inherit name fst snd; };
prod = fst: snd: sigma "_" fst (_: snd);
pair = fst: snd: surface.mk "pair" { inherit fst snd; };
fst_ = pair: surface.mk "fst" { inherit pair; };
snd_ = pair: surface.mk "snd" { inherit pair; };

natBoolProduct = prod H.nat H.bool;
natBoolPair = pair H.zero H.true_;
natBoolPairAnn = Core.ann natBoolPair natBoolProduct;
```

## Sums

Sum injections keep both sides of the type explicit so the generated
datatype constructors are inferable. Case analysis uses a constant
motive for the STLC fragment.

```nix
sum = left: right: surface.mk "sum" { inherit left right; };
inl = left: right: term: surface.mk "inl" { inherit left right term; };
inr = left: right: term: surface.mk "inr" { inherit left right term; };
case_ = left: right: result: scrut: onLeft: onRight:
  surface.mk "case" { inherit left right result scrut onLeft onRight; };

stlcSumCaseChecks =
  let
    term = case_ H.nat H.bool H.nat leftZeroAnn
      (n: n)
      (_: H.zero);
    r = check term H.nat { path = [ "sum" "case" ]; };
  in
  !(r ? error);
```



#### STLC Recursive Lists


Lists are already available in the HOAS layer as a generated recursive
datatype. This surface gives them ordinary STLC syntax and shows how
omitted element types can be solved from an expected `List A`.

## List constructors

`List A`, `nil A`, and `cons A h t` translate to the generated HOAS
list carrier and constructors.

```nix
list = elem: surface.mk "list" { inherit elem; };
nil = elem: surface.mk "nil" { inherit elem; };
cons = elem: head: tail: surface.mk "cons" { inherit elem head tail; };

explicitNilNat = nil H.nat;
oneTwoList =
  cons H.nat one
    (cons H.nat (H.natLit 2) explicitNilNat);
```

## Folding lists

The fold form elaborates to `listElim` with a constant result type.
The checked example computes the sum of `[1, 1, 1]` and proves the
result is `3`.

```nix
listFold = elem: result: onNil: onCons: scrut:
  surface.mk "listFold" { inherit elem result onNil onCons scrut; };

sumList = xs:
  listFold H.nat H.nat H.zero
    (head: _tail: ih: add head ih)
    xs;

stlcListFoldSumChecks =
  (H.checkHoas (H.eq H.nat (sumList ones) three) H.refl).tag == "desc-con";
```

## Element-type holes

`implicitNil` and `implicitCons` allocate a surface metavariable for
the missing element type. Checking against `List Nat` solves that
metavariable as `Nat`.

```nix
implicitElementFromExpected = { context, label, hoas ? H }:
  let
    implicit = context.implicitMeta {
      type = { ctx = C.emptyCtx; ty = V.vU V.vLevelZero; };
      inherit label;
    };
    expectedType = context.expectedType or null;
    elem = if expectedType == null then null else listElement expectedType;
  in
  if expectedType == null
  then S.unsolvedImplicitError { metas = [{ id = implicit.id; }]; }
  else if elem == null
  then expectedListError context
  else {
    inherit elem implicit;
    solvedState = M.solveMeta implicit.id (E.eval [ ] (hoas.elab elem)) implicit.state;
  };
```



#### STLC Refinements and Diagnostics


The refinement surface gives a source-language spelling to the HOAS
refinement carrier and preserves diagnostic intent. A missing annotation,
an ordinary type mismatch, and a failed refinement proof are distinct
failures.

## Refinement values

A refinement type is represented as a dependent pair whose second
component is a positive decision. The surface `refine` form packages
the witness and proof into that carrier.

```nix
atLeastOneNat =
  refinement "AtLeastOne" H.nat (n: H.le one n);

oneLeOne = H.leSS H.leZ;
oneAtLeastOne = refine atLeastOneNat one oneLeOne;

stlcRefinementValueChecks =
  let
    r = check oneAtLeastOne atLeastOneNat
      { path = [ "refinement" "value" ]; };
  in
  !(r ? error) && r.tag == "pair";
```

## Refinement failure

If the witness and proof do not match, the surface reports a
refinement-specific diagnostic instead of exposing the raw Sigma
mismatch as the main error.

```nix
zeroWithOneProof = refine atLeastOneNat H.zero oneLeOne;

stlcBadRefinementHasSurfaceDiagnostic =
  let
    position = { path = [ "bad" "refinement" ]; };
    r = check zeroWithOneProof atLeastOneNat position;
  in
  (r ? error)
  && (r.kind or null) == "stlc.refinement-failure"
  && (r.position or null) == position;
```

## Diagnostic classes

The examples keep three failure classes separate: unsolved implicit
information, ordinary checker errors, and refinement failures. That
gives editors and command-line tools enough structure to suggest the
right repair.

```nix
stlcDiagnosticUnsolvedImplicitIsDistinct =
  let
    position = { path = [ "diagnostic" "implicit" ]; };
    r = elaborate (Core.holeLam "x" (x: Core.var x)) position;
  in
  (r ? error)
  && (r.kind or null) == "surface.unsolved-implicit"
  && (r.position or null) == position;

stlcDiagnosticRefinementFailureIsDistinct =
  let
    position = { path = [ "diagnostic" "refinement" ]; };
    r = check zeroWithOneProof atLeastOneNat position;
  in
  (r ? error)
  && (r.kind or null) == "stlc.refinement-failure";
```



### Applications

#### Category Theory


This example is a larger proof library, organized as a guided tour. Each
file builds on the previous one: proof combinators, arithmetic lemmas,
algebraic structures, functors, and a Yoneda-style round trip.

The public `api` exposes extracted Nix functions. The `hoas` attrset
keeps the typed HOAS terms available for users who want to inspect or
extend the proofs.

## Arithmetic proof layer

The first layer derives equality combinators from `J`, defines
addition by Nat elimination, and proves the standard addition laws.
Computational facts are extracted as ordinary Nix functions.

```nix
cat = import ./examples/category-theory { inherit fx; };

cat.api.add 3 5 == 8
cat.tests.addComm
```

## Algebra and functors

The algebra files package the arithmetic proofs as a monoid and a
one-object category. The functor file reuses the same doubling map as
both a monoid homomorphism and an endofunctor.

```nix
cat.tests.natAddMonoid
cat.tests.natCategory
cat.tests.doubleFunctor
```

## Yoneda round trips

The final file states the evaluate/lift pair for a small
types-as-groupoids presentation and checks both round-trip laws.

```nix
cat.tests.yonedaEval
cat.tests.yonedaLift
cat.tests.evalLift
cat.tests.liftEval
```



#### Expression Interpreter


This example implements a strict expression language with arithmetic,
booleans, let bindings, lambdas, application, and recursive bindings.
The evaluator emits effects for environment lookup, local scope, and
failure; handlers decide how those requests run.

The same module also exports scalable expression generators used by the
benchmark suite.

## Expression syntax

Expressions are plain tagged Nix attrsets. Constructors keep the
evaluator independent from any parser or source format.

```nix
num = n: { _tag = "Expr"; _variant = "Num"; inherit n; };
add = l: r: { _tag = "Expr"; _variant = "Add"; inherit l r; };
lam = param: body: { _tag = "Expr"; _variant = "Lam"; inherit param body; };
app = fn: arg: { _tag = "Expr"; _variant = "App"; inherit fn arg; };
```

## Handler boundary

Variable lookup, scoped execution, and failure are effects. Recursive
bindings work by building a closure whose environment refers back to
itself, while the handler owns the actual environment map.

```nix
lookup = name: send "lookup" name;
getEnv = send "getEnv" null;
fail = msg: send "fail" msg;

run = expr:
  let result = handle {
    handlers = mkHandler { };
    state = { env = { }; };
  } (eval expr);
  in if result ? error then throw "eval error: ${result.error}" else result.value;
```

## Benchmark generators

`exprs.nix` generates large recursive and nested expressions. The
benchmark suite imports these generators from `examples/interp`.

```nix
interp.exprs.benchmarks.fib10
interp.exprs.benchmarks.lets500
interp.exprs.benchmarks.sum1000
```



#### Build Simulator


This example models a small build planner. Nodes depend on other nodes,
builders consume dependency outputs, and handlers provide cache,
configuration, logging, and failure behavior.

The graph generators produce the scalable workloads used by the
benchmark suite.

## Graph nodes

Nodes are plain Nix records. A builder receives the evaluated
dependency results and configuration, then returns either a value or
an error marker.

```nix
leaf = name: value: {
  inherit name;
  deps = [ ];
  builder = { deps, config }: value;
};

sumBuilder = { deps, config }:
  builtins.foldl' (acc: v: acc + v) (config.base or 0)
    (builtins.attrValues deps);
```

## Effectful evaluation

The evaluator requests cache reads, cache writes, configuration,
logging, and failure through effects. Swapping the handler changes
observability without changing graph traversal.

```nix
eval = graph:
  handle { handlers = handlersWithLogging; state = mkState graph; }
    (buildNode graph.root);

evalQuiet = graph:
  handle { handlers = handlersQuiet; state = mkState graph; }
    (buildNode graph.root);
```

## Benchmark generators

`graphs.nix` generates linear, wide, diamond, tree, mixed, and
failing graphs. The benchmark suite imports them from
`examples/build-sim`.

```nix
buildSim.graphs.benchmarks.linear500
buildSim.graphs.benchmarks.diamond10
buildSim.graphs.benchmarks.mixed_large
```



## API Reference

### Core API

#### Kernel


Freer monad kernel: Return/OpCall ADT with FTCQueue bind, `send`, `map`, `seq`, `pipe`, `kleisli`.

## `bind`

_bind: sequence two computations; if the first is `Pure`, apply `f` to its value; otherwise snoc `f` onto the FTCQueue for O(1) per-step composition._

```
bind : Computation a -> (a -> Computation b) -> Computation b
```

Monadic bind:

```
bind comp f = case comp of
  Pure a     -> f a
  Impure e q -> Impure e (snoc q f)
```

O(1) per bind via FTCQueue snoc (Kiselyov & Ishii 2015, section 3.1).

## `impure`

_impure: re-export of `fx.comp.impure` for kernel consumers._

```
impure : Effect -> FTCQueue -> Computation a
```

Re-export of the computation `Impure` constructor.

## `kleisli`

_kleisli: compose two Kleisli arrows `(a -> M b)` and `(b -> M c)` into a single `(a -> M c)`; the arrow product of the freer-monad Kleisli category._

```
kleisli : (a -> Computation b) -> (b -> Computation c) -> a -> Computation c
```

Kleisli composition. Compose two Kleisli arrows into a single arrow. The associative `>=>` operator in Haskell terminology.

## `map`

_mapComp (exported as `map`): apply `f` to the eventual result of a computation (Functor instance); implemented as `bind comp (x: pure (f x))`._

```
map : (a -> b) -> Computation a -> Computation b
```

Map a function over the result of a computation (Functor instance). Exposed as `map` at the module's top-level.

## `pipe`

_pipe: chain a computation through a list of Kleisli arrows, threading each result into the next via bind; the empty arrow list yields `init` unchanged._

```
pipe : Computation a -> [(a -> Computation b)] -> Computation b
```

Chain a computation through a list of Kleisli arrows. Each arrow's input is the previous arrow's output.

## `pure`

_pure: re-export of `fx.comp.pure` for kernel consumers._

```
pure : a -> Computation a
```

Re-export of the computation `Pure` constructor.

## `queue`

_queue: re-export of the FTCQueue namespace for advanced handler composition and adaptation._

```
queue : Namespace
```

Re-export of `fx.queue` for advanced use.

## `send`

_send: lift an effect request named `name` carrying `param` into a computation suspended at that effect; the handler's response resumes via the continuation queue._

```
send : String -> a -> Computation b
```

Send an effect request. Returns an `Impure` computation whose continuation queue resolves to the handler's response.

## `seq`

_seq: thread a list of computations left-to-right via bind, discarding intermediate values and returning only the last; the empty list yields `pure null`._

```
seq : [Computation a] -> Computation a
```

Sequence a list of computations, threading effects via `bind`. Returns the last result; intermediate values are discarded.



#### Comp


Computation ADT: introduction and elimination forms for `Pure | Impure`.

## `impure`

_impure: build a suspended computation (`Impure` constructor) carrying an effect request and a continuation queue to resume against._

```
impure : { name, param } -> FTCQueue -> Computation a
```

Create a suspended computation. The OpCall constructor of the freer monad — pairs an effect with the continuation queue.

## `isComp`

_isComp: test whether a value is a computation (has `_tag` of `Pure` or `Impure`); returns `false` for any other Nix value._

```
isComp : a -> Bool
```

Test whether a value is a computation. Returns `true` iff `_tag` is `Pure` or `Impure`.

## `isPure`

_isPure: hot-path predicate for `_tag == "Pure"`; cheaper than `match` for branching since it avoids the case-record allocation._

```
isPure : Computation a -> Bool
```

Test whether a computation is `Pure`. For hot-path conditionals where `match` would allocate a case record.

## `match`

_match: eliminate a computation by cases, dispatching to `pure` or `impure` clauses; consumers should use this instead of inspecting `_tag` directly._

```
match : Computation a -> { pure : a -> b, impure : Effect -> FTCQueue -> b } -> b
```

Eliminate a computation by cases:

```
match comp { pure = a: ...; impure = effect: queue: ...; }
```

Every function that consumes a `Computation` should go through
`match` or `isPure` — never inspect `_tag` directly.

## `pure`

_pure: lift a value into a pure computation (`Pure` constructor); the trivial computation that returns the value without performing any effect._

```
pure : a -> Computation a
```

Lift a value into a pure computation. The Return constructor of the freer monad.



#### Binds


Idiomatic Nix bind helpers: `bindAttrs`, `bindComp`, `bindFn`, plus the `optionalArg` sentinel.

## `bindAttrs`

_bindAttrs: sequence an attrset of effectful or send-able values; non-computation values become `send name value`, `optionalArg` probes via `has-handler` first._

```
bindAttrs : { <name> = Computation a | OptionalArg | Param; __sort? = [String] -> [String] } -> Computation { <name> = a }
```

Like a bind-chain but operates over named attrset of required-effects.

```nix
bind.attrs { foo = 99; bar = pure 22; baz = asks (env: env.baz); }
```

Values that are non-effects become send params: `send "foo" 99`.
Pass the `optionalArg` sentinel to mark a key as optional: bindAttrs
probes via `has-handler` first and omits the key when no handler is
installed (so a Nix function's default value can take over).

Result has same attr-keys with corresponding effect result.

See also: `bind.comp`, `bind.fn` for which this is the foundation.

# NOTE: Ordering of chained effects.

Since an attrSet has no order, this function chains effects in
same order as `builtins.attrNames` (alphabetical). If you need
an special order for computations that might be order senstive,
specify a `__sort = names => names` function.

## `bindComp`

_bindComp: turn an effectful function into an effect chain via `bindAttrs`; required args become required sends, optional args (with Nix defaults) probe via `has-handler`._

```
bindComp : { <name> = Computation a | Param } -> ({ <args> }: Computation b) -> Computation b
```

Turns a Nix effectful function into an effect chain via bindAttrs.

```nix
bindComp { bar = pure 22; } ({ foo, bar }: pure (foo * bar))
```

The function sees bar as the result of `pure 22` and `foo` as the
result of `send "foo" false` -- false comes directly from using
`lib.functionArgs f`, the handler can know if "foo" is optional in f.

Optional args (those with defaults in the Nix function) are probed
via has-handler before sending. If no handler exists, the arg is
skipped and the Nix default kicks in.

This works by using `bindAttrs` on the intersection of function args
and attrs.

## `bindFn`

_bindFn: like `bindComp` but for pure Nix functions; lifts the function's result into `pure` while still resolving its arguments through the effect system._

```
bindFn : { <name> = Computation a | Param } -> ({ <args> }: b) -> Computation b
```

Like bindComp but works on normal Nix functions and turns
its result into a pure-effect.

```nix
bindFn { bar = pure 22; } ({ foo, bar }: foo * bar)
```

## `optionalArg`

_optionalArg: sentinel for `bindAttrs`/`bindComp` optional effect arguments; absent handlers omit the attr so Nix defaults can apply._

```
optionalArg : OptionalArg
```

Sentinel value marking an attr as handler-conditional in `bindAttrs`.



#### Trampoline


Trampolined interpreter using `builtins.genericClosure` for O(1) stack depth.

## `handle`

_handle: trampolined handler combinator with a custom `return` clause; interprets the computation through `handlers` from initial `state` then folds the pair via `return`._

```
handle : { return ? Identity, handlers, state ? null } -> Computation a -> { value, state }
```

Trampolined handler combinator with `return` clause.

Follows Kiselyov & Ishii's `handle_relay` pattern but trampolined
via `genericClosure` for O(1) stack depth.

**Arguments** (attrset):
- `return` — `value -> state -> { value, state }`. How to transform the final Pure value. Default: identity.
- `handlers` — `{ effectName = { param, state }: { resume | abort, state }; }`. Each must return `{ resume; state; }` or `{ abort; state; }`.
- `state` — initial handler state. Default: null.

**Handler state and closure-valued fields** — the trampoline
`deepSeq`-forces handler state at each step. Derivations and other
values that hang under `deepSeq` must be wrapped with
`fx.state.thunk.mkThunk` before being stored in handler state, and
unwrapped with `fx.state.thunk.forceThunk` after `handle` returns.
Closure-valued fields are opaque to `deepSeq` and don't need wrapping,
but any attrset field reachable from state that contains a derivation
or pointer-cyclic value does.

## `rotate`

_rotate: selectively handle known effects and rotate unknown ones outward; matches the Kyo-style handler-rotation law for nested scopes._

```
rotate : { return ? Identity, handlers, state ? null } -> Computation a -> Computation b
```

Selectively handle known effects and rotate unknown effects outward.

If the current effect has a matching handler, the handler is applied.
If it does not match, the effect is re-suspended and its continuation
is wrapped so handling resumes after that effect is interpreted by an
outer handler.

This corresponds to the Kyo-style handler rotation law
from https://gist.github.com/vic/3a7f52974a28675dbaf40b34bec74787:

```
handle(tag1, suspend(tag2, i, k), f) = suspend(tag2, i, x => handle(tag1, k(x), f))` for `tag1 != tag2
```

## `run`

_run: drive a computation through the `genericClosure` trampoline with a handler attrset and initial state; returns `{ value, state }` at O(1) stack depth._

```
run : Computation a -> Handlers -> State -> { value : a, state : State }
```

Run a computation through the `genericClosure` trampoline.

**Arguments:**
- `comp` — the freer monad computation to interpret
- `handlers` — `{ effectName = { param, state }: { resume | abort, state }; ... }`
- `initialState` — starting state passed to handlers

Handlers must return one of:

```
{ resume = value; state = newState; }  -- invoke continuation with value
{ abort  = value; state = newState; }  -- discard continuation, halt
```

This is the defunctionalized encoding of Plotkin & Pretnar (2009):
`resume` ≡ invoke continuation k(v), `abort` ≡ discard k.

Stack depth: O(1) — constant regardless of computation length.
Time: O(n) where n = number of effects in the computation.

**Handler state and closure-valued fields** — the trampoline
`deepSeq`-forces handler state at each step. Derivations and other
values that hang under `deepSeq` must be wrapped with
`fx.state.thunk.mkThunk` before being stored in handler state, and
unwrapped with `fx.state.thunk.forceThunk` after `run` returns.
Closure-valued fields are opaque to `deepSeq` and don't need wrapping,
but any attrset field reachable from state that contains a derivation
or pointer-cyclic value does.



#### Queue


FTCQueue (catenable queue, after Kiselyov & Ishii 2015). O(1) `snoc`/`append`, amortized O(1) `viewl`.

## `append`

_append: concatenate two queues in O(1); identity queues short-circuit and the `__rawResume` rotation flag is propagated when present._

```
append : FTCQueue a b -> FTCQueue b c -> FTCQueue a c
```

Concatenate two queues. O(1).

Identity queues short-circuit (return the other side untouched).
The `__rawResume` flag is preserved so `fx.bind` chains around
`scope.provide` retain deep-handler semantics.

## `leaf`

_leaf: build a singleton FTCQueue containing one continuation; the leaf of the catenable-tree representation._

```
leaf : (a -> Computation b) -> FTCQueue a b
```

Create a singleton queue containing one continuation function.

## `node`

_node: join two FTCQueues into a balanced tree node; O(1) concatenation that defers traversal cost to `viewl`._

```
node : FTCQueue a x -> FTCQueue x b -> FTCQueue a b
```

Join two queues. O(1) — just creates a tree node; the cost is amortised by `viewl` during deconstruction.

## `qApp`

_qApp: apply a queue of continuations to a starting value; trampolines pure continuations via `genericClosure` and halts at the first `Impure` result._

```
qApp : FTCQueue a b -> a -> Computation b
```

Apply a queue of continuations to a value. Processes continuations
left-to-right: if a continuation returns `Pure`, feed the value
to the next continuation. If it returns `Impure`, append the
remaining queue to the effect's own queue and return.

## `singleton`

_singleton: alias for `leaf`; build an FTCQueue from a single continuation function with no nesting._

```
singleton : (a -> Computation b) -> FTCQueue a b
```

Create a queue with a single continuation. O(1). Synonym for `leaf`.

## `snoc`

_snoc: append one continuation to the right end of a queue in O(1); preserves the `__rawResume` rotation flag for deep-handler semantics._

```
snoc : FTCQueue a b -> (b -> Computation c) -> FTCQueue a c
```

Append a continuation to the right of the queue. O(1).

Preserves the `__rawResume` flag through extension so deep-handler
rotation continuations keep routing effectful resumes back through
inner-scope handlers.

## `viewl`

_viewl: extract the leftmost continuation from a queue with amortised O(1) cost via `viewlGo` rotation; returns `{ head, tail }`, `tail = null` for singletons._

```
viewl : FTCQueue a b -> { head : (a -> Computation b), tail : FTCQueue a b | null }
```

Extract the leftmost continuation from the queue. Amortized O(1).

Returns `{ head = fn; tail = queue | null; }` — `tail` is `null`
when the queue had only one element.



#### Adapt


Handler context transformation. Contravariant on context, covariant on continuation.

## `adapt`

_adapt: lift a child-state handler through a `get`/`set` lens onto parent state; contravariant on context extraction, covariant on result incorporation._

```
adapt : { get : P -> S, set : P -> S -> P } -> Handler S -> Handler P
```

Transform a handler's state context.

Wraps a handler that works with child state `S` so it works with
parent state `P`, using a `get`/`set` lens. Propagates both
`resume` and `abort`.

```nix
counterHandler = { param, state }: { resume = null; state = state + param; };
adapted = adapt { get = s: s.counter; set = s: c: s // { counter = c; }; } counterHandler;
# adapted now works with { counter = 0; logs = []; } state
```

## `adaptHandlers`

_adaptHandlers: lift an entire handler set through the same `get`/`set` lens; equivalent to mapping `adapt` over each handler in the attrset._

```
adaptHandlers : { get : P -> S, set : P -> S -> P } -> Handlers S -> Handlers P
```

Adapt an entire handler set (attrset of handlers) to a different state context.
Applies the same `get`/`set` lens to every handler in the set.

```nix
stateHandlers = {
  get = { param, state }: { value = state; inherit state; };
  put = { param, state }: { value = null; state = param; };
};
adapted = adaptHandlers { get = s: s.data; set = s: d: s // { data = d; }; } stateHandlers;
```



#### Pipeline


Typed pipeline framework with composable stages.

Stages are composable transformations executed with reader (immutable
environment), error (collecting validation errors), and acc (non-fatal
warnings) effects. The run function wires up all handlers and returns
{ value, errors, warnings, typeErrors }.

```nix
let
  stage1 = pipeline.mkStage {
    name = "discover";
    transform = data:
      bind (pipeline.asks (env: env.config)) (cfg:
        pure (data // { config = cfg; }));
  };
  result = pipeline.run { config = "prod"; } [ stage1 ];
in result  # => { config = "prod"; }
```

## `ask`

_ask: reader-effect helper returning the full pipeline environment._

```
ask : Computation Env
```

Convenience re-export of `fx.effects.reader.ask`.

## `asks`

_asks: reader-effect helper applying a projection to the pipeline environment._

```
asks : (Env -> a) -> Computation a
```

Convenience re-export of `fx.effects.reader.asks`.

## `bind`

_bind: re-export of `fx.kernel.bind` for pipeline stage implementations._

```
bind : Computation a -> (a -> Computation b) -> Computation b
```

Re-export of `fx.kernel.bind`.

## `compose`

_compose: chain a list of stages into a single computation; each stage's transform receives the previous output and returns the next stage's input wrapped in a computation._

```
compose : [Stage] -> Data -> Computation Data
```

Chain stages into a single computation.

Each stage's transform receives the output of the previous stage
and returns a computation producing the next stage's input.
Initial data seeds the pipeline.

## `map`

_map: re-export of `fx.kernel.map` for pipeline stage implementations._

```
map : (a -> b) -> Computation a -> Computation b
```

Re-export of `fx.kernel.map`.

## `mkStage`

_mkStage: build a named pipeline stage carrying a `transform`, optional `inputType`/`outputType` schemas, and a `description`; stages chain through `compose`._

```
mkStage : { name, description ? "", transform, inputType ? null, outputType ? null } -> Stage
```

Create a named pipeline stage.

`transform : Data -> Computation Data`
  Takes current pipeline data, uses effects (ask, raise, warn),
  returns computation producing updated pipeline data.

inputType/outputType : optional type schemas for validation
  at stage boundaries (checked when provided).
  Validation uses fx.types.validate which sends typeCheck effects.

## `pure`

_pure: re-export of `fx.kernel.pure` for pipeline stage implementations._

```
pure : a -> Computation a
```

Re-export of `fx.kernel.pure`.

## `raise`

_raise: collecting-error helper for pipeline stages._

```
raise : String -> Computation a
```

Convenience re-export of `fx.effects.error.raise`.

## `raiseWith`

_raiseWith: collecting-error helper with context for pipeline stages._

```
raiseWith : Context -> String -> Computation a
```

Convenience re-export of `fx.effects.error.raiseWith`.

## `run`

_run: execute a pipeline with reader/error/acc/typecheck handlers wired up; returns `{ value, errors, warnings, typeErrors }` from the final state._

```
run : Args -> [Stage] -> { value : Data, errors : [Err], warnings : [Warn], typeErrors : [Err] }
```

Execute a pipeline with effect handling.

`args : { ... }`
  Becomes the reader environment -- stages access via ask/asks.

stages : [Stage]
  Ordered list of stages to execute.

Returns:
  value      -- final pipeline data from last stage
  errors     -- list of { message, context } from validation failures
  warnings   -- list of non-fatal warning items
  typeErrors -- list of type validation errors

## `warn`

_warn: accumulator helper for non-fatal pipeline warnings._

```
warn : a -> Computation null
```

Convenience re-export of `fx.effects.acc.emit`.



#### State


The trampoline deepSeq-forces handler state at each step;
derivations and other cyclic attrsets hang. `mkThunk` wraps a
value as `{ _tag = "Thunk"; _force = _: value; }` — Nix never
recurses into a closure environment, so deepSeq sees only the
inert tag and closure. Wrap before storing; unwrap with
`forceThunk` after `fx.run`/`fx.handle` returns.

## Sub-namespaces

- [`thunk`](/nix-effects/core-api/state/thunk)

## Source

- [`src/state/thunk.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/state/thunk.nix)



#### Thunk


Runtime carrier module. Three exports:

  mkThunk    : a       -> Thunk a
  forceThunk : Thunk a -> a
  isThunk    : Value   -> Bool

A `Thunk` is `{ _tag = "Thunk"; _force = _: value; }`. The value is
captured in the closure's environment, where `builtins.deepSeq` cannot
reach it. The companion HOAS combinator `H.thunk inner` provides the
structurally-lazy kernel type former.

This carrier is intentionally runtime-only: the HOAS `thunk`
combinator supplies the typed surface, and handlers use the carrier
to keep state transport lazy under trampoline evaluation.

## `forceThunk`

_forceThunk: recover the value hidden inside a Thunk carrier; rejects raw values and malformed carriers._

```
forceThunk : Thunk a -> a
```

Recover the value captured inside a `Thunk` carrier.

## `isThunk`

_isThunk: predicate recognizing Thunk carriers by their `_force` closure._

```
isThunk : Value -> Bool
```

Return true when a value has the Thunk carrier shape.

## `mkThunk`

_Thunk: deepSeq-safe carrier for transporting values through trampoline-threaded handler state via a closure that hides the value from `builtins.deepSeq`._

```
mkThunk : a -> Thunk a
```

A `Thunk` is `{ _tag = "Thunk"; _force = _: value; }`. The value is
captured in the closure's environment, where `builtins.deepSeq` cannot
reach it. The companion HOAS combinator `H.thunk inner` provides the
structurally-lazy kernel type former.

This carrier is intentionally runtime-only: the HOAS `thunk`
combinator supplies the typed surface, and handlers use the carrier
to keep state transport lazy under trampoline evaluation.



#### Sugar


Opt-in syntax-livability layer for nix-effects.

- `fx.sugar.do` / `fx.sugar.letM` — combinator forms
- `fx.sugar.operators.__div` — `/` as reverse-apply (bind)
- re-exports of `pure bind run handle map seq pipe kleisli`

See `book/src/sugar.md` for the opt-in matrix and caveats.

## `bind`

_Re-export of fx.kernel.bind. See fx.kernel for details._

## `do`

_do: build a composable Kleisli arrow `(a -> M b)` from a list of steps; plain functions `(a -> b)` are auto-lifted via `pure`, monadic functions `(a -> M b)` pass through. Apply the result to a seed to obtain a `Comp b`._

```
do : [a -> b | a -> M b] -> (a -> M b)
```

Use when steps form a linear pipeline that should remain
point-free and composable. Because `do` returns a Kleisli arrow,
two pipelines glue without lambdas:
`kleisli (do [f g]) (do [h i]) == do [f g h i]`. Data-last
argument order makes `map (do [validate enrich]) xs` natural.

Auto-lifting lets pure and effectful steps mix freely — runtime
dispatch via `isComp` decides whether to thread through `map` or
`bind`. An empty list gives the identity arrow `x: pure x`.

Prefer `steps` when discarding intermediate values is intentional
(effect sequencing). Prefer `kleisli` for a single binary
composition. Use `letM` when bound values are siblings rather
than a left-to-right pipeline.

## `handle`

_Re-export of fx.trampoline.handle. See fx.trampoline for details._

## `kleisli`

_Re-export of fx.kernel.kleisli. See fx.kernel for details._

## `letM`

_letM: `attrs`-based monadic binding — runs `bindAttrs attrs` to gather a record of results, then passes the record to continuation `k` for the next step._

```
letM : { name = Comp a } -> ({ name = a } -> Comp b) -> Comp b
```

Use when several independent computations must complete before a
single dependent step runs — `letM { a = ca; b = cb; } ({ a, b }: ...)`
replaces a nested `bind ca (a: bind cb (b: ...))` chain with a
flat record. Field order in the resulting record is unspecified;
ordering of side effects across fields is determined by
`bindAttrs`, not by the caller's attribute layout.

Prefer over `do` when the bound values are siblings rather than a
left-to-right pipeline. For a single bind, plain `bind` is
clearer.

## `map`

_Re-export of fx.kernel.map. See fx.kernel for details._

## `operators`

_operators: sugar operator overloads — currently `__div` aliasing `fx.kernel.bind` so `c / k` reads as `bind c k` in expression context._

Opt-in operator-style monadic composition. The attrset's
`__div` field is invoked by Nix's `/` operator when the LHS
is an attrset carrying `__div`. Use sparingly: operator
overloading is non-idiomatic in Nix and obscures dataflow for
readers unfamiliar with the convention. The combinator forms
(`bind`, `do`, `kleisli`) remain the canonical entry points.

## `pipe`

_Re-export of fx.kernel.pipe. See fx.kernel for details._

## `pure`

_Re-export of fx.kernel.pure. See fx.kernel for details._

## `run`

_Re-export of fx.trampoline.run. See fx.trampoline for details._

## `seq`

_Re-export of fx.kernel.seq. See fx.kernel for details._

## `steps`

_steps: sequence a list of `Comp` steps left-to-right via `bind`, returning a single composed `Comp`; each step receives the previous result, the seed is `pure null`._

```
steps : [a -> Comp b] -> Comp b
```

Use when only the side effects of each step matter — analogous to
Haskell's `sequence_`. The seed value is `pure null`, so the
first step's argument is `null`; discard it if the first step is
producer-shaped (`_: pure x`). An empty list returns `pure null`.

Prefer `do` for composable, point-free Kleisli pipelines that
thread values. Prefer `kleisli` when composing two Kleisli
arrows without an initial value, and `pipe` when threading a
non-monadic seed through effectful transforms.

## `types`

_types: refinement-applicable type wrappers — each primitive becomes a `__functor`-bearing record so `Int (n: n > 0)` chains another `refined` layer; `wrap` lifts an arbitrary type into the same callable form._

Sugar layer over `fx.types.refinement.refined`. Each entry
carries `__functor self pred = sugared (refined "name?" self pred)`,
so calling a type as a function tightens it with a predicate.
`__toString self = self.name` makes interpolated names
readable. The wrapped primitives (`Int`, `String`, `Bool`,
`Float`, `Path`, `Null`, `Unit`, `Any`) come from
`fx.types.primitives`; `wrap` lets callers lift any other
type into the same chainable shape.

## Source

- [`src/sugar/effects.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/sugar/effects.nix)
- [`src/sugar/operators.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/sugar/operators.nix)
- [`src/sugar/types.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/sugar/types.nix)



#### Build


`plan` validates a sequence of `BuildStep` records via
`fx.pipeline.run` (reader/error/acc effects). `materialize` lowers
a validated plan to a `pkgs.runCommand` derivation; shell
generation is pure and tested inline.

## `materialize`

_materialize: convert a validated `BuildPlan` into a `pkgs.runCommand` derivation; copies sources, scopes per-step env vars, runs steps under `set -euo pipefail`._

```
materialize : { pkgs, plan, native ? [] } -> Derivation
```

Materialize a validated `BuildPlan` into a derivation.

Converts the eval-time plan (validated by `fx.build.plan`) into a
`pkgs.runCommand` derivation. Sources are copied into a working
directory, per-step environment variables are scoped, and steps
execute sequentially under `set -euo pipefail`.

The `plan` argument is the `.plan` field from `fx.build.plan`'s output.
Shell generation helpers (`mkStepScript`, `mkSourceSetup`,
`mkBuildScript`) are pure functions tested inline.

## `plan`

_plan: validate build steps against `BuildStep`, filter by `when` predicates against reader context, and collect errors/warnings without throwing._

```
plan : { name, steps, sources ? {}, context ? {} } -> { plan : BuildPlan, errors : [Err], warnings : [Warn], typeErrors : [Err] }
```

Validate and process build steps into a `BuildPlan`.

Runs an eval-time pipeline that validates each step against
`BuildStep`, filters steps by `when` predicates using reader
context, and collects all errors without throwing.

## Sub-namespaces

- [`types`](/nix-effects/core-api/build/types)

## Source

- [`src/build/materialize.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/build/materialize.nix)
- [`src/build/plan.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/build/plan.nix)
- [`src/build/types.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/build/types.nix)



#### Types


Build types for effects-powered builders.

`BuildStep` and `BuildPlan` describe build pipelines at the type level,
enabling validation before materialization into derivations.

## `BuildPlan`

_BuildPlan: open-record type for a complete build pipeline; requires non-empty `name` and a `[BuildStep]` list, permits `sources` and `context`._

Build plan: a complete build pipeline.

Required: `name` (non-empty), `steps` (list of `BuildStep`).
Optional (open record): `sources`, `context`.

## `BuildStep`

_BuildStep: open-record type for a single shell step in a build pipeline; requires non-empty `name` and `run`, permits `tools`/`env`/`when`/etc._

Build step: a single step in a build pipeline.

Required: `name` (non-empty), `run` (shell fragment).
Optional (open record): `description`, `tools`, `env`, `inputType`,
`outputType`, `when`.



#### Experimental


Names, shapes, and laws under this namespace may change without
deprecation cycles. Sub-modules are promoted out (and renamed)
once they stabilise.

## Sub-namespaces

- [`desc-interp`](/nix-effects/core-api/experimental/desc-interp)



#### Desc-interp


`desc.nix` encodes FreeFx as `plus pureSummand impureSummand`;
continuations live in an FTCQueue value (Kiselyov & Ishii) rather
than meta-level Nix functions. `kernel.nix` mirrors `fx.kernel`'s
`pure`/`send`/`bind`; `bind` snocs into the Impure summand's
queue without recursing on the μ-tree. `trampoline.nix` drives
programs via `builtins.genericClosure` at O(1) host stack depth.

## Handler shortcut layering

Each canonical handler op admits a partial-evaluation residual
that bypasses kernel `vApp` per Impure step. Soundness splits:

- **kernel-side** (`effects/*-shortcut-laws.nix`): `H.refl` lemma
  `handle_X op s ≡_kernel mkResumeAt … r s` (resp. `mkAbortAt`)
  certifying the per-op rewrite under ι+β.
- **emitter-side** (`extract.nix`): per-primitive Val-conv test
  `eval (HOAS witness) ≡_Val extract (Primitive …)`. Sugars
  (`Resume`/`Abort`/`PairRaw`) fold into primitives.
- **composed-side** (`compose.nix` + `composed-shortcut.nix` +
  `composed-shortcut-laws.nix`): `composeHandlers` over UniRet
  closes the algebra under `+`. Six lemmas chain
  `composeHandlersInl/InrLemma` with per-effect uniform-shortcut
  lemmas; `composedHandlerShortcut` mirrors the kernel-composed
  path by direct Val construction.

## Adding a new effect with a handler shortcut

Recipe — apply in order:

1. **Identify canonical RHS shapes.** Reduce `handle_X op s` per
   constructor via ι+β. Each canonical op should normalise to
   `mkResumeAt … r s` or `mkAbortAt … v s` (or a bare `H.pair _
   _` outside the UniRet shape).

2. **Extend `extract.nix` only if needed.** Existing sugars cover
   the UniRet and bare-pair shapes; primitives (`DescCon`,
   `BootInl`, `BootInr`, `Pair`, `Tt`, `BootRefl`) suffice for
   anything else. Add a sugar only when a non-trivial shape
   repeats across multiple effects.

3. **Write `effects/x-shortcut-laws.nix`.** One `H.refl` lemma per
   canonical op asserting `handle_X op s ≡_kernel mkXAt …`.
   Mirror `effects/state-shortcut-laws.nix`'s `withPrefix`/
   `lamPrefix` helper layout. If `uniformOf_X` differs from
   `handle_X` (error's three strategies), add
   `effects/x-uniform-shortcut-laws.nix` too.

4. **Wire `handlerShortcut` in `atType`.** Pre-compute metadata
   Vals (`leftSig`, `rightSig`, `sumDescVal`) once per
   instantiation; in `handlerShortcut op stateVal`, dispatch on
   `op._opTag` and return `extract (Resume …)` /
   `extract (Abort …)` / `extract (PairRaw …)`. Smart
   constructors tag canonical ops via `_opTag = "<effect>-<op>"`.
   If `uniformOf_X` is needed for composition, expose
   `uniformOfShort` (or `uniformOfShortAt A` if A varies
   post-`atType`).

5. **Add parity tests in `trampoline.nix`.** For each canonical
   op, compare `runX { handler; dispatch; }` vs
   `runX { handler; dispatch; handlerShortcut; }` via
   `fx.tc.conv.conv 0` on both `.value` and `.state`. For ops
   that abort with a Nix throw (strict-style), force `.state.tag`
   under `builtins.tryEval` and assert both paths trip the throw.

Composition with another effect via `composeHandlers` reuses the
per-effect `uniformOfShort` plus `composedHandlerShortcut H_short_A
H_short_B metaFor`; soundness is anchored kernel-side by
`composed-shortcut-laws.nix` without any per-effect-pair work.

## Sub-namespaces

- [`compose`](/nix-effects/core-api/experimental/desc-interp/compose)
- [`compose-laws`](/nix-effects/core-api/experimental/desc-interp/compose-laws)
- [`composed-shortcut`](/nix-effects/core-api/experimental/desc-interp/composed-shortcut)
- [`composed-shortcut-laws`](/nix-effects/core-api/experimental/desc-interp/composed-shortcut-laws)
- [`desc`](/nix-effects/core-api/experimental/desc-interp/desc)
- [`descind-laws`](/nix-effects/core-api/experimental/desc-interp/descind-laws)
- [`effects`](/nix-effects/core-api/experimental/desc-interp/effects)
- [`extract`](/nix-effects/core-api/experimental/desc-interp/extract)
- [`kernel`](/nix-effects/core-api/experimental/desc-interp/kernel)
- [`trampoline`](/nix-effects/core-api/experimental/desc-interp/trampoline)

## Source

- [`src/experimental/desc-interp/compose-laws.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/compose-laws.nix)
- [`src/experimental/desc-interp/compose.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/compose.nix)
- [`src/experimental/desc-interp/composed-shortcut-laws.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/composed-shortcut-laws.nix)
- [`src/experimental/desc-interp/composed-shortcut.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/composed-shortcut.nix)
- [`src/experimental/desc-interp/desc.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/desc.nix)
- [`src/experimental/desc-interp/descind-laws.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/descind-laws.nix)
- [`src/experimental/desc-interp/extract.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/extract.nix)
- [`src/experimental/desc-interp/kernel.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/kernel.nix)
- [`src/experimental/desc-interp/trampoline.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/trampoline.nix)



#### Compose


fx.experimental.desc-interp.compose: universal handler-result type UniRet and its smart constructors. Every kernel-resident handler can be re-shaped into a UniRet-returning form; composeHandlers operates uniformly on that shape.

## `UniRet`

_UniRet : `Π (S:U) (Op:U) (Resp:Op→U) (op:Op) (A:U). U` — universal handler-result type. Left summand `Σ _r:(Resp op). S` = resume (response + new state). Right summand `Σ _a:A. S` = abort (final value + new state). State's `handle_StateTy` is conv-equal to `Π S A. Π op:EffState S. Π _s:S. UniRet S (EffState S) (Resp_State S) op A` — see the inline conv test below._

## `UniRetTy`

_Π-type of UniRet: `Π (S:U) (Op:U) (Resp:Op→U) (op:Op) (A:U). U`._

## `composeHandlers`

_composeHandlers S_A S_B Op_A Op_B Resp_A Resp_B A H_A H_B —
kernel-resident combinator taking two UniRet-shaped handlers and
producing a UniRet-shaped handler over the sum effect. Body
dispatches outer `sumElim` on `op`, projects the matching state
slot, runs the per-effect handler, then inner-`sumElim`s on the
UniRet result to re-package into the composed shape with the
threaded product state. The composed-law witness lifts
per-effect laws through this shape._

## `composeHandlersTy`

_Π-type of composeHandlers: `Π (S_A S_B Op_A Op_B : U). Π (Resp_A : Op_A → U). Π (Resp_B : Op_B → U). Π (A : U). (Π op:Op_A. Π _s:S_A. UniRet S_A Op_A Resp_A op A) → (Π op:Op_B. Π _s:S_B. UniRet S_B Op_B Resp_B op A) → Π op:(Sum Op_A Op_B). Π _s:(Σ S_A S_B). UniRet (Σ S_A S_B) (Sum Op_A Op_B) (composedResp Op_A Op_B Resp_A Resp_B) op A`._

## `composedResp`

_composedResp Op_A Op_B Resp_A Resp_B op — paired response family for the sum effect. sumElim-driven so `composedResp … (inl opA) ≡ Resp_A opA` and `composedResp … (inr opB) ≡ Resp_B opB` by iota; composeHandlers relies on this conv-equality to retype the mkResume r-argument._

## `composedRespAt`

_composedRespAt Op_A Op_B Resp_A Resp_B — Nix-level helper for the 4-arg composedResp spine; result has type `Π op:(Sum Op_A Op_B). U`._

## `composedRespTy`

_Π-type of composedResp: `Π (Op_A Op_B : U). Π (Resp_A : Op_A → U). Π (Resp_B : Op_B → U). Π op:(Sum Op_A Op_B). U`._

## `mkAbort`

_mkAbort : `Π S Op Resp op A. A → S → UniRet S Op Resp op A` — right-injection smart constructor._

## `mkAbortAt`

_mkAbortAt S Op Resp op A a s — Nix-level helper for the fully-applied mkAbort spine._

## `mkAbortTy`

_Π-type of mkAbort._

## `mkResume`

_mkResume : `Π S Op Resp op A. (Resp op) → S → UniRet S Op Resp op A` — left-injection smart constructor._

## `mkResumeAt`

_mkResumeAt S Op Resp op A r s — Nix-level helper for the fully-applied mkResume spine._

## `mkResumeTy`

_Π-type of mkResume._

## `uniRetAt`

_uniRetAt S Op Resp op A — Nix-level helper for the fully-applied UniRet spine; consumers avoid hand-rolling the 5-arg app each time._



#### Compose-laws


fx.experimental.desc-interp.compose-laws: kernel-checked one-shot meta-theorem for composeHandlers. Two clauses (inl/inr); both discharge by H.refl.

## `composeHandlersInlLemma`

_Inl clause proof: 12 lams + H.refl. checkHoas succeeds because kernel conv decides composeHandlers' iota universally._

## `composeHandlersInlLemmaTy`

_Inl clause Π-type: composeHandlers on (inl op_A, pair s_A s_B) ≡ sumElim … (H_A op_A s_A) (mkResume_composed …) (mkAbort_composed …) with s_B threaded._

## `composeHandlersInrLemma`

_Inr clause proof: 12 lams + H.refl._

## `composeHandlersInrLemmaTy`

_Inr clause Π-type: mirror of the inl clause with the state-slot roles swapped._



#### Composed-shortcut


Pipeline per Impure step on a composed op: read `op._side` /
`op._inner`, project the composed state with `extract.Project`,
recurse via the matching per-side shortcut, then `extract.OfElim`
on the sub-UniRet — Resume → composed Resume; Abort → composed
Abort — repacking the sibling state slot via `extract.PairRaw`.

Soundness: kernel-side `composedHandlerShortcutLemma`
(`composed-shortcut-laws.nix`) chains `composeHandlersInl/InrLemma`
with per-effect uniform-shortcut lemmas; emitter-side, the
`_self.tests` below conv-check kernel-composed vs shortcut-emitted
Vals at concrete canonical ops.

## `composedHandlerShortcut`

_composedHandlerShortcut H_short_A H_short_B metaFor op stateVal — composed UniRet Val mirroring `eval (composeHandlers … H_A H_B opVal stateVal)`. `op` carries `_side`/`_inner` sidecars from `composedInl`/`composedInr`; `metaFor` is the composed-UniRet metadata lookup keyed by inner-op tag; per-side shortcuts must return UniRet Vals. `null` propagates from any of the inputs (kernel fallback)._

## `composedInl`

_composedInl Op_A Op_B subOp — `H.inl Op_A Op_B subOp` with `_side = "composed-inl"`, `_inner = subOp`. Sidecars are ignored by elab and survive `K.send`'s `impureCon` wrap._

## `composedInr`

_composedInr Op_A Op_B subOp — `H.inr` counterpart of `composedInl`._

## `mkComposedMeta`

_mkComposedMeta { SigmaSHoas; A; respHoas; } — precompute `{ sumDescVal; leftSigVal; rightSigVal; }` for the composed UniRet at one canonical inner op (response type already ι-reduced)._



#### Composed-shortcut-laws


fx.experimental.desc-interp.composed-shortcut-laws: six H.refl lemmas — state's three canonical ops on inl and error's three strategies on inr — anchoring `composedHandlerShortcut` soundness. Each chains `composeHandlersInl/InrLemma`, the per-effect uniform-shortcut lemma, and inner `sumElim` ι; all three reductions are conv-decidable.

## `errorCollectingInrLemma`

_H.refl proof of `errorCollectingInrLemmaTy`. Resume payload := `tt`; new s_B := `cons E payload s_B`._

## `errorCollectingInrLemmaTy`

_`Π E S_A A. Π H_A. Π payload:E. Π s_A:S_A. Π s_B:List E. composeHandlers … H_A uniformOf_collecting (inr (error E payload)) (pair s_A s_B) ≡ mkResumeAt … tt (pair s_A (cons E payload s_B))`._

## `errorResultInrLemma`

_H.refl proof of `errorResultInrLemmaTy`. Abort channel `Sum E A_inner` carries `inl payload`._

## `errorResultInrLemmaTy`

_`Π E S_A S_B A_inner. Π H_A. Π payload:E. Π s_A:S_A. Π s_B:S_B. composeHandlers … H_A uniformOf_result (inr (error E payload)) (pair s_A s_B) ≡ mkAbortAt … (Sum E A_inner) (inl E A_inner payload) (pair s_A s_B)`._

## `errorStrictInrLemma`

_H.refl proof of `errorStrictInrLemmaTy`. Strict always aborts; abort payload := `payload`._

## `errorStrictInrLemmaTy`

_`Π E S_A S_B. Π H_A. Π payload:E. Π s_A:S_A. Π s_B:S_B. composeHandlers … H_A uniformOf_strict (inr (error E payload)) (pair s_A s_B) ≡ mkAbortAt … E payload (pair s_A s_B)`._

## `stateGetInlLemma`

_H.refl proof of `stateGetInlLemmaTy`. `handle_State (get S) s_A ι→ inl(pair s_A s_A)`; inner sumElim ι folds to the composed mkResumeAt._

## `stateGetInlLemmaTy`

_`Π E S_A A. Π H_B. Π s_A:S_A. Π s_B:List E. composeHandlers … handle_State H_B (inl (get S_A)) (pair s_A s_B) ≡ mkResumeAt … (inl (get S_A)) A s_A (pair s_A s_B)`._

## `stateModifyInlLemma`

_H.refl proof of `stateModifyInlLemmaTy`. New sub-state := `fn s_A`; resume payload := `tt`._

## `stateModifyInlLemmaTy`

_`Π E S_A A. Π H_B. Π fn:S_A→S_A. Π s_A:S_A. Π s_B:List E. composeHandlers … handle_State H_B (inl (modify S_A fn)) (pair s_A s_B) ≡ mkResumeAt … tt (pair (fn s_A) s_B)`._

## `statePutInlLemma`

_H.refl proof of `statePutInlLemmaTy`. New sub-state := `param`; resume payload := `tt`._

## `statePutInlLemmaTy`

_`Π E S_A A. Π H_B. Π param s_A:S_A. Π s_B:List E. composeHandlers … handle_State H_B (inl (put S_A param)) (pair s_A s_B) ≡ mkResumeAt … tt (pair param s_B)`._



#### Desc


fx.experimental.desc-interp.desc: freer monad encoded as a levitated Desc (freeFx = pure + impure plus continuation queue); the substrate descInterp runs.

## `freeFx`

_freeFx Eff Resp A : Desc¹ ⊤ — freer monad as a plus-of-two-summands description; the Impure summand's continuation slot is a queue value `μI U² (kontQueueApp Eff Resp) (Resp op, A)` rather than a meta-level fn._

```
freeFx : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas (Desc¹ ⊤)
```

## `freeFxApp`

_freeFxApp Eff Resp A — identity-tagged HOAS form of `freeFx Eff Resp A`; canonApp wrapper that stamps the resulting VDescCon with `_canonRef = { id = "freeFx"; params = [Eff, Resp, A]; }` so conv/quote short-circuit on the canonical identity._

```
freeFxApp : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas (Desc¹ ⊤)
```

## `impureCon`

_impureCon Eff Resp A op q — smart constructor for the Impure summand; `q : μI U² (kontQueueApp Eff Resp) (Resp op, A)` is a queue value carrying the continuation. Emits a desc-con HOAS form with a Desc¹ inr payload storing `op` and the ret witness through `LiftAt 0 1`._

```
impureCon : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas Eff -> Hoas (μI U² kontQueueApp …) -> Hoas (FreeFx Eff Resp A)
```

## `kontQueue`

_kontQueue Eff Resp : IDesc(U × U) — description-side FTCQueue (Kiselyov & Ishii 2015, section 3.1) at the indexed slice; three-summand plus encoding Identity / Leaf / Node where ∃M existentials are reified as descArgAt-bound index witnesses (CDMM 2010, section 6). Levitation transposition of `nix/nix-effects/src/queue.nix`._

```
kontQueue : Hoas U -> Hoas (U -> U) -> Hoas (IDesc (U × U))
```

## `kontQueueApp`

_kontQueueApp Eff Resp — identity-tagged HOAS form of `kontQueue Eff Resp`; canonApp wrapper that stamps the resulting VDescCon with `_canonRef = { id = "kontQueue"; params = [Eff, Resp]; }` so conv on μI(kontQueueApp …) self-equality short-circuits without forcing `.D`. X and A are dropped from the wrapper's params — the indexing is intrinsic to `IDesc(U × U)`._

```
kontQueueApp : Hoas U -> Hoas (U -> U) -> Hoas (IDesc (U × U))
```

## `pureCon`

_pureCon Eff Resp A v — smart constructor for the Pure summand; emits a desc-con HOAS form with a Desc¹ inl payload storing `v` and the ret witness through `LiftAt 0 1`._

```
pureCon : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas A -> Hoas (FreeFx Eff Resp A)
```

## `qIdentity`

_qIdentity Eff Resp X — smart constructor for the Identity summand of `kontQueue`; emits a desc-con HOAS form at index (X, X) with payload `bootInl (X, refl)` of the outer plus. Carries `_index = { X; A = X; }` sidecar._

```
qIdentity : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas (μI U² kontQueueApp …)
```

## `qLeaf`

_qLeaf Eff Resp X A fn — smart constructor for the Leaf summand; `fn : X → μ(freeFxApp Eff Resp A)` is a HOAS lam with `fn.domain == X` (host-level `==` is the principled Nix-meta surrogate for the descArgAt(X)-instantiation equality the kernel checker would enforce, mirroring qNode's seam check on `_index`). Emits a desc-con HOAS form at index (X, A) with payload `bootInr (bootInl (X, (A, (fn, refl))))` of the nested plus. Carries `_index = { X; A; }` sidecar._

```
qLeaf : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas U -> Hoas (X -> μ freeFx) -> Hoas (μI U² kontQueueApp …)
```

## `qNode`

_qNode Eff Resp l r — smart constructor for the Node summand; `l` and `r` are queue values whose `_index` sidecars supply the index witnesses. Seam M = l._index.A is asserted equal to r._index.X via Nix-level == (kernel has no surface metavariables; the host-level check is the principled enforcement). Emits a desc-con HOAS form at index (l._index.X, r._index.A) with payload `bootInr (bootInr (X, (M, (A, (l, (r, refl))))))` of the nested plus. Carries `_index = { X; A; }` sidecar._

```
qNode : Hoas U -> Hoas (U -> U) -> Hoas (μI U² kontQueueApp …) -> Hoas (μI U² kontQueueApp …) -> Hoas (μI U² kontQueueApp …)
```



#### Descind-laws


fx.experimental.desc-interp.descind-laws: kernel-level laws derived via `descInd kontQueueApp` at the indexed slice. Hosts qAppKernel (kernel-resident transposition of trampoline.qApp) and qAppIdLaw (qApp qIdentity x ≡ pure x as a kernel conv-witness).

## `qAppIdLaw`

_qAppIdLaw : Π(X:U). Π(x:X). bootEq (μ freeFx X) (qAppKernel (X,X) (qIdentity X) x) (pureCon X x). The Identity-collapse law as a kernel conv-witness; the proof is `bootRefl`, justified by descInd-on-descCon β through the Identity step body. Demonstrates that the indexed inductive hypothesis is operationally usable — the lemma's well-typedness depends essentially on `descInd kontQueueApp` projecting `fst_(i)` / `snd_(i)`._

```
qAppIdLaw : Π(X:U). Π(x:X). bootEq (μ freeFx X) (qAppKernel (X,X) (qIdentity X) x) (pureCon X x)
```

## `qAppIdLawTy`

_qAppIdLawTy Eff Resp: Π-type generated for the qApp identity law at one effect signature._

## `qAppKernel`

_qAppKernel Eff Resp i q x — kernel-resident `qApp` defined via `descInd kontQueueApp`. Identity branch returns `pureCon X x` (X = fst_(i) = snd_(i) forced by index); Leaf branch returns `fn x`; Node branch returns `bind (ih_l x) ih_r` cashing in both indexed IHs at (X,M) and (M,A). Mirrors `trampoline.qApp` but at the kernel layer._

```
qAppKernel : Hoas U -> Hoas (U -> U) -> Hoas U² -> Hoas (μI U² kontQueueApp i) -> Hoas (fst_(i)) -> Hoas (μ freeFxApp Eff Resp (snd_(i)) tt)
```



#### Effects


`error` exposes one op with `strict`/`collecting`/`result`
handler strategies. `state` declares `EffState : Π(S:U). U` with
`get`/`put`/`modify` and ships a kernel-term `handle_State`
head-normalised at run-entry by the trampoline bridge.
`typecheck` declares `EffTypeCheck : Π(R:U). U` with one `report`
op and six policy handlers: five fold a stream of membership
decisions, and `strict` throws on the first failure.

## Sub-namespaces

- [`error`](/nix-effects/core-api/experimental/desc-interp/effects/error)
- [`error-shortcut-laws`](/nix-effects/core-api/experimental/desc-interp/effects/error-shortcut-laws)
- [`error-uniform-shortcut-laws`](/nix-effects/core-api/experimental/desc-interp/effects/error-uniform-shortcut-laws)
- [`state`](/nix-effects/core-api/experimental/desc-interp/effects/state)
- [`state-shortcut-laws`](/nix-effects/core-api/experimental/desc-interp/effects/state-shortcut-laws)
- [`typecheck`](/nix-effects/core-api/experimental/desc-interp/effects/typecheck)
- [`typecheck-shortcut-laws`](/nix-effects/core-api/experimental/desc-interp/effects/typecheck-shortcut-laws)

## Source

- [`src/experimental/desc-interp/effects/error-shortcut-laws.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/effects/error-shortcut-laws.nix)
- [`src/experimental/desc-interp/effects/error-uniform-shortcut-laws.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/effects/error-uniform-shortcut-laws.nix)
- [`src/experimental/desc-interp/effects/error.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/effects/error.nix)
- [`src/experimental/desc-interp/effects/state-shortcut-laws.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/effects/state-shortcut-laws.nix)
- [`src/experimental/desc-interp/effects/state.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/effects/state.nix)
- [`src/experimental/desc-interp/effects/typecheck-shortcut-laws.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/effects/typecheck-shortcut-laws.nix)
- [`src/experimental/desc-interp/effects/typecheck.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/experimental/desc-interp/effects/typecheck.nix)



#### Error


Pair with `experimental.desc-interp.trampoline.run`:

```nix
let er = error.atType_strict H.string H.nat;
in run er.eff er.resp H.nat returnTy
     { handler = er.handler; dispatch = er.dispatch; }
     program initialState
```

Strategies differ in handler return shape and dispatch action:

  strict     : Σ State E              → action="throw"
  collecting : Σ (List E) Unit        → action="resume", response=tt
  result     : Σ State (Sum E A_inner)→ action="abort"

## `EffError`

_EffError : Π(E:U₀). U₀ — kernel datatype with one constructor `error(payload:E)`. Built via `H.datatypeP`; macro-derived `.T`, `.D`, `.elim`, and the `error` introducer._

## `EffErrorTy`

_Π-type of error's op-identity family: `Π(E:U₀). U₀`._

## `Resp_collecting`

_Collecting error response family; errors resume with Unit while accumulating payloads in state._

## `Resp_collectingTy`

_Π-type of collecting-error's response family: `Π(E:U₀). Π(_op:EffError E). U₀`. Body returns `Unit` — collecting always resumes with `tt`._

## `Resp_result`

_Result-channel error response family; errors abort into Sum E A_inner._

## `Resp_resultTy`

_Π-type of result-error's response family: `Π(E:U₀). Π(_op:EffError E). U₀`. Body returns `Void` — result never resumes (abort lives in the program's typed result channel)._

## `Resp_strict`

_Strict error response family; every error op has Void response because strict errors never resume._

## `Resp_strictTy`

_Π-type of strict-error's response family: `Π(E:U₀). Π(_op:EffError E). U₀`. Body returns `Void` at every op — strict never resumes._

## `atType_collecting`

_`atType_collecting E` — per-`E` monomorphisation of `handle_collecting` (State specialised to `List E`). Exposes the `State` field as a convenience for callers needing `H.nil E` initial values._

## `atType_result`

_`atType_result E State A_inner` — per-`(E, State, A_inner)` monomorphisation of `handle_result` with the `Sum E A_inner` result channel pre-built._

## `atType_strict`

_`atType_strict E State` — per-`(E, State)` monomorphisation of `handle_strict` with a `raise` smart constructor and `dispatch` interpreter pre-built. Pass `{ handler; dispatch; }` to the trampoline._

## `handle_collecting`

_Kernel collecting error handler; conses payloads into List E state and resumes with Unit._

## `handle_collectingTy`

_Π-type of the collecting error handler: `Π(E:U₀). Π(op:EffError E). Π(_s:List E). Σ (List E) Unit`. Always resumes — handler accumulates errors into `List E` state, signals resume via `tt`. Dispatch action = `"resume"`._

## `handle_result`

_Kernel result error handler; aborts with Sum E A_inner while preserving state._

## `handle_resultTy`

_Π-type of the result error handler: `Π(E State A_inner:U₀). Π(op:EffError E). Π(_s:State). Σ State (Sum E A_inner)`. Always aborts — handler returns `inl payload` in the Sum-typed result channel. Dispatch action = `"abort"`._

## `handle_strict`

_Kernel strict error handler; maps raise to throw-shaped Σ State E._

## `handle_strictTy`

_Π-type of the strict error handler: `Π(E State:U₀). Π(op:EffError E). Π(_s:State). Σ State E`. Non-resumable — handler surrenders the error payload with the final state. Dispatch action = `"throw"`._

## `uniformOf_collecting`

_`uniformOf_collecting E A`: UniRet-shaped adapter for `handle_collecting`. Dispatches via EffError.elim so the resume payload `tt : Unit ≡ Resp_collecting E (error E payload)` types in each branch._

## `uniformOf_collectingTy`

_Π-type of `uniformOf_collecting`: UniRet at S := List E, with A as a phantom parameter (collecting never aborts)._

## `uniformOf_result`

_`uniformOf_result E State A_inner`: UniRet-shaped adapter for `handle_result`. Projects `Σ State (Sum E A_inner)` into `mkAbort … sumPayload state`._

## `uniformOf_resultTy`

_Π-type of `uniformOf_result`: UniRet at A := Sum E A_inner (handle_result's typed result channel becomes the abort value)._

## `uniformOf_strict`

_`uniformOf_strict E State`: UniRet-shaped adapter for `handle_strict`. Projects `Σ State E` into `mkAbort … e s`; always inhabits the right summand._

## `uniformOf_strictTy`

_Π-type of `uniformOf_strict`: UniRet at A := E (the surrender value rides the abort channel)._



#### Error-shortcut-laws


fx.experimental.desc-interp.effects.error-shortcut-laws: kernel-checked one-shot lemmas for each `handle_*` on the canonical EffError raise. Each lemma discharges by `H.refl` — ι on EffError.elim fires at the single `error` constructor, then β reduces the onError branch to a bare `H.pair _ _`. RHSes match `extract.PairRaw` emitter output, anchoring per-strategy shortcut soundness at the kernel layer.

## `collectingRaiseLemma`

_Proof of collecting-raise lemma: 3 lams + H.refl. State specialised to `List E`; onError cons-es payload onto the prior list and signals resume via `tt`._

## `collectingRaiseLemmaTy`

_Π-type of collecting-raise lemma: `Π E. Π payload:E. Π s:List E. handle_collecting E (error E payload) s ≡ H.pair (H.cons E payload s) H.tt : Σ (List E) Unit`._

## `resultRaiseLemma`

_Proof of result-raise lemma: 5 lams + H.refl. Always aborts; the Sum E A_inner result channel always carries the inl-injected payload (handler never produces inr)._

## `resultRaiseLemmaTy`

_Π-type of result-raise lemma: `Π E State A_inner. Π payload:E. Π s:State. handle_result E State A_inner (error E payload) s ≡ H.pair s (H.inl E A_inner payload) : Σ State (Sum E A_inner)`._

## `strictRaiseLemma`

_Proof of strict-raise lemma: 4 lams + H.refl. EffError has one constructor, so ι on `EffError.elim 0` fires immediately at `error`; β on the onError λs (`H.lam payload. H.lam _s. H.pair _s payload`) yields `H.pair s payload`._

## `strictRaiseLemmaTy`

_Π-type of strict-raise lemma: `Π E State. Π payload:E. Π s:State. handle_strict E State (error E payload) s ≡ H.pair s payload : Σ State E`._



#### Error-uniform-shortcut-laws


fx.experimental.desc-interp.effects.error-uniform-shortcut-laws: kernel-checked H.refl lemmas certifying that each `uniformOf_*` on the canonical EffError raise reduces to the appropriate `mkResumeAt`/`mkAbortAt` UniRet form. All three `uniformOf_X` are defined as direct `EffError.elim 0`-dispatches; at the canonical `error E payload` op, ι on the elim fires (single constructor → onError branch) and β on the onError λs delivers the RHS in one normal-form step. So all three lemmas discharge by H.refl uniformly.

## `collectingUniformLemma`

_Proof of collecting-uniform lemma: single H.refl over `uniformOf_collecting`'s direct `EffError.elim 0` dispatch at the canonical `error` constructor. ι + two β. Kernel typing of mkResume's r-slot additionally requires `Resp_collecting E op ≡_ι Unit`, which the same ι firing delivers._

## `collectingUniformLemmaTy`

_Π-type of collecting-uniform lemma: `Π E A. Π payload:E. Π s:List E. uniformOf_collecting E A (error E payload) s ≡ mkResumeAt (List E) Ee Resp_collecting_E op A tt (cons E payload s) : UniRet (List E) Ee Resp_collecting_E op A`._

## `resultUniformLemma`

_Proof of result-uniform lemma: single H.refl over `uniformOf_result`'s direct `EffError.elim 0` dispatch at the canonical `error` constructor. ι + two β; the onError branch's body emits `mkAbort … (inl E A_inner payload) _s` directly._

## `resultUniformLemmaTy`

_Π-type of result-uniform lemma: `Π E State A_inner. Π payload:E. Π s:State. uniformOf_result E State A_inner (error E payload) s ≡ mkAbortAt State Ee Resp_result_E op (Sum E A_inner) (inl E A_inner payload) s : UniRet State Ee Resp_result_E op (Sum E A_inner)`._

## `strictUniformLemma`

_Proof of strict-uniform lemma: single H.refl over `uniformOf_strict`'s direct `EffError.elim 0` dispatch at the canonical `error` constructor. ι + two β._

## `strictUniformLemmaTy`

_Π-type of strict-uniform lemma: `Π E State. Π payload:E. Π s:State. uniformOf_strict E State (error E payload) s ≡ mkAbortAt State Ee Resp_strict_E op E payload s : UniRet State Ee Resp_strict_E op E`._



#### State


Pair with `experimental.desc-interp.trampoline.run`:

```nix
let st = state.atType H.nat H.nat;
in run st.eff st.resp H.nat
     { inherit (st) handler dispatch; }
     program initialState
```

## `EffState`

_EffState : Π(S:U₀). U₀ — kernel datatype with three constructors (`get`, `put(param:S)`, `modify(fn:S→S)`). Built via `H.datatypeP`; macro-derived `.T`, `.D`, `.elim`, and per-constructor introducers._

## `EffStateTy`

_Π-type of state's op-identity family: `Π(S:U₀). U₀`._

## `Resp_State`

_Resp_State S op: response type family for state operations; get returns S, put/modify return Unit._

## `Resp_StateTy`

_Π-type of state's per-op response family: `Π(S:U₀). Π(_op:EffState S). U₀`._

## `atType`

_`atType S A` — per-`(S, A)` monomorphisation of `(EffState, Resp_State)` shipping `send`-wrapped smart constructors `get`/`put`/`modify`, the kernel-resident `handler` (= `handle_State` applied to `S` and `A`), and the Nix-side `dispatch` interpreter that reads the kernel-eval'd Sum return value into a `{ action; newState; response?; value?; }` step decision for the trampoline._

## `elimAt`

_elimAt k S — EffState.elim k with hidden state type supplied._

## `getAt`

_getAt S — EffState.get with hidden state type supplied._

## `handle_State`

_handle_State S A op s: kernel-resident state handler returning UniRet left/resume results for get, put, and modify._

## `handle_StateTy`

_Π-type of the state handler: `Π(S A:U₀). Π(op:EffState S). Π(_s:S). Sum (Σ _r:Resp_State[S,op], S) (Σ _a:A, S)`. Always returns the left (resume) summand — state effects never abort._

## `modifyAt`

_modifyAt S fn — EffState.modify with hidden state type and explicit function parameter supplied._

## `modifyPrefixAt`

_modifyPrefixAt S — EffState.modify with hidden state type supplied, leaving the explicit function parameter._

## `putAt`

_putAt S param — EffState.put with hidden state type and explicit state parameter supplied._

## `putPrefixAt`

_putPrefixAt S — EffState.put with hidden state type supplied, leaving the explicit state parameter._



#### State-shortcut-laws


fx.experimental.desc-interp.effects.state-shortcut-laws: kernel-checked one-shot lemmas for handle_State on each canonical EffState op (get/put/modify). Each lemma discharges by `H.refl` — kernel conv decides reduction universally via ι on EffState.elim + Resp_State. Lemma RHSes match the `extract.Resume` emitter output, anchoring the shortcut path's soundness at the kernel layer.

## `getLemma`

_Proof of get-lemma: 3 lams + H.refl. Reduction at canonical `get` is by ι on `EffState.elim` plus β on the onGet branch; `Resp_State S (get S) ≡ S` by ι makes the resume payload `s` well-typed._

## `getLemmaTy`

_Π-type of get-lemma: `Π S A. Π s:S. handle_State S A (get S) s ≡ mkResumeAt S Op Resp (get S) A s s`._

## `modifyLemma`

_Proof of modify-lemma: 4 lams + H.refl. `Resp_State S (modify S fn) ≡ Unit` by ι; new state := `fn s`._

## `modifyLemmaTy`

_Π-type of modify-lemma: `Π S A. Π fn:S→S. Π s:S. handle_State S A (modify S fn) s ≡ mkResumeAt S Op Resp (modify S fn) A tt (fn s)`._

## `putLemma`

_Proof of put-lemma: 4 lams + H.refl. `Resp_State S (put S param) ≡ Unit` by ι; the prior state `s` is discarded and resume carries new state `param`._

## `putLemmaTy`

_Π-type of put-lemma: `Π S A. Π param s:S. handle_State S A (put S param) s ≡ mkResumeAt S Op Resp (put S param) A tt param`._



#### Typecheck


Pair with `experimental.desc-interp.trampoline.run`:

```nix
let tc = typecheck.atType_collecting fx.tc.kernel.failure.DiagError;
in run tc.eff tc.resp H.unit
     { inherit (tc) handler dispatch; }
     program initialState
```

A program is a `bind` chain of `tc.report reason path carrier passed`
ops; `reason` is the closed five-token enum, `path` the internalized
structural blame site (a `Path = List Position` over the value-side
alphabet `Field`/`Elem`/`Tag`/`Tuple`), `carrier` the opaque host
residue, `passed` the host-precomputed decision. Every op resumes with
`tt`; the handler folds the decision into its state and never inspects
the carrier.

## `ByReason`

_Per-reason counter tuple in constructor order (a five-Nat Σ-chain)._

## `EffTypeCheck`

_EffTypeCheck : Π(R:U₀). U₀ — one constructor `report(reason:Reason, path:Path, carrier:R, passed:Bool)`._

## `EffTypeCheckTy`

_Π-type of the op-identity family: `Π(R:U₀). U₀`._

## `Path`

_`Path = List Position` — the structural blame site carried by `report`, mirroring the producer's typeCheck `path`._

## `Position`

_Value-side descent position: `Field name` / `Elem idx` / `Tag name` / `Tuple idx`. The internalized core of `fx.diag.positions` for value-validation paths (`name` a strEq-comparable carrier, `idx` a Nat); rendered segment text stays host-side._

## `Reason`

_Closed five-token diagnostic enum (shapeMismatch/missingField/extraField/predicateFailed/deferredPi)._

## `Resp`

_Response family: every `report` op resumes with Unit (the decision rides in the op, not the resume)._

## `atType_collecting`

_`atType_collecting R` — monomorphises the collecting handler and ships `{ eff; resp; handler; dispatch; report; evalOp; handlerShortcut }`. The shortcut rebuilds the resume residual directly (certified by `typecheck-shortcut-laws.nix`)._

## `atType_firstN`

_`atType_firstN R` — monomorphised first-N bridge record._

## `atType_logging`

_`atType_logging R` — monomorphised logging bridge record._

## `atType_pretty`

_`atType_pretty R` — monomorphised pretty bridge record._

## `atType_strict`

_`atType_strict R` — monomorphises the strict handler and ships `{ eff; resp; handler; dispatch; report; evalOp; handlerShortcut }` with a conditional-throw dispatch (resume on pass, throw on fail); the shortcut emits the Sum directly (`Resume`/`Abort`)._

## `atType_summarize`

_`atType_summarize R` — monomorphised summarize bridge record._

## `atType_summarizeAssoc`

_`atType_summarizeAssoc R` — monomorphised summarize-assoc bridge record (assoc-list byReason)._

## `bumpReason`

_bumpReason r b — increment the counter for reason `r` via the Reason eliminator (no string comparison)._

## `handle_collecting`

_Collecting handler: a fail conses the residue, a pass keeps the list. Returns `Σ (List R) Unit`._

## `handle_firstN`

_First-N handler: an O(1) down-counter records failures until it reaches zero, then drops. Returns `Σ (Σ (List R) Nat) Unit`._

## `handle_logging`

_Logging handler: every decision is recorded as `(passed, residue)`. Returns `Σ (List (Σ Bool R)) Unit`._

## `handle_pretty`

_Pretty handler: conses the host-rendered failure line (carried opaquely) on a fail. Same shape as collecting._

## `handle_strict`

_Strict handler: a pass resumes (left summand), a fail surrenders the residue (right summand). Returns `Sum (Σ Unit Unit) (Σ R Unit)`; the right summand drives a `throw`._

## `handle_summarize`

_Summarize handler: groups failures by the reason enum, tracking (passed, failed) totals. Returns `Σ (Σ ByReason (Σ Nat Nat)) Unit`._

## `handle_summarizeAssoc`

_Summarize-assoc handler: groups failures into a `List (Σ String Nat)` byReason assoc list via `insertOrIncrement` (a `listElim`+`strEq` fold), tracking (passed, failed) totals. Returns `Σ (Σ (List (Σ String Nat)) (Σ Nat Nat)) Unit`. The production-faithful `byReason` attrset shape, alongside the O(1) closed-enum variant._

## `insertOrIncrement`

_insertOrIncrement key assoc — a `listElim` fold over a `List (Σ String Nat)` byReason assoc list: a `strEq` key match bumps the entry's count in place, otherwise a new `(key, 1)` is appended._

## `reasonName`

_reasonName r — render the reason enum to its production `byReason` key token (shape-mismatch/missing-field/extra-field/predicate-failed/deferred-pi) via the Reason eliminator._



#### Typecheck-shortcut-laws


fx.experimental.desc-interp.effects.typecheck-shortcut-laws: kernel-checked one-shot lemmas certifying each typecheck handler on the canonical `report` op reduces to its shortcut residual (`pair newState tt` for the resume strategies; a `Sum` inl/inr for strict). Each discharges by `H.refl` — ι on EffTypeCheck.elim fires the single `report` branch, β binds the four fields + state, and the step's `boolElim` at a concrete `passed` selects the arm. RHSes match the `extract.PairRaw`/`Resume`/`Abort` emitter outputs, anchoring per-strategy shortcut soundness at the kernel layer. firstN-fail splits on the stuck down-counter (`suc`/`zero`); summarize/summarize-assoc fail keep the reason symbolic (one lemma per variant covers all tokens).

## `collectingFail`

_Proof of collecting-fail: 5 lams + H.refl. A fail conses the residue (RHS via consAtExplicit)._

## `collectingFailTy`

_Π-type of collecting-fail: `… (report … false) s ≡ H.pair (cons carrier s) tt`._

## `collectingPass`

_Proof of collecting-pass: 5 lams + H.refl. A pass keeps the accumulator._

## `collectingPassTy`

_Π-type of collecting-pass: `Π R reason path carrier. Π s:List R. handle_collecting R (report reason path carrier true) s ≡ H.pair s tt`._

## `firstNFailSuc`

_Proof of firstN-fail-suc: 6 lams + H.refl. The recorded list is annotated (the `ind` step body is synthesized, so a bare cons carries no element type)._

## `firstNFailSucTy`

_Π-type of firstN-fail at `remaining = suc rp`: `… (report … false) (pair coll (suc rp)) ≡ H.pair (pair (cons carrier coll) rp) tt` — record and decrement._

## `firstNFailZero`

_Proof of firstN-fail-zero: 5 lams + H.refl._

## `firstNFailZeroTy`

_Π-type of firstN-fail at `remaining = zero`: `… (report … false) (pair coll zero) ≡ H.pair (pair coll zero) tt` — drop and hold (the abort state)._

## `firstNPass`

_Proof of firstN-pass: 5 lams + H.refl._

## `firstNPassTy`

_Π-type of firstN-pass: `… handle_firstN R (report … true) s ≡ H.pair s tt` (no `ind`; the state is returned)._

## `loggingFail`

_Proof of logging-fail: 5 lams + H.refl._

## `loggingFailTy`

_Π-type of logging-fail: `… (report … false) s ≡ H.pair (cons (pair false carrier) s) tt`._

## `loggingPass`

_Proof of logging-pass: 5 lams + H.refl. Every decision is recorded; the outcome rides in the record._

## `loggingPassTy`

_Π-type of logging-pass: `… handle_logging R (report … true) s ≡ H.pair (cons (pair true carrier) s) tt`._

## `prettyFail`

_Proof of pretty-fail: 5 lams + H.refl._

## `prettyFailTy`

_Π-type of pretty-fail: `… (report … false) s ≡ H.pair (cons carrier s) tt` (the host-rendered line rides in carrier)._

## `prettyPass`

_Proof of pretty-pass: 5 lams + H.refl._

## `prettyPassTy`

_Π-type of pretty-pass: same shape as collecting-pass (`H.pair s tt`)._

## `strictFail`

_Proof of strict-fail: 5 lams + H.refl._

## `strictFailTy`

_Π-type of strict-fail: `… (report … false) s ≡ inr strictLeft (strictRight R) (pair carrier s)` — surrender the residue down the right summand (the throw channel)._

## `strictPass`

_Proof of strict-pass: 5 lams + H.refl._

## `strictPassTy`

_Π-type of strict-pass: `… handle_strict R (report … true) s ≡ inl strictLeft (strictRight R) (pair tt s)` — resume down the left summand._

## `summarizeAssocFail`

_Proof of summarize-assoc-fail: 7 lams + H.refl._

## `summarizeAssocFailTy`

_Π-type of summarize-assoc-fail (reason symbolic): `… (report reason … false) (pair br (pair pt ft)) ≡ H.pair (pair (insertOrIncrement (reasonName reason) br) (pair pt (suc ft))) tt`._

## `summarizeAssocPass`

_Proof of summarize-assoc-pass: 7 lams + H.refl._

## `summarizeAssocPassTy`

_Π-type of summarize-assoc-pass: `… handle_summarizeAssoc R (report … true) (pair br (pair pt ft)) ≡ H.pair (pair br (pair (suc pt) ft)) tt`._

## `summarizeFail`

_Proof of summarize-fail: 7 lams + H.refl._

## `summarizeFailTy`

_Π-type of summarize-fail (reason symbolic): `… (report reason … false) (pair br (pair pt ft)) ≡ H.pair (pair (bumpReason reason br) (pair pt (suc ft))) tt`. `bumpReason reason br` stays neutral on both sides, so one lemma covers every reason._

## `summarizePass`

_Proof of summarize-pass: 7 lams + H.refl._

## `summarizePassTy`

_Π-type of summarize-pass: `… handle_summarize R (report … true) (pair br (pair pt ft)) ≡ H.pair (pair br (pair (suc pt) ft)) tt` — bump the passed total._



#### Extract


## Soundness layering

- **kernel-side (HOAS)**: per-canonical-op lemma
  `handle_X op s ≡_kernel mkResumeAt … r s` proved by `H.refl`
  + ι (mirrors `compose-laws.nix`).
- **emitter-side (Val)**: per-primitive conv test
  `eval (HOAS witness) ≡_Val extract (Primitive …)` shown via
  `fx.tc.conv.conv 0`. Sugar tests are consequences of the
  primitive tests + composition.
- **chain**: kernel-path Val ≡ shortcut-path Val at every
  canonical op.

## Algebra

- **Primitives** — `DescCon`, `BootInl`, `BootInr`, `Pair`,
  `Tt`, `BootRefl`. One-to-one mirrors of `V.vDescCon` /
  `vBootInl` / `vBootInr` / `vPair` / `vTt` / `vBootRefl`.
- **Sugars** — `Resume`, `Abort`, `PairRaw`. Folded shapes
  rewriting into nested primitive RF trees; no capability
  beyond the primitives.
- **Consumers** — `Project`, `OfElim`. Read a Val (or RF, via
  polymorphic `extract`) back into a Val; used by composed
  shortcuts.

Caller supplies `sumDescVal` / `leftSig` / `rightSig` once per
`atType` instance. `sumDescValOf leftSig rightSig` recovers
the VDescCon `.D` slot from a HOAS sum type by evaluating a
canonical `H.inl` skeleton.

## `Abort`

_Abort sumDescVal leftSig rightSig value state — UniRet right summand sugar. Folds to `DescCon sumDescVal Tt (BootInr leftSig rightSig (Pair (Pair value state) BootRefl))`. Used by error-strict (surrender), error-result (Sum-typed channel), and composed abort paths._

## `BootInl`

_BootInl left right val — primitive mirror of `V.vBootInl left right val`. Left-summand selector inside a `DescCon` for a plus-of-args description._

## `BootInr`

_BootInr left right val — primitive mirror of `V.vBootInr left right val`. Right-summand counterpart of `BootInl`._

## `BootRefl`

_BootRefl — primitive mirror of `V.vBootRefl`. Structural marker for the `ret` slot of descArg._

## `DescCon`

_DescCon D i d — primitive mirror of `V.vDescCon D i d`. `D` is a descriptor Val, `i` the index Val, `d` the constructor payload._

## `OfElim`

_OfElim scrutinee onResume onAbort — Val-side pattern match on a UniRet-shaped scrutinee. `onResume`/`onAbort` are Nix `Val → Val` functions receiving the bootInl/bootInr payload (a `(payload, state)` VPair). Used by composed shortcuts to dispatch on inner sub-handler results._

## `Pair`

_Pair fst_ snd_ — primitive mirror of `V.vPair fst snd`._

## `PairRaw`

_PairRaw fst_ snd_ — alias for `Pair`. Documents intent as a bare `H.pair _ _` residual (as opposed to UniRet-inner pair). Used by error's three strategies whose reduced RHS isn't UniRet-wrapped._

## `Project`

_Project side of_ — first or second projection of a VPair-typed Val. `side ∈ {"fst","snd"}`. Used by composed-shortcut state-slot repack._

## `Resume`

_Resume sumDescVal leftSig rightSig resp state — UniRet left summand sugar. Folds to `DescCon sumDescVal Tt (BootInl leftSig rightSig (Pair (Pair resp state) BootRefl))`. Mirrors `eval (mkResumeAt S Op Resp op A resp state)`._

## `Tt`

_Tt — primitive mirror of `V.vTt`. Unit Val constant._

## `extract`

_extract : ResidualForm → Val. Direct attrset construction targeting the VDescCon/VBootInl|VBootInr/VPair encoding produced by `eval` on the canonical mkResumeAt / mkAbortAt / fst_ / snd_ / sumElim spines. Per-constructor conv tests under `_self.tests` discharge emitter-side soundness._

## `sumDescValOf`

_sumDescValOf leftSigHoas rightSigHoas — recovers the VDescCon `.D` slot for a `H.sum leftSig rightSig` instantiation by evaluating a canonical `H.inl` skeleton and reading its `.D`. Caller-side helper for building `Resume`/`Abort` metadata Vals once per `atType` instance._



#### Kernel


fx.experimental.desc-interp.kernel: pure/send/bind constructors producing FreeFx Desc values directly as `μ freeFxApp` data, not Nix-host computations.

## `bind`

_bind Eff Resp A B m f — sequence two computations. Pure case applies `f` to the payload; Impure case snocs `f` into the queue. Linear continuation chains stay flat in the queue, sidestepping Nix's call-depth ceiling._

```
bind : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas U -> Hoas (μ freeFxApp Eff Resp A) -> (Hoas A -> Hoas (μ freeFxApp Eff Resp B)) -> Hoas (μ freeFxApp Eff Resp B)
```

## `pure`

_pure Eff Resp A v — lift v into the Pure summand of FreeFx; alias for `D.pureCon`._

```
pure : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas A -> Hoas (μ freeFxApp Eff Resp A)
```

## `qSnoc`

_qSnoc Eff Resp B q f — append the Nix-meta continuation `f` (Hoas q._index.A → Hoas (μ freeFxApp Eff Resp B)) to the right of queue `q`. The chain's input type is q._index.X and its current output is q._index.A. Identity short-circuits to a fresh `qLeaf` at (q._index.A, B); otherwise builds `qNode q (qLeaf q._index.A B fn)` with the seam M = q._index.A asserted via the sidecar invariant on qNode._

```
qSnoc : Hoas U -> Hoas (U -> U) -> Hoas U -> Hoas (μI U² kontQueueApp …) -> (Hoas A -> Hoas (μ freeFxApp Eff Resp B)) -> Hoas (μI U² kontQueueApp …)
```

## `send`

_send Eff Resp op — issue an effect request with the identity continuation; emits an impureCon whose queue slot is `qIdentity Eff Resp (Resp op)` at index `(Resp op, Resp op)`._

```
send : Hoas U -> Hoas (U -> U) -> Hoas Eff -> Hoas (μ freeFxApp Eff Resp (Resp op))
```



#### Trampoline


fx.experimental.desc-interp.trampoline: qApp/run/handle interpreters trampolining FreeFx Desc values via genericClosure for O(1) stack depth on long chains.

## `handle`

_handle Eff Resp A { return?; handler; dispatch; state } prog — thin wrapper over `run` with a custom `return` clause folding the final (value, state) pair._

```
handle : Hoas U -> Hoas (U -> U) -> Hoas U -> { return?, handler, dispatch, state } -> Hoas (μ freeFxApp Eff Resp A) -> b
```

## `qApp`

_qApp Eff Resp q x — apply queue `q` to value `x : Hoas q._index.X`; trampolines Pure-returning leaves via genericClosure; on Impure splices the inner queue with the remaining tail. The queue's `_index` sidecar carries the (X, A) indexing that the kernel's μI U² slot witnesses._

```
qApp : Hoas U -> Hoas (U -> U) -> Hoas (μI U² kontQueueApp …) -> Hoas X -> Hoas (μ freeFxApp Eff Resp A)
```

## `qAppend`

_qAppend Eff Resp l r — concatenate two queues. Identity short-circuits on either side mirror `queue.nix:append`; otherwise builds `qNode l r` with the seam M = `l._index.A` (= `r._index.X`, asserted host-level by qNode). The composite queue inhabits μI U² kontQueueApp (l._index.X, r._index.A)._

```
qAppend : Hoas U -> Hoas (U -> U) -> Hoas (μI U² kontQueueApp …) -> Hoas (μI U² kontQueueApp …) -> Hoas (μI U² kontQueueApp …)
```

## `run`

_run Eff Resp A { handler; dispatch } prog initialState — drive `prog : μ(freeFxApp Eff Resp A)` to completion via a `genericClosure` worklist; per Impure node, the kernel-resident `handler` term is applied to the op + threaded state via `vApp`, and the Nix-side `dispatch` interpreter reads the kernel-eval'd result to produce a step decision._

```
run : Hoas U -> Hoas (U -> U) -> Hoas U -> { handler; dispatch } -> Hoas (μ freeFxApp Eff Resp A) -> Hoas State -> { value; state }
```



### Diagnostics

#### Positions


Shared diagnostic alphabet. Pure data.

A Position names the blame location in a structural descent through
a Desc or through raw MLTT structure (Π / Σ / Ann / μ / App). The
alphabet is description-centric: names such as `DArgSort`, `DPlusL`,
and `PiDom` identify sub-positions by their meaning in the structure,
not by the code path that happens to visit them.

Each Position carries four fields:

  - `tag`     : variant discriminator (used by hint-key lookup);
  - `segment` : short rendered path label (e.g. `"arg.S"`, `"Π.dom"`);
  - `intent`  : semantic role description, rendered by the pretty
                 printer as a "what was expected at this position"
                 gloss alongside the segment;
  - `rule`    : optional descent-rule annotation; null on every
                 constant. `withRule` produces a decorated variant
                 and `bindPR` populates it at the emission site.

`intent` and `rule` are opaque to the hint resolver: keys are built
from `tag` only, so decorating Positions does not affect lookup.

Two kinds of consumer:

  - A kernel enrichment layer that wraps rule delegations, emitting
    a child error tagged with the `Position` of the sub-call that
    failed.
  - A value-level validator (record / list / variant field walkers)
    that emits `Field` / `Elem` / `Tag` positions from its per-
    component blame traversal.

Both consumers produce `Error` trees whose children are keyed by
`Position`, allowing errors from either source to compose into one
tree.

## `AnnTerm`

_AnnTerm: canonical Position constant for the term being annotated._

```
Position
```

Canonical diagnostic Position constant. Segment: `ann.term`.

## `AnnType`

_AnnType: canonical Position constant for the type annotation supplied._

```
Position
```

Canonical diagnostic Position constant. Segment: `ann.type`.

## `AppArg`

_AppArg: canonical Position constant for the argument supplied to the application._

```
Position
```

Canonical diagnostic Position constant. Segment: `app.arg`.

## `AppHead`

_AppHead: canonical Position constant for the function applied._

```
Position
```

Canonical diagnostic Position constant. Segment: `app.head`.

## `Case`

_Case: parameterised position naming an eliminator's case handler by `name` — generated constructor names, `"inl"`/`"inr"`, `"base"`, `"onRet"`/`"onArg"`/`"onRec"`/`"onPi"`/`"onPlus"`, `"step"`._

```
Case : String -> Position
```

## `DArgBody`

_DArgBody: canonical Position constant for the description body produced by `arg`'s family._

```
Position
```

Canonical diagnostic Position constant. Segment: `arg.T`.

## `DArgEq`

_DArgEq: canonical Position constant for the equality witness paired with `arg`'s sort._

```
Position
```

Canonical diagnostic Position constant. Segment: `arg.eq`.

## `DArgLevel`

_DArgLevel: canonical Position constant for the universe level at which `arg`'s sort lives._

```
Position
```

Canonical diagnostic Position constant. Segment: `arg.k`.

## `DArgSort`

_DArgSort: canonical Position constant for the sort inhabited by `arg`'s argument._

```
Position
```

Canonical diagnostic Position constant. Segment: `arg.S`.

## `DConLayer`

_DConLayer: parameterised position naming the `layer`-th step in a peeled linear-recursive `desc-con` trampoline chain (0 = outermost, n = base); renders as `con[<layer>]`; quotient representative of homogeneous μ-unfolding paths so per-blame chain depth stays constant regardless of trampoline depth._

```
DConLayer : Int -> Position
```

## `DElimLevel`

_DElimLevel: canonical Position constant for the universe level at which the eliminator's motive lives._

```
Position
```

Canonical diagnostic Position constant. Segment: `elim.k`.

## `DPiBody`

_DPiBody: canonical Position constant for the description body produced by `pi`'s family._

```
Position
```

Canonical diagnostic Position constant. Segment: `pi.T`.

## `DPiEq`

_DPiEq: canonical Position constant for the equality witness paired with `pi`'s sort._

```
Position
```

Canonical diagnostic Position constant. Segment: `pi.eq`.

## `DPiFn`

_DPiFn: canonical Position constant for the index selector function of `pi`._

```
Position
```

Canonical diagnostic Position constant. Segment: `pi.f`.

## `DPiLevel`

_DPiLevel: canonical Position constant for the universe level at which `pi`'s domain lives._

```
Position
```

Canonical diagnostic Position constant. Segment: `pi.k`.

## `DPiSort`

_DPiSort: canonical Position constant for the sort inhabited by `pi`'s domain._

```
Position
```

Canonical diagnostic Position constant. Segment: `pi.S`.

## `DPlusL`

_DPlusL: canonical Position constant for the left summand of `plus`._

```
Position
```

Canonical diagnostic Position constant. Segment: `plus.L`.

## `DPlusR`

_DPlusR: canonical Position constant for the right summand of `plus`._

```
Position
```

Canonical diagnostic Position constant. Segment: `plus.R`.

## `DRecIndex`

_DRecIndex: canonical Position constant for the index value supplied to `rec`._

```
Position
```

Canonical diagnostic Position constant. Segment: `rec.j`.

## `DRecTail`

_DRecTail: canonical Position constant for the description tail spliced onto `rec`._

```
Position
```

Canonical diagnostic Position constant. Segment: `rec.D`.

## `DRetIndex`

_DRetIndex: canonical Position constant for the index value supplied to `ret`._

```
Position
```

Canonical diagnostic Position constant. Segment: `ret.j`.

## `Elem`

_Elem: parameterised position naming a list element by `idx`; renders as `[<idx>]` in blame paths and carries `idx` for downstream lookup by integer index._

```
Elem : Int -> Position
```

## `Field`

_Field: parameterised position naming a record field by `name`; renders as `.<name>` in blame paths and carries `name` for downstream lookup by field-key._

```
Field : String -> Position
```

## `JEq`

_JEq: canonical Position constant for the equality witness consumed by `J`._

```
Position
```

Canonical diagnostic Position constant. Segment: `J.eq`.

## `JLhs`

_JLhs: canonical Position constant for the left endpoint of `J`._

```
Position
```

Canonical diagnostic Position constant. Segment: `J.a`.

## `JRhs`

_JRhs: canonical Position constant for the right endpoint of `J`._

```
Position
```

Canonical diagnostic Position constant. Segment: `J.b`.

## `JType`

_JType: canonical Position constant for the type carrying `J`'s two endpoints._

```
Position
```

Canonical diagnostic Position constant. Segment: `J.A`.

## `LamBody`

_LamBody: canonical Position constant for the body of the lambda under its bound variable._

```
Position
```

Canonical diagnostic Position constant. Segment: `lam.body`.

## `LetBody`

_LetBody: canonical Position constant for the body of the let-binding._

```
Position
```

Canonical diagnostic Position constant. Segment: `let.body`.

## `LevelMaxLhs`

_LevelMaxLhs: canonical Position constant for the left operand of `max`._

```
Position
```

Canonical diagnostic Position constant. Segment: `max.L`.

## `LevelMaxRhs`

_LevelMaxRhs: canonical Position constant for the right operand of `max`._

```
Position
```

Canonical diagnostic Position constant. Segment: `max.R`.

## `LevelSucPred`

_LevelSucPred: canonical Position constant for the predecessor of `suc`._

```
Position
```

Canonical diagnostic Position constant. Segment: `suc.pred`.

## `Motive`

_Motive: canonical Position constant for the motive of the eliminator._

```
Position
```

Canonical diagnostic Position constant. Segment: `motive`.

## `MuDesc`

_MuDesc: canonical Position constant for the description argument of `con`._

```
Position
```

Canonical diagnostic Position constant. Segment: `con.D`.

## `MuIndex`

_MuIndex: canonical Position constant for the index value supplied to `con`._

```
Position
```

Canonical diagnostic Position constant. Segment: `con.i`.

## `MuPayload`

_MuPayload: canonical Position constant for the payload of `con` at its index._

```
Position
```

Canonical diagnostic Position constant. Segment: `con.d`.

## `MuUnroll`

_MuUnroll: canonical Position constant for an unrolling step of μ._

```
Position
```

Canonical diagnostic Position constant. Segment: `μ`.

## `OpaqueType`

_OpaqueType: canonical Position constant for the Π-type annotation of the opaque lambda._

```
Position
```

Canonical diagnostic Position constant. Segment: `opaque.type`.

## `PiCod`

_PiCod: canonical Position constant for the codomain family of Π._

```
Position
```

Canonical diagnostic Position constant. Segment: `Π.cod`.

## `PiDom`

_PiDom: canonical Position constant for the domain type of Π._

```
Position
```

Canonical diagnostic Position constant. Segment: `Π.dom`.

## `Scrut`

_Scrut: canonical Position constant for the scrutinee of the eliminator._

```
Position
```

Canonical diagnostic Position constant. Segment: `scrut`.

## `SigmaFst`

_SigmaFst: canonical Position constant for the first component type of Σ._

```
Position
```

Canonical diagnostic Position constant. Segment: `Σ.fst`.

## `SigmaSnd`

_SigmaSnd: canonical Position constant for the second component type of Σ._

```
Position
```

Canonical diagnostic Position constant. Segment: `Σ.snd`.

## `Sub`

_Sub: canonical Position constant for the subsumption bridge from CHECK to INFER._

```
Position
```

Canonical diagnostic Position constant. Segment: `sub`.

## `Tag`

_Tag: parameterised position naming a tagged-union arm by `name`; renders as `#<name>` in blame paths and carries `name` for downstream lookup by variant tag._

```
Tag : String -> Position
```

## `Tuple`

_Tuple: parameterised position naming a tuple component by static `idx`; renders identically to `Elem` (`[<idx>]`) but stays distinct so consumers tell n-ary tuple from list descent._

```
Tuple : Int -> Position
```

## `ULevel`

_ULevel: canonical Position constant for the level argument of `U`._

```
Position
```

Canonical diagnostic Position constant. Segment: `U.k`.

## `eq`

_eq: structural equality on `Position` values; relies on Nix's attrset-by-content comparison so equal positions compare equal regardless of construction path._

```
eq : Position -> Position -> Bool
```

## `isPosition`

_isPosition: predicate recognising the `Position` ADT — checks `_tag == "Position"`; complements the `Layer`/`Error` predicates from `fx.diag.error`._

```
isPosition : Any -> Bool
```

## `renderSegment`

_renderSegment: render a `Position` as its short human-readable segment (`"arg.S"`, `"plus.L"`, `".age"`); single field read since the segment is carried on the Position itself._

```
renderSegment : Position -> String
```

## `withRule`

_withRule: decorate a `Position` with a descent-rule annotation, returning a structurally distinct Position whose `rule` field is set to the supplied string; leaves the original canonical constant intact for sharing._

```
withRule : String -> Position -> Position
```

Use at the kernel-rule call site to record which rule emitted
the descent — paired with `bindPR` to wrap the inner
computation under a Position that carries both the structural
coordinate (`tag`/`segment`/`intent`) and the rule identity.
The hint resolver ignores `rule` (keys come from `tag` only),
so decorating Positions never changes lookup.



#### Error


Diagnostic Error ADT.

An Error has a Layer (Kernel | Generic | Contract), a layer-discriminated
Detail record, a short msg, an optional hint, and a list of children.
A leaf has `children = []`; a branch has a non-empty children list
whose entries are `{ position, error }` pairs. Sibling failures produce
many children; a chained descent produces one child; a leaf has none.

Constructors:
  mkKernelError   { position?, rule, msg, expected?, got?, ctx_depth?, hint? }
  mkGenericError  { type?, context?, value, desc?, index?, guard?, msg, hint? }
  mkContractError { type?, context?, value, guard, msg, hint? }

Per-layer Detail builders:
  mkKernelDetail / mkGenericDetail / mkContractDetail

Combinators:
  nestUnder  : Position -> Error -> Error
  addChild   : Position -> Error -> Error -> Error
  setLeafHint : Hint -> Error -> Error

Layer constants: Kernel, Generic, Contract.
Predicates: isError, isLayer, isDetail, isKernel, isGeneric, isContract.
Equality: eq (structural).

Pure data. No dependencies on kernel, trampoline, effects, tc, or
types modules.

## `Contract`

_Contract: Layer constant tagging a value with the correct shape that violates a refinement predicate (`guard`)._

Paired with a `ContractDetail` carrying `value`, the mandatory
`guard = { predicate = "…"; }`, and optionally the surface
`type` and outer `context`. Renderer formats Contract failures
as predicate violations distinct from shape mismatches.
Pre-allocated; never construct via `{ _tag = ...; }`.

## `Generic`

_Generic: Layer constant tagging a value whose shape fails to inhabit a description._

Emitted by sugar validators (`fx.types.*`) and the generic
`descElim`-driven shape checker. Paired with a `GenericDetail`
carrying `value` (the failing input) and usually `type` /
`desc` identifying the violated contract. Pure shape failures
(record-field type mismatch, wrong variant tag) live here;
refinement-predicate failures belong in `Contract`.

## `Kernel`

_Kernel: Layer constant tagging a kernel-layer diagnostic error; `Error.layer` is set to this for typechecker/elaborator failures._

Emitted by `checkHoas` / `infer` / elaborator passes. Paired
with a `KernelDetail` carrying `rule` (the failing kernel rule
name) and typically `expected` / `got` carrying normalised
value-domain types. Pre-allocated; never construct via
`{ _tag = ...; }`.

## `addChild`

_addChild: append a keyed child `Error` to a branching `parent`; used by collecting handlers that gather many sibling failures under one root without flattening the blame paths._

```
addChild : Position -> Error -> Error -> Error  -- position, parent, child
```

Use for sibling collection (record fields, variant cases, list
elements all rejected against the same root contract). Order
of insertion is preserved in the resulting children list, so
callers control reporting order. The parent's `layer` /
`detail` / `msg` are not overwritten — they describe the
outer-shape failure, while each child describes one element's
failure. For descent (one-deep hop), use `nestUnder` instead;
`addChild` is the multi-sibling counterpart.

## `appendTrace`

_appendTrace: append a `{ rule, position }` entry to a Kernel-layer error's `detail.trace`; non-Kernel errors pass through unchanged. Used by `bindP`/`bindPR` to auto-capture the descent chain as the error unwinds._

```
appendTrace : (String | null) -> Position -> Error -> Error
```

## `captureFrame`

_captureFrame: project a typing context into a `{ depth, env, types, names }` Frame suitable for `KernelDetail.frame`; reads `ctx.names` defensively so contexts without name tracking still produce a well-formed frame._

```
captureFrame : Ctx -> Frame
```

## `eq`

_eq: structural equality on `Error` values — relies on Nix's attrset-by-content comparison so equal trees compare equal regardless of construction path._

```
eq : Error -> Error -> Bool
```

Equality is content-based, so two distinct constructions of
the same shape (`mkKernelError { rule = "r"; msg = "m"; }`
twice) compare equal — useful for test assertions and for
deduplicating siblings in a collecting handler. Position
ADT values inside `children` participate in the comparison,
so chains with reordered hops are not equal.

## `isContract`

_isContract: `Layer` variant predicate — true iff the value is the `Contract` constant._

```
isContract : Any -> Bool
```

## `isDetail`

_isDetail: predicate recognising the `Detail` ADT — checks `_tag == "Detail"` plus the presence of a `layer` self-discriminator._

```
isDetail : Any -> Bool
```

## `isError`

_isError: predicate recognising the `Error` ADT — checks `_tag == "Error"` plus the required fields `layer`, `detail`, `msg`, `children`._

```
isError : Any -> Bool
```

Use at module boundaries where input could be anything;
internal code that constructs Errors via the per-layer
constructors doesn't need to check. The predicate rejects bare
attrsets that happen to have `_tag = "Error"` but are missing
required fields — guards against accidental partial
construction more than against type confusion.

## `isGeneric`

_isGeneric: `Layer` variant predicate — true iff the value is the `Generic` constant._

```
isGeneric : Any -> Bool
```

## `isKernel`

_isKernel: `Layer` variant predicate — true iff the value is the `Kernel` constant._

```
isKernel : Any -> Bool
```

## `isLayer`

_isLayer: predicate recognising the `Layer` ADT — checks `_tag == "Layer"` plus the presence of `tag`; accepts `Kernel`, `Generic`, and `Contract`._

```
isLayer : Any -> Bool
```

Does not distinguish the variants — pair with a check on `.tag`
for layer-specific dispatch, or use `isKernel` / `isGeneric` /
`isContract`. Rejects plain attrsets `{ tag = "Kernel"; }` that
lack `_tag`, so renderer branching can trust a positive result
to mean a canonical constant.

## `mkContractDetail`

_mkContractDetail: build a Contract-layer `Detail` record from optional field overrides; defaults set every field to null and carry the layer self-discriminator. Callers should always populate `guard`._

```
mkContractDetail : { type?, value?, context?, guard? } -> Detail
```

## `mkContractError`

_mkContractError: build a contract-layer leaf `Error` from `{ value, guard, msg, type?, context?, hint? }`; `value` has the correct shape but `guard` rejected it._

```
mkContractError : { value, guard, msg, type?, context?, hint? } -> Error
```

`guard` is mandatory — a `{ predicate = "…"; }` record naming
the refinement that rejected `value`. Without a guard the
failure is structural, not contractual, and belongs in
`mkGenericError`. `type` and `context` describe the surrounding
contract for the renderer.

## `mkGenericDetail`

_mkGenericDetail: build a Generic-layer `Detail` record from optional field overrides; defaults set every field to null and carry the layer self-discriminator._

```
mkGenericDetail : { type?, desc?, value?, context?, index?, guard? } -> Detail
```

## `mkGenericError`

_mkGenericError: build a generic-layer leaf `Error` from `{ value, msg, type?, context?, desc?, index?, guard?, hint? }`; `value` is the thing whose shape failed to inhabit the description._

```
mkGenericError : { value, msg, type?, context?, desc?, index?, guard?, hint? } -> Error
```

`type` is the surface name presented to the user (`"PersonT"`,
`"NonEmptyList"`); `desc` is the underlying `Desc I` shape if
the producer has it; `context` is an outer-scope name used in
nested record/variant failures. The `guard` slot is retained
for callers that have not yet migrated refinement failures to
`mkContractError`; prefer Contract for new producers.

## `mkKernelDetail`

_mkKernelDetail: build a Kernel-layer `Detail` record from optional field overrides; defaults set every field to null (trace to []) and carry the layer self-discriminator._

```
mkKernelDetail : { rule?, expected?, got?, ctx_depth?, term?, frame?, trace? } -> Detail
```

## `mkKernelError`

_mkKernelError: build a kernel-layer leaf `Error` from `{ rule, msg, position?, expected?, got?, ctx_depth?, term?, frame?, trace?, hint? }`; when `position` is supplied, wraps the leaf in `nestUnder` so the rule emits its own descent coordinate._

```
mkKernelError : { rule, msg, position?, expected?, got?, ctx_depth?, term?, frame?, trace?, hint? } -> Error
```

`rule` is the kernel-rule identifier — `hints.nix` keys its
Hint table off `rule` plus blame-path-suffix, so use the
canonical name (`"check"`, `"desc-arg"`, `"univ-poly"`, …) not
an ad-hoc string. `expected` / `got` should be value-domain
terms (post-`eval`), not unelaborated HOAS — the diff renderer
expects normalised shape. Supplying `position` is equivalent
to `nestUnder p (mkKernelError { … })`; use it when the rule
emits a single descent hop, not when the caller will add hops
of its own. `term` names the failing surface-term shape;
`frame` is a Ctx snapshot via `captureFrame`; `trace` is
usually left empty at emission and populated by `bindP` /
`bindPR` as the error unwinds.

## `nestUnder`

_nestUnder: add a positional hop above `inner`, producing a new branch whose single child carries `position` as its edge label; pass-through of layer/detail/msg/hint preserves leaf rendering at any depth._

```
nestUnder : Position -> Error -> Error
```

Pass-through invariant: the wrapper's `layer`, `detail`, `msg`,
and `hint` are copied from `inner`. This is what lets the
renderer pick its branch (Kernel vs Generic) and pick the
leaf's payload at any depth without descending the chain —
the entire single-child chain reports the same diagnostic,
just with a longer blame path. Stacking is by repeated
application: `nestUnder pOuter (nestUnder pInner leaf)` yields
a chain whose outer edge is `pOuter`, inner edge `pInner`.

## `setLeafHint`

_setLeafHint: walk the single-child chain to its leaf and overwrite `hint` on the endpoint, returning a structurally-equivalent tree; stack-safe via `splitChainFast`/`splitChainSlow` to kernel-descent depth._

```
setLeafHint : Hint -> Error -> Error
```

Only mutates the chain endpoint. If the endpoint is branching
(children count > 1), returns the tree unchanged — sibling-
specific hint attachment is the caller's responsibility, the
function is intentionally a no-op there to avoid clobbering
ambiguity. Stack-safe to arbitrary depth: switches from direct
recursion to a `genericClosure` worklist past `fastPathLimit`
(500) frames. Use after `hints.resolve` has produced a Hint
for the failure, not before.



#### Hints


Hint resolver for diagnostic Errors.

Exports:
  resolve  : Error -> Hint | null
  classify : Error -> String
  hints    : { <key> = Hint; }

A Hint is `{ _tag = "Hint"; text; category; severity; docLink; }`.
The `_tag` marker keeps it terminal for `api.extractValue`, and
the remaining fields are plain data consumable by renderers,
LSPs, docs, and linters. Severity is `"error"` at this layer;
`docLink` resolves to a dedicated per-key page on
`docs.kleisli.io` of the form
`/nix-effects/diag-hints/<slug>`, where `<slug>` matches the
docs-site heading-id slugification rule applied to the key.
Each per-key page is also exposed as an MCP resource at
`docs://kleisli/nix-effects/diag-hints/<slug>`, so a compiler
Hint dereferences to focused agent-readable content in one
fetch.

Keys encode a leaf-anchored suffix of the blame path plus the
classifier pattern: `"<pos1>.<pos2>...<posN>::<pattern>"`. A key
matches when its positions equal the last N tags of the blame
path; `resolve` returns the hint under the longest matching
suffix. Single-position keys are the 1-hop special case. Hint
text is position-semantic: no kernel-rule strings, no source-file
references.

Chain walking recurses directly up to 500
frames, then falls through to a `builtins.genericClosure` slow
path that WHNF-forces the next node.

## `classify`

_classify: derive the classifier pattern string from an `Error`'s detail and leaf position — yields the right-hand side of suffix-keys consumed by `resolve` (e.g. `"universe-mismatch"`)._

```
classify : Error -> String
```

## `hints`

_hints: the closed `{ key = Hint }` registry indexed by `<pos1>.<pos2>...<posN>::<pattern>` keys; each value carries `text`, `category`, `severity`, `docLink` to the per-key `/nix-effects/diag-hints/<slug>` page._

## `mkHint`

_mkHint: structured `Hint` constructor from a `category` and `text` — sets `_tag = "Hint"` (terminal for `extractValue`), `severity = "error"`, and the default `docLink` pointing at the diag-hints section root._

```
mkHint : Category -> String -> Hint
```

## `resolve`

_resolve: walk a blame path inward from leaf to root, returning the `Hint` under the longest matching suffix-key — the canonical lookup for surfacing position-semantic guidance on a kernel `Error`._

```
resolve : Error -> Hint | null
```

## `taxonomy`

_taxonomy: closed list of allowed `Hint.category` values (`"universe"`, `"sort"`, `"description"`, `"arity"`, `"indexing"`, `"inhabitation"`, …); enforced by the `hints-categories-in-taxonomy` test._

## Hint registry

Diagnostic hints give stable names to recurring checker and validation
failures. Use the per-hint pages when an error includes a `Hint::<key>`
token, or scan the registry below to see the available hint keys.

### DArgSort::universe-mismatch

Category: **universe** · Severity: **error**

the sort position of `arg` must live in U(0); descriptions only carry small types. Pass `u 0`, or factor the dependency through `descRec` / `descPi` if a larger type is genuinely needed.

### DPiSort::universe-mismatch

Category: **universe** · Severity: **error**

the sort position of `pi` must live in U(0); `descPi` takes a small domain. Use `u 0`, or encode the dependency through an index instead of the Pi domain.

### LevelMaxLhs::type-mismatch

Category: **universe** · Severity: **error**

the left operand of `max` must be a Level

### LevelMaxRhs::type-mismatch

Category: **universe** · Severity: **error**

the right operand of `max` must be a Level

### LevelSucPred::type-mismatch

Category: **universe** · Severity: **error**

the predecessor of `suc` must be a Level

### ULevel::type-mismatch

Category: **universe** · Severity: **error**

the level argument of `U` must be a Level

### AnnType::not-a-type

Category: **sort** · Severity: **error**

the annotation position must be a type (live in some U(k)), not a term. Write a type expression such as `nat`, `bool`, `u 0`, or a user-defined datatype.

### JType::not-a-type

Category: **sort** · Severity: **error**

the type parameter of `J` must be a type (live in some U(k)), not a term. Pass a type expression like `nat`, `u 0`, or the type shared by J's two endpoints.

### Motive.PiDom::not-a-type

Category: **sort** · Severity: **error**

the motive's domain must be a type (live in some U(k)). The motive receives the scrutinee's type as its domain and returns a type; supply a concrete type such as `nat`, `u 0`, or the datatype being eliminated.

### Motive::not-a-type

Category: **sort** · Severity: **error**

an eliminator's motive must return a type (live in some U(k))

### PiCod::not-a-type

Category: **sort** · Severity: **error**

the codomain family of Π must return a type for each argument, not an ordinary value. Provide a function whose body inhabits some `U k`.

### PiDom::not-a-type

Category: **sort** · Severity: **error**

the domain of Π must be a type (live in some U(k)), not a term or value. Supply a type expression like `nat`, `bool`, `u 0`, or a user-defined datatype.

### DArgBody::not-a-desc

Category: **description** · Severity: **error**

the body of `arg` must produce a description (Desc I), not an ordinary value. Build one with `descRet`, `descArg`, `descRec`, `descPi`, or `descPlus`.

### DPiBody::not-a-desc

Category: **description** · Severity: **error**

the body of `pi` must produce a description for each input, not a plain term. Return a Desc I via `descRet`, `descArg`, `descRec`, `descPi`, or `descPlus`.

### DPlusL::not-a-desc

Category: **description** · Severity: **error**

the left summand of `plus` must be a description (Desc I)

### DPlusR::not-a-desc

Category: **description** · Severity: **error**

the right summand of `plus` must be a description at the same index type as the left summand

### DRecTail::not-a-desc

Category: **description** · Severity: **error**

the tail position of `rec` must itself be a description, not an ordinary term. Continue the spine with `descRet`, `descArg`, `descRec`, `descPi`, or `descPlus`.

### MuDesc::not-a-desc

Category: **description** · Severity: **error**

the description argument of μ must be a Desc I term, not an ordinary value. Construct it with `descRet`, `descArg`, `descRec`, `descPi`, or `descPlus`.

### AppHead::not-a-function

Category: **arity** · Severity: **error**

the head of an application must have a function type (Pi)

### DPiFn::not-a-function

Category: **arity** · Severity: **error**

the index selector `f` of `pi` must be a function `S -> I`

### Motive::not-a-function

Category: **arity** · Severity: **error**

the motive must be a function from the scrutinee's type into a type, not a bare type or value. Supply a one-argument function whose body lives in some `U k`.

### OpaqueType::not-a-function

Category: **arity** · Severity: **error**

the annotation on an opaque lambda must be a Pi type

### DPiFn::type-mismatch

Category: **indexing** · Severity: **error**

the index selector's domain must match the declared sort `S`

### DRecIndex::type-mismatch

Category: **indexing** · Severity: **error**

the index position of `rec` must match the Desc's declared index type. Pass a term of that index type, or adjust the enclosing `μ I ...` to match.

### DRetIndex::type-mismatch

Category: **indexing** · Severity: **error**

the index position of `ret` must match the Desc's declared index type. Supply a term of that index type, or redefine the enclosing `μ I ...` over the index you actually have.

### MuIndex::type-mismatch

Category: **indexing** · Severity: **error**

the index passed to `con` must have the description's index type

### MuPayload::type-mismatch

Category: **indexing** · Severity: **error**

the payload of `con` must inhabit the description's interpretation at the given index

### Elem::inhabitation-failed

Category: **inhabitation** · Severity: **error**

the element does not inhabit the list's element type

### Field::inhabitation-failed

Category: **inhabitation** · Severity: **error**

the field's value does not inhabit the declared field type

### SigmaFst::inhabitation-failed

Category: **inhabitation** · Severity: **error**

the first component does not inhabit the declared `fst` type

### SigmaSnd::inhabitation-failed

Category: **inhabitation** · Severity: **error**

the second component does not inhabit the dependent `snd` type

### Tag::inhabitation-failed

Category: **inhabitation** · Severity: **error**

the variant's payload does not inhabit the branch type

### Elem::refinement-failed

Category: **refinement** · Severity: **error**

the element violates the element type's refinement predicate

### Field::refinement-failed

Category: **refinement** · Severity: **error**

the field's value violates the field type's refinement predicate

### SigmaFst::refinement-failed

Category: **refinement** · Severity: **error**

the first component violates the `fst` type's refinement predicate

### SigmaSnd::refinement-failed

Category: **refinement** · Severity: **error**

the second component violates the `snd` type's refinement predicate

### Tag::refinement-failed

Category: **refinement** · Severity: **error**

the variant's payload violates the branch type's refinement predicate

### Case::type-mismatch

Category: **elimination** · Severity: **error**

this case-body's inferred type does not match the type the eliminator's motive requires

### Scrut::type-mismatch

Category: **elimination** · Severity: **error**

the scrutinee's type must match the eliminator's expected shape. Annotate the scrutinee via `ann`, or switch to the eliminator that matches its inferred type.

### AnnTerm::type-mismatch

Category: **type-mismatch** · Severity: **error**

the annotated term does not match its declared type

### AppArg::type-mismatch

Category: **type-mismatch** · Severity: **error**

the argument does not match the function's domain

### JType::type-mismatch

Category: **type-mismatch** · Severity: **error**

the type parameter of `J` must match the type of its two endpoints

### OpaqueType::type-mismatch

Category: **type-mismatch** · Severity: **error**

the opaque lambda's declared domain does not match the expected domain

### ::unhandled-boot-inl

Category: **shape** · Severity: **error**

the left injection `inl x` has no inference rule — the sum type's right summand is not determined by the syntax of `x` alone. Annotate with `ann (inl x) (sum A B)` to fix the expected sum, or place it where checking already provides one.

### ::unhandled-boot-inr

Category: **shape** · Severity: **error**

the right injection `inr y` has no inference rule — the sum type's left summand is not determined by the syntax of `y` alone. Annotate with `ann (inr y) (sum A B)` to fix the expected sum, or place it where checking already provides one.

### ::unhandled-boot-refl

Category: **shape** · Severity: **error**

`refl` has no inference rule — the type of the equated endpoint is not determined by its syntax. Annotate with `ann refl (eq A x x)`, or use `refl` where the surrounding rule already supplies an expected equality type.

### ::unhandled-lam

Category: **shape** · Severity: **error**

this lambda has no inference rule — its domain and codomain types are not determined by its syntax. Annotate with `ann (lam …) (pi A B)` to drive checking, or place it where the surrounding rule already supplies an expected Pi type.

### ::unhandled-other

Category: **shape** · Severity: **error**

this intro form has no inference rule — its type is not determined by its syntax alone. Either annotate the term with `ann <term> <type>` to switch the kernel into checking mode, or move it inside a context where an expected type is already known.

### ::unhandled-pair

Category: **shape** · Severity: **error**

this pair has no inference rule — its component types are not determined by its syntax. Annotate with `ann (pair …) (sigma A B)` to drive checking, or place it where the surrounding rule already supplies an expected Sigma type.

### ::unhandled-tt

Category: **shape** · Severity: **error**

the unit value `tt` has no inference rule — there is exactly one type it can inhabit. The kernel still asks for an annotation to keep inference syntax-directed. Use `ann tt unit` at the use site, or check `tt` against an expected `unit` type.



#### Pretty


Pretty-printing for diagnostic Errors.

Exports:
  pathSegments : Error -> [String]
  pathString   : Error -> String
  oneLine      : Error -> String
  multiLine    : Error -> String

Chain walkers recurse directly up to 500
frames, then fall through to a `builtins.genericClosure` slow
path that WHNF-forces the next node at each step.

Pure data -> string; no effects.

## `multiLine`

_multiLine: render `Error` as a multi-line block — header line, blame path, detail fields rendered with `renderValue`, and the optional hint text indented under the leaf._

```
multiLine : Error -> String
```

## `oneLine`

_oneLine: render `Error` as a single-line diagnostic combining `pathString`, layer tag, msg, and (when present) hint text — suited for editor squigglies and terse log output._

```
oneLine : Error -> String
```

## `pathSegments`

_pathSegments: walk an `Error` from root to leaf collecting position tags as strings; stack-safe to kernel-descent depth via the same fast/slow split as the other chain walkers._

```
pathSegments : Error -> [String]
```

## `pathString`

_pathString: render `Error`'s root-to-leaf positions as a dotted path (e.g. `"DArgSort.PiCod.AppArg"`); useful for log lines and one-line diagnostic summaries._

```
pathString : Error -> String
```

## `renderValue`

_renderValue: render an arbitrary detail value (term/type/payload) as a string suitable for inclusion in diagnostic output; centralises the formatting policy across `oneLine`/`multiLine`._

```
renderValue : Any -> String
```



### Effects

#### State


Mutable state effect: get/put/modify with standard handler.

## `get`

_get: read the current state threaded by the state handler; impure request whose response IS the handler state._

```
get : Computation s
```

Read the current state. Returns a Computation that, when handled,
yields the current state value.

## `gets`

_gets: read a projection of the current state via a user function; sugar for `bind get (s: pure (f s))`._

```
gets : (s -> a) -> Computation a
```

Read a projection of the current state.

## `handler`

_state.handler: interprets get/put/modify over a single state value; pair with `trampoline.handle` and the initial state._

Standard state handler. Interprets get/put/modify effects.
Use with `trampoline.handle`:

```nix
handle { handlers = state.handler; state = initialState; } comp
```

- `get`: returns current state as value
- `put`: replaces state with param, returns null
- `modify`: applies param (a function) to state, returns null

## `modify`

_modify: apply a function to the current state in place; impure request resuming with null after the handler runs the transformer._

```
modify : (s -> s) -> Computation null
```

Apply a function to the current state. Returns a Computation that,
when handled, transforms the state via f and returns null.

## `put`

_put: replace the current state with the supplied value; impure request resuming with null._

```
put : s -> Computation null
```

Replace the current state. Returns a Computation that, when handled,
sets the state to the given value and returns null.

## `update`

_update: read the state, run a user computation against it to produce `{ state, value }`, put the new state, return the value._

```
update : (s -> Computation { state, value }) -> Computation value
```

Apply a computation to the current state. Returns a Computation that,
when handled, updates the state and returns value.



#### Reader


Read-only environment effect: ask/asks/local with standard handler.

## `ask`

_ask: read the current environment threaded by the reader handler; impure request whose response IS the handler state._

```
ask : Computation env
```

Read the current environment.

## `asks`

_asks: read a projection of the environment via a user-supplied function; sugar for `bind ask (env: pure (f env))`._

```
asks : (env -> a) -> Computation a
```

Read a projection of the environment.

## `handler`

_reader.handler: interprets ask/local effects with state IS the (immutable) environment; ask resumes with state, local replaces it._

Standard reader handler. Interprets ask effects.
The state IS the environment (immutable through the computation).

```nix
handle { handlers = reader.handler; state = myEnv; } comp
```

## `local`

_local: run a sub-computation under a modifier-transformed environment; sends `local` so handlers can install the modified env._

```
local : (env -> env) -> Computation a -> Computation a
```

Run a computation with a modified environment. Returns a new
computation that transforms the environment before executing
the inner computation.

Since handlers are pure functions, local is implemented by
wrapping the inner computation's ask effects with the modifier.
In practice, use separate handler installation with the modified env.



#### Writer


Append-only output effect: tell/tellAll with list-collecting handler.

## `handler`

_writer.handler: collects tell/tellAll output as a list in handler state, starting at `[]`; pair with `trampoline.handle`._

Standard writer handler. Collects tell output in state as a list.
Initial state: `[]`

```nix
handle { handlers = writer.handler; state = []; } comp
```

## `tell`

_tell: append a single value to the writer effect's output log; impure request resuming with null._

```
tell : w -> Computation null
```

Append a value to the output log.

## `tellAll`

_tellAll: append a list of values to the writer effect's output log in a single impure request; one bind instead of N from mapping tell._

```
tellAll : [w] -> Computation null
```

Append a list of values to the output log.



#### Acc


Accumulator effect: emit/emitAll/collect for incremental list building.

## `collect`

_collect: read the acc effect's currently accumulated items as a list; impure request returning the contents captured so far._

```
collect : Computation [a]
```

Read the current accumulated items as a list. Returns whatever has been
emitted within the surrounding handled scope.

## `emit`

_emit: append a single item to the acc effect's accumulator; issues an impure effect request whose result is null._

```
emit : a -> Computation null
```

Append a single item to the accumulator. Pairs with `collect` to read
back all items emitted within the surrounding handled scope.

## `emitAll`

_emitAll: append a list of items to the acc effect's accumulator in a single impure request; one bind instead of N from mapping emit._

```
emitAll : [a] -> Computation null
```

Append a list of items to the accumulator in a single effect request.
Equivalent to mapping `emit` over the list but cheaper at runtime.

## `handler`

_acc.handler: standard accumulator handler implementing emit/emitAll/collect over a list state with `[]` as the initial value._

Standard accumulator handler. State is the list of accumulated items,
starting at `[]`.

```nix
handle { handlers = acc.handler; state = []; } comp
```



#### Error


Error effect with contextual messages and multiple handler strategies.

## `collecting`

_error.collecting: handler that accumulates every error into state as a list of `{ message, context }` and resumes computation with null._

Collecting error handler: accumulates errors in state as a list.
Resumes computation with null so subsequent effects still execute.
Use when you want all errors, not just the first.

State shape: list of { message, context }

## `raise`

_raise: send an `error` effect carrying a message and empty context; the handler decides whether to throw, collect, or recover._

```
raise : string -> Computation a
```

Raise an error. Returns a Computation that sends an "error" effect.
The handler determines what happens: throw, collect, or recover.

## `raiseWith`

_raiseWith: raise an error with a context string; handlers can collect contexts to assemble stack-trace-style reports._

```
raiseWith : string -> string -> Computation a
```

Raise an error with context. The context string describes where
in the computation the error occurred, enabling stack-trace-like
error reports when used with the collecting handler.

## `result`

_error.result: handler that aborts with a tagged `{ _tag = "Error"; message; context; }` value; uses the non-resumption protocol._

Result error handler: aborts computation with tagged Error value.
Uses the non-resumption protocol to discard the continuation.

Returns `{ _tag = "Error"; message; context; }` on error.

## `strict`

_error.strict: handler that throws on the first error via `builtins.throw`, prefixing context when present; halts evaluation immediately._

Strict error handler: throws on first error via builtins.throw.
Use when errors should halt evaluation immediately.

Includes context in the thrown message when available.



#### Conditions


CL-style condition system: signal/warn with restart-based recovery.

## `collectConditions`

_conditions.collectConditions: handler that accumulates each condition into state as `{ name, data }` and resumes with `continue`._

Collecting handler: accumulates conditions in state, resumes with continue.
State shape: list of { name, data }
Initial state: []

## `fail`

_conditions.fail: last-resort handler that throws on any condition (via `builtins.throw`); ignores available restarts._

Fail handler: throws on any condition. Ignores available restarts.
Use as a last-resort handler.

## `ignore`

_conditions.ignore: handler that silently discards every condition by resuming with `{ restart = "continue"; value = null; }`._

Ignore handler: resumes with null for any condition.
All conditions are silently discarded.

## `signal`

_signal: raise a CL-style condition with name, data, and available restart names; the handler returns `{ restart, value }` to choose recovery._

```
signal : string -> any -> [string] -> Computation any
```

Signal a condition. The handler chooses a restart strategy.

**Arguments:**
- `name` — condition name (e.g. `"division-by-zero"`, `"file-not-found"`)
- `data` — condition data (error details, context)
- `restarts` — list of available restart names

The handler receives `{ name, data, restarts }` and returns a
`{ restart, value }` attrset. The continuation receives this choice.

## `warn`

_warn: raise a warning condition with the conventional `muffle-warning` restart; if the handler doesn't muffle, computation continues._

```
warn : string -> any -> Computation null
```

Signal a warning condition. Like signal but with a conventional
`"muffle-warning"` restart. If the handler doesn't muffle, the
computation continues normally.

## `withRestart`

_withRestart: handler factory invoking a named restart with a given value for one matched condition; throws on every other condition._

```
withRestart : string -> string -> any -> handler
```

Create a handler that invokes a specific restart for a named condition.
For all other conditions, falls through (throws).

**Arguments:**
- `condName` — condition name to match
- `restartName` — restart to invoke
- `restartVal` — value to pass via the restart



#### Choice


Non-deterministic choice effect: choose/fail/guard with list handler.

## `choose`

_choose: non-deterministic selection from a list of alternatives; the handler determines exploration strategy (e.g. listAll for all branches)._

```
choose : [a] -> Computation a
```

Non-deterministic choice from a list of alternatives. The handler
determines how alternatives are explored.

## `fail`

_fail: abort the current non-deterministic branch; equivalent to `choose []` with an empty-alternatives short-circuit._

```
fail : Computation a
```

Fail the current branch of non-deterministic computation.
Equivalent to `choose []`.

## `guard`

_guard: continue when the predicate is true, fail the branch when false; threads boolean predicates into non-deterministic search._

```
guard : bool -> Computation null
```

Guard a condition: continue if true, fail if false.

## `initialState`

_choice.initialState: starting state `{ results = []; pending = []; }` for the listAll handler; pair with `handle` to run._

Initial state for the listAll handler.

## `listAll`

_choice.listAll: handler exploring every non-deterministic branch and accumulating results into `state.results`; list-monad semantics._

Handler that explores all non-deterministic branches and returns
a list of all results. Empty choices abort that branch.

State is `{ results : [a], pending : [Computation a] }`.
After handling, results are in `state.results`.

```nix
let r = handle { handlers = choice.listAll; state = choice.initialState; } comp;
in r.state.results
```



#### Scope


Computation-scoped handlers via effect rotation.

## `handlersFromAttrs`

_scope.handlersFromAttrs: lift an attrset of handlers, functions, or constants into named effect handlers; preserves shape and state._

```
handlersFromAttrs : { <name> = handler | (param -> a) | a; ... } -> handlers
```

Helper to transform an attrset into named handlers.

If attrValue is a function `{ param, state }` it is used directly as handler;
If attrValue is a function, resume is `f param` and preserves state;
Otherwise a constant handler always resumes with attrValue, preserving state.

## `provide`

_scope.provide: install stateless handlers for a sub-computation's dynamic extent (reader/val pattern); outer handler state survives unchanged._

```
scope.provide : handlers -> Computation a -> Computation a
```

Install handlers for a computation's dynamic extent without
touching state. Unhandled effects rotate outward; outer handler
state mutations survive unaffected.

This is the reader/val handler pattern (Koka's `val`, Haskell's
`runReader`, Scheme's `parameterize`) — use it when handlers are
stateless (resume with a constant, pass state through).
For handlers that need their own state, use scope.run or
scope.stateful instead.

## `run`

_scope.run: handle named effects inside a sub-computation and hide the scope's own state from the caller; rotates unknown effects outward._

```
scope.run : { handlers, state? } -> Computation a -> Computation a
```

Run a computation with scoped handlers. Effects matching `handlers`
are handled inside the scope. Unknown effects rotate outward.
The scope's internal state is hidden — caller sees only the body's value.

## `runWith`

_scope.runWith: like scope.run but surfaces the scope's final `{ value, state }` to the caller; raw rotation without state hiding._

```
scope.runWith : { handlers, state? } -> Computation a -> Computation { value, state }
```

Like scope.run but exposes the scope's final state alongside the value.

## `stateful`

_scope.stateful: run a sub-computation under scoped handlers while preserving outer state around the rotation point; wraps state.update._

```
stateful : handlers -> Computation a -> Computation a
```

Run a computation with scoped handlers while preserving
state around effect rotation.

## `val`

_scope.val: provide constant values as named effect handlers for a sub-computation; sugar for `provide (handlersFromAttrs bindings)`._

```
scope.val : { <name> = value; ... } -> Computation a -> Computation a
```

Provide constant values as named effect handlers for a
computation's dynamic extent. Each key in the bindings attrset
becomes an effect that resumes with the corresponding value.
Built on scope.provide via handlersFromAttrs.

Named after Koka's `val` effect handler. For the traditional
single-environment reader (ask/asks/local), see fx.effects.reader.



#### Linear


Graded linear resource tracking: acquire/consume/release with usage enforcement.

Each resource gets a capability token at acquire time. The graded handler
covers linear (exactly once), affine (at most once via release), exact(n),
and unlimited usage through a single maxUses parameter.

Quick start:

```nix
let comp = bind (linear.acquireLinear "secret") (token:
  bind (linear.consume token) (val:
    pure val));
in linear.run comp
```

For composition with other handlers, use handler/return/initialState with
`adaptHandlers`.

## `acquire`

_acquire: take a graded linear resource and obtain a capability token; `maxUses` (or null) sets the linearity bound enforced by the handler._

```
acquire : { resource : a, maxUses : Int | null } -> Computation Token
```

Acquire a graded linear resource. Returns a capability token.

The token wraps the resource with an ID for tracking. The handler
maintains a resource map in its state, counting each consume call
against the maxUses bound.

- `maxUses = 1` — Linear: exactly one consume required
- `maxUses = n` — Exact: exactly n consumes required
- `maxUses = null` — Unlimited: any number of consumes allowed

Tokens should be consumed exactly maxUses times, or explicitly
released. At handler exit, the return clause (finalizer) checks:
released → always OK, `maxUses = null` → always OK,
otherwise → `currentUses` must equal `maxUses`.

## `acquireExact`

_acquireExact: acquire a resource that must be consumed exactly `n` times; encodes graded linearity beyond pure linear/affine._

```
acquireExact : a -> Int -> Computation Token
```

Acquire a resource that must be consumed exactly n times.

## `acquireLinear`

_acquireLinear: acquire a strictly linear resource (maxUses = 1); the finalizer fails unless exactly one consume happens before scope exit._

```
acquireLinear : a -> Computation Token
```

Acquire a linear resource (exactly one consume required).

## `acquireUnlimited`

_acquireUnlimited: acquire a resource with `maxUses = null`; the finalizer never reports usage mismatches for unlimited tokens._

```
acquireUnlimited : a -> Computation Token
```

Acquire an unlimited resource (any number of consumes allowed).

## `consume`

_consume: spend a use of a capability token and return the wrapped resource; aborts with `LinearityError` on use-after-release or bound-exceeded._

```
consume : Token -> Computation a
```

Consume a capability token, returning the wrapped resource value.

Increments the token's usage counter. Aborts with `LinearityError` if:
- Token was already released (`"consume-after-release"`)
- Usage would exceed maxUses bound (`"exceeded-bound"`)

The returned value is the original resource passed to acquire.

## `handler`

_linear.handler: interprets linearAcquire/linearConsume/linearRelease over a `{ nextId, resources }` state; emits tagged LinearityError on misuse._

Graded linear resource handler. Interprets linearAcquire, linearConsume,
and linearRelease effects. Tracks resource usage in handler state.

Use with `trampoline.handle`:

```nix
handle {
  handlers = linear.handler;
  return = linear.return;
  state = linear.initialState;
} comp
```

Or use the convenience: `linear.run comp`

- `linearAcquire`: creates token, adds resource entry to state
- `linearConsume`: increments usage counter, returns resource value
- `linearRelease`: marks resource as released (finalizer skips it)

## `initialState`

_linear.initialState: `{ nextId = 0; resources = {}; }`; monotonic ID counter plus an empty resource map indexed by stringified ID._

Initial handler state for the linear resource handler.

```nix
{ nextId = 0; resources = {}; }
```

- `nextId`: monotonic counter for generating unique resource IDs.
- `resources`: map from ID (string) to resource tracking entry.

## `release`

_release: drop a capability token without consuming it; the finalizer then skips it (affine usage). Aborts on double-release._

```
release : Token -> Computation null
```

Explicitly release a capability token without consuming it.

Marks the resource as released. The finalizer skips released resources,
so this allows affine usage (acquire then drop). Aborts with
`LinearityError` on double-release.

## `return`

_linear.return: finalizer checking every non-released, finite-bound resource was consumed exactly `maxUses` times; wraps mismatches in LinearityError._

```
return : a -> State -> { value : a | LinearityError, state : State }
```

Finalizer return clause for the linear handler.

Checks each resource in handler state:
- `released` → OK (explicitly dropped)
- `maxUses = null` → OK (unlimited)
- otherwise → `currentUses` must equal `maxUses`

On violation, wraps the original value in a `LinearityError` with
details of each mismatched resource. On success, passes through
unchanged. Runs on both normal return and abort paths.

## `run`

_linear.run: convenience wrapper bundling handler, return, and initialState; runs a computation under the graded linear discipline._

```
run : Computation a -> { value : a | LinearityError, state : State }
```

Run a computation with the graded linear handler.

Bundles handler, return clause, and initial state into one call.
To compose with other handlers, use handler/return/initialState
separately with `adaptHandlers`.

```nix
let
  comp = bind (acquireLinear "secret") (token:
    bind (consume token) (val:
      pure "got:${val}"));
in linear.run comp
# => { value = "got:secret"; state = { nextId = 1; resources = { ... }; }; }
```



#### Typecheck


Reusable typeCheck handlers. Use `policy.<name>` for the canonical surface; legacy `strict`/`collecting`/`logging` attributes are preserved for back-compat.

## `collecting`

_policy.collecting: accumulates every failing typeCheck into state as a list of `{ context, typeName, actual, message, path, reason }`._

Collecting typeCheck handler: accumulates errors in state.
Resumes with `true` on success, `false` on failure (computation continues).

State shape: list of `{ context, typeName, actual, message, path, reason }`
Initial state: `[]`

## `firstN`

_policy.firstN N: bounded-collection handler keeping up to N failures, then setting `aborted = true` and dropping the rest. State stays bounded._

```
firstN : Int -> Handler
```

Bounded-collection handler: collects up to N failures, then drops the rest.

Useful for early-termination policies where the consumer only needs
a handful of representative errors. After the Nth failure, `aborted`
flips true and subsequent failures are silently dropped (state size
stays bounded at N entries).

State shape: `{ collected :: [errorRecord]; aborted :: Bool; }`
Initial state: `{ collected = []; aborted = false; }`

## `logging`

_policy.logging: records every typeCheck (pass and fail) in state with `passed` boolean; useful for tracing without aborting computation._

Logging typeCheck handler: records every check (pass or fail) in state.
Always resumes with the actual check result (boolean).

State shape: list of `{ context, typeName, passed, path, reason }`
Initial state: `[]`

## `policy`

_policy: canonical grouped surface for typecheck handlers._

Grouped `strict`/`collecting`/`logging`/`firstN`/`summarize`/`pretty` handlers.

## `pretty`

_policy.pretty cfg: emits one pre-formatted `[reason] expected T at <loc>, got <actualType>` line per failure; renders the Position-list path with per-segment separators._

```
pretty : { sourceMap? } -> Handler
```

Display-rendering handler: emits one pre-formatted line per failure.

Renders the blame location by concatenating each Position's
`segment` field (`.field`, `[i]`, `#Tag` carry their own
separator). Falls back to `context` when the path is empty.
Each line is shaped:
  [reason] expected typeName at <location>, got <actualType>

`cfg.sourceMap` is reserved for future source-span annotation; not
consumed yet.

State shape: `[String]` (one entry per failure; consumer joins with
newline for display).
Initial state: `[]`

## `strict`

_policy.strict: throws on the first failing typeCheck via `builtins.throw`; resumes with true on success. Halts evaluation on error._

Strict typeCheck handler: throws on first type error.
Resumes with true on success (check passed).

Use when type errors should halt evaluation immediately.
State: unused (pass null).

## `summarize`

_policy.summarize: bounded-memory grouping by `reason`; tracks counts per reason plus pass/fail totals. State is O(K) in distinct reasons, not O(N)._

Bounded-memory grouping handler: counts failures by `reason`, drops
per-failure data (value/path/context/message) so memory stays O(K)
in the number of distinct reasons rather than O(N) in the number
of effects.

Use for high-volume validation where individual error records would
blow up state — only the aggregate matters.

State shape: `{ byReason :: { <reason> = Int; ... }; passed :: Int; failed :: Int; }`
Initial state: `{ byReason = {}; passed = 0; failed = 0; }`



#### HasHandler


Check if a handler with given name exists in current scope.



### Types

#### Foundation


Type system foundation: Type constructor, check, validate, make, refine.

## `bind`

_bind: re-export of `fx.kernel.bind` for dependent contract modules._

Re-export of `fx.kernel.bind`.

## `check`

_check: predicate that asks whether `value` inhabits `type`; returns the type's guarded kernel decision as a Bool, never throws._

```
check : Type -> Value -> Bool
```

Check whether a value inhabits a type. Pure — returns a Bool. The dual of `make`, which throws on failure.

## `defEq`

_defEq: definitional equality on types; true iff the kernel-conversion judgment `Γ ⊢ A._kernel ≡ B._kernel` holds under β/η/ι/μ reduction._

```
defEq : Type -> Type -> Bool
```

Definitional equality on types. This is the type-theoretic
equality that decides when two type expressions denote the same
type:

    conv 0 (eval [] (elab A._kernel)) (eval [] (elab B._kernel))

Strictly stronger than meta-language `==` on `_kernel`: Nix `==`
only coincides with conv when the encoding contains no closures.
After the description-backed migration of Record/Variant/Certified,
`(H.datatype …).T` carries Pi-binder closures and per-call fresh
thunks; `==` on those kernels is no longer a sound proxy for
type equality. `defEq` is the correct predicate.

Grounded in Martin-Löf (1984), section 6, and standard NbE conversion
(Abel et al. 2007).

## `make`

_make: assert-and-return; runs `type.check` on the value, returning it on success or throwing a `nix-effects type error` on failure._

```
make : Type -> Value -> Value
```

Validate a value and return it, or throw on failure. The throwing dual of `check`.

## `mkType`

_mkType: foundation type constructor; builds a `nix-effects` type from a kernel HOAS representation plus optional guard/verify/universe/approximate flags._

```
mkType : { name, kernelType ? null, guard ? null, verify ? null, description ? name, universe ? null, approximate ? false } -> Type
```

Create a type from its kernel representation.

A nix-effects type is defined by its `kernelType` — an HOAS type tree
representing the type in the MLTT kernel. All fields are derived:

- `.check` = `decide(kernelType, v)` — the decision procedure
- `.universe` = `checkTypeLevel(kernelType)` — computed universe level
- `.kernelCheck` = same as `.check`
- `.prove` = kernel proof checking for HOAS terms

Arguments:

- `name` — Human-readable type name
- `kernelType` — HOAS type tree (required — this IS the type)
- `guard` — Optional runtime predicate for refinement types.
  When present, `.check = kernelDecide(v) && guard(v)` (conjunction —
  kernel catches structural errors, guard handles residual constraints).
  The guard handles constraints the kernel can't express (e.g., x >= 0).
- `verify` — Optional custom verifier
  (`self → fuel → path → value → Computation`).
  `fuel` is the native-recursion budget: recursive verifiers
  descend natively while it is positive and defer the sub-walk
  via a `deriveBounce` effect when it runs out, keeping deep
  structures stack-safe. Non-recursive verifiers ignore it.
  `path` is a list of `fx.diag.positions` Position records
  describing the structural descent from the validation root
  (e.g. `[(P.Field "a") (P.Field "b")]` for a nested field,
  `[(P.Elem 0) (P.Field "mtu")]` for a list element's field).
  When null (default), `validate` is auto-derived by wrapping
  `check` in a `typeCheck` effect. Supply a custom `verify` for
  types that decompose checking (e.g. Record sends separate
  effects per field for blame tracking).
- `description` — Documentation string (default = `name`)
- `universe` — Optional universe level. When null (default), the level
  is computed from `checkTypeLevel(kernelType)`. The computed level is
  total: `.universe` throws — rather than fabricating a level — when
  the kernel type is not a type, depends on a term, or is
  level-polymorphic. A supplied `universe` is enforced against the
  kernel minimum: it may over-approximate it (e.g. for a fallback
  `kernelType`) but under-approximation is inconsistent and throws, and
  it cannot pin a level on a type that has none.
- `approximate` — When true, the kernelType is a sound but lossy
  approximation (e.g., `H.function_` for Pi, `H.any` for Sigma).
  Suppresses `_kernel`, `kernelCheck`, and `prove` on the result,
  since the kernel representation doesn't precisely capture this type.
  The kernelType is still used internally for universe computation.

## `pure`

_pure: re-export of `fx.kernel.pure` for dependent contract modules._

Re-export of `fx.kernel.pure`.

## `refine`

_refine: narrow a base type with an extra predicate; returns a refined `Type` whose `check` conjoins kernel decision with the supplied guard._

```
refine : Type -> (Value -> Bool) -> Type
```

Narrow a type with an additional predicate. Creates a refinement type
whose check = kernelDecide(v) ∧ guard(v) (conjunction).
The base type's kernel provides structural checking; the guard handles
the refinement predicate the kernel cannot express.
Grounded in Freeman & Pfenning (1991) "Refinement Types for ML" and Rondon et al. (2008) "Liquid Types".

## `refineGuard`

_refineGuard: build a refinement type's guard slot from a base type and a predicate; a KernelPred witness yields a kernel-derived (authoritative) guard composed with the base's witness, a raw predicate stays an opaque lambda conjoined with `base.check`._

```
refineGuard : Type -> (Value -> Bool | KernelPred) -> (Value -> Bool | KernelPred)
```

Shared by `refine` and `refinement.refined` so both compose guards identically. A `KernelPred` predicate is threaded through (and `andKP`-composed with `base._kernelPred`); a raw predicate becomes `v: base.check v && predicate v`.

## `send`

_send: re-export of `fx.kernel.send` for dependent contract modules._

Re-export of `fx.kernel.send`.

## `validate`

_validate: emit a standalone `typeCheck` effect with an explicit `context` string for ad-hoc validation; prefer `type.validate` unless overriding context._

```
validate : Type -> Value -> String -> Computation Bool
```

Standalone effectful validation with explicit context string.

Sends a `typeCheck` effect with the given type, value, and context.
The handler receives `{ type, context, value }` and determines the
response: throw, collect error, log, or offer restarts.

For typical use, prefer `type.validate` (auto-derived by `mkType`,
uses the type's name as context). This 3-arg form is for cases
where a custom context string is needed.



#### Primitives


Primitive types: String, Int, Bool, Float, Attrs, Path, Derivation, Function, Null, Unit, Any.

## `Any`

_Any: top type; every Nix value inhabits it, backed by `H.any` — used as the lossy fallback kernel for approximate types._

Top type. Every value inhabits `Any`. Approximate types fall back to `Any` for their kernel slot.

## `Attrs`

_Attrs: primitive type for any Nix attribute set; backed by `H.attrs` — accepts every attrset including `{}`, never checks field shape._

Attribute set type. Any attrset, including `{}`. Use `Record` for declared-field shape.

## `Bool`

_Bool: primitive type whose only inhabitants are `true` and `false`; backed by the `H.bool` kernel type with precise kernel decision._

Boolean type. Inhabited by `true` and `false`.

## `Derivation`

_Derivation: primitive type for Nix derivation values — attrsets carrying `type = "derivation"`. The store-producing irreducible value category that makes Nix Nix; rejects plain attrsets, strings, and paths._

Derivation type. Nix derivation values (built via `mkDerivation` /
`runCommand` / `stdenv.mkDerivation` etc.).

Membership is decided structurally: any attrset with
`type = "derivation"` qualifies. Bare attrsets (no `type` field),
strings (e.g. `"pkgs.hello"`), and paths (e.g. `./foo`) are
rejected — derivations are a distinct value category.

## `Float`

_Float: primitive type whose values are Nix floating-point numbers; backed by `H.float_` and decided by `builtins.isFloat` (excludes ints)._

Float type. Inhabited by Nix floats; rejects integers.

## `Function`

_Function: primitive type for Nix lambdas; backed by `H.function_` and decided by `builtins.isFunction` — argument/result shape is not introspected._

Function type. Any Nix lambda. The arrow shape (`a -> b`) is not checked at this level — use `H.forall` for that.

## `Int`

_Int: primitive type whose values are Nix integers; backed by the `H.int_` kernel type and decided by `builtins.isInt` (excludes floats)._

Integer type. Inhabited by Nix integer values; rejects floats.

## `Null`

_Null: primitive type whose only inhabitant is `null`; isomorphic to `Unit` and backed by the `H.unit` kernel type._

Null type. Only `null` inhabits it. Isomorphic to `Unit`.

## `Path`

_Path: primitive type for Nix path values; rejects strings — paths and strings are distinct value categories in Nix._

Path type. Nix path values (e.g. `./foo`); not interchangeable with strings.

## `String`

_String: primitive type whose values are Nix strings; backed by the `H.string` kernel type and decided by `builtins.isString` at the elaborator._

String type. Inhabited by Nix string values.

## `Unit`

_Unit: primitive type with one inhabitant `null`; isomorphic to `Null`, backed by the `H.unit` kernel type — the trivial / terminal type._

Unit type. Trivial type with one inhabitant. Isomorphic to `Null`.



#### Constructors


Type constructors: Record, RecordOpen, ListOf, Maybe, Either, Variant.

## `Either`

_Either: tagged sum type constructor; `Either L R` accepts `{ _tag = "Left"; value : L }` or `{ _tag = "Right"; value : R }`._

```
Either : Type -> Type -> Type
```

Tagged union of two types. Accepts `{ _tag = "Left"; value = a; }`
or `{ _tag = "Right"; value = b; }`.

## `ListOf`

_ListOf: homogeneous list type constructor; `ListOf T` checks every element has type `T`, blames per-index, never short-circuits — handler picks error policy._

```
ListOf : Type -> Type
```

Homogeneous list type. `ListOf Type` checks that all elements have the given type.

Custom verifier sends per-element `typeCheck` effects with indexed context
strings (e.g. `List[Int][2]`) for blame tracking. Unlike Sigma, elements
are independent — no short-circuit. All elements are checked; the handler
decides error policy (strict aborts on first, collecting gathers all).

## `Maybe`

_Maybe: option type constructor; `Maybe T` accepts null or any value of type `T`; kernel precision and sufficiency inherit from the inner type._

```
Maybe : Type -> Type
```

Option type. Maybe Type accepts null or a value of Type.

## `Record`

_Record: closed record type constructor; `Record { f = T; ... }` checks that values carry exactly the declared fields with matching types and rejects extras._

```
Record : { <field> = Type; ... } -> Type
```

Closed record type constructor. Takes a schema `{ field = Type; ... }`
and checks that a value has exactly the declared fields with correct
types. Unknown fields are rejected — for open semantics use `RecordOpen`.

Verify is per-field and emits one `typeCheck` effect per blamed field,
threading a `Field name` Position so handlers can recover the structural
path.

## `RecordOpen`

_RecordOpen: open-record type constructor; like `Record` but undeclared fields are accepted untouched, useful for records carrying optional metadata slots._

```
RecordOpen : { <field> = Type; ... } -> Type
```

Open record type constructor. Like `Record`, but undeclared fields are
permitted (and ignored by kernel and verify). Use for types whose
values carry intentional metadata slots beyond the declared schema —
e.g. build steps with optional `tools` / `env` / `when` annotations.

The kernel datatype tags `openExtras = true` in `_dtypeMeta` so
downstream type-directed walks know to allow them.

## `Variant`

_Variant: discriminated-union type constructor; `Variant { tag = T; ... }` accepts `{ _tag = name; value }` checked against the named branch._

```
Variant : { <tag> = Type; ... } -> Type
```

Discriminated union. Takes `{ tag = Type; ... }` schema.
Accepts `{ _tag = "tag"; value = ...; }` where value has the corresponding type.



#### Refinement


Refinement types and predicate combinators.
Grounded in Freeman & Pfenning (1991) and Rondon et al. (2008).

## `allOf`

_allOf: conjoin a list of predicates. A non-empty list of all-KernelPred members folds into one KernelPred (the conjoined refinement internalizes); any raw lambda, or an empty list, yields a plain conjoined guard that holds when every member holds (empty = constant `true`)._

```
allOf : [(KernelPred | (Value -> Bool))] -> (KernelPred | (Value -> Bool))
```

Combine predicates with conjunction: `(allOf [p1 p2]) v = p1 v && p2 v`. All-KernelPred input folds to a KernelPred so the refinement internalizes; a raw-lambda member demotes to a plain guard. Empty list returns constant `true`.

## `anyOf`

_anyOf: disjoin a list of predicates into one that holds when any member holds; the empty list yields a constant `false`._

```
anyOf : [(Value -> Bool)] -> Value -> Bool
```

Combine predicates with disjunction: `(anyOf [p1 p2]) v = p1 v || p2 v`. Empty list returns `false`.

## `eqInt`

_eqInt: kernel-internalizing factory predicate `x == k` over Int; internalizes into the kernel `ktype`._

```
eqInt : Int -> KernelPred
```

KernelPred witness factory over the signed-int carrier deciding `x == k`.

## `inRange`

_inRange: factory predicate asserting that a numeric value lies within `[lo, hi]`; both endpoints are inclusive._

```
inRange : Number -> Number -> Number -> Bool
```

Predicate factory: `(inRange lo hi) v = lo <= v <= hi`. Both endpoints inclusive.

## `inRangeInt`

_inRangeInt: kernel-internalizing factory predicate `lo <= x <= hi` over Int; both endpoints inclusive, internalizes into the kernel `ktype`._

```
inRangeInt : Int -> Int -> KernelPred
```

KernelPred witness factory over the signed-int carrier deciding `lo <= x <= hi`.

## `matching`

_matching: factory predicate that holds when a value is a string fully matched by the supplied regex pattern; non-strings are rejected._

```
matching : String -> String -> Bool
```

Predicate factory: `(matching pattern) s = s matches regex pattern`. Full-match semantics — anchor not needed.

## `negate`

_negate: flip a predicate's polarity; `negate p` accepts exactly the values `p` rejects, and vice versa._

```
negate : (Value -> Bool) -> Value -> Bool
```

Negate a predicate: `(negate p) v = !(p v)`.

## `nonEmpty`

_nonEmpty: predicate asserting that a string or list has at least one element/character; values of other types are rejected._

```
nonEmpty : (String | List) -> Bool
```

Predicate: string or list is non-empty. Rejects non-string/non-list inputs.

## `nonEmptyStr`

_nonEmptyStr: kernel-internalizing refinement predicate deciding String non-emptiness via the host-backed `strLen` (`1 <= length x`). As the predicate of `refined`/`refine` it internalizes into the kernel `ktype`, unlike the raw `nonEmpty` which also covers the list carrier._

```
nonEmptyStr : KernelPred
```

KernelPred witness over the string carrier deciding `length x >= 1` through `strLen`. Use in place of `nonEmpty` on String to internalize the refinement (non-null `.ktype`).

## `nonNegative`

_nonNegative: predicate asserting that a numeric value is greater than or equal to zero; accepts zero, rejects negatives._

```
nonNegative : Number -> Bool
```

Predicate: `value >= 0`. Zero accepted.

## `nonNegativeInt`

_nonNegativeInt: kernel-internalizing refinement predicate `x >= 0` over Int; internalizes into the kernel `ktype` when used with `refined`/`refine`._

```
nonNegativeInt : KernelPred
```

KernelPred witness over the signed-int carrier deciding `x >= 0`.

## `oneOfStr`

_oneOfStr: kernel-internalizing factory predicate deciding membership in a fixed String literal set, via the kernel's decidable `strEq`; a singleton list is equality-against-literal. As the predicate of `refined`/`refine` it internalizes into the kernel `ktype`. Decides by literal equality — substring/match stay outside the kernel._

```
oneOfStr : [String] -> KernelPred
```

KernelPred witness factory over the string carrier deciding `x ∈ {lits…}` as a strEq disjunction. Unlike `matching` (a raw lambda needing string introspection the kernel lacks), this internalizes.

## `positive`

_positive: predicate asserting that a numeric value is strictly greater than zero; rejects zero, negatives, and non-numerics by extension._

```
positive : Number -> Bool
```

Predicate: `value > 0`. Strict — zero is rejected.

## `positiveInt`

_positiveInt: kernel-internalizing refinement predicate `x > 0` over Int; as the predicate of `refined`/`refine` it yields a type whose check is kernel-decided and whose `.ktype` is non-null._

```
positiveInt : KernelPred
```

KernelPred witness over the signed-int carrier deciding `x > 0`. Unlike `positive` (a raw lambda), this internalizes into the kernel `ktype`.

## `refined`

_refined: build a named refinement type narrowing `base` with an extra predicate; the resulting type's `check` conjoins kernel decision with the guard._

```
refined : String -> Type -> (Value -> Bool) -> Type
```

Create a named refinement type. The supplied predicate runs in
addition to the base type's check — kernel handles structural
validation, the predicate handles residual constraints.



#### Dependent


Dependent contracts: Pi (Π), Sigma (Σ), Certified, Vector, DepRecord.
Grounded in Martin-Löf (1984) "Intuitionistic Type Theory".

## `Certified`

Subset type `Σ(x:A).P(x)` with `P(x)` a mere proposition. The witness
is an inhabitant of `P(x)`, not the host Bool. Two formers, one type:

- decidable `predicate` (a `reflect` KernelPred) → `P x = KT.P(decide t x)`
  (`Unit`/`Void` ≡ `KT.El t`); witness is the Unit inhabitant (`null`),
  synthesized by `certify`. `_kernelSufficient = true`; `_kernel = El t`.
- general `{ family; bridge; }` (`family : A → U`, or a `mkPropFamily`
  bundle passed as `family`) → `P x = squash(family x)`, proof
  irrelevance definitional; witness is `squashIntro` of a checked HOAS
  proof supplied to `certifyProof v p`. `_kernelSufficient = false`.

A predicate that is neither (a raw host lambda) yields no proof, so it is
not a `Certified` — construction throws. For an un-proven runtime guard
use `fx.types.refinement.refined`.

Construction:

- `.certify v` — decidable: pure, fail-closed, synthesizes the witness.
- `.certifyProof v p` — general: checks `p : family(v)`, then truncates.
- `.certifyE v` — decidable effectful dual (sends `typeCheck` on failure).
- `.certifyProofE v p` — general effectful dual (sends `typeCheck` on failure).
- `.check` / `.validate` — inherited from Sigma (pair check / effectful intro).
- `.prove term` — checks a term against the genuine subset `_kernel`.

Membership decides component-wise: `.check`/`.validate` ride a structural
`Σ x:A. Unit` kernelType (host-decidable without normalizing), with the
predicate decided at the concrete fst; `_kernel` exposes the real `El t`.

## `DepRecord`

Dependent record type built on nested Sigma.

Schema is an ordered list of `{ name; type; }` where `type` can be:

- A Type (static field)
- A function (`partial-record → Type`) for dependent fields

Isomorphic to nested Sigma types:

```
{ a : A, b : B(a) }              ≅  Σ(a:A).B(a)
{ a : A, b : B(a), c : C(a,b) }  ≅  Σ(a:A).Σ(b:B(a)).C(a,b)
```

Values are nested Sigma pairs:

```nix
{ fst = a; snd = { fst = b; snd = c; }; }
```

Inherits from Sigma: `.validate` (effectful), `.proj1`, `.proj2`,
`.pair`, `.pairE`, `.curry`, `.uncurry`.

Use `.pack` to convert flat attrset → nested Sigma value.
Use `.unpack` to convert nested Sigma value → flat attrset.

## `Pi`

Dependent function type `Π(x:A).B(x)`.

Arguments:

- `domain` — Type A
- `codomain` — A-value → Type (type family B indexed by domain values)
- `universe` — Universe level (explicit parameter — see below)
- `name` — optional display name

== Higher-order contract with algebraic effects ==

Pi is a HIGHER-ORDER CONTRACT (Findler & Felleisen 2002). Higher-order
contracts check function values differently from data values: a data
contract is verified immediately and completely, but a function contract
is verified incrementally at each application site. This is the
standard, correct strategy for function contracts — not a deficit.

The (Specification, Guard, Verifier) triple for Pi:

```
Guard (check):       builtins.isFunction — the immediate first-order
                     part of the contract. Soundly rejects non-functions.
Verifier (validate): effectful guard (auto-derived, 1 arg) — wraps
                     the guard in a typeCheck effect for blame tracking.
Elimination (checkAt): deferred contract check (2 args) — verifies a
                     specific application f(arg) by sending typeCheck
                     effects for both domain (arg : A) and codomain
                     (f(arg) : B(arg)).
```

This is precisely the Findler-Felleisen decomposition: the immediate
part (`isFunction`) is checked at introduction; the deferred part
(domain + codomain) is checked at each elimination site via `checkAt`.

== Adequacy ==

```
check f ⟺ all typeCheck effects in (validate f) pass
```

Both `check` and `validate` verify the introduction form (is it a function?).
`checkAt` verifies individual applications — the deferred contract.

== Universe level ==

Universe level is an explicit parameter. In MLTT, the level is computed
as `max(i, sup_{a:A} level(B(a)))` by inspecting the syntax of B.
For types with explicit kernelType, the kernel computes and verifies
levels via checkTypeLevel. The explicit universe parameter provides
the level for the surface API's `.universe` field.

== MLTT rule mapping ==

```
Formation:          Pi { domain, codomain, universe }
Introduction check: .check (guard: isFunction)
Introduction verify: .validate (effectful guard, auto-derived)
Elimination:        .apply (pure), .checkAt (effectful, deferred contract)
Computation:        β-reduction (Nix evaluation)
```

Operations:

- `.checkAt f arg` — deferred contract check at elimination site
- `.apply arg` — pure elimination: compute codomain type B(arg)
- `.compose f other` — compose Pi types (requires witness function)
- `.domain` — the domain type A
- `.codomain` — the type family B

## `Sigma`

Dependent pair type `Σ(x:A).B(x)`.

Arguments:

- `fst` — Type A (type of the first component)
- `snd` — A-value → Type (type family for the second component)
- `universe` — Universe level (explicit parameter)
- `name` — optional display name
- `kernelType` — optional explicit HOAS kernel form (see below)

Values are `{ fst; snd; }` where `fst : A` and `snd : B(fst)`.

== Kernel form: explicit vs. approximate ==

`snd : A-value → Type` lives at the Nix-meta level — it operates on
Nix values. The kernel form `H.sigma name fst._kernel (a: ...)`
needs a closure operating on **HOAS variables**, not Nix values.
The two categories disagree:

```
snd          : NixVal → Type        (surface, Nix-meta)
kernel snd   : HoasVar → HoasType   (kernel, HOAS-level)
```

For genuinely-dependent `snd` (e.g., `x: if x > 0 then Int else String`),
`snd` cannot be applied to an HOAS variable — the test on the variable
would crash. So the library does not attempt automatic derivation;
omitting `kernelType` produces `_kernel = H.any` with `approximate =
true`. Downstream consumers that take Sigma through `elaborateType`
recover the structure at the surface→kernel boundary; consumers that
use `_kernel` directly (kernel walkers, the generic `deriveCheck`
dispatcher) see `H.any`.

Pass `kernelType` explicitly when you need the kernel form to **be** a
Sigma — for example when piping the Type into another datatype
constructor whose kernel walker dispatches on `_htag == "sigma"`:

```nix
Prod = Sigma {
  fst = Int;
  snd = _: String;
  universe = 0;
  kernelType = H.sigma "x" Int._kernel (_: String._kernel);
};
```

For the non-dependent case (snd ignores its argument) the explicit
form is mechanical and could in principle be derived; the library
treats both cases uniformly to keep the dependent/non-dependent
distinction out of the surface API.

== First-order contract — guard is exact ==

Sigma is a FIRST-ORDER CONTRACT: both components are concrete data,
so the contract is checked immediately and completely. The guard
(`check`) IS full membership — there is no over-approximation.

```
Guard (check):    fst:A ∧ snd:B(fst) — exact. G = ⟦Σ(x:A).B(x)⟧.
Verifier (verify): decomposed effectful check — sends separate
                  typeCheck effects for fst and snd for blame tracking.
```

This contrasts with Pi where the guard over-approximates (`isFunction`)
because functions are higher-order. Sigma pairs are data — the
dependent relationship (snd's type depends on fst's value) can be
fully verified because both values are available.

Adequacy:

```
T.check v ⟺ all typeCheck effects in T.validate v pass
```

Under the all-pass handler. The guard is exact and the decomposed
verifier sends individual `typeCheck` effects per component — the all-pass
handler's boolean state tracks whether all passed. Totality: if the input
is structurally malformed (not an attrset, missing `fst`/`snd`), verify falls
back to a single `typeCheck` for the whole type — failure goes through the
effect system, never crashes Nix.

Universe level is an explicit parameter (computing
`sup_{a:A} snd(a).universe` requires evaluating the type family on
all domain values, same as Pi).

== MLTT rule mapping ==

```
Formation:    Sigma { fst, snd, universe }
Introduction: .check (exact guard), .validate (effectful, decomposed)
Elimination:  .proj1 (π₁), .proj2 (π₂)
Computation:  π₁(a,b) ≡ a, π₂(a,b) ≡ b
```

Operations:

- `.proj1 pair` — first projection π₁
- `.proj2 pair` — second projection π₂
- `.pair a b` — smart constructor (throws on invalid)
- `.validate v` — effectful: decomposed typeCheck effects for blame
- `.pairE a b` — effectful smart constructor
- `.pullback f g` — contravariant predicate pullback (see below)
- `.curry` / `.uncurry` — standard Sigma adjunction
- `.fstType` — the type A
- `.sndFamily` — the type family B

## `Vector`

Length-indexed list type family, built on Pi.

```
Vector(A) = Π(n:Nat).{xs : List(A) | |xs| = n}
```

This is the correct Martin-Löf encoding: Vector IS a Pi type.
It inherits `.validate` (effectful), `.compose`, `.apply`, `.domain`, `.codomain`
from Pi.

Usage:

```nix
Vector elemType           # the Pi type family (Nat → SizedList)
(Vector elemType).apply 3 # specific type for length 3
```

## `mkPropFamily`

Bundle a propositional `family` (`A → U`) with its `bridge` into one
handle for `Certified`'s general former. Pass it via the `family`
argument: `Certified { base; family = mkPropFamily { family; bridge; }; }`.
The two-argument `{ family; bridge; }` form remains valid.



#### Linear


Linear type constructors: structural guards for capability tokens.

Pure type predicates that check token structure without consuming.
Usage enforcement is in effects/linear.nix (separate concerns).

Linear(T)       — exactly one consume required
Affine(T)       — at most one consume (release allowed)
Graded(n, T)    — exactly n consumes (generalizes Linear/Affine)

See Orchard et al. (2019) for graded modal types.

## `Affine`

_Affine: structural type constructor for capability tokens that may be consumed at most once; identical shape to `Linear`, release is permitted._

```
Affine : Type -> Type
```

Affine type: capability token that may be consumed at most once.

Structurally identical to `Linear(T)`. The name communicates that the
resource may be explicitly released (dropped) via `effects/linear.release`
without consuming it — "at most once" vs Linear's "exactly once."

The structural guard is the same: both check for a valid capability
token with inner type T. The usage distinction (exactly-once vs
at-most-once) is enforced by the effect handler, not the type system.

Operations:

- `.check v` — pure guard: is v a valid affine token wrapping T?
- `.validate v` — effectful: sends `typeCheck` for blame tracking
- `.innerType` — the wrapped type T

## `Graded`

_Graded: structural type constructor for capability tokens with declared usage multiplicity; generalises Linear/Affine via the `maxUses` parameter._

```
Graded : { maxUses : Int | null, innerType : Type } -> Type
```

Graded type: capability token with usage multiplicity annotation.

Generalizes Linear and Affine via a `maxUses` parameter:

```nix
Graded { maxUses = 1; innerType = T; }    # ≡ Linear(T)
Graded { maxUses = null; innerType = T; }  # ≡ Unlimited(T)
Graded { maxUses = n; innerType = T; }     # ≡ Exact(n, T)
```

The structural guard is the same as Linear and Affine — token
structure with inner type check. The `maxUses` appears in the type
name for documentation but is NOT checked by the guard (the grade
lives in handler state, not the token).

The name uses ω for null (unlimited):
`Graded(1, Int)`, `Graded(5, String)`, `Graded(ω, Bool)`

From Orchard et al. (2019) "Quantitative Program Reasoning with
Graded Modal Types" — semiring-indexed usage annotations where
+ models branching, × models sequencing, 1 = linear, ω = unlimited.

Operations:

- `.check v` — pure guard: is v a valid graded token wrapping T?
- `.validate v` — effectful: sends `typeCheck` for blame tracking
- `.innerType` — the wrapped type T
- `.maxUses` — the declared usage multiplicity

## `Linear`

_Linear: structural type constructor for capability tokens that must be consumed exactly once; checks token shape, leaves usage tracking to the linear effect handler._

```
Linear : Type -> Type
```

Linear type: capability token that must be consumed exactly once.

Creates a type whose `check` verifies the capability token structure:

```nix
{ _linear = true, id = Int, resource = innerType }
```

Pure structural guard — checking does not consume the token.
`effects/linear.nix` tracks consumption separately.

Adequacy invariant:

```
Linear(T).check v ⟺ all typeCheck effects in Linear(T).validate v pass
```

Holds by construction via `mkType`'s auto-derived `validate`.

Operations:

- `.check v` — pure guard: is v a valid linear token wrapping T?
- `.validate v` — effectful: sends `typeCheck` for blame tracking
- `.innerType` — the wrapped type T



#### Universe


Universe hierarchy: Type_0 : Type_1 : Type_2 : ... Lazy infinite non-cumulative tower.

## `Type_0`

_Type_0: first universe in the non-cumulative tower._

Predefined `Type_0` universe.

## `Type_1`

_Type_1: second universe in the non-cumulative tower._

Predefined `Type_1` universe.

## `Type_2`

_Type_2: third universe in the non-cumulative tower._

Predefined `Type_2` universe.

## `Type_3`

_Type_3: fourth universe in the non-cumulative tower._

Predefined `Type_3` universe.

## `Type_4`

_Type_4: fifth universe in the non-cumulative tower._

Predefined `Type_4` universe.

## `level`

_level: read a type's universe level as an `Int`; level 0 covers atomic types, level 1 contains `Type_0`, and so on up the stratified tower. Throws (via `.universe`) when the type's level is term-dependent or level-polymorphic._

```
level : Type -> Int
```

Get the universe level of a type. Equivalent to `.universe` field
access; provided for explicit calls. Like `.universe`, it throws
rather than fabricating a level when the type's universe is
term-dependent or level-polymorphic (no ground `suc^n zero`).

## `lift`

_lift: raise a type by one universe — `lift t = liftTo (t.universe + 1) t`, preserving its values._

```
lift : Type -> Type
```

Raise a type by one universe level. `lift t = liftTo (t.universe + 1) t`. See `liftTo`.

## `liftTo`

_liftTo: explicit cross-level coercion — `liftTo m t` reindexes type `t` to universe `m` (require `m >= t.universe`), preserving its values; idempotent at `m == t.universe`, throws when `m` is below `t`'s level._

```
liftTo : Int -> Type -> Type
```

Reindex a type to a higher universe. `liftTo m t` has universe `m` and
accepts exactly the values `t` accepts (`check` is preserved); its
`_kernel` is the kernel `LiftAt` of `t`'s kernel type. Requires
`m >= t.universe`; idempotent at `m == t.universe`. The non-cumulative
tower has no implicit subsumption, so this is how a lower-level type
becomes a member of a higher universe.

## `typeAt`

_typeAt: factory producing the non-cumulative universe type `Type_n`; values of `Type_n` are types of universe exactly n; `Type_n` itself has universe `n+1`._

```
typeAt : Int -> Type
```

Create universe type at level n (non-cumulative). `Type_n` contains
exactly the types with universe `n` — a lower-level type is not subsumed,
use `lift`/`liftTo` for the explicit coercion. `Type_n` itself has
universe `n + 1`, enforcing `Type_n : Type_(n+1)` for all n and avoiding
Russell's paradox.



### Streams

#### Core


Stream primitives: done/more/fromList/iterate/range/replicate.

## `done`

_done: terminate a stream with a final value; produces a pure `Step` tagged `Done` carrying that value as the stream's result._

```
done : a -> Computation (Step a b)
```

Terminate a stream with a final value. Returns a pure Computation
whose `_tag` is `"Done"` and whose `value` is the supplied result.

## `fromList`

_fromList: convert a Nix list into a stream; emits each element as `More` and terminates with `Done null`._

```
fromList : [a] -> Computation (Step null a)
```

Create a stream from a list. The empty list collapses to `done null`.

## `iterate`

_iterate: build an infinite stream by repeated application: `[x, f x, f (f x), ...]`; must be paired with a limiting combinator to terminate._

```
iterate : (a -> a) -> a -> Computation (Step r a)
```

Create an infinite stream by repeated application:

```
iterate f x = [x, f(x), f(f(x)), ...]
```

Must be consumed with a limiting combinator (`take`, `takeWhile`).

## `more`

_more: yield one head element followed by a continuation stream; produces a pure `Step` tagged `More` with `head` and `tail` fields._

```
more : a -> Computation (Step r a) -> Computation (Step r a)
```

Yield an element and a continuation stream. The `tail` argument is
a Computation, so the rest of the stream stays lazy.

## `range`

_range: build a stream of integers from `start` inclusive to `end` exclusive; empty when `start >= end`._

```
range : Int -> Int -> Computation (Step null Int)
```

Create a stream of integers from `start` (inclusive) to `end`
(exclusive). Empty when `start >= end`.

## `replicate`

_replicate: build a stream of `n` copies of value `x`; empty when `n <= 0`, otherwise emits `n` `More` steps then `Done null`._

```
replicate : Int -> a -> Computation (Step null a)
```

Create a stream of `n` copies of a value. Empty when `n <= 0`.



#### Transform


Stream transformations: map, filter, scanl, flatMap.

## `filter`

_sfilter (exported as `filter`): keep only elements that satisfy the predicate; failing elements are dropped silently with no blame._

```
sfilter : (a -> Bool) -> Computation (Step r a) -> Computation (Step r a)
```

Keep only elements satisfying a predicate. Exposed as `filter` at
the module's top-level.

## `flatMap`

_flatMap: apply `f` returning a stream to each element and flatten via `concat`; expands one input element into zero or more outputs._

```
flatMap : (a -> Computation (Step r b)) -> Computation (Step r a) -> Computation (Step r b)
```

Apply a function that returns a stream to each element, then
flatten the resulting streams with `concat`.

## `map`

_smap (exported as `map`): map a function over each element of a stream; the structure of `More`/`Done` steps is preserved._

```
smap : (a -> b) -> Computation (Step r a) -> Computation (Step r b)
```

Map a function over each element of a stream. Exposed as `map` at
the module's top-level.

## `scanl`

_scanl: emit a running left-fold; for each input element, emit the accumulator before combining with the element to advance._

```
scanl : (b -> a -> b) -> b -> Computation (Step r a) -> Computation (Step r b)
```

Accumulate a running fold over the stream, yielding each
intermediate accumulator value.



#### Limit


Stream limiting: take, takeWhile, drop.

## `drop`

_drop: skip the first `n` elements and forward the remainder unchanged; non-positive `n` is a no-op._

```
drop : Int -> Computation (Step r a) -> Computation (Step r a)
```

Skip the first `n` elements of a stream. Non-positive `n` is a no-op.

## `take`

_take: yield at most the first `n` elements of a stream, then `Done null`; non-positive `n` yields the empty stream immediately._

```
take : Int -> Computation (Step r a) -> Computation (Step null a)
```

Take the first `n` elements of a stream. Non-positive `n` yields
the empty stream.

## `takeWhile`

_takeWhile: yield prefix elements while the predicate holds; terminates on the first element that fails the predicate._

```
takeWhile : (a -> Bool) -> Computation (Step r a) -> Computation (Step null a)
```

Take elements while a predicate holds. The first element that
fails the predicate is discarded along with everything after.



#### Combine


Stream combination: concat, interleave, zip, zipWith.

## `concat`

_concat: yield all elements of `s1`, then all elements of `s2`; if `s1` ends immediately we forward `s2` directly without rewrapping._

```
concat : Computation (Step r a) -> Computation (Step s a) -> Computation (Step s a)
```

Concatenate two streams: all elements of the first, then all of
the second. Sequential, not interleaved.

## `interleave`

_interleave: alternate elements between two streams; when the leading stream ends, the trailing stream takes over uninterrupted._

```
interleave : Computation (Step r a) -> Computation (Step s a) -> Computation (Step null a)
```

Interleave two streams: alternate elements from each. When one
stream ends the other continues to completion.

## `zip`

_zip: pair elements positionally into `{ fst, snd }` records; stops when either input stream ends._

```
zip : Computation (Step r a) -> Computation (Step s b) -> Computation (Step null { fst : a, snd : b })
```

Zip two streams into a stream of pairs. Stops when either stream ends.

## `zipWith`

_zipWith: pair elements positionally and combine each pair with `f`; stops when either input stream ends._

```
zipWith : (a -> b -> c) -> Computation (Step r a) -> Computation (Step s b) -> Computation (Step null c)
```

Zip two streams with a combining function. Stops when either stream ends.



#### Reduce


Stream reduction: fold, toList, length, sum, signal, signalOn, any, all.

## `all`

_all: return `true` if every element satisfies the predicate; short-circuits on first miss via lazy evaluation of the stream tail._

```
all : (a -> Bool) -> Computation (Step r a) -> Computation Bool
```

Check if all elements satisfy a predicate. Short-circuits on
first failing element.

## `any`

_any: return `true` if any element satisfies the predicate; short-circuits on first match via lazy evaluation of the stream tail._

```
any : (a -> Bool) -> Computation (Step r a) -> Computation Bool
```

Check if any element satisfies a predicate. Short-circuits on
first match — the rest of the stream is never forced.

## `fold`

_fold: left-fold a stream into a single value with initial accumulator `z`; the canonical terminal combinator other reducers delegate to._

```
fold : (b -> a -> b) -> b -> Computation (Step r a) -> Computation b
```

Left fold over a stream. Drains the stream, threading the
accumulator through `f` for each element.

## `length`

_length: count the number of elements in a stream; equivalent to `fold (n: _: n + 1) 0` over the stream's element steps._

```
length : Computation (Step r a) -> Computation Int
```

Count the number of elements in a stream.

## `signal`

_signal: emit `z` then forward only values not structurally equal to the previous emission; specialisation of `signalOn` over `==`._

```
signal : a -> Computation (Step r a) -> Computation (Step r a)
```

Return a stream that emits only when the incoming values change,
using structural equality to detect duplicates.
Equivalent to `signalOn z (x: y: x == y)`.

## `signalOn`

_signalOn: emit `z` then forward only values the comparator deems different from the previous emission; suppresses runs of equivalent inputs._

```
signalOn : a -> (a -> a -> Bool) -> Computation (Step r a) -> Computation (Step r a)
```

Return a stream that emits only when the incoming values change.
The comparator receives the current value and the next stream value;
if they compare equal, the next value is skipped.

The returned stream begins with the provided initial value `z`.

## `sum`

_sum: sum all numeric elements in a stream starting from 0; equivalent to `fold (acc: x: acc + x) 0`._

```
sum : Computation (Step r Number) -> Computation Number
```

Sum all numeric elements in a stream. Initial accumulator is `0`.

## `toList`

_toList: collect all stream elements into a list in emission order; equivalent to `fold (acc: x: acc ++ [x]) []`._

```
toList : Computation (Step r a) -> Computation [a]
```

Collect all stream elements into a list, preserving emission order.



### Type Checker

#### Term


Syntax of the kernel's term language. All 48 constructors produce
attrsets with a `tag` field (not `_tag`, to distinguish kernel terms
from effect system nodes). Binding is de Bruijn indexed: `mkVar i`
refers to the i-th enclosing binder (0 = innermost).

Name annotations (`name` parameter on `mkPi`, `mkLam`, `mkSigma`,
`mkLet`) are cosmetic — used only in error messages, never in
equality checking.

## Constructors

### Variables and Binding
- `mkVar : Int → Tm` — variable by de Bruijn index
- `mkLet : String → Tm → Tm → Tm → Tm` — `let name : type = val in body`
- `mkAnn : Tm → Tm → Tm` — type annotation `(term : type)`

### Functions
- `mkPi : String → Tm → Tm → Tm` — dependent function type `Π(name : domain). codomain`
- `mkLam : String → Tm → Tm → Tm` — lambda `λ(name : domain). body`
- `mkApp : Tm → Tm → Tm` — application `fn arg`

### Pairs
- `mkSigma : String → Tm → Tm → Tm` — dependent pair type `Σ(name : fst). snd`
- `mkPair : Tm → Tm → Tm` — pair constructor `(fst, snd)`
- `mkFst : Tm → Tm` — first projection
- `mkSnd : Tm → Tm` — second projection

### Inductive Types
- `mkUnit`, `mkTt` — unit type and value
- `mkBootSum`, `mkBootInl`, `mkBootInr`, `mkBootSumElim` — bootstrap coproduct for `descPlus`
- `mkBootEq`, `mkBootRefl`, `mkBootJ` — identity type with J eliminator

### Universes
- `mkU : (Int | Tm) → Tm` — universe `U(level)`. Accepts either a
  concrete Int (wrapped via `mkLevelLit`) or a Level-typed Tm
  directly.
- `mkLevelLit : Int → Tm` — builds `suc^n zero` as a Level term.

### Axiomatized Primitives
- `mkString`, `mkInt`, `mkFloat`, `mkAttrs`, `mkPath`, `mkDerivation`, `mkFunction`, `mkAny` — type formers
- `mkStringLit`, `mkIntLit`, `mkFloatLit`, `mkAttrsLit`, `mkPathLit`, `mkDerivationLit`, `mkFnLit`, `mkAnyLit` — literal values

## `funextTypeTm`

_funextTypeTm: pre-elaborated kernel term for the funext axiom's type `∀(j,k,A,B,f,g). (∀a. Eq (B a) (f a) (g a)) -> Eq (Π a:A. B a) f g`._

## `mkAbsurd`

_mkAbsurd: empty-type eliminator — `absurd P x` discharges a stuck `x : Empty` to produce a value of any type `P`; well-typed only when `x` is a neutral (Empty has no canonical inhabitants)._

```
mkAbsurd : Tm -> Tm -> Tm  -- type (P), term (x : Empty)
```

## `mkAllD`

_mkAllD: induction-hypothesis collector `All D X P i payload` — given motive `P : (i:I) -> X i -> U(k)`, threads `P` through every recursive child in the payload._

```
mkAllD : Tm -> Tm -> Tm -> Tm -> Tm -> Tm -> Tm -> Tm  -- k, I, D, level, X, P, i, payload
```

## `mkAnn`

_mkAnn: type annotation `(term : type)` — fixes the checking direction at the kernel level; consumed by `Sub` and elaboration._

```
mkAnn : Tm -> Tm -> Tm  -- term, type
```

## `mkAnnTrusted`

_mkAnnTrusted: type annotation marked as elaborator-trusted — `check` skips re-validation of `term` against `type` since elaboration has already proved well-typedness._

```
mkAnnTrusted : Tm -> Tm -> Tm  -- term, type
```

## `mkAnnTrustedWithDescRef`

_mkAnnTrustedWithDescRef: trusted annotation carrying a `_descRef` sidecar — used by the HOAS elaborator to retain levitated description provenance across eval/quote round-trips._

```
mkAnnTrustedWithDescRef : Tm -> Tm -> Any -> Tm  -- term, type, descRef
```

## `mkAnnTrustedWithLabels`

_mkAnnTrustedWithLabels: trusted annotation carrying `_label` / `_conLabel` sidecars — used by `H.withDescLabel` / `H.withConLabel` to surface presentation labels on `descView`._

```
mkAnnTrustedWithLabels : Tm -> Tm -> { label?, conLabel? } -> Tm
```

## `mkAny`

_mkAny: axiomatised top primitive type `Any` — accepts every Nix value; used as the lossy-fallback kernel for approximate types._

## `mkAnyLit`

_mkAnyLit: kernel literal for an arbitrary Nix value `v : Any` — used by approximate types whose kernel slot is `mkAny`._

```
mkAnyLit : Any -> Tm
```

## `mkApp`

_mkApp: function application `fn arg` — head `fn` is checked first to infer Π type, then `arg` is checked against the domain._

```
mkApp : Tm -> Tm -> Tm  -- fn, arg
```

## `mkAttrs`

_mkAttrs: axiomatised primitive type `Attrs` — type former at U(0) inhabited by any Nix attribute set, including `{}`._

## `mkAttrsLit`

_mkAttrsLit: kernel literal for a Nix attribute set `a : Attrs`; the attrs are carried opaquely (no per-field validation at the kernel level)._

```
mkAttrsLit : Attrs -> Tm
```

## `mkBootEq`

_mkBootEq: bootstrap identity type `Eq(A, a, b)` — propositional equality used by `descRet`'s level transport and by the J eliminator._

```
mkBootEq : Tm -> Tm -> Tm -> Tm  -- A, a, b
```

## `mkBootInl`

_mkBootInl: left-injection of `mkBootSum` — `inl(a) : A + B`; carries both `A` and `B` for elaboration shape recovery._

```
mkBootInl : Tm -> Tm -> Tm -> Tm  -- leftTy, rightTy, value
```

## `mkBootInr`

_mkBootInr: right-injection of `mkBootSum` — `inr(b) : A + B`; carries both `A` and `B` for elaboration shape recovery._

```
mkBootInr : Tm -> Tm -> Tm -> Tm  -- leftTy, rightTy, value
```

## `mkBootJ`

_mkBootJ: J eliminator on `mkBootEq` — transports a property `motive` along a proof of equality, yielding a term at the other endpoint._

```
mkBootJ : Tm -> Tm -> Tm -> Tm -> Tm -> Tm -> Tm  -- A, a, motive, identity, b, eq
```

## `mkBootRefl`

_mkBootRefl: bootstrap reflexivity `refl : Eq(A, a, a)` — the canonical inhabitant of every reflexive identity type; check-mode only at elaboration._

## `mkBootSum`

_mkBootSum: bootstrap coproduct type `A + B` — used by `descPlus` to encode sum-of-descriptions before generic sums become available._

```
mkBootSum : Tm -> Tm -> Tm  -- left, right
```

## `mkBootSumElim`

_mkBootSumElim: bootstrap sum eliminator — case-splits a `A + B` scrutinee through `onLeft`/`onRight` arms at motive `(_:A+B) -> Q _`._

```
mkBootSumElim : Tm -> Tm -> Tm -> Tm -> Tm -> Tm -> Tm  -- leftTy, rightTy, motive, onLeft, onRight, scrut
```

## `mkCanonApp`

_mkCanonApp: generic identity-tagged application — `canon-app id params body` evaluates by currying-applying `body` to `params` and stamps the result `VDescCon` with `_canonRef = { id; params; }`; conv/quote short-circuit on the canonical identity instead of forcing `.D`._

```
mkCanonApp : String -> [Tm] -> Tm -> Tm  -- id, params, body
```

## `mkDerivation`

_mkDerivation: axiomatised primitive type `Derivation` — type former at U(0) inhabited by Nix derivation values (attrsets with `type = "derivation"`); the irreducible Nix-store-producing value category._

## `mkDerivationLit`

_mkDerivationLit: kernel literal for a Nix derivation `d : Derivation`; the value is carried opaquely (kernel never inspects derivation attrs)._

```
mkDerivationLit : Derivation -> Tm
```

## `mkDesc`

_mkDesc: level-zero description type `Desc I k` at index sort `I : U(0)` and universe level `k` — the levitated algebra of constructors for datatypes._

```
mkDesc : Tm -> Tm -> Tm  -- k, I
```

## `mkDescAt`

_mkDescAt: `Desc^k I` carrying an explicit `iLev` for the universe of `I`. The kernel synthesises the desc-formation level as `U(suc (max k iLev))`._

```
mkDescAt : Tm -> Tm -> Tm -> Tm  -- iLev, k, I
```

## `mkDescCon`

_mkDescCon: constructor introduction for `μ I D i` — takes a payload typed by `interpD D (μ I D) i` and returns the corresponding `μ` value._

```
mkDescCon : Tm -> Tm -> Tm -> Tm  -- D, i, payload
```

## `mkDescConChain`

_mkDescConChain: flat-form linear-chain dual of an N-deep mkDescCon. `layers` is a flat outer-first Nix-list of `{ i; heads }` records; `base = { D; i; d }` at the terminator. The consumer pass-graph (evalF, conv, extract, quote) walks the list iteratively, so libnix `forceValueDeep` depth is O(1) regardless of N. Bijective dual of the chain-form Val (`_shape == "linearChain"`)._

```
mkDescConChain : { layers : [{i:Tm; heads:[Tm]}]; base : {D:Tm; i:Tm; d:Tm}; outerD : Tm; payloadTag : String; payloadLeft : Tm; payloadRight : Tm; } -> Tm
```

## `mkDescConWithCert`

_mkDescConWithCert: `mkDescCon` carrying a `Squash`-truncated guard certificate — threads a refinement guard's decision proof through the kernel for description-backed Record/Variant constructors (`descConCertified`)._

```
mkDescConWithCert : Tm -> Tm -> Tm -> Tm -> Tm  -- D, i, payload, cert
```

## `mkDescDescApp`

_mkDescDescApp: level-zero applied form of `descDesc` — `Desc^(suc L) ⊤` whose mu-fixpoint is `Desc^L I` for `I : U(0)`; bootstraps generic programming over descriptions themselves._

```
mkDescDescApp : Tm -> Tm -> Tm  -- I, L
```

## `mkDescDescAppAt`

_mkDescDescAppAt: applied form of `descDesc` carrying an explicit `ℓ` for the universe of `I` — generalised outer signature `λℓ:Level. λI:U(ℓ). λL:Level. Desc^(suc (max L ℓ)) ⊤`._

```
mkDescDescAppAt : Tm -> Tm -> Tm -> Tm  -- ℓ, I, L
```

## `mkDescInd`

_mkDescInd: levitated induction principle on `μ I D` — given a motive and step function, produces a generic recursor over the data described by `D`._

```
mkDescInd : Tm -> Tm -> Tm -> Tm -> Tm -> Tm  -- I, D, motive, step, scrut
```

## `mkEmpty`

_mkEmpty: empty type `Empty` — initial type at universe level 0; no constructors._

## `mkEverywhereD`

_mkEverywhereD: payload-traversal combinator over a description — applies a per-node `f` at every recursive position, producing a derived payload of the same shape._

```
mkEverywhereD : Tm -> Tm -> Tm -> Tm -> Tm -> Tm -> Tm -> Tm -> Tm
```

## `mkFloat`

_mkFloat: axiomatised primitive type `Float` — type former at U(0) inhabited by Nix floats (excludes integers)._

## `mkFloatLit`

_mkFloatLit: kernel literal for a Nix float `x : Float`._

```
mkFloatLit : Float -> Tm
```

## `mkFnLit`

_mkFnLit: kernel literal for an opaque Nix function `f : Function` — wraps the function in an `fnBox` for thunk-identity-preserving conversion._

```
mkFnLit : Function -> Tm
```

## `mkFst`

_mkFst: first-projection eliminator on a Σ-typed term — yields the dependent `fst` component; Σ-eta is exercised in `conv`._

```
mkFst : Tm -> Tm
```

## `mkFunction`

_mkFunction: axiomatised primitive type `Function` — type former at U(0) inhabited by opaque Nix-level functions wrapped via `mkOpaqueLam`._

## `mkFunext`

_mkFunext: function-extensionality axiom — given pointwise-equal `f`, `g` at every argument, produces an equality proof `Eq (Π a:A. B a) f g`._

```
mkFunext : Tm -> Tm -> Tm -> Tm -> Tm -> Tm  -- A, B, f, g, hypothesis
```

## `mkInt`

_mkInt: axiomatised primitive type `Int` — type former at U(0) inhabited by Nix integers (excludes floats)._

## `mkIntEq`

_mkIntEq: host `==` on `Int` literals `intEq a b : Bool` (parallel to `mkStrEq`)._

```
mkIntEq : Tm -> Tm -> Tm  -- a, b
```

## `mkIntLe`

_mkIntLe: host `<=` on `Int` literals `intLe a b : Bool` (parallel to `mkStrEq`). Non-symmetric — operand order preserved on a neutral spine._

```
mkIntLe : Tm -> Tm -> Tm  -- a, b
```

## `mkIntLit`

_mkIntLit: kernel literal for a Nix integer `n : Int`._

```
mkIntLit : Int -> Tm
```

## `mkInterpD`

_mkInterpD: interpret a description `D : Desc I k` against a recursive carrier `X : I -> U(k)` at index `i`, yielding the payload type `interpD D X i`._

```
mkInterpD : Tm -> Tm -> Tm -> Tm -> Tm  -- k, I, D, X, i
```

## `mkLam`

_mkLam: lambda abstraction `λ(name : domain). body` — domain annotation is optional at check time (overridden by expected Π's domain)._

```
mkLam : String -> Tm -> Tm -> Tm  -- name, domain, body
```

## `mkLet`

_mkLet: let-binding `let name : type = val in body` — `name` is cosmetic, the binder is introduced into body's de Bruijn context as index `0`._

```
mkLet : String -> Tm -> Tm -> Tm -> Tm  -- name, type, val, body
```

## `mkLevel`

_mkLevel: universe-level sort `Level : U(0)` — the type former whose inhabitants are level expressions used in `mkU`._

## `mkLevelLit`

_mkLevelLit: concrete Level literal from an `Int` — builds `suc^n zero` as a Level term; entry point for level-polymorphism-free code._

```
mkLevelLit : Int -> Tm
```

## `mkLevelMax`

_mkLevelMax: pointwise max of two levels `max(l, r) : Level` — used to compute the universe of `Σ` / `Π` types whose components inhabit distinct universes._

```
mkLevelMax : Tm -> Tm -> Tm  -- l, r
```

## `mkLevelSuc`

_mkLevelSuc: successor `suc(level) : Level` — increment a Level expression by one._

```
mkLevelSuc : Tm -> Tm
```

## `mkLevelZero`

_mkLevelZero: level-zero literal `0 : Level` — base case of `Level`'s inductive structure._

## `mkLift`

_mkLift: Tarski lift `LiftAt l m A : U(m)` with `l ≤ m` — non-cumulative cross-level transport of a type at level `l` into level `m`._

```
mkLift : Tm -> Tm -> Tm -> Tm  -- l, m, A
```

## `mkLiftElim`

_mkLiftElim: elimination of `Lift l m A` — lowers a lifted term back to its original level; the inverse pairing with `mkLiftIntro`._

```
mkLiftElim : Tm -> Tm -> Tm -> Tm -> Tm  -- l, m, A, x
```

## `mkLiftIntro`

_mkLiftIntro: introduction of `Lift l m A` — lifts a term `a : A` at level `l` to a term at level `m`; eq witness is auto-emitted via `mkBootRefl`._

```
mkLiftIntro : Tm -> Tm -> Tm -> Tm -> Tm  -- l, m, A, a
```

## `mkLitVal`

_mkLitVal: closed-Val splice — opaque Val carrier whose eval is identity on the carried value. O(1) Val→Tm reflection; sound iff val is closed._

```
mkLitVal : Val -> Tm
```

## `mkMu`

_mkMu: levitated fixpoint `μ I D i` — carrier type of values whose constructors are described by `D : Desc I k` at index `i`._

```
mkMu : Tm -> Tm -> Tm -> Tm  -- I, D, i
```

## `mkOpaqueLam`

_mkOpaqueLam: lambda over an opaque Nix function — kernel never inspects or applies it; `fnBox` thunk identity preserves conv reflexivity across eval/quote rounds._

```
mkOpaqueLam : FnBox -> Tm -> Tm  -- fnBox, piType
```

## `mkPair`

_mkPair: pair constructor `(fst, snd)` — both components are checked against the corresponding Σ slots at the expected type._

```
mkPair : Tm -> Tm -> Tm  -- fst, snd
```

## `mkPath`

_mkPath: axiomatised primitive type `Path` — type former at U(0) inhabited by Nix path values._

## `mkPathLit`

_mkPathLit: kernel literal for a Nix path `p : Path`._

```
mkPathLit : Path -> Tm
```

## `mkPi`

_mkPi: dependent function type `Π(name : domain). codomain` — `name` is cosmetic, the binder is introduced into codomain's de Bruijn context as index `0`._

```
mkPi : String -> Tm -> Tm -> Tm  -- name, domain, codomain
```

## `mkSigma`

_mkSigma: dependent pair type `Σ(name : fst). snd` — `name` is cosmetic, the binder is introduced into snd's de Bruijn context as index `0`._

```
mkSigma : String -> Tm -> Tm -> Tm  -- name, fst, snd
```

## `mkSnd`

_mkSnd: second-projection eliminator on a Σ-typed term — yields the `snd` component with `fst` substituted; Σ-eta is exercised in `conv`._

```
mkSnd : Tm -> Tm
```

## `mkSquash`

_mkSquash: propositional truncation `Squash A` — quotient of `A` collapsing all inhabitants to one, used for proof-irrelevant fields._

```
mkSquash : Tm -> Tm
```

## `mkSquashElim`

_mkSquashElim: eliminator for `Squash` restricted to `Squash`-typed motives — preserves proof irrelevance by forbidding motives that distinguish inhabitants._

```
mkSquashElim : Tm -> Tm -> Tm -> Tm -> Tm  -- A, motive, fn, scrut
```

## `mkSquashIntro`

_mkSquashIntro: introduction of `Squash A` — lifts any `a : A` to a single inhabitant of `Squash A`._

```
mkSquashIntro : Tm -> Tm
```

## `mkStrEq`

_mkStrEq: decidable equality on `String` literals `strEq a b : Bool` — used by indexed datatypes whose constructor selection branches on string keys._

```
mkStrEq : Tm -> Tm -> Tm  -- a, b
```

## `mkStrLen`

_mkStrLen: host string length `strLen s : Int` on a `String` literal; a stuck string operand keeps it neutral. Internalizes string-length refinements (e.g. non-emptiness)._

```
mkStrLen : Tm -> Tm  -- s
```

## `mkString`

_mkString: axiomatised primitive type `String` — type former at U(0) inhabited by Nix string values._

## `mkStringLit`

_mkStringLit: kernel literal for a Nix string `s : String`._

```
mkStringLit : String -> Tm
```

## `mkTt`

_mkTt: unit value `tt` — sole inhabitant of `mkUnit`; eta-converts every term of type `Unit` to itself._

## `mkU`

_mkU: universe type `U(level)` at the given level expression — accepts either a concrete `Int` (wrapped via `mkLevelLit`) or a Level-typed `Tm`._

```
mkU : (Int | Tm) -> Tm
```

## `mkUnit`

_mkUnit: unit type `Unit` — terminal type with single inhabitant `tt`; backs `fx.types.Unit` at universe level 0._

## `mkVar`

_mkVar: variable reference by de Bruijn index — `0` is the innermost binder; higher indices reach outer binders._

```
mkVar : Int -> Tm
```



#### Value


Values are the semantic domain produced by evaluation. They use
de Bruijn *levels* (counting outward from the top of the context),
not indices, which makes weakening trivial.

## Closures

`mkClosure : Env → Tm → Closure` — defunctionalized closure.
No Nix lambdas in the TCB; a closure is `{ env, body }` where
`body` is a kernel Tm evaluated by `eval.instantiate`.

## Value Constructors

Each `v*` constructor mirrors a term constructor:

- `vLam`, `vPi` — function values/types (carry name, domain, closure)
- `vSigma`, `vPair` — pair types/values
- `vUnit`, `vTt` — unit
- `vBootSum`, `vBootInl`, `vBootInr` — bootstrap coproduct values
- `vBootEq`, `vBootRefl` — identity values
- `vU` — universe values
- `vString`, `vInt`, `vFloat`, `vAttrs`, `vPath`, `vDerivation`, `vFunction`, `vAny` — primitive types
- `vStringLit`, `vIntLit`, `vFloatLit`, `vAttrsLit`, `vPathLit`, `vDerivationLit`, `vFnLit`, `vAnyLit` — primitive literals

## Neutrals

`vNe : Level → Spine → Val` — a stuck computation: a variable
(identified by de Bruijn level) applied to a spine of eliminators.

`freshVar : Depth → Val` — neutral with empty spine at the given depth.
Used during type-checking to introduce fresh variables under binders.

## Elimination Frames (Spine Entries)

- `eApp`, `eFst`, `eSnd` — function/pair eliminators
- `eBootSumElim`, `eBootJ` — inductive eliminators

## `eAbsurd`

_eAbsurd: elimination frame for `absurd` on a neutral `Empty`-typed scrutinee — carries the target type `P`; sound because `Empty` has no canonical inhabitants, so this frame can only arise on a stuck spine._

```
eAbsurd : Val -> SpineEntry  -- type P
```

## `eAllD`

_eAllD: elimination frame for `allD` on a neutral description — carries motive `P` plus shape parameters._

```
eAllD : Val -> Val -> Val -> Val -> Val -> Val -> SpineEntry
```

## `eApp`

_eApp: elimination frame for function application — pushes an argument onto a neutral spine._

```
eApp : Val -> SpineEntry
```

## `eBootJ`

_eBootJ: elimination frame for the J eliminator on a neutral identity proof — carries A, a, motive, refl-case, b._

```
eBootJ : Val -> Val -> Val -> Val -> Val -> SpineEntry
```

## `eBootSumElim`

_eBootSumElim: elimination frame for `bootSumElim` on a neutral sum scrutinee — carries motive and case arms._

```
eBootSumElim : Val -> Val -> Val -> Val -> Val -> SpineEntry
```

## `eDescInd`

_eDescInd: elimination frame for `descInd` on a neutral `μ`-typed scrutinee — carries `I`, `D`, motive, step._

```
eDescInd : Val -> Val -> Val -> Val -> SpineEntry
```

## `eEverywhereD`

_eEverywhereD: elimination frame for `everywhereD` on a neutral description — carries per-node `f` plus shape parameters._

```
eEverywhereD : Val -> Val -> Val -> Val -> Val -> Val -> Val -> SpineEntry
```

## `eFst`

_eFst: elimination frame for first-projection on a Σ neutral._

## `eIntEq`

_eIntEq: `intEq` frame on a neutral int operand — carries the other operand (symmetric)._

```
eIntEq : Val -> SpineEntry
```

## `eIntLeL`

_eIntLeL: `intLe` frame where the neutral operand is the lhs — carries the rhs._

```
eIntLeL : Val -> SpineEntry
```

## `eIntLeR`

_eIntLeR: `intLe` frame where the neutral operand is the rhs — carries the lhs._

```
eIntLeR : Val -> SpineEntry
```

## `eInterpD`

_eInterpD: elimination frame for `interpD` on a neutral description — carries `k`, `I`, `X`, `i` for completion when the neutral resolves._

```
eInterpD : Val -> Val -> Val -> Val -> SpineEntry
```

## `eLiftElim`

_eLiftElim: elimination frame for `liftElim` on a neutral `Lift l m A` — carries `l`, `m`, `A` for level lowering._

```
eLiftElim : Val -> Val -> Val -> SpineEntry
```

## `eSnd`

_eSnd: elimination frame for second-projection on a Σ neutral._

## `eSquashElim`

_eSquashElim: elimination frame for `squashElim` on a neutral `Squash`-typed scrutinee — carries motive shape (`A`, `B`) and case function `f`._

```
eSquashElim : Val -> Val -> Val -> SpineEntry
```

## `eStrEq`

_eStrEq: elimination frame for `strEq` on a neutral string operand — carries the other operand for completion when the neutral resolves._

```
eStrEq : Val -> Val -> SpineEntry
```

## `eStrLen`

_eStrLen: elimination frame for `strLen` on a neutral string operand — nullary; the stuck operand is the spine head, so the frame carries nothing._

```
eStrLen : SpineEntry
```

## `envCons`

_envCons: O(1) environment extension — prepend a value as index 0; no list copy, no cached field._

```
envCons : Val -> Env -> Env
```

## `envFromList`

_envFromList: normalize a Nix-list environment to cons cells (index 0 = list head); idempotent on cons (isList guard) so evaluator entry points normalize in O(1) on already-cons inputs._

```
envFromList : [Val] | Env -> Env
```

## `envLen`

_envLen: environment length (binder depth) via an iterative genericClosure spine walk — O(N) time, O(1) stack (overflow-free); no cached field, which would recurse N-deep at read or build._

```
envLen : Env -> Int
```

## `envNil`

_envNil: empty de Bruijn environment (the cons-cell nil)._

## `envNth`

_envNth: iterative de Bruijn lookup (foldl' over a range) — clears the C-stack and max-call-depth on deep environments; a plain Nix list is indexed verbatim (isList guard) so elaborate-layer list-contexts pass through unchanged._

```
envNth : Env -> Int -> Val
```

## `envPrepend`

_envPrepend: prepend a short Nix list of values (index 0 first) onto an environment._

```
envPrepend : [Val] -> Env -> Env
```

## `envToList`

_envToList: materialize a de Bruijn spine into an index-ordered Nix list (index 0 = most recent) via an iterative genericClosure walk — O(N) time, O(1) stack (overflow-free). For whole-context reads (`any`/`map`/`filter` over every binding); a plain Nix list passes through verbatim (isList guard), null yields the empty list. Inverse of envFromList on cons inputs._

```
envToList : Env -> [Val]
```

## `freshVar`

_freshVar: introduce a fresh neutral variable at the given depth — used during type-checking to bind a fresh witness under Π / Σ / let binders._

```
freshVar : Int -> Val  -- depth
```

## `mkClosure`

_mkClosure: defunctionalised closure `{ env, body }` — captures the evaluation environment and the kernel `Tm` body; instantiated by `eval.instantiate` without Nix lambdas in the TCB._

```
mkClosure : Env -> Tm -> Closure
```

## `vAllD`

_vAllD: value-domain induction-hypothesis collector — threads motive `P` through every recursive position in a payload._

```
vAllD : Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val
```

## `vAny`

_vAny: value-domain axiomatised top primitive `Any : U(0)` — accepts every Nix value._

## `vAnyLit`

_vAnyLit: value-domain literal carrying an arbitrary Nix value `v : Any` — used by approximate types whose kernel slot is `vAny`._

```
vAnyLit : Any -> Val
```

## `vAttrs`

_vAttrs: value-domain axiomatised primitive `Attrs : U(0)` — inhabited by any Nix attrset._

## `vAttrsLit`

_vAttrsLit: value-domain literal carrying an opaque Nix attrset `a : Attrs`._

```
vAttrsLit : Attrs -> Val
```

## `vBootEq`

_vBootEq: value-domain bootstrap identity type `Eq(A, a, b)` — propositional equality used by `descRet`'s level transport and by the J eliminator._

```
vBootEq : Val -> Val -> Val -> Val  -- A, a, b
```

## `vBootInl`

_vBootInl: value-domain left-injection `inl(a) : A + B` — carries `leftTy` and `rightTy` for elaboration shape recovery._

```
vBootInl : Val -> Val -> Val -> Val  -- leftTy, rightTy, value
```

## `vBootInr`

_vBootInr: value-domain right-injection `inr(b) : A + B` — carries `leftTy` and `rightTy` for elaboration shape recovery._

```
vBootInr : Val -> Val -> Val -> Val  -- leftTy, rightTy, value
```

## `vBootRefl`

_vBootRefl: value-domain reflexivity `refl : Eq(A, a, a)` — canonical inhabitant of every reflexive identity; conv collapses all proofs of refl to this._

## `vBootSum`

_vBootSum: value-domain bootstrap coproduct type `A + B` — used by `descPlus`'s sum-of-descriptions before generic sums become available._

```
vBootSum : Val -> Val -> Val
```

## `vDerivation`

_vDerivation: value-domain axiomatised primitive `Derivation : U(0)` — Nix derivation values; the store-producing irreducible value category._

## `vDerivationLit`

_vDerivationLit: value-domain literal carrying a Nix derivation `d : Derivation` opaquely._

```
vDerivationLit : Derivation -> Val
```

## `vDesc`

_vDesc: value-domain level-zero description type `Desc I k` at index sort `I : U(0)` and universe level `k`._

```
vDesc : Val -> Val -> Val  -- level, I
```

## `vDescAt`

_vDescAt: value-domain `Desc^k I` carrying an explicit `iLev` for the universe of `I`. The conv unfolding rule reads `iLev` to construct the expected `mkDescDescAppV` D-slot._

```
vDescAt : Val -> Val -> Val -> Val  -- level, iLev, I
```

## `vDescCon`

_vDescCon: value-domain constructor `descCon(D, i, payload)` — the canonical introducer for `μ I D i` values._

```
vDescCon : Val -> Val -> Val -> Val  -- D, i, payload
```

## `vDescConChain`

_vDescConChain: flat-chain VDescCon for linearChain Descs. `.d` is stub `vTt`; chain lives in `_layers` (Nix list, outer-first) + `_base`. Chain-wide BootSum wrapper info on `_payloadTag`/`_payloadLeft`/`_payloadRight`. Outer cert is `_layers[0].cert`. O(1) libnix stack on deep force; non-chain-aware consumers crash on `.d.fst` rather than silently mis-reading a degenerate view._

```
vDescConChain : Val -> Val -> String -> Val -> Val -> [LayerRec] -> Val -> Val  -- D, i, payloadTag, payloadLeft, payloadRight, layers, base
```

## `vDescConTagged`

_vDescConTagged: value-domain `descCon` stamped with a canonical-reference identity `_canonRef = { id; params }` for conv and quote short-circuiting; skips forcing `.D` on known descriptions, breaking universe-level descent loops. Carries no proof or certificate — `_canonRef` is a conv/quote identity tag only._

```
vDescConTagged : Val -> Val -> Val -> Val -> Val  -- D, i, payload, _canonRef
```

## `vEmpty`

_vEmpty: value-domain empty type — initial type with no inhabitants; conv-equal in one step by tag identity._

## `vEverywhereD`

_vEverywhereD: value-domain payload-traversal combinator — applies per-node `f` at every recursive position, producing a same-shape derived payload._

```
vEverywhereD : Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val
```

## `vFloat`

_vFloat: value-domain axiomatised primitive `Float : U(0)`._

## `vFloatLit`

_vFloatLit: value-domain literal carrying a Nix float `x : Float`._

```
vFloatLit : Float -> Val
```

## `vFnLit`

_vFnLit: value-domain literal carrying an opaque Nix function — `fnBox` preserves thunk identity for conv reflexivity._

```
vFnLit : FnBox -> Val
```

## `vFunction`

_vFunction: value-domain axiomatised primitive `Function : U(0)` — opaque-function carrier._

## `vFunext`

_vFunext: value-domain funext axiom — given pointwise equality, produces equality of functions at `Π(a:A). B a`._

```
vFunext : Val -> Val -> Val -> Val -> Val -> Val
```

## `vInt`

_vInt: value-domain axiomatised primitive `Int : U(0)`._

## `vIntLit`

_vIntLit: value-domain literal carrying a Nix integer `n : Int`._

```
vIntLit : Int -> Val
```

## `vInterpD`

_vInterpD: value-domain interpretation `interpD D X i` — yields the payload type for a constructor described by `D` against carrier `X`._

```
vInterpD : Val -> Val -> Val -> Val -> Val -> Val  -- k, I, D, X, i
```

## `vLam`

_vLam: value-domain lambda `λ(name : domain). body` — carries a defunctionalised closure rather than a Nix function, keeping the TCB Nix-lambda-free._

```
vLam : String -> Val -> Closure -> Val
```

## `vLazyDescIndAccLayer`

_vLazyDescIndAccLayer: MACHINE-INTERNAL deferred accumulator layer of a `descInd` linear chain. Applying expands via four kAppVV frames (step i d (vPair prevAcc vTt) arg); never escapes `runMachineAtF`._

```
vLazyDescIndAccLayer : Val -> Val -> Val -> Val -> Val  -- step, i, d, prevAcc
```

## `vLevel`

_vLevel: value-domain Level type `Level : U(0)`._

## `vLevelLit`

_vLevelLit: value-domain concrete Level literal `n : Level` — derived from a Nix integer at evaluation time._

```
vLevelLit : Int -> Val
```

## `vLevelMax`

_vLevelMax: value-domain pointwise max `max(l, r) : Level` — used for universes of dependent products / pairs across distinct levels._

```
vLevelMax : Val -> Val -> Val  -- l, r
```

## `vLevelSuc`

_vLevelSuc: value-domain successor of a Level expression `suc(l) : Level`._

```
vLevelSuc : Val -> Val
```

## `vLevelZero`

_vLevelZero: value-domain level-zero literal `0 : Level`._

## `vLift`

_vLift: value-domain Tarski lift `Lift l m A` — non-cumulative cross-level transport of type `A : U(l)` into `U(m)` with `l ≤ m`._

```
vLift : Val -> Val -> Val -> Val  -- l, m, A
```

## `vLiftIntro`

_vLiftIntro: value-domain introduction of `Lift l m A` — lifts a term `a : A` at level `l` to a term at level `m`._

```
vLiftIntro : Val -> Val -> Val -> Val -> Val  -- l, m, A, a
```

## `vMu`

_vMu: value-domain levitated fixpoint `μ I D i` — carrier type of values whose constructors are described by `D` at index `i`._

```
vMu : Val -> Val -> Val -> Val  -- I, D, i
```

## `vNe`

_vNe: neutral value — stuck computation `var^lvl <spine>`; head is a de Bruijn level, spine is a list of elimination frames awaiting reduction._

```
vNe : Int -> Spine -> Val  -- level, spine
```

## `vNeSnoc`

_vNeSnoc: O(1) neutral-spine extension — append one elimination frame via the skew-binary RAL backing `_ral`, keeping `.spine` a materialized in-order list. Use in place of `vNe lvl (n.spine ++ [frame])` to avoid the O(N²)/overflow-prone Nix-list snoc._

```
vNeSnoc : Val -> SpineEntry -> Val  -- neutral, frame
```

## `vOpaqueLam`

_vOpaqueLam: value-domain opaque lambda over a Nix function — kernel never inspects it; `fnBox` thunk identity preserves conv reflexivity._

```
vOpaqueLam : FnBox -> Val -> Val  -- fnBox, piType
```

## `vPair`

_vPair: value-domain pair `(fst, snd)` — components held in WHNF, projected by `eFst` / `eSnd` spine frames._

```
vPair : Val -> Val -> Val
```

## `vPath`

_vPath: value-domain axiomatised primitive `Path : U(0)`._

## `vPathLit`

_vPathLit: value-domain literal carrying a Nix path `p : Path`._

```
vPathLit : Path -> Val
```

## `vPi`

_vPi: value-domain dependent function type `Π(name : domain). codomain` — carries a closure for the codomain to permit semantic substitution._

```
vPi : String -> Val -> Closure -> Val
```

## `vSigma`

_vSigma: value-domain dependent pair type `Σ(name : fst). snd` — carries a closure for the snd component to permit semantic substitution._

```
vSigma : String -> Val -> Closure -> Val
```

## `vSquash`

_vSquash: value-domain propositional truncation `Squash A` — quotient of `A` collapsing all inhabitants to one for proof-irrelevant fields._

```
vSquash : Val -> Val
```

## `vSquashIntro`

_vSquashIntro: value-domain introduction of `Squash A` — lifts any inhabitant of `A` to the sole inhabitant of `Squash A`._

```
vSquashIntro : Val -> Val
```

## `vString`

_vString: value-domain axiomatised primitive `String : U(0)`._

## `vStringLit`

_vStringLit: value-domain literal carrying a Nix string `s : String`._

```
vStringLit : String -> Val
```

## `vThunkTm`

_vThunkTm: MACHINE-INTERNAL deferred-Tm Val produced by `ev` on non-atomic Tms. Captures `{ env; tm }`; the driver's `Done` handler forces top-level VThunkTm before returning, so external code observes it only in stored sub-Val fields._

```
vThunkTm : Env -> Tm -> Val
```

## `vTt`

_vTt: value-domain unit value `tt` — sole inhabitant of `vUnit`; conv collapses all Unit-typed values to this._

## `vU`

_vU: value-domain universe `U(level)` — the type of types at a given Level value._

```
vU : Val -> Val
```

## `vUnit`

_vUnit: value-domain unit type — terminal type with single inhabitant `vTt`; eta-converted in `conv`._



#### Quote


Converts values back to terms, translating de Bruijn levels to
indices. Pure function — part of the TCB.

## Core Functions

- `quote : Depth → Val → Tm` — read back a value at binding depth d.
  Level-to-index conversion: `index = depth - level - 1`.
- `quoteSp : Depth → Tm → Spine → Tm` — quote a spine of eliminators
  applied to a head term (folds left over the spine).
- `quoteElim : Depth → Tm → Elim → Tm` — quote a single elimination
  frame applied to a head term.
- `nf : Env → Tm → Tm` — normalize: `eval` then `quote`. Useful for
  testing roundtrip idempotency (`nf env (nf env tm) == nf env tm`).
- `lvl2Ix : Depth → Level → Index` — level-to-index helper.

## Trampolining

Linear VDescCon chains are quoted iteratively via `genericClosure`
for O(1) stack depth on deep generated data (5000+ elements).

## Binder Quotation

For VPi, VLam, VSigma: instantiates the closure with a fresh
variable at the current depth, then quotes the body at `depth + 1`.

## `lvl2Ix`

_lvl2Ix: convert a de Bruijn level to an index at binding `depth` — `index = depth - level - 1`; helper exposed for downstream tooling that interleaves with quotation._

```
lvl2Ix : Depth -> Level -> Index
```

## `nf`

_nf: normalise a term to its canonical form by `eval` then `quote` — useful for testing round-trip idempotency (`nf env (nf env tm) == nf env tm`)._

```
nf : Env -> Tm -> Tm
```

## `quote`

_quote: read-back a value `Val` to a term `Tm` at binding `depth` — translates de Bruijn levels to indices via `index = depth - level - 1`. Pure TCB function._

```
quote : Depth -> Val -> Tm
```

## `quoteElim`

_quoteElim: quote a single elimination frame applied to a head term — dispatches on frame tag, recursively quoting each carried argument._

```
quoteElim : Depth -> Tm -> Elim -> Tm
```

## `quoteSp`

_quoteSp: quote a spine of elimination frames applied to a head term — folds left over the spine, calling `quoteElim` at each step._

```
quoteSp : Depth -> Tm -> Spine -> Tm
```



#### Conv


Checks whether two values are definitionally equal at a given
binding depth. Purely structural — no type information used, no
eta expansion. Pure function — part of the TCB.

## Core Functions

- `conv : Depth → Val → Val → Bool` — check definitional equality.
- `convSp : Depth → Spine → Spine → Bool` — check spine equality
  (same length, pairwise `convElim`).
- `convElim : Depth → Elim → Elim → Bool` — check elimination frame
  equality (same tag, recursively conv on carried values).

## Conversion Rules

- **Structural**: same-constructor values with matching fields.
  Universe levels compared by `==`. Primitive literals by value.
- **Binding forms**: Pi, Lam, Sigma compared under a fresh
  variable at depth d (instantiate both closures, compare at d+1).
- **Compound values**: recursive on all components.
- **Neutrals**: same head level and convertible spines.
- **Catch-all**: different constructors → false.

## Trampolining

Deep ordinary data is represented by generated `VDescCon` values.
Conversion stays structural except for explicitly documented
eta/unfolding rules.

## No Eta

`conv` does not perform eta expansion: a neutral `f` and
`λx. f(x)` are **not** definitionally equal. Cumulativity
(`U(i) ≤ U(j)`) is handled in check.nix, not here.

## `admitLevel`

_admitLevel: is a Level term-independent? — every `normLevel` summand rests on a `zero` or empty-spine `var` base; the shared predicate behind every universe-level soundness gate. Rejects applied-neutral bases, admits level variables._

```
admitLevel : Val -> Bool
```

## `cPeelArm`

_cPeelArm: deep-arm classifier for `cPeel` — peels VNe spines and VMu/VDesc/VBootEq towers onto the machine frontier via the shared `elimGoals` decomposition. Returns a layer record or null._

```
cPeelArm : Depth -> Val -> Val -> ({ kind; goals; na; nb; nd; } | null)
```

## `cPeelBinder`

_cPeelBinder: binder-arm classifier for `cPeel` — mirrors convStep's VPi/VLam/eta/VSigma arms (and the preceding Lift-collapse guard) so binder layers peel flat. Returns a layer record or null._

```
cPeelBinder : Depth -> Val -> Val -> ({ kind; goals; na; nb; nd; } | null)
```

## `conv`

_conv: definitional equality on values at binding `depth` — purely structural with Σ/Unit/Π-eta; foundation of `Sub` in `check` and the kernel TCB._

```
conv : Depth -> Val -> Val -> Bool
```

## `convElim`

_convElim: elimination-frame equality at binding `depth` — same tag and recursively `conv` on every carried value; building block of `convSp`._

```
convElim : Depth -> Elim -> Elim -> Bool
```

## `convLevel`

_convLevel: definitional equality on Level expressions — `normLevel` both sides, then structural compare; required because `convLevel` is non-trivial under `levelMax` associativity._

```
convLevel : Val -> Val -> Bool
```

## `convSp`

_convSp: spine equality at binding `depth` — same length plus pairwise `convElim` on each frame; used to compare two neutral-value spines._

```
convSp : Depth -> Spine -> Spine -> Bool
```

## `convStep`

_convStep: single conversion step over forced values — the conv dispatch body, called by the `runConvF` machine for non-structural goals._

```
convStep : Depth -> Val -> Val -> Bool
```

## `normLevel`

_normLevel: normalise a Level expression to canonical form — `levelMax`/`levelSuc` collapsed via the algebraic laws so two equivalent forms compare equal under `convLevel`._

```
normLevel : Val -> Val
```



#### Eval


Pure evaluator: interprets kernel terms in an environment of
values. Zero effect system imports — part of the trusted computing
base (TCB).

## Core Functions

- `eval : Env → Tm → Val` — evaluate with default fuel (10M steps)
- `evalF : Int → Env → Tm → Val` — evaluate with explicit fuel budget
- `instantiate : Closure → Val → Val` — apply a closure to an argument

## Elimination Helpers

- `vApp : Val → Val → Val` — apply a function value (beta-reduces VLam, extends spine for VNe)
- `vFst`, `vSnd` — pair projections
- `vBootSumElim` — sum elimination
- `vBootJ` — identity elimination (computes to base on VBootRefl)

## Trampolining

Generated `desc-con` chains use `builtins.genericClosure` to flatten
recursive structures iteratively, guaranteeing O(1) stack depth on
deep generated recursive data.

## Fuel Mechanism

Each `evalF` call decrements a fuel counter. When fuel reaches 0,
evaluation throws `"normalization budget exceeded"`. This bounds
total work and prevents unbounded computation in the Nix evaluator.
Default budget: 10,000,000 steps.

## `descView`

_descView: default-fuel one-step semantic view of a description value — return `{ tag = "DView{Ret,Arg,Rec,Pi,Plus}"; idx; ...payload }` selecting the description's outer constructor._

```
descView : Val -> { tag : DViewTag; idx : Int; ... } | null
```

Dispatches on both primitive `VDescX` shapes and encoded
`VDescCon` shapes uniformly. The `idx` field gives the summand
position (`0` = ret, `1` = arg, `2` = rec, `3` = pi, `4` = plus).
Primary consumer is `check.nix`'s `desc-con` trampoline, which
uses the view to detect plus-coproduct shapes with linear
recursion. Returns `null` for `VNe` or values whose `_canonRef`
is opaque.

## `eval`

_eval: default-fuel wrapper around `evalF`; spends from the `defaultFuel` (10M-step) budget. The canonical evaluator entry for kernel consumers._

```
eval : Env -> Tm -> Val
```

## `evalF`

_evalF: kernel-term evaluator. Routes through the depth-budgeted hybrid in `tc/eval/direct.nix`: direct `mkValueF` recursion for shallow structural terms, the CEK machine (`tc/eval/machine.nix`) at budget exhaustion and for the tags that must see machine-internal Val tags (notably `VLazyDescIndAccLayer`). `mkValueF` remains exported for overlays (notably `tc/elaborate/eval-overlay.nix`) that compose their own self-table with VMeta-aware dispatch._

```
evalF : Int -> Env -> Tm -> Val
```

## `instantiate`

_instantiate: default-fuel closure application — given `Closure { env; body; }` and an argument `Val`, evaluate the body in the extended environment._

```
instantiate : Closure -> Val -> Val
```

## `linearProfile`

_linearProfile: default-fuel linear-recursion classifier — given a description value `D`, return a list of pre-rec field types if `D` is a `descArg`-chain ending in `descRec descRet`; `null` if `D` is non-linear (tree, multi-rec, or non-plus)._

```
linearProfile : Val -> [{ S : Val; ... }] | null
```

Walks the `descArg`/`descRec` chain via `descView`; succeeds
when every pre-rec field is `descArg` and the tail is exactly
`descRec descRet`. Used by `check.nix`'s `desc-con` trampoline
to detect when a plus-coproduct `A + B` has exactly one
linear-recursive summand — the case where chain peeling
applies and 5000+ layers can be checked without recursion.

## `machine`

_fx.tc.eval.machine: CEK abstract machine. `runMachineF` is the defunctionalized form of `evalF`; `runQuoteF` is the symmetric read-back driver consumed by `tc/quote.nix`._

## `mkDescDescAppV`

_mkDescDescAppV: default-fuel canonical `descDesc iLev I L`-value constructor — produces the levitated description-of-descriptions value, cached and shared across the kernel for index `I` at universe `iLev` and level `L`._

```
mkDescDescAppV : Val -> Val -> Val -> Val  -- iLev, I, L
```

## `mkValueF`

_mkValueF: dispatch-algebra-parameterized core evaluator body. Kernel instantiates `mkValueF self`; overlays (notably `tc/elaborate/eval-overlay.nix`) instantiate with their own self-table to thread VMeta-aware dispatch through closure bodies, preserving kernel-purity (Abel-Pientka 2011, section 2; see `tc/elaborate/value.nix:13-17`)._

```
mkValueF : Self -> Int -> Env -> Tm -> Val
```

## `sumPayloadTmView`

_sumPayloadTmView: term-level sum-payload view — given a `Tm` that is `boot-inl`/`boot-inr` or a sum-shaped `desc-con` with `_descConCert`, return `{ side; value; rebuild; rebuildVal; }` to drive the `desc-con` trampoline's payload walker; `null` for non-sum shapes._

```
sumPayloadTmView : Tm -> { side : "inl" | "inr"; value : Tm; rebuild : Tm -> Tm; rebuildVal : (Tm -> Val) -> Val -> Val; } | null
```

## `sumPayloadValView`

_sumPayloadValView: value-level sum-payload view — given a `Val` that is `VBootInl`/`VBootInr` or a sum-shaped `VDescCon` with `_descRef`, return `{ side; value; rebuild; }` for use in the `desc-con` trampoline; `null` for non-sum shapes._

```
sumPayloadValView : Val -> { side : "inl" | "inr"; value : Val; rebuild : Val -> Val; } | null
```

## `vAllD`

_vAllD: default-fuel `allD L I D K X M i d` — the type expressing that every recursive position in description-payload `d` (at index `i`) satisfies motive `M`._

```
vAllD : Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val
```

## `vApp`

_vApp: default-fuel kernel function-application value — beta-reduces `VLam`, extends the spine for `VNe`, threads through `VDescViewFn`._

```
vApp : Val -> Val -> Val
```

## `vBootJ`

_vBootJ: J-eliminator over `VBootEq` — on `VBootRefl` returns the base case (checker has already verified the sides match); on `VNe` extends the spine with an `eBootJ` frame._

```
vBootJ : Val -> Val -> Val -> Val -> Val -> Val -> Val
```

Arguments are `type lhs motive base rhs eq`. When `eq` is
`VBootRefl`, returns `base` directly — the checker has already
verified `lhs ≡ rhs`, so `rhs` is unused. When `eq` is `VNe`,
preserves `rhs` in the `EBootJ` spine frame so quotation can
reconstruct the stuck term. Any other shape is rejected with
an internal error.

## `vBootSumElim`

_vBootSumElim: default-fuel boot-sum eliminator — dispatches `VBootInl` to `onLeft` and `VBootInr` to `onRight`; extends the spine on `VNe`._

```
vBootSumElim : Val -> Val -> Val -> Val -> Val -> Val -> Val
```

## `vDescInd`

_vDescInd: default-fuel generic eliminator for description-based indexed inductives — `ind D P step i (con d) = step i d (everywhere D D P (lam j x. ind D P step j x) i d)`._

```
vDescInd : Val -> Val -> Val -> Val -> Val -> Val
```

Arguments: description `D`, motive `P : (i:I) -> mu D i -> U`,
step function `step`, target index `i`, scrutinee
(a `VDescCon` or `VNe`). On `VDescCon`, builds the inductive
hypothesis as a self-reference closure over `step`/`motive`/`D`/`I`,
feeds the canonical `mu D` family to `vEverywhereDF`, and
applies `step i d (everywhereResult)`. On `VNe`, extends the
spine with `eDescInd D motive step i`. The motive must be a
`VLam` so `I` is recoverable from its domain annotation.

## `vEverywhereD`

_vEverywhereD: default-fuel `everywhereD L I D K X M ih i d` — apply inductive hypothesis `ih` at every recursive position of `d`, producing the `allD` witness consumed by `vDescInd`._

```
vEverywhereD : Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val
```

## `vFst`

_vFst: kernel pair-projection — return the first component of a `VPair`; extend the spine with `eFst` on a stuck `VNe`. Forces a deferred `VThunkTm` first (the VThunkTm read-site invariant), as `vAppF` does, so the direct evaluator opening a machine-built closure env never reads a thunk's `.tag`._

```
vFst : Val -> Val
```

## `vInterpD`

_vInterpD: default-fuel description interpretation — given `L_val I_val D X i`, compute the type `interp I D X i` whose values are layers of the recursive datatype determined by `D`._

```
vInterpD : Val -> Val -> Val -> Val -> Val -> Val
```

## `vLiftElimF`

_vLiftElimF: kernel `lower` eliminator — idempotent at `convLevel l m`; β-reduces `lower _ (lift _ a) -> a` on `VLiftIntro`; appends `ELiftElim` to a stuck `VNe` spine._

```
vLiftElimF : Val -> Val -> Val -> Val -> Val -> Val
```

## `vLiftF`

_vLiftF: kernel `Lift l m eq A` type-former value — the type of values of `A : U(l)` transported up to `U(m)`; collapses idempotently when `convLevel l m` and composes nested Lifts._

```
vLiftF : Val -> Val -> Val -> Val -> Val
```

Idempotence: `Lift l l _ A ≡ A` for homogeneous code — returns
`A` directly when `convLevel l m`.
Composition: `Lift l m _ (Lift l' l _ A') ≡ Lift l' m _ A'` —
flattens by lowering the inner level. The witness slot `eq`
is irrelevant on collapse since both bound conditions hold by
transitivity; emit `vBootRefl` for the composed form.

## `vLiftIntroF`

_vLiftIntroF: kernel `liftIntro` value former — wraps `a : A` as a `VLift l m _ A`-typed value; idempotent at `convLevel l m`, and η-reduces a stuck `lower`-spine via `lift _ (lower _ x) ≡ x`._

```
vLiftIntroF : Val -> Val -> Val -> Val -> Val -> Val
```

Witness-irrelevance is enforced structurally: levels are
compared via `convLevel` and the carried `A` via syntactic
equality. The spine's `eq` field is not consulted. The
η-reduction inspects the tail of a `VNe` spine for an
`ELiftElim` frame whose parameters match; on hit, drops the
frame to yield the inner stuck term.

## `vSnd`

_vSnd: kernel pair-projection — return the second component of a `VPair`; extend the spine with `eSnd` on a stuck `VNe`. Forces a deferred `VThunkTm` first (the VThunkTm read-site invariant), as `vAppF` does, so the direct evaluator opening a machine-built closure env never reads a thunk's `.tag`._

```
vSnd : Val -> Val
```

## Sub-namespaces

- [`_internal`](/nix-effects/type-checker/eval/_internal)
- [`dispatch`](/nix-effects/type-checker/eval/dispatch)

## Source

- [`src/tc/eval/core.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/eval/core.nix)
- [`src/tc/eval/desc.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/eval/desc.nix)
- [`src/tc/eval/direct.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/eval/direct.nix)
- [`src/tc/eval/machine.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/eval/machine.nix)



#### _internal


fx.tc.eval._internal: cross-part evaluator helpers reachable from sibling parts via the self-fixpoint; not part of the stable consumer surface.

## `mkCanonAppVF`

_mkCanonAppVF: value-level constructor for `canon-app id params body`-as-tagged-`VDescCon` — currying-applies `body` to `params` and stamps the result with `_canonRef = { id; params; body; }` so conv/quote short-circuit on the canonical identity instead of forcing `.D`._

```
mkCanonAppVF : Int -> String -> [Val] -> Val -> Val
```

Generic counterpart of `mkDescDescAppVF` for user-registered
canonical descriptions. `bodyVal` is expected to be a curried
chain of `VLam`s that, after applying every element of
`paramVals`, yields a `VDescCon`. The raw result's `.D`/`.i`/`.d`
fields are reused; the `_canonRef` stamp takes precedence in
conv and quote so the recursive `.D` slot is never forced.

`bodyVal` is preserved on the stamp so `quote` can emit
`T.mkCanonApp id params body`. `canonRefConv` compares stamps
by `(id, params)` only; `body` is conv-irrelevant.

Throws if the curried application does not produce a
`VDescCon` — the smart-form's static contract.

## `mkDescDescAppVF`

_mkDescDescAppVF: value-level constructor for `descDesc I L`-as-tagged-`VDescCon` — builds the tagged shell before forcing the recursively computed fields so conv/quote can recognise the canonical reference without descending into the strong-levitation spiral._

```
mkDescDescAppVF : Int -> Val -> Val -> Val
```

Returns a `VDescCon` whose `_canonRef = { id = "descDesc";
I; L; }` marker lets conv/quote treat the value opaquely.
Eliminators (`descView`, `vInterpDF`, ...) walk through
`descViewF`'s one-step semantic view of the same reference
rather than forcing `.D` directly.

The underlying `raw` value is `descDescVal I L` evaluated via
`vAppF`; its fields are reused but the canonical marker takes
precedence in conv and quote. This separation enables sharing
a single `descDesc` value across every recursive position in
the kernel without re-evaluating the spiral.



#### Dispatch


fx.tc.eval.dispatch: full kernel evaluator self-fixpoint. Consumed by overlay constructions (notably `tc/elaborate/eval-overlay.nix`) that need to build a meta-aware self-table replacing selected dispatch attrs while inheriting the rest.

## `descView`

_descView: default-fuel one-step semantic view of a description value — return `{ tag = "DView{Ret,Arg,Rec,Pi,Plus}"; idx; ...payload }` selecting the description's outer constructor._

```
descView : Val -> { tag : DViewTag; idx : Int; ... } | null
```

Dispatches on both primitive `VDescX` shapes and encoded
`VDescCon` shapes uniformly. The `idx` field gives the summand
position (`0` = ret, `1` = arg, `2` = rec, `3` = pi, `4` = plus).
Primary consumer is `check.nix`'s `desc-con` trampoline, which
uses the view to detect plus-coproduct shapes with linear
recursion. Returns `null` for `VNe` or values whose `_canonRef`
is opaque.

## `eval`

_eval: default-fuel wrapper around `evalF`; spends from the `defaultFuel` (10M-step) budget. The canonical evaluator entry for kernel consumers._

```
eval : Env -> Tm -> Val
```

## `evalF`

_evalF: kernel-term evaluator. Routes through the depth-budgeted hybrid in `tc/eval/direct.nix`: direct `mkValueF` recursion for shallow structural terms, the CEK machine (`tc/eval/machine.nix`) at budget exhaustion and for the tags that must see machine-internal Val tags (notably `VLazyDescIndAccLayer`). `mkValueF` remains exported for overlays (notably `tc/elaborate/eval-overlay.nix`) that compose their own self-table with VMeta-aware dispatch._

```
evalF : Int -> Env -> Tm -> Val
```

## `instantiate`

_instantiate: default-fuel closure application — given `Closure { env; body; }` and an argument `Val`, evaluate the body in the extended environment._

```
instantiate : Closure -> Val -> Val
```

## `linearProfile`

_linearProfile: default-fuel linear-recursion classifier — given a description value `D`, return a list of pre-rec field types if `D` is a `descArg`-chain ending in `descRec descRet`; `null` if `D` is non-linear (tree, multi-rec, or non-plus)._

```
linearProfile : Val -> [{ S : Val; ... }] | null
```

Walks the `descArg`/`descRec` chain via `descView`; succeeds
when every pre-rec field is `descArg` and the tail is exactly
`descRec descRet`. Used by `check.nix`'s `desc-con` trampoline
to detect when a plus-coproduct `A + B` has exactly one
linear-recursive summand — the case where chain peeling
applies and 5000+ layers can be checked without recursion.

## `mkCanonAppVF`

_mkCanonAppVF: value-level constructor for `canon-app id params body`-as-tagged-`VDescCon` — currying-applies `body` to `params` and stamps the result with `_canonRef = { id; params; body; }` so conv/quote short-circuit on the canonical identity instead of forcing `.D`._

```
mkCanonAppVF : Int -> String -> [Val] -> Val -> Val
```

Generic counterpart of `mkDescDescAppVF` for user-registered
canonical descriptions. `bodyVal` is expected to be a curried
chain of `VLam`s that, after applying every element of
`paramVals`, yields a `VDescCon`. The raw result's `.D`/`.i`/`.d`
fields are reused; the `_canonRef` stamp takes precedence in
conv and quote so the recursive `.D` slot is never forced.

`bodyVal` is preserved on the stamp so `quote` can emit
`T.mkCanonApp id params body`. `canonRefConv` compares stamps
by `(id, params)` only; `body` is conv-irrelevant.

Throws if the curried application does not produce a
`VDescCon` — the smart-form's static contract.

## `mkDescDescAppV`

_mkDescDescAppV: default-fuel canonical `descDesc iLev I L`-value constructor — produces the levitated description-of-descriptions value, cached and shared across the kernel for index `I` at universe `iLev` and level `L`._

```
mkDescDescAppV : Val -> Val -> Val -> Val  -- iLev, I, L
```

## `mkDescDescAppVF`

_mkDescDescAppVF: value-level constructor for `descDesc I L`-as-tagged-`VDescCon` — builds the tagged shell before forcing the recursively computed fields so conv/quote can recognise the canonical reference without descending into the strong-levitation spiral._

```
mkDescDescAppVF : Int -> Val -> Val -> Val
```

Returns a `VDescCon` whose `_canonRef = { id = "descDesc";
I; L; }` marker lets conv/quote treat the value opaquely.
Eliminators (`descView`, `vInterpDF`, ...) walk through
`descViewF`'s one-step semantic view of the same reference
rather than forcing `.D` directly.

The underlying `raw` value is `descDescVal I L` evaluated via
`vAppF`; its fields are reused but the canonical marker takes
precedence in conv and quote. This separation enables sharing
a single `descDesc` value across every recursive position in
the kernel without re-evaluating the spiral.

## `mkValueF`

_mkValueF: dispatch-algebra-parameterized core evaluator body. Kernel instantiates `mkValueF self`; overlays (notably `tc/elaborate/eval-overlay.nix`) instantiate with their own self-table to thread VMeta-aware dispatch through closure bodies, preserving kernel-purity (Abel-Pientka 2011, section 2; see `tc/elaborate/value.nix:13-17`)._

```
mkValueF : Self -> Int -> Env -> Tm -> Val
```

## `sumPayloadTmView`

_sumPayloadTmView: term-level sum-payload view — given a `Tm` that is `boot-inl`/`boot-inr` or a sum-shaped `desc-con` with `_descConCert`, return `{ side; value; rebuild; rebuildVal; }` to drive the `desc-con` trampoline's payload walker; `null` for non-sum shapes._

```
sumPayloadTmView : Tm -> { side : "inl" | "inr"; value : Tm; rebuild : Tm -> Tm; rebuildVal : (Tm -> Val) -> Val -> Val; } | null
```

## `sumPayloadValView`

_sumPayloadValView: value-level sum-payload view — given a `Val` that is `VBootInl`/`VBootInr` or a sum-shaped `VDescCon` with `_descRef`, return `{ side; value; rebuild; }` for use in the `desc-con` trampoline; `null` for non-sum shapes._

```
sumPayloadValView : Val -> { side : "inl" | "inr"; value : Val; rebuild : Val -> Val; } | null
```

## `vAllD`

_vAllD: default-fuel `allD L I D K X M i d` — the type expressing that every recursive position in description-payload `d` (at index `i`) satisfies motive `M`._

```
vAllD : Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val
```

## `vApp`

_vApp: default-fuel kernel function-application value — beta-reduces `VLam`, extends the spine for `VNe`, threads through `VDescViewFn`._

```
vApp : Val -> Val -> Val
```

## `vBootJ`

_vBootJ: J-eliminator over `VBootEq` — on `VBootRefl` returns the base case (checker has already verified the sides match); on `VNe` extends the spine with an `eBootJ` frame._

```
vBootJ : Val -> Val -> Val -> Val -> Val -> Val -> Val
```

Arguments are `type lhs motive base rhs eq`. When `eq` is
`VBootRefl`, returns `base` directly — the checker has already
verified `lhs ≡ rhs`, so `rhs` is unused. When `eq` is `VNe`,
preserves `rhs` in the `EBootJ` spine frame so quotation can
reconstruct the stuck term. Any other shape is rejected with
an internal error.

## `vBootSumElim`

_vBootSumElim: default-fuel boot-sum eliminator — dispatches `VBootInl` to `onLeft` and `VBootInr` to `onRight`; extends the spine on `VNe`._

```
vBootSumElim : Val -> Val -> Val -> Val -> Val -> Val -> Val
```

## `vDescInd`

_vDescInd: default-fuel generic eliminator for description-based indexed inductives — `ind D P step i (con d) = step i d (everywhere D D P (lam j x. ind D P step j x) i d)`._

```
vDescInd : Val -> Val -> Val -> Val -> Val -> Val
```

Arguments: description `D`, motive `P : (i:I) -> mu D i -> U`,
step function `step`, target index `i`, scrutinee
(a `VDescCon` or `VNe`). On `VDescCon`, builds the inductive
hypothesis as a self-reference closure over `step`/`motive`/`D`/`I`,
feeds the canonical `mu D` family to `vEverywhereDF`, and
applies `step i d (everywhereResult)`. On `VNe`, extends the
spine with `eDescInd D motive step i`. The motive must be a
`VLam` so `I` is recoverable from its domain annotation.

## `vEverywhereD`

_vEverywhereD: default-fuel `everywhereD L I D K X M ih i d` — apply inductive hypothesis `ih` at every recursive position of `d`, producing the `allD` witness consumed by `vDescInd`._

```
vEverywhereD : Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val -> Val
```

## `vFst`

_vFst: kernel pair-projection — return the first component of a `VPair`; extend the spine with `eFst` on a stuck `VNe`. Forces a deferred `VThunkTm` first (the VThunkTm read-site invariant), as `vAppF` does, so the direct evaluator opening a machine-built closure env never reads a thunk's `.tag`._

```
vFst : Val -> Val
```

## `vInterpD`

_vInterpD: default-fuel description interpretation — given `L_val I_val D X i`, compute the type `interp I D X i` whose values are layers of the recursive datatype determined by `D`._

```
vInterpD : Val -> Val -> Val -> Val -> Val -> Val
```

## `vLiftElimF`

_vLiftElimF: kernel `lower` eliminator — idempotent at `convLevel l m`; β-reduces `lower _ (lift _ a) -> a` on `VLiftIntro`; appends `ELiftElim` to a stuck `VNe` spine._

```
vLiftElimF : Val -> Val -> Val -> Val -> Val -> Val
```

## `vLiftF`

_vLiftF: kernel `Lift l m eq A` type-former value — the type of values of `A : U(l)` transported up to `U(m)`; collapses idempotently when `convLevel l m` and composes nested Lifts._

```
vLiftF : Val -> Val -> Val -> Val -> Val
```

Idempotence: `Lift l l _ A ≡ A` for homogeneous code — returns
`A` directly when `convLevel l m`.
Composition: `Lift l m _ (Lift l' l _ A') ≡ Lift l' m _ A'` —
flattens by lowering the inner level. The witness slot `eq`
is irrelevant on collapse since both bound conditions hold by
transitivity; emit `vBootRefl` for the composed form.

## `vLiftIntroF`

_vLiftIntroF: kernel `liftIntro` value former — wraps `a : A` as a `VLift l m _ A`-typed value; idempotent at `convLevel l m`, and η-reduces a stuck `lower`-spine via `lift _ (lower _ x) ≡ x`._

```
vLiftIntroF : Val -> Val -> Val -> Val -> Val -> Val
```

Witness-irrelevance is enforced structurally: levels are
compared via `convLevel` and the carried `A` via syntactic
equality. The spine's `eq` field is not consulted. The
η-reduction inspects the tail of a `VNe` spine for an
`ELiftElim` frame whose parameters match; on hit, drops the
frame to yield the inner stuck term.

## `vSnd`

_vSnd: kernel pair-projection — return the second component of a `VPair`; extend the spine with `eSnd` on a stuck `VNe`. Forces a deferred `VThunkTm` first (the VThunkTm read-site invariant), as `vAppF` does, so the direct evaluator opening a machine-built closure env never reads a thunk's `.tag`._

```
vSnd : Val -> Val
```



#### Check


Semi-trusted (Layer 1): uses the TCB (eval/quote/conv) and reports
type errors via `send "typeError"`. Bugs here may produce wrong
error messages but cannot cause unsoundness.

## Core Functions

- `check : Ctx → Tm → Val → Computation Tm` — checking mode.
  Verifies that `tm` has type `ty` and returns an elaborated term.
- `infer : Ctx → Tm → Computation { term; type; }` — synthesis mode.
  Infers the type of `tm` and returns the elaborated term with its type.
- `checkType : Ctx → Tm → Computation Tm` — verify a term is a type.
- `checkTypeLevel : Ctx → Tm → Computation { term; level; }` — like
  `checkType` but also returns the universe level.

## Context Operations

- `emptyCtx` — empty typing context `{ env = []; types = []; depth = 0; }`
- `extend : Ctx → String → Val → Ctx` — add a binding (index 0 = most recent)
- `lookupType : Ctx → Int → Val` — look up a variable's type by index

## Test Helpers

- `runCheck : Computation → Value` — run a computation through the
  trampoline handler, aborting on `typeError` effects.
- `checkTm : Ctx → Tm → Val → Tm|Error` — check and unwrap.
- `inferTm : Ctx → Tm → { term; type; }|Error` — infer and unwrap.

## Key Behaviors

- **Sub rule**: when checking mode doesn't match (e.g., checking a
  variable), falls through to `infer` and uses `conv` to compare.
- **Non-cumulative universes**: Tarski-style, exact-level — `U(i)` does
  not subsume into `U(j)` for `i < j`; conv compares levels by
  `convLevel` with no cumulativity coercion.
- **Large elimination**: motives may return any universe, enabling
  type-computing eliminators (`checkMotive`).
- **Trampolining**: Succ and Cons chains checked iteratively.

## `_blame`

__blame: shared blame-frame discipline for bindP — { handlers, fold, empty } installed by every trampoline that runs a kernel check Computation so position wrapping is reconstructed at the single top-level typeError handler. `blame` is an opaque cons list (deepSeq-opaque ⇒ O(1)/step, structurally shared); `empty` is its nil for state init._

```
_blame : { handlers : Handlers, fold : Blame -> Error -> Error, empty : Blame }
```

## `_yield`

__yield: tcYield defer discipline — { handlers, wrap } installed alongside _blame by every trampoline running a kernel check Computation. A head `wrap` makes a recursive checker entry effect-first (O(1) WHNF), so the bindP `isPure` fast path stays flat on recursive arms while leaving syntactic leaves Pure. `tcYield` carries no state and no blame frame — observationally invisible._

```
_yield : { handlers : Handlers, wrap : Computation a -> Computation a }
```

## `bindP`

_bindP: position-tagged bind for kernel rule bodies — brackets the inner computation with a push/pop blame frame so any typeError it raises is wrapped under the given Position before reaching the top-level handler._

```
bindP : Position -> Computation a -> (a -> Computation b) -> Computation b
```

Brackets an impure inner computation `m` with a
`tcBlamePush`/`tcBlamePop` frame whose wrap calls
`D.nestUnder position` on every `diag.Error` `m` raises. A pure
`m` skips the frame and threads its value to `k` (it raises
nothing, so push-then-pop is a no-op). The push is emitted before
an impure `m`, so the combinator is `Impure` in O(1) and forces
`m` only to WHNF — recursion in `m` defers into the trampoline.
The wrapping records the descent coordinate at the caller site —
precision that downstream generic paths (the `check → infer`
catch-all, deep conv failures) cannot supply.

The continuation `k` runs after the pop, so errors it raises
are not wrapped by this frame. Frames are reconstructed onto
the leaf error by the single top-level handler (see `_blame`).
Use over `K.bind` whenever the failing site has a definite
positional identity in the surface syntax; pair with
`bindPChain` to thread N positions through one bracket.

## `bindPChain`

_bindPChain: fused sequential variant of `bindP` — threads a list of positions through a single shared typeError handler so the emitted blame chain has `positions[0]` as the outermost edge._

```
bindPChain : [Position] -> Computation a -> (a -> Computation b) -> Computation b
```

Equivalent to nested `bindP p_1 (bindP p_2 (... (bindP p_n m)
k_pure) k_pure) k` when intermediate continuations are pure
passthroughs, but pushes a single composite frame nesting the
positions outermost-first. `positions` is forced only on the
error path; empty `positions` push an identity frame.

## `bindPR`

_bindPR: rule-annotated variant of `bindP` — wraps the inner computation under `withRule rule position` so the blame edge records both the structural coordinate and the kernel-rule identity that emitted the descent._

```
bindPR : Position -> String -> Computation a -> (a -> Computation b) -> Computation b
```

Equivalent to `bindP (fx.diag.positions.withRule rule position)
m k`. The hint resolver consults only `position.tag`, so the
rule annotation never changes hint lookup — it surfaces in
pretty-printed output and is available to any consumer reading
`Position.rule` directly.

## `check`

_check: bidirectional checking-mode entry — verify `tm : ty` and return the elaborated kernel term; dispatches intro-form rules against their type-formers and falls through to synthesis plus structural conversion._

```
check : Ctx -> Tm -> Val -> Comp Tm
```

Dispatches intro forms against their corresponding type formers:
`lam` vs `VPi`, `pair` vs `VSigma`, `tt` vs `VUnit`,
`boot-inl`/`boot-inr` vs `VBootSum`, `boot-refl` vs `VBootEq`,
`squash-intro` vs `VSquash`, `string-lit`/`int-lit`/... vs
their primitive value types, and the trampolined `desc-con` vs
`VMu`. Anything not matched falls through to `infer` plus a
structural `C.conv` round-trip — the sole CHECK-to-INFER bridge
in the bidirectional rules.

The kernel is Tarski-style and non-cumulative: a term checked
against `U(k)` must have inferred type exactly `U(k)` modulo
`convLevel`. No universe-cumulativity coercion fires here.
Per-summand level mixing in `desc-arg` / `desc-pi` is handled
through the bound-witness slot at synthesis time.

The `desc-con` branch is trampolined for deep recursive data
(5000+ layers): it peels homogeneous linear-recursive chains
along a single recursive position when the description is a
plus-coproduct `A + B` with exactly one linear-recursive
summand. Non-linear shapes (tree, mutual recursion, multiple
recursive constructors, non-plus `D`) fall through to per-layer
checking via the degenerate `n = 0` branch. Constructor
certificates (`_descConCert`) accelerate the non-recursive case
by skipping the chain walk entirely.

Failure modes emit `D.mkKernelError` via the `typeError` effect;
positions and rule keys identify the failure site for the
diagnostic renderer. Cross-ref: `infer` for the synthesis side,
`checkMotive` for eliminator motive validation.

## `checkTm`

_checkTm: unwrapped variant of `check` — runs `runCheck (self.check ctx tm ty)` so callers get the elaborated term or a flat error record without manual trampoline handling._

```
checkTm : Ctx -> Tm -> Val -> Tm | { error; msg; expected; got }
```

## `checkType`

_checkType: thin wrapper around `checkTypeLevel` that discards the level — verifies `tm` is a type and returns the elaborated term only._

```
checkType : Ctx -> Tm -> Computation Tm
```

## `checkTypeLevel`

_checkTypeLevel: type-formation judgement — verifies that `tm` is a type and returns both the elaborated term and the universe Level value it inhabits._

```
checkTypeLevel : Ctx -> Tm -> Computation { term; level }
```

`level` is a kernel Level *value* (`V.vLevelZero`,
`V.vLevelSuc`, `V.vLevelMax`) — not a Nix integer — so
level-polymorphic types (`U(k)` for a variable `k : Level`)
flow through without ad-hoc integer machinery. Levels come
from the typing derivation, not post-hoc value inspection
(e.g., `Π(x:A). B` computes its level as the `vLevelMax` of
domain/codomain levels). The fallback path delegates to
`infer` and succeeds iff the inferred type is a universe; in
that case `.type.level` is already a Level value and is
forwarded verbatim.

## `emptyCtx`

_emptyCtx: empty typing context `{ env = envNil; types = envNil; names = envNil; depth = 0; }` — the zero of `extend`; starting point for top-level `check`/`infer` invocations. env/types/names are de Bruijn cons-list spines (index 0 = most recent binding) walked iteratively by `envNth`, so deep contexts stay host-stack- and call-depth-flat._

```
emptyCtx : Ctx
```

## `extend`

_extend: append a binding to a typing context — pushes a fresh de Bruijn variable at depth `ctx.depth`, the new type at index 0, and the name at index 0 of `names`; depth increments by one. `depth`/`eb` are forced at each extend so the scalar counters stay plain ints, never deferred `+1`/`or`-thunk chains that recurse N-deep on the C-stack when finally forced (cf. value.nix env-spine memo). The entry-yield budget `eb` carries through unchanged (consumed only at `check`/`infer` heads)._

```
extend : Ctx -> String -> Val -> Ctx
```

## `infer`

_infer: bidirectional synthesis-mode entry — given a term, return both the elaborated kernel term and a `Val` representing its inferred type; covers variables, annotations, application, projections, eliminators, the universe hierarchy, primitive type formers, and Desc/Mu operations._

```
infer : Ctx -> Tm -> Comp { term : Tm; type : Val; }
```

Dispatches on `tm.tag` to one rule per term shape. Type formers
(`pi`, `sigma`, `list`, `boot-sum`, `boot-eq`, `mu`, `squash`)
delegate to `checkTypeLevel` and lift the returned level into a
`VU` type. Eliminators (`bool-elim`, `list-elim`, `sum-elim`,
`desc-ind`, `j`, `squash-elim`, ...) are the most intricate
dispatches: each builds expected motive/step types by quoting
the motive at the appropriate de Bruijn depth, accounting for
the fresh binders introduced by each step lambda.

Variables look up their type in `ctx.types` by index. `ann`
elaborates the type annotation first, then checks the body
against the resulting `Val` — with one optimisation: when
`_descRef` is present and the body is `trusted` (emitted only
by `T.mkAnnTrusted` inside the kernel itself), the body is
accepted without re-checking. This avoids quadratic blowup on
deep recursive-data CHECK where every layer carries the same
encoded element description. `app` infers the function side,
validates the argument against the domain, and instantiates the
codomain closure with the argument's value.

Failure to find an applicable rule emits a `typeError` with
rule `"infer"` and message `"cannot infer type"`. Per-rule
positions and rules identify the specific failure for the
diagnostic renderer. Cross-ref: `check` for the checking-mode
side, `checkTypeLevel` for type-former level extraction,
`checkMotive` for motive validation in eliminator rules.

## `inferTm`

_inferTm: unwrapped variant of `infer` — runs `runCheck (self.infer ctx tm)` so callers get `{ term; type }` or a flat error record without manual trampoline handling._

```
inferTm : Ctx -> Tm -> { term; type } | { error; msg; expected; got }
```

## `lookupType`

_lookupType: read a variable's type from a context by de Bruijn index — index 0 is the most recent binding; throws on out-of-range index with a descriptive message. Indexes the `types` cons-list spine via the iterative `envNth` (host-stack- and call-depth-flat); the bound check uses the O(1) `depth` counter (= spine length) instead of re-walking the spine._

```
lookupType : Ctx -> Int -> Val
```

## `runCheck`

_runCheck: discharge a checking computation through the trampoline handler — collapses `typeError` into a flat `{ error; msg; expected; got }` record; returns the success value on the happy path._

```
runCheck : Computation a -> a | { error; msg; expected; got }
```

Installs a `typeError` handler that aborts the computation on
the first emission, exposing the structured `diag.Error` as
`error` plus convenience projections `msg`,
`expected`, and `got` (the leaf detail fields). The success
branch returns whatever the computation yielded; only the
post-handle `result.value` is exposed (state is discarded).

Pair with `checkTm` / `inferTm` for the unwrapped form, or
with `fx.tc.check.diag.runCheckD` / `runCheckDLazy` for
hint-decorated failures.

## Sub-namespaces

- [`_internal`](/nix-effects/type-checker/check/_internal)
- [`diag`](/nix-effects/type-checker/check/diag)

## Source

- [`src/tc/check/bindP.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/check/bindP.nix)
- [`src/tc/check/check.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/check/check.nix)
- [`src/tc/check/ctx.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/check/ctx.nix)
- [`src/tc/check/infer.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/check/infer.nix)
- [`src/tc/check/type.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/check/type.nix)



#### Diag


Outside the trust boundary. Routes kernel check/infer results
through the trusted core and decorates failures with a resolved
hint + a SourceMap-sourced surface origin. No new effects.

## API

- `sourceMap` — SourceMap data type and combinators. See the
  module's own doc for the full surface.
- `checkD   : Ctx -> Tm -> Val -> SourceMap -> Any`
- `inferD   : Ctx -> Tm -> SourceMap -> Any`
- `runCheckD : SourceMap -> Computation -> Any`
- `runCheckDLazy : (Unit -> SourceMap) -> Computation -> Any`

On success, these return what the trusted core returned (the
elaborated Tm for checkD, `{term; type;}` for inferD). On failure,
they return `{ error; msg; expected; got; hint; surface; }`.

`runCheckDLazy` defers `mkSm null` into the failure branch, so the
success path pays one closure allocation instead of the full SM
walker. Kernel HOAS entry points (`checkHoas`/`inferHoas`) use this
variant.

`hint` is a `Hint` record (`{ _tag="Hint"; text; category;
severity; docLink; }`) from `fx.diag.hints.resolve`, or null.
`surface` is the SourceMap's hoas payload at the blame chain's
leaf, or null when the chain exits the mapped region.

Soundness audit: this module contains no kernel rule logic. A bug
here can produce wrong hint text or an incorrect surface back-map;
it cannot cause an ill-typed term to be accepted.

## `checkD`

_checkD: `check` with diagnostic decoration — shorthand for `runCheckD sm (C.check ctx tm ty)`; returns the elaborated term on success, decorated error record on failure._

```
checkD : Ctx -> Tm -> Val -> SourceMap -> Tm | { error; msg; expected; got; hint; surface }
```

## `inferD`

_inferD: `infer` with diagnostic decoration — shorthand for `runCheckD sm (C.infer ctx tm)`; returns `{ term; type }` on success, decorated error record on failure._

```
inferD : Ctx -> Tm -> SourceMap -> { term; type } | { error; msg; expected; got; hint; surface }
```

## `runCheckD`

_runCheckD: kernel-result decorator — runs `C.runCheck` then, on failure, attaches a resolved hint (via `fx.diag.hints.resolve`) and a SourceMap-sourced surface back-mapping; success path untouched._

```
runCheckD : SourceMap -> Computation -> Tm | { error; msg; expected; got; hint; surface }
```

Lives outside the trust boundary: no new effect handlers,
no rule logic. The trusted `typeError` handler from `ctx.nix`
runs first; this combinator is a value-level transform on
the failure attrset.

On success, returns whatever the trusted core returned
(elaborated `Tm`). On failure, augments the flat record
with `hint` (a `Hint` record or `null`) and `surface` (the
SourceMap's hoas payload at the blame chain's leaf, or
`null` when the chain exits the mapped sub-tree).

## `runCheckDLazy`

_runCheckDLazy: deferred-SourceMap variant of `runCheckD` — takes a thunk that's forced only on failure, sparing the success path the full SourceMap walker allocation._

```
runCheckDLazy : (Unit -> SourceMap) -> Computation -> Tm | { error; msg; expected; got; hint; surface }
```

Used by kernel HOAS entry points (`checkHoas` / `inferHoas`)
where the SourceMap is a pure byproduct of elaboration and
is consulted only when resolving surface positions on error.
The success path pays one closure allocation instead of the
full SourceMap construction.

## `sourceMap`

_sourceMap: parallel structure threaded alongside elaborated `Tm` — back-maps a kernel `Error`'s `Position`-chain blame to the HOAS surface node that produced the offending sub-term._

A SourceMap mirrors the shape of an elaborated `Tm`, carrying
at each node an opaque HOAS-origin reference plus a map from
`Position` keys to child SourceMaps. Its sole purpose is
back-mapping: given an error raised by the kernel during
`check`/`infer` — whose blame is expressed as a `Position`
chain threaded through `Error.children` by `bindP` — resolve
that chain to the HOAS surface node that produced the
offending sub-Tm.

Structure:

```
SourceMap = {
  _tag = "SourceMap";
  hoas : Any | null;          # HOAS-origin reference (opaque)
  subs : AttrSet SourceMap;   # keyed by positionKey(Position)
}
```

Surface: constructors (`leaf`, `node`, `opaque`), descent
(`descend`, `descendChain`, `hoasAt`, `hoasAtError`), chain
extraction (`chainPositions`), key derivation (`positionKey`),
and the type predicate (`isSourceMap`). The key alphabet is
whatever `src/diag/positions.nix` emits via `positionKey`;
chain walking uses the same fast/slow split as
`src/diag/pretty.nix` (`builtins.genericClosure` beyond 500
steps).

## Source

- [`src/tc/check/diag/shell.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/check/diag/shell.nix)
- [`src/tc/check/diag/source_map.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/check/diag/source_map.nix)



#### _internal


fx.tc.check._internal: cross-part checker helpers reachable from sibling parts via the self-fixpoint; not part of the stable consumer surface.

## `checkDescAtAnyLevel`

_checkDescAtAnyLevel: description checking at any universe level — accepts both primitive `VDesc` results and encoded `VMu` descriptions (the `VDesc ↔ μ_⊤(descDesc I L)` correspondence) and threads the universe level back to the caller for downstream encoding decisions._

```
checkDescAtAnyLevel : Ctx -> Tm -> Val -> Computation { term; level }
```

Trusted-annotation fast path: when `dTm` is a `T.mkAnnTrusted`
with a complete `_descRef`, build a canonical description term
directly (skipping the unfolding scan) and reuse the carried
level. Otherwise fall through to inference and dispatch on the
inferred type's tag:

- `VDesc`: the level is already on the type; conv-check that the
  index type matches `iTyVal` and forward.
- `VMu`: the description is encoded — scan a bounded list of
  candidate universe levels (the prelude exercises `L = 0..3`)
  and ask `conv` whether `V.vDesc lev iTyVal` unifies with the
  inferred type. Conv fires the symmetric `VDesc ↔ VMu`
  unfolding internally (same mechanism as
  `conv.nix:344-355`).
- Anything else: emit a `typeError` — not a description.

Used by `desc-con` checking (`check.nix`) for `_descConCert`
validation, by `infer.nix` for `desc-ind` motive and branch
checking, and by `type.nix:mu` to thread the description level
into the `μ` type's universe level.

## `checkMotive`

_checkMotive: eliminator-motive validation — walks the lambda layers of a motive against an expected domain chain `D_1 → … → D_n → U(k)` and returns the elaborated motive term together with the universe level `k` of its codomain._

```
checkMotive : Ctx -> Tm -> Chain -> Comp { term; level }
```

The domain chain is a `{ head : Val; tail : Val → Chain } | null`
sequence so each layer's domain may depend on the previously-bound
value (required by `desc-ind`, whose motive is
`(i : I) → μ D i → U(k)`). 1-argument call sites use the
`singleton` helper to build a one-element chain.

- Lambda motive: extend the context with the current layer's
  domain, recurse into the body with `chain.tail freshV`, and
  wrap the result in `T.mkLam`. The level threads up unchanged
  through each lam wrapper so the innermost codomain's universe
  flows back to eliminators that care about it (e.g., `desc-ind`'s
  `allTy`).
- Non-lambda motive: fall through to `infer`, then walk the
  inferred Π-chain in lock-step with the expected `chain`,
  conv-checking each domain and instantiating each codomain
  through a fresh variable. The innermost codomain must be a
  universe; its level is the motive's level.

Failure modes emit `D.mkKernelError` under the `P.Motive` position
for the diagnostic renderer. Cross-ref: `singleton` for the
unary-chain helper, `infer` for the synthesis fallback,
`checkTypeLevel` for the innermost-universe leaf.

## `singleton`

_singleton: build a one-element motive chain — `{ head = dom; tail = _: null; }` — the trivial telescope used by `checkMotive` call sites with a single domain and no nested binder dependency._

```
singleton : Val -> Chain
```

The motive chain consumed by `checkMotive` is a nested
`{ head : Val; tail : Val → Chain } | null` structure so each
layer's domain may depend on prior binder values. Most
eliminator sites (Sum, Eq, Squash) have only one motive
argument and no inter-binder dependency; `singleton dom` packs
that into the chain shape with a constant `tail` that ignores
its argument and returns `null` — closing the chain after a
single layer.



#### Elaborate


Bridges the fx.types layer to the kernel's term representation
via the HOAS combinator layer. Provides the Nix ↔ kernel boundary.

## Type Elaboration

- `elaborateType : FxType → Hoas` — convert an fx.types type descriptor
  to an HOAS tree. Dispatches on: (1) `_kernel` annotation, (2) structural
  fields (Pi: domain/codomain, Sigma: fstType/sndFamily), (3) name
  convention (Bool, Nat, String, Int, Float, ...).
  Dependent Pi/Sigma require explicit `_kernel` annotation.

## Value Elaboration

- `elaborateValue : Hoas → NixVal → Hoas` — convert a Nix value to
  an HOAS term tree given its HOAS type. Bool→true_/false_, Int→natLit,
  List→cons chain, Sum→inl/inr, Sigma→pair. Trampolined for large lists.

## Structural Validation

- `validateValue : Path → Hoas → NixVal → [{ type; context; value; path; reason; }]` —
  collecting-handler bridge over `fx.tc.generic.check.deriveCheck`.
  Accumulates every `typeCheck` effect emission from the canonical
  structural validator into a list of typed error records carrying
  structured `Path` (Position-list) descents to each failure site.
  Empty list ↔ `elaborateValue` would succeed (soundness invariant).

## Value Extraction

- `extract : Hoas → Val → NixValue` — reverse of `elaborateValue`.
  Converts kernel values back to Nix values. Generated Nat/List
  `VDescCon` chains become Nix ints/lists; generated sums become tagged unions.
  Pi extraction wraps the VLam as a Nix function with boundary conversion.
  Opaque types (Attrs, Path, Function, Any) throw — kernel discards payloads.
- `extractInner : Hoas → Val → Val → NixValue` — three-argument extraction
  with kernel type value threading. Supports dependent Pi/Sigma via closure
  instantiation instead of sentinel tests.
- `reifyType : Val → Hoas` — converts a kernel type value back to HOAS.
  Fallback for when HOAS body application fails (dependent types).
  Loses sugar (VSigma→sigma, not record).

## Decision Procedure

- `decide : Hoas → NixVal → Bool` — returns true iff elaboration
  and kernel type-checking both succeed. Uses `tryEval` for safety.
- `decideType : FxType → NixVal → Bool` — elaborate type then decide.

## Full Pipeline

- `verifyAndExtract : Hoas → Hoas → NixValue` — type-check an HOAS
  implementation against an HOAS type, evaluate, extract to Nix value.
  Throws on type error.

## Value Embedding

- `embedVal : Val → Hoas` — lift a kernel value back into HOAS.
  `quote 0` reads the value to a closed `Tm`; `H.embedTm` wraps it
  via the `pre-elab` rule. Use when a Val produced by kernel
  evaluation (e.g. an effect handler's response) needs to flow into
  a surrounding HOAS expression that is itself about to be
  elaborated and re-evaluated.

## `decide`

_decide: boolean decision procedure — returns `true` iff `elaborateValue` succeeds and the kernel type-checker accepts the resulting HOAS value; `tryEval` catches all elaboration throws._

```
decide : Hoas -> NixVal -> Bool
```

## `decideType`

_decideType: `decide` lifted to `fx.types` descriptors — runs `elaborateType` then `decide`. Convenience for users working with `fx.types` rather than raw HOAS types._

```
decideType : FxType -> NixVal -> Bool
```

## `elaborateType`

_elaborateType: convert an `fx.types` type descriptor to an HOAS type tree — dispatches on `_kernel` annotation, structural fields (Pi: domain/codomain, Sigma: fstType/sndFamily), then name convention (Bool, Nat, Unit, ...). Dependent Pi/Sigma require explicit `_kernel`._

```
elaborateType : FxType -> Hoas
```

Three dispatch tiers, tried in order:

1. `_kernel` annotation: returned directly. This is the
   authoritative path for types built via `mkType` with an
   explicit `kernelType` (covers refinement, dependent, linear,
   levitated descriptions).
2. Structural fields: `Pi { domain, codomain, checkAt }` →
   `H.forall`; `Sigma { fstType, sndFamily, proj1 }` →
   `H.sigma`. Only non-dependent families (constant-codomain /
   constant-sndFamily) are accepted at this tier — dependent
   families throw and demand the `_kernel` path.
3. Name convention: primitives (`Bool`, `Nat`, `Unit`, `Null`,
   `String`, `Int`, `Float`, `Attrs`, `Path`, `Function`,
   `Any`) map to their HOAS prelude entries.

Unknown types throw with a message directing the author to
add `_kernel`. Cross-ref: `elaborateValue` for the dual on
values, `decideType` for the boolean pipeline.

## `elaborateValue`

_elaborateValue: strict-handler bridge over `fx.tc.generic.check.deriveElaborate` — produces the HOAS term that witnesses the value's typing, throwing on the first shape mismatch (catchable by `tryEval`)._

```
elaborateValue : Hoas -> NixVal -> Hoas
```

Composes the canonical structural walker
`fx.tc.generic.check.deriveElaborate` with the strict handler
from `fx.effects.typecheck.strict`. The walker is the same fold
as `validateValue` instantiated at carrier `Hoas`; the strict
handler throws on the first emitted typeCheck failure.

Per-tag construction is owned by the hoasAlg algebra inside
`tc/generic/check.nix`: `Bool` → `true_`/`false_`; `Nat` →
`natLit`; `String`/`Int`/`Float` → primitive literals; `List` →
cons chain via an O(1)-per-step continuation accumulator; `Sum`
→ `inl`/`inr`; `Sigma` → `pair`; constructor records →
prev-threaded `H.app` chain via `D.fieldType` (typeFn-aware for
dependent fields).

Fails fast on the first shape mismatch via `builtins.throw`.
Soundness invariant: `validateValue [] hoasTy v` is `[]` iff
`elaborateValue hoasTy v` does not throw on the same input.

## `embedVal`

_embedVal: Val-to-HOAS lift — `embedVal v` reflects a closed kernel `Val` into HOAS via `H.litVal`; the elaborator emits `T.mkLitVal` and eval returns the value verbatim. O(1) regardless of value depth._

```
embedVal : Val -> Hoas
```

Use when a kernel value needs to flow into a surrounding HOAS
expression that will be re-elaborated and re-evaluated. The
canonical example is an effect handler's response handed to a
user continuation: the continuation receives a Val but wants to
build further HOAS like `H.app H.succ response` for the next
program fragment. Without the lift, `H.elab` recurses into the
Val (which lacks `_htag`) and throws.

Soundness: the splice rule `eval ρ (LitVal v) = v` discards the
environment, so v must be closed (no free de Bruijn levels).
The bridge guarantees this — values reaching the embed site
are evaluation results of closed handler programs.

Cost: O(1). The prior `H.embedTm (quote 0 v)` composition walked
v structurally each call, producing quadratic blow-up in
iterative bridge use (a chain of N `bind get (n: …embedVal n…)`
steps quoted progressively deeper state Vals).

Reference: two-level type theory splice (Kovács, "Staged
Compilation with Two-Level Type Theory", POPL 2024;
Annenkov–Capriotti–Kraus–Sattler 2019).

## `evalOverlay`

_evalOverlay: default-fuel wrapper around `evalOverlayF`._

```
evalOverlay : Env -> Tm -> ElabVal
```

## `evalOverlayF`

_evalOverlayF fuel env tm: meta-aware kernel-term evaluator. Substitute for `evalF` at sites that may evaluate closure bodies whose environment contains `VMeta` values._

```
evalOverlayF : Fuel -> Env -> Tm -> ElabVal
```

## `extract`

_extract: kernel-value to Nix-value extraction — reverse of `elaborateValue`; computes the kernel type from the HOAS type once, then delegates to `extractInner` for the recursive walk with kernel type-value threading._

```
extract : Hoas -> Val -> NixValue
```

## `extractInner`

_extractInner: three-argument kernel value extraction — takes an HOAS type (for dispatch and sugar), a kernel type value (for dependent codomain/snd computation), and the kernel value to extract._

```
extractInner : Hoas -> Val -> Val -> NixValue
```

Inner workhorse for `fx.tc.elaborate.extract`. Threads the
kernel type value alongside the HOAS form so dependent
Pi / Sigma codomains can be instantiated through closure
application rather than sentinel-test heuristics. The Pi
branch wraps Nix arguments via `self.elaborateValue` before
feeding them back into the kernel; the mutual recursion
closes through `self`.

Decoding strategy varies by type tag: Nat / List / Sum
generated shapes are walked via `VDescCon`-chain
decomposition (trampolined via `genericClosure` for stack
safety on deep values); Pi extraction wraps a `VLam` as a
Nix function with boundary conversion; opaque types
(Attrs, Path, Function, Any) throw because the kernel
discards their payloads.

## `instantiateOverlay`

_instantiateOverlay: default-fuel wrapper around `instantiateOverlayF`._

```
instantiateOverlay : Closure -> ElabVal -> ElabVal
```

## `instantiateOverlayF`

_instantiateOverlayF fuel cl arg: meta-aware closure instantiation. Where kernel `instantiateF` crashes when the closure environment contains a `VMeta` (kernel `vAppF` reads `.tag` which `VMeta` lacks), this overlay routes app/elim dispatch through `VMeta`-aware variants and threads overlay evaluation transitively through closure bodies._

```
instantiateOverlayF : Fuel -> Closure -> ElabVal -> ElabVal
```

## `reifyType`

_reifyType: kernel-to-HOAS type rebuild — converts a kernel type `Val` back to an HOAS type for extract dispatch; loses sugar (VSigma → H.sigma rather than H.record)._

```
reifyType : Val -> Hoas
```

Used as a fallback when the HOAS body cannot be applied
(dependent-type instantiation, polymorphic app-spine
reduction). The HOAS body is preferred when available since
it preserves record/variant/maybe structure.

Generated `nat` / `list` / `sum` shapes reify to raw-tag
HOAS attrsets rather than the module-level `H.nat` /
`H.listOf` / `H.sum` combinators — the public combinators
carry app-spines or `_dtypeMeta`, while raw tags dispatch
directly to `extractInner`'s decoders and avoid re-entering
type reify.

## `validateValue`

_validateValue: collecting-handler bridge over `fx.tc.generic.check.deriveCheck` — accumulates every `typeCheck` effect emission produced by the canonical structural validator._

```
validateValue : Path -> Hoas -> NixVal -> [{ type; context; value; path; reason; }]
```

Composes the canonical structural validator
`fx.tc.generic.check.deriveCheck` with the collecting handler
from `fx.effects.typecheck.collecting` to accumulate every typed
failure across the value tree.

The path argument is a structured Position list from
`fx.tc.generic.path` (alias of `fx.diag.positions`); each
emitted error record carries the descent path to its failure
site under `reason ∈ { shape-mismatch, missing-field,
predicate-failed, deferred-pi }`.

Returns `[]` iff `elaborateValue` would not throw on the same
input. Use for upfront validation in build-time gates and
structural diagnostics; use `elaborateValue` directly when only
the elaborated value is needed.

## `verifyAndExtract`

_verifyAndExtract: full type-check + evaluate + extract pipeline — given an HOAS type and an HOAS implementation, type-check the impl against the type, evaluate to a kernel value, and extract to a Nix value; throws on type error._

```
verifyAndExtract : Hoas -> Hoas -> NixValue
```

The canonical entry point for closing a verified-impl pipeline
back to ordinary Nix data. Evaluates the term returned by
`checkHoas` — not a fresh elaboration of the impl — so the
extracted value is the one that was verified, with all metas
(e.g. a polymorphic list's element type, solved only by
checking against the expected type) already pinned. The kernel
type value is the direct elaboration of `hoasTy`; `extractInner`
reads descriptions through `descView`, which treats primitive
and encoded shapes uniformly, so the type's representation need
not match the checked term's.

On type-check failure throws `"verifyAndExtract: type check
failed"` — callers needing structured diagnostics should split
the pipeline: `H.checkHoas` for the error attrset, then
`extract`/`extractInner` only on success.

## Sub-namespaces

- [`_internal`](/nix-effects/type-checker/elaborate/_internal)
- [`meta`](/nix-effects/type-checker/elaborate/meta)

## Source

- [`src/tc/elaborate/check.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/check.nix)
- [`src/tc/elaborate/conv.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/conv.nix)
- [`src/tc/elaborate/core.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/core.nix)
- [`src/tc/elaborate/effects.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/effects.nix)
- [`src/tc/elaborate/eval-overlay.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/eval-overlay.nix)
- [`src/tc/elaborate/extract.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/extract.nix)
- [`src/tc/elaborate/infer.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/infer.nix)
- [`src/tc/elaborate/insertion.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/insertion.nix)
- [`src/tc/elaborate/meta-core.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/meta-core.nix)
- [`src/tc/elaborate/quote.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/quote.nix)
- [`src/tc/elaborate/runElab.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/runElab.nix)
- [`src/tc/elaborate/value.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/value.nix)



#### Meta


fx.tc.elaborate.meta: meta-aware overlay — `VMeta`, overlay check/infer, overlay eliminators, quote, `elabConv`, five scoped meta-effects (force/getMetas/assignMeta/emitConstraint/getConstraints), `runElab` handler.

## `addAndSimplifyConstraint`

_addAndSimplifyConstraint c state: simplify a constraint, allocate its id, append it to 𝒦, and update mentions._

```
addAndSimplifyConstraint : Constraint -> ElabState -> { id : Int; state : ElabState; }
```

## `addConstraint`

_addConstraint c state: allocate a constraint id, append to 𝒦, and register watcher mentions._

```
addConstraint : Constraint -> ElabState -> { id : Int; state : ElabState; }
```

## `assignMeta`

_assignMeta id tm: send-emitter extending Δ with `id ↦ tm`. Wakes any watchers registered in `mentions[id]` (per Abel-Pientka, section 7) when the assignment lands. Response shape: unit._

```
assignMeta : Int -> Tm -> Comp Unit
```

## `coerce`

_coerce: embed a kernel `Val` into `ElabVal`. Identity at the Nix level — the coproduct `ElabVal = Val ⊎ VMeta` is structural (kernel `Val`s are already valid `ElabVal` inhabitants because `VMeta` has a disjoint tag)._

```
coerce : Val -> ElabVal
```

## `descendImplicitPi`

_Wrap a body in implicit lambdas peeling leading implicit binders from an expected type._

```
descendImplicitPi : Ctx -> Val -> (Ctx -> Val -> Comp Tm) -> Comp Tm
```

## `dispatchMeta`

_dispatchMeta: bridge `dispatch` for the 5 meta-effects — selects the appropriate step on `ctx.op._opTag` and threads `ctx.state` (Nix-side Δ/𝒦/mentions attrset). Throws on unknown tags so accidental effect-set drift fails at build time._

```
dispatchMeta : { op; outputVal; state } -> { action; newState; response?; }
```

## `elabAllDF`

_elabAllDF fuel level I D K X M i d: meta-aware allD. `VMeta` in the description position appends `EAllD`._

```
elabAllDF : Fuel -> Val -> Val -> ElabVal -> Val -> Val -> Val -> Val -> Val -> ElabVal
```

## `elabAppF`

_elabAppF fuel fn arg: meta-aware application helper. Rigid `fn` delegates to the kernel evaluator; `VMeta` appends `EApp arg` to its spine._

```
elabAppF : Fuel -> ElabVal -> ElabVal -> ElabVal
```

## `elabBootJ`

_elabBootJ type lhs motive base rhs eq: meta-aware J eliminator. `VBootRefl` reduces to `base`; `VMeta` appends `EBootJ`._

```
elabBootJ : Val -> Val -> Val -> Val -> Val -> ElabVal -> ElabVal
```

## `elabBootSumElimF`

_elabBootSumElimF fuel left right motive onLeft onRight scrut: meta-aware bootstrap sum eliminator. `VMeta` appends `EBootSumElim`._

```
elabBootSumElimF : Fuel -> Val -> Val -> Val -> Val -> Val -> ElabVal -> ElabVal
```

## `elabCheck`

_elabCheck ctx tm ty: elaborator checking wrapper. Rigid cases delegate to the rigid checker; meta-involving Sub-rule cases synthesize then call `elabConv`, emitting postponed constraints instead of rigid type errors._

```
elabCheck : Ctx -> ElabTm -> ElabVal -> ElabComp ElabTm
```

## `elabCheckTm`

_elabCheckTm ctx tm ty: run `elabCheck` under `runElab` and return the value branch._

```
elabCheckTm : Ctx -> ElabTm -> ElabVal -> ElabTm | Error
```

## `elabConv`

_elabConv d ty lhs rhs: meta-aware conversion for elaboration. Rigid comparisons delegate to kernel conversion; comparisons involving `VMeta` emit postponed `conv` constraints; Pi/Sigma types are compared structurally using overlay eliminators so metas retain their spines._

```
elabConv : Depth -> Val -> ElabVal -> ElabVal -> Comp Bool
```

## `elabDescIndF`

_elabDescIndF fuel D motive step i scrut: meta-aware descInd eliminator. `VMeta` appends `EDescInd`._

```
elabDescIndF : Fuel -> Val -> Val -> Val -> Val -> ElabVal -> ElabVal
```

## `elabEverywhereDF`

_elabEverywhereDF fuel level I D K X M ih i d: meta-aware everywhereD. `VMeta` in the description position appends `EEverywhereD`._

```
elabEverywhereDF : Fuel -> Val -> Val -> ElabVal -> Val -> Val -> Val -> Val -> Val -> Val -> ElabVal
```

## `elabFst`

_elabFst p: meta-aware first projection. Rigid pairs/neutrals delegate to the kernel evaluator; `VMeta` appends `EFst`._

```
elabFst : ElabVal -> ElabVal
```

## `elabInfer`

_elabInfer ctx tm: elaborator synthesis wrapper. Rigid terms delegate to the rigid checker; overlay meta terms carrying a type annotation synthesize that annotation without entering the rigid checker._

```
elabInfer : Ctx -> ElabTm -> ElabComp { term : ElabTm; type : ElabVal }
```

## `elabInferApp`

_elabInferApp ctx tm: App-mode synthesis. Infers fn type, peels leading implicit Pis via `insertImplicits` when the call site is explicit, then checks the argument against the resulting explicit domain._

```
elabInferApp : Ctx -> ElabTm -> Comp ({ term; type } | Error)
```

## `elabInferTm`

_elabInferTm ctx tm: run `elabInfer` under `runElab` and return the value branch._

```
elabInferTm : Ctx -> ElabTm -> { term; type } | Error
```

## `elabInterpDF`

_elabInterpDF fuel level I D X i: meta-aware interpD. `VMeta` in the description position appends `EInterpD`._

```
elabInterpDF : Fuel -> Val -> Val -> ElabVal -> Val -> Val -> ElabVal
```

## `elabLiftElimF`

_elabLiftElimF l m eq A x: meta-aware Lift eliminator. `VMeta` appends `ELiftElim`._

```
elabLiftElimF : Val -> Val -> Val -> Val -> ElabVal -> ElabVal
```

## `elabSnd`

_elabSnd p: meta-aware second projection. Rigid pairs/neutrals delegate to the kernel evaluator; `VMeta` appends `ESnd`._

```
elabSnd : ElabVal -> ElabVal
```

## `elabSquashElimF`

_elabSquashElimF fuel A B f x: meta-aware propositional-truncation eliminator. `VMeta` appends `ESquashElim`._

```
elabSquashElimF : Fuel -> Val -> Val -> Val -> ElabVal -> ElabVal
```

## `emitConstraint`

_emitConstraint c: send-emitter appending `c` to the constraint queue 𝒦. Distinct from `typeError` (a type-error is proof of unsolvability; a postponed constraint is a monotone wait per Optimist's Lemma, GMM section 6.2 Lemma 4). Response shape: the allocated constraint id._

```
emitConstraint : Constraint -> Comp Int
```

## `emptyState`

_emptyState: initial `runElab` state — Δ, 𝒦, watcher index, ordered meta ids, and monotone fresh counters._

```
emptyState : ElabState
```

## `evalElab`

_evalElab state env tm: zonk tm against state.delta then delegate to kernel eval. Unsolved metas yield a stuck VMeta value._

```
evalElab : ElabState -> Env -> Tm -> Val
```

## `extendMeta`

_extendMeta id type state: add a Hole entry to Δ and advance the fresh-id counter past it._

```
extendMeta : Int -> MetaType -> ElabState -> ElabState
```

## `force`

_force v: send-emitter requesting Δ-aware reduction of `v`. Kernel `Val`s pass through unchanged; `VMeta { id; spine; type }` is reduced via `delta[id] · spine` when `id` is solved in Δ, else returned unchanged. Response shape: `ElabVal`._

```
force : ElabVal -> Comp ElabVal
```

## `forceMeta`

_forceMeta v state: if `v` is solved in Δ, replay its captured spine over the solution._

```
forceMeta : VMeta -> ElabState -> ElabVal
```

## `freshMeta`

_freshMeta type: allocate a new metavariable hole in Δ of the given type. Response shape: VMeta._

```
freshMeta : MetaType -> Comp VMeta
```

## `freshMetaInState`

_freshMetaInState type state: allocate a new `VMeta` and append a matching Hole entry to Δ._

```
freshMetaInState : MetaType -> ElabState -> { meta : VMeta; state : ElabState; }
```

## `getConstraints`

_getConstraints: send-emitter reading the current constraint queue 𝒦. Response shape: `𝒦 : [Constraint]`._

```
getConstraints : Comp [Constraint]
```

## `getMetas`

_getMetas: send-emitter reading the current meta-context Δ. Response shape: `Δ : { <metaId> = { tm; type } | null }`._

```
getMetas : Comp Delta
```

## `handle_Meta`

_handle_Meta: kernel HOAS shell `λ_op. λ_s. tt` for the meta-effects bridge. Paired with `runElab`'s `dispatchMeta`, which carries the actual per-op interpretation Nix-side._

## `handle_MetaTy`

_handle_MetaTy: `Π(_op:metaEff). Π(_s:Unit). Unit`. Unit codomain reflects that `outputVal` carries no info for meta-effects — Δ updates and responses flow Nix-side via `dispatchMeta`._

## `insertImplicits`

_Peel leading implicit Pi binders of a function's inferred type by fresh-meta insertion. Returns Comp { term; type } with the explicit head._

```
insertImplicits : Ctx -> Tm -> Val -> Comp { term : Tm; type : Val }
```

## `isHole`

_isHole m: true when a metavariable-context entry is unsolved._

```
isHole : MetaEntry -> Bool
```

## `isImplicitPi`

_Predicate: value is a VPi with implicit plicity sidecar._

```
isImplicitPi : Val -> Bool
```

## `isSolved`

_isSolved m: true when a metavariable-context entry carries a solution._

```
isSolved : MetaEntry -> Bool
```

## `isVMeta`

_isVMeta: predicate distinguishing the overlay `VMeta` from kernel `Val`s — true iff `v._vTag == "VMeta"`. Kernel `Val`s use `tag` (not `_vTag`) for ADT discrimination, so the predicate is decidable on the disjoint union._

```
isVMeta : ElabVal -> Bool
```

## `isVMetaTy`

_Predicate: value is a VMeta (overlay representation)._

```
isVMetaTy : Val -> Bool
```

## `levelsVal`

_levelsVal v: collect neutral variable levels referenced by an elaborator value._

```
levelsVal : ElabVal -> [Level]
```

## `lookupMeta`

_lookupMeta state id: read a Δ entry by metavariable id, returning null when absent._

```
lookupMeta : ElabState -> Int -> MetaEntry | Null
```

## `markConstraint`

_markConstraint cid status extra state: update one constraint status and merge extra diagnostic fields._

```
markConstraint : Int -> String -> AttrSet -> ElabState -> ElabState
```

## `mentionsOf`

_mentionsOf vals: collect unique metavariable ids referenced by a list of elaborator values._

```
mentionsOf : [ElabVal] -> [Int]
```

## `metaEff`

_metaEff: kernel-typed effect signature for the elaborator's 5 meta-effects — 5-element `H.variant` over tags `force` / `getMetas` / `assignMeta` / `emitConstraint` / `getConstraints`. Payload types are uniformly `H.unit`; semantic payload data rides in the Nix-host sentinel attached to the `op` argument._

```
metaEff : Hoas U
```

## `metaIdsVal`

_metaIdsVal v: collect metavariable ids referenced by an elaborator value and its spine payloads._

```
metaIdsVal : ElabVal -> [Int]
```

## `metaResp`

_metaResp: response-type function for `metaEff` — kernel-typed `λ_op : metaEff. H.unit`. All five meta-effects return Nix-host opaque values; the kernel-level response is uniformly unit._

```
metaResp : Hoas (metaEff -> U)
```

## `mkConstraint`

_mkConstraint c: normalize a constraint record with default position, mentions, and status fields._

```
mkConstraint : AttrSet -> Constraint
```

## `mkHole`

_mkHole id type: construct an unsolved metavariable-context entry._

```
mkHole : Int -> MetaType -> MetaEntry
```

## `mkMeta`

_mkMeta: overlay term head for quoted metavariables. This is not a kernel `Tm` constructor; it lives only in `fx.tc.elaborate`'s meta-aware term overlay._

```
mkMeta : Int -> [ElabTm] -> ElabTm
```

## `mkSolved`

_mkSolved id tm type: construct a solved metavariable-context entry._

```
mkSolved : Int -> ElabVal -> MetaType -> MetaEntry
```

## `mkVMeta`

_mkVMeta: construct an overlay metavariable value — `{ _vTag = "VMeta"; id; spine; type = { ctx; ty } }`. `id` is the globally-unique meta identifier allocated by `runElab`; `spine` is the local-variable spine captured at construction (Abel-Pientka, section 2 σ); `type` carries the meta's allocation-site typing context plus its expected type (paper's `A[Φ]` annotation)._

```
mkVMeta : Int -> [Val] -> { ctx : Ctx; ty : Val } -> ElabVal
```

## `nf`

_nf env tm: kernel eval followed by meta-aware quote._

```
nf : Env -> Tm -> ElabTm
```

## `occurs`

_occurs id v: true when `v` references metavariable `id`._

```
occurs : Int -> ElabVal -> Bool
```

## `patternSpine`

_patternSpine spine: true for application spines whose arguments are distinct bound variables._

```
patternSpine : Spine -> Bool
```

## `plicityAwait`

_Emit a postponed plicity-await constraint awaiting the named meta; re-awakens when the meta solves._

```
plicityAwait : Ctx -> Int -> Val -> Val -> Comp Int
```

## `processActiveConstraints`

_processActiveConstraints state: rerun local simplification for active constraints and preserve non-active constraints._

```
processActiveConstraints : ElabState -> ElabState
```

## `quote`

_quote d v: meta-aware read-back. Rigid values delegate to `fx.tc.quote`; `VMeta` quotes to `mkMeta id []` with its elimination spine replayed as ordinary term eliminators._

```
quote : Depth -> ElabVal -> ElabTm
```

## `quoteElim`

_quoteElim d head frame: replay one kernel spine frame against an overlay term head, recursively using meta-aware `quote` for frame payloads._

```
quoteElim : Depth -> ElabTm -> SpineEntry -> ElabTm
```

## `quoteSp`

_quoteSp d head spine: fold `quoteElim` over a stored elimination spine._

```
quoteSp : Depth -> ElabTm -> [SpineEntry] -> ElabTm
```

## `reawakenMentions`

_reawakenMentions ids state: mark postponed constraints watching solved metavariables active._

```
reawakenMentions : [Int] -> ElabState -> ElabState
```

## `registerMentions`

_registerMentions mentions cid index: add a constraint id to every mentioned metavariable watcher list._

```
registerMentions : [Int] -> Int -> MentionsIndex -> MentionsIndex
```

## `runElab`

_runElab A program: discharge an elaborator computation through the descInterp trampoline. Threads `emptyState` Nix-side via the bridge's `state` channel; `handle_Meta` (kernel shell) plus `dispatchMeta` (Nix-side interpreter) discharge the 5 meta-effects._

```
runElab : Hoas U -> Hoas (μ freeFxApp metaEff metaResp A) -> { value; state : ElabState; }
```

## `sigmaFlatten`

_sigmaFlatten id state: replace an unsolved Sigma-typed meta with a pair of freshly allocated component metas._

```
sigmaFlatten : Int -> ElabState -> ElabState
```

## `simplifyConstraint`

_simplifyConstraint c state: locally simplify one constraint by rigid conversion, direct meta solving, occurs-check failure, or postponement._

```
simplifyConstraint : Constraint -> ElabState -> { state : ElabState; constraint : Constraint; }
```

## `solveMeta`

_solveMeta id tm state: replace a Δ entry with a Solved entry and reawaken constraints watching that id._

```
solveMeta : Int -> ElabVal -> ElabState -> ElabState
```

## `updateConstraint`

_updateConstraint cid f state: update one constraint in 𝒦 by id._

```
updateConstraint : Int -> (Constraint -> Constraint) -> ElabState -> ElabState
```

## `zonkTm`

_zonkTm depth state tm: substitute solved metas in `tm`. Returns `{ error = { unsolved-meta; id; ctx; } }` if any `Hole` is in `state.delta`; else `{ value = tm' }` with thunked sub-fields (stack-safe, forcing deferred to consumer access)._

```
zonkTm : Depth -> ElabState -> Tm -> Result Tm
```

## Source

- [`src/tc/elaborate/meta/constraints.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/meta/constraints.nix)
- [`src/tc/elaborate/meta/context.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/meta/context.nix)
- [`src/tc/elaborate/meta/eval.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/meta/eval.nix)
- [`src/tc/elaborate/meta/meta.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/meta/meta.nix)
- [`src/tc/elaborate/meta/unify.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/meta/unify.nix)
- [`src/tc/elaborate/meta/zonk.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/elaborate/meta/zonk.nix)



#### _internal


fx.tc.elaborate._internal: cross-part elaboration helpers reachable from sibling parts via the self-fixpoint; not part of the stable consumer surface.

## `reifyDesc`

_reifyDesc: kernel-to-HOAS description rebuild — converts a description `Val` back to an HOAS description; counterpart to `reifyType` used internally by `extractInner` for `mu` decoding fallbacks._

```
reifyDesc : Val -> Hoas
```

Reverses `evalDesc`: walks a description Val via `descView` and
rebuilds the corresponding HOAS form (`H.descRet`, `H.descArg`,
`H.descRec`, `H.descPi`, `H.plus`). Recursion is in `self` so
descRec / plus sub-descriptions traverse uniformly.

Used by `reifyType`'s `VMu` fallback when no sugared shape
(Bool / Nat / List / Sum) matches the description: the result
is an anonymous `H.mu (reifyDesc D) H.tt` that `extractInner`'s
mu branch can then decode against an optional `_dtypeMeta`.



#### Hoas


Higher-Order Abstract Syntax layer that lets you write kernel terms
using Nix lambdas for variable binding. The `lower` function
compiles HOAS trees to de Bruijn indexed Tm terms.

## Example

```nix
# Π(A:U₀). A → A
H.forall "A" (H.u 0) (A: H.forall "x" A (_: A))
```

## Type Combinators

- `nat`, `bool`, `unit`, `void` — base types
- `string`, `int_`, `float_`, `attrs`, `path`, `derivation`, `function_`, `any` — primitive types
- `thunk` (parametric: `thunk : Hoas -> Hoas`) — generic deepSeq-safe carrier
- `listOf : Hoas → Hoas` — List(elem)
- `sum : Hoas → Hoas → Hoas` — Sum(left, right)
- `eq : Hoas → Hoas → Hoas → Hoas` — generated EqDT(type, lhs, rhs)
- `u : Int → Hoas` — Universe at level
- `forall : String → Hoas → (Hoas → Hoas) → Hoas` — Π-type (Nix lambda for body)
- `sigma : String → Hoas → (Hoas → Hoas) → Hoas` — Σ-type

## Compound Types (Sugar)

- `record : [{ name; type; }] → Hoas` — nested Sigma (sorted fields)
- `maybe : Hoas → Hoas` — Sum(inner, Unit)
- `variant : [{ tag; type; }] → Hoas` — nested Sum (sorted tags)
- `product : String → [Field] → DataSpec` — named single-constructor μ-datatype

## Term Combinators

- `lam : String → Hoas → (Hoas → Hoas) → Hoas` — λ-abstraction
- `let_ : String → Hoas → Hoas → (Hoas → Hoas) → Hoas` — let binding
- `zero`, `succ`, `true_`, `false_`, `tt`, `refl` — intro forms; `refl` is check-mode only
- `nil`, `cons`, `pair`, `inl`, `inr` — data constructors
- `stringLit`, `intLit`, `floatLit`, `attrsLit`, `pathLit`, `derivationLit`, `fnLit`, `anyLit` — primitive literals
- `absurd`, `ann`, `app`, `fst_`, `snd_` — elimination/annotation

## Eliminators

- `ind` — generated natural eliminator adapter
- `boolElim` — (k : Level) → (Q : bool → U(k)) → Q true_ → Q false_ → (b : bool) → Q b
- `listElim` — generated list eliminator adapter
- `sumElim` — generated sum eliminator adapter
- `j` — EqDT eliminator adapter with J-shaped arguments

## Ornaments

- `ornI`, `ornDesc`, `ornForget` — first-class ornaments compiled to existing `Desc`, `mu`, and `descInd` programs; ornaments are not kernel primitives
- `ornPullback`, `ornLiftFold` — transport base programs to ornamented datatypes by composing with `ornForget`
- `ornLiftProducer`, `ornLiftTransform` — lift base producers/transforms through functional ornament output sections
- `algOrn` — algebraic ornament builder for `descRet`/`descArg`/`descRec`/keep-only `descPi`/`descPlus`, generating an ornament indexed by an algebra result
- `functionalOrnament`, `ornBuild` — manual sections of `ornForget` for explicit base-to-ornamented construction
- `validateFunctionalLaws`, `functionalCompose` — law metadata checks and composition for sectioned ornaments
- `validateOrnament`, `tryOrnament`, `validateAlgOrn`, `tryAlgOrn` — total structured diagnostics for user-facing ornament construction

## Lowering

- `lower : Int → Hoas → Tm` — compile at given depth
- `elab : Hoas → Tm` — compile from depth 0

## Convenience

- `checkHoas : Hoas → Hoas → Tm|Error` — elaborate type+term, type-check
- `inferHoas : Hoas → { term; type; }|Error` — elaborate and infer
- `natLit : Int → Hoas` — build S^n(zero)

## Stack Safety

Binding chains (pi/lam/sigma/let), succ chains, and cons chains
are elaborated iteratively via `genericClosure` — safe to 8000+ depth.

## `False`

_False: propositional falsehood — alias for the kernel-primitive `void` (`empty`) per HoTT Book, section 1.7 (`False = ⊥`); the initial-object dual of `True`._

```
False : Hoas
```

## `True`

_True: propositional truth — alias for `unit` per HoTT Book, section 1.7 (`True = ⊤`). Distinct from `BoolDT`'s data-level `true_`._

```
True : Hoas
```

## `WDT`

_WDT: W-type description macro — packages shape sort + position family into a `DataSpec` for arbitrary-branching inductive trees outside the description layer._

```
WDT : Hoas -> (Hoas -> Hoas) -> DataSpec
```

## `absurd`

_absurd: HOAS empty-type eliminator — `absurd P x` discharges `x : Empty` to a value of any type `P` at any universe level; the unique map from the initial object._

```
absurd : Hoas -> Hoas -> Hoas  -- targetType P, scrutinee x
```

## `absurdFin0`

_absurdFin0: vacuous-`fin 0` eliminator — `absurdFin0 P x` discharges `x : fin 0` to any type `P` via no-confusion on the impossible `Eq Nat (succ m) zero`._

```
absurdFin0 : Hoas -> Hoas -> Hoas  -- P, x
```

`fin 0` is vacuous because both fzero and fsuc constructor
payloads carry `Eq Nat (succ m) i` leaves, which at `i = 0`
give `Eq Nat (succ m) zero` — uninhabited. The implementation
uses a single J transport at motive `λx _. natCaseU P Unit x`,
landing at `Unit` for succ cases (filled by `tt`) and at `P`
at the goal case `i = zero`. Used by `void` and surface
`absurd`.

## `absurdPrim`

_absurdPrim: HOAS kernel-primitive empty-type eliminator — `absurdPrim P x` discharges a stuck `x : Empty` to produce a value of any type `P` at any universe level; the unique map from the initial object._

```
absurdPrim : Hoas -> Hoas -> Hoas  -- targetType P, scrutinee x
```

## `algArg`

_algArg: arg algebra — consumes the `descArg`'s payload via `body : s -> Algebra`, recursing into the rest of the description through the resulting algebra._

```
algArg : (Tm -> Algebra) -> Algebra
```

## `algOrn`

_algOrn: build an `Ornament` from an algebra over a base description — indexed by the algebra's result, so each ornamented value carries its algebra trace as the J-index._

```
algOrn : { I?, J, baseD | D, erase, algebra, resultTy?, pack?, proof?, level?, meta? } -> Ornament
```

## `algOrnDiagnosticRecords`

_algOrnDiagnosticRecords: total structured diagnostics describing every shape mismatch between an algebra and its target description; returns `[]` on success._

```
algOrnDiagnosticRecords : Attrs -> [Diagnostic]
```

## `algOrnDiagnostics`

_algOrnDiagnostics: human-readable text forms of `algOrnDiagnosticRecords` for inclusion in error messages and test assertions._

```
algOrnDiagnostics : Attrs -> [String]
```

## `algPiKeep`

_algPiKeep: pi-keep algebra — `body` consumes the Π-quantified branch using `branchIndex` (or full `{ branchIndex, ... }` record), generating an algebra per branch._

```
algPiKeep : (Tm | { branchIndex, ... }) -> (Tm -> Algebra) -> Algebra
```

## `algPlus`

_algPlus: plus algebra — sum of two sub-algebras, mirroring `descPlus`; routes the algebra into `left` or `right` depending on the constructor arm taken._

```
algPlus : Algebra -> Algebra -> Algebra
```

## `algRec`

_algRec: rec algebra — handles a `descRec` arm by giving `body : recResult -> Algebra` over the recursive child's algebra result; threads results upward._

```
algRec : (Tm -> Algebra) -> Algebra
```

## `algRet`

_algRet: ret algebra — terminates an algebraic ornament arm by returning a constant `result` value for the leaf description; used over `descRet` shapes._

```
algRet : Tm -> Algebra
```

## `allD`

_allD: induction-hypothesis collector — `allD level I D K X M i d` produces the type `All D X M i d`, threading motive `M` through every recursive position in payload `d`._

```
allD : Level -> Hoas -> Hoas -> Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

## `and`

_and: propositional conjunction — `and P Q := Σ (_:P). Q` per HoTT Book, section 1.7. Elaborates to a sigma._

```
and : Hoas -> Hoas -> Hoas
```

## `ann`

_ann: HOAS type annotation — `ann term type` produces `(term : type)`; fixes the checking direction so the kernel verifies `term` against `type` rather than inferring._

```
ann : Hoas -> Hoas -> Hoas
```

Essential at every position where the kernel would otherwise
need to infer a type from a checkable form (e.g. lambda
bodies producing data constructors). The elaborator emits
`mkAnn`; `check` consumes the annotation and validates the
term against the declared type. Default — re-checks the body
at every use site. For named-definition / δ-rule discipline
on smart constructors whose bodies are well-typed by
construction (and where re-checking would diverge through
mutual recursion), see `annTrusted`.

## `annTrusted`

_annTrusted: HOAS type annotation that propagates the declared type without re-checking the body — the δ-rule analogue. `annTrusted term type` declares `(term : type)` as a named definition whose body is well-typed by construction._

```
annTrusted : Hoas -> Hoas -> Hoas
```

Use this for smart constructors that wrap closed expressions
whose well-typedness follows compositionally from the
kernel-typed combinators used to build them. The infer rule's
`trusted` branch skips the body re-check that `ann` performs,
making this the only viable annotation form for mutually
recursive smart constructors (e.g. `freeFxApp` ↔
`kontQueueApp` in `experimental/desc-interp/desc.nix`, where
each body references the other through `μ(…App …)`).

Discipline: the caller is responsible for verifying the body
against the declared type at definition time (manually, or
via a separately-checkable test fixture). At use sites the
kernel propagates the declared type unconditionally.

Elaborates to `mkAnnTrusted`. Equivalent in spirit to Coq's
`Definition foo : T := body` or Agda's signature-then-body
form — the type is looked up at use sites, not re-derived.

## `any`

_any: kernel-primitive `Any` type — top type covering every Nix value; used as a fallback when no narrower type fits._

```
any : Hoas
```

## `anyLit`

_anyLit: HOAS Any-literal marker — placeholder term checkable against `any`; covers any kernel-opaque Nix value._

```
anyLit : Hoas
```

## `app`

_app: HOAS function application — `app f arg` builds the redex; β-reduces during normalisation when `f` is a lambda._

```
app : Hoas -> Hoas -> Hoas
```

## `attrs`

_attrs: kernel-primitive `Attrs` type — opaque Nix attrset axiomatised at the kernel level; literal-only entry via `attrsLit`._

```
attrs : Hoas
```

## `attrsLit`

_attrsLit: HOAS Attrs-literal marker — placeholder term checkable against `attrs`; the actual Nix attrset is not embedded in the kernel term._

```
attrsLit : Hoas
```

## `bool`

_bool: HOAS `Bool` type former — generated by `BoolDT.T`; isomorphic to `Sum Unit Unit` under the description encoding._

```
bool : Hoas
```

## `boolElim`

_boolElim: HOAS `Bool` eliminator — `boolElim k Q onT onF b` runs `BoolDT.elim k`; the motive `Q : bool -> U(k)` may depend on the scrutinee._

```
boolElim : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- k, motive, onTrue, onFalse, scrut
```

For constant motives use `tc.verified.if_` which auto-
generates `λ_:bool.resultTy`. Dependent motives are needed
when the result type differs between true and false cases —
e.g. dispatching to different datatypes via `natCaseU`.

## `canonApp`

_canonApp: generic identity-tagged HOAS application — `canonApp id params body` produces a `VDescCon` stamped with `_canonRef = { id; params; }` at eval time, so conv/quote short-circuit on the canonical identity instead of forcing the recursive `.D` slot. Use to add cycle-safe outer references for user-defined recursive descriptions (freer monads, FTCQueues, ...)._

```
canonApp : String -> [Hoas] -> Hoas -> Hoas
```

## `checkFunctionalLaws`

_checkFunctionalLaws: identity on `F` when every law-check passes, otherwise throws the concatenated diagnostic text — the assertive sibling of `validateFunctionalLaws`._

```
checkFunctionalLaws : FunctionalOrnament -> FunctionalOrnament  -- throws on failure
```

## `checkHoas`

_checkHoas: HOAS-driven type-checker — `checkHoas typeHoas termHoas` elaborates both, runs the kernel `check` rule, and returns the checked term or a structured Error._

```
checkHoas : Hoas -> Hoas -> Tm | Error
```

The principal entry for verifying a HOAS term against a HOAS
type. Elaborates type and term in tandem (so binders align),
then invokes the kernel `check` rule which produces a
verified `Tm` or a structured `Error` carrying the failing
rule and contextual `Detail`. Returns the Error directly
(does not throw); callers route through `?error` for fast
dispatch.

## `con`

_con: HOAS constructor declarator — `con name fields` packages an ordered list of field declarations into a constructor specification consumed by `datatype`._

```
con : String -> [Field] -> Constructor
```

## `conI`

_conI: indexed-constructor declarator — `conI name fields targetIndex` declares a constructor whose carrier targets a specific index of the datatype's index family._

```
conI : String -> [Field] -> (Hoas -> Hoas) -> Constructor
```

## `cong`

_cong: User-Eq congruence — proof of `∀A B (f:A→B) x y. Eq A x y -> Eq B (f x) (f y)`; one J application transporting refl through the function. Composes with `trans` for diagram-chase proofs on derived equalities._

```
cong : Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- A, B, f, x, y, p
```

## `congSuc`

_congSuc: Level-suc congruence — proof of `∀a b. Eq Level a b -> Eq Level (suc a) (suc b)`; derived via J transporting refl along the supplied equality._

```
congSuc : Hoas
```

## `cons`

_cons: HOAS list-cons constructor — `cons h t` prepends `h : A` to `t : listOf A`; element type inferred._

```
cons : Hoas -> Hoas -> Hoas  -- head, tail
```

## `datatype`

_datatype: HOAS datatype macro — `datatype name [con …]` declares a named ⊤-slice datatype, emitting `{ D, T, elim, <constructors> }` with `_dtypeMeta` for walker dispatch._

```
datatype : String -> [Constructor] -> DataSpec
```

The macro builds the description from constructor field lists,
synthesises the type former (`T = mu D tt`), generated
constructors that introduce values, and an eliminator
specialised for the description. The result attrset's
`_dtypeMeta` field carries the constructor list for walker
dispatch (used by `recoverConstructor` / `walkAttrsetDatatype`).
Surface entry point for declaring new datatypes — prefer over
manual `mu` + `descCon` construction.

## `datatypeI`

_datatypeI: indexed-datatype macro — `datatypeI name indexSort [conI …]` declares a datatype indexed by `indexSort`; each constructor must declare its target index._

```
datatypeI : String -> Hoas -> [ConI] -> DataSpec
```

Indexed counterpart to `datatype`. The index sort `I` parametrises
the carrier family, and each constructor's `conI` declares the
index it produces. The resulting `T : I -> U` is the family
type former; `app T idx` is the carrier at a specific index.
Prelude `fin`, `vec` use this form.

## `datatypeP`

_datatypeP: parametric-datatype macro — `datatypeP name [param …] [con …]` declares a datatype parametric in zero or more sort parameters._

```
datatypeP : String -> [Param] -> (Hoas -> [Constructor]) -> DataSpec
```

Parameters are sorts external to the datatype; the
constructor list is a function of the parameter binders.
Resulting `T` takes parameters before producing the carrier
type. Prelude `listOf`, `sum` would be expressed via this
macro (in practice they're macro-generated via `ListDT`,
`SumDT` at fixed parameter shapes).

## `datatypePI`

_datatypePI: parametric + indexed datatype — `datatypePI name [param …] indexSortFn [conI …]` combines parameters and indices in one macro._

```
datatypePI : String -> [Param] -> (Hoas -> Hoas) -> (Hoas -> [ConI]) -> DataSpec
```

The most general datatype declarator: takes external
parameters AND an index sort that can depend on those
parameters, AND constructors whose index decisions depend on
both. Used by `vec` (parameter A, index n : nat) and similar
prelude families.

## `dec`

_dec: decidability proposition — `dec P := P ⊎ ¬ P` per Agda `Relation.Nullary.Dec`. Defined as `sum P (not P)`; inhabitants built via `yes` / `no` and eliminated via `decElim`._

```
dec : Hoas -> Hoas
```

## `decAnd`

_decAnd: conjunction decidability — `decAnd P Q dp dq : dec (and P Q)` given `dp : dec P` and `dq : dec Q`. Both yes ⇒ yes (pair); either no ⇒ no (refute via fst_/snd_)._

```
decAnd : Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- P, Q, decP, decQ
```

## `decElim`

_decElim: eliminator for `dec P` — `decElim P motive oy on d` discharges `d : dec P` against motive `M : dec P -> U(0)` with branches `oy : (p:P) -> M (yes _ p)` and `on : (r: not P) -> M (no _ r)`. Forwards to `sumElim` at level 0._

```
decElim : Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- P, motive, oyes, ono, d
```

## `decNot`

_decNot: negation decidability — `decNot P dp : dec (not P)`. yes ⇒ no (negation contradicts the proof); no ⇒ yes (the refutation IS the negation witness)._

```
decNot : Hoas -> Hoas -> Hoas  -- P, decP
```

## `decOr`

_decOr: disjunction decidability — `decOr P Q dp dq : dec (or_ P Q)`. Either yes ⇒ yes (inl/inr); both no ⇒ no (refute via sumElim)._

```
decOr : Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- P, Q, decP, decQ
```

## `decideEqIntZ`

_decideEqIntZ: decidability of IntZ equality — `decideEqIntZ m n : dec (Eq IntZ m n)`. Four-case `intzElim` sign cascade; same-sign quadrants delegate to `decideEqNat` and lift via cong / injectivity; cross-sign quadrants refute via `signsDiffer` / `signsDifferRev`. Agda `Data.Integer.Properties._≟_`._

```
decideEqIntZ : Hoas  -- closed kernel function Π m. Π n. dec (Eq IntZ m n)
```

## `decideEqNat`

_decideEqNat: decidability of Nat equality — `decideEqNat m n : dec (Eq Nat m n)`. Closed kernel `lam`-term performing simultaneous structural recursion on both arguments. Agda `Data.Nat.Properties._≟_`._

```
decideEqNat : Hoas  -- closed kernel function Π m. Π n. dec (Eq Nat m n)
```

## `decideLeIntZ`

_decideLeIntZ: decidability of `intzLe` — `decideLeIntZ m n : dec (intzLe m n)`. Four-case `intzElim` sign cascade following `intzLe`'s quadrant table; pos-pos delegates to `decideLeNat`, pos-negSucc returns `no` (target reduces to `void`), negSucc-pos returns `yes tt` (target reduces to `unit`), negSucc-negSucc delegates to `decideLeNat` at flipped arguments. Agda `Data.Integer.Properties._≤?_`._

```
decideLeIntZ : Hoas  -- closed kernel function Π m. Π n. dec (intzLe m n)
```

## `decideLeNat`

_decideLeNat: decidability of `Le` — `decideLeNat m n : dec (le m n)`. Closed kernel `lam`-term following Agda `Data.Nat.Properties._≤?_` four-case recipe (zero-zero, zero-suc, suc-zero, suc-suc)._

```
decideLeNat : Hoas  -- closed kernel function Π m. Π n. dec (le m n)
```

## `derivation`

_derivation: kernel-primitive `Derivation` type — Nix derivation values (attrsets carrying `type = "derivation"`); the store-producing irreducible Nix value category, axiomatised at the kernel level with literal-only entry via `derivationLit`._

```
derivation : Hoas
```

## `derivationLit`

_derivationLit: HOAS Derivation-literal marker — placeholder term checkable against `derivation`; the Nix derivation is not embedded in the kernel term._

```
derivationLit : Hoas
```

## `desc`

_desc: ⊤-slice description type former — alias for `descI unitPrim`; descriptions over the kernel-primitive unit index type._

```
desc : Hoas
```

## `descArg`

_descArg: argument-position description-encoder — `descArg I k S T` extends a description with a non-recursive field of sort `S`, with `T` the continuation under the bound value._

```
descArg : Hoas -> Level -> Hoas -> Hoas -> Hoas
```

## `descCataBool`

_descCataBool: constant-Bool-motive description catamorphism — `descCataBool { D, carrier, onArg }` folds `onArg`'s per-field Boolean decisions over `μ ⊤ D`, conjoining every `descArg` field and recursive child. The non-dependent specialisation of `descInd`._

```
descCataBool : { D : Hoas; carrier : Hoas; onArg : Int -> Hoas -> Hoas -> Hoas } -> Hoas  -- result : carrier -> Bool
```

## `descCon`

_descCon: description-constructor introduction — `descCon D i d` builds an element of `μ I D i` from payload `d` matching `D`'s shape at index `i`._

```
descCon : Hoas -> Hoas -> Hoas -> Hoas  -- D, index, payload
```

Used internally by the elaborator to emit `mu` carriers from
interpreted payloads. Surface code building inductive values
typically routes through generated constructors
(`zero`/`succ`/`true_`/`nil`/etc.) which call `descCon` with
the right payload shape. Direct use is for advanced
ornament-bridging code.

## `descDesc`

_descDesc: levitated description-of-descriptions — `descDesc I k` is the description whose μ-carrier is `Desc^k I`; foundational for description encoding._

```
descDesc : Hoas -> Level -> Hoas  -- I, k
```

The plus-tree of `descDesc` has five summands corresponding
to the description constructors (`retI`, `descArg`, `recI`,
`piI`, `plusI`). Every encoded HOAS description elaborates
through `descDesc` so each `VDescCon` value carries its
constructor tag explicitly. Universe-polymorphic over `k`.

## `descElim`

_descElim: encoded description eliminator — `descElim I k L motive onRet onArg onRec onPi onPlus scrut` walks the cascade over `descDesc I k`'s plus-tree to dispatch on `scrut`'s constructor summand._

```
descElim : Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

The deep machinery for analysing description shapes. Each
`on*` callback handles one summand of the description
encoding. Surface code rarely needs this directly — `descInd`
is the friendlier face for value-level induction; `descElim`
is needed for type-level dispatch over description shape
(e.g. inside ornament machinery).

## `descInd`

_descInd: description-induction principle — `descInd D motive step i scrut` eliminates `scrut : μ I D i` against motive `Q : ∀i:I. μ I D i -> U`, using `step` to handle each summand with its inductive hypotheses._

```
descInd : Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- D, motive, step, index, scrut
```

Generic indexed induction. The `step` argument receives the
index, the payload, and the inductive hypotheses (`allD`-
wrapped). Generated eliminators like `NatDT.elim`,
`ListDT.elim` are pre-applied specialisations of `descInd`.

## `descPi`

_descPi: ⊤-slice piI alias — `descPi k S D` quantifies over sort `S` and continues with `D` under a constant-index function; the index-of-payload defaults to `ttPrim`._

```
descPi : Level -> Hoas -> Hoas -> Hoas  -- k, sort, continuation
```

## `descRec`

_descRec: ⊤-slice recI alias — `recI unitPrim 0 ttPrim D`; adds a ⊤-indexed recursive child to a description._

```
descRec : Hoas -> Hoas  -- continuation
```

## `descRet`

_descRet: ⊤-slice retI alias — `retI unitPrim 0 ttPrim`; the standard leaf of a ⊤-indexed description, used by prelude descriptions like `natDesc`._

```
descRet : Hoas
```

## `elab`

_elab: closed-term HOAS-to-Tm compiler — lowers a HOAS term from depth 0, runs meta-aware synthesis + zonking, and surfaces unsolved metas as a throw at the elaborator boundary._

```
elab : Hoas -> Tm
```

## `elab2`

_elab2: pair-producing elaborator — runs `elab` and `sourceMapOf` together, returning `{ tm, sourceMap }`; used by the diagnostic shell which consumes both outputs._

```
elab2 : Hoas -> { tm : Tm, sourceMap : SourceMap }
```

## `embedTm`

_embedTm: opaque HOAS carrier for a closed kernel `Tm` — `embedTm tm` wraps an already-elaborated term so it can sit inside a surrounding HOAS tree; `elaborate` returns the carried `tm` verbatim regardless of binding depth._

```
embedTm : Tm -> Hoas
```

Use when a pre-built Tm needs to flow back through the HOAS
surface. For Val embedding, prefer `H.litVal` (or
`fx.tc.elaborate.embedVal`), which reflects the Val directly
in O(1) without the `quote 0` walk.

Soundness depends on the carried `Tm` being closed under the
binders surrounding the embed site.

Elaborates via the `pre-elab` rule in `tc/hoas/lower.nix`.

## `empty`

_empty: HOAS empty type — alias for the kernel-primitive `emptyPrim`; the initial-object dual of `unit`._

```
empty : Hoas
```

## `eq`

_eq: HOAS propositional equality — `eq A a b` builds `EqDT A a b`, the levitated identity type over a sort `A`; `refl` introduces, `j` eliminates._

```
eq : Hoas -> Hoas -> Hoas -> Hoas
```

## `eqCongSucc`

_eqCongSucc: congruence of `suc` — `eqCongSucc m n e : Eq Nat (suc m) (suc n)` given `e : Eq Nat m n`. bootJ at motive `λx _. Eq Nat (suc m) (suc x)`; base case satisfied by `bootRefl`._

```
eqCongSucc : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, eq
```

## `eqDT`

_eqDT: prelude equality type — `eqDT A a b` is `μ A (eqDesc A a) b`, the indexed datatype carrier of equality at sort `A`._

```
eqDT : Hoas -> Hoas -> Hoas -> Hoas  -- A, lhs, rhs
```

## `eqDTToEq`

_eqDTToEq: datatype equality → bootstrap equality — `eqDTToEq A a b x` extracts a `bootEq A a b` witness from `x : eqDT A a b` via descInd at motive `Q i x = bootEq A a i`._

```
eqDTToEq : Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- A, lhs, rhs, x
```

## `eqDesc`

_eqDesc: prelude equality description — `eqDesc A a` builds the single-constructor retI-only description of `EqDT A a : A -> U`, used as the carrier description of equality at sort `A`._

```
eqDesc : Hoas -> Hoas -> Hoas  -- A, lhs
```

## `eqInjSucc`

_eqInjSucc: injectivity of `suc` — `eqInjSucc m n e : Eq Nat m n` given `e : Eq Nat (suc m) (suc n)`. bootJ at motive `λx _. Eq Nat m (predNat x)`; base case `Eq Nat m m` via β-reduction of `predNat (suc m)`._

```
eqInjSucc : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, eqSucc
```

## `eqIsoBwd`

_eqIsoBwd: backward leg of the eq ↔ eqDT iso — proves `bootEq (eqDT A a b) (eqToEqDT (eqDTToEq x)) x`; descInd on `x` reduces to the diagonal via inner J transport._

```
eqIsoBwd : Hoas -> Hoas -> Hoas -> Hoas  -- A, lhs, rhs
```

## `eqIsoFwd`

_eqIsoFwd: forward leg of the eq ↔ eqDT iso — proves `bootEq (bootEq A a b) (eqDTToEq (eqToEqDT e)) e`; J on `e` collapses both sides at the base case._

```
eqIsoFwd : Hoas -> Hoas -> Hoas -> Hoas  -- A, lhs, rhs
```

## `eqRefutSuccZero`

_eqRefutSuccZero: McBride no-confusion — `eqRefutSuccZero m e : void` refutes `e : Eq Nat (suc m) zero`. bootJ at motive `λx _. natCaseU void unit x`; base `tt` at unit, result `void` at zero._

```
eqRefutSuccZero : Hoas -> Hoas -> Hoas  -- m, eq
```

## `eqRefutZeroSucc`

_eqRefutZeroSucc: symmetric McBride no-confusion — `eqRefutZeroSucc n e : void` refutes `e : Eq Nat zero (suc n)`. bootJ at motive `λx _. natCaseU unit void x`._

```
eqRefutZeroSucc : Hoas -> Hoas -> Hoas  -- n, eq
```

## `eqToEqDT`

_eqToEqDT: bootstrap equality → datatype equality — `eqToEqDT A a b e` converts `e : bootEq A a b` to `eqDT A a b` via J transporting `reflDT` along the witness._

```
eqToEqDT : Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- A, lhs, rhs, eq
```

## `everywhereD`

_everywhereD: induction-hypothesis constructor — `everywhereD level I D K X M ih i d` builds the `allD …` witness by applying `ih` at every recursive subposition._

```
everywhereD : Level -> Hoas -> Hoas -> Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

## `false_`

_false_: HOAS `Bool` constructor `false` — generated by `BoolDT`; corresponds to the left summand of bool-as-`Sum Unit Unit`._

```
false_ : Hoas
```

## `field`

_field: HOAS datatype field declarator — `field name type` declares a non-recursive constructor field; the macro routes through `descArg`._

```
field : String -> Hoas -> { name; type; }
```

## `fieldAt`

_fieldAt: universe-polymorphic field declarator — `fieldAt name level type` declares a field at an explicit sort level._

```
fieldAt : String -> Level -> Hoas -> { name; type; level; }
```

## `fieldD`

_fieldD: dependent-field declarator — `fieldD name type indexFn` declares a field whose type can depend on prior fields via the index function._

```
fieldD : String -> Hoas -> (Hoas -> Hoas) -> { name; type; indexFn; }
```

## `fin`

_fin: prelude `Fin` type family — forwarder for `FinDT.T`; `app fin n` is the type of natural numbers strictly less than `n`._

```
fin : Hoas  -- application yields fin n : Hoas
```

## `finDesc`

_finDesc: prelude `Fin` description — forwarder for `FinDT.D`, the indexed description of the finite-natural family `Fin : nat -> U`._

```
finDesc : Hoas
```

## `finElim`

_finElim: prelude `Fin` eliminator — `finElim k P Pz Ps n x` discharges `x : fin n` against motive `P : ∀n:nat. fin n -> U(k)` with branches for fzero / fsuc._

```
finElim : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

## `floatLit`

_floatLit: HOAS Float literal — `floatLit f` lifts a Nix float to a kernel `floatLit` Tm checkable against `float_`._

```
floatLit : Float -> Hoas
```

## `float_`

_float_: kernel-primitive `Float` type — Nix-meta floats axiomatised at the kernel level; literals enter via `floatLit`._

```
float_ : Hoas
```

## `fnLit`

_fnLit: HOAS Function-literal marker — placeholder term checkable against `function_`; the Nix function is not embedded in the kernel term._

```
fnLit : Hoas
```

## `forall`

_forall: HOAS Π-type former — `forall name dom body` builds `Π(name:dom). body` with `body` a Nix function receiving the bound variable as a HOAS term._

```
forall : String -> Hoas -> (Hoas -> Hoas) -> Hoas
```

The body is a Nix function so the binder is a real Nix-level
variable inside the user's scope. `elaborate` converts it to a
de Bruijn `Tm` with the correct index. Chains of `forall` are
elaborated iteratively via `genericClosure`, so deeply-nested
Π-types are stack-safe to depths of 8000+. The `name` is
cosmetic — used only in error messages and never in equality
checking.

## `fst_`

_fst_: HOAS Σ-pair first projection — extracts the left component; reduces by π₁ during normalisation when the argument is a `pair`._

```
fst_ : Hoas -> Hoas
```

## `fsuc`

_fsuc: prelude `Fin` successor constructor — `fsuc k` lifts `k : fin m` to `succ k : fin (succ m)`; predecessor inferred._

```
fsuc : Hoas -> Hoas  -- fin-predecessor
```

## `function_`

_function_: kernel-primitive `Function` type — opaque Nix function axiomatised at the kernel level; literal-only entry via `fnLit`._

```
function_ : Hoas
```

## `functionalCompose`

_functionalCompose: compose two functional ornaments `outer` over `inner`, producing a functional ornament whose section threads through both `chooseIndex`/`section` pipelines._

```
functionalCompose : FunctionalOrnament -> FunctionalOrnament -> FunctionalOrnament
```

## `functionalLawDiagnosticRecords`

_functionalLawDiagnosticRecords: run every check in `F.laws.checks`, collecting structured diagnostics for every law that fails to evaluate or returns non-`true`; total._

```
functionalLawDiagnosticRecords : FunctionalOrnament -> [Diagnostic]
```

## `functionalLawDiagnostics`

_functionalLawDiagnostics: human-readable string forms of `functionalLawDiagnosticRecords` for surfacing law-check failures in test output and error reports._

```
functionalLawDiagnostics : FunctionalOrnament -> [String]
```

## `functionalOrnament`

_functionalOrnament: package `{ ornament, chooseIndex, section, indexProof?, laws?, meta? }` into a validated `FunctionalOrnament` record, the section/builder bundle that bridges base producers to ornamented outputs._

```
functionalOrnament : { ornament, chooseIndex, section, indexProof?, laws?, meta? } -> FunctionalOrnament
```

## `functionalOrnamentDiagnosticRecords`

_functionalOrnamentDiagnosticRecords: total structured diagnostics describing every missing / ill-typed field of a candidate `functionalOrnament` spec; returns `[]` when the spec is valid._

```
functionalOrnamentDiagnosticRecords : Attrs -> [Diagnostic]
```

## `functionalOrnamentDiagnostics`

_functionalOrnamentDiagnostics: human-readable strings derived from `functionalOrnamentDiagnosticRecords` for surfacing in error messages and test assertions._

```
functionalOrnamentDiagnostics : Attrs -> [String]
```

## `fzero`

_fzero: prelude `Fin` zero constructor — `fzero : fin (succ m)`; predecessor inferred from the expected type._

```
fzero : Hoas
```

## `iff`

_iff: propositional biconditional — `iff P Q := (P → Q) × (Q → P)` per HoTT Book, section 1.7. Built as `and (P→Q) (Q→P)`._

```
iff : Hoas -> Hoas -> Hoas
```

## `implicitApp`

_Implicit application — caller passes implicit explicitly. Same kernel Tm as `app`, plus `_plicity` sidecar._

```
Hoas -> Hoas -> Hoas
```

## `implicitForall`

_Implicit Π-binder. Same kernel Tm as `forall`, plus `_plicity` sidecar._

```
String -> Hoas -> (Hoas -> Hoas) -> Hoas
```

## `implicitLam`

_Implicit λ-binder. Same kernel Tm as `lam`, plus `_plicity` sidecar._

```
String -> Hoas -> (Hoas -> Hoas) -> Hoas
```

## `ind`

_ind: HOAS `Nat` induction principle wrapper — `ind k P B S n` runs `NatDT.elim k` after binding motive `P`, base `B`, and step `S` at their required types._

```
ind : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- k, motive, base, step, scrut
```

The motive `P : nat -> U(k)` may depend on the scrutinee; for
constant motives drop to `tc.verified.match` which auto-
generates `λ_:nat.resultTy`. The wrapper inserts three `let_`
bindings before the application spine so the kernel can infer
each leg of the dependent application chain. Level `k`
accepts a Nix Int, a HOAS Level term, or a kernel Tm.

## `inferHoas`

_inferHoas: HOAS-driven type inference — `inferHoas termHoas` elaborates and runs the kernel `infer` rule, returning `{ term, type }` or a structured Error._

```
inferHoas : Hoas -> { term : Tm, type : Val } | Error
```

Complement to `checkHoas` for the synthesis direction. Many
HOAS forms are inference-friendly (annotated values,
applications with inferable heads); pure inference fails on
checking-only forms like bare lambdas or data constructors
without an enclosing annotation.

## `inl`

_inl: HOAS sum left-injection — `inl v` builds `Left v : Sum A B`; level, leftTy, rightTy inferred. Alias of `inlAt` post-implicit-migration._

```
inl : Hoas -> Hoas  -- value
```

## `inr`

_inr: HOAS sum right-injection — `inr v` builds `Right v : Sum A B`; level, leftTy, rightTy inferred. Alias of `inrAt` post-implicit-migration._

```
inr : Hoas -> Hoas  -- value
```

## `intEq`

_intEq: HOAS kernel int equality — `intEq a b` produces a `bool` HOAS term; reflects the `mkIntEq` primitive (host `==`)._

```
intEq : Hoas -> Hoas -> Hoas
```

## `intLe`

_intLe: HOAS kernel int order — `intLe a b` produces a `bool` HOAS term; reflects the `mkIntLe` primitive (host `<=`)._

```
intLe : Hoas -> Hoas -> Hoas
```

## `intLit`

_intLit: HOAS Int literal — `intLit n` lifts a Nix integer to a kernel `intLit` Tm checkable against `int_`._

```
intLit : Int -> Hoas
```

## `int_`

_int_: kernel-primitive `Int` type — Nix-meta integers axiomatised at the kernel level; distinct from `nat`, which is the description-derived `Nat`._

```
int_ : Hoas
```

## `interpD`

_interpD: description interpreter — `interpD level I D X i` produces the payload type `⟦D⟧ X i` at level `level`, the fibre over index `i` when the recursive position is filled by `X`._

```
interpD : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- level, I, D, X, i
```

## `intz`

_intz: prelude `IntZ` type — `IntZDT.T`. Literature-canonical 2-constructor inductive integer with unique representation._

```
intz : Hoas
```

## `intzDecode`

_intzDecode: sign-erasing payload extractor `intz -> Nat`. `intzPos n` and `intzNegSucc n` both yield `n`. Used as the bootJ motive discriminator in `intzPosInjective` / `intzNegSuccInjective`._

```
intzDecode : Hoas
```

## `intzDesc`

_intzDesc: prelude `IntZ` description — `IntZDT.D`. Two-summand description with one Nat field per constructor (`pos` / `negSucc`)._

```
intzDesc : Hoas
```

## `intzElim`

_intzElim: prelude `IntZ` eliminator — `intzElim k Q onPos onNegSucc z` runs `IntZDT.elim k`; the motive `Q : intz -> U(k)` may depend on the scrutinee. Mirrors `boolElim`'s shape with two payload-carrying case branches over a Nat field each._

```
intzElim : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- k, motive, onPos, onNegSucc, scrut
```

## `intzLe`

_intzLe: prelude `IntZ` ordering type-family — `intzLe m n : U(0)` follows Agda `Data.Integer.Base._≤_` four cases: pos-pos delegates to Nat `le`; pos-negSucc is `void` (positives never ≤ negatives); negSucc-pos is `unit` (negatives always ≤ positives); negSucc-negSucc flips arguments and delegates back to Nat `le` (negSucc is monotonically decreasing in its argument)._

```
intzLe : Hoas -> Hoas -> Hoas  -- m, n
```

## `intzLit`

_intzLit: Nix-meta bridge from a Nix integer to `IntZ` — `intzLit n` returns `intzPos (natLit n)` for `n >= 0` and `intzNegSucc (natLit (-n - 1))` for `n < 0`. Boundary cases: `intzLit 0 = intzPos 0`; `intzLit (-1) = intzNegSucc 0`._

```
intzLit : Int -> Hoas
```

## `intzNegSucc`

_intzNegSucc: prelude `IntZ` negative constructor — `intzNegSucc n : intz` encodes the integer `-(n+1)` for `n : Nat`. `intzNegSucc 0` is `-1`._

```
intzNegSucc : Hoas -> Hoas  -- n
```

## `intzNegSuccCong`

_intzNegSuccCong: congruence of `intzNegSucc` — `intzNegSuccCong m n e : Eq IntZ (negSucc m) (negSucc n)` lifts `e : Eq Nat m n`._

```
intzNegSuccCong : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, natEq
```

## `intzNegSuccInjective`

_intzNegSuccInjective: symmetric injectivity of `intzNegSucc` via the same `intzDecode` motive._

```
intzNegSuccInjective : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, intzEq
```

## `intzPos`

_intzPos: prelude `IntZ` non-negative constructor — `intzPos n : intz` encodes the integer `n` for `n : Nat`. `intzPos 0` is the canonical zero._

```
intzPos : Hoas -> Hoas  -- n
```

## `intzPosCong`

_intzPosCong: congruence of `intzPos` — `intzPosCong m n e : Eq IntZ (pos m) (pos n)` lifts `e : Eq Nat m n`. bootJ at motive `λx _. Eq IntZ (pos m) (pos x)`; mirrors `eqCongSucc`._

```
intzPosCong : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, natEq
```

## `intzPosInjective`

_intzPosInjective: injectivity of `intzPos` — `intzPosInjective m n e : Eq Nat m n` from `e : Eq IntZ (pos m) (pos n)`. bootJ at motive `λx _. Eq Nat m (intzDecode x)`; β on the decoder collapses base case to `Eq Nat m m`._

```
intzPosInjective : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, intzEq
```

## `isLeafOrn`

_isLeafOrn: predicate identifying leaf functional ornaments via the `_leafOrnTag = "leaf-ornament"` tag._

```
isLeafOrn : Value -> Bool
```

## `j`

_j: HOAS J-eliminator for `EqDT` — `j A a P base b e` discharges `e : EqDT A a b` against motive `P : ∀x:A. EqDT A a x -> U`, computing the goal type at `b`._

```
j : Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- type, lhs, motive, base, rhs, eq
```

The classic Martin-Löf J: given a base case at the diagonal
(`base : P a refl`), transports along any equality. Used by
`transNat`, `congSuc`, `maxSucDom`, `eqToEqDT`, etc. The
motive must accept both the right-hand side and the equality
term; for substitution-only patterns, write a constant-in-eq
motive `λx _. ...`.

## `just`

_just: HOAS Maybe just-injection — `just innerTy v` is `inl v : maybe innerTy`._

```
just : Hoas -> Hoas -> Hoas  -- innerTy, value
```

## `justAt`

_justAt: universe-polymorphic Maybe just-injection — `justAt k innerTy v` is `inl v : maybeAt k innerTy`._

```
justAt : Level -> Hoas -> Hoas -> Hoas  -- level, innerTy, value
```

## `lam`

_lam: HOAS lambda — `lam name dom body` builds `λ(name:dom). body` with `body` a Nix function receiving the bound variable; the principal term-binding form._

```
lam : String -> Hoas -> (Hoas -> Hoas) -> Hoas
```

Body is a Nix function, so the variable binding flows through
Nix's own scope. `elaborate` produces a de Bruijn `Tm` with
index 0 for the innermost binder. Chains of `lam` are
elaborated iteratively (stack-safe to 8000+). Use `opaqueLam`
when wrapping a non-HOAS Nix function for which kernel
checking would otherwise require recovering structure.

## `le`

_le: prelude `Le` curried type family — `le m n` is the type of proofs that `m ≤ n` over `Nat`. The Agda `Data.Nat.Base._≤_` inductive predicate (z≤n / s≤s constructors)._

```
le : Hoas -> Hoas -> Hoas  -- m, n
```

## `leDesc`

_leDesc: prelude `Le` description — forwarder for `LeDT.D`, the indexed description of the order family `Le : Σ Nat (_: Nat) -> U` (curried at surface as `le m n`)._

```
leDesc : Hoas
```

## `leElim`

_leElim: prelude `Le` eliminator with curried-motive adapter — `leElim K P Pz Ps m n pf` discharges `pf : le m n` against motive `P : (m n : nat) -> le m n -> U(K)` with branches for `leZ` / `leSS`. Internally adapts the Σ-indexed motive of `LeDT.elim`._

```
leElim : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

## `leInjSS`

_leInjSS: injectivity of `leSS` — `leInjSS m n pf : Le m n` given `pf : Le (suc m) (suc n)`. leElim at motive `λm' n' _. Le (predNat m') (predNat n')`; leZ fills via `leZ ∘ predNat`, leSS fills with the recursive witness directly (via β on `predNat (suc _)`)._

```
leInjSS : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, leSuccSucc
```

## `leRefutSuccZero`

_leRefutSuccZero: refutation of `Le (suc m) zero` — leElim at motive `λm' n' _. natCaseU unit (natCaseU void unit n') m'`; both leZ and leSS case targets collapse to `unit`, while the refutation target at (suc m, 0) collapses to `void`._

```
leRefutSuccZero : Hoas -> Hoas -> Hoas  -- m, leProof
```

## `leSS`

_leSS: prelude `Le` step constructor (s≤s) — `leSS lemn : Le (suc m) (suc n)` for `lemn : Le m n`; `m`, `n` inferred. Lifts ≤-witnesses through simultaneous successor._

```
leSS : Hoas -> Hoas  -- lemn
```

## `leZ`

_leZ: prelude `Le` base constructor (z≤n) — `leZ : Le 0 n`; bound `n` inferred. Decidability witness for `decideLeNat 0 n`._

```
leZ : Hoas
```

## `leafOrnament`

_leafOrnament: constructor for a *leaf functional ornament* — a refinement of a primitive HOAS type former (one with `_htag ≠ "mu"`) carrying Nix-meta `forget : Refined → Base` and `section : Base → Refined`. The leaf case is the literature-faithful specialisation of Dagand–McBride 2014 (JFP) functional ornaments to type formers without a μ-encoded description. The canonical instance is `thunkOrnament`._

```
leafOrnament : { primitive : HoasType, forget : Refined -> Base, section : Base -> Refined, sectionProof? : Refined -> Bool, meta? : Attrs } -> LeafOrnament
```

## `leafOrnamentDiagnosticRecords`

_leafOrnamentDiagnosticRecords: total structured diagnostics for a candidate leaf-ornament spec — codes `leaf.invalid-spec | leaf.missing-{primitive,forget,section} | leaf.invalid-{primitive,forget,section,section-proof}`._

```
leafOrnamentDiagnosticRecords : Attrs -> [Diagnostic]
```

## `leafOrnamentDiagnostics`

_leafOrnamentDiagnostics: human-readable text forms of `leafOrnamentDiagnosticRecords` for surfacing in error messages and test assertions._

```
leafOrnamentDiagnostics : Attrs -> [String]
```

## `let_`

_let_: HOAS let binding — `let_ name ty val body` builds `let name : ty = val in body` with `body` a Nix function receiving the bound variable._

```
let_ : String -> Hoas -> Hoas -> (Hoas -> Hoas) -> Hoas
```

Used internally by eliminator wrappers (`ind`, `listElim`,
`sumElim`) to bind motive / base / step at their required
types before the application spine, making each subterm
inferable. User code typically uses `let_` to share
subexpressions or to name intermediate values for clarity.

## `level`

_level: HOAS universe-level type former — inhabits `U(0)`; lets users quantify over universes via `forall "k" level (k: …)` and build level expressions inline._

```
level : Hoas
```

## `levelMax`

_levelMax: HOAS Level join — `levelMax l m` produces `max(l, m)`; the semilattice operation used by `descArg` / `descPi` and the universe of dependent products._

```
levelMax : Hoas -> Hoas -> Hoas
```

## `levelSuc`

_levelSuc: HOAS Level successor — `levelSuc l` produces `l + 1`; used to build closed level expressions and inside `congSuc` for Eq-on-Level transport._

```
levelSuc : Hoas -> Hoas
```

## `levelZero`

_levelZero: HOAS Level constant `0` — the base universe level; combines with `levelSuc` / `levelMax` to form arbitrary closed level expressions._

```
levelZero : Hoas
```

## `listDesc`

_listDesc: prelude `List` description constructor — `listDesc A` produces the two-summand description `descRet + descArg A (_: descRec descRet)` of `List A`._

```
listDesc : Hoas -> Hoas
```

## `listElim`

_listElim: HOAS list eliminator wrapper — `listElim k A P N C xs` runs `ListDT.elim k A` after binding motive / nil-branch / cons-step at their required types._

```
listElim : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- k, A, motive, onNil, onCons, scrut
```

The cons step has type `∀h:A. ∀t:listOf A. ∀_:P t. P (cons h t)`
— the inductive hypothesis is the recursive call's result.
For constant motives use `tc.verified.matchList`. The level
argument threads into the motive's codomain universe.

## `listOf`

_listOf: HOAS list type former — `listOf elemTy` is `μ Unit listDesc tt` at element type `elemTy`; the description-derived counterpart to Nix-native lists._

```
listOf : Hoas -> Hoas
```

## `listOfAt`

_listOfAt: universe-polymorphic list type former — `listOfAt level A` builds `List A` at the given universe level, used when the homogeneous-level `listOf` cannot carry an element type above U(0)._

```
listOfAt : Hoas -> Hoas -> Hoas  -- level, A
```

## `litVal`

_litVal: closed-Val splice — `litVal v` reflects a closed kernel Val into HOAS without structural reconstruction; `eval ρ (mkLitVal v) = v` independent of ρ. O(1) Val→HOAS lift, contrasted with `embedTm (quote 0 v)` which is O(size v)._

```
litVal : Val -> Hoas
```

Splice in the sense of two-level type theory (Kovács, POPL 2024;
Annenkov–Capriotti–Kraus–Sattler 2019): reflects a value from the
semantic domain back into syntax with eval as the identity. Sound
iff the carried Val is closed — `eval` discards the environment,
so any free de Bruijn level would never resolve.

The canonical Val→HOAS lift in the bridge; replaces the
`embedTm (quote 0 v)` composition when v will only be re-evaluated.

## `lower`

_lower: depth-parameterised HOAS-to-Tm compiler — `lower depth h` converts a HOAS term to its de Bruijn `Tm` representation; `depth` is the binding level at the call site._

```
lower : Int -> Hoas -> Tm
```

The principal HOAS-side compilation entry. Binding chains are
lowered iteratively via `genericClosure` for stack safety
to 8000+ depth. Use directly when controlling the binding
depth (e.g. when re-lowering an open HOAS subterm). For
the closed-term case, prefer `elab` which fixes `depth = 0`.

## `maxSucDom`

_maxSucDom: Level-max-suc transport — proof of `∀a b. Eq Level (max a b) b -> Eq Level (max a (suc b)) (suc b)`; lifts max-bound witness through suc on the right operand._

```
maxSucDom : Hoas
```

## `maybe`

_maybe: HOAS optional type — `maybe inner` is `Sum inner Unit`; left payload carries a value, right marks absence._

```
maybe : Hoas -> Hoas
```

## `maybeAt`

_maybeAt: universe-polymorphic optional — `maybeAt k inner` is `Sum inner (LiftAt 0 k Unit)` at level k; `maybe` is the level-zero default._

```
maybeAt : Level -> Hoas -> Hoas  -- level, inner
```

## `mu`

_mu: ⊤-slice inductive carrier — alias for `muI unitPrim D i`; the unit-indexed special case used by prelude datatypes like nat, list, bool._

```
mu : Hoas -> Hoas -> Hoas  -- D, i
```

## `nat`

_nat: HOAS `Nat` type former — generated by `NatDT.T` from the macro-derived natural-number datatype; serves as the index sort for vector / list-length families._

```
nat : Hoas
```

## `natCaseU`

_natCaseU: nat-case at the universe level — `natCaseU A B` is `λn:nat. case n { zero => A; succ _ => B; }`; built on `descInd nat.D` with sum-branching on the per-constructor payload._

```
natCaseU : Hoas -> Hoas -> Hoas  -- zeroBranch, succBranch
```

The discriminator's result type is `U(0)` regardless of
scrutinee; the inductive hypothesis is discarded since
discrimination is value-shape-driven, not recursive. Used by
`vhead` to make the vnil/vcons branches target different
types (`unit` vs the element type), and by `absurdFin0` to
target the goal type at zero and `Unit` at succ.

## `natDesc`

_natDesc: prelude `Nat` description — `descRet + descRec descRet`; the canonical two-summand description of natural numbers as zero + succ(Nat)._

```
natDesc : Hoas
```

## `natLit`

_natLit: Nix integer to HOAS Nat — `natLit n` builds `succ^n zero` as a HOAS term; convenience wrapper around iterated `succ` application._

```
natLit : Int -> Hoas
```

## `natPredCase`

_natPredCase: nat-case with predecessor-dependent succ branch — `natPredCase A n` returns `unit` at zero and `vec A m` at `succ m`; generalises `natCaseU` to payload-dependent succ cases._

```
natPredCase : Hoas -> Hoas  -- elemTy
```

Used by `vtail` to build the vecElim motive
`P n xs = natPredCase A n` so the vnil branch targets `unit`
(filled by `tt`) and the vcons branch targets `vec A pred`
(filled by the tail). Implementation extracts the
predecessor via `fst_ r` on the inr summand.

## `natToLevel`

_natToLevel: meta-level integer-to-Level helper — `natToLevel n` produces `levelSuc^n levelZero`; throws on non-Int input; emits closed Level syntax only._

```
natToLevel : Int -> Hoas
```

## `nil`

_nil: HOAS empty-list constructor — `nil : listOf A`; element type inferred from the expected type._

```
nil : Hoas
```

## `no`

_no: negative decidability witness — `no P r : dec P` for a refutation `r : not P`. Routes through the right injection of `P ⊎ ¬ P`._

```
no : Hoas -> Hoas -> Hoas  -- P, refutation
```

## `not`

_not: propositional negation — `not P := P → ⊥` per HoTT Book, section 1.7. Elaborates to a pi with `void` codomain._

```
not : Hoas -> Hoas
```

## `nothing`

_nothing: HOAS Maybe none-injection — `nothing innerTy` is `inr tt : maybe innerTy`._

```
nothing : Hoas -> Hoas  -- innerTy
```

## `nothingAt`

_nothingAt: universe-polymorphic Maybe none-injection — `nothingAt k innerTy` is `inr (lift tt) : maybeAt k innerTy`._

```
nothingAt : Level -> Hoas -> Hoas  -- level, innerTy
```

## `opaqueLam`

_opaqueLam: HOAS opaque-lambda wrapper — `opaqueLam nixFn piHoas` packages a non-HOAS Nix function with its declared Π-type; the kernel treats the body as an unverified trust boundary._

```
opaqueLam : (Any -> Any) -> Hoas -> Hoas
```

Use only when the body cannot be expressed as HOAS — e.g.
wrapping a recursion-irregular helper produced outside the
kernel. The elaborator emits `mkOpaqueLam`; the type-checker
cannot recover the body's HOAS shape, so it accepts the
declared `piHoas` without re-validation. Prefer `verifiedFn`
from `tc.verified` when the body IS expressible as HOAS — that
path keeps body verification.

## `or_`

_or_: propositional disjunction — `or_ P Q := P + Q` per HoTT Book, section 1.7. Trailing underscore avoids the Nix `or` keyword in identifier position (mirrors `true_` / `false_`)._

```
or_ : Hoas -> Hoas -> Hoas
```

## `ornArgInsert`

_ornArgInsert: argInsert-node spec for `ornI.node` — inserts a fresh `arg S` field absent from the base description; body binds the inserted witness recursively._

```
ornArgInsert : Tm -> (Tm -> OrnNode) -> { tag = "argInsert"; S; body }
```

## `ornArgKeep`

_ornArgKeep: argKeep-node spec for `ornI.node` — keeps a base `descArg S body` field unchanged in the ornament; body re-binds the same `s : S` recursively._

```
ornArgKeep : Tm -> (Tm -> OrnNode) -> { tag = "argKeep"; S; body }
```

## `ornBuild`

_ornBuild: build the ornamented value at index `i` from `baseValue` by invoking `F.section`; the canonical entry point for ornament construction from a base witness._

```
ornBuild : FunctionalOrnament -> Tm -> Tm -> Tm
```

## `ornCompose`

_ornCompose: vertical composition of ornaments — given `inner : I -> J` and `outer : J -> K`, produce `outer ∘ inner : I -> K`; sequential refinement._

```
ornCompose : Ornament -> Ornament -> Ornament  -- outer, inner
```

## `ornDesc`

_ornDesc: compile an `Ornament` to its annotated `Desc J` term — the levitated description of the ornamented datatype, ready for `muI` / `interpD`._

```
ornDesc : Ornament -> Tm  -- Desc J
```

## `ornForget`

_ornForget: produce the forgetting morphism `mu (ornDesc O) ~> mu (baseD O)`, mapping every ornamented value back to its underlying base-description value._

```
ornForget : Ornament -> Tm  -- J -> ornMu -> baseMu
```

## `ornI`

_ornI: master constructor of an `Ornament` over a base description, packaging `{ I, J, erase, baseD, node }` and optional level/meta into the canonical ornament record consumed by `ornDesc` / `ornMu` / `ornForget`._

```
ornI : { I, J, erase, baseD, node, level?, meta? } -> Ornament
```

## `ornId`

_ornId: identity ornament on `D : Desc I` — `forget` is the identity at every index; the unit of `ornCompose`. Recovers `D` as its own ornament._

```
ornId : Tm -> Tm -> Ornament  -- I, D
```

## `ornIndexProof`

_ornIndexProof: extract the `indexProof` slot of a functional ornament — the proof `i -> baseValue -> erase (chooseIndex i baseValue) ≡ i` certifying the section commutes with forget._

```
ornIndexProof : FunctionalOrnament -> (Tm -> Tm -> Tm)
```

## `ornLiftFold`

_ornLiftFold: alias for `ornPullback` specialised to folds — composes a base fold with `ornForget` so it runs on ornamented carriers without re-deriving the algebra._

```
ornLiftFold : Ornament -> (Tm -> Tm) -> Tm -> Tm  -- resultTy, baseFold -> lifted
```

## `ornLiftProducer`

_ornLiftProducer: lift a base producer `baseFn` through a functional ornament `F` — run the producer on the base input, then build the ornamented output via `F.section`._

```
ornLiftProducer : FunctionalOrnament -> (Tm -> Tm) -> Tm -> Tm -> Tm
```

## `ornLiftTransform`

_ornLiftTransform: lift a base transform through paired input/output functional ornaments — forget the ornamented input, run the base transform, build the ornamented output._

```
ornLiftTransform : { input : OrnLike, output : FunctionalOrnament, fn } -> Tm -> Tm -> Tm -> Tm
```

## `ornMu`

_ornMu: build the ornamented `mu` at index `j`, i.e. `muI J (ornDesc O) j` — the carrier type of values living over the ornament at that index._

```
ornMu : Ornament -> Tm -> Tm  -- index in J yields kernel type
```

## `ornPiKeep`

_ornPiKeep: piKeep-node spec for `ornI.node` — keeps a Π-quantified field over `S`; `branch` supplies the base/ornament index functions and proof, defaulting to identity._

```
ornPiKeep : Tm -> (Tm | { baseF, ornF, proof }) -> OrnNode -> { tag = "piKeep"; S; tail; baseF; ornF; proof; l }
```

## `ornPlus`

_ornPlus: plus-node spec for `ornI.node` — sum of two ornament arms `left` and `right`, mirroring `descPlus` at the ornament level._

```
ornPlus : OrnNode -> OrnNode -> { tag = "plus"; left; right }
```

## `ornPullback`

_ornPullback: transport a base program `baseFn : I -> baseMu -> R(i)` along `ornForget`, yielding the same program over ornamented inputs at every J index._

```
ornPullback : Ornament -> (Tm -> Tm) -> Tm -> Tm  -- resultTy, baseFn -> lifted
```

## `ornRec`

_ornRec: rec-node spec for `ornI.node` — a recursive child at index `j` with proof `erase j ≡ baseIndex` and a `tail` ornament for the remainder of the constructor._

```
ornRec : Tm -> (Tm | { proof, baseIndex }) -> OrnNode -> { tag = "rec"; j; proof; baseIndex; tail }
```

## `ornRet`

_ornRet: ret-node spec for `ornI.node` — terminates an ornament arm at index `j` in J with a base-index witness `baseIndex` and proof `erase j ≡ baseIndex`._

```
ornRet : Tm -> Tm -> Tm -> { tag = "ret"; j; proof; baseIndex }
```

## `ornSection`

_ornSection: extract the `section` builder from a functional ornament — the function `i -> baseValue -> ornamentedValue` that realises the section morphism._

```
ornSection : FunctionalOrnament -> (Tm -> Tm -> Tm)
```

## `ornTargetIndex`

_ornTargetIndex: extract the `chooseIndex` slot of a functional ornament — the function `i -> baseValue -> J` that picks the ornamented index for each base input._

```
ornTargetIndex : FunctionalOrnament -> (Tm -> Tm -> Tm)
```

## `ornament`

_ornament: master surface — given a monomorphic generated `DataSpec` (`base`) and a constructor-by-constructor `spec`, produce the ornamented `Datatype` plus `forget` morphism._

```
ornament : DataSpec -> OrnamentSpec -> Datatype
```

## `ornamentDiagnosticRecords`

_ornamentDiagnosticRecords: total structured diagnostics covering every surface error in an ornament spec — missing constructors, unknown arms, malformed fields, out-of-order keeps._

```
ornamentDiagnosticRecords : DataSpec -> OrnamentSpec -> [Diagnostic]
```

## `ornamentDiagnostics`

_ornamentDiagnostics: human-readable text forms of `ornamentDiagnosticRecords` for surfacing in error messages and test assertions._

```
ornamentDiagnostics : DataSpec -> OrnamentSpec -> [String]
```

## `pair`

_pair: HOAS Σ-pair introduction — `pair fst snd` packages two HOAS values; the surrounding type annotation pins which Σ-type the pair inhabits._

```
pair : Hoas -> Hoas -> Hoas
```

## `path`

_path: kernel-primitive `Path` type — opaque Nix path axiomatised at the kernel level; literal-only entry via `pathLit`._

```
path : Hoas
```

## `pathLit`

_pathLit: HOAS Path-literal marker — placeholder term checkable against `path`; the Nix path is not embedded in the kernel term._

```
pathLit : Hoas
```

## `piField`

_piField: Π-typed field declarator — `piField name sort body` declares a function-typed field where every element of `sort` indexes into the body description._

```
piField : String -> Hoas -> (Hoas -> Hoas) -> { name; sort; body; pi; }
```

## `piFieldD`

_piFieldD: dependent Π-typed field — `piFieldD` extends `piField` with the ability for the body to depend on prior constructor fields._

```
piFieldD : String -> Hoas -> (Hoas -> Hoas -> Hoas) -> { name; sort; body; pi; indexFn; }
```

## `plicity`

_Plicity tag namespace: explicit/implicit values + predicates._

```
{ explicit : Plicity; implicit : Plicity; isPlicity : Any -> Bool; isImplicit : Plicity -> Bool; }
```

## `plus`

_plus: ⊤-slice description sum — alias for `plusI unitPrim 0 A B`; the standard form for combining prelude descriptions like nat = retI + recI(retI)._

```
plus : Hoas -> Hoas -> Hoas
```

## `predNat`

_predNat: saturating Nat predecessor — `predNat zero ≡ zero`, `predNat (suc m) ≡ m`. Built via `ind` with constant `nat` motive. Consumed by `eqInjSucc` and `leInjSS`._

```
predNat : Hoas  -- closed function nat -> nat
```

## `product`

_product: HOAS named single-constructor μ-datatype — `product name [H.field …]` is sugar for `datatype name [(con name fields)]`; returns the full DataSpec so deriveSchema/deriveDescriptor and validateValue work unchanged._

```
product : String -> [Field] -> DataSpec
```

The named parallel to `record` (anonymous, `.T`-only) and
`variant` (n-con sum). The single constructor's name is the
type name, since a product has no constructor to disambiguate.
Fields project flat, with no inner `value` wrapper. Use when
the domain type has a stable user-supplied name and consumers
need the full DataSpec (`.T`, `.cons`, `.<name>` ctor, `.elim`).

## `recField`

_recField: recursive-field declarator — `recField name indexFn` declares a recursive position whose target index is computed from prior fields._

```
recField : String -> (Hoas -> Hoas) -> { name; indexFn; recursive; }
```

Marks the field as a recursive child via `_recursive = true`,
routing through `descRec` rather than `descArg` in the
description-emission step. The `indexFn` extracts the target
index from prior fields, supporting indexed datatypes whose
recursive children reference different indices.

## `recFieldAt`

_recFieldAt: universe-polymorphic recursive-field declarator — `recFieldAt name level indexFn` with explicit level for the recursive position._

```
recFieldAt : String -> Level -> (Hoas -> Hoas) -> { name; indexFn; recursive; level; }
```

## `record`

_record: HOAS record type — `record [{name; type}…]` builds a mono-constructor μ-datatype whose single constructor takes the listed fields in order; surface for `v.field` projection._

```
record : [{ name : String; type : Hoas; }] -> Hoas
```

Compiled to a mono-constructor μ-datatype carrying `_dtypeMeta`
with one constructor named `mk` whose fields match the input
list. The type's canonical name is `Record{fieldName1, …}`
sorted alphabetically. Use `v.field recordTy "name" record` to
project a field by name; the eliminator is derived once and
reused across projections.

## `refinementPred`

_refinementPred: Σ-encoded refinement-predicate carrier `refinementPred dom predFn = Σ (x : dom) (Dec (predFn x))`. McBride & McKinna 2004 'The view from the left'. `predFn` is a Nix-meta `Hoas -> Hoas` predicate following the surface convention of `sigma` / `forall` / `lam`. Inhabitants pair a value with a decision proof; the decision procedure is supplied at the value level rather than encoded in the type._

```
refinementPred : Hoas -> (Hoas -> Hoas) -> Hoas  -- domain, predFn
```

## `refl`

_refl: HOAS reflexivity introduction for `EqDT` — emitted in check-mode against a goal `EqDT A a a`; the elaborator handles the level/index inference._

```
refl : Hoas
```

## `reflDT`

_reflDT: prelude equality reflexivity — `reflDT A a : eqDT A a a`; the canonical inhabitant of the diagonal._

```
reflDT : Hoas -> Hoas -> Hoas  -- A, value
```

## `reifyLevel`

_reifyLevel: HOAS Level → kernel Level Tm — converts a HOAS-side level expression (Int, level term, or already-reified Tm) to the kernel's canonical Level representation._

```
reifyLevel : Level -> Tm
```

## `retI`

_retI: indexed retI-constructor — `retI I k j` builds a `Desc^k I` leaf returning index `j`; level-polymorphic over `k`._

```
retI : Hoas -> Level -> Hoas -> Hoas  -- I, k, targetIndex
```

## `sigma`

_sigma: HOAS Σ-type former — `sigma name fst body` builds `Σ(name:fst). body`; the dependent-pair counterpart to `forall`._

```
sigma : String -> Hoas -> (Hoas -> Hoas) -> Hoas
```

Stack-safe like `forall` (iterative `genericClosure`
elaboration). Pairs enter via `pair`, project via `fst_` /
`snd_`. For records of more than two fields, prefer `record`
which is encoded as a mono-constructor μ-datatype with named
projections via `v.field`.

## `signsDiffer`

_signsDiffer: no-confusion refutation `(m n : Nat) -> Eq IntZ (pos m) (negSucc n) -> void`. McBride 2000 PhD, section 3.5 discriminator-motive technique applied to the IntZ sign discriminator (`unit` on `pos`, `void` on `negSucc`) plus `bootJ` transport._

```
signsDiffer : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, e
```

## `signsDifferRev`

_signsDifferRev: symmetric no-confusion refutation `(m n : Nat) -> Eq IntZ (negSucc m) (pos n) -> void`. Same discriminator-motive technique as `signsDiffer` with the `pos` / `negSucc` targets swapped._

```
signsDifferRev : Hoas -> Hoas -> Hoas -> Hoas  -- m, n, e
```

## `snd_`

_snd_: HOAS Σ-pair second projection — extracts the right component; reduces by π₂ during normalisation when the argument is a `pair`._

```
snd_ : Hoas -> Hoas
```

## `sourceMapOf`

_sourceMapOf: HOAS surface → SourceMap walker — produces a structural map from the HOAS term's positions to source-form metadata; consumed by the diagnostic shell to associate errors with source positions._

```
sourceMapOf : Hoas -> SourceMap
```

## `squash`

_squash: HOAS propositional truncation — `squash A` is the type `‖A‖` whose elements are all conv-equal; collapses A's content to mere inhabitation._

```
squash : Hoas -> Hoas
```

Two `squashIntro _` values inhabiting the same `squash A` are
conv-equal by definitional irrelevance — equality holds
without inspecting payloads. Use to express subsingleton
propositions or to enforce proof-irrelevance on otherwise
relevant data.

## `squashElim`

_squashElim: HOAS truncation eliminator — `squashElim A B f x` lifts `f : A -> squash B` over `x : squash A`; restricted to `squash`-typed motives so irrelevance is preserved._

```
squashElim : Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- A, B, f, x
```

Restricted to motives whose target is `squash B` — eliminating
out of a squash into a relevant type is forbidden (would
violate irrelevance). For relevant-target elimination, the
only path is constructing a derivation that requires no
inspection of the squashed value.

## `squashIntro`

_squashIntro: HOAS truncation introduction — `squashIntro a` wraps `a : A` into `squash A`; the resulting witness ignores the underlying value under conv._

```
squashIntro : Hoas -> Hoas
```

## `strEq`

_strEq: HOAS kernel string equality — `strEq a b` produces a `bool` HOAS term; reflects the `mkStrEq` primitive of the kernel._

```
strEq : Hoas -> Hoas -> Hoas
```

## `strLen`

_strLen: HOAS kernel string length — `strLen s` produces an `int_` HOAS term; reflects the `mkStrLen` primitive (host string length)._

```
strLen : Hoas -> Hoas
```

## `string`

_string: kernel-primitive `String` type — axiomatised; literals enter via `stringLit`, equality is decidable via `strEq`._

```
string : Hoas
```

## `stringLit`

_stringLit: HOAS String literal — `stringLit s` lifts a Nix string to a kernel `stringLit` Tm checkable against `string`._

```
stringLit : String -> Hoas
```

## `succ`

_succ: HOAS `Nat` successor — `succ n` builds `n + 1`; introduces `nat` at the `descRec descRet` summand._

```
succ : Hoas -> Hoas
```

## `sum`

_sum: HOAS coproduct type former — `sum A B` builds `A + B` via `SumDT.T` at the implicit base level; inhabitants enter via `inl` / `inr`._

```
sum : Hoas -> Hoas -> Hoas
```

## `sumDesc`

_sumDesc: prelude `Sum` description constructor — `sumDesc A B` produces the two-summand description `descArg A (_: descRet) + descArg B (_: descRet)` of `Sum A B`._

```
sumDesc : Hoas -> Hoas -> Hoas
```

## `sumElim`

_sumElim: HOAS sum eliminator wrapper — `sumElim k A B P L R s` runs `SumDT.elim k` at the base universe level; `L` and `R` are dependent on the injected payload._

```
sumElim : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- k, A, B, motive, onLeft, onRight, scrut
```

Calls `sumElimAt levelZero …` for the homogeneous-level
common case. For sums constructed via `inlAt` / `inrAt` at a
non-zero level, use `sumElimAt` directly with the matching
level. For constant motives use `tc.verified.matchSum`.

## `sup`

_sup: HOAS W-type constructor `sup s t` — supplies the node-shape `s` and the recursive-children family `t : pos s → W`._

```
sup : Hoas -> Hoas -> Hoas
```

## `surfacePlicity`

_Read the plicity sidecar, defaulting to explicit._

```
Any -> Plicity
```

## `thunk`

_thunk: generic deepSeq-safe carrier type former — `thunk a` is `{ _tag = "Thunk"; _force = _: a }`. Lazy structural check: walker verifies `_force` is a closure but does NOT invoke it; inner-type validation runs post-forget. Forget map: `t._force null`. Use as a payload type wherever values must survive trampoline `deepSeq` while remaining recoverable._

```
thunk : Hoas -> Hoas
```

## `thunkOrnament`

_thunkOrnament: derived leaf-functional-ornament constructor for `H.thunk inner` with `forget = forceThunk` and `section = mkThunk`. The functional ornament induced by `forceThunk : Thunk A → A` per Dagand–McBride 2014 (JFP), section 3, specialised to the primitive Thunk carrier from `fx.state.thunk`._

```
thunkOrnament : HoasType -> LeafOrnament
```

## `trans`

_trans: User-Eq transitivity — proof of `∀A x y z. Eq A x y -> Eq A y z -> Eq A x z`; one J application transporting `pxy` along `pyz`. Chains with `cong` to build diagram-chase witnesses without expanding either equality's RHS through the kernel._

```
trans : Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- A, x, y, z, pxy, pyz
```

## `true_`

_true_: HOAS `Bool` constructor `true` — generated by `BoolDT`; corresponds to the right summand of bool-as-`Sum Unit Unit`._

```
true_ : Hoas
```

## `tryAlgOrn`

_tryAlgOrn: total constructor — returns `{ ok, diagnostics, value? }` where `value` is the `algOrn`-built ornament when `ok`, otherwise diagnostics-only._

```
tryAlgOrn : Attrs -> { ok : Bool, diagnostics : [Diagnostic], value? : Ornament }
```

## `tryFunctionalOrnament`

_tryFunctionalOrnament: total constructor — returns `{ ok, diagnostics, value? }` where `value` is the built functional ornament when `ok`, otherwise diagnostics-only._

```
tryFunctionalOrnament : Attrs -> { ok : Bool, diagnostics : [Diagnostic], value? : FunctionalOrnament }
```

## `tryLeafOrnament`

_tryLeafOrnament: total constructor — returns `{ ok, diagnostics, value? }` where `value` is the built leaf ornament when `ok`, otherwise diagnostics-only._

```
tryLeafOrnament : Attrs -> { ok : Bool, diagnostics : [Diagnostic], value? : LeafOrnament }
```

## `tryOrnament`

_tryOrnament: total constructor — returns `{ ok, diagnostics, value? }` where `value` is the built ornamented datatype when `ok`, otherwise diagnostics-only._

```
tryOrnament : DataSpec -> OrnamentSpec -> { ok : Bool, diagnostics : [Diagnostic], value? : Datatype }
```

## `tt`

_tt: HOAS unit value — the unique inhabitant of `unit`; ⊤-slice convention places this at every retI leaf of description scaffolding._

```
tt : Hoas
```

## `u`

_u: HOAS universe former — `u level` builds `U(level)`, the universe of types at the given level; `level` accepts a Nix Int, a HOAS Level term, or a kernel Tm._

```
u : Level -> Hoas
```

## `unit`

_unit: HOAS unit type — alias for the kernel-primitive `unitPrim`; the ⊤-slice index sort for description machinery and refinement bound markers._

```
unit : Hoas
```

## `validateAlgOrn`

_validateAlgOrn: total predicate `{ ok, diagnostics }` over a candidate `algOrn` spec — checks every algebra arm against its description shape without throwing._

```
validateAlgOrn : Attrs -> { ok : Bool, diagnostics : [Diagnostic] }
```

## `validateFunctionalLaws`

_validateFunctionalLaws: total predicate `{ ok, diagnostics }` over a functional ornament's law-check bundle; reports which checks failed without throwing._

```
validateFunctionalLaws : FunctionalOrnament -> { ok : Bool, diagnostics : [Diagnostic] }
```

## `validateFunctionalOrnament`

_validateFunctionalOrnament: total predicate over candidate functional-ornament specs returning `{ ok, diagnostics }`; never throws, intended for upstream `try*` and surface validators._

```
validateFunctionalOrnament : Attrs -> { ok : Bool, diagnostics : [Diagnostic] }
```

## `validateLeafOrnament`

_validateLeafOrnament: total predicate `{ ok, diagnostics }` over a candidate leaf-ornament spec; rejects μ-encoded primitives, already-ornamented primitives, and missing/malformed forget/section/sectionProof fields._

```
validateLeafOrnament : Attrs -> { ok : Bool, diagnostics : [Diagnostic] }
```

## `validateOrnament`

_validateOrnament: total predicate `{ ok, diagnostics }` over `(base, spec)` for the user-facing `ornament` surface; never throws._

```
validateOrnament : DataSpec -> OrnamentSpec -> { ok : Bool, diagnostics : [Diagnostic] }
```

## `variant`

_variant: HOAS tagged-union type — `variant [{tag; type}…]` builds an n-constructor μ-datatype whose tags become single-field constructor names._

```
variant : [{ tag : String; type : Hoas; }] -> Hoas
```

Each branch becomes a single-field constructor named after the
tag, so a value `{ _tag = "Left"; value = v; }` walks via the
recovery `_tag` branch finding constructor "Left" and reading
its `value` field. The canonical type name is
`Variant{tag1, tag2, …}` with tags sorted alphabetically.

## `variantAt`

_variantAt: universe-polymorphic tagged-union — `variantAt k [{tag; type}…]` nests `sumAt k` over branches already at U(k); `variant` is the level-zero default._

```
variantAt : Level -> [{ tag : String; type : Hoas; }] -> Hoas
```

## `variantInject`

_variantInject: HOAS variant-value injection — `variantInject ty tag inner` produces the nested `inl/inr` chain that injects `inner` into `tag`'s branch of `ty`._

```
variantInject : Hoas -> String -> Hoas -> Hoas  -- variantTy, tag, value
```

## `variantInjectAt`

_variantInjectAt: universe-polymorphic variant-value injection — `variantInjectAt k ty tag inner` nests `inl/inr` at level k to inject `inner` into `tag`'s branch of `ty`._

```
variantInjectAt : Level -> Hoas -> String -> Hoas -> Hoas  -- level, variantTy, tag, value
```

## `vcons`

_vcons: prelude `Vec` cons constructor — `vcons x xs` prepends `x : A` to `xs : vec A m`, producing `vec A (succ m)`; element type and predecessor inferred._

```
vcons : Hoas -> Hoas -> Hoas  -- head, tail
```

## `vec`

_vec: prelude `Vec` type family — forwarder for `app VecDT.T A`; `app (vec A) n` is the type of vectors of length `n` carrying elements of type `A`._

```
vec : Hoas -> Hoas  -- elemTy
```

## `vecDesc`

_vecDesc: prelude `Vec` description — forwarder for `app VecDT.D A`; the indexed description of length-indexed vectors over element type `A`._

```
vecDesc : Hoas -> Hoas  -- elemTy
```

## `vecElim`

_vecElim: prelude `Vec` eliminator — `vecElim k A P Pn Pc n xs` discharges `xs : vec A n` against motive `P : ∀n:nat. vec A n -> U(k)`._

```
vecElim : Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

## `vhead`

_vhead: prelude `Vec` head extractor — `vhead A n xs` returns the first element of `xs : vec A (succ n)`; eliminator-driven via the `natCaseU unit A` motive._

```
vhead : Hoas -> Hoas
```

## `vnil`

_vnil: prelude `Vec` empty constructor — `vnil : vec A zero`; element type inferred._

```
vnil : Hoas
```

## `void`

_void: HOAS empty type — alias for `empty` / `emptyPrim`; the initial-object dual of `unit`, eliminated via `absurd`._

```
void : Hoas
```

## `vtail`

_vtail: prelude `Vec` tail extractor — `vtail A n xs` returns the tail of `xs : vec A (succ n)` at type `vec A n`; eliminator-driven via the `natPredCase A` motive._

```
vtail : Hoas -> Hoas
```

## `w`

_w: W-type former — generalised inductive type for trees with arbitrary branching; foundational for encoding finitely-branching datatypes outside the description layer._

```
w : Hoas -> Hoas -> Hoas  -- shapeTy, posFn
```

## `wDesc`

_wDesc: W-type description forwarder — alias for `WDT.D`, the description of W-type trees over shape S and position family pos._

```
wDesc : Hoas -> (Hoas -> Hoas) -> Hoas
```

## `wElim`

_wElim: W-type eliminator forwarder — alias for `WDT.elim`, the dependent recursor for W-type trees._

```
wElim : Level -> Hoas -> (Hoas -> Hoas) -> Hoas -> Hoas -> Hoas -> Hoas
```

## `withConLabel`

_withConLabel: attach a surrounding-constructor label to a description-encoding HOAS form — `withConLabel label form` adds `_conLabel = label`; conv-irrelevant._

```
withConLabel : String -> Hoas -> Hoas
```

Set by the `datatype` macro at each constructor's spine site,
so each summand carries its constructor name. Surfaces
through `descView`'s `.conLabel` field. Orthogonal to
`withDescLabel` (separate slot) so labeling a field-labeled
description with a constructor name doesn't overwrite the
field's identity.

## `withDescLabel`

_withDescLabel: attach a presentation label to a description-encoding HOAS form — `withDescLabel label form` adds `_label = label`; conv-irrelevant, idempotent under re-labeling._

```
withDescLabel : String -> Hoas -> Hoas
```

Surfaces back through `descView`'s `.label` field. Used by
renderers (pretty-printers, doc generators) to surface field
names without affecting type equality — two descriptions
differing only in labels are conv-equal. Orthogonal to
`withConLabel`, which lives in a separate `_conLabel` slot.

## `yes`

_yes: positive decidability witness — `yes P p : dec P` for a proof `p : P`. Routes through the left injection of `P ⊎ ¬ P`._

```
yes : Hoas -> Hoas -> Hoas  -- P, proof
```

## `zero`

_zero: HOAS `Nat` constructor — the natural-number zero; introduces `nat` at the `descRet` summand of `natDesc`._

```
zero : Hoas
```

## Sub-namespaces

- [`_internal`](/nix-effects/type-checker/hoas/_internal)

## Source

- [`src/tc/hoas/combinators.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/combinators.nix)
- [`src/tc/hoas/datatype.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/datatype.nix)
- [`src/tc/hoas/decidable.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/decidable.nix)
- [`src/tc/hoas/desc.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/desc.nix)
- [`src/tc/hoas/forced.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/forced.nix)
- [`src/tc/hoas/lower.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/lower.nix)
- [`src/tc/hoas/ornament.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/ornament.nix)
- [`src/tc/hoas/plicity.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/plicity.nix)
- [`src/tc/hoas/source_map.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/hoas/source_map.nix)



#### _internal


Unstable internal surface — boot-sum/boot-eq helpers, kernel-Tm encoders, and indexed-variant scaffolding; prefer SumDT/EqDT-generated forms in user code.

## `bootEq`

_bootEq: bootstrap propositional-equality type former at the description layer — `bootEq T a b` is the kernel-internal `Eq` used before EqDT is available. Prefer the SumDT/EqDT-generated `eq` for end-user code._

```
bootEq : Hoas -> Hoas -> Hoas -> Hoas  -- type, lhs, rhs
```

## `bootInl`

_bootInl: bootstrap left-injection at the description layer — `bootInl L R v` introduces a `boot-sum L R` from `v : L`. Used by the freer-monad-as-description encoding to build μ-values where no SumDT-generated `inl` applies._

```
bootInl : Hoas -> Hoas -> Hoas -> Hoas  -- L, R, v
```

## `bootInr`

_bootInr: bootstrap right-injection at the description layer — `bootInr L R v` introduces a `boot-sum L R` from `v : R`. See `bootInl`._

```
bootInr : Hoas -> Hoas -> Hoas -> Hoas  -- L, R, v
```

## `bootJ`

_bootJ: bootstrap J-eliminator at the description layer — `bootJ T a P b c eq` transports `b : P a a refl` along `eq : bootEq T a c` to `P a c eq`. Prefer EqDT-generated `j` for end-user code._

```
bootJ : Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- T, a, motive, base, c, eq
```

## `bootRefl`

_bootRefl: bootstrap reflexivity witness at the description layer — checkable against any `bootEq T a a`. Prefer EqDT-generated `refl` for end-user code._

```
bootRefl : Hoas
```

## `bootSum`

_bootSum: bootstrap binary coproduct type former at the description layer — `bootSum L R` is the kernel-internal `Sum` used before SumDT is available; arises inside `descPlus` interpretation._

```
bootSum : Hoas -> Hoas -> Hoas  -- L, R
```

## `bootSumElim`

_bootSumElim: bootstrap sum eliminator at the description layer — `bootSumElim L R P onL onR scrut` discharges `scrut : bootSum L R` to `P scrut`. Prefer SumDT-generated `sumElim` for end-user code._

```
bootSumElim : Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- L, R, motive, onLeft, onRight, scrut
```

## Sub-namespaces

- [`_encoders`](/nix-effects/type-checker/hoas/_internal/_encoders)
- [`_forced`](/nix-effects/type-checker/hoas/_internal/_forced)
- [`_indexed`](/nix-effects/type-checker/hoas/_internal/_indexed)



#### _encoders


Kernel-Tm and Val-level encoders for surface description combinators; consumed by `tc/eval` (descDescVal) and `tc/generic` (encodeDescXTm pre-evaluations).

## `__descDesc`

___descDesc: private internal-use alias for `descDesc` — exposed for the encoder cascade; surface code should use `descDesc`._

```
__descDesc : Hoas -> Level -> Hoas
```

## `descDescApp`

_descDescApp: applied `descDesc` form — `descDescApp I k` produces `descDesc I k` as a closed Tm; convenience for sites that need the pre-applied form._

```
descDescApp : Hoas -> Level -> Hoas
```

## `descDescAppAtI`

_descDescAppAtI: applied `descDesc` form with explicit index-universe level — `descDescAppAtI iLev I k` evaluates to a canonical stamp with params `[iLev, I, k]`._

```
descDescAppAtI : Level -> Hoas -> Level -> Hoas
```

## `descDescTm`

_descDescTm: pre-elaborated `descDesc` term — closed kernel `Tm` form usable directly by kernel rules that need the description-of-descriptions without re-elaborating._

```
descDescTm : Tm
```

## `descDescVal`

_descDescVal: pre-evaluated `descDesc` value — the kernel `Val` form, ready for `interpD` / `descInd` consumption without re-evaluation._

```
descDescVal : Val
```

## `encodeDescArg`

_encodeDescArg: HOAS encoder for `descArg` — `encodeDescArg I k S T` builds the structural encoding of a `descArg I k S T` description._

```
encodeDescArg : Hoas -> Level -> Hoas -> Hoas -> Hoas
```

## `encodeDescArgAt`

_encodeDescArgAt: HOAS encoder for `descArgAt` — universe-polymorphic encoder for `descArgAt I l k S T`._

```
encodeDescArgAt : Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas
```

## `encodeDescArgAtTm`

_encodeDescArgAtTm: pre-elaborated `encodeDescArgAt` — closed kernel `Tm`._

```
encodeDescArgAtTm : Tm
```

## `encodeDescArgTm`

_encodeDescArgTm: pre-elaborated `encodeDescArg` — closed kernel `Tm`._

```
encodeDescArgTm : Tm
```

## `encodeDescElim`

_encodeDescElim: HOAS encoder for `descElim` — produces the cascade application that walks `descDesc`'s plus-tree to dispatch on a `VDescCon` value's constructor._

```
encodeDescElim : Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

## `encodeDescElimTm`

_encodeDescElimTm: pre-elaborated `encodeDescElim` — closed kernel `Tm` form of the eliminator cascade._

```
encodeDescElimTm : Tm
```

## `encodeDescElimVal`

_encodeDescElimVal: pre-evaluated `encodeDescElim` — kernel `Val` form, ready for direct consumption without re-evaluation._

```
encodeDescElimVal : Val
```

## `encodeDescPi`

_encodeDescPi: HOAS encoder for `piI` — `encodeDescPi I k S f D` builds the structural encoding of a `piI I k S f D` description._

```
encodeDescPi : Hoas -> Level -> Hoas -> Hoas -> Hoas -> Hoas
```

## `encodeDescPiAt`

_encodeDescPiAt: HOAS encoder for `piIAt` — universe-polymorphic encoder for `piIAt I l k S f D`._

```
encodeDescPiAt : Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas
```

## `encodeDescPiAtTm`

_encodeDescPiAtTm: pre-elaborated `encodeDescPiAt` — closed kernel `Tm`._

```
encodeDescPiAtTm : Tm
```

## `encodeDescPiTm`

_encodeDescPiTm: pre-elaborated `encodeDescPi` — closed kernel `Tm`._

```
encodeDescPiTm : Tm
```

## `encodeDescPlus`

_encodeDescPlus: HOAS encoder for `plusI` — `encodeDescPlus I k A B` builds the structural encoding of a `plusI I k A B` description._

```
encodeDescPlus : Hoas -> Level -> Hoas -> Hoas -> Hoas
```

## `encodeDescPlusTm`

_encodeDescPlusTm: pre-elaborated `encodeDescPlus` — closed kernel `Tm`._

```
encodeDescPlusTm : Tm
```

## `encodeDescRec`

_encodeDescRec: HOAS encoder for `recI` — `encodeDescRec I k j D` builds the structural encoding of a `recI I k j D` description._

```
encodeDescRec : Hoas -> Level -> Hoas -> Hoas -> Hoas
```

## `encodeDescRecTm`

_encodeDescRecTm: pre-elaborated `encodeDescRec` — closed kernel `Tm`._

```
encodeDescRecTm : Tm
```

## `encodeDescRet`

_encodeDescRet: HOAS encoder for `retI` — `encodeDescRet I k j` builds the `μ ⊤ (descDesc I k) tt` value structurally encoding a `retI I k j` description._

```
encodeDescRet : Hoas -> Level -> Hoas -> Hoas  -- I, k, targetIdx
```

## `encodeDescRetTm`

_encodeDescRetTm: pre-elaborated `encodeDescRet` — closed kernel `Tm` lambda; consumed by `interpD`'s encoded-desc view branch._

```
encodeDescRetTm : Tm
```

## `natDescTm`

_natDescTm: pre-elaborated `Nat` description term — closed kernel `Tm` encoding `natDesc`; used by the kernel where the HOAS form would re-elaborate._

```
natDescTm : Tm
```



#### _forced


Forced-argument analysis helpers for datatype constructors; consumed by datatype elaboration and tests that inspect recoverable constructor fields.

## `forcedFieldNames`

_McBride-forced subset of a constructor's fields: a field is forced iff its sentinel marker occurs in `targetIdx prevFull` or in `fieldTyOf f_j prev_<j` for some j > i. Returns field names in declaration order._

```
{ fields : [Field]; targetIdx : Prev -> Hoas; fieldTyOf : ?Field -> Prev -> Hoas } -> [String]
```

## `forcedFieldSet`

_forcedFieldNames re-keyed as `{ <name> = true; }` for O(1) membership._

```
{ fields; targetIdx; fieldTyOf? } -> { <name> = true; }
```

## `isFieldForced`

_Predicate form: whether the named field appears in the forced set._

```
{ fields; targetIdx; fieldTyOf? } -> String -> Bool
```

## `mentionsOf`

_Collect `_signatureField` marker names occurring in a HOAS term. Binder bodies are descended by applying their closure to a `forced-probe` sentinel._

```
Hoas -> [String]
```



#### _indexed


Indexed/equality-aligned combinators (`muI`, `piI`, `recI`, `plusI`, `inrAt`, `fieldAt`) consumed by ornament construction and indexed-datatype test fixtures.

## `LiftAt`

_LiftAt: HOAS cross-level type former — `LiftAt l m A : U(m)` for `A : U(l)` with `l ≤ m`; bound witness auto-emitted as `mkBootRefl` when convLevel decides `Eq Level (max l m) m`._

```
LiftAt : Level -> Level -> Hoas -> Hoas  -- l, m, A
```

Idempotent at equal levels: `LiftAt l l A ≡ A` (no wrapping
when `sameLevelSyntax l l`). Use to transport a type from a
lower universe to a higher one without changing inhabitation.
For level-polymorphic binders where convLevel cannot decide,
use `LiftAtWithEq` and supply the proof explicitly.

## `LiftAtWithEq`

_LiftAtWithEq: LiftAt variant carrying an explicit bound-witness — `LiftAtWithEq l m eq A` supplies `eq : Eq Level (max l m) m` when convLevel cannot decide it._

```
LiftAtWithEq : Level -> Level -> Hoas -> Hoas -> Hoas  -- l, m, eq, A
```

## `consAtExplicit`

_consAtExplicit: internal List cons with hidden level + element type supplied explicitly for rigid/raw evaluation sites._

```
consAtExplicit : Level -> Hoas -> Hoas -> Hoas -> Hoas  -- level, elemTy, head, tail
```

## `datatypeAt`

_datatypeAt: universe-polymorphic ⊤-slice datatype — `datatypeAt name level [con …]` emits a datatype at sort level `level`._

```
datatypeAt : String -> Level -> [Constructor] -> DataSpec
```

## `datatypePAt`

_datatypePAt: universe-polymorphic parametric datatype — `datatypePAt` extends `datatypeP` with explicit sort levels for parameters._

```
datatypePAt : String -> Level -> [Param] -> (Hoas -> [Constructor]) -> DataSpec
```

## `descArgAt`

_descArgAt: universe-polymorphic descArg — `descArgAt I l k S T` builds the same with explicit sort level `l`._

```
descArgAt : Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas
```

## `descArgAtAtI`

_descArgAtAtI: fully universe-explicit indexed descArg — `descArgAtAtI iLev I l k S T` threads both the index-universe level and payload sort level._

```
descArgAtAtI : Level -> Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas
```

## `descArgAtI`

_descArgAtI: indexed descArg with explicit index-universe level — `descArgAtI iLev I k S T` for index types `I : U(iLev)`._

```
descArgAtI : Level -> Hoas -> Level -> Hoas -> Hoas -> Hoas
```

## `descArgWithEq`

_descArgWithEq: descArgAt variant with explicit bound-witness — supplies the `eq : Eq Level (max l k) k` proof for level-polymorphic positions._

```
descArgWithEq : Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas
```

## `descAt`

_descAt: universe-polymorphic ⊤-slice description — alias for `descIAt k unitPrim`; descriptions at level `k` over the unit index type._

```
descAt : Level -> Hoas
```

## `descI`

_descI: indexed description type former — `descI I` builds `Desc I`, the universe of descriptions over index sort `I`; level defaults to 0._

```
descI : Hoas -> Hoas
```

## `descIAt`

_descIAt: universe-polymorphic indexed description — `descIAt k I` builds `Desc^k I`; the level-omitting `descI` defaults to level 0._

```
descIAt : Level -> Hoas -> Hoas
```

## `descIAtAtI`

_descIAtAtI: fully universe-explicit indexed description — `descIAtAtI iLev k I` builds `Desc^k I` for `I : U(iLev)`._

```
descIAtAtI : Level -> Level -> Hoas -> Hoas
```

## `descIAtI`

_descIAtI: indexed description with explicit index-universe level — `descIAtI iLev I` builds `Desc I` for `I : U(iLev)`._

```
descIAtI : Level -> Hoas -> Hoas
```

## `descPiAt`

_descPiAt: universe-polymorphic ⊤-slice descPi — `descPiAt l k S D` with explicit sort level `l`._

```
descPiAt : Level -> Level -> Hoas -> Hoas -> Hoas
```

## `descPiWithEq`

_descPiWithEq: descPiAt variant with explicit bound-witness — supplies the `eq : Eq Level (max l k) k` proof for level-polymorphic descriptions._

```
descPiWithEq : Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas
```

## `fieldAt`

_fieldAt: universe-polymorphic field declarator — `fieldAt name level type` declares a field at an explicit sort level._

```
fieldAt : String -> Level -> Hoas -> { name; type; level; }
```

## `fieldAtWithEq`

_fieldAtWithEq: fieldAt variant carrying an explicit bound-witness — supplies the `eq : Eq Level (max l k) k` proof for level-polymorphic positions._

```
fieldAtWithEq : String -> Level -> Hoas -> Hoas -> { name; type; level; eq; }
```

## `fieldDAt`

_fieldDAt: universe-polymorphic dependent-field declarator — combines `fieldAt`'s explicit level with `fieldD`'s index dependence._

```
fieldDAt : String -> Level -> Hoas -> (Hoas -> Hoas) -> { name; type; level; indexFn; }
```

## `fieldDAtWithEq`

_fieldDAtWithEq: universe-polymorphic dependent-field with explicit bound-witness — combines fieldDAt with explicit eq._

```
fieldDAtWithEq : String -> Level -> Hoas -> Hoas -> (Hoas -> Hoas) -> { name; type; level; eq; indexFn; }
```

## `inlAt`

_inlAt: universe-polymorphic left-injection — `inlAt v` builds `Left v : Sum A B`; level, leftTy, rightTy inferred._

```
inlAt : Hoas -> Hoas  -- value
```

## `inlAtExplicit`

_inlAtExplicit: internal Sum left-injection with hidden parameters supplied explicitly for raw evaluation sites._

```
inlAtExplicit : Level -> Hoas -> Hoas -> Hoas -> Hoas  -- level, leftTy, rightTy, value
```

## `inrAt`

_inrAt: universe-polymorphic right-injection — `inrAt v` builds `Right v : Sum A B`; level, leftTy, rightTy inferred._

```
inrAt : Hoas -> Hoas  -- value
```

## `inrAtExplicit`

_inrAtExplicit: internal Sum right-injection with hidden parameters supplied explicitly for raw evaluation sites._

```
inrAtExplicit : Level -> Hoas -> Hoas -> Hoas -> Hoas  -- level, leftTy, rightTy, value
```

## `liftAt`

_liftAt: HOAS lift introduction — `liftAt l m A a` produces `LiftAt l m A` from `a : A`; idempotent at equal levels (no introducer when `l = m`)._

```
liftAt : Level -> Level -> Hoas -> Hoas -> Hoas  -- l, m, A, a
```

## `liftAtWithEq`

_liftAtWithEq: explicit-witness lift introduction — `liftAtWithEq l m eq A a` with the caller-provided `eq` term derived via `congSuc` / `maxSucDom` for level-polymorphic positions._

```
liftAtWithEq : Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas  -- l, m, eq, A, a
```

## `lowerAt`

_lowerAt: HOAS lift elimination — `lowerAt l m A x` extracts `a : A` from `x : LiftAt l m A`; β-reduces with `liftAt`, idempotent at equal levels._

```
lowerAt : Level -> Level -> Hoas -> Hoas -> Hoas  -- l, m, A, x
```

## `lowerAtWithEq`

_lowerAtWithEq: explicit-witness lift elimination — `lowerAtWithEq l m eq A x` mirroring `liftAtWithEq`; uses the supplied `eq` to discharge the level bound._

```
lowerAtWithEq : Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas  -- l, m, eq, A, x
```

## `muI`

_muI: indexed inductive carrier former — `muI I D i` builds `μ I D i`, the value type at index `i` of the description `D : Desc I`._

```
muI : Hoas -> Hoas -> Hoas -> Hoas  -- I, D, i
```

The carrier is constructed by `descCon D i d` from interpreted
payloads. Eliminated via `descInd D Q step i x` for indexed
induction. The kernel routes `mu` through the description-
rule path, never as a bare `mu` constructor — every `muI` flow
eventually applies the encoder cascade.

## `muIAtI`

_muIAtI: indexed inductive carrier with explicit index-universe level — `muIAtI iLev I D i` builds `μ I D i` for `I : U(iLev)`._

```
muIAtI : Level -> Hoas -> Hoas -> Hoas -> Hoas
```

## `nilAtExplicit`

_nilAtExplicit: internal List nil with hidden level + element type supplied explicitly for rigid/raw evaluation sites._

```
nilAtExplicit : Level -> Hoas -> Hoas  -- level, elemTy
```

## `piFieldAt`

_piFieldAt: universe-polymorphic Π-typed field — `piFieldAt name level sort body` with explicit level._

```
piFieldAt : String -> Level -> Hoas -> (Hoas -> Hoas) -> { ... }
```

## `piFieldAtIndex`

_piFieldAtIndex: piFieldAt variant emitting an explicit-target-index — used when the recursive Π must specify the index of the resulting recursive child._

```
piFieldAtIndex : String -> Level -> Hoas -> (Hoas -> Hoas) -> (Hoas -> Hoas) -> { ... }
```

## `piFieldAtIndexWithEq`

_piFieldAtIndexWithEq: piFieldAtIndex with explicit bound-witness._

```
piFieldAtIndexWithEq : String -> Level -> Hoas -> Hoas -> (Hoas -> Hoas) -> (Hoas -> Hoas) -> { ... }
```

## `piFieldAtWithEq`

_piFieldAtWithEq: piFieldAt with explicit bound-witness — supplies the `eq` proof for level-polymorphic positions._

```
piFieldAtWithEq : String -> Level -> Hoas -> Hoas -> (Hoas -> Hoas) -> { ... }
```

## `piFieldDAt`

_piFieldDAt: universe-polymorphic dependent Π-typed field — combines piFieldAt with piFieldD's dependence on prior fields._

```
piFieldDAt : String -> Level -> Hoas -> (Hoas -> Hoas -> Hoas) -> { ... }
```

## `piFieldDAtIndex`

_piFieldDAtIndex: piFieldDAt variant emitting an explicit-target-index._

```
piFieldDAtIndex : String -> Level -> Hoas -> (Hoas -> Hoas -> Hoas) -> (Hoas -> Hoas -> Hoas) -> { ... }
```

## `piFieldDAtIndexWithEq`

_piFieldDAtIndexWithEq: piFieldDAtIndex with explicit bound-witness._

```
piFieldDAtIndexWithEq : String -> Level -> Hoas -> Hoas -> (Hoas -> Hoas -> Hoas) -> (Hoas -> Hoas -> Hoas) -> { ... }
```

## `piFieldDAtWithEq`

_piFieldDAtWithEq: universe-polymorphic dependent Π-typed field with explicit bound-witness._

```
piFieldDAtWithEq : String -> Level -> Hoas -> Hoas -> (Hoas -> Hoas -> Hoas) -> { ... }
```

## `piI`

_piI: indexed piI-constructor — `piI I k S f D` builds a description that quantifies over `S` then continues with `D` parametrised by the chosen element via `f : S -> Tm` (the index function)._

```
piI : Hoas -> Level -> Hoas -> Hoas -> Hoas -> Hoas  -- I, k, sort, indexFn, continuation
```

## `piIAt`

_piIAt: universe-polymorphic piI — `piIAt I l k S f D` builds the same shape as `piI` but with explicit sort level `l` and continuation level `k`, used when level decisions cannot be left to convLevel._

```
piIAt : Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas
```

## `piIAtAtI`

_piIAtAtI: fully universe-explicit indexed piI — `piIAtAtI iLev I l k S f D` threads the index-universe level and payload sort level._

```
piIAtAtI : Level -> Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas
```

## `piIAtI`

_piIAtI: indexed piI with explicit index-universe level — `piIAtI iLev I k S f D` for descriptions over `I : U(iLev)`._

```
piIAtI : Level -> Hoas -> Level -> Hoas -> Hoas -> Hoas -> Hoas
```

## `piIWithEq`

_piIWithEq: piIAt variant carrying an explicit bound-witness — `piIWithEq I l k S f eq D` supplies the `eq : Eq Level (max l k) k` proof when the elaborator cannot auto-decide via `convLevel`._

```
piIWithEq : Hoas -> Level -> Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

## `plusI`

_plusI: indexed description sum — `plusI I k A B` builds `A + B` at index sort `I` and level `k`; both `A` and `B` must share index sort and level._

```
plusI : Hoas -> Level -> Hoas -> Hoas -> Hoas
```

## `plusIAtI`

_plusIAtI: indexed description sum with explicit index-universe level — `plusIAtI iLev I k A B` for descriptions over `I : U(iLev)`._

```
plusIAtI : Level -> Hoas -> Level -> Hoas -> Hoas -> Hoas
```

## `recI`

_recI: indexed recI-constructor — `recI I k j D` adds a recursive child at target index `j` to the continuation description `D`; the recursive position contributes payload at `μ I D' j` for the inner D'._

```
recI : Hoas -> Level -> Hoas -> Hoas -> Hoas  -- I, k, targetIndex, continuation
```

## `recIAtI`

_recIAtI: indexed recI-constructor with explicit index-universe level — `recIAtI iLev I k j D` for `I : U(iLev)`._

```
recIAtI : Level -> Hoas -> Level -> Hoas -> Hoas -> Hoas
```

## `retIAtI`

_retIAtI: indexed retI-constructor with explicit index-universe level — `retIAtI iLev I k j` for leaves over `I : U(iLev)`._

```
retIAtI : Level -> Hoas -> Level -> Hoas -> Hoas
```

## `sumAt`

_sumAt: universe-polymorphic coproduct — `sumAt level A B` builds `A + B` at the given universe level, used when the homogeneous-level `sum` cannot decide the bound witness._

```
sumAt : Hoas -> Hoas -> Hoas -> Hoas  -- level, A, B
```

## `sumElimAt`

_sumElimAt: universe-polymorphic sum eliminator — `sumElimAt level k A B P L R s` runs the sum eliminator at the given universe level, matching `inlAt` / `inrAt` construction._

```
sumElimAt : Hoas -> Level -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas  -- level, k, A, B, motive, onLeft, onRight, scrut
```



#### Surface


Surface specifications define constructor tags and handlers. HOAS
elaboration consults the attached registry only for nodes that carry
`_surfaceRegistry`, so existing HOAS terms continue through the built-in
dispatcher.

## `collectImplicitMetas`

_Collect surface-created implicit metavariable terms from an elaborated overlay term._

```
ElabTm -> [SurfaceMeta]
```

## `collectSurfaceMetas`

_Collect explicitly marked overlay metavariable terms from an elaborated surface result._

```
ElabTm -> [SurfaceMeta]
```

## `containsImplicitMeta`

_Predicate for unresolved surface-created implicit metavariable terms._

```
ElabTm -> Bool
```

## `containsSurfaceMeta`

_Predicate for any overlay metavariable term inside an elaborated surface result._

```
ElabTm -> Bool
```

## `defineOrnament`

_Package a surface-to-target mapping with section and forget morphisms for elaborator derivation._

```
{ source, target, mapping?, section?, forget? } -> SurfaceOrnament
```

## `defineSurface`

_Define a named surface language with constructor metadata and elaboration handlers._

```
{ name, description?, scope?, constructors } -> SurfaceSpec
```

## `deriveElaborator`

_Derive an elaborator entry point from a surface specification and optional ornament section. Expected type and source position are threaded into surface handlers._

```
{ surface, ornament? } -> { registry, elaborate }
```

## `deriveParser`

_Derive a parser shell for a surface specification._

```
{ surface, parse? } -> { parse }
```

## `derivePrinter`

_Derive a small printer for surface AST nodes._

```
{ surface, render? } -> { print }
```

## `elaborate`

_Elaborate one surface term, optionally checking it against an expected HOAS type and source position._

```
{ surface, term, expectedType?, position?, ornament? } -> Tm | Error
```

## `finalizeSurfaceElab`

_Return a structured unsolved-implicit error when elaboration leaves surface implicit metas unresolved._

```
{ result, state?, term?, surface?, position? } -> ElabTm | Error
```

## `framework`

_Convenience bundle for the surface-language definition, ornament, elaboration, parser, and printer APIs._

## `handlerContext`

_Build the argument record passed to surface elaboration handlers, adding expected type, source position, and implicit-meta helpers._

```
{ h, depth, lower, hoas, fx, ... } -> HandlerArgs
```

## `implicitMeta`

_Allocate an implicit metavariable using the Phase 6 meta-context shape and return both overlay value and term forms._

```
{ type?, state?, position?, surface?, label? } -> { id, value, term, state }
```

## `parse`

_Parse one input value with a derived parser shell or supplied parser._

```
{ surface, input, parse? } -> Hoas
```

## `prelude`

_Minimal surface prelude with List and an implicit-argument nil proof fixture._

## `print`

_Print one surface AST node with a derived or supplied renderer._

```
{ surface, term, render? } -> String
```

## `surfaceTerm`

_Construct one term from a surface specification._

```
SurfaceSpec -> String -> Attrs -> Hoas
```

## `toy`

_Toy boolean surface used as an end-to-end elaboration fixture._

## `unsolvedImplicitError`

_Build the structured surface error for unresolved implicit metavariables._

```
{ metas, term?, surface?, position? } -> Error
```

## `withSurfaceContext`

_Attach root expected-type and position metadata to a surface AST node before elaboration._

```
{ term, expectedType?, position? } -> Hoas
```

## Sub-namespaces

- [`registry`](/nix-effects/type-checker/surface/registry)

## Source

- [`src/tc/surface/define-ornament.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/define-ornament.nix)
- [`src/tc/surface/define-surface.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/define-surface.nix)
- [`src/tc/surface/derive-elaborator.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/derive-elaborator.nix)
- [`src/tc/surface/derive-parser.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/derive-parser.nix)
- [`src/tc/surface/derive-printer.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/derive-printer.nix)
- [`src/tc/surface/framework.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/framework.nix)
- [`src/tc/surface/handler-context.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/handler-context.nix)
- [`src/tc/surface/implicit.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/implicit.nix)
- [`src/tc/surface/prelude.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/prelude.nix)
- [`src/tc/surface/registry.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/surface/registry.nix)



#### Registry


Surface elaborator registry operations.

## `empty`

_Empty surface elaboration registry._

```
Registry
```

## `emptyRegistry`

_Alias for the empty surface elaboration registry._

```
Registry
```

## `fromHandlers`

_Build a surface registry from an attrset of constructor-tag handlers._

```
{ tag : Handler } -> Registry
```

## `handlerFor`

_Alias for lookup._

```
Registry -> String -> Handler | Null
```

## `isRegistry`

_Predicate for surface elaboration registries._

```
Any -> Bool
```

## `lookup`

_Return the handler registered for a surface constructor tag, or null._

```
Registry -> String -> Handler | Null
```

## `merge`

_Merge two surface registries, rejecting duplicate constructor handlers._

```
Registry -> Registry -> Registry
```

## `node`

_Construct a surface AST node carrying its registry._

```
Registry -> String -> Attrs -> Hoas
```

## `normalize`

_Normalize nullable registry inputs to a registry record._

```
Registry | Null -> Registry
```

## `register`

_Register a handler for one surface constructor tag._

```
Registry -> String -> Handler -> Registry
```

## `withRegistry`

_Attach a surface elaboration registry to an existing node._

```
Registry -> Attrs -> Hoas
```



#### Generic


Reflection over levitated descriptions and datatype macro outputs.
Datatype consumers should use this layer instead of raw `_dtypeMeta`.
Generic algebraic ornament helpers check algebra descriptors against
`generic.desc.shape`; the supported fragment is ret/arg/rec/plus.
Ornament validation exposes total structured diagnostics for expected
surface errors; semantic ornament maps remain pure over validated inputs.
Functional ornaments expose manual sections for canonical
base-to-ornamented construction; synthesis is layered on later.
The first synthesis layer accepts `{ base; spec; synth; }`, reuses the
ordinary ornament spec, and requires explicit builders for inserted fields.
Proof-marked inserted fields use `prove` or `synth.constructors.<name>.proofs`
and report unresolved proof obligations as structured diagnostics.
Declared measures feed algebraic/measure-derived inserted fields through
the synthesis builder context and produce missing-measure obligations.
Function transport lifts base producers and transforms through canonical
functional output sections while existing pullback remains forget-then-run.

## `path`

_path: list-level operations on a `[Position]` descent chain — `empty`, `extend`, `render`, `renderAll`. Position segments themselves are constructed via `fx.diag.positions` (`P.Field name`, `P.Elem i`, etc.); this module only handles the list assembly and pretty-rendering._

```
path : { empty, extend, render, renderAll }
```

Operations on a path (a list of `Position` segments naming a
structural descent from a validation root to a failure site):

- `empty = []` is the root path.
- `extend : Path -> Position -> Path` appends a segment.
- `render : Position -> String` pretty-renders one segment.
- `renderAll : Path -> String` concatenates rendered segments.

Position segments are produced by `fx.diag.positions` (the
canonical curried constructors `Field`, `Elem`, `Tag`, `Tuple`,
plus the ~30 nullary description/MLTT positions). Handlers
consume the same `Position` records regardless of whether they
come from kernel descent or value-side `verify=` walks.

## Sub-namespaces

- [`check`](/nix-effects/type-checker/generic/check)
- [`checkD`](/nix-effects/type-checker/generic/checkD)
- [`datatype`](/nix-effects/type-checker/generic/datatype)
- [`derive`](/nix-effects/type-checker/generic/derive)
- [`desc`](/nix-effects/type-checker/generic/desc)
- [`ornaments`](/nix-effects/type-checker/generic/ornaments)
- [`value`](/nix-effects/type-checker/generic/value)

## Source

- [`src/tc/generic/check.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/generic/check.nix)
- [`src/tc/generic/checkD.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/generic/checkD.nix)
- [`src/tc/generic/datatype.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/generic/datatype.nix)
- [`src/tc/generic/derive.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/generic/derive.nix)
- [`src/tc/generic/desc.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/generic/desc.nix)
- [`src/tc/generic/ornaments.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/generic/ornaments.nix)
- [`src/tc/generic/path.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/generic/path.nix)
- [`src/tc/generic/value.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/generic/value.nix)



#### Desc


A uniform interface to levitated descriptions
(`Desc I k`) that hides the encoder details behind a small
algebra of views, folds, and predicates. Every entry accepts
either HOAS or evaluated `Val` descriptions — `evalDesc`
normalises to `Val` idempotently.

`descView` returns a one-step semantic view exposing the outer
constructor as both an integer `idx` (0=ret, 1=arg, 2=rec, 3=pi,
4=plus) and a human-readable `kind` string, alongside the
constructor-specific fields (`I`, `k`, `j`, `sTy`, `tFn`, `sub`,
`A`, `B`, plus optional `label`/`conLabel` sidecar metadata).

`foldDesc` is the catamorphism: pass per-constructor handler
functions, each receiving a record with the recursed sub-values
already materialised. `foldDescM` is the monadic dual — each
handler returns a `Computation R` and the combinator binds
sub-results before invoking the matching case; `paraDM` is the
paramorphic variant that additionally exposes the original
sub-description `Val` at each recursive site (for callers that
consult kernel-level shape without paying for a monadic
descent). `foldDescWithPath` mirrors `foldDescM` and threads a
`[fx.diag.positions]` chain extended at each descent so handlers
can construct positionally-blamed errors directly from inside
the fold. `mapDesc` is the structural map — handlers return
either replacement HOAS, an explicit `{ _replaceChildren = …; }`
payload, or a `Val` for direct substitution; identity mappers
reconstruct definitionally-equal outputs via the canonical
encoder chain.

`deepEqualDesc` decides definitional equality by delegating to
`fx.tc.conv.conv`; presentation labels (`_label`, `_conLabel`)
are conv-irrelevant. `children`, `shape`, and the `isRet` /
`isArg` / `isRec` / `isPi` / `isPlus` predicates round out the
introspection surface for callers that want lightweight
structural queries without writing a full fold.

## `children`

_children: direct sub-descriptions list — empty for `ret`, `[body]` for `arg`/`rec`/`pi` (arg applies the body to a `vTt` placeholder), `[A, B]` for `plus`._

```
children : Hoas | Val -> [Val]
```

## `deepEqualDesc`

_deepEqualDesc: definitional equality on description values — evaluates both arguments via `evalDesc`, then runs `fx.tc.conv.conv 0` for full conv-equality._

```
deepEqualDesc : Hoas | Val -> Hoas | Val -> Bool
```

## `descView`

_descView: one-step semantic view of a description value — returns `{ idx, kind, I, k, ... }` selecting the outer constructor (`0` = ret, `1` = arg, `2` = rec, `3` = pi, `4` = plus); throws on malformed inputs._

```
descView : Hoas | Val -> { idx : 0..4; kind : String; I : Val; k : Val; ... }
```

Friendly wrapper around `fx.tc.eval.descView` that adds a
human-readable `kind` field alongside the integer `idx`.
Returns the raw view fields (`I`, `k`, `j`, `sTy`, `tFn`,
`sub`, `A`, `B`, optional `label`/`conLabel`) so callers can
peel apart any description shape uniformly.

Use this entry as the canonical view for generic programming
over levitated descriptions; the lower-level
`fx.tc.eval.descView` is identical in semantics but skips the
kind-naming step.

## `evalDesc`

_evalDesc: idempotent description normaliser — returns evaluated `Val` descriptions unchanged, evaluates HOAS descriptions via `H.elab` + `E.eval []`; throws on inputs that are neither._

```
evalDesc : Hoas | Val -> Val
```

## `foldDesc`

_foldDesc: catamorphism over description structure — recursively decomposes a description into its ret/arg/rec/pi/plus shape and invokes the matching case in `cases` with the materialised sub-values._

```
foldDesc : { ret? ; arg? ; rec? ; pi? ; plus? ; default? } -> Hoas | Val -> R
```

## `foldDescM`

_foldDescM: monadic catamorphism over description structure — recurses through ret/arg/rec/pi/plus and binds each sub-`Computation R` before invoking the matching handler, so handlers receive already-bound `R` carriers and the combinator owns the threading._

```
foldDescM : { ret? ; arg? ; rec? ; pi? ; plus? ; default? } -> Hoas | Val -> Computation R
```

Monadic dual of `foldDesc`. Each handler returns a
`Computation R`; recursed sub-computations are sequenced via
`fx.kernel.bind` before the handler runs, so a handler
observes bound `R` values (not raw computations).

Per-summand handler shapes:

- `ret`   : `{ view; j }` — no sub-recursion.
- `arg`   : `{ view; sTy; body; sample }` where
             `body : arg -> Computation R` defers recursion at
             the body's parameter and `sample : R` is the bound
             result of recursing on the placeholder-instantiated
             body (mirrors the pure `foldDesc` arg convention).
- `rec`   : `{ view; j; sub }` with `sub : R`.
- `pi`    : `{ view; sTy; fn; sub }` with `sub : R` (the
             selector `fn` stays raw — it's a `Val`, not a
             description).
- `plus`  : `{ view; left; right }` with both bound.

The `default` handler is used when a per-summand handler is
absent; default-of-defaults is `_: K.pure null`.

Use this fold to drive `checkD`/`inferD`-shaped walkers where
each kernel-CHECK sub-delegation lives inside a
`Computation Tm` (typeError handler, `bindP`-style position
wrapping). The combinator preserves the pure-bind discipline:
recursing at a summand whose sub-walk resolves to `K.pure …`
does not install a handler.

## `foldDescWithPath`

_foldDescWithPath: monadic catamorphism that threads a `path` of `fx.diag.positions` segments AND uses `bindP` at each descent so emitted typeErrors auto-wrap under the structural position before re-raising._

```
foldDescWithPath : [Position] -> { ret? ; arg? ; rec? ; pi? ; plus? ; default? } -> Hoas | Val -> Computation R
```

Variant of `foldDescM` with two-pronged structural blame:
every descent installs a `fx.tc.check.bindP` handler under
the descent's position, and the current `path` is exposed to
handlers as data. The blame alphabet at each descent:

  arg.T   → `P.DArgBody`
  rec.D   → `P.DRecTail`
  pi.T    → `P.DPiBody`
  plus.L  → `P.DPlusL`
  plus.R  → `P.DPlusR`

Because the descent uses `bindP`, a sub-handler that emits
`typeError` produces an error tree whose outermost edge is
the descent position, with the original error nested under
it. Nested descents stack — a typeError emitted at the leaf
of a plus(rec(ret)) descent surfaces with the edge chain
`[DPlusL, DRecTail]` outermost-first, matching the kernel's
existing positional-blame convention. Handlers that prefer
explicit position wrapping can use the `path` argument and
`D.nestUnder` directly; both routes compose because the
alphabet is identical.

Each handler receives the *current* `path` (the chain leading
to its node, not yet extended by its own descent) and, for
non-leaf summands, helper extenders matching what the
descent will install:

- `ret`   : `{ view; path; j }`.
- `arg`   : `{ view; path; sTy; body; sample; bodyPath }` —
             `bodyPath = path ++ [DArgBody]`.
- `rec`   : `{ view; path; j; sub; subPath }` —
             `subPath = path ++ [DRecTail]`.
- `pi`    : `{ view; path; sTy; fn; sub; subPath }` —
             `subPath = path ++ [DPiBody]`.
- `plus`  : `{ view; path; left; right; leftPath; rightPath }`.

Pass `[]` as the root path for a top-level walk. Nested
callers pass the outer chain so positions compose
end-to-end.

## `isArg`

_isArg: predicate — `true` iff the description's outer constructor is `descArg`._

```
isArg : Hoas | Val -> Bool
```

## `isPi`

_isPi: predicate — `true` iff the description's outer constructor is `descPi`._

```
isPi : Hoas | Val -> Bool
```

## `isPlus`

_isPlus: predicate — `true` iff the description's outer constructor is `plusI` (binary sum)._

```
isPlus : Hoas | Val -> Bool
```

## `isRec`

_isRec: predicate — `true` iff the description's outer constructor is `descRec`._

```
isRec : Hoas | Val -> Bool
```

## `isRet`

_isRet: predicate — `true` iff the description's outer constructor is `descRet`._

```
isRet : Hoas | Val -> Bool
```

## `mapDesc`

_mapDesc: structurally rewrite each layer of a description via per-shape mapper functions, then reconstruct using the canonical encoder chain — the result is conv-equivalent to the original when mappers are identities._

```
mapDesc : { ret? ; arg? ; rec? ; pi? ; plus? } -> Hoas | Val -> Val
```

## `paraDM`

_paraDM: monadic paramorphism over description structure — each handler additionally receives the original sub-description `Val` alongside the bound recursed result, enabling certificate-aware fast paths and reflective elaborators._

```
paraDM : { ret? ; arg? ; rec? ; pi? ; plus? ; default? } -> Hoas | Val -> Computation R
```

Paramorphic variant of `foldDescM`. Where `foldDescM` exposes
only the recursed `R` carrier at each sub-position, `paraDM`
also exposes the raw sub-description `Val` — required by
callers that inspect the kernel-level description shape
without paying for a monadic descent (certificate consultation,
ornament-section selection, reflection).

Per-summand handler shapes:

- `ret`   : `{ view; j }`.
- `arg`   : `{ view; sTy; body; bodyDesc; sample; sampleDesc }`
             — `body : arg -> Computation R` and the
             parallel `bodyDesc : arg -> Val` return
             the sub-description without recursing. `sample`
             and `sampleDesc` are the bound result and raw
             `Val` at the placeholder respectively.
- `rec`   : `{ view; j; sub; subDesc }` — `subDesc : Val` is
             the original sub-description `view.sub`.
- `pi`    : `{ view; sTy; fn; sub; subDesc }`.
- `plus`  : `{ view; left; right; leftDesc; rightDesc }`.

`default` and identity-on-failure semantics match `foldDescM`.

## `shape`

_shape: tagged-record skeleton of a description — returns `{ kind = "ret" | "arg" | "rec" | "pi" | "plus"; ...payload }` with only the shape-relevant fields; payload depends on `kind`._

```
shape : Hoas | Val -> { kind : String; ... }
```



#### Datatype


Operates on the `_dtypeMeta` attrset attached to every datatype
produced by `H.datatype` / `H.datatypeI` / `H.datatypeP`, and on
`H.app`-spines whose head carries `_dtypeMeta` (instantiated
polymorphic datatypes). `datatypeInfo` is the canonical entry:
it normalises a raw meta or applies `meta.instantiate` to the
spine args before returning a fully-defaulted record (`indexed`,
`params`, `paramArgs`, `indexTy`, plus both `constructors` and
the legacy `cons` alias).

Lookup helpers stay close to caller intent: `constructors`,
`fields`, `constructorByName`, and `constructorByIx` accept
either pre-normalised meta or a raw `DataSpec`. Mismatched
names and out-of-range indices throw with descriptive
messages; nothing fails silently.

Field-level resolution threads `prev` — the record of
previously-materialised dependent-field values — so
`fieldType field prev` returns the kernel HOAS type for both
concrete fields (`field.type`) and dependent fields
(`field.typeFn prev`). `targetIndex con prev` resolves a
constructor's target index in the datatype's index type the
same way. `fieldRole` exposes the optional `role` annotation
used by generic derivations to distinguish payload from
proof-bearing fields.

## `constructorByIx`

_constructorByIx: lookup a constructor by zero-based declaration-order index; throws on out-of-range or non-integer index._

```
constructorByIx : Meta | DataSpec -> Int -> Constructor
```

## `constructorByName`

_constructorByName: lookup a constructor by name in a datatype's meta/`DataSpec`; throws on unknown name with a descriptive message._

```
constructorByName : Meta | DataSpec -> String -> Constructor
```

## `constructors`

_constructors: extract the constructor list from a meta or `DataSpec` — accepts either a pre-normalised meta with `constructors` or a raw `DataSpec`, calling `datatypeInfo` for the latter._

```
constructors : Meta | DataSpec -> [Constructor]
```

## `datatypeInfo`

_datatypeInfo: produce normalised metadata from either a `DataSpec` (record with `_dtypeMeta`) or an `H.app` spine whose head is a polymorphic datatype; for polymorphic heads, applies `meta.instantiate` to the spine args._

```
datatypeInfo : DataSpec | Hoas -> Meta
```

## `fieldRole`

_fieldRole: extract the `role` annotation from a field, or `null` if unset. Used by generic derivations to distinguish e.g. proof-bearing fields from ordinary payload._

```
fieldRole : Field -> String | null
```

## `fieldType`

_fieldType: resolve a field's HOAS type — prefers `field.typeFn prev` (dependent fields) over `field.type` (concrete); throws if neither slot is filled._

```
fieldType : Field -> AttrSet -> Hoas
```

## `fields`

_fields: extract the field list from a constructor record; defaults to `[]` for constructors with no fields slot._

```
fields : Constructor -> [Field]
```

## `instantiate`

_instantiate: apply parameter arguments to a polymorphic datatype `DataSpec`, returning the normalised meta for that instantiation; throws for non-polymorphic datatypes given non-empty `paramArgs`._

```
instantiate : DataSpec -> [Hoas] -> Meta
```

## `isDatatype`

_isDatatype: predicate identifying values that carry `_dtypeMeta` directly, or app-spines whose head carries `_dtypeMeta` (instantiated polymorphic datatypes)._

```
isDatatype : Any -> Bool
```

## `normalizeMetadata`

_normalizeMetadata: canonicalise a raw `_dtypeMeta` attrset — requires `constructors`, defaults `indexed`/`params`/`paramArgs`/`indexTy`, and pre-fills every field with `level`/`eq`/`proof`/`type`/`typeFn`/`S`/`SFn`/`idxFn`/`branchIdxFn`/`role`/`source` slots._

```
normalizeMetadata : Meta -> Meta
```

## `targetIndex`

_targetIndex: compute a constructor's target index in the datatype's index type — applies `con.targetIdx prev` where `prev` is the materialised previous-field record; throws if no `targetIdx` function is present._

```
targetIndex : Constructor -> AttrSet -> Hoas
```



#### Value


Two-way conversion between HOAS values and Nix
constructor-records, plus generic structural traversal. The
type argument accepts either an HOAS type directly or a
datatype-output record carrying `.T`; everything else is
normalised by `typeOf` internally.

`view` is the HOAS-or-Nix → tagged-record direction:
record/variant datatypes return `{ _con = "name"; …fields }`,
primitives flatten to their native Nix form. The function is
idempotent on values already in HOAS form. `review` is the
inverse, kernel-elaborating a Nix value back to HOAS via
`Elab.elaborateValue`. `toConstructorRecord` and
`fromConstructorRecord` are intent-named aliases preferred in
datatype-generic code.

`fold` consumes a `{ <ctor> = Fields -> R; default? }` map and
dispatches on `_con`; `recAt` fields are recursively folded
before being passed in, all other fields appear raw. Missing
constructors fall through to `cases.default constructor` or
throw. `mapChildren` rewrites a single layer: each `recAt`
field is replaced by `childMapper field child`; non-recursive
fields pass through unchanged. The result is normalised by
`view` so it round-trips with `review`.

## `fold`

_fold: structural fold over a generated datatype value — dispatches on the constructor's name in `cases`, recursing into `recAt` fields before invoking the case function with the record of materialised fields._

```
fold : Hoas -> { <ctor> = Fields -> R; default? : Constructor -> Fields -> R; } -> NixVal -> R
```

Each case in `cases` receives a record of materialised fields
keyed by field name; `recAt` fields have already been folded
recursively, all other fields appear as raw Nix values. Missing
constructors fall through to `cases.default constructor` if
present, else throw `"missing case '<name>'"`.

Implementation note: walks via `view` + `constructorByName`,
so the input must be either a constructor-record or a value
elaborable via `review`. Non-attrset value views (e.g., raw
`Nat`) bypass this function — caller folds over the primitive
directly.

## `fromConstructorRecord`

_fromConstructorRecord: alias of `review` — the datatype-generic name for the record-to-value direction; preferred when expressing intent over generated datatypes._

```
fromConstructorRecord : Hoas | { T : Hoas; ... } -> NixVal -> Hoas
```

## `mapChildren`

_mapChildren: rewrite a single layer of a generated datatype — for each `recAt` field, apply `childMapper field child`; non-recursive fields pass through unchanged. The result is `view`-normalised so it round-trips with `review`._

```
mapChildren : Hoas -> (Field -> NixVal -> NixVal) -> NixVal -> NixVal
```

## `review`

_review: Nix-value → HOAS-value — friendly alias of `Elab.elaborateValue` taking the type either as `Hoas` directly or via a `.T` field (datatype outputs); inverse of `view`._

```
review : Hoas | { T : Hoas; ... } -> NixVal -> Hoas
```

## `toConstructorRecord`

_toConstructorRecord: alias of `view` — the datatype-generic name for the value-to-record direction; preferred when expressing intent over generated datatypes._

```
toConstructorRecord : Hoas | { T : Hoas; ... } -> Hoas | NixVal -> NixVal
```

## `view`

_view: HOAS-value or Nix-value → Nix constructor-record — kernel-elaborates if given a Nix value, then `Elab.extract`s back to a tagged record (`_con` for record/variant datatypes, primitive for leaf types)._

```
view : Hoas | { T : Hoas; ... } -> Hoas | NixVal -> NixVal
```

Idempotent on the HOAS form: when `value` is already an HOAS
tree (`_htag` present), it skips re-elaboration. Otherwise
round-trips through `review` to produce an HOAS value, then
evaluates and extracts.

Returns a constructor-record `{ _con = "name"; ...fields }` for
record/variant datatypes. Primitive values (Nat, String, ...)
flatten to their native Nix form. Cross-ref: `fromConstructorRecord`
is the alias name used in the datatype-generic API surface.



#### Derive


Generic, codegen-friendly summaries of a datatype's shape.
Each helper consumes a `DataSpec` (or pre-normalised meta) and
produces a pure-data record that downstream tooling — schema
validators, doc renderers, codegen, dependency analysers —
can consume without re-walking the kernel HOAS.

`typeDescriptor` projects an arbitrary HOAS or `Val` type to
`{ kind; … }` with a finite tag set covering primitives
(`nat`/`bool`/`int`/`string`/`float`/`attrs`/`path`/`function`/`any`/`unit`/`universe`),
algebraic forms (`list { elem }`, `sum { left; right }`,
`datatype { name; args? }`), recursive sites (`recursive`),
and unknown fallthrough (`hoas { tag }`).

`deriveDescriptor` is the base artefact: name, constructors,
per-field records with kind / index / level / role / source /
proof / recursive-index / branch-index / dependent-type /
type-descriptor. `deriveSchema` projects to
JSON-Schema-flavoured `{ title; oneOf }`. `deriveDocs`
re-shapes for Markdown / HTML rendering. `deriveFold` produces
the fold-skeleton record for code generators.

`deriveDeps` walks a constructor record, emitting a
`{ nodes; edges }` graph that records constructor descents
(`recAt` recursion sites), role-tagged dependency fields
(matched against a fixed role policy), and proof-bearing
fields. The output is consumable by the generic graph
renderer and by build-time dependency analysers.

## `deriveDeps`

_deriveDeps: build a node-and-edge dependency graph from a value — walks each constructor record, emitting nodes for constructors and edges for `recAt` recursion sites, role-tagged dependency fields, and proof-bearing fields._

```
deriveDeps : DataSpec -> NixVal -> { datatype, root, rootPath, indexed, index, nodes, edges }
```

Traversal seeds at path `\"$\"` and recurses into each `recAt`
field, accumulating constructor nodes and per-field edges.
Emitted edge kinds:

- `recAt` field on a constructor: edge from parent to child
  constructor, carrying `field`, `role`, `source`, and the
  resolved child type.
- Dependency-role field (matching the role-policy predicate):
  edge to a referenced datatype.
- Proof-bearing field (`proof = true`): edge tagging the
  unresolved obligation.

The returned `nodes` / `edges` shape is consumable by the
generic graph renderer and by build-time dependency analysers.

## `deriveDescriptor`

_deriveDescriptor: produce a full structured descriptor of a datatype — name, constructors, fields with kinds/types/roles, and source provenance. The base artefact other `derive*` helpers consume._

```
deriveDescriptor : DataSpec -> { name : String; constructors : [ConstructorDescriptor]; ... }
```

## `deriveDocs`

_deriveDocs: produce a documentation-friendly descriptor — same `name` and `constructors` as `deriveDescriptor` plus a `heading` field for use in Markdown/HTML rendering._

```
deriveDocs : DataSpec -> { heading : String; name : String; constructors : [...] }
```

## `deriveFold`

_deriveFold: produce a fold-skeleton descriptor — `{ datatype; cases = [{ name; fields = [{ name; kind; type; }] }] }`; consumed by code generators emitting per-datatype fold scaffolds._

```
deriveFold : DataSpec -> { datatype : String; cases : [Object] }
```

## `deriveSchema`

_deriveSchema: produce a JSON-Schema-flavoured `{ title, oneOf : [ConstructorSchema] }` from a datatype — each constructor schema records its name, field name+kind+type, and metadata flags (target index, proof, etc.)._

```
deriveSchema : DataSpec -> { title : String; oneOf : [Object] }
```

## `typeDescriptor`

_typeDescriptor: convert a kernel type (HOAS or `Val`) into a structured descriptor record — `{ kind; name?; constructors?; ... }` summarising the shape; used downstream by schema, docs, and dependency derivations._

```
typeDescriptor : Hoas | Val | null -> { kind : String; ... }
```



#### Check


The single polymorphic fold over the full HOAS type algebra,
parameterised by an `Algebra A`. Two canonical algebras live
alongside it: `unitAlg` returns `null` at every node and is
used for validation (the walker emits `typeCheck` effects on
failure); `hoasAlg` constructs the corresponding HOAS term at
every node and is used for elaboration. Validation and
elaboration are not two functors — they are one fold
instantiated at two carriers.

`deriveCheck` and `deriveElaborate` thread `unitAlg` /
`hoasAlg` respectively. Both accept `(ty, path, value)` and
return a `Computation A`; the walker owns shape inspection,
`_htag` dispatch, `fx.kernel` effect emissions, path
threading, and the dependent-Σ snd-type derivation via an
internal strict-handler trampoline on fst. Algebras own
per-shape success-case construction and the field-walker (so
`unitAlg` matches the legacy `f.type`-only traversal while
`hoasAlg` threads `prev` through `fieldType` for
dependent-field resolution).

`checkWithGuard` composes `deriveCheck` with a refinement
predicate: shape-check via the unit walker first, predicate
second (the two cannot run in parallel — the predicate's
domain is exactly the values that pass shape). When the
eventual Σ-with-Decide-snd encoding lands, this special case
collapses into `deriveCheck` over Σ-types and the helper
deletes.

Failure reasons carry one of `shape-mismatch`, `missing-field`,
`extra-field`, `predicate-failed`, or `deferred-pi`, routed by
handlers under `fx.effects.typecheck.*`.

## `checkWithGuard`

_checkWithGuard: refinement-predicate-aware variant of `deriveCheck` — runs shape check first via `unitAlg`, then composes the type's refinement predicate when present; required while refined types are encoded outside the canonical Σ-with-Decide-snd form._

```
checkWithGuard : Type -> Path -> Value -> Computation Null
```

## `deriveCheck`

_deriveCheck: canonical typed walker over the HOAS algebra threading `unitAlg` — emits `fx.effects.typecheck` failures with structured `reason` (shape-mismatch, missing-field, extra-field, predicate-failed, deferred-pi) and `path` (a `fx.diag.positions` chain)._

```
deriveCheck : Type -> Path -> Value -> Computation Null
```

## `deriveElaborate`

_deriveElaborate: canonical typed walker over the HOAS algebra threading `hoasAlg` — reconstructs the corresponding HOAS term at every successfully-checked node; shares path threading and dispatch with `deriveCheck`._

```
deriveElaborate : Type -> Path -> Value -> Computation Hoas
```



#### CheckD


checkD: generic bidirectional checker for Desc payloads — validates terms against `interpD level I D X i` by walking the description.

## `checkD`

_checkD: check a payload term against the interpretation of a description at a concrete index and recursive family._

```
checkD : Ctx -> Level -> I -> D -> X -> i -> Tm -> Computation Tm
```

## `checkDAt`

_checkDAt: spec-record variant of checkD; spec contains `{ level; I; D; X; i; }`._

```
checkDAt : Ctx -> { level; I; D; X; i; } -> Tm -> Computation Tm
```

## `inferD`

_inferD: synthesize the checked payload and its `interpD level I D X i` type._

```
inferD : Ctx -> Level -> I -> D -> X -> i -> Tm -> Computation { term; type; }
```

## `inferDAt`

_inferDAt: spec-record variant of inferD; spec contains `{ level; I; D; X; i; }`._

```
inferDAt : Ctx -> { level; I; D; X; i; } -> Tm -> Computation { term; type; }
```



#### Ornaments


Three families of ornament construction over kernel
descriptions: raw structural ornaments (`ornament`,
`compose`, `forget`, `forgetHoas`, `pullback`,
`pullbackHoas`), algebraic ornaments derived from algebras
over the supported fragment (`algOrn`, `algShape`,
`algSupportedFragment`, `algShapeDiagnostics`,
`checkAlgShape`, `liftFold`), and functional ornaments for
lifting producers / transforms through canonical output
sections (`functional`, `functionalSection`,
`functionalTargetIndex`, `functionalBuildIndexed` /
`functionalBuild`, `liftProducerIndexed` / `liftProducer`,
`liftTransformIndexed` / `liftTransform`,
`composeFunctional`).

Validation is uniform across families: every constructor has
a `validate` / `try` / `diagnose` triple
(`validateSpec` / `tryOrnament` / `diagnoseSpec`,
`validateAlgOrn` / `tryAlgOrn` / `diagnoseAlgOrn`,
`validateFunctional` / `tryFunctional` / `diagnoseFunctional`,
plus the law-level `validateFunctionalLaws` /
`diagnoseFunctionalLaws`). `validate*` throws on rejection
with a structured diagnostic, `try*` returns
`{ success; value | diagnostic }`, `diagnose*` always returns
the diagnostic record. The supported algebraic fragment is
`[ "ret" "arg" "rec" "pi" "plus" ]`.

Convenience aliases `section`, `targetIndex`, `buildIndexed`,
and `build` re-export the corresponding `functional*` entries
for callers writing in the functional-ornament idiom.

## `algOrn`

_algOrn: build an algebraic ornament from `args`, running `checkAlgShape` first so unsupported algebra shapes are rejected with structured diagnostics before delegating to `H.algOrn`._

```
algOrn : { I?, J, baseD | D, erase, algebra, ... } -> Ornament
```

## `algShape`

_algShape: total predicate `{ ok, kind, expected }` over an algebra value's shape — surfaces the offending `kind` when the algebra falls outside `algSupportedFragment`._

```
algShape : Algebra -> { ok : Bool, kind? : String, expected? : [String] }
```

## `algShapeDiagnostics`

_algShapeDiagnostics: human-readable diagnostic strings for an algebra whose shape falls outside the supported `ret/arg/rec/pi/plus` fragment._

```
algShapeDiagnostics : Attrs -> [String]
```

## `algSupportedFragment`

_algSupportedFragment: the constructor-tag whitelist `[ "ret" "arg" "rec" "pi" "plus" ]` accepted by `algOrn`; surfaced as the `expected` field of `algShape`'s diagnostic when an algebra falls outside this fragment._

```
algSupportedFragment : [String]
```

## `build`

_functionalBuild: build the ornamented value from `baseValue` at the unit index `tt` — convenience wrapper for J = `Unit` functional ornaments._

```
functionalBuild : FunctionalOrnament -> Tm -> Tm
```

## `buildIndexed`

_functionalBuildIndexed: build the ornamented value at an explicit `index` from `baseValue` — wraps `H.ornBuild` for the indexed surface._

```
functionalBuildIndexed : FunctionalOrnament -> Tm -> Tm -> Tm
```

## `checkAlgShape`

_checkAlgShape: return `algebra` unchanged when it lies in the supported fragment, otherwise throw with the concatenated `algShapeDiagnostics` text._

```
checkAlgShape : Attrs -> Algebra  -- throws on unsupported shape
```

## `checkSpec`

_checkSpec: surface `_ornMeta` from a built ornament — exposes `{ base, spec, core, cfg }` for downstream introspection of the ornament's provenance and shape._

```
checkSpec : DataSpec -> OrnamentSpec -> Attrs
```

## `compose`

_compose: vertical composition of ornaments at the generic surface — `outer ∘ inner` lifts the inner ornament's J through the outer's K, automatically unpacking `.ornament` cores._

```
compose : Ornament -> Ornament -> Ornament  -- outer, inner
```

## `composeFunctional`

_composeFunctional: vertical composition of two functional ornaments — threads `inner.chooseIndex` and `inner.section` into `outer` to produce a stacked section pipeline._

```
composeFunctional : FunctionalOrnament -> FunctionalOrnament -> FunctionalOrnament
```

## `diagnoseAlgOrn`

_diagnoseAlgOrn: human-readable diagnostic strings for a candidate algebraic-ornament spec — derived from `H.algOrnDiagnostics`, suitable for error messages and tests._

```
diagnoseAlgOrn : Attrs -> [String]
```

## `diagnoseFunctional`

_diagnoseFunctional: human-readable diagnostic strings for a candidate functional-ornament spec — derived from `validateFunctional` for surfacing in errors._

```
diagnoseFunctional : Attrs -> [String]
```

## `diagnoseFunctionalLaws`

_diagnoseFunctionalLaws: human-readable diagnostic strings for failed law checks on a functional ornament — surfaces which law-check returned non-`true` or failed to evaluate._

```
diagnoseFunctionalLaws : FunctionalOrnament -> [String]
```

## `diagnoseSpec`

_diagnoseSpec: human-readable diagnostic strings for a candidate `(base, spec)` — derived from `H.ornamentDiagnostics`, suitable for error messages and tests._

```
diagnoseSpec : DataSpec -> OrnamentSpec -> [String]
```

## `forget`

_forget: apply the forgetting morphism to an ornamented `value`, returning the underlying base-description value at the same J-index._

```
forget : OrnamentedDatatype -> Tm -> Tm
```

## `forgetHoas`

_forgetHoas: yield the HOAS-level `forget` term `J -> ornMu -> baseMu` for an ornamented datatype or raw ornament; prefers `forget0` when the J-index is `Unit`._

```
forgetHoas : OrnamentedDatatype -> Tm
```

## `functional`

_functional: total smart constructor for a functional ornament — validates `args` via `validateFunctional` and throws with diagnostics on failure, otherwise returns the built record._

```
functional : Attrs -> FunctionalOrnament  -- throws on invalid spec
```

## `functionalBuild`

_functionalBuild: build the ornamented value from `baseValue` at the unit index `tt` — convenience wrapper for J = `Unit` functional ornaments._

```
functionalBuild : FunctionalOrnament -> Tm -> Tm
```

## `functionalBuildIndexed`

_functionalBuildIndexed: build the ornamented value at an explicit `index` from `baseValue` — wraps `H.ornBuild` for the indexed surface._

```
functionalBuildIndexed : FunctionalOrnament -> Tm -> Tm -> Tm
```

## `functionalSection`

_functionalSection: extract the `section` slot of a functional ornament — the builder `i -> baseValue -> ornamentedValue` realising the section morphism._

```
functionalSection : FunctionalOrnament -> (Tm -> Tm -> Tm)
```

## `functionalTargetIndex`

_functionalTargetIndex: extract the `chooseIndex` slot of a functional ornament — the function `i -> baseValue -> J` that picks the ornamented index per base input._

```
functionalTargetIndex : FunctionalOrnament -> (Tm -> Tm -> Tm)
```

## `lift`

_lift: functorial container lifts — given an ornament `O : Ornament A A'`, `lift.list` / `lift.attrs` / `lift.maybe` produce `Ornament (F A) (F A')` whose forget is the standard functorial action of `F` on `O.forget`; `lift.field name O` is the elementary product-component move. Inputs may be leaf or decorated μ-ornaments; the μ-case delegates element forget to the meta walker._

```
lift : { list : Ornament -> Ornament, attrs : Ornament -> Ornament, maybe : Ornament -> Ornament, field : String -> Ornament -> Ornament }
```

## `liftFold`

_liftFold: alias for `pullbackHoas` specialised to folds — composes a base fold with `forget` so it runs on ornamented carriers without re-deriving the algebra._

```
liftFold : OrnamentedDatatype -> (Tm -> Tm) -> Tm -> Tm
```

## `liftProducer`

_liftProducer: lift a base producer through a functional ornament at unit index `tt` — convenience wrapper for J = `Unit`._

```
liftProducer : FunctionalOrnament -> (Tm -> Tm) -> Tm -> Tm
```

## `liftProducerIndexed`

_liftProducerIndexed: lift a base producer `baseFn : baseInput -> baseValue` through a functional ornament at an explicit J-index, returning the ornamented output._

```
liftProducerIndexed : FunctionalOrnament -> Tm -> (Tm -> Tm) -> Tm -> Tm
```

## `liftTransform`

_liftTransform: lift a base transform through paired input/output functional ornaments at unit indices — convenience wrapper for J = `Unit` on both sides._

```
liftTransform : { input, output : FunctionalOrnament, fn } -> Tm -> Tm
```

## `liftTransformIndexed`

_liftTransformIndexed: lift a base transform through paired input/output functional ornaments at explicit indices — auto-unpacks `.ornament` cores from the input side._

```
liftTransformIndexed : { input, output : FunctionalOrnament, fn } -> Tm -> Tm -> Tm -> Tm
```

## `ornament`

_ornament: user-facing entry — given a generated `DataSpec` (`base`) and a constructor-by-constructor `spec`, produce the ornamented `Datatype` with `forget` morphism baked in._

```
ornament : DataSpec -> OrnamentSpec -> Datatype
```

## `pullback`

_pullback: apply a base function `baseFn` to a forgotten ornamented value — the value-level companion to `pullbackHoas`, running entirely in HOAS application._

```
pullback : OrnamentedDatatype -> Tm -> Tm -> Tm
```

## `pullbackHoas`

_pullbackHoas: HOAS-level pullback of a base function `baseFn : I -> baseMu -> R(i)` through an ornamented carrier — auto-unpacks `.ornament` cores from generated datatypes._

```
pullbackHoas : OrnamentedDatatype -> (Tm -> Tm) -> Tm -> Tm
```

## `section`

_functionalSection: extract the `section` slot of a functional ornament — the builder `i -> baseValue -> ornamentedValue` realising the section morphism._

```
functionalSection : FunctionalOrnament -> (Tm -> Tm -> Tm)
```

## `tryAlgOrn`

_tryAlgOrn: total constructor — returns `{ ok, diagnostics, value? }` where `value` is the algebraic ornament when valid, otherwise diagnostics-only._

```
tryAlgOrn : Attrs -> { ok : Bool, diagnostics : [Diagnostic], value? : Ornament }
```

## `tryFunctional`

_tryFunctional: total constructor — returns `{ ok, diagnostics, value? }` where `value` is the built functional ornament when valid, otherwise diagnostics-only._

```
tryFunctional : Attrs -> { ok : Bool, diagnostics : [Diagnostic], value? : FunctionalOrnament }
```

## `tryOrnament`

_tryOrnament: total constructor — returns `{ ok, diagnostics, value? }` where `value` is the built ornamented datatype when valid, otherwise diagnostics-only._

```
tryOrnament : DataSpec -> OrnamentSpec -> { ok : Bool, diagnostics : [Diagnostic], value? : Datatype }
```

## `validateAlgOrn`

_validateAlgOrn: total predicate `{ ok, diagnostics }` over candidate `algOrn` args — checks each algebra arm against its description shape without throwing._

```
validateAlgOrn : Attrs -> { ok : Bool, diagnostics : [Diagnostic] }
```

## `validateFunctional`

_validateFunctional: total predicate `{ ok, diagnostics }` over candidate functional-ornament `args` — `coreOf` is applied to `.ornament` first so generated datatypes pass through._

```
validateFunctional : Attrs -> { ok : Bool, diagnostics : [Diagnostic] }
```

## `validateFunctionalLaws`

_validateFunctionalLaws: delegates to `H.validateFunctionalLaws` — total predicate `{ ok, diagnostics }` over a functional ornament's law-check bundle._

```
validateFunctionalLaws : FunctionalOrnament -> { ok : Bool, diagnostics : [Diagnostic] }
```

## `validateSpec`

_validateSpec: total predicate `{ ok, diagnostics }` over an `(base, spec)` candidate for the user-facing `ornament` surface — never throws._

```
validateSpec : DataSpec -> OrnamentSpec -> { ok : Bool, diagnostics : [Diagnostic] }
```



#### Verified


High-level combinators for writing kernel-checked implementations.
Write programs with these combinators, then call `v.verify` to
type-check and extract a Nix function that is correct by construction.

## Example

```nix
# Verified successor: Nat → Nat
v.verify (H.forall "x" H.nat (_: H.nat))
         (v.fn "x" H.nat (x: H.succ x))
# → Nix function: n → n + 1
```

## Literals

- `nat : Int → Hoas` — natural number literal (S^n(zero))
- `str : String → Hoas` — string literal
- `int_ : Int → Hoas` — integer literal
- `float_ : Float → Hoas` — float literal
- `true_`, `false_` — boolean literals
- `null_` — unit value (tt)

## Binding

- `fn : String → Hoas → (Hoas → Hoas) → Hoas` — lambda abstraction
- `let_ : String → Hoas → Hoas → (Hoas → Hoas) → Hoas` — let binding

## Data Operations

- `pair`, `fst`, `snd` — Σ-type construction and projection
- `field : Hoas → String → Hoas → Hoas` — record field projection by name
- `inl`, `inr` — Sum injection
- `app` — function application

## Eliminators (Constant Motive)

These auto-generate the motive `λ_.resultTy`, so you only supply
the result type and the branches:

- `if_ : Hoas → Hoas → { then_; else_; } → Hoas` — Bool elimination
- `match : Hoas → Hoas → { zero; succ : k → ih → Hoas; } → Hoas` — Nat elimination
- `matchList : Hoas → Hoas → Hoas → { nil; cons : h → t → ih → Hoas; } → Hoas` — List elimination
- `matchSum : Hoas → Hoas → Hoas → Hoas → { left; right; } → Hoas` — Sum elimination
- `matchData : Datatype → Hoas → Hoas → { <con>; } → Hoas` — any non-parametric `H.datatype`
- `elimData : Level → Datatype → Hoas → Hoas → { <con>; } → Hoas` — `matchData` with a dependent motive

## Derived Combinators

- `map : Hoas → Hoas → Hoas → Hoas → Hoas` — map f over a list
- `fold : Hoas → Hoas → Hoas → Hoas → Hoas → Hoas` — fold over a list
- `filter : Hoas → Hoas → Hoas → Hoas` — filter a list by predicate

## Pipeline

- `verify : Hoas → Hoas → NixValue` — type-check + eval + extract
- `verifiedFn : Hoas → Hoas → VerifiedValue` — callable value with
  `_hoasImpl` for full kernel body verification in parent types

## `app`

_app: HOAS function application — `app f arg` builds the redex; β-reduces during normalisation when `f` is a lambda._

```
app : Hoas -> Hoas -> Hoas
```

## `elimData`

_elimData: generic non-parametric user-datatype eliminator with dependent motive — builds branch binders from `_dtypeMeta` and ann-wraps each body against the meta-β-reduced motive image, so branch bodies are checked rather than synthesised. Handlers keyed by ctor name, curried over fields then one IH per `recAt` field._

```
elimData : Level -> Datatype -> Hoas -> Hoas -> { <con> : field… -> ih… -> Hoas; } -> Hoas
```

## `false_`

_false_: HOAS literal — the `False` constructor of `H.bool` as `inl tt`; reflects the bool-as-sum levitation discipline._

```
false_ : Hoas
```

## `field`

_field: HOAS record field-projection by name — derives the universal-property eliminator for a mono-constructor datatype and applies it to extract the named field._

```
field : Hoas -> String -> Hoas -> Hoas
```

Requires `recordTy` to carry `_dtypeMeta` with exactly one
constructor (records are mono-constructor datatypes via
`H.record`). Throws at build time if the type is
multi-constructor, has no fields, or the requested field name
is absent. The 1-field special case reduces via ι
(`elim P (λa.a) (mk a) ≡ a`); no surface branching is needed.
Field positions are read from `meta.constructors[0].fields` in
declaration order, so renaming a field in source is a
breaking change.

## `filter`

_filter: HOAS list-filter combinator — keeps elements where `pred : elemTy -> Bool` returns `true_`; built on `listElim` plus per-element `boolElim`._

```
filter : Hoas -> Hoas -> Hoas -> Hoas
```

Annotates `pred` with `H.forall "_" elemTy (_: H.bool)` so
the application infers. `pred` must be a HOAS function term
producing a `bool` HOAS value (e.g. via `if_`, `match`, or a
direct `true_`/`false_`). Element order is preserved; the
accumulator threads via the inductive hypothesis.

## `float_`

_float_: HOAS literal — lift a Nix float to a `floatLit` HOAS term checkable against `H.float_`._

```
float_ : Float -> Hoas
```

## `fn`

_fn: HOAS lambda — `fn name domTy body` builds `λ(name:domTy). body`, with `body` a Nix function receiving the bound variable as a HOAS term._

```
fn : String -> Hoas -> (Hoas -> Hoas) -> Hoas
```

## `fold`

_fold: HOAS list-fold combinator — combines elements right-to-left using `f : elemTy -> resultTy -> resultTy` starting from `init`._

```
fold : Hoas -> Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

Annotates `f` with `H.forall "_" elemTy (_: H.forall "_" resultTy (_: resultTy))`
so the applications `f h ih` infer correctly. `f` must be a
HOAS function term built with `fn` (or nested `fn` for the
curried two-argument case). The accumulator threads through
`ih`; the empty-list case returns `init`.

## `fst`

_fst: first projection on a HOAS Σ-pair; reduces by π₁ during normalisation._

```
fst : Hoas -> Hoas
```

## `if_`

_if_: bool-elimination wrapper — supplies a constant motive `λ_.resultTy` so callers write only the result type and the two branches._

```
if_ : Hoas -> Hoas -> { then_ : Hoas; else_ : Hoas; } -> Hoas
```

Use when the branch result type does not depend on the
scrutinee. For a dependent motive (different result type per
branch), drop to `H.boolElim` directly. The synthesised motive
is `λ_:bool.resultTy`; `boolElim`'s level argument is fixed at
0 here, so cross-universe branching also needs `H.boolElim`.

## `inl`

_inl: HOAS sum left-injection — `inl leftTy rightTy term` builds an `A + B` term carrying `term : A` in the left branch._

```
inl : Hoas -> Hoas -> Hoas -> Hoas
```

## `inr`

_inr: HOAS sum right-injection — `inr leftTy rightTy term` builds an `A + B` term carrying `term : B` in the right branch._

```
inr : Hoas -> Hoas -> Hoas -> Hoas
```

## `int_`

_int_: HOAS literal — lift a Nix integer to an `intLit` HOAS term checkable against `H.int_` (the kernel `Int` axiom, distinct from `nat`)._

```
int_ : Int -> Hoas
```

## `let_`

_let_: HOAS let binding — `let_ name ty val body` builds `let name : ty = val in body`; `body` is a Nix function receiving the bound variable._

```
let_ : String -> Hoas -> Hoas -> (Hoas -> Hoas) -> Hoas
```

## `makeRecord`

_makeRecord: HOAS record construction by name — applies the mono-constructor of a μ-encoded record type to the field values in declaration order, dual to `field`'s named projection._

```
makeRecord : Hoas -> { <field> = Hoas; ... } -> Hoas
```

Dual to `field`. Given a record type built by `H.record` (or
any mono-constructor datatype carrying `_dtypeMeta`) and an
attrset keyed by field name, produces the HOAS term
`mk a₀ … aₙ₋₁` where each `aᵢ` is read from `argsAttrs`
by field name, and
field order follows `meta.constructors[0].fields` (for
`H.record`, alphabetical by name).

Throws at build time on a multi-constructor datatype, a
missing required field, or an unknown extra field. The
constructor term used is `meta.constructors[0].ctor`, exposed
on the kernel datatype attrset by `_datatypeImpl`.

Use this in verified implementations that return records, so
consumer code never needs to reach for `builtins.foldl' H.app
DT.mk [...]` or know the μ-encoding.

## `map`

_map: HOAS list-map combinator built on `listElim` — applies `f : elemTy -> resultTy` to every element, threading the inductive hypothesis to accumulate the output list._

```
map : Hoas -> Hoas -> Hoas -> Hoas -> Hoas
```

Annotates `f` with `H.forall "_" elemTy (_: resultTy)` so the
kernel can infer the application type. `f` must be a HOAS
function term (build one with `fn`), not a Nix function. For
element transformations that aren't expressible as a uniform
HOAS function (e.g. type-dependent on element shape), drop to
`H.listElim` directly.

## `match`

_match: nat-elimination wrapper — supplies a constant motive `λ_.resultTy`; the `succ` callback receives both predecessor `k` and inductive hypothesis `ih`._

```
match : Hoas -> Hoas -> { zero : Hoas; succ : Hoas -> Hoas -> Hoas; } -> Hoas
```

The succ callback receives two HOAS values: `k` (the
predecessor binder, of type `nat`) and `ih` (the inductive
hypothesis, of type `resultTy`). Use when result type is
non-dependent on the scrutinee; drop to `H.ind` for dependent
motives. Level is fixed at 0 by the synthesised motive.

## `matchData`

_matchData: `elimData` with constant motive `λ_.resultTy` — the `matchSum`/`matchList` analogue for arbitrary non-parametric `H.datatype`s._

```
matchData : Datatype -> Hoas -> Hoas -> { <con> : field… -> ih… -> Hoas; } -> Hoas
```

## `matchList`

_matchList: list-elimination wrapper — constant motive `λ_.resultTy`; the `cons` callback binds head, tail, and inductive hypothesis._

```
matchList : Hoas -> Hoas -> Hoas -> { nil : Hoas; cons : Hoas -> Hoas -> Hoas -> Hoas; } -> Hoas
```

The cons callback receives three HOAS values: `h` (the head
element of type `elemTy`), `t` (the tail list of type
`listOf elemTy`), and `ih` (the inductive hypothesis of type
`resultTy`). For dependent motives, drop to `H.listElim`.
Level fixed at 0.

## `matchSum`

_matchSum: sum-elimination wrapper — constant motive `λ_.resultTy`; the left and right callbacks receive their respective payloads._

```
matchSum : Hoas -> Hoas -> Hoas -> Hoas -> { left : Hoas -> Hoas; right : Hoas -> Hoas; } -> Hoas
```

Each callback receives one HOAS value: the left payload for
`left`, the right payload for `right`. Use when the result
type doesn't depend on which case fires; drop to `H.sumElim`
for dependent motives. Level fixed at 0.

## `nat`

_nat: HOAS literal — wrap a Nix `Int` as a `succ^n zero` natural-number HOAS term checkable against `H.nat`._

```
nat : Int -> Hoas
```

## `null_`

_null_: HOAS literal — the unique inhabitant `tt` of `H.unit`; the conventional empty / placeholder value in verified code._

```
null_ : Hoas
```

## `pair`

_pair: HOAS Σ-pair constructor — `pair fst snd` packages two HOAS values; the surrounding annotation fixes which Σ-type the pair inhabits._

```
pair : Hoas -> Hoas -> Hoas
```

## `snd`

_snd: second projection on a HOAS Σ-pair; reduces by π₂ during normalisation._

```
snd : Hoas -> Hoas
```

## `str`

_str: HOAS literal — lift a Nix `String` to a `stringLit` HOAS term checkable against `H.string`._

```
str : String -> Hoas
```

## `strElem`

_strElem: HOAS membership check on a `List String` — folds `strEq target` across the list, accumulating `true_` if any element matches._

```
strElem : Hoas -> Hoas -> Hoas
```

Built on `fold` plus `strEq`: each list element is compared
to `target`; the accumulator starts at `false_` and stays
`true_` once a match is seen. Use when verified code needs a
membership predicate over strings; for raw kernel-level
equality on a single pair, use `strEq`.

## `strEq`

_strEq: kernel string equality returning a `Bool` HOAS term; reflects the `mkStrEq` primitive of the kernel._

```
strEq : Hoas -> Hoas -> Hoas
```

## `true_`

_true_: HOAS literal — the `True` constructor of `H.bool` as `inr tt`; reflects the bool-as-sum levitation discipline._

```
true_ : Hoas
```

## `verifiedFn`

_verifiedFn: extract a kernel-verified callable carrying `_hoasImpl` — `elaborateValue`'s Pi case uses the HOAS body for full re-verification instead of falling back to an opaque trust boundary._

```
verifiedFn : Hoas -> Hoas -> { __functor; _hoasImpl }
```

Returns an attrset callable via `__functor` (so
`(verifiedFn piTy body) arg` works) and carrying
`_hoasImpl = body` so parent elaboration can re-check the body
against a more general type instead of treating it as an
opaque lambda. Use when the verified function will be
embedded inside another verified type-check (e.g. as a field
of a verified record); for standalone use, `verify` is
simpler.

## `verify`

_verify: full pipeline — kernel-check a HOAS implementation against a HOAS type, then evaluate and extract a Nix value witnessing the body._

```
verify : Hoas -> Hoas -> NixValue
```

Calls `fx.tc.elaborate.verifyAndExtract` internally. Returns
the Nix value (typically a function or data structure) that
the type-checked HOAS body denotes; consume via normal Nix
call or attribute access. Use as the final step of a
verified-implementation pipeline. For a callable wrapper that
retains the HOAS implementation so parent-type elaboration can
re-check the body, use `verifiedFn` instead.



#### Kernel


Kernel-internal `validate` for the internalizable fragment of
`mkType`-buildable types. A code is a base carrier type (any `U_0`
type — a mu-encoded inductive or a primitive) paired with a finite
stack of predicates over that carrier; the decider is the conjunction
of the stack.

## Surface (`ktype`)

- `KType : U_1` — a base carrier type paired with a predicate stack
- `beta t : U_0` — the base carrier of a code (constant along refinement)
- `psi t : beta t -> Bool` — the accumulated membership predicate
- `El t` — the derived refinement subtype `Sigma x:beta t. P (psi t x)`
- `P` — the `Bool -> U_0` membership decoder (`P true ~> Unit`, `P false ~> Void`)
- `betaFn`/`decideFn`/`ElFn` — the same functions as closed kernel terms
- `andB`, `iota`/`refine` constructor helpers

## Decision (`decide`)

- `decide t : beta t -> Bool` — membership in `El t`; `decide = psi`

## `decide`

_fx.tc.kernel.decide: the membership decision procedure decide = psi : (t:KType) -> beta t -> Bool._

## `failure`

_fx.tc.kernel.failure: the kernel transcription of the diagnostic Error ADT (DiagError — a mono-constructor record over Layer/Detail/msg/hint and an opaque Unit children slot) and the Failure of a rejected check as a dependent Sigma-chain (FailureTy = Sigma ktp:KType. Sigma x:(beta ktp). Sigma ctx. Sigma rsn. Sigma pth. DiagError; FailureTheory the base-only Sigma). Layer/Detail sub-shapes, the layerOf/detailOf/mkDiag/mkFailure constructors, the fst_/snd_-spine Failure projections, and the named DiagError field projections._

## `handlers`

_fx.tc.kernel.handlers: the six typecheck-policy handlers (strict/collecting/logging/firstN/summarize/pretty) as closed kernel step terms folding a stream of membership decisions into accumulated state. A decision is a host-known boolean `passed` plus an opaque host-rendered residue Rec; each step is `... -> Σ State payload` whose reduction is the state transition. firstN carries an O(1) down-counter; summarize renders the reason enum to its production key token via `reasonName` and groups failures into a `List (Σ String Nat)` assoc list via `insertOrIncrement` (a `listElim`+`strEq` fold). Exports the step terms, their result shapes, and the Reason/assoc grouping vocabulary._

## `ktype`

_fx.tc.kernel.ktype: flat predicate-stack datum — KType : U_1 (a base carrier type paired with a predicate stack over it), beta (the carrier), the accumulator-fold decider psi/decide, derived El, the membership decoder P, andB, and the iota/refine constructors._

## `reflect`

_fx.tc.kernel.reflect: reflect a Nix-side carrier type into its KType code (reflect/reflectRefine), the checkable Boolean predicate vocabulary for refinement arms — Int over the primitive carrier via the host-backed intLe/intEq (positiveInt, nonNegativeInt, inRangeInt, eqInt) and String literal-set membership (oneOfStrTerm, via strEq) plus non-emptiness (strNonEmptyTerm, via strLen) — and the KernelPred witness layer (mkKernelPred, andKP, isKernelPred, sealed, kernelExpressible, ktypeOf, deriveGuard) with ready-made witnesses: Int (intPositive, intNonNegative, intInRange, intEq) and String (strOneOf, strNonEmpty), O(1)-bridged and guard-derived from their kernel terms._

## `validate`

_fx.tc.kernel.validate: the membership-decision arm of typechecking. validateClosed t v context reason path diagError decides membership with the kernel oracle (elaborate.decide) and either returns `pure v` or raises the host `typeCheck` effect with the caller-supplied diagnostics — the closed-input generalization of the auto-derived validateAt. validateK R t reason path carrier x is the kernel-internal report producer: it emits one kernel `report` op whose decision is the KType decider applied to the carrier (`decide t x`), returning `freeFx (EffTypeCheck R) Resp Unit` for the kernel handlers to fold. validateEl R t payload x is the kernel-internal certifier — the membership-witness dual of validateK: it produces the dependent witness `El t` when `decide t x` accepts, and otherwise aborts on EffError's strict (Void-response) raise carrying the opaque payload, so no witness is ever forged; returns `freeFx (EffError R) Resp_strict (El t)`._

## Source

- [`src/tc/kernel/decide.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/decide.nix)
- [`src/tc/kernel/failure.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/failure.nix)
- [`src/tc/kernel/flat-faithfulness.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/flat-faithfulness.nix)
- [`src/tc/kernel/handlers.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/handlers.nix)
- [`src/tc/kernel/ktype.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/ktype.nix)
- [`src/tc/kernel/level-soundness.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/level-soundness.nix)
- [`src/tc/kernel/reflect.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/reflect.nix)
- [`src/tc/kernel/soundness.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/soundness.nix)
- [`src/tc/kernel/validate.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/tc/kernel/validate.nix)



### Diagnostic Hints

#### DArgSort::universe-mismatch


**Key:** `DArgSort::universe-mismatch`

**Category:** universe · **Severity:** error

**Source:** [`src/diag/hints.nix:844`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L844)

the sort position of `arg` must live in U(0); descriptions only carry small types. Pass `u 0`, or factor the dependency through `descRec` / `descPi` if a larger type is genuinely needed.

## Example

`Hint::DArgSort::universe-mismatch` means the `DArgSort` position uses a universe level that is too large for that slot. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: description argument sorts must stay in U0.
descArg (u 1) (_: descRet tt)

# Better: keep the argument sort small.
descArg (u 0) (_: descRet tt)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DPiSort::universe-mismatch


**Key:** `DPiSort::universe-mismatch`

**Category:** universe · **Severity:** error

**Source:** [`src/diag/hints.nix:848`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L848)

the sort position of `pi` must live in U(0); `descPi` takes a small domain. Use `u 0`, or encode the dependency through an index instead of the Pi domain.

## Example

`Hint::DPiSort::universe-mismatch` means the `DPiSort` position uses a universe level that is too large for that slot. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: descPi's domain sort is too large.
descPi (u 1) f (_: descRet tt)

# Better: use a small domain sort.
descPi (u 0) f (_: descRet tt)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### LevelMaxLhs::type-mismatch


**Key:** `LevelMaxLhs::type-mismatch`

**Category:** universe · **Severity:** error

**Source:** [`src/diag/hints.nix:922`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L922)

the left operand of `max` must be a Level

## Example

`Hint::LevelMaxLhs::type-mismatch` means the `LevelMaxLhs` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: max's left operand is not a Level.
levelMax nat level0

# Better: both operands are levels.
levelMax level0 level1

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### LevelMaxRhs::type-mismatch


**Key:** `LevelMaxRhs::type-mismatch`

**Category:** universe · **Severity:** error

**Source:** [`src/diag/hints.nix:924`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L924)

the right operand of `max` must be a Level

## Example

`Hint::LevelMaxRhs::type-mismatch` means the `LevelMaxRhs` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: max's right operand is not a Level.
levelMax level0 nat

# Better: both operands are levels.
levelMax level0 level1

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### LevelSucPred::type-mismatch


**Key:** `LevelSucPred::type-mismatch`

**Category:** universe · **Severity:** error

**Source:** [`src/diag/hints.nix:920`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L920)

the predecessor of `suc` must be a Level

## Example

`Hint::LevelSucPred::type-mismatch` means the `LevelSucPred` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: suc expects a Level.
levelSuc nat

# Better: pass a level expression.
levelSuc level0

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### ULevel::type-mismatch


**Key:** `ULevel::type-mismatch`

**Category:** universe · **Severity:** error

**Source:** [`src/diag/hints.nix:926`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L926)

the level argument of `U` must be a Level

## Example

`Hint::ULevel::type-mismatch` means the `ULevel` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: U expects a Level argument.
u nat

# Better: pass a level.
u level0

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### AnnType::not-a-type


**Key:** `AnnType::not-a-type`

**Category:** sort · **Severity:** error

**Source:** [`src/diag/hints.nix:862`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L862)

the annotation position must be a type (live in some U(k)), not a term. Write a type expression such as `nat`, `bool`, `u 0`, or a user-defined datatype.

## Example

`Hint::AnnType::not-a-type` means the `AnnType` position uses a term or value where the checker needs a type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the annotation is a term.
ann (natLit 0) (natLit 1)

# Better: annotate with a type.
ann (natLit 0) nat

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### JType::not-a-type


**Key:** `JType::not-a-type`

**Category:** sort · **Severity:** error

**Source:** [`src/diag/hints.nix:870`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L870)

the type parameter of `J` must be a type (live in some U(k)), not a term. Pass a type expression like `nat`, `u 0`, or the type shared by J's two endpoints.

## Example

`Hint::JType::not-a-type` means the `JType` position uses a term or value where the checker needs a type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: J's type argument is a term.
J (natLit 0) motive refl x y p

# Better: J's type argument is the type of both endpoints.
J nat motive refl x y p

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Motive.PiDom::not-a-type


**Key:** `Motive.PiDom::not-a-type`

**Category:** sort · **Severity:** error

**Source:** [`src/diag/hints.nix:931`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L931)

the motive's domain must be a type (live in some U(k)). The motive receives the scrutinee's type as its domain and returns a type; supply a concrete type such as `nat`, `u 0`, or the datatype being eliminated.

## Example

`Hint::Motive.PiDom::not-a-type` means the `PiDom` position under `Motive` uses a term or value where the checker needs a type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the motive's Pi domain is a term.
motive = pi (natLit 0) (_: u 0)

# Better: the motive's Pi domain is a type.
motive = pi nat (_: u 0)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Motive::not-a-type


**Key:** `Motive::not-a-type`

**Category:** sort · **Severity:** error

**Source:** [`src/diag/hints.nix:894`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L894)

an eliminator's motive must return a type (live in some U(k))

## Example

`Hint::Motive::not-a-type` means the `Motive` position uses a term or value where the checker needs a type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the motive returns a term.
motive = x: natLit 0

# Better: the motive returns a type.
motive = x: nat

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### PiCod::not-a-type


**Key:** `PiCod::not-a-type`

**Category:** sort · **Severity:** error

**Source:** [`src/diag/hints.nix:860`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L860)

the codomain family of Π must return a type for each argument, not an ordinary value. Provide a function whose body inhabits some `U k`.

## Example

`Hint::PiCod::not-a-type` means the `PiCod` position uses a term or value where the checker needs a type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the codomain family returns a term.
pi nat (_: natLit 0)

# Better: the codomain family returns a type.
pi nat (_: nat)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### PiDom::not-a-type


**Key:** `PiDom::not-a-type`

**Category:** sort · **Severity:** error

**Source:** [`src/diag/hints.nix:858`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L858)

the domain of Π must be a type (live in some U(k)), not a term or value. Supply a type expression like `nat`, `bool`, `u 0`, or a user-defined datatype.

## Example

`Hint::PiDom::not-a-type` means the `PiDom` position uses a term or value where the checker needs a type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: a Pi domain must be a type, not a term.
pi (natLit 0) (_: nat)

# Better: put a type in the domain.
pi nat (_: nat)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DArgBody::not-a-desc


**Key:** `DArgBody::not-a-desc`

**Category:** description · **Severity:** error

**Source:** [`src/diag/hints.nix:846`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L846)

the body of `arg` must produce a description (Desc I), not an ordinary value. Build one with `descRet`, `descArg`, `descRec`, `descPi`, or `descPlus`.

## Example

`Hint::DArgBody::not-a-desc` means the `DArgBody` position uses an ordinary term where the checker needs a Desc. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the body returns an ordinary term.
descArg nat (_: natLit 0)

# Better: the body returns a description.
descArg nat (_: descRet tt)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DPiBody::not-a-desc


**Key:** `DPiBody::not-a-desc`

**Category:** description · **Severity:** error

**Source:** [`src/diag/hints.nix:850`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L850)

the body of `pi` must produce a description for each input, not a plain term. Return a Desc I via `descRet`, `descArg`, `descRec`, `descPi`, or `descPlus`.

## Example

`Hint::DPiBody::not-a-desc` means the `DPiBody` position uses an ordinary term where the checker needs a Desc. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the dependent body returns a term.
descPi nat f (_: natLit 0)

# Better: the dependent body returns a Desc.
descPi nat f (_: descRet tt)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DPlusL::not-a-desc


**Key:** `DPlusL::not-a-desc`

**Category:** description · **Severity:** error

**Source:** [`src/diag/hints.nix:876`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L876)

the left summand of `plus` must be a description (Desc I)

## Example

`Hint::DPlusL::not-a-desc` means the `DPlusL` position uses an ordinary term where the checker needs a Desc. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the left summand is not a description.
descPlus (natLit 0) rightDesc

# Better: both summands are descriptions.
descPlus (descRet tt) rightDesc

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DPlusR::not-a-desc


**Key:** `DPlusR::not-a-desc`

**Category:** description · **Severity:** error

**Source:** [`src/diag/hints.nix:878`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L878)

the right summand of `plus` must be a description at the same index type as the left summand

## Example

`Hint::DPlusR::not-a-desc` means the `DPlusR` position uses an ordinary term where the checker needs a Desc. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the right summand is not a description.
descPlus leftDesc (natLit 0)

# Better: both summands are descriptions.
descPlus leftDesc (descRet tt)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DRecTail::not-a-desc


**Key:** `DRecTail::not-a-desc`

**Category:** description · **Severity:** error

**Source:** [`src/diag/hints.nix:856`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L856)

the tail position of `rec` must itself be a description, not an ordinary term. Continue the spine with `descRet`, `descArg`, `descRec`, `descPi`, or `descPlus`.

## Example

`Hint::DRecTail::not-a-desc` means the `DRecTail` position uses an ordinary term where the checker needs a Desc. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the tail after a recursive position is a term.
descRec i (natLit 0)

# Better: continue with another description.
descRec i (descRet i)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### MuDesc::not-a-desc


**Key:** `MuDesc::not-a-desc`

**Category:** description · **Severity:** error

**Source:** [`src/diag/hints.nix:864`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L864)

the description argument of μ must be a Desc I term, not an ordinary value. Construct it with `descRet`, `descArg`, `descRec`, `descPi`, or `descPlus`.

## Example

`Hint::MuDesc::not-a-desc` means the `MuDesc` position uses an ordinary term where the checker needs a Desc. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: mu expects a Desc, not a term.
mu nat (natLit 0)

# Better: construct the Desc explicitly.
mu nat (descRet zero)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### AppHead::not-a-function


**Key:** `AppHead::not-a-function`

**Category:** arity · **Severity:** error

**Source:** [`src/diag/hints.nix:882`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L882)

the head of an application must have a function type (Pi)

## Example

`Hint::AppHead::not-a-function` means the `AppHead` position uses a non-function where the checker needs a Pi-typed term. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the application head is not a function.
app (natLit 0) (natLit 1)

# Better: apply a lambda or another Pi-typed term.
app (lam "x" nat (x: x)) (natLit 1)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DPiFn::not-a-function


**Key:** `DPiFn::not-a-function`

**Category:** arity · **Severity:** error

**Source:** [`src/diag/hints.nix:872`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L872)

the index selector `f` of `pi` must be a function `S -> I`

## Example

`Hint::DPiFn::not-a-function` means the `DPiFn` position uses a non-function where the checker needs a Pi-typed term. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the index selector is not a function.
descPi nat expectedIndex (_: descRet expectedIndex)

# Better: provide a selector from the domain into the index type.
descPi nat (x: expectedIndex) (_: descRet expectedIndex)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Motive::not-a-function


**Key:** `Motive::not-a-function`

**Category:** arity · **Severity:** error

**Source:** [`src/diag/hints.nix:868`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L868)

the motive must be a function from the scrutinee's type into a type, not a bare type or value. Supply a one-argument function whose body lives in some `U k`.

## Example

`Hint::Motive::not-a-function` means the `Motive` position uses a non-function where the checker needs a Pi-typed term. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: an eliminator motive is a bare type.
natElim nat zero succCase n

# Better: make the motive a function from the scrutinee.
natElim (x: nat) zero succCase n

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### OpaqueType::not-a-function


**Key:** `OpaqueType::not-a-function`

**Category:** arity · **Severity:** error

**Source:** [`src/diag/hints.nix:890`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L890)

the annotation on an opaque lambda must be a Pi type

## Example

`Hint::OpaqueType::not-a-function` means the `OpaqueType` position uses a non-function where the checker needs a Pi-typed term. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: an opaque lambda annotation must be a Pi type.
opaqueLam nat body

# Better: annotate it with a function type.
opaqueLam (pi nat (_: nat)) body

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DPiFn::type-mismatch


**Key:** `DPiFn::type-mismatch`

**Category:** indexing · **Severity:** error

**Source:** [`src/diag/hints.nix:874`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L874)

the index selector's domain must match the declared sort `S`

## Example

`Hint::DPiFn::type-mismatch` means the `DPiFn` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the selector domain does not match the declared sort.
descPi nat (s: stringIndex) (_: descRet stringIndex)

# Better: the selector consumes the same sort descPi declares.
descPi nat (n: natIndex n) (_: descRet (natIndex n))

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DRecIndex::type-mismatch


**Key:** `DRecIndex::type-mismatch`

**Category:** indexing · **Severity:** error

**Source:** [`src/diag/hints.nix:854`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L854)

the index position of `rec` must match the Desc's declared index type. Pass a term of that index type, or adjust the enclosing `μ I ...` to match.

## Example

`Hint::DRecIndex::type-mismatch` means the `DRecIndex` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the recursive position points at the wrong index type.
descRec wrongIndex tailDesc

# Better: recurse at an index from the Desc index type.
descRec expectedIndex tailDesc

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### DRetIndex::type-mismatch


**Key:** `DRetIndex::type-mismatch`

**Category:** indexing · **Severity:** error

**Source:** [`src/diag/hints.nix:852`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L852)

the index position of `ret` must match the Desc's declared index type. Supply a term of that index type, or redefine the enclosing `μ I ...` over the index you actually have.

## Example

`Hint::DRetIndex::type-mismatch` means the `DRetIndex` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the return index is not in the Desc index type.
descRet wrongIndex

# Better: return at an index of the declared index type.
descRet expectedIndex

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### MuIndex::type-mismatch


**Key:** `MuIndex::type-mismatch`

**Category:** indexing · **Severity:** error

**Source:** [`src/diag/hints.nix:886`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L886)

the index passed to `con` must have the description's index type

## Example

`Hint::MuIndex::type-mismatch` means the `MuIndex` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the constructor index has the wrong type.
con wrongIndex payload

# Better: construct at an index from the declared index type.
con expectedIndex payload

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### MuPayload::type-mismatch


**Key:** `MuPayload::type-mismatch`

**Category:** indexing · **Severity:** error

**Source:** [`src/diag/hints.nix:888`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L888)

the payload of `con` must inhabit the description's interpretation at the given index

## Example

`Hint::MuPayload::type-mismatch` means the `MuPayload` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the payload does not match the constructor description.
con expectedIndex wrongPayload

# Better: build a payload matching the description at that index.
con expectedIndex expectedPayload

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Elem::inhabitation-failed


**Key:** `Elem::inhabitation-failed`

**Category:** inhabitation · **Severity:** error

**Source:** [`src/diag/hints.nix:902`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L902)

the element does not inhabit the list's element type

## Example

`Hint::Elem::inhabitation-failed` means the `Elem` position contains a value that does not inhabit the generated type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: a list element does not inhabit the element type.
IntList.validate [ 1 "two" 3 ]

# Better: every element inhabits the element type.
IntList.validate [ 1 2 3 ]

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Field::inhabitation-failed


**Key:** `Field::inhabitation-failed`

**Category:** inhabitation · **Severity:** error

**Source:** [`src/diag/hints.nix:898`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L898)

the field's value does not inhabit the declared field type

## Example

`Hint::Field::inhabitation-failed` means the `Field` position contains a value that does not inhabit the generated type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the field value has the wrong shape.
User.validate { name = 42; }

# Better: use a value inhabiting the field type.
User.validate { name = "alice"; }

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### SigmaFst::inhabitation-failed


**Key:** `SigmaFst::inhabitation-failed`

**Category:** inhabitation · **Severity:** error

**Source:** [`src/diag/hints.nix:912`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L912)

the first component does not inhabit the declared `fst` type

## Example

`Hint::SigmaFst::inhabitation-failed` means the `SigmaFst` position contains a value that does not inhabit the generated type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the first component does not inhabit fst's type.
pair "not-a-nat" proof

# Better: fst inhabits its declared type.
pair (natLit 3) proof

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### SigmaSnd::inhabitation-failed


**Key:** `SigmaSnd::inhabitation-failed`

**Category:** inhabitation · **Severity:** error

**Source:** [`src/diag/hints.nix:914`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L914)

the second component does not inhabit the dependent `snd` type

## Example

`Hint::SigmaSnd::inhabitation-failed` means the `SigmaSnd` position contains a value that does not inhabit the generated type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the second component does not inhabit snd's dependent type.
pair (natLit 3) "not-a-proof"

# Better: snd inhabits the type determined by fst.
pair (natLit 3) proofFor3

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Tag::inhabitation-failed


**Key:** `Tag::inhabitation-failed`

**Category:** inhabitation · **Severity:** error

**Source:** [`src/diag/hints.nix:906`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L906)

the variant's payload does not inhabit the branch type

## Example

`Hint::Tag::inhabitation-failed` means the `Tag` position contains a value that does not inhabit the generated type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the variant payload does not inhabit the branch type.
Result.validate { tag = "Ok"; value = false; }

# Better: the payload matches the selected branch.
Result.validate { tag = "Ok"; value = 200; }

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Elem::refinement-failed


**Key:** `Elem::refinement-failed`

**Category:** refinement · **Severity:** error

**Source:** [`src/diag/hints.nix:904`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L904)

the element violates the element type's refinement predicate

## Example

`Hint::Elem::refinement-failed` means the `Elem` position contains a value that fails the refinement predicate. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: one element fails the element refinement.
PositiveList.validate [ 1 -2 3 ]

# Better: every element satisfies the refinement.
PositiveList.validate [ 1 2 3 ]

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Field::refinement-failed


**Key:** `Field::refinement-failed`

**Category:** refinement · **Severity:** error

**Source:** [`src/diag/hints.nix:900`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L900)

the field's value violates the field type's refinement predicate

## Example

`Hint::Field::refinement-failed` means the `Field` position contains a value that fails the refinement predicate. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the field has the right base type but fails its predicate.
User.validate { age = -1; }

# Better: satisfy the refinement predicate.
User.validate { age = 42; }

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### SigmaFst::refinement-failed


**Key:** `SigmaFst::refinement-failed`

**Category:** refinement · **Severity:** error

**Source:** [`src/diag/hints.nix:916`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L916)

the first component violates the `fst` type's refinement predicate

## Example

`Hint::SigmaFst::refinement-failed` means the `SigmaFst` position contains a value that fails the refinement predicate. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: fst has the right base type but fails its refinement.
pair (-1) proof

# Better: fst satisfies the refinement.
pair 1 proof

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### SigmaSnd::refinement-failed


**Key:** `SigmaSnd::refinement-failed`

**Category:** refinement · **Severity:** error

**Source:** [`src/diag/hints.nix:918`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L918)

the second component violates the `snd` type's refinement predicate

## Example

`Hint::SigmaSnd::refinement-failed` means the `SigmaSnd` position contains a value that fails the refinement predicate. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: snd fails the refinement depending on fst.
pair 3 (-1)

# Better: snd satisfies the dependent refinement.
pair 3 4

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Tag::refinement-failed


**Key:** `Tag::refinement-failed`

**Category:** refinement · **Severity:** error

**Source:** [`src/diag/hints.nix:908`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L908)

the variant's payload violates the branch type's refinement predicate

## Example

`Hint::Tag::refinement-failed` means the `Tag` position contains a value that fails the refinement predicate. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the variant payload fails the branch refinement.
Port.validate { tag = "Tcp"; value = -1; }

# Better: the payload satisfies the branch refinement.
Port.validate { tag = "Tcp"; value = 443; }

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Case::type-mismatch


**Key:** `Case::type-mismatch`

**Category:** elimination · **Severity:** error

**Source:** [`src/diag/hints.nix:910`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L910)

this case-body's inferred type does not match the type the eliminator's motive requires

## Example

`Hint::Case::type-mismatch` means the `Case` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: one case branch returns the wrong type.
caseOf scrutinee { left = x: true_; right = y: natLit 0; }

# Better: all branches return the motive's type.
caseOf scrutinee { left = x: natLit 1; right = y: natLit 0; }

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### Scrut::type-mismatch


**Key:** `Scrut::type-mismatch`

**Category:** elimination · **Severity:** error

**Source:** [`src/diag/hints.nix:866`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L866)

the scrutinee's type must match the eliminator's expected shape. Annotate the scrutinee via `ann`, or switch to the eliminator that matches its inferred type.

## Example

`Hint::Scrut::type-mismatch` means the `Scrut` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the eliminator is used on a scrutinee of the wrong type.
natElim motive zero succCase true_

# Better: use a scrutinee with the eliminator's type.
natElim motive zero succCase (natLit 3)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### AnnTerm::type-mismatch


**Key:** `AnnTerm::type-mismatch`

**Category:** type-mismatch · **Severity:** error

**Source:** [`src/diag/hints.nix:880`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L880)

the annotated term does not match its declared type

## Example

`Hint::AnnTerm::type-mismatch` means the `AnnTerm` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the annotated term does not inhabit the annotation.
ann true_ nat

# Better: the term matches the annotation.
ann (natLit 1) nat

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### AppArg::type-mismatch


**Key:** `AppArg::type-mismatch`

**Category:** type-mismatch · **Severity:** error

**Source:** [`src/diag/hints.nix:884`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L884)

the argument does not match the function's domain

## Example

`Hint::AppArg::type-mismatch` means the `AppArg` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the argument does not match the function domain.
app (lam "x" nat (x: x)) true_

# Better: pass an argument from the domain.
app (lam "x" nat (x: x)) (natLit 1)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### JType::type-mismatch


**Key:** `JType::type-mismatch`

**Category:** type-mismatch · **Severity:** error

**Source:** [`src/diag/hints.nix:896`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L896)

the type parameter of `J` must match the type of its two endpoints

## Example

`Hint::JType::type-mismatch` means the `JType` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: J's type argument does not match the endpoints.
J bool motive refl zero zero p

# Better: use the endpoints' shared type.
J nat motive refl zero zero p

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### OpaqueType::type-mismatch


**Key:** `OpaqueType::type-mismatch`

**Category:** type-mismatch · **Severity:** error

**Source:** [`src/diag/hints.nix:892`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L892)

the opaque lambda's declared domain does not match the expected domain

## Example

`Hint::OpaqueType::type-mismatch` means the `OpaqueType` position supplies a term whose type does not match the expected type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: the opaque lambda domain disagrees with the expected domain.
opaqueLam (pi bool (_: nat)) body

# Better: align the declared domain with the expected Pi domain.
opaqueLam (pi nat (_: nat)) body

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### ::unhandled-boot-inl


**Key:** `::unhandled-boot-inl`

**Category:** shape · **Severity:** error

**Source:** [`src/diag/hints.nix:945`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L945)

the left injection `inl x` has no inference rule — the sum type's right summand is not determined by the syntax of `x` alone. Annotate with `ann (inl x) (sum A B)` to fix the expected sum, or place it where checking already provides one.

## Example

`Hint::unhandled-boot-inl` means `inl` is in inference mode without an expected Sum type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: inl does not determine the right summand by itself.
infer emptyCtx (inl (natLit 1))

# Better: annotate the intended sum type.
infer emptyCtx (ann (inl (natLit 1)) (sum nat bool))

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### ::unhandled-boot-inr


**Key:** `::unhandled-boot-inr`

**Category:** shape · **Severity:** error

**Source:** [`src/diag/hints.nix:947`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L947)

the right injection `inr y` has no inference rule — the sum type's left summand is not determined by the syntax of `y` alone. Annotate with `ann (inr y) (sum A B)` to fix the expected sum, or place it where checking already provides one.

## Example

`Hint::unhandled-boot-inr` means `inr` is in inference mode without an expected Sum type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: inr does not determine the left summand by itself.
infer emptyCtx (inr true_)

# Better: annotate the intended sum type.
infer emptyCtx (ann (inr true_) (sum nat bool))

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### ::unhandled-boot-refl


**Key:** `::unhandled-boot-refl`

**Category:** shape · **Severity:** error

**Source:** [`src/diag/hints.nix:949`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L949)

`refl` has no inference rule — the type of the equated endpoint is not determined by its syntax. Annotate with `ann refl (eq A x x)`, or use `refl` where the surrounding rule already supplies an expected equality type.

## Example

`Hint::unhandled-boot-refl` means `refl` is in inference mode without an expected equality type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: refl does not determine the equality type by itself.
infer emptyCtx refl

# Better: annotate the equality being proven.
infer emptyCtx (ann refl (eq nat zero zero))

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### ::unhandled-lam


**Key:** `::unhandled-lam`

**Category:** shape · **Severity:** error

**Source:** [`src/diag/hints.nix:939`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L939)

this lambda has no inference rule — its domain and codomain types are not determined by its syntax. Annotate with `ann (lam …) (pi A B)` to drive checking, or place it where the surrounding rule already supplies an expected Pi type.

## Example

`Hint::unhandled-lam` means a lambda is in inference mode without an expected Pi type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: a lambda reaches inference without an expected Pi type.
infer emptyCtx (lam "x" nat (x: x))

# Better: annotate it so checking mode knows the Pi type.
infer emptyCtx (ann (lam "x" nat (x: x)) (pi nat (_: nat)))

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### ::unhandled-other


**Key:** `::unhandled-other`

**Category:** shape · **Severity:** error

**Source:** [`src/diag/hints.nix:951`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L951)

this intro form has no inference rule — its type is not determined by its syntax alone. Either annotate the term with `ann <term> <type>` to switch the kernel into checking mode, or move it inside a context where an expected type is already known.

## Example

`Hint::unhandled-other` means an introduction form is in inference mode without enough expected type information. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: an introduction form reaches inference without context.
infer emptyCtx introForm

# Better: annotate the expected type at the boundary.
infer emptyCtx (ann introForm expectedType)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### ::unhandled-pair


**Key:** `::unhandled-pair`

**Category:** shape · **Severity:** error

**Source:** [`src/diag/hints.nix:941`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L941)

this pair has no inference rule — its component types are not determined by its syntax. Annotate with `ann (pair …) (sigma A B)` to drive checking, or place it where the surrounding rule already supplies an expected Sigma type.

## Example

`Hint::unhandled-pair` means a pair is in inference mode without an expected Sigma type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: a pair reaches inference without an expected Sigma type.
infer emptyCtx (pair (natLit 1) true_)

# Better: annotate it with the Sigma type it should inhabit.
infer emptyCtx (ann (pair (natLit 1) true_) (sigma "x" nat (_: bool)))

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


#### ::unhandled-tt


**Key:** `::unhandled-tt`

**Category:** shape · **Severity:** error

**Source:** [`src/diag/hints.nix:943`](https://github.com/kleisli-io/nix-effects/blob/main/src/diag/hints.nix#L943)

the unit value `tt` has no inference rule — there is exactly one type it can inhabit. The kernel still asks for an annotation to keep inference syntax-directed. Use `ann tt unit` at the use site, or check `tt` against an expected `unit` type.

## Example

`Hint::unhandled-tt` means `tt` is in inference mode without an expected Unit type. The example shows the failing form first, then one way to give the checker the missing structure.

```nix
# Bad: tt reaches inference without an expected Unit type.
infer emptyCtx tt

# Better: annotate tt or check it against unit.
infer emptyCtx (ann tt unit)

```


---

[← All diagnostic hints](/nix-effects/diag-hints)


## Additional pages (including unstable internal surfaces)

### Applications


Application examples are full modules rather than isolated snippets.
They expose ordinary Nix APIs, include prose walkthroughs, and provide
workload generators consumed by the benchmark suite.

The source for this section lives under [examples/](https://github.com/kleisli-io/nix-effects/tree/main/examples).

## Walkthroughs

- [Category Theory](/nix-effects/application-examples/categoryTheory): Kernel-checked arithmetic, algebra, functors, and Yoneda-style constructions.
- [Expression Interpreter](/nix-effects/application-examples/interp): A small expression language interpreted with lookup, scoped environment, and failure effects.
- [Build Simulator](/nix-effects/application-examples/buildSim): A dependency-graph evaluator with cache, configuration, logging, and failure effects.



### Concepts


Concepts collects the theory that shapes the library. It is useful
when you want the design vocabulary behind the implementation:
algebraic effects, freer monads, queue-backed binds, normalization by
evaluation, and levitated descriptions.


### Diagnostic Hints


Diagnostic hints are stable labels for recurring checker and validation
failures. When an error includes a `Hint::<key>` token, the matching
page explains what the key means and where to start debugging.

Use this section when the raw error is too local and you need the
larger shape of the failure: which kind of invariant was violated,
what the checker was trying to establish, and what sort of change is
usually relevant.

Each hint page also points back to the source location that emits the
hint.


### Effects and Validation


Effect examples keep the computation fixed and change the handler.
This makes policy choices explicit: collect validation errors, log
each check, or stop at the first failure.

The source for this section lives under [examples/](https://github.com/kleisli-io/nix-effects/tree/main/examples).

## Walkthroughs

- [Handler-Swap Validation](/nix-effects/effect-examples/handlerSwapValidation): Run one validation computation with collecting, logging, and strict handlers.



### Examples


The examples show nix-effects in complete, small programs. They move
from proof construction, to effect-handler policy, to surface languages
built over the HOAS kernel, to application-sized interpreters and graph
evaluators.

The same examples live in the source tree under `examples/` if you want
to run or adapt them locally.

## Where to start

Start with proof examples when you want to see values checked by the
kernel. Use the effect example to compare validation policies without
changing the computation. Use the surface-language examples when you
want to build a small syntax layer over HOAS. Use the application
examples when you want complete programs that also feed the benchmark
suite.

```nix
examples/
  proof-basics.nix
  equality-proofs.nix
  verified-functions.nix
  handler-swap-validation.nix
  stlc/
  category-theory/
  interp/
  build-sim/
```

## Walkthrough groups

- [Proofs](/nix-effects/proof-examples) - Kernel-checked proof walkthroughs: computation, equality reasoning, and verified extraction.
- [Effects and Validation](/nix-effects/effect-examples) - Effect-handler walkthroughs that show one computation running under multiple validation policies.
- [Surface Languages](/nix-effects/surface-examples) - Small source-language walkthroughs built over HOAS, refinements, diagnostics, and generated data.
- [Applications](/nix-effects/application-examples) - Complete example programs that double as benchmark workloads.



### Guide


The guide is the shortest path from using nix-effects to understanding
the pieces that make it useful. Start with setup and handler basics,
then follow the later chapters when you need typed validation,
description-backed datatypes, ornaments, proofs, or syntax helpers.


### Internals


Internals explains how nix-effects is put together. These pages cover
the trampoline, the relationship between the effect layer and the
type-checking kernel, the trusted computing boundary, and the formal
contract maintained by the kernel.


### Proofs


Proof examples show how HOAS terms become kernel-checked evidence and
usable Nix values. Start with computational equality, then move to
reusable equality combinators and verified function extraction.

The source for this section lives under [examples/](https://github.com/kleisli-io/nix-effects/tree/main/examples).

## Walkthroughs

- [Proof Basics](/nix-effects/proof-examples/proofBasics): Computational proof examples checked by the HOAS kernel and exposed as ordinary Nix values.
- [Equality Proofs](/nix-effects/proof-examples/equalityProofs): Derive reusable equality combinators from the J eliminator and check them through the kernel.
- [Verified Functions](/nix-effects/proof-examples/verifiedFunctions): Kernel-checked HOAS programs extracted into plain Nix functions.



### Surface Languages


Surface-language examples build a simply typed lambda calculus in
layers. The core syntax introduces functions and application; later
pages add products, sums, recursive lists, refinements, and diagnostics.

The source for this section lives under [examples/](https://github.com/kleisli-io/nix-effects/tree/main/examples).

## Walkthroughs

- [Surface STLC](/nix-effects/surface-examples/stlc): Surface-language walkthroughs for a simply typed lambda calculus.