# MixOS — the whole manual

<!-- generated by docs/_build/gen-site.mix; do not edit -->

> MixOS is an agent-operable computing system: a Linux userland where every app is a service, every service speaks one message bus, and Mix is the shell. It is tried as a small signed systemd-nspawn image that runs on its own virtual terminal beside the user's existing desktop, at native GPU, input and audio speed.

Generated from the Markdown pages of https://mixos.dev/ in sidebar order. It describes the current `main` branch. Index: https://mixos.dev/llms.txt

---

<!-- page: https://mixos.dev/docs/ (source: https://mixos.dev/docs/README.md) -->

# Docs

Everything on mixos.dev that is not one component's documentation lives
here. A component's page is at `/<component>/`, for example
[`/mix/`](../mix/README.md) for the Mix language or
[`/term/`](../term/README.md) for the terminal. Every page is also published
as Markdown at its source path, and [`/llms.txt`](https://mixos.dev/llms.txt)
lists them all. The [site URL layout](decisions/2026-10-16-site-url-layout.md)
decision fixes these addresses.

## Guides

- [Try it beside your desktop](try.md): run MixOS as a small signed image on
  its own virtual terminal, next to the desktop you already use.
- [Driving apps over the Bus](drive.md): how an agent drives a native MixOS
  app through Bus verbs.

## Indexes

- [Components](components.md): every component, with its kind, install
  profiles, source and page.
- [Desktop](desktop.md) and [Server](server.md): the components each install
  profile includes.

## Decisions

Public decision records are the authority for the MixOS tree. The
foundational ones:

- [Source layout and naming](decisions/2026-10-04-source-layout.md)
- [egui applications, engine first](decisions/2026-10-09-egui-applications.md)
- [Commands take parameters and return results](decisions/2026-10-20-commands-take-parameters.md)
- [One repository, install profiles](decisions/2026-10-12-one-repository-install-profiles.md)
- [One system binary](decisions/2026-10-12-one-system-binary.md)
- [Site URL layout](decisions/2026-10-16-site-url-layout.md)

Every decision record is listed in [`/llms.txt`](https://mixos.dev/llms.txt)
and in the [repository](https://github.com/markc/mixos/tree/main/docs/docs/decisions).

## Specifications

- [Bus verb registry](https://github.com/markc/mixos/blob/main/docs/docs/spec/bus/verbs.conf.mix)
- [Bridge](spec/bridge/README.md)
- [Portal](spec/portal/README.md)
- [Releases](spec/releases/README.md)
- [Settings](spec/settings/README.md)
- [Mix programs and documents](spec/mix/2026-10-08-programs-and-documents.md)
- [Handler closure capture](spec/handler-closure-capture.md)

---

<!-- page: https://mixos.dev/mix/ (source: https://mixos.dev/mix/README.md) -->

# Mix — manual

The reference manual for the **Mix** language, one page per topic. The canonical
home of these pages is
[`docs/mix/`](https://github.com/markc/mixos/tree/main/docs/mix) in the public
[markc/mixos](https://github.com/markc/mixos) monorepo; add a page by dropping
`TOPIC.md` there. The same files render everywhere:

- **Terminal** — `mix man TOPIC` (`mix man` alone prints this index). Every
  page is built into the `mix` binary, so it needs no checkout and no network;
  the lookup order and its overrides are in [the mix command](cli.md).
- **Web** — [mixos.dev/mix](https://mixos.dev/mix/overview) serves this
  directory.
- **GitHub** — browse [`docs/mix/`](https://github.com/markc/mixos/tree/main/docs/mix)
  directly; this file doubles as the directory README.
- **Local clone** — plain markdown with relative links; any editor or viewer
  works.

**New to Mix, or coming from bash/Python/JS? Read [gotchas](gotchas.md) first** —
it is the errata against every other language's reflexes, and every row of its
table is executed by `cargo test -p system --test man_gotchas`, so it cannot
rot. `mix man syntax` is the mental model; gotchas is the corrections.

## Start here

- **[overview](overview.md)** — what Mix is, why it exists, where it came from.
- **[invocation & CLI](invocation.md)** — `mix file`, `-c`, `-`, `-i`, login shell, `--serve`, flags.
- **[the mix command](cli.md)** — `mix help`/`man`/`builtins`/`what`/`status`/`trace`/… meta-commands.
- **[syntax & the classifier](syntax.md)** — tokens, the newline rule, shell-vs-Mix dispatch.
- **[gotchas](gotchas.md)** — the guesses from bash/Python/JS that are silently wrong here. Read it first.

## The language

- **[variables, sigils & scope](variables.md)** — `$` sigils, `${...}`, function-local binding.
- **[strings](strings.md)** — `'raw'` vs `"interp"`, `..` concat, codepoint/byte/grapheme ops.
- **[numbers](numbers.md)** — f64, radix literals, ordering, coercion.
- **[operators](operators.md)** — arithmetic, comparison, `and`/`or`/`not`, `..`, `?:`, `??`.
- **[control flow](control-flow.md)** — `if`/`while`/`for`/`loop`, if-as-expression, `break`/`continue`.
- **[functions, lambdas & modules](functions.md)** — `fn`, closures, the pass-in/return/reassign triad.
- **[modules — require/include/source](modules.md)** — `require()` isolated module loading vs the splice loaders.
- **[lists & maps](collections.md)** — literals, indexing, `push`/`pop`, the base footguns.
- **[higher-order functions](hof.md)** — `map`/`filter`/`reduce`/`sort_by`/`group_by`/…
- **[errors & exit handling](errors.md)** — `try`/`catch`/`die`/`panic`, `run_rc().rc`, timeouts.

## Builtins & I/O

- **[math](math.md)** — rounding, powers, logs, trig, `min`/`max`/`clamp`, constants.
- **[files & I/O](io.md)** — `read_file`/`write_file`/`glob`/`stat`/`chmod`/`walk`/…
- **[processes & system](system.md)** — `run`/`run_rc`/`run_stream`/`spawn`/`env`/`exit`/…
- **[job control](job-control.md)** — foreground/background jobs, suspension, resume (interactive).
- **[data & serialization](data.md)** — JSON, TOML, `jq`, `data_encode`, strict-data `.mix`.
- **[byte buffers](buffer.md)** — `buffer`/`buffer_push`/`freeze`, the one reference-semantic type.
- **[regular expressions](regex.md)** — `re_match`/`re_find`/`re_replace`/`re_split`/`grep_lines` (subject first).
- **[dates & time](datetime.md)** — `time`/`date_format`/`now_iso`/`duration_format`.
- **[http](http.md)** — `http_get`/`http_post`/`http_request`, deadlines.
- **[datastar](datastar.md)** — `ds_*` SSE event framing.
- **[archives](tar.md)** — `tar_list`/`tar_unpack`/`tar_pack`, zstd/gzip/none, safe staged extraction.
- **[SQLite](sqlopen.md)** — `sqlopen`/`sqlexec`/`sqlclose`, read-only by default, `"rwc"` creates.

## Mesh & runtime

- **[Bus messaging](bus.md)** — `send`/`emit`/`address`/`on`, `$result`/`$rc` bands, the mesh.
- **[serving as a citizen](serve.md)** — `mix --serve service.mix`, the supervised runtime.
- **[remote execution (ssh)](remote.md)** — `ssh_run`/`ssh_must`/`ssh_mix`, env transports.
- **[capabilities & embedding](capabilities.md)** — the capability classes + sandbox model.
- **[expression evaluation mode](expr-eval.md)** — `eval_expr_string()`, the single-expression rule, the static deny walk.

## Reference

- **[builtin index](builtins.md)** — every builtin by category.
- **[lint diagnostics](lint.md)** — every MIX-XXXX code and its story.
- **[reserved words](keywords.md)** — the keyword set, keywords-as-names.
- **[shell-dispatch mode](shell-mode.md)** — pipes, `&&`, brace expansion, `$(...)`, redirects.
- **[owned interactive editor](owned-editor.md)** — `MIX_EDITOR=owned` (preview).
- **[usage statistics](stats.md)** — runtime modes, report windows, persistence, kill switch, static coverage.

## Where Mix lives

Mix is the MixOS shell and scripting language. The interpreter lives in the
`mix` library at `libs/mix`; `cli/mix-shell` owns the interactive shell and
native ABP citizen runtime, and `cli/system` builds the `mix` binary.
The source versions are declared in
[`libs/mix/Cargo.toml`](https://github.com/markc/mixos/blob/main/libs/mix/Cargo.toml)
and [`cli/mix-shell/Cargo.toml`](https://github.com/markc/mixos/blob/main/cli/mix-shell/Cargo.toml).
Use `mix --version` to identify the installed binary, which can differ from
the current source.

Use `mix builtins --names` to discover valid builtin names, and `mix builtins
<name>` for their contracts. `mix man overview` and `mix man syntax` explain the
language and command classifier. Discovery should inspect process status rather
than stop a sequence when a lookup is invalid.

Mix scripts use `run_argv` for local processes and native Bus verbs for application
control. `run_argv_must` is appropriate when a non-zero exit must stop the script.
The public language regression corpus accompanies the interpreter transplant.

## Programs and documents

The accepted target for the next major Mix refactor and deployment is two file
families:

| Extension | Meaning |
| --- | --- |
| `.mix` | Executable Mix program: macro, behaviour, service, module, installer or test |
| `.mx` | Declarative Mix document: configuration, scene, theme, catalogue, manifest or data specification |

All program roles use the same language. Documents use strict parsing and an
owning schema where applicable. Only declared binding fields may evaluate the
existing restricted, side-effect-free expression subset. Data strings otherwise
remain literal. A schema is a contract/validator, not necessarily another file.

This is an **accepted target, not a completed runtime migration**. Current
consumers still use `*.conf.mix`, `*.spec.mix`, `*.data.mix`, `scene.mix` and other
legacy data names. Keep their working paths until upgraded readers are deployed.
Do not rename executable helper modules such as a scene library's `data.mix`.

The refactor must refuse `.mx` through executable file loaders and retain strict
document errors without code/shell fallback. Scenes keep their current envelope
and pure bindings initially. Readers upgrade before files and writers; rollback
includes compatible binaries, scripts and documents.

New purposes use existing programs or versioned document schemas. Another file
family or evaluation mode requires an architectural decision. See the
[decision](https://mixos.dev/docs/decisions/2026-10-08-mix-programs-and-documents/) and
[file-family contract](https://mixos.dev/docs/spec/mix/2026-10-08-programs-and-documents/).

## Exit status

Uncaught script errors print a diagnostic and exit 1, including messages with
`interrupted:false` or the word `interrupted`. Signal outcomes come from actual
SIGINT/SIGTERM delivery: non-interactive scripts and `-c` exit 130/143. SIGINT
on an interactive terminal retains exit 0 unless `--result-fd` is used.
A caught interrupt still takes precedence over the evaluation's result;
`--result-fd` emits an error frame rather than a successful value.
Script-defined error codes do not impersonate OS signals; `--serve` retains
its graceful shutdown behaviour.

## Design docs & specs

Public contracts and accepted decisions live under
[`docs/docs/spec`](https://github.com/markc/mixos/tree/main/docs/docs/spec) and
[`docs/docs/decisions`](https://github.com/markc/mixos/tree/main/docs/docs/decisions).
Private deployment records are not part of the public manual. Accepted
decisions can describe staged work; check the current implementation and
installed binary when a feature's availability matters.

## The library

The `mix` component is the language library
([`libs/mix`](https://github.com/markc/mixos/tree/main/libs/mix)): lexer,
parser, evaluator, builtin contracts and embedded handler interfaces.
Features select the optional data, networking and cryptographic
facilities; the interpreter's core stays independent of the Bus and
desktop. It was transplanted from `mix` at mixos
`e0297242305f3a3c3de09f1ca01e8faa771768da`, retaining its regression corpus
and public language version. The shell is [mix-shell](https://mixos.dev/mix-shell/),
and the `mix` binary is built by [system](https://mixos.dev/system/).

## Changes

- **[changelog](changelog.md)**: the Mix library's change history, generated from
  `libs/mix/CHANGELOG.md`.

## See also

```
mix help              the full categorized builtin reference
mix builtins [CAT]    list builtins, optionally by category
mix what NAME         one-line description of a builtin or keyword
mix man TOPIC         read any of the pages above in the terminal
```

For AI agents: [`AGENTS.md`](https://github.com/markc/mixos/blob/main/AGENTS.md) at
the repo root is a short orientation sheet whose canonical reference is this
manual.

---

<!-- page: https://mixos.dev/docs/try/ (source: https://mixos.dev/docs/try.md) -->

# Try it beside your desktop

Keep the Linux desktop you already use. MixOS runs next to it on another
virtual terminal (VT): your desktop stays on VT1, MixOS takes another VT, and
you flip between them with **Ctrl+Alt+F1** and **Ctrl+Alt+F5**. Both keep
running.

This is how MixOS is meant to be tried, and it shapes the whole design.

> **Status:** the mechanism runs daily on the developers' machines. The
> download and the one-command installer are being built. This page
> describes what they will do.

## Why not a virtual machine?

VirtualBox, virt-manager, Incus and Proxmox show a guest desktop in a window,
through a virtual GPU and emulated or remote-display input. You can feel that,
and a desktop is exactly the kind of software where you notice. Getting native
graphics out of a VM means passing through a second GPU, which most people
can't do.

On its own VT, MixOS drives the **real GPU, keyboard, mouse and speakers**.
There is no hypervisor, virtual GPU, remote-display protocol or second kernel
in the way. What you try is what you would get.

## How it works

Three things already in the Linux kernel and systemd do the work:

1. **Virtual terminals.** Each VT is a separate console. When you switch, the
   kernel asks the current owner to let go before handing over.
2. **GPU and input handover.** Only one program can drive the display at a
   time. Your desktop's compositor is managed by `systemd-logind` on VT1;
   MixOS's compositor is managed by `seatd` on its own VT. Each lets go of the
   display and input devices when its VT goes to the background, and takes
   them back when it returns.
3. **Separate sessions.** MixOS keeps its own runtime directory and its own
   session bus, so nothing it runs collides with your desktop's.

The container is what makes it a download: `systemd-nspawn` runs MixOS as a
self-contained machine, `importctl` fetches and verifies the signed image, and
`machinectl` starts, stops and removes it.

## What you need

- A mainstream Linux distribution running systemd: Ubuntu, Fedora, Debian,
  Arch, openSUSE or Mint, among others.
- `systemd-nspawn`. Debian-family systems need the `systemd-container`
  package; most others already have it.
- Intel or AMD graphics. NVIDIA's proprietary driver needs extra work and
  comes later.
- `sudo`, for the one install command.

## What the installer will do

1. Check your system: systemd and kernel versions, GPU vendor, and a free VT.
2. Fetch the signed MixOS image and verify its signature.
3. Describe the machine in one small configuration file: which GPU, which VT,
   your audio, and a separate home directory with chosen folders shared.
4. Reserve the VT so no login prompt starts there.
5. Start MixOS and switch to its VT. If MixOS doesn't come up in time, it
   switches you back to VT1 automatically.

Removal undoes every step and leaves your system exactly as it was.

## Things to know first

- **It is not a sandbox.** MixOS gets your real input devices and GPU, so
  trust it as you would any package you install as root.
- **Your desktop keeps running** in the background, and so does everything in
  it. While MixOS is in front, the installer stops your desktop from deciding
  you have gone idle and suspending the machine.
- **Apps can't be in both places at once.** Firefox and Thunderbird already
  open on one desktop refuse to open the same profile on the other. That is
  their profile lock protecting your data, not a fault.
- **If a screen ever goes black,** SSH in from another machine, or use
  Alt+SysRq+R followed by Ctrl+Alt+F1 where your kernel allows it.

## For agents

Every page on this site is static HTML, and also published as Markdown: this
page is [`/try.md`](/docs/try.md). [`/llms.txt`](/llms.txt) indexes the whole
manual and [`/llms-full.txt`](/llms-full.txt) is all of it in one file.

---

<!-- page: https://mixos.dev/docs/drive/ (source: https://mixos.dev/docs/drive.md) -->

# Driving apps over the Bus

MixOS is agentic first: anything a person can do in a native app, an agent
can do over the Bus. Every egui app built on the shared toolkit offers two
sets of verbs:

- **Its own verbs**, which read and change its state directly, such as
  BusViewer's `busviewer.filter` or `busviewer.call`. These are the
  fastest and most precise way to work with an app.
- **The drive verbs**, which are the same in every app and work the window
  the way a hand does: read the widget tree, click, type, press keys,
  scroll, open menus, move the window and take a screenshot.

The drive verbs are named under the app's own prefix: `<app>.ui.tree`,
`<app>.ui.click`, `<app>.window` and so on. `HELP` and `app.describe` list
all of an app's verbs with their arguments, both sets included.

## Replies and refusals

A verb answers with return code 0 and a JSON body, or with return code 10
and a body naming the reason:

```json
{"error_code": "ARGUMENT", "message": "give exactly one of label and id"}
```

| `error_code` | Meaning |
|---|---|
| `ARGUMENT` | The arguments are wrong, or name something that is not there. |
| `UNKNOWN_VERB` | The app has no such verb. |
| `BUSY` | Not now: work is in flight, a dialog is open, the window is hidden, no frame has been drawn yet, or the app is closing. |
| `CANCELLED` | Input that was accepted but never delivered: the window was hidden or minimised first, or the app closed. |
| `CAPTURE` | A screenshot could not be taken or written. |
| `UNAVAILABLE` | The app does not offer the drive verbs. |

An app's own verbs may add codes of their own; BusViewer's are listed
[below](#busviewer-the-worked-example).

## The drive verbs

Coordinates and sizes are in points, egui's logical pixels: the same space
for every verb, at any display scale.

### `<app>.ui.tree`

The widget tree, from egui's AccessKit output for the last frame, depth
first from the root.

- **Arguments:** `label` (optional, a case-insensitive substring of the
  label), `exact` (optional; `true` makes `label` match the whole label,
  case and all, so "Close" does not also list "Close All") and `role`
  (optional, an AccessKit role name such as `Button`, `TextInput` or
  `MultilineTextInput`). Only matching nodes are listed.
- **Answer:** `{root, focus, nodes}`. Each node carries:
  - `id`: the node id, as **decimal text**;
  - `role`, `label`, `value` and `placeholder`;
  - `rect`: `[x0, y0, x1, y1]`;
  - `enabled`, `focused` and `selected`;
  - `checked`: `"true"`, `"false"`, `"mixed"` or null;
  - `children`: the child ids;
  - `depth`.
- **Refused** with `BUSY` until the first frame has been drawn.

Node ids are 64-bit numbers, and most JSON readers keep only 53 bits of a
number. Every id in a drive answer is therefore text, and should be passed
back as text. For a plain text label, egui puts the text in the node's
value; the drive verbs report it as the `label` too.

### `<app>.ui.click`

**Each step is one frame.** Input verbs run one pass per step and answer
a pass after their last, so their time is the window's frame interval. A
session on a background VT, or a window without focus, may be drawn only
once a second: there a `ui.click` (move, click, redraw) takes about two to
three seconds, and a `ui.type` a pass per line and per newline. Expect
that wait; it is not a hang.

Moves the pointer to a node's centre in one pass, then presses and
releases there in the next, as a quick hand does within one frame. Passes
can be far apart (a compositor may draw an unfocused window only once a
second), and egui takes a release more than 0.8 s after its press as a
long press, not a click, so the two never wait for separate passes. A
separate `ui.pointer` press and release are two passes, and may be a long
press for that reason.

- **Arguments:**
  - exactly one of `label` (exact text) or `id` (decimal text, or an exact
    integer);
  - `button`: `primary` (the default), `secondary` or `middle`;
  - `double`: true for a double-click.
- A `label` matches nodes whose label is exactly that text. If none has
  it, nodes whose placeholder (hint text) is that text match instead.
- A control (a button, link, checkbox, field, slider, menu item and so on)
  wins over text that repeats its name, such as its own tooltip or a
  label beside it.
- When several nodes still match, the click is refused with `ARGUMENT`,
  listing their ids; click one of them by id.
- **Answer:** `{target, at, menu, focused, pointer}`. `target` is the node
  that was clicked and `at` the point. The rest is the state the click
  left: the open menu (as `ui.menu` reports it), the focused node and the
  pointer position.
- **Tracing:** every input verb (`ui.click`, `ui.pointer`, `ui.scroll`,
  `ui.key`, `ui.type`) takes `trace: true`, and its answer then carries
  `passes`: one entry per pass the job ran, with every input event egui
  read in it (the platform's own and the injected ones, in order), egui's
  input `time` for the pass in seconds, and what
  egui made of them: `clicked`, `drag_started`, `dragged`, `drag_stopped`,
  `hovered` and `contains_pointer` (widget ids, the same decimal text as
  node ids), the `pointer` position, whether a button is `down`, and
  `no_longer_a_click` (the pointer has moved too far since the press for
  its release to click). Use it when a click answers but does nothing.

### `<app>.ui.pointer`

One pointer event at a point.

- **Arguments:** `x`, `y`, `action` (`move`, `press` or `release`) and
  `button` (optional, as for `ui.click`).
- **Answer:** `{menu, focused, pointer}`.

Press and release are separate requests, so an agent can drag, or open a
menu on press the way a person does.

### `<app>.ui.scroll`

Moves the pointer to `x`, `y` and scrolls there by `dx`, `dy` points, with
egui's signs: a positive `dy` moves the content down, revealing what is
above. egui animates a scroll over a few frames, so the answer may arrive
before the content has finished moving.

### `<app>.ui.key`

Presses and releases one key.

- **Arguments:** `key`, an egui key name (`Enter`, `Escape`, `Tab`,
  `ArrowDown`, `F1`, `A`, …), and `modifiers` (optional), a list of
  `ctrl`, `shift`, `alt` or `command`. Off macOS, `command` is Ctrl.
- **Answer:** `{menu, focused, pointer}`.

A key with modifiers triggers the app's shortcuts exactly as the keyboard
does.

### `<app>.ui.type`

Types `text` into the focused widget. A newline in the text presses Enter.
Focus a field first, for example with a `ui.click` on it.

### `<app>.ui.menu`

The open menu: `{menu: {menu, path, depth}}`, or `{menu: null}` when no menu
is open.

- `menu`: the open menu's title.
- `path`: the highlighted row's label at each open level, null where no row
  is highlighted.
- `depth`: the level the keyboard acts on.

### `<app>.ui.menu.list`

Every menu, as the menu bar draws it: `{menus: [{title, rows}]}`. A row is
`{label, id, shortcut, enabled, checked}`, with `submenu` holding the rows
of a submenu row (whose `id` is null), or `{separator: true}`.

### `<app>.ui.menu.open`

Opens a menu, and submenus within it, by label.

- **Arguments:** `path`, a list: a menu title, then the label of a row at
  each level below it. Every row but the last must open a submenu. Or
  `menu`, a title alone. Case and a trailing "…" don't matter.
- **Answer:** the open menu, as `ui.menu` reports it. The last row named is
  highlighted, and the keyboard acts on the deepest open level, so a
  `ui.key` Enter then runs that row.
- **Refused** (`ARGUMENT`): no path, a title or label the menus don't
  have, a disabled row, or a row before the last that opens no submenu.

### `<app>.ui.menu.close`

Closes every open menu. Answers `{closed}`: whether one was open.

### `<app>.ui.capture`

A screenshot of the window, written to a new PNG file.

- **Arguments:** `name`, optional (see the rules below).
- **Answer:** `{path, width, height}`, with the size in physical pixels.

Captures are confined to the app's own directory:

- Every capture goes to `$XDG_RUNTIME_DIR/<app>/captures/`. The app creates
  that directory, mode 0700. Each of its two levels must be a real
  directory; a symbolic link there refuses the capture.
- A caller gives at most a file name, never a path. The name must:
  - end in `.png` and be at most 128 bytes;
  - contain no `/`, `\`, NUL or `..`;
  - not start with a dot.
- Without a name, the app picks a fresh `capture-<pid>-<n>.png`.
- A name that already exists, as a file or as a link, is refused with
  `ARGUMENT`. The file is created exclusively, mode 0600, so a link planted
  while the capture waits fails the capture (`CAPTURE`) instead of being
  followed.
- Without `XDG_RUNTIME_DIR` there is nowhere to capture to, and every
  capture is refused.
- The screenshot is waited for for 10 seconds at most, then the capture is
  refused with `CAPTURE`.

### `<app>.window`

A window command, sent the way the title bar's caption buttons send it.

- **Arguments:** `action`: `minimize`, `maximize`, `restore`, `close` or
  `focus`.
- **Answer:** the window state (as `window.state` reports it) plus
  `requested`, the action.
- `maximize`, `restore` and `focus` answer two frames later, with the state
  the window then reports.
- A minimised window draws no frames, so `minimize` first settles any input
  still queued (see [Ordering](#ordering)), then answers at once.
- `close` answers at once. The app then closes as if its close button had
  been pressed, finishing work it has accepted first.

### `<app>.window.state`

`{size, outer_size, maximized, minimized, fullscreen, focused,
pixels_per_point}`, where `size` and `outer_size` are `[width, height]`.

## Ordering

The drive verbs are built so that a caller can step an app
deterministically.

- **Input runs one request at a time, in order.** Each step of a click,
  key or text is its own frame: for a click, the move, the press and the
  release. The answer comes one frame after the last step, so it reports
  what the input changed.
- **Later requests wait for earlier input.** The app holds each Bus command
  in arrival order. Further input (`ui.click`, `ui.pointer`, `ui.scroll`,
  `ui.key`, `ui.type`, `ui.capture`) joins the input queue directly. Every
  other verb waits until the input before it has been answered: reads such
  as `ui.tree`, `window` commands, and the app's own verbs. So `ui.type`
  into a field followed by an app verb that reads that field sees the
  typed text.
- **A hidden window draws no frames.** While the window is minimised or
  covered, new input is refused with `BUSY`. Input already accepted is
  settled:
  - a request that only had its redraw frame left is answered normally;
  - anything with input still to send is answered `CANCELLED`.

  A click cancelled after its press, but before its release, has its
  button released safely when the window returns. The pointer first moves
  away, so the release can never complete the click.
- **Closing answers everything.** Before an app closes its Bus connection,
  every request it has accepted gets an answer:
  - input in progress: return code 0, with `closing: true`, and
    `interrupted: true` when part of it was never sent;
  - queued input and captures: `CANCELLED`;
  - every other request, including any still arriving: `BUSY`.

## BusViewer: the worked example

Native `<app>.commands` responses report `shortcut` and `more` using stored
keymap chords, with modifiers in Ctrl, Alt, Shift order. Key names follow the
keymaps grammar (`ArrowLeft` or `Left`, `=`, `-`, `/`), so reported chords can
be used in keymap overrides without translating display labels.

Command execution returns `DENIED` for an authorisation refusal and
`DISABLED` when the command cannot run in the current state. Authorisation
is checked first.

BusViewer browses the services and verbs on a node and calls one verb with
a JSON body. Everything in its window is also a Bus verb.

### Reading

| Verb | Arguments | Answer |
|---|---|---|
| `busviewer.ping` | | `{schema, version}` |
| `busviewer.info` | | the whole state: connection, discovery snapshot, selection, body, last reply, status, and the arranged UI (`ui`) |
| `busviewer.tree` | | `{rows}`: the rows the tree shows, depth first, each with `key`, `kind`, `label`, `depth`, `expanded`, `selected` and its child count; verb rows add `selection`, error rows `error` |
| `busviewer.reply` | | `{text, value}`: the reply panel and the last reply |
| `busviewer.commands` | | every menu command with its label, shortcut, further chords (`more`, when it has any) and whether it is enabled now. The shortcuts are those in force: the desktop profile can rebind them (`settings.apply` `keymaps.busviewer.<id>`) |
| `HELP`, `app.describe` | | every verb, with arguments |

A row's `kind` is `service`, `verb`, `error`, `peers`, `peer` or
`no_peers`. Its `key` names it in the verbs below, for example
`service:noded` or `verb:noded:noded.list`.

### Changing state

| Verb | Arguments | Notes |
|---|---|---|
| `busviewer.filter` | `text` | Filters the tree, as typing in the search field does. Answers with the rows. |
| `busviewer.expand` | `key`, `open` (bool) | Opens or closes a row that has children. |
| `busviewer.select_row` | `key` | Selects any row. A verb row also selects its verb. |
| `busviewer.select` | `service`, `verb` | Selects an advertised verb. |
| `busviewer.body` | `text` | Sets the JSON body (at most 65,536 bytes). Refused while a call is using the body. |
| `busviewer.split` | `value`, 0 to 1 | The services pane's share of the window, kept between 0.2 and 0.65. The answer reports the value in effect, to 4 places. |
| `busviewer.dialog` | `open`: `"about"`, `"shortcuts"` or null | Opens a dialog, or closes the open one. |
| `busviewer.call` | `service`, `verb` and `body`, each optional | Calls the selected verb once, or the given one; `service` and `verb` go together. The answer is the reply: `{service, verb, request_body, rc, body}`. A transport failure is never retried: it answers return code 10 with `transport_error` and `outcome_unknown`. |
| `busviewer.theme` | `scheme`, `style`, `mode`, `decorations` and `caption_side`, each optional: a name, or null | Chooses the window's theme, in this window only. A present key sets that axis (null follows the session's), an absent one leaves it, and an unknown name is refused with `ARGUMENT`; nothing changes unless every axis is valid. Schemes: `ocean`, `crimson`, `stone`, `forest`, `sunset`, `mono`, `pro`, `studio`, `classic`; styles: `plain`, `pro`, `studio`, `classic`, or `own` for the scheme's own; modes: `light`, `dark`; decorations: `csd` (the app's title bar), `ssd` (the compositor's, with the menus in a menu-bar row); caption sides: `right`, `left`. The answer is `{scheme, style, mode, decorations, caption_side, effective: {…}}`: the choice, then what the window shows. Taken while a dialog is open. |
| `busviewer.execute` | `id` | Runs one command, from the menus or the title bar: `file.refresh`, `file.quit`, `edit.format`, `edit.clear`, `edit.copy`, `bus.call`, `help.shortcuts`, `help.about`, `view.search`, `view.mode` (the light/dark switch), and View › Theme's choices `view.theme.<scheme>`, `view.theme.session`, `view.mode.light`, `view.mode.dark`, `view.mode.session`, `view.style.own`, `view.style.<style>`, `view.style.session`, `view.decorations.csd`, `view.decorations.ssd`, `view.captions.left`, `view.captions.right`. `busviewer.commands` lists them all, with each choice's `checked` tick. |
| `busviewer.refresh` | | Discovers services again. |
| `busviewer.show` | | Restores and focuses the window. |
| `busviewer.quit` | | Closes once idle. |

While a dialog is open, the window takes no edits, so neither does the
Bus: those verbs are refused with `BUSY` until the dialog is closed.
BusViewer's own refusals are:

- `BUSY`: a refresh or call is in flight, or a dialog is open;
- `DISCONNECTED`: the node's broker is unreachable;
- `ARGUMENT` and `UNKNOWN_VERB`, as above;
- `UNKNOWN_COMMAND` and `DISABLED`, from `busviewer.execute`.

### Driving it from Mix

This script opens the Help menu, closes it again, filters the tree, and
captures the window:

```mix
-- Open BusViewer's Help menu, close it, filter the tree and capture the window.
$app = "busviewer"

fn drive($verb, $args)
  $payload = json_encode($args)
  send $app $verb body=$payload timeout=30
  if $rc != 0 then
    raise("DRIVE", $verb .. " rc=" .. to_string($rc) .. ": " .. to_string($result))
  end
  return if type($result) == "string" then json_parse($result) else $result end
end

$opened = drive("busviewer.ui.click", {label: "Help"})
print "open menu: " .. json_encode($opened.menu)
drive("busviewer.ui.key", {key: "Escape"})
$rows = drive("busviewer.filter", {text: "settings"}).rows
print to_string(len($rows)) .. " rows match"
$shot = drive("busviewer.ui.capture", {name: "settings.png"})
print "capture: " .. $shot.path
```

Each `send` waits for its answer before the next one is sent. A longer
scenario follows the same pattern: send a verb, check its return code,
print the fields that matter, and stop at the first surprise. That is how
the project's own driver checks a running BusViewer from end to end.

## For app authors

The drive verbs come from the toolkit's `drive` module, an egui plugin. It
switches AccessKit on, keeps each frame's widget tree, and injects input
through egui's input hook: the same path a person's input takes. An app
wires it up in five places:

1. `drive::install(ctx, "<app>")` once, when the window opens.
2. For each `<app>.ui.*` or `<app>.window*` command, call
   `drive::request(ctx, id, verb, args)` from inside a frame, with the
   prefix stripped. It returns either an answer to send now, or nothing,
   meaning the answer will come later.
3. `drive::logic(ctx)` once per frame, from the app's logic. It runs while
   the window is hidden too, and returns the answers to send.
4. `drive::pending(ctx)` and `drive::queues(verb)`, to hold later commands
   back while earlier input is still running.
5. `drive::finish(ctx)` before closing, sending every answer it returns
   before the Bus connection stops.

`drive::describe("<app>")` lists the verbs for `HELP` and `app.describe`.
BusViewer's shell (`apps/busviewer/src/shell.rs`) is the reference wiring.

---

<!-- page: https://mixos.dev/docs/components/ (source: https://mixos.dev/docs/components.md) -->

# Components

Every MixOS component, generated from the component metadata: each principal
package's `[package.metadata.mixos]`, or a Mix component's `component.mx`, read by
`tools/component_index.mix`. Install profiles come only from a declared `profiles`
list; a shipping component that has not declared one yet is unclassified. By
profile: [desktop](desktop.md) and [server](server.md). This page describes the current `main` branch of MixOS.

| Component | Kind | Profiles | Source | Description |
|---|---|---|---|---|
| [assets](../assets/README.md) | lib | none (library) | [`libs/assets`](https://github.com/markc/mixos/tree/main/libs/assets) | The resolver for a pinned, immutable set of fonts, icons and emoji on the local disk, which finds, verifies and reads a published set without any downloader or daemon. |
| [backdrop](../backdrop/README.md) | app | unclassified | [`apps/backdrop`](https://github.com/markc/mixos/tree/main/apps/backdrop) | The MixOS desktop background — drawn by its own program on the compositor's background layer, on every output, at native and fractional scale. |
| [blobd](../blobd/README.md) | service | unclassified | [`services/blobd`](https://github.com/markc/mixos/tree/main/services/blobd) | The node blob store: content-addressed bytes kept in mds, with owner pins, quotas and garbage collection. The MixOS port of blobd, with the store, the Bus citizen, the byte lane and the cross-node… |
| [bridged](../bridged/README.md) · [changelog](../bridged/changelog.md) | service | unclassified | [`services/bridged`](https://github.com/markc/mixos/tree/main/services/bridged) | How bridged puts an external application with a line-delimited JSON control channel on the Bus, one instance per application, and what that exposes. |
| [buildinfo](../buildinfo/README.md) | lib | none (library) | [`libs/buildinfo`](https://github.com/markc/mixos/tree/main/libs/buildinfo) | Compile-time build provenance for MixOS binaries, and the --version contract every binary answers. |
| [bus](../bus/README.md) | lib | none (library) | [`libs/bus`](https://github.com/markc/mixos/tree/main/libs/bus) | The Bus wire format and the broker client library, with a supervised connection to noded that survives broker restarts. |
| [busviewer](../busviewer/README.md) | app | unclassified | [`apps/busviewer`](https://github.com/markc/mixos/tree/main/apps/busviewer) | BusViewer is the MixOS desktop app that lists the services and verbs on this node's Bus, shows each verb's description and the mesh peers, and calls one verb once with a JSON body. |
| [ced](../ced/README.md) | app | unclassified | [`apps/ced`](https://github.com/markc/mixos/tree/main/apps/ced) | The MixOS Editor, a desktop text editor over the edit Bus service, where people and agents edit the same document at once and see each other's carets, selections and changes live. |
| [citizen](../citizen/README.md) | lib | none (library) | [`libs/citizen`](https://github.com/markc/mixos/tree/main/libs/citizen) | An app's supervised native Bus connection, shared by the MixOS apps for registration, calls, replies, single-instance launch and window restore. |
| [command](../command/README.md) · [changelog](../command/changelog.md) | lib | none (library) | [`libs/command`](https://github.com/markc/mixos/tree/main/libs/command) | UI-free command registry, typed dispatch and executed journal. |
| [compd](../compd/README.md) · [changelog](../compd/changelog.md) | service | unclassified | [`services/compd`](https://github.com/markc/mixos/tree/main/services/compd) | The MixOS Wayland compositor, which owns scanout, rendering, input and capture, and serves the comp Bus service with its workspaces, verbs, topics and props tree. |
| [config](../config/README.md) | lib | none (library) | [`libs/config`](https://github.com/markc/mixos/tree/main/libs/config) | Where MixOS keeps its files and how a conf.mix file is read, with one directory rule for every component and descriptor-safe atomic file helpers. |
| [daemon](../daemon/README.md) | lib | none (library) | [`libs/daemon`](https://github.com/markc/mixos/tree/main/libs/daemon) | Shared HTTP host parsing, listener guards, TLS and ACME provisioning. |
| [davproto](../davproto/README.md) | lib | none (library) | [`libs/davproto`](https://github.com/markc/mixos/tree/main/libs/davproto) | CalDAV and CardDAV codecs that convert between JSCalendar or JSContact and iCalendar or vCard, with strong ETags, and no transport or storage. |
| [design](../design/README.md) | lib | none (library) | [`libs/design`](https://github.com/markc/mixos/tree/main/libs/design) | The MixOS design-token system, which compiles a strict-data theme source into resolved colours, metrics, typography and button tables for one scheme, mode and contrast. |
| [dnsd](../dnsd/README.md) | service | server | [`services/dnsd`](https://github.com/markc/mixos/tree/main/services/dnsd) | authoritative mesh DNS for the zones in zones.mix |
| [dopus](../dopus/README.md) | app | unclassified | [`apps/dopus`](https://github.com/markc/mixos/tree/main/apps/dopus) | MixOS's twin-pane file manager — two folder trees side by side, Places and Properties sidebars, drag and drop between panes, menus and keys for every action, and a Bus surface for agents that reads… |
| [edit](../edit/README.md) | lib | none (library) | [`libs/edit`](https://github.com/markc/mixos/tree/main/libs/edit) | Shared headless text buffers used by editd and Ced, with revision checks, transactions, operational transforms, per-origin undo, anchors and search. |
| [editd](../editd/README.md) · [changelog](../editd/changelog.md) | service | unclassified | [`services/editd`](https://github.com/markc/mixos/tree/main/services/editd) | The edit service, which holds shared text buffers that people and agents edit together, with revision checks, per-origin undo, anchors, atomic save, external-change detection and recovery. |
| [editor](../editor/README.md) | lib | none (library) | [`libs/editor`](https://github.com/markc/mixos/tree/main/libs/editor) | The shared plain-text editor widget for MixOS egui applications, a virtualised monospace view over the headless editing model that works on a local file or a shared buffer. |
| [editor-model](../editor-model/README.md) | lib | none (library) | [`libs/editor-model`](https://github.com/markc/mixos/tree/main/libs/editor-model) | The headless text-editing model shared by MixOS editors, turning commands and motions into edits and keeping a local mirror of an edit-service buffer in step with the server, plus highlighting and… |
| [email](../email/README.md) | app | unclassified | [`apps/email`](https://github.com/markc/mixos/tree/main/apps/email) |  |
| [expr](../expr/README.md) | lib | none (library) | [`libs/expr`](https://github.com/markc/mixos/tree/main/libs/expr) | The pure expression language of Mix Scenes bindings, which compiles an expression, reports the globals it reads and evaluates it over JSON values under size and time limits. |
| [files](../files/README.md) | lib | none (library) | [`libs/files`](https://github.com/markc/mixos/tree/main/libs/files) | Rooted reads and the files-as-truth markdown corpus model. |
| [hostd](../hostd/README.md) · [changelog](../hostd/changelog.md) | service | unclassified | [`services/hostd`](https://github.com/markc/mixos/tree/main/services/hostd) | How hostd answers questions about the host and carries out privileged host changes through closed, typed verbs behind standing grants, receipts and rollback, so agents never need sudo. |
| [indexd](../indexd/README.md) | service | desktop | [`services/indexd`](https://github.com/markc/mixos/tree/main/services/indexd) | Local semantic search over the MixOS Bus, with an ssh bridge and an in-process CLI. |
| [inputd](../inputd/README.md) · [changelog](../inputd/changelog.md) | service | unclassified | [`services/inputd`](https://github.com/markc/mixos/tree/main/services/inputd) | How inputd turns keys into Bus verbs below the compositor, keeps the user keys for the person, and holds its keyboard grab only while its own VT is active. |
| [logging](../logging/README.md) | lib | none (library) | [`libs/logging`](https://github.com/markc/mixos/tree/main/libs/logging) | Shared tracing, sink selection, reload handles and process statistics for MixOS services and the Mix shell. |
| [maild](../maild/README.md) · [changelog](../maild/changelog.md) | service | server | [`services/maild`](https://github.com/markc/mixos/tree/main/services/maild) | JMAP, SMTP, IMAP and DAV mail service |
| [mds](../mds/README.md) | lib | none (library) | [`libs/mds`](https://github.com/markc/mixos/tree/main/libs/mds) | Per-container-set SQLite metadata and a content-addressable blob store, the storage library that maild links and blobd will use. A library, not a daemon. |
| [mesh-sign](../mesh-sign/README.md) · [changelog](../mesh-sign/changelog.md) | cli | unclassified | [`cli/mesh-sign`](https://github.com/markc/mixos/tree/main/cli/mesh-sign) | Signs and verifies the mesh inventory, the trust root of a MixOS mesh. |
| [mimedb](../mimedb/README.md) | lib | none (library) | [`libs/mimedb`](https://github.com/markc/mixos/tree/main/libs/mimedb) | A library that reads the freedesktop shared-mime-info database and decides a file's type from its name and content the way GLib does, so MixOS names a file's type as the desktop does. |
| [mix](../mix/README.md) · [changelog](../mix/changelog.md) | lib | none (library) | [`libs/mix`](https://github.com/markc/mixos/tree/main/libs/mix) |  |
| [mix-shell](../mix-shell/README.md) · [changelog](../mix-shell/changelog.md) | cli | unclassified | [`cli/mix-shell`](https://github.com/markc/mixos/tree/main/cli/mix-shell) | The Mix shell library, holding the interactive line editor, the command classifier, the native-session bootstrap and the Bus citizen runtime that the mix binary runs. |
| [mixos-mcp](../mixos-mcp/README.md) · [changelog](../mixos-mcp/changelog.md) | cli | base | [`cli/mixos-mcp`](https://github.com/markc/mixos/tree/main/cli/mixos-mcp) | MCP stdio access to the native MixOS Bus. |
| [mixtrayd](../mixtrayd/README.md) | service | unclassified | [`services/mixtrayd`](https://github.com/markc/mixos/tree/main/services/mixtrayd) |  |
| [monitor](../monitor/README.md) | app | desktop | [`apps/monitor`](https://github.com/markc/mixos/tree/main/apps/monitor) | Monitor is the MixOS task manager, showing the processes and performance that monitord reports for this node or any node on the mesh, with End task and Kill for this node's processes. |
| [monitord](../monitord/README.md) · [changelog](../monitord/changelog.md) | service | base | [`services/monitord`](https://github.com/markc/mixos/tree/main/services/monitord) | How monitord samples a host's CPU, memory, disks, network and processes, keeps history in memory and SQLite, and answers read verbs on the Bus, so any node's load can be read from anywhere on the… |
| [noded](../noded/README.md) · [changelog](../noded/changelog.md) | service | unclassified | [`services/noded`](https://github.com/markc/mixos/tree/main/services/noded) | The MixOS Bus broker, which handles service registration, discovery, routing, subscriptions, authenticated local session grants and mesh peering between nodes. |
| [notifyd](../notifyd/README.md) | service | unclassified | [`services/notifyd`](https://github.com/markc/mixos/tree/main/services/notifyd) | How notifyd keeps the desk's notifications, shows them as toasts and in the Notifications page, and tells an agent or app which button the human pressed. |
| [portald](../portald/README.md) | service | unclassified | [`services/portald`](https://github.com/markc/mixos/tree/main/services/portald) | How portald serves the XDG Settings and ScreenCast portals on the session bus, where the appearance values and screen frames come from, and how applications and agents use them. |
| [prefs](../prefs/README.md) | app | unclassified | [`apps/prefs`](https://github.com/markc/mixos/tree/main/apps/prefs) | MixOS's preferences window — a sidebar of editors: Applications follows, installs, updates, rolls back and removes upstream releases; Appearance sets the session's colour scheme, style, mode,… |
| [props](../props/README.md) | lib | none (library) | [`libs/props`](https://github.com/markc/mixos/tree/main/libs/props) | Property read types, revisions, namespace storage and native Bus routing for MixOS services. |
| [releasesd](../releasesd/README.md) | service | unclassified | [`services/releasesd`](https://github.com/markc/mixos/tree/main/services/releasesd) | How releasesd follows upstream application releases on GitHub and installs their Linux builds per user, verified, with rollback, from the command line or the Bus. |
| [scene](../scene/README.md) | lib | none (library) | [`libs/scene`](https://github.com/markc/mixos/tree/main/libs/scene) | The Mix Scenes document core, which parses, lints, resolves and diffs scene documents and their bindings without a renderer or interpreter. |
| [screenshot](../screenshot/README.md) | app | unclassified | [`apps/screenshot`](https://github.com/markc/mixos/tree/main/apps/screenshot) | MixOS's screenshot app — Print Screen for a region, Shift+Print for the screen, Alt+Print for a window; arrows, boxes, pens, highlighter, text, numbered markers, crop and redaction that stay… |
| [settings](../settings/README.md) · [changelog](../settings/changelog.md) | lib | none (library) | [`libs/settings`](https://github.com/markc/mixos/tree/main/libs/settings) | Headless desktop settings types, validation, resolution and the shared consumer that apps and the compositor use to follow the settings authority. |
| [settingsd](../settingsd/README.md) · [changelog](../settingsd/changelog.md) | service | unclassified | [`services/settingsd`](https://github.com/markc/mixos/tree/main/services/settingsd) | The headless desktop settings authority, the one writer for a session profile's settings, with durable receipts and retained change publication on the Bus. |
| [strict](../strict/README.md) | lib | none (library) | [`libs/strict`](https://github.com/markc/mixos/tree/main/libs/strict) | The MixOS strict-data format, the grammar of conf.mix and data.mix files, loaded as data and never executed. |
| [syntax](../syntax/README.md) | lib | none (library) | [`libs/syntax`](https://github.com/markc/mixos/tree/main/libs/syntax) | The syntax highlighting library for MixOS text editors, which runs Microsoft Edit's compiled lsh language definitions line by line over any chunked text store. |
| [system](../system/README.md) | cli | unclassified | [`cli/system`](https://github.com/markc/mixos/tree/main/cli/system) | The system package builds the mix shell executable with optional noded, monitord, maild, webd and dnsd personalities selected by the name it is started under. |
| [term](../term/README.md) · [changelog](../term/changelog.md) | app | unclassified | [`apps/term`](https://github.com/markc/mixos/tree/main/apps/term) | The MixOS terminal, with tabs, split panes and a GPU-drawn grid, driven by the session settings and fully scriptable over the Bus. |
| [test-broker](../test-broker/README.md) | lib | none (library) | [`libs/test-broker`](https://github.com/markc/mixos/tree/main/libs/test-broker) | A development fixture that runs the real noded modules in an isolated broker runtime for the Term-to-Mix native session acceptance tests. |
| [thumbs](../thumbs/README.md) | lib | none (library) | [`libs/thumbs`](https://github.com/markc/mixos/tree/main/libs/thumbs) | File thumbnails made the freedesktop way, read from and written to the shared thumbnail cache and generated by the system's installed thumbnailers in their own processes. |
| [toolkit](../toolkit/README.md) · [changelog](../toolkit/changelog.md) | lib | none (library) | [`libs/toolkit`](https://github.com/markc/mixos/tree/main/libs/toolkit) | The shared shell for MixOS egui applications, giving every app the same theme, fonts, icons, title bar, menus, chrome components, command registry, Fluent strings and Bus drive verbs. |
| [toolsd](../toolsd/README.md) | service | server | [`services/toolsd`](https://github.com/markc/mixos/tree/main/services/toolsd) | Runs the tools webd's admin panel queues (whois, dig, traceroute, shwho) as an unprivileged drain, outside webd's sandbox. |
| [webd](../webd/README.md) | service | server | [`services/webd`](https://github.com/markc/mixos/tree/main/services/webd) | Virtual hosts, CMS routes, embedded Mix handlers and ACME for the MixOS web service. |

## Packages

Every workspace package and Mix component, with the component that owns it.
Private crates stay under their owning component. Dependency closure is
checked separately by the layering gate.

| Package | Component | Kind | Layer | Contract | Version |
|---|---|---|---|---|---|
| [backdrop](https://github.com/markc/mixos/blob/main/apps/backdrop/Cargo.toml) | backdrop | app | desktop | none | 0.1.2 |
| [wallpaper](https://github.com/markc/mixos/blob/main/apps/backdrop/crates/wallpaper/Cargo.toml) | backdrop | app | core | none | 0.1.2 |
| [busviewer](https://github.com/markc/mixos/blob/main/apps/busviewer/Cargo.toml) | busviewer | app | desktop | public | 0.1.2 |
| [inspector](https://github.com/markc/mixos/blob/main/apps/busviewer/crates/inspector/Cargo.toml) | busviewer | app | core | none | 0.1.2 |
| [ced](https://github.com/markc/mixos/blob/main/apps/ced/Cargo.toml) | ced | app | desktop | public | 0.1.2 |
| [documents](https://github.com/markc/mixos/blob/main/apps/ced/crates/documents/Cargo.toml) | ced | app | core | none | 0.1.2 |
| [dopus](https://github.com/markc/mixos/blob/main/apps/dopus/Cargo.toml) | dopus | app | desktop | public | 0.1.2 |
| [dopus-core](https://github.com/markc/mixos/blob/main/apps/dopus/crates/dopus-core/Cargo.toml) | dopus | app | core | none | 0.1.2 |
| [email](https://github.com/markc/mixos/blob/main/apps/email/Cargo.toml) | email | app | desktop | public | 0.1.2 |
| [jmap](https://github.com/markc/mixos/blob/main/apps/email/crates/jmap/Cargo.toml) | email | app | core | none | 0.1.2 |
| [monitor](https://github.com/markc/mixos/blob/main/apps/monitor/Cargo.toml) | monitor | app | desktop | public | 0.1.2 |
| [vitals](https://github.com/markc/mixos/blob/main/apps/monitor/crates/vitals/Cargo.toml) | monitor | app | core | none | 0.1.2 |
| [prefs](https://github.com/markc/mixos/blob/main/apps/prefs/Cargo.toml) | prefs | app | desktop | public | 0.1.2 |
| [preferences](https://github.com/markc/mixos/blob/main/apps/prefs/crates/preferences/Cargo.toml) | prefs | app | core | none | 0.1.2 |
| [screenshot](https://github.com/markc/mixos/blob/main/apps/screenshot/Cargo.toml) | screenshot | app | desktop | public | 0.1.2 |
| [annotation](https://github.com/markc/mixos/blob/main/apps/screenshot/crates/annotation/Cargo.toml) | screenshot | app | core | none | 0.1.2 |
| [term](https://github.com/markc/mixos/blob/main/apps/term/Cargo.toml) | term | app | desktop | public | 0.4.0 |
| [term-core](https://github.com/markc/mixos/blob/main/apps/term/crates/term-core/Cargo.toml) | term | app | core | none | 0.1.2 |
| [term-render](https://github.com/markc/mixos/blob/main/apps/term/crates/term-render/Cargo.toml) | term | app | desktop | none | 0.1.2 |
| [mesh-sign](https://github.com/markc/mixos/blob/main/cli/mesh-sign/Cargo.toml) | mesh-sign | cli | core | none | 0.1.2 |
| [mix-shell](https://github.com/markc/mixos/blob/main/cli/mix-shell/Cargo.toml) | mix-shell | cli | mix | public | 0.117.0 |
| [mixos-mcp](https://github.com/markc/mixos/blob/main/cli/mixos-mcp/Cargo.toml) | mixos-mcp | cli | core | none | 0.1.2 |
| [system](https://github.com/markc/mixos/blob/main/cli/system/Cargo.toml) | system | cli | core | none | 0.1.2 |
| [assets](https://github.com/markc/mixos/blob/main/libs/assets/Cargo.toml) | assets | lib | core | public | 0.1.2 |
| [buildinfo](https://github.com/markc/mixos/blob/main/libs/buildinfo/Cargo.toml) | buildinfo | lib | core | none | 0.1.2 |
| [bus](https://github.com/markc/mixos/blob/main/libs/bus/Cargo.toml) | bus | lib | core | none | 0.1.2 |
| [citizen](https://github.com/markc/mixos/blob/main/libs/citizen/Cargo.toml) | citizen | lib | core | none | 0.1.2 |
| [command](https://github.com/markc/mixos/blob/main/libs/command/Cargo.toml) | command | lib | core | public | 0.3.0 |
| [config](https://github.com/markc/mixos/blob/main/libs/config/Cargo.toml) | config | lib | core | none | 0.1.2 |
| [daemon](https://github.com/markc/mixos/blob/main/libs/daemon/Cargo.toml) | daemon | lib | core | none | 0.1.2 |
| [davproto](https://github.com/markc/mixos/blob/main/libs/davproto/Cargo.toml) | davproto | lib | core | none | 0.1.2 |
| [design](https://github.com/markc/mixos/blob/main/libs/design/Cargo.toml) | design | lib | core | none | 0.1.2 |
| [edit](https://github.com/markc/mixos/blob/main/libs/edit/Cargo.toml) | edit | lib | core | none | 0.1.2 |
| [editor-model](https://github.com/markc/mixos/blob/main/libs/editor-model/Cargo.toml) | editor-model | lib | core | none | 0.1.2 |
| [editor](https://github.com/markc/mixos/blob/main/libs/editor/Cargo.toml) | editor | lib | desktop | none | 0.1.2 |
| [expr](https://github.com/markc/mixos/blob/main/libs/expr/Cargo.toml) | expr | lib | core | none | 0.1.2 |
| [files](https://github.com/markc/mixos/blob/main/libs/files/Cargo.toml) | files | lib | core | none | 0.1.2 |
| [logging](https://github.com/markc/mixos/blob/main/libs/logging/Cargo.toml) | logging | lib | core | none | 0.1.2 |
| [mds](https://github.com/markc/mixos/blob/main/libs/mds/Cargo.toml) | mds | lib | core | none | 0.1.2 |
| [mimedb](https://github.com/markc/mixos/blob/main/libs/mimedb/Cargo.toml) | mimedb | lib | mix | none | 0.1.2 |
| [mix](https://github.com/markc/mixos/blob/main/libs/mix/Cargo.toml) | mix | lib | mix | public | 0.117.0 |
| [props](https://github.com/markc/mixos/blob/main/libs/props/Cargo.toml) | props | lib | core | none | 0.1.2 |
| [scene](https://github.com/markc/mixos/blob/main/libs/scene/Cargo.toml) | scene | lib | core | none | 0.1.2 |
| [settings](https://github.com/markc/mixos/blob/main/libs/settings/Cargo.toml) | settings | lib | core | public | 0.8.0 |
| [strict](https://github.com/markc/mixos/blob/main/libs/strict/Cargo.toml) | strict | lib | core | none | 0.1.2 |
| [syntax](https://github.com/markc/mixos/blob/main/libs/syntax/Cargo.toml) | syntax | lib | core | none | 0.1.2 |
| [test-broker](https://github.com/markc/mixos/blob/main/libs/test-broker/Cargo.toml) | test-broker | lib | core | none | 0.1.2 |
| [thumbs](https://github.com/markc/mixos/blob/main/libs/thumbs/Cargo.toml) | thumbs | lib | core | none | 0.1.2 |
| [toolkit](https://github.com/markc/mixos/blob/main/libs/toolkit/Cargo.toml) | toolkit | lib | desktop | none | 0.1.2 |
| [blobd](https://github.com/markc/mixos/blob/main/services/blobd/Cargo.toml) | blobd | service | core | none | 0.1.2 |
| [bridged](https://github.com/markc/mixos/blob/main/services/bridged/component.mx) | bridged | service | desktop | public | 0.2.0 |
| [compd](https://github.com/markc/mixos/blob/main/services/compd/Cargo.toml) | compd | service | desktop | public | 0.2.0 |
| [comp-model](https://github.com/markc/mixos/blob/main/services/compd/crates/comp-model/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [comp-service](https://github.com/markc/mixos/blob/main/services/compd/crates/comp-service/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [decor](https://github.com/markc/mixos/blob/main/services/compd/crates/decor/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [dispatcher](https://github.com/markc/mixos/blob/main/services/compd/crates/dispatcher/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [drivers](https://github.com/markc/mixos/blob/main/services/compd/crates/drivers/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [edges](https://github.com/markc/mixos/blob/main/services/compd/crates/edges/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [effects](https://github.com/markc/mixos/blob/main/services/compd/crates/effects/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [frames](https://github.com/markc/mixos/blob/main/services/compd/crates/frames/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [graphics](https://github.com/markc/mixos/blob/main/services/compd/crates/graphics/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [headless](https://github.com/markc/mixos/blob/main/services/compd/crates/headless/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [kms](https://github.com/markc/mixos/blob/main/services/compd/crates/kms/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [ledger](https://github.com/markc/mixos/blob/main/services/compd/crates/ledger/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [model](https://github.com/markc/mixos/blob/main/services/compd/crates/model/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [motion](https://github.com/markc/mixos/blob/main/services/compd/crates/motion/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [native](https://github.com/markc/mixos/blob/main/services/compd/crates/native/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [nested](https://github.com/markc/mixos/blob/main/services/compd/crates/nested/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [outputs](https://github.com/markc/mixos/blob/main/services/compd/crates/outputs/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [policy-host](https://github.com/markc/mixos/blob/main/services/compd/crates/policy-host/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [policy](https://github.com/markc/mixos/blob/main/services/compd/crates/policy/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [protocols](https://github.com/markc/mixos/blob/main/services/compd/crates/protocols/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [recorder](https://github.com/markc/mixos/blob/main/services/compd/crates/recorder/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [render-gles](https://github.com/markc/mixos/blob/main/services/compd/crates/render-gles/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [scene-host](https://github.com/markc/mixos/blob/main/services/compd/crates/scene-host/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [scenegraph](https://github.com/markc/mixos/blob/main/services/compd/crates/scenegraph/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [screencopy](https://github.com/markc/mixos/blob/main/services/compd/crates/screencopy/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [seat](https://github.com/markc/mixos/blob/main/services/compd/crates/seat/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [slots](https://github.com/markc/mixos/blob/main/services/compd/crates/slots/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [surfaces](https://github.com/markc/mixos/blob/main/services/compd/crates/surfaces/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [testkit](https://github.com/markc/mixos/blob/main/services/compd/crates/testkit/Cargo.toml) | compd | test | desktop | none | 0.1.2 |
| [ui](https://github.com/markc/mixos/blob/main/services/compd/crates/ui/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [wlcs](https://github.com/markc/mixos/blob/main/services/compd/crates/wlcs/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [world](https://github.com/markc/mixos/blob/main/services/compd/crates/world/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [x11-wm](https://github.com/markc/mixos/blob/main/services/compd/crates/x11-wm/Cargo.toml) | compd | service | desktop | none | 0.1.2 |
| [dnsd](https://github.com/markc/mixos/blob/main/services/dnsd/Cargo.toml) | dnsd | service | core | public | 0.3.4 |
| [dns-core](https://github.com/markc/mixos/blob/main/services/dnsd/crates/dns-core/Cargo.toml) | dnsd | service | core | none | 0.1.2 |
| [editd](https://github.com/markc/mixos/blob/main/services/editd/Cargo.toml) | editd | service | core | public | 0.2.0 |
| [hostd](https://github.com/markc/mixos/blob/main/services/hostd/Cargo.toml) | hostd | service | core | public | 0.1.0 |
| [indexd](https://github.com/markc/mixos/blob/main/services/indexd/Cargo.toml) | indexd | service | core | public | 0.1.2 |
| [inputd](https://github.com/markc/mixos/blob/main/services/inputd/Cargo.toml) | inputd | service | core | public | 0.5.0 |
| [inputd-core](https://github.com/markc/mixos/blob/main/services/inputd/crates/inputd-core/Cargo.toml) | inputd | service | core | none | 0.1.2 |
| [inputd-schema](https://github.com/markc/mixos/blob/main/services/inputd/crates/inputd-schema/Cargo.toml) | inputd | service | core | none | 0.1.2 |
| [maild](https://github.com/markc/mixos/blob/main/services/maild/Cargo.toml) | maild | service | core | public | 0.1.2 |
| [maild-auth](https://github.com/markc/mixos/blob/main/services/maild/crates/maild-auth/Cargo.toml) | maild | service | core | none | 0.1.2 |
| [maild-bayesian](https://github.com/markc/mixos/blob/main/services/maild/crates/maild-bayesian/Cargo.toml) | maild | service | core | none | 0.1.2 |
| [maild-rules](https://github.com/markc/mixos/blob/main/services/maild/crates/maild-rules/Cargo.toml) | maild | service | core | none | 0.1.2 |
| [mixtrayd](https://github.com/markc/mixos/blob/main/services/mixtrayd/Cargo.toml) | mixtrayd | service | desktop | public | 0.1.2 |
| [monitord](https://github.com/markc/mixos/blob/main/services/monitord/Cargo.toml) | monitord | service | core | public | 0.1.0 |
| [noded](https://github.com/markc/mixos/blob/main/services/noded/Cargo.toml) | noded | service | core | public | 0.18.3 |
| [mesh-trust](https://github.com/markc/mixos/blob/main/services/noded/crates/mesh-trust/Cargo.toml) | noded | service | core | none | 0.1.2 |
| [mesh](https://github.com/markc/mixos/blob/main/services/noded/crates/mesh/Cargo.toml) | noded | service | core | none | 0.1.2 |
| [notifyd](https://github.com/markc/mixos/blob/main/services/notifyd/component.mx) | notifyd | service | desktop | public | 0.1.0 |
| [portald](https://github.com/markc/mixos/blob/main/services/portald/Cargo.toml) | portald | service | core | public | 0.1.0 |
| [releasesd](https://github.com/markc/mixos/blob/main/services/releasesd/component.mx) | releasesd | service | desktop | public | 0.2.0 |
| [settingsd](https://github.com/markc/mixos/blob/main/services/settingsd/Cargo.toml) | settingsd | service | core | public | 0.1.0 |
| [toolsd](https://github.com/markc/mixos/blob/main/services/toolsd/component.mx) | toolsd | service | core | public | 0.1.0 |
| [webd](https://github.com/markc/mixos/blob/main/services/webd/Cargo.toml) | webd | service | core | public | 0.1.2 |

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-09-egui-applications/ (source: https://mixos.dev/docs/decisions/2026-10-09-egui-applications.md) -->

# Decision — egui applications, engine first

Status: accepted 2026-10-09.

## The decision

Commands take parameters and return results; see [the amendment](2026-10-20-commands-take-parameters.md).

- **The UI toolkit is egui/eframe on wgpu, from crates.io.** MixOS vendors no UI
  toolkit and tracks egui's current release deliberately.
- **Engine first.** An application's behaviour lives in pure-data engine
  crates that know nothing about the UI. The egui crate is a thin shell that
  renders state and dispatches commands.
- **Every action is a command.** A command has a stable id, a label, a menu
  path, an optional shortcut, an enablement rule and a handler. Menus,
  shortcuts and the command palette are generated from the registry. The UI,
  the `mix` command line and ABP Bus verbs all dispatch commands by id, so
  everything a person can do in an application an agent can do too, locally or
  across the mesh.
- **UI state is one serialisable struct.** Agents can read it, drive it and
  restore it over the Bus.
- **One MixOS theme.** Colours, metrics, radii and type come from design
  tokens. Hard-coded colours are refused by a gate.
- **Tests and offscreen snapshots are the gate** for UI changes, rendered
  without a window and checked as images.
- **Rendering is GPU-first through wgpu.** Specialised CPU renderers (terminal
  and editor text) draw into textures. A software adapter is the fallback.
- **External applications are welcome without being forked.** An application
  that offers a line-delimited JSON control channel can be bridged to the Bus
  as a set of verbs by one generic adapter, and runs inside the MixOS session
  unmodified.

## Why

The approach makes every application agent-operable by construction, keeps
behaviour testable without a display, and rests on a mature toolkit with a
stable release cadence.

## Consequences

- Applications and the desktop furniture enter this tree as they are written
  to this standard.
- Performance claims are measured on real hardware and recorded with their
  workload before and after a change.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-04-source-layout/ (source: https://mixos.dev/docs/decisions/2026-10-04-source-layout.md) -->

# Decision — source layout and naming

**Accepted 2026-10-04.** The binding rules are in the repository's
[`AGENTS.md`](https://github.com/markc/mixos/blob/main/AGENTS.md). This page records why.

## The decision

- **The top level is classified by kind of artefact, one axis only:**
  `apps/`, `services/`, `cli/`, `libs/` and `session/`, beside `tests/`,
  `tools/`, `etc/`, `share/`, `docs/` and `vendor/`. Layer and domain are
  metadata checked by gates, never directories.
- **Components are self-contained.** A component's crates, systemd units, Mix
  scripts, assets, translations and tests live in its one directory. Private
  crates nest in the component's own `crates/`.
- **Plain names:** no brand or layer prefixes. Names are unique across the
  resolved dependency graph and never reused once retired.
- **Promotion to `libs/` is a reviewed decision, not an automatic move.**
- **The Mix language is two packages:** the embeddable library `mix` in
  `libs/mix`, and the shell `mix-shell` in `cli/mix-shell`, which builds the
  `mix` binary. Daemons embed the interpreter without linking the shell.

## Evidence: how comparable projects do it

Checked against each project's repository on 2026-10-04.

| Project | Shape | Naming | Why |
|---|---|---|---|
| Zed | one workspace, flat `crates/` (249 crates) | plain | internal crates, never published |
| rust-analyzer | flat `crates/` (35) | plain; renamed when published | same |
| Servo, Deno | `components/`, `ext/` | plain | split by role |
| Bevy, uv, nushell | flat `crates/` | prefixed | every crate published to crates.io |
| Haiku | `src/{apps,kits,servers,libs,bin,…}` | plain | by kind of artefact |
| SerenityOS | `Userland/{Applications,Libraries,Services,Utilities,…}` | `Lib*` | by kind of artefact |

Two lessons:

- **Prefixes appear where crates are published** into a global namespace.
  Unpublished workspaces use plain names successfully at very large scale.
- **Operating-system projects divide by kind of artefact,** the most stable
  classifier: an app seldom becomes a library.

## What was weighed

- **Layer + kind + domain at one level** (the earlier plan: `bus/`, `mix/`,
  `core/`, `services/`, `desktop/`). Rejected: three axes compete at one
  level. A desktop daemon could plausibly sit in either of two places, and a
  crate that changes layer has to move.
- **One flat `crates/` directory** (Zed, rust-analyzer), with per-package
  co-location. Seriously considered: it gives fully stable paths, because
  nothing about classification is encoded in a path. Not chosen. With
  hundreds of siblings, a large compositor and a tiny parser look identical;
  the kind of a component (and therefore its lifecycle: units, man pages,
  install rules) would no longer be visible; and the case for stable paths
  is weaker than it looks, because an app becoming a library is exactly
  the kind of change that deserves a deliberate move and review.
- **Domain-first** (`mail/`, `media/`, `mesh/`…). Rejected: domains blur and
  multiply, and cross-domain code has no home.
- **One repository per component**. Rejected: MixOS keeps one
  workspace so one dependency graph can be gated, shared code can be
  consolidated, and changes across components are atomic. Its benefits
  (per-package distribution, separate teams) do not apply here.

## Review

The proposal was reviewed cold by four model families: Codex, GLM, DeepSeek
and, as tie-breaker, Gemini.

- **Kind-first layout:** three of four. The dissent preferred the flat
  directory for path stability. That argument is recorded above.
- **What all reviewers converged on** reshaped the rules:
  - artefacts co-located with their component;
  - `vendor/` shared at the top level;
  - no automatic promotion;
  - Mix out of `cli/` and split into two packages;
  - layers derived from dependencies and cross-checked;
  - removal as a reviewed operation;
  - a Bus verb registry and a name-retirement registry;
  - licence headers in the REUSE format, checked without Python;
  - Fluent for translations;
  - a test-tier taxonomy;
  - public decision records like this one.
- **Considered and declined:**
  - top-level `sys/`, `init/`, `hw/` and `patches/`;
  - a separate test workspace.
  FFI crates take a `-sys` suffix instead, and patch notes live with each
  vendored upstream.

---

<!-- page: https://mixos.dev/assets/ (source: https://mixos.dev/assets/README.md) -->

# assets

The resolver for a pinned, immutable set of fonts, icons and emoji on the
local disk. No downloader, daemon or storage service: an installer
publishes a set as `<root>/sets/<id>` and points `<root>/current` at it;
this crate finds, checks and reads it.

The source is [`libs/assets`](https://github.com/markc/mixos/tree/main/libs/assets).

## A published set

```
<root>/
  current -> sets/2026-10-04-core-3      the activation link
  sets/2026-10-04-core-3/
    manifest.conf.mix                    strict data, schema mixos.static-assets.v1
    fonts.css                            generated stylesheet, text locked as web_css
    fonts/  icons/  emoji/  web/  licences/
```

The manifest (`Manifest`) names the schema, the set ID, the font roles
(`sans`, `serif`, `mono`, `icons`, `emoji`, `display`, `serif_italic`,
`mono_italic`, …) and the family each role declares (`font_families`),
and locks every file (`AssetFile`: path, HTTPS url and upstream, revision,
licence, size, SHA-256, BLAKE3). The `icons` role's font has a
`.codepoints` catalogue beside it (`name hex` per line) that becomes the
`icon(name)` table.

Opening a set checks the layout (no symlinks, no escapes, no extra
components), the manifest against the rules in `manifest.rs`, every size
and the stylesheet text. `verify` streams every file through both hashes.
A set, once opened, is pinned to its `sets/<id>` directory: swapping
`current` changes what the next reader selects, not what this one holds.

## The generic API

Nothing in the core knows which project is asking. A `Lookup` is an ordered
list of asset roots the caller names:

```rust
use assets::{AssetSet, Lookup, XdgData};

// Roots from the XDG data directories (user first), then a system root
// from an environment variable with a default.
let lookup = Lookup::new()
    .xdg("example/assets")                                   // $XDG_DATA_HOME/…, each $XDG_DATA_DIRS/…
    .root_from_env("EXAMPLE_ASSETS", "/usr/share/example/assets");
let set: Option<AssetSet> = lookup.discover()?;              // first root with `current`, verified
let set: Option<AssetSet> = lookup.select()?;                // the same, sizes checked but no hashing

// Explicit inputs for a test, or a lookup assembled some other way.
let lookup = Lookup::new().xdg_in("example/assets", &XdgData::default()).root("/srv/assets");
let lookup: Lookup = vec![std::path::PathBuf::from("/srv/assets")].into_iter().collect();

// Reading.
let sans = set.font_path("sans");          // Option<PathBuf>
let family = set.family("sans");           // Option<&str>
let glyph = set.icon("delete");            // Option<char>
let css = set.file_path("fonts.css")?;     // Result<Option<PathBuf>>: only locked files resolve
set.verify()?;                             // sizes, SHA-256 and BLAKE3 of every file

// An installer opens its own root directly, before activating.
let set = AssetSet::open(root, "2026-10-04-core-3")?;
let set = AssetSet::current(root)?;        // follow `current` once; None when absent
```

Lookup rules: unset or empty XDG variables take their defaults
(`~/.local/share`, `/usr/local/share:/usr/share`); relative entries are
ignored; a root without `current` falls through; a root whose `current` is
dangling or whose set is malformed is an error, so a broken override is
reported rather than silently replaced by a system set.

The core depends on [strict](../strict/README.md) (the manifest parser),
`serde`, `sha2`, `blake3`, `hex` and `thiserror`. With
`default-features = false` that is all it depends on, and another project
can take it as is. The `verified` feature (pulled in by the default `mixos`
feature) adds [config](../config/README.md), whose `config::atomic` module
provides the descriptor-safe directory walk the verified reads use.

## Verified byte reads

`AssetSet::read_verified(limits)` re-reads a set into a `VerifiedSet`
that owns every byte, instead of answering paths:

```rust
let set = assets::mixos::discover()?.unwrap();               // opened, hashed once
let verified = set.read_verified(ReadLimits::default())?;    // read once, owned
let sans: &[u8] = verified.font("sans").unwrap().bytes();    // never reopened
```

What the read guarantees:

- **Descriptor-relative, symlink-free.** The set directory is opened
  through `config::atomic::open_directory` (no symlink in any component of
  the absolute path) and every file through `config::atomic::open_nested`
  (no symlink in any intermediate component or in the final file, which
  must be a regular file). The manifest is opened and read exactly once,
  through the descriptor.
- **Strict reparse.** The manifest is parsed and validated again from its
  own bytes; the verified set never trusts an earlier `AssetSet::open`.
  Manifest parse errors stay `Error::Manifest`, icon catalogue errors stay
  `Error::Invalid`, content differences stay `Error::Mismatch`.
- **One read, exact length, both digests.** Each locked file is
  descriptor-opened once, its metadata length must equal the locked size,
  it is read exactly once, and the SHA-256 and BLAKE3 are computed over
  the same owned bytes that are retained (`VerifiedFile::bytes`). A file
  that grows or shrinks while being read is refused.
- **Bounded capture.** `ReadLimits` bounds the manifest, each file and the
  total captured bytes (defaults: 256 KiB manifest, 64 MiB per file,
  128 MiB in all). Every bound is capped by a hard limit
  (`ReadLimits::MAX_MANIFEST_BYTES`, `MAX_FILE_BYTES`, `MAX_TOTAL_BYTES`:
  256 KiB, 256 MiB, 512 MiB), so no request can capture unbounded bytes;
  the total is a bound on captured source bytes, deliberately not
  `MAX_FILES × MAX_FILE_BYTES`. It is not a process-heap limit: the
  parsed manifest, the icon table and the one-time bounded read and
  conversion scratch are outside it.
- **The identity pins bytes, not a path.** `VerifiedSet::identity()` is a
  `SetIdentity`: the set ID plus the BLAKE3 of the exact manifest bytes
  the set was read from. Two directories that share an ID but hold
  different manifests are different identities, and the digest can be
  recomputed from `manifest_bytes()`.

Replacement semantics: once the set directory descriptor is opened, reads
are bound to that inode. Swapping or removing `sets/<id>` afterwards
changes what the next reader sees, never what a captured `VerifiedSet`
holds. Nothing is reopened later; the directory descriptor is retained
for the life of the set.

## The MixOS defaults

`assets::mixos` (the default `mixos` feature) is the MixOS search path, kept
apart from the core the way [bus](../bus/README.md) keeps `noded_url()`:

| Order | Root |
|---|---|
| 1 | `$XDG_DATA_HOME/mixos/assets` (`~/.local/share/mixos/assets`) |
| 2 | each `$XDG_DATA_DIRS` entry's `mixos/assets` (`/usr/local/share`, `/usr/share`) |
| 3 | `assets` under `config::path(Dir::Share)`: `$MIXOS_SHARE/assets`, default `/opt/mixos/share/assets` |

```rust
let set = assets::mixos::discover()?;              // once, at startup, hashes verified
let set = assets::mixos::select()?;                // once, at startup, no hashing (compd)
let lookup = assets::mixos::lookup();              // the roots, for diagnostics
let lookup = assets::mixos::lookup_in(&xdg, &share); // explicit inputs
```

The lock and installer for the MixOS set live in
[`share/assets/`](https://github.com/markc/mixos/tree/main/share/assets)
(`core.conf.mix`, `install.mix`), which publishes to
`/opt/mixos/share/assets`.

## Testing

`cargo test -p assets`. The unit tests cover the validators, the catalogue
parser, the read limits and the lookup order; `tests/sets.rs` the public
behaviour on fixture sets in a temporary directory (pinning across a
`current` swap, XDG precedence, tampering, symlinks, escapes, bad
manifests); `tests/verified.rs` the verified reads (owned bytes surviving
path replacement and removal, descriptor pinning across a substitution,
symlink escapes, staging limits, length and digest refusals, malformed
manifests and catalogues); `tests/layout.rs` the installed
`2026-10-04-core-3` layout rebuilt with stand-in bytes and resolved
through the MixOS search path, plus the real installation when the
machine has one. `config::atomic::open_nested`'s walker refusals are
tested in `libs/config/src/atomic.rs`.

---

<!-- page: https://mixos.dev/backdrop/ (source: https://mixos.dev/backdrop/README.md) -->

# Backdrop

Backdrop draws the MixOS desktop background. It is its own program, not
part of the compositor: it puts one surface on the compositor's
background layer for each output, under every window and panel, and
draws it with egui. A crash in it never takes the session down.

What it draws today:

- a **solid colour** per output, or the **session theme's** colour when no
  document names one;
- a **PNG or JPEG image**, with fill, fit, centre, tile or stretch sizing;
- a **slideshow**, from a folder or an explicit image list, with a half-second
  crossfade. Each output may have its own wallpaper.

The live folder view remains planned. The probe (`backdrop --probe`) is the
regression gate for the surfaces, scale and input, and draws its own labels.

## The document

`backdrop.mx` (strict data, `schema: 1`), in the app's config directory
(`AppDirs`, `config/backdrop.mx`) unless `--config PATH` names another.

```text
schema: 1
default: { colour: "#1e1e2e" }
outputs: {
  "DP-1": { image: "/usr/share/wallpapers/hills.jpg", fallback: "#000000" },
}
```

- `schema` is required and must be `1`.
- `default` is one wallpaper; without it the session theme's colour fills
  every output.
- Each wallpaper names exactly one of `colour` (`#RRGGBB`, six hex digits),
  `image` (an absolute path) or `slideshow` (the source and timing below).
  `fallback` (`#RRGGBB`) goes with an image or slideshow: it shows behind
  transparent pixels and in letterbox bars. Without it the theme colour shows.
- `fit` goes with an image or slideshow. It defaults to `fill`, which crops
  equally from opposite edges to cover the output. `fit` preserves the aspect
  ratio with letterbox bars; `centre` centres the image at its native pixel
  size; `tile` repeats at its native pixel size from the top left; `stretch`
  covers the output without preserving the aspect ratio. Native sizing honours
  the output scale even when the retained texture has been downscaled.
- `outputs` maps an output's name (`DP-1`) to its own wallpaper; an output
  without one takes the default.
- Unknown keys, wrong types, bad colours, relative paths and other shapes
  are refused, naming the field. A bad document at start stops the app.

Command line: `--colour #RRGGBB` or `--image FILE` replaces the document's
**default** for this run (it is not stored). `--service NAME` registers the
Bus name (default `backdrop`).

## Slideshows

```text
schema: 1
default: {
  slideshow: { folder: "/usr/share/wallpapers", interval_s: 600, shuffle: false },
  fallback: "#101820",
  fit: "fit",
}
```

Replace `folder` with `images: ["/usr/share/wallpapers/a.png",
"/usr/share/wallpapers/b.jpg"]` for an explicit order. Exactly one source is
required, all paths are absolute, and an explicit list must be non-empty.
`interval_s` defaults to 600 and values below 5 are refused. `shuffle` defaults
to false. Folder discovery is bounded and non-recursive; PNG and JPEG files
are sorted before scheduling. Discovery and decoding run on the worker.
The folder is discovered at startup or on a set; reapply the document to pick up
folder changes. Repeated paths in a list share one schedule entry.

A slideshow retains its current image while the next decodes. A failed decode
keeps that image and reports the error; the failed entry is skipped on the next
attempt, which waits for the interval. Entries are tried again on later cycles.
A successful advance crossfades for about 0.5 seconds, then releases
the previous image and texture. The configured source is preserved when stored.
A refused replacement also defers active slideshows for another interval, so
their last good image stays visible after the refusal.

## Images

- PNG and JPEG only. The file is opened once, without blocking (a FIFO or
  device is refused), and read through a limit of 32 MiB; anything larger is
  refused. The format, the header's dimensions and the pixels all come from
  those same bytes. A header over 16384 pixels a side, or over 32 Mpx, is
  refused before any pixel buffer exists. The decoder's own allocation cap is
  256 MiB.
- Decoding runs on one worker thread, one image at a time. The kept image is
  downscaled so its longest side is at most 3840 pixels.
- At most four resident image sources per document, counted after command-line
  overrides. A slideshow counts as one source regardless of its list length;
  only its selected images are decoded.
- Every image a set names is decoded again, even one already on screen, so a
  file replaced at the same path is picked up by the next set.
- A set applies only once all its images are decoded. A missing, corrupt,
  oversize or unsupported image refuses the whole change: the last applied
  backdrop stays on screen, and the reason is in `backdrop.state`. Images being
  kept for a refused or superseded set are dropped at once; in-flight results
  are discarded on completion.

### Memory budgets

Two aggregate budgets, both enforced; the per-image limits above are not
totals.

| Budget | Limit | Worst case |
|---|---|---|
| Decoded RGBA held by the controller (applied and candidate images together) | 512 MiB (`RESIDENT_BUDGET`) | a decode that would take the total over it is refused (`IMAGE`); the last applied images stay until a whole candidate set applies |
| Accounted wallpaper texture bytes, across all outputs, overlap included (`TEXTURE_BUDGET`) | 512 MiB | four full-size outputs swapping (four old and four new textures) |

Each output keeps its own texture at the decoded size, capped at 3840 pixels
a side. The budget can leave additional outputs on fallback when there is no
room for their textures. An image over the device's texture-size limit keeps
the output's last good image on screen, or shows fallback when there is none,
with the limit reported in that output's `error`.

A full-size image is 3840 × 3840 × 4 bytes = 56.25 MiB, the largest kept. Four
applied plus four candidates is 450 MiB, which fits the 512 MiB resident budget.
Textures are accounted as the bytes of the new size reserved while the old is
still held, so a swap is counted in full. When bytes are released, live outputs
are woken once so one that was starved draws again; nothing wakes when nothing
is freed.

- A context owns one image texture, or two during a slideshow crossfade.
  Replacing it reserves the new size
  while the old is still held, so the overlap is counted; a texture that does
  not fit leaves that output on its fallback colour, with the reason in its
  `error`. Removing an output, showing a solid colour, or a change of image
  releases its bytes.
- A texture upload copies the decoded image once (a transient copy of at most
  one image, on the CPU).

These account for wallpaper data, rather than total process RSS or GPU-driver
memory. Compressed input, decoder allocations, RGBA conversion and resizing
have their own transient bounds; the renderer also owns resources beyond the
wallpaper textures.

## The Bus

Service `backdrop` (or `--service`). Verbs (registered in
`docs/docs/spec/bus/verbs.conf.mix`):

| Verb | Class | Body | Reply |
|---|---|---|---|
| `backdrop.ping` | query | `{}` | `{schema, service}` |
| `backdrop.state` | query | `{}` | the state below |
| `backdrop.set` | intent | a complete document (above) | the change, once applied |
| `backdrop.next` | intent | `{}` | full state, once the next images have decoded and applied |

`backdrop.set` replaces the whole document; it does not patch it. A valid
set waits for its images, is stored in the document's file (atomically,
through `config::atomic`), and then applies. Its reply is `rc 0` with
`{requested, active, config_file}`. A refusal is `rc 10` with
`{error_code, message}`:

- `ARGUMENT`: the body is not a valid document (nothing changed);
- `IMAGE`: an image did not decode (nothing changed);
- `STORE`: the document could not be stored (nothing changed), or it was
  stored but its durability is not confirmed (applied; the reply says so);
- `SUPERSEDED`: a newer set replaced this one before it applied.
- `BUSY`: a next arrived while a set or advance was decoding;
- `NON_SLIDESHOW`: a next was requested with no applied slideshow;
- `UNKNOWN`: the requested verb is not implemented.

`backdrop.next` advances configured slideshows without changing or storing their
sources. It refuses a configuration with no slideshow. An advance waiting for
decode keeps the current pixels; a newer set can supersede it. Refused advances
are not published as executed commands.
Automatic advances run independently for each configured source and wait for
the active crossfade to finish. A corrupt image on one output does not stop
other outputs' schedules. A manual next advances all slideshows together and
can interrupt their current fade.

`backdrop.state` answers with no output on screen:
`{schema, service, requested, active, pending, error, config, config_file,
outputs, fit, slideshows}`. `fit` is the default image's effective fit (or null
for a solid fill); outputs also report their effective fit. Each slideshow
reports its output (null for the default), `current_path`, `index`, `count`,
`interval_s`, `shuffle`, `pending` and `fading`.
`requested` and `active` are revisions: `requested` numbers every request,
including startup and automatic slideshow advances,
made, and `active` is the revision of the accepted configuration. `pending` is
the revision still decoding, if any. `error` is the last refused change's
reason until another change applies successfully, including an automatic advance.
`outputs` lists each output drawn so far, with its size, scale, what it
shows (`theme`, `colour`, `image` or `fallback`), its `error`, and
`presented_revision`: the revision that output last drew. Use that field to see
what is on screen; `active` alone does not mean every output has presented it yet.

Every applied Bus set or next is one run of its command and is published on
`backdrop.command.executed` with origin `bus`. The command line's default is
not a run: it is the start state.

## Cost

It costs nothing while nothing changes. A static colour or image draws once
per output and then sleeps; a set, a decode, a change of output or scale wakes
it through egui's repaint request.

The slideshow controller waits on its inbox until the next schedule or fade
deadline. It never polls. Repaints run only while a fade is active, and stop
when the previous texture is released.

## Start-up and failure

- The Bus registration must succeed: if the broker refuses or is unreachable,
  backdrop exits with the reason rather than running a second, unregistered
  wallpaper.
- An output that goes away is released (`LayerProgram::removed`): its context,
  its texture and its status.

## Known gaps

- The theme's colour is taken from the installed style's panel fill, not a
  named design token. Naming the desktop token is a follow-up.
- Overlapping sets (one still decoding when the next arrives) are exercised by
  the controller's unit tests; the Mix gate sends its sets one after another.
- Input limits bound allocations, not filesystem latency. A stalled mount can
  block the single decode lane until its I/O returns; state, ping, theme and
  solid-colour controls remain available. Superseded in-flight results are
  discarded on completion; already queued jobs are withdrawn immediately.

## Running it

Run it inside a MixOS session: `backdrop`, or `backdrop --colour #1e1e2e`,
or `backdrop --image /abs/path.jpg --service backdrop-test`.

## Source layout

The source is
[`apps/backdrop`](https://github.com/markc/mixos/tree/main/apps/backdrop):

- `src/main.rs`: command line, the start-up document, the layer loop;
- `src/control.rs`: the Bus controller and its one command, `backdrop.set`;
- `src/program.rs`: the layer program, which only draws a published view;
- `src/probe.rs`: `--probe`, the regression probe (JSON lines on stdout);
- `crates/wallpaper`: the engine: the document, colour, fit, decode limits
  and revisions. Pure data, no Bus and no window.

## Tests

Building and the cargo tests are not in this tree's checks yet; the cargo
gate runs on a build worker. `cargo build -p backdrop` enables toolkit's
`layer` feature.

- `tests/desktop/wallpaper_gate.mix` runs the wallpaper on a private broker and
  a private nested compd, takes screenshots of a solid colour and a PNG
  (`share/brand`'s favicon), and checks `backdrop.set` and `backdrop.state`: a
  refused image keeps the last good pixels and revision, rapid sets apply in
  order, a non-document is refused, the accepted document is stored, and the
  process is idle. Run it from the checkout; `--image-fixture PATH` names a
  different PNG and `--shot-out DIR` keeps the PPMs.
- `tests/desktop/backdrop_gate.mix` is the `--probe` regression gate: input,
  paint and occlusion. It runs the probe on a private nested compd and
  checks the band, the paint, the screen, click delivery and occlusion:
  `mix tests/desktop/backdrop_gate.mix --bin <compd> --config-file tests/desktop/smoke-settings.json`.
  On a build worker add `--software --private-bus --noded <noded>`.
- Unit tests (`cargo test -p wallpaper`, `cargo test -p backdrop`) cover the
  document, colour, fit, decoder limits (including an oversized header and a
  FIFO), revisions, candidate and active images, the texture budget and the
  verb registry.

---

<!-- page: https://mixos.dev/blobd/ (source: https://mixos.dev/blobd/README.md) -->

# blobd

The node blob store. Bytes live by hash in the mds content-addressed store.
Names live by owner, in a blobd-owned `blobd.sqlite`. Movement between nodes
happens over a byte lane on the WireGuard address; the Bus carries references
only, never bytes.

The daemon `blobd` registers on the Bus as `blobd`, serves the `blob.*` verbs,
publishes its events with `retain: false`, and listens for byte-lane transfers
on the WireGuard address. Cross-node fetches go through the same lane.

On a mesh node that runs the previous build, it replaces that build in place: the unit keeps the uid, the group
and the state root.

- **Storage:** the store runs on the `mds` library (`libs/mds`).
- **Identity kept on disk:** the cas group `blob` and the state root
  `/var/lib/mixos/blobd` are unchanged, so the port reads the live store on
  the existing nodes without moving data.

---

<!-- page: https://mixos.dev/bridged/ (source: https://mixos.dev/bridged/README.md) -->

# Bridging external applications

Some applications MixOS runs are not MixOS's own: they are built elsewhere
and offer their own automation port. MixOS never forks them to add Bus
verbs. Instead, `bridged` connects to an application's control channel and
answers on the Bus for it, so agents and scripts drive it the same way as
any native app.

One `bridged` instance serves one application, under the application's own
name. An instance named `fakeapp` answers `fakeapp.call`,
`fakeapp.commands`, `fakeapp.execute`, `fakeapp.inspect`,
`fakeapp.screenshot` and `fakeapp.status`.

## What the application must offer

A line-delimited JSON control channel on loopback TCP:

1. Optionally, an auth line first on every connection:
   `{"id":"auth","method":"auth","params":{"token":"<64 hex>"}}`, or with
   `auth: "key"`, the same line with `params.key`. A key is written by the
   application to a file after it starts, and may be rotated; the bridge
   reads that file on every connect.
2. Then one request per line, `{"id":N,"method":"...","params":{...}}`.
3. One reply per line, `{"id":N,"ok":true,"result":...}` or
   `{"id":N,"ok":false,"error":"..."}`, matched to its request by `id`.

The named verbs use the methods `engine.commands`, `engine.execute`,
`ui.inspect` and `ui.screenshot`; `<app>.call` passes any other method
through. The full contract is in the
[bridge spec](../docs/spec/bridge/README.md).

## Setting up an instance

Write the instance config, `/etc/mixos/bridge/<app>.conf.mix` (or
`$MIXOS_ETC/bridge/<app>.conf.mix` for a session). The file name is the
instance name:

```text
port: 47801,
token_file: "/home/user/.config/fakeapp/control.token"
```

For an application whose port has no auth step, write `auth: "none"` and no
`token_file`. For an application that writes its own key file after it
starts, write `auth: "key"` with the same `token_file` (the key file's path).
The instance starts before the key exists; calls answer rc 11 until it does.
Then start the unit:

```sh
systemctl start bridged@fakeapp
```

The unit runs `mix bridged.mix --start fakeapp`. It checks the instance first,
before the name joins the Bus, then runs `mix --serve bridged.mix --name
fakeapp` as its child. A refused start exits 2, with the reason in the
journal, and is never restarted. Any other failure (a crash, a broken
install) is restarted a few times and then left failed. A normal
`systemctl stop` ends the bridge with status 143, which the unit counts as
clean. Run the bridge under the unit, not `--start` by hand: outside systemd,
killing the `--start` process alone can leave the serve child running. A
start is refused when:

- the Mix binary is older than 0.112.1, which cannot bound writes (`RUNTIME`);
- the name is not a valid Bus service name, or starts with `mixos-`
  (`NAME_INVALID`);
- the name belongs to the Bus broker (`noded`, `noded-*`) (`NAME_RESERVED`);
- the name is the first segment of a verb already registered to another
  component, such as `settings` (`NAME_RESERVED`);
- the installed verb registry, `/opt/mixos/share/bus/verbs.conf.mix`, is
  missing or unreadable (`REGISTRY`: the check fails closed);
- the config or the token file is missing or wrong, or the token file is
  readable by group or other (`CONFIG`, `TOKEN`).

## Using it

```sh
send fakeapp fakeapp.status
send fakeapp fakeapp.commands
send fakeapp fakeapp.execute body='{"command":"file.new","params":{"width":640}}'
send fakeapp fakeapp.call body='{"method":"echo","params":{"a":1}}'
```

| rc | Meaning |
|---|---|
| 0 | The app did it; the body is its result as JSON. |
| 10 | The app refused; the body is its error text. |
| 11 | The app could not be reached: connect, auth, transport or timeout, or the bridge is backing off after one. |
| 12 | The request was wrong: a missing field, a body that is not a JSON object, or a request longer than `max_line` (1 MiB by default). |

The bridge keeps one connection open. If the application goes away, calls
answer rc 11, the bridge waits `backoff_s` (default 2 seconds), then
reconnects and authenticates again on the next call. Each call's network
work (connect, auth, writing the request, reading the reply) shares one
`timeout_s` budget, so an application that stops reading, or reads too
slowly, gets rc 11 at about `timeout_s` and a fresh connection after the
backoff. Preparing the request (encoding a large body) cannot be cut short,
so it can add to the time a call takes beyond `timeout_s`; the network step
after it then fails at once. This needs Mix 0.112.1 or later.

## Security

Read this before bridging an application.

- **Any mesh member can drive a bridged application.** The Bus gives every
  member of the mesh access to every verb; there is no per-verb access
  control, and `bridged` adds none. Whatever the application's control
  channel allows, any mesh member can do through `<app>.call`: send it UI
  input, run its commands and, if it has file commands, read and write files.
  Bridge only applications you would let every mesh member drive.
- **File access is the application's to limit.** An application that offers
  file I/O over its control channel should confine it to automation roots it
  is started with (read and write directories). The bridge passes paths
  through unchanged and cannot confine them.
- **The token stays on this node.** It is read from `token_file` at start
  and sent only on the loopback connection. It never appears in `status`, in
  an error or in a log line; if the application echoes it in an error or a
  result, the bridge replaces it with `[redacted]`. The token file must be
  `0600` (a file group or other can read is refused) and readable by the
  unit's user (`mixos`).
- **Loopback only.** The config refuses any host but `127.0.0.1` or
  `localhost`, and connects to `127.0.0.1` for either.
  An `auth: "none"` port is open to every local process while the
  application runs, Bus or no Bus; open it only for applications you bridge.
- **A local process can squat the port.** If the application dies, any
  local process that binds its port before it comes back receives the
  token on the bridge's next reconnect, and can then pass itself off as the
  application to the bridge, and use the token against the real application
  once it returns. Loopback TCP has no way to prove who is listening; a
  unix-socket control channel, checked by owner, would close this, and is a
  possible future protocol option. Until then, bridge applications only on
  machines whose local users you trust.
- **The unit's environment is the administrator's.** Keep
  `/etc/mixos/bridge/<app>.env` and the config writable only by root:
  whoever can change them (`BRIDGED_MIX` in particular) picks the code that
  runs as `mixos`.
- **The unit is sandboxed.** It runs without capabilities or new
  privileges, sees the file system read-only (homes included) with private
  `/tmp` and `/var/tmp`, and may send IP traffic to loopback only. So keep
  the config and the token file out of `/tmp` and `/var/tmp`, where the unit
  cannot see them. A Bus that is not on loopback (for example a session
  broker at `ws://<container-ip>:<port>`) needs a drop-in, `systemctl edit
  bridged@<app>`, adding `IPAddressAllow=<broker-ip>` under `[Service]`.
  The loopback-only IP filter is cgroup BPF: systemd enforces it for this
  system unit and the serve child on kernels and hosts that support it, and
  ignores it where they do not (some container managers, for example). The
  `systemd-analyze security` score is computed from the unit file and does
  not prove the filter is enforced on a given host.
- **The name cannot shadow a system service.** The start checks refuse a
  name that a registered verb already starts with, and the Bus itself refuses
  a name that is already registered.

## Status

`bridged` is version 0.2.0 (unreleased); 0.2.0 adds `auth: "key"`. Its six verbs are declared in the Bus
verb registry, `docs/docs/spec/bus/verbs.conf.mix` (schema 3), as the `bridged`
instance family `<app>.<verb>`. The static registry gate checks the family's
owner and suffix. Installing the registry is a separate prerequisite: the
scripts and the registry must come from the same revision, and the registry
must be at `/opt/mixos/share/bus/verbs.conf.mix` or named by `BRIDGED_VERBS`
in `/etc/mixos/bridge/<app>.env`. Otherwise every start is refused. This
source tree is not a live deployment, and nothing in it installs the
registry for you.

The family is declared with `members: "instances"`, so the running
instances are not listed. `tools/verb_registry.mix --instances DIR` checks
only the private file-stem naming and collisions; it reads no config token.
Mesh access is unchanged: the Bus still gives every member every verb. The
runtime guard reads the verbs and families lists. It does not enforce the
full canonical format (field order, spacing); the static gate does that.

**Verb classes.** `<app>.call` and `<app>.execute` are `intent`;
`<app>.commands`, `<app>.inspect` and `<app>.status` are `query`.
`<app>.screenshot` is `intent`: its `focus` option can bring the window
forward, a change another caller sees, so it is not a query even though it
only captures. See the
[instance verb families decision](../docs/decisions/2026-10-13-instance-verb-families.md).

## Source and tests

`bridged` is a Mix component
([decision](../docs/decisions/2026-10-10-mix-components.md)): no Cargo
package, identity in `component.mx`. The source is
[`services/bridged`](https://github.com/markc/mixos/tree/main/services/bridged):

| Path | What |
|---|---|
| `scripts/lib/bridge_core.mix` | the stateless core: config, token, serve-name guard, line-JSON client |
| `scripts/bridged.mix` | the Bus service (`mix --serve … --name <app>`); `--start <app>` (the unit: checks, then the service as a child); `--check <app>` (the checks alone) |
| `units/bridged@.service` | one unit per application; config `/etc/mixos/bridge/<app>.conf.mix` |
| `tests/lib/fake_app.mix` | a stand-in application on `tcp_listen` (token, key or no auth, slow and dropping methods) |
| `tests/bridge_core_test.mix` | offline: config, token, guard, spec fixture, the client against stand-in apps |
| `tests/bridged_test.mix` | every verb over a private broker, the start refusals, `--start` (no child on a refusal, the child's exit code passed through), the app dying and coming back |

Run the tests from the checkout root with Mix 0.112.1 or later. The mix
binary the tests run under is `BRIDGED_MIX`, else `MIXOS_TEST_MIX`, else
`/opt/mixos/bin/mix`. The Bus test needs a `noded`: `--noded <path>`, else
`MIXOS_TEST_NODED`, else `/opt/mixos/bin/noded`. An empty variable counts as
unset. `tools/mix_tests.mix` sets `MIXOS_TEST_MIX`, `MIXOS_TEST_NODED` and
`BRIDGED_MIX` to the fresh build:

```sh
mix services/bridged/tests/bridge_core_test.mix
mix services/bridged/tests/bridged_test.mix
```

---

<!-- page: https://mixos.dev/buildinfo/ (source: https://mixos.dev/buildinfo/README.md) -->

# buildinfo

Compile-time build provenance for MixOS binaries: package name, version,
git sha (short and full), dirty bit and build time, plus the `--version`
contract every binary answers.

- `emit()` runs in a consumer's `build.rs` and captures the consumer
  repository's HEAD into `MIXOS_GIT_SHA`, `MIXOS_GIT_SHA_FULL`,
  `MIXOS_GIT_DIRTY`, `MIXOS_BUILD_TIME` and the embedded
  `MIXOS_BUILDINFO_MARKER`.
- `build_info!()` expands in the consumer crate and reads those variables
  into a `BuildInfo`.
- `exit_on_version!()` is `main`'s first statement: it answers
  `--version`/`-V` (and `--json`) and exits 0, or falls through.
- The binary also carries `MIXOS-BUILDINFO:1:{…}` as bytes, so an inventory
  can read provenance without running it (`find_markers`).

No dependencies. `SOURCE_DATE_EPOCH` pins the build time for reproducible
builds.

Test: `cargo test -p buildinfo`.

The source is [`libs/buildinfo`](https://github.com/markc/mixos/tree/main/libs/buildinfo).

---

<!-- page: https://mixos.dev/bus/ (source: https://mixos.dev/bus/README.md) -->

# bus

The Bus wire format and the broker client.

- `bus::wire` (always built): `BusMessage`, `parse`, `parse_strict`,
  `parse_lenient` and the size caps. A message is `---`-fenced `key: value`
  headers (sorted) plus an optional body. The format is a frozen contract
  with every running peer.
- `bus::client` (the default `client` feature): `Connection`, one registered
  WebSocket to the broker ([noded](../noded/README.md)); `SupervisedClient`,
  the same under a reconnect supervisor whose incoming stream survives
  broker restarts and which replays every recorded topic subscription before
  reporting `Connected`; `IncomingCommand`; and `noded_url()`, which finds
  the broker (`MIXOS_NODED_URL`, then `node.conf.mix` via
  `MIXOS_NODE_CONFIG`, `$MIXOS_ETC`, `~/.config/mixos` or `/etc/mixos`, then
  `ws://127.0.0.1:4200/ws`).

A wire-only consumer depends on `bus` with `default-features = false` and
pulls in nothing but `serde_json`.

The source is [`libs/bus`](https://github.com/markc/mixos/tree/main/libs/bus).

## Starting without a broker

Resident GUI hosts can use `SupervisedClient::connect_options(name, url).start()`
inside their existing Tokio runtime to return immediately while the broker is
unavailable. The same supervisor handles initial dial, registration, topic
replay and later reconnects. Until first success the state is `Connecting`,
generation is zero and outbound work fails fast; first complete
registration and replay publishes generation one. The single incoming
receiver remains usable across outages. `connect().await` retains its
five-attempt initial budget for callers that need bounded startup. Neither
API queues outbound work.

## Bounded incoming lanes

`bounded_incoming(capacity)` drops overflow silently, reported only as an
`Overflow` marker. `bounded_incoming_rpc(capacity)` opts into refusal: an
id-bearing request with no `topic` header that the full lane cannot retain
gets an `rc 10` `BUSY` reply on the same connection it arrived on, so the
caller can retry. Topic deliveries and id-less frames remain lossy. If that
refusal cannot be written within 100 ms, the old connection gets a
best-effort close within a further 100 ms, and the supervisor detaches its
handle before redialling; the physical close may follow later if another
holder still references it. No reply is ever sent through the replacement
connection.

## Registration rejections

With `fatal_on_registration_rejection(true)`, `registration_rejection()`
retains the broker's exact return code and diagnostic before publishing
`Fatal`, for both initial registration and reconnect. Sampling it is
non-consuming; transport failure has no refusal diagnostic. Close,
shutdown, deregister and drop are safe before a first socket exists and
fence late registration publication. These are client lifecycle APIs; the
frozen ABP wire format is unchanged.

A broker rejection is typed: `RegistrationRejected` keeps the public `rc`
and `message` fields. Field reads and the tuple accessors stay
source-compatible, but old two-field struct literals no longer compile
(construct with `RegistrationRejected::new`). It adds `kind()`, which
decodes the structured rejection body
(`{"schema": "noded.registration-rejection.v1", "error_code": "NAME_TAKEN", "message": …}`,
sent alongside the unchanged `rc=10` and `error` header).
`RegistrationRejectionKind::NameTaken` is produced only from that body; an
admission refusal, a legacy text-only broker, or a missing, malformed,
oversized or unrecognised body is `Unknown`: classification never
string-matches the wording. `ClientError::registration_rejection_typed()`
and `SupervisedError::registration_rejection_typed()` expose the typed
value, and the `(rc, message)` tuple accessors remain for compatibility.

## Tests

`cargo test -p bus`. The integration test drives a stub broker in process;
no noded is needed.

---

<!-- page: https://mixos.dev/busviewer/ (source: https://mixos.dev/busviewer/README.md) -->

# BusViewer

`busviewer` (app id `dev.mixos.busviewer`) is a native window onto the Bus
of the node it runs on. It asks noded which services are registered, asks
each service to describe its verbs, and shows them as a tree. Select a verb
to read its arguments and description, type a JSON body, and call it. The
reply is shown with its return code. BusViewer also lists the mesh nodes
this node can see.

It is for people and agents who want to see what a node offers and try a
verb by hand. It ships in the `mixos-desktop` package set. Nothing else in
the workspace depends on it.

BusViewer is also the reference app for driving a window over the Bus.
Everything in its window is a Bus verb, and
[Driving apps over the Bus](../docs/drive.md#busviewer-the-worked-example)
uses it as the worked example.

The source is
[`apps/busviewer`](https://github.com/markc/mixos/tree/main/apps/busviewer).

## How it is built

BusViewer follows the engine-first rule in
[AGENTS.md](https://github.com/markc/mixos/blob/main/AGENTS.md) §4.1. It is
two crates:

- **`inspector`** (`crates/inspector`): the headless engine. No UI and no
  I/O. It holds the protocol model, the discovery and call rules, and the
  handling of every `busviewer.*` verb.
- **`busviewer`**: the egui shell. It draws the engine's state, runs the
  engine's effects on a small tokio runtime, and owns the command registry
  that the menus, the shortcuts and the Bus all go through.

The engine never does work itself. The shell feeds it events (Bus
deliveries, finished discoveries and calls, edits made in the window), and
the engine returns `Effect`s for the shell to carry out: `Discover`,
`Call`, `Show`, `Reply`, `Commands`, `Execute`, `Describe`, `Drive`, `Copy`
and `Exit`. Every effect that leaves the process carries a ticket. A
completion whose ticket is not the one in flight is ignored, so a late
reply can never land on a newer operation.

### inspector

| Module | What it holds |
|---|---|
| `model` | `Verb`, `Snapshot` (services, each with its verbs or an error; peers), `Selection`, the parsers for `noded.list`, `noded.peers`, `HELP` and `app.describe`, the limits, and `describe()`, the app's own verb list |
| `engine` | `Engine`, `Effect`, `Dialog`, `Row` and `RowKind` (the services tree), `UiState` (what a person arranges), `Session` (the session theme) |
| `bus` | the connection, through the shared [citizen](../citizen/README.md) library: `start`, `probe`, `forward`, `show`, and `discover` |

Discovery calls `noded.list` and `noded.peers`, then asks every service for
`HELP`, falling back to `app.describe`. It describes eight services at a
time. A service that fails to describe itself shows as an error row and
does not stop the others.

The limits are fixed in `model`:

- a JSON body is at most 65,536 bytes;
- a reply is shown up to 1,000,000 bytes, then marked as truncated.

### busviewer

| Module | What it holds |
|---|---|
| `src/main.rs` | options, single-instance launch, the eframe window |
| `src/lib.rs` | the string catalogue: `strings()`, `label()`, `label_with()` |
| `src/shell.rs` | `Shell`: applies events, settles effects, runs Bus work, follows the desktop profile, wires the toolkit drive layer |
| `src/view.rs` | `view()`: draws the engine's state and returns what the person did as `UiEvent`s; it never changes state itself |
| `src/commands.rs` | `registry()`: every command, with its menu, shortcut, icon and when it is enabled |
| `i18n/en/busviewer.ftl` | the English strings |

The shell applies one event and settles its effects before it reads the
next, so a later delivery can never change what an earlier command acts
on. Within one frame, edits are applied before commands, so a call uses
the body the person sees. Bus work wakes the window only when something
finished; nothing polls.

## Rules

- **One operation at a time.** A refresh or a call in flight makes the
  window busy. Bus requests that need it idle are refused with `BUSY`.
- **A call is sent once.** BusViewer never retries. A transport failure is
  reported as return code 10 with the outcome unknown.
- **No call on bad input.** An unadvertised target, a body over the limit
  or invalid JSON is refused before anything is sent. An empty body is
  allowed.
- **Closing answers everything.** Quit waits until accepted work is
  finished, and every Bus request already accepted gets an answer before
  the connection stops.
- **One window per session.** A second launch finds the running BusViewer
  on the Bus, asks it to show its window through compd, and exits.

## Bus

BusViewer registers as `busviewer` on the local broker. Its verbs are
registered in
[`verbs.conf.mix`](https://github.com/markc/mixos/blob/main/docs/docs/spec/bus/verbs.conf.mix)
with owner `busviewer`.

- Reading: `busviewer.ping`, `busviewer.info`, `busviewer.tree`,
  `busviewer.reply`, `busviewer.commands`, plus `HELP` and `app.describe`.
- Changing state: `busviewer.filter`, `busviewer.expand`,
  `busviewer.select_row`, `busviewer.select`, `busviewer.body`,
  `busviewer.split`, `busviewer.dialog`, `busviewer.theme`,
  `busviewer.call`, `busviewer.execute`, `busviewer.refresh`,
  `busviewer.show`, `busviewer.quit`.
- The window's drive verbs, from the toolkit: `busviewer.ui.tree`,
  `busviewer.ui.click`, `busviewer.ui.pointer`, `busviewer.ui.scroll`,
  `busviewer.ui.key`, `busviewer.ui.type`, `busviewer.ui.menu`,
  `busviewer.ui.menu.list`, `busviewer.ui.menu.open`,
  `busviewer.ui.menu.close`, `busviewer.ui.capture`, `busviewer.window`
  and `busviewer.window.state`.

Arguments, answers and refusal codes (`BUSY`, `DISCONNECTED`, `ARGUMENT`,
`UNKNOWN_VERB`, `UNKNOWN_COMMAND`, `DISABLED`) are tabled in
[Driving apps over the Bus](../docs/drive.md#busviewer-the-worked-example).
Tree rows are named by key, for example `service:noded` or
`verb:noded:noded.list`.

Calling a verb from Mix through BusViewer:

```mix
$body = json_encode({service: "noded", verb: "noded.list"})
send busviewer busviewer.call body=$body timeout=30
print $result
```

The answer is `{service, verb, request_body, rc, body}`.

## Commands and keys

Every menu item, shortcut and `busviewer.execute` id is one command in
`src/commands.rs`:

| Command | Menu | Key |
|---|---|---|
| `file.refresh` | File › Refresh services | Ctrl+R |
| `file.quit` | File › Quit | Ctrl+Q |
| `edit.format` | Edit › Format JSON body | Ctrl+Shift+F |
| `edit.clear` | Edit › Clear body | |
| `edit.copy` | Edit › Copy reply | |
| `bus.call` | Bus › Call verb | Ctrl+Enter |
| `help.shortcuts` | Help › Keyboard shortcuts | Ctrl+/ |
| `help.about` | Help › About BusViewer | |
| `view.search` | title bar search button | Ctrl+F |
| `view.mode` | title bar light/dark button | |

View › Theme adds the `view.theme.*`, `view.mode.*`, `view.style.*`,
`view.decorations.*` and `view.captions.*` choices. They set the theme of
this window only; the session's theme file is never written. The Help menu
opens with a field that searches every command. The desktop profile can
rebind the shortcuts (`keymaps.busviewer.<id>`), and `busviewer.commands`
reports the ones in force.

## Running it

```text
busviewer [--noded-url URL] [--service NAME] [--comp NAME]
```

- `--noded-url`: the broker to use. The default is the session's noded.
- `--service`: the Bus name to register as, `busviewer` by default.
- `--comp`: the compositor's service name, used to raise the window. The
  default is `$MIXOS_COMP_SERVICE`, or `comp`.

Service names may contain only ASCII letters, digits, `-`, `_` and `.`.

The window follows the desktop profile's look and keymaps from
[settingsd](../settingsd/README.md), through the
[settings](../settings/README.md) follower, and updates when they change.
With no theme chosen it starts in Studio Dark.

## Testing

On an authorised build worker at a pushed commit:

```text
cargo test --locked -p inspector -p busviewer
```

- The engine's unit tests (`crates/inspector/src/engine.rs`, `model.rs`)
  cover discovery, selection, the body, calls, the Bus verbs, refusals,
  tickets and quitting, with no UI.
- `tests/shell.rs` runs the real `Shell` on a logging Bus handle (the
  `inspector` `testing` feature) and checks every reply, call and the final
  quit in order.
- `tests/drive.rs` drives the window over its Bus verbs against the real
  view: clicks, typing, the title bar controls, menus.
- `tests/view.rs` checks the dialogs, the body buttons and their tooltips,
  and the search field through kittest.
- `tests/snapshot.rs` takes offscreen snapshots in several themes into
  `tests/snapshots/`. Regenerate with `UPDATE_SNAPSHOTS=1` and look at the
  images before committing them.
- `tests/registry.rs` checks that the verb registry lists exactly the
  verbs BusViewer describes, and that read-only verbs are class `query`
  ([verb classes](../docs/decisions/2026-10-11-verb-classes.md)).
- `crates/inspector/tests/native.rs` runs discovery, calls and
  single-instance registration against an isolated real broker. It is
  ignored by default and needs `BUSVIEWER_TEST_URL`.

---

<!-- page: https://mixos.dev/ced/ (source: https://mixos.dev/ced/README.md) -->

# Ced

Ced is the MixOS Editor: a desktop editor over the `edit` Bus service
([editd](../editd/README.md)). A document lives in the service, not in the
window, so several people and agents can edit it at once. Ced shows their
carets, selections and changes as they happen, and keeps typing instant by
applying it locally first.

## Running

```
ced [PATH[:LINE[:COL]]…]   open paths (in the running ced, if there is one)
ced --headless             every verb, no window
ced --service NAME         register as NAME (tests)
```

The edit service must be running. Ced registers on the Bus as `ced`; a
second `ced` hands its paths to the first and exits.

## The window

- **Menus, shortcuts and Bus actions are one registry.** Every action has
  the same id in the menu bar, as a shortcut (Notepad++ conventions: see
  Help › Keyboard Shortcuts) and in `ced.action {id}`.
- **Tabs** show unsaved changes, and ◆ when another origin edited the
  document since you last looked at it.
- **The notice strip** keeps warnings, edits that could not be applied
  (re-insert them at the caret or dismiss them), and a document that lost
  its connection to the service (keep your copy or take the service's).
- **Find** (Ctrl+F, Ctrl+H) runs in the service, so it searches the shared
  text, not a local copy.
- **Markdown and commit messages wrap**; code scrolls sideways.
- **Problems** (Ctrl+Shift+M) lists the document's diagnostics.
- View › Theme picks this window's scheme, style and mode.

## Bus

`ced.*` (schema `ced.v1`): `ping`, `info`, `open`, `new`, `tabs`, `focus`,
`state`, `type`, `select`, `action`, `actions`, `wait`, `layout`, `stats`,
`diagnostics`, `problems`, plus `app.describe` and `app.quit`; and the
toolkit drive verbs (`ced.ui.*`, `ced.window`, `ced.window.state`; see
[driving an app](../docs/drive.md)). A Bus caller's edits carry its own
origin (`agent:ced.<caller>`), so they show as an agent's, and its undo is
its own.

## Source

- `crates/documents`: the engine, with no UI toolkit. Open documents (one
  tab per buffer of the edit service, each a mirror with its editing model,
  highlighting and diagnostics), every action, the `ced.*` verbs and their
  waiters, reconnects and reattaches, the session.
- `src/`: the shell. The Bus thread, `ced --headless`, and the egui window
  around the shared [editor](../editor/README.md) text view.

The source is [`apps/ced`](https://github.com/markc/mixos/tree/main/apps/ced).

## Tests

`cargo test -p documents -p ced`: the engine's unit and golden verb-fixture
tests, and `tests/window.rs`, which runs the real window against the fake
edit service in-process (no Bus): typing reaches the service, and two
offscreen snapshots. Regenerate them with `UPDATE_SNAPSHOTS=1` and look at
them before committing.

## Not yet

- Macros and the Output panel's content.
- Linting Mix files on save (the Problems panel shows diagnostics other
  tools send with `ced.diagnostics`).
- Paste from the menu asks the platform for the clipboard; the primary
  selection (middle click) is the compositor's, not ced's.

---

<!-- page: https://mixos.dev/citizen/ (source: https://mixos.dev/citizen/README.md) -->

# citizen

An app's supervised native Bus connection, shared by the MixOS apps
(BusViewer, [Prefs](../prefs/README.md)). Headless: no UI dependency.

- `start(app, service, url)`: register as `service` and receive
  `Delivery`s: commands for the app, `Changed` (service registration),
  `Theme`, `Connected` and `Disconnected`.
- `Handle`: `raw`/`call` other services (30 s), or `raw_within` with a
  longer limit for work that legitimately runs long; `reply` once to each
  command; `quit`, which answers every accepted command
  (`BUSY: <app> is closing`) before the connection closes; `wait_done`.
- `probe`/`forward`: single-instance launch through `<app>.ping` and
  `<app>.show`; `noded_url()`: the broker this session uses.
- `show(handle, comp, app_id)`: restore and focus this process's window
  through [compd](../compd/README.md).
- With the `testing` feature: `Handle::sink()`, a handle with no connection
  that logs its calls, replies and quit.

Promoted from BusViewer's engine when Prefs became its second owner (see
[AGENTS.md](https://github.com/markc/mixos/blob/main/AGENTS.md) §2.2). Test
with `cargo test -p citizen`.

The source is [`libs/citizen`](https://github.com/markc/mixos/tree/main/libs/citizen).

---

<!-- page: https://mixos.dev/command/ (source: https://mixos.dev/command/README.md) -->

<!-- SPDX-License-Identifier: MIT OR Apache-2.0 -->

# Command

`command` is the shared, UI-free registry for application engines. It owns
`Command<S>`, `Registry<S>`, `Described`, `Error`, `Scope`, `Origin`,
`Executed`, `Journal` and Fluent `Strings`. Its public contract is 0.3.0.
There are no egui or windowing dependencies.

`Registry::execute(id, state, params, origin)` looks up the command, calls
the optional `authorize` hook, checks enablement, refuses parameters on
nullary commands, then runs the handler and returns its JSON result.
Refusals are `Unknown`, `Denied { id, reason }`, `Disabled { id, reason }`, `BadParams { id, msg }`
or `Failed`. Only successful handlers are journaled. Queries skip the journal;
intent, input and system commands are recorded.

Handlers with parameters declare `ParamSpec { type_name, schema }`, derive
`schemars::JsonSchema` on their serde request struct, and deserialize with
`deny_unknown_fields`, mapping decoding errors to `BadParams`. Schema reporting
does not itself validate a request. Nullary commands accept JSON null or an
empty object; other input is refused. The `nullary!(id, label, handler)` macro
wraps an existing `fn(&mut S)` as an intent returning JSON null.

`describe(state, strings)` keeps id, label, menu, shortcut, more, enabled and
checked. It adds reason (null when enabled), class (`intent`, `query`, `input`,
`system`) and schema (null for nullary commands). Empty `more` is still omitted.
The authorisation hook sees id, origin and params at dispatch; describe reports
state enablement, since it has no caller or parameter body.

Shortcuts and Lucide icon names are strings. Bindings, conflict policy,
overrides, choices, toggles, scopes and changing labels live here. An adapter
supplies chord validation when applying a keymap. `Strings` handles Fluent
catalogues; `Labels` allows an adapter to supply catalogue fallbacks.

[Toolkit](../toolkit/README.md) retains egui shortcut parsing, event handling,
menus and palette rendering. Its existing nullary `Command`, `CommandError`
and three-argument `Registry::execute` remain compatibility wrappers, so
existing application tables need no edits. It re-exports the moved data types.
New engine-owned tables use `toolkit::command::EngineAdapter::new(registry)`:
it caches parsed shortcuts and resolved icons and dispatches typed parameters
through the original registry.

Executed events are **v2**: v, run, seq, at_ms, id, origin, params, result,
then dropped. The accepted params are preserved verbatim, including null;
nullary runs store null params and `note()` stores null for both fields.
The result is the handler's returned value. Each field above 4096 compact
JSON bytes is replaced with `{ bytes, sha256 }`, the byte count and lowercase
SHA-256 of `serde_json::to_vec` output. `executed::bounded` and
`executed::EXECUTED_RESULT_BYTES` expose that policy. `note` and `take_executed`
remain available through toolkit for citizen's publisher, which updates dropped.

`ExecuteRequest { id, params }` is the body type referenced by every
`<app>.execute` row in verb registry schema 4. It derives serde and JsonSchema,
refuses unknown fields, and defaults omitted or null params to None. Existing
apps retain their current parsers during migration.

Authorisation refusal returns Denied before checking enablement, parameters
or running the handler. Toolkit maps it to legacy `CommandError::Denied`.
Both adapters report stored `shortcut` and `more` strings in the keymaps
grammar, in Ctrl, Alt, Shift order. Keys preserve the stored spelling, such as
`ArrowLeft` or `Left`, `=`, `-` and `/`.

The application layering table (`apps/layers.conf.mix`) prevents engine
dependency paths from reaching GUI crates, including through another workspace
library. Unit and integration tests cover dispatch, schema reporting, journals
and the toolkit shortcut behaviour.

## History

`command::History<D>` holds bounded `Arc<D>` snapshots for a cloneable,
comparable document state. `History::new(initial, history::Budget {
max_entries, max_bytes, bytes })` bounds retained undo and redo snapshots;
the current state and saved checkpoint are retained separately. The byte
function measures one snapshot, conservatively counting shared allocations.
Edits clone the current state and commit only on success. Failed edits leave
the state, checkpoint and both stacks untouched. New edits clear redo.

`edit(label, closure)` starts an undo step; consecutive
`edit_coalesced(key, closure)` calls with the same key share a step. An ordinary
edit, undo, redo or `mark_saved()` ends the coalescing group. `current()`,
`can_undo()`, `can_redo()`, `depth()` and `labels()` expose state without mutation.
`mark_saved()` records a checkpoint; `dirty()` compares document values.

---

<!-- page: https://mixos.dev/compd/ (source: https://mixos.dev/compd/README.md) -->

# compd

The MixOS Wayland compositor.

compd owns KMS scanout, the GLES renderer and one shared wgpu device, its
own egui surfaces (capture overlays, notifications, the Mix Scenes shell),
the Xwayland window manager, frame pacing, fractional scale, input devices
and capture. On top of that sits the MixOS policy layer: the agent seat,
the `comp` Bus service (verbs, topics and the props tree), the frame and
presentation ledgers, panel holders and hot corners, and strict idle
discipline (no frames on a static screen).

Bevy, when enabled, may render effects on the shared wgpu device. It never
owns the frame loop, scheduling, compositing or protocol handling.

## Settings at startup

Quoin prepares cached or embedded settings while its existing Bus
supervisor registers. Its persistent cache is service-owned under the
configured variable data directory at `compd/cache/settings`; all
validation and filesystem work runs on the scene host's Bus worker
(`scene-host` `lane`). `shell.props.get` exposes `settings` and
`settings_cache` evidence. A cache persistence receipt must match the
current applied identity before it describes that presentation. Transport
outages and terminal registration refusal preserve usable appearance. Only
explicit initial refusal permits the configured scene service override; an
established shell identity never switches names. Shutdown drains the newest
activated capture and closes the worker under one two-second budget with a
bounded completion margin. Timeouts report failure without claiming
persistence.

The settings come from [settingsd](../settingsd/README.md) through the
[settings](../settings/README.md) library.

## Toast scenes

A scene with `window: {"kind":"toast","w":360,"h":120}` uses a
separate, pointer-interactive toast seat. It never takes keyboard focus,
including on click or with an authored autofocus field. It draws above
windows and edge panels, below the dialog and session lock.

The draft intent verbs are `shell.toast.show {scene, output?, h?}` and
`shell.toast.hide {scene}`. Both reply `{scene, visible, applied:true}`.
Scenes load hidden; show reserves the one toast seat and hide releases it.
A different scene's show returns rc 10 `TOAST_BUSY` with
`holder:{scene, owner}`. Unknown scenes return `NOT_FOUND`, other mount
kinds `NOT_TOAST`, and a nonnumeric height `INVALID_HEIGHT`.

The output defaults to the selected output, as for dialogs. Width clamps
to 240–2048 logical px and height to 60–2048 (defaults 360×120). A show can
override height; showing the same scene again resizes it, and omitting
height preserves its current override. Reload updates the authored geometry
and keeps visibility; changing kind requires an unload first.

Placement is top right, 12 logical px inside the usable area left by
layer-shell exclusive zones and docked scene panels. The drawn size fits
inside that area on small outputs. Chrome defaults to false; `chrome:true`
adds a title frame and a close button that hides the toast.

## Layout

| Path | What |
|---|---|
| `src/` | the `compd` binary: CLI, event loop, Bus and scene wiring |
| `crates/` | compd's private crates (engine, protocols, policy, backends) |
| `layers.conf.mix` | the private crates' dependency order, checked by `tools/layering_gate.mix` |
| `tests/` | integration tests |

The source is
[`services/compd`](https://github.com/markc/mixos/tree/main/services/compd).
The desktop-tier gates that run compd nested or on hardware live in
[`tests/desktop/`](https://github.com/markc/mixos/tree/main/tests/desktop)
at the repository root.

## Build

```
cargo build --profile release-fast -p compd                     # nested backend
cargo build --profile release-fast -p compd --no-default-features \
    --features backend-native                                   # KMS backend
cargo build --profile release-fast -p compd --features backend-all   # all three
cargo build --profile release-fast -p compd --no-default-features \
    --features backend-headless                                 # headless
```

`capture-ffmpeg` adds hardware video capture through libav; the default
build links no FFmpeg.

`desktop-dbus` explicitly enables the optional desktop compatibility
adapters. The default native session has no D-Bus client or portal
dependency. It passes environment directly to children; delegated cgroup
placement before exec and `cgroup.kill` provide complete cleanup when
`MIXOS_CONTAIN_CHILDREN=1`.

## Run

Nested, inside another Wayland session:

```
compd --nested --socket wayland-compd --config-file=settings.json
```

On a VT, through the seat (libseat/seatd):

```
compd kms-live --device /dev/dri/card1 --connector HDMI-A-1 --scale 2.5
```

compd waits for its own VT to become active and never switches VT itself.
`--bus-service NAME` and `--scene-service NAME` override the Bus names
(default `comp`); `compd --help` lists every flag. Settings are read from
`--config-file`, else `~/.config/compd/settings.json`. Preferences are read
from `preferences.json` beside it.

Native fixed-refresh outputs use late-latch composition by default. After a
flip with pending redraws, each CRTC waits until the next kernel-timestamped
vblank minus its render budget. Two 50-commit buckets retain the maximum time
from the armed deadline (or clamped plan instant) to commit return, including
dispatch delay and sibling rendering. Exportable render fences also contribute
their kernel signal timestamp through a non-blocking calloop source. GPU
callback dispatch latency is excluded; unavailable or invalid timestamps leave
GPU tails to the learned floor. Modesets and the first commit and flip after reset do not
train steady-state cost or phase.

Deadline anchoring accepts DRM scanout timestamps up to 2 ms ahead of the
handler's monotonic clock, covering an interrupt delivered during blanking
before active scanout begins. Larger future offsets and dispatch delays over
200 ms are rejected. The tearing phase keeps its existing arrival fallback
for future timestamps.

The budget is the larger of that measured maximum and a learned floor, plus
`late_latch_margin_us` (default 1500). A miss on a deferred frame raises the floor
to the submitted budget minus margin plus one eighth of a refresh, capped at
one refresh interval. The floor shrinks by only 50 µs per 100 target hits;
idle gaps preserve that run. A miss, or unknown feedback on a deferred frame,
breaks the run. The initial estimate is 2 ms. The 1.5 ms margin covers residual jitter
and GPU observation error; hardware timing still needs measurement under load.

Set `late_latch:false` in the settings file to disable it, or set the emergency
environment switch `COMPD_DISABLE_LATE_LATCH` (any value). Both take effect at
startup without rebuilding; the margin uses the same settings file. Schema 7
adds these fields to older files in memory. Startup, the first redraw after
idle, untrustworthy timestamps, over-budget frames, tearing, governed pacing,
active VRR on that CRTC and active capture retain immediate composition.
The VRR preference alone does not disable late latch: unsupported connectors,
refused requests and VRR-off pipes still use fixed-refresh deadlines. The gate
reads cached committed DRM state, independently for each output.
Nested and headless
backends keep their existing pacing. Frame callbacks and presentation feedback
use their existing paths, including empty-frame callback timers.

With `COMPD_FRAME_TRACE=1`, `kms_latch_deferred` and `kms_latch_deadline`
describe the wait and render; other `kms_latch_*` decision stages name the
immediate-path reason. `kms_latch_hit`, `kms_latch_miss` or `kms_latch_unknown`
on completion records the result. These ledger trace events use the same
output ID as `kms_queue_frame`, a target CLOCK_MONOTONIC timestamp in `detail`
(microseconds, zero if unavailable), and the budget in `aux` (microseconds).
The result uses the submitted frame's budget. A hit allows half an interval of
timestamp tolerance; a full missed vblank is a miss. Tracing off performs no
extra ID hashing or trace clock reads.

With the `backend-headless` feature, a render node can drive a virtual
output without a VT, seat, input device or parent compositor:

```
compd --headless --socket wayland-headless --size 1920x1080 --scale 1 \
    --render-node /dev/dri/renderD128 --config-file settings.json
```

The output is `headless-0` at 60 Hz; `--size` sets physical pixels and
`--scale` sets the logical-to-physical scale (defaults 1920x1080 and 1).
`--render-node` defaults to the `render_node` setting. EGL must report the
selected node. The default Bus name is `comp-headless`, overridden with
`--bus-service`; the binding profile is `headless`, without VT or host
interception chords. XWayland is disabled. Startup preserves inherited
scheduling and nice values and does not publish desktop session variables.

Frames repaint into alternating offscreen textures only when the scene
changes or a capture is due, capped at 60 Hz. `COMPD_HEADLESS_REFRESH_HZ`
selects 30–60 Hz (default 60) for both the virtual mode and timer.
Completion is waited on before screencopy, frame callbacks and software
presentation feedback. Both `zwlr_screencopy` and `comp.capture.frame` work
on idle outputs. Captures choose cursor inclusion individually: the normal
frame excludes cursor elements, and a second pass runs only for captures
requesting them. Callback-only commits and unchanged captures do not
increase the window's `presentation.presented` counter.

The ignored `headless` GPU tests need a built `compd` with this feature
beside the test binaries, or selected by `COMPD_TEST_BINARY`. The capture
tests also need built `noded` and `testkit-screenshot` binaries beside them;
they start an owned private broker, without using a running desktop's Bus.
The plain EGL client probe needs `weston-simple-egl` (override its path with
`COMPD_TEST_EGL_CLIENT`); it records the first buffer's actual creation
request and checks captured pixels.

The Phase 5 app test also needs `editd`, the testkit binaries (including
`testkit-ssim`) and `cargo build -p ced --example ced-headless-probe`.
This test-only launcher adds wgpu adapter logging to ced's normal entry point;
production apps and backends keep their behaviour. The test runs ced against
its own Bus and compositor, checks an idle pair at SSIM ≥ 0.99, types through
the agent seat, requires SSIM < 0.999 and reads the exact text through
`ced.state`. PNGs and the client trace remain in `headless-app-artifacts`
beside the built binaries. Supply `COMPD_TEST_APP_REFERENCE=/absolute/ref.png`
to additionally compare the initial headless window with a console reference
at the fixed 0.99 threshold; absence is explicitly reported as unmeasured.

Capture that reference in the console session environment with a running
`editd`, no existing ced window and a scale-1 output:

```text
/opt/mixos/bin/mix services/compd/crates/testkit/scripts/app_reference.mix /tmp/ced-reference.png --comp comp --output OUTPUT
```

The same helper launches the headless test window. It gives ced fresh private
app state, places its geometry at (80,60), waits for 800×560, creates a blank
document and captures its window without the cursor via `comp.capture.frame`.
Its last stdout line is JSON containing the PNG path, requested geometry,
observed window row, scale and capture metadata. It closes its own child after
capture; the GPU test uses `--keep` to take ownership for input checks. Use the
same theme, fonts and application build for both references. Session artefacts
are left beside the PNG in `<path>.session`, which must not already exist.
`testkit-ssim A.png B.png --threshold 0.99` compares the pair; it also accepts
`--crop X,Y,WxH`, or tightly packed raw RGBA with `--size WxH`. Its grayscale
metric uses uniform sliding 8×8 valid windows, population covariance, rounded
Rec.601 luma, K1=0.01, K2=0.03 and L=255; alpha is ignored. It returns 1 below
threshold and 2 for invalid arguments or images, including mismatched sizes.

`compd-headless@.service` runs inside a headless desk with its own noded,
session bus, PipeWire and portald. `%i` is the session slot (for example
`rec`), with settings in `/etc/mixos/session/%i.env` and Bus service `comp`
inside that desk. It uses the render group, no seatd or tty, nice 10 and
`mixos-headless.slice` (`CPUQuota=200%`). Provisioning places the desk's
capture services and encoder in the same slice. Both units are owned by
`services/compd/units/`; they do not create the desk.

`testkit-presentation-probe --rate 60 --hold-s 60` measures independent
commit pacing and presentation misses. Add `--stall-every 30 --stall-ms 50`
for a positive control. Its header documents the pixel frame ID marker;
`services/compd/crates/testkit/scripts/frame_ids.mix FILE.rgba --size WxH`
decodes unscaled raw RGBA client content (PNG is not supported).
Run timing assertions with an optimised compositor, built with
`--profile release-fast` and selected through `COMPD_TEST_BINARY`; the test
harness and probe can remain debug builds. Report the binary profile with
the measured rates and misses. Debug compositor overhead is part of its
measured presentation latency and can dominate a one-interval deadline.

`cursor_sensitivity` in `preferences.json` is a speed multiplier on top of
the output scale: compd multiplies each relative pointer delta by both, so
`1.0` moves the cursor at the same logical speed at every scale. Clients
asking for relative motion get the raw deltas.

## Session activity

`comp.session.get {}` is a draft query returning
`{"version":1,"active":true,"vt":3,"since_ms":1792108800123}`. `active`
describes this compositor's libseat session, including while paused after a
console VT switch. `since_ms` is Unix milliseconds at the last transition,
or at compd's Bus startup before the first transition.

Topic `<service>.session.changed` (normally `comp.session.changed`) publishes
`{"version":1,"active":false,"vt":3,"since_ms":1792108800456,"event_seq":42}`
once at startup and once on each pause or resume. It uses the shared
observation sequence, outbox and gap reporting. The publisher runs on its
own Bus worker, so pause events do not wait for rendering or resumption.
Subscribe before querying to establish the current state without polling;
on an observation gap, query again. Across desks, the most recent
`active:true` transition identifies the desk the human is viewing.

The session unit supplies `MIXOS_VT=%i`. compd reads it once when starting
its Bus service; `vt` is a u32 or `null` when the variable is absent or
cannot be parsed. A nested compositor with no supplied VT reports `null`.
The VT is never inferred from a runtime path or display name.

## Workspaces

Every output has a current workspace; windows belong to one. Verbs on the
`comp` service:

| Verb | Arguments | Reply |
|---|---|---|
| `comp.workspaces.list` | none | `{count, current, o_<key>: {current}, list: [{index, windows, name}]}`, the same object as `comp.props.get {path: "workspaces"}`; `name` is null when unnamed |
| `comp.workspace.switch` | `{index, output?, wrap?}` | `{output, from, to}` |
| `comp.window.send_to_workspace` | `{id, generation, index, follow?}` | the window |
| `comp.workspaces.set_count` | `{count: 1..=16, persist?}` | `{from, count, persisted?, persist_error?}` |
| `comp.workspace.rename` | `{index, name, persist?}` | `{index, name, previous, persisted?}` |

`index` is 1-based; switch and send also take `"next"` and `"prev"`.
Shrinking the count moves every window above it to the last workspace and
drops the removed workspaces' names. A name is trimmed, at most 64
characters, with no control characters; `""` clears it. `persist` defaults
to true: the count and the names are written to `preferences.json`
(`workspaces_count`, `workspace_names`) and compd starts with them. If the
file cannot be written, the change still applies and the reply has
`persisted: false` and `persist_error`. A session lock refuses every
workspace change and hides the names (and window counts) from readers.

Topic `comp.workspace.changed` (`<service>.workspace.changed`) carries
`{version: 1, count, current, outputs: {o_<key>: current}, names, event_seq}`
whenever the count, a current workspace or a name changes. `names` has one
entry per workspace, null when unnamed. Window counts are not in it;
`comp.props.changed` on `workspaces.list` carries them. The two topics are
sequenced separately, so a subscriber may see one before the other.

## Test

```
cargo test --workspace
mix tests/desktop/nested_smoke.mix --help
mix tests/desktop/parity_suite.mix --help
```

---

<!-- page: https://mixos.dev/config/ (source: https://mixos.dev/config/README.md) -->

# config

Where MixOS keeps its files, and how a `*.conf.mix` file is read.

- `config::path(Dir::Etc | Var | Run | Share)`: one rule for every
  directory. A `MIXOS_ETC` / `MIXOS_VAR` / `MIXOS_RUN` / `MIXOS_SHARE`
  override wins; else `$MIXOS/etc`, `/var`, `/run` when a root is set; else
  the XDG directory for a user (`~/.config/mixos`, `~/.local/share/mixos`,
  `$XDG_RUNTIME_DIR/mixos`) or the system directory for root (`/etc/mixos`,
  `/var/lib/mixos`, `/run/mixos`). `Share` is installed read-only data at
  `/opt/mixos/share` whatever the root or user. Resolved once per process
  and cached; `Dirs::resolve(&Environment)` applies the rule to explicit
  inputs for tests.
- `config::parse` / `config::parse_file` and `Value`, `Map`, `Error`,
  `ErrorKind`: the [strict](../strict/README.md) crate's strict-data
  loader, re-exported so a config reader needs one dependency. Typed
  loading is `strict::from_file`.

No dependency on the Mix language. Test with `cargo test -p config`.

## Node configuration and TLS

`node::NodeConfig` reads `node.conf.mix`, selected by `MIXOS_NODE_CONFIG`
or the native `Dir::Etc` search paths. The optional `maild` section contains
typed ports, hostname, storage paths, spam settings, the legacy `tls_cert` /
`tls_key` pair and `tls: { identity: [...], strict_sni: false }`. Mail state
defaults to `path(Dir::Var)/maild/{mail.db,blobs,mds}`. Unknown service and
mail settings survive typed round trips.

Optional `jmap_listen`, `jmap_upstream`, `smtp_inbound_listen` and
`smtps_listen` fields override the corresponding address helpers. Otherwise
the helpers use the node IP and mail ports (8443, 25 and 465 by default).
`jmap_upstream()` uses HTTPS. Missing mail settings remain valid.

`node::{TlsConfig,TlsIdentityConfig}` are always available. Each identity
requires `server_name`, `cert` and `key`; its independent `default` and
`no_sni_fallback` flags default to false. Enable the optional `tls` feature
for `load_tls_config(cert_path, key_path)` and
`tls::sni::{SniCertResolver,TlsIdentity,pick_identity}`. The resolver loads
PEM pairs and matches names case-insensitively. Unknown SNI uses the default;
absent SNI prefers the no-SNI identity then the default. If neither flag is
set anywhere, the first identity fills both roles. Strict SNI rejects unknown
names and clients which omit SNI. `default_identity()` remains available for
pre-TLS greetings, including in strict mode.

`from_conf_mix_str` and `load_conf_mix_path` return `config::Error` (the
strict loader error); node search/load functions retain `anyhow::Result`.
Verify TLS with `cargo test -p config --features tls`.

The source is [`libs/config`](https://github.com/markc/mixos/tree/main/libs/config).

## Application directories

`AppDirs` shares the existing Ced/Dopus per-application root, config, state
and cache rules. First absolute root wins: `MIXOS_APP_HOME`, then
`MIXOS_APPS_HOME/<component>`, `MIXOS_VAR/apps/<component>` (or
`MIXOS/var/apps/<component>`), `XDG_STATE_HOME/mixos/apps/<component>`,
then `HOME/.local/state/mixos/apps/<component>`. An invalid component or
absent absolute root returns `None`. Resolution performs no I/O. App-owned
filenames stay in their owners; this promotion preserves existing paths and
lets other native settings consumers use the same isolated cache policy.
`resolve_with` injects inputs for tests without mutating process
environment.

## Atomic directories

`atomic::open_directory` refuses symlinks in every component.
`atomic::create_directory` uses the same held-descriptor walk and provisions
missing components with mode 0700. It validates the entire absolute path
before creation, refuses parent traversal and leaves existing permissions
unchanged.

## Web configuration and ACME policy

`node::WebdConfig` adds the web listener, vhost, share roots, auxiliary
DB and ACME settings to `NodeConfig`. `web_listen()` derives the legacy
listen address; `synthesize_listeners()` validates explicit binds and
host ownership, retaining the fail-soft disabled-host path. Unknown web
settings survive typed node round trips.

`resolve_webd_acme()` checks per-vhost issuance choices, HTTP-01 readiness
and the node-level Let's Encrypt production Subscriber Agreement. Only
the policy resolver can mint an `AcmeTosAcceptance` proof.

Node loading, directory resolution and TLS/SNI use the existing config
implementations. Client discovery and connect helpers already live in
`bus::client_helpers`; config remains independent of the Bus client.

---

<!-- page: https://mixos.dev/daemon/ (source: https://mixos.dev/daemon/README.md) -->

# daemon

Protocol-independent daemon infrastructure. `http_host` parses and normalises
request hosts. `listen` owns explicit interface binds, connection tagging,
ACL/rate/concurrency guards and live enable/disable controls.

Enable `tls` for SNI certificate snapshots, LE production/staging chain
validation, HTTP-01 ACME account/order handling and internal self-signed
certificate generation. SNI selection and the PEM loader are re-exported
from config, preserving one implementation.

The four staging trust anchors retain their original DER bytes and source
references in `tls/le_staging_roots.rs`. They are used only for staging.

Test with `cargo test --locked -p daemon --features tls` and
`cargo test --locked -p daemon --no-default-features`. No issuance request
or deployed listener is needed for the test suite.

Source: [libs/daemon](https://github.com/markc/mixos/tree/main/libs/daemon).

---

<!-- page: https://mixos.dev/davproto/ (source: https://mixos.dev/davproto/README.md) -->

# davproto

CalDAV and CardDAV codecs: the wire-format side of a DAV server or client,
with no transport and no storage.

- `ical`: JSCalendar (RFC 8984) to iCalendar VEVENT (RFC 5545), and the
  reverse mapping for a DAV PUT. A verbatim iCalendar body is kept under a
  data key so a GET returns it unchanged.
- `vcard`: JSContact (RFC 9553) to vCard 4.0 (RFC 6350), with the same
  verbatim round-trip.
- `etag`: strong ETags, a BLAKE3 hash of the content, so an ETag changes
  exactly when the content does.

The crate is a pure library. It does not open sockets, read files or touch
a database. Callers (maild's DAV server, a future DAV client) own those.

The source is [`libs/davproto`](https://github.com/markc/mixos/tree/main/libs/davproto).

## Test

Run the unit tests on a build worker, not locally:

    cargo test -p davproto --locked
    cargo clippy -p davproto --all-targets --locked -- -D warnings
    cargo fmt -p davproto -- --check

---

<!-- page: https://mixos.dev/design/ (source: https://mixos.dev/design/README.md) -->

# design

The MixOS design-token system. A design source is a strict-data document
(`theme.conf.mix`) holding OKLCH colour primitives, metrics, type scales,
semantic text pairs and the button family's mapping rules, plus modifier
blocks per scheme and mode. Breeze and Adwaita each provide light and dark
chrome palettes and a Studio-based style; scheme and style remain independent.
The append-only compatibility table supplies both palettes, styles and terminal
defaults to older sources with `defaulted-scheme` provenance. An authored
scheme binding retains its source colours. A scheme modifier without that
binding is incomplete: the whole compatibility scheme supplies its colours
and semantic pairs. Authors defining their own new scheme provide both its
palette and its style binding. Missing bindings for the original
nine schemes remain errors.

Breeze keeps its surface colours, blue accent and selection opacity. Six
foreground/action values are adjusted to meet the contrast requirement after
egui's rounded, premultiplied sRGB blending. Text is checked on all seven
resting, hovered and pressed surfaces, including their accent-soft tints.
Primary-button ink is checked at 100%, 93% and 85% opacity on all five
resting surfaces. The minimum rendered ratios are:

| mode / role | reference | shipped | minimum contrast |
|---|---|---|---|
| light / `text_faint` | `#515A64` | `#4D5660` | 4.558:1 on tinted pressed |
| light / `accent_text` | `#1E5E88` | `#1A5A84` | 4.520:1 on tinted pressed |
| light / `primary_bg` | `#237AB4` | `#0F66A0` | 4.536:1 at 85% on field |
| dark / `text_faint` | `#A4AAB1` | `#B8BEC5` | 4.504:1 on tinted pressed |
| dark / `accent_text` | `#50B8EE` | `#61C9FF` | 4.543:1 on tinted pressed |
| dark / `danger` | `#E36F7B` | `#EB7783` | 3.013:1 on tinted pressed (3:1 floor) |

The reference inputs measured 4.283:1 and 4.261:1 for light faint/accent text on tinted pressed,
3.601:1 and 3.789:1 for dark faint/accent text there, and 3.813:1 for the
light primary button at 85% on chrome. Dark danger measured 2.742:1 on tinted
pressed, below its 3:1 interactive-surface floor. These adjustments preserve
the contrast requirements rather than importing those failures.

The compiler flattens it for one
`DesignContext` (scheme, mode, contrast, optional app) into a resolved
design: gamut-mapped colours with WCAG contrast checked, resolved metrics
and typography, and a total button table keyed by variant, size,
interaction and focus. Every failure is a stable, source-addressed
diagnostic.

The crate is headless and has no renderer dependency. Its only
dependencies are [strict](../strict/README.md) (the source format) and
`serde`.

- `parse_design_source` / `parse_legacy_v0_source` read a source; the
  embedded default is `EMBEDDED_DEFAULT_SOURCE`.
- `compile_design` produces a `DesignCompileResult`; `apply_compiled_design`
  stamps a revision onto an accepted candidate.
- `Scheme`, `Mode`, `Contrast` are the closed selection axes;
  `active_typography` reads a typography role with embedded defaults.
- The default selection, used when nothing chooses a theme, is studio,
  dark. `DesignContext::revision_one()` is revision one's ocean, light,
  which the v0 equivalence gate and the revision-one parity tests pin.

Build and test with `cargo test -p design`.

The source is [`libs/design`](https://github.com/markc/mixos/tree/main/libs/design).

---

<!-- page: https://mixos.dev/dnsd/ (source: https://mixos.dev/dnsd/README.md) -->

# dnsd — authoritative mesh DNS

`dnsd` answers authoritative DNS queries over UDP and TCP for the zones in
an explicit strict-data `zones.mix` file. It refuses names outside its
authority and does not recurse. The private `dns-core` crate owns the zone
model, parsing, snapshots, persistence, resolver and wire codec.

```text
/opt/mixos/bin/dnsd --zones /opt/mixos/etc/dnsd/zones.mix --state /var/lib/mixos/dnsd/state --listen 127.0.0.1:5353
```

All three arguments are required. Repeat `--listen` to bind more than one
address. Wildcard binds are refused. The default `mixos` feature reads
`node.conf.mix` using `config` (including `MIXOS_ETC` and
`MIXOS_NODE_CONFIG`) and accepts the configured WireGuard IP or loopback.
If node configuration is absent or invalid, non-loopback binds require
`--allow-non-loopback-listen`, with a warning. The standalone build
(`--no-default-features`) always uses this explicit-flag posture.
The citizen retries unavailable bind addresses for up to 30 seconds.

The example zone schema is in
`services/dnsd/tests/fixtures/zones.mix`. Operators supply their own zones;
the fixture is test data. `SIGHUP` reloads the file, preserving the last
good snapshot on failure. Persisted serial floors retain their existing
v1 format, so a binary rollback can read state written by this port.

The `dnsd` Bus service exposes two read-only queries:

| Verb | Reply |
|---|---|
| `dnsd.zone.snapshot` | Serial-excluded configuration hash (decimal string), sorted zone names and count |
| `dnsd.stats` | Response counters by DNS rcode |

DNS serving continues while the broker is unavailable. Registration
retries with bounded exponential backoff. Mutation verbs are rejected.

`services/dnsd/units/dnsd.service` runs `/opt/mixos/bin/dnsd` as `dnsd`,
with UID and GID 506, `CAP_NET_BIND_SERVICE` and the original hardening.
Its config root is `MIXOS_ETC=/opt/mixos/etc`, with `dnsd/zones.mix` and
`dnsd/service.env` (`LISTEN=192.0.2.10:53`). Its state root is
`MIXOS_VAR=/var/lib/mixos`, with `dnsd/state`. The unit sets those roots
explicitly; changing the roots also requires overriding its argument and
environment-file paths. Node identity comes from
`/opt/mixos/etc/node.conf.mix`. The sysusers and tmpfiles fragments are
owned by the component. Installing these files does not activate DNS.

```text
cargo test --locked -p dnsd
cargo test --locked -p dns-core
cargo test --locked -p dnsd --no-default-features
cargo build --release --locked -p dnsd
```

Run Rust commands on the configured build worker. The integration prober
starts a temporary loopback daemon, drives real UDP and TCP queries and
retains the source load guard for timing assertions. `--version --json`
reports the package, version, build commit and timestamp.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-07-settings-authority/ (source: https://mixos.dev/docs/decisions/2026-10-07-settings-authority.md) -->

# Desktop settings have one native ABP authority

Status: accepted architecture, implementation staged. Contract version 0.1.0.

Desktop appearance and layout belong to a headless `settingsd` authority. Settings
controls, Mix operators and agents submit validated batches through native ABP.
Applications and compd/Quoin consume complete accepted snapshots through shared
headless `settings` contracts and one theme adapter per UI layer. Closing a
Settings page does not stop delivery. Other services retain their own hardware
and operational settings; discovery does not create a distributed transaction.

The shared library has multiple external owners from its first commit:
settingsd, applications and compd. The plain component names `settings` and
`settingsd` describe their public contracts. Config remains independent of Bus;
the UI toolkit layer remains independent of settings transport. No COSMIC implementation
or GPL/MPL code is incorporated.

Settings behaviour has one shared implementation per concern: `settings`
consumer ordering/recovery and render-domain comparison; one theme adapter
projecting settings onto the UI toolkit; shared reusable controls and
role/default builders; and one shared event-loop activation/invalidation path.
Applications retain their service lifetime, content and deliberate overrides.
Compd owns output geometry, work areas, Wayland configuration and presentation.
Standard widgets inherit current defaults without copied app palettes, font
captures or settings handlers. Extract repeated components during migrations;
keep headless crates independent of renderers and the UI layer independent of Bus.

Each profile has one exclusive writer. Authored settings, revision and bounded
operation receipts share a durable strict-data replacement. A no-op persists a
receipt without changing semantic revision. The durable store incarnation fences
restores; broker sequence is delivery order, not settings revision. Caller access
remains open across the trusted mesh. Correct target/revision binding and
canonical publisher ownership do not require the operator to own the session.

Native calls/events use existing ABP/noded, preserving frozen framing and
identity constants. External toolkit D-Bus adapters are later compatibility
boundaries inside the independent MixOS session. Retained broker snapshots are
presentation/recovery aids, not a durable offline store. Recovery is driven by
lifecycle/connection/loss events, without an idle settings polling loop.

Consumer application and frame presentation are separate evidence. Compositor
geometry/input updates remain coherent while Wayland configure/ack/buffer changes
complete asynchronously. No global same-vblank guarantee is made.

The authority/store and shared consumer primitives are implemented; consumers
adopt them as they enter this tree. Full widget geometry/resources, panel reconfiguration, native
frame/first-map acceptance, named profiles, previews, replication and compatibility
remain in development. This decision establishes ownership; individual fixtures
do not close full desktop acceptance. See the [initial contract](../spec/settings/README.md).

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-08-mix-programs-and-documents/ (source: https://mixos.dev/docs/decisions/2026-10-08-mix-programs-and-documents.md) -->

# Decision — `.mix` programs and `.mx` documents

Status: accepted 2026-10-08. Target of the **next major Mix binary refactor and
deployment**; implementation and filename migration are pending. The release
number is assigned during implementation, not inferred from this decision.

## The decision

| Family | Canonical extension | Meaning |
| --- | --- | --- |
| Mix program | `.mix` | Executable Mix with its ordinary language capabilities and caller authority |
| Mix document | `.mx` | Strict declarative data consumed and validated by a defined reader/schema |

Macros, scene behaviours, services, installers, tests and modules are roles of
ordinary Mix programs. They introduce no separate grammar or extension. Themes,
configuration, specifications, manifests, catalogues and scenes are document
purposes. Different schemas do not make different script languages.

An `.mx` document cannot contain general executable Mix. A schema may allow
the existing restricted, side-effect-free expression subset in precisely defined
fields. Scene bindings remain permitted under their current limits; function
calls, assignment, process/file effects and Bus operations remain refused.

The first migration preserves existing strict-data and scene-envelope syntax.
This decision unifies file families and execution rules, not every document's
grammar. Changing the scene envelope later is a separate schema migration, not
a prerequisite or excuse to add another parser now.

## Enforcement and evolution

1. Ordinary program execution and executable file/module loading refuse `.mx`,
   including serve/reload paths. A malformed document never falls back to the
   full interpreter or shell. Extension checks complement strict parsing; they
   are not a malware detector or sandbox for intentionally run programs.
2. Generic documents use strict parsing. App-owned documents also validate their
   schema, supplied by the owning reader and/or declared in the document. A
   schema can be a Rust type/validator; it need not be another file.
3. Data strings stay literal except at schema-declared restricted binding fields.
   A document describing commands does not gain execution authority by being
   data; running those actions is an executable program responsibility.
4. New purposes use existing Mix programs or versioned document schemas. A new
   family, suffix or evaluation mode requires an accepted decision explaining
   why existing facilities fail, authority/resource limits, negative tests and
   compatibility. There is no macro or workflow dialect to introduce.
5. Legacy `.conf.mix`, `.spec.mix`, `.data.mix`, `scene.mix` and other inventoried
   data names remain readable during a measured migration. They are transitional
   spellings, not additional permanent families. Accepting this decision does
   not make current binaries recognise or enforce the new extension.
6. Install upgraded readers before switching files/writers. Preserve user data,
   expose conflicts between old/new files, and retain a tested binary-plus-data
   rollback. Frozen MixOS deployments are not silently upgraded or renamed.
   No frozen ABP bytes or cross-node transport contracts change.

Canonical examples are `behaviour.mix`, `report_selection.mix`, `settings.mx`,
`scene.mx` and `authority.mx`. Keep script homes from the macro decision:
app-local `config/macros/` and global `/opt/mixos/mix` hold executable macros;
documents remain in their owning component/app directories.

The [file-family contract](../spec/mix/2026-10-08-programs-and-documents.md)
specifies boundaries and acceptance. The [Mix guide](../../mix/README.md) distinguishes
current behaviour from the target. This decision updates the source-layout
file conventions and the macro contract's planned data-fixture spelling while
preserving their existing compatibility obligations.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-09-chrome-family-and-schemes/ (source: https://mixos.dev/docs/decisions/2026-10-09-chrome-family-and-schemes.md) -->

# Decision — the chrome family and chrome schemes

Status: accepted 2026-10-09.

## The decision

- **A typed `chrome` family in the design.** Application chrome (title bars,
  menus, tabs, panels and controls) is described by one closed set of colour
  roles, such as `chrome`, `card`, `field`, `hover`, `text_dim`, `accent` and
  `caption_close`. Each role names a colour primitive.
- **Chrome colours are exact.** No contrast adjustment, recipe or derivation
  applies to a chrome role: it renders exactly as authored. Colours are
  written as OKLCH at nine decimals, which round-trips every 8-bit sRGB value
  (the design crate tests the full cube).
- **Coverage is explicit.** A design that authors the chrome family must
  author every role, and an unknown role or primitive is a compile error.
- **Three chrome schemes**, `pro`, `studio` and `classic`, join the six hue
  schemes. Their light and dark modes step the interface brightness:

  | scheme | dark | light |
  |---|---|---|
  | `pro` | Pro | Pro Medium Gray |
  | `studio` | Studio | Studio Light |
  | `classic` | Classic | Classic |

- **Semantic pairs keep their guarantees.** In the chrome schemes the semantic
  pairs (`base`, `card`, `popover` and the rest) take the neutral `mono`
  palette for the mode, so every contrast rule still holds for components that
  read pairs. The egui toolkit draws the chrome schemes from the chrome family.

## Why

A desktop whose applications sit side by side should look like one desktop,
down to the pixel. Exact chrome roles make that a matter of values, not
adjustments, while the semantic pairs keep their accessibility guarantees.

## Consequences

- `Scheme::is_chrome_scheme()` tells consumers which styling path applies.
- Tests that pinned the six revision-one schemes iterate `Scheme::REVISION_ONE`;
  the chrome schemes carry their own exact-value tests.
- Components that read semantic pairs, such as the compositor's own panels,
  move to the chrome family over time.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-09-icons-and-type/ (source: https://mixos.dev/docs/decisions/2026-10-09-icons-and-type.md) -->

# Decision — icons and type

Status: accepted 2026-10-09.

## The decision

- **Icons are Lucide.** Every icon in MixOS applications and the desktop
  comes from the [Lucide](https://lucide.dev) set: 24 px grid, round caps and
  joins, a single stroke colour. Icons are taken unmodified from a pinned
  upstream release and ship with Lucide's licence (ISC, with MIT for the
  icons derived from Feather) and a `NOTICE` line. A component ships only the
  icons it uses.
- **Type is Inter and JetBrains Mono.** Interface text is Inter; numbers,
  code and JSON are JetBrains Mono. Both are SIL OFL 1.1 and ship as
  unmodified static faces from their upstream releases.
- **The shipped desktop sizes** are Inter Regular at 12.5 px for body text,
  10.5 px for small text, Inter SemiBold at 15 px for headings, Inter Medium
  for emphasis, and JetBrains Mono at 12 px.
- **Weight is a design token.** Each typography role names a weight, and the
  renderer selects the static face of that weight (300 Light, 400 Regular,
  500 Medium, 600 SemiBold). A light profile, with body text at 300, is a
  change to the design's weights and nothing else.
- **Icon stroke is a design token.** The design metric `icon.stroke_width`
  sets the stroke every icon is drawn with (default 1.5, the approved
  baseline; a session choice may override it, see
  [session icon stroke and type](2026-10-14-session-icon-stroke-and-type.md)), so a
  lighter icon set accompanies a lighter type profile without new assets.
- **Colour comes from the theme.** Icons take the colour of the text around
  them; no icon carries a colour of its own.

## Why

One icon family and one type family give every MixOS application, and the
external applications that run alongside them, the same look. Making weight
and stroke tokens keeps the visual weight of the whole desktop adjustable in
one place.

## Consequences

- `libs/toolkit` embeds the faces and icons and applies them from the theme.
- A new icon is added by copying its SVG from the pinned Lucide release into
  the component that uses it and listing it there.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-10-mix-components/ (source: https://mixos.dev/docs/decisions/2026-10-10-mix-components.md) -->

# Decision — Mix components

Status: accepted 2026-10-10. Amends [the source layout](2026-10-04-source-layout.md)
(AGENTS.md §2 and §10).

## The decision

- **A component may be written entirely in Mix.** It lives where its kind
  says (`services/<role>d/`, `apps/<name>/`, `cli/<name>/`, `libs/<name>/`)
  and follows every naming rule. It has no Cargo package.
- **Its identity is `component.mx`** at the top of the component, a
  strict-data document (schema 1) with the fields a Cargo package carries
  in `[package.metadata.mixos]`, plus the name, version and principal
  program:

  ```text
  {
    schema: 1,
    name: "releasesd",          -- = directory = component
    component: "releasesd",
    kind: "service",            -- matches the kind directory
    layer: "desktop",           -- bus | mix | core | desktop
    contract: "public",         -- none | public
    version: "0.1.0",           -- the component's own MAJOR.MINOR.PATCH
    program: "scripts/releasesd.mix"
  }
  ```

- **A component is one or the other.** A directory with both `Cargo.toml`
  and `component.mx` is refused.
- **Layout inside the component:**
  - programs in `scripts/`, modules they `require` in `scripts/lib/`;
  - units in `units/`, calling `/opt/mixos/bin/mix` by absolute path;
  - tests in `tests/*_test.mix`.
- **Install location:** a Mix component's `scripts/` tree installs to
  `/opt/mixos/lib/<component>/`, read-only like the binaries in
  `/opt/mixos/bin`. `/opt/mixos/share` stays for data.
- **Shared Mix test helpers** live in `tests/lib/`. The first is
  `private_bus.mix`, which starts a throwaway, owned noded broker for Bus
  tests of serve citizens.
- **Gates.** `tools/component_index.mix` reads both identity sources,
  applies the same identity, layer and contract rules to each, and checks
  that `program` names a `.mix` file inside the component. Names are unique
  across both kinds. A Mix component has no Cargo dependency closure, so its
  declared layer is checked at review: it may use only the `mix` binary, the
  Bus and the verbs of components at or below its layer.
- **Versions and contracts.** A Mix component carries its own version, since
  there is no workspace package to inherit one from. With
  `contract: "public"`, its Bus verbs and document schemas are registered
  like any other (`docs/docs/spec/bus/verbs.conf.mix`, `docs/docs/spec/<topic>/`).

## Why

Mix is the system's own language. A service that is mostly glue (talking
HTTP, checking hashes, moving files, answering the Bus) is shorter, clearer
and easier for an agent to change in Mix than in Rust, and Mix already has
the primitives. Until now every component had to be a Cargo package, so such
a service had a choice of being rewritten in Rust to fit the layout, or
hidden in another component's `scripts/`, where it has no owner, no index
entry and no gate. Neither is honest.

`component.mx` keeps the one rule that matters (directory = component =
name, with a declared kind, layer and contract), so the component index stays
the agent's single map of the tree.

## Consequences

- The first Mix component is `services/releasesd` (upstream application
  releases).
- The generic line-JSON bridge for external applications (AGENTS.md §4.1)
  will land the same way.
- `tools/component_install.mix` installs Mix components: `scripts/` to
  `/opt/mixos/lib/<component>/` and `units/` to `/etc/systemd/system`. It
  writes an install record, keeps one previous tree for rollback and has a
  `--check` for drift. `--root` targets an image or container tree. Units of
  Rust components still wait for the unit collector.
- Rejected: a separate top-level directory for Mix programs. It would
  classify by language, not by kind of artefact.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-10-scheme-and-style-axes/ (source: https://mixos.dev/docs/decisions/2026-10-10-scheme-and-style-axes.md) -->

# Decision — scheme and style are separate axes

Status: accepted 2026-10-10.

## The decision

- **Scheme and style are separate choices.** The scheme picks the colours:
  one of the nine palettes. The style picks the chrome's forms and lengths:
  `plain`, `pro`, `studio` or `classic`. A theme context has a scheme, a
  style, a mode and a contrast. A style of "none" means the scheme's own
  style, which keeps every existing selection exactly as it was.
- **Any palette takes any style.** A chrome style draws from the chrome
  colour roles. The `pro`, `studio` and `classic` palettes author those
  roles. Every other palette derives them from its semantic pairs, through
  a typed and documented mapping in the design (`families.chrome.derive`).
  For example, the bar is the `base` surface, cards the `secondary`
  surface, and selections and the menu highlight the `accent` pair. A
  colour a palette does author always wins over the derivation. In the
  other direction, the plain style draws any palette through its semantic
  pairs, which every palette has.
- **The contrast rules still hold.** The pairs keep their WCAG checks.
  Derived text roles sit on surfaces of the same pair, or close to them,
  and the design tests that text on derived chrome meets AA (4.5:1) in
  every hue palette, mode and contrast. The authored chrome palettes stay
  exact, as before.
- **Light or dark base comes from the palette.** Whether the chrome sits
  on a light or a dark base is read from the lightness of its own `chrome`
  colour, not from the style. A light palette in a style first designed
  for a dark one is still drawn light.
- **Decorations and caption side sit beside the axes.** They change no
  colour or length, so they are not part of the design context:
  - `csd`: the application draws its own title bar, as before;
  - `ssd`: the compositor decorates the window, and the application shows
    its menus and right-hand controls in a menu-bar row;
  - caption side `right` (the default) or `left`. On the left the order is
    Close, Minimize, Maximize, with Close in the corner, and the menus
    follow the captions.
- **Every surface takes the axes.** Settings has `appearance.style`,
  `appearance.decorations` and `appearance.caption_side`. The shared theme
  file has `style:`, `decorations:` and `caption_side:`. Each application's
  View → Theme menu has a Style group and a Decorations group. An app's own
  choice persists, and older saved state loads with the defaults.

## Why

Palette and style answer different questions. Tying them together meant a
colour preference forced a layout, and a layout preference forced colours.
As separate axes, each new palette works in every style and each new style
works with every palette.

## Consequences

- Every scheme, style, mode and contrast combination compiles; the design
  tests compile them all.
- A new palette needs no chrome colours to work in a chrome style. It can
  still author any of them where the derived colour is not the one wanted.
- The style family's binding from each scheme to its own style remains.
  It is what "the scheme's own style" resolves to.
- The style family no longer carries a base token. The light or dark base
  is the palette's, as described above.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-10-style-tokens-as-data/ (source: https://mixos.dev/docs/decisions/2026-10-10-style-tokens-as-data.md) -->

# Decision — style tokens as data

Status: accepted 2026-10-10.

## The decision

- **A typed `style` family in the design.** The chrome family says which
  colours the chrome is. The style family says which forms it takes and
  how big they are. Every choice a renderer used to make by asking which
  scheme it was drawing is now one token:
  - forms, such as a tab strip or cards for panel groups, a checkbox or a
    switch for on/off controls, bevels or outlines, a ringed, plain or block
    slider knob, and pill or rounded push buttons;
  - lengths, such as the title-bar height, the menu row padding, the bar
    and dock sizes, the push-button height and the corner radii;
  - the renderer base: pair-based or chrome widgets, and a light, dark or
    mode-following base palette.
- **Tokens are typed and closed.** Each token is a named choice, a flag or a
  number with a declared range. Every style must author every token. A
  missing, unknown or ill-typed token is a compile error, as is a scheme with
  no style or one bound to a style that does not exist.
- **Styles are named and bound per scheme.** `styles` holds named token
  sets, and `schemes` gives every scheme exactly one of them. The shipped
  design has four styles: `pro`, `studio` and `classic` for the chrome
  schemes, and `plain` for the six hue schemes. `plain` writes down, as data,
  the geometry those schemes used to derive from their pair-based style. A
  style does not vary by mode or contrast, and modifier blocks cannot alter
  it.
- **Renderers read the resolved style, never the scheme.** The egui toolkit
  builds its chrome from the compiled style. No component branches on a
  scheme any more. A design that authors no style family takes the embedded
  design's style for its scheme.

## Why

The chrome styles should be values a designer can edit and compare, not
branches a programmer has to find. With the style family, a new style is a
new token set in the design, with no renderer change. Moving every decision
across changed no pixel: the toolkit's and the applications' snapshots
render the same images before and after.

## Consequences

- This lays the ground for a separate style axis, where any palette can be
  combined with any style. Today the binding from scheme to style is fixed
  in the design; a later decision can make the style its own selection.
- `Scheme::is_chrome_scheme()` now only groups schemes, for example in theme
  menus. The style's `widgets` token decides which styling path applies.
- A form the token set cannot express yet, such as a new tab shape, still
  needs code once: a new choice for the token and the code that draws it.
  After that, any style can select it.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-11-compd-module-layout/ (source: https://mixos.dev/docs/decisions/2026-10-11-compd-module-layout.md) -->

# Decision — compd's module layout on entry

Status: accepted 2026-10-11. Amends [the source layout](2026-10-04-source-layout.md)
(AGENTS.md §4, Rust modules).

## Context

AGENTS.md §4 forbids new `mod.rs` and `foo/foo.rs` files and says code
transplanted from elsewhere is renamed on entry. The compositor's crates
arrive written in an older layout: about 570 `mod.rs` files and about 270
self-named module files (`foo/foo.rs`, each the file of a module `foo::foo`).

## The decision

- **Every `dir/mod.rs` becomes `dir.rs` on entry.** Rust resolves `dir.rs`
  with its children in `dir/`, so the rename changes no module path. An
  explicit `#[path]` resolves against the directory of the file that holds
  it, so each one in a renamed file is rewritten (for example
  `#[path = "encode/dialog_unavailable.rs"]` in `graphics`).
- **Self-named module files stay, as a standing exception.** Each is the
  canonical file of a module `foo::foo`; removing it renames the module at
  every caller, which is churn a transplant should not carry. No lint can
  gate them either way (`clippy::self_named_module_files` enforces the
  opposite, `mod.rs` style).
- **The exception shrinks and ends.** It covers only the compd crates, and
  each crate leaves it when it is next substantially edited: its self-named
  modules are dissolved into their parents in a change of their own. No new
  self-named module file is added to any crate.
- **No `mod.rs` can come back.** Every compd crate carries
  `[lints.clippy] mod_module_files = "deny"`, as the rest of the workspace
  does, and clippy runs as a gate.

## Consequences

- The transplant stays a near-zero semantic change, so its tests prove the
  same behaviour they proved before.
- Readers of compd will meet `foo::foo` paths for a while.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-11-executed-commands/ (source: https://mixos.dev/docs/decisions/2026-10-11-executed-commands.md) -->

# Decision — executed commands are published

Status: accepted 2026-10-11. Amends [egui applications](2026-10-09-egui-applications.md)
(AGENTS.md §4.1).

## The decision

Amended 2026-10-20 by [commands take parameters and return results](2026-10-20-commands-take-parameters.md). The body is v2; v1 events are no longer emitted.

- **Every application publishes each command it runs.**
  - The topic is `<app>.command.executed`, where `<app>` is the
    application's Bus service name.
  - An event means the command registry accepted the invocation and the
    command's handler returned.
  - A command that is unknown or disabled is refused, and nothing is
    published.
  - The event does not report the outcome of work the handler queued, such
    as a save that later fails. Outcomes travel by the application's own
    verbs and topics.
- **The body:**

  ```text
  {
    v: 2,
    run: "5f0c…",           -- this process: a UUID drawn once at start
    seq: 812,                -- per run, from 1, assigned in execution order
    at_ms: 1760160000123,    -- integer ms since the Unix epoch, at handler return
    id: "file.open",         -- the command's stable id
    origin: "menu",          -- menu | shortcut | palette | ui | bus | macro
    params: null,            -- accepted body, null for a nullary run or note()
    result: null,            -- returned value; note() records null
    dropped: 0               -- events this run lost since the last one published
  }
  ```

- **`seq` and `dropped`:**
  - **Numbering.** `seq` is assigned when the event is created, before it
    is queued, so the published stream may have gaps.
  - **Loss.** When the queue is full the oldest queued event is dropped and
    a loss counter grows. The next event that is actually published carries
    the counter in `dropped`, and the counter resets. A gap in `seq` always
    equals the sum of the `dropped` values that explain it.
  - **Ordering.** `seq`, not `at_ms`, orders a run's events: the wall clock
    can move.
  - **A new run.** A different `run` means the application restarted, and
    `seq` starts again at 1. Consumers key a sequence by the publishing
    service (and node) together with `run`; `run` is opaque.
  - **Reconnects.** Events that could not be published while the Bus was
    away count as dropped.
  - **Unknown outcomes.** A publish whose outcome is unknown (the
    connection failed after the frame went out, or no answer came) may have
    reached subscribers, so it is assumed delivered and not counted. If it
    was in fact lost, a subscriber sees a gap that `dropped` does not
    explain, the same as its own missed deliveries. Exact accounting there
    would need a broker receipt per event.
  - **Subscriber loss.** A subscriber that misses deliveries detects it from
    `seq` gaps that `dropped` does not explain.
- **`origin` is the mechanism that reached the registry**, not an earlier
  cause:
  - `menu`: a menu row, including one chosen through synthetic input;
  - `shortcut`: a key binding, including a synthetic key press;
  - `palette`: the command palette or Help search;
  - `ui`: any other control in the window, such as a toolbar button;
  - `bus`: `<app>.execute` (or another verb whose documentation says it runs
    a registry command);
  - `macro`: the shared macro runner. This value is reserved until
    applications have a Macros menu.
- **Parameters and result:** the event carries the accepted params and the
  returned result, or a digest above a bound. Each field is measured using
  compact JSON (`serde_json::to_vec`); a value above 4096 bytes becomes
  `{ bytes, sha256 }`, with a lowercase SHA-256 digest of those bytes. The
  accepted params are preserved verbatim; the registry cannot reserialise
  defaults applied inside a handler. Nullary params and both `note()` fields
  are null.
- **Publishing never blocks the application.**
  - Events go through a bounded queue on the application's existing effect
    path.
  - The topic is not retained.
  - Events still queued when the application exits are lost, and nothing
    counts them: the next run starts afresh.
- **It will be implemented once.** The UI-free command registry (`libs/command`) will take
  the origin at dispatch and record each run. The shared Bus connection (the
  `citizen` library, or an application's own connection until it moves to
  `citizen`) will publish the records. An application will not write its own
  publisher.

## Why

Every action is already a command with a stable id, and agents already reach
every command over the Bus. Until now the commands a person ran by hand
stayed inside the process. Nothing could watch them, record them or learn
from them. Publishing each run closes that gap with one hook, and it is the
first half of how [`rec`](2026-10-11-rec-and-play.md) writes a person's work
as a script.

## Consequences

- AGENTS.md §4.1 gains the rule.
- `Registry::execute` gains an origin, and the existing call sites state
  theirs.
- Each application gets a test proving that a menu command and a Bus command
  are both published with the right origin and consecutive `seq`, and that
  a refused command publishes nothing.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-11-keymaps-in-settings/ (source: https://mixos.dev/docs/decisions/2026-10-11-keymaps-in-settings.md) -->

# Key bindings are desktop settings

Status: accepted. Settings contract 0.4.0 (additive). Widens
[Desktop settings have one native ABP authority](2026-10-07-settings-authority.md),
whose scope was the desktop's appearance and layout.

## Context

Every egui application offers its actions as commands with optional
shortcuts ([egui applications](2026-10-09-egui-applications.md)). Before
this decision each application kept its key bindings its own way:

- dopus read an overlay file, `keymap.conf.mix`, in its config directory,
  once at start-up;
- ced had a fixed table of Notepad++-style defaults;
- BusViewer and Prefs had shortcuts written into their command lists;
- each parsed chord text in its own way (`ArrowLeft` in dopus, `Left` in
  ced).

So a person changing a key had to know which application kept it where, an
agent could not change one over the Bus, and nothing could show every
binding in one place.

## Decision

1. **The user's bindings live in settingsd.** The authored desktop profile
   gains `keymaps`: per application id, per action id, the list of chords
   the person chose. An empty list unbinds the action. An action that is
   not listed keeps the application's default.
2. **Defaults stay with the application.** An application's default chords
   ship in its code, beside the actions they run, so a new action arrives
   with its key and an application without settingsd still has its keys.
   settingsd stores only what the person changed.
3. **One chord grammar.** A chord is modifiers then one key, joined by `+`:
   `Ctrl`, `Alt` and `Shift`, in any order, then a key name. Key names are
   egui's (`ArrowLeft`, `PageDown`, `F6`, `Delete`, `Num1`), a single letter
   or digit, or one of the short forms `Up`, `Down`, `Left`, `Right`, `=`,
   `-` and `/`. `Ctrl` is the platform's command key. One stroke per chord.
   settingsd checks the grammar; the application checks the key name, and
   reports and skips one it does not know.
4. **Edited by the existing transaction.** `settings.apply` takes
   `keymaps.<app>` (the whole map, or null to drop every change for that
   application) and `keymaps.<app>.<action>` (a list of chords, or null to
   return that action to its default). Limits: 16 applications, 256 actions
   each, 4 chords per action, 32 bytes per chord.
5. **Followed live.** The summary (`settings.get {view: summary}` and the
   summary topic) carries `keymaps`, omitted while empty. Each application
   applies its own entry whenever the profile's revision changes, so a new
   binding works at once, without a restart.
6. **How an application applies them.** The toolkit's command registry keeps
   the defaults it was built with. Applying a profile entry starts from
   them:
   - each listed action takes exactly its listed chords: the first is its
     menu accelerator, the rest also run it;
   - a chord the person bound takes precedence over a default, and the
     default loses that chord;
   - an unknown action or key is skipped and reported in the application's
     log.
7. **The record format is unchanged.** `keymaps` is authored and omitted
   while empty, so every stored profile re-serialises byte for byte and its
   seal still verifies. It has no effect on the resolved design, so the
   effective digest and design revision do not move when only a binding
   changes.

## Consequences

- dopus no longer reads `keymap.conf.mix`. No such file existed on the
  running session, so nothing needed migrating.
- `<app>.commands` reports each command's effective shortcut and its further
  chords, so an agent can read what a key does before and after a change.
- A shell that decodes the full snapshot (`deny_unknown_fields`) must be
  rebuilt before a profile carries `keymaps`. The portal is one; it is
  rebuilt with this change.
- A Keyboard Shortcuts page in Prefs can follow: it reads each application's
  commands over the Bus and writes `keymaps.<app>.<action>`.

## Not covered

- The compositor's own bindings (workspace and window keys) are not an
  application's commands; they stay in the compositor for now.
- Multi-stroke chords, and keys an editor widget handles itself (Cut, Copy,
  Paste and the cursor keys in ced's editor).

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-11-rec-and-play/ (source: https://mixos.dev/docs/decisions/2026-10-11-rec-and-play.md) -->

# Decision — rec and play

Status: accepted 2026-10-11. Amends [the source layout](2026-10-04-source-layout.md)
(AGENTS.md §3.4).

## The decision

- **One Rust command-line tool, `cli/recplay`, installed as `rec` and
  `play`.** The binary is `recplay`. `rec` and `play` are links to it,
  added at install time in `/opt/mixos/bin`, and it chooses its behaviour
  from the name it was started as. Run as `recplay`, it prints help for both.
- **`play` puts something on the desktop.**
  - A file or URI opens with the handler the desktop already knows. That
    means shared-mime-info for the type, desktop entries' `MimeType=` and
    `mimeapps.list` for the handler. MixOS ships no table of its own and
    names no application.
  - A `.mix` program is performed when the person runs `play x.mix`
    themselves.
  - An `.mx` document is read by its schema and never executed.
  - `play` has **no media decoders.** It describes and previews a foreign
    format only through a handler's own command-line tool, named in a
    per-user document that ships empty.
- **`play` is the one resolver.**
  - `play --serve` answers `play.open`, `play.resolve`, `play.info`,
    `play.handlers` and `play.perform` on the Bus. The file manager and the portal's OpenURI
    use it, so every way of opening a file reaches the same handler.
  - Opening a `.mix` over the Bus shows it in the editor. Only
    `play.perform` runs it, and every perform is logged.
- **`rec` writes an editable Mix script** from what happens on the desktop.
  It builds on [executed commands](2026-10-11-executed-commands.md), [verb
  classes](2026-10-11-verb-classes.md) and the broker's observation stream.
  Runs of lines to one application are grouped in `address … end`, and a
  script never waits with a sleep.
- **A recording spec comes first.** `docs/docs/spec/recording/` is written and
  accepted before `rec` is built. It settles what these sources alone
  cannot:
  - **Replay arguments.** The broker does not show the payloads of a native
    session's calls, and a command event carries no arguments. Each
    application declares a recording surface: the committed actions it
    publishes with the arguments needed to repeat them, such as the path a
    dialog returned.
  - **One record per action.** A Bus call that runs a command shows up both
    in observation and as a command event. A causal identifier, or a rule
    for which source is authoritative, keeps exactly one.
  - **Per-verb replay rules.** Targets are resolved stably instead of being
    dropped (a tab, a buffer). Fencing values are made fresh on replay
    (revisions, operation ids). Deliberate waits such as `ced.wait` are kept
    as conditions, never turned into sleeps.
  - **Sensitivity.** Each owner marks what is sensitive, including text
    embedded in other values. A recording that lacks a required argument
    says so and is marked incomplete. It never guesses.
- **`rec` and `play` are accepted name collisions.** Both names belong to
  sox, which installs `/usr/bin/rec` and `/usr/bin/play` (checked
  2026-10-11 in Arch Linux and Debian trixie, where sox is the only owner).
  - MixOS installs to `/opt/mixos/bin`, which comes first in its PATH, so a
    MixOS session's `play` is this one.
  - sox's commands stay reachable by full path.
  - MixOS's own units and scripts call `/opt/mixos/bin/play` by absolute
    path.
  - `recplay` itself collides with nothing.

## Why

Opening a file and recording what a person does are two halves of the same
contract, the desktop's verbs. One resolver means the file manager, the
portal, the command line and agents never disagree about which application
opens a file. Using the freedesktop data that applications already install
means MixOS learns a new format the moment an application that handles it
is installed, without a MixOS change.

A recorded script is ordinary Mix. It can be read, edited, shared and
performed on another machine, and it shows exactly how the work was done.

The two names are the plain words for the two actions. sox's tools of the
same names are audio utilities that a MixOS session does not ship. The cost,
calling them by full path, falls on few people and is easy to pay.

## Consequences

- AGENTS.md §3.4 lists the accepted collisions: `mix` (Elixir), and `rec`
  and `play` (sox).
- `play`'s Bus verbs, the per-user handler document and the Bus snapshot
  document schema are registered as contracts when they land.
- The file manager stops spawning `xdg-open` and calls `play.open`.
- Rejected: a MixOS MIME-to-application table. It duplicates what every
  application already installs, and it would have to name applications.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-11-settings-authority-stays-a-service/ (source: https://mixos.dev/docs/decisions/2026-10-11-settings-authority-stays-a-service.md) -->

# The settings authority stays a separate service on noded

Status: accepted. Builds on
[Desktop settings have one native ABP authority](2026-10-07-settings-authority.md).

## Context

The question came up whether settingsd should be merged into noded, since
every settings read and publication already passes through the broker.

- noded is the Bus broker: every service and application on a node
  depends on it, and the ABP wire is frozen.
- settingsd is a domain authority. It owns a durable, sealed settings
  store, compiles design sources into projections, and answers
  `settings.apply` and `settings.get`.
- noded retains settingsd's last publication, so an application starts
  with the right look while settingsd is stopped or restarting.

## Decision

1. **settingsd stays its own process and unit**, a client of noded like
   editd, portald and releasesd. It is not merged into noded, and noded
   gains no settings logic beyond what any service gets: topic
   reservation for the registered owner, retention and owner stamping.
2. **The reasons are failure isolation and least privilege, not
   convenience:**
   - a settingsd crash, restart or upgrade must not drop the Bus;
     retained topics carry consumers through it;
   - design compilation is CPU work. One apply once took about 370 ms of
     compile time; inside the broker that would stall every message;
   - noded listens on the network; the settings store is written only by
     settingsd's service account;
   - noded is generic plumbing and runs on headless nodes with no desktop
     settings at all.
3. **The costs are accepted and handled where they arise:** start order
   (settingsd starts after noded is reachable, and the session target
   upholds it), one Bus hop per read, and changes that touch both, such as
   a new reserved topic, ship together.

## Consequences

- A proposal to fold another service (editd, portald, releasesd) into
  noded meets the same test and is refused for the same reasons unless a
  decision says otherwise.
- Bus-level improvements that help settings, such as publisher stamps for
  plain clients or conditional reads, belong in noded as generic features
  available to every service.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-11-settings-snapshot-schema-2/ (source: https://mixos.dev/docs/decisions/2026-10-11-settings-snapshot-schema-2.md) -->

# Settings snapshot schema 2 sends each design once

Status: accepted. Settings contract 0.3.0 (additive), snapshot schema 2 beside
schema 1. Follows [plain followers read a summary](2026-10-11-settings-summary-reads.md).

## Context

A snapshot carries one compiled design projection per effective context:
the desktop and each native app. With the embedded design every context
shares one projection, so a 499 KB schema 1 snapshot holds seven copies of
one 71 KB projection. Native consumers (the portal, the compositor's scene
host and applications on the shared `settings` consumer) need those
projections, receive the snapshot as a retained topic delivery and read it
again to confirm, so each of them moves about 1 MB per change.

Several of those consumers belong to applications still awaiting their port
to this tree's egui toolkit. They carry their own copy of the settings
library and must keep working, unchanged, until each is ported.

## Decision

1. **Schema 2 is a wire form.** `settings::compact::CompactSnapshot` holds
   each distinct projection once under `designs`, keyed by its digest; each
   context's `design` is a digest naming one. `compact::decode` expands
   schema 1 or 2 into the same in-memory `Snapshot`, so the consumer,
   reducer, cache and effective digests do not change. A context naming an
   unknown design, or a design no context names, is refused. Digests are
   opaque keys to the decoder.
2. **Asked for, never assumed.** `settings.get` (full view) and
   `settings.appearance.get` take `schema`: 1 is the default and is never
   sent; 2 answers in the compact form; any other is refused with
   `unsupported_schema`.
3. **A compact topic.** settingsd publishes the retained snapshot on three
   topics, in order: `settingsd.desktop.changed.<profile>` (schema 1),
   `settingsd.desktop.compact.<profile>` (schema 2), then the summary. A
   revision is published once all three are; a failure retries all three.
   noded reserves the compact topic for settingsd as it does the others.
4. **Ported consumers move now.** The shared native consumer
   (`settings::native`) follows the compact topic and reads schema 2, and
   the portal asks for schema 2. Measured with the embedded design, the
   compact snapshot is about 72 KB where schema 1 is 499 KB.
5. **Unported consumers move with their port.** An application or service
   still on its own copy of the settings library keeps following the schema
   1 topic and reading schema 1. Each moves when it is ported, by using the
   shared consumer. Nothing in an unported consumer changes for this
   decision.

## Retiring schema 1

The schema 1 topic and default stay while any consumer still uses them.
Publishing schema 1 costs a full snapshot per change, so once the last
consumer has moved, a later decision stops publishing it and makes schema 2
the default read. The library keeps decoding schema 1 for caches and old
retained state.

## Not chosen

Deltas between revisions, compression and local compilation are discussed
in the summary decision. Schema 2 removes duplication without changing what
a consumer holds; local compilation (no projection on the wire) remains the
next step once consumers can pin the design source by digest.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-11-settings-summary-reads/ (source: https://mixos.dev/docs/decisions/2026-10-11-settings-summary-reads.md) -->

# Plain settings followers read a summary, not the snapshot

Status: accepted. Settings contract 0.2.0 (additive). Builds on
[Desktop settings have one native ABP authority](2026-10-07-settings-authority.md).

## Context

The settings snapshot carries the profile's complete effective design: one
compiled projection per context (the desktop and each native app). Measured
on a running session with the embedded design source:

- a `settings.get` reply is 499 KB of JSON, 498 KB of it `effective`: seven
  byte-identical 71 KB projections, 62 KB of each a button table;
- settingsd publishes that whole snapshot as the retained payload of
  `settingsd.desktop.changed.<profile>`;
- an application following the session look on a plain Bus connection
  (`settings::follow::Follower`) cannot verify a delivery's publisher, so it
  treats the delivery as a hint and reads `settings.get` again. It uses only
  the profile's identity, revision and appearance names.

One appearance change therefore moved about 0.5 MB to every plain follower
twice (the delivery and the re-read), and each parsed it. Idle traffic is
zero; the cost is per change. Native consumers (the portal, the compositor's
scene host and applications using the shared `settings` consumer) do use the
projections, from owner-stamped deliveries.

## Decision

1. **A summary topic.** settingsd also publishes a retained
   `settingsd.desktop.summary.<profile>` whose payload is a
   `settings::Summary`: schema, binding, incarnation, revision, design
   revision, source digest, the appearance names and `custom_source`. It
   never carries the projections or a custom design source. noded reserves
   it for settingsd exactly as it reserves the snapshot topic: only the
   registered `settingsd` service may publish or clear it, and inner routing
   headers are canonicalised. A revision counts as published once both
   topics are; a failure retries both.
2. **A summary read.** `settings.get` takes an optional `view`: `full` (the
   default, the complete snapshot as before) or `summary` (the same
   `Summary` under `summary`, with the usual status fields). An unknown view
   is refused like any unknown field. A request without `view` reads exactly
   as it did under 0.1.0, and the field is never sent at its default.
3. **Plain followers move to the summary.** The `Follower` subscribes to
   the summary topic and reads the summary view; Prefs does the same. A
   follower still treats a delivery only as a hint: this decision does not
   change how deliveries are trusted.
4. **Native consumers are unchanged.** The snapshot topic and the full view
   keep their schema and behaviour for every consumer that uses projections.

Measured on the same session after the change, one appearance change sends
a plain follower a 566-byte summary delivery and a 587-byte summary read,
where it had a 542 KB delivery and a 542 KB read. The remaining large
transfers belong to native consumers: the snapshot publish, the portal's
`settings.appearance.get` and the compositor scene host's full read, each
about 542 KB. They are the subject of the deduplication step below.

## Rollout

The summary topic is new, so the order matters: noded (the reservation),
then settingsd (publishes and serves the summary), then the followers. A
follower that reaches a settingsd without the summary view is refused
(`unknown field`) and keeps its last look, and it hears no hints from a
settingsd that does not publish the summary topic. Roll back in the reverse
order.

## Considered and deferred

- **Deduplicating `effective` by content digest** (one copy per distinct
  projection, contexts naming a digest) would make the full snapshot about
  72 KB. It changes snapshot schema 1, which native consumers decode and the
  optional cache stores, so it needs a schema 2 negotiated per request and
  the consumer, reducer and cache moving together. It is the next step for
  native consumers.
- **Compiling projections locally from the summary.** A projection is a
  function of the pinned source and the selected axes, and native consumers
  already link the design library: they could compile instead of
  transferring, at a few milliseconds per context. It needs the source
  pinned by digest and a compiler-version check, which the cache already
  records.
- **Immutable artifacts fetched by digest** remain the planned path for
  settings too large to inline (the 960 KiB snapshot ceiling).
- **Deltas between revisions** are not worth it: a scheme change rewrites
  most colour values in a projection, so a JSON delta is nearly the size of
  the projection. A summary is already smaller than any delta of it.
- **Compression** under the frozen ABP framing would mean base64 bodies;
  WebSocket permessage-deflate is not available in the Bus's WebSocket
  library and its window is too small for repeated 71 KB projections.
- **Trusting summary deliveries** (dropping the re-read) needs the
  publisher stamp noded already records to reach plain clients. It is a
  separate change to the Bus client API.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-11-verb-classes/ (source: https://mixos.dev/docs/decisions/2026-10-11-verb-classes.md) -->

# Decision — verb classes

Status: accepted 2026-10-11. Amends AGENTS.md §5 (Bus verbs are wire
contracts).

Amended 2026-10-20 by [commands take parameters and return results](2026-10-20-commands-take-parameters.md).
Registry schema 4 adds a trailing `schema` field to every verb and family:
`none` for no body or an empty object, `pending` through 2026-11-30 inclusive
in UTC, or a Rust serde request type deriving `JsonSchema`. Type paths match
`^[a-z][a-z0-9_]*(::[A-Za-z][A-Za-z0-9_]*)+$`, such as
`command::ExecuteRequest`. The gate accepts schema 2, 3 or 4 for fixtures;
the repository registry must be 4. It refuses `schema` below version 4,
missing or malformed body schemas at version 4, and expired `pending`
placeholders, naming each expired verb or family. `--today YYYY-MM-DD`
overrides the UTC date for tests.

## The decision

- **The verb registry moves to schema 2.** Every entry in
  `docs/docs/spec/bus/verbs.conf.mix` gains a `class`, one of:

  | class | Meaning | Examples |
  |---|---|---|
  | `intent` | Changes what an application or service holds, or what another caller would see, at someone's request | `<app>.open`, `<app>.execute`, `<app>.refresh`, `settings.apply`, `releases.notes` (it fetches when nothing is cached), `<app>.quit`, `<app>.window` |
  | `query` | Changes nothing another caller could observe. The one allowance: it may write the artefact it was asked for and returns, such as a screenshot | `<app>.ping`, `.info`, `.state`, `.commands`, `.ui.tree`, `.ui.capture`, `.window.state`, `settings.get`, `ced.wait` |
  | `input` | Synthetic low-level input, standing in for a person's hands | `<app>.ui.click`, `.ui.pointer`, `.ui.scroll`, `.ui.key`, `.ui.type` |
  | `system` | Session plumbing. The single-instance activation verb `<app>.show` is `system` even when something calls it directly | `<app>.show` |

- **The class describes the verb, not one call.** A verb that both reads and
  changes state is `intent`.
- **When in doubt, it is `intent`.** Dropping a real action is worse than
  keeping a read.
- **A verb an application describes as `read_only` is a `query`.** Each
  application's registry test checks this. The reverse need not hold:
  `.ui.capture` writes a file, so it is not read-only, but it is still a
  query.
- **The registry gate** (`tools/verb_registry.mix`) refuses:
  - a schema other than 2;
  - an entry that is not in the canonical one-line form;
  - an unknown or missing field;
  - a bad name, owner, status or version;
  - a duplicate;
  - a class outside the four.

## Why

Tools that watch the Bus need to know what a verb is for:

- a recorder keeps intent and drops reads;
- a live traffic view colours them differently;
- an agent asked "what changed?" looks only at intent.

Without a declared class, each tool guesses from verb names, and the guesses
drift apart. The registry already declares every verb's owner, version and
status, so its purpose belongs there too.

## Consequences

- Every existing entry is classified in one change, together with the gate.
- A new verb is registered with its class from its first commit.
- Classes are about purpose, not replay. A recorder still needs each owner's
  replay rules ([rec and play](2026-10-11-rec-and-play.md)), for example
  that `ced.wait` is a deliberate ordering point.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-12-hostd/ (source: https://mixos.dev/docs/decisions/2026-10-12-hostd.md) -->

# Decision — hostd, the host service

Status: accepted 2026-10-12.

## The decision

- **One service, `hostd`, runs as root on each host.** It has two jobs:
  information about the host (hardware, OS, the MixOS mode, network
  management state, devices, power) and privileged actions on the host.
  It is the host agent of the VT-native design: the only MixOS code on the
  host besides `mix`.
- **No generic exec.** No verb runs a caller-supplied command, script or
  shell string. Each verb does one job, checks its arguments against a
  schema and does the work natively (writes the file itself, calls
  networkd, resolved, logind or iwd over Varlink or D-Bus).
- **Written in Rust.** Mix is the client. A root process that interprets
  scripts is too much attack surface.
- **A verb that can't be reversed is not added.** Exception: the two desk
  power verbs, `desk.restart` and `desk.stop` (see Amendments).
- **Every new verb is reviewed on its own,** and the verb list stays short.

### Callers and transport

- **Local callers** use a Unix socket. Identity comes from the kernel
  (`SO_PEERCRED`) and the caller's cgroup, never from the request.
- **Reads are also served on the Bus,** like any other service's.
- **Writes from other nodes** are accepted only when signed by a controller
  key listed in that host's policy, over the target node, a nonce and an
  expiry. Mesh trust alone never authorises a write. A host with no listed
  controller accepts no remote writes. Enforcement is on the receiving
  host.
- **Ports below 1024 are not hostd's job.** A service that binds one gets
  `AmbientCapabilities=CAP_NET_BIND_SERVICE` in its own unit.

### Tiers

| Tier | Examples | Gate |
|---|---|---|
| read | host info, network state, devices | caller identity |
| reversible | Wi-Fi connect, link configuration, device bind, suspend | a standing grant, plus a dead-man check or a kept previous state |
| reversible, wide blast radius | firewall, host package upgrade, reboot | a grant, a second signature from an independent reviewer, and a rate limit |
| irreversible | — | no verb exists |

### Autonomy within limits set in advance

- **Standing grants,** not per-call prompts. A grant names the caller (from
  the kernel), the verbs, argument limits and an optional expiry. Only
  creating or widening a grant needs a person, confirmed through physical
  input that no Bus caller can synthesise.
- **Reversible by construction.** A verb applies its change, runs a health
  check, and reverts unless the check passes in time. It keeps the previous
  state (the previous file, or a filesystem snapshot) behind a receipt that
  `hostd.undo` restores.
- **Limits:** a rate limit per caller and verb, a circuit breaker after
  repeated rollbacks, and a `freeze` that drops hostd to reads only.
- **Audit:** one journal record per call.

### Files hostd owns

hostd writes only files it names itself (networkd files are
`/etc/systemd/network/50-hostd-*`) and never edits a file it didn't write.

## Why

- Agents need to change host configuration (network, WireGuard, power,
  devices) without `sudo` from a session, and without a person approving
  each call.
- MixOS core has no polkit. hostd is the mechanism and its policy in one
  small binary, with rules as data instead of scripts.
- Closed verbs make a stolen credential worth far less than a root shell.

## Consequences

- Session code never shells out to `sudo`; a missing host action is a new
  hostd verb.
- Write verbs arrive one reviewed verb at a time. The first is
  `net.link.apply`; the verbs, grants and refusals are documented in the
  [host service manual](../../hostd/README.md).
- **Root on the host** means uid 0 in hostd's own pid and user namespaces,
  proven through a pidfd. Root inside a container is never root on the
  host, with or without uid remapping.

## Amendments

### 2026-10-13: desk power verbs are an exception to "no irreversible verbs"

`desk.restart` and `desk.stop` restart or power off one desk machine. A
powered-off desk cannot be put back by hostd, so no undo can exist. The
desk must still be able to restart or stop itself, so the two verbs are
admitted as exceptions to the irreversibility rule. They are not a pattern
for other verbs.

Reversibility is replaced by these limits, which apply to both verbs:

- **One desk per grant.** The verb takes no machine name. The grant's
  `desks` limit must name exactly one valid machine, and that machine is the
  only one the verb can touch. A caller with no desk, or two, is refused.
- **The host is never powered.** The verbs run `machinectl reboot` or
  `machinectl poweroff` on the named machine only.
- **A standing grant, rate limited.** Nothing runs without a grant, and a
  grant carries a rate limit and an expiry.
- **Freeze applies.** `hostd.freeze` refuses both verbs.
- **Every call is recorded,** as a receipt and in the audit journal. `hostd.undo`
  refuses both verbs.

Deferred (Mark, 2026-10-13): the second signature from an independent reviewer
that the reboot tier requires is not built for `desk.*`. Security gates are
added once the desktop is ready for daily use, where they are needed. Until
then, the grant's rate limit and expiry are the only second check.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-12-non-root-install-and-service-ports/ (source: https://mixos.dev/docs/decisions/2026-10-12-non-root-install-and-service-ports.md) -->

# Decision — non-root install, per-service users, mesh-first ports

Status: proposed 2026-10-12. Builds on
[one repository, install profiles](2026-10-12-one-repository-install-profiles.md)
and the one-system-binary design (every headless daemon a personality of
`mix`, chosen by `argv[0]`), which needs its own decision record.

## The question

The server programs (maild, webd, dnsd and the rest) are moving into MixOS,
headed for one `mix` binary. Updates already reach desktop users through
releasesd, which by rule never changes anything as root. Can a whole node,
servers included, be installed and kept current without root, and how do
unprivileged daemons serve ports 25, 53, 443, 465, 587 and 993?

## Where these servers run

The usual MixOS server is a node on its owner's own WireGuard mesh, a /24
of their machines. Mail, web and DNS are served to that mesh, not to the
internet. A server that must take connections from outside the mesh (an MX
on public port 25, a public website on 443) is the exception. This record
covers the mesh case and states what it does not settle for the public one.

## The decision

### 1. Root installs once; updates never need it

- **Bootstrap (root, once per node, and again only when units change):**
  create the system users, install the unit, socket, sysusers and tmpfiles
  files, and hand the server prefix to the `mixos` user.
- **The server prefix `/opt/mixos` is owned by the system user `mixos`.**
  A releasesd instance running as `mixos` keeps it current, with the same
  checks as a desktop install (GitHub digest and `SHA256SUMS`, staged
  unpack, previous version kept for rollback). It uses releasesd's existing
  layout through its environment: `MIXOS_RELEASES_ROOT=/opt/mixos`, so
  releases land in `/opt/mixos/opt/<app>/<version>` and their programs are
  linked into `/opt/mixos/bin`. The unit paths (`/opt/mixos/bin/<daemon>`)
  do not change.
- **Desktop installs stay per user** in `~/.local`, as today.
- Binaries are readable and executable by everyone and writable only by
  `mixos`. No daemon runs as `mixos`.

### 2. Every daemon runs as its own user

- Each server daemon runs as its own system user (`maild`, `webd`, `dnsd`
  and so on), declared in its component's sysusers fragment. Never as root,
  never as a login user, never as `mixos`.
- Each daemon's state lives in its own `StateDirectory=`, which no other
  service user can read. A compromised webd cannot read mail, keys or the
  login user's home.
- Units use systemd's sandboxing (`NoNewPrivileges=yes`,
  `ProtectSystem=strict`, `ProtectHome=yes`, `PrivateTmp=yes` and a
  `CapabilityBoundingSet=` that names only what the daemon needs), and each
  component's units are reviewed against that list.

### 3. Privileged ports come from systemd

- **Socket activation is the target.** A system `.socket` unit binds the
  privileged ports as root and passes the open sockets to the daemon
  (`LISTEN_FDS`). The daemon never holds a capability. Socket activation
  also keeps the listening socket open across a restart, so an upgrade
  drops no connections that are still queued.
- **Interim:** a daemon that cannot take inherited sockets yet gets
  `AmbientCapabilities=CAP_NET_BIND_SERVICE` with
  `CapabilityBoundingSet=CAP_NET_BIND_SERVICE` in its unit. Taking
  inherited sockets is part of each port's definition of done (maild,
  webd, dnsd).
- **Not file capabilities.** The kernel clears them whenever the file is
  replaced, so every update would silently lose the ports. In the one
  binary they would also give the `mix` shell, and every script, the right
  to bind 443.
- **Not lowering `net.ipv4.ip_unprivileged_port_start` by default.** It
  applies to every user on the node. A node owner may still choose it for a
  single-user machine, but MixOS does not do it for them.

### 4. Mesh first

- Server daemons listen on the node's mesh address by default, never on
  every address. The `.socket` units name the mesh address
  (`ListenStream=<mesh-ip>:25`, with `FreeBind=yes` so the socket can be
  bound before the WireGuard interface is up).
- Listening on a public address is an explicit per-node configuration,
  never a default and never part of an install profile.

### 5. Applying an update without root

- releasesd (as `mixos`) moves `current` and records the transition in
  `meta.json`. A root-owned systemd `.path` unit watches that file and
  starts a root service that restarts only the units whose component
  version or hash changed in the release manifest. The `mixos` user
  triggers the restart but never controls which units restart or how.
- A release whose units, sysusers or tmpfiles fragments changed cannot be
  applied by `mixos`. releasesd installs the binaries, reports that the
  bootstrap step is needed, and leaves the running services on the
  previous version until a root user runs the installer.

### 6. What still needs root at run time

- **nspawnd:** `systemd-nspawn` needs root. It stays a root service in its
  own profile, outside this model.
- **noded:** reading network state needs nothing; changing it needs
  `CAP_NET_ADMIN`, granted in its unit the same way as the interim port
  capability, only if that node uses the feature.
- **compd:** none. Seat, input and display access come through logind and
  libseat, as today.

## Not settled: servers open to the internet

A daemon that accepts connections from outside the mesh (an MX on public
port 25, a public website on 443) faces hostile traffic. Running it as its
own sandboxed user, with the port granted by systemd, is still the baseline.
It is not shown to be enough: rate limits, DoS behaviour, TLS and ACME
exposure, whether the public listener should be its own process or node, and
firewall policy all belong to a separate decision before any public
listener ships as a supported configuration.

## Why

- **Updates without root** are what make the releasesd model work for a
  whole operating system: no package manager, no distribution repository,
  and no root shell for routine updates.
- **Per-service users** limit what one compromised daemon can reach. Running
  every daemon as the login user would have been simpler, but would have
  handed a mail-server bug the owner's SSH keys and secrets.
- **Ports from systemd** grant the right per service and per port, survive
  updates, and keep capabilities away from the shell that shares the
  binary.
- **Mesh first** matches how MixOS servers are used, and keeps the
  internet-facing case visible as the exception it is.

## Alternatives

- **Everything as the login user** (user units with lingering, plus the
  sysctl). Rejected: no isolation between daemons or from the owner's home.
- **File capabilities on `mix`.** Rejected: lost on every update, and
  granted to every script.
- **Root installs through a package manager.** Rejected: it is the
  dependency that releasesd removes.
- **Root-run releasesd for the server prefix.** Rejected: releasesd's trust
  rule (never act as root) is what makes a bad release unable to take over
  the node. A fixed `.path` unit for restarts keeps root's part small.

## Consequences

- Each server component ships a sysusers fragment, its units with the
  sandboxing list, and `.socket` units for its ports. The install-profile
  resolver lists them, as that decision already requires.
- maild, webd and dnsd learn to take inherited sockets as part of their
  ports.
- releasesd gains a server instance (`mixos` user, `/opt/mixos` root) and a
  "units changed" result. The restart service and its `.path` unit are new
  work, alongside the installer the install-profiles decision calls for.
- The bootstrap installer is the only routine root step, and it runs again
  only when a release changes units.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-12-one-repository-install-profiles/ (source: https://mixos.dev/docs/decisions/2026-10-12-one-repository-install-profiles.md) -->

# Decision — one repository, install profiles

Status: accepted 2026-10-12; amended 2026-10-12 after review. AGENTS.md
§2.3 (identity and metadata), §2.5 (Mix components) and §10 (the
checklist) are amended in the same change that adds the `profiles` field
and its gate.

## The question

MixOS has two audiences: a desktop (the compositor, the apps and their
settings services) and servers (mail, web, blobs, DNS and the mesh daemons
on headless nodes). The server programs have not moved into this
repository yet. Should they get a repository of their own?

## The decision

- **Everything stays in this repository and its one Cargo workspace.**
  Desktop, server, command-line and library code alike. There is no second
  MixOS source repository for server programs.
- **The split is an install split, not a source split.** Every shipping
  component declares the **install profiles** that include it:

  | Profile | Meaning |
  |---|---|
  | `base` | On every MixOS system: the shell and the Bus node |
  | `server` | What a headless node may run |
  | `desktop` | The desktop session: compositor, apps, their services and the session's own wiring |

- **Composition.** `server` and `desktop` each include `base`: resolving
  either one yields its own components plus `base`'s. A system may install
  both. A resolved set is the union of its profiles, each component once.
- **Who declares.** A component's *principal* package declares `profiles`:
  the package whose name is its component (the directory under `apps/`,
  `services/` or `cli/`), or a Mix component's `component.mx`. The list is
  non-empty, has no duplicates and names only the three profiles. The field
  is absent on libraries, on a component's private crates (whatever `kind`
  they inherit from their owner), and on `tool` and `test` packages.
  Libraries are never installed on their own; they are linked into what
  needs them. The session's targets and wiring (`session/`) belong to
  `desktop`; when the `session` kind lands, it declares `profiles` like any
  other shipping component.
- **Where it is declared.** A Rust component adds `profiles` to its
  `[package.metadata.mixos]`:

  ```toml
  [package.metadata.mixos]
  component = "webd"
  kind = "service"
  layer = "core"
  contract = "public"
  profiles = ["server"]
  ```

  A Mix component adds the same `profiles` list to its `component.mx`.
- **Naming.** Install profiles are unrelated to Cargo's build profiles
  (`release`, `release-fast`) and to any service's own settings profiles.
  Prose says "install profile"; tools take `--install-profile`, beside
  `--cargo-profile` and `--target`, never a bare `--profile`.
- **The profile gate** is new, workspace-wide work. Today's closure and
  layering gates check compd's own crates only; they do not protect other
  components. The profile gate:
  - refuses the declaration errors above;
  - refuses a `base` or `server` component that itself declares the
    `desktop` layer;
  - resolves the normal and build dependency closure of each `base` and
    `server` principal, for every feature set its profiles build, and
    refuses any `desktop`-layer workspace package in it, and any upstream
    GUI crate (smithay, egui, eframe, wgpu, winit, Bevy and the like) even
    though those carry no MixOS metadata;
  - for a Mix component, which has no Cargo closure, refuses a `desktop`
    layer in a `base` or `server` component; what it calls on the Bus is
    checked at review, as AGENTS.md §2.5 already says.

  The component index ([`/docs/components/`](../components.md)) shows each component's
  profiles.
- **Resolving, installing and activating are separate.**
  - **Resolve:** one tool answers "what is in `server`?" from the metadata,
    deterministically. Its output covers the packages to build, the Mix
    components, and each component's runtime artefacts: units by class
    (system or session), `sysusers` and `tmpfiles` fragments, and assets.
    Build scripts, images and installers never keep their own lists.
  - **Install:** places those files. Rust components go to an installer
    that gives binaries and units the record, rollback and drift check
    `tools/component_install.mix` gives Mix components (separate work that
    follows this decision); Mix components go to that existing installer.
  - **Activate:** which services a particular node runs, with what
    configuration, is that node's decision, not the profile's. Installing
    `server` makes a service available; it does not start every server on
    every node.

### The first assignment

| Component | Profiles |
|---|---|
| `mix-shell` (the `mix` binary), `noded` | `base` |
| `compd`, `settingsd`, `portald`, `editd`, `releasesd`, `busviewer`, `ced`, `dopus`, `prefs` | `desktop` |

`server` starts empty: the server programs join it as they move in (mail,
web, blobs and the rest). `releasesd` is a per-user session service and
`editd` serves the session's editors, so both are `desktop`. A headless
mode for either would be its own decision, with suitable supervision,
before it joins `server`.

## Why

- **The two sides share their foundation.** The Bus, noded, Mix, the config
  and props libraries and logging sit under both, and they change almost
  daily. A second repository could pin them as Git dependencies rather than
  wait for releases, but every foundation change would still mean a
  coordinated upgrade on the other side, and consolidating duplicated code
  across the boundary would mean moving it between repositories.
- **Changes cut across both.** The verb registry's move to classes changed
  the registry, its gate and every application in one commit. Across two
  repositories that is coordinated pull requests that can drift apart.
- **The separation that matters can be enforced here.** Headless code
  never needing a GUI stack is a property of a dependency closure, and the
  profile gate checks exactly that for every `base` and `server` component.
  A repository boundary would enforce it less precisely: it says nothing
  about which features or which programs a node gets.
- **This was decided once already.** The
  [source layout decision](2026-10-04-source-layout.md) rejected one
  repository per component so that one dependency graph can be gated,
  shared code consolidated, and changes made atomically. A desktop/server
  split is the same proposal in two pieces, and nothing it relied on has
  changed.
- **What people actually need separated is the build and the install.** A
  mail server should never compile or install the compositor. Profiles say
  that precisely, from data, in one place.

## Alternatives

- **A second repository for server programs.** The strongest case for it:
  an independent lockfile, toolchain and release pipeline, so desktop
  dependency churn never touches a server build and a server fix never
  waits on the desktop. That isolation is real; it loses to the shared,
  fast-moving foundation and the consolidation still to do. A split would
  be the right call if the server side ever needed a different licence,
  private code, its own team or its own release cadence. None of these
  applies. Private deployment detail already lives outside this repository.
- **Cargo features or a second workspace in this repository.** Rejected. A
  second workspace means two lockfiles and two dependency graphs, which is
  what AGENTS.md §0 rules out. Features select code inside a crate, not
  which programs a system gets.
- **A top-level `server/` directory.** Rejected: the top level is
  classified by kind only (AGENTS.md §1). A web server is a service like
  any other; which systems it belongs on is data.

## Consequences

- One `Cargo.lock`: a dependency bump for the desktop also moves the
  servers' resolved versions, and a server fix ships from the same tree as
  that day's desktop work. Each component's tests and the gates catch a
  break; the alternative was version drift between repositories.
- Building a server set compiles only that set's closure (`cargo build -p`),
  so headless builds stay small. A server build host still checks out the
  whole tree, desktop vendor forks included.
- AGENTS.md §2.3 and §2.5 gain the `profiles` field, and §10's checklist
  asks for it.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-12-one-system-binary/ (source: https://mixos.dev/docs/decisions/2026-10-12-one-system-binary.md) -->

# Decision — one system binary

Status: accepted 2026-10-12, **on hold 2026-10-20**. Amends [the source layout](2026-10-04-source-layout.md)
(AGENTS.md §2.3, §3.4, §6 and §9).

> **On hold (2026-10-20).** The single multicall binary is not to be deployed on
> any host of the fleet. The fleet runs separate binaries. The personality
> plumbing stays in the tree, and the decision is to be revisited at a future date.

> **Correction (2026-10-19): the fleet build target is glibc, not musl.** The
> "Fleet builds are static" item below does not describe current practice. cbc
> builds against the workers' glibc, and the shipped `mix` and `webd` binaries
> link dynamically against glibc. The governing plan
> (`_plan/2026-10-02-mixos-transplant-plan.md`, §3.0 "Build target for mesh
> nodes") allows static or musl only where a node's glibc is too old. Every
> node in use is new enough, so no musl build is planned. Treat the static
> musl item and the matching sentence in "Why" as superseded until this
> decision is amended.

## The decision

- **One binary, `mix`, carries the shell and every headless daemon.** It is
  built by a new host component, `cli/system` (package `system`, kind `cli`).
  The host's only code is the dispatcher and the global allocator.
- **A daemon is a personality, chosen by the name the binary was started
  as.** `noded`, `maild`, `webd` and the rest are symlinks to `mix` in
  `/opt/mixos/bin`. Each still runs as its own process, under its own unit
  and journal identity, because the kernel names a process after the name it
  was executed by. There are no daemon subcommands under `mix`: the shell's
  first-argument namespace stays the shell's.
  - `mix --personalities` lists what the binary contains, with each
    component's version.
  - An unknown name exits 2 and prints that list.
  - The shell's self re-execution passes `mix` as its name, so a re-exec from
    a daemon personality comes back as the shell.
- **Components keep their identity.** Each daemon keeps its own crate, tests,
  units, metadata, version and verb registry. Its library exports
  `pub fn main() -> ExitCode`; its own `[[bin]]` stays for development
  builds. `cli/mix-shell` becomes a library with no binary.
- **What goes in:** the shell, `noded`, and every headless base and server
  daemon as it arrives, including the headless desktop-profile services.
  **What stays out:** anything with a GUI stack (compd, the applications),
  and any daemon whose dependencies dwarf the rest. The install-profile
  gate's closure check enforces the first.
- **One personality per process.** No setup happens at link or load time.
  The async runtime, TLS provider, signal masks, panic hook and logger are set
  up in the personality's own `main`, never in a shared library's
  initialiser. Each personality passes its own logging identity and records
  its own build provenance. Every personality uses one allocator, mimalloc.
  A test starts every personality and checks its identity.
- **Fleet builds are static.** The shipped binary targets
  `x86_64-unknown-linux-musl`, fully static, so one file runs on every
  supported distribution regardless of its C library.
- **Shell tests test the shipped binary.** The shell's process-level tests
  live in `cli/system/tests/` and run `mix` as built by the host.

## Why

Every daemon links the same core: the async runtime, serialisation, the Bus,
the Mix evaluator, logging. Linked separately, each carries its own copy, and
every release links that core once per daemon. Measured on the first
two-personality build (the shell and `noded`), the combined binary was 11%
smaller than the two separate ones and its release link took 40% less time.
Both gains grow with each personality. A static musl build cost nothing in
size, startup or evaluator speed, and the same file ran on both
distributions tested.

One file also means one artifact per architecture, one hash to verify and one
version on every node. Running daemons keep the old file's inode, so an
upgrade restarts only the units whose component changed.

Memory is not part of the case: different personalities run different code,
so they share little.

## Consequences

- AGENTS.md §2.3: `cli/system` builds the `mix` binary. `cli/mix-shell` is
  the shell's library and builds no binary.
- AGENTS.md §3.4: a daemon may be installed as a personality, a symlink named
  after its component; units name the symlink.
- AGENTS.md §6: `cli/system` is the one package allowed a non-dev dependency
  on `kind = "cli"` packages.
- AGENTS.md §9: the bootstrap is `cargo build --profile release-fast -p system`.
- Build scripts that built `-p mix-shell` to get `mix` build `-p system`.
- The installer creates each node's personality symlinks from its install
  profiles, keeps the previous binary for rollback, and restarts only changed
  units. The release archive's manifest lists each personality with its
  component version.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-12-scene-strings/ (source: https://mixos.dev/docs/decisions/2026-10-12-scene-strings.md) -->

# Decision — scene strings until Mix reads Fluent

Status: accepted 2026-10-12. Bounds AGENTS.md §4's i18n rule for Mix Scenes content until the gap below is closed.

## The problem

AGENTS.md §4 says user-visible strings come from Fluent catalogues
(`<component>/i18n/<lang>/<component>.ftl`) and that new GUI code does not
hard-code them. Mix Scenes content, the panel, launcher, calendar, notes
and settings scenes in `share/scenes`, is written in Mix, and **Mix has no
Fluent loader**. A scene cannot read a catalogue today. Its strings ("Apps",
the calendar's month names, the launcher's category labels, and the
panel's hover tips) are English literals in Mix.

That is a gap in Mix, not a reason to work around it (AGENTS.md §0).

## The decision

- **Until Mix reads Fluent, a scene library keeps its user-visible strings
  in one table** — the English source — and builds every string through one
  lookup. `share/scenes/lib/models.mix` does this for the panel's hover
  tips: `$TEXT` holds them, `text(key, vars)` fills `{name}` placeholders
  and `counted(n, none, one, many)` chooses the plural form.
- **No new scattered literals.** New user-visible scene strings go into
  such a table, never inline in the model code.
- **The table is the seam.** When Mix gains a Fluent reader, each table
  becomes `share/scenes/i18n/en/<scene-library>.ftl`, keyed exactly as the
  table is, and the lookup reads the session's language with English as
  the fallback. The callers do not change.
- **Older literals** ("Apps" in the panel template, `CATEGORY_LABELS` and
  the month names in `lib/data.mix`) move into tables when their scenes are
  next edited, not as a drive-by.

## Closing the gap

The Mix work is a Fluent reader (parse `.ftl`, resolve a message with
arguments and plural selectors, choose a locale with fallback), added to
`libs/mix` as a builtin or a standard module. This decision is superseded
when that lands and the scene tables are converted.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-12-screenshot/ (source: https://mixos.dev/docs/decisions/2026-10-12-screenshot.md) -->

# Decision — screenshot

Status: accepted 2026-10-12; amended 2026-10-13 (saved shots are named
`YYYYMMDD_HHMMSS.png`, as Spectacle can name them, instead of
`Screenshot YYYY-MM-DD HH-MM-SS.png`). Amends
[the source layout](2026-10-04-source-layout.md) (AGENTS.md §3.4).

## The decision

- **The screenshot and annotation app is `apps/screenshot`.** Its package,
  binary and directory are `screenshot`, its app id is
  `dev.mixos.screenshot` and its Bus service and verbs are `screenshot` and
  `screenshot.*`. "Screenshot" is exactly what the app does, and it is the
  word a person looks for in a launcher.
- **It supersedes Cap.** Cap was the iced screenshot app (`apps/cap`,
  `dev.mixos.cap`, verbs `cap.*`) that lived outside this tree. The egui
  port brings its behaviour across under the new name:
  - the engine moves into the `annotation` crate: the immutable capture,
    the editable objects with undo, one painter for preview and export,
    and no-clobber PNG publication;
  - the iced shell is rewritten on the toolkit, with every action a
    registry command.

  Cap's names are retired and stay reserved (§3.5): the binary `cap`, the
  app id `dev.mixos.cap` and the verbs `cap.ping`, `cap.info`,
  `cap.capture`, `cap.cancel`, `cap.open`, `cap.annotate`, `cap.move`,
  `cap.delete`, `cap.crop`, `cap.undo`, `cap.redo`, `cap.export`,
  `cap.show` and `cap.quit`. They are entered in the retired-names
  registry when it lands. None of them was ever registered here.
- **Print Screen starts it.** compd's bindings, in both profiles:
  - Print takes a region;
  - Shift+Print takes the whole output;
  - Alt+Print takes the window that had the keyboard.

  compd launches `screenshot --comp SERVICE --capture MODE`, naming its own
  Bus service (so a nested compd's key captures through that compd) and,
  for a window capture, the window that had the keyboard at the key press.
  There is one window and one headless instance per compositor:
  `screenshot` and `screenshot-headless` for `comp`, `screenshot-<comp>`
  and `screenshot-headless-<comp>` for another when the name fits in 31
  bytes, else `screenshot--<hash>` and `screenshot-headless--<hash>`; a
  window name never starts with `screenshot-headless`. If that window is already running, the new
  process hands the request to it over the Bus (`screenshot.take`) and
  exits. Unsaved annotations are never discarded by a key press: the window
  comes forward and asks first.
- **Saved shots go to the screenshots folder.** Save (Ctrl+S) writes
  `XDG_PICTURES_DIR/Screenshots/YYYYMMDD_HHMMSS.png` (local time) with no
  dialog. A taken name gets `_2`, `_3` and so on, and nothing is ever
  replaced. Every save is published on `screenshot.saved` and recorded, so
  an agent gets the latest shots from `screenshot.recent` without being
  told a path.
- **`screenshot` is an accepted name collision.**
  - Arch Linux's `extra/nwg-shell` installs `/usr/bin/screenshot`, a helper
    for that shell. It was the only owner found on 2026-10-12, checked with
    `pacman -F`.
  - In Debian trixie no package installs a `screenshot` in a binary
    directory. The name appears only inside private directories (a GIMP
    plug-in, the Qt examples), checked with the packages.debian.org
    contents search.
  - Fedora was not checked: it has no public file search that works
    without a Fedora host.
  - MixOS installs to `/opt/mixos/bin`, which comes first in its PATH, so a
    MixOS session's `screenshot` is this one. compd launches it from its
    own directory, and the desktop entry names it by absolute path.

## Why

The plain word is the right name for the plain job, and `cap` said
nothing to someone who did not already know it. The collision costs
little: nwg-shell's helper is internal to nwg-shell and is not run by name
inside a MixOS session.

Handing a shot to an agent should need no typing. A fixed folder, a name
that sorts by time, a topic on every save and a query for the latest shots
give the agent the file without the person saying where it is.

## Consequences

- AGENTS.md §3.4 lists the accepted collisions: `mix` (Elixir), `rec` and
  `play` (sox), and `screenshot` (nwg-shell).
- The `screenshot.*` verbs and its drive verbs are registered in
  `docs/docs/spec/bus/verbs.conf.mix`.
- compd's binding table gains Print, Shift+Print and Alt+Print. No F1–F12
  key is bound, bare or with modifiers: those belong to the person
  ([decision](2026-10-17-function-keys-belong-to-the-user.md)).

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-12-system-dialogs/ (source: https://mixos.dev/docs/decisions/2026-10-12-system-dialogs.md) -->

# Decision — shipped system dialogs

Status: accepted 2026-10-12. Widens the scene loader's v1 rule that only
the Scene Editor may be a dialog.

## The problem

The scene host has one dialog seat. A dialog takes it when it loads, keeps
it while loaded, takes the keyboard when it shows and gives it back when it
hides. The loader therefore refused `window.kind: "dialog"` for every
installation except the Scene Editor, so no other part of the desktop could
ask a short question, such as the name for a workspace.

## The decision

- **A system dialog** is a shipped scene template that:
  - is marked `hidden: true` in its shipped `template.conf.mix`;
  - declares `window.kind: "dialog"` in its shipped `scene.mix`;
  - is installed under its own template name.

  The loader allows it to load as a dialog. The permission is read from the
  shipped files under the templates root, never from the user-editable
  installed copy. A shipped dialog that is not hidden, a system dialog
  installed (or forked) under another name, and any other scene edited into
  a dialog are all still refused. The installed copy of a system dialog is
  the person's own, like any installed scene, and keeps the permission its
  name carries.
- **Hidden templates stay out of the gallery**, so people still see one
  dialog scene, the Scene Editor.
- **A system dialog holds the seat only while it shows.** Its owner installs
  it disabled and enables it to ask. The dialog disables itself once its
  dialog is hidden by Save, Cancel or Esc, or by another dialog taking the
  seat.
- **The Scene Editor.** By default the Scene Editor is a native application
  window, not a dialog scene. It never uses the dialog seat, so it and a
  system dialog can both be open. The legacy scene frontend
  (`SCENES_EDITOR_APP=0`) is a dialog scene and keeps priority:
  - opening it pre-empts a system dialog;
  - it holds the seat for as long as it is loaded, hidden or not, so a
    system dialog asked for meanwhile is refused (`DIALOG_BUSY`) and its
    owner says so;
  - unloading it (`scenes.editor.close {unload: true}`) frees the seat.
- **One system dialog at a time.** A dialog asked to show for something else
  while it is already showing (another workspace) refuses until it is saved
  or cancelled. A failed start is rolled back (the scene is disabled again),
  and the dialog releases the seat only when the host's current state shows
  it hidden, never on a stale notice.
- **Focus.** A dialog takes the keyboard when it maps and gives it back when
  it hides. Its `window.autofocus` field gets focus as it opens.

The first system dialog is `share/scenes/workspace-rename`. Right-clicking a
pager button opens it for that workspace, and it names the workspace through
`comp.workspace.rename`.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-13-bundled-font-licences/ (source: https://mixos.dev/docs/decisions/2026-10-13-bundled-font-licences.md) -->

# Bundled fallback font licences

**Status: accepted, 2026-10-13.**

MixOS uses Inter and JetBrains Mono for its application typography and retains
egui's bundled fallback fonts for additional glyph and emoji coverage.
The pinned `epaint_default_fonts` 0.36.2 package declares
`(MIT OR Apache-2.0) AND OFL-1.1 AND Ubuntu-font-1.0`.

The dependency checker permits those licences only for that exact package
version. The general permissive code-dependency allowlist is unchanged.
Updating the font bundle version requires reviewing the exception and the
shipped licence files together. This does not change MixOS's own MIT OR
Apache-2.0 licence or replace its primary typefaces.

The bundled font notices and complete upstream licence texts are recorded in
`libs/toolkit/assets/fonts/fallbacks/`. Their hashes, the primary-font licence
texts and the Lucide licence are pinned in the toolkit's licence manifest.
`libs/toolkit/scripts/install_licenses.mix` verifies that manifest and installs
the notices under `share/licenses/toolkit/`. Desktop release archives and the
native image builder invoke this same installer.

The font licences permit embedding and redistribution subject to their
conditions, including preservation of copyright and licence notices and
restrictions on renaming modified fonts. We keep the upstream font files
unmodified. References: [SIL OFL 1.1](https://openfontlicense.org/open-font-license-official-text/)
and [Ubuntu Font Licence 1.0](https://canonical.com/legal/font-licence).

Lucide SVGs supply interface icons. Noto Emoji remains a text/emoji fallback;
removing Material Symbols does not remove emoji coverage.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-13-desk-and-deskd/ (source: https://mixos.dev/docs/decisions/2026-10-13-desk-and-deskd.md) -->

# Decision — desk and deskd

Status: accepted 2026-10-13. Follows the multi-call precedent of
[rec and play](2026-10-11-rec-and-play.md); within the naming rules of
[the source layout](2026-10-04-source-layout.md) (AGENTS.md §3).

## The decision

- **`desk` is the desktop's applications in one binary.** The GUI apps
  (busviewer, ced, dopus, prefs, screenshot, backdrop, and term when it
  lands) build into one executable, `desk`. Each app's name is a link to
  it in `/opt/mixos/bin`, and the binary runs the app it was started as.
  `desk <app> [args]` does the same, and `desk` alone lists the apps.
- **`deskd` is the desktop's session services in one binary**, by the same
  rule: the services a desktop session runs and a headless host does not
  (portald, settingsd, editd). Each keeps its name as a link and its own
  unit.
- **What stays separate:**
  - `mix` (the shell, on every host);
  - `noded` (the broker, on every host, desktop or not);
  - `hostd` (the host's information and privilege service, on every
    host). It runs as root and is the one way to elevate: it never shares
    a binary with `deskd` or anything else that runs as the session
    account;
  - `compd` (the compositor: its robustness and its dependency set are
    its own).
- **Each app and service is still its own process.** A crash ends one app,
  not the others; units, desktop entries and scripts keep calling
  `/opt/mixos/bin/<name>`.
- **Each crate keeps a `run` entry point and its own `main`**, so
  `cargo run -p ced` and every per-app test work as before. The multi-call
  crates only dispatch. Identity (build info, app ID, version) is passed by
  each app's `run`, never taken from the multi-call crate's package.

## Why

Every egui app links its own egui, wgpu, naga, fonts and icons: about
22 MB of each binary is that shared runtime, and an app's own code is 1 to
3 MB. A measured prototype put six apps (backdrop, busviewer, ced, dopus,
prefs, screenshot; release profile, fat LTO) in one binary: 128.7 MB
separately, 29.4 MB together. Link-time optimisation removes the
duplicates, and running apps share one mapped executable, so the runtime
is in memory once.

Rust dynamic libraries were rejected: there is no stable Rust ABI, libstd
would ship as a shared library, LTO stops at the boundary, and generic code
is still copied into each app. A C-ABI wrapper around egui would be a
second UI API.

## The names

- `desk` and `deskd` are plain nouns, a pair in the `<role>d` convention
  (§3.1, §3.4), unique in the dependency graph, and installed by no Arch
  package (checked 2026-10-13; the other distributions' file lists are
  checked before first use).
- The layers read in order:
  - **MixOS** is the system.
  - **mix** is its shell and language.
  - **noded** is the broker on every host.
  - **hostd** is the host's information and privileged actions, as root,
    on every host.
  - **compd**, **desk** and **deskd** are the desktop.

  A headless host runs `mix`, `noded` and `hostd`; a desktop adds the
  other three.
- A machine running the desktop is "a desk"; numbered instances (a desk
  and its number) are names of machines, not of these binaries.

## Not decided here

When each app and service moves in, the install layout of the links, and
how `component_install.mix` and the unit collector treat a multi-call
binary. Those land with the implementation.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-13-instance-verb-families/ (source: https://mixos.dev/docs/decisions/2026-10-13-instance-verb-families.md) -->

# Instance verb families (schema 3)

Status: accepted, 2026-10-13.

## Context

Some Bus verbs are not one name. A bridge serves one service per instance it
runs, so a verb such as `<instance>.status` exists once for each running
instance, and the instances are known only at runtime. The verb registry
(`docs/docs/spec/bus/verbs.conf.mix`, checked by `tools/verb_registry.mix`) listed
only concrete names, so there was no place to record these verbs or to check
that a name could not be taken by an instance.

## Decision

1. **Schema 3 is additive.** The `verbs` list is unchanged from schema 2, and
   its entries stay concrete in this migration. A new `families` list follows
   it. A family does not stand in for a concrete verb, in the registry or in
   code. This decision does not settle whether a concrete verb may later be
   expressed as a family; that would take its own decision.

2. **Schema 2 takes no families.** A schema 2 file with a `families` key is
   refused, empty or not, so an unvalidated list cannot pass as legacy data.
   Schema 1 stays refused. Schema 3 requires a `families` list, even an empty
   one.

3. **Family fields** are exactly `pattern`, `owner`, `members`, `version`,
   `status`, `class`, in that order, one entry per line, written
   `pattern:"…"` (never `name:"…"`). The fields are validated like the verb
   fields: release versions, the statuses and classes below, and component
   names for the owner.

4. **Pattern.** It is `<app>.<suffix>`, where the literal `<app>` stands for
   the instance name and the suffix is one or more lower identifier segments
   (`call`, `ui.tree`). Catch-all patterns are refused, and each pattern is
   unique across all owners.

5. **Members.** `members` is either `"instances"`, meaning the members are
   runtime instances and are not listed, or a nonempty list of unique Bus
   service names.
   - Families of one owner may share a listed member, so one service can
     implement several families (for example `<app>.call` and `<app>.status`).
   - A listed member used by families of two owners is refused.
   - A listed member may equal the first segment of concrete verbs only when
     every such verb has the family's owner, and the expanded wire name
     (`member.suffix`) is not itself a concrete verb. An exact concrete
     duplicate is always refused.
   - Any other collision is refused, not resolved.

6. **Class semantics** are those of
   `docs/docs/decisions/2026-10-11-verb-classes.md`. A family records its class as
   written; the gate checks that it is one of the four classes and does not
   infer it from the handler. The `bridged` families are classed:
   - `<app>.call` and `<app>.execute` are `intent`.
   - `<app>.commands`, `<app>.inspect` and `<app>.status` are `query`.
   - `<app>.screenshot` is `intent`. A capture alone would be a query (a query
     may write the artefact it returns), but its `focus` option can bring the
     window forward, which another caller sees. A family has one class, so the
     verb is intent whether or not `focus` is set.

7. **Family ownership.** A family with `"instances"` belongs to its owner
   component only. The source check accepts an `on @.<suffix>` declaration
   only from the component whose `"instances"` family has that suffix. Every
   such family must be declared at least once in its owner's runtime code.
   Another component declaring the same suffix is refused as a wrong owner.

8. **Declarations come from the native parser.** The source check reads the
   handler metadata of the native `mix lint --json` (lint schema 2). There is
   no fallback reader.

## Checks and their limits

- **Source check (`--source ROOT`).** The gate reads the `.mix` files under
  `apps/`, `services/`, `cli/` and `libs/`. It skips `tests/`, `test/`,
  `benches/`, `fuzz/`, and `*.conf.mix`/`*.spec.mix` files. The declarations
  come from the native parser: each file is passed to `mix lint --json FILE`,
  and every handler whose command starts with `@.` is a declaration. The
  handler metadata is the parsed AST, so nested and duplicate declarations
  count, and text inside quotes, heredocs and comments does not. The source
  is never executed.
  - **Feature detection.** The lint document is schema 2, with a `handlers`
    list. A Mix that answers without it fails with `native Mix lacks parsed
    handler metadata; rebuild current Mix`. There is no fallback parser.
  - **Fail-closed.** A file that does not lint (nonzero exit), output that is
    truncated, a document that is not valid JSON, a wrong `tool`, `files` or
    `summary`, or a handler with a bad `command`, `file` or `line` each make the
    check fail. An unreadable source root or nested source directory fails the
    check too. Diagnostics and source text are never printed.
  - **Walk.** The gate lists each directory with the native `ls` and reads each
    entry with `stat`, recursing by hand. The native `glob` and `walk` skip an
    unreadable directory without an error, so they are not used to prove an
    absence. Test, bench and fuzz directories are skipped before the recursion.
    The source root and each kind directory must be a plain directory (a
    symlink is refused). Trailing slashes are dropped before that check, so a
    symlink named with one is refused too. Only the last component of each such
    path is checked without following links; a symlink in a directory above it
    is followed, as any path is. A symlink anywhere else in a kind's tree is
    refused, and so is a directory that cannot be listed.
  - The check is **structural**. It proves that a handler for the suffix sits
    in the owner's code, not that it registers at runtime. The owner's Bus
    suite tests the runtime registration.
- **Instance check (`--instances DIR`).** Each `*.conf.mix` file stem in DIR
  is checked against the Bus name rule, the reserved names (the `mixos-`
  prefix, `noded` and `noded-*`, the broker's session-name shape), the first
  segments of concrete verbs and the listed family members. A name that is a
  concrete prefix or a listed member is refused whatever its owner. DIR must be
  a plain directory (a trailing slash does not get a symlink past this), and an
  unreadable DIR fails the check. Any path may hold glob characters, since `ls`
  takes a name, not a pattern. Configs are flat by design: the gate lists the
  top level only, dot files included. A `*.conf.mix` entry in a subdirectory,
  and any other file, is ignored; none of them is a runtime config, and the gate
  neither recurses into them nor reads their contents. Symlinks, directories and other non-regular files named
  `*.conf.mix` are refused, and so are configs when the registry has no
  instances family. Config contents and tokens are never read.
- **Offline.** Neither check touches the network or a running broker. A name
  that passes here is a name the Bus will accept, as far as the Bus's own
  rules go. A runtime refusal (for example, a broker that has already
  registered the name) is still possible and is not this gate's concern.
- **Mesh exposure is unchanged.** Nothing in the gate or the registry changes
  what any mesh peer can reach. The families describe names; a service's own
  configuration decides what it serves.

## Consequences

- Schema 2 files stay valid as long as they carry no families.
- The source check needs a Mix whose `mix lint --json` reports handler
  metadata (lint schema 2). An older Mix fails the source check until it is
  rebuilt; the gate does not fall back to another reader.
- A new instance family needs a family entry, and an `on @.<suffix>` handler
  in its owner's code, in the same change.
- Public examples use only the neutral fixture names `fakeapp`, `demod` and
  `otherd`. No runtime instance name belongs in this repository's docs.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-14-session-icon-stroke-and-type/ (source: https://mixos.dev/docs/decisions/2026-10-14-session-icon-stroke-and-type.md) -->

# Decision — session icon stroke and type

Status: accepted 2026-10-14. Extends
[icons and type](2026-10-09-icons-and-type.md) and the
[keymaps in settings](2026-10-11-keymaps-in-settings.md) precedent.

## The decision

- **Four optional session choices** join the profile's appearance:
  `appearance.icon_stroke` (1.0 to 3.0 in quarter steps, on Lucide's 24-unit
  grid), `appearance.font_family`, `appearance.font_weight` (100 to 900 in
  steps of 100) and `appearance.mono_family`.
- **None means the design's own value**: the `icon.stroke_width` token (the
  approved 1.5 baseline), Inter, the scheme's own weight, and JetBrains Mono.
- **The stroke baseline stays 1.5.** It is the approved baseline (hub plan
  `2026-10-13-lucide-panel-icons`), and the shipped token matches it.
- **A user weight replaces the weight locked by the chrome schemes.** Body
  text takes the chosen weight; headings keep their design offset above it.
- **System fonts are runtime data.** A chosen family is read from the host's
  font files when it is available. Nothing is embedded, so the bundled-font
  licence obligations in
  [bundled font licences](2026-10-13-bundled-font-licences.md) are unchanged.
  A missing or still-scanning family falls back to the bundled Inter, which
  stays behind any system font as glyph fallback.
- **Carried by the existing carrier.** `settings.apply` takes the new keys,
  `prefs.appearance.set` is the Prefs front verb, and every app follows the
  summary topic as it does for the scheme. No new verb.

## Why

The icon stroke and the typeface are the two things a person most often
wants to tune, and they are session-wide, so they belong in the profile and
not in each app. Making them optional keeps every existing profile's digest
valid, so nothing is migrated.

## Digest and rollback

- The new `Appearance` fields are omitted when unset, like `style`,
  `decorations` and `caption_side`. A profile that sets none of them
  re-serialises byte for byte.
- The store is format 3. A profile that sets any of the four keys will not
  load in a format-2 build, because `Appearance` denies unknown fields. Roll
  back by resetting the keys first, with `settings.reset` or a null value.

## Scope

- **Apps following the session look** (busviewer, ced, dopus, screenshot)
  pick the choices up through `session_look` and `toolkit::install`, with no
  edits beyond the overlay.
- **Prefs** builds its own theme from its draft; it is updated alongside.
- **backdrop** draws textures only, with no text or icon widgets, and
  installs once at startup. It is out of scope.
- **compd's title bars** use their own theme builder and an embedded-only
  font database. They follow in a later slice, once the contract is proven
  nested; the `Effective` and `ChangePlan` fields are already in place.
- **Profiles that name their own design source** receive no session look,
  so they keep their design's own values. The choices are still saved.

## Consequences

- `libs/settings` 0.6.0 and store format 3. The change is additive for every
  profile that does not set a choice.
- `libs/toolkit` gains a theme overlay applied by `session_look`, a stroke
  precedence (overlay, then token, then `DEFAULT_STROKE` 1.5), a weight
  override that beats the chrome lock, and a background scan of the host's
  font files.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-16-email-accounts-in-settings/ (source: https://mixos.dev/docs/decisions/2026-10-16-email-accounts-in-settings.md) -->

# Decision — email accounts live in settingsd, passwords in the app

Status: accepted 2026-10-16. Applies to the [email app](../../email/README.md)
and the [settings contract](../spec/settings/README.md) (`email.*`, contract
0.8.0).

## The decision

- **Non-secret account settings live in settingsd.**
  - The session profile's `email` group holds every account, in tree
    order: `id`, `name`, `url`, `email`, `ca_path`, `enabled` and
    `signature`. It also holds `default_account` and the mail options
    (`page_size`, `mark_read_on_open`, `confirm_delete`).
  - `email.accounts` is replaced whole by one fenced `settings.apply`.
    A change that removes the default account resets
    `email.default_account` in the same batch, so settingsd never holds
    half a change.
  - The email app follows the group through the session-profile summary
    and reconciles its connections live.
  - Ids are minted once (`acct-` and 12 hex digits) and never reused for
    another account.
- **Passwords never enter settingsd.**
  - settingsd publishes retained snapshots on the Bus, which every
    client can read. The `email` group therefore has no password field,
    and every account record refuses unknown keys, so an apply carrying
    `password` is refused.
  - Each password lives in the email app's own file,
    `<config>/secrets.conf.mix` (`{schema_version: 1, passwords: {id: …}}`).
    The directory is 0700 and the file 0600, it is replaced atomically,
    and the poison-pill law applies: a malformed file is never
    overwritten.
  - Only the email app writes that file, and a password leaves it only
    toward the account's own server.
- **A password is reachable only through a write-only verb.**
  - `email.account.password.set {id, password}` stores a password and
    reconnects the account.
  - `email.account.set` may carry `password` too. It is held only once
    settingsd has accepted the account.
  - No verb, topic, log line or diagnostic returns a password.
    `email.accounts` and `email.info` report `has_password: bool`.
- **Prefs is the configuration surface.**
  - Accounts are added, edited, removed, reordered and made the default
    in Prefs' Email section, which writes `email.*` through settingsd. It
    sets passwords through `email.account.password.set`, starting Email
    first if it is not running.
  - The email app has no account form of its own. With no account, or
    with an account that failed or has no password, it offers Open Email
    Settings.
- **The app keeps a cache of the last accounts it read** in its own
  config (schema 2, which holds no secret). When settingsd is absent, the
  cached accounts open read-only and the status line says so. Account
  writes are refused with `UNAVAILABLE` until settingsd is back.
- **The single account of an older install migrates once, losing
  nothing.**
  - The account comes from the schema-1 `config.conf.mix` and is given an
    id derived from its URL and address.
  - Its password is written to the secrets file first. An inline CA
    bundle goes to a 0600 file beside it, which the account then names by
    `ca_path`.
  - The account is then applied to settingsd, and made the default when
    there is none. An account settingsd already holds with the same URL
    and address is adopted instead.
  - The schema-1 file is kept, and is written back unchanged, until
    settingsd has the account and its password is durable under that
    account's id. Only then is it rewritten as schema 2.

## Why

- **The Bus must not carry secrets.** The session profile is retained
  and broadcast so that any app can follow it. A password there would be
  readable by every Bus client and would appear in every snapshot and
  backup of the profile.
- **One place to configure.** Terminal preferences already live in
  settingsd and are edited in Prefs. Mail accounts are the same kind of
  thing, and a second account form inside the app would drift from it.
- **Automation needs the accounts as data.** An agent can list, add or
  disable an account through `settings.apply` or the email verbs. It
  never handles a secret, unless it is the one supplying the password.

## Consequences

- **A settings read never deletes a password.** Only an explicit action
  through Email does: `email.account.remove`, or
  `email.account.password.set` with an empty password. An account removed
  elsewhere (in Prefs, by a reset) drops the app's client and view, and
  leaves its entry in the 0600 secrets file, unused. That is accepted:
  losing a password to a misread would be worse.
- **An empty account list is not a removal of them all.** settingsd omits
  the group at its defaults, so an older settingsd, a reset and a profile
  without the group cannot be told apart. While accounts are shown, such
  a read keeps them (views, connections, passwords) with a status note,
  until a read lists accounts again or one is removed through Email.
- **Migration steps land in order, each durably.** First the password is
  saved to the secrets file. Then the account is applied to settingsd.
  Then, if settingsd held it under another id, the password is saved
  under that id. Only then is the schema-1 file rewritten. A failure at
  any step, including a poison-pill refusal to write the secrets file,
  leaves the schema-1 file untouched, and the next launch runs the
  migration again.
- A conflicting change (two writers at once) is refused by the fence.
  The email app reads again, retries a few times, and then reports
  `CONFLICT`.
- MixOS has no keyring yet. The secrets file has the same trust as the
  app's other private files. A keyring, when it lands, replaces only that
  file; the settings group and the verbs stay as they are.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-16-monitord-and-monitor/ (source: https://mixos.dev/docs/decisions/2026-10-16-monitord-and-monitor.md) -->

# Decision — monitord and Monitor

Status: accepted 2026-10-16.

## The decision

- **`monitord`** (`services/monitord`, kind service, layer core) runs once
  per host as its own unprivileged user. It samples the system and its
  processes, keeps recent history in memory and longer history in SQLite,
  and answers read verbs on the Bus. It runs headless; a mesh node with no
  desktop is a first-class host.
- **`Monitor`** (`apps/monitor`, binary `monitor`, app id
  `dev.mixos.monitor`) is the egui task manager: processes, performance
  graphs, apps, services and users, in the shape people know from Windows
  Task Manager and GNOME Mission Center. It reads everything through
  monitord's verbs, never from `/proc` itself, so the same window shows any
  node on the mesh (`monitord.<node>.bus`).
- **monitord observes; it does not act.** No verb signals, renices or
  stops anything.
  - The `monitord` command line acts locally as the person who runs it:
    `monitord signal` and `monitord renice` make the system call directly
    and the kernel decides, exactly like `kill` and `renice`.
  - Acting across users or across the mesh is hostd's job, as closed verbs
    behind grants ([hostd decision](2026-10-12-hostd.md)), added one
    reviewed verb at a time.
- **A personality of the system binary.** monitord's library exports
  `main`; `cli/system` carries it
  ([one system binary](2026-10-12-one-system-binary.md)). The unit runs
  `/opt/mixos/bin/monitord serve`.

### History

| Tier | Resolution | Kept | Where |
|---|---|---|---|
| live | the sample interval (1 s) | 10 minutes | memory ring |
| short | 1 minute (avg, min, max) | 7 days | SQLite |
| long | 1 hour (avg, min, max) | 1 year | SQLite |

- SQLite (`rusqlite`, already in the system binary through the shell)
  holds only system-wide series: CPU, memory, swap, load, pressure, and one
  series per network interface and disk. Per-core and per-process series
  live in memory only; they are too many to keep.
- The database is `/var/lib/monitord/history.db`, owned by monitord. It is
  a cache: deleting it loses history, nothing else.
- Retention is configuration, so a small node can keep less.

### Sampling

- System-wide sampling runs all the time at 1 s. It reads a handful of
  `/proc` files and costs next to nothing.
- The process table is sampled only while someone is reading it: a
  `monitord.processes` call holds the process sampler on for 30 s. An idle
  mesh node does not walk `/proc` every second. A cold call samples twice,
  a short interval apart, so CPU percentages are never zero by default.
- monitord reads what an unprivileged user can read. A process's I/O
  counters and some of its details are readable only for monitord's own
  processes; elsewhere those fields are absent, never guessed. Wider reads
  are a later, reviewed capability (`CAP_SYS_PTRACE` or a hostd verb).

### On the Bus

- Read verbs (all queries): `monitord.status`, `monitord.snapshot`,
  `monitord.processes`, `monitord.process`, `monitord.series` and
  `monitord.history`. The verbs and their bodies are documented in the
  [monitord manual](../../monitord/README.md).
- A retained topic, `monitord.summary`, carries a small system summary
  every 5 s, so a dashboard of the whole mesh subscribes instead of
  polling.
- The reply bodies are a public contract (`contract = "public"`), versioned
  in monitord's changelog. Monitor depends on the JSON, not on monitord's
  Rust types. If a second component needs those types, they are promoted to
  a library by review (AGENTS.md §2.2).

### What it is built from

- **Phase 1 reads the kernel directly.** `/proc` and `/sys` parsers are
  small, and each one reads from a root directory, so tests run against a
  fixture tree, the way hostd's do. No collection crate is needed yet.
- **Later phases use permissive crates,** each checked against `deny.toml`
  when it enters:

  | Area | Crate |
  |---|---|
  | NVIDIA | `nvml-wrapper` (MIT OR Apache-2.0) |
  | AMD | `libamdgpu_top` (MIT) |
  | Intel, and GPU use per process on every vendor | `qmlib` (Apache-2.0) |
  | systemd units, login sessions | `zbus_systemd` (MIT OR Apache-2.0) |
  | battery | `starship-battery` (ISC) |
  | graphs, tables (Monitor) | `egui_plot`, `egui_table` (MIT OR Apache-2.0) |

- **Code may be lifted** from bottom (MIT) and systemd-manager-tui (MIT),
  with its notice kept (AGENTS.md §4).
- **GPL and other copyleft monitors are reference only:** Mission Center
  and magpie, Resources, nvtop. Nobody copies or translates their code.
  Where one of them shows *what* to read, the reader is written fresh from
  the kernel's documentation.

### Phases

1. monitord: CPU, memory, swap, pressure, load, disks, network interfaces,
   the process table and tree; history; the Bus verbs and topic; the command
   line, with local `signal` and `renice`.
2. Monitor: the egui window over phase 1, any node on the mesh.
3. GPUs: NVIDIA, AMD and Intel, with use per process.
4. systemd services and the Apps view (processes grouped by application).
5. Sensors, fans, battery, power.
6. Privileged readings (per-process network bytes over eBPF, SMART, RAPL
   energy, DMI) through a reviewed capability or hostd verbs.

## Why

- Every node on the mesh should be able to say what it is doing, in one
  shape, to any agent or window that asks, without ssh.
- The split between a headless sampler and a window is already the right
  one in Mission Center (magpie and its GTK frontend), but that code is
  GPL-3.0 and MixOS is MIT OR Apache-2.0. Permissive Rust crates cover
  most of the same ground, and what they don't cover is small.
- Keeping monitord read-only keeps it unprivileged, so it can run
  everywhere. Killing a process is already a kernel-checked system call for
  the local user; across users or nodes it is a privileged change, and
  those go through hostd.

## Consequences

- noded's built-in `mon` module (`mon.status`, `mon.processes`,
  `mon.props.*`) is superseded. Its verbs were never registered and nothing
  in the tree calls them. It is removed once monitord is installed on the
  mesh.
- monitord adds a system user, `monitord`, and the state directory
  `/var/lib/monitord`.
- Monitor's graphs and tables record their performance workloads (a
  2,000-process table, a 64-core grid) before they are optimised
  (AGENTS.md §4.1).

## Amendments

### 2026-10-16: Monitor's End task and Kill, and its widgets

- **Monitor acts on this node's processes the way the command line does.**
  End task (SIGTERM) and Kill (SIGKILL) are local system calls made as the
  person running Monitor, and the kernel decides. They are off while
  another node is shown, and no Bus verb of monitord's is involved. Acting
  on another node, or as another user, stays hostd's.
- **Phase 2 adds no graph or table crate.** The graphs are painted
  directly: a 64-core grid is 64 graphs a frame, which a plotting widget
  per graph would make heavy. The process table is `egui_extras`'
  `TableBuilder`, already in the tree. `egui_plot` and `egui_table` stay
  candidates for when a view needs what they add (zoom, axes, ragged rows).

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-16-site-url-layout/ (source: https://mixos.dev/docs/decisions/2026-10-16-site-url-layout.md) -->

# Decision — site URL layout

Status: accepted 2026-10-16, after review by two independent reviewers.

## The question

mixos.dev serves two readers from the same files. A person in a browser
gets a static HTML page, and nothing needs JavaScript to render. An agent
or script on any machine fetches the same page as Markdown and starts from
`/llms.txt`. MixOS will grow to hundreds of apps, services, libraries and
tools over the next few years. How should the URL space be organised, so
that an address, once published, never has to change?

## The decision

### Two namespaces

- **Each component's documentation is at the top level, under the
  component's name.** Examples: `/mix/`, `/term/`, `/compd/`, `/hostd/`,
  `/noded/`.
- **Everything that is not a component lives under `/docs/`.** That covers
  guides such as `/docs/try/` and `/docs/drive/`, plus
  `/docs/decisions/`, `/docs/spec/`, `/docs/dev/`, `/docs/releases/`, and
  the generated indexes below. The site's global navigation has a Docs
  entry that leads there.

### Component names

- A component's name is the `component` declared by its principal package
  in `[package.metadata.mixos]`, or by its `component.mx`. Component names
  are already plain, unique across the workspace and never reused (see
  [source layout](2026-10-04-source-layout.md)), so an address can be
  built from the name alone.
- A component name starts with a lowercase letter and contains only
  lowercase letters, digits and hyphens.
- **Two names are reserved: `docs` and `v`.** The component metadata gate
  refuses them, so a forbidden name is caught when the component is
  created, not when the site is built.
- Site machinery uses names no component can take. Generator inputs and
  assets live in `_build/` and `_web/` (renamed from `build/` and `web/`),
  and root files (`index.html`, `404.html`, `llms.txt`, `llms-full.txt`,
  `sitemap.xml`, `robots.txt`, `CNAME`, the favicons) all contain a dot or
  start with an underscore.
- **Mix's names.** The `mix` component is the language library, so `/mix/`
  is the Mix language manual and the same pages `mix man TOPIC` reads. The
  `mix` binary's component is `system` (`/system/`), and the shell is
  `mix-shell` (`/mix-shell/`). Each links to the others.

### Where pages come from, and their addresses

The path of a source file relative to the site root (the repository's
`docs/` directory) determines its address. The table gives every
mapping:

| Source | HTML | Markdown |
|---|---|---|
| `docs/<name>/README.md` | `/<name>/` | `/<name>/README.md` |
| `docs/<name>/<page>.md` | `/<name>/<page>/` | `/<name>/<page>.md` |
| `docs/docs/<page>.md` | `/docs/<page>/` | `/docs/<page>.md` |
| `<component dir>/CHANGELOG.md` (mirrored) | `/<name>/changelog/` | `/<name>/changelog.md` |
| Generated index pages | `/docs/<index>/` | `/docs/<index>.md` |

- **The Markdown is published at its source path.** Relative links inside
  it therefore resolve correctly under ordinary URL resolution. An agent
  builds a component's Markdown address as `/<name>/README.md`. The
  generator checks every relative link in both formats.
- **Hand-written component documentation lives in `docs/<name>/`.** That
  is its one canonical copy. The component's own directory keeps a short
  `README.md` that points to the page, so someone browsing the source
  finds it.
- **`CHANGELOG.md` stays beside the code**, where releases update it. Only
  the principal package's changelog is published. The published copy is
  generated and never edited. Relative links in it are rewritten to the
  source on GitHub. A component with no changelog has no changelog page.
  `changelog` is therefore a reserved page name inside every component.
- **The doubled `docs/docs/`** is accepted. It keeps the rule that the
  source path determines the address, without a rename table.
- **Generated pages have a Markdown twin** like every other page.
- **HTML is the canonical address.** Each HTML page names its Markdown as
  `<link rel="alternate" type="text/markdown">`. `sitemap.xml` lists HTML
  only.

### Navigation from metadata

- **The URL never encodes kind, layer or install profile.** These change
  over a component's life: a library is promoted, or a desktop service
  becomes useful headless.
- `/docs/desktop/` and `/docs/server/` are generated index pages listing
  components by their declared install `profiles`. A component in both is
  listed in both, with one page. Components in the `base` profile are
  listed under a reader-facing heading such as "Core components". The word
  `base` stays in the installation docs.
- `/docs/components/` is the one complete, generated component index,
  giving each component's name, kind, profiles, source path and page. It
  replaces the hand-run `docs/docs/dev/components.md` (formerly
  `docs/dev/components.md`).
- Until `profiles` is declared everywhere, the indexes list undeclared
  components as unclassified. They never guess from `layer`.

### Agents

- `/llms.txt` lists every section, with absolute Markdown URLs: one line
  per component (with its kind and profiles) and one per page under
  `/docs/`. Every published document can be reached from it.
  `llms-full.txt` remains an optional single file.
- Every page states that it describes the current `main` branch.

### Every component has a page

- The principal package of every component (app, service, cli or lib) and
  every Mix component must have `docs/<name>/README.md`. Private crates and
  `tool` and `test` packages are excluded.
- **A component without a page fails the site gate.** While existing
  components are being documented, the ones still missing are named in an
  exception list in `site.conf.mix`. That list may only shrink, and a new
  component cannot be added to it.

### Addresses are permanent

From the day this decision is accepted:

- A profile change or a source move never changes an address.
- An address that goes away keeps working in both formats: an entry in
  `site.conf.mix`'s `redirects` for browsers, plus a short Markdown page at
  the old `.md` address that names the new one, because an agent fetching
  Markdown does not follow an HTML redirect.
- A split leaves a page that links to its successors. A retired component
  keeps a retirement page, which stays listed in `/llms.txt`, and its name
  is never reused.

### Versions

`/v/` is reserved for versioned copies of the site. How they work is
decided before the first stable release.

## Why

- **One namespace for components, one for everything else.** An address
  either names a component or starts with `/docs/`. Only two names are off
  limits for components.
- **Names are the most stable thing a component has.** The source-layout
  decision rejected splitting the source tree by desktop, server or core,
  because a component could plausibly sit in either of two places and
  moves between them. Putting that axis into URLs would have recreated the
  problem where a move is most costly.
- **It matches what already works.** `/mix/` and the existing component
  pages (`/hostd/`, `/noded/`, `/prefs/`, `/backdrop/`, `/screenshot/`,
  `/dopus/`) are already at the top level, and `mix man` already fetches
  `/mix/<topic>.md` and `/mix/README.md`.
- **One canonical copy.** Keeping hand-written docs in `docs/` rather than
  beside the code relaxes the source-layout principle that a component is
  self-contained. That is deliberate: documentation for readers has one
  home, one navigation and one gate. Code, tests and changelogs stay with
  the component.

## Rejected

- **Mirror repository paths** (`/apps/term/`, `/libs/bus/`). The address
  is predictable, but it encodes kind, and it moves when a component moves
  in the source tree.
- **Sections by install profile** (`/desktop/term/`, `/server/maild/`,
  `/base/noded/`). Profiles are deployment data that change, a component
  can be in two, and `server` is empty today. A profile change would move
  a public URL.
- **A component prefix** (`/c/term/` or `/components/term/`). It protects
  the component namespace, but `/docs/` does the same job from the other
  side, with shorter, more readable component URLs.
- **Docs beside the code, mirrored into the site.** That makes two copies,
  needs a freshness gate and a mapping table, and splits navigation.
- **A `/<name>.md` alias for each component page.** Relative links in it
  would resolve against the wrong directory.
- **Mapping `/docs/` to a differently named source directory** (for
  example `docs/guides/`). It avoids `docs/docs/`, but it adds a permanent
  rename table.

## Consequences

- Nobody depends on the current URLs, so this one move keeps no old
  address. The permanence rules apply from acceptance.
- The root pages that are not components move under `docs/docs/`: `try`
  and `drive`, plus `decisions/`, `spec/` and `dev/`.
- Root pages that describe a component become its page
  (`docs/hostd.md` becomes `docs/hostd/README.md`, and so on). Four were
  named after a topic rather than their component, and take the
  component's name: `edit` becomes `editd`, `portal` becomes `portald`,
  `bridge` becomes `bridged` and `releases` becomes `releasesd`. (The
  first draft of this record listed `edit`, `bridge` and `releases` as
  non-component pages; each documents one service.)
- The component READMEs beside the code move into `docs/<name>/README.md`,
  leaving a pointer behind. The CHANGELOGs stay where they are.
- `docs/build/` and `docs/web/` become `docs/_build/` and `docs/_web/`.
- The component metadata gate gains the name grammar and the reserved
  names.
- `gen-site` gains the output-collision check (every HTML, Markdown, asset
  and generated output), the changelog mirror, the generated indexes and
  their Markdown twins, the alternate links, the missing-page gate with its
  exception list, and a grouped `llms.txt`.
- Every link to a moved page is updated, including in AGENTS.md and the
  decision records.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-17-function-keys-belong-to-the-user/ (source: https://mixos.dev/docs/decisions/2026-10-17-function-keys-belong-to-the-user.md) -->

# Decision — the function keys belong to the user

Status: accepted 2026-10-17. Amends [egui applications](2026-10-09-egui-applications.md)
(AGENTS.md §4.1) and builds on
[key bindings are desktop settings](2026-10-11-keymaps-in-settings.md).

## The decision

- **F1–F12 belong to the person.** No program gives a command a default
  chord on a function key: not bare, and not with Ctrl, Alt, Shift or any
  mix of them. This covers every command registry and every default key
  table, in apps, the desktop furniture and the session.
- **The person may bind them.** A keymap entry in the desktop profile
  (`keymaps.<app>.<action>`, applied by `Registry::rebind`) may put any
  command on any function key, with any modifiers. Nothing in this decision
  narrows what a person can bind.
- **A command that wants a key gets another one.** Conventional non-F
  chords are used where they exist:
  - Keyboard Shortcuts: `Ctrl+/`;
  - Refresh: `Ctrl+R`.

  Where there is no good chord, the command keeps its menu row and has no
  default key.

### What is allowed and what is not

| | Allowed |
|---|---|
| A default chord on F1–F12, any modifiers, in any registry or key table | no |
| A further default chord (`Registry::add_shortcuts`) on F1–F12 | no |
| A person's keymap override onto F1–F12, any modifiers | yes |
| An application passing a function key through as input (a terminal sending its escape sequence to the program inside) | yes: that is not a binding |
| The keyboard layout's own keysyms (`XF86Switch_VT_n` from Ctrl+Alt+Fn) | yes: they are the layout's, and compd binds the keysym, not the F-key |

## How it is enforced

- **The toolkit's command registry refuses one.** `Registry::add` (and so
  `add_toggle` and the theme menu) and `Registry::add_shortcuts` panic when a
  default chord's key is F1–F12, whatever its modifiers. The message names
  the command id and this decision. Every app builds its registry in its
  own tests, so a violation fails `cargo test` before it can ship.
- **`Registry::rebind` is not checked.** It applies the person's bindings,
  and those may use any key. The toolkit's tests prove both sides: default
  bare, Ctrl and Shift function-key chords are refused, and an override to
  F5 binds and runs.
- **One list.** `toolkit::keymap::USER_KEYS` and `toolkit::keymap::user_only`
  name the keys. A default key table that is not a toolkit registry checks
  its chords against them in its own test.
- **AGENTS.md §4.1** states the rule.

## Why

- **The person's own bindings come first.** People put their global
  shortcuts, compositor actions, assistive tools, dictation, push-to-talk
  and macros on the function keys, because those keys are otherwise spare.
  A default an app ships on one either shadows that binding while the app
  has focus or is shadowed by it, and the person loses either way.
- **Predictability across apps.** F1, F2, F5 and the rest mean different
  things in different programs elsewhere. When no MixOS program claims
  them, a function key does in every app exactly what the person bound it
  to, or nothing.
- **A private note was not enough.** The rule lived in a note and in one
  app's test (screenshot's `no_bare_function_key_is_bound`), and new apps
  kept breaking it. A rule the registry enforces cannot be forgotten.

## Alternatives considered

**Allow the modified F-keys (Ctrl+F\*, Alt+F\*) and refuse only the bare
ones.** Rejected: nearly every modified function key is already taken
before an app starts.

- **Ctrl+Alt+F1–F12** switch virtual terminals. The keyboard layout turns
  them into the XKB `SwitchVt1`–`SwitchVt12` keysyms, compd maps those
  (`services/compd/crates/slots/src/library/input/keyboard/format/format.rs`),
  and MixOS's VT-separated sessions depend on them.
- **Ctrl+F\***: a typical stock KDE Plasma session binds Ctrl+F1–F4
  (desktops 1–4), plus Ctrl+F7, Ctrl+F9, Ctrl+F10 and Ctrl+F12 (window
  effects and the overview). Those are global grabs, so an app's default
  on one would silently never fire.
- **Alt+F\***: Alt+F1 (application menu), Alt+F3 (window operations) and
  Alt+F4 (close window) are near-universal desktop conventions.
- **Shift+F10** is the standard keyboard context-menu key, which
  keyboard-only and assistive use relies on.
- **Meta/Super+F\*** belong to the compositor.
- **Terminal programs**: F-key chords must reach TUI programs inside a
  terminal (mc, htop) unclaimed.

What is left free changes from desktop to desktop and release to release.
One simple rule, no default on a function key at all, holds everywhere; a
deny-list would be tied to one desktop's current configuration. A person
who wants any F-chord binds it in their keymap.

**A typed check** (a default-chord type that cannot hold a function key).
Rejected for now: it would change the `shortcut` field of every command in
every app, for a guard the registry already gives at start-up and in every
app's own tests.

## Migration

The existing default function-key chords on main are removed. Each command
keeps its menu row:

| App | Command | Was | Now |
|---|---|---|---|
| Monitor | `file.refresh` | F5 | Ctrl+R |
| Monitor | `help.shortcuts` | F1 | Ctrl+/ |
| BusViewer | `help.shortcuts` | F1 | Ctrl+/ |
| Prefs | `help.shortcuts` | F1 | Ctrl+/ |
| dopus | `help.shortcuts` | F1 | Ctrl+/ |
| dopus | `file.rename` | F2, Ctrl+E | Ctrl+E |
| dopus | `nav.switch-pane` | F6, Tab | Tab |
| dopus | `view.refresh` | F5, Ctrl+R | Ctrl+R |
| ced | `search.find_next` | F3 | none (Enter in the find field) |
| ced | `search.find_prev` | Shift+F3 | none |

dopus's Parent Folder gains Alt+ArrowUp beside Backspace, the usual file
manager chord. ced's list of contextual keys no longer claims F10 for the
menu bar; no code bound it. screenshot's own test is removed: the registry
now refuses what it checked, with modifiers too.

A person who wants an old key back binds it in their profile, for example
`keymaps.dopus.file.rename = ["F2", "Ctrl+E"]`.

## Consequences

- AGENTS.md §4.1 gains the rule.
- A new app that binds a function key by default fails its own registry
  tests at once, with a message pointing here.
- The affected apps' manuals list the new keys.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-18-property-store-in-props/ (source: https://mixos.dev/docs/decisions/2026-10-18-property-store-in-props.md) -->

# Decision — service property storage belongs in props

Status: accepted 2026-10-18.

## The decision

`libs/props` owns the shared service property substrate: namespace schemas,
capabilities, hooks, lifecycle, audit, storage, mutation routing and event
dispatch. Its empty default feature set remains pure types and revisions;
`store`, `sqlite` and `router` add the respective facilities.

`libs/logging` owns the reserved `log` namespace and live-filter watcher,
behind its opt-in `props` feature. Services supply domain-table mappings
and use their existing native Bus connection for subscription grants and
publication. No new crate, transport or broker is introduced.

The [condensed contract](../spec/props/README.md) preserves capability
strings, verb envelopes, errors, topic suffixes, audit canonicalisation and
the five `__props_*` table names and DDL. Persisted databases require no
migration. `noded.props.subscribe_grant`, already served by the broker,
is registered as an intent because it installs a subscription for another
peer. Concrete service verbs are registered when their owner adopts them.

## Why

Service domain data and the logging bridge need the same schema, storage,
audit and native routing contracts. Keeping those contracts beside the
existing property read surface avoids duplicate stores and projection
logic; replay and live delivery use the same functions. Optional features
keep database and runtime dependencies out of pure readers. This is the
deliberate shared API boundary for logging and the forthcoming mail service
port, with other domain services able to use the same substrate.

## Authority and secrets

`settingsd` continues to own desktop and session settings. This substrate
owns each service's durable domain records: a mail server's mailbox accounts
are distinct from the email application's `email.accounts` profile group.
It creates no second authority for desktop preferences.

The [email settings decision](2026-10-16-email-accounts-in-settings.md)
continues to govern app passwords. Fields declared secret are redacted on
ordinary reads, public describe and passive events; audit keys never enter
the Bus. An explicit secrets-read capability remains part of the existing
privileged service contract. No application password publication is added.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-19-mcp-program-name/ (source: https://mixos.dev/docs/decisions/2026-10-19-mcp-program-name.md) -->

# MCP bridge program name

Status: accepted.

The MCP stdio bridge is the CLI component `cli/mixos-mcp`, package and
binary `mixos-mcp`. It is the single exception to the ban on a `mixos-`
program prefix. All other component naming rules remain in force.

Clients register the server as `mixos`, so qualified tool names are
`mcp__mixos__<tool>`. The bridge uses the native Bus client and the same node
configuration discovery as other MixOS clients. It ships in the server
prefix archive, alongside the system binary.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-20-commands-take-parameters/ (source: https://mixos.dev/docs/decisions/2026-10-20-commands-take-parameters.md) -->

<!-- SPDX-License-Identifier: MIT OR Apache-2.0 -->

# Decision — commands take parameters and return results

Status: accepted 2026-10-20. Amends [egui applications](2026-10-09-egui-applications.md), [executed commands](2026-10-11-executed-commands.md) and [verb classes](2026-10-11-verb-classes.md).

## The decision

- **A command has typed parameters and a result.** Its parameter type is a serde struct that refuses unknown fields and derives a JSON Schema; `<app>.commands` reports the schema, enablement and the disabled reason; `<app>.execute { id, params }` runs it and returns the result.
- **The registry is UI-free** (`libs/command`). Engine crates own their command tables; the egui crate renders menus, shortcuts and the palette from them.
- **One path.** UI, shortcuts, palette, macros, Bus and headless all dispatch through the registry. A verb that performs an action a command defines is refused in review.
- **Executed events carry `params` and `result`** (`v: 2`); a value above 4 KiB is replaced by `{ bytes, sha256 }`.
- **Every registered verb names its body schema** (registry schema 4): a request type, `none`, or `pending` through 2026-11-30 inclusive in UTC.

## Why

An action's id alone cannot express the choices needed to run it again.
Typed parameters make those choices explicit, and a result lets every caller
observe the same outcome. One registry keeps validation and enablement
consistent across the UI, Bus and headless paths.

## Consequences

- Engines own serde request types and their schemas; handlers deserialize
  accepted parameters and return results.
- Events preserve the accepted JSON body verbatim, rather than reserialising
  handler defaults. Nullary runs carry null parameters; `note()` carries null
  parameters and results.
- Each parameter and result value is measured separately using compact JSON
  bytes. Above 4096 bytes it becomes `{ bytes, sha256 }`, with a lowercase
  SHA-256 digest of those bytes. This bounds the executed journal.
- `<app>.commands` reports stored chords in Ctrl, Alt, Shift modifier order,
  preserving key names from the keymaps grammar, including short forms.
- Verb owners replace migration placeholders with request types or `none`
  by the cutoff. The gate refuses expired placeholders by verb or family name.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-20-headless-backend/ (source: https://mixos.dev/docs/decisions/2026-10-20-headless-backend.md) -->

# Render-node headless compositor backend

Status: accepted, 2026-10-20.

compd has three backends: `kms-live` owns physical scanout, `nested` draws
inside a host compositor, and `headless` draws a virtual output using only
a render node. Headless is the offscreen test and future recording target;
hardware behaviour continues to be tested on KMS.

The headless backend lives beside nested at compd layer 4. GBM/EGL opens
the selected render node and verifies the EGL device identity. There is no
DRM device, master, connector, libseat, udev or libinput. The virtual output
is `headless-0`; mode and scale are explicit. Two offscreen GLES textures
alternate, with full repaints after scene damage. A one-shot software timer
caps frames at 60 Hz and stops while idle. Software presentation uses
CLOCK_MONOTONIC and claims no hardware completion or vblank.
`COMPD_HEADLESS_REFRESH_HZ` may select a lower rate from 30 through 60 Hz;
the virtual mode and frame timer use the same rate. The default is 60 Hz.

The binding profile is `headless`; the default Bus service is
`comp-headless`, with `comp-<name>` available through `--bus-service` for
instances. Headless never requests realtime priority or negative nice,
starts no XWayland, and leaves the desktop session environment alone.

Headless owns agent input authority without a VT; session locks still clear
agent input, while KMS and nested retain their session-pause rules. `seat0`
is advertised with no capabilities, and human input refuses `seat_unavailable`.
The agent pointer starts at output centre; absolute `headless-0` moves clamp
to the mode's logical bounds. Each Bus service has its own observation topics,
window registry and presentation statistics.

Screencopy and Bus captures run after completed offscreen rendering, including
on idle outputs. The normal picture excludes cursor elements; a second pass
is made only when a capture requests them. Cursor inclusion is chosen per
capture, including mixed requests in one frame, and an unavailable picture
fails its capture rather than substituting another cursor policy. Capturing
unchanged content does not count as a new presentation.

## Deployment and recording

An instance is a headless desk: its own nspawn machine, noded, session bus,
PipeWire and portald, with only the GPU render node bound and no VT, tty or
seatd. `compd-headless@.service` uses the session slot `%i`, just as `compd@`
does: a console desk uses a VT number; a headless desk can use `rec`. Both
read `/etc/mixos/session/%i.env`. Inside the desk, the compositor's Bus service
is `comp`; each desk has its own node. The standalone CLI default remains
`comp-headless`.

The component owns `mixos-headless.slice` with `CPUQuota=200%`; the desk's
compositor runs there at nice 10. Desk provisioning places its portal,
PipeWire, WirePlumber and encoder in that slice too. The container has its
own quota, so the slice does not need a per-instance name.
`COMPD_HEADLESS_REFRESH_HZ` passes through the session environment file.

portald's `serve --screencast-max-framerate N` sets the cast ceiling in
1..=120 Hz. It defaults to 30, preserving console sessions; a headless desk
can request 60 through its portal unit drop-in. This ceiling does not change
the compositor's refresh rate. These templates do not provision or start a desk.

Phase 4b acceptance measures presentation cadence: `presented_hz` is the
presented-frame count divided by the paced probe's elapsed time, and
`cadence_missed` counts presentation gaps greater than 1.5 requested intervals.
Captured-frame uniqueness is measured from the probe's pixel frame IDs.
The client-deadline `missed` count remains a regression guard only: two
free-running 60 Hz clocks beat against that deadline without establishing
a compositor cadence defect.

The Phase 2 plain Wayland EGL client probe (`weston-simple-egl`, with
`WAYLAND_DEBUG=client`) created its first `wl_buffer` through `wl_shm_pool`.
Its rendered pixels survived composition and screencopy, but this was a
`wl_shm` fallback. Client DMA-BUF negotiation remains unproven; this probe
does not establish the GPU-client DMA-BUF path.

Phase 5b publishes the validated headless render node in the kernel registry
as the composite device for backends without a scanout binding. The DMA-BUF
advertiser uses the native GPU binding first, as before, otherwise this node,
otherwise the v3 flat format list (nested). Headless therefore advertises
`zwp_linux_dmabuf_v1` v5-capable feedback with `main_device` equal to the render
node's `dev_t`, using the existing narrowed import format set. Mesa can select its
hardware EGL driver from that feedback without a legacy `wl_drm` global.
The GPU acceptance tests read the default feedback on a real Wayland client,
compare its main device against the selected node's `st_rdev`, and require a
tranche carrying valid format-table indices. The plain EGL client must create
linux-dmabuf buffers and pass the existing rendered-pixel readback checks;
this establishes GPU EGL client allocation, import and composition. The ced
probe continues to record its actual wgpu adapter and attached buffer type.
This does not establish hardware Vulkan WSI on the build workers: their only
Vulkan ICD is llvmpipe and they lack `vulkan-intel`. On a headless desk with
`vulkan-intel` installed, ced chose Vulkan on the Intel GPU and presented
through linux-dmabuf even against the earlier v3 global (2026-10-21,
recorded in the private journal); the Vulkan path depends on the ICD being
in the desk image, which the image builder now includes.

The Phase 5b Intel render-node run observed a version 6 global from the current
Smithay feedback helper. Mesa bound version 4. Default feedback named
`0xe280`, equal to the selected node's (`/dev/dri/renderD128`) `st_rdev`, with
one tranche of 224 format indices.
`weston-simple-egl` created linux-dmabuf buffers; screencopy retained its dark
background and bright bar. Ced chose `Gl`, `IntegratedGpu`,
`Mesa Intel(R) Iris(R) Xe Graphics (RPL-P)`, Mesa 26.2.4, and attached
linux-dmabuf buffers. Idle SSIM was 1.0 and typed SSIM 0.980828380141, with
exact Bus text readback. No console reference was supplied for this run.

Phase 5 uses ced's real egui/wgpu window with a private noded and editd, so
`ced.state {text:true}` can confirm agent-seat typing independently of pixels.
The reference helper `services/compd/crates/testkit/scripts/app_reference.mix`
creates a fresh document and places an 800×560 window at (80,60), scale 1,
in either session; the console-desk reference is captured separately with
that same helper. Before the first GPU run, the acceptance threshold is fixed
at grayscale SSIM ≥ 0.99 for repeated idle captures and the console/headless
comparison, allowing minor rasterisation differences while rejecting material
layout changes. The known typed line must produce SSIM < 0.999 against the
blank document, alongside exact Bus text readback. SSIM uses uniform sliding
8×8 valid windows, population covariance, Rec.601 luma, K1=0.01, K2=0.03 and
L=255. A test-only ced launcher installs a log subscriber around the unchanged
entry point to record the chosen wgpu adapter; Wayland client tracing records
the actual buffer creation request. A shm result is reported as a weaker
client-buffer claim, even when wgpu renders on a GPU. Software wgpu adapters
are recorded explicitly and establish no GPU-client claim.

What the headless-only run proves, and does not (review, 2026-10-21): with no
console reference supplied, the test shows a large, stable rendered change
after typing plus exact model text; it does not check glyph correctness
(tofu or a wrong font fallback would still pass). Glyphs are only pinned by
the console comparison. SSIM at 0.99 tolerates uniform brightness drift: a
+10 luma shift scores about 0.9955 at mid grey and 0.9988 at bright grey, so
a brightness regression is within the threshold by design and must be
caught elsewhere. The tested artefact is the test-only launcher, which
compiles the shipped entry point from the same source; drift is a compile
error, never silent. The first Phase 5 run chose a software Vulkan adapter
(llvmpipe) with `wl_shm`; Phase 5b's device feedback enables the hardware GL
path recorded above. Hardware Vulkan WSI is unproven on the workers and
observed on a desk with the Intel ICD. Open follow-ups
are the test's fixed post-typing sleep (retry once on an unchanged capture),
the helper's leftover `.session` directory on
failure, and its reliance on `spawn` merging the parent environment.

## Wayland conformance (Phase 6)

[canonical/wlcs](https://github.com/canonical/wlcs) exercises protocol behaviour:
buffers, pointer and touch delivery, constraints, clipboard and selection,
subsurfaces, shell roles and popups, output descriptions and supported extensions.
It does not establish KMS, physical input or hardware presentation correctness.
The baseline pins **v1.8.1**, commit
`2b385328366de5db19521b9b3eef81861430d984`.

The private `wlcs` crate produces `libcompd_wlcs.so`. It implements the C ABI
independently, with the callback structure informed by
[Smithay 0.7's wlcs_anvil](https://github.com/Smithay/smithay/tree/v0.7.0/wlcs_anvil).
Small client/surface lookup fragments in the compd adapter follow that reference.
The C ABI shim and owned-child lifecycle were implemented for compd. The `/256`
conversion implements Wayland's signed 24.8 fixed-point ABI; `touch_destroy`
auto-up is local lifetime handling (wlcs_anvil's touch destroy is empty).
Both source headers and `NOTICE` credit the reference; its MIT licence remains
in `vendor/smithay/LICENSE.txt`.
It owns a fresh `compd --headless` child for each server, isolating process-global
configuration, logging and GPU resources across tests. An inherited socket carries
test requests and client descriptors directly to compd's event loop. That control
socket has no listening endpoint; the child also listens on `--socket wayland-wlcs`
inside its private runtime directory. Pointer events call the agent seat's existing
policy-host injection path; touch uses that host's agent hit test on down and
Smithay's held focus for motion and up. Refused delivery returns an explicit error
on the control socket and is printed with the compositor log path. Window placement
uses the native policy-host placement executor with a test-only entry point:
it retains redraw, pointer retargeting and interactive-grab completion while
permitting deliberately off-output positions. All new
entry points are behind `wlcs`. Callbacks wait for completion on the compositor loop.
The extension descriptor is read from a live Wayland registry, including the
advertised versions. Creation probes a short-lived child and reaps it to cache
the descriptor before wlcs asks for it. The descriptor callback only reads the
cache, including after stop; only explicit start retains a test compositor.
Stop kills and reaps the owned child,
and parent death also kills it after a wlcs abort. The adapter is compiled only
with compd's `wlcs` feature and installed only on the headless backend.

Placement uses the requested **wl_surface origin** at screen `(x, y)`. The shim
converts through the native camera transform (world `(0, 0)` is screen centre),
adds the committed xdg geometry offset to obtain the Space element location,
then reads the public window row and checks that its surface origin projects
back to `(x, y)`. Successful checks appear in the gate output. Absolute pointer
and touch coordinates use the same conversion, avoiding a half-screen shift.

There is a contract discrepancy in the pinned wlcs tests. `display_server.h`
describes the window's left/top; both `pointer_respects_window_geom_offset` and
`touch_respects_window_geom_offset` in `tests/xdg_toplevel_stable.cpp:131,162`
(and their v6 equivalents at `103,134`) expect local input coordinates
`input - placement + geometry_offset`, which positions the **window geometry**
origin. They use offset `(35, 12)` and input delta `(20, 30)`, expecting
`(55, 42)`. Under the explicitly selected surface-origin convention, the correct
local point would be `(20, 30)`. Smithay's reference adapter also uses the geometry
origin: `vendor/smithay/wlcs_anvil/src/main_loop.rs:213` maps the element at the
wlcs location without adding the geometry offset. The pinned tests and that
reference agree; this adapter's selected surface-origin convention differs.
This contract mismatch is established from source, not inferred from a failed
run. No test source or normal compositor behaviour is changed to conceal it.

The fresh recording reports the four named cases as follows (coordinates below
are pixels, converted from Wayland 24.8 values):

| Case | Observed result |
| --- | --- |
| `XdgToplevelStableTest.pointer_respects_window_geom_offset` | Fails the coordinate assertion: `(2.5, 24)` observed, `(55, 42)` expected by wlcs. Placement self-check reports `(200, 280)`. |
| `XdgToplevelStableTest.touch_respects_window_geom_offset` | `touch_down` refuses `touch_no_target`; the touched-window assertion sees NULL, before the coordinate assertion. Placement self-check reports `(200, 280)`. |
| `XdgToplevelV6Test.pointer_respects_window_geom_offset` | Skipped: missing `zxdg_shell_v6 >= 1`. |
| `XdgToplevelV6Test.touch_respects_window_geom_offset` | Skipped: missing `zxdg_shell_v6 >= 1`. |

The stable pointer result also differs from `(20, 30)`, so the convention mismatch
alone does not explain that failure. The native coordinate/focus path still needs
tracing; the stable touch case stops at native hit testing. Neither stable case
reports `unconfigured_buffer` in this recording, and neither v6 case tests input.

Build on a GPU worker, keeping wlcs outside the MixOS checkout:

```text
git clone --depth 1 --branch v1.8.1 https://github.com/canonical/wlcs /build/wlcs
cmake -S /build/wlcs -B /build/wlcs/build -DCMAKE_BUILD_TYPE=Release \
  -DBOOST_ROOT=/build/wlcs/deps/usr \
  -DCMAKE_CXX_FLAGS=-Wno-error=deprecated-declarations
cmake --build /build/wlcs/build --target wlcs -j4
cargo build -p wlcs --locked
cargo build -p compd --no-default-features --features wlcs --locked
cargo clippy -p wlcs --all-targets --no-deps --locked -- -D warnings
cargo --config 'env.COMPD_WLCS_BINARY="/build/mixos/target/debug/compd"' \
  test -p wlcs --locked -- --ignored --nocapture
/opt/mixos/bin/mix services/compd/tests/wlcs_gate.mix \
  --wlcs /build/wlcs/build/wlcs \
  --shim /build/mixos/target/debug/libcompd_wlcs.so \
  --compd /build/mixos/target/debug/compd \
  --output-dir /build/wlcs/run-1
```

Wayland development files, gtest/gmock and Boost headers are required. The first
build used Boost 1.92.0 unpacked under `deps`, without a system install. The
compiler flag permits wlcs's deprecated gmock `Invoke` calls with gmock 1.18.0.
`WLCS` may replace `--wlcs`; `COMPD_TEST_RENDER_NODE` selects the render node.
The ignored shim lifecycle test needs an absolute `COMPD_WLCS_BINARY` because
Cargo runs it from the package directory. It checks cached descriptors before
start and after stop, including stable backing storage. `--no-deps` scopes
Clippy's warning gate to the shim rather than inherited legacy dependency lints.

The gate enumerates every test and runs four isolated processes at a time, each with a 20-second
deadline, preserving JSON, process results and compositor logs in the output
directory. It checks every name and outcome against
`services/compd/tests/wlcs_expectations.conf.mix`; additions, removals and changed
outcomes fail with a diff. The first observation uses `--record --expectations
<new-file>`; recording refuses to overwrite a file. Disabled and unsupported
tests are recorded as skipped. The `flaky` list must be empty: exemptions are
refused, and every observed outcome must match. The control socket's 10-second
read/write timeout is half the process deadline; transport errors name the
compositor log before aborting. Conformance failures are
recorded for later work; Phase 6 does not change compositor policy to fix them.

The first complete observation (2026-10-21) recorded **1,228 tests: 361 passed,
563 failed, 304 skipped, 0 classified flaky**. Every failed case produced a
complete JSON report; no case hit the gate's process deadline. Unsupported
protocols use wlcs's `wlcs-skip-test` JSON property, even though gtest also
records an exception for them. These are skips, alongside disabled cases.

After the shim review, a fresh recording from `ab43adf4` on 2026-10-21 produced
the same inventory and outcomes. The expectation file was removed before
recording; its data was regenerated rather than preserving any exemptions.

| Outcome or failure class | Before review | Fresh recording |
| --- | ---: | ---: |
| Passed | 361 | 361 |
| Failed | 563 | 563 |
| Skipped | 304 | 304 |
| Flaky | 0 | 0 |
| `xdg_surface` 3, `unconfigured_buffer` | 319 | 319 |
| `zwlr_layer_surface_v1` 0, `invalid_surface_state` | 79 | 79 |
| Input-region assertions | 58 | 58 |

Every one of the 1,228 cases produced complete JSON; none hit a process deadline,
terminated by signal or reported an adapter error. **237 cases passed the
surface-origin self-check.** Unchanged outcomes do not validate the old shim:
the named stable `touch_and_drag_on_surface_seen` and
`touch_drag_outside_of_surface_and_back_not_lost` cases still fail with
`unconfigured_buffer` before reaching input injection, so they cannot prove
touch continuity. Fixture source (`src/surface_builder.cpp`) shows that these
cases use `XdgStableSurfaceBuilder`, which assigns the xdg role, sets window
geometry and calls `attach_visible_buffer` without the initial bufferless
commit/configure/ack handshake. Their errors are consistent with enforcing
that handshake; their current outcomes do not validate touch delivery.

Two subsequent complete gate runs against committed baseline `de856d52` passed
the name-by-name outcome comparison. Each again recorded **361 passed, 563 failed,
304 skipped, 0 flaky**, with 237 successful placement checks and complete JSON
for all 1,228 cases. Neither run hit a process deadline, terminated by signal or
reported an adapter error. The expectation data and both observed inventories
were also compared structurally and matched exactly.

The original three largest classes were xdg unconfigured-buffer errors (319),
layer-surface invalid-state errors (79), and input-region assertions (58).
The remaining original classes were 38 event timeouts, 24 missing-notification
cases, 7 keyboard-focus cases and 38 other assertions or protocol errors.
The interface name is part of every protocol error's identity:

- **`xdg_surface`, error 3 = `unconfigured_buffer`.** Stable
  [xdg-shell.xml](https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/stable/xdg-shell/xdg-shell.xml)
  requires an initial bufferless commit, the first `configure` event and its
  `ack_configure` before attaching a buffer; earlier attaches are errors. The
  client trace of `ForeignToplevelManagerTest.detects_toplevel_closed` shows
  xdg surface/toplevel creation followed directly by buffer attach and commit,
  without that handshake. Compd's error 3 is correct enforcement for this
  fixture, which bypasses `create_visible_surface`'s handshake. This trace
  does not classify the other 318 cases; per-case traces are required before
  assigning ownership across the class. Separately,
  `XdgSurfaceStableTest.attaching_buffer_to_unconfigured_xdg_surface_is_an_error`
  attaches after `get_xdg_surface` without a role or commit; its trace shows
  no error where error 3 is required in the original recording. Smithay's
  role pre-commit checks at
  `vendor/smithay/src/wayland/shell/xdg/mod.rs:1673` (posted at `1721`) and
  `2067` (posted at `2116`), installed by
  `xdg/handlers/surface.rs:130,208`, do not cover this attach-only sequence.
  The native follow-up below fixes
  this **missing attach-time validation**; it does not establish a
  configure-state defect.
- **`zwlr_layer_surface_v1`, error 0 = `invalid_surface_state`.** The 79-case
  baseline class is on this interface, not `zwlr_layer_shell_v1`:
  `Layer/LayerSurfaceLayerTest.surface_on_lower_layer_is_initially_placed_below/0`
  reports `must ack the initial configure before attaching buffer`, raised in
  `vendor/smithay/src/wayland/shell/wlr_layer/mod.rs:576`. Its client trace
  shows `get_layer_surface` and `set_size`, then buffer attach, frame and
  commit, without an initial bufferless commit, configure or acknowledgement.
  [Layer-shell XML](https://gitlab.freedesktop.org/wlroots/wlr-protocols/-/blob/master/unstable/wlr-layer-shell-unstable-v1.xml)
  requires that handshake before attaching a buffer. The rejection is correct
  for this fixture: its configure listener can acknowledge events, but no
  initial bufferless commit requests one before attachment. The remaining 78
  cases need individual attribution. The XML defines
  **`zwlr_layer_shell_v1`, error 0 = `role`** separately: another role is
  already assigned. That check is at
  `vendor/smithay/src/wayland/shell/wlr_layer/handlers.rs:84,85`, with the
  role stamp in `wayland/compositor/tree.rs:170`. An erroneous early or stale
  assignment on a fresh surface would be a compd defect, but the original logs
  contain
  **zero** failures with that interface/error pair. Calling the observed
  79 failures role errors would misattribute the protocol object.
- **Input-region targeting and coordinates:** the shim's surface placement
  and screen/world conversion are corrected above. Remaining input-region
  assertions exercise compd's native hit testing and are **compd defects**;
  for example, `MultiRectEdges/RegionSurfaceInputCombinations.input_inside_region_seen/8`
  verifies surface origin `[64, 49]`, completes absolute motion, then reports
  `no_pointer_target` on the button operation. Its paired touch case reports
  `touch_no_target` on down. These are native hit misses after verified placement,
  not silently successful adapter deliveries. No protocol error code is raised.
  Start at `services/compd/crates/world/src/surface/interface/core/hit.rs:478`
  (fitted surface coordinates) and `vendor/smithay/src/desktop/wayland/window.rs`
  (`surface_under`). The stable geometry-offset cases have the observed native
  coordinate/hit failures recorded above, in addition to the source-level
  **wlcs/shim placement-contract mismatch**.
- **Event timeouts, missing notifications and keyboard focus:** these are
  **compd conformance gaps** in the native event, constraints, layout and focus
  paths. They have no protocol error code unless the individual report names
  one. In particular, pointer constraints miss expected locked/unlocked events;
  exclusive-zone layout can time out. The adapter's device refusals are explicit
  in the case logs and must be considered when tracing each case.
- **Other assertions or protocol errors:** retained per case, including
  missing mandated errors for invalid buffers and unconfigured surfaces,
  popup placement/lifecycle and output metadata assertions. These are compd
  conformance defects; the geometry-offset cases also have the stated contract
  mismatch, which does not fully explain their observed failures.
  They are not evidence of a protocol-permitted refusal of a valid client.

All failed cases remain in the expectation file. This phase fixes the shim and
records evidence for follow-up without changing normal compd policy. Failure
class counts alone do not establish that every case is a compositor defect.

### Native xdg attach validation follow-up

The native frontend now checks non-null `wl_surface.attach` requests before
changing pending buffer state. A live xdg wrapper must have its initial
configure sent and acknowledged; otherwise the wrapper receives
`xdg_surface.unconfigured_buffer` immediately, including when no role or
commit follows. The check reads current role state and preserves NULL attaches,
ordinary surfaces, valid toplevel and popup handshakes, wrapper recreation and
the existing retention of pending configures across unmap. Healthy attaches
use one surface-state lock without collecting wrapper handles; errors are
posted after locks are released.

Ten raw-wire regression guards cover refusal and acceptance, stale ACKs after
unmap, proper remapping, wrapper recreation and both popup outcomes. They live
with the existing xdg wrapper guards in vendored Smithay and are registered in
`tools/smithay_guards.mix` and `vendor/smithay/PATCHES.md`.

The unchanged canonical v1.8.1 suite now records **362 passed, 562 failed, 304
skipped, 0 flaky**. Only
`XdgSurfaceStableTest.attaching_buffer_to_unconfigured_xdg_surface_is_an_error`
changed from failed to passed; all other 1,227 outcomes are unchanged. The
complete run retained 1,228 JSON reports and 237 placement checks, with no
process deadline or signal. No canonical fixture or exemption was changed.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-21-desktop-theming-and-style/ (source: https://mixos.dev/docs/decisions/2026-10-21-desktop-theming-and-style.md) -->

# Decision — desktop theming and style

Status: accepted 2026-10-21. Amends [egui applications](2026-10-09-egui-applications.md),
[style tokens as data](2026-10-10-style-tokens-as-data.md),
[scheme and style axes](2026-10-10-scheme-and-style-axes.md),
[the chrome family](2026-10-09-chrome-family-and-schemes.md),
[session icon stroke and type](2026-10-14-session-icon-stroke-and-type.md),
[settings authority](2026-10-07-settings-authority.md) and
[settings summary reads](2026-10-11-settings-summary-reads.md).
Settings contract 0.9.0 (additive), store format 4.

## The decision

- **One look per process.** An application installs its theme once with
  `toolkit::install` and reads every colour, length, radius, stroke and
  font back from the egui context. Nothing is threaded through view
  functions; no application sets an egui style, visuals or fonts itself.
- **One canonical icon stroke.** Desktop icons use the context's default
  stroke of 1.5 on the 24-unit icon grid. A fixture that previously passed
  2.0 explicitly moves to that canonical default. The existing
  `appearance.icon_stroke` choice keeps its contract and still owns an
  explicit session override; views have no independent stroke choice.
- **Every painted or interacted number is a token, and later tokens are
  data.** The style family's forty original tokens are the required set;
  every later token is defaulted from an append-only compatibility table
  when a design omits it, through an immutable fallback rule that covers
  every authored style name, so every sealed profile keeps compiling and
  adding a token never needs a store migration. There are no read-only
  values: the behaviour values (resize edges, scrub rates, hit tolerance,
  menu scroll speed, double-click time, the icon mask) are tokens with
  floors that keep the interaction possible.
- **Applications add no literal lengths and no literal colours.**
- **Session tunables.** The profile's `tune` maps `style.<token>` or
  `chrome.<role>` to a value, validated against a registry the design
  crate publishes and `settings.describe` lists; `apps.<id>.tune` does the
  same for one application; `view.look.preview` does it for one window.
  Style and chrome tunes therefore have session, application and window
  scope. Relations between tokens are constraints validated on the final
  layered values and refused with both sides named. Unknown and retired
  names in a stored record are kept and reported, never dropped; aliases
  are canonicalised within each layer. The design is never patched.
- **Resolution order:** session axes, the application's own axis
  override, the window's choice; the profile's pinned design source
  compiled with its defaults; the legacy session choices (icon stroke,
  fonts); session tune; application tune; window preview; then
  accessibility (`ui.reduced_motion` zeroes animation). Every value
  reports its source and what it shadows. Legacy choices own their
  targets.
- **Every application compiles the profile's pinned design source.** When
  the profile's source digest differs from the design the binary carries,
  the application fetches the source once with `settings.source`,
  verifies it by digest, caches it per user and compiles it; until it
  arrives the embedded design is drawn and reported. Custom design sources
  are therefore ordinary profiles: the session look, tunes and previews
  apply to them.
- **Tuned colours are exact and unchecked;** writes warn below 4.5:1 and
  the look report marks them. The field focus border stays and its width
  and colour role are tokens.
- **Read, preview and choose over the Bus.** Every application answers
  `<app>.look` and publishes `<app>.look.changed`: authority identity, the
  window's look generation, which source was compiled, axes, every token
  and role with value, default, source and shadowed layers, the egui slot
  each role owns, the fonts actually drawn, content regions with the
  palette they draw with. `view.look.preview {tune, expect}` is fenced on
  the authority's incarnation and revision and on the window's look
  generation, bounded, one per window, cleared by every look change except
  the arrival of the window's pinned design source, which keeps it.
  `view.theme.set` is the window's axis choice; older per-application
  theme verbs are deprecated aliases. Writes use `settings.validate`,
  `settings.apply` (fenced; `null` resets), `settings.reset` and
  `prefs.appearance.set`. Undo is the caller's held before-values applied
  as an inverse fenced on the accepted receipt.
- **One scroll bar.** `toolkit::scroll` wraps egui's bar with the style's
  tokens; the handle takes the state's text colour at a resting opacity,
  the track shows only while hot. The document canvas keeps its own bars,
  from tokens.
- **One form row** (`toolkit::form`) and one set of fields.
- **Chrome and content are two scopes.** A light content region draws the
  window's design and overlays with only the mode forced to light; other
  regions inherit the window. **The terminal's colours are a settings
  domain with session scope,** `terminal.colors`: sixteen ANSI entries,
  foreground, background and cursor, each a colour or null for the
  design's default for the session's scheme and mode (the cursor default
  is a policy, invert or a colour); a running program's palette changes
  sit over them until reset; explicit RGB cells are drawn as sent.
- **The compositor's title bars follow each window's look.** A
  server-decorated window's bar is drawn from that window's resolved look,
  read with `<app>.look` and refreshed on `<app>.look.changed`, so a
  window's own scheme choice and its preview show in its title bar. The
  window's application is attributed through the broker's own record of
  the service's connection, never through self-reported identity; a
  window the compositor cannot attribute, or an extra window of a
  multi-window application that carries no toplevel tag, draws the
  persistent session and application look. The wallpaper follows the same
  look.
- **Two new chrome schemes, `breeze` and `adwaita`,** each light and dark,
  with their own styles and terminal colour tables; a design that lacks
  them takes them from the compatibility table.
- **Rollout and rollback.** Every reader ships before settingsd writes the
  new fields; `settingsd downgrade --to 3 --target <previous binary>`
  checks eligibility in process and then with the previous binary itself
  on each candidate, and only then re-seals the store for it, primary
  first; it refuses otherwise, naming the reason.
- **Gates.** Workspace clippy disallows the raw egui widgets, every style
  setter and theme threading by resolved path; legitimate uses outside
  applications carry an `expect` with a reason that fails when stale;
  `tools/style_gate.mix` refuses spacing and colour literals and unlisted
  constants in every application GUI crate, and holds the toolkit to its
  token inventory.

## Why

A desktop is one surface. The tokens, the settings authority and the
toolkit already exist; what leaked was the last mile inside each
application, where a stroke was threaded by hand, a gap was a number and a
scroll bar was whatever egui gave. Closing those leaks once, and letting a
session tune any token over the Bus, means the next hundred style
adjustments are data and a `settings.apply`, not a release and not a
migration.

## Consequences

- Every application changes mechanically once; new knobs never need a
  schema field, a store migration or a Prefs change again.
- Prefs builds its Appearance controls from the registry, for the session
  and per application, each showing the design default, the inherited
  session value and the application's override, and gains a terminal
  Colours group.
- An agent can read exactly what any window draws and why, and change
  any style token or chrome colour for the session, one application or
  one window, and the terminal's colours for the session, under any
  design source.

---

<!-- page: https://mixos.dev/docs/decisions/2026-10-22-weekly-cbc-releases/ (source: https://mixos.dev/docs/decisions/2026-10-22-weekly-cbc-releases.md) -->

# Weekly CBC releases, starting with Linux x86_64

Status: accepted, 2026-10-22. The first public release still requires its
own green gate and acceptance record.

MixOS starts with Linux x86_64 binaries built against Ubuntu 24.04's glibc
2.39. Each later architecture or operating system needs its own build,
package and install proof before it appears in a release.

All Rust build, test and Clippy work runs on the designated CBC workers at
one full source commit. The release build uses a signed Ubuntu 24.04 build
root on a CBC worker. The packager runs every shipped binary there, records
the source commit and hashes in `release.manifest.mx`, and refuses a higher
glibc floor. Those exact bytes move to a draft GitHub Release; GitHub does
not rebuild them. A published release is immutable.

The full gate is two commit statuses on the candidate's exact commit:
`mixos/weekly-x86_64-source` (build, Clippy, tests, source gates and Mix
tests) and then `mixos/weekly-x86_64-artifacts` (packaging, disposable gold
preflight, draft upload and draft asset digests). It runs for a frozen
weekly candidate. There is no GitHub-hosted Rust build; a push runs only the
lint tier described below.
A failed gate cannot create a publishable candidate, and the last published
version remains current. Any cheaper source checks must use their own status
name and cannot stand in for the full gate.

The weekly candidate is cut on **Friday** (amended 2026-10-23). The weekend
is for review, and Sunday night is the window for an emergency rebuild, so
the working week starts on a known-good release. Changes merged between
releases are not release candidates and do not run the full gate.

Every push runs the **lint tier** instead (`tools/lint.mix`, workflow
`lint`, amended 2026-10-23). It runs `rustfmt --check`, a syntax or data
check of every Mix file, and the repository's own gates that need no
compile: closure, layering, verb registry, webd, units, style, component
index and site. The site check needs the pinned font assets and subsetting
tools, so a bare runner skips it; the pre-commit hook runs it on every
commit. The tier compiles no Rust
and runs no tests. Its runner uses the `mix` binary from the latest
published release, verified against that release's `SHA256SUMS.txt`.

`mixos-desktop` and `mixos-server` have separate package membership and
acceptance. A desktop candidate may pass while a server service still needs
admission. The release notes state exactly which archives are accepted.

The canonical system installation is `/opt/mixos`. A privileged Mix gold
installer verifies the published manifest and archives, records a receipt,
and supports rollback. It does not activate running sessions. Prefs and
releasesd currently offer verified **per-user** application installs; their
MixOS entries do not update `/opt/mixos`. A system update control in Prefs
must use a reviewed native privilege and activation path before it can claim
to update the system.

Implementation and operator steps: [Releasing MixOS](../dev/releasing.md).

---

<!-- page: https://mixos.dev/docs/dev/2026-10-21-source-and-build-map/ (source: https://mixos.dev/docs/dev/2026-10-21-source-and-build-map.md) -->

## Read first

This manual describes source on `main`; installed binaries can be older or
built from another revision. Check the installed program's version and its
live `app.describe` or `HELP` response before relying on an API. An accepted
decision records the intended contract and can describe work still being
implemented; it is not proof that every planned feature is available.

- [Repository rules and layout](https://github.com/markc/mixos/blob/main/AGENTS.md)
- [Mix gotchas](https://mixos.dev/mix/gotchas.md): read before writing Mix.
- [Component index](https://mixos.dev/docs/components.md): source paths, kinds and install profiles.
- [Driving apps over the Bus](https://mixos.dev/docs/drive.md): discovery, commands and captures.

## Source and build map

One public repository, [markc/mixos](https://github.com/markc/mixos), holds one
Cargo workspace and the site source. Paths below are relative to its root.

- `libs/mix/`: the `mix` Cargo package and Rust library, with the lexer,
  parser, evaluator, builtins and language regression tests.
- `cli/mix-shell/`: the `mix-shell` library, owning the interactive shell,
  script runner, command dispatch and supervised Bus citizen runtime.
- `cli/system/`: the `system` package that builds the `mix` executable.
  Its default daemon personalities are `noded`, `monitord`, `maild`, `webd`
  and `dnsd`. Other services, including `settingsd`, `hostd`, `portald` and
  `compd`, have their own packages and executables.
- `apps/`: GUI applications; `services/`: daemons; `libs/`: shared libraries.
  GUI apps use egui/eframe and wgpu, with common widgets in `libs/toolkit/`.
  Each app links its libraries into its own executable: shared widget code
  changes require rebuilding and restarting each affected app.
- `docs/mix/`: the public Mix manual; `docs/_build/gen-site.mix`: the native
  Mix site generator, including this index and `llms-full.txt`.

In the designated Rust build environment,
`cargo build --locked --profile release-fast -p system --bin mix` produces
`target/release-fast/mix`. `cargo build -p mix` builds the language library,
not the shell executable. Installed binaries belong under `/opt/mixos/bin`.
Mix programs run directly with `/opt/mixos/bin/mix script.mix`; editing a
program does not require compiling Rust. Use `mix builtins NAME` for builtin
contracts, `run_argv` or `run_argv_must` for processes and `ssh_mix` for remote
Mix programs.

The `.mix` program / `.mx` document split is an accepted migration target.
Existing readers still use legacy names such as `*.conf.mix` and `scene.mix`;
check the owning reader before renaming data or assuming a loader's behaviour.

---

<!-- page: https://mixos.dev/docs/dev/releasing/ (source: https://mixos.dev/docs/dev/releasing.md) -->

# Releasing MixOS

The first release target is Linux x86_64 with a glibc 2.39 floor. The
release contract is in `tools/release_packages.mx`. The initial desktop
candidate contains one archive, `release.manifest.mx`, and `SHA256SUMS.txt`.
The desktop archive includes the ten desktop products, indexd, the desktop
settings authority settingsd, and the Mix runtime used by its session scripts.
An admitted server archive can join a later candidate. Every archive in a
candidate comes from one exact public source commit. Packaging an unadmitted
service does not admit it for publication.

## Build and gate

Use a designated CBC worker and freeze a full 40-character source commit.
`tools/release_gate.mix check --commit SHA` runs format, workspace build,
Clippy, functional tests, the release-mode editd latency test, Term's
native-session end-to-end tests against the freshly built Mix, source gates
and Mix tests. Its `LOG` lines identify the saved stage logs. The
`mixos/weekly-x86_64-source` commit status goes green only after that
exact-source gate passes. The separate `mixos/weekly-x86_64-artifacts` status
goes green only after packaging, disposable gold preflight, draft upload
and GitHub asset digest comparison also pass at the same commit. There
is no Rust build on a GitHub push. A push runs only the lint tier: run
`mix tools/lint.mix` locally before pushing to see the same result.
Candidates are cut weekly on Friday.

For packaging, prepare a signed Ubuntu 24.04 root with glibc 2.39, the
pinned Rust toolchain from `rust-toolchain.toml`, Cargo's cache, and the
development libraries used by the workspace: `libxkbcommon-dev`,
`libwayland-dev`, `libx11-dev`, `libxrandr-dev`, `libxi-dev`,
`libxcursor-dev`, `libgl1-mesa-dev`, `libegl-dev`, `libgles-dev`,
`libgbm-dev`, `libdrm-dev`, `libinput-dev`, `libudev-dev`,
`libseat-dev`, `libpixman-1-dev`, `libpulse-dev`,
`libpipewire-0.3-dev` and `libspa-0.2-dev`. It also needs `git`,
`build-essential`, `pkg-config`, `clang`, `libarchive-tools`, `meson`,
`ninja-build` and `patchelf`.
Ubuntu 24.04 supplies libinput 1.25, while compd's tablet dial support
uses the 1.26 ABI. Build libinput 1.26.2 from upstream tag `1.26.2`
(peeled commit `3402f380019dc4f882e1d8627029607aca3f4be6`) inside the
same root with Meson, install it under `/usr`, and run `ldconfig` there.
Keep that pinned source checkout inside the target directory. The gate
refuses another libinput source or library version. The desktop archive
bundles the 1.26.2 shared library and its licence; compd's relative
runtime library path makes that copy take precedence over the host copy.
After installing the listed build dependencies in the root, the CBC worker
can provision the pinned library with:

```text
/opt/mixos/bin/mix tools/libinput_compat.mix \
  --rootfs /srv/ubuntu-24.04-root --target-dir /srv/mixos-target
```

The script verifies the upstream commit and installed ABI. It is safe to
run again after an Ubuntu root update.
On the CBC worker, the native Mix gate takes absolute
paths for the root, Cargo and Rustup homes, and a dedicated target
directory. It bind-mounts the exact checkout, toolchain, cache, target,
`/proc` and `/dev/null` into the root, checking each mount's identity.
It refuses a root that does not report glibc 2.39 or does not see the
requested commit.

```text
mix tools/release_gate.mix package --commit FULL_SHA --version V \
  --package desktop \
  --rootfs /srv/ubuntu-24.04-root --target-dir /srv/mixos-target \
  --cargo-home /home/user/.cargo --rustup-home /home/user/.rustup \
  --libinput-source /srv/mixos-target/libinput-1.26.2-src \
  --out /srv/mixos-target/release-V
```

The package stage builds each selected Cargo package once in that root.
The packager then runs each binary's `--version` inside the same root,
checks the source hash and bundled libinput resolution, and writes the
archives and manifest. The
`--fixture-binaries` option is for tests only; the gold installer refuses
fixture manifests. Check the complete saved log and the archive hashes
before upload. Never substitute a build made against a newer host glibc.

## Stage and publish

Transfer the three desktop output files from CBC with a hash comparison on both
sides. Upload them to a new **draft** GitHub Release at the frozen commit,
then compare GitHub's asset digests with the CBC files. Do not replace an
existing published tag or its assets. Publishing requires a full green
status, archive checks, clean install and rollback proof, and acceptance
for every included archive. The release notes identify any archive that
is still pending. Enable immutable releases before public publication.

After the initial release, cut one candidate each week. Failure holds the
previous release; it does not trigger repeated rebuilds on every push.

## Install the system gold tree

The operator supplies the manifest hash from the verified GitHub asset
digest. `plan` makes no gold changes. `apply` needs one explicit privileged
invocation, and prints a receipt ID for `rollback`. The installer refuses
a missing or changed archive, wrong source or architecture, a glibc floor
above the host, and unsafe archive paths.

```text
sudo /opt/mixos/bin/mix tools/gold_release.mix plan \
  --manifest /path/to/release.manifest.mx --manifest-sha256 TRUSTED_SHA256 \
  --archive-dir /path/to/assets --package desktop

sudo /opt/mixos/bin/mix tools/gold_release.mix apply \
  --manifest /path/to/release.manifest.mx --manifest-sha256 TRUSTED_SHA256 \
  --archive-dir /path/to/assets --package desktop
```

Install and activate are separate operations. A shared desk sees the host
gold tree through its mount. An isolated desk needs a hash-checked copy
of that tree and its own restart. Test the isolated desk first, then the
shared desk. The public installer does not assume particular console
numbers. Prefs currently tracks and installs MixOS releases per user; it
does not update or restart a system desk.

---

<!-- page: https://mixos.dev/docs/spec/bridge/ (source: https://mixos.dev/docs/spec/bridge/README.md) -->

# Bridge contract

Status: draft, version 0.2.0. Machine-checkable fixture:
[`bridge.spec.mix`](bridge.spec.mix). Verified by
`services/bridged/tests/bridge_core_test.mix` (the config contract against
the fixture, the wire protocol against a stand-in app) and
`services/bridged/tests/bridged_test.mix` (every verb over a private broker).

`bridged` puts an external application on the Bus. The application offers a
line-delimited JSON control channel on loopback TCP; one `bridged` instance
per application maps six Bus verbs onto it. This page fixes the control
channel an application must offer, the instance config schema, the serve-name
rule and the Bus verbs.

## The control channel an application offers

| Item | Rule |
|---|---|
| Transport | TCP on the loopback interface, one port per application. The bridge keeps one connection open and reuses it. |
| Framing | One JSON object per line, UTF-8, `\n`-terminated (a trailing `\r` is ignored). A line is at most `max_line` bytes. |
| Auth (`auth: "token"`) | The first line on every connection is `{"id":"auth","method":"auth","params":{"token":"<64 hex>"}}`. The application replies `{"id":"auth","ok":true,...}` or refuses and closes. The bridge sends nothing else until that reply is ok. |
| Auth (`auth: "key"`) | As `token`, with `params.key`. The application writes the 64-hex secret to the key file after it starts, and may rotate it; the bridge reads the file on every connect, before any bytes are sent. |
| No auth (`auth: "none"`) | Requests start at once. An application that receives an `auth` line it does not expect should refuse it and close. Any local process can use such a port while it is open. |
| Request | `{"id":N,"method":"<name>","params":{...}}`, `N` a number the bridge increments per request. |
| Reply | `{"id":N,"ok":true,"result":<any JSON>}` or `{"id":N,"ok":false,"error":"<text>"}`, matched to the request by `id`. Lines that are not JSON or carry another `id` are skipped. A reply without a boolean `ok` is a transport failure. |
| Port squatting (residual) | Loopback TCP cannot prove who listens. If the application dies, a local process that binds its port before it returns receives the token on the bridge's next reconnect, and can then impersonate the application to the bridge and use the token on the real one. A unix-socket control channel checked by owner would close this; it is a possible future protocol option. |
| Methods the named verbs use | `engine.commands`, `engine.execute` (`{command, params}`), `ui.inspect`, `ui.screenshot` (`{path?, focus?}`). An application without one of them answers `ok:false`; `<app>.call` reaches any other method. |

## Bus verbs

An instance started with `--name <app>` answers under its own name.

| Verb | Body | Sends | Reply on rc 0 |
|---|---|---|---|
| `<app>.call` | `{method, params?}` | `<method>` with `params` (default `{}`) | the app's `result` |
| `<app>.commands` | — | `engine.commands` | the app's `result` |
| `<app>.execute` | `{command, params?}` | `engine.execute {command, params}` | the app's `result` |
| `<app>.inspect` | — | `ui.inspect` | the app's `result` |
| `<app>.screenshot` | `{path?, focus?}`, or empty | `ui.screenshot` with only those keys | the app's `result` |
| `<app>.status` | — | nothing | `{service, connection, host, port, auth, instance, connects, failures, calls, last_error, last_latency_ms, retry_after_s}` |

`connection` is `never-connected`, `up` or `down`. `status` never contains
the token.

| rc | Meaning | Body |
|---|---|---|
| 0 | The app replied `ok:true` | its `result` as JSON |
| 10 | The app replied `ok:false` | its `error` text |
| 11 | Connect, auth, transport or timeout failure, or backing off after one | text saying which |
| 12 | A bad request from the caller (missing field, body not a JSON object, an encoded request over `max_line`) | text naming the problem |

Every call has one transport deadline, `timeout_s`, starting when the call
does. Connect, the auth line and its reply, and the request and its reply
all draw on that one budget: each write gets the time left as `tcp_send`'s
`{timeout}`, which bounds the whole send, and each read gets the time left
too. So a peer that stops reading or reads too slowly cannot hold a call
past it: the write fails, the call answers rc 11 and the connection is
dropped. A budget already spent before a write fails the same way without
sending.

The budget bounds transport, not local work. Encoding the request
(`json_encode`) and Mix's scheduling run on the same clock but cannot be
interrupted, so they can take a call past `timeout_s`; the next transport
step then fails at once without touching the network. For example, a
32 MiB request with `timeout_s` 0.001 spends tens of milliseconds encoding,
then is refused before writing. This needs Mix >= 0.112.1; on an older Mix
the bridge refuses to start (`RUNTIME`).

After a transport failure, or a reply without a boolean `ok`, the connection is dropped and no new one is tried for
`backoff_s`; calls in that window answer rc 11 at once.

The token never appears in a reply: any occurrence of it, in any letter case,
in an app's error text, in a result, or in `last_error`, is replaced by
`[redacted]`.

**Registration.** The six verbs are an instance family, `<app>.<verb>` with
owner `bridged` and `members: "instances"` (runtime members, not listed). They
are declared in `docs/docs/spec/bus/verbs.conf.mix` (registry schema 3). The static
gate `tools/verb_registry.mix` checks the family's owner and suffix;
`tools/verb_registry.mix --instances DIR` checks private file-stem naming and
collisions only and reads no config token. The runtime guard reads the verbs
and families lists but does not enforce the full canonical format. Installing
the registry is a separate deployed prerequisite: the scripts and the registry
come from the same revision, at `/opt/mixos/share/bus/verbs.conf.mix` or the
`BRIDGED_VERBS` override.

**Classes.** `<app>.call` and `<app>.execute` are `intent`; `<app>.commands`,
`<app>.inspect` and `<app>.status` are `query`. `<app>.screenshot` is `intent`,
because its `focus` option can bring the window forward, a change another
caller sees, even though the verb otherwise only captures. The reasoning is in
the [decision](../../decisions/2026-10-13-instance-verb-families.md).

## Instance config, version 0.2.0

A strict-data document (`load_data`; never executed).

**Path:** `$BRIDGED_CONFIG` when set; otherwise `<etc>/bridge/<app>.conf.mix`,
where `<etc>` is `$MIXOS_ETC` when set, else `/etc/mixos`. The file stem is
the serve name.

```text
port: 47801,
token_file: "/home/user/.config/fakeapp/control.token",
timeout_s: 20
```

| Key | Type | Default | Rule |
|---|---|---|---|
| `port` | integer | required | 1–65535 |
| `host` | string | `"127.0.0.1"` | `"127.0.0.1"` or `"localhost"`, which is connected to as `127.0.0.1` (never `::1`); anything else is refused |
| `auth` | string | `"token"` | `"token"`, `"key"` or `"none"`; an explicit `nil` is refused |
| `token_file` | string | — | required with `auth: "token"` or `"key"`, refused with `auth: "none"`; a leading `~/` expands to `$HOME`. With `key` it is the key file, read on every connect; a missing or unusable key is rc 11 before any connect, and the next retry after `backoff_s` reads it again |
| `timeout_s` | number | 5 | (0, 300]: the whole-call deadline |
| `connect_timeout_s` | number | 2 | (0, 300]: the connect step, within the deadline |
| `backoff_s` | number | 2 | [0, 300]: the pause after a transport failure |
| `max_line` | integer | 1048576 | 64–16777216 bytes per line, both ways: a longer reply is a transport failure (rc 11); a longer request is refused before it is sent (rc 12) |
| `instance` | string | — | 1–64 of `[A-Za-z0-9_-]`; echoed by `status` so a launcher can recognise its own bridge |

Unknown keys are refused, so a typo never falls back to a default. The token
file holds exactly 64 hex characters (one trailing newline allowed) and has
no group or other permission bits (`chmod 600`). Errors name the file, never
its content.

## Serve name and the start checks

The name must match `^[a-z][a-z0-9-]{1,30}$`, the Bus's own rule for a
service name, and must not start with `mixos-` (`mix --serve` strips that
prefix before registering, so the checked name and the Bus name would
differ). The broker's own names are refused as noded refuses them: `noded`,
`noded-*`, and the session-name shape `<t|c><1-7 of [a-z0-9]>-<22 of
[a-z2-7]>`. It must also not be the first segment of a verb the registry
already gives to another component, so an instance can never answer, say,
`settings.status`. The registry read is `$BRIDGED_VERBS`, else the installed
`/opt/mixos/share/bus/verbs.conf.mix`:

| Registry entry | Reserves |
|---|---|
| `verbs: [{name, ...}]` | the first segment of `name`, whatever the status (retired names stay reserved) |
| `families: [{pattern, members: "instances"}]` | nothing (runtime members, such as bridged's own family) |
| `families: [{pattern, members: [names]}]` | each listed name |
| `families: [{pattern}]` with a literal first segment | that segment; an `<app>` or `*` first segment reserves nothing |

The guard fails closed: a missing or unreadable registry, one without a
`verbs` list, an entry without a `name` or `pattern`, or an unknown `members`
form refuses the start. `families` is optional, so the schema-1 registry and
later schemas with families both read.

A refused start prints `bridged: refusing to start: CODE: message` and exits
2. Codes: `RUNTIME` (Mix older than 0.112.1), `NAME_INVALID`, `NAME_RESERVED`,
`REGISTRY`, `CONFIG`, `TOKEN`.
`mix bridged.mix --check <app>` runs the same checks without joining the Bus
and exits 0 when the instance may start; an unexpected error at start exits 3,
never 2.

The unit runs `mix bridged.mix --start <app>`. That process runs the same
checks in process, before the name reaches the Bus, and exits 2 on a
documented refusal without starting anything. Otherwise it runs
`mix --serve bridged.mix --name <app>` as its child (no shell) and exits with
the child's exit code. Mix has no process-replacing exec, so the parent and
child pair is deliberate; the unit's control-group kill stops both. The unit
never restarts on exit 2 (`RestartPreventExitStatus=2`); every other non-zero
exit, including a missing or unreadable script (exit 1), is a failure,
restarted under `Restart=on-failure` and rate-limited by
`StartLimitBurst=5` in `StartLimitIntervalSec=60`. A clean stop exits 143:
systemd signals both processes, and Mix records the SIGTERM the parent gets
and exits 143 whatever the child returned, so the unit lists
`SuccessExitStatus=143`. `$BRIDGED_MIX` overrides the mix binary the child
runs under (default `/opt/mixos/bin/mix`); it exists for tests.

Starting `mix --serve bridged.mix --name <app>` directly, not through
`--start`, registers the name on the Bus before the checks run, so a
refused name holds a free Bus name for a moment before the process exits.
`--start` (the unit) is the supported path. The reverse collision, a verb
registered later whose first segment is an instance already running, is
the verb-registry gate's to refuse, not the bridge's: the bridge checks only
at start.

The unit is sandboxed: no capabilities or new privileges, the file system
read-only with private `/tmp` and `/var/tmp` (config and token files must
live elsewhere), address families limited to IPv4, IPv6 and unix sockets,
and IP traffic to loopback only (`IPAddressAllow=localhost`,
`IPAddressDeny=any`). A Bus endpoint off loopback needs a drop-in adding its
address to `IPAddressAllow`. The IP filter is cgroup BPF: enforced on hosts
that support it, ignored where they do not, and not proven by the offline
`systemd-analyze security` score.

`--start` outside systemd has no parent-death protection: killing the
`--start` process alone can orphan the serve child. Run it under the unit,
whose control group holds both. `BRIDGED_MIX` and the instance's `.env` file
must be administrator-controlled: anyone who can change them picks the code
that runs as `mixos`.

## Changes

- 0.2.0 (2026-10-13): additive `auth: "key"` (`params.key`, secret read from
  `token_file` on each connect). Token and none modes are unchanged.
- 0.1.0 (2026-10-10): first version.

---

<!-- page: https://mixos.dev/docs/spec/handler-closure-capture/ (source: https://mixos.dev/docs/spec/handler-closure-capture.md) -->

# Handler closure capture

Lambdas defined inside an `on` handler capture its local variables by value,
including callbacks passed to `map` and `all` and nested callbacks. Those
locals remain available if the closure escapes the handler. Global variables
continue to be read live; capturing handler locals does not freeze globals.

Each handler invocation has its own local frame. A closure retains the locals
of its defining invocation, rather than reading another invocation's locals.
Assignment inside a closure continues to bind a function-local variable.

---

<!-- page: https://mixos.dev/docs/spec/mix/2026-10-08-programs-and-documents/ (source: https://mixos.dev/docs/spec/mix/2026-10-08-programs-and-documents.md) -->

# Mix program and document file-family contract

Status: accepted target contract, version 1.0.0, 2026-10-08. Planned for the next
major Mix refactor/deployment; no current-binary conformance is claimed. Authority:
[programs and documents decision](../../decisions/2026-10-08-mix-programs-and-documents.md).

## 1. Families, not dialects

`.mix` is executable Mix. `.mx` is a declarative Mix document. Macro, behaviour,
module, task, installer and resident citizen are executable roles; configuration,
theme, spec, catalogue, manifest, policy and scene are document schemas/purposes.
The public API vocabulary is program/document, not safe/unsafe script flavours.

The same interpreter and program grammar serve every executable role. Full
language access remains subject to caller OS permissions and existing host
capability policy; it does not imply privileged execution. Schema binding
evaluation uses the existing pure expression implementation, never a second
general interpreter or a quietly expanded builtin allowlist.

Canonical new data filenames end in `.mx`, for example `node.mx`, `settings.mx`,
`theme.mx`, `scene.mx`, `template.mx` and `authority.mx`. Stems follow existing
repository naming rules and describe purpose where useful; no new compound
suffix is required to select a trust class. Executable test gates remain `.mix`;
their declarative fixtures become `.mx`.

## 2. Program/file admission

All file-based program entry points refuse `.mx` before evaluating any content:

- Direct CLI program execution, `--serve`, interactive file execution and every
  serve initial load, reload candidate and committed generation.
- `source`, `include`, `require`, prelude/startup file loading and any equivalent
  executable file reader in the library or an embedder.
- App macro runners, scene behaviour launchers and automation dispatchers.

Provide a stable structured refusal code and diagnostic saying that the file is
a document and requires a document reader. Exact code registration occurs with
the implementation. `--no-lint` and normal script flags do not bypass admission;
there is no general execute-document override.

Check both the requested path and resolved file target, including symlinks, with
one shared policy used across callers. `.MX` is also refused on executable paths;
writers emit lowercase `.mx`. Filename admission is not a comprehensive security
boundary: renaming, explicit source-string evaluation and intentionally running
a program remain under the caller's authority. Strict parsing is what keeps
document consumption non-executing.

Anonymous program source (`-c`, stdin, library source-string APIs) remains
explicitly executable input, with existing capability policy. Document readers
must never pass document bytes to those APIs or reclassify a failed parse as
program source. Do not disable ordinary stdin/REPL workflows to simulate content
provenance that the runtime cannot establish.

Document checking/linting is non-executing. CLI `--check`/check/lint handling of
`.mx` must validate as a document, or return a clear unsupported-schema/kind
diagnostic. It must never report executable syntax checks as document validation.
The implementation must define this UX and its machine-readable output, without
silently guessing an executable fallback.

## 3. Document readers and schemas

Generic `.mx` documents use the existing strict parser: literals, lists, maps,
comments and the existing round-trip encoding. It refuses variables, calls,
command substitutions, interpolation, statements and executable separators.
`load_data` remains a data-only API and is documented for `.mx`; parsing failure
is terminal for that load. It does not invent filenames or dispatch script code.

Application/service-owned documents additionally validate their owning schema.
The caller may supply schema identity and version, or the document may declare
them; if both do, disagreement is refused. Generic literal data need not carry
an app schema. Schema identity/version are semantic, not another filename family.
Existing numeric `schema` fields do not have to be converted to strings merely
to rename files. Migration must preserve each owning schema's version semantics.

Scene `.mx` documents retain their current `---` header envelope and fenced
strict-data widget map in this first refactor. The existing scene reader handles
that structure; the generic strict reader does not become a scene interpreter.
A consumer explicitly selects its document reader/kind. An unknown kind/schema,
invalid envelope, malformed widget map or invalid binding produces a document
error. No candidate reader is ever the executable parser.

Do not couple extension migration to a rewrite of scene metadata or layouts.
If a common strict-data scene envelope is useful later, version it and provide
a migration independently. Existing layout, model, action-name, diff and source
round-trip contracts must remain intact in this release.

## 4. Restricted bindings and action authority

Only schema-declared fields can interpret restricted expression strings. In all
other fields the identical string is literal data. The scene binding compiler
retains its model/item roots, allowed operations, dependency tracking and size,
time and aggregate list-row limits. Calls, assignments, shell forms, process
launches, file writes and Bus requests cannot be smuggled in through a binding.

Data may name an action implemented by a trusted application/program, but cannot
supply a general executable action body. A workflow document or rule catalogue
is not a bypass for the normal activation/authority of the program consuming it.
Do not introduce automatic command-string evaluation, executable includes or
download-and-run behaviour into document readers.

Non-executing is not synonymous with consequence-free: schemas must still bound
resource use and validate referenced paths/assets/settings according to their
own contracts. The file-family change does not promise that every configuration
value or action reference is appropriate for every consumer.

## 5. Legacy compatibility and migration

Inventory every data consumer and producer, not just files with recognised
suffixes. Include generated runtime state, embedded include_str fixtures, startup
configuration, tests, asset manifests, scenes, watched paths, install collectors,
public guides and private hub automation. Distinguish code/data from its actual
reader; names such as `data.mix` can be executable helper modules and must not be
renamed blindly. No bulk suffix replacement or executable grammar change.

Use explicit rollout phases:

1. Readers gain `.mx` support and legacy data compatibility. Program paths refuse
   `.mx`. Record capability/version evidence on every deployment target.
2. Migrate source fixtures and literals, install collectors and app/service path
   resolvers. Deploy coupled binary/script bundles while retaining legacy files
   needed by unmigrated callers.
3. Switch owning writers to canonical `.mx` only after their readers are ready.
   Migrate user files explicitly and retain recoverable originals and a receipt.
4. Remove legacy spellings only after every supported consumer and tested rollback
   is accounted for, through a documented compatibility-removal release.

Generic `load_data(path)` uses the literal supplied path; it must not silently
rewrite arbitrary `.mix` filenames. Owning configuration/scene resolvers may
support old/new alternatives explicitly. If both exist, compare typed semantic
values under the owning schema: equivalent copies get a visible migration
diagnostic; differing copies are a conflict requiring explicit resolution. A
malformed canonical file does not cause a quiet fallback to an old file.
Declared precedence or explicit operator selection must be observable.

Migration tools run in Mix through native facilities, with a preview/report,
idempotent apply, ownership checks, originals and bounded failure recovery. Do
not rewrite schema versions, erase comments, overwrite user edits or convert
operational identities without a specific migration requirement. Preserve state
and registry format identities, hashes/signature domains and frozen ABP bytes.
Any affected signed artefact is reissued through its existing native authority;
renaming a signed path is not permission to edit signed content in place.

## 6. Component integration and deployment

`libs/strict`, `libs/expr` and `libs/scene` keep their headless separation from
the full Mix interpreter. `libs/mix` and `cli/mix-shell` share program admission;
`libs/config` and owning services/apps handle document paths/schema validation.
Use existing install collectors and native deployment/lifecycle facilities. No
new broker, alternate node-control transport or duplicate parser is introduced.

This is a coordinated binary/library/consumer refactor, not a stand-alone CLI
rename. Build provenance must identify the exact revision, language/library and
binary versions, enabled features, test receipts and installed document formats.
Select the actual release number and compatibility window in its release record.
The current source baseline is language 0.109.1 / binary 0.109.4; that is not the
new release or evidence about every installed target.

Qualify an isolated native target before any working desktop, then roll through
explicitly selected native targets. Stage readers before documents and writers;
verify the real ABP path, loaded scenes/configuration and executable macros. The
self-contained VT-native image carries all readers, interpreter and documents.
It must not depend on host packages or host desktop/session resources.

Rollback includes compatible binary, consumer scripts and document/state copies.
Restoring only the previous binary after a filename migration is insufficient.
Candidate reload failure must preserve the accepted evaluator and managed children.
Frozen MixOS nodes keep their old spellings until separately migrated; no broad
fleet deploy or production restart follows merely from accepting this spec.

## 7. Required acceptance matrix

| Boundary | Required evidence |
| --- | --- |
| Program admission | Valid and malicious `.mx` refused by direct CLI, serve/reload, REPL file launch, source/include/require, macro and library file APIs before a marker effect occurs; cover symlinks, uppercase and `--no-lint` |
| Strict data | Valid `.mx` round-trips; variables, calls, interpolation, substitutions and statements refuse; errors cannot enter executable fallback |
| Scenes | Existing fixtures renamed without semantic change; pure bindings resolve, effectful bindings refuse, resource bounds and layout/model diffs still pass |
| Schema selection | Known versions work; unknown/mismatched schema/kind, invalid fields and malformed canonical files refuse visibly |
| Legacy coexistence | Old/new readers, generated writers, equal/conflicting duplicate files, missing paths, idempotent migration and interruption recovery behave as specified |
| Native applications | Ced macro/undo remains executable `.mix`; all six app consumers, Quoin scenes and relevant service configuration load through their real native path |
| Packaging/identity | New image has required documents/readers; signed path changes use the native authority; freeze checks confirm no ABP wire/domain-byte changes |
| Deployment/recovery | Exact candidate build runs on isolated target; selected-target rollout reports loaded formats and final state; old binary-plus-data rollback actually restores service/scene/macro behaviour |

Implement declarative fixtures as `.mx` and executable integration gates as `.mix`.
Use negative tests with observable marker effects rather than tests that merely
check an extension helper. Successful docs builds, renamed files or mock readers
do not establish runtime conformance. No extra script families may be introduced
as a shortcut around these boundaries.

---

<!-- page: https://mixos.dev/docs/spec/portal/ (source: https://mixos.dev/docs/spec/portal/README.md) -->

# Portal contract: Settings and ScreenCast

Settings status: accepted, version 0.1.0 (ScreenCast is a draft, below). The cbc2 verification of `services/portald`
passed on the commit that carries it (dcd2f1a). The verbs and wire shapes below
are fixed by the XDG portal specification.

`portald` implements the Settings interface of the XDG desktop portal, on the
session bus, for the `org.freedesktop.appearance` namespace. The machine-checkable
key table is in [portal.spec.mix](portal.spec.mix).

## Bus identity

| Item | Value |
|---|---|
| Bus name | `org.freedesktop.portal.Desktop` (requested without queueing) |
| Object path | `/org/freedesktop/portal/desktop` |
| Interface | `org.freedesktop.portal.Settings`, version property 2 |
| Error prefix | `org.freedesktop.portal.Error` |

## Methods and signal

- `Read(s namespace, s key) -> v`: the value in one extra variant layer,
  deprecated form.
- `ReadOne(s namespace, s key) -> v`: the value in a single layer.
- `ReadAll(as namespaces) -> a{sa{sv}}`: globs matched against namespaces.
  An unmatched glob yields no namespace entry. An empty array or any empty
  filter matches all namespaces. Up to 64 filters of 256 bytes each are accepted;
  larger requests return `org.freedesktop.portal.Error.InvalidArgument`.
- `SettingChanged(s namespace, s key, v value)`: emitted only when a key's value
  changes.

An unserved namespace or key on `Read` or `ReadOne` returns
`org.freedesktop.portal.Error.NotFound`.

## Keys

| Namespace | Key | Wire type | Values |
|---|---|---|---|
| `org.freedesktop.appearance` | `color-scheme` | `u` | 1 dark, 2 light |
| `org.freedesktop.appearance` | `contrast` | `u` | 0 normal, 1 high |
| `org.freedesktop.appearance` | `accent-color` | `(ddd)` | sRGB 0 to 1; absent when the source has no accent |

Defaults before any projection: `color-scheme` 1 (dark), `contrast` 0, no
`accent-color`.

## Source and identity

- Source verb: `settings.appearance.get`, read-only, from `settingsd`.
- The reply carries the atomic snapshot evidence alongside the projection.
  The shared settings Consumer checks the evidence and manages subscription,
  initial reads, lifecycle generations, delivery loss and bounded recovery.
- Trigger: authenticated retained topic `settingsd.desktop.changed.<profile>`.
  A publication also triggers a read when settingsd restarts at the same revision.
- A projection is identified by binding, incarnation and revision. A projection
  older than the held one within the same incarnation is refused and counted as
  stale. An equal identity changes nothing. A new incarnation is adopted.
- The authority's projection schema is `APPEARANCE_SCHEMA = 1`. An unknown
  schema is refused.

## Startup

1. Load the validated binding-specific cache at
   `<state directory>/<instance>/<profile>/appearance.json`, else defaults.
   A mismatched binding and the old unpartitioned cache are ignored.
2. Request the bus name without queueing immediately. A held name refuses a
   second instance. Authority work runs asynchronously.
3. Answer Read within 250 ms of process launch, tested with the production binary
   and configuration against a silent authority, including cache and profile switch.
4. Serve, and back off on source failure from 250 ms to 30 s. Transport recovery
   remains alive through initial broker failure.

The name is never held waiting on the source.

## Verbs

`portald.status` (read-only) is registered in `docs/docs/spec/bus/verbs.conf.mix`.

## Compatibility

Version 2 of the interface is the one served. A breaking change to a method
shape, key type or key value needs a new interface version, and both versions
must be served during the deprecation period.

## ScreenCast

Status: draft. Served with `portald serve --screencast`; first verified on
desk12 VT4, 2026-10-20 (a 3840x2160 frame received through the portal by a
PipeWire consumer). The method and signal shapes are fixed by the XDG portal
specification; what MixOS offers within them is below.

| Item | Value |
|---|---|
| Interface | `org.freedesktop.portal.ScreenCast`, version property 5, same object |
| `AvailableSourceTypes` | 1 (monitor) |
| `AvailableCursorModes` | 3 (hidden, embedded) |
| Request path | `/org/freedesktop/portal/desktop/request/<sender>/<handle_token>` |
| Session path | `/org/freedesktop/portal/desktop/session/<sender>/<session_handle_token>` |

`<sender>` is the caller's unique name without the leading `:` and with `.`
as `_`. A token is 1 to 64 ASCII letters, digits or `_`; an absent token is
generated.

- `CreateSession(a{sv}) -> o`: `Response` 0 with `session_handle` (`s`).
- `SelectSources(o, a{sv}) -> o`: `types` must include 1; `cursor_mode` 1 or 2
  (default 1); otherwise `InvalidArgument` at the call. `multiple` and
  `persist_mode` are accepted and ignored. `Response` 0.
- `Start(o, s, a{sv}) -> o`: `InvalidArgument` before `SelectSources` or when
  already started. `Response` 0 with `streams` `a(ua{sv})` (one stream:
  `position (ii)`, `size (ii)` in logical coordinates, `source_type` 1, `id`
  the output name) and `persist_mode` 0; `Response` 2 when nothing can be
  captured.
- `OpenPipeWireRemote(o, a{sv}) -> h`: after a successful `Start` only.
- Every `Response` is addressed to the owner. `Request.Close` by the owner
  removes the request with no `Response`; a `Start` closed this way stops its
  cast.
- A session is the caller's alone: another caller gets `NotFound` (methods)
  or `AccessDenied` (`Session.Close`). It ends on `Session.Close` (no
  signal), on its owner leaving the bus, or with `Session.Closed` when capture
  stops on its own.
- The stream is a PipeWire node with `media.class` `Video/Source`, `BGRx`, the
  output's mode size, variable rate up to 30 fps, memfd buffers.

Consent: every `Start` is granted by the `allow` policy, a standing grant
matching the caller's process name, or an answer to a notifyd question (Allow /
Deny, 60 s, timeout denies). A refusal answers `Response` 1. Bus verbs, all
local-only (`broker_origin` must be `local`, else rc 13 `FORBIDDEN`):
`portald.screencast.pending` (query), `portald.screencast.answer {request,
allow}` (input), `portald.screencast.grant {app?, count?, ttl_ms?}` (intent),
`portald.screencast.revoke {id?}` (intent). Registered in
`docs/docs/spec/bus/verbs.conf.mix`.

## Deferred

- The FileChooser interface.
- ScreenCast: window sources, several streams, restore
  tokens, DMA-BUF frames and a permission-limited remote.
- Accent as a settings field. The current projection carries the design's
  resolved accent through settingsd's in-memory sidecar, outside the sealed
  snapshot.
- Caller identity and sandboxed app IDs.

---

<!-- page: https://mixos.dev/docs/spec/props/ (source: https://mixos.dev/docs/spec/props/README.md) -->

# Service property contract

Status: accepted, version 0.2.1. This records the existing structured
namespace wire surface implemented by `props`' optional store and router.
The [ownership decision](../../decisions/2026-10-18-property-store-in-props.md)
places it in `libs/props`. Verbs belong to the service exposing them and
must be registered under that owner in the [Bus registry](../bus/verbs.conf.mix).

## Addressing

Commands are `<svc>.props.<suffix>`. The `namespace` header names a
registered unqualified namespace; its capability name is `<svc>.<namespace>`.
Collection records require a non-empty `key`. Singleton requests omit `key`
or send an empty key; replies use the schema's canonical key.

`if_version` is an optional decimal u64 fence, required when the namespace
declares `require_version`; zero fences creation. Record `version` and
namespace `nseq` increase on commits. `cause` is an optional correlation
string on mutations. Actor identity comes from the authenticated peer,
never a caller-supplied actor header. `_lifecycle` is reserved.

This surface requires structured addressing. `set` refuses `path` with
`flat_path_mutation_deferred`; other verbs refuse it as mixed addressing.
The compositor's flat `{path,value,generation}` mutation remains its own
contract. `field_path` is refused on set/delete/get, even when empty.
Get refuses any non-empty body. List refuses `cursor`, `limit`, `order_by`,
`filter`, `fields` and any non-empty body. These refusals carry diagnostic
prefixes `field_path_deferred`, `get_projection_deferred` or
`list_option_deferred` under `validation_error`.

## Verbs

| Suffix | Headers/body and successful reply |
| --- | --- |
| `set` | JSON object body; `merge=true`/`patch` (default) or `false`/`replace`. Simple reply: `{namespace,key,version,nseq,created,warnings?}`. Saga reply: `{namespace,key,set_version,set_nseq,complete_version,complete_nseq,lifecycle,created,reason?}`. |
| `delete` | Collection only; optional `if_version`, `cause`. Reply: `{namespace,key,deleted:true,tombstone_version,nseq}`. |
| `get` | `{namespace,key,version,nseq,fields}`; `nseq` is the observed namespace cursor. |
| `list` | `{namespace,nseq,records:[{key,version,fields}],next_cursor:null}`. |
| `describe` | `view=public` (default) or `full`; `{namespace,schema_version,cardinality,fields,primary_key_field?}`. Fields carry name, type, secret flag, default, validators, help and optional since/until. |
| `watch` | Optional decimal u64 `since_nseq` (default zero); grant live delivery then return `{namespace,observed_nseq,events,live:true,caught_up:{event_type:"caught_up",namespace,nseq}}`. |
| `audit.watch` | Same cursor and grant sequence; audit rows in `events`, with no `caught_up` field. |

Get/list/describe are queries; set/delete/watch/audit.watch are intents.
Watch verbs install an observable broker subscription. Replay-only
`live:false` is available exclusively in the library's unit tests.

## Capabilities and redaction

Policies resolve `PeerIdentity` into exact capability strings:
`props.read:<svc>.<ns>`, `props.write:<svc>.<ns>`,
`props.describe:<svc>.<ns>:public`, `props.describe:<svc>.<ns>:full`,
`props.audit:<svc>.<ns>` and `props.read:<svc>.<ns>:secrets`.
Set/delete require write, get/list/watch require read, and audit.watch
requires audit independently of read. Describe requires the selected view's
capability; `schema_public=deny` refuses public describe.

Get/list replace fields declared `secret:true` with null unless the caller
also has the explicit secrets capability. Stored values are projected
verbatim without filling missing defaults, preserving audit reproducibility.
Public describe omits secret fields and redacts secret validator names.
Passive event topics never carry record values or secret field names.
Audit keys remain in the owner's private storage and never enter the Bus.

## Watch and topics

The reserved topics are `<svc>.props.records.changed` and `<svc>.props.audit`.
Only the owner publishes; direct `topic.subscribe` is refused, including
for the owner. After its capability check, the service calls
`noded.props.subscribe_grant` with non-empty `topic`, `target_peer` and
`namespace` headers. The broker authenticates the topic owner, requires a
connected registered target, and installs a top-level namespace body filter.
Success returns `{subscription_id,namespace}` with rc 0; refusal uses rc 10
(including `target_peer_not_connected`). The registered verb's owner is
`noded`, class `intent`, version 0.1.0.

The grant completes **before** the observed cursor is captured. Replay
contains `since_nseq < nseq <= observed_nseq`; later events are eligible
for live delivery. The `caught_up.nseq` is always the observed cursor,
including when the caller supplied a higher cursor. Process replay, then
the marker, and discard overlapping live events through that cursor;
deduplicate by `(namespace,key,nseq)`.

Records-changed bodies contain `namespace,key,kind,verb,nseq,version,
audit_epoch,actor,ts` and optional `fields_changed`,
`secret_fields_changed_count`, `cause`, plus `lifecycle,reason?` on completed
events. Kinds are `created`, `updated`, `deleted`, `completed`, `reconciled`.
Audit bodies contain `namespace,key,verb,version,nseq,audit_epoch,actor,at,
audit_digest` and optional `fields_changed`; they omit kind, lifecycle,
cause and secret count. Timestamps use RFC 3339 UTC with milliseconds.
Records-changed bodies omit the digest. Both topics use `retain:false`.

Replay and live publication share the same projection functions. Each
dispatcher starts at the current cursor, preserving older history for
replay. Publication is best-effort: errors are logged and the cursor still
advances; recover through watch. A missing granter returns `unavailable`;
grant failure returns `grant_failed` without leaking upstream routing detail.

## Errors

Failure bodies contain `{error_code,message}`; the Bus error field carries
the human message. Success is rc 0. The closed vocabulary is:

| rc | `error_code` |
| --- | --- |
| 10 | `auth_denied`, `not_found`, `validation_error`, `conflict`, `version_mismatch`, `replay_window_exceeded`, `grant_failed` |
| 20 | `storage_error`, `hook_error`, `unavailable` |

Version mismatches add `expected_version,current_version`; replay-window
errors add `since_nseq,oldest_nseq`. Validation-hook rejection maps to
`validation_error`; an operational hook failure maps to `hook_error`.

## Storage

`SqliteStore` owns exactly five table names and their frozen DDL:
`__props_meta` (namespace nseq and audit epoch), `__props_records` (versions,
lifecycle and tombstones), `__props_events` (durable replay/audit history),
`__props_audit_keys` (per-namespace private keys) and `__props_values`
(the optional default JSON mapping). The schema-compatibility test pins
all five definitions from `sqlite_master.sql`. Existing databases open
without migration. Domain mappings own their business tables and must
participate in the substrate's single `BEGIN IMMEDIATE` transaction.

Hard delete removes metadata and restarts a recreated record at version 1;
it cannot require version fencing. Soft delete retains the tombstone
version and recreates against that version. Tombstones do not yet expire.
Saga writes commit provisioning before completion to active or failed.
Reconciliation alone increases audit epoch. Each event digest is lowercase
hex HMAC-SHA256 over canonical sorted-key JSON plus its nseq as eight
big-endian bytes, using a private 32-byte namespace key; deletes hash null.
There is no previous-digest chain. The in-memory backend is for tests and
in-process services and implements hard deletion only.

## Logging

The opt-in `logging/props` bridge registers singleton `log`, canonical key
`current`. Its fields are `level` (`none,error,warn,info,debug`, default info),
`filter` (EnvFilter string, default empty), `format` (`human,json`, default
human), `applied_at` and `source` (strings, default empty), and `applied_by`
(`cli,env,props,default`, default default). All remain mutable. Hooks reject
invalid enums/filter syntax and all deletes using prefixes
`log_unknown_enum_variant:`, `log_filter_invalid:` and `log_undeletable:`.
The watcher applies level/filter, using `off` for none; it neither rebuilds
sinks nor writes metadata back. Its private Notify is separate from the
dispatcher signal. Registration/read failures map to `LogError::Props`.

---

<!-- page: https://mixos.dev/docs/spec/releases/ (source: https://mixos.dev/docs/spec/releases/README.md) -->

# Releases contract

Status: accepted, version 0.3.0 (0.3.0 adds optional `category` metadata;
0.2.0 adds `exec_wrapper`). Verified by
`services/releasesd/tests/releases_test.mix` (offline logic) and
`services/releasesd/tests/releasesd_test.mix` (every verb over a private
broker).

`releasesd` follows GitHub repositories named in a per-user catalogue and
installs their Linux release tarballs for that user. This page fixes the
catalogue schema, the Bus verbs and the on-disk layout that other tools may
rely on.

## Bus identity

| Item | Value |
|---|---|
| Service | `releases` (`mix --serve releasesd.mix --name releases`) |
| Verbs | `releases.status`, `.list`, `.check`, `.notes`, `.install`, `.update`, `.rollback`, `.remove`, `.link` |
| Bodies | JSON objects; `{}` or an empty body where no field is required |
| Success | rc 0, JSON reply |
| Refusals | rc 10 bad request, rc 14 unknown app, rc 15 the operation failed; body `{error_code, message}` |

Error codes: `USAGE`, `ROOT`, `UNKNOWN_APP`, `CATALOGUE`, `NO_RELEASE`, `NO_ASSET`,
`AMBIGUOUS_ASSET`, `DOWNLOAD`, `DIGEST`, `UNVERIFIABLE`, `LAYOUT`,
`NO_PREVIOUS`, `PENDING`, `BUSY`.

| Verb | Body | Reply |
|---|---|---|
| `releases.status` | — | `{catalogue, apps, installed, root, share, bin, state, authenticated, arch}` |
| `releases.list` | `{apps?}` | rows from the last check |
| `releases.check` | `{apps?}` | rows after asking GitHub |
| `releases.notes` | `{app}` | `{app, tag, published, url, notes}` |
| `releases.install` | `{app, tag?}` | result |
| `releases.update` | `{apps?}` | results; default every installed app |
| `releases.rollback` | `{app}` | result |
| `releases.remove` | `{app}` | result |
| `releases.link` | `{apps?}` | results |

A row is `{app, repo, category, category_label, installed, latest, published, checked, status}`, with
`category` the catalogue's optional group and `category_label` its display label
(null when absent), and
`status` one of `current`, `update`, `not installed`, `unchecked` or
`error: <text>`. A result is `{app, action, version?, previous?, verified?,
links?, skipped?, error?}`; `verified` is `{asset, sha256, proofs, tag}`.

## Catalogue, schema 1

The optional top-level `categories` map supplies display labels for supported
groups, for example `{creative: "Graphics"}`. Labels must be non-empty strings
of at most 64 characters without control characters. Labels are projected onto
rows so Prefs can use catalogue terminology without knowing external products.

A strict-data document, by default `$XDG_CONFIG_HOME/mixos/releases.mx`
(`~/.config/mixos/releases.mx`). A missing file is the default catalogue,
MixOS itself: `mixos-desktop` and `mixos-server`, both from `markc/mixos`. It
is re-read on every request.

```text
{
  schema: 1,
  apps: [
    {name: "example", repo: "owner/example"},
    {name: "other", repo: "owner/other", asset: "(?i)linux-x86_64-full\\.tar\\.gz$"}
  ]
}
```

| Field | Rule |
|---|---|
| `name` | `^[a-z0-9][a-z0-9-]{0,63}$`, unique; it becomes a directory name |
| `repo` | `owner/name` on GitHub |
| `asset` | optional regex choosing the tarball when the default is wrong or ambiguous |
| `category` | optional `mixos-desktop`, `mixos-server`, `creative` or `other`, used by Prefs to group rows; omitted entries remain in Other, with legacy MixOS bundle identifiers recognised |
| `exec_wrapper` | optional list of 1–32 non-empty strings without control characters, the first an absolute path without `=`; see below |

**`exec_wrapper`.** When `link` writes the app's desktop entries, every
`Exec=` becomes `Exec=<wrapper…> -- <the entry's own Exec>`. The entry's own
Exec keeps its field codes (`%F`, `%U` …) and is made absolute as usual.
Each wrapper argument is written per the Desktop Entry Specification: `%` is
doubled; an argument with a reserved character is double-quoted, with
`"` `` ` `` `$` `\` escaped inside the quotes; then every backslash is
escaped once more as a string value. The literal `--` separates the wrapper
from the app's command, so a wrapper can always fall back to running that
command as it stands. Every `Exec` is wrapped, Desktop Actions included,
with whitespace before the key and around `=` allowed. The main group and
every Desktop Action must have a non-empty `Exec`, or the entry is refused
(`LAYOUT`). An install, update or rollback checks this before the version
becomes current, so a refusal changes nothing. If a wrapper is added while
an install or rollback is interrupted and the target cannot be wrapped, the
retry abandons that change: `current` returns to the other recorded version
(if that one passes), `previous` is cleared, and `meta.json` records
`abandoned: {op, target, reason}`. A rollback that does this reports it as
its result. A wrapped entry gets `DBusActivatable=false`, since D-Bus
activation would start the app without its `Exec`. `TryExec` stays the
app's real program. The entry is
rebuilt from the app's own copy on every link, so it is never wrapped twice.
The link manifest records the final content. Removing the field unwraps the
entry on the next link.

The default asset is the one release file matching `linux[-_.]<arch>.tar.gz`
(`x86_64`, `amd64` or `x64`; `aarch64` or `arm64`), excluding web builds.

## Verification

An install proceeds only if every checksum source the release publishes
matches, and at least one exists: the asset's API `digest`, and a
`SHA256SUMS`/`checksums` file (itself matched to its own API digest) that
lists the tarball exactly once. Anything else refuses with `DIGEST` or
`UNVERIFIABLE`, and nothing changes on disk.

## Trust rules

- **Never as root.** Every operation that changes files refuses with `ROOT`
  when run as uid 0, before taking any lock or creating any file. Installs
  are per user, by that user.
- **The release is checked before use.** It is unpacked into a stage without
  owners, special permissions, ACLs, extended attributes or file flags, then
  refused (`LAYOUT`) if any symlink does not lead, step by step and through
  no other symlink, to an existing file or directory inside the release; if
  it holds a special file; or if any file is setuid or setgid. Desktop entries are read
  only when they are regular files inside the release.
- **Downloads are bounded.** The tarball may not exceed its published size
  (2 GiB when none is given), a checksum file 1 MiB, and each file must
  arrive within 30 minutes.
- **A manifest is evidence, not permission.** Each entry is `{path,
  states}`, every state a link target or a sha256. A path is replaced or
  removed only if it is inside this target and still in one of its states;
  anything else is left and reported (`skipped`, `kept`). Before changing
  anything, a relink publishes an intent manifest listing each path's old and
  new state, so an interrupted relink is recognised and finished.
- **Only managed versions are touched.** A version directory is managed when
  it carries `.verified-<version>.json`. Pruning and removal touch nothing
  else; an app directory holding anything unmanaged is kept. `current` and
  names ending in `.json` are never versions.
- **A retry finishes the job.** Before `current` moves, `meta.json` records
  the new version and previous one plus `pending: {op, target}`, cleared once
  the links are done. A later install, rollback or link first resumes a
  pending transition exactly: a resumed rollback is the rollback asked for; a
  resumed install is finished before a new rollback starts from it. Several
  link targets may share one opt directory (a session seeing it read-only):
  `pending` records its originating target by a random id kept in the
  target's own `<share>/mixos/releases/.target-id` (never by path: two mount
  namespaces can show different directories at one path). Only that target
  resumes and clears it, another target's `link` only reconciles its own links, and its
  install, rollback or remove refuses with `PENDING` until the origin has
  finished.
  Installing the version that is already current reconciles its links.
- **Serialised, in one order.** Locks are always taken installation first
  (`<root>/opt/.releases.lock`, shared by every target using that opt
  directory, whatever its state directory), then target
  (`<share>/mixos/releases/.lock`). Install, update, rollback and remove hold
  both. A link holds its target and, when it can open it, the installation;
  through a read-only opt it cannot, and it then only reconciles its own links
  and never resumes a pending transition. The service also handles requests in order:
  while an install downloads, other requests wait, so callers allow minutes
  for `install` and `update`.

## Layout

Root defaults to `~/.local`.

| Path | What |
|---|---|
| `<root>/opt/<app>/<version>/` | the release prefix: `bin/`, `share/` |
| `<root>/opt/<app>/current` | symlink to the active version |
| `<root>/opt/<app>/meta.json` | `{name, repo, version, previous, verified, installed_at, pending?, abandoned?}` |
| `<root>/opt/<app>/.verified-<version>.json` | the proof of each kept version |
| `<share>/mixos/releases/<app>.links.json` | what was made in this target: `[{path, states: [{link} or {sha256}]}]` |
| `$XDG_STATE_HOME/mixos/releases/<app>.json` | the last check: ETag, latest release |

The current and previous versions are kept; older ones are pruned. Links:
`bin/*` into `<root>/bin`; desktop entries into `<share>/applications` with
`Exec`/`TryExec` made absolute through `current`; hicolor icons and MIME
packages as symlinks. A path that is not in the target's manifest is never
replaced or removed.

## Environment

`MIXOS_RELEASES_ROOT`, `MIXOS_RELEASES_VIEW` (the root as the apps see it,
for installs into a container), `MIXOS_RELEASES_SHARE`, `MIXOS_RELEASES_BIN`,
`MIXOS_RELEASES_CATALOGUE`, `MIXOS_RELEASES_STATE`, `MIXOS_RELEASES_API`
(default `https://api.github.com`) and `GITHUB_TOKEN` (else `gh auth token`).
The token is sent only to `https://api.github.com`.

---

<!-- page: https://mixos.dev/docs/spec/settings/ (source: https://mixos.dev/docs/spec/settings/README.md) -->

# Desktop settings contract

Status: accepted authority contract, version 0.4.0 (0.2.0 added the summary
topic and read view, [decision](../../decisions/2026-10-11-settings-summary-reads.md);
0.3.0 added snapshot schema 2, [decision](../../decisions/2026-10-11-settings-snapshot-schema-2.md);
0.4.0 adds key bindings, [decision](../../decisions/2026-10-11-keymaps-in-settings.md)). Full desktop consumer
integration remains in development. No frozen ABP wire bytes change.

`settingsd` serves one explicitly initialised profile in the initial slice.
`settings` provides shared headless types, resolver, consumer and snapshot reducer;
`design::DesignReadProjection` is render data that cannot construct an accepted
design or fork compiler apply lineage. Consumers are the desktop applications
and compd's Quoin shell.

## Served verbs

All trusted mesh operators can invoke these verbs. Requests carry JSON bodies;
responses preserve ordinary ABP rc conventions: 0 for handled results and 10 for
refusal, invalid input or unknown verbs. Domain status is structured in the body.

| Verb | Input and result |
| --- | --- |
| `settings.describe` | No mutation; version, fields, ranges, defaults, limits and implemented/deferred capabilities |
| `settings.get` | `{binding:{instance,profile}, view?, schema?}`; `view` `full` (default): complete accepted snapshot under `snapshot`, in `schema` 1 (default) or 2 (each distinct design projection once under `designs`, contexts naming it by digest; other schemas refused with `unsupported_schema`); `summary`: the profile's `Summary` (schema, binding, incarnation, revision, design revision, source digest, appearance names, `custom_source`, `keymaps` when any are set, `terminal` when any value is set, and `email` when any value is set; never projections or a source) under `summary`; both with publication/recovery status |
| `settings.appearance.get` | `{binding:{instance,profile}, schema?}`; read-only appearance projection (`mode`, `contrast`, sRGB `accent`) tagged with incarnation and revisions; the reply also includes the atomic `snapshot` (in `schema` 1 or 2, as for `settings.get`) for shared Consumer validation; `wrong_target` on a foreign binding |
| `settings.validate` | Fenced apply-shaped body; resolve/compile candidate without a write or receipt; valid with current base identity or diagnostics/conflict |
| `settings.apply` | Fenced batch described below; durable changed/unchanged receipt |
| `settings.reset` | Apply-shaped body with empty changes and explicit reset paths; same transaction semantics |
| `settings.status` | Binding plus optional operation_id; accepted/published revision and retained receipt or unknown_operation |

The profile identifier and instance use 1–64 ASCII letters, digits, dash or
underscore. Operation IDs use the same character set, up to 128 bytes. Revisions
are canonical decimal u64 **strings**, including on strict-data boundaries;
numeric, overflowing, signed and leading-zero representations are refused.
Panel thickness accepts a whole numeric value such as 48 or 48.0, within its
declared range; Mix data numbers use floating representation. Fractional values,
numeric strings and overflow are refused before acceptance.

```json
{
  "binding": {"instance": "example", "profile": "default"},
  "expected_incarnation": "authority-readback-uuid",
  "expected_revision": "1",
  "operation_id": "example-batch-1",
  "changes": {
    "appearance.mode": "light",
    "ui.text_scale": 1.1,
    "shell.panels.bottom.thickness": 48
  },
  "reset": []
}
```

An optional request_digest is checked against BLAKE3 of the canonical serde JSON
representation of the typed request, with request_digest set to null. Object
maps are sorted; reset-list order remains part of the request. Use the shared
request digest API rather than hashing arbitrary JSON text. Reusing an operation
ID with different input is refused. Receipt lookup/deduplication precedes expected
revision conflict, after target/incarnation checks. An old retained operation can
retrieve its original receipt after subsequent edits.
Retry the identical request to recover its receipt. Updating a fence changes the
digest and requires a new operation ID. Validation checks the present fence;
another writer may still win before a later apply.

Retain at most 128 receipts, inside the accepted document. A no-op writes its
receipt durably without increasing desktop revision or publishing a new snapshot.
Missing/evicted IDs return unknown_operation: opaque IDs have no expiry order,
and the initial contract cannot prove expired_operation. Resolve ambiguity by
readback and a newly fenced operation; exactly-once is not promised beyond
retention. Restores establish a new incarnation and clear foreign-history
receipts. Status includes publication_pending and recovering separately from
durable acceptance; a changed result can remain unpublished after broker failure.

## Initial data and resolution

The schema covers appearance scheme/style/mode/contrast, window decorations
(csd or ssd) and caption side (right or left) plus embedded or complete
strict-data design source; UI density/text scale/reduced motion; named panels
with edge/mode/thickness; ordered shell pages; and whole app override records
with scheme/mode/contrast/text scale. Describe supplies exact ranges. Unknown
fields/scopes are refused. Field reset restores a package default; removing an
app override restores profile inheritance. Per-field authored provenance beyond
these initial concrete profile values is later work.
The package source is pinned in accepted storage at profile creation. Null
appearance.source selects that pinned source, including after binary upgrades;
it does not silently adopt the upgraded binary's embedded defaults. Adopting a
new package source requires an explicit mutation with a new revision.
The accepted effective digest also fences compiler interpretation drift. A
changed interpretation requires explicit migration rather than changing the
same accepted identity on reload.

The accepted record carries a format number (absent in format 1; now 2). On
open the record's seal is verified as stored, in its own format, so tampering
is still refused. An older record is then upgraded by one rule: everything
authored is kept, the effective interpretation is resolved again from the
authored desktop and the pinned source (derived data is never trusted across
formats), both digests are sealed at the current format, and the backup and
then the primary are replaced atomically. A second open changes nothing. An
authored field added later is omitted at its default, so older records still
verify; a change to the effective interpretation bumps the format.

Validate the whole candidate and all advertised app contexts before acceptance.
Compilation checks the source's claimed contexts. App overlays affect their
context alone; profile high contrast takes precedence. A custom source is at
most 256 KiB. Encoded requests are at most 384 KiB. Inline snapshots are at most
960 KiB, reserving 64 KiB for ABP/broker envelope overhead under the current 1 MiB
retained limit. Larger settings are refused until native immutable artifact
delivery is implemented. Required fonts/assets and runtime live capability are
not yet advertised.

Snapshot schema 1 includes binding, incarnation, desktop revision, resolved-design
generation, source digest, complete desktop and effective per-app/desktop design
projections. The resolved-design generation is owned by the authority and
survives restart; it is not a broker sequence or a reconstituted compiler apply
handle. Clients must confirm an incarnation change through fresh bound readback
before installing it. Work tickets fence superseded asynchronous completion.
Conflicting payloads at the same incarnation/revision trigger a fresh read;
if the bound authority confirms the contradiction, report it and preserve the
installed values rather than enter an endless readback loop.
Fresh decoded topic deliveries use Reducer.observe. Captured tickets are for
asynchronous completions; a new delivery can advance the state while an older
bound read is pending, and that read cannot roll the revision back.

The settings library API is now 0.5.0; authority verbs are 0.3.0. Snapshot
schema 1 is the default; schema 2 is its compact wire form, decoded into the
same in-memory snapshot. The shared native consumer follows the compact topic
and reads schema 2; consumers on their own library copy stay on schema 1 until
ported. The shared consumer performs subscribe-before-get over the host's
existing supervised Bus connection through its optional native executor. It
owns no transport/task/incoming receiver. Hosts feed connection generations,
deliveries and explicit queue loss, execute at most one current action, and
cancel superseded work. Bootstrap buffers one latest candidate; loss coalesces
one later full read. A bounded history suppresses repeated rejected confirmation
candidates. Transport recovery has one pending backoff from 250 ms to 30 seconds;
success/disconnect cancels it. Protocol/target/schema refusal is visible and
quiescent until a new event or explicit refresh. Every native call is bounded
to one second; the host must also cap the combined initial bootstrap to one
second and show a labelled fallback while recovery continues.
Use the same initial deadline with `native::execute_until` for subscribe and
read. Recovery exposes an absolute deadline, preserved during malformed-event
storms; arrivals cannot restart or bypass it. Canonical app/shell constructors
choose `app:<id>` or `desktop` contexts. Captured read tickets and baselines
distinguish real same-incarnation rollback from a valid read racing a newer
publication. Cancel old executor futures when their current work ticket changes.

One context-specific change plan separates paint, text, layout, resources, motion
and optional shell geometry. Source/provenance/revision-only changes advance
evidence without rendering work. Received accepted data is distinct from staged
and applied data. Prepare all resources, then on the renderer event loop check
the stage ticket immediately before synchronous activation and acknowledgement,
without an intervening await. Old connection, consumer and stage completions
cannot claim application. Hosts must fence the actual swap as well as its report.
Identical render inputs need no swap; application never proves presentation.
`Consumer::evidence()` reports binding, context, connection generation,
confirmation, presentation kind, accepted (`current`) and UI-acknowledged
(`applied`) identities, plus normal and fallback faults. Each identity carries
incarnation, canonical string revision, design revision and source digest.
Absent identities are null. Losing confirmation demotes installed current data
to LastGood; an installed fallback is never an authority fence. The shell
exposes this same evidence at `shell.props.get` path `settings`, including root
and dotted reads such as `settings.applied.revision`, behind its existing caller
and connection checks. Evidence does not assert a broker participant record or
frame presentation. `settings_cache` supplies the shared host's persistence
identity, cache fault and fallback diagnostics. The persistence identity is
historical and must match current applied evidence to describe that capture.
Quoin uses the shared worker's service-owned persistent cache while its existing
Bus supervisor starts; terminal refusal preserves offline resources, and only
explicit initial rejection permits a configured scene service override.
`compd.truth.slots.<id>.decided` independently reads the
geometry owner's decided size, or null when absent, without falling back to
committed client geometry. The native desktop geometry gate compares these
readbacks with real client configures and captured pixels.
DTO field additions require explicit classification in the shared comparison;
source/provenance exclusions are deliberate rather than wildcard omissions.
Shared fallback preparation tries validated retained bootstrap data, then local
cache, then current embedded defaults. The host supplies readiness checks for
every reference used by its context and shell capability on its worker. A fenced
completion produces the same immutable UI stage; it never seeds the authority
reducer or mutation fences. Installed data has explicit Current, Retained,
Cached, LastGood and Embedded labels. Identical fresh authority data can promote
cache/embedded evidence without a redundant swap.

Optional `settings/cache` stores applied authority/retained generations in an
existing isolated absolute cache directory. Its versioned JSON envelope binds
instance/profile, context, shell capability, interpretation and content digest.
Bounded directory-relative regular-file reads refuse symlinks in every path
component and cannot block on FIFOs. Before reuse, complete projections must
match current compilation of their authored inputs; unavailable old pinned
package sources and compiler drift are refused visibly. Exact JSON float
round trips preserve these checks. Digests detect corruption, not file origin;
valid cache data still supplies no authority evidence. A stable locked serial
writer fences superseded applied-generation saves, permits retry of the latest
failed attempt and reports ambiguous post-rename failure. All I/O belongs off
the UI loop. Cache failure preserves usable applied data. Real font/asset loading,
artifact preparation and GUI fallback/first-map timing remain pending.

## Shell panel preferences

Quoin prepares appearance and the global panel policy together, then installs
both on the compositor loop before acknowledging the settings revision. Each
record's explicit edge selects one of four panels on every current and future
output; the record ID is provenance, independent of a connector or page name.
`dock`, `overlay` and `hidden` map to runtime docked, pinned and hidden modes.
The default profile owns the bottom panel in dock mode, requesting 40 logical
pixels. An edge without pages draws nothing and reserves no work area.

Thickness is requested logical pixels. Runtime edge ranges, the active page's
minimum and the output/opposite-edge budget fit the request. A bottom page with
a 52-pixel minimum therefore presents 52 pixels for the default 40-pixel
request. Panel rows include a nullable `settings` object with the record ID,
`requested_px`, `fitted_px`, `presented_px`, `reserved_px` and constraint names.
Output shrinkage fits the panel; regrowth recovers the request. Page selection
and registration use the existing carousel and panel model.

Settings owns the mode and thickness of each declared edge. Conflicting legacy
panel writes refuse `SETTINGS_MANAGED` before changing interaction state; exact
current mode or settled-size requests are no-ops. Transient show/hide and page
selection remain available. Persistent toggles cannot undock managed panels.
For managed edges Toggle changes transient visibility only while hidden; docked
or pinned modes treat it as a successful no-op. Corner-menu mode entries are
disabled while managed; activating a disabled selection is an inert action.
Removing a profile record
restores that edge's captured local mode and settled thickness. Saving a page
selection keeps those local values, so profile preferences do not leak into the
local state file. Thickness or appearance updates retain interaction holders;
an actual transition to hidden retires invalid keyboard/menu holders.

Duplicate records targeting one edge and non-empty `shell.page_order` lack a
runtime identity mapping and fail whole shell preparation. The authority's
schema can accept them, but Quoin reports the preparation fault and retains
the last good appearance and panel policy. Correct them through a new fenced
settings mutation. This is consumer capability validation, not a rollback of
the accepted authority revision. Empty page ordering preserves local order.

Requested maximised windows keep their owning output and follow only changes
to their desired content rectangle; removal chooses an available output while
retaining the original unmaximise geometry. Scene reservations are reconciled
after settings activation and before frame work, including without the comp
Bus port. An unchanged target does not emit another maximise configure while
the client is slow to acknowledge or replace its buffer. The compositor's
decided slot remains authoritative during these transitions; older legally
acknowledged buffers do not undo a newer target. Existing aspect-preserving
fit and inverse input mapping remain in use.

Fullscreen continues to use the whole output. Its compositor record, pending
protocol intent and committed state fence work-area reconfiguration through
delayed entry/exit commits. After fullscreen releases ownership, the next normal
dispatch restores the latest maximised content rectangle, even if the work-area
map has not changed again. Window geometry changes schedule redraw and retarget
the human Wayland pointer, respecting grabs. This does not by itself prove
stationary hover or scene bounds before/after rendering.

The protocol fixtures exercise actual xdg configure/ack/buffer commits using
the production geometry executor. Their headless output has no renderer; native
Bus delivery fixtures and protocol fixtures do not establish their composed
rendered settings-to-frame behaviour. Persistent tiling, new maximise intent
with no outputs, native window/input/frame evidence and VT latency acceptance
remain outstanding. Current text scale changes the title font, while decoration
extents continue to come from the selected style's fixed height and border.

## Key bindings

The profile's `keymaps` holds the person's key bindings: per application
id, per action id, the chords chosen. An empty list unbinds the action; an
action not listed keeps the application's own default, which ships with the
application. The field is omitted while empty, so profiles written before it
keep their seals, and it does not affect the resolved design.

- **Apply:** `keymaps.<app>` takes the whole map (null drops every change
  for that app); `keymaps.<app>.<action>` takes a list of chords (null
  returns the action to its default). Action ids are dotted: everything
  after the app id is the action id.
- **Chords:** `Ctrl`, `Alt` and `Shift`, each at most once and in any
  order, then one key: a name of ASCII letters and digits (`ArrowLeft`,
  `F6`, `PageDown`, `B`, `1`) or `=`, `-`, `/`. settingsd checks this
  grammar; the application checks that it knows the key.
- **Limits:** 16 applications, 256 actions each, 4 distinct chords per
  action, 32 bytes per chord, 64 bytes per action id.
- **Followers:** the summary carries `keymaps`, and each application applies
  its own entry when the revision changes (`toolkit::Registry::rebind`).

## Terminal

The profile's `terminal` holds the term's preferences. Each default is the
term's behaviour before the group existed, except padding (8 px instead of
1 px) and the focus ring: `accent` at strength 0.25 gives a quiet tint from
the current theme accent. `neutral` remains available; `accent` at strength
0.5 matches the earlier half-accent ring. Each value is omitted at its
default, so older profiles keep their seals. It does not affect the resolved
design. Terminal colours are not a setting: they follow the session theme.

| Field | Type and range | Default |
| --- | --- | --- |
| `terminal.font.family` | string or null, 1–128 bytes, no control characters | null: `appearance.mono_family` |
| `terminal.font.size` | number 6–48 | the design's UI type size |
| `terminal.font.weight` | integer 100–900, step 100 | 400 |
| `terminal.padding` | integer 1, 2, 4, 8 or 16 (px) | 8 |
| `terminal.scrollback.lines` | integer 0–1000000 | 1000 |
| `terminal.scroll.speed` | integer 10–200 (rows per wheel line, scaled by speed/40; touchpad travel in cell heights at that scale) | 40 |
| `terminal.border.width` | integer 1–4 (px) | 1 |
| `terminal.cursor.shape` | `block`, `underline` or `bar` | `underline` |
| `terminal.cursor.blink` | boolean | false |
| `terminal.focus.ring` | `neutral` or `accent` | `accent` |
| `terminal.focus.strength` | number 0–1, used with `accent` | 0.25 |
| `terminal.mouse.copy_on_select` | boolean | false |
| `terminal.env.term` | `[a-z0-9-]{1,64}`; new tabs and panes | `xterm-256color` |

Apply and reset take each path, or `terminal` for the whole group. The
summary carries `terminal` when any value is set.

## Email

The profile's `email` holds the email app's JMAP accounts and mail options.
**It is not secret and cannot hold a secret.** The snapshot and summary are
retained on the Bus for any client to read, so an account has no password
field and every record in the group refuses unknown keys: an account carrying
`password` is refused with `validation_failed`, and nothing is written.
Passwords live only in the email app's private secrets file, set through its
own write-only verb. The group is omitted at its defaults, so older profiles
keep their seals and the store format stays 3. It does not affect the
resolved design.

| Field | Type and range | Default |
| --- | --- | --- |
| `email.accounts` | list of accounts, at most 64, ids unique; replaced whole, in tree order | `[]` |
| `email.default_account` | an `id` in `email.accounts`, or null | null: the first enabled account |
| `email.mail.page_size` | integer 10–500 | 100 |
| `email.mail.mark_read_on_open` | boolean | true |
| `email.mail.confirm_delete` | boolean | true |
| `email.mail.quote_on_reply` | boolean: whether a plain Reply quotes the original | true |
| `email.mail.reply_position` | `"above"` or `"below"`: where the reply text goes in a quoted reply | `"above"` |

Each account is a record of exactly these keys:

| Key | Type and range | Default |
| --- | --- | --- |
| `id` | `[a-z0-9-]{1,64}`, stable; the writer mints `acct-` and 12 hex digits | required |
| `name` | the tree label: 1–128 bytes, no control characters, no surrounding space | required |
| `url` | the JMAP base: `https://host[:port][/path]`, the host a DNS name, IPv4 or bracketed IPv6 address; no userinfo (`user:secret@`, so no password rides in a URL), query, fragment, backslash, trailing slash or space; at most 2048 bytes | required |
| `email` | the login and default From: one `@` with text on both sides, no space; at most 254 bytes | required |
| `ca_path` | an absolute path to a PEM bundle, or null for the system roots | null |
| `enabled` | boolean | true |
| `signature` | plain text appended to new drafts: at most 4096 characters, no control characters but newline and tab | `""` |

A refused account is named by position: `email.accounts[2].url`. The default
account must name an account, so removing it from the list needs
`email.default_account` changed or reset in the same batch. Apply and reset
take each path, or `email` for the whole group (null resets it too);
`email.mail` alone is not a path. The summary carries `email` when any value
is set; `settings::email::from_snapshot` and `from_summary` read it.

## Topics and storage

Publish retained `settingsd.desktop.changed.<profile>` (the snapshot in schema
1), then retained `settingsd.desktop.compact.<profile>` (schema 2), then
retained `settingsd.desktop.summary.<profile>` (its `Summary`), all owned by
the registered `settingsd` service. The unscoped base names are reserved too.
A revision is published once all three topics are; a failure retries all three. All clients may
subscribe; ordinary publishers/clearers cannot replace its canonical state.
Noded strips inner routing headers and stamps broker_service independently of
caller input. The publisher repopulates retained state at startup and reconnect,
even without a settings mutation. Generic props-prefix ownership is deliberately
not used: embedding a profile in that prefix changes its matched service owner.
Failed publication starts a single pending retry job, with exponential backoff
from 250 ms capped at 30 seconds. Success removes the job and every timer.
Reconnection or a new revision restarts the backoff. There is no idle heartbeat;
publication_pending remains visible throughout a failed pending job.

**Following from an app.** An app on a plain Bus connection (no owner
stamps) subscribes to the profile's summary topic, treats a delivery only as
a hint, and reads the look with `settings.get`'s `summary` view, never the
complete snapshot: `settings::follow::Follower` keeps one read in
flight (hints during it fold into one more), ignores an answer older than one
already seen (same incarnation, lower or equal revision), adopts the instance
from `wrong_target` once (never the profile), and reports settingsd missing so
the app keeps its theme file. `toolkit::session_look` turns the profile's
appearance into the app's session theme; an appearance naming its own design
package (`source`) or a name the app does not know keeps the theme file's.

Default root: resolved MixOS Etc directory / `settings/<profile>/`. Explicit
test roots are supported. One retained writer.lock inode provides a process
flock; it is never removed on normal exit. The root must be an owned directory
not writable by other users. `desktop.conf.mix` holds schema, binding,
incarnation, revisions, authored desktop, pinned package source, receipts and
a verified BLAKE3 content digest and effective interpretation digest. These
digests detect corruption and interpretation drift; they are not an
authentication signature. A synced
`desktop.previous.conf.mix` is written before replacing the accepted generation.
Files are private, never evaluated as Mix source.
Reads, lock acquisition, replacements and syncs are relative to the same held
directory descriptor. Replacing/detaching the profile directory or writer-lock
inode fences the existing writer. Newly created directory entries are synced in
their parents before initial acceptance.

Replacement uses exclusive temporary create, write, file sync, directory-relative
rename and directory sync. Pre-rename errors leave accepted state unchanged.
Post-rename sync errors report outcome_unknown and fence further mutations until
recovery; they cannot be reported as a known uncommitted failure. Corrupt input
is preserved before a valid backup is restored with a new incarnation. Newer
schemas or mismatched target bindings are not overwritten by a fallback.
Corruption evidence is hard-linked and synced before the atomic replacement;
recovery never removes the primary before its replacement is ready.
A missing established primary fails visibly even with a backup; automatic
recovery applies only to a present corrupt primary.
I/O errors, strict shape changes and intact documents requiring a changed
compiler interpretation fail without an automatic backup rollback.

`settingsd init --instance example` explicitly creates a profile and refuses
existing accepted/backup data. `settingsd serve --instance example` never
materialises defaults for a missing established store. Plain `settingsd seed
--instance example` validates an existing profile without rewriting valid state;
it refuses a wholly missing directory. First installation explicitly uses
`settingsd seed --allow-create --instance example` as the service account.
A retained writer.lock is establishment evidence: even --allow-create refuses
a missing established primary without a backup. Existing-store
corruption uses the same validated, evidence-preserving recovery as serve.
The unit validates with plain seed before serving, binds the instance to the machine hostname, and
the session target wants/upholds it. Settings readiness never blocks application
or compositor startup. The image provisions the authority account's writable
MixOS settings parent and seeds once explicitly. Automatic unit startup never
uses --allow-create; missing mounts/directories fail visibly rather than resetting
preferences. Isolated native image adoption still needs runtime evidence.

## Validation and remaining scope

Machine fixtures: [authority.spec.mix](authority.spec.mix). Rust tests cover
precision, patches, projection round-trip, writer locking, changed/no-op receipts,
lost replies, conflicts, digest reuse, eviction, backup restore and future schemas.
`tests/settings/authority_test.mix` runs real ABP publication, unrelated operator
mutation, forged publish/clear refusal, authority restart and cold broker restart
against isolated noded instances. Broker loss keeps the authority alive and its
writer exclusive; the shared consumer reconnects through the same client and
the authority repopulates the empty retained broker without a semantic edit.
The broker-restart fixture also starts a headless cold consumer from persisted
cache while offline, then promotes it to current with no redundant stage after
fresh ABP readback. Resource readiness is a fixture inventory, not GUI proof.
Another native fixture keeps an authority registered but deliberately withholds
read replies, exercising the combined bootstrap deadline and expired work.
OS process lifecycle here belongs to the test fixture; application calls
and observations remain native ABP.

This slice does not claim GUI propagation, renderer acknowledgements, presentation,
GUI offline-fallback/first-map timing, candidate import/watch, immutable artifacts,
full field provenance, named-profile management, compatibility, scheduled policy,
preview, routed observation or replication. Every deferred feature must extend
the same authority and shared contracts, with appropriate contract versions and
migration. Native VT/image presentation and latency gates remain outstanding.

---

<!-- page: https://mixos.dev/dopus/ (source: https://mixos.dev/dopus/README.md) -->

# DOpus

DOpus is MixOS's file manager: two panes side by side, each a folder
tree, with a Places sidebar on the left and a Properties sidebar on the
right. The name is a nod to Directory Opus on the Amiga, whose twin panes
it keeps.

## The window

- **Two panes.** Each shows one folder as a tree with Name, Size and
  Modified columns; columns that do not fit are hidden, Modified first. One
  pane is active; Switch Pane (Tab) moves between them, and copy and
  move always go to the other pane. Drag the divider to change the split.
- **The path field** at the top of each pane always shows where it is. Click
  it, type a path and press Enter to go there; `~` is your home, and a file
  path opens the folder that holds it.
- **The tree.** A chevron or a double-click opens a folder in place;
  another collapses it. Double-click a file to open it in its default
  application.
- **Selecting.** Click a row to select it, Ctrl-click to add or remove one,
  Shift-click for a range. The arrow keys, Home and End move the selection.
- **Sorting.** Click a column header to sort by it, ascending first; click
  it again to reverse.
- **Places** lists Home, the filesystem root and your Desktop, Documents,
  Downloads, Music, Pictures and Videos folders, where they exist. Its
  toggle sits left of the left pane's path field.
- **Properties** shows the selected item: kind, size, dates, permissions,
  owner and path, under a preview of a file when one can be made. Its
  toggle sits right of the right pane's path field.
- **Previews** (View › Previews, per pane, on by default) are thumbnails
  from the desktop's shared thumbnail cache, made by the thumbnailers
  installed on the system (the same ones GNOME and COSMIC use). A type
  with no thumbnailer keeps its icon. Files on network, FUSE and automounted filesystems (NFS, SMB,
  sshfs, ntfs-3g and the like) keep their icons too, unless
  `remote_previews: true` is set in the configuration (below). A file
  whose filesystem stops answering keeps its icon rather than holding up
  the previews of the others.
- **Icons** show what a folder or file holds: your well-known folders have
  their own, and files are grouped by their MIME type (document, code,
  image, audio, video, archive, spreadsheet, presentation, font, disk
  image, program, shell script).
- **Drag and drop.** Drag rows from one pane onto the other, or onto a
  folder in it, and choose Move Here, Copy Here or Cancel.
- **Right-click** a row or a pane's background for the actions that apply
  there.

Deleting asks first, and naming a new folder or a rename is checked before
anything happens. Copies, moves and deletes run in the background, and the
status line says how they ended.

## Menus and keys

The menus hold every action except moving the selection (the arrow keys,
Home and End) and the quick theme keys (Ctrl+Alt+D for light or dark,
Ctrl+Alt+1 to 6 for a scheme; View › Theme has the full choice). Help ›
Keyboard Shortcuts lists every key in force.

| Menu | Action | Keys |
|---|---|---|
| File | Open | Enter |
| | New Folder | Ctrl+Shift+N |
| | Rename | Ctrl+E |
| | Copy to Other Pane | Ctrl+C |
| | Move to Other Pane | Ctrl+X |
| | Delete | Delete |
| | Quit | Ctrl+Q |
| View | Places, Properties | Ctrl+B, Ctrl+I |
| | Hidden Files | Ctrl+H |
| | Refresh | Ctrl+R |
| | Sort by Name, Size, Modified | Ctrl+1, Ctrl+2, Ctrl+3 |
| | Theme | (this window's look; the session's by default) |
| Go | Back, Forward | Alt+ArrowLeft, Alt+ArrowRight |
| | Parent Folder | Backspace, Alt+ArrowUp |
| | Home | Alt+Home |
| | Location… | Ctrl+L |
| | Switch Pane | Tab |
| Help | Keyboard Shortcuts | Ctrl+/ |

To change a key, set it in the desktop profile: the binding applies at once,
and DOpus's defaults stay for every action you leave alone. For example,
`settings.apply` with `keymaps.dopus.nav.parent: ["Ctrl+U"]` makes Ctrl+U
the parent-folder key, an empty list leaves an action without a key, and a
reset of `keymaps.dopus` restores the defaults. See [key bindings are desktop
settings](../docs/decisions/2026-10-11-keymaps-in-settings.md).

## What it remembers

The two panes' folders, sorting and hidden-files setting, which pane was
active, the split, and the sidebars' state and widths are kept in
`config.conf.mix` in DOpus's own directory (by default
`~/.local/state/mixos/apps/dopus/config/`). `dopus --print-config` shows the
configuration it would use. One setting lives only there:
`remote_previews` (default `false`) makes previews of files on network,
FUSE and automounted filesystems too.

## For agents

DOpus answers on the Bus as `dopus` (schema `dopus.v1`).

| Verb | Arguments | Answer |
|---|---|---|
| `dopus.ping`, `dopus.describe`, `dopus.info` | | liveness, the control surface, version and build |
| `dopus.state` | | both panes (path, sort, hidden files, previews, selection, rows, status) and the sidebars |
| `dopus.open` | `paths` (one per pane), or one path and `pane` | goes there |
| `dopus.action` | `id`, `pane` (`left`, `right` or `active`) | runs one action |
| `dopus.actions.list` | | every action, its keys in force and whether it can run now |
| `dopus.theme.set` | `scheme`, `mode` | this window's look |
| `dopus.quit` | | closes the window |

**File operations are keyboard-only.** `dopus.action` refuses every `file.*`
action (`FORBIDDEN`). Input played through the drive verbs (`dopus.ui.*`)
is held to the same rule: while it runs, file actions and opening files are
refused, and a delete, name or drop dialog can be dismissed but not
accepted. The rule holds for the whole time drive input runs, so a key you
press yourself in that moment is refused too; press it again after. An agent reads, navigates, sorts and selects through DOpus, but
never creates, renames, moves, copies, deletes or opens files through it.

The window is drivable like every MixOS app, including its menus: see
[driving an app](../docs/drive.md) (`dopus.ui.*`, `dopus.window`). The verbs are
registered in `docs/docs/spec/bus/verbs.conf.mix`.

Each command run from a menu, a key, a sidebar button or an accepted
`dopus.action` is published on `dopus.command.executed`, with how it was
reached (`menu`, `shortcut`, `ui` or `bus`;
[executed commands](../docs/decisions/2026-10-11-executed-commands.md)). A refused
action is not published.

`dopus --headless` runs the core and the Bus port without a window, for
tests: the same verbs, minus those that need a window. It publishes its
accepted `dopus.action` runs on `<service>.command.executed` too.

---

<!-- page: https://mixos.dev/edit/ (source: https://mixos.dev/edit/README.md) -->

# Edit

Shared headless text buffers used by [editd](../editd/README.md) and
[Ced](../ced/README.md). This promotion has two external owners: the
service is the authoritative buffer store; the app uses the same revision,
operation, anchor and position contracts for local echo and rebasing. No
Bus connection, clock, renderer or async runtime is required by this
library.

The Microsoft Edit buffer implementation remains in
[`vendor/msedit`](https://github.com/markc/mixos/tree/main/vendor/msedit),
with its licence, upstream revision and retained commit-failure, Unicode
and convergence tests. This library supplies the revision CAS,
transactions, single-authority OT, per-origin undo, anchors and search API
above it.

Source provenance is recorded in the repository's `NOTICE`.
The source is [`libs/edit`](https://github.com/markc/mixos/tree/main/libs/edit).

---

<!-- page: https://mixos.dev/editd/ (source: https://mixos.dev/editd/README.md) -->

# Edit service

`editd` registers the `edit` service and serves the `edit.v1` contract.
[Ced](../ced/README.md) and agents share its buffers through native ABP.
The service is headless and requires no compositor or D-Bus session.

`edit.open`, `edit.list` and `edit.get` discover buffers and page their
contents. `edit.insert`, `edit.delete`, `edit.replace` and `edit.apply` change
text. `edit.save`, `edit.reload` and `edit.close` manage disk state.
`edit.undo`, `edit.redo` and `edit.history` expose history; selection, cursor
and anchor verbs retain positions across edits. Properties have get, list,
describe and watch ports. Ask `HELP` for the complete manifest.

Mutations can carry origin, operation identity and expected revision.
Buffer identities include a daemon epoch, so a restarted service does not
silently reinterpret an old identifier. Paged snapshots remain tied to their
captured revision while later edits arrive. Slow work on one buffer does not
block operations on another.

## Buffers and recovery

The buffer model is the [edit](../edit/README.md) library, shared with Ced:
revision CAS, per-origin undo, anchors, atomic save, external-change
detection and a recoverable change feed. This service owns its actors,
filesystem watching and the recovery writer.

Discovery uses the shared node configuration. Recovery defaults beneath
`MIXOS_VAR/edit/recovery`, following the MixOS Var directory rule.
`MIXOS_EDIT_RECOVERY_DIR` selects an absolute recovery directory, and
`MIXOS_EDIT_RECOVERY=0` disables durable recovery. The session supplies its
own state root.

## Tests

The retained integration tests exercise dispatch, recovery and the actual
service over a private native noded, rather than a substitute control
socket.

The source is
[`services/editd`](https://github.com/markc/mixos/tree/main/services/editd).

---

<!-- page: https://mixos.dev/editor-model/ (source: https://mixos.dev/editor-model/README.md) -->

# editor-model

`editor-model` is the frontend side of the [edit service](../editd/README.md):
everything an editor needs that is not drawing. It has no UI toolkit, needs
no async runtime and does no Bus I/O. The transport stays in the consumer;
the mirror only produces requests (`types::Outgoing`) and consumes replies
and events.

Used by:

- [editor](../editor/README.md), the shared egui editor widget, which turns
  keys and pointer events into `EditCommand`s;
- [ced](../ced/README.md) and its `documents` crate, including
  `ced --headless`, which drive the mirror against `editd`.

It builds on the [edit](../edit/README.md) library (`Text`, `ot`, `view`,
`wire`, origins) and the [`syntax`](../syntax/README.md) crate (lsh highlighting).

The source is [`libs/editor-model`](https://github.com/markc/mixos/tree/main/libs/editor-model).

## Modules

| Module | What it holds |
|---|---|
| `model` | `EditorModel`: selection, preferred column, scroll, overwrite, remote carets, change markers and the input-method composition range. `command()` turns an `EditCommand` into a `LocalEdit`. |
| `mirror` | `Mirror`: one buffer's view text (confirmed rev + in-flight + queue) with local echo and single-authority OT rebase against `editd`. Pure: no Bus, no clock; every method returns a `Step`. |
| `highlight` | `Highlight`: per-view highlighting state, lsh languages through `syntax::cache`, Mix through the Mix lexer. |
| `diag` | `Diagnostics`: per-source diagnostic sets (`mix lint --json` output, or external sets) mapped through edits. |
| `types` | Shared types every frontend speaks: `Intent`, `LocalEdit`, `ViewDelta`, `Outgoing`, `Incoming`, `Conflict`, `Notice`, `OpIdGen`, `bus_lane_label`. |
| `fake` | `FakeEditd`, a fake `edit` daemon over the real `edit::Buffer`, for tests (feature `fake`). |

## The editor model

`EditorModel::command(&text, &cfg, command)` applies an `EditCommand` to the
current view text and returns the `LocalEdit` to send, or `None` for a pure
motion. Commands: insert, newline, backspace, delete, delete word left or
right, tab, outdent, duplicate line, delete line, move line up or down,
toggle comment, `Move { to, extend }`, select all, select word
(double-click), select line (triple-click) and set selection. Motions are
left and right, word left and right, up and down, smart Home, End, page up
and down, document start and end, and `To(offset)`.

The contracts, from the module docs:

- Every motion is grapheme-correct through `edit::view`; Up and Down keep
  `preferred_cells`.
- A multi-line Tab or Outdent is one multi-item `LocalEdit`: one
  `edit.apply`, one undo group. `coalesce` is set only for single-grapheme
  typing and backspace/delete runs.
- Newline copies the line's leading whitespace and uses the buffer's line
  ending. ToggleComment uses the language's line-comment token
  (`line_comment_for`: `--` for Mix, `//` for Rust, C, C++, Go and
  JavaScript, `#` for shell, Python, TOML and YAML; other languages get
  nothing).
- `apply_delta` maps the selection, remote carets and markers through a
  `ViewDelta`. A delta that overlaps the composition range cancels it.
- Lines are 1-based, cells 0-based.

```rust
use edit::text::Text;
use edit::view::MeasureCfg;
use editor_model::model::{EditCfg, EditCommand, EditorModel};

let cfg = EditCfg {
    measure: MeasureCfg { tab_size: 4, ambiguous_wide: false },
    insert_spaces: true,
    eol: "\n",
    line_comment: Some("--"),
};
let text = Text::from_text("hello\n").unwrap();
let mut m = EditorModel::default();
let edit = m.command(&text, &cfg, EditCommand::Insert("> ".into()));
// `edit` is Some(LocalEdit { items, coalesce, caret_after }) for the mirror.
```

## The mirror

`Mirror::bootstrap` starts from an `edit.open` reply. The host then feeds it
`local_edit`, `server_op` (undo, redo, save, reload, apply at a revision),
`on_event` (`edit.changed`), `on_reply`, `on_deadline`, `on_page` and
`on_history`, and after every call drains `next_outgoing`,
`take_retry_timer`, `take_echo_timer` and `take_outcomes`. The deltas it
produces are `ViewDelta`s, the one thing the editor side consumes: how the
view text changed, with its kind (`Local`, `Remote`, `Undo`, `Redo`,
`Reload`, `Revert`, `Resync`), revision and view generation.

The rules are binding and written out in the module docs of
[`src/mirror.rs`](https://github.com/markc/mixos/blob/main/libs/editor-model/src/mirror.rs):
one request in flight per buffer; how a server edit is folded (duplicate,
gap, own ack, or a remote fold that rebases pending ops and reports a
`Conflict`); how replies, `busy` backoff and refusals are handled; what
happens at a deadline; recovery from an event gap, a reconnect or an epoch
change (history first, then a paged snapshot); and the keep-mine transfer
of a detached copy, staged over 1 MiB.

## Highlighting and diagnostics

- **Highlight**: lsh languages are checkpointed every 1024 lines and seek
  under a per-frame `SliceBudget`; a line not reached yet draws plain. Mix
  languages (`mix`, `scene`, `mix-data`) are relexed whole off the UI
  thread, 150 ms after the last delta (the caller debounces and runs the
  worker); buffers over 2 MiB stay plain. A result tagged for another
  epoch, buffer, language or config is discarded; an older result is used
  only above the first line touched since.
- **Diagnostics**: one set per source. `LINT_SOURCE` is the frontend's own
  `mix lint --json -` run (schema version 2 only); any other source is an
  external set (`ced.diagnostics`). A diagnostic whose line was touched
  since its tagged generation is dropped; the rest map through the deltas.

## Features

- `mix` (the crate default; the workspace dependency turns default
  features off, and ced and editor enable it): Mix highlighting through the
  Mix lexer. Without it, Mix buffers draw plain.
- `fake`: the `fake` module, for consumers' tests. ced's tests enable it.

## Testing

Unit tests sit beside each module (`src/model/tests.rs`,
`src/highlight/tests.rs`, `src/diag/tests.rs`). The mirror is tested end to
end against `FakeEditd`:

- `tests/fixture_server_side.rs` runs the server side of every scripted
  scenario in
  [`tests/fixtures/mirror/`](https://github.com/markc/mixos/tree/main/libs/editor-model/tests/fixtures/mirror)
  (format in its README), so a contradictory fixture fails there first.
- `tests/mirror_convergence.rs` replays every fixture through a real
  `Mirror`, checking the exact requests sent and the declared client
  expectations, then runs proptest properties over random interleavings of
  typing, agent edits, undo, reordered or dropped events and replies, lost
  requests, deadlines and dedup eviction. The emitted deltas are replayed
  onto a shadow string that must match the mirror's text.

On an authorised build worker:

```
cargo test --locked -p editor-model
```

A vertical-motion benchmark is `#[ignore]`d; run it in release on a build
node.

---

<!-- page: https://mixos.dev/editor/ (source: https://mixos.dev/editor/README.md) -->

# editor

The shared plain-text editor for MixOS egui applications: a monospace,
virtualised view over the headless editing model (`editor-model`,
[edit](../edit/README.md)). [Ced](../ced/README.md) is built on it, and so
is any application that needs a text editor: a Markdown editor, a notes
pane, a config field.

- **Only visible rows are measured and drawn.** A multi-megabyte file, or a
  multi-megabyte line, costs about the same per frame as a short one.
- **Soft wrap is a view option** (`Wrap::Words`): rows break after
  whitespace, inside a word only when it is longer than a row.
- **The widget never edits text.** It turns keys, pointer, clipboard and
  input-method events into `Event`s (mostly `EditCommand`s) for the
  document's owner to apply.
- **Colours come from the theme**, through the toolkit's chrome roles, with
  every highlight class kept at 3:1 contrast or better.

The source is [`libs/editor`](https://github.com/markc/mixos/tree/main/libs/editor).

## A local document

`local::Document` is the editor without a daemon: an `edit::buffer::Buffer`
with open and save (byte-order mark and line endings kept), undo and redo,
and highlighting for the 25 lsh languages, Markdown included.

```rust
let mut doc = editor::local::Document::open("notes.md")?;
let palette = editor::Palette::from_theme(&theme);
let view = editor::View::prose(); // soft wrap, no line numbers

// each frame
doc.show(ui, &palette, &view);
if doc.is_dirty() { /* offer to save: doc.save()? */ }
```

## A shared buffer

Ced applies the same events to a buffer shared through the edit service
(`editor_model::mirror`) and passes other origins' carets, selections and
change markers through the same `Doc`. Any application can move from a
local document to a shared one without changing its UI code.

## Saving

`save` writes a new temporary file beside the real one (created
exclusively, so no existing file or link is followed), gives it the
original's permissions, flushes it and renames it into place. Saving
through a symbolic link writes the link's target; the link stays a link.
Edits the buffer refuses (a paste over the 1 MiB request limit) are kept
for `take_refusal`. `set_contents` is a reload: it has no request limit,
and Undo does not take it back.

## Tests

`cargo test -p editor`: measurement, rows and wrapping, geometry, keys, the
input-method guard, palettes in every scheme, the local document, and
`tests/snapshot.rs`, which drives a real document through egui (typing,
selection, undo, read-only) and keeps offscreen snapshots. Regenerate the
snapshots with `UPDATE_SNAPSHOTS=1` and look at them before committing.

## Known limits

- One monospace grid: proportional text is a separate, larger piece of work.
- With soft wrap, the scrollbar counts visual rows for documents up to
  256 KiB and lines beyond that.
- In lines over 64 KiB, which break every row width, a tab wider than a
  whole row can leave an empty row before it.
- A text area under two cells wide wraps at two cells (the widest cluster
  but a tab), so its second cell is clipped.
- A row's end and the next row's start are the same offset, and a caret has
  no affinity yet: Up or Down onto a row that breaks inside a word stops
  before its last character, so the caret stays on that row.
- Glyphs come from the theme's faces; scripts they do not cover (CJK, for
  one) draw as boxes until the font set gains a fallback.
- Without wrap, Home and End are logical; with wrap, Up and Down move by
  rows and Home and End stay logical.
- Mix-family buffers are highlighted by the Mix lexer only when the `mix`
  feature is on and the owner runs the relex (Ced does).

---

<!-- page: https://mixos.dev/email/ (source: https://mixos.dev/email/README.md) -->

# email — the MixOS JMAP mail client

`email` (`dev.mixos.email`) is the reserved MixOS mail client: a **pure
JMAP client** that speaks HTTPS to any RFC 8620/8621-shaped server, whether
that is the mesh's own maild or someone else's server. It holds **any
number of accounts**, shown as a tree in the Thunderbird style. Mail is
listed, read, composed, sent, flagged, moved and deleted. Calendars,
events, address books and contacts are listed, shown and created. Every
action can also be done over the Bus.

## Running it

```
email [--noded-url URL] [--service NAME]
```

A second launch raises the first window.

## Accounts are set up in Prefs

Accounts are configured in **Prefs → Email**, not in the app
([decision](../docs/decisions/2026-10-16-email-accounts-in-settings.md)).
Each account has the fields below.

| Field | What it is |
|---|---|
| Name | The label in the tree. |
| Server URL | The JMAP server base (`https://…`, no trailing slash): maild directly, or a webd vhost that proxies `/jmap`. |
| Email address | The login, the Basic username at the token exchange, and the default From. |
| Password | Kept only in the app's private `secrets.conf.mix` (0600). It never enters settingsd. |
| CA bundle path | Optional. An absolute path to a PEM bundle to trust when the server's certificate is self-issued. |
| Enabled | Off disconnects the account and keeps it listed. |
| Signature | Plain text added to new drafts after a `-- ` line. |

The group also holds the **default account** (the compose From) and the
mail options: **page size** (10–500, default 100), **mark read on open**
and **confirm before delete**. Every change applies at once:

- a new enabled account with a password connects;
- a change to the URL, address or CA path reconnects;
- a rename relabels;
- turning an account off disconnects it;
- a removed account's client and view go.

A settings read never deletes a password. Only **Email** forgets one: an
account removed with `email.account.remove`, or an empty
`email.account.password.set`. An account removed elsewhere (in Prefs, or
by a settings reset) leaves its entry in `secrets.conf.mix`, unused.

settingsd omits the `email` group at its defaults, so a read with no
accounts cannot be told apart from a settingsd that does not carry the
group. When such a read arrives while accounts are shown, Email keeps
them (views, connections, passwords) and says so in the status line. It
stops keeping them at the next read that lists accounts, or when an
account is removed through Email.

If settingsd is not running, the window opens the accounts it last saw
(cached in its config) read-only, and the status line says so.

With no account the window shows **Open Email Settings**. An account that
failed to connect, or has no password yet, shows its error, **Retry** and
the same button.

**Upgrading from the single-account version.** The old `config.conf.mix`
(schema 1, with the password inline) migrates once, losing nothing:

1. The password is written to `secrets.conf.mix`, and an inline CA bundle
   to `ca-<id>.pem` beside it. Nothing else happens until that save has
   landed. A user name and password inside the old server URL are
   removed (the status line says so, without the URL).
2. The account is added to settingsd and made the default. When
   settingsd already holds it under another id, the password is written
   under that id, and that save must land too.
3. Only then is the file rewritten as schema 2: the window shape and the
   accounts cache, with no secret.

Until settingsd has taken the account, the old file stays as it was and
the account works as before.

Files, in `~/.local/state/mixos/apps/email/config/`:

| File | Holds |
|---|---|
| `config.conf.mix` | schema 2: split sizes, mode, selected account, collapsed tree nodes, the last accounts seen |
| `secrets.conf.mix` | the passwords, by account id (0600, written only by email) |
| `ca-<id>.pem` | a migrated account's CA bundle |

A malformed file loads defaults and is never overwritten.

## The window

- **The tree** (left). Each account is a root node, with its connection
  state and its total unread count. Under each account come:
  - its **mailboxes**, nested by parent, with unread counts (the inbox
    first, the trash last);
  - a **Calendars** group;
  - an **Address Books** group.

  Clicking a node selects its account, the matching surface and that
  folder, calendar or book. Nodes collapse and expand, and the state is
  remembered. Once the tree has focus, **↑/↓** move, **←/→** collapse and
  expand (or go to the parent or first child) and **Enter** selects.
- **The centre**: the selected account's mail page (newest first, as many
  as the page size), its calendar's events, or its book's contacts, with
  a server-side filter over name, email and company. The mail page is a
  table of one compact row per email: **Subject** (with flag and
  attachment markers; drag its edge to widen it), **From** and a compact
  **Date** (the time today, the weekday this week, the day and month this
  year, else the full date). Unread rows are bold. Clicking a row opens
  it in the reader; once the list has the keyboard, **↑/↓** move the
  selection and open each email, and **Enter** opens the selected one.
- **The reader**: the open email (plain text first, the HTML source when
  there is no plain text), event or contact. A text body written as
  Markdown is rendered: a `text/markdown` part always, and a
  `text/plain` one when the toolkit's conservative detector finds
  Markdown in it (a fence, a table, two headings, or two of a heading,
  a list, bold, inline code, a link and a block quote). Quoted replies,
  signatures, forwarded headers, bare URLs and ASCII art never trigger
  it. Rendered mail shows headings, lists and task boxes, code blocks
  that scroll sideways, tables, quotes and links (http, https and mailto
  open in the desktop's browser or mail handler; the address shows on
  hover). Images are never fetched, because remote images in mail track
  their reader: the alt text is a link to the image. Raw HTML is shown as
  text. View › Message › **Render Markdown** (a tick) flips one email
  between the rendering and its text, either way. The choice lasts while
  that email is open.

  The reader opens with a toolbar of what to do with the email: **Reply**
  (its ▾ chooses with or without the quoted original), **Reply All**,
  **Forward** and, apart, **Delete**. The subject comes first, as the
  pane's heading, then From, To and the date. A right-click anywhere in
  the reader opens the **Message** menu.
- **Compose** (To, Cc, Bcc, Subject, body, and From when there are
  several accounts), reply, reply all and forward. If the account's login
  (server or address) changes while a draft is open, Send waits: the
  dialog shows the new address and **Use New Address**. Mail is sent through
  the proven recipe: build the message, upload it, create the Email in
  Sent, then submit. **Sending requires maild**, because the create step
  uses maild's extension of a top-level `blobId` on `Email/set`. A strict
  RFC 8621 server builds an Email from uploaded MIME with `Email/import`,
  so it refuses the send; `Email/import` is future work.
- **The Message menu** holds everything that acts on the open email:
  reply (with or without the quote), reply all, forward, star, mark read
  or unread, junk or not junk, move, and delete to Trash (confirmed when
  the settings ask). **Junk** moves the email into the account's Junk
  mailbox and **Not Junk** moves it from Junk back to the inbox; maild
  trains its spam filter on those moves (there is no junk keyword). An
  account without a Junk mailbox shows Junk disabled, saying so. After a
  delete, move or junk the reader opens the next email in the list (the
  previous one when it was the last).
  Labels follow the email (**Star** or **Remove Star**, **Mark as Read** or
  **Mark as Unread**). Marking an open email unread leaves it open and
  unread: only opening an email marks it read.
- **Attachments.** An email with attachments shows a paperclip and its
  count at the end of the reader's toolbar (and Message › Attachments…).
  Its popup lists each one with its type, name and size, and **Save**
  and **Open**; **Save all** saves every one that can be fetched. Saving
  writes into your downloads directory (`$XDG_DOWNLOAD_DIR`, the
  `user-dirs.dirs` entry, else `~/Downloads`) and never replaces a file:
  a taken name becomes `name (1).ext`. Names from mail are cleaned (no
  paths, `..`, control characters or leading dots, 200 bytes at most),
  files are written whole and readable only by you, and the status line
  names where each went. **Open** saves into a private directory first
  and hands the file to the desktop's default application; programs and
  scripts (executables, shell scripts, `.desktop` files and the like)
  are Save only. A part the server could not decode is shown greyed. The
  download runs in the background; nothing is written until the whole
  file has arrived.
- **Printing** (Message › Print…, Ctrl+P) goes through the browser's
  print dialog, which also offers **Save to PDF**: MixOS has no print
  service. The email becomes one self-contained page in a private
  directory (`$XDG_RUNTIME_DIR/email-print/`, readable only by you), shown
  as the reader shows it: Markdown rendered, else the plain text. Headers
  (From, To, Cc, Date, Subject) come first, in the light theme on white.
  Nothing from the email runs or loads: its HTML is printed as text,
  images are their alt text (a remote image would tell the sender), and a
  strict Content-Security-Policy allows only the page's own style and the
  script that opens the dialog. The page opens in Firefox through the
  session launcher; without one, the status line names the file to open.
  Pages older than a day are removed on the next print.
- **Address completion** in To, Cc and Bcc. After two characters of an
  address the field offers up to eight: the account's contacts (from
  every address book) first, then addresses it has seen (recipients of
  loaded Sent pages, senders of other loaded pages, kept in memory only).
  Only the entry being typed is completed, the one after the last `,` or
  `;` outside quotes. **Up**/**Down** move, **Enter** or **Tab** take one
  as `Name <address>, ` (the name quoted when it holds a comma or another
  special character), **Escape** closes the list. Addresses already in the
  field are left out. The contacts are looked up once typing pauses
  (200 ms), and only the newest lookup's answer is shown.
- **Quoted replies.** A reply quotes the original's text body (a Markdown
  email's source; an HTML-only email's text) under an "On …, Ann wrote:"
  line, every line marked `> ` (an already quoted line gains another
  `>`), with the original's signature cut at its `-- ` line and lines
  never re-wrapped. The person's text and signature go above the quote.
  Plain text only.
- **New Event** and **New Contact** forms. Start and end are RFC 3339
  instants.

## Keyboard

| Shortcut | Action |
|---|---|
| Ctrl+T | Refresh the account (Thunderbird's Get Messages) |
| Ctrl+Q | Quit |
| Ctrl+N | Compose |
| Ctrl+R | Reply |
| Ctrl+Shift+R | Reply all |
| Ctrl+L | Forward |
| S | Star or remove the star |
| M | Mark read or unread |
| J / Shift+J | Junk / Not junk |
| Ctrl+Shift+M | Move the open email |
| Delete | Delete the open email |
| Ctrl+P | Print (the browser's print dialog, or save as PDF) |
| Ctrl+Shift+E | New event |
| Ctrl+Shift+K | New contact |
| Ctrl+1 / 2 / 3 | Mail / Calendar / Contacts |
| Ctrl+PageDown / PageUp | Next / previous account |

The shortcuts follow Thunderbird's. S, M, J, Shift+J and Delete act only while no
text field has the keyboard (they type into the search box or a draft
otherwise). Help › Keyboard Shortcuts shows the chords in force.

## Driving it over the Bus

Service `email`, schema `email.v1`. `HELP` lists the verbs, and
`app.describe` gives each one with its arguments and `read_only` flag.
`account` defaults to the selected account. A refusal is rc 10 with
`{error_code, message}`, and two of the codes are kept distinct:

- `UNKNOWN_ACCOUNT`: no account has that id;
- `NOT_FOUND`: the account's server holds no email, mailbox, event or
  contact with that id.

The other codes are `INVALID_ARGUMENT`, `NOT_CONNECTED`, `UNAVAILABLE`
(settingsd absent), `CONFLICT`, `TIMEOUT` (settingsd did not answer a
write within 60 s), `STALE` (the account reconnected while the request
was pending, so its answer would come from the old connection),
`SUPERSEDED` (a newer `email.open` replaced this one before it loaded), `MIGRATION_PENDING` (the account is still moving
from the old config, so its password cannot change, and it cannot be
removed, until that finishes), `CANCELLED` (Email closed before the
request ran; a write that may have run answers `OUTCOME_UNKNOWN`),
`SERVER`,
`BUSY`, `UNKNOWN_VERB`, `UNKNOWN_COMMAND` and `DISABLED`.

Queries that need the server answer when the server does. The window
never waits on them.

| Verb | Class | Does |
|---|---|---|
| `email.ping`, `email.info`, `email.commands` | query | probe; the whole window state (no secret); the command registry |
| `email.accounts` | query | the accounts with `has_password` and `state`, never a password |
| `email.mailboxes {account?}` | query | mailboxes with roles, parents and counts |
| `email.list {account?, mailbox?, offset?, limit?, query?}` | query | one page, newest first, with `total` |
| `email.search {account?, text, mailbox?, limit?}` | query | emails matching text |
| `email.get {account?, id}` | query | one email's headers and `text` body |
| `email.calendars`, `email.events {calendar?, from?, to?}`, `email.event.get {id}` | query | calendars and events |
| `email.books`, `email.contacts {book?, filter?}`, `email.contact.get {id}` | query | address books and contacts |
| `email.show`, `email.quit` | system, intent | raise, close |
| `email.execute {id}` | intent | run any registry command (published with origin `bus`) |
| `email.mode {name}`, `email.refresh {account?}` | intent | switch surface; fetch again (a failed account reconnects) |
| `email.account.set {id?, name, url, email, password?, ca_path?, enabled?, signature?}` | intent | create or update in settingsd; answers `{id}` once settingsd accepts |
| `email.account.remove {id}`, `email.account.default {id}` | intent | through settingsd, fenced |
| `email.account.password.set {id, password}` | intent | write-only: the secrets file, then reconnect; an empty password forgets it for any account id, even one settingsd no longer holds (`{forgotten}`) |
| `email.account.connect {id}`, `email.account.select {id}` | intent | reconnect; show |
| `email.mailbox.select/create/rename/delete` | intent | `create` answers `{id}` |
| `email.open {id}` | intent | show an email in the reader; answers once loaded |
| `email.mark {ids, read?, flagged?}`, `email.move {ids, mailbox}`, `email.delete {ids, destroy?}` | intent | the list and counts refresh after |
| `email.attachments {id}` | query | the email's attachments (part, name, type, size, undecodable, save_only), never their content |
| `email.attachment.save {id, part, dir?}` | intent | save one attachment (into `dir`, absolute and existing, else the downloads directory) without replacing a file; answers `{path}` |
| `email.contacts.suggest {text, limit?}` | query | address completions for `text`: contacts first, then addresses the account has seen; at most `limit` (8) |
| `email.print {id?}` | intent | write the print page (the open email by default) and open it in the browser; answers `{path, opened}` |
| `email.junk {ids, junk}` | intent | move to the Junk mailbox (`junk: true`) or back to the inbox; maild trains spam or ham on the move; answers `{ids, mailbox}` |
| `email.send {to, cc?, bcc?, subject, body, in_reply_to?}` | intent | send without the dialog |
| `email.compose {…}`, `email.reply {id, all?}`, `email.forward {id, to?}` | intent | open the compose dialog, filled in |
| `email.calendar.select`, `email.event.create/update/delete` | intent | `create` answers `{id}`; `end` or an ISO 8601 `duration` |
| `email.book.select`, `email.contact.create/update/delete` | intent | `create` answers `{id}` |
| `email.ui.*`, `email.window`, `email.window.state` | input, query | the toolkit [drive verbs](../docs/drive.md) |

Every command the window runs (menu, shortcut, button or `email.execute`)
is published on `email.command.executed` with how it was reached.

`email.info` reports how the open email is shown under each account's
`mail.reader`: `{"format": "markdown" | "plain", "auto": true | false}`,
where `auto` is false once the person (or `email.execute
{"id":"view.reader.markdown"}`) has flipped it. The command is disabled
when the open email has no text body.

From Mix:

```
send email email.accounts
send email email.list body='{"account":"acct-3f9a1c2b4d5e","mailbox":"m-inbox","limit":20}'
send email email.search body='{"text":"invoice"}'
send email email.mark body='{"ids":["E42"],"read":false}'
send email email.event.create body='{"title":"Standup","start":"2026-10-17T09:00:00+10:00","duration":"PT15M"}'
send email email.account.password.set body='{"id":"acct-3f9a1c2b4d5e","password":"…"}'
```

## How it talks to the server

There is one HTTPS client per account. On connect, the password is
exchanged for a Bearer token (`POST /auth/tokens/issue`) and the Session
is discovered (`GET /.well-known/jmap`). Every method call after that
carries the token. A server without the token endpoint falls back to
Basic auth on every request. Requests batch their methodCalls and chain
`Email/query` into `Email/get` through a ResultReference, so a list is one
round trip. Every answer carries its account id and connection generation,
so a late answer from one account, or from an account's earlier
connection, is never applied to another.

The engine (`apps/email/crates/jmap`) is ported from the retired Dioxus
mail client, with its faults fixed:

- session discovery and URL templates instead of hard-coded paths;
- real pagination;
- Bcc carried through;
- `In-Reply-To` wrapped exactly once;
- CR/LF stripped from header inputs (header injection);
- typed handling of method errors.

## Performance workload

The recorded workload for future profiling is a 10,000-email mailbox in
each of several accounts. The list renders one page (the page size) from
a single query-and-get round trip, the reader fetches one email's bodies
when it opens, and the tree's work grows with the mailbox count, not the
email count. Nothing else scales with mailbox size.

---

<!-- page: https://mixos.dev/expr/ (source: https://mixos.dev/expr/README.md) -->

# expr

The pure expression language of Mix Scenes bindings. A scene binds a port
to an expression such as `= $model.rows`, `= not $model.volume.has_icon` or
`= $model.prefix .. $item.cells[0]`; this crate compiles the expression,
reports which globals it reads, and evaluates it over `serde_json::Value`
globals under size and time limits.

The language is the expression subset of [Mix](../mix/README.md) with every
builtin denied: literals, `$name` globals with field and index access,
arithmetic, `..` concatenation, comparisons, `and`/`or`/`??`, the ternary
and the `if … then … else … end` expression. Calls, assignments, statements
and shell or Bus forms are refused at compile time with
`ErrorKind::NotAllowed`. The crate does not depend on the Mix interpreter.

```rust
let model = serde_json::json!({"prefix": "live ", "rows": [{"cells": ["one"]}]});
let binding = expr::compile("$model.prefix .. $model.rows[0].cells[0]")?;
assert_eq!(binding.roots().iter().collect::<Vec<_>>(), ["model"]);
let text = binding.eval(&[("model", &model)], &expr::Limits::default())?;
assert_eq!(text, "live one");
```

Test: `cargo test -p expr`. The semantics are pinned in
`tests/semantics.rs`; the crate documentation in `src/lib.rs` lists what is
accepted, refused and how errors are classified.

The source is [`libs/expr`](https://github.com/markc/mixos/tree/main/libs/expr).

---

<!-- page: https://mixos.dev/files/ (source: https://mixos.dev/files/README.md) -->

# files

Shared filesystem and markdown corpus logic for webd and the files service.
`rooted_read::ReadRoot` pins an operator-provisioned root descriptor and
opens regular files with Linux `openat2`, refusing symlinks, escapes and
unsupported kernels. There is no path-based fallback.

The corpus model includes surgical frontmatter writes, the canonical Bus
header reader, BLAKE3 hashes, UUIDv7 identity, link extraction, reconcile
diffs and generic place-scoped filesystem operations. `atomic` preserves
its streamed verification, mode and no-replace contracts; these differ
from config's descriptor-relative configuration replacement helpers.

Enable `sqlite` for index persistence, ingestion and reconciliation.
Test with `cargo test --locked -p files --features sqlite` and
`cargo test --locked -p files --no-default-features`.

Source: [libs/files](https://github.com/markc/mixos/tree/main/libs/files).

Promoted from Dopus's private crate when webd became the second external
owner. Both consumers use the same API and tests; there is no second
filesystem implementation.

---

<!-- page: https://mixos.dev/hostd/ (source: https://mixos.dev/hostd/README.md) -->

# The host service

`hostd` is the one MixOS service that runs as root on a host. It does two
jobs:

- **It describes the host:** hardware, OS, the MixOS mode, and who manages
  the network.
- **It makes privileged changes** through a short list of closed, typed
  verbs. Each change is checked, recorded, and reversed if it doesn't work.

Agents and session code ask hostd instead of running `sudo`. The rules
behind it are in the
[hostd decision](../docs/decisions/2026-10-12-hostd.md).

## Calling it

Locally, hostd listens on `/run/hostd/hostd.sock` (mode 0660, group
`hostd`). Frames are JSON, each ended by a NUL byte, many per connection:

```text
-> {"verb":"net.state","body":{}}\0
<- {"rc":0,"body":{...}}\0
```

`rc` is 0 on success and 10 on refusal, with `body.status` saying why. From
a shell:

```text
hostd call host.info
hostd call net.link.apply '{"link":"eth1","config":{"mode":"dhcp"}}'
```

Read verbs are also on the Bus, owned by `hostd`. Changes are never taken
from the Bus.

There is one hostd per host, run as root and socket-activated:

```text
hostd serve                      # local socket, plus the Bus when noded is up
hostd serve --no-bus             # local socket only
```

`hostd serve` refuses to take over a socket another hostd is serving.

## Verbs

| Verb | Tier | What |
|---|---|---|
| `host.info` | read | hostname, kernel, OS, MixOS mode, container, uptime, CPU, memory |
| `net.state` | read | which network managers run, networkd links and files, resolved DNS, iwd stations, hostd's own files |
| `hostd.status` | read | frozen or not, the policy's state, the caller's identity, and the grants it holds: `held` (names) and `held_grants` (each in full: verbs, limits, expiry, rate) |
| `hostd.receipt` | read | one change's receipt: what it changed, under which grant, how it ended (never file contents) |
| `hostd.freeze` | control | refuse every change until thawed: root on the host, or a grant naming it |
| `hostd.thaw` | control | accept changes again and lift grant suspensions: root on the host only |
| `net.link.apply` | write | configure one link through networkd, rolled back unless it comes up |
| `hostd.undo` | write | put back what an applied change replaced; needs no grant of its own (see below) |
| `net.wg.apply` | write | configure a WireGuard link through networkd, rolled back unless it comes up and its peers complete a handshake |
| `desk.restart` | write | restart the desk machine that the caller's grant names, session and console included (starts `desk-restart@DESK.service`); the host stays up; no undo |
| `desk.stop` | write | power off the desk machine that the caller's grant names and give the console back (starts `desk-stop@DESK.service`); the host stays up; no undo |

The desk verbs take no machine name. A grant gives the caller one desk through
its `desks` limit, which must name exactly one machine. A grant with no desk,
or with two, is refused.

A desk power action is a cycle that outlives the caller: a restart stops the
desk's session, reboots the machine, starts the session again and switches
the console back to the desk's VT if it was in front (returning it to the
previous VT if the compositor does not come up); a stop returns the console
to the VT that was in front, stops the session and powers the machine off.
hostd runs none of these steps. It starts the host's template unit for the
action with `systemctl start --no-block`, records a receipt that the cycle
started, and answers. The host installs `desk-restart@.service` and
`desk-stop@.service`; the unit's journal says how the cycle ended. If either
unit is missing, the verb is refused `unit_failed`.

Only hostd on the host can do this. A hostd running inside a desk refuses
both verbs `in_container`. The desk reaches the host's hostd through its
socket bound into the machine, so the grant names the caller by its cgroup as
the host sees it, under the machine's payload:
`/machine.slice/systemd-nspawn@DESK.service/payload/system.slice/system-scenes.slice/scenes@VT.service/*`.
Every refusal is logged at warn under `hostd::audit`.
| `net.wifi.scan` | write | scan for Wi-Fi networks on one device (iwd). It changes nothing durable, but it drives the radio, so it needs a grant |
| `net.wifi.connect` | write | connect a Wi-Fi device to a network (iwd), put back unless connected in time |

`host.info` is also published as the retained topic `hostd.info`.

## Who may change what

Reads are open to anyone who can reach hostd. Changes need a **standing
grant** in `/etc/hostd/policy.mx`, a strict-data document that only root
can change:

```text
{
  schema: 1,
  grants: [
    {name: "desk-network",
     caller: {cgroup: "/machine.slice/systemd-nspawn@desk.service/*"},
     verbs: ["net.link.apply"],
     limits: {links: ["eth0", "wlan0"]},
     expires: "2027-01-01T00:00:00Z",
     rate: {count: 3, per_s: 600}}
  ]
}
```

- **The caller is matched by what the kernel says,** never by what it
  sends: its uid and its cgroup. A cgroup only counts when hostd holds a
  pidfd for the caller and the caller was alive after the cgroup was read.
  Both are read again for every request.
- **`X/*` matches the cgroup `X` and everything below it.** Name a subtree
  the caller can't move itself into, such as one under `machine.slice`.
- **Verbs** are exact names or a family such as `net.*`. No grant can name
  `hostd.thaw`.
- **Limits** are allow-lists the verb checks its arguments against
  (`links` for `net.link.apply`). A key the grant doesn't list is
  unrestricted.
- **Rate** applies per caller, with a grant-wide cap of four callers' worth.
- **Default deny.** No policy file means no grants.

The policy is read for every change, so an edit takes effect at once. A
file that anyone but root could change, or that sits in a directory anyone
but root could change, is refused.

## What a change does

Every write follows the same pattern:

1. **Check:** the request is typed and validated (no free text reaches a
   file), then the grant, limits, rate and freeze state.
2. **Record:** a receipt keeps the previous content of every file the change
   replaces.
3. **Apply:** hostd writes only files it names itself, and never edits a file
   it didn't write.
4. **Prove:** a health check runs within the change's window (5 to 60
   seconds, 20 by default).
5. **Keep or revert:** a change that doesn't pass is rolled back
   automatically.

One change runs at a time, host-wide. A change waits at most 15 seconds
behind others (`busy` after that), and the whole gate runs again once it
holds the lock, so a freeze, a suspension, an expiry or a policy edit that
lands while it waits is obeyed. A change runs to the end, rollback
included, even if the caller hangs up.

**A stop waits for a running change** (up to 80 seconds), and a change that
a crash or a forced kill cuts short is rolled back when hostd next starts,
before it accepts any change.

Recovery looks at what each file holds before it acts. It puts back the
backup only over content hostd itself installed. A file someone else has
changed since is left alone, and the receipt is marked `abandoned`. A
rollback, undo or recovery that can't finish, or a receipt that can't be
recorded, blocks all changes (`recovery_pending`). Every later change
retries it first, and changes resume once it finishes.

**Undo puts back exactly what a receipt replaced,** and only while the file
still holds what that change installed. If a later change, or anyone's
edit, has replaced it since, undo is refused (`superseded`): undo the later
change first.

**Two rollbacks in a row** under one grant suspend that grant until root on
the host thaws hostd.

## Network links

`net.link.apply` gives one link a networkd configuration:

```text
{"link": "eth1", "config": {"mode": "dhcp"}}
{"link": "eth1", "config": {"mode": "static",
  "addresses": ["192.0.2.10/24"], "gateway": "192.0.2.1", "dns": ["192.0.2.53"]},
 "window_s": 30}
```

- hostd writes `/etc/systemd/network/50-hostd-<link>.network`, reloads
  networkd and reconfigures the link.
- **`route_metric`** (static with a gateway, or DHCP) sets the metric of
  the default route the link installs. A higher metric loses to a lower
  one, so a second uplink with a high metric never takes over the host's
  default route.
- **It passes** when networkd reports the link configured from hostd's file,
  carrying every requested address with its prefix length. With DHCP or a
  gateway, the default route must also be installed (through the requested
  gateway, if static) and **the gateway must answer**: hostd sends it one UDP
  datagram and reads the kernel's neighbour table until the gateway's
  address resolves. A gateway that doesn't exist fails the change, even one
  inside the link's own subnet.
- **A link another file already configures is refused** (`foreign_config`),
  and so is a link that carries addresses nobody's networkd file set, by
  hand or by another manager such as NetworkManager
  (`unmanaged_configured`). hostd's rollback restores files, so it can't
  give such a link its old runtime configuration back, and it doesn't take
  it over.

The reply to a change that passed (`rc` 0):

```text
{"receipt": "<id>", "outcome": "applied", "reason": null, "grant": "<grant>",
 "grant_suspended": false, "link": {"admin": "configured", "operational": "routable"}}
```

A change that failed and was reversed comes back with `rc` 10, as
`{"status": "rolled_back", "detail": {...}}`, where `detail` has the same
keys. Keep the `receipt` id to undo the change later, or to look it up with
`hostd.receipt`.

**Undo needs no grant of its own.** `hostd.undo {receipt}` is allowed to
whoever holds a grant that covers the original change: its verb and its
limits (for `net.link.apply`, that link). A grant that may configure `hd0`
may undo its own changes to `hd0`. Naming `hostd.undo` in a grant adds
nothing.

## WireGuard links

`net.wg.apply` gives one WireGuard link its networkd configuration:

```text
{"name": "wg-home", "addresses": ["10.99.0.1/24"], "listen_port": 51820,
 "peers": [{"public_key": "<base64>", "endpoint": "vpn.example.com:51820",
            "allowed_ips": ["10.99.0.0/24"], "keepalive_s": 25}],
 "window_s": 25}
```

- hostd writes `50-hostd-<name>.netdev`, `50-hostd-<name>.network` and the
  private key `50-hostd-<name>.key` in `/etc/systemd/network`.
- **The key never leaves the host.** hostd makes it the first time,
  readable only by root and group `systemd-network` (mode 0640), and keeps
  it across later applies. Replies carry only the `public_key`, for the
  peers' side.
- **It passes** when the link comes up configured from hostd's file with
  every address, and **every peer with an endpoint completes a handshake**
  within the window. A peer that never answers puts the change back.
- `require_handshake: false` skips the handshake wait. Use it for the first
  side of a new pair, whose peer doesn't exist yet.
- A link of that name hostd didn't create is refused (`foreign_config`).
- A changed `.netdev` takes effect because hostd deletes its own link and
  networkd creates it again. Peers reconnect within a keepalive.
- Grants limit WireGuard links by `links`, like other links.

hostd's unit has two capabilities, both for this verb:
- `CAP_CHOWN`, to give the key file to group `systemd-network`;
- `CAP_NET_ADMIN`, to read peer handshakes over WireGuard netlink and to
  delete its own WireGuard link.

## Wi-Fi

Wi-Fi goes through iwd. hostd never starts iwd: if it isn't running, the
Wi-Fi verbs answer `no_iwd`.

```text
{"device": "wlan0"}                                         net.wifi.scan
{"device": "wlan0", "ssid": "home", "passphrase": "…"}      net.wifi.connect
{"device": "wlan0", "ssid": "cafe-open", "window_s": 30}    net.wifi.connect
```

- **`net.wifi.scan`** replies with each network's SSID, security
  (`open`, `psk`), signal in dBm, and whether iwd already knows it.
- **`net.wifi.connect`** writes no files.
  - **The passphrase never leaves hostd except to iwd.** It reaches iwd
    through an agent that hostd registers for that one connect. The agent
    answers only the process that owns iwd's bus name, and only for the
    network being connected. iwd saves the network itself, after a
    successful connect. Receipts and the audit never hold the passphrase.
  - **It passes** when the device is connected to that SSID within the
    window.
  - **If it doesn't,** hostd forgets the network (if this change made it
    known) and reconnects the network the device was on before, or
    disconnects if it was on none.
  - **A known network takes no passphrase.** To change one, forget it
    first. An open network takes none, and 802.1X networks are
    `unsupported`.
- **Undo** puts the device back the same way. It is refused (`superseded`)
  once the device has moved to another network since. If someone else
  moved the device during a change, the put-back leaves it alone.
- Grants limit Wi-Fi by `links` (the device) and `ssids`.

## Stopping it

`hostd.freeze` stops every change at once and survives restarts and
reboots. An unreadable freeze record counts as frozen. Only root on the
host itself thaws it, never root inside a container.

## Refusals

| Status | Meaning |
|---|---|
| `not_served` | no such verb |
| `bad_request` | the body doesn't fit the verb's schema |
| `local_only` | a control or write verb arrived over the Bus |
| `caller_unverified` | hostd couldn't prove the caller's cgroup |
| `no_grant` | no unexpired grant covers this caller and verb |
| `outside_grant` | a grant covers the verb but not these arguments |
| `grant_suspended` | the circuit breaker suspended the grant |
| `rate_limited` | the grant's rate is used up |
| `frozen` | hostd is frozen |
| `policy_invalid` | the policy can't be loaded; changes are refused |
| `root_only` | only root on the host may do this |
| `foreign_config`, `unmanaged_configured`, `no_such_link` | `net.link.apply` or `net.wg.apply` won't touch this link |
| `no_iwd`, `no_such_station`, `no_such_network`, `unsupported` | Wi-Fi: iwd isn't running, the device isn't an iwd station, the SSID isn't in range, or the security type isn't handled |
| `rolled_back` | the change failed its health check and was reversed |
| `superseded` | undo refused: the file no longer holds what that change installed |
| `not_applied` | undo refused: the change was rolled back or already undone |
| `rollback_failed`, `undo_incomplete` | a rollback or undo couldn't finish; it is retried, and writes wait |
| `recovery_pending` | an unfinished change is being retried and hasn't finished yet; writes wait |
| `timeout`, `busy` | too slow, or too many requests at once |

## Source layout

The source is
[`services/hostd`](https://github.com/markc/mixos/tree/main/services/hostd):

| File | What |
|---|---|
| `src/local.rs` | the local socket: NUL-framed JSON, per-uid and per-connection limits |
| `src/caller.rs` | caller identity from `SO_PEERCRED`, a held pidfd, cgroup and namespaces, read per request |
| `src/service.rs` | the verb table, tiers, dispatch and the `authorise` gate |
| `src/policy.rs` | grants: loading (one `O_NOFOLLOW` open, root-only), matching, rate limits |
| `src/freeze.rs` | the kill switch, failing closed |
| `src/receipt.rs` | receipts, durable atomic writes, restore, the circuit breaker |
| `src/txn.rs` | the transaction every write runs through: receipt first, conclude (keep or put back, breaker, durable outcome), recovery, undo |
| `src/link.rs` | `net.link.apply`: validation, rendering, the change, its proof |
| `src/wg.rs` | `net.wg.apply`: WireGuard netdev, network and key files, the handshake proof |
| `src/wgnl.rs` | WireGuard generic netlink (peer handshakes) and deleting a link |
| `src/wifi.rs` | `net.wifi.scan` and `net.wifi.connect` through iwd: the one-connect passphrase agent, runtime put-back |
| `src/networkd.rs` | networkd over D-Bus and Varlink, the event-driven health wait |
| `src/net.rs`, `src/info.rs` | the read verbs |
| `units/` | `hostd.socket`, `hostd.service` (sandboxed), `sysusers.conf` |

## Adding a write verb

1. A typed request with `deny_unknown_fields`, validated into a plan before
   anything else happens. Anything the plan reads from the host (a key, a
   file) is read inside the writer lock.
2. `service::write(host, origin, peer, verb, limits, ...)` with the
   allow-list keys the verb checks: it gates the call, takes the writer
   lock, gates it again and runs the change in its own task.
3. The change through `txn`: `FileChange::backup` for every file (with the
   mode and group a new file needs), `txn::begin`, the change and its proof,
   then `txn::conclude`. Never order the breaker or the receipt by hand.
4. A `reapply` for the verb in `txn::put_back`, so rollback, recovery and
   undo can make the host use the restored files. Without it the verb
   doesn't ship.
5. The paths it writes added to `ReadWritePaths=`, and any capability it
   needs to `CapabilityBoundingSet=`, in `units/hostd.service`, with the
   reason beside it.
6. Registered in `docs/docs/spec/bus/verbs.conf.mix` (class `intent`), in
   this page, and reviewed on its own.

## Tests

`cargo test -p hostd`: no test needs root. The live gate for network writes
runs as root on a disposable networkd host, on dummy links only, and
removes everything it made.

---

<!-- page: https://mixos.dev/indexd/ (source: https://mixos.dev/indexd/README.md) -->

# The semantic index service

> **Status: Bus wired.** The engine, reconnecting daemon, bridge, CLI and
> system unit are implemented. Corpus parity and production cutover are
> separate steps. The tokenizer golden records the legacy 0.21.4/onig token IDs.

`indexd` stores text chunks with their embeddings and returns the nearest
matches for a query. Embeddings are computed locally on the CPU with
`nomic-ai/nomic-embed-text-v1.5` (768 dimensions), through the pure-Rust
`candle` stack. The model files are loaded from a local directory and never
downloaded at run time. Vectors live in SQLite (`sqlite-vec`), and search runs
over an in-memory copy, re-ranked by feedback and staleness.

It runs on one workstation host as a system service, registered on that
host's own node. Agents usually reach it through `mixos-mcp`
(`context_search`, `index_workspace`, the `skills_*` tools). A desk on the
same machine reaches it over the Bus, or over ssh through `indexd bridge`,
which reads newline-delimited JSON on stdin and makes each request as a local
Bus call.

## Asking it

On the Bus, the service is `indexd`:

```mix
send indexd indexd.stats
send indexd indexd.search query="how are service dependencies declared" limit=3
```

Each body is a JSON object. Clients may include an `action` equal to the verb
suffix; a conflicting value is rejected. Replies contain the verb's JSON
directly. Errors use rc 10 and a string `error` field. Metadata is always a
JSON-encoded string, including each element of `store.metadata`.

| Verb | Request fields | Reply |
|---|---|---|
| `indexd.embed` | `texts`, optional `prefix` | `embeddings` |
| `indexd.store` | `texts`, `source`, `metadata` | `stored`, `duplicates`, `ids` |
| `indexd.search` | `query`, `limit`, optional `source`, `metadata_filter` | `results` |
| `indexd.update` | `id`, optional `content`, `metadata`, `source` | `updated`, `re_embedded` |
| `indexd.delete` | optional `ids`, optional `filter` (at least one non-empty) | `deleted` |
| `indexd.list` | optional `source`, `limit`, `offset` | `items`, `total` |
| `indexd.feedback` | `id`, `useful` | `id`, `feedback_score` |
| `indexd.supersede` | `old_id`, `new_id`, optional `reason` | `updated` |
| `indexd.stale` | optional `source`, `never_retrieved_age_days`, `low_value_min_retrievals`, `long_dormant_days`, `per_bucket_limit` | three buckets, `total_chunks` |
| `indexd.stats` | none | counts, model/cache/queue statistics, `by_source` |
| `indexd.index_file` | absolute `path`, optional `content`, `source`, `domain`, `background` | `indexed`, `sections`; background acknowledgement when queued |

`search` excludes superseded chunks before applying its limit. Filter entries
have `field`, `op` (`eq`, `gt`, `lt`, `gte`, `lte`, `contains`) and `value`.

Delete filters use the same predicate shape, for example
`{"filter":[{"field":"path","op":"eq","value":"/srv/project/a.md"}]}`.
Predicates are ANDed; when IDs are also supplied they restrict the matching set.
DELETE accepts only `eq`, with a non-empty string, number or boolean value.
Each predicate also requires the matching JSON type (integers and reals share
the numeric type); null, arrays and objects are refused. Search retains all
operators listed above.
Deletion updates the durable vectors and in-memory index in one operation.

## CLI and bridge

`indexd -c /etc/mixos/indexd/config.conf.mix call indexd.stats` opens the
configured engine in-process and prints one JSON reply, with exit status 0
for success or 1 for an error. Bare verb names also work. For example:

```text
indexd -c /etc/mixos/indexd/config.conf.mix call indexd.search '{"query":"service dependencies","limit":3}'
```

Writes (`store`, `update`, `delete`, `feedback`, `supersede`, `index_file`)
require `call --offline` with the daemon stopped: otherwise its in-memory
index would desynchronise. Read verbs need no flag. `call` always refuses
`background:true` because no process remains to run the queued job.

`indexd bridge` connects to the local node's Bus once and forwards one call
per stdin line, flushing each reply immediately. It does not open the index
or require model configuration. Keep one process alive for repeated requests,
including through `ssh -T user@example.test /opt/mixos/bin/indexd bridge`.
The bridge honours non-empty `MIXOS_NODED_URL` first. Otherwise it reads
`--node-config PATH`, then non-empty `MIXOS_NODE_CONFIG`, defaulting to
`/opt/mixos/etc/node.conf.mix`, the same file pinned by the system unit.
It derives the broker address from that file rather than user config discovery.

```json
{"id":1,"verb":"indexd.search","body":{"query":"service dependencies","limit":3}}
```

Each stdout line is `{"id":1,"rc":0,"body":{...}}`, with the original JSON
`id` preserved. Application errors retain rc 10 and the JSON error body.
Transport failures use `{"id":1,"rc":-1,"error":"..."}` and then exit non-zero,
including initial connection failure, so a supervisor can respawn it. EOF exits 0;
stdout contains only protocol replies. The bridge never retries a call.

Requests may carry `timeout_secs`, default 60 and capped at 600 seconds.
A timeout returns `{"id":1,"rc":-1,"kind":"timeout","error":"..."}` and
leaves the bridge alive. The operation's outcome is unknown. Empty Bus bodies
become JSON `null`; Bus error headers are forwarded as the top-level `error`.

## Operating the system service

`indexd serve` registers service `indexd` using the standard Bus connection
helper, advertises the eleven verbs above, and reconnects with backoff.
`MIXOS_NODE_CONFIG` selects the system broker, as for dnsd. The supplied unit
pins `/opt/mixos/etc/node.conf.mix`; no broker URL is embedded in indexd.
SIGTERM stops admission and completes accepted Bus calls before exit.
The model loads lazily on the blocking pool under the inference permit and
unloads after the configured idle interval (300 seconds by default).

Configuration lookup is `-c/--config`, then
`/etc/mixos/indexd/config.conf.mix`, then
`$XDG_CONFIG_HOME/mixos/indexd.conf.mix` (or the equivalent under `$HOME/.config`).
`indexd -c FILE check-config` validates the local `config.json`,
`tokenizer.json` and `model.safetensors` before loading any weights. HF snapshot
symlinks are supported. There is no database environment override;
`service.vectors_db` is authoritative. `MIXOS_INDEXD_SEARCH` remains the
engine's one-release rollback switch (`sqlite` selects SQLite search).

The default domain map is empty, so unmapped files use `general`. Configure
absolute prefixes; the daemon does not expand `~` in domain keys or file paths.
The sample at [`services/indexd/examples/config.conf.mix`](https://github.com/markc/mixos/blob/main/services/indexd/examples/config.conf.mix) includes:

```text
domains: {map: {
  "/home/user/Projects/mixos": "mixos",
  "/home/user/.mix": "mix",
  "/home/user/.ns": "ns",
  "/home/user/.mc": "mc"
}}
```

Replace `/home/user` with the operator's absolute home path. Set `model_dir`
to the pre-seeded snapshot; no model download happens at runtime.
`ProtectHome=yes` hides home directories from the service: callers must pass
`index_file.content` for those paths, or use `store`. `index_file` rejects a
tilde-prefixed path even when content is supplied.

The component owns `indexd.service` and `sysusers.conf`; the desktop release
bundle carries the standalone binary and these files under `share/indexd/units/`,
with the sample config under `share/indexd/examples/config.conf.mix`,
following the component-owned maild packaging pattern. Install the binary
under `/opt/mixos/bin`, the unit under `/etc/systemd/system`, sysusers under
`/usr/lib/sysusers.d/indexd.conf`, and a customised config under
`/etc/mixos/indexd/config.conf.mix`. Apply sysusers before starting the service.
The unit wants system `noded.service`, runs as `indexd:indexd`, limits memory
to 2 GiB, sets `MALLOC_ARENA_MAX=2`, and hardens filesystem, devices and kernel
access. TCP address families remain available for the configured broker.
`MemoryDenyWriteExecute=yes` follows the former candle CPU service.
systemd creates the state and configuration directories, so no tmpfiles entry
is needed. Before cutover, back up existing data and explicitly change its
ownership from the legacy account; the new account does not reuse its UID.

## Tests

On a CBC worker, `cargo test -p indexd` runs the engine tests, registry checks,
real daemon/bridge pipe tests, and `services/indexd/tests/bus_test.mix` against
`libs/test-broker`. Set `MIXOS_TEST_MIX` if Mix is not installed at
`/opt/mixos/bin/mix`. Embeddings are deterministic cache fixtures; no model
is needed. The tokenizer parity test compares 0.22.2 token IDs against the
committed legacy 0.21.4/onig golden; it stays ignored unless
`INDEXD_TEST_TOKENIZER` names the staged tokenizer file.

## Indexd is not exhaustive

indexd answers "what is relevant to X", quickly and approximately, from an
index that can lag the files. To prove that something does **not** occur, use
an exact search over the current files instead.

---

<!-- page: https://mixos.dev/inputd/ (source: https://mixos.dev/inputd/README.md) -->

# The input broker

`inputd` reads the keyboard below the compositor, where Left Ctrl and Right
Ctrl are still different keys. A key the person has bound fires a Bus verb
and never reaches an app. Everything else is passed on unchanged.

It is the successor of AmigaOS's `input.device`: keys become verbs, and
bindings are data that a person, an agent or a Bus message can change.

## The user keys

These strokes belong to the person, never to an app or a system default:

- **bare F1 to F12;**
- **Right Ctrl, Right Alt or Right Shift with an arrow** (any of the three
  right-hand modifiers, and no other modifier).

inputd swallows every user key on its press, repeats and release unless the
person has bound it to a verb or marked it passthrough. The shipped keymap
binds none of them. `Ctrl+F3`, bare arrows and Left-hand modifier arrows
stay with the apps.

The one shipped binding is the system-reserved recovery chord `Ctrl+Alt+P`
(Left or Right Ctrl with Left Alt), which toggles the scene editor.

## How a key is decided

Each key is decided **once, at its press**, and keeps that decision until
it is released:

- **fire:** a binding matched, so its verb is sent and the key is
  swallowed. A row with `repeat: "allow"` fires again on each repeat.
- **swallow:** an unbound user key.
- **pass:** anything else, or a passthrough row. The key is re-emitted on
  the `inputd virtual keyboard` device.

Releasing Right Ctrl before → still swallows the → release. A binding
changed while a key is held applies from that key's next press.

## Grab and VTs

With `--grab DEVICE` or `--grab-name NAME`, inputd grabs the keyboard
(`EVIOCGRAB`) and re-emits what it passes. With `--vt N[,M...]` it holds the
grab only while one of those VTs is the active console:

- **On switch-away,** it releases on the re-emitter every key it had passed
  and is still held, then drops the grab. The next VT's compositor reads the
  keyboard directly.
- **On switch-to,** it takes the grab again, but only once **no key is
  down**. A key held across the grab would stay down in the compositor,
  which saw its press but would never see its release. So while the
  switch chord (Ctrl+Alt+Fn) is still held, inputd waits ungrabbed and
  checks again at each report from the keyboard, and also on a timed retry
  with a backoff from 50 ms up to 2 s (in case another holder takes the
  last release). While another holder still has the device, it retries on
  the same backoff.
- **If the kernel drops events** (`SYN_DROPPED`), inputd re-reads which
  keys are down, releases every key it had passed on, and swallows any key
  still held until it is released.

It watches `/sys/class/tty/tty0/active` with `poll(2)`, so a switch wakes it
at once: the active VT is never polled on a timer. The only timers are the
bounded grab retries above. The re-emitter is made once, at
start, and kept: a compositor in a container cannot see an input device that
appears after it started.

## Known limits

All of these happen only while inputd takes the grab (at startup or on
switching to its VT) with keys in motion, and none can be closed from inputd. They
close where the compositor enforces the user keys itself: compd's user-key
layer.

- **A key can stay down in the compositor.** If a key is pressed before the
  grab and released in the brief window while inputd checks, grabs and
  discards queued events, the release is consumed under the grab. The
  compositor saw the press on the original keyboard and never sees its
  release; `EVIOCGRAB` offers no way to hand it back on that device.
- **A key tapped as the grab is taken can be lost.** A press and release
  that both land between the grab and the discard of queued events reach
  neither the apps nor inputd's bindings. Nothing is left held.
- **User keys pass while inputd waits.** While a key is held at switch-to,
  inputd is not grabbed, so a user key pressed in that time reaches the
  apps unclassified.

## Running it

| flag | what it does |
|---|---|
| (none) | the Bus service only; no keyboard |
| `--observe DEVICE` | read a keyboard without grabbing it, and log what each key would do |
| `--grab DEVICE` | grab this event node |
| `--grab-name NAME` | grab the node whose name in `/proc/bus/input/devices` is NAME |
| `--vt N[,M...]` | hold the grab only on these VTs |
| `--grab-timeout SECONDS` | exit after this long, which releases the grab |
| `--keymap PATH` | the keymap file (default: `keymap.json` in the state directory) |

The unit `inputd.service` runs the Bus service only. An operator turns the
grab on with a drop-in, after a supervised run with `--grab-timeout` from a
shell that can kill it. Any exit of inputd, SIGKILL included, releases the
grab.

## The keymap file

`/var/lib/mixos/inputd/keymap.json` (the unit's state directory), in the
keymap.v1 format:

```json
{"version": 1, "physical": [
  {"stroke": {"code": 106, "modifiers": {"right_ctrl": true}},
   "action": "comp.workspace.switch", "args": {"index": "next"},
   "service": "comp", "repeat": "allow"}
]}
```

`code` is the Linux key code. `service` names the Bus service the verb goes
to; without it, the verb's first dot-segment does. `args` is the verb's
body. A row with `"passthrough": true` re-emits its stroke instead.

## Verbs

| verb | what it does |
|---|---|
| `input.query` | the rows, the mode and the generation |
| `input.bind` | add or replace a row (`{"layer":"physical", ...row}`) |
| `input.unbind` | remove the row on a stroke (`{"code":..., "modifiers":{...}}`) |
| `input.mode` | `{"mode":"transparent"}` passes every key unchanged; `normal`; empty toggles |
| `input.reload` | re-read the keymap file |
| `input.key` | inject a key press, release or tap |
| `input.pointer.move`, `.button`, `.scroll` | inject pointer input |

Bindings are written through to the keymap file. `MIXOS_MESH_OPEN=0`
limits the keymap changes to node-local callers.

---

<!-- page: https://mixos.dev/logging/ (source: https://mixos.dev/logging/README.md) -->

# logging

Shared tracing, sink selection, reload handles and process statistics for
MixOS services and the Mix shell. The default build has no Bus or HTTP
listener; `bus-handlers`, `prometheus` and `props` are explicit features. Log files
use the directory rule in [config](../config/README.md), including isolated
session roots.

Transplant provenance: commit
`e0297242305f3a3c3de09f1ca01e8faa771768da`, MIT OR Apache-2.0. Production callers are Mix and
[noded](../noded/README.md).

## Property-controlled logging

Enable `props` to register the `<svc>.log` singleton against the service's
[property store](../props/README.md). Call
`logging::props::register(&mut router, &store)` to obtain `LogNamespace`,
then await `logging::props::attach(&handle, namespace)` on the service's
Tokio runtime. Registration and read failures return `LogError::Props`.

Accepted `level` and `filter` writes update the live `EnvFilter`.
`level=none` installs `off` while preserving the subscriber for later
changes. Hooks reject malformed filters, unknown enum variants and deletes.
The watcher uses a namespace-private `Notify`, so it does not compete with
the property dispatcher. It lives until the Tokio runtime shuts down.

`format` remains stored introspection data and does not rebuild sinks.
`applied_at`, `applied_by` and `source` remain mutable metadata; the watcher
does not write them back. The current log policy grants every reachable
peer the namespace's capabilities, including write access that can silence
logging. Services needing narrower access must supply their policy.
See the [contract](../docs/spec/props/README.md#logging) for the frozen schema.

The source is [`libs/logging`](https://github.com/markc/mixos/tree/main/libs/logging).

---

<!-- page: https://mixos.dev/maild/ (source: https://mixos.dev/maild/README.md) -->

# maild

Maild serves JMAP, SMTP, IMAP, CalDAV and CardDAV. Its library builds the
same runtime for the daemon and integration tests. Private crates provide
mail authentication, rules, Bayesian classification and metadata storage.

## Properties

Maild uses the shared `props` library with its `store`, `sqlite` and `router`
features. A `SqliteStore` named `maild` and a `PropsRouter` with service name
`maild` own the `account_overrides`, `accounts`, `aliases`, `domains`,
`engine_config`, `retention`, `tls_identities` and `log` namespaces. The
namespace modules register their schemas, SQLite mappings and hooks during
`build_runtime`; the logging library registers `log` through
`logging::props::register`.

The router handles `maild.props.*` requests. Durable changes publish on
`maild.props.records.changed` and `maild.props.audit`; replay and audit
semantics, capability strings, error tokens and the five `__props_*`
SQLite table names follow the shared props contract unchanged. Account,
alias and domain hooks reconcile the mail store after committed changes.

## Shared libraries

Maild uses `bus::native_client::NodedClient` and the Bus connection helpers.
Its advertised verbs are registered in the repository Bus registry and checked
by `tests/registry.rs`. Incoming commands retain their connection generation;
the typed port helper preserves the remote return code and parsed reply.

Configuration uses `config::Dir::{Etc, Var}` and `config::path`. The system
file is `<Etc>/maild/config.conf.mix`; strict-data loaders return typed errors.
Node-wide mail settings use the typed `config::node::NodeConfig` fields, with
the shared `config::tls` SNI resolver. Logging attaches the namespace returned
by `logging::props::register` through `logging::props::attach`.

Build provenance comes from `buildinfo` and its `MIXOS_*` build variables.
Mail filters use the shared `mix` interpreter with its `json` and `serde`
features. DAV uses `davproto` and the `mixos:rawICalendar` and `mixos:rawVCard`
keys; retired raw keys remain errors.

## Metadata store

`Mds` is the storage interface. `SqliteCasMds` stores per-set metadata in
SQLite, shares a content-addressable blob store, and emits notifications
after transactions commit. The library supports verification, garbage
collection, index rebuilding, statistics and set archive import/export.

The archive format retains its original v1 identifier for compatibility with
existing exports. The GC quiescence override is `MDS_GC_QUIESCENCE_SECS`;
it accepts integer seconds of at least five, with a default of 60 seconds.

Run `cargo test -p mds` on a build worker. The `mem-store` feature exposes
an in-memory implementation for consumers' tests. `_stress-helper` enables
the internal `mds-stress-writer` and its Unix SIGKILL recovery test; this
helper is never installed.

## Running and packaging

The system binary carries maild as a personality: install `maild` as a symlink
to `mix`. The standalone development binary runs the same library entry point.
`tools/package.mix` includes that symlink, the template service and sysusers
declaration, and the vendored parser's licences in the server archive.

`maild@INSTANCE.service` requires `noded@INSTANCE.service` and reads the same
`/etc/mixos/session/INSTANCE.env` file, including its `MIXOS_NODE_CONFIG` broker
configuration. It runs as the `maild` account. The unit uses
`/etc/mixos/maild/config.conf.mix`, creates `StateDirectory=maild`, and sets
`MIXOS_VAR=/var/lib/maild`; configured TLS material must be readable by maild.
The unit documentation URL points to this manual.

`maild.service` is the plain per-host form, for a host that runs the plain
`noded.service` rather than per-session brokers. It reads the node config
from `/etc/mixos`, creates `StateDirectory=mixos/maild`, and takes its data
paths from the maild config. The sysusers declaration adds maild to the
`mixos-tls` group (gid 510), which it shares with webd for the TLS keys.

---

<!-- page: https://mixos.dev/mds/ (source: https://mixos.dev/mds/README.md) -->

# mds

Per-container-set SQLite metadata and a content-addressable blob store.

`mds` is a library. It has no daemon of its own: maild links it, and blobd
will link it as the blob store. It provides the `Mds` trait, the production
implementation `SqliteCasMds` (one `data.sqlite` per set, one box-wide
`blobs.sqlite` index, and a flat CAS directory), and a `MemMds` for tests
behind the `mem-store` feature.

- Immutable content, multi-container mutable metadata, ordered access within
  a container, and a change log.
- Set and container lifecycle, blob put and get with BLAKE3 addressing, item
  add, copy, move and flags, change feeds, rebuild, verify, gc, export and
  import.
- Events are emitted after the durable commit, to an in-process sink. Publishing
  them on the Bus is the consumer's job.

The operator command-line binary is not ported yet.

---

<!-- page: https://mixos.dev/mesh-sign/ (source: https://mixos.dev/mesh-sign/README.md) -->

# mesh-sign

`mesh-sign` turns the authored `inventory.mix` into the signed trust root,
`inventory.signed`, and checks a signed inventory against the genesis public
key. The signing and verifying code is the same code the mesh daemon `noded`
uses, so the two cannot disagree about the bytes a signature covers.

Install the binary at `/opt/mixos/bin/mesh-sign`.

## Subcommands

| Command | What it does |
|---|---|
| `genesis` | Create the genesis Ed25519 key and store its signing half in the secrets database. It refuses to overwrite an existing key unless `--force` is given. |
| `sign INVENTORY --out PATH` | Sign an authored inventory and verify the result before reporting success. `--valid-days` sets an advisory horizon. `--recovery N` and `--recovery-generation N` set the recovery fields and are mutually exclusive. |
| `verify SIGNED` | Check a signed inventory against the genesis key. It takes `--genesis-pub PATH` or `--genesis-pub-base64 B64`, or else reads the key from the secrets database. `--expected-mesh NAME` pins the mesh name, and `--against-authored PATH` checks the signed payload against an authored file. `--json` prints one versioned JSON object. |
| `pubkey` | Print the genesis public key, which is provisioned to each node as `/opt/mixos/etc/noded/genesis.pub`. |
| `d2-gen NODE` / `d2-pubkey NODE` | Create or print a node's admission key. |
| `wg-gen --private-file PATH` | Create a node-local WireGuard key in a new mode-0600 file and print only the public key. |
| `wg-pubkey --private-file PATH` | Print the public key of an existing protected node key. |

Global options: `--secrets-db PATH` (default `~/.ns/_etc/secrets/secrets.db`)
and `--mesh NAME` (default `bus`). `mesh-sign --version` prints the build
provenance.

## Verify report

`verify --json` prints an object whose `format` is `cosmix-mesh-sign.verify.v1`.
That string is a frozen wire constant. It keeps its original spelling so that
existing consumers still match it.

## Testing

Build and test on a cbc worker, not on the desk:

    mix ~/.mix/_bin/cbc-build.mix --worker cbc2 --repo mixos --commit <sha> -- cargo test -p mesh-sign --locked

The integration suite (`cli/mesh-sign/tests/verify_cli.rs`) runs the binary
against generated keys and inventories in a temporary directory.

---

<!-- page: https://mixos.dev/mimedb/ (source: https://mixos.dev/mimedb/README.md) -->

# mimedb

`mimedb` reads the freedesktop shared-mime-info database from the same
files the desktop reads, and decides a file's MIME type by GLib's rules. The
answer agrees with `gio info` and the file manager. It is a plain Rust
library with no Bus verbs, and its only dependency is `libc`.

Two components use it:

- [Mix](../mix/README.md), through the `mime_type()` builtin (behind the
  `mix` crate's `mime` feature; see [Mix I/O](../mix/io.md)).
- [thumbs](../thumbs/README.md), which types a file before choosing a
  thumbnailer for it.

The source is
[`libs/mimedb`](https://github.com/markc/mixos/tree/main/libs/mimedb).

## The database

Each `mime` directory under `$XDG_DATA_HOME` (default `~/.local/share`) and
`$XDG_DATA_DIRS` (default `/usr/local/share:/usr/share`) can hold `globs2`
(or the older `globs`), `magic`, `aliases` and `subclasses`. Directories are
read highest precedence first, and relative entries are ignored, as the XDG
spec requires. A higher directory's `__NOGLOBS__` and `__NOMAGIC__` entries
clear a lower one's rules for that type. Missing directories and files are
skipped. A file over 16 MiB (`MAX_FILE`) is skipped, and so is anything that
is not a regular file once opened: a FIFO in a database directory is never
waited on.

## How a type is decided

1. A non-regular file is its `inode/*` type (`inode/directory`,
   `inode/fifo` and so on), and an empty file is `application/x-zerosize`.
2. If exactly one glob matches the name, that is the answer.
3. Otherwise the leading bytes are sniffed: the highest-priority magic
   match, or `text/plain` when the content looks like text.
4. With no glob match, the sniffed type is the answer, or
   `application/octet-stream` (uncertain) if nothing was sniffed. With
   several glob matches, a sniffed type of priority 80 or more wins; failing
   that, the first glob type that is a subclass of the sniffed type wins;
   failing that, the first glob type wins, marked uncertain.

Globs are matched in GLib's order: a literal name, then the longest
`*.suffix`, then full patterns. At most `SNIFF_MAX` (16384) bytes are read,
GLib's limit, and fewer when the magic rules reach less far.

One known limit: full patterns use the crate's own `fnmatch`, not glibc's.
POSIX named classes use Unicode's predicates instead of a locale's tables,
and collating symbols cannot end a range. The stock database uses neither.

## API

- `Database::load()` loads the desktop's database (`xdg_mime_dirs()`);
  `Database::load_from(&dirs)` loads given `mime` directories, highest
  precedence first.
- `for_path(path, content) -> PathGuess` types a file, following symlinks.
  With `content` false the file is never opened. A missing path is typed by
  its name (`exists: false`); an unreadable one by its name, uncertain.
- `guess(name, data) -> Guess` decides from an optional name and optional
  leading bytes, for a caller that already has the file open.
- `Guess { mime, by, uncertain }`, where `by` is a `By`: `Stat`, `Glob`,
  `Magic`, `Content` (an empty file or the text check) or `Fallback`.
  `By::as_str()` gives the lower-case name.
- `globs(name)`, `sniff(data)`, `unalias(mime)`, `is_subclass(mime, base)`
  and `parents(mime)`. Parents come nearest first and include the spec's
  implicit ones: `text/plain` for `text/*` types and
  `application/octet-stream` for everything but `inode/*`. Cycles in
  `subclasses` are visited once.
- `is_stale()` reports whether any directory or database file has changed
  (timestamp or size) since loading, so a long-lived caller can reload.
  `sniff_len()` is how many bytes to read before calling `guess`.
- `text_fallback(data)` and `looks_like_text(data)` are the two text checks.

## Example

thumbs reads the start of a file it already has open and asks for its type:

```rust
let db = mimedb::Database::load();
let mut data = Vec::new();
source.take(db.sniff_len() as u64).read_to_end(&mut data)?;
let mime = db.guess(Some("photo.jpg"), Some(&data)).mime;
```

From Mix, the same answer comes from `mime_type()`, which keeps one
database per thread and reloads it when `is_stale()` says so or the XDG
directories change:

```mix
$r = mime_type("/etc/hosts")
print($r.mime)
```

## Source and tests

- `src/lib.rs`: the database, loading and layering, the decision rules,
  and the subclass graph.
- `src/glob.rs`: parsing `globs2`/`globs` and the desktop's match order,
  including `fnmatch`.
- `src/magic.rs`: parsing and matching the binary `magic` file.

Unit tests in each module build private `mime` directories in a temporary
directory, so they never depend on the host's `/usr/share/mime`. They cover
layer clearing, staleness after a same-size rewrite, oversized files,
priority-zero magic, cycles and very wide parent graphs. The `mix` crate's
[`tests/mime_type.rs`](https://github.com/markc/mixos/blob/main/libs/mix/tests/mime_type.rs)
tests the builtin against a private database the same way.

---

<!-- page: https://mixos.dev/mix-shell/ (source: https://mixos.dev/mix-shell/README.md) -->

# mix-shell

The Mix shell: interactive line and editor facilities, the strict command
classifier, the native-session bootstrap and the ABP citizen runtime. All
application calls go through noded; the retired per-application socket fast
path is omitted. The client supervisor is the shared implementation in
[bus](../bus/README.md).

The language itself is the [mix](../mix/README.md) library, and its manual
is at [/mix/](../mix/README.md).

## The binary

This package is a library. The `mix` binary is built by
[system](../system/README.md), which runs `mix_shell::main` when started as
`mix` ([decision](../docs/decisions/2026-10-12-one-system-binary.md)):
`cargo build -p system`. The shell's process-level tests live in
`cli/system/tests` and run that binary (`cargo test -p system`); the unit
tests and library-only tests stay here.

## Session and manuals

The bootstrap retains the frozen `MIXOS_SESSION_FD` marker, sealed memfd
name and native-session transcripts. Ordinary shells initialise no grant
owner. Bundled manuals are available offline and use the same directory
rule as the session's other installed resources. Explicit remote manual
selection remains available.

## Provenance

Transplanted from `src/crates/mix` at mixos
`e0297242305f3a3c3de09f1ca01e8faa771768da`, with the complete regression
corpus. The native integration fixture compiles noded's production modules
and Term's production sealed-FD implementation, rather than simulating
session RPCs.

The source is
[`cli/mix-shell`](https://github.com/markc/mixos/tree/main/cli/mix-shell).

---

<!-- page: https://mixos.dev/mix/buffer/ (source: https://mixos.dev/mix/buffer.md) -->

# buffer — the reference-semantic mutable byte buffer

`Buffer` is the one type in Mix with **reference semantics**. Everything else —
strings, numbers, lists, maps, `bytes` — is value-semantic: `$b = $a` gives `$b`
an independent copy, and passing a value into a function can't mutate the
caller's copy. A `Buffer` is the deliberate exception: `$b = $a` makes `$b` an
**alias** of the same underlying byte store, and an in-place append through
either name is visible through both.

It exists for one job: building or editing **large binary blobs** (audio/video
samples, `.mid`/`.wav`/image bytes) without the O(n²) cost of value-semantic
append. `buffer_push` grows the store in place (O(1) amortized); the
value-semantic alternative — re-building a `bytes` each step — copies the whole
growing blob every time. When you're done, `freeze` snapshots the buffer to a
value-semantic `bytes` for the write_file / hash / base64 / http sinks.

List the family live with `mix builtins buffer`; one-line help with
`mix builtins NAME`.

## The builtins

| Call | Result | Notes |
|---|---|---|
| `buffer()` | empty buffer | |
| `buffer(n)` | buffer of `n` zero bytes | allocate — `n` a non-negative integer |
| `buffer("MThd")` | buffer of the string's UTF-8 bytes | |
| `buffer($bytes)` / `buffer($buf)` | an **independent** copy | fresh backing store |
| `buffer([items])` | flat splice of each item | each item: int 0-255 / string / bytes / buffer |
| `buffer_push($buf, item, ...)` | `nil` — appends in place | reference-semantic; variadic; same item kinds |
| `buffer_get($buf, i)` | byte at 0-based `i` as a number, or `nil` if out of range | |
| `buffer_set($buf, i, byte)` | `nil` — writes `byte` (0-255) at `i` | errors if `i` is out of range |
| `bytes_len($buf)` | length in bytes | the same builtin works on `bytes` |
| `freeze($buf)` | a value-semantic `bytes` snapshot | the bridge to the byte sinks |

`bytes_to_string`, `base64_encode`, `hash_sha256`/`hash_blake3`, and
`write_file`/`append_file`/`write_new` all also accept a `Buffer` directly, so
you rarely need an explicit `freeze` just to hand a buffer to a sink.

Since **v0.64.0** a buffer also answers the generic sequence operations and the
whole `bytes_*` family — `$buf[i]`, `length($buf)`, `slice($buf, s, e)`,
`for each $x in $buf`, `bytes_find`, `bytes_split`, `bytes_to_hex` and the rest;
see [io](io.md#bytes-as-a-sequence-v0640). Three properties matter because a
buffer is reference-semantic:

- **`slice` returns an independent `bytes`**, never a view — a later
  `buffer_push` cannot change a slice you already took.
- **`for each` is pinned at loop entry** — growing the buffer inside the body
  does not extend the loop.
- **`$buf[i]` is NOT a synonym for `buffer_get($buf, i)`.** They agree on an
  in-range non-negative integer, and both answer `nil` when a non-negative
  index is past the end — but they part company on the other index forms:
  `$buf[i]` follows Mix's universal *indexing* rules (a negative index counts
  from the end, a fractional one truncates), while `buffer_get` is a strict
  accessor that **raises** on both:

  ```mix
  $buf = buffer("ab")
  print($buf[-1])              -- 98  (the last byte)
  print(buffer_get($buf, -1))  -- raises: index must be a non-negative integer
  ```

  Neither is wrong; `$buf[i]` is consistent with `$list[i]`/`$str[i]`/`$b[i]`,
  and `buffer_get` is consistent with `buffer_set`, which must refuse a
  computed-nonsense index rather than write somewhere surprising.

Writing through the index (`$buf[i] = 65`) is still refused; the in-place write
is `buffer_set`.

## Building binary — the media-pipeline idiom

```mix
-- a MIDI header chunk: ASCII magic + raw length/format bytes in one call
$mid = buffer(["MThd", 0, 0, 0, 6, 0, 1, 0, 1, 0, 0x60])
buffer_push($mid, "MTrk")          -- append the track magic in place
buffer_push($mid, 0x90, 60, 100)   -- a note-on event, byte by byte
write_file("out.mid", $mid)        -- the buffer writes verbatim
```

`buffer([...])` and `buffer_push` take the same flat item kinds — an integer
0-255 becomes one byte (a non-integral or out-of-range number is an error, since
Mix numbers are f64), a string splices its UTF-8 bytes (inline ASCII magic like
`"RIFF"`/`"P6"`), and a `bytes`/`buffer` splices its current content.

## Reference semantics — the one thing to remember

```mix
$a = buffer([1, 2])
$b = $a                 -- $b ALIASES $a — same backing store
buffer_push($b, 3)
print(bytes_len($a))    -- 3  (the append through $b is visible through $a)

$c = buffer($a)         -- buffer($x) makes an INDEPENDENT copy
buffer_push($c, 9)
print(bytes_len($a))    -- 3  (unchanged — $c has its own store)

$snap = freeze($a)      -- value-semantic bytes; frozen at this moment
buffer_push($a, 99)
print(bytes_len($snap)) -- 3  (the snapshot doesn't move)
```

Gotchas that fall out of reference semantics:

- **A buffer inside a copied list stays shared.** Copying a list deep-copies its structure, but a `Buffer` element is a reference — the copy's element and the original's element are the same buffer. Use `freeze($buf)` or `buffer($buf)` to store an independent snapshot in a collection.
- **`==` is content equality**, like `bytes`: two distinct buffers with the same bytes compare equal. A `Buffer` and a `bytes` are never equal — `freeze` first to compare across the two types.
- **`print`/interpolation show `<buffer:N>`**, never the raw bytes (dumping high-bit bytes corrupts terminals — the same reason `bytes` prints `<bytes:N>`). Reach the payload with `bytes_to_string`, `base64_encode`, or `write_file`.
- **An empty buffer is falsy**; a non-empty one is truthy.

## When to use which

- Reach for **`bytes`** (value-semantic) for a fixed binary payload you read once — an HTTP body, a `read_file_bytes` result, a `base64_decode` output — and for anything you store in a list/map or pass around expecting copy semantics.
- Reach for **`Buffer`** (reference-semantic) when you are *constructing* or *editing* a blob incrementally — appending in a loop, patching bytes in place — where the value-semantic copy-per-step would be O(n²).
- `freeze` converts buffer → bytes when you're done building; `buffer($bytes)` converts the other way when you want to start editing.

---

<!-- page: https://mixos.dev/mix/builtins/ (source: https://mixos.dev/mix/builtins.md) -->

# Builtin index

Every Mix builtin grouped by category, generated from the binary's own `mix builtins --json`. See the linked topical page for prose and examples; `mix what NAME` prints a one-line description of any single builtin (or keyword), and `mix help` prints a compact names-only summary.

Some builtins are feature-gated on the `mixos-lib-mix` crate (`json`, `regex`, `toml`, `yaml`, `datetime`, `url`, `crypto`, `http`, `sqlite`, `archive`, `dkim`, `markdown`, `datastar`, `xml`, `mime`) so embedders can pull only what they need — the `mix` binary turns them all on.

## Machine-readable discovery (metadata_schema 1)

From 0.97.0, `required_capabilities` lists additional unconditional capability
classes beyond `capability`. File transfers use this to require filesystem
access even without an options map. Evaluator policy checks and `mix lint`
enforce the combined set; `conditional_capabilities` remains option-dependent.

Argument entries also carry `hint` (instructional text or null), including
encode-first guidance for file payloads; this is additive within metadata_schema 1.

Since 0.29.0 every builtin carries a structured contract — per-argument names/kinds/optionality, derived min/max arity, a return shape, effect flags, an operational-failure mode, and any conditional capabilities. The human signature shown by `mix builtins <name>` is derived from the same contract, so it can never drift from the machine metadata.

- `mix builtins --json` — the full table as a JSON array; each entry carries `metadata_schema` (1), `kind` (`builtin` or `statement` for print/eprint), `name`, `category`, `capability` (kebab class, or `statement`), `conditional_capabilities` (`[{option, capability}]`), `description`, `signature`, `arity` (`{min, max, exact}` — `max: null` = variadic; `exact` is normally `null`, but when a builtin's accepted argument counts are NOT a contiguous range it lists them exhaustively, e.g. `random` has `exact: [0, 2]` — an arity checker must use `exact` when present), `args` (`[{name, required, variadic, kind}]`), `returns`, `effects`, and `operational_failure`.
- `mix builtins --data` — the same logical array as strict-data Mix source (parse with `data_parse` / `load_data`); `null` becomes `nil`.
- Value shapes (`kind`/`returns`) are `{type: "any"|"nil"|"bool"|"number"|"string"|"bytes"|"buffer"|"function"}` scalars, `{type: "list", items: shape}`, `{type: "map", shape: name-or-null, fields: [...]}`, or `{any_of: [shapes...]}` unions.
- `effects` flags: `must_use` (discarding the result hides a failure — `run_rc`, `ssh_run`, `http_*`, ...), `blocking` (unbounded/external wait: process, network, stdin, sleep), `shell` (backed by `/bin/sh`), `mutates_args` (`push`, `buffer_push`, ...), `terminates` (`exit`, `panic`).
- `operational_failure`: how I/O-level failure is reported — `not-applicable` (pure), `raises` (catchable error), `returns-result` (encoded in the returned value, e.g. `ok:false` / `status:0` / exit code), `terminates`. Argument-validation errors always raise regardless.
- Arity in the contract is the documented surface; a few older builtins tolerate surplus arguments at runtime. `mix lint` checks calls against the contract, which is deliberately stricter.
- **Argument type gate and nil** (0.103.x): the evaluator checks argument types against the contract for the side-effect classes (fs/process/network/bus) in every mode, and for pure builtins under strict mode. A `nil` VALUE is checked like any other value — there is no blanket nil exemption, so `write_file(nil, "x")` and `mkdir(nil)` raise TYPE_MISMATCH instead of coercing nil into a literal `"nil"` path. An optional argument that intentionally treats an explicit `nil` as "omitted/default" declares it in the contract as `any_of(…, nil)` (e.g. `run_argv`/`exists`/`write_atomic`/`stat`/`walk` opts, `hash_file` algo, `bytes_to_string` opts, `normalize` form, `slice` end); that is the ONLY way a nil reaches the builtin. `any` args accept nil because they accept everything. A nil in a plain `string`/`number`/`map` slot raises in the same modes as any other wrong type.

> The tables below are generated: `docs/_build/gen-builtins-md.mix` writes
> one section per category, one row per entry of `mix builtins --json`, in
> the binary's order. `cargo test -p system --test man_pages` fails when the
> committed tables differ from the binary it built, so after adding or
> changing a builtin run
> `mix docs/_build/gen-builtins-md.mix --mix target/debug/mix`. Rows of kind
> `statement` (`print`, `eprint`, and the Bus forms `send`, `emit`, `on`,
> `reply`, ...) are keyword forms listed beside the builtins; see
> [bus](bus.md).

## string  — see [strings](strings.md)

  length          Length of a string (codepoints), list/map (elements), or bytes/buffer (bytes, v0.64.0)
  len             Alias for length()
  upper           Convert string to uppercase
  lower           Convert string to lowercase
  left            Return leftmost N characters
  right           Return rightmost N characters
  substr          Extract substring by codepoint position and length (splits emoji/combining; see grapheme_substr)
  pos             Find first position of needle in haystack (1-based, 0=not found — so `if pos(..)` reads correctly, since 0 is falsy). 0-based twin: index_of(), which takes its args the other way round and is NOT safe in a condition
  lastpos         Find last position of needle in haystack (1-based, 0=not found — safe in a condition, 0 is falsy). 0-based twin: last_index_of(), which takes its args the other way round
  strip           Remove leading/trailing whitespace, or codepoints in charset: strip(s[, charset]) (0.63.0 — the 2nd arg was silently IGNORED before)
  trim            Alias for strip(): trim(s[, charset]) — charset is a SET of codepoints to strip from both ends (0.63.0; was silently ignored). One-sided: ltrim/rtrim
  replace         Replace all occurrences of old with new in string
  replace_must    replace() that REFUSES a no-op: raises NEEDLE_ABSENT when old does not occur, and NEEDLE_COUNT when {count: n} is given and the occurrence count differs. Optional {path} names the file in the message. The form to use in a read_file -> edit -> write_file chain (0.90.0)
  split           Split string into list by delimiter (default: space)
  join            Join list into string with delimiter (default: space)
  starts_with     Test if string starts with prefix
  ends_with       Test if string ends with suffix
  contains        Test if string/list contains a value, or a bytes/buffer contains a byte needle (needle: bytes/buffer/string/byte number, non-empty; v0.70.0) — the correct yes/no test, and what to use instead of a bare index_of() in a condition
  repeat          Repeat string N times
  lpad            Left-pad string to width (codepoint count; see lpad_w for display cells). Optional 3rd arg is the fill character, default space: lpad(s, 12, "0") (v0.54.0)
  rpad            Right-pad string to width (codepoint count; see rpad_w for display cells). Optional 3rd arg is the fill character, default space (v0.54.0)
  lpad_w          Left-pad to width in terminal display CELLS (UAX #11; CJK/emoji=2) — aligns wide-char columns. Optional 3rd arg is the fill character (must be 1 cell wide), default space (v0.54.0)
  rpad_w          Right-pad to width in terminal display CELLS (UAX #11; CJK/emoji=2) — aligns wide-char columns. Optional 3rd arg is the fill character (must be 1 cell wide), default space (v0.54.0)
  reverse         Reverse a string (by codepoint; splits emoji — see grapheme_reverse), list, or bytes/buffer (byte-wise → a new value-semantic bytes, v0.70.0)
  words           Count whitespace-delimited words in string
  word            Extract Nth word from string (1-based)
  ord             Unicode codepoint of the FIRST character: ord("A") -> 65, ord("é") -> 233. Empty string raises. Inverse: chr()
  chr             The 1-character string for a Unicode codepoint: chr(65) -> "A", chr(10084) -> "❤". Surrogates (D800-DFFF) and >0x10FFFF raise, same rule as \u{...}. Inverse: ord()
  normalize       Unicode normalisation (UAX #15): normalize(s[, form]) with form "NFC" (default), "NFD", "NFKC" or "NFKD" (case-insensitive; nil selects NFC; anything else raises VALUE_ERROR). Makes canonically-equivalent text compare equal: a decomposed e + combining acute (macOS filenames, NFD) equals the precomposed é after normalize(); NFKC also folds compatibility forms (fullwidth letters, ligatures: normalize("fi", "NFKC") -> "fi"). Emoji and ZWJ sequences pass through unchanged (v0.92.0)
  mix_tokens      How Mix itself tokenises Mix source, for tools that read .mix files: mix_tokens(source[, {comments: bool}]) -> [{kind, text, line, col}] from the real lexer, in source order; nothing is run. kind: number, string (a quoted literal), word (a bare word), interp_string, heredoc, variable, command_sub, keyword, operator, punct, newline, and comment (only with comments:true; # and -- comments). text is the exact source span (a heredoc includes its body and terminator); line and col are 1-based, col in characters. Newlines inside (), [] and {} are not tokens. Source that does not lex raises MIX_SOURCE_LEX with details {line, col} (v0.117.0)
  before          Text before the FIRST delim: before(s, delim) -> string | nil (nil when delim absent; "" is a real result — delim at the start). Empty delim raises
  after           Text after the FIRST delim: after(s, delim) -> string | nil (nil when delim absent; "" when delim at the end). Empty delim raises. Want a default? `after($s, "=") or ""`
  before_last     Text before the LAST delim -> string | nil (nil when absent). Empty delim raises
  after_last      Text after the LAST delim -> string | nil (nil when absent) — basename/extension: after_last(path, "/"), after_last(name, "."). Empty delim raises
  split_once      Split at the FIRST delim: split_once(s, delim) -> [head, tail] | nil (nil when absent — never a 1-element list). Empty delim raises
  rsplit_once     Split at the LAST delim -> [head, tail] | nil (nil when absent). Empty delim raises
  between         Text after the first a and before the NEXT b: between(s, a, b) -> string | nil (nil if either marker absent, in that order). Empty a or b raises
  strip_prefix    s without a leading p, else s UNCHANGED (never nil — "nothing to strip" is an answer). Empty p -> unchanged. Kills the starts_with+substr idiom
  strip_suffix    s without a trailing x, else s UNCHANGED (never nil). Empty x -> unchanged
  replace_first   Replace the FIRST occurrence of old; old absent -> s unchanged. Empty old mirrors replace(): inserts new at the start (replace_first("ab", "", "X") is "Xab")
  count_of        Non-overlapping occurrences of needle in s; 0 for an empty needle. (The HOF count(list, pred) is a different builtin)
  ltrim           Strip leading whitespace, or leading codepoints in charset: ltrim(s[, charset]) — PHP-style charset is a SET of codepoints, not a prefix string
  rtrim           Strip trailing whitespace, or trailing codepoints in charset: rtrim(s[, charset])
  lines           Split into lines: \n-separated, ONE trailing \r stripped per line (CRLF and LF both work; a lone \r is not a terminator), exactly one trailing empty element dropped (the final newline). lines("") -> []; "a\n\n" -> ["a", ""]. Native since 0.63.0 (was a prelude fn that kept \r and the trailing "")
  fields          awk-style fields: split on whitespace RUNS, no empties; fields("") -> []. 0-based access fields(s)[2]; the 1-based single-field form is word(s, n)
  chars           Codepoints as 1-char strings (grapheme_* builtins exist for clusters). Native since 0.63.0 (was a prelude fn)
  last_index_of   0-based codepoint index of the LAST occurrence in a string, or last index of a value in a list; -1 if absent. The 0-based twin of lastpos() (args reversed). List search compares with == — SCALAR elements only, exactly like index_of (a map/list element never matches; deep_eq is the structural comparison). ⚠ Like index_of, NEVER bare in a condition: -1 is truthy, 0 is falsy
  template        Substitute single-brace {key} placeholders in a string from a map
  word_wrap       Wrap text to a column width (codepoint budget; see word_wrap_w for display cells)
  word_wrap_w     Wrap text to a column width in terminal display CELLS (UAX #11; CJK/emoji=2)
  markdown_escape Escape markdown metacharacters in a string
  markdown        Render CommonMark + GFM markdown (tables, strikethrough, task lists, footnotes) to HTML; raw HTML is escaped and unsafe URL schemes neutralised (requires markdown feature)
  html_escape     Escape & < > " ' for HTML element text + quoted attribute values (not JS/CSS/URL/srcdoc contexts)
  sanitize        Make untrusted bytes safe for one-line diagnostics: collapse line breaks (incl. U+2028/9) to spaces, replace C0/C1 controls and Trojan-Source bidi/zero-width chars with '?'
  re_match        Subject-first regex test: re_match(s, pattern) -> bool, true if pattern matches anywhere in s
  re_find         All matches as {match, start, end[, groups]} maps with CODEPOINT offsets (compose with substr/slice/index_of; the deleted legacy regex_find answered in UTF-8 BYTE offsets). [] when none
  re_replace      Replace ALL matches: re_replace(s, pattern, replacement) — subject FIRST; $1/${name} backrefs in replacement
  re_replace_must re_replace() that REFUSES a no-op: raises NEEDLE_ABSENT when the pattern does not match, and NEEDLE_COUNT when {count: n} is given and the match count differs. Optional {path} names the file in the message (0.90.0)
  re_split        Split s on each match of pattern (subject first)
  grep_lines      Lines of text matching pattern (subject first; regex when enabled, else substring) — the line filter (its pattern-first predecessor grep() was deleted in release B)
  csv_parse       Parse CSV string into a list of header-keyed row maps. delim is exactly ONE ASCII byte (default ","; empty/multi-byte/non-string/nil and NUL/CR/LF/quote raise TYPE_MISMATCH — never a silent default or truncation)
  ini_parse       Parse INI string into nested map of sections
  xml_parse       Parse a strict-XML string (or bytes, e.g. an HTTP body) into a Value tree (requires xml feature). Default simple mode is the SOAP/RSS consumer shape: {RootName: …} with namespace prefixes stripped, attributes as @name keys, repeated sibling elements collapsed to a list, a leaf element's text as its value, mixed text under #text, xmlns declarations dropped. Pass {mode:"tree"} for full fidelity: nodes are {name, attrs, children} with prefixes + xmlns preserved and text children as plain strings. Strict XML only — real-world HTML is tag soup and will NOT parse.
  url_parse       Parse URL into {scheme, host, port, path, query, fragment}
  url_decode      Percent-decode a URL/form-encoded string ('+' → space)
  url_encode      Percent-encode a string for use in a URL/form body
  rfc2047_decode  Decode RFC 2047 encoded-words in a mail header value (=?charset?B/Q?data?=) to a plain string. Honours the charset token (utf-8/us-ascii/iso-8859-1; anything else falls back to UTF-8-lossy), joins adjacent encoded-words at the BYTE level per §6.2 so a character split across two words survives, and passes malformed words through literally rather than losing the header. Accepts string/bytes/buffer (v0.67.0)
  rfc2047_encode  Encode a header value as RFC 2047 encoded-words in UTF-8, or return it UNCHANGED when it is already plain ASCII with no "=?" (§5: encode only when needed). Optional {encoding: "B"|"Q"}, default B. Words are kept within the §2 75-character limit and split on CHARACTER boundaries so each stays independently decodable (v0.67.0)
  parse_query     Parse a k=v&k2=v2 query/form string into a map (url-decoded, last-wins)
  parse_form      Parse an x-www-form-urlencoded body into a map (alias of parse_query)
  byte_length     Length of a string in raw UTF-8 bytes (the pre-0.8.0 length() value for strings)
  byte_pos        Byte offset of needle in haystack (1-based, 0=not found) — byte twin of pos(), 0-based twin byte_index_of(). Safe in a condition (0 is falsy)
  byte_lastpos    Last byte offset of needle in haystack (1-based, 0=not found) — byte twin of lastpos()
  byte_index_of   Byte offset of needle in string (0-based, -1=not found) — byte twin of string index_of(), 1-based twin byte_pos(). ⚠ NEVER use bare in a condition: -1 is truthy, 0 is falsy (MIX-W2305)
  grapheme_count  Count grapheme clusters (user-perceived chars: emoji/flags/combining count as 1)
  grapheme_substr Substring by grapheme cluster position and length (won't split emoji/combining marks)
  grapheme_reverse Reverse a string by grapheme cluster (emoji/combining-safe, unlike reverse())
  display_width   Terminal display width in cells (UAX #11; CJK/emoji=2, combining=0, East-Asian-ambiguous=1)

## type  — see [numbers](numbers.md)

  deep_eq         Structural equality for any two values: maps compare by key set + deep_eq values (insertion order IGNORED), lists elementwise in order, scalars as ==. The answer `==` cannot give for maps/lists — since v0.68.0 `==`/`!=` RAISES when both sides are a map or list, and names this builtin. Caveats, inherited from ==: a FUNCTION value is never equal (even to itself — a callback-bearing map is not deep_eq its own copy) and Buffer-vs-Bytes is false (freeze() first). Raises past 512 nesting levels
  type            Return type name: string, number, bool, list, map, nil
  to_number       Convert value to number (nil if not numeric)
  to_string       Convert value to its string representation
  is_number       Test if value is numeric or a numeric string
  is_empty        Test if string/list/map is empty, or value is nil ("0" is NOT empty)
  has_builtin     Does THIS mix have the named builtin? has_builtin(name) -> bool. `mix builtins NAME` exits 0 for any name and cannot answer this; use for feature gates and compat shims: `if not has_builtin("ws_connect") then die "needs mix >= 0.74" end`. A feature-gated name absent from this build still reads true (the binary knows it, and calling raises 'requires the X feature') (v0.78.0)
  mix_version     The language runtime version as structured data: {major, minor, patch, string} — so a version gate never parses --version text (v0.78.0)

## math  — see [math](math.md)

  round           Round to nearest integer, half away from zero; round(x, n) to n decimal places (n<0 rounds to tens/hundreds) (v0.19.0)
  floor           Round down toward -inf; floor(x, n) to n decimal places (v0.19.0)
  ceil            Round up toward +inf; ceil(x, n) to n decimal places (v0.19.0)
  trunc           Truncate toward zero (drop the fraction); trunc(x, n) to n decimal places (v0.19.0)
  abs             Absolute value (v0.19.0)
  sign            Sign of x: -1, 0, or 1 (±0→0, NaN→NaN) (v0.19.0)
  band            Bitwise AND of two integers. Both arguments must be exact integers within ±2^53 (the range f64 represents without loss); a fraction, an infinity, a NaN or an out-of-range magnitude raises rather than silently truncating. Chiefly for permission bits: band(stat(p)["perm"], 0o111) != 0 asks whether any execute bit is set (v0.46.0)
  bor             Bitwise OR of two integers; same exact-integer domain as band (v0.46.0)
  bxor            Bitwise exclusive-OR of two integers; same exact-integer domain as band (v0.46.0)
  bnot            Bitwise NOT (one's complement) over 64-bit two's complement: bnot(0) is -1. Same exact-integer domain as band (v0.46.0)
  bshl            Shift left by n bits (n in 0..63). Raises rather than wrapping if the result leaves the exact-integer range (v0.46.0)
  bshr            Arithmetic shift right by n bits (n in 0..63); the sign bit is replicated, so bshr(-8, 1) is -4 (v0.46.0)
  sqrt            Square root (negative→NaN) (v0.19.0)
  cbrt            Cube root (defined for negatives) (v0.19.0)
  pow             Raise to a power: pow(base, exp) = base^exp (v0.19.0)
  exp             e raised to the x (v0.19.0)
  ln              Natural logarithm, base e (ln(0)→-inf, ln(neg)→NaN) (v0.19.0)
  log10           Base-10 logarithm (v0.19.0)
  log2            Base-2 logarithm (v0.19.0)
  log             Logarithm in an arbitrary base: log(x, base) (v0.19.0)
  min             Smallest of the number arguments, or of a single list argument: min(a, b, …) | min(list). Lexicographic when all args are strings; NaN-skipping (v0.19.0)
  max             Largest of the number arguments, or of a single list argument: max(a, b, …) | max(list). Lexicographic when all args are strings; NaN-skipping (v0.19.0)
  clamp           Constrain a number to a range: clamp(x, lo, hi) (errors if lo > hi) (v0.19.0)
  hypot           Euclidean distance sqrt(x²+y²) computed without intermediate overflow: hypot(x, y) (v0.19.0)
  sin             Sine of x in radians (v0.19.0)
  cos             Cosine of x in radians (v0.19.0)
  tan             Tangent of x in radians (v0.19.0)
  asin            Arcsine in radians (domain [-1, 1], else NaN) (v0.19.0)
  acos            Arccosine in radians (domain [-1, 1], else NaN) (v0.19.0)
  atan            Arctangent in radians (v0.19.0)
  atan2           Angle in radians of the point (x, y): atan2(y, x) (v0.19.0)
  pi              The constant π (v0.19.0)
  e               Euler's number e (v0.19.0)
  random          random() -> float in [0,1); random(min, max) -> integer in [min, max] inclusive (v0.23.0)

## list  — see [collections](collections.md)

  push            Append value to end of list (mutates)
  pop             Remove and return last element of list (mutates)
  shift           Remove and return first element of list (mutates)
  sort            Return sorted copy of list (all-number lists sort numerically; else lexicographic)
  index_of        Find 0-based index of value in a list, of a needle substring in a string (codepoint-based), or of a byte needle in a bytes/buffer (byte offset; needle: bytes/buffer/string/byte number, non-empty; v0.70.0); -1 if absent. 1-based twin: pos() (args reversed). ⚠ NEVER use bare in a condition — -1 (absent) is TRUTHY and 0 (first position) is FALSY, so both answers invert; use contains() for yes/no or compare >= 0 (MIX-W2305)
  unique          Return list with duplicates removed
  range           Generate list of numbers from start to end with optional step. Bounds/step must be whole numbers within i64 — fractional or oversized values raise VALUE_OUT_OF_RANGE instead of silently saturating (strict since v0.59.0)
  flat            Flatten nested lists into a single list
  concat          Concatenate 2+ lists into one new list (one level; each arg must be a list)
  slice           Sub-sequence [start, end): negative indices and out-of-range clamp, a reversed range is empty (v0.2.0). Slices a list (elements), string (codepoints), or bytes/buffer (bytes → a new value-semantic bytes, v0.64.0)
  take            First N items of a list (negative N = last N) (v0.2.0); also string (codepoints) and bytes/buffer (bytes → a new value-semantic bytes, v0.70.0)
  drop            Skip first N items of a list (negative N = drop last N) (v0.2.0); also string (codepoints) and bytes/buffer (bytes → a new value-semantic bytes, v0.70.0)
  zip             Pair two lists element-wise into [a, b] tuples (v0.2.0)

## map  — see [collections](collections.md)

  keys            Return list of map keys
  values          Return list of map values
  has_key         Test if map contains a key
  merge           Merge two maps (second wins on conflicts)
  delete          Return map with key removed

## buffer  — see [buffer](buffer.md)

  buffer          Create a reference-semantic MUTABLE byte buffer (the escape hatch from value semantics for large binary/audio/video). buffer() or buffer(nil) empty; buffer(n) n zero bytes; buffer(string) UTF-8; buffer(bytes|buffer) independent copy; buffer([items]) flat splice of int 0-255 / string / bytes / buffer. Append with buffer_push (O(1) amortized, aliases share); freeze() to a value-semantic bytes (v0.26.0)
  buffer_push     Append bytes to a buffer IN PLACE (reference-semantic: every alias sees the growth). Each item is an int 0-255, string (UTF-8), bytes, or buffer. Self-append-safe (v0.26.0)
  buffer_get      Byte at 0-based index i as a number 0-255, or nil if out of range (v0.26.0)
  buffer_set      Write byte (0-255) at 0-based index i, in place; errors if i is out of range — grow with buffer_push first (v0.26.0)
  freeze          Snapshot a buffer to a value-semantic bytes (a copy of the current content) — the bridge into write_file/hash/base64/http (v0.26.0)

## io  — see [io](io.md)

  read_file       Read entire file contents as string
  fs_watch        Register Linux inotify watch; returns evaluator-owned opaque handle. Delivers fs.changed via $event.args; bounded, overflow requires rescan; no polling fallback
  fs_unwatch      Cancel watch and pending changes; wake fs_wait with FS_WATCH_CANCELLED
  fs_wait         Suspend until a filesystem batch; cancellation-safe; refused in serve and expression modes
  dir_open        Open a retained native directory root; evaluator-owned numeric handle. Refuses symlink components. Linux openat2 required; no fallback (v0.108.0)
  dir_rename      Move a regular file or directory between relative paths beneath a retained root, atomically refusing overwrite. Landlock ABI 2 and erratum 3 required. Refuses symlink sources and escaping parents. Root pathname checked before operation; retained inode remains the containment boundary during concurrent root moves (v0.108.0)
  dir_close       Close an evaluator-owned retained directory root; invalid or closed handles raise (v0.108.0)
  read_file_bytes Read file contents as raw bytes. Optional 2nd arg caps the read: read_file_bytes(path, 8192) reads at most 8192 bytes (header-sniffing without slurping a huge file) (v0.3.1; cap v0.17.1)
  read_lines      Read file as a list of lines (trailing newline stripped, empty last line dropped) (v0.2.3)
  load_data       Read + parse a strict-data .mix file (bare-key `k: v`, the zones.mix/conf.mix form) into a Value — the non-executing twin of source/include, for substrate-internal data that must NOT run as code (v0.9.0)
  write_file      Write a string, bytes or buffer to file (creates/overwrites); bytes/buffer are written verbatim, a string as UTF-8. Nothing else is coerced — nil/map/list/function/number/bool raise TYPE_MISMATCH before the file is opened (encode with json_encode/data_encode/to_string first)
  write_new       Atomically create a new file with mode. write_new(path, content, 0o600) — mode as a value (octal literal) or octal string "0600"; fails if path exists; mode applied at creation (no umask race). content is a string, bytes or buffer (nothing else is coerced — wrong types raise TYPE_MISMATCH before the O_EXCL open)
  write_atomic    Replace or create a file so every reader and every crash sees the old complete file or the new complete file, never a partial one: write_atomic(path, data[, {durability, mode, max_bytes}]). data is a string, bytes or buffer (nothing else is coerced). A temp is claimed O_EXCL beside the target (same filesystem), written, optionally synced, and renamed over the target; any failure before the rename removes the temp and leaves the target untouched. durability "none" (default: atomic, NOT durable across power loss) | "file" (fsync the file before the rename) | "full" (also fsync the directory after it). An existing target keeps its mode and owner (raises rather than silently change the owner); a new file gets 0o666 & ~umask; mode sets it exactly. A symlink path replaces the file it names and keeps the link. max_bytes raises WRITE_TOO_LARGE before touching disk. A killed process can leave a hidden .NAME.mixtmp-* temp beside the target, never a partial target
  append_file     Append a string, bytes or buffer to file (created if missing); bytes/buffer append verbatim, a string as UTF-8. Nothing else is coerced — nil/map/list/function/number/bool raise TYPE_MISMATCH before the file is opened
  exists          Test if path exists. FOLLOWS symlinks by default, so a dangling link reads as absent — that is the right answer for "can I open something here" and the wrong one for "is this name taken". exists(path, {follow_symlinks: false}) is the lstat form and sees the link itself (v0.39.0). opts may be nil, like being omitted.
  access          Ask the kernel whether this process can access path using its effective uid/gid: mode is a non-empty, duplicate-free string of r/w/x/f letters (f = existence and is redundant when combined). Follows symlinks. Unlike inspecting stat().perm, this honours POSIX ACLs. Ordinary absence/denial returns false; malformed input or an unexpected syscall failure raises (v0.45.0).
  is_dir          Test if path is a directory
  is_file         Test if path is a regular file
  realpath        Canonicalise a path: resolve every symlink + `.`/`..` to the absolute real path (like `readlink -f` / realpath(3)). The path MUST exist. realpath(path) -> string | nil (nil ONLY when a component is missing; a permission/IO/symlink-loop/non-UTF-8 failure RAISES — v0.103.14). NORMALISATION ONLY, not a race-free authorization primitive: canonicalise-then-use is not atomic, so for an exec/open safety check, exec/open the RETURNED canonical path (which has no symlinks to re-traverse), not the original (v0.31.2)
  glob            List files matching a glob pattern (supports ** globstar in v0.2.1)
  ls              List directory entries
  mkdir           Create directory: mkdir(path[, {parents}]). parents defaults to true (create_dir_all). {parents: false} creates only the final component and fails if the parent is missing — the form to use when the parent was placed deliberately and re-creating it would hide its removal (v0.42.0)
  flock           Take a process-held advisory file lock: flock(path[, {shared, wait, create}]) -> bool. Exclusive and non-blocking by default; contention returns false, genuine filesystem errors raise. wait is seconds (0 = do not wait). A shared lock opens an existing file read-only, so it needs no write access; an exclusive one opens read-write. A missing file is created (0644) unless create:false, which raises LOCK_FILE_MISSING (v0.117.0). Repeated acquisition of the same canonical path by this process is idempotent-true (v0.43.0)
  funlock         Release and close this process's advisory lock for path. Returns true when held, false when not held (v0.43.0)
  fcntl_lock      Take a POSIX record lock over the whole file: fcntl_lock(path[, {shared, wait, create}]) -> bool — the fcntl(2) lock namespace C daemons use for pidfiles/lockfiles, which flock(2) locks never see (Linux keeps the two families separate). Contract-identical to flock: exclusive + non-blocking default, contention false, real errors raise, shared opens an existing file read-only, create:false refuses a missing one, per-process idempotent-true by canonical path. Implemented as open-file-description locks (F_OFD_SETLK): they conflict with other processes' traditional fcntl records, and survive this process opening/closing the same path elsewhere — a read_file of the locked path cannot drop them (v0.71.0)
  fcntl_unlock    Release and close this process's POSIX record lock for path. true when held, false when not (v0.71.0)
  copy            Copy a single file: copy(src, dst). Overwrites dst; preserves the source permission bits. Use copy_tree for a directory (v0.22.0).
  copy_tree       Recursively copy a directory: copy_tree(src, dst). Creates dst, copies files (perms preserved) and symlinks (as symlinks); merges into an existing dst (v0.22.0).
  symlink         Create a symbolic link: symlink(target, linkpath) — symlink(2), arguments in symlink(2) order (target first, the link to create second). `target` is stored verbatim and is NOT resolved or validated: a relative target resolves against the link's own directory, and creating a dangling link is legal. Raises EEXIST if linkpath already exists. Read the other way with read_link() (v0.38.0).
  read_link       Read a symbolic link's target: read_link(path) -> string — readlink(2), returning the target EXACTLY as stored (possibly relative, possibly dangling), which is what distinguishes it from realpath()'s full resolution. Raises EINVAL when path is not a symlink; test first with stat(path, {follow_symlinks: false}).is_symlink (v0.38.0).
  rename          Rename/move a path within one filesystem: rename(src, dst) — rename(2), so replacing an existing dst is ATOMIC (a concurrent reader sees either the old file or the new one, never a partial write). This is the primitive for a safe in-place update: write a temp file beside the target, then rename over it. Raises EXDEV across filesystems (copy + remove instead) and ENOENT when src is missing (v0.37.0).
  remove          Remove a single file/symlink: remove(path). No-op if already gone (rm -f). Errors if path is a directory — use remove_dir (v0.22.0).
  remove_dir      Recursively remove a directory and its contents: remove_dir(path) (rm -rf). No-op if already gone (v0.22.0).
  chmod           Set file/directory permissions. chmod(path, 0o755) — mode as a VALUE (use an octal literal) or an octal string "0755" (v0.11.0: a number is now the value, not its decimal digits read as octal)
  fsync           Make a file, a directory or a whole tree durable: fsync(path[, {recursive}]) -> number of inodes synced. A file is fsync(2)ed; a directory is opened and fsynced, which persists the entries created, renamed or removed in it; recursive:true syncs every regular file and directory beneath (children first, symlinks never followed, their entries persisted by their directory), then the directory itself. The path itself follows a symlink. Failures raise FSYNC_FAILED with details.path naming what could not be synced (v0.117.0)
  chown           Set file owner/group by numeric uid/gid: chown(path, 1000, 1000). Follows symlinks by default; chown(path, uid, gid, {follow_symlinks:false}) changes a symlink itself (lchown, v0.117.0). Numeric only (no name resolution) (v0.17.1)
  mime_type       The type of a file from the freedesktop shared-mime-info database, as the desktop names it (requires mime feature): mime_type(path[, {content}]) -> {mime, by, uncertain, exists, parents}. Globs first, magic to settle a missing or ambiguous glob, then a text check (the GLib order). by is stat|glob|magic|content|fallback; parents lists every supertype nearest first, ending text/plain (for text/*) and application/octet-stream. {content:false} never opens the file. A missing path is typed by name with exists:false; an unreadable file by name, uncertain. Follows symlinks (v0.113.0)
  stat            Stat a path → map {uid, gid, nlink, size, mode, perm, ino, dev, ctime, mtime, atime, ctime_nsec, mtime_nsec, atime_nsec, is_file, is_dir, is_symlink}. ino/dev are STRINGS (u64, exceed f64 exact range); mode is full st_mode, perm = mode & 0o7777; *time are epoch seconds (f64) and *_nsec the sub-second part 0..=999999999 (v0.44.0) — compare the PAIR to see a same-second rewrite. Follows symlinks by default; stat(path, {follow_symlinks:false}) is lstat (v0.17.1)
  line_count      Count lines in a file by streaming — never loads the whole file (byte-oriented, so it works on non-UTF-8 files too) (streams since v0.28.1)
  head            First N lines of a file as a list (default 10) — streams and stops after N lines, never reads the rest (the no-slurp twin of take(read_lines(p), n)) (v0.28.1)
  tail            Last N lines of a file as a list (default 10) — reads backwards in blocks from EOF, never slurps the whole file (the no-slurp twin of take(read_lines(p), -n)) (v0.28.1)
  basename        Return the filename component of a path
  dirname         Return the directory component of a path
  extname         Return the file extension (including the leading dot)
  path_join       Join path components with the native separator
  path_parts      Decompose a path into {dir, base, stem, ext} (v0.2.1)
  walk            Recursive directory walk: walk(dir, {max_depth, follow_symlinks, include_dirs, strict}); invalid max_depth raises instead of becoming unlimited (strict since v0.55.0). Unreadable directories and unstat-able entries are skipped unless strict: true, which raises WALK_UNREADABLE (details.path names the first one) so a gate can tell no matches from could not look
  readline        Read a line from stdin (optional prompt argument)
  read_stdin      Read all of stdin to EOF as a string (for pipe/hook input). STRICT UTF-8 — binary stdin raises; use read_stdin_bytes for that
  read_stdin_bytes Read all of stdin to EOF as raw bytes — the binary twin of read_stdin, which refuses invalid UTF-8. Optional arg caps the read: read_stdin_bytes(8192) reads at most 8192 bytes, the same cap contract as read_file_bytes (v0.65.0)
  tty_mode        Put the controlling terminal into raw or cooked mode: tty_mode("raw") disables canonical buffering, echo and signal generation (a lone ESC arrives as one byte — the keystroke-recorder primitive), tty_mode("cooked") restores the saved termios. The original termios is restored on process exit if the caller never returns to cooked (v0.103.9)
  stdin_copy      Copy stdin to a file, flushing every chunk, until EOF — the incremental twin of read_stdin_bytes, so a recorder killed mid-stream keeps the bytes it already read. Pair with tty_mode("raw") to capture keystrokes (v0.103.9)
  sqlopen         Open a SQLite database and return a handle: sqlopen(path[, mode]). mode "ro" (default) is read-only and the file must exist (SQL_NO_DATABASE otherwise); "rw" or "rwc" opens read-write and creates a missing file, in WAL mode with a 5 s busy timeout. ":memory:" is a private in-memory database. Any other mode raises. See mix man sqlopen
  tar_list        List a tar archive (zstd default, gzip or none codec) WITHOUT extracting: streaming entries {name,size,mode,uid,gid,kind,mtime}; the compressed stream is drained to EOF so the frame checksum is verified
  tar_unpack      Safely unpack a tar archive into dest (which must not exist, in a parent no other user can write unless sticky): every member is validated (no absolute/.. paths, a leading ./ accepted, no device/fifo, symlink targets contained relative to the link's own directory and never through another symlink, no extraction through a created symlink, hardlinks only to earlier files), entries land in a private staging dir held by descriptor and renamed into place (never replacing dest) only after the stream verifies to EOF — non-zero data after the tar end is refused (one tar; one zstd frame, gzip members concatenate); PAX global headers count as metadata. opts: codec (zstd default), numeric_owner (default true for root only), xattrs (default true: user.* only), keep_special_bits (default false strips suid/sgid and security.capability), privileged_xattrs (default false: trusted.*, ACLs, other security.*), max_entries, max_bytes, max_name, max_stream_bytes (bounds the decoded stream, longname/PAX buffers included), max_xattr_bytes (16 MiB). Unapplied owners are listed in the receipt's warnings, and their special bits dropped
  tar_pack        Pack a source DIRECTORY into a new archive at path (deterministic sorted walk, numeric owner/mtime/mode, security.capability captured as a SCHILY.xattr PAX record with keep_special_bits; refuses device/fifo members, an output inside the source, and a file that changes size while packed). opts: codec (zstd default), level (zstd 1..=22 default 7, gzip clamps to 9), keep_special_bits (default false strips suid/sgid)
  sqlexec         Execute SQL on a SQLite handle, return result rows
  sqlclose        Close a SQLite database handle
  write_stdout    Write values to fd 1 AS THEY ARE — no trailing newline, no separator, flushed. bytes/buffer go out verbatim; every other value renders exactly as print() renders it. Never re-opens a path, so it works when fd 1 belongs to another user (the sieve-filter case). A failed write RAISES (catchable): IO_BROKEN_PIPE when the consumer went away, else IO_WRITE_FAILED — print raises the same way since 0.99.0 (B9)
  write_stderr    Write values to fd 2 as they are — the stderr twin of write_stdout, same contract (v0.65.0)
  print_raw       ALIAS of write_stdout — identical contract, the spelling for `print` without the trailing newline (v0.65.0)
  eprint_raw      ALIAS of write_stderr — identical contract, the spelling for `eprint` without the trailing newline (v0.65.0)
  print           Print values to stdout with newline (statement, not a builtin call); bare `print` emits a blank line
  eprint          Print values to stderr with newline (statement, not a builtin call); bare `eprint` emits a blank line

## system  — see [system](system.md)

  env             Get environment variable value ("" if unset); env(name, default) returns default when unset or empty
  time            Return current Unix timestamp as float
  monotonic       Return CLOCK_MONOTONIC seconds as a float — the kernel monotonic clock (the one compositor FRAME_TRACE start_us/end_us stamp), never stepped by NTP or wall-clock adjustment, so it never goes backwards and differences are true elapsed intervals. The epoch is unspecified (on Linux it counts from boot); use time() for calendar timestamps, this for measuring and for correlating with compositor traces
  pid             Return current process ID
  uid             Effective user id of this process (geteuid) — normally the id a file access is checked against (Linux checks fsuid, which tracks euid unless setfsuid(2) is called; no Mix script can call it, though an embedder can), so it is the one to compare a stat() map's `uid` against when deciding whether a path is yours (v0.41.0)
  gid             Effective group id of this process (getegid) — the companion to uid(), for comparing against a stat() map's `gid`; same fsgid caveat, and it answers only whether a file's group is the EFFECTIVE one, so use groups() to decide which permission class applies (v0.41.0)
  groups          Every group id this process is in — the getgroups(2) supplementary set plus the effective gid, sorted. This is what decides whether the kernel applies a file's GROUP or OTHER permission bits: gid() alone cannot answer it for a file grouped under one of your other groups (v0.42.0)
  args            Return list of script arguments
  getopt          Parse args against a spec map: getopt(args(), {all:{short:"a"}, out:{short:"o", arg:true}}) -> {opts, rest, errors}. opts has every declared option (flag->bool, value->string|nil); rest=positionals (incl. post `--`); errors=collected unknown-option/missing-value strings ([]=clean). Forms: --long, -s, --k=v, --k v, -s v, -- terminator. Minimal: no bundling/abbrev (v0.12.0)
  exit            Exit with optional status code
  sleep           Sleep for N seconds (async)
  task_start      Start an in-process handler task; command must have an async handler. No Bus traffic. Requires the runner's LocalSet; drained on shutdown
  run             Run shell command via sh, return trimmed stdout as string. run(cmd, [{timeout: seconds}]) — 0 (default) = no deadline; a timed-out child is PG-killed and run dies (catchable)
  run_rc          Run shell command, return {rc, stdout, stderr, timed_out, interrupted} map. run_rc(cmd, [{timeout: seconds}]) — 0 (default) = no deadline; timeout → rc=-1 timed_out=true
  run_stream      Run an argv LIST directly (no sh), inheriting stdio so output streams live and the child can use the terminal (interactive when it has a pty, e.g. ssh -t); returns the exit code. run_stream(argv, [{env, clear_env, cwd}]) — same env/cwd semantics as run_argv, so an interactive child gets variables without an `env` prefix exposing them in its ps argv (v0.51.0). The run_argv-only opts (timeout, stdin, stdout, stderr, max_output, stream) are rejected by name: this runner blocks until the child exits and captures nothing
  run_argv        Run an argv list directly (no shell) with structured stdio routing and a whole-call deadline that starts before route opening. opts: timeout; grace (seconds: at the deadline SIGTERM the process group, wait up to grace for it, then SIGKILL — default 0 = SIGKILL at once; refused with timeout:0); stdin nil|string|bytes|buffer|{file}|{null:true}|{inherit:true} (only when mix's own stdin is not a terminal, else STDIN_TERMINAL — use run_stream); stdout capture|inherit|null|{file,append?,mode?}; stderr capture|inherit|null|stdout|{file,append?,mode?}; cwd/env/clear_env; max_output; stream. stdout/stderr default capture; output files default truncate, mode 0o600. Routed non-capture streams return "" with truncation false and are not capped. stderr:stdout merges into stdout. File-open failure or route-open deadline is a PROCESS_STDIO value and the child is not spawned. Captured output abandoned at a deadline is returned partially with its truncation flag true. stream:true + stdout:inherit and all bad options raise OPTION_INVALID before spawn. opts may be nil (defaults). Ordinary command/setup failure is encoded in the VALUE; timeout default 30s; max_output default 8 MiB per captured stream
  run_parallel    Run many argv jobs concurrently with a bounded worker pool: run_parallel(jobs[, {max, timeout}]) -> list of process_result maps in INPUT order. Each job is an argv list (like run_argv's first arg) OR a {argv, stdin, cwd, env, clear_env, stdout, stderr, max_output, timeout, grace} map mirroring run_argv's options. max bounds concurrency (default 8, hard-capped at 256 live workers — excess jobs still run, drained by index); a top-level timeout (seconds) overrides every job's own. A job may NOT disable its deadline (timeout: 0 is refused) — one hung job would park the whole batch. Each result is EXACTLY run_argv's process_result map, so existing result-handling code ports unchanged; one job's ordinary failure (nonzero/timeout/spawn) is DATA in its map, never a raise. Process-level fan-out (std::thread over the run_argv engine), NOT in-language concurrency — the evaluator is single-threaded and Values never cross a thread; a job's `stream` flag is ignored (parallel tee would interleave). The killer use is ssh_mix fan-out: run_parallel of ssh argvs. A parse error in ANY job fails the whole call before spawning (v0.82.0)
  run_argv_must   Fail-fast run_argv with the same structured stdio opts: returns captured stdout unchanged when ok and no captured stream truncated ("" when stdout is routed), else raises PROCESS_EXIT_NONZERO / PROCESS_TIMEOUT / PROCESS_SIGNAL / PROCESS_INTERRUPTED / PROCESS_OUTPUT_LIMIT or the result's setup/lifecycle error_code (PROCESS_STDIO / PROCESS_SPAWN / PROCESS_IO / PROCESS_INTERNAL) with the complete result map in $err.details.result
  run_pipeline    Run one or more argv stages without a shell, connecting each stdout to the next stdin. Stage maps accept argv/cwd/env/clear_env/stderr, plus stdin on the first stage and stdout on the last, using run_argv's stdio grammar. Every route and pipe is prepared before any stage runs, so PIPELINE_STDIO means no stage ran. Returns a distinct pipeline_result with final stdout/exit fields and per-stage outcomes. One whole-call deadline starts before route opening; captured output abandoned at that deadline is partial with its truncation flag true. Non-final SIGPIPE is NOT accepted by default: any stage killed by a signal makes the pipeline not-ok, matching `set -o pipefail`. Pass allow_signal:true to accept a non-final SIGPIPE when every downstream stage succeeded (the `yes | head -1` idiom). Every stage carries status ok|exit_nonzero|signal|broken_pipe|timeout|interrupted|setup_error and broken_pipe (killed by SIGPIPE: its reader closed); the result carries status ok|exit_nonzero|signal|broken_pipe|timeout|interrupted|setup_error, failed_stage (the RIGHTMOST non-ok stage, pipefail's rule; nil when none) and a one-line human summary — gates branch on status, never on text. Ordinary failure is encoded in the VALUE — never raises
  run_pipeline_must Fail-fast run_pipeline twin: returns final stdout unchanged when the pipeline is ok and no captured output truncated; otherwise raises PIPELINE_* with the complete pipeline_result in $err.details.result
  spawn           Start a child and return its PID. String form uses a shell and optional stdout/stderr paths. Argv form runs directly with options: detach, die_with_parent, exit_event, tag, cwd, env, clear_env, stdout, stderr. exit_event:true (Linux pidfd) registers the sole reaper in this evaluator and emits proc.exited {pid,tag,exit_code,signal}; tag is a string up to 4096 bytes, default empty. Cannot detach a managed child. Managed children are killed and reaped when their evaluator retires, after handler drain; failed reload leaves old managed children intact. die_with_parent additionally arms kernel parent-death SIGKILL. Without exit_event, existing detached/owned/plain spawn semantics apply. Stdio defaults null, capture is refused; cwd/env/clear_env match run_argv. See system manual for lifetime rules
  kill            Send signal to process (default SIGTERM); returns false when the signal could not be delivered. Both arguments must be whole NUMBERS and neither is coerced — a bool/string pid raises TYPE_MISMATCH rather than becoming 0 (which signals this process's whole group), and an unrecognised signal raises rather than silently defaulting to SIGTERM (strict since v0.52.0)
  shell_quote     Single-quote-wrap a string for safe interpolation into a POSIX shell command
  sql_quote       Escape a string for SQL string literals: doubles ' and escapes \ (MySQL/MariaDB-safe — the documented target; also safe for SQLite, where a literal backslash arrives doubled — use sqlexec binds for exact bytes); NUL bytes stripped
  random_password Generate an alphanumeric password (default len 16, no O/o, guaranteed upper+lower+digit)
  ssh_run         Run a command on a remote host via ssh; returns {stdout, stderr, exit_code, ok, duration_ms, host, timed_out, interrupted, utf8_lossy, stdout_truncated, stderr_truncated}; max_output optionally caps local capture bytes per stream (omitted: unbounded; 0 is REJECTED — unlike run_argv, where 0 means unbounded — omit the key instead). A cap that cuts mid-UTF-8-sequence makes the lossy decode insert U+FFFD, so utf8_lossy: true beside stdout_truncated: true may be local truncation damage, not remote garbage. env values ship by default in a Mix driver to the remote mix binary (mix_bin opt, else local env MIX_REMOTE_BIN, else /opt/mixos/bin/mix)
  ssh_must        ssh_run wrapper: returns stdout on success, throws a Mix error otherwise
  ssh_mix         Run Mix source on a remote host: ships the source over ssh stdin into `<mix_bin> -`, bypassing ALL shell quoting. The remote binary is the mix_bin opt, else the local env var MIX_REMOTE_BIN, else /opt/mixos/bin/mix; it must be an absolute path or a bare name using only [A-Za-z0-9_./+-] (anything else raises OPTION_INVALID locally). ssh_mix(host, source, [opts]) -> same map as ssh_run; bindings maps valid Mix identifier names to strict-data-encoded values prepended as `$name` assignments, and decode:"data"|"json" adds a parsed `.value` from stdout. max_output caps local capture per stream (0 rejected; omit for unbounded); a truncated stdout REFUSES to decode (raises) — a truncated prefix can parse as a smaller, wrong value — so omit decode and inspect stdout/stdout_truncated to work with partial output. Accepts every ssh_run opt except stdin/env_transport. Remote command failure stays in the result value; invalid arguments/options raise locally. (v0.20.4)
  ssh_mix_many    ssh_mix on many hosts at once: ssh_mix_many(hosts, source[, opts]) -> map host -> ssh_result, keyed in INPUT order. Every host gets the same source, bindings, env and decode, and each result is EXACTLY ssh_mix's ssh_result map, so per-host handling code ports unchanged. opts = every ssh_mix opt plus max (concurrency, default 8, at most 256 live workers — run_parallel's numbers, its own loop). Options are validated once (even for an empty host list) and every host is checked before any ssh spawns; a wrong argument type raises TYPE_MISMATCH. After that nothing raises — one host's failure is DATA in its own map: unreachable, nonzero exit and timeout arrive as ok:false; a local spawn/pipe failure as ok:false with error_code (`PROCESS_SPAWN`, `PROCESS_STDIO`, …) and error; a decode refusal (truncated or unparseable stdout, where ssh_mix raises) as ok:false, decode_error and no value; a host never started because of Ctrl-C as ok:false, interrupted:true. hosts must be unique strings; timeout:0 is refused (one hung host would park the batch); there is no whole-call deadline
  send_mail       Send a plain-text email through the local MTA: send_mail({to, from, subject, body[, headers]}[, {host, sendmail, timeout, mix_bin}]) -> run_argv's process_result + message_id (+ host, only with the host opt). Renders an RFC 5322 message (From, To, Subject, Date, Message-ID, MIME-Version, text/plain utf-8) and pipes it to `sendmail -t -i -f <envelope>` on stdin — never a network SMTP client; ok means the MTA accepted it, not that it was delivered. to is a string or list of strings; Cc/Bcc go in headers. from is exactly one mailbox, addr or Name <addr> (a comment, a second mailbox or <> raises); its address is the envelope sender. Long headers are folded within 78 columns (an unbreakable run over 998 raises); a non-ASCII body or one with a line over 998 bytes goes quoted-printable, else 7bit. A non-ASCII subject is RFC 2047-encoded; every other header value must be ASCII, and CR/LF/NUL in any header raises. headers adds headers or replaces the generated Date/Message-ID/MIME-Version; From/To/Subject there raise (set them in msg), and so do Content-Type/Content-Transfer-Encoding (send_mail encodes the body itself, always text/plain utf-8). sendmail is found on PATH, then /usr/sbin/sendmail, /usr/lib/sendmail, unless the sendmail opt names it. host sends from that host via ssh_exec (remote default /usr/sbin/sendmail); mix_bin (host only) names the remote mix binary, as for ssh_mix. An MTA failure or missing sendmail is DATA (ok:false, exit_code, stderr, error_code); bad input raises before anything runs: OPTION_INVALID (msg fields, options), TYPE_MISMATCH (msg not a map, arity), or ssh_exec's own validation errors with host
  ssh_exec        Run an argv list DIRECTLY on a remote host via a strict-data driver and remote run_argv. Remote stdio allowlist: stdin nil|string|{file}|{null:true} (a stdin STRING is always data, as locally — there is no stdin "inherit" route on either side); stdout capture|null|{file}; stderr capture|null|stdout|{file}. File paths resolve remotely. stdout/stderr inherit and stream:true raise OPTION_INVALID locally before ssh because they would corrupt or bypass the result envelope. Binary stdin also raises locally. Transport/protocol failures and remote command failure are returned in the process_result plus host; a remote without run_argv returns SSH_REMOTE_UNSUPPORTED without running the command. The remote mix binary is the mix_bin opt (older name remote_mix), else local env MIX_REMOTE_BIN, else /opt/mixos/bin/mix
  process_alive   Test if a process exists (signal 0 check). EPERM counts as alive: existence does not imply permission to signal, including another user's process. pid must be a positive whole NUMBER; no coercion. Nonpositive, bool or string PIDs raise TYPE_MISMATCH. Reaps exited unmanaged children; controller-owned job and registered native-task PIDs use only signal 0 so their sole wait owner retains every status (zombies may briefly report alive).
  net_watch       Subscribe to Linux rtnetlink link/address changes; returns an evaluator-owned opaque handle. Delivers net.changed {watch, changes:[{kind:"link"|"addr", ifname, index, up, removed, operstate?, loopback?, wireless?, family?, address?, prefix?}], overflow, closed?} via $event.args; bursts coalesce per link/address, repeats that change nothing are dropped, overflow means re-read net_state(). opts {events: ["link","addr"]}. No polling fallback
  net_unwatch     Cancel a net_watch handle and its pending changes
  net_state       Snapshot of network links and addresses from an rtnetlink dump: {links:[{ifname, index, up, operstate?, loopback, wireless}], addresses:[{ifname, index, family, address, prefix}]}. up = operstate up, or IFF_UP+IFF_RUNNING when the driver reports unknown (lo, WireGuard)
  audio_watch     Subscribe to PipeWire (pulse server) change notices through one managed `pactl subscribe` child; returns an evaluator-owned opaque handle. Delivers audio.changed {watch, changes:[{facility, kind, index}], overflow, closed?} via $event.args; read the volume with audio_state() once per batch. closed {error_code:AUDIO_SOURCE_EXITED} when the server goes away. opts {facilities (default sink, source, server, card), runtime_dir}
  audio_unwatch   Cancel an audio_watch handle: kills and reaps its pactl child, drops pending changes
  audio_state     Default audio sink volume via one `wpctl get-volume @DEFAULT_AUDIO_SINK@` (2 s deadline): {ok, volume, level (0-100+), muted, reason?}. No default sink, a wpctl that is missing or cannot start, or a timeout is ok:false with a reason, never an error. opts {runtime_dir}
  panic           Abort via an uncatchable Rust panic (distinct from catchable die); the SPEC 18 §3.4 handler boundary isolates it in --serve mode
  raise           Raise a catchable structured error: raise(code, message[, details]) — code is UPPER_SNAKE (e.g. "VALIDATION_REQUIRED", stable identifiers, scripts may define their own); a non-string message is coerced to its string form; catch with `catch $msg, $err` and read $err.code / $err.details / $err.frames (v0.29.0)
  hostname        Return the system hostname
  cwd             Return current working directory
  chdir           Change current working directory
  platform        Return OS platform string (linux, macos, windows, etc.)
  script_path     The absolute, symlink-resolved path of the running ENTRY script, fixed when it starts: the same answer as realpath($0) at start, and a chdir() does not move it. nil under `mix -c`, in the REPL and for `mix -` (stdin). Always the entry script: a require()d module, even during its top-level init, gets the entry script's path, not its own (v0.111.0)
  script_version  The running entry script's provenance: {name, version, sha, sha256, modified, mix: {version, sha, dirty}} — `version` is the `-- version: X.Y.Z` header (nil when absent or malformed), `sha` the first 12 hex of the content SHA-256, `modified` the file mtime as RFC 3339 UTC (nil for `mix -`). Always the ENTRY script (a require()d module gets its caller's record); held per evaluator, so each --serve RELOAD generation answers for its own file. Returns nil in the REPL, under `mix -c`, and in embedders that install no record. The same facts `mix SCRIPT --version` prints, as data (v0.95.0)
  which           Locate an EXECUTABLE in PATH: a PATH entry is returned only if it is a regular file the kernel says this process may execute (faccessat2 X_OK, so POSIX ACLs count), never merely a file that exists, and never a directory. cmd must be a string and is not coerced. Returns nil when nothing on PATH is runnable under that name (executability enforced since v0.52.0)
  date_format     Format Unix timestamp with strftime pattern
  date_parse      Parse date string with strftime pattern into Unix timestamp
  now_iso         Current time as ISO 8601 string
  duration_format Format seconds as human-readable duration (e.g. "2h 15m")
  relative_time   Format timestamp as relative string (e.g. "3 hours ago")
  base64_encode   Encode string as base64
  base64_decode   Decode base64 string
  hash_blake3     BLAKE3 hash of a string/bytes/buffer → lowercase hex; pass {raw:true} for the raw digest as bytes (v0.66.0)
  hash_sha256     SHA-256 hash of a string/bytes/buffer → lowercase hex; pass {raw:true} for the raw 32 digest bytes (v0.66.0 — before that a second argument was silently IGNORED)
  hash_md5        MD5 hash of a string/bytes/buffer → lowercase hex; {raw:true} → bytes. ⚠ CRYPTOGRAPHICALLY BROKEN (collisions since 2004) — legacy interop only (Content-MD5, mail dedup keys, checksums against existing tools), NEVER a security decision; use hash_sha256/hash_blake3 for those (v0.66.0)
  hash_sha1       SHA-1 hash of a string/bytes/buffer → lowercase hex; {raw:true} → bytes. ⚠ CRYPTOGRAPHICALLY BROKEN (SHAttered, 2017) — legacy interop only (git object ids, older ETags/APIs), NEVER a security decision; use hash_sha256/hash_blake3 for those (v0.66.0)
  hmac_sha256     HMAC-SHA256 (RFC 2104) of a message with a secret key → lowercase hex; {raw:true} → the 32 MAC bytes (v0.66.0) — webhook signature verification (Stripe-Signature etc). Accepts string/bytes/buffer for both args (requires crypto feature)
  password_hash   Hash a password: password_hash(plaintext[, cost]) → bcrypt $2b$… string (cost 4-31, default 12; input over 72 bytes raises), or password_hash(plaintext, {scheme: "sha512-crypt"[, rounds]}) → $6$… for Dovecot passdbs (rounds 1000-999999999, default 5000; 16-char salt; default rounds emit the implicit glibc `$6$salt$hash` form, 120 chars with the {SHA512-CRYPT} prefix, while any other rounds value adds a `rounds=N$` field). Client-side hashing before writing maild.accounts.password over the Bus — a raw props.set stores the field verbatim (requires crypto feature; v0.71.0, sha512-crypt v0.102.6)
  password_verify Check a plaintext password against a hash: bcrypt (any $2a$/$2b$/$2y$ form) or SHA-crypt ($6$/$5$, incl. the Dovecot {SHA512-CRYPT} prefix) → bool. A malformed hash RAISES rather than answering false — a corrupt stored hash is a config fault, not a wrong password (requires crypto feature; v0.71.0, sha-crypt v0.102.6)
  constant_time_eq Timing-safe equality for secrets/MACs: compares full length with no early exit (plain == leaks a timing oracle). Use for webhook signature comparison. Accepts string/bytes/buffer
  jwt_rs256_sign  Sign JSON object claims with a PEM RSA private key using RS256; optional JSON object headers, alg pinned to RS256. Returns a compact JWT; crypto feature. No token exchange or expiry/audience policy
  hash_file       Streaming digest of a file, fixed 64 KiB working set whatever the size: hash_file(path[, "md5"|"sha1"|"sha256"|"blake3"|nil][, {raw:true}]) → lowercase hex, or bytes with {raw:true}. md5/sha1 added v0.66.0 and are BROKEN hashes for legacy interop only (v0.24.0)
  uuid            Generate a new random UUID v4 string
  dkim_keygen     Generate a DKIM keypair. dkim_keygen("rsa", [bits=2048]) or dkim_keygen("ed25519") → {algorithm, private_pem, public_b64, dns_txt_record}
  http_get        HTTP GET. http_get(url, [headers], [{timeout, ssl_verify, ca_file, ca_pem}] — timeout default 30, 0 disables; ssl_verify default true, false skips TLS cert/hostname checks like curl -k; ca_file/ca_pem ADD a private CA to the default roots — mutually exclusive with each other and with ssl_verify:false, 4 MiB cap, bad PEM raises HTTP_TLS, v0.29.0) → {status, body, bytes, headers, final_url, duration_ms, error_code, error} (headers lowercase-name→list; final_url after redirects; transport failure = status:0 + HTTP_* error_code; v0.30.0). `body` is the response decoded as UTF-8 (nil if not valid UTF-8); `bytes` is the raw byte buffer. Response bodies are capped at 64 MiB (over-cap → {status:0, error}).
  http_post       HTTP POST. http_post(url, body, [headers], [{timeout, ssl_verify, ca_file, ca_pem}]) → {status, body, bytes, headers, final_url, duration_ms, error_code, error} (headers lowercase-name→list; final_url after redirects; transport failure = status:0 + HTTP_* error_code; v0.30.0). Opts (incl. ssl_verify: false → skip TLS verification like curl -k) and `body`/`bytes` semantics (incl. the 64 MiB body cap) match http_get.
  http_request    HTTP any-verb. http_request(method, url, [body], [headers], [{timeout, ssl_verify, ca_file, ca_pem}]) → {status, body, bytes, headers, final_url, duration_ms, error_code, error} (headers lowercase-name→list; final_url after redirects; transport failure = status:0 + HTTP_* error_code; v0.30.0). Opts (incl. ssl_verify: false → skip TLS verification like curl -k) and `body`/`bytes` semantics (incl. the 64 MiB body cap) match http_get.
  http_post_multipart HTTP POST with a multipart/form-data body: http_post_multipart(url, fields, files, [headers], [opts]) → http_response map. `fields` is a map of string form fields; `files` is a map of field_name → {filename, content_type?, data: bytes|buffer} (raw binary payloads, the webhook/file-upload slot — v0.103.12). The boundary is generated, and the Content-Type header is set accordingly.
  http_put_file   Stream a regular file or inclusive range with exact Content-Length. Opts: method PUT/POST/PATCH (default PUT), range:{start,end}, headers, idle_timeout (seconds, default 30), deadline (seconds, default 0), ssl_verify, ca_file, ca_pem. Redirects disabled; 3xx returned. Deadline is cooperative and best-effort during blocking DNS/IO. Fixed 64 KiB transfer buffer; response capped at 64 MiB. Operational errors return status:0; invalid options raise. bytes_written counts source bytes consumed, size is window size, blake3 hashes that window (nil on failure). published is false (no local publication).
  http_get_file   Stream GET through a unique temp sibling and publish atomically. Opts: overwrite (default false), append (default false; requires expect_blake3 and matching 206 Content-Range), expect_blake3 (64 lowercase hex), max_bytes (final size), headers, idle_timeout (seconds, default 30), deadline (seconds, default 0), ssl_verify, ca_file, ca_pem. 200/206 require identity framing and Content-Length; missing length or encoded responses return HTTP_IDENTITY_FRAMING. Append copies and hashes the existing prefix. Redirects returned; error bodies never installed. No-replace is atomic. Deadline is cooperative and best-effort during blocking DNS/IO. bytes_written counts downloaded bytes, size includes prefix, blake3 hashes the final file. published records publication even if directory fsync fails. Operational errors return status:0; invalid options raise.
  bytes_len       Length of a Value::Bytes buffer in bytes (v0.3.1)
  string_to_bytes Convert a string to its UTF-8 byte representation (v0.3.1)
  bytes_to_string Convert a bytes buffer to a string; strict UTF-8, or pass {lossy:true} for a from_utf8_lossy decode (v0.17.2). Also accepts a Buffer.
  bytes_find      0-based byte offset of needle in a bytes/buffer value, -1 if absent; optional `from` (signed, clamped) starts the scan and the result stays ABSOLUTE. Needle: bytes/buffer/string/byte number 0-255, and must not be empty. ⚠ NEVER use bare in a condition: -1 is truthy, 0 is falsy (MIX-W2305) (v0.64.0)
  bytes_starts_with Test whether a bytes/buffer value starts with a prefix (bytes/buffer/string/byte number 0-255); an empty prefix is true (v0.64.0)
  bytes_ends_with Test whether a bytes/buffer value ends with a suffix (bytes/buffer/string/byte number 0-255); an empty suffix is true (v0.70.0)
  bytes_split     Split a bytes/buffer value on a separator (bytes/buffer/string/byte number 0-255) → list of bytes. Same piece rules as split(): absent separator → one whole piece, leading/trailing separator → empty piece. An EMPTY separator raises (v0.64.0)
  bytes_concat    Concatenate 1+ bytes/buffer/string values into one new bytes (a string joins as its own UTF-8). A list argument raises and names bytes_from (v0.64.0)
  bytes_from      Build bytes from a LIST, flat-splicing each item — int 0-255 = one byte, string = its UTF-8, bytes/buffer = its content (same item vocabulary as buffer([items])) (v0.64.0)
  bytes_to_hex    Lowercase hex of a bytes/buffer value, two chars per byte, no separator (v0.64.0)
  bytes_from_hex  Decode a hex string to bytes — strict: even length, [0-9a-fA-F] only, no separators or whitespace. Exact inverse of bytes_to_hex (v0.64.0)
  dns_query       Ask one DNS server one question and get the whole answer: dns_query(name, type[, {server, port, timeout, tcp, recurse}]) -> {ok, rcode, aa, ra, tc, answers, authority, additional, server, port, transport, duration_ms}; each record is {name, type, ttl, data}. type is A, AAAA, MX, TXT, SRV, NS, SOA, PTR, CNAME, CAA, ... (PTR of an IP address asks its reverse name). server defaults to the first resolv.conf nameserver, port 53, timeout 5 s, recurse true (the RD flag); tcp:true forces TCP and a truncated UDP answer is retried over TCP. The name is always fully qualified (no search list). Timeout, unreachable and malformed replies return {ok:false, error_code: DNS_TIMEOUT|DNS_UNREACHABLE|DNS_PROTOCOL|DNS_IO|DNS_SERVER, error}; bad arguments raise (v0.117.0)
  dns_lookup      Resolve a hostname to a list of IP address strings
  udp_send        Send ONE UDP datagram: udp_send(host, port, payload) -> bytes sent. Payload (string/bytes/buffer) goes out verbatim; host is resolved. Not a socket API — nothing to hold or close (v0.71.0)
  udp_recv        Receive ONE UDP datagram: udp_recv(port[, {timeout, host, max}]) -> {bytes, text, from_host, from_port}, or nil on timeout (an ordinary answer, not a fault). timeout seconds default 30, 0 = wait forever; host = bind address default 0.0.0.0; max caps the read (default 65535 = never truncates; a longer datagram truncates to max, recvfrom(2)'s own contract). text is the payload as UTF-8 or nil — bytes always carries the truth (v0.71.0)
  ws_connect      Open a websocket (ws:// or wss://): ws_connect(url[, {insecure, headers, timeout}]) -> numeric handle. insecure:true skips TLS cert verification (self-signed device endpoints — the LG SSAP case); headers adds handshake request headers; timeout seconds bounds connect AND handshake (default 30, must be positive). Requires ws feature (v0.74.0)
  ws_send         Send one websocket frame: text for a string payload, binary for bytes/buffer; flushed before returning. A closed connection raises and retires the handle (v0.74.0)
  ws_recv         Wait for the next DATA frame: ws_recv(handle[, timeout]) -> string (text frame) | bytes (binary frame) | nil on timeout (poll again). timeout seconds default 30, 0 = wait forever. Ping/pong handled internally. A peer close RAISES (catchable) and retires the handle — closed is not confusable with quiet. In a Class C async body, numeric ws_recv(handle[, timeout]) yields on native readiness; subscribed numeric handles refuse SOCKET_SUBSCRIBED. Source-id recv yields outside serve mode; serve mode refuses SOCKET_RECV_SERVE so the event pump cannot steal frames. nil on timeout keeps the connection usable; a terminal raises SOCKET_CLOSED (v0.74.0)
  ws_close        Close a websocket handle: true when it was live, false when unknown/already retired (never raises for the not-held case, like funlock) (v0.74.0)
  http_serve      BLOCKING static file server — the python -m http.server slot: http_serve(root[, {port, host, duration, index, listing, render_md, requests}]) -> requests served. GET/HEAD only (405 otherwise), NO TLS ever and NO dynamic handlers (both are webd's job). port 0 (default) binds ephemeral and PRINTS the URL; host defaults 127.0.0.1 (pass "0.0.0.0" to expose); duration 0 = until SIGINT; listing opts into directory indexes; render_md serves .md as HTML (markdown feature); spa (true=index, or a shell filename) answers an extensionless would-be-404 with that shell so a client-side router boots — for a single-shell SPA; clean_urls serves /foo.html for /foo (GitHub Pages parity — for a pre-rendered page-per-route site), tried before spa. Traversal-proof: every canonicalised path must stay under the canonicalised root (v0.75.0)
  http_recv       Accept ONE HTTP request, answer it, return it: http_recv(port[, {timeout, host, max, respond}]) -> {method, path, query, headers, body, bytes, from_host, from_port}, or nil on timeout. The OAuth-localhost-redirect / webhook-catch shape. respond: {status, body, content_type, headers} (default 200 "ok"); max caps the request body (default 1 MiB); host defaults 127.0.0.1 (v0.75.0)
  tcp_connect     Open a raw TCP connection: tcp_connect(host, port[, {timeout, tls, insecure}]) -> numeric handle. tls:true wraps in TLS (ring-pinned, webpki roots); insecure:true skips cert verification. The stream-socket primitive for a line/binary protocol (SMTP/redis/memcached probe, banner grab) UDP/WS/HTTP don't cover (v0.78.0)
  tcp_send        Send bytes on a TCP handle: tcp_send(h, payload[, {timeout}]) -> bytes sent (string/bytes/buffer, verbatim; flushed). Without timeout each write is bounded by the socket's 30 s write timeout, as before. With {timeout} (seconds, 0 = wait forever) one deadline bounds the WHOLE send however many partial writes it takes; on expiry it raises TCP_SEND_TIMEOUT (details {written, total}) and retires the handle, and bytes already written stay written. The timed wait honours SIGTERM and Ctrl-C. On a tcp_on handle the timeout is the receipt deadline (0 keeps the 30 s bound) (v0.78.0; timeout v0.112.1)
  tcp_recv        Read available bytes: tcp_recv(h[, {timeout, max}]) -> bytes (buffered bytes first, then one read of at most 256 KiB — poll again for more even when max is larger) | nil on timeout (poll again). Bytes not string — a stream has no frame boundary. A peer close RAISES and retires the handle. timeout default 30 (0=forever), max default 64 KiB. Numeric Class C recv yields on native readiness. Source-id recv yields outside serve; serve mode refuses SOCKET_RECV_SERVE and consumes frames through handlers. nil on timeout keeps the connection usable; terminal raises SOCKET_CLOSED (v0.78.0)
  tcp_recv_line   Read the next LINE: tcp_recv_line(h[, {timeout, max}]) -> string (LF + one trailing CR stripped) | nil on timeout. Buffers across reads; if `max` bytes accumulate with no newline the handle RAISES and RETIRES (a peer that never terminates a line — broken framing). For line protocols (SMTP/redis) so a caller need not hand-roll a \r\n scanner. On a unix_connect {frame:"nul"} handle a line is a NUL-terminated frame (no CR stripping). From v0.115.0 a line longer than max raises even when its terminator has arrived. Numeric Class C recv yields on native readiness. A line-mode source-id recv yields outside serve; serve mode refuses SOCKET_RECV_SERVE and uses event handlers. nil on timeout keeps the connection usable; terminal raises SOCKET_CLOSED (v0.78.0)
  ws_on           Subscribe a ws_connect handle to the event stream: ws_on(handle, command) -> source id (string). The connection MOVES to an evaluator-generation reader thread: ordered frames arrive as `command` events {watch, frame:{kind:"text"|"binary", data}} (binary data hex-encoded), a peer close as ONE terminal {watch, closed:{reason}} — then the source retires. ws_send on the moved handle routes to the owner and awaits its receipt; numeric ws_recv refuses. Serve handlers receive frames as events. The reader parks in poll(2) when idle (no timer). Overflow hard-closes the socket with exactly one terminal event, never a silent drop. ws_unwatch cancels, joins and emits NO terminal marker (v0.107.0)
  ws_unwatch      Cancel a ws_on subscription: ws_unwatch(source) -> nil. Cancels and joins the reader, drops queued frames and wakes a parked ws_recv with SOCKET_WATCH_HANDLE. Emits NO terminal event (explicit close — documented). Unknown or retired sources raise (v0.107.0)
  tcp_on          Subscribe a tcp_connect handle to the event stream: tcp_on(handle, command[, {frame:"line"|"bytes", max}]) -> source id (string). frame defaults to "bytes": ordered raw chunks of at most 64 KiB; frame:"line" splits on LF (one trailing CR stripped) with max capping the line length (default 65536) — a line over max hard-closes with one terminal event. On a unix_connect {frame:"nul"} handle, line frames end at NUL; from v0.115.0 a complete line over max also hard-closes. Same ownership, ordering, overflow and retirement rules as ws_on; tcp_recv consumes a bytes source, tcp_recv_line a line source, and a mismatched verb refuses (SOCKET_KIND). A tcp_listen LISTENER subscribes too (no options): each accepted connection arrives as {watch, accepted:{handle, peer:{host, port}}}, handle a plain connected handle; tcp_accept(source) takes the next one outside serve mode (v0.107.0; listeners v0.112.0)
  tcp_unwatch     Cancel a tcp_on subscription: tcp_unwatch(source) -> nil. Same contract as ws_unwatch (v0.107.0)
  tcp_close       Close a TCP handle or listener: true when live, false when unknown/already closed (never raises for that, like funlock) (v0.78.0)
  tcp_listen      Listen for TCP connections: tcp_listen(host, port[, {backlog}]) -> numeric listener handle (tcp_connect's handle space). host is required: "127.0.0.1" is the normal choice, and a non-loopback address ("0.0.0.0", a LAN IP) must be named explicitly. port 0 binds an ephemeral port (read it with tcp_local_addr); backlog defaults to 128 (1..4096). Owned by the evaluator generation. Raises TCP_LISTEN_ADDR_IN_USE, TCP_LISTEN_PERMISSION, TCP_LISTEN_ADDR_UNAVAILABLE, TCP_LISTEN_ADDRESS, TCP_LISTEN_ARGUMENT, TCP_HANDLE_LIMIT (v0.112.0)
  tcp_accept      Wait for one connection on a tcp_listen listener: tcp_accept(listener[, {timeout}]) -> numeric connected handle (use with tcp_send/tcp_recv/tcp_recv_line/tcp_on/tcp_close) | nil on timeout. timeout seconds default 30, 0 = wait forever. Numeric Class C accept yields on native readiness; a subscribed listener refuses SOCKET_SUBSCRIBED. Source-id accept (a tcp_on listener source) yields outside serve; serve mode refuses SOCKET_RECV_SERVE. Accepted handles belong to the evaluator generation (v0.112.0)
  tcp_local_addr  Local address of a TCP listener or connected handle: tcp_local_addr(handle) -> {host, port} — how a script that bound port 0 learns its port (v0.112.0)
  unix_connect    Open a unix-domain stream socket: unix_connect(path[, {timeout, frame}]) -> numeric handle in tcp_connect's handle space, so tcp_send, tcp_recv, tcp_recv_line, tcp_on and tcp_close take it (tcp_local_addr refuses: no TCP address). path is an absolute filesystem path (at most 107 bytes; abstract sockets are not offered). timeout (seconds, default 30) bounds the connect and each write; a listener with a full backlog fails at once (UNIX_CONNECT_BUSY) rather than block. frame:"nul" makes a line a NUL-terminated frame (Varlink, hostd): tcp_recv_line returns the next frame without its NUL and tcp_on {frame:"line"} delivers one per event; send the NUL yourself (tcp_send(h, json .. chr(0))). frame:"line" (default) keeps LF lines. Raises UNIX_CONNECT_NOT_FOUND, UNIX_CONNECT_PERMISSION, UNIX_CONNECT_REFUSED, UNIX_CONNECT_BUSY, UNIX_CONNECT_TIMEOUT, UNIX_CONNECT_ARGUMENT, UNIX_CONNECT (v0.115.0)
  help            Show Mix builtin help in the REPL
  project_info    Read-only workspace introspection: project_info() -> {root, main: {members: [crate names], exclude, toolchain}, desktop: bool} — the main workspace members (crates/* minus excludes), the pinned rust-toolchain channel, and whether the desktop workspace is present. For orchestration scripts, no ad-hoc TOML parsing (v0.103.15)
  require         Load a Mix module: evaluate the file once in an isolated scope, return its exports (map of top-level fns + $vars, or the file's top-level return value). Cached per canonical path; cycles error (v0.27.0)

## format  — see [strings](strings.md)

  fmt             printf-style format string → string. Specs: %s %d %f %.Nf %Nd %-Ns %0Nd %% (v0.2.0; %0Nd zero-pad v0.54.0 — numeric only, use lpad(s,n,"0") for strings). Dynamic width `*` takes the width from the next argument: %*s %-*s %*d %0*d %*f (v0.63.0; the width argument must be a non-negative integer). For byte-exact C-printf parity (%e %g %x, flags, glibc float rounding) use sprintf()
  sprintf         C-compatible printf: sprintf(fmt, ...) → string. Conversions %d %i %u %o %x %X %f %F %e %E %g %G %s %c %%; flags - + 0 # and space; width/precision incl. *; length modifiers parsed and ignored (integer conversions are 64-bit, so a negative %u/%x prints its 64-bit two's-complement). Float output matches glibc printf byte-for-byte (fixture-tested) — for emitting numbers a C/Rust consumer compares exactly. Divergences: %s pads by codepoints and %.Ns truncates to ≤N bytes without splitting a codepoint; %c takes a Unicode scalar (v0.71.0)
  printf          Formatted write to stdout (no trailing newline — include \n explicitly) (v0.2.0)
  eprintf         Formatted write to stderr (v0.2.0)
  format_bytes    Format byte count as human-readable size (e.g. "1.5 MB"); a non-numeric argument raises (strict since v0.55.0)
  format_number   Format number with thousands separators; non-numeric value/decimals arguments raise (strict since v0.55.0)

## json  — see [data](data.md)

  json_parse      Parse JSON string into Mix value
  json_encode     Encode Mix value as JSON string
  jq              Run a jq filter; filter MUST yield 0 (→nil) or 1 (→value) output, >1 raises. jq(value, filter)
  jq_all          Run a jq filter, collect ALL outputs as a list (the stream case). jq_all(value, filter)
  read_json       Read a single-record JSON file directly into a Mix value (v0.2.3)
  read_jsonl      Read a JSON-lines file — list of records, strict by default, {skip_errors: true} for lenient (v0.2.3)
  yaml_parse      Parse a YAML string into a Mix value (requires yaml feature; v0.71.0). Single document by default (0 docs → nil, >1 raises); pass {docs:true} for a list of every document. Anchors/aliases resolved; scalar mapping keys become string keys; a non-scalar key raises
  yaml_encode     Encode a Mix value as YAML (requires yaml feature; v0.71.0). No leading --- marker, trailing newline guaranteed; whole numbers emit as integers; nil/bool/number/string/list/map only — bytes, buffer or function values raise
  toml_parse      Parse TOML string into Mix map
  toml_encode     Encode Mix value as TOML. Raises TOML_UNREPRESENTABLE with {path,type} details for nil, function, bytes, or buffer values instead of silently replacing them with empty strings (strict since v0.55.0)
  data_parse      Parse a strict-data `.conf.mix` string into a Mix value (inverse of data_encode) (v0.3.2)
  data_encode     Encode a Mix value as a strict-data `.conf.mix` string with correct \$ / \~ / \\ escaping; round-trips through data_parse. data_encode(value, [pretty]) — truthy 2nd arg emits multi-line indented output (v0.3.2)

## validate  — see [data](data.md)

  require_key     Assert a map key is present with a non-nil value and return it; raises VALIDATION_REQUIRED with details {path, expected, actual_type} (v0.29.0)
  expect_type     Assert a value's type and return it: expect_type($v, "integer") — types: any nil bool number integer string bytes buffer list map function (integer = finite whole within ±2^53-1); raises VALIDATION_TYPE (v0.29.0)
  nonblank        Assert a string contains a non-whitespace character, return it UNTRIMMED; the optional label names the value in the error; raises VALIDATION_NONBLANK — the boundary guard against nil/"" flowing into hostnames and paths (v0.29.0)
  get_or          Map lookup with a default that covers BOTH an absent key and a nil value (the tolerant twin of require_key) (v0.29.0)
  validate        Validate a map against a field spec at a job/API boundary: validate($raw, {node: {type: "string", nonblank: true}, plan: {enum: ["gold", "silver"]}, vmid: {type: "integer", min: 100, max: 999999}, tags: {required: false, type: "list", items: {type: "string"}}, owner: {type: "map", schema: {name: {nonblank: true}}}}). Rules: required (default TRUE) / type (string or list of types) / nonblank / enum / min / max / min_length / max_length / items / schema. Returns the ORIGINAL map unchanged; optional absent-or-nil fields skip their rules; unknown INPUT fields pass through; unknown RULE keys raise VALIDATION_SPEC; violations raise VALIDATION_* with details {path, expected, actual_type} — paths like owner.name and tags[2] (v0.29.0)

## hof  — see [hof](hof.md)

  sort_by         Return list sorted ascending by key function (stable) (v0.2.0)
  filter          Return new list of items where predicate returns truthy (v0.2.0)
  map             Return new list of transform(item) results (v0.2.0)
  reduce          Fold list left with an explicit init: reduce($xs, $init, function($a, $b) = ...) (v0.2.0)
  any             Short-circuit: true if any item matches predicate (v0.2.0)
  all             Short-circuit: true if every item matches predicate (v0.2.0)
  count           Count items where predicate returns truthy (v0.2.0)
  min_by          Return the ITEM (not the key) with minimum key-function value (v0.2.0)
  max_by          Return the ITEM with maximum key-function value (v0.2.0)
  sum_by          Sum of key(item) across all items, returns number (v0.2.0)
  group_by        Map of stringified-key → list of items (first-seen key order) (v0.2.0)
  unique_by       Dedup list by key function, first occurrence wins (v0.2.0)

## bus  — see [bus](bus.md)

  bus_call        Call a host-injected Bus verb under delegated identity: bus_call(verb, args) → reply. The embedder bounds which verbs are reachable and injects the delegation envelope; the script names no host/peer/actor
  publish         One-call topic publish (0.63.0): publish(topic, body[, opts]) builds the SPEC-02 wire frame and sends it via noded topic.publish — no hand-built ---\n frames, no body=/name= header-route trap. body is the payload STRING (json_encode a map first); opts: {retain: bool, command: string (inner frame header override, defaults to topic), headers: map}. Sets $rc/$result like `send`; returns rc (0 = published)
  serve_name      The Bus service name this `mix --serve` citizen registered under — the `--name` value, else the script-stem derivation — or nil in a plain script or the REPL. Read it instead of hard-coding the name: a second instance started with `--name other` must publish `other`, not the first instance's name, in anything that routes replies or clicks back to it. `$me = serve_name() ?? "quoin-panel"` keeps a script runnable outside serve mode (v0.91.0)
  is_reload_candidate True only while a `--serve` hot-reload candidate's init body is executing (false during the initial boot, in a plain script, and in every committed generation). A loader branches on it: the candidate must prepare passive state only — no starts, no spawns, no stopping old behaviour, no persisted writes — because a failed candidate reverts to the old evaluator with its managed children intact, and the committed generation reaps the old children before its own `lifecycle.commit` handler starts anything. Commit-time work belongs in an `on lifecycle.commit` handler, which the runtime queues locally exactly once per committed swap
  send            Send a request to a Bus port: send PORT VERB [ARGS...]. Reply bands in $rc: 0 delivered+accepted; 1..9 delivered with a warning (still success); >=10 peer application error (kept in $rc, details in $reply); -1 transport failure; -2 per-send timeout; -3 Bus unavailable. $result holds the reply body
  emit            Fire-and-forget Bus message (no reply is waited for): emit PORT VERB [ARGS...]
  address         Set the default Bus target for a block: address PORT ... end (bare send lines inside go to PORT)
  on              Register a Bus handler: on VERB ... end. A serve citizen answers VERB calls; reply() sends the answer. Topic subscribers match on the inner command
  reply           Answer the in-flight request the serve pump is dispatching (only inside an on handler); payload becomes the caller's $result
  subscribe       Register interest in a Bus topic so deliveries reach a matching on handler: subscribe("topic.name")
  unsubscribe     Drop interest in a Bus topic: unsubscribe("topic.name")
  port_exists     True when a Bus port exists on the broker
  bus_reconnect   Reconnect the Bus broker session
  noded_register  Register this node with noded (identity/bootstrap)

## db  — see [capabilities](capabilities.md)

  db_query        Query the host-injected scoped DB: db_query(sql, [params]) → rows
  db_exec         Exec on the host-injected scoped DB: db_exec(sql, [params]) → {affected, last_insert_id}

## jmap  — see [capabilities](capabilities.md)

  jmap            Call the host-injected JMAP upstream: jmap(method, args) → result, or jmap([[method,args,callId],…]) → methodResponses
  jmap_upload     Upload bytes as a JMAP blob via the host-injected upstream: jmap_upload(body[, content_type]) → blobId (the compose half of the mail seam; Email/set create is blob-only)

## datastar  — see [datastar](datastar.md)

  ds_patch_elements Frame an HTML fragment as a Datastar patch-elements SSE event: ds_patch_elements(html, [{selector, mode, view_transition}]) → event string. mode=outer(default)/inner/remove/replace/prepend/append/before/after. Caller MUST html_escape() untrusted content first — this only frames (requires datastar feature) (v0.18.1)
  ds_patch_signals Frame a signal update as a Datastar patch-signals SSE event: ds_patch_signals(signals_map_or_json, [{only_if_missing}]) → event string. A map is JSON-encoded; a string is used verbatim (requires datastar feature) (v0.18.1)
  ds_sse          Assemble a text/event-stream response body from one event string or a list of them: ds_sse(event | [events]) → body. Pair with headers={"Content-Type":"text/event-stream"} (requires datastar feature) (v0.18.1)

## Prelude — Mix-defined helpers, not builtins

`mix help` also lists a small **prelude** (`sum`, `avg`): plain Mix functions auto-loaded from `std/prelude.mix` before every script and `~/.mixrc`. They are not builtins — `mix builtins` and `mix what` do not know them. A builtin always shadows a same-named Mix function, which is why the old prelude `min`/`max`/`abs`/`clamp` shims were retired when the native `math` category landed in v0.19.0, and why the `lines`/`chars`/`read_lines` shims went with the 0.63.0 native `lines`/`chars` (the `read_lines` builtin had shadowed its shim since v0.2.3).

## See also

- [overview](overview.md) · [keywords](keywords.md) · [the mix CLI](cli.md)
- `mix builtins [CATEGORY]` lists one category with one-line descriptions (`mix builtins` alone lists them all); `mix what NAME` describes one builtin or keyword; `mix help` prints the compact category / keyword / subcommand summary.

---

<!-- page: https://mixos.dev/mix/bus/ (source: https://mixos.dev/mix/bus.md) -->

# bus — MixOS Agent Bus messaging (send / emit / address / on)

**Bus messaging is what makes Mix more than "a better shell."** `send`, `emit`,
`address`, and `on … end` are *language keywords*, not library calls — Mix talks
to a local message broker (and, over the mesh, to remote brokers) with no SDK,
no client object, no boilerplate. This is the ARexx lineage made native: every
service is a named, addressable port; a Mix one-liner can drive any of them.

> **Most examples on this page need a live broker** (`noded`, from the
> [cos repo](https://github.com/markc/mixos)). Where a broker is running the output
> shown is real, captured from `mix 0.21.2`. Where no broker is present the Bus
> forms **degrade gracefully** (see [No broker](#no-broker--graceful-degradation)) —
> that path is verified separately. Treat the networked examples as illustrative
> of the shape; the language facts (keywords, `$result`/`$rc`, RPC vs
> fire-and-forget, target syntax) are exact.

```mix
send noded noded.ping            -- RPC to the LOCAL broker
print("rc=" .. $rc)
print("" .. $result)
```
```text
rc=0
result={extensions: {core: 1.0, topic: 1.0}, pong: true}
```

---

## Connection events

In `--serve`, `on bus.connected` receives `{generation}` in `$event.args` after
the initial connection and after reconnection. The generation comes from the
supervised client's successful-connection counter; it is not a wall-clock time
or the script's reload generation. Use the event to refresh snapshots and
reconcile after a broker restart, without a recovery timer.

The adapter waits on `subscribe_state()`. It emits at most once per observed
connected generation. State changes can coalesce while a handler is busy:
generations can skip, so treat the notice as a request to resynchronise rather
than an audit log of every connection. The state observer is shared with the
supervised connection across script reloads; a reload alone does not emit a new
connection event. A dropped receive future preserves state readiness. The lazy
non-serve Bus connection contract is unchanged.

Local native events (`fs.changed`, `proc.exited`, `bus.connected`) share the same
handler dispatch and `$event.args` conversion as incoming Bus events. Structured
event bodies are parsed even in a library build without the optional JSON
*builtin* feature. This introduces no new transport or local-only command gate;
the citizen's public verbs retain their existing local/mesh routing.

## The model in one paragraph

A **broker** (`noded`) runs on the node. Services register a **name**
(`noded`, `statecache`, `webd`, …). You **`send`** a service a **command** (a
dotted verb like `noded.ping`) with optional **key=value args**; the reply lands
in `$result` and the status code in `$rc`. That's an RPC. **`emit`** is the same
shape but fire-and-forget — no reply, no wait. **`address`** is a block of
implicit sends to one target. **`on … end`** is the other direction: it
*subscribes* a handler that fires when a matching message arrives — the basis of
a Mix [citizen](#serve-mode--mix-as-a-daemon-citizen) that *is* an addressable service.

The win over bash/python: there is no equivalent without a client library. In
Mix it is grammar.

---

## `send` — RPC (request/reply)

`send <target> <command> [key=value …]` dispatches a command and **waits for the
reply**. Three result variables are set as a side effect:

| Var | Meaning |
|---|---|
| `$result` | the reply value (a [map](collections.md), list, string, … — field-accessible) |
| `$reply` | the WHOLE reply body, JSON-parsed, for every response — success or refusal, whatever its dialect — and `nil` when the body is empty or not JSON, or the send never got a reply (0.92.0). See [below](#reading-rc-ok-vs-application-error-vs-transport-failure). |
| `$rc` | numeric status in signed bands: `0` delivered+accepted · `1..9` delivered with a warning (still success) · `>= 10` peer application error (the exact peer rc is kept) · `-1` transport failure · `-2` per-send `timeout=` exceeded · `-3` Bus unavailable (no broker). All negatives are non-fatal. |

```mix
send noded noded.info
print("rc=" .. $rc)
print("" .. $result)
```
```text
rc=0
{node: node1, noded: {binary: noded, name: noded, pid: 1342, version: 0.6.10, ...}, schema_version: 1, service_count: 8, uptime_s: 9445, wg_ip: 192.0.2.5}
```

`$result` is structured data — reach into it with `.field` access or `["key"]`
(see [collections](collections.md)):

```mix
send noded noded.ping
if $result.pong then
  print("pong is true")
end
print("core ext: " .. ("" .. $result.extensions.core))
```
```text
pong is true
core ext: 1.0
```

### Verb names with keyword segments (mix 0.96.2)

A bare verb is a dotted name, and **any segment may be a Mix keyword** —
Bus verbs belong to the services that define them, and `select`, `if`,
`print`, `end` are ordinary verb words there:

```mix
send ced ced.select anchor=0
send edit edit.select
emit x x.if.for
on ced.select
  reply("ok")
end
```

The same rule holds everywhere a bare Bus name is written: the `send`/`emit`
command, `address` body lines, a dotted target (`send print.x verb`), and the
`on` handler header. A keyword may also *lead* the name, but only when dotted
(`send svc select.all`, `on print.page`); a bare keyword verb (`send svc
select`) stays a parse error — quote it: `send svc "select"`. `fn` and
`function` segments are read by their source spelling (`x.fn` is `"x.fn"`).
Before 0.96.2 a keyword segment failed with `unexpected token Dot` and the
verb had to be quoted (`send ced "ced.select"`); quoting still works.

### `send` as an expression

`send` also returns the reply, so you can capture it directly (it still sets
`$result`/`$rc` too):

```mix
$r = send noded noded.ping
print("captured: " .. ("" .. $r))
```
```text
captured: {extensions: {core: 1.0, topic: 1.0}, pong: true}
```

### Args: scalars, `body=`, and numbers

For `send`, bare `key=value` args are serialized as a **JSON body** (RPC
framing) by default — noded/indexd/maild verbs read their args from it — with
two exceptions that select **header routing** (scalar args → Bus headers,
`body=` → the body channel):

- a `body=` key is present (the caller is speaking the headers+body shape), or
- the command is a SPEC-12 namespace-mode property call — `<svc>.props.<op>` (incl. multi-segment ops like `props.audit.watch`) with a `namespace=` arg — which reads args from Bus headers, so a kv-only `send webd webd.props.get namespace=x key=y` works without an explicit `body=""`. (SPEC-07 flat-path reads — `noded.props.get path=…` — carry no `namespace=` and stay JSON-body, as their servers expect. Both triggers apply on the broker path only; the local Unix-port path has no header mode.)

(`emit` header-routes **all** map args — RPC-style JSON body is a `send`/`call`
shape.) Whole-number args serialize as JSON **integers**,
not floats — so `limit=2` arrives as `2`, and a peer field typed `usize`/`i64`
accepts it; a fractional value (`2.5`) stays a float.

A `body=`-bearing `send` **awaits its reply** exactly like a positional or
scalar-header send — the handler's `reply(...)` lands in `$rc`/`$result`. (Only
`emit` is fire-and-forget; the arg shape never changes whether a reply is
collected.)

```mix
send noded noded.ping limit=2 note="hello"
print("rc=" .. $rc)
```
```text
rc=0
```

### Reading `$rc`: ok vs application error vs transport failure

A `$rc` of `>= 10` from a *reachable* broker is an **application** error (e.g.
unknown service, rejected command) — the peer's exact rc is preserved (a peer
`rc=42` stays `42`, never flattened to `10`) and it does **not** mean the mesh is
down. A `$rc` in `1..9` is a delivered-with-warning success:

```mix
send nonesuch some.cmd
print("rc=" .. $rc)
print("result=" .. ("" .. $result))
```
```text
rc=10
result=Service 'nonesuch' not found
```

A **negative** `$rc` is a *local*, non-fatal signal — the send never reached a
peer, so `$result` carries the reason string and the script continues: `-1`
transport failure (a broker was there but the send failed — lost or broken
connection), `-2` a per-send `timeout=` budget exceeded, `-3` Bus unavailable (no
broker was ever present, a bare host). See [timeout](#per-send-timeout) and
[no broker](#no-broker--graceful-degradation).

**A structured refusal keeps its body — on the header route.** When a
header-routed send (one with a `body=` arg, or a SPEC-12 `*.props.*` call with
`namespace=`) gets `rc >= 10` with a JSON object naming an `error_code`,
`$result` is that object — field-accessible, so `$result.error_code` and
whatever else it carries (`reason`, `retry_requires`) are readable. (0.87.0)
The ordinary JSON-body send never did this: there `$result` is the `error`
header, else the body's `error` string, else the body text verbatim — so an
`error_code` body with no `error` field arrives as raw JSON TEXT in `$result`.
On either route, read the structure from `$reply` (below), which is the parsed
body whatever its shape; `$result` is for the message.

**`$reply` keeps every field of every reply.** Most daemons refuse in the other
dialect — `{"error": "occluded", "under": {…}}` — and `$result` reduces that to
its message string on purpose, so existing scripts keep working. The detail
(`occluded.under`, `stale_target.current`, `timeout.waited_ms`,
`invalid_args.allowed`) is in `$reply`, the whole parsed body:

```mix
send comp comp.window.focus id=2
if $rc == 10 and $result == "occluded" then
  print("covered by window " .. to_string($reply.under.id))
end
```

`$reply` is set on every `send` (and every address-block line): the parsed body
for a success (the same value as `$result`) or a refusal of either dialect, and
`nil` when the body is empty or not JSON, or when no reply arrived (`$rc < 0`).
One limit: a target reached over its **local Unix port** (a sibling
user-service, not the broker) reports a refusal as a message only, so there
`$reply` is `nil` for a refusal. (0.92.0)

**`$rc`, `$result` and `$reply` are shared, not per-call.** A `send` updates the
existing variable of that name — and once a top-level `send` has created them,
that is the script's global, so a `send` inside a function or an `on` handler
overwrites it too. In a `mix --serve` citizen whose async handlers interleave,
handler A can `send`, yield, and read back the `$rc`/`$result`/`$reply` of
handler B's send. (`$event` is only partly different: a handler BODY's own
`$event` is per-invocation, but a function called from that body reads a
shared global `$event` and has the same interleaving hazard — pass `$event`
into the function as an argument.) Per-invocation binding of all three is
planned (filed in the Mix TODO list). Until it lands, read them immediately
after the `send`, or capture the reply with the expression form —
`$r = send svc cmd` — and copy `$rc` into a local before the next await.

**A wrong verb name answers at once.** A `mix --serve` citizen (or any script
with `on` handlers) that receives a request for a command it has no handler
for refuses it immediately with `rc 10`. On an ordinary send `$result` is the
message ("unknown command 'x' (this citizen handles: …)"); on the header
route (a `body=` send) the `error_code` rule above makes `$result` the whole
object instead. Either way the structure is in `$reply` —
`$reply.error_code == "UNKNOWN_COMMAND"`, `$reply.command` the verb you sent,
`$reply.available` the citizen's declared handlers. (Before 0.92.0 the request
was dropped: the caller waited out its full timeout and got `-2`, which read as
a mesh problem.) So a `-2` from a citizen that answers its other verbs is no
longer a typo symptom — look at the citizen's handler instead. Props paths such
as `lifecycle.generation` are not verbs: read them with
`send svc svc.props.get path="lifecycle.generation"`. The code is a Mix
citizen's: other daemons name the same refusal differently — comp answers
`unknown_verb`, noded its own rc 10 message — so a script that must work
against any service should test `$rc >= 10` and read the code from `$reply`
rather than match one spelling.

**A Mix citizen's runtime refusals are all in the error band.** Besides
`UNKNOWN_COMMAND`, the serve runtime answers a request itself in two more
cases, each with an `error` message and an `error_code`. `rc` 15 and 16 are
the runtime's; pick another `rc >= 10` for a handler's own `reply()` refusals,
and treat `error_code` as the authoritative signal:

| `$rc` | `$reply.error_code` | When |
|---|---|---|
| 10 | `UNKNOWN_COMMAND` | no `on` handler for the verb |
| 15 | `HANDLER_FAULT` | the handler raised, `die`d or panicked before replying; the real error is in the citizen's log, never on the wire |
| 16 | `HANDLER_CANCELLED` | the citizen shut down or reloaded while the handler was still running |

Before mix 0.94.0 the last two answered `rc 1` and `rc 2`, which this section
defines as delivered-with-warning success, so a `$rc >= 10` check missed them.
See [handler fault isolation](serve.md#handler-fault-isolation-the-per-request-boundary).

## `send` and the verified session lane

A locally registered service can be addressed two ways, and only one of them
carries an identity. A TCP connection is known by a name the caller asserts
about itself, which is not an authority — which is why a session-enrolled
service's protected verbs answer `FORBIDDEN` over it. A Unix connection to the
local broker carries peer credentials the KERNEL supplies, so the broker learns
who is calling without having to be told.

`send` now prefers that verified lane, with no change to how you write it:

```mix
$list = send noded "noded.list"          -- find the instance
$r = send $name "term.session" body=$b   -- a protected verb, admitted
```

This grants no new authority. Any same-uid process can already open this
connection — the pane shell and every test harness do — and a local
`DefaultOpen` service admits the resulting session-less ambient principal for a
matching uid/node/broker epoch. What was missing was a way for a SCRIPT to use
it. (0.87.0)

**The fallback is not an error path.** Where no verified lane is available — a
headless host with no local broker socket, a broker running under another
account, a genuinely remote target — `send` falls back to exactly the path it
used before and behaves exactly as it did. The attempt costs nothing when the
socket is absent: a path that does not exist fails at the stat, not at a
timeout. The lane is chosen once per connection, so a script can never end up
with some sends authenticated and others not.

**Discovery.** `noded.list` projects by uid: a caller that owns a record gets
its full `ServiceInfo` including the session details, while everyone else gets
the bare name. A driver over the verified lane is same-uid by construction, so
one `send noded "noded.list"` is enough to find a service's per-instance name
and address it.

---

## `emit` — fire-and-forget

`emit <target> <command> [key=value …]` dispatches and returns immediately. No
reply is awaited and **`$rc`/`$result` are not set** by `emit` — it is a
statement that yields `nil`, used when you don't care about (or can't get) an
answer, e.g. publishing to a topic or notifying a service.

```mix
emit noded noded.ping note=hi
-- no $rc is written by emit; do not read it after an emit
print("emitted")
```
```text
emitted
```

Gotchas:

- `emit` is a **statement**, not an expression — `$x = emit …` is a parse error. (`send` *can* be an expression; `emit` cannot.)
- Because `emit` writes neither `$rc` nor `$result`, reading `$rc` right after an `emit` (with no prior `send`) raises *undefined variable `$rc`* — pre-init it or just don't.

---

## `publish(topic, body[, opts])` — one-call topic publish (0.63.0)

Publishing to a topic used to require two pieces of lore: the body handed
to `noded topic.publish` must itself be a **SPEC-02 wire frame**
(`---\ncommand: …\n---\npayload`), and the `send` needed `body=` spelled
before `name=`/`retain=` would header-route. `publish()` does both:

```mix
$rc2 = publish("comp.corner.entered", json_encode({corner: "tl"}))
if $rc2 != 0 then eprint("publish failed: " .. $result) end
```

- `topic` — the noded topic name; by default it is also the inner frame's
  `command:` header (what subscribers' `on` matches).
- `body` — the payload **string** (`json_encode` a map first — the wire
  format is the caller's choice, never hidden). `nil`/absent → empty.
- `opts` — `{retain: bool}` (default false); `{command: "corner.entered"}`
  overrides the inner frame header (the fleet publishes topic
  `comp.corner.entered` with inner command `corner.entered`);
  `{headers: {event_seq: 1042}}` adds frame header lines. Topic, command
  and headers are newline-checked — frame injection raises instead of
  corrupting the wire.

Sets `$rc`/`$result` exactly like `send` (and sets `$reply` to `nil`, so an
earlier send's reply is never read as the publish's) and returns the rc, so
`if publish(..) != 0` reads naturally. Without a broker it degrades like
`send`: `$rc = -3`, non-fatal.

**Hyphenated targets need no quoting.** `send comp-nested …`,
`emit desktop-vt1 …` and `address shell-scenes-p2 … end` all read the
hyphenated name whole. Hyphenated service names are the norm on the mesh, so
the bare form has to work; quoting and `$var` remain exactly equivalent
spellings.

The accepted shape is deliberately narrow, and is the
[shell classifier](shell-mode.md)'s tight-hyphen rule for command heads plus
`.` for dotted names: an ASCII letter or `_` first, at least one `-`,
alphanumerics / `_` / `-` / `.` within, an alphanumeric or `_` last, and the
whole thing delimited by whitespace, a newline, a `;`, or end of input.
A first segment that is a Mix keyword is fine too (`next-hop`, `print-server`,
`on-boot`), because a bare keyword in target position was never anything but a
parse error.

Anything else keeps the expression reading it always had — a call
(`send env("DEST") …`), an index, a parenthesised expression, a `$var`, and a
**spaced** `send a - b …`, where the space says an operator was meant. The one
exception is a concat whose left operand is a bare hyphenated word
(`send a-b .. "c" …`): that is now a *parse* error where it used to be a
runtime one, because the word is taken as the target and the `..` is left with
nowhere to go. It could never have been a working concat — the left operand of
`..` there is a bareword, which is a string, so the subtraction ahead of it
always failed first.

**Quote a name the bare form cannot reach.** Two shapes fall outside it, and
quoting is the answer to both:

| name | why | write |
|---|---|---|
| `a--b` | `--` opens a **comment**, so the bare word stops there and the shape is refused | `send "a--b" …` |
| `fn-svc` | `fn` starts a lambda | `send "fn-svc" …` |

All-digit segments are fine bare, including malformed-looking ones: `svc-1`,
`svc-10`, `bterm-bevy-3164175`, `desktop-vt01`, and since 0.92.0 also `svc-01`,
`node-007` and `a-1.2.3`. Before 0.92.0 the lexer read a leading-zero or
multi-dot segment as a bad NUMBER and refused the line
(`ambiguous leading-zero number '007'`, an error that never mentioned `send`);
it now lexes such a segment as part of the word when it sits in the bare target
right after `send`/`emit`/`address`, or in an `on` header (0.113.1). Everywhere else — `$x = 007`, a
`$var-007` target, a hyphenated command — the refusal is unchanged.

Nothing that worked before changed meaning: the shape *requires* a hyphen, so
every target that already resolved still takes the expression path, and a
bareword is a string, so `a - b` on two barewords was always the runtime type
error "cannot use 'a' as number" rather than arithmetic. (Before this, the
bare form died at runtime with exactly that message while `mix --check` and
`mix lint` both passed the line — an earlier version of this paragraph told
you to quote it and said the grammar would not change.)

---

## `address` — a block of implicit sends to one target

`address <target> … end` opens a block where **each line is an implicit send**
to that target. Drop the `send` keyword inside the block — writing it is a parse
error (the runtime catches the typo deliberately). Each line sets `$rc`/`$result`
in turn, so after the block they hold the **last** send's outcome.

```mix
address noded
  noded.ping
  noded.info
end
print("rc=" .. ("" .. $rc))
```
```text
rc=0
```

`address` is the ergonomic ARexx-style "talk to one port for a while" form. It is
purely a shorthand for repeated `send <same-target> …` lines.

---

## Targets: static dotted `.bus` vs dynamic built

The **command position** of `send`/`emit`/`address` accepts an expression, and so
does the **target**. Two shapes matter:

**1. A bare local service name** — `noded`, `statecache`, `webd`. The broker
routes it on the local node.

```mix
send statecache INFO
print("" .. $result)
```
```text
{description: Mix supervised Bus citizen (SPEC 18 Phase 1 runtime), name: statecache, version: 0.21.2}
```

**2. A static dotted `.bus` address** — `<service>.<node>.bus` addresses a
*remote* node's broker directly, mesh-routed, **no ssh and no string building**.
This literal-address path fires only for a **bare identifier immediately followed
by a dot** (e.g. `noded.node1.bus`); a single bareword, a `$var`, a `(paren expr)`,
a bareword call like `env("X")`, an index, and a `..` concat all stay ordinary
expressions.

```mix
-- illustrative (needs the named node to exist on the mesh):
send noded.node1.bus noded.info
print("" .. $result)
```

Self-addressing works — `send noded.<thisnode>.bus` resolves to the local broker.

**3. A dynamic target from a loop/var** — build the address (or the verb) with
`..` concat. This is the path when the node name isn't a literal:

```mix
$node = "node1"
$target = "noded." .. $node .. ".bus"
-- send $target noded.info   -- illustrative; routes to that node's broker

-- the verb is an expression too:
$verb = "noded" .. ".ping"
send noded $verb
print("rc=" .. ("" .. $rc) .. " result=" .. ("" .. $result))
```
```text
rc=0 result={extensions: {core: 1.0, topic: 1.0}, pong: true}
```

> Edge: if an inline `(expr)` in command position collides with the parser,
> pre-build the verb into a `$var` (as above) and pass the var.

---

## Per-send `timeout=`

`send … timeout=<seconds>` puts a wall-clock budget on the RPC (cooperative
cancellation; the pending-reply slot is freed on expiry). On timeout you get
`$rc = -2` (RC_TIMEOUT) — its **own** numeric band, distinct from `-1` transport
— with a `timeout: …` reason in `$result`. Non-fatal: the script continues.

```mix
-- against a 2s-slow downstream:
send slowsvc do.work timeout=0.5
-- $rc     == -2      (RC_TIMEOUT, numeric)
-- $result == "timeout: send to slowsvc exceeded 0.5s"
```

Rules (all raise a `RuntimeError` if violated): `timeout=` must be a **finite,
positive** number; **absence** means "no timeout" (there is no sentinel value);
`nil` is treated as absent (so `timeout=$t` is fine when `$t` may be unbound);
duplicate `timeout=` is last-wins. The `timeout=` slot is consumed locally and
does **not** appear in the args delivered to the peer.

---

## `port_exists(name)` — is a service registered?

A builtin (not a keyword) that asks the broker whether a named service is in its
registry. Useful as a guard before an RPC.

In `--serve`, a failed registry request raises a catchable mesh-unavailable
error (Mix 0.109.0). Only a successful registry response can establish that a
service is absent. `emit` retains its fire-and-forget, non-fatal language
contract during a transport failure; it supplies no delivery acknowledgement.

```mix
print("statecache: " .. ("" .. port_exists("statecache")))
print("ghost:      " .. ("" .. port_exists("ghostservice")))
```
```text
statecache: true
ghost:      false
```

> Note: the broker need not list *itself* in its service registry, so
> `port_exists("noded")` can return `false` even while `send noded noded.ping`
> succeeds — `port_exists` reflects the **registered-services list**, not broker
> reachability.

---

## `on … end` — receiving messages (handlers)

`on <command> [desc "doc-string"] [async] … end` (`desc` and `async` compose
in either order) registers a **handler** that fires when a matching Bus
message arrives. The handler body uses newline- or
`;`-separated statements closed by `end` — **no `do` keyword**. The
`<command>` matches the *inner command* of the inbound message (the verb the
publisher sent), **not** the topic/target name — check the publisher to know
what to match. The optional `desc "…"` doc-string (mix ≥ 0.87.1) is static
metadata: a serve citizen surfaces it as the verb's `description` in its
`HELP` reply — see [Serve citizens](serve.md).

```mix
on order.created desc "Acknowledge a new order"
  print("got an order: " .. $event.body)
  reply("ack")
end
```

The `<command>` is a dotted name whose segments may be Mix keywords
(`on ced.select`, `on print.page`) — see
[keyword segments](#verb-names-with-keyword-segments-mix-0962).
A hyphenated name is read whole, with the same shape and the same two
quoting exceptions as a [hyphenated `send` target](#send-and-the-verified-session-lane):
`on dopus-test.command.executed` handles that topic (mix ≥ 0.113.1). Before
0.113.1 the header stopped at the hyphen, so the handler registered as
`dopus` and `-test.command.executed` became its body: it parsed, linted
clean and never fired. The quoted form, `on "dopus-test.command.executed"`,
works in every version.

Legacy `done` still closes `on` (with a deprecation warning); prefer `end`.

### The `$event` map

Inside a handler, the inbound message is available as `$event`, a map with four
fields:

| Field | Type | Access |
|---|---|---|
| `$event.command` | string | the inbound verb |
| `$event.headers` | map | scalar headers, e.g. `$event.headers["topic"]` |
| `$event.body` | string | the raw message body |
| `$event.args` | parsed body \| nil | the body pre-parsed as JSON, or `nil` |

```mix
on topic.delivery
  $topic = $event.headers["topic"]
  print("delivery on " .. $topic .. ": " .. $event.body)
end
```

**`$event` has dynamic extent** (0.63.0): a `fn` the handler body calls —
at any depth — sees the same `$event`, so helpers like
`fn describe() return $event.headers["topic"] end` work. (Before 0.63.0
the handler→fn hop lost it — function frames only fall through to globals
— and the resulting `NAME_UNDEFINED` was swallowed by fault isolation:
the blind-but-healthy citizen.) A fn's own `$event` parameter or local
still shadows it; `$event` stays read-only inside the dispatch; after the
dispatch a top-level `$event` global is restored (or reads `nil` if there
was none).

`$event.args` is a convenience view of the body: when the sender used the
JSON-body path — a **positional** `send svc cmd "a" "b"` (which arrives as
`{"_0":"a","_1":"b"}`) or a **map** arg — the body is already-parsed JSON, so
`$event.args["_0"]` / `$event.args.field` save you a `json_parse($event.body)`.
It is symmetric with the already-parsed `$event.headers` map; `$event.body`
stays the raw string regardless.

`$event.args` is `nil` when the body is empty or is **not** JSON — a raw
`body="hi"` text payload reads back as `nil`, so a handler tells "structured
args" from "raw text" and reaches for `$event.body` in the latter case:

```mix
on order.submit
  if $event.args != nil then
    reply("ok, item " .. ("" .. $event.args["_0"]))   -- send order.submit "widget"
  else
    reply(10, "expected structured args, got: " .. $event.body)
  end
end
```

### `reply(...)` — answer a request

From inside an `on` handler servicing a **request** (one expecting a reply), call
`reply(body)` or `reply(rc, body)`:

```mix
on statecache.get
  reply($current_value)         -- rc defaults to 0
end

on do.validate
  if not $event.body then
    reply(10, "missing input")  -- non-zero rc = application error to the caller
  else
    reply(0, "ok")
  end
end
```

`reply` rules: `rc` must be an integer `0..=255`; it may only be called from
inside an `on` handler; it errors loudly if the current event is *not* a request
(a topic delivery has no caller to answer). A dropped reply would block the
requester forever, so every `reply` failure path is a hard error by design.

### `async` handlers (Class C)

`task_start(command, body)` starts a registered handler chain in process,
without sending a Bus message. `command` and `body` are strings; the body is
decoded into `$event.args` just as for other handler invocations. The event
has empty headers and no reply correlation. The chain must contain an `async`
handler (`TASK_HANDLER` otherwise). It uses the existing Class C task registry,
shutdown drain and runner LocalSet; embedders must provide that LocalSet.
The builtin requires Process capability and is refused in expression mode.

Mixed chains retain declaration order: an async entry can wait on `sleep`,
then a plain entry acquires the writer lock and reads current state to commit.
Never assign a whole pre-wait state copy after a yield. A clock can start one
local task at init and recheck its running flag on `bus.connected`, with no
Bus self-emits. A task is a local continuation, not a separate service or
transport, and does not provide exactly-once remote effects.

A trailing `async` on the handler header marks it **Class C** — the dispatch
*yields* at every `send`/`reply`/`sleep_ms` so concurrent invocations interleave
instead of head-of-line-blocking each other behind a slow downstream call. Plain
(non-`async`) handlers are **Class S**: run-to-completion, one at a time. Use
`async` only when a handler makes a slow/remote downstream `send` and the citizen
serves concurrent callers.

```mix
on aggregate.report async
  send slow.upstream fetch.data          -- yields here; peers can interleave
  reply($result)
end
```

`async` is a *contextual* modifier, not a reserved word — variables/keys named
`async` elsewhere are unaffected. **Synchronous request cycles (A→B→A) are
prohibited and deadlock** — `async` does not legalise them; break a cycle with
fire-and-forget `emit` + a topic reply instead.

### `subscribe` / `unsubscribe` — topic pub/sub

`subscribe("topic.name")` registers interest in a [topic](bus.md) so topic
deliveries reach a matching `on` handler; `unsubscribe("topic.name")` drops it.
Both are builtins that require a live broker — unlike `send`/`emit`, they
**raise** rather than no-op when no broker is reachable (a script must not believe
it subscribed when it didn't).

```mix
subscribe("metrics.cpu")
on metrics.cpu
  print("cpu sample: " .. $event.body)
end
-- … then enter serve mode / the event pump to actually receive them
```

---

## Serve mode — Mix as a daemon (citizen)

`mix --serve <script.mix> [--name <service>]` runs a script as a **first-class,
supervised Bus citizen**: the top-level body executes once as init (open
resources, `subscribe`, register `on` handlers), then the runtime registers the
service name and enters the event pump, dispatching inbound messages to your `on`
handlers. This is the AmigaOS "application with an ARexx port" model — a
long-lived, addressable Mix process that *is* a service. The full lifecycle
contract (registration, reconnect/backoff, handler fault isolation, graceful
`SIGTERM`/`QUIT` shutdown, health properties) is **SPEC 18**.

**Handler faults are isolated but OBSERVABLE** (0.63.0). A raise or panic
in a handler body never kills the citizen (SPEC 18 §3.4) — but it no
longer disappears either: one `mix: handler fault: <command>[N]: …` line
reaches stderr, `lifecycle.health` flips to `degraded`, and
`lifecycle.handler_faults` / `lifecycle.last_fault` count and name it in
the props surface. Before 0.63.0 a faulting handler looked exactly like a
healthy one (noded reported `delivered=1` while its side effects silently
never happened).

**`lifecycle.commit` is a native hook, never a verb.** After a hot-reload
swap commits, the runtime queues one local `lifecycle.commit` event into
the new generation (see [Serve citizens](serve.md) — post-commit
handover). A wire-delivered `lifecycle.commit` is refused with `rc 10`
before any author handler and is filtered from `HELP`: an external caller
cannot run a loader's commit behaviour ahead of or behind the real commit.

A live citizen answers the standard verbs like any Rust daemon:

```mix
send statecache HELP
print("" .. $result)
```
```text
[{args: [], description: List all commands this service accepts, name: HELP}, {args: [], description: Service identity and capabilities, name: INFO}, {args: [], description: Graceful shutdown: deregister, then exit 0 (SPEC 18 §3.5), name: QUIT}, {args: [path?], description: Property snapshot at an optional path, name: statecache.props.get}, ...]
```

A minimal state-holder citizen:

```mix
-- statecache.mix — run with: mix --serve statecache.mix
$value = "(none)"

subscribe("config.current")

on config.current               -- a topic delivery updates our state
  $value = $event.body
end

on statecache.get               -- a request reads it back
  reply($value)
end
```

> A *transient* `mix <script>` (not `--serve`) can `send`/`emit` and even
> `subscribe`, but it has no service name, no reconnect, and the process ends when
> the script does — fine for one-shot orchestration drivers, not for a resident
> service.

---

## Orchestration — citizen ↔ citizen

A Mix citizen can `send`/`address` other citizens, so multi-service orchestration
is native: **pipeline** (A→B→C), **scatter-gather** (fan a request to N workers,
merge replies), **supervisor/worker**, and **review-loop** (a proposer and a
critic iterating). A driver that is its own sole caller (a cron/oneshot/CLI
invocation, no registered name) issuing sequential `send`s is correct under the
cooperative loop. The hard rule: keep the synchronous-request graph **acyclic**;
break any cycle with `emit` + topic replies (see [the deadlock note](#async-handlers-class-c)).

```mix
-- scatter-gather sketch (illustrative)
$replies = []
for each $w in ["worker.a", "worker.b", "worker.c"]
  send $w do.task input=$payload
  push($replies, $result)
end
-- merge $replies …
```

---

## No broker — graceful degradation

For a one-shot local authority query, a caller may launch `mix` with
`MIXOS_NODED_EXPECTED_SERVER_PID` set to a positive decimal PID obtained from
its trusted process supervisor. This pins the server of the verified Unix
connection to the kernel's connect-time `SO_PEERCRED` PID. A missing or
mismatched PID refuses the connection before WebSocket setup or any Bus RPC.
While the variable is present, Mix does not discover the Unix endpoint over
TCP or fall back to anonymous TCP; it checks the pin again on every reconnect.
An invalid value also refuses Bus traffic. Supply the variable only to the
one-shot process that needs the check.

The handler uses a **lazy probe** with a small state machine, so Bus forms behave
predictably on a host that may or may not have a broker:

- **Never had a broker (`NeverPresent`).** `send` returns `nil` with `$rc = -3` (RC_UNAVAILABLE — "Bus unavailable before delivery"; `$result` names the URL it tried), `emit` is silently dropped, `port_exists` returns `false` — **no raise**. `emit` and `port_exists` don't re-probe (no per-call boot cost).
- **Had a broker, lost the connection (`Lost`).** `send` returns `nil` with `$rc = -1` (RC_TRANSPORT) and `emit` is silently dropped — both **non-fatal**, so a mesh script survives a broker blip instead of crashing. `port_exists` **raises** `mesh unavailable: … (call bus_reconnect() to retry the probe)`.
- **`send` retries.** In either state a `send` dials again before it answers, re-reading `MIXOS_NODED_URL` and the node config, bounded by its own `timeout=`. Without `timeout=`, each lane's connect is bounded by 5 seconds, including the WebSocket handshake: up to 10 seconds if both the verified Unix and anonymous TCP lanes stall. After a connection succeeds, waiting for the reply is bounded by `timeout=` when supplied, else by the client's 60-second safety net. A script that sent before its broker listened, that changed `MIXOS_NODED_URL`, or that outlived a broker restart recovers on its next `send` (since 0.117.0; before, every send answered `-3` until `bus_reconnect()`). A failed retry leaves the state as it was.
- **`subscribe`/`unsubscribe`/`reply`** raise in *both* states — these can't be faked; a script must know they didn't happen.
- **`bus_reconnect()`** resets the probe to `Unprobed` so the next Bus form re-dials — the recovery primitive for `emit`, `port_exists` and the serve forms after installing a broker or after a broker bounce.

This is deliberate: `send`/`emit` stay **non-fatal in every state** (a bare host
reads `$rc = -3`, a lost broker `-1`), so a script isn't forced to guard Bus it
may never use — and because the bare-host path no longer fakes `rc=0`, a
`$rc == 0` now strictly means *delivered*. The forms that can't be faked
(`port_exists` once a broker was lost, `subscribe`/`unsubscribe`/`reply` in either
state) still raise, so a genuine outage is heard.

---

## Quick reference

| Form | Direction | Sets `$rc`/`$result`? | Waits? |
|---|---|---|---|
| `send t cmd k=v` | out, RPC | yes | yes (reply) |
| `$r = send t cmd` | out, RPC (expr) | yes | yes |
| `emit t cmd k=v` | out, fire-and-forget | **no** | no |
| `address t … end` | out, block of sends | yes (last line) | yes per line |
| `on cmd … end` | in, handler | — | event pump |
| `on cmd async … end` | in, Class C handler | — | yields on `send` |
| `reply(body)` / `reply(rc, body)` | answer a request | — | no |
| `subscribe(t)` / `unsubscribe(t)` | topic interest | — | yes (raises if no broker) |
| `port_exists(name)` | registry query | — | yes |
| `bus_reconnect()` | reset the probe | — | — |

Sharp edges:

- Command position matches the publisher's **inner verb**, not the topic/target.
- `emit` is a statement only (no `$x = emit …`) and sets **neither** `$rc` nor `$result`.
- Inside `address`, do **not** write `send` (each line is already a send).
- Synchronous request cycles deadlock — keep the graph acyclic.
- `send`/`emit` are **non-fatal in every failure state**: `send` writes a negative `$rc` (`-3` no broker, `-1` lost/transport, `-2` timeout) and returns `nil`, `emit` is silently dropped. `port_exists` raises once a broker was seen and lost; `subscribe`/`unsubscribe`/`reply` raise whenever the broker is unreachable.

## See also

- [strings](strings.md) — `..` concat for building dynamic targets/verbs; `${…}` vs literal `$name`
- [collections](collections.md) — field access into `$result` / `$event` maps
- [functions](functions.md) — handler bodies, lambdas, the pass-in/return/reassign state idiom
- [running commands](system.md) — `run` / `run_rc` / `ssh_run` for non-Bus I/O
- [builtins index](builtins.md) — `port_exists`, `subscribe`, `reply`, `bus_reconnect`, `sleep_ms`
- The [cos repo](https://github.com/markc/mixos) — `noded`, the Bus broker
- The [mix repo](https://github.com/markc/mixos) — [AGENTS.md](https://github.com/markc/mixos/blob/main/AGENTS.md) is the agent orientation sheet; this manual is the language reference
- ARexx background — [Wikipedia: ARexx](https://en.wikipedia.org/wiki/ARexx)
- `mix help` · `mix what send` · `mix what emit` · `mix what address` (`on`/`reply` are handler forms `mix what` does not index)

---

<!-- page: https://mixos.dev/mix/capabilities/ (source: https://mixos.dev/mix/capabilities.md) -->

# Capabilities & embedding

Mix is two things at once: a **standalone shell** (where every builtin is allowed and the only limits are the self-protection caps) and an **embeddable interpreter** that daemons like `webd` and `maild` link as a library to run operator-authored scripts in-process. The second use case is why Mix has a **capability model**: a way to declare, per builtin, what *host authority* it exercises, so an embedder can hand a script a sandbox — "you may read the database and call JMAP, but not write files or spawn processes" — and have the evaluator enforce it before each call.

This page covers the `CapabilityClass` taxonomy (the exact enum), the `CategoryAllowList` policy embedders use, how shell syntax is gated, the resource caps that bound any single run, and the in-proc-trusted vs out-of-proc-untrusted embedding model. It is accurate to the Rust source at `mixos-lib-mix/src/builtins.rs` and `evaluator.rs` as of Mix 0.21.x.

> If you are just **writing scripts for the `mix` CLI**, you never see any of this — the standalone binary allows every class. The capability gate only fires when Mix is *embedded* and the embedder installs a policy. Read on if you author scripts that run inside a daemon, or if you embed Mix yourself.

## The nine capability classes

Every builtin carries exactly one `CapabilityClass`, **declared at its table entry** in `BUILTINS` / `HOFS` (the `builtin_table!` macro) — a single source of truth. Adding a builtin without naming its class is a *compile error*, not a silent `Pure`-default that would open a sandbox hole. (An older hand-maintained `match` failed open; the table-declared form fails closed.)

```rust
// mixos-lib-mix/src/builtins.rs
pub enum CapabilityClass {
    Pure,     // no host authority: string/number/collection/in-memory ops
    FsRead,   // reads the filesystem
    FsWrite,  // mutates the filesystem
    Network,  // talks to the network
    Process,  // controls other processes
    Env,      // reads host/environment info or stdin
    Db,       // host-injected database seam (mediated)
    Jmap,     // host-injected JMAP seam (mediated)
    Bus,      // host-injected delegated-Bus seam (mediated)
}
```

There are **nine** classes, no more — `Bus` is the newest, added in 0.20.3 for the delegated-Bus seam (below). (Mix has no separate `Random`, `Crypto`, or `Time` capability — `time`, `uuid`, `random_password`, `sleep`, and the hash/base64 builtins are all `Pure`: they compute over their arguments and carry no host authority worth gating.)

| Class | Meaning | Representative builtins |
|---|---|---|
| **Pure** | No host authority — pure functions over their arguments. **Always allowed.** | `length` `upper` `split` `join` `replace` `round` `sqrt` `json_parse` `markdown` `html_escape` `time` `uuid` `random_password` `sleep` `hash_sha256` and all the `map`/`filter`/`reduce` HOFs |
| **FsRead** | Reads or observes the filesystem. | `fs_watch` `fs_unwatch` `fs_wait` `read_file` `read_file_bytes` `read_lines` `read_json` `read_jsonl` `load_data` `exists` `is_file` `is_dir` `ls` `glob` `walk` `stat` `line_count` |
| **FsWrite** | Mutates the filesystem. | `write_file` `write_new` `append_file` `mkdir` `flock` `funlock` `chmod` `chown` `sqlopen` `sqlexec` `sqlclose` |
| **Network** | Talks to the network (arbitrary outbound). | `http_get` `http_post` `http_request` `dns_lookup` `ssh_run` `ssh_must` `ssh_mix` |
| **Process** | Controls other processes / process lifecycle. | `run` `run_rc` `run_stream` `spawn` `kill` `process_alive` `audio_watch` `audio_unwatch` `audio_state` `chdir` `exit` `panic` |
| **Env** | Reads host/environment info or stdin. | `env` `cwd` `hostname` `pid` `platform` `which` `net_watch` `net_unwatch` `net_state` `readline` `read_stdin` |
| **Db** | Host-injected, *mediated* database seam. | `db_query` `db_exec` |
| **Jmap** | Host-injected, *mediated* JMAP seam. | `jmap` `jmap_upload` |
| **Bus** | Host-injected, *mediated* delegated-Bus seam. | `bus_call` |

A few classifications are deliberate and worth knowing:

- **`panic` is `Process`,** not `Pure`. It is a real Rust `panic!`, **uncatchable** by Mix `try`/`catch` — a termination primitive a sandbox must be able to deny, exactly like `exit`. (In `--serve` mode the SPEC 18 §3.4 handler boundary isolates a panicking handler from the rest of the citizen.)
- **`chdir` is `Process`** (it mutates the process's working directory), not `FsRead`.

### Why `Db`, `Jmap`, and `Bus` are separate from `FsWrite` / `Network`

You could imagine folding `db_query` into `FsWrite` (it touches a SQLite file) and `jmap` into `Network` (it makes an HTTP call). They are kept distinct on purpose, because each is a **scoped, mediated seam the embedder controls** — not raw authority the script wields itself:

- The **`Db` seam** (`DbHandler`) is a database connection the *embedder opens and hands in*. Granting `Db` lets a CMS handler run `db_query`/`db_exec` against that one store **without** granting raw `FsWrite` (which would let it `write_file` anywhere). The raw file-level SQLite builtins (`sqlopen`/`sqlexec`) stay `FsWrite` — those *are* arbitrary filesystem authority.
- The **`Jmap` seam** (`JmapHandler`) is a single upstream the embedder configured. The script **never names a host**; its reach is only the embedder's one configured endpoint. Granting `Jmap` to a PIM handler lets it talk to *that* mail server without granting `Network` (arbitrary outbound HTTP to anywhere). This is the whole point of the seam — `jmap` is host-agnostic by construction.
- The **`Bus` seam** (`BusCallHandler`, installed via `set_bus_call_handler`) is a **delegated** Bus control-plane channel — deliberately **not** the raw broker (`BusHandler`, the `send`/`emit` keywords, which are gated `Bus` like `bus_call` since 0.89.0, so a policy that withholds `Bus` denies the bare forms too; a sandboxed handler still only *reaches* the mesh through the seam). The embedder bounds **which verbs** are reachable (a per-route exact-verb allowlist) and injects the **delegation envelope** — the authenticated actor, vhost, route — from *trusted request state*. The script calls `bus_call(verb, args)` and names **no host, peer, or actor**: it cannot forge identity or reach an unlisted verb. This is how a sandboxed webd handler calls a maild verb under the requesting user's delegated identity without holding broker authority.

This is the legibility win: an embedder grants the *narrow, mediated* thing (`Db`, `Jmap`, `Bus`) instead of the *broad, raw* thing (`FsWrite`, `Network`, the broker).

### The `bus_call` builtin

`bus_call(verb, args)` returns the verb's reply as a Mix value. Its checks run in a fixed order: the **capability gate fires first** (a policy that doesn't allow `Bus` denies the call before the handler is even consulted), then argument validation — `verb` must be a non-empty string; `args` is an optional map (omitted or `nil` means an empty map); the args must be JSON-encodable, so a function or raw-bytes value anywhere inside is rejected up front (the same footgun guard as `jmap`) — then the handler runs. A handler refusal (a verb not in the route's allowlist, an unreachable broker, an error rc from the peer) raises a **catchable** error, and the reply is bounded by the collection-size caps below.

With no handler installed — the standalone `mix` binary, a plain library embed — all three seam builtins exist but raise a catchable "not available" error:

```mix
try
  bus_call("mail.send", {to: "x"})
catch $e
  print("" .. $e)
end
```
```text
bus_call not available (no bus_call handler registered)
```

(`db_query` and `jmap` behave the same way: `database not available (no db handler registered)`, `jmap not available (no jmap handler registered)`. A seam builtin never silently no-ops.)

### Inspecting a builtin's class

The `capability_category(name)` function returns the class for any name (a non-builtin name returns `Pure` — it has no authority of its own, and the `is_builtin` gate rejects non-builtins before dispatch anyway). The descriptive *doc category* shown by `mix what` / `mix builtins` (string/math/io/system) is a **different axis** — it organises the help output and does not map 1:1 to `CapabilityClass`:

```text
$ mix what env
env: Get environment variable value

$ mix builtins system | head -3
system builtins:
  env             Get environment variable value
  time            Return current Unix timestamp as float
```

`time` and `env` are both in the `system` doc category, but their capability classes differ (`Pure` vs `Env`). The doc category is for humans browsing; the `CapabilityClass` is for the sandbox. The three seam builtins carry their own doc categories (`db`, `jmap`, `bus`) that are deliberately **absent** from the `mix builtins` category list — they are embedder-only surface, so `mix builtins db` reports an unknown category — but `mix what db_query` / `mix what bus_call` still describe them.

## CategoryAllowList — the ready-made policy

An embedder gates a script by installing a `CapabilityPolicy`. The shipped, batteries-included one is `CategoryAllowList`: it **always allows `Pure`**, plus an explicit allow-set of other classes, and **denies everything else**.

```rust
// mixos-lib-mix/src/builtins.rs
use std::rc::Rc;
use mixos_lib_mix::{CategoryAllowList, CapabilityClass};

// A CMS handler: may read files + use the mediated DB seam, nothing else.
let policy = CategoryAllowList::new(&[
    CapabilityClass::FsRead,
    CapabilityClass::Db,
]);
evaluator.set_capability_policy(Rc::new(policy));   // stored as Rc<dyn CapabilityPolicy>
```

With that policy installed, the evaluator consults `check_builtin(name)` **once per builtin/HOF dispatch, before the builtin runs**:

```rust
fn check_builtin(&self, name: &str) -> Result<(), String> {
    let class = capability_category(name);
    if class == CapabilityClass::Pure || self.allowed.contains(&class) {
        Ok(())
    } else {
        Err(format!("{name} requires {class:?} capability"))
    }
}
```

So under the policy above, `read_file(...)` and `db_query(...)` run, `upper(...)` runs (Pure is free), but `write_file(...)` fails with `capability denied: write_file requires FsWrite capability` and `http_get(...)` with `capability denied: http_get requires Network capability` — the evaluator prefixes `capability denied:` to whatever reason the policy returns, and raises it as a normal catchable runtime error. A daemon that wants finer control than "by class" — e.g. allow `read_file` but not `glob`, both `FsRead` — writes its own `CapabilityPolicy` and matches exact builtin names.

The trait is intentionally tiny — two methods, one with a default:

```rust
pub trait CapabilityPolicy {
    fn check_builtin(&self, name: &str) -> Result<(), String>;
    fn check_class(&self, class: CapabilityClass) -> Result<(), String> { /* default */ }
}
```

The standalone `mix` CLI installs **no** policy — every class is allowed and the only bounds are the resource caps below. That is correct: the operator running `mix script.mix` already has full authority on the host; gating it would be theatre.

## Gating shell syntax (the `check_class` escape hatch)

Here is the trap an embedder must not fall into: Mix's **shell syntax does not go through the builtin table**. `sh "..."`, the `$(...)` command substitution, `... | cmd` pipes, and a bare shell-dispatch line all spawn `/bin/sh` directly. A policy that only implemented `check_builtin` would gate `run(...)` but let `$(rm -rf /)` straight through — a sandbox escape.

So those constructs are gated through a **second seam, `check_class(CapabilityClass::Process)`**, before the shell runs. The evaluator calls it at every site that reaches process authority without a builtin name: `sh`, the `$()` command substitution, `… | cmd` pipes, a bare shell-dispatch line executed from a `source`d file, and the `export` statement (it mutates the process-global environment that every thread reads). A denial reads `capability denied: <construct>: <reason>` — e.g. `capability denied: sh: Process capability not allowed`. The trait's *default* `check_class` maps each class to a representative builtin (`Process` → `"run"`, `FsRead` → `"read_file"`, `FsWrite` → `"write_file"`, `Network` → `"http_get"`, `Env` → `"env"`, `Db` → `"db_query"`, `Jmap` → `"jmap"`, `Bus` → `"bus_call"`; `Pure` is always allowed) and reuses `check_builtin`, so a policy that only implements `check_builtin` **still gates shell execution correctly** — it can't accidentally leave the hole open. `CategoryAllowList` overrides `check_class` to gate against its allow-set directly:

```rust
fn check_class(&self, class: CapabilityClass) -> Result<(), String> {
    if class == CapabilityClass::Pure || self.allowed.contains(&class) {
        Ok(())
    } else {
        Err(format!("{class:?} capability not allowed"))
    }
}
```

`include` and `source` (which read a file off disk) are likewise gated as `FsRead` at the evaluator, not left ungated. The bare `send`/`emit` broker forms are gated `Bus` at their exec sites, and so are the **implicit sends an `address "target" … end` block's body lines desugar to** — a third dispatch site, not a path through `send` — and the **six evaluator-reserved Bus builtins** (`port_exists`, `bus_reconnect`, `noded_register`, `subscribe`, `unsubscribe`, `reply`), which sit outside the BUILTINS table and so failed class resolution open to `Pure` (all since 0.89.0 — before that all of these bypassed the policy entirely). The principle: **every path that reaches host authority is gated**, whether it is a named builtin or a piece of syntax. See [shell dispatch](shell-mode.md) for what `sh`/`$()`/pipes do and [Bus messaging](bus.md) for `send`/`emit`/`on`. For the one-expression embedding entry point that bakes this deny-set into a static pre-execution walk, see [expression evaluation mode](expr-eval.md).

## Resource caps — the self-protection limits

Capabilities answer *what authority*; resource caps answer *how much*. These are enforced **natively in the tree-walking evaluator** — there is no external sandbox engine, no added dependency. They protect even a naive embedder that never installs a policy, and they protect the standalone `mix` binary from a runaway script taking down the host. Three categories, plus a parser cap and per-builtin output caps.

### Call-recursion depth

Unbounded Mix recursion overflows the **native Rust stack** before any cooperative check can fire — an uncatchable SIGSEGV that takes the whole host process down. So unlike the others this knob is **finite by default** (`DEFAULT_RECURSION_LIMIT = 16`) — it must protect a naive embedder. Each consumer raises it for its own stack: the `mix` binary uses **128** on its ~8 MB main thread.

```mix
function f($n)
  if $n <= 0 then return 0 end
  return f($n - 1)
end
print(f(500))
```
```text
Runtime error at line 3: recursion depth exceeded (limit 128)
```

A clean catchable error, never a crash. An embedder running on a smaller stack (e.g. maild's per-message inbound filter on a tokio worker, where the async call path burns tens of KB per level and overflows around depth ~32) keeps the lower default so it fails *reliably* with this error rather than flakily overflowing.

### Wall-clock time, list / map / string size

`EvalLimits` carries the other knobs, all `None` (uncapped) by default and set via `set_limits`:

```rust
pub struct EvalLimits {
    pub recursion_limit: usize,            // depth knob (above)
    pub time_limit: Option<Duration>,      // wall-clock budget for one run
    pub max_list_len: Option<usize>,       // cap on any single list's length
    pub max_map_len: Option<usize>,        // cap on any single map's entries
    pub max_string_len: Option<usize>,     // cap on any single string's bytes
}
```

The **time budget** is checked at the per-statement poll, so a loop-based runaway is bounded; but a single blocking builtin (`run`, `ssh_run`, `http_*`) **cannot be interrupted mid-syscall** — the deadline fires at the next statement, not inside the syscall. Keep that in mind when budgeting an embedded handler that shells out.

### Parser nesting cap

The parser caps expression/statement nesting at **depth 200**, so deeply-nested input is a clean `ParseError`, not a stack-overflow abort — neither a login-shell line nor an embedded daemon can be crashed by `((((((...`:

```text
$ mix -c 'print(((( ... 210 deep ... ))))'
Parse error at line 1:202: nesting too deep (limit 200)
```

### Per-builtin output caps (always on)

Several builtins reject an oversized result with a normal runtime error rather than OOMing the process — independent of any policy, in the standalone binary too:

```mix
print(repeat("x", 300000000))
```
```text
Runtime error at line 1: repeat() result would exceed 268435456 bytes (256 MiB cap)
```

```mix
$r = range(1, 20000000)
```
```text
Runtime error at line 1: range() would produce 20000000 elements (cap 10000000)
```

- `repeat` / `lpad` / `rpad` (and the `_w` twins): **256 MiB** result cap.
- `range`: **10,000,000** elements.
- `http_get` / `http_post` / `http_request`: **64 MiB** response body (over-cap → `{status: 0, error}`).
- `substr` clamps an out-of-range length/offset rather than panicking.

## The embedding model — trusted in-proc vs untrusted out-of-proc

This is the load-bearing distinction, and the capability gate's honest scope.

> **An in-process capability gate is a *robustness* boundary for trusted scripts, not a *containment* boundary for untrusted code.** A compromise owns the address space the gate runs in. This is stated plainly in the source and in SPEC 18 §6: *"Not a sandbox."*

What that means in practice:

- **In-proc, trusted (the supported embedding).** A daemon links `mixos-lib-mix` and runs **operator- or agent-authored, reviewed** scripts in its own process — a webd CMS handler, a maild inbound filter, a Mix citizen daemon (SPEC 18). These scripts are the **same trust class as the Rust daemon itself**; they run under a real SPEC-10 UID (a registered serve-mode citizen takes a 600–699 identity UID; an unregistered transient citizen inherits its supervisor's 500–599 daemon UID). The `CategoryAllowList` here is **defence in depth** — it stops a *buggy* trusted script from doing something surprising (a filter that accidentally calls `run`), and it makes the script's authority **legible** ("this handler is FsRead + Db only"). It is not, and is not claimed to be, a wall against a malicious script.

- **Out-of-proc, untrusted (the only safe path for arbitrary code).** Genuinely untrusted or multi-tenant Mix must run in a **separate process** under OS-level isolation (its own UID, namespaces, cgroups, seccomp) — the maild/webd trust-split ADR. SPEC 18 §6 is explicit: *no in-process untrusted eval mode is specified or permitted.* The capability classes still apply inside that worker as defence in depth, but the real boundary is the process and the kernel, not the `CapabilityPolicy`.

And the standing rule for either mode — **WG-trusted ≠ caller-benign**: a Mix citizen reached over the trusted WireGuard mesh must still **validate inbound Bus request fields** before they parameterise a path, an exec, SQL, or an outbound call. Trust-domain membership bounds *who* can reach the handler; it does not make the request *content* safe. External exposure is mediated only — a citizen never binds a public port; it is reached from outside its broker solely through an explicit `webd` route + authz entry, default-deny. See [Bus messaging](bus.md) for the citizen runtime and `send`/`emit`/`on`.

### Choosing what to grant

A short decision guide for an embedder wiring up a `CategoryAllowList`:

- Start from **`Pure` only** (the default allow-set is empty) and add the *narrowest* class that lets the handler do its job.
- Prefer the **mediated seams** (`Db`, `Jmap`) over the **raw** classes (`FsWrite`, `Network`) wherever the handler's real need is "talk to *my* store / *my* upstream", not "arbitrary filesystem / arbitrary outbound".
- Grant **`Process` last and reluctantly** — it implies `run`, `spawn`, `kill`, `exit`, *and* all shell syntax (`sh`/`$()`/pipes). A handler that needs to shell out is a candidate for moving its logic into a builtin or out-of-proc worker.
- Remember `Process` also covers `panic` and `exit` — denying `Process` is what keeps a handler from terminating the host daemon.

## See also

- [shell dispatch](shell-mode.md) — `sh`, `$(...)`, pipes; gated as `Process`
- [Bus messaging](bus.md) — `send`/`emit`/`on`, the citizen runtime, handler seams
- [builtins index](builtins.md) — every builtin and its doc category
- [functions](functions.md) · [strings](strings.md) · [running commands](system.md)
- `mix what NAME` — one-line description of a builtin or keyword
- `mix builtins [CATEGORY]` — list builtins by (doc) category
- `mix help` — the `mix` command surface and CLI flags
- Source of truth: [`builtins.rs`](https://github.com/markc/mixos/blob/main/libs/mix/src/builtins.rs) (`CapabilityClass`, `CategoryAllowList`, `capability_category`), [`evaluator.rs`](https://github.com/markc/mixos/blob/main/libs/mix/src/evaluator.rs) (`CapabilityPolicy`, `EvalLimits`)
- [AGENTS.md](https://github.com/markc/mixos/blob/main/AGENTS.md) — the agent orientation sheet (this manual is the language reference)
- The [mix](https://github.com/markc/mixos) · [bus](https://github.com/markc/mixos) · [cos](https://github.com/markc/mixos) repos

---

<!-- page: https://mixos.dev/mix/cli/ (source: https://mixos.dev/mix/cli.md) -->

# cli — the `mix` meta-command

Inside the Mix REPL (and from the OS shell as `mix <subcommand>`) the bareword
**`mix`** is its own dispatcher: a built-in suite for introspecting the live
session, reading the language reference, building/testing the interpreter,
probing the Bus mesh, and driving AI-assisted workflows. It is *not* a Mix
builtin function — it is a command the shell intercepts before evaluation, so
you write `mix vars`, never `mix("vars")`.

Two execution contexts, one command surface:

- **From the OS shell** — `mix status`, `mix builtins math`, `mix what round`. The binary keeps an explicit allowlist of meta names and checks it *before* treating the argument as a script filename — so a script named `build` in the CWD is shadowed (run it as `mix ./build`). The session it reports on is the one that binary just started (so `mix vars` from a cold shell shows only the prelude functions), which makes the build/reference/mesh families useful while the *introspection* family is most meaningful inside a running REPL. `mix stats` also works here as a one-shot: every report names its window, and `mix stats coverage DIR` uses the real parser for static authorship coverage. See [usage statistics](stats.md).
- **Inside the REPL** — the same plus the **stateful** subcommands that need live REPL state: `time`, `trace`, `history`, `reload`, `diagnose` (and `stats` against the live in-session counters). Those live in the REPL loop, not `meta::dispatch`, because they need readline history, the trace flag, or the usage-stats handle. From the OS shell these names are *not* on the allowlist — `mix trace on` there is read as a script filename (`Error reading 'trace': No such file or directory`). After checking all meta names, the REPL also treats an existing first token as a script path: `mix FILE [args…]` runs it in a clean child process and returns to the same prompt. This is deliberately different from `source FILE`, which executes in and can modify the current session scope.

Bare `mix` prints the status overview **inside the REPL**; from the OS shell
it starts the REPL instead (use `mix status` there). Meta names win over CWD
files in both contexts, so `mix status` remains the status command even when a
file named `status` exists; use `mix ./status` to run that file. An unknown
non-file token inside the REPL prints
`mix: unknown meta-command '<token>' (and no such file)` on stderr and then the
subcommand overview (the `mix meta-commands:` listing); from the OS shell an
unknown name is tried as a script filename.

```mix
mix status
```

```text
mix 0.21.2
  pid:       50960
  uptime:    ?
  memory:    5776 kB
  variables: 0
  aliases:   0
  functions: 5
  scope:     1 frame(s)
  trace:     off
```

## Introspection — what is in the session

These read the live [scope](variables.md): variables, [aliases](shell-mode.md),
user [functions](functions.md), and the runtime config.

```
mix status      version + pid, uptime, RSS, var/alias/func counts, scope depth, trace
mix vars        every variable as `$name = value` (values over 60 chars truncated)
mix aliases     every alias as `name = expansion`
mix functions   every user function as `name(param, param)`
mix all         vars + aliases + functions under --- section headers ---
mix type NAME   classify NAME: builtin / keyword / alias / function / variable / PATH command
mix config      version, $HOME, prelude path, ~/.mixrc path, OS id, arch, pid
```

`mix type` resolves in the same order the evaluator does — builtin → keyword →
alias → user function → variable → `$PATH` command → not found:

```mix
mix type round
mix type ls
mix type bogusname
```

```text
round is a builtin function
ls is a builtin function
bogusname: not found
```

`mix functions` and `mix all` from a cold shell show the [prelude](builtins.md)
shims that ship in every session:

```mix
mix functions
```

```text
avg(list)
chars(s)
lines(s)
read_lines(path)
sum(list)
```

`mix config` is the quickest way to confirm which interpreter and rc file are in
play:

```mix
mix config
```

```text
version:  mix 0.21.2
home:     /home/user
prelude:  /home/user/.mixos/crates/mixos-lib-mix/std/prelude.mix
rc file:  /home/user/.mixrc
os:       linux
arch:     x86_64
pid:      50955
```

> `mix status` shows `uptime: ?` when run from the OS shell — the process has no
> recorded start instant for a one-shot invocation; inside a long-lived REPL it
> reports real uptime.

## Reference — learn the language

The reference family is self-documenting and verified against the binary, so it
never drifts from training data. Start broad with `mix help`, narrow with
`mix builtins CATEGORY`, pinpoint with `mix what NAME`, then read the full
prose with `mix man TOPIC`.

```
mix help              full categorized builtin reference + keyword list + subcommand map
mix keywords          every reserved word, one per line
mix builtins [CAT]    list builtins (derived signature + description); with a category, only that one
mix builtins --json   machine-readable contract table (metadata_schema 1 — see builtins.md)
mix builtins --data   same table as strict-data Mix source
mix builtins --names  bare name-per-line list
mix what NAME         one-line description of a builtin OR a keyword
mix man [TOPIC]       read a markdown manual page (no arg = the index)
mix syntax            shortcut for `mix man variables`
mix operators         shortcut for `mix man operators`
mix diff bash         bash → Mix translation cheatsheet
mix tutorial          guided walkthrough of the basics
mix examples          copy-paste-runnable snippets by category
```

`mix builtins` takes one of ten categories — `string type math list map io
system format json hof` — and prints each derived signature with its registered
description (signatures are generated from the structured contracts, 0.29.0):

```mix
mix builtins math
```

```text
math builtins:
  round(x[, n]) -> number          Round to nearest integer, half away from zero; round(x, n) to n decimal places (n<0 rounds to tens/hundreds) (v0.19.0)
  floor(x[, n]) -> number          Round down toward -inf; floor(x, n) to n decimal places (v0.19.0)
  ceil(x[, n]) -> number           Round up toward +inf; ceil(x, n) to n decimal places (v0.19.0)
  ...
  pi() -> number                   The constant π (v0.19.0)
  e() -> number                    Euler's number e (v0.19.0)
```

A bad category lists the valid set instead of failing silently:

```text
mix builtins: unknown category 'maths'
Categories: string, type, math, list, map, io, system, format, json, hof
```

All CLI/meta output is BrokenPipe-tolerant. If a downstream reader closes early,
Mix treats writes to that closed stream as normal and exits normally; it never
prints a Rust `Broken pipe` panic or exits `101`. For example, this is safe even though
`head` consumes only the start of the JSON report:

```text
mix builtins --json | head
```

The pipeline status remains the last command's status under ordinary shell
rules, so a successful `head` makes the pipeline successful.

`mix what` answers "what does this single name do?" for both builtins and
keywords from the same lookup:

```mix
mix what round
mix what send
mix what map
```

```text
round: Round to nearest integer, half away from zero; round(x, n) to n decimal places (n<0 rounds to tens/hundreds) (v0.19.0)
send: Send message to Bus port: send PORT "msg"
map: Return new list of transform(item) results (v0.2.0)
```

`mix apropos TERM` is the search when you *don't* know the name yet — one
case-folding substring pass across builtin names AND descriptions, keyword
names AND descriptions, and the manual's section headings, each hit saying
where to read more. It is the answer to "I need to pad a string but I don't
know it's called `lpad`":

```mix
mix apropos pad
```

```text
BUILTINS
  lpad  (string)  — Left-pad string to width (codepoint count; …) (v0.54.0)
  rpad  (string)  — Right-pad string to width (codepoint count; …) (v0.54.0)
  …
MANUAL SECTIONS
  mix man strings  § Padding with something other than a space
```

`mix what NAME` also falls through to this search when `NAME` is not an exact
builtin or keyword, so a near-miss surfaces the candidates instead of printing
`unknown` (v0.80.0).

`mix keywords` is the canonical reserved-word list — the names you cannot use
as function or variable *names* (`function step(...)` is an error). Since 0.21
a keyword IS accepted anywhere it is unambiguously a name — bare map keys
(`{label: 1, to: "x"}`), field access (`$m.to`), `send` kwargs — with the one
exception of `fn`, which lexes identically to `function` and still needs
quoting as a key. See [keywords](keywords.md).

```mix
mix keywords
```

```text
Mix reserved words:

  if
  else
  end
  for
  in
  while
  loop
  function
  fn
  return
  select
  ...
```

### `mix man` reads the manual built into the binary

`mix man TOPIC` prints the markdown page `TOPIC.md`. Every page in `docs/mix/`
is compiled into the `mix` binary (zstd-compressed, about a third of a
megabyte), so a binary copied alone to a new machine, with no checkout and no
network, still has its whole manual. The built-in copy is also the one that
documents exactly the binary you are running: a checkout or the online site may
be ahead of it or behind it.

Lookup order, with no `MIXOS_MAN_*` variable set:

1. **The built-in manual.**
2. **Files on disk**, for a page this binary does not carry: the installed
   share tree (`$MIXOS_SHARE/mix/man`), then a checkout's `docs/mix`
   (`$MIXOS`, else the root found above the running binary, else
   `~/Projects/mixos`).
3. **The online copy**, as in `auto` mode below.

No argument reads the index (`README.md`); an unknown topic lists the available
ones (the list excludes `README` itself):

```mix
mix man math        -- prints the math page from the binary
mix man             -- prints the index
mix man nope        -- "no manual page for 'nope'" + available topics
```

**Environment controls:**

- `MIXOS_MAN_SOURCE=local` — never use the network. Files on disk win (the
  share tree, then the checkout), then the built-in manual, then the cache.
  Use it while editing pages in a checkout, so your edits show before the
  binary is rebuilt.
- `MIXOS_MAN_SOURCE=auto` or `MIXOS_MAN_URL=<base>` — the online contract: a
  copy fetched within the last 24 h, else a fetch from `mixos.dev/mix` (or
  `<base>`; 2 s wall-clock budget, HTTPS-only, cached under your XDG cache
  dir), else files on disk, else the built-in manual, else a stale cached copy.

`mix doctor` reports how many pages are readable and how many are built in.
`mix syntax` and `mix operators` are thin aliases — `mix man variables` and
`mix man operators` respectively. To add a topic, drop `TOPIC.md` into
`docs/mix/`; the next build carries it, it publishes to `mixos.dev/mix` on the
next Pages build, and `mix man TOPIC` finds it with no code change.

### `mix diff bash`

A side-by-side translation table for anyone arriving from bash — it captures the
sharp edges directly (`$` sigils everywhere, `..` for concat, `end`/`done`/`next`
for block close, `$rc` instead of `$?`). `mix diff sh` is accepted as an alias;
any other language names the available set (`available: bash`):

```mix
mix diff bash
```

```text
Bash to Mix Translation Cheatsheet

Bash                               Mix
──────────────────────────────     ──────────────────────────────
VAR="value"                        $var = "value"
echo "$VAR"                        print $var
if [ -f file ]; then               if is_file("file") then
[[ -z $a ]]                        if $a == "" then
for i in 1 2 3; do                 for each $i in [1, 2, 3]
...
```

## Build — rebuild the interpreter from itself

The build family wraps `cargo` against the Mix source tree (`$MIXOS_SRC`,
default `$MIXOS`) so the REPL can rebuild and re-exec into a fresh binary —
the self-reconstruction surface. Point `$MIXOS_SRC` at the directory holding
the workspace `Cargo.toml` (in a clone of the public repo that is `mix/src`).

```
mix build       cargo build --release, then install target/release/mix → $MIXOS_BIN/mix
mix clean       cargo clean (removes the target/ tree)
mix update      git pull, then build + install
mix test        cargo test, streaming output
mix self check  syntax-check ~/.mixrc and std/prelude.mix without executing them
mix check FILE  syntax-check one .mix file (lex + parse, no execution)
```

`mix build` removes the destination first (a running ELF can't be written in
place — `ETXTBSY`), copies the new binary in, and — when run from the REPL —
saves history then `exec()`s into it, so the new interpreter replaces the old
process live. As a one-shot from the OS shell it installs and simply exits
(there is no REPL to restart). `mix update` is `git pull` then the same build.

`mix check` is a fast parse-only gate — perfect for a pre-commit hook or
validating a script before shipping it:

```mix
mix check /tmp/ok.mix      -- a well-formed file
mix check /tmp/bad.mix     -- an unterminated function header
```

```text
OK: /tmp/ok.mix
/tmp/bad.mix: Parse error at line 2:1: expected variable, got Eof
```

`mix self check` validates your two startup files. `~/.mixrc` is treated as a
hybrid Mix-plus-shell file (it tolerates bareword shell lines), while
`std/prelude.mix` must be strict, whole-file-valid Mix:

```mix
mix self check
```

```text
~/.mixrc: OK
std/prelude.mix: OK
```

(A `.mixrc` that mixes bareword shell lines with Mix reports
`OK (mixed shell+Mix)` — the per-line classifier validated every line.)

### `mix watch` — the edit-test loop

`mix watch PATTERN COMMAND` is a polling file-watcher: every 250 ms it scans
the current directory for files matching PATTERN and runs COMMAND (via
`sh -c`) when one changes, with a 500 ms debounce. Globs are simple — `*.ext`,
or `**/*.ext` to recurse (hidden directories and `target/` are always
skipped). Ctrl-C stops it.

```mix
mix watch '*.mix' 'cargo test'
```

## Diagnostics — measure and trace

### `mix doctor` — is this install healthy, and what am I talking to?

One command answering both questions, from the OS shell or the REPL. Each line
is `✓` (fine), `⚠` (a caveat, with the fix), or `✗` (broken, with the fix):

```
mix doctor
```

```text
mix doctor — mix 0.81.0

  ✓ version    0.81.0 · git 1a2b3c4d5e6f · built 2026-09-05T…Z
  ✓ features   json regex markdown toml serde datetime url crypto http sqlite archive dkim datastar xml yaml ws
  ✓ prelude    loaded (2 functions in scope)
  ✓ manual     33 page(s) readable
  ✓ stats      writable at /home/you/.local/state/mix
  ✓ bus        reachable at ws://…/ws

healthy — no ✗ checks
```

It **exits non-zero if any `✗` check fails**, so it gates: `mix doctor && deploy`.
The `features` line is the honest set THIS binary was compiled with (a slimmed
build reports fewer, never claims a capability it lacks); the `bus` line is a
bounded reachability probe — the whole connect runs on a worker thread capped at
~600 ms, so even a hostname endpoint with a dead resolver cannot hang it. Set
`MIX_DOCTOR_SKIP_BUS` to skip the probe entirely (the line then reads `—`), for
a hermetic run that touches no broker. The checks are deliberately local —
version/provenance, compiled features, prelude, manual (checkout **or** `mix man`
cache), stats-dir writability, and Bus — with no fleet awareness; that belongs
to the hub's tools. Only the `stats` check can fail hard (`✗`); an unreachable
Bus is a `⚠`, never a `✗`, so `mix doctor` still passes on a standalone box.

These need live REPL state (readline history, the trace flag, the stats
handle), so they are handled in the REPL loop rather than `meta::dispatch`.
Apart from `mix stats` — which also runs one-shot from the OS shell against
the on-disk data — they are **not** available as `mix …` from the OS shell.

```
mix trace [on|off]    per-statement tracing to stderr (no arg = report state) — see below
mix history [PAT]     show readline history, optionally filtered to lines containing PAT
mix reload            re-execute ~/.mixrc in the current session
mix diagnose [on|off] auto-send REPL errors to Claude for diagnosis (needs the claude CLI)
mix stats [SUB]       usage tracking — see below
```

### `time` — the timing modifier

`time` is a shell-dispatch **modifier**, not a meta-command: it wraps whatever
follows — an external command, a pipeline, a bareword function, or Mix code —
and reports elapsed time on stderr. Unlike the rest of this section it is NOT
REPL-only; it works under `-c` and over ssh too. Full semantics:
[shell-mode](shell-mode.md).

```mix
time sum([1, 2, 3, 4, 5])
```

```text
15
Elapsed: 0.012ms
```

`mix time EXPR` is the same modifier under its older spelling. Before 0.32.0 it
was a REPL-only meta-command that could time Mix code but not a command, and a
bare `time cmd` died with `time: No such file or directory` — bash's `time` is a
keyword, so there is no `time` binary for the classifier to find.

### `mix trace` — the statement tracer

`mix trace on` prints one line **to stderr** for every statement executed, in
the form `trace <file>:<line> <kind>` — in the REPL the file shows as
`<repl>`:

```mix
mix trace on
$x = 41
print($x + 1)
```

```text
Trace: on
trace <repl>:1 Assignment
trace <repl>:1 Print
42
```

Shell-dispatch lines are traced too, as `trace <repl> shell: <cmd>` —
external binaries, pipelines, `cd`, and whole `&&`/`||`/`;` chains (a chain
traces as one line, after alias expansion). The `mix …` meta-commands
themselves are excluded as REPL machinery, as is the prompt's own render.

The tracer is self-contained: no `RUST_LOG` needed, and `RUST_LOG` does
**not** enable it (a `tracing` subscriber exists only under `--serve`) — the
stderr line is the real channel. It is REPL-only: it cannot be armed under
`--serve` or from a non-interactive `ssh host '<mix>'`. Current state shows in
`mix status` (`trace: on|off`) and `mix context` (`"trace": true|false`);
`mix trace` with no argument reports it.

### `mix stats` — usage tracking

`mix stats` aggregates which builtins, functions, aliases, commands, keywords,
meta-commands, and error kinds you actually use — including a `never` report
of builtins/keywords you have never invoked. Data lives under
`$XDG_STATE_HOME/mix/` (default `~/.local/state/mix/`) as JSONL: one appended
record per run (`mix man stats`).
`query` runs SQL over an in-memory database built from it. `MIX_STATS=0`
disables the subsystem. Run `mix stats` for the top-20 overview, or a subcommand:

```
mix stats              top 20 most-used across all categories
mix stats builtins     per-builtin usage counts          mix stats never      never-used builtins/keywords
mix stats functions    user-function counts              mix stats sessions   session history
mix stats aliases      alias expansion counts            mix stats raw        current stats as JSON
mix stats commands     external-command counts           mix stats reset      reset current counters
mix stats keywords     keyword counts                    mix stats clear NAME remove NAME from every category
mix stats meta         meta-command counts               mix stats all        aggregate every weekly file
mix stats errors       error-kind counts                 mix stats week W     one week (e.g. 2026-W27)
mix stats trend NAME / since DATE / query SQL            SQLite history
```

## Files — `mix edit`, the one-line edit that refuses to guess

```
mix edit [--all] [-n|--dry-run] FILE OLD NEW
```

Replace **OLD** with **NEW** in **FILE**. OLD is matched *exactly* —
byte-for-byte, no pattern syntax, no delimiter to choose, nothing to escape.

This exists to remove the `sed -i` reflex, which was never about the language:
a one-line edit *from a prompt* had no Mix shape shorter than writing a `.mix`
file. So the contract is the opposite of `sed`'s on the two axes that actually
bite:

| | `sed -i 's/OLD/NEW/'` | `mix edit` |
|---|---|---|
| OLD is not present | exit **0**, file unchanged, says nothing | exit **1**, file unchanged, says so |
| OLD occurs twice | edits the first match **on every line** (all of them with `g`), silently | exit **2**, **writes nothing**, names every matching line |
| OLD contains `.` `*` `/` `[` | matches other text, or is a syntax error | a literal dot, star, slash, bracket |
| what changed | nothing printed | the changed line, as `-`/`+` |

```
$ mix edit src/main.rs "0.89.2" "0.89.3"
src/main.rs:3
- version = "0.89.2"
+ version = "0.89.3"
```

An ambiguous needle is a refusal, not a choice:

```
$ mix edit conf.mix "port = 8080" "port = 9090"
mix edit: conf.mix: OLD occurs 2 times; file unchanged
  conf.mix:4: port = 8080
  conf.mix:19: port = 8080
Pass --all to edit every occurrence, or give a longer OLD.
```

**Exit codes** — the reason this is a subcommand and not a meta-command
(meta-commands all exit 0):

| rc | meaning | file |
|---|---|---|
| 0 | edited | written |
| 1 | OLD not found | untouched |
| 2 | OLD occurs more than once and `--all` was not given | untouched |
| 3 | usage error, unreadable file, unwritable **directory**, non-UTF-8 input, or a file that changed since it was read | untouched |

(rc 3 is about the *directory*, not the file's own write bit: the edit is a
temp-file rename, so a read-only file in a writable directory is edited and
keeps its read-only mode.)

`--all` is the explicit opt-in to edit every occurrence. `-n` / `--dry-run`
reports the matches and writes nothing.

**Flags come first, then `FILE OLD NEW` verbatim.** Option parsing stops at the
first non-flag argument, so OLD and NEW can be any text at all —
`mix edit f.rs "=>" "->"` and `mix edit f.rs 1 -1` are ordinary edits, not
unknown options. `--` forces the switch early, for a FILE that starts with a
dash. A flag *after* FILE is a usage error that says so.

Other properties worth knowing:

- **OLD may span lines.** Pass a `"one\ntwo"` and the two-line block is one
  needle. The printed diff shows every line the edit touches, on both sides.
- **Overlapping candidates are not an ambiguity.** `aa` in `aaa` is one
  occurrence, because that is what the edit will actually replace — counting
  overlaps would refuse an edit that was never ambiguous.
- **The write is atomic.** A sibling temp file is created `O_EXCL` at 0600,
  written, fsynced, given the original's permission bits and renamed over it.
  An interrupted run leaves the old file intact, an edited script keeps its
  executable bit, and a pre-placed file or symlink at the temp path is refused
  rather than followed.
- **A symlinked FILE is followed.** The edit lands on the target and the link
  survives as a link — renaming over the link itself would silently replace it
  with a regular file and leave the real target stale.
- **A file that changed since it was read is refused** (rc 3, nothing written),
  so a concurrent edit or an editor save is a refusal rather than a silent
  overwrite. This narrows the race to the gap between the re-check and the
  rename; it is not a lock, and a writer landing inside that gap still wins.
- **`OLD == NEW` is a usage error** (rc 3), not a no-op, because it is
  invariably a mistake.

`mix edit` works at the interactive Mix prompt as well as from the OS shell;
there the exit code lands in `$status`.

In a script the nearest equivalent is [`replace()`](strings.md) — but it is
**silent** when the needle is absent, returning the input unchanged, so a
script doing this has to check the result itself.

## Ecosystem — probe the Bus mesh

These query the local [noded](bus.md) broker for its registered Bus service
roster (the mesh is TCP noded — `ws://<wg-ip>:4200/ws` — resolved the same way
the [`send`](bus.md) keyword resolves a target). All three fail fast with a 5 s
timeout so a stale broker address can't hang a diagnostic.

```
mix mesh          mesh status + the full list of services the local noded knows
mix ports         the registered Bus ports/services with a count
mix ping SERVICE  is SERVICE reachable? (`noded` itself is always the local broker)
```

```mix
mix mesh
```

```text
Bus mesh active via local noded (ws://192.0.2.10:4200/ws)
  dnsd
  indexd
  log
  webd
4 service(s) registered
```

```mix
mix ping webd
mix ping noded
mix ping nope
```

```text
webd: reachable (registered with noded)
noded: reachable (local broker)
nope: not found
```

When no broker is running the same commands degrade to a clean one-line message
(`No mesh — local noded not reachable (...)`) rather than an error.

There is also a small **orchestration** group: `mix deploy SVC`
(`systemctl --user restart mixos-SVC`), `mix health [SVC]` (probe Bus unix
sockets in `/run/bus`, falling back to `/tmp/bus`), and `mix logs SVC [-f]`
(`journalctl --user -u mixos-SVC`, last 50 lines; `-f`/`--follow` to stream).
These assume a systemd-user-managed MixOS install.

## AI-powered — agent-driven workflows

The AI family shells out to the Claude Code CLI (`claude -p "<prompt>"`); each
constructs a task prompt pointed at the Mix source tree. If `claude` is not on
`$PATH` they print an install hint and stop — they never alter anything on their
own.

```
mix fix DESC      read source, write a fix + test, run cargo test
mix extend DESC   implement a feature (tests first), run cargo test
mix review        git log / git diff HEAD~1, then a code review
mix explain NAME  explain how a builtin works from builtins.rs + evaluator.rs
mix evolve        pick the highest-value item from MIX_TODO.md and implement it
mix dogfood       write practical scripts, report awkward syntax / gaps
mix fuzz          generate random Mix to fuzz the parser/evaluator, report crashes
mix teach         build a tutorial .mix from the newest features
```

A related triad — `mix ask QUESTION` (one-shot Claude query with session context
injected), `mix chat` (interactive Claude with a Mix-aware system prompt), and
`mix context` / `mix snapshot` (export vars + functions + aliases + runtime info
as JSON) — feeds the live session into an agent. `mix context` is the
machine-readable companion to `mix all`:

```mix
mix context
```

```text
{
  "aliases": { ... },
  "current_line": 42,
  "cwd": "/home/user",
  "extensions": [ ... ],
  "functions": [ ... ],
  "pid": 50955,
  "scope_depth": 1,
  "trace": false,
  "variables": { ... }
}
```

Finally, `mix claude-start` / `mix claude-stop` / `mix claude-status` manage
the `mixos-claude` Bus port daemon (socket
`/run/user/<uid>/mixos/ports/claude.sock`): `start` spawns the binary
(searched in `$MIXOS_SRC/target/{release,debug}/`, then `$PATH`), `stop`
removes the socket, `status` probes it and flags a stale socket.

## Notes

### Native pane-shell status (stage A)

An S3-enrolled interactive shell answers `shell.status` on its existing,
broker-allocated pane-shell name and connection. It creates no extra service,
transport, builtin or legacy `--serve` handler. The resident remains responsive
while readline, Mix evaluation or a managed foreground child occupies the shell.
Non-attached shells allocate no status state, timers or worker threads.

The bounded JSON request (at most 2048 bytes) has `version: 1`, `target` and
no replay cursor. `target` contains `broker_epoch`,
`record` (`record_id`, `incarnation`, `binding_generation`), `instance_id`,
`pane_id` and `pane_generation`, exactly as supplied by current S3 discovery.
Unknown request fields, invalid versions and malformed values are refused.

Replies contain a versioned `status.snapshot`, capabilities and freshness
metadata. Snapshot phases follow these boundaries:

| Phase | Meaning |
|---|---|
| `starting` | Before ShellReady, including startup hooks |
| `idle` | After ShellReady, evaluation finish, or a line that ran nothing |
| `prompt-preparing` | Building the primary prompt, including custom `prompt()` |
| `prompt-ready` | Editor activated; `continuation` distinguishes secondary prompts |
| `evaluating` | An accepted line is being classified, expanded or evaluated, with a command ID |
| `foreground-child` | A foreground producer holds a bracket |
| `exiting` | Shell exit or replacement |

 Prompt generation increases for every new
primary or continuation prompt; `continuation` distinguishes them. Custom prompt
evaluation is `prompt-preparing` without a command ID; continuation prompts do
not enter that phase. An accepted line allocates its monotonic command ID at
acceptance, not at evaluation, so the window in which it is classified and
alias-expanded reports `evaluating` with that ID rather than `idle`. The ID is
retained through foreground waits, and cleared when the evaluation finishes or
when the line turns out to run nothing — an empty line, an incomplete
continuation or a parse error — which returns the phase to `idle`.
The foreground phase follows the job kernel's terminal lease for foreground
pipelines and `fg`, and brackets the existing synchronous `run_stream` spawn/wait.
This observation does not change `run_stream` job or signal semantics and does
not enumerate jobs.

The reducer supplies the owned editor's next prompt generation. Only its actual
Editing acknowledgement commits that value and prompt-ready; a deferred,
suspended or failed begin publishes nothing. Deferred foreground activation
commits exactly once, and later suspend/resume of the same prompt does not bump
it. `prompt_binding_generation` and `prompt_source` retain the identity supplied
at Begin, while `source` names the current attachment. Zero/null means the prompt
began before attachment. The full source plus prompt generation is required for
future admission; the editor's numeric binding component alone is not identity.
Legacy readline reports its entry boundary because it has no activation
acknowledgement. `cwd` is the last observed directory, captured at shell startup
and successful shell `cd` (including `cd -`, pushd/popd and sourced shell lines)
or Mix `chdir()` transitions. Failed changes preserve it. Paths are bounded to
4096 UTF-8 bytes with explicit truncation; unavailable observations are null.

The version-1 reply's `status` has exactly `snapshot`, `sampled_ms`,
`transition_age_ms` and `cwd_age_ms`. These times use the shared CLOCK_BOOTTIME
clock, in milliseconds since status-state creation, including time suspended;
they are not wall time. Admission lease-age comparisons use that same clock.
`sampled_ms`, `transition_age_ms` and `cwd_age_ms` state freshness at sampling;
delivery delay adds to those ages. A snapshot is information, never an execution
permit. No background polling of cwd, editor or evaluator occurs. Producers
commit owned transitions under a short state lock; transport, serialisation,
filesystem calls, evaluator calls and child waits occur outside that lock.
The 64-transition replay ring is internal in stage A. Replay cursors, gap
reporting and event delivery are deferred to stage B and absent from this v1
request/reply contract. Binding changes advance the same sequence. Historical
transitions retain their original source, while replies name the current source.

Admission uses BROKER-023 `read_state`: owning Term and explicitly scoped current
principals, plus independent same-UID verified owners under `default-open`.
Restricted policy denies ambient callers; cross-UID, TCP, unverified and sibling
principals receive the same bounded `REFUSED` response without status or target
details. Id-less notices never enter status admission or receive replies. Bound callers cannot fall back to ambient rights.
Correlated lease checks revalidate both caller and target at admission, and
detached residents do not dispatch requests. Admitting a session-bound caller
costs one lease check plus one re-read of the resident's own attachment: the
connection's broker epoch and connection id are fixed for its lifetime and are
taken once, not per check. Every session RPC serialises on that one connection,
so a renewal that loses its deadline to admission load is retried once with a
fresh deadline before the attachment is given up. Stale targets return
`STALE_GENERATION`. Recovery uses S3; it never resets shell sequence or prompt
generation. Jobs, signals, foreground/resume,
isolated tasks, input and event publication report `UNSUPPORTED`, never `BUSY`.
Evaluation submit and inspect report what this build can actually do — see
stage D below — and report `UNSUPPORTED` wherever it cannot.
The resident runs at most four admission tasks alongside its receive/renew/restart
loop, one of which is reserved for the pane's own Term: other same-UID callers
share three, so a flood by them cannot starve the owner into uniform refusals.
That reservation is a scheduling class only — the reserved slot re-runs the whole
admission policy like any other. Excess requests receive `REFUSED`; refusal writes
are polled alongside control rather than blocking it, including when the transport
has already dropped, so an admitted request is never answered with silence.
Restart cancels outstanding admission tasks.
The verified lane retains at most 64 commands of at most 64 KiB envelope/body.
Its reader task neither writes nor waits: an overflowed request is handed to the
receive owner, which writes that connection's `REFUSED`, and a dropped id-less
lifecycle notice raises a delivery gap the resident treats exactly as it treats
the broker's own lifecycle gap. Other clients retain their existing receive
configuration.

### Native pane-shell execution (stage D)

The same enrolled attachment answers `shell.execute`, `shell.execute.result`
and `shell.execute.cancel`. These are BROKER-023 `execute`, not `read_state`:
holding the capability that answers questions about the shell does not reach
them, and a caller without `execute` is refused before learning that the family
exists.

**Admission is empty-primary-prompt only.** A submission is admitted when the
shell is at `prompt-ready`, not a continuation, with an empty draft, no history
search, no paste in progress and no partially-decoded key — and when the
`prompt_generation` it names is the one actually at the prompt. Anything else
is refused, and the refusal discards nothing: a half-typed line is still there,
character for character, and finishing it runs the human's line.

| Situation | Answer |
|---|---|
| Empty primary prompt, generation matches | admitted |
| Half-typed draft, history search, paste in progress | `BUSY` |
| Continuation prompt | `BUSY` |
| Evaluating, foreground child, starting, exiting | `BUSY` |
| Custom `prompt()` still rendering | `BUSY` |
| Wrong prompt generation, or a target that is not this shell | `STALE_GENERATION` |
| No owned editor (the rustyline path) | `UNSUPPORTED` |
| Retention table full | `RESOURCE_LIMIT` |
| Same request id, different body | `CONFLICT` |
| Unauthorised, or the attachment lost mid-admission | `REFUSED` |

Nothing queues behind a busy shell. There is no state in which a submission is
accepted now and executed at some later prompt, because a caller cannot know
what the shell will be doing then — and a snapshot is information, never an
execution permit.

The admitted line is **visibly echoed before it runs**, through the editor's own
terminal, naming the principal and the command id:

```
mix: execute #7 admitted for Term ff86c6c7: print("hello")
```

The source in that line is escaped by a printable **allowlist**, not a blocklist:
anything outside ordinary printable text is rendered rather than emitted. That
covers the characters `is_control` does not report — bidi overrides and
isolates, zero-width joiners, the BOM, a soft hyphen, `U+2028`/`U+2029` — each
of which can reorder or hide what a reader sees without being a control code. A
submission is attacker-chosen bytes drawn into a terminal a human is reading,
and the allowlist means a new trick is escaped by default rather than passed
through by omission.

A source too long for one line is truncated with its tail NAMED:

```
mix: execute #7 admitted for PaneShell 9c1f via Term ff86c6c7: <head> …[+812 bytes, sha256:3ab19f04]
```

Nothing executes with an unannounced tail, and two submissions sharing a head
are still distinguishable. When a forwarder relays somebody else's submission
the announcement reads `<originator> via <forwarder>`: the shell authenticated
the forwarder, not the name it relayed, and the wording says so rather than
implying the shell verified it.

If the whole line cannot be put on the glass, the pane says
`announcement abandoned; nothing executed` instead — an announcement is
zero-or-whole, because a partial one reads exactly like a real admission.

**A reservation takes nothing away.** Between the moment the shell agrees to run
a submission and the moment it commits, the prompt is still live: still in raw
mode, still being read a byte at a time, still the human's. Any input at all
during that window — a single character, even one that edits nothing — ends the
reservation, and the submission is refused having announced nothing. The
terminal only changes hands at the commit itself, which is one atomic step:
reads stopped, cooked mode restored, announcement written, line executed. That
ordering is why a keystroke can never be painted into the announcement by kernel
echo, and can never arrive as the admitted execution's standard input.

Execution then follows the same path a typed line takes — the same classifier,
aliases, job integration and history policy — adopting the command id that was
minted, echoed and recorded before it started. Admission never opens a
continuation: a submission that turns out to be an incomplete line is refused
and the prompt is returned, because a remote execution may not leave a human
holding half of someone else's line.

`shell.execute` answers immediately with `{"state":"running","operation_id":…}`;
`shell.execute.result` returns that operation's state and, once it has one, its
result. Both it and `shell.execute.cancel` are scoped to the actor that
submitted — holding `execute` authorises driving the shell, not reading back
what somebody else drove it to do — and an operation belonging to another actor
is refused exactly like one that does not exist.

Retries are BROKER-018 idempotent: an identical submission under the same
request id replays the recorded answer rather than executing a second time.
**Request ids must be monotonic per caller.** A spent id stays spent even after
its record is gone (see the cap below), so reusing a lower id answers
`UNKNOWN_OUTCOME` rather than executing; callers going through Term get this
for free, because Term mints its own sequence, but a direct caller has to keep
its own counter.
**Fifteen minutes is the ceiling, not a promise.** The store holds 256
operations, and a busy shell reaches that long before it reaches the clock; the
oldest COMPLETED record is then evicted (a running one never is). What survives
eviction is a per-actor high-water mark, so a retry whose record is gone answers
`UNKNOWN_OUTCOME` rather than executing a second time — the id stays spent even
when its result no longer exists.

Three refusals are worth telling apart, because they are different facts:

* `BUSY` — nothing was announced and nothing ran. The request id is untouched
  and the same submission may simply be retried. This is the commonest refusal
  by design: a reservation is given up the instant the human touches the
  keyboard, so a busy pane produces it routinely.
* `UNKNOWN_OUTCOME` with `reason: admission_abandoned_before_execution` — proven
  that nothing ran, but the id is spent and its outcome recorded. Retrying it
  replays that; use a new id to try again.
* `UNKNOWN_OUTCOME` with `reason: admission_claimed_without_report` — the shell
  cannot say whether the line ran. The named `operation_id` stays resolvable, so
  `shell.execute.result` on it is how the caller finds out.

The result is serialised on the evaluator owner, so no interpreter value ever
crosses to the Bus thread:

```json
{"state":"finished","result":{
  "outcome":"completed",  "status":0,
  "value":{"type":"string","version":1,"bytes":"11","truncated":false,"text":"hello world"},
  "duration_ms":"3",
  "cancellation":{"requested":false,"delivered":"none"}}}
```

`outcome` is the execution's verdict and `value.truncated` is a property of how
much of the answer fitted. They are independent: a command that succeeded and
returned more than 16 KiB still succeeded.

### Isolated supervised tasks (P4)

`shell.task.submit` / `shell.task.result` / `shell.task.cancel` are the SECOND
execution mode, and almost everything above does not apply to them. An
evaluation runs inside the shell; a task is a separate process. It therefore
has no prompt to be admitted at — **BUSY is never a task refusal**, and a task
submitted while the human is mid-line runs anyway. That independence is the
point of the mode.

A submission carries exactly one of `source` (Mix text) or `argv` (program and
arguments, never a shell string); both or neither is `INVALID_ARGUMENT`. `cwd`
is required and must exist. `timeout_ms` is required, non-zero and capped at ten
minutes. There is no stdin in v1: the task gets `/dev/null`, and a
stdin-feeding task is a named future field rather than a silent absence.

**The environment is enumerated, not inherited.** A task starts from exactly:

    HOME  USER  PATH  LANG  TERM=dumb
    MIXOS  MIXOS_SRC  MIXOS_BIN  MIXOS_ETC
    MIXOS_NODE_CONFIG  MIXOS_BROKER_ACCOUNT

plus the caller's `env` overlay, which WINS on a name collision. Those values
are snapshotted when the shell STARTS, so a task sees the shell's startup PATH
and not whatever the shell has since set. Nothing else crosses: a variable the
shell sets at runtime does not reach a task, and the fixtures assert that as
whole-set equality rather than by spot-checking names.

**Termination is hard here, and it is the only hard guarantee in the surface.**
Cancel or timeout sends SIGTERM to the task's process GROUP, waits two seconds,
then sends SIGKILL. The reported outcome is read from `wait()`, never from the
fact that a signal was sent — a cancel request is still not proof a process
stopped, but the wait status is. The outcome names the POLICY that ended the
task (`timeout`, `cancelled`) with the signal beside it as `escalated_to`, so a
deliberate deadline is never presented as an indistinguishable external kill.

If the bounded termination ladder cannot obtain a final wait status, the
report says `unknown`; it never claims a successful exit from sending SIGKILL.
Since Mix 0.109.0, that report is published before waiting for eventual kernel
cleanup. The original supervisor keeps the child registered and retains its
native concurrency slot until reaping completes. Four pending supervisors
still exhaust the four-slot limit and further submissions receive
`RESOURCE_LIMIT`, even if their reports have already settled. Reaping retries
interrupted waits, and registry removal is synchronised with shutdown sweeping.

Between a cancel being accepted and `wait()` settling, `shell.task.result`
reports `state: "cancelling"` — a real state, so a caller that asked for
cancellation and reads `running` is not left wondering whether its request
arrived.

Streams are captured separately and exactly; this is the mode the manual points
to when interactive attribution is only best-effort. Each is capped at 64 KiB of
ENCODED text — what the reply actually costs, not what was read, because a NUL
costs one byte to capture and six to encode — with the REAL byte count and a
`truncated` flag reported, and truncation never turns a successful task into a
failed one.

A task's descendants can outlive it holding the inherited pipes open. Once the
supervisor has its outcome the drains get the same two-second grace and then
stop, and the stream reports `writer_survived: true`: the report says it stopped
listening rather than presenting a bounded read as the whole of the output.
Nothing waits on a process nobody is supervising, so a task that backgrounds a
ten-minute sleeper still settles at once and gives back its concurrency slot.

In `source` mode the value travels a dedicated descriptor rather than stdout —
see `--result-fd` below — so a task that prints and a task that returns are not
competing for one stream. `argv` mode has no interpreter value and says
`not_applicable` rather than presenting an absent one as a failure.

**Declared limits.** A task's lifetime is bounded by the shell's, through two
mechanisms because neither covers the other's case. `PR_SET_PDEATHSIG` binds the
task LEADER to the supervisor thread that forked it, which is what survives a
SIGKILL of the shell — no teardown hook runs then. But pdeathsig reaches the
leader alone, so a normal exit would leave the leader's own children running;
the shell therefore SIGKILLs every live task GROUP on its way out.

The declared residual is narrower than "any grandchild": a process that leaves
the task's group by calling `setsid` or `setpgid` for itself is outside both
mechanisms and survives. That is the orphan case, stated rather than dressed up
as a containment the implementation does not have.

`umask` and rlimits are inherited and are the operator's bound; the shell's own
bounds are the concurrency cap (four), the timeout, and 4 KiB each for `argv`
and the `env` overlay — sized to what the 8 KiB dispatch request can actually
carry, so each is a limit a caller can really provoke rather than decoration.
The two answer differently on purpose: an over-budget `env` overlay is
`RESOURCE_LIMIT`, because the overlay is a quantity of state the shell declines
to carry, while an over-budget `argv` is `INVALID_ARGUMENT`, because the command
line itself is malformed for this surface.

A spawn that fails is never `INVALID_ARGUMENT` — the request was well-formed,
and the failure happened after validation accepted it. Which code it does get is
decided by errno, because the two halves call for different responses. A program
that is not there, or a `cwd` that stopped being a directory between validation
and the fork, is `NOT_FOUND`: the caller named it and can correct it, and it is
deliberately the same code validation gives for a missing `cwd`, so one mistake
does not change its name depending on how fast the filesystem moved. Everything
else — out of descriptors, out of memory, out of processes — is `RESOURCE_LIMIT`
with `reason: "spawn_failed"`, which is the transient class: back off and retry.
Either way the request id stays unspent, and the error set stays closed, so a
caller can still switch on it exhaustively.

**Advertised deferrals**, refused explicitly rather than left to look like
typos: `shell.task.watch` and `shell.task.list` answer `UNSUPPORTED` with
`reason: "deferred"` — a bare code would be word-for-word what an unknown verb
gets back, which is not an advertisement of anything (v1 is poll-only, through
`shell.task.result`); there is no stdin feeding; there is no
reply chunking (the 64 KiB caps stand in for it); and a task has no Bus identity
of its own — it is supervised state inspectable through the owning shell, not a
mesh citizen.

#### `mix --result-fd N`

`mix --result-fd N -c <source>` writes the final expression value, encoded by
the interpreter's own strict-data serializer, to descriptor `N` as a
big-endian u32 length followed by exactly that many bytes. `N` must be above
stderr and must already be open; both are checked at startup and refused
loudly, because a task promised a structured result that silently produced none
is the failure with no symptom.

The flag must precede `-c`, which consumes the rest of the line as script
arguments, and it is refused outright without one: `-c` is the only mode that
produces a value to frame, so accepting the flag anywhere else would promise a
result that never arrives. Text streams are untouched: `-c` has never echoed its
final value to stdout, so stdout stays the program's own output and the value
travels the descriptor.

The whole frame is capped at 64 KiB, not just the value inside it. The value is
encoded once and then escaped again as it goes into the frame, so capping only
the inner encoding let a quote-heavy value produce a frame too large to read —
which the reader then saw as a writer killed mid-write. An oversized value comes
back as a truncated reference instead: the caller learns a value existed, and
how big it was.

An evaluation stopped by a signal writes an ERROR frame naming the signal and
exits non-zero. It has to: the interpreter catches SIGTERM for its own graceful
shutdown, and a supervisor ends a task with exactly that signal — so without
this, a cancelled task and one that genuinely returned nil produced identical
successful frames. (A plain `mix -c` with no result descriptor still exits 0 on
Ctrl-C; scripts depend on it, and that is not the case this rule is about.)

The length prefix is what makes four situations distinguishable that an unframed
stream collapses into one: nothing written at all (`result_missing`), a declared
length the payload does not satisfy because the writer was killed mid-frame
(`result_torn`), a partial frame the supervisor stopped waiting for because a
survivor still held the pipe (`result_abandoned`), and a complete frame whose
value reports that it was larger than the cap.

#### Cancellation, and what it is actually worth

`shell.execute.cancel` resolves one immutable evaluation identity. A request for
an evaluation that has already finished says so and signals nothing, so a
cancellation can never reach a successor evaluation — the failure mode the
single process-wide interrupt flag made inevitable. `SIGINT` is mapped the same
way: the signal records which evaluation was running when it arrived, so a
Ctrl-C at an idle prompt cannot trip the next line. A cancelled evaluation's
intent is sticky, so a Mix `try`/`catch` around cancelled work cannot swallow it
and run on.

Delivery is cooperative, and the table says only what is true:

| Path | Guarantee |
|---|---|
| Ordinary statements | cooperative, at the evaluator's existing checkpoints |
| Optimised native loops | cooperative, at the existing periodic check |
| Captured runners (`run_argv`, `run_pipeline`) | existing polling; the runner abandons its child |
| Managed interactive foreground job | **SIGINT to the process group**, via the job controller — the one path that does not depend on the target polling anything |
| `run_stream` | not interruptible while blocked in the child wait |
| `serve()` | **not covered**: its interrupt is a process-wide shutdown request, consumed by the pump's own exit rather than reported as a delivered cancellation |
| Blocking HTTP, filesystem and device calls; uncooperative extensions | **no pre-emption** |

The group signal is SIGINT and stops there. Escalating to `SIGTERM` and then
`SIGKILL` would need a grace period this shell does not run a clock for, and a
shell that escalated on its own would destroy work a human could still have
recovered with `fg`. The `cancel` reply reports `signalled_pgid` when a real
group signal went out, so a caller can tell the two strengths apart rather than
having to assume.

What cannot be promised is not promised: arbitrary builtin pre-emption,
rolling back side effects, killing threads, or terminating descendants after
they detach. Bounded termination of uncooperative work needs a separately
supervised process, which by construction cannot inherit or mutate this shell's
scope. `cancel` reports `requested`, `already_finished` or `unknown`, and a
finished evaluation's report distinguishes `cancelled` from `completed_anyway`.

Noninteractive shells, `--serve`, `mix -c` and any shell without an attachment
carry none of this: no surface is registered, no admission state is allocated,
no result store exists, and `serve`'s process-wide shutdown semantics are
untouched. One thing is NOT unchanged, and it applies to every Mix process: the
SIGINT handler now also records which evaluation a signal was aimed at, so
`interrupt::init` registers one additional chained handler. Two relaxed atomic
stores, no allocation, no behaviour change to what the signal does — but it is a
difference, and "byte-identical" would have been a claim this page could not
back.

- `mix` is intercepted by the shell, so it never sees `$`-sigil arguments — write `mix what round`, not `mix what $name`.
- The introspection family (`vars`/`aliases`/`functions`/`all`/`context`) is most useful **inside a REPL**, where the session has accumulated state; from a one-shot OS-shell invocation it reports only the freshly-loaded prelude.
- The diagnostics family (`time`/`trace`/`history`/`reload`/`diagnose`) is REPL-only — those names are not on the OS-shell allowlist, so `mix trace on` there is read as a script filename. The one exception is `mix stats`, which has a dedicated one-shot OS-shell path against the same on-disk data.
- Paths follow the MixOS layout: source at `$MIXOS_SRC` (default `$MIXOS`), installed binaries at `$MIXOS_BIN` (default `~/.local/bin`, or `/usr/local/bin` when running as root).

## See also

- [the manual index](README.md) — every page `mix man TOPIC` can read
- [variables](variables.md) — the `$`-sigil scope `mix vars` reports on
- [functions](functions.md) — what `mix functions` lists
- [shell-mode](shell-mode.md) — the alias/classifier layer behind `mix aliases` and `mix reload`
- [invocation](invocation.md) — the `mix -c` / `mix -` / `--serve` entry points around this command
- [keywords](keywords.md) · [operators](operators.md) · [math](math.md) — topics readable via `mix man TOPIC`
- [Bus messaging](bus.md) — the `send`/`emit`/`address` mesh `mix mesh`/`ports`/`ping` probe
- [builtins index](builtins.md) — the full builtin catalogue behind `mix builtins`
- The public repo: [github.com/markc/mixos](https://github.com/markc/mixos)

```
mix help          full categorized reference + the complete subcommand map
mix what NAME     one-line description of any builtin or keyword
mix man TOPIC     read a full manual page (mix man with no arg = the index)
```

---

<!-- page: https://mixos.dev/mix/collections/ (source: https://mixos.dev/mix/collections.md) -->

# collections — lists & maps

Mix has two compound data types: the **list** (an ordered, 0-indexed sequence)
and the **map** (an ordered key→value table, insertion order preserved). Both are
first-class values — store them in variables, nest them, pass them to functions,
return them, iterate them, and serialise them with [data](data.md). Most list +
map builtins live in the `list` and `map` categories — list them live with
`mix builtins list` / `mix builtins map` — but a few multi-type ones
(`contains`, `reverse`, `length`/`len`) sit in the `string` category since they
also operate on strings, so `mix builtins list` won't show every name used here.
Get one-line help for any name with `mix what NAME`.

> One-line model: **lists are `[a, b, c]` 0-indexed (negatives count from the
> end, for reads AND writes); maps are `{key: value}` read with `.key` or
> `["key"]`. `push`/`pop`/`shift` and index-assignment mutate in place; everything
> else returns a fresh copy. Lists pass into functions by value, and
> `List == List` **raises** — use `deep_eq(a, b)`.**

## Literals & printing

```mix
$nums = [10, 20, 30]
$user = { name: "ada", age: 36 }
print("" .. $nums)
print("" .. $user)
print("" .. [])
print("" .. {})
```
```text
[10, 20, 30]
{name: ada, age: 36}
[]
{}
```

A list literal is `[`…`]` with `,`-separated elements; a map literal is `{`…`}`
with `key: value` pairs. **Map keys are bare identifiers, keyword lexemes, or
string literals** — `{ name: "ada" }` and `{ "name": "ada" }` are the same map.
Since 0.21 a [keyword](keywords.md) is accepted as a bare key wherever it is
unambiguously a name: `{ label: 1, to: "x", on: true, parse: 2 }` all parse, and
the same keywords work in dot-field reads and writes (`$m.to`, `$m.label = 2`).
The **one exception is `fn`** — it lexes to the same token as `function`, so it
needs the quoted key `{ "fn": 1 }` and bracket access `$m["fn"]` (`.fn` is a
parse error).

**Map keys are always strings.** A bare *number* is not a valid literal key —
`{ 22: "ssh" }` is a parse error; quote it (`{ "22": "ssh" }`). Indexing with a
number coerces to the key's string form, so `$m[22] = "ssh"` stores key `"22"`
and `$m[22]` / `$m["22"]` both read it back.

Elements and values are any Mix value, so nesting is free:

```mix
$cfg = { server: { host: "node1", ports: [80, 443] }, tls: true }
print("" .. $cfg)
```
```text
{server: {host: node1, ports: [80, 443]}, tls: true}
```

Note the print form is **debug-ish, not round-trippable**: strings inside a
container print *without* quotes (`[a, b]`, not `["a", "b"]`). For a parseable
representation use [`data_encode`](data.md) / `json_encode`.

## Indexing

Lists are **0-indexed**. A **negative** index counts from the end (`-1` is the
last element). An **out-of-range** index returns `nil` (never an error) — the
same three rules hold for a string (yielding a one-character string) and, since
**v0.64.0**, for `bytes`/`buffer` (yielding the byte as a **number** 0-255; see
[io](io.md#bytes-as-a-sequence-v0640)):

```mix
$l = [10, 20, 30]
print($l[0])
print($l[2])
print($l[-1])
print($l[5])
```
```text
10
30
30
nil
```

Maps are read with **dot** (`$m.key`) or **bracket** (`$m["key"]`) syntax; they
are equivalent. Use the bracket form when the key is computed or held in a
variable, or when it isn't a bare identifier. A **missing key** returns `nil`:

```mix
$m = { name: "ada", age: 36 }
print($m.name)
print($m["age"])
print($m.missing)
$k = "name"
print($m[$k])
```
```text
ada
36
nil
ada
```

### The `"*"` wildcard key

If a map has a key `"*"`, an indexing miss falls back to that value instead of
`nil`. Handy for default/catch-all tables (e.g. a port→service map — note the
quoted numeric keys, and that the numeric index `80` coerces to the string key
`"80"`):

```mix
$svc = { "22": "ssh", "80": "http", "*": "unknown" }
print($svc[80])
print($svc[12345])
```
```text
http
unknown
```

### Footgun: `pos` is 1-based, indexing is 0-based

`index_of` (and list/`substr` indexing) are **0-based**; the string-search
builtin `pos` is **1-based** and returns `0` for "not found". Don't mix them up:

```mix
$fruits = ["apple", "pear", "plum"]
print("index_of (0-based): " .. ("" .. index_of($fruits, "pear")))
print("index_of miss: " .. ("" .. index_of($fruits, "fig")))
print("pos (1-based): " .. ("" .. pos("pear", join($fruits, " "))))
```
```text
index_of (0-based): 1
index_of miss: -1
pos (1-based): 7
```

`index_of(list, value)` → 0-based index, or **-1** when absent. `pos(needle,
haystack)` is a *string* op (see [strings](strings.md)) — 1-based, **0** when
absent.

## Iterating

`for each` walks a list directly. Over a **map** with ONE variable it yields
the **keys** (in insertion order) — `for each $k in $m` and
`for each $k in keys($m)` are equivalent; look values up with `$m[$k]`. With
**two** variables it yields **(key, value)** since 0.68.0, so no lookup is
needed:

```mix
$ports = [22, 80, 443]
for each $p in $ports
  print("- port " .. ("" .. $p))
end

$m = { host: "node1", port: 8080, tls: true }
for each $k in $m
  print($k .. " = " .. ("" .. $m[$k]))
end
```
```text
- port 22
- port 80
- port 443
host = node1
port = 8080
tls = true
```

Over a **string** `for each` yields one-character strings, and since **v0.64.0**
over a `bytes`/`buffer` it yields the bytes as **numbers** 0-255 (see
[io](io.md#bytes-as-a-sequence-v0640)). Every source is materialised at loop
entry, so mutating it in the body never extends the loop.

A **second variable** binds the position for a list, string or bytes, and the
**value** for a map — see
[control-flow](control-flow.md#two-variables-over-a-map-bind-key-value--changed-in-0680)
for the 0.68.0 change and what stayed put.

For value-producing transforms prefer a [hof](hof.md) (`map`/`filter`/`reduce`/
`sort_by`) over a hand-rolled `for each` + `push`.

## Length & emptiness

`length` (alias `len`) returns the **element count** for a list and the
**key count** for a map (for a *string* it counts codepoints — see
[strings](strings.md); for a **`bytes`/`buffer`** it counts bytes, v0.64.0 —
see [io](io.md#bytes-as-a-sequence-v0640)). `is_empty` tests for zero length:

```mix
print("" .. length([10, 20, 30]))
print("" .. len({ a: 1, b: 2 }))
print("" .. is_empty([]))
print("" .. is_empty({ a: 1 }))
```
```text
3
2
true
false
```

## Mutating builtins (in place)

Three builtins **mutate the list in place**. `push` appends and **returns
`nil`**; `pop`/`shift` remove and **return the removed element** (or `nil` on an
empty list).

```mix
$l = [1, 2, 3]
push($l, 4)
print("after push: " .. ("" .. $l))
print("pop -> " .. ("" .. pop($l)))
print("shift -> " .. ("" .. shift($l)))
print("now: " .. ("" .. $l))
```
```text
after push: [1, 2, 3, 4]
pop -> 4
shift -> 1
now: [2, 3]
```

### Footgun: what `push` mutates depends on what you hand it

`push`/`pop`/`shift` reach the list **through the variable slot**. That makes
their behaviour shape-dependent, and it is the single most-tripped-over corner in
Mix:

- **First argument is a bare variable** (`push($l, 3)`) → mutates `$l` in place, and `push` **returns `nil`**. So `$l = push($l, 3)` ✗ clobbers `$l` to `nil`. Call it as a statement: `push($l, 3)` ✓.
- **First argument is anything else** — `push($m["a"], 3)`, `push($m.a, 3)` — there is no slot to mutate, so it appends to a **copy** and returns the new list. A bare `push($m["a"], 3)` therefore does **nothing at all**: the write is lost, silently. Assign the result back instead: `$m["a"] = push($m["a"], 3)` ✓.

Since 0.33.0 `mix lint` catches the dead form as **MIX-E1501**, and the same
release lets you skip the idiom entirely for maps of maps by writing the nested
assignment directly (see [Nested assignment](#nested-assignment)).

```mix
$l = [1, 2]
print("push returns: " .. ("" .. push($l, 3)))
$m = { a: [1] }
$m["a"] = push($m["a"], 2)
print("" .. $m)
```
```text
push returns: nil
{a: [1, 2]}
```

### Index-assignment

Assigning to an index mutates in place. **Maps auto-create** the key (so this is
how you build a map incrementally) — via bracket (`$m["a"] = 1`) or single-level
dot (`$m.b = 2`), which are equivalent. **List writes resolve signed indices
exactly like reads**: a negative index writes from the end (`$l[-1] = v` sets the
last element):

```mix
$m = {}
$m["a"] = 1
$m.b = 2
print("" .. $m)

$l = [10, 20, 30]
$l[1] = 99
$l[-1] = 77
print("" .. $l)
```
```text
{a: 1, b: 2}
[10, 99, 77]
```

**Out-of-range and mistyped list writes are loud errors** (since 0.20.5 — they
were previously silent no-ops, and a negative write corrupted element 0):

- an out-of-range index (either direction) raises `list index 7 out of range (length 3)` — a lost write is data loss; use `push` to grow a list;
- only a **number** indexes a list on write — `$l["a"] = v` raises `cannot index list with string`; a NaN/infinite index is rejected too;
- index-assigning into a scalar (`$x = 5` then `$x[0] = 1`) raises `cannot index-assign into number` — and since 0.33.0 the **dot form raises too** (`$x.f = 1` previously discarded the write in silence).

This is a **deliberate read/write asymmetry**: a missing *read* still returns
`nil` (safe default), a missing *write* errors (silent data loss).

### Nested assignment

Since 0.33.0 an assignment target may carry **any number of accessors**, in any
mix of `.field` and `["key"]`, over maps and lists alike:

```mix
$m = {}
$m["u"]["k"] = 1
$m.a.b.c = "deep"
$l = [[1, 2]]
$l[0][1] = 99
print("" .. $m)
print("" .. $l)
```
```text
{u: {k: 1}, a: {b: {c: deep}}}
[[1, 99]]
```

This is not sugar for the old read-mutate-write-back dance: it walks the path and
mutates **in place**, so building a map of maps is linear where the workaround was
quadratic (it deep-copied the inner container on every write).

**A missing or `nil` intermediate is auto-created as a map** — but only when the
next accessor is a name or a string key, which is the only case where the intent
is unambiguous:

- `$m["g1"]["k"] = 1` on an empty `$m` creates `$m["g1"] = {}` first ✓
- `$m["a"][0] = 1` **raises**: `[0]` could mean a list slot or the map key `"0"`, and guessing would freeze one interpretation into your data. Assign an explicit `[]` or `{}` first.

**Nothing else is auto-created, and nothing is auto-overwritten:**

- an existing scalar intermediate raises (`$m = { a: 5 }` then `$m["a"]["b"] = 1` → `cannot index-assign into number at $m[a]`) — a map is never dropped on top of your data;
- **lists never extend**, at any depth — `$m["a"][5] = 9` on a 1-element list raises, exactly as a single-level write does;
- the `"*"` wildcard is a **read** fallback only: `$m.missing.k = 1` creates `missing`, it does not mutate `$m["*"]`.

**A failed nested write creates nothing.** The path is validated before it is
touched, so a write that dies halfway leaves no half-built maps behind — which
matters because `catch` can resume after it.

## Pure list builtins (return a copy)

Every builtin below leaves its argument **unchanged** and returns a **new** list.

### sort / unique / reverse

```mix
print("" .. sort([3, 1, 20, 2]))
print("" .. unique([1, 2, 2, 3, 1]))
print("" .. reverse([1, 2, 3]))
```
```text
[1, 2, 3, 20]
[1, 2, 3]
[3, 2, 1]
```

> **`sort` orders a homogeneous number list numerically; everything else is
> lexicographic.** A list whose every element is a number sorts by value
> (`sort([2, 10, 1, 20])` → `[1, 2, 10, 20]`). A list of strings — or a *mixed*
> list — compares by the **string** form of each element instead, so
> `sort([2, "a", 1])` → `[1, 2, a]`. For any other key (a map field, a computed
> value, descending order) use [`sort_by`](hof.md):

```mix
print("numbers:  " .. ("" .. sort([2, 10, 1, 20])))
print("strings:  " .. ("" .. sort(["banana", "apple", "cherry"])))
print("by field: " .. ("" .. sort_by([{p: 80}, {p: 22}], fn($r) = $r["p"])))
```
```text
numbers:  [1, 2, 10, 20]
strings:  [apple, banana, cherry]
by field: [{p: 22}, {p: 80}]
```

`unique` removes duplicates **keeping first-seen order**. `reverse` works on a
list, a string, or (since v0.70.0) a bytes/buffer value (byte-wise, returning
a new value-semantic `bytes`).

### contains / index_of

```mix
$l = ["x", "y", "z"]
print("" .. contains($l, "y"))
print("" .. contains($l, "q"))
print("" .. index_of($l, "z"))
print("" .. index_of($l, "q"))
```
```text
true
false
2
-1
```

`contains(list, v)` → bool (it also accepts a *string* haystack, and since
0.70.0 a *bytes/buffer* subject with a byte needle — but **not** a map; use
`has_key` for maps). `index_of(list, v)` → 0-based position or `-1` (also
string and, since 0.70.0, bytes/buffer — see [io](io.md) for the byte-unit
rules).

### range

`range(start, end)` is **inclusive of both ends**, with an optional step. Step
direction must match the start→end direction or you get an empty list. A step of
`0`, or a range over 10M elements, errors.

Bounds and step must be **whole numbers within the i64 range** (fractional,
non-finite, or beyond ±2^63 raises `VALUE_OUT_OF_RANGE` naming the argument).
Before 0.59.0 an oversized bound silently saturated: `range(1e30, 1e30)`
answered `[9223372036854775807]` — a value the caller never wrote.

All supplied bounds and the optional step must coerce to numbers. Numeric
strings remain valid (`range("1", "3")` → `[1, 2, 3]`); an unparseable value
raises `TYPE_MISMATCH` with its argument position instead of silently becoming
`0` (or `1` for step).

```mix
print("" .. range(1, 5))
print("" .. range(0, 10, 2))
print("" .. range(5, 1, -1))
print("" .. range(5, 1))
```
```text
[1, 2, 3, 4, 5]
[0, 2, 4, 6, 8, 10]
[5, 4, 3, 2, 1]
[]
```

### flat

`flat` recursively flattens nested lists into one flat list:

```mix
print("" .. flat([1, [2, 3], [4, [5, 6]]]))
```
```text
[1, 2, 3, 4, 5, 6]
```

### concat

`concat($a, $b, …)` joins **2+ lists** into one new list, **one level deep** —
unlike `flat`, it does not recurse into nested elements, so a list *of lists*
(or of maps) is concatenated without disturbing the inner structure:

```mix
print("" .. concat([1, 2], [3, 4], [5]))
print("" .. concat([[1, 2]], [[3, 4]]))
```
```text
[1, 2, 3, 4, 5]
[[1, 2], [3, 4]]
```

It returns a fresh list and mutates nothing — the clean, O(total) way to
**accumulate a sequence across helpers** under Mix's by-value list model: a
helper returns its items, the caller `concat`s them in, sidestepping the
[`push($param, …)`-into-a-copy trap](#footgun-lists-pass-into-functions-by-value)
entirely. Each argument must be a list (a non-list arg is a loud error); pass at
least two.

### slice / take / drop

`slice(list, start[, end])` returns the half-open range `[start, end)`. **End is
exclusive**; omit it (or pass `nil`) to slice to the end. Negative indices count
from the end, and all bounds **clamp** (out-of-range never errors):

```mix
$l = [10, 20, 30, 40, 50]
print("" .. slice($l, 1, 3))
print("" .. slice($l, -2))
print("" .. slice($l, -100, 100))
```
```text
[20, 30]
[40, 50]
[10, 20, 30, 40, 50]
```

`slice` also accepts a **string** (`slice("hello", 1, 3)` → `"el"`, counting
codepoints — see [strings](strings.md)) and, since **v0.64.0**, a
**`bytes`/`buffer`** value (counting bytes, returning a new value-semantic
`bytes` — see [io](io.md#bytes-as-a-sequence-v0640)). A **reversed** range is
empty in every case: `slice($l, 3, 1)` is `[]`, not a wrap-around.

`take(list, n)` keeps the **first** `n` (negative `n` → **last** `|n|`);
`drop(list, n)` skips the **first** `n` (negative `n` → drops the **last**
`|n|`). Both also accept a string (codepoints) and, since **v0.70.0**, a
bytes/buffer value (bytes → a new value-semantic `bytes`):

```mix
$l = [10, 20, 30, 40, 50]
print("take 2:   " .. ("" .. take($l, 2)))
print("take -2:  " .. ("" .. take($l, -2)))
print("drop 2:   " .. ("" .. drop($l, 2)))
print("drop -2:  " .. ("" .. drop($l, -2)))
```
```text
take 2:   [10, 20]
take -2:  [40, 50]
drop 2:   [30, 40, 50]
drop -2:  [10, 20, 30]
```

### zip

`zip(a, b)` pairs corresponding elements into 2-element lists, stopping at the
shorter input. Destructure each pair with `[0]` / `[1]`:

```mix
print("" .. zip([1, 2, 3], ["a", "b"]))
for each $pair in zip(["host", "port"], ["node1", 8080])
  print($pair[0] .. " = " .. ("" .. $pair[1]))
end
```
```text
[[1, a], [2, b]]
host = node1
port = 8080
```

## Pure map builtins

### keys / values / has_key

```mix
$m = { host: "node1", port: 8080, tls: true }
print("" .. keys($m))
print("" .. values($m))
print("" .. has_key($m, "port"))
print("" .. has_key($m, "user"))
```
```text
[host, port, tls]
[node1, 8080, true]
true
false
```

`keys`/`values` return lists in **insertion order**. `has_key(map, key)` is the
map-membership test — remember `contains` does **not** accept a map and will
raise `contains() expects a string, list, bytes or buffer`.

### merge / delete

Both are **non-mutating** — they return a new map and leave the original alone.
`merge(a, b)` overlays `b` onto `a` (b wins on conflicts); `delete(map, key)`
returns a copy without that key.

```mix
$base = { host: "node1", port: 8080 }
$out = merge($base, { port: 9090, tls: true })
print("merged: " .. ("" .. $out))
print("original: " .. ("" .. $base))
print("deleted:  " .. ("" .. delete($base, "port")))
print("still:    " .. ("" .. $base))
```
```text
merged: {host: node1, port: 9090, tls: true}
original: {host: node1, port: 8080}
deleted:  {host: node1}
still:    {host: node1, port: 8080}
```

## `List == List` raises (0.68.0) — use `deep_eq`

`==` and `!=` raise `TYPE_ERROR` when **both** operands are a map or list —
including a self-compare (`$a == $a`) and a list-vs-map cross-compare.

Until 0.68.0 they answered `false`/`true` instead — always, regardless of
contents. That is not a comparison; it is a constant wearing a comparison's
clothes, and it read as working code right up until someone depended on it.
The raise names the fix:

```
TYPE_ERROR: `==` is not defined for list and list — it would always answer
false, not compare them. Use deep_eq(a, b) for structural comparison
```

**Use `deep_eq(a, b)` (0.63.0)** — structural equality: maps compare by key
set with insertion order ignored, lists elementwise in order, scalars as
`==`:

```mix
print(deep_eq([1, {x: 2}], [1, {x: 2}]))   -- true
print(deep_eq({a: 1, b: 2}, {b: 2, a: 1})) -- true (map order ignored)
print(deep_eq([1, 2], [2, 1]))             -- false (list order matters)
```

Scalars compare as `==`, with the corners that implies: a **function**
value is never equal — even to itself, so a callback-bearing map is not
`deep_eq` its own copy — and Buffer-vs-Bytes is false (`freeze()` first).
Nesting deeper than 512 levels raises (catchable) rather than recursing
unboundedly.

Or compare a derived value (length, `join`, an element) — those are scalars,
so `==` applies normally:

```mix
$a = [1, 2, 3]
$b = [1, 2, 3]
print("deep_eq:       " .. ("" .. deep_eq($a, $b)))
print("same length:   " .. ("" .. (length($a) == length($b))))
print("same joined:   " .. ("" .. (join($a, ",") == join($b, ","))))
```
```text
deep_eq:       true
same length:   true
same joined:   true
```

### A collection compared to a SCALAR still answers — `$m[$k] == nil` works

Only collection-vs-collection raises. A same-type `false` **misleads** — it
invites the reading "these two lists differ", which is not what was computed.
A collection and a scalar differ by *type*, so `false` there is truthful,
exactly as `1 == "a"` is honestly false:

```mix
$reg = {}
print($reg["k"] == nil)   -- true  (key absent)
$reg.k = [1, 2]
print($reg["k"] == nil)   -- false (key present, value is a list)
print([1] == "text")      -- false
print([1] != nil)         -- true
```

That first pattern is the whole reason for the narrower rule: `$map[$key] ==
nil` is **the** key-absence idiom, and the value on the left is a list or map
precisely when the key IS populated. Raising there would fail
data-dependently — the same line working until the map fills up.

### The raise is scoped to the OPERATORS — searching builtins are unchanged

`contains`, `index_of`, `last_index_of` and `unique` compare elements
internally, without going through `==`. They do **not** raise — and they also
still treat two equal-looking collections as different:

```mix
print(contains([{a: 1}], {a: 1}))      -- false, NOT a raise
print(index_of([[1], [2]], [2]))       -- -1
print(length(unique([[1], [1], [2]]))) -- 3 — no dedup of equal lists
```

That asymmetry is deliberate but worth knowing: since 0.68.0 `==` is loud
about collections while these stay quiet. Scoping the change to the operators
is what keeps `contains($list, $scalar)` — the overwhelmingly common use —
working, and there is no `deep_contains` yet. When you need a structural
search, drive it yourself:

```mix
$found = false
for each $item in $haystack
  if deep_eq($item, $needle) then $found = true end
end
```

## Footgun: lists pass into functions by value

A list (or map) handed to a function is **copied in**. Mutating the parameter —
`push`, `pop`, index-assignment — changes only the function's local copy; the
caller's value is untouched. The idiom is **pass in → `return` the new value →
reassign at the call site** (the triad — see [functions](functions.md)):

```mix
function with_tail($list)
  push($list, 99)
  return $list
end

$xs = [1, 2, 3]
$ys = with_tail($xs)
print("caller (unchanged): " .. ("" .. $xs))
print("returned:           " .. ("" .. $ys))
$xs = with_tail($xs)
print("after reassign:     " .. ("" .. $xs))
```
```text
caller (unchanged): [1, 2, 3]
returned:           [1, 2, 3, 99]
after reassign:     [1, 2, 3, 99]
```

## Quick reference

```text
LISTS
[a, b, c]            list literal (0-indexed)
$l[i]   $l[-1]       index READ (negative from end; OOB -> nil)
$l[i] = v            index WRITE (negative from end; OOB/non-number = ERROR; grow with push)
length($l) / len     element count
is_empty($l)         true when zero length
push($l, v)          append, MUTATES, returns nil
pop($l) / shift($l)  remove last / first, MUTATES, returns element (nil if empty)
sort($l)             all-number list→numeric; else lexicographic (sort_by for keys)
unique($l)           dedupe, first-seen order
reverse($l)          reversed copy
contains($l, v)      bool membership
index_of($l, v)      0-based pos, or -1
range(a, b[, step])  inclusive both ends
flat($l)             recursively flatten nested lists
concat($a, $b, …)    join 2+ lists into one new list (one level)
slice($l, s[, e])    half-open [s, e); negatives + clamp; reversed range = empty
                     (also string -> string, bytes/buffer -> bytes, v0.64.0)
take($l, n) drop($l, n)   first/last n  (negative n flips the end)
zip($a, $b)          element-wise [a, b] pairs, min length

MAPS
{k: v, "x": w}       map literal (insertion-ordered; keys are STRINGS; keywords ok bare, "fn" not)
$m.key  $m["key"]    read (missing -> nil; "*" key = wildcard fallback)
$m["key"] = v        assign / auto-create key (dot form $m.key = v equivalent, one level only)
keys($m) values($m)  lists, insertion order (for each $k in $m iterates keys)
has_key($m, k)       membership (NOT contains — that errors on a map)
merge($a, $b)        new map, b wins on conflicts (non-mutating)
delete($m, k)        new map without k       (non-mutating)
length($m)           key count
```

## See also

- [hof](hof.md) — `map` / `filter` / `reduce` / `sort_by` / `group_by` / `zip`-style transforms over collections (and the numeric `sort_by` that fixes lexical `sort`)
- [functions](functions.md) — the pass-by-value triad and closures
- [strings](strings.md) — `split` (string → list), `join` (list → string), `pos`, codepoint vs byte semantics
- [data](data.md) — `data_encode`, `json_parse` / `json_encode`, `jq` for round-trippable serialisation
- [keywords](keywords.md) — the keyword list, and which lexemes double as bare map keys / fields
- [builtins index](builtins.md) — every builtin by category

```text
mix builtins list     list every list builtin with its one-line description
mix builtins map      list every map builtin
mix what NAME         one-line description of a single builtin
mix help              the full categorized builtin reference
```

Source of truth: the Mix repo at <https://github.com/markc/mixos> (verified
against **mix 0.21.2** — the binary is the oracle).

---

<!-- page: https://mixos.dev/mix/control-flow/ (source: https://mixos.dev/mix/control-flow.md) -->

# Control flow

Mix has the control structures you expect — `if`, `while`, `for`, plus an ARexx-style `select` and a bare `loop` — with a few rules that bite anyone extrapolating from C, bash, or Python:

- **Every block closes with `end`.** There is no `}`, no `fi`/`esac`. (Legacy `next`/`done` still parse but warn — see [Legacy terminators](#legacy-terminators).)
- **There is no `do` keyword.** A bareword `do` after a loop header is just a discarded string: with a statement after it on the same line it's a *parse error*; alone at the end of the header line it silently does nothing. Drop the `do`.
- **Statements use newline or `;` separators.** Prefer newlines in files; `;` is the compact one-line form.
- **Conditions use Mix truthiness**, not a bool requirement (see [Truthiness](#truthiness)).
- **A loop var is a normal variable**, not block-scoped — it survives the loop at top level.

For transforming a list into another list, prefer a [HOF lambda](hof.md) (`map`/`filter`/`reduce`) over a hand-rolled loop; reach for the loops below for side effects (`print`, `send`) and stateful iteration.

---

## `if` / `elif` / `else if` / `else`

```mix
$x = 7
if $x > 10 then
  print("big")
elif $x > 5 then
  print("medium")
else
  print("small")
end
```
```text
medium
```

The header is `if <cond> then` — the `then` is **required** (`if $x` followed by a newline is `Parse error … expected Then, got Newline`). A middle branch is `elif <cond> then`, or equivalently the two-word `else if <cond> then` — both spellings parse into the same flat chain closed by a **single** `end` (they may even be mixed in one chain), and the final catch-all is a bare `else`. `elif` was added in 0.33.3; before that only `else if` existed. Only `end` closes an `if`; a legacy `done`/`next` is rejected:

```mix
if true then
  print("x")
done
```
```text
Parse error at line 3:1: unexpected token Done
```

`if` evaluates its branches lazily — only the first truthy condition's body runs, the rest are skipped.

### Truthiness

The condition does **not** have to be a boolean. `is_truthy` classifies every value:

| Value | Truthy? |
|---|---|
| `false`, `nil` | false |
| `0` (number) | false |
| `""` (empty string) | false |
| `"0"` (the one-char string) | **false** |
| any other string (`"0.0"`, `"false"`, `" "`) | true |
| `[]` / `{}` / empty bytes | false |
| non-empty list/map/bytes | true |
| any number `!= 0`, any function | true |

```mix
if "" then print("a") else print("empty string is falsy") end
if 0 then print("b") else print("zero is falsy") end
if "0" then print("c") else print("the string 0 is falsy") end
if "0.0" then print("but 0.0 as a string is truthy") end
if [] then print("d") else print("empty list is falsy") end
```
```text
empty string is falsy
zero is falsy
the string 0 is falsy
but 0.0 as a string is truthy
empty list is falsy
```

The `"0"` case is a deliberate shell-flavoured trap: `"0"` is falsy, `"0.0"` is truthy. When in doubt, compare explicitly (`if $s != "" then …`). For combining conditions use `and` / `or` / `not` (see [operators](operators.md)).

### `if` as an expression

Since 0.20 `if … then … else … end` can also be used **in expression position** — anywhere a value goes: an assignment, a call argument, inside a `..` concatenation. It short-circuits (only the taken branch runs). Each branch is a statement block whose value is its **last statement** (or nil if empty / no branch matched):

```mix
$code = 404
$msg = if $code == 200 then "ok" else if $code == 404 then "not found" else "?" end
print($msg)
print("status: " .. if $code >= 400 then "error" else "fine" end)
print(length(if false then "ab" else "abcd" end))
```
```text
not found
status: error
4
```

A multi-statement branch yields its last statement's value:

```mix
$v = if true then
  $a = 10
  $a * 2
else
  0
end
print($v)
```
```text
20
```

A **trailing operator binds to the if's value** — the `end` closes the expression first:

```mix
$x = if true then 1 else 2 end + 3
print($x)
```
```text
4
```

A leading `if` at the start of a statement is still a plain statement (its value is discarded); the expression form fires only when the `if` is nested inside an expression. For the terse one-line form, reach for the ternary `cond ? a : b`, and for "value or default" the nil-coalescing `??` (see [operators](operators.md)). Prefer either over the Lua-style `cond and a or b` idiom — Mix is broadly falsy, so that silently returns `b` whenever the middle value is falsy.

---

## `while`

Runs the body while the condition stays truthy, re-checking before each iteration (zero iterations if false at entry):

```mix
$n = 3
while $n > 0
  print($n)
  $n = $n - 1
end
```
```text
3
2
1
```

```mix
while false
  print("never")
end
print("skipped")
```
```text
skipped
```

There is no `do` after the condition — the body simply starts on the next line.

---

## `loop`

An unconditional loop — the ARexx/Smalltalk infinite loop. You exit it with [`break`](#break-and-continue) (or `return` from inside a function, or `die`):

```mix
$i = 0
loop
  $i = $i + 1
  if $i > 3 then
    break
  end
  print($i)
end
```
```text
1
2
3
```

`loop` is the right shape when the exit test is mid-body, not at the top (a `do … while` in other languages).

---

## `for $i = a to b [step s]`

A numeric counter loop. **Both bounds are inclusive**, the default step is `+1`. (There is no range *operator* — `..` is string concatenation; for a range as a list, see `range()` in [builtins](builtins.md).)

```mix
for $i = 1 to 3
  print($i)
end
```
```text
1
2
3
```

A negative `step` counts **down** (and the `to` bound is still inclusive):

```mix
for $i = 10 to 0 step -2
  print($i)
end
```
```text
10
8
6
4
2
0
```

The step may be fractional (numbers are f64 — see [math](math.md)):

```mix
for $x = 0 to 1 step 0.25
  print($x)
end
```
```text
0
0.25
0.5
0.75
1
```

Bounds and step are arbitrary expressions, evaluated **once** before the loop:

```mix
$lo = 2
$hi = 5
for $i = $lo to $hi
  print($i)
end
```
```text
2
3
4
5
```

### Direction and edge cases

The loop guard is direction-aware: with `step > 0` it stops once `$i > end`, with `step < 0` once `$i < end`. So a positive step over a descending range runs **zero** times rather than forever. **`step 0` never advances the counter — an infinite loop.** Mix does not promote a zero step to 1 (unlike shell brace expansion); don't compute a step that can reach 0.

A number or numeric string is accepted for each bound and step. A value that
`to_number` cannot parse raises `TYPE_MISMATCH`, naming whether it was the
start, end, or step; it never silently becomes `0`/`1`. This includes
`"inf"`, `"nan"`, and overflowing `"1e999"`, which are deliberately not Mix
numeric strings:

```mix
for $i = 1 to "x"
  print($i)
end
```
```text
TYPE_MISMATCH: for-loop end must be a number, got "x" (string)
```

A `NaN` start/end/step (e.g. from `sqrt(-1)`) is rejected up front (`for-loop start/end/step is NaN`) — it would otherwise be an unbounded loop, since every guard against `NaN` is false.

`to`, `step`, and `label` are keywords: they can never name a function or variable (`function step(…)` is a parse error — `expected identifier, got Step`), but since 0.21 a keyword is accepted anywhere it is unambiguously a name — a bare map key, a `.field` — so `for $i = $m.to to 7` parses. See [keywords](keywords.md).

---

## `for $x in <list>` (a.k.a. `for each`)

Iterates the elements of a list — the workhorse for collections. Since
0.63.0 the `each` keyword is **optional**: `for $x in $xs` and
`for each $x in $xs` are the same statement, and both stay supported
indefinitely (`each` is not deprecated). What disambiguates iteration from
the [counted loop](#for-i--a-to-b-step-s) is the token after the variable —
`in` (or a `,`) iterates, `=` counts:

```mix
for $fruit in ["apple", "pear", "fig"]
  print($fruit)
end
```
```text
apple
pear
fig
```

Add an **index variable** with a comma — `for $i, $x in …` or
`for each $i, $x in …` (the index is 0-based):

```mix
for each $i, $x in ["a", "b", "c"]
  print($i .. ": " .. $x)
end
```
```text
0: a
1: b
2: c
```

`for each` also accepts a **string** (yields one codepoint per iteration — emoji-correct since strings are codepoint-based, see [strings](strings.md)) and a **map** (yields the keys, in insertion order):

```mix
for each $ch in "héllo"
  print($ch)
end
```
```text
h
é
l
l
o
```

```mix
$m = { name: "Ada", lang: "Mix" }
for each $k in $m
  print($k .. " = " .. $m[$k])
end
```
```text
name = Ada
lang = Mix
```

### Two variables over a map bind (key, value) — changed in 0.68.0

The second variable is what changes by iterable. Over a **list, string or
bytes** two variables bind **(index, item)**. Over a **map** they bind
**(key, value)** — so the map form needs no `$m[$k]` lookup:

```mix
$m = { name: "Ada", lang: "Mix" }
for each $k, $v in $m
  print($k .. " = " .. $v)
end
```
```text
name = Ada
lang = Mix
```

**Before 0.68.0 this bound (index, key)** — the first variable was a counter
and the second was the key, which meant the value still had to be looked up
and the pairs form did not exist. Both spellings changed together
(`for each $k, $v` and the bare `for $k, $v`), and the **one-variable map
form still yields keys**, unchanged — it is what the release-cycle
`MIX-D3006` note pointed code at before the flip landed. (A map has no
position to bind, so there is no counter form; code that genuinely wanted a
running index over a map's keys counts one itself.)

Anything else (a number, nil) raises `cannot iterate over <type>`. An empty list/map/string runs the body zero times.

> **Iterating snapshots the source.** `for each` takes the items up front — for a map, **both the keys and the values** — so mutating the underlying variable mid-loop changes neither the iteration set nor what the remaining iterations bind. (This is also why `for each` is by-value friendly — see the loop-var scoping note below.)

### Prefer a HOF for value-producing bodies

If the loop body only builds a new collection or folds to a single value, a [HOF lambda](hof.md) is the idiom — it's shorter and side-effect-free:

```mix
$doubled = map([1, 2, 3, 4], fn($x) = $x * 2)
print($doubled)
```
```text
[2, 4, 6, 8]
```

Use `for each` for genuine side effects (printing, [`send`](bus.md), pushing into an accumulator). Reach for `map` / `filter` / `reduce` / `sort_by` when you're transforming data.

---

## `select` / `when` / `otherwise`

ARexx-style multi-way branch — Mix's `switch`. Each `when <expr> then` is tested for **equality** (`==`) against the selector value; the first match runs and the rest are skipped. `otherwise` is the optional default:

```mix
$x = 2
select $x
when 1 then
  print("one")
when 2 then
  print("two")
when 3 then
  print("three")
otherwise
  print("many")
end
```
```text
two
```

It works on strings just as well — a clean command dispatcher:

```mix
$cmd = "list"
select $cmd
when "add" then print("adding")
when "list" then print("listing")
otherwise print("unknown")
end
```
```text
listing
```

The `when` arms are **arbitrary expressions**, evaluated and compared at match time (not constant labels like C's `case`):

```mix
$x = 4
$two = 2
select $x
when $two * 2 then print("computed match: 4")
otherwise print("no")
end
```
```text
computed match: 4
```

Match is value equality (`==`). Be aware of the collection gotcha: **`List == List` is always `false`**, so a list selector never matches a list `when` — destructure or compare a scalar key instead:

```mix
$x = [1, 2]
select $x
when [1, 2] then print("matched list")
otherwise print("no match - lists never equal")
end
```
```text
no match - lists never equal
```

Each `when` arm takes exactly **one** expression (there is no `when 1, 2 then` multi-value arm — use `otherwise` plus an `if`, or normalise the selector first), and the `then` after it is required. With no matching `when` and no `otherwise`, `select` does nothing — no error.

---

## `break` and `continue`

`break` exits the innermost loop; `continue` skips to its next iteration. They work in `for`, `for each`, `while`, and `loop`:

```mix
$i = 0
loop
  $i = $i + 1
  if $i > 3 then
    break
  end
  print($i)
end
```
```text
1
2
3
```

```mix
for $i = 1 to 6
  if $i == 3 then
    continue
  end
  print($i)
end
```
```text
1
2
4
5
6
```

### Conditional `break if` / `continue if`

A one-line guarded form — `break if <cond>` / `continue if <cond>` — saves a wrapping `if … end`:

```mix
for $i = 1 to 10
  continue if $i < 3
  break if $i > 6
  print($i)
end
```
```text
3
4
5
6
```

### Labeled loops — break/continue an outer loop

Tag a loop header with `label <name>` — all four loop forms accept it (`for … label x`, `for each … label x`, `while <cond> label x`, `loop label x`) — then `break <name>` / `continue <name>` to act on that loop from inside a nested one:

```mix
for $i = 1 to 3 label outer
  for $j = 1 to 3
    if $i == 2 and $j == 2 then
      break outer
    end
    print($i .. "," .. $j)
  end
end
```
```text
1,1
1,2
1,3
2,1
```

```mix
for $i = 1 to 3 label rows
  for $j = 1 to 3
    continue rows if $j == 2
    print($i .. "," .. $j)
  end
end
```
```text
1,1
2,1
3,1
```

`continue rows` abandons the rest of the *inner* loop and jumps to the next iteration of the labeled *outer* loop. A `break`/`continue` whose label matches no enclosing loop propagates upward until one matches — and if **none** matches, it escapes every loop and aborts the script with a runtime error (`unexpected break outside loop`). A label typo is a crash, not a silent no-op.

---

## Inline (single-statement) bodies

A loop or `if` body may be a **single statement on the header line**, with no `do` and the same trailing `end`:

```mix
for $i = 1 to 3 print($i) end
```
```text
1
2
3
```

```mix
$c = 0
while $c < 3 $c = $c + 1 end
print($c)
```
```text
3
```

```mix
$a = []
for each $x in [1, 2, 3] push($a, $x * 10) end
print($a)
```
```text
[10, 20, 30]
```

Use `;` to put more than one body statement on the same physical line:

```mix
for each $x in [1, 2, 3]; print($x); print($x * 10); end
```

Critically, **`do` is not a keyword** — a bareword `do` parses as a discarded
string. Inline, it becomes the first body statement and the real body breaks the
parse:

```mix
for each $x in [1, 2, 3] do print($x) end
```
```text
Parse error at line 1:29: expected end of statement, got Print
```

Sneakier: with a **newline** after the `do` (the bash-style block header), the loop parses and runs — the `do` is just a silently discarded first statement. It looks like `do` is supported; it isn't. Drop it either way.

---

## Legacy terminators

The old block terminators still parse but emit a deprecation warning — **`next`** closes `for`/`for each`, **`done`** closes `while`/`loop`/`on` (the warning names the block kind: `'done' is deprecated for 'loop' blocks, …`). Migrate them to `end`:

```mix
for $i = 1 to 2
  print($i)
next
```
```text
warning: <mix> line 3: 'next' is deprecated for 'for' blocks, use 'end' instead
1
2
```

```mix
$n = 2
while $n > 0
  print($n)
  $n = $n - 1
done
```
```text
warning: <mix> line 5: 'done' is deprecated for 'while' blocks, use 'end' instead
2
1
```

`if` and `function`/`fn` accept **only** `end` — there is no legacy form for them. **Use `end` everywhere** in new code.

---

## Loop-variable scope (the one footgun)

Mix has **no per-iteration block scope** — the loop var is a single slot reused each pass, and it **persists after the loop** at top level:

```mix
for $i = 1 to 3
  $last = $i
end
print("last i was " .. $last)
```
```text
last i was 3
```

Inside a [function](functions.md) this is subtler: a loop var (and `for each` element/index var, and `catch $e`) binds **function-locally**, so a library's `for each $p in …` *shadows* rather than *clobbers* a same-named caller/global `$p`. But that also means a body assignment like `$total = $total + $x` inside a function binds a local and does **not** write through to an outer global — to propagate a result out, `return` it. See [functions](functions.md).

---

## See also

- [functions](functions.md) — `function`/`fn`, `return`, closures, the pass-in/return/reassign triad
- [hof](hof.md) — `map` / `filter` / `reduce` / `sort_by`: prefer these over value-producing loops
- [operators](operators.md) — `and` / `or` / `not`, comparisons, `..` concatenation
- [strings](strings.md) — codepoint iteration, interpolation rules
- [collections](collections.md) — lists & maps, `push`, indexing bases
- [error handling](errors.md) — `try` / `catch`, `die`
- [bus](bus.md) — `on … end` handlers (which also accept the legacy `done`)
- [keywords](keywords.md) — the reserved-word list; keywords as bare map keys/fields (0.21)
- [builtins index](builtins.md) — full builtin catalogue
- Lineage: [ARexx](https://en.wikipedia.org/wiki/ARexx) (`select`/`when`/`otherwise`, `do … end` blocks)
- `mix help` — one-line builtin summary · `mix what for` / `mix what select` — per-keyword help

```text
$ mix what for
for: Numeric loop: for $i = 1 to 10 ... end; iteration: for $x in LIST ... end ('each' optional: for each $x in LIST)
```

---

<!-- page: https://mixos.dev/mix/data/ (source: https://mixos.dev/mix/data.md) -->

# data — data & serialization

Mix reads and writes structured data through a single mental model: **every
format parses to the same `Value` tree** (string · number · bool · list · map ·
nil), and every encoder turns that tree back into text. There is one in-memory
shape; the format is just the doorway. So `json_parse` → walk with `.field` /
`[i]` → `json_encode` (or `toml_encode`, or `data_encode`) is the universal
round-trip.

List the category live with `mix builtins json`; one-line help for any name with
`mix what NAME`.

| Format | Text → Value | Value → text | File reader |
|---|---|---|---|
| JSON | `json_parse` | `json_encode` | `read_json`, `read_jsonl` |
| TOML | `toml_parse` | `toml_encode` | — (use `read_file` + `toml_parse`) |
| YAML | `yaml_parse` | `yaml_encode` | — (use `read_file` + `yaml_parse`) |
| strict-data `.mix` | `data_parse` | `data_encode` | `load_data` |
| CSV | `csv_parse` | — | — |
| INI | `ini_parse` | — | — |
| XML | `xml_parse` | — | — |
| jq query | `jq`, `jq_all` (over a `Value`) | — | — |
| numeric coercion | `to_number` | — | — |

`json_parse`/`json_encode`, `jq`/`jq_all`, `read_json`/`read_jsonl` are gated
behind the `json` feature, `toml_parse`/`toml_encode` behind `toml`,
`yaml_parse`/`yaml_encode` behind `yaml`, and `xml_parse` behind `xml`; the shipped `mix` binary turns them all on.
`data_parse`/`data_encode`, `load_data`, `csv_parse`, `ini_parse`, `to_number`,
and `template` are core — always present, no feature gate.

This page also covers [`template`](#template--filling-text-from-a-map)
(placeholder substitution from a map) and the typed
[`sqlexec` binds](#sqlexec--typed-sql-binds) — the other two places Mix values
cross a text/SQL serialization boundary.

## JSON

`json_parse(string)` turns a JSON document into a Mix value; field access is
`.key` for objects, `[i]` for arrays. `json_encode(value[, pretty])` is the
inverse.

```mix
$m = json_parse("{\"name\":\"alpha\",\"port\":25,\"tags\":[\"a\",\"b\"]}")
print($m.name)
print($m.port)
print($m.tags[0])
```

```text
alpha
25
a
```

```mix
$m = { name: "alpha", port: 25, on: true }
print(json_encode($m))
```

```text
{"name":"alpha","on":true,"port":25}
```

> Since 0.21 a Mix **keyword works as a bare map key** — `on: true`, `to: "x"`,
> `label: 1` all parse unquoted. The one exception is `fn` (it lexes identically
> to `function`): write `{ "fn": … }`. Keys with a dash/dot/space still need
> quotes. See [maps](collections.md).

A truthy second argument selects multi-line indented output:

```mix
$m = { name: "alpha", nested: { a: 1, b: 2 } }
print(json_encode($m, true))
```

```text
{
  "name": "alpha",
  "nested": {
    "a": 1,
    "b": 2
  }
}
```

### Key ordering — the one JSON footgun

A Mix `Map` is insertion-ordered, but the JSON doorway is not — **in either
direction**. `json_encode` goes through `serde_json` **without** `preserve_order`,
so it emits keys **sorted alphabetically**; `json_parse` returns object keys
sorted the same way, **not** in document order. If byte-stable, order-preserving
output matters (a generated config a human will diff, a signed canonical form),
use [`data_encode`](#strict-data-mix--the-substrate-format) instead — it
preserves insertion order.

```mix
$m = { zebra: 1, apple: 2, mango: 3 }
print("literal:     " .. ("" .. $m))   -- map literal: insertion order
print("data_encode: " .. data_encode($m))
print("json_encode: " .. json_encode($m))
print("json_parse:  " .. data_encode(json_parse("{\"zebra\":1,\"apple\":2}")))
```

```text
literal:     {zebra: 1, apple: 2, mango: 3}
data_encode: {"zebra": 1, "apple": 2, "mango": 3}
json_encode: {"apple":2,"mango":3,"zebra":1}
json_parse:  {"apple": 2, "zebra": 1}
```

### JSON value mapping

| JSON | Mix |
|---|---|
| `null` | `nil` |
| `true` / `false` | bool |
| number | `Number` (f64) |
| string | `String` |
| array | `List` |
| object | `Map` (`IndexMap`) |

```mix
$m = json_parse("{\"a\":null,\"b\":3.5,\"c\":1000000000000}")
print($m.a == nil)
print($m.b)
print($m.c)
```

```text
true
3.5
1000000000000
```

Mix numbers are f64, so an integer above 2^53 loses exact precision on the way
through — a documented constraint, not a bug (see [numbers](numbers.md)). JSON
object keys must be strings, and they come back **sorted**, not in document
order (§above).

### What JSON can't represent

`json_encode` is **loud on non-finite numbers**: a `NaN` / `±inf` anywhere in
the value raises a catchable error (JSON has no spelling for them — encoding
`0` silently would corrupt data):

```mix
try
  print(json_encode({ bad: sqrt(-1) }))
catch $e
  print("" .. $e)
end
```

```text
json_encode: non-finite number NaN has no JSON representation (JSON has no NaN/Infinity)
```

A **function** or **bytes** value inside the tree encodes as `null` — JSON
simply has no such type:

```mix
print(json_encode({ f: function($x) return $x end, s: "ok" }))
```

```text
{"f":null,"s":"ok"}
```

`data_encode` is stricter on both counts — it **raises** on functions and bytes
too (§strict-data below).

### Reading JSON from disk

`read_json($path)` is `read_file` + `json_parse` in one call (one record per
file). `read_jsonl($path[, opts])` reads a **JSON-lines** file — one independent
record per line — into a list, skipping blank lines.

```mix
-- /tmp/rec.json  = {"name":"alpha","port":25,"tags":["a","b"]}
$r = read_json("/tmp/rec.json")
print($r.name)
print($r.tags[1])
```

```text
alpha
b
```

```mix
-- /tmp/recs.jsonl =
--   {"id":1,"ok":true}
--   {"id":2,"ok":false}
--   {"id":3,"ok":true}
$recs = read_jsonl("/tmp/recs.jsonl")
print(length($recs))
print($recs[0].id)
print($recs[2].ok)
```

```text
3
1
true
```

`read_jsonl` is **strict by default** — one malformed line aborts the whole read
with a line number. Pass `{ skip_errors: true }` to silently drop bad lines
(useful for a log whose rotated tail can be truncated):

```mix
-- /tmp/bad.jsonl has a junk middle line
$strict = read_jsonl("/tmp/bad.jsonl")            -- raises: "... line 2: ..."
$lenient = read_jsonl("/tmp/bad.jsonl", { skip_errors: true })
print(length($lenient))                            -- the two good records
```

```text
2
```

### Parse errors raise

`json_parse` / `read_json` / `read_jsonl` raise a catchable runtime error on
malformed input (the same fail-fast policy as the rest of Mix — a broken literal
is a script bug, not absent data). Wrap with [`try`/`catch`](errors.md):

```mix
try
  $m = json_parse("{oops")
catch $e
  print("bad json: " .. ("" .. $e))
end
```

```text
bad json: json_parse: key must be a string at line 1 column 2
```

## jq — querying a Value

`jq(value, filter)` and `jq_all(value, filter)` run a real [jq](https://jqlang.github.io/jq/)
filter (embedded [jaq](https://github.com/01mf02/jaq) engine) over any Mix value
— typically `json_parse` output, but any list/map tree works. The `value` is a
**Mix value, not a JSON string**: `json_parse` is the text→value door, `jq` is the
query door — any list/map literal works too, no JSON round-trip needed. Design
notes: the jq-builtin design doc (operator control repo since 2026-07-23).

The split is about **output cardinality**, the thing jq makes hard for a
single-return language:

- **`jq(value, filter)`** — for a filter that yields **0 or 1** output. 0 → `nil`, 1 → that value unwrapped. A filter that returns an *array as one value* (`map(.x)`, `[ .a[] ]`) belongs here — it's one output. **More than one output raises.**
- **`jq_all(value, filter)`** — for a **stream** filter (`.items[]`, `.[] | select(…)`). **Always a list**: 0 outputs → `[]`, N → `[v0, …]`. You can always `for each` it.

```mix
$m = json_parse("{\"a\":{\"b\":{\"c\":42}}}")
print(jq($m, ".a.b.c"))
```

```text
42
```

```mix
$m = json_parse("{\"items\":[{\"n\":\"x\"},{\"n\":\"y\"}]}")
print(jq($m, "[ .items[].n ]"))      -- bracketed: one array output -> jq()
```

```text
[x, y]
```

```mix
$m = json_parse("{\"items\":[{\"n\":\"x\",\"sz\":50},{\"n\":\"y\",\"sz\":150}]}")
$big = jq_all($m, ".items[] | select(.sz > 100) | .n")   -- stream -> jq_all()
print($big)
```

```text
[y]
```

A stream filter handed to `jq()` raises with the fix spelled out:

```mix
$m = json_parse("[1,2,3]")
print(jq($m, ".[]"))
```

```text
Runtime error at line 2: jq(): filter produced more than one output; use jq_all(), or wrap the filter as `[ … ]` / `map(...)` / add `first` to make it a single value
```

### Absent data vs. errors

A valid filter over absent data is **not** an error — `.missing` → jq `null` →
Mix `nil` for `jq()`, and an empty stream → `[]` for `jq_all()`. There is no
`default` argument; use jq's own alternative operator `//`:

```mix
$m = json_parse("{\"a\":1}")
print(jq($m, ".missing // \"none\""))   -- absent -> the alternative
$r = jq($m, ".nope")
if $r == nil then print("got nil") end
```

```text
none
got nil
```

A **malformed filter** or a **jq runtime type error** (e.g. indexing a number)
raises, like `json_parse` on bad JSON:

```mix
$m = json_parse("{\"a\":1}")
print(jq($m, ".a |"))
```

```text
Runtime error at line 2: jq(): cannot parse filter ".a |": Parse([(Term, "")])
```

> jq (the embedded jaq engine) **preserves** object key insertion order — `jq($m,
> ".")` returns keys in their original order, and constructed objects like `jq($m,
> "{b: .b, a: .a}")` keep the written order. The alphabetical look in JSON examples
> above comes from `json_parse`/`json_encode`, not from jq. For canonical,
> order-stable serialization reach for `data_encode`.

## YAML (v0.71.0)

`yaml_parse(string[, {docs: true}])` → value; `yaml_encode(value)` → a YAML
string. This is the surface the provisioned-YAML fleet runs on — Grafana
alerting/dashboards/datasources, Prometheus and Alloy config that deploy
scripts generate, edit, and **gate on**: a deploy script that cannot parse
what it deploys cannot validate it either (this used to shell out to
`ruby -ryaml`).

```mix
$y = yaml_parse(read_file("rules.yaml"))
for each $g in $y["groups"]
  print($g["name"] .. ": " .. len($g["rules"]) .. " rule(s)")
end
write_file("rules.yaml", yaml_encode($y))
```

The mapping mirrors JSON's: scalars → nil/bool/number/string, sequences →
lists, mappings → maps in document order. The details that differ from a
naive reading:

- **Documents.** By default the input must hold at most one document —
  none is `nil`, more than one **raises** (naming the fix). Pass
  `{docs: true}` for a list of every document in the stream.
- **Keys.** Mix maps are string-keyed: scalar YAML keys keep their natural
  text (`25:` becomes `"25"`); a sequence or mapping used as a key raises.
- **Anchors and aliases** are resolved during parsing; tags are not
  preserved. **Merge keys are NOT resolved**: yaml-rust2 has no `<<`
  handling, so `<<: *defaults` parses as a literal `"<<"` entry whose
  inherited fields are *not* flattened into the map — a gating script
  must flatten them itself or avoid `<<` in files it validates.
  `.inf`/`.nan`-style reals that Rust cannot parse keep their text as
  strings rather than being guessed at.
- **Encoding** emits no leading `---` marker, guarantees a trailing
  newline, writes whole numbers as integers, and quotes only what YAML
  requires — including keys like `on`/`yes` that YAML 1.1 would read as
  booleans. `nil`/bool/number/string/list/map only; bytes, buffer or
  function values raise — and so does a **non-finite number** (bare
  `inf`/`NaN` would read back as *strings*; `json_encode` and
  `toml_encode` refuse the same way).
- **Nesting is capped at 256 levels** in both directions (a hostile
  deep-nesting input raises a catchable error, like `serde_json`'s 128).
- Round trip holds: `yaml_parse(yaml_encode($v))` rebuilds the same value.

## TOML

`toml_parse(string)` → map; `toml_encode(value)` → a pretty TOML string. Tables
become nested maps; a whole-valued number encodes as a TOML integer, a fractional
one as a float.

```mix
$t = toml_parse("name = \"alpha\"\nport = 25\n\n[server]\nhost = \"192.0.2.1\"")
print($t.name)
print($t.port)
print($t.server.host)
```

```text
alpha
25
192.0.2.1
```

```mix
$m = { name: "alpha", port: 25, server: { host: "192.0.2.1" } }
print(toml_encode($m))
```

```text
name = "alpha"
port = 25

[server]
host = "192.0.2.1"
```

There is no `read_toml`; compose it — `toml_parse(read_file($path))`. TOML
datetimes parse to a string.

TOML has no representation for Mix `nil`, function, `bytes`, or `buffer`
values. `toml_encode` therefore raises `TOML_UNREPRESENTABLE` instead of
silently replacing any of them with `""`. The structured error's `details`
map carries the exact `path` and `type`, including list indexes:

```mix
try
  print(toml_encode({jobs: [{payload: freeze(buffer([1, 2]))}]}))
catch $message, $error
  print($error.code)
  print($error.details.path)
  print($error.details.type)
end
```

```text
TOML_UNREPRESENTABLE
$.jobs[0].payload
bytes
```

Convert deliberately before encoding: `base64_encode($bytes)` for binary
payloads, omit an absent field rather than storing `nil`, and never put a
function in a data tree.

## strict-data `.mix` — the substrate format

Mix has its own JSON-equivalent data format: a `.conf.mix` / `.spec.mix` file is a
JSON-shaped tree with a friendlier surface — bareword keys, optional top-level
braces, `#` comments, trailing commas, `nil`. Crucially it **parses only as
data**: no `$vars`, no `$(cmd)`, no `${...}`, no function calls, no control flow.
It is the format for substrate-internal config that must never run as code.

- `data_parse(string)` — text → value (the non-executing parser).
- `data_encode(value[, pretty])` — value → text, with correct escaping; **round-trips** through `data_parse` and **preserves key order**.
- `load_data($path)` — read + `data_parse` a file (the non-executing twin of [`source`/`include`](functions.md), which *run* a file).

Literal heredocs are accepted as strings, including their normal trailing-newline
semantics. A heredoc containing `${...}` interpolation or `$(...)` command
substitution is rejected like every other executable strict-data construct.

**Escapes in strict-data strings.** A literal `${` is written `\${` (the same
`\$` escape as program source) and a leading `~` is written `\~` — which is
exactly what `data_encode` emits, so its output always reads back unchanged.
From 0.92.0 strict data also decodes JSON's `\uXXXX` form (exactly four hex
digits; a surrogate pair is joined, a lone surrogate is a parse error) as well
as the braced `\u{…}`, so JSON-encoded text — which escapes control characters
that way — reads back as the original string. Program source is unchanged: a
bare `\u` not followed by `{` stays literal there. JSON text is still not
strict data in general: `json_encode` leaves `$` bare, so text carrying `${`
must be escaped (`replace($json, '${', '\${')`) or produced by `data_encode`.

```mix
$cfg = { name: "alpha", port: 25, tags: ["a", "b"] }
print(data_encode($cfg))
print(data_encode($cfg, true))   -- truthy 2nd arg = multi-line
```

```text
{"name": "alpha", "port": 25, "tags": ["a", "b"]}
{
  "name": "alpha",
  "port": 25,
  "tags": [
    "a",
    "b"
  ]
}
```

`data_encode` emits exactly the escaping the strict-data lexer round-trips —
`\$`, `\"`, `\\`, `\n`, `\t`, `\r`, `\e`; any other control character as
`\u{…}`; and a leading `\~` when (and only when) the string is `~` or starts
with `~/`, the two shapes the lexer would expand to `$HOME` — so a string that
ends in `$` (a regex) or contains a backslash survives intact. This is what
makes it **safe to splice hostile values**
into a generated config or a remote script: the value arrives as inert data, never
as a command. (It is **not** a shell escaper — don't feed its output to `/bin/sh`.)

```mix
$v = { rx: "ends-with$", win: "a\\b" }
print(data_encode($v))
```

```text
{"rx": "ends-with\$", "win": "a\\b"}
```

The round-trip is exact for any data-shaped tree:

```mix
$orig = { name: "alpha", regex: "x$", tags: ["a", "b"], n: 7 }
$back = data_parse(data_encode($orig))
print($back.regex)
print($back.tags[1])
print($back.n)
```

```text
x$
b
7
```

`data_parse` accepts the canonical no-braces top-level map (newline- or
comma-separated `key: value`):

```mix
$d = data_parse("name: \"alpha\"\nport: 25\nenabled: true")
print($d.name)
print($d.enabled)
```

```text
alpha
true
```

Strict-data does **not** accept executable Mix's `;` statement separator — use
newlines or commas. `data_parse("a: 1; b: 2")` raises a line-numbered
strict-data violation rather than quietly widening the configuration format.

A **missing comma** inside a braced map or list is named as exactly that
(0.72.0): ``missing `,` after this map entry``, anchored at the line of the
entry that lacks it. (It used to surface as `expected RBrace, got
String("b")` at the line *after* the omission — the parser's state, not the
author's mistake, and 20 lines away in a real config.)

…and **rejects every executable construct** with a line-numbered error — that
rejection is the whole point:

```mix
print(data_parse("x: now()"))
```

```text
Runtime error at line 1: data_parse: Strict-data violation at line 1: function call `now(...)` not allowed in data files. data files cannot invoke functions; use a literal value
```

Keys that are Mix **keywords** need no quoting (since 0.21): a `.conf.mix` key
named `to`, `on`, `in`, or `label` parses bare. The one exception is `fn` — it
lexes identically to `function`, so quote it (`"fn": 1`).

`load_data` is the file-reading form, for data the Mix tooling and a Rust
consumer should read through the one same parser (e.g. a mesh inventory):

```mix
-- /tmp/inv.mix (strict-data, NOT a script):
--   name: "mesh-inventory"
--   nodes: [
--     { host: "node1", addr: "192.0.2.1" },
--     { host: "node2", addr: "192.0.2.2" },
--   ]
$inv = load_data("/tmp/inv.mix")
print($inv.name)
print($inv.nodes[0].host)
print($inv.nodes[1].addr)
```

```text
mesh-inventory
node1
192.0.2.2
```

**Every way `load_data` can fail is catchable** (since 0.36.1) — missing file,
unreadable file, syntax error in the data, or an executable construct the
strict-data rules reject. All four arrive as ordinary runtime errors naming the
path, so a `try/catch` around a config read actually holds:

```mix
$cfg = nil
try
  $cfg = load_data("/etc/mixos/app.conf.mix")
catch $e
  print("cannot read config: " .. $e)
  exit(2)
end
```

> Before 0.36.1 a *malformed* file raised a raw parse error, and
> [`try/catch`](errors.md) deliberately does not catch those — the script
> aborted with exit 1 straight through the handler above, while a *missing*
> file was caught normally. If you rely on that `catch`, check
> `mix --version`.

> `data_encode` cannot represent a non-finite number (`NaN`/`±inf`), a function
> value, or a bytes value — it **raises** a catchable error rather than emit
> silently-lossy text (where `json_encode` degrades functions/bytes to `null`,
> §above).

## CSV & INI — text tables and config

`csv_parse(string[, delim])` reads the **first line as a header** and returns a
list of maps keyed by those headers. Fields are trimmed. The optional second
argument is a single-byte delimiter (default `,`); anything else —
an empty or multi-byte string, a non-string, or `nil` — raises
TYPE_MISMATCH instead of silently defaulting or truncating.

```mix
$rows = csv_parse("name,port\nalpha,25\nbeta,143")
print($rows[0].name)
print($rows[1].port)
print(length($rows))
```

```text
alpha
143
2
```

```mix
$rows = csv_parse("a|b\n1|2", "|")
print($rows[0].a)
print($rows[0].b)
```

```text
1
2
```

Three sharp edges: the parser is a **naive split** — no RFC-4180 quote handling,
so a quoted field containing the delimiter splits in two (`"x,y"` becomes the
fields `"x` and `y"`); `delim` must be **exactly one ASCII byte** and not NUL,
CR, LF or a double quote (anything else raises TYPE_MISMATCH); and a row with
more fields than headers keys the extras by 0-based field index (`col1`,
`col2`, …). Blank lines are skipped.

`ini_parse(string)` reads `[section]` headers and `key = value` lines into a
nested map. Lines starting `#` or `;` are comments. Keys before any section land
under `_global`.

```mix
$ini = ini_parse("debug = true\n[server]\nhost = 192.0.2.1\nport = 25\n[log]\nlevel = info")
print($ini["_global"].debug)
print($ini.server.host)
print($ini.server.port)
print($ini.log.level)
```

```text
true
192.0.2.1
25
info
```

> **Every CSV / INI value is a string** — even `25` and `true`. These parsers do
> no type inference (a value with leading zeros, a hostname, and a port look the
> same as text). Coerce numerics yourself with `to_number` (next section). JSON,
> TOML, and strict-data preserve the types they can represent; each serializer
> documents what happens when a Mix-only type reaches its boundary. TOML and
> strict-data raise rather than substituting a different value.

## XML — SOAP/RSS documents

`xml_parse(string[, {mode}])` parses **strict XML** into a Value tree. The
default `simple` mode is shaped for consuming SOAP/RSS-style API responses:
namespace prefixes are stripped, attributes become `@name` keys, repeated
sibling elements collapse into a list, a leaf element's trimmed text becomes
its value, mixed text lands under `#text`, and `xmlns` declarations are
dropped. The result is `{RootName: …}`, so a SOAP response navigates as plain
map access:

```mix
$r = xml_parse("<e:Envelope xmlns:e=\"urn:x\"><e:Body><status>OK</status><ns><s>ns1.example.net</s><s>ns2.example.net</s></ns></e:Body></e:Envelope>")
print($r.Envelope.Body.status)
print($r.Envelope.Body.ns.s[1])
print(length($r.Envelope.Body.ns.s))
```

```text
OK
ns2.example.net
2
```

Attribute and mixed-text keys start with `@`/`#`, so they need bracket access:

```mix
$a = xml_parse("<a id=\"7\">hi &amp; bye</a>")
print($a.a["@id"])
print($a.a["#text"])
```

```text
7
hi & bye
```

Pass `{mode: "tree"}` for full fidelity: every element is a
`{name, attrs, children}` node with namespace prefixes and `xmlns` attributes
preserved and child order intact; text children appear as plain strings
(whitespace-only text between elements is dropped in both modes).

```mix
$t = xml_parse("<ns:a x=\"1\">t<b/>u</ns:a>", {mode: "tree"})
print($t.name)
print($t.attrs.x)
print($t.children[0])
print($t.children[1].name)
```

```text
ns:a
1
t
b
```

Sharp edges: **strict XML only** — real-world HTML is tag soup and will not
parse (that needs an HTML5 parser, deliberately not this builtin). Every parsed
value is a **string** (like CSV/INI — coerce with `to_number`). Simple mode is
**lossy by design**: ordering across differently-named siblings, mixed-content
interleaving, and namespace identity are all dropped — reach for `{mode:
"tree"}` when they matter. A single child element is a scalar and two-plus
collapse to a list, so a maybe-repeated element needs a `type()` check (or
navigate the tree mode instead). Only predefined (`&amp;` `&lt;` `&gt;`
`&apos;` `&quot;`) and numeric character entities resolve — no DTD, so custom
entities error. Input must be UTF-8 (a `bytes` payload from `http_get` is
accepted and decoded strictly). Nesting is capped at 256 levels; malformed
input, mismatched/unclosed tags, multiple roots, and text outside the root all
error rather than best-guess.

## to_number — numeric coercion

`to_number(value)` returns the value as a `Number`, or `nil` if it can't coerce.
It accepts a number, a numeric string (surrounding whitespace trimmed), or a bool
(`true`→1, `false`→0); anything else → `nil`. This is the bridge from
string-typed CSV/INI/form data back to arithmetic.

```mix
print(to_number("3.14"))
print(to_number("  42  "))
print(to_number(true))
print(to_number("nope"))
print(to_number([1, 2]))
```

```text
3.14
42
1
nil
nil
```

Coercion is **strict about non-finite spellings**: `"inf"`, `"infinity"`,
`"nan"`, and an overflowing `"1e999"` all return `nil` — a word the Rust float
parser happens to accept is not a Mix numeric string. `is_number` agrees on the
string case. Number **values** still propagate IEEE-754 non-finites through
math (`sqrt(-1)` is `NaN`) — it is the string doorway that's strict. Ordinary
scientific notation is fine (`to_number("1e6")` → `1000000`). See
[numbers](numbers.md).

```mix
print(to_number("inf"))
print(to_number("1e999"))
print(is_number("nan"))
print(sqrt(-1))
```

```text
nil
nil
false
NaN
```

The `nil`-on-failure return is the validation idiom — branch instead of crashing:

```mix
$rows = csv_parse("name,port\nalpha,25")
$p = to_number($rows[0].port)
if $p == nil then
  print("port is not a number")
else
  print($p + 1)
end
```

```text
26
```

## template — filling text from a map

`template(tmpl, map)` substitutes single-brace `{key}` placeholders (not
`{{key}}`) with the map's values, stringified the way `print` would. The second
argument must be a map — anything else raises.

```mix
print(template("{name} is a {role}", { name: "alpha", role: "relay" }))
print(template("{n} items, ok={ok}", { n: 3, ok: true }))
```

```text
alpha is a relay
3 items, ok=true
```

Three rules make it safe over untrusted values:

- **Single-pass**: a substituted value is emitted verbatim and never rescanned, so data containing `{other_key}` cannot inject a second substitution — and the output never depends on map iteration order:

```mix
print(template("{a} and {b}", { a: "{b}", b: "SECRET" }))
```

```text
{b} and SECRET
```

- A `{key}` not present in the map, a `{` with no closing `}`, and a nested `{` all stay **literal** — no error, no silent empty string.
- Matching is **byte-exact** — no Unicode normalization, no case-folding (see [strings](strings.md)).

## sqlexec — typed SQL binds

The embedded SQLite builtins (`sqlite` feature; on in the shipped binary) are
the other place Mix values cross a serialization boundary. `sqlopen(path)`
opens **read-only**; `sqlopen(path, "rw")` opens read-write (WAL mode, 5s busy
timeout). `sqlexec(handle, sql[, params])` executes with `?` placeholders;
`sqlclose(handle)` closes.

Parameters bind **typed** — never stringified:

| Mix value | SQLite bind |
|---|---|
| `nil` | `NULL` |
| bool | `INTEGER` `0`/`1` |
| whole finite number (i64 range) | `INTEGER` |
| any other number (fractional, huge) | `REAL` |
| string | `TEXT` |
| bytes | `BLOB` |
| list / map / function | **loud error** — no SQL representation |

`params` is a list (one element per `?`) or a single bare value. A non-reading
statement (`INSERT`/`UPDATE`/`CREATE` …) returns `{affected: N}`; a
row-returning statement (`SELECT`, a row-returning `PRAGMA` — decided by SQLite
itself, not a keyword match) returns a **list of maps**, mapping back `NULL` →
`nil`, `INTEGER`/`REAL` → number, `TEXT` → string, and a `BLOB` → the
placeholder string `"<blob N bytes>"`.

```mix
$db = sqlopen(":memory:", "rw")
sqlexec($db, "create table t (a, b, c)")
print(data_encode(sqlexec($db, "insert into t values (?, ?, ?)", [nil, true, 2.5])))
print(data_encode(sqlexec($db, "select typeof(a) as ta, typeof(b) as tb, typeof(c) as tc from t")))
sqlclose($db)
```

```text
{"affected": 1}
[{"ta": "null", "tb": "integer", "tc": "real"}]
```

Binds are the **exact-bytes** path — prefer them over composing SQL text with
`sql_quote` (which escapes for a string literal and doubles a backslash on the
way into SQLite; see [system](system.md)).

## Boundary validation (v0.29.0)

Mix's tolerant `nil` semantics stay the default everywhere — a missing map key
reads as `nil`, and general string coercion renders that as `"nil"`, which is
exactly how a blank provisioning field once became part of a constructed
hostname. The validation family makes strictness a one-call choice at your
job/API/form boundary; failures raise structured `VALIDATION_*` errors with
`details {path, expected, actual_type}` (see [errors](errors.md)):

```mix
$job = validate($raw, {
  node: {type: "string", nonblank: true},
  host: {type: "string", nonblank: true},
  vmid: {type: "integer", min: 100, max: 999999},
  plan: {enum: ["gold", "silver"]},
  tags: {required: false, type: "list", items: {type: "string", nonblank: true}},
  owner: {required: false, type: "map", schema: {name: {nonblank: true}}}
})
```

- `validate(value, spec)` — validates a map against a field spec, returns the ORIGINAL map unchanged (composable; no hidden normalization). Rules per field: `required` (default TRUE), `type` (one name or a list — `any nil bool number integer string bytes buffer list map function`; `integer` = finite whole within ±2^53-1), `nonblank`, `enum` (normal Mix equality, so `"8080"` matches `8080`), `min`/`max` (inclusive numeric), `min_length`/`max_length` (string codepoints / list items / map entries), `items` (rule map for every list element), `schema` (nested field spec). Optional fields that are absent or nil skip their rules; unknown INPUT fields pass through; a typo'd RULE key raises `VALIDATION_SPEC` instead of silently no-opping. Violation paths read `owner.name`, `tags[2]`.
- `require_key(map, key)` — assert present + non-nil, return the value (`VALIDATION_REQUIRED`).
- `expect_type(value, kind)` — assert the type, return the value (`VALIDATION_TYPE`).
- `nonblank(value[, label])` — assert a non-blank string, return it UNTRIMMED; the label names the value in the error (`VALIDATION_NONBLANK`).
- `get_or(map, key, default)` — the tolerant twin: default covers both absent and nil.

Using `validate(...)`/`require_key(...)` as a bare statement is a legitimate
assertion — the raise is the point; the return value is for composing.

## Choosing a format

- **JSON** — interop with the outside world (HTTP APIs, JMAP, other tools). Loses key order in both directions (keys come back sorted); types preserved.
- **strict-data `.mix`** (`data_*` / `load_data`) — substrate-internal config and data a human authors or an agent generates. Order-preserving, comment-friendly, safe-by-construction (never runs as code), exact round-trip. The default for anything Mix owns end-to-end.
- **TOML** — interop with TOML-native tooling.
- **CSV / INI** — ingesting legacy text tables / config; string-typed, no encoder.
- **jq** — querying/filtering a value you already have, especially predicate selection over a stream.

## See also

- [strings](strings.md) — string vs. raw quoting, `${...}` interpolation, `..` concat
- [collections](collections.md) — lists, maps, indexing, `.field` / `[i]` access
- [functions](functions.md) — and the HOFs (`map`/`filter`/`sort_by`) you run over parsed data
- [files](io.md) — `read_file` / `write_file` / `read_lines` / `read_file_bytes`
- [errors](errors.md) — `try`/`catch` around a parse that may raise
- [modules](functions.md) — `source` / `include` (which *run* a file) vs. `load_data` (which doesn't)
- [Bus messaging](bus.md) — `data_encode` for safely splicing values into a remote script
- [math](math.md) — numeric builtins over the numbers `to_number` produces
- [numbers](numbers.md) — f64 precision, radix literals, non-finite propagation
- [system](system.md) — `sql_quote` / `shell_quote` and when binds beat quoting
- The [mix repo](https://github.com/markc/mixos)

```
mix builtins json     list every JSON / TOML / data builtin
mix what NAME         one-line description of a single builtin (e.g. mix what jq)
mix help              the full categorized builtin reference
```

---

<!-- page: https://mixos.dev/mix/datastar/ (source: https://mixos.dev/mix/datastar.md) -->

# datastar — Datastar SSE event framing

Three builtins that **frame** [Datastar](https://data-star.dev) v1 Server-Sent
Events: `ds_patch_elements`, `ds_patch_signals`, and `ds_sse`. They are the pure
half of the Datastar SDK — they build the exact wire bytes the Datastar JS
client reads to patch the DOM or update the client-side signal store, and
`ds_sse` glues those event strings into a `text/event-stream` response body.

> **The one rule:** these builtins **FRAME, they do not ESCAPE.** A caller MUST
> `html_escape()` untrusted content *before* passing it to `ds_patch_elements`,
> exactly as for any rendered page (see [strings](strings.md)). Framing wraps
> your bytes in SSE lines; it does nothing to neutralise `<script>` in them.

These builtins are feature-gated on the `datastar` feature; the `mix` binary
turns it on, so they are always present in the shipped binary. They are built on
the upstream [`datastar`](https://crates.io/crates/datastar) crate's
framework-agnostic wire serializer, so the format tracks upstream and never
drifts. One-line help: `mix what ds_patch_elements`. Added in **mix 0.18.1**.

## Mental model

Datastar's transport is plain SSE. Each event is a few lines:

```text
event: <datastar-event-type>
data: <field> <value>
data: <field> <value>
<blank line>
```

A blank line terminates the SSE frame. Mix gives you one builtin per Datastar
event type plus an assembler:

| Builtin | Event type | Purpose |
|---|---|---|
| `ds_patch_elements(html[, opts])` | `datastar-patch-elements` | morph HTML into the DOM |
| `ds_patch_signals(sig[, opts])`   | `datastar-patch-signals`  | update the client signal store |
| `ds_sse(event \| [events])`        | —                         | concatenate event strings into a response body |

Each `ds_patch_*` call returns a **string** — one fully-framed SSE event,
trailing blank line included. `ds_sse` just splices those strings (no
re-framing, no separators added — each event already carries its own blank-line
terminator).

## ds_patch_elements — patch the DOM

```
ds_patch_elements(html, [{selector, mode, view_transition}]) -> event string
```

The first argument is an HTML fragment. The optional second argument is a map of
options. Bare call, no options:

```mix
$ev = ds_patch_elements("<div id=\"clock\">12:34</div>")
print($ev)
```
```text
event: datastar-patch-elements
data: elements <div id="clock">12:34</div>

```

(The output ends with a blank line — the SSE frame terminator.)

### Options

| Key | Values | Default |
|---|---|---|
| `selector` | a CSS selector string | none (Datastar uses the element's `id`) |
| `mode` | `outer` `inner` `remove` `replace` `prepend` `append` `before` `after` | `outer` |
| `view_transition` | a bool: `true` → emit `useViewTransition true`; `false`/absent → off | off |

Two option-map behaviours to know: a `nil`-valued `selector`/`mode` is treated as
absent, and **unknown keys are silently ignored** — there is no strict allowlist
here (unlike `run`/`ssh_run` opts), so a typo'd `selectr:` produces a
default-targeted frame, not an error. A non-string first argument is coerced to
its string form (`ds_patch_elements(42)` frames the text `42`).

```mix
$ev = ds_patch_elements("<li>row</li>", {selector: "#list", mode: "append"})
print($ev)
```
```text
event: datastar-patch-elements
data: selector #list
data: mode append
data: elements <li>row</li>

```

`view_transition` wraps the patch in a browser View Transition:

```mix
$ev = ds_patch_elements("<p>hi</p>", {view_transition: true})
print($ev)
```
```text
event: datastar-patch-elements
data: useViewTransition true
data: elements <p>hi</p>

```

### mode = remove

`remove` deletes matching elements and **requires** a `selector` (there is no
HTML to send — pass `""` or anything; it is ignored):

```mix
$ev = ds_patch_elements("", {mode: "remove", selector: "#toast"})
print($ev)
```
```text
event: datastar-patch-elements
data: selector #toast
data: mode remove

```

Forgetting the selector is a clean runtime error, not a silent malformed frame:

```mix
ds_patch_elements("x", {mode: "remove"})
-- Runtime error: ds_patch_elements: mode 'remove' requires a 'selector' in the options map
```

An unknown mode is rejected up front:

```mix
ds_patch_elements("x", {mode: "swap"})
-- Runtime error: ds_patch_elements: unknown mode 'swap'
--   (expected one of outer/inner/remove/replace/prepend/append/before/after)
```

### Multi-line HTML is re-prefixed per line

If the HTML contains newlines, every line gets its own `data: elements` prefix —
that is how SSE carries a multi-line value, and it is what keeps an embedded `\n`
from forging a new frame:

```mix
$html = "<ul>\n  <li>one</li>\n  <li>two</li>\n</ul>"
print(ds_patch_elements($html))
```
```text
event: datastar-patch-elements
data: elements <ul>
data: elements   <li>one</li>
data: elements   <li>two</li>
data: elements </ul>

```

This composes cleanly with `markdown()` (documented below) — render author
content to HTML, then frame it:

```mix
$ev = ds_patch_elements(markdown("# Hi\n\nrender me"), {selector: "#post", mode: "inner"})
print($ev)
```
```text
event: datastar-patch-elements
data: selector #post
data: mode inner
data: elements <h1>Hi</h1>
data: elements <p>render me</p>

```

## ds_patch_signals — update the client signal store

```
ds_patch_signals(signals_map_or_json, [{only_if_missing}]) -> event string
```

Datastar keeps a reactive **signal store** in the browser. This event merges a
patch into it. Pass a **map** (or a **list** — it becomes a JSON array) and it
is JSON-encoded for you:

```mix
$ev = ds_patch_signals({count: 5, name: "ada"})
print($ev)
```
```text
event: datastar-patch-signals
data: signals {"count":5,"name":"ada"}

```

Pass a **string** and it is used **verbatim** — it must already be valid JSON
(e.g. from `json_encode()`):

```mix
$ev = ds_patch_signals("{\"open\":true}")
print($ev)
```
```text
event: datastar-patch-signals
data: signals {"open":true}

```

`only_if_missing` makes the patch a default — it only sets signals the client
does not already have (good for initial values that must not clobber user edits).
Like `view_transition`, it is a strict bool: `"false"`/`0`/`nil` raise
`TYPE_MISMATCH` rather than being read as a truthiness.

```mix
$ev = ds_patch_signals({theme: "dark"}, {only_if_missing: true})
print($ev)
```
```text
event: datastar-patch-signals
data: onlyIfMissing true
data: signals {"theme":"dark"}

```

Any other first-argument type (number, bool, nil) is rejected:

```mix
ds_patch_signals(42)
-- Runtime error: ds_patch_signals: first argument must be a signals map or JSON string, got number
```

The map/list path uses the same encoder as `json_encode`, with the same rules
(see [JSON & data](data.md)): a **NaN or ±inf number anywhere in the value
raises** a catchable error rather than silently corrupting the store (since
mix 0.21) —

```mix
ds_patch_signals({bad: sqrt(0 - 1)})
-- Runtime error: ds_patch_signals: encode signals:
--   non-finite number NaN has no JSON representation (JSON has no NaN/Infinity)
```

— and a lambda or bytes value inside the map encodes as `null`.

## ds_sse — assemble the response body

```
ds_sse(event | [events]) -> text/event-stream body
```

`ds_sse` takes one event string or a **list** of them and concatenates them into
a single body string. It does **not** re-frame or insert separators — each event
already carries its own blank-line terminator, so back-to-back events are
correctly delimited.

A single event (the round-trip is identity — `ds_sse` of one event is that event):

```mix
$body = ds_sse(ds_patch_signals({n: 1}))
print($body)
```
```text
event: datastar-patch-signals
data: signals {"n":1}

```

A multi-event stream — patch the DOM, then flip a signal, in one response:

```mix
$e1 = ds_patch_elements("<span>a</span>", {selector: "#x", mode: "inner"})
$e2 = ds_patch_signals({ready: true})
$body = ds_sse([$e1, $e2])
print($body)
```
```text
event: datastar-patch-elements
data: selector #x
data: mode inner
data: elements <span>a</span>

event: datastar-patch-signals
data: signals {"ready":true}

```

An empty list yields an empty body; a list element that is not a string is a
clear error (`ds_sse: list element N must be an SSE event string, got <type>`).

## Security — frame, never escape

Repeat, because it is the trap: **these builtins do not sanitise.** Whatever
bytes you hand `ds_patch_elements` go on the wire and into the DOM. For any
content that came from a user, a request, a database row, or any non-author
source, run `html_escape()` first:

```mix
$user = "<script>alert(1)</script>"
$ev = ds_patch_elements("<div>" .. html_escape($user) .. "</div>")
print($ev)
```
```text
event: datastar-patch-elements
data: elements <div>&lt;script&gt;alert(1)&lt;/script&gt;</div>

```

`html_escape(s)` escapes the five HTML-significant characters — `&` `<` `>` `"`
`'` (the apostrophe as `&#x27;`, the HTML5-universal form, not the HTML4-invalid
`&apos;`) — making a value safe to interpolate into HTML **element text** or an
**ordinary quoted attribute value**. That prevents *syntactic breakout* only: it
is NOT sufficient where the value is interpreted as code or a URL — event
handlers (`onclick=…`), `style=…`, `srcdoc`, or URL-valued attributes
(`href`/`src`: an entity-escaped `javascript:…` still runs). Those contexts need
scheme/context validation, not just entity escaping.

For author content authored in Markdown, `markdown()` already escapes raw HTML
and neutralises unsafe URL schemes (next section) — so
`ds_patch_elements(markdown($author_md), …)` is safe without a separate
`html_escape`.

### Frame-injection guards (built in)

The builtins fail closed against SSE frame injection even when you forget to
escape, so a stray control character cannot forge an extra event:

- **`selector`** goes into a single, un-split `data: selector …` line, so any CR or LF in it is **rejected** — a CSS selector never legitimately carries one:

```mix
ds_patch_elements("x", {selector: "#a\ndata: mode inner"})
-- Runtime error: ds_patch_elements: selector must not contain a line terminator (CR/LF)
--   — SSE frame-injection guard
```

- **`elements`** and a verbatim **`signals`** string are CR→LF normalised, then every `\n`-split line is re-prefixed with its field name — so an embedded newline (even a lone `\r` that `str::lines()` would miss) becomes another `data:` continuation line, never a frame break. A `\r\n` pair normalises to **one** `\n`, never a doubled newline (which would read as the blank-line frame separator).
- The **map path** for `signals` is JSON-encoded by serde, which escapes control characters, so its `data:` line is provably single-line.

These are defence-in-depth, **not** a substitute for `html_escape` — a guard
stops frame forgery; it does nothing about `<script>` inside an otherwise-valid
single-line fragment.

## markdown — render author content to HTML

```
markdown(md) -> HTML string
```

Renders **CommonMark + GFM** Markdown to HTML — the natural upstream of
`ds_patch_elements` for content authored in Markdown. The GFM extensions are
enabled: **tables**, **strikethrough** (`~~gone~~` → `<del>`), **task lists**
(`- [x]` → a disabled checkbox), and **footnotes**. Feature-gated on the
`markdown` feature (the `mix` binary turns it on); a Pure builtin, so always
callable in sandboxed contexts (see [capabilities](capabilities.md)).

Its output is **safe by default for author content**:

- **Raw HTML in the source is escaped** — emitted as literal text, never active markup:

```mix
print(markdown("hi <b>bold</b> <script>alert(1)</script>"))
```
```text
<p>hi &lt;b&gt;bold&lt;/b&gt; &lt;script&gt;alert(1)&lt;/script&gt;</p>
```

- **Unsafe URL schemes are neutralised** — a link or image URL whose scheme is `javascript:`, `data:`, or `vbscript:` is rewritten to `#`. The scheme check strips ASCII whitespace/control characters first (browsers ignore those inside a scheme, so a whitespace-obfuscated `<java script:…>` destination still counts as `javascript:`); relative URLs and ordinary schemes (`https:`, `mailto:`) pass through untouched:

```mix
print(markdown("[x](javascript:alert(1)) [y](https://ok.example)"))
```
```text
<p><a href="#">x</a> <a href="https://ok.example">y</a></p>
```

The companion `markdown_escape(s)` goes the other direction: it
backslash-escapes Markdown metacharacters (`\` `*` `_` `[` `]` `(` `)` `#`
`` ` `` `|` `>` `-`) so a plain-text value can be embedded in Markdown source
without becoming markup.

## webd integration

In MixOS these builtins exist so a Mix SSR handler running inside the `webd`
web daemon can drive a live page over SSE without a client-side framework. The
shape of a handler is: build event strings, assemble with `ds_sse`, and return
the body with the right content type:

```mix
-- inside a webd Mix handler (illustrative)
$rows = map($items, $render_row)          -- each -> an HTML <li>
$ev   = ds_patch_elements(join($rows, "\n"), {selector: "#list", mode: "inner"})
$body = ds_sse($ev)

return {
  status:  200,
  headers: { "Content-Type": "text/event-stream" },
  body:    $body
}
```

The Datastar JS client (loaded once in the page shell) opens the SSE connection,
reads each framed event, and applies the DOM patch or signal update — no
per-widget JavaScript, no compiled UI framework. This is the "Datastar as a
transport, not a client library" posture: the server emits patches, the browser
applies them.

## Quick reference

```text
ds_patch_elements(html)                              -- morph by element id (mode=outer)
ds_patch_elements(html, {selector, mode})            -- target + how to patch
ds_patch_elements("", {mode:"remove", selector:"#x"})-- delete (selector required)
ds_patch_elements(html, {view_transition:true})      -- wrap in a View Transition
ds_patch_signals({k:v, ...})                         -- merge a signal patch (map/list -> JSON)
ds_patch_signals($json_string)                       -- verbatim JSON signals
ds_patch_signals(sig, {only_if_missing:true})        -- set defaults only
ds_sse($event)                                       -- body from one event
ds_sse([$e1, $e2, ...])                              -- body from several events
markdown($md)                                        -- CommonMark+GFM -> safe HTML
markdown_escape($text)                               -- escape text INTO markdown source
html_escape($text)                                   -- escape text INTO html element text

-- modes: outer(default) inner remove replace prepend append before after
-- unknown option-map keys are silently ignored (no strict allowlist)
-- a NaN/inf number in a signals map raises (JSON has no NaN/Infinity)
-- ALWAYS html_escape() untrusted content before ds_patch_elements()
```

## See also

- [strings](strings.md) — string handling, interpolation and escaping rules
- [builtins index](builtins.md) — all builtin categories (the `ds_*` builtins are not bucketed by `mix builtins` — use `mix what <name>`)
- [higher-order functions](hof.md) — `map`/`filter` for building fragment lists
- [JSON & data](data.md) — `json_encode` for a verbatim `ds_patch_signals` payload, and the shared encoder rules (non-finite numbers raise)
- [capabilities](capabilities.md) — the `ds_*` and `markdown` builtins are Pure
- [Bus messaging](bus.md) — the mesh transport behind a live-data handler
- Datastar — <https://data-star.dev> (hypermedia framework, SSE patch semantics)
- The Mix repo — <https://github.com/markc/mixos>
- ARexx lineage (every app an addressable, scriptable port) — the ergonomic precedent for Mix as a control surface
- `mix what ds_patch_elements` · `mix what ds_patch_signals` · `mix what ds_sse` · `mix what markdown`

---

<!-- page: https://mixos.dev/mix/datetime/ (source: https://mixos.dev/mix/datetime.md) -->

# Dates & time

Mix represents a moment in time as a **Unix timestamp** — a plain number of seconds since the epoch (1970-01-01 00:00:00 UTC). Everything else is conversion: format a timestamp into text, parse text back into a timestamp, or describe an interval. There is no opaque "date object" — a timestamp is just a [number](numbers.md), so you do date arithmetic with `+`, `-`, and the rest of the numeric operators.

```mix
$now = time()          -- seconds since the epoch, as a float
$tomorrow = $now + 86400   -- one day later — just arithmetic
print(date_format($tomorrow, "%Y-%m-%d"))
```

The seven builtins:

| Builtin | Returns | Purpose |
|---|---|---|
| `time()` | number (float seconds) | current Unix timestamp |
| `monotonic()` | number (float seconds) | monotonic-clock reading for measuring intervals |
| `now_iso()` | string | current local time as ISO 8601 / RFC 3339 |
| `date_format(ts [, fmt])` | string | render a timestamp via strftime (**local** time) |
| `date_parse(s)` | number | parse a date string → Unix timestamp |
| `duration_format(secs)` | string | render a span of seconds as `1d 2h 3m 4s` |
| `relative_time(ts)` | string | render a timestamp as `3h ago` / `in 5m` |

`time()` and `monotonic()` are always available. The five conversion builtins are **`datetime`-feature-gated** in the library, but the shipping `mix` binary turns the feature on, so they are always present in the `mix` CLI and as a login shell. All seven are `Pure`-class (no I/O beyond reading a clock) and register under the `system` builtin category — `mix builtins system` lists them. For *pausing* rather than measuring, `sleep(n)` lives on the [system](system.md) page.

## time() — the current timestamp

`time()` returns the current Unix time as a **float** with sub-second precision (it is `SystemTime::now()` as `as_secs_f64`).

```mix
print(time())
```
```text
1783052394.0787532
```

The value obviously changes every call — examples below show the *shape*, not a fixed number. Because it is a number you can compare and subtract directly:

```mix
$t = time()
print("" .. ($t > 1700000000))
```
```text
true
```

To time a block of work, capture `time()` before and after and feed the difference to [`duration_format`](#duration_format--human-readable-spans):

```mix
$start = time()
-- ... do work ...
$elapsed = time() - $start
print("took " .. duration_format($elapsed))
```

> `time()` is a float. `date_format` / `relative_time` truncate it to whole seconds internally (`as i64`), so passing the raw `time()` value is fine — you never need to round it yourself.

The numeric inputs accept numbers and numeric strings. A supplied value that
`to_number` cannot parse raises `TYPE_MISMATCH`; it never silently becomes the
epoch or a zero-duration result.

## monotonic() — the clock that never goes backwards

`monotonic()` returns seconds on the kernel's `CLOCK_MONOTONIC` clock as a **float**. Use it **instead of `time()` whenever you are measuring an interval rather than stamping a calendar moment**: `time()` is wall-clock time, and NTP can step or slew it, so a `time() - $start` difference can come out wrong — even negative — across a clock adjustment. `monotonic()` never goes backwards (two successive reads always satisfy `later >= $earlier`), which is exactly the property an elapsed-time, timeout, or "did this happen before that" computation needs. It is also the clock the compositor's frame traces stamp (`start_us`/`end_us` in the compositor's `FRAME_TRACE` records), so a Mix measurement can be correlated with a compositor trace from the same machine.

```mix
$start = monotonic()
-- ... do work ...
print("took " .. (monotonic() - $start) .. "s")
```

The trade-offs: the epoch is unspecified (on Linux it usually counts from machine boot), so the absolute value means nothing across reboots or other machines — only differences and ordering — and `date_format`/`duration_format` have nothing useful to say about it. It also does not include time the machine spends suspended.

## now_iso() — current local time as a string

`now_iso()` takes no arguments and returns the current **local** time as an RFC 3339 string (chrono's `Local::now().to_rfc3339()`), including the fractional seconds and the offset from UTC.

```mix
print(now_iso())
```
```text
2026-07-03T14:19:54.080883176+10:00
```

The trailing `+10:00` is the machine's local UTC offset (here AEST). Use `now_iso()` for log lines and timestamps you want a human to read at a glance; use `time()` when you need a number to do arithmetic on.

## date_format(ts [, fmt]) — timestamp → text

`date_format` turns a Unix timestamp into a string using a **strftime** pattern. The timestamp is interpreted as UTC seconds, then **converted to the machine's local timezone** before formatting.

- Argument 1: the timestamp (number; a float is truncated to whole seconds).
- Argument 2 (optional): the strftime format string. **Default is `"%Y-%m-%d %H:%M:%S"`.**

```mix
print(date_format(1700000000))
```
```text
2023-11-15 08:13:20
```

(That output is in local time, +10; the same instant is `2023-11-14 22:13:20` in UTC.)

Custom patterns — these are [chrono](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) strftime specifiers:

```mix
print(date_format(1700000000, "%Y-%m-%d"))
print(date_format(1700000000, "%A, %d %B %Y"))
print(date_format(1700000000, "%H:%M"))
print(date_format(1700000000, "%I:%M %p"))
print(date_format(1700000000, "%a %j %s"))
```
```text
2023-11-15
Wednesday, 15 November 2023
08:13
08:13 AM
Wed 319 1700000000
```

Common specifiers:

| Token | Meaning | Token | Meaning |
|---|---|---|---|
| `%Y` | 4-digit year | `%H` | hour, 24h (00–23) |
| `%m` | month (01–12) | `%I` | hour, 12h (01–12) |
| `%d` | day of month (01–31) | `%M` | minute (00–59) |
| `%B` / `%b` | month name / abbrev | `%S` | second (00–60) |
| `%A` / `%a` | weekday name / abbrev | `%p` | AM/PM |
| `%j` | day of year (001–366) | `%z` | UTC offset (`+1000`) |
| `%s` | Unix timestamp | `%%` | a literal `%` |

`date_format` needs at least one argument:

```mix
print(date_format())
```
```text
Runtime error at line 1: date_format() expects at least 1 argument(s), got 0
```

### Local vs UTC — read this

`date_format` always renders in the **machine's local timezone** — there is no UTC-output variant and no timezone argument. If you need UTC output, format the offset into the string and reason about it yourself, or include `%z`/`%Z` so the offset is explicit:

```mix
print(date_format(1700000000, "%Y-%m-%d %H:%M:%S %z"))
```
```text
2023-11-15 08:13:20 +1000
```

## date_parse(s) — text → timestamp

`date_parse` converts a date string back into a Unix timestamp (a number). It tries three formats in order and returns on the first that matches:

1. **RFC 3339 / ISO 8601** with an explicit offset or `Z` — e.g. `2023-11-15T08:13:20+10:00`, `...Z`. The offset is honoured.
2. **`%Y-%m-%d %H:%M:%S`** (space-separated) — interpreted as **UTC**.
3. **`%Y-%m-%d`** (date only) — interpreted as **UTC midnight**.

```mix
print("" .. date_parse("2023-11-15T08:13:20+10:00"))
print("" .. date_parse("2023-11-15T08:13:20Z"))
print("" .. date_parse("2023-11-15 08:13:20"))
print("" .. date_parse("2023-11-15"))
```
```text
1700000000
1700036000
1700036000
1700006400
```

Note the difference: the offset form `+10:00` lands on `1700000000`, while the bare `2023-11-15 08:13:20` is read as UTC and lands on `1700036000` (10 hours later). **The space and date-only forms have no timezone, so they are always UTC** — supply an explicit offset when you mean local time.

Two edge cases of the format list:

- **Fractional seconds parse in the RFC 3339 form only**, and are truncated — `date_parse("2023-11-15T08:13:20.5+10:00")` returns `1700000000` (whole seconds; the result is always an integral number).
- **A `T`-separated string *without* an offset does not parse.** `date_parse("2023-11-15T08:13:20")` raises — RFC 3339 requires the offset (or `Z`), and the offset-less fallback format is the *space*-separated `%Y-%m-%d %H:%M:%S` only. Swap the `T` for a space, or append an offset.

Anything that matches none of the three formats raises a catchable runtime error:

```mix
print("" .. date_parse("15/11/2023"))
```
```text
Runtime error at line 1: date_parse: cannot parse '15/11/2023'
```

Wrap it in [`try`/`catch`](errors.md) when the input is untrusted:

```mix
try
  $ts = date_parse($input)
  print(date_format($ts, "%Y-%m-%d"))
catch $e
  print("bad date: " .. ("" .. $e))
end
```

### The round-trip gotcha (parse-then-format)

`date_parse` treats the timezone-less forms as **UTC**, but `date_format` renders in **local** time — so a naive round-trip shifts by your UTC offset:

```mix
$ts = date_parse("2023-11-15 08:13:20")   -- read as 08:13:20 UTC
print(date_format($ts, "%Y-%m-%d %H:%M:%S %z"))
```
```text
2023-11-15 18:13:20 +1000
```

Parsed at `08:13:20` UTC, re-rendered at `18:13:20 +1000`. This is correct behaviour (same instant, two zones), but it surprises people. To round-trip text-identically, either include an explicit offset in the input that matches your locale, or format with the offset printed (`%z`/`%Z`) so the shift is visible.

## duration_format — human-readable spans

`duration_format(secs)` turns a number of seconds (an *elapsed time*, not a timestamp) into a compact `Nd Nh Nm Ns` string. It drops any zero leading units, but always shows at least `0s` for a zero span. A float is truncated to whole seconds.

```mix
print(duration_format(0))
print(duration_format(45))
print(duration_format(90))
print(duration_format(3600))
print(duration_format(3661))
print(duration_format(8100))
print(duration_format(90061))
print(duration_format(125.9))
```
```text
0s
45s
1m 30s
1h
1h 1m 1s
2h 15m
1d 1h 1m 1s
2m 5s
```

The breakdown is days / hours / minutes / seconds (1 day = 86400s); there is no weeks/months unit. Zero-valued **leading and middle** units are omitted (`2h 15m` has no `0s`, `1h` has no minutes), but the result is never empty. A **negative** input clamps to `0s` (the seconds are cast to an unsigned count before splitting) — an elapsed span is never negative, so take `abs()` first if your subtraction can go either way. Pair it with a `time()` difference for an uptime/elapsed readout:

```mix
$elapsed = 5025
print("uptime " .. duration_format($elapsed))
```
```text
uptime 1h 23m 45s
```

## relative_time — "3h ago" / "in 5m"

`relative_time(ts)` compares a timestamp against **now** (`Utc::now()`) and renders the gap as a short relative phrase. Past times read `... ago`; future times read `in ...`.

```mix
print(relative_time(time() - 30))
print(relative_time(time() - 7200))
print(relative_time(time() - 172800))
print(relative_time(time() + 300))
print(relative_time(time() + 90000))
```
```text
30s ago
2h ago
2d ago
in 5m
in 1d
```

The granularity is a single largest unit, truncating: under 60s → `Ns`, under an hour → `Nm`, under a day → `Nh`, otherwise `Nd`. It picks one unit only (no `2h 5m` — `7200`s reads `2h`, and `7800`s also reads `2h`). For a precise span use `duration_format` on the difference instead.

## Patterns

### Stamp a log line

```mix
print(now_iso() .. "  starting job")
```
```text
2026-07-03T14:19:54.080883176+10:00  starting job
```

### "Last seen" in a table row

```mix
$rows = [
  { name: "alpha", last: time() - 45 },
  { name: "node1", last: time() - 9000 }
]
for each $r in $rows
  print($r["name"] .. ": " .. relative_time($r["last"]))
end
```
```text
alpha: 45s ago
node1: 2h ago
```

### Day-bucket a timestamp (group events by date)

```mix
$ts = 1700000000
$day = date_format($ts, "%Y-%m-%d")
print("bucket " .. $day)
```
```text
bucket 2023-11-15
```

### Compute a deadline and show it both ways

```mix
$deadline = time() + 3600
print("due " .. date_format($deadline, "%H:%M") .. " (" .. relative_time($deadline) .. ")")
```
```text
due 15:20 (in 1h)
```

## Gotchas

- **A timestamp is a number, an elapsed span is a number — don't confuse them.** `date_format`/`relative_time` take an absolute timestamp (seconds since epoch); `duration_format` takes a duration (seconds of elapsed time). `duration_format(time())` prints a meaningless `20637d 4h …` (the age of the epoch).
- **`date_format` is always LOCAL; `date_parse` treats offset-less input as UTC.** There is no timezone parameter on either. Naive parse→format round-trips shift by your UTC offset (see above) — include `%z` or an explicit offset to make it visible.
- **Newline or `;` separates statements** — `mix -c '$t = time(); print(date_format($t))'` is valid Mix. A shell-dispatch line still gives `;` its shell command-list meaning (see [shell](shell-mode.md)).
- **Concatenate with `..`, never `+`.** `print("at " .. date_format($t))` — `+` is numeric addition only.
- **`$name` is literal inside `"double quotes"`.** Build strings with `..` concat (`"day " .. $day`); only `${name}` interpolates. See [strings](strings.md).
- **Sub-second precision is dropped on format.** `date_format`/`relative_time` truncate the float to whole seconds; `now_iso()` keeps nanoseconds because it formats `Local::now()` directly.
- **Bad numeric input raises.** A numeric string (`"1700000000"`) works, but a non-numeric string — including `"inf"`/`"nan"`/`"1e999"`, rejected by strict coercion since 0.21 — raises `TYPE_MISMATCH` from `date_format`, `relative_time`, and `duration_format`. A timestamp outside chrono's representable range (for example `1e18`) raises `VALUE_OUT_OF_RANGE`; it never clamps to the epoch.
- **`date_parse` raises on no match** — only the three documented formats parse (and `T`-separated input *must* carry an offset). Wrap untrusted input in `try`/`catch`.
- **No date *math* helpers** (add-month, day-of-week-of, business-day). Do arithmetic on the raw timestamp (`$t + 86400` for +1 day) and read fields back via `date_format` strftime tokens like `%A`/`%j`.

## See also

- [math](math.md) — numeric operators and functions (timestamps are numbers; `abs`, `round`)
- [numbers](numbers.md) — numeric coercion rules, `to_number`/`is_number`
- [strings](strings.md) — `..` concat, interpolation, formatting output
- [errors](errors.md) — `try`/`catch` for `date_parse` failures
- [system](system.md) — `sleep(n)`, `run`/`run_rc` timeouts, process helpers
- [builtins index](builtins.md) — the full builtin catalogue
- [shell](shell-mode.md) — `mix -c` one-liner rules (newlines, classifier)
- chrono strftime reference — <https://docs.rs/chrono/latest/chrono/format/strftime/index.html>
- Run `mix help` for the category listing, or `mix what date_format` (also `time`, `monotonic`, `date_parse`, `now_iso`, `duration_format`, `relative_time`) for a one-line description of any builtin.

---

<!-- page: https://mixos.dev/mix/errors/ (source: https://mixos.dev/mix/errors.md) -->

# errors — error handling & exit control

Mix has one error channel and three ways to use it: **catch** an error and recover
(`try … catch $e … end`), **raise** one deliberately (`die`), or **stop the whole
process** (`exit`, or the uncatchable `panic`). `exit` first unwinds active
`finally` cleanup; `panic` aborts past it. Command failures are split two ways
on purpose — `run` *raises* (catch it or it kills the script), while `run_rc`
*returns a status map* you branch on. The parser and evaluator have resource caps
(nesting, recursion) that turn a runaway script into a **clean, catchable error**
instead of a native crash.

Mental model: when you `catch $e`, `$e` is the **message string** — unchanged since
the beginning. Since 0.29.0 every runtime error ALSO carries a structured payload
(a stable `code`, optional `details` map, and a call traceback); bind it with the
optional second catch variable — `catch $msg, $err` — and raise your own with
`raise(code, message[, details])`. Since 0.30.0 a `finally` clause runs on every
exit path. There is no exception hierarchy.

## The two kinds of failure

| | Raised by | Catchable by `try`? | Exit code if uncaught |
|---|---|---|---|
| **`die` error** | `die "msg"`, `run(...)` on non-zero exit or timeout | **yes** | 1 |
| **runtime error** | unbound `$var`, bad builtin arg, recursion cap, division/modulo by zero, `ssh_must(...)` on failure | **yes** | 1 |
| **lexer / parse error** | bad syntax (a misplaced `;` inside an expression, missing operand, nesting cap) | **no** — fails before any code runs | 1 |
| **`panic(...)`** | the `panic` builtin only | **no** — aborts the process (see [§ panic](#panic--the-uncatchable-abort)) | 101 (Rust panic abort) |
| **`exit(code)`** | the `exit` builtin | **no** — it *is* the exit | `code` |

The dividing line: `try` catches the two errors that happen **while your code is
running** (`die` and runtime errors). A **syntax** error is detected at parse time —
before the first statement executes — so no `try` can wrap it. `exit` and `panic`
are not errors at all and cannot land in `catch`: `exit` is an interpreter control
signal that runs `finally` while unwinding to the process boundary; `panic` aborts.

## Structured errors, codes & tracebacks (0.29.0)

Every catchable error carries a structured payload. `catch $msg, $err` binds it —
`$msg` stays the plain message string, `$err` is a map:

```mix
try
  raise("VALIDATION_REQUIRED", "node is required", {field: "node"})
catch $msg, $err
  print($err.code)             -- VALIDATION_REQUIRED
  print($err.message)          -- node is required
  print($err.details.field)    -- node
  print(length($err.frames))   -- call traceback, outermost first
end
```

- `$err.code` — a stable `UPPER_SNAKE` identifier. Legacy errors surface as `RUNTIME_ERROR` (generic runtime failures) and `USER_DIE` (`die`, plus `run` non-zero/timeout today). Emitted today: `NAME_UNDEFINED`, `FUNCTION_UNDEFINED`, `CAPABILITY_DENIED`, `TYPE_MISMATCH`/`OPTION_INVALID` (argument validation), `VALUE_OUT_OF_RANGE` (a typed value outside a backend's representable domain), `TOML_UNREPRESENTABLE` (`toml_encode`, with `{path,type}` details), the `PROCESS_*` family (`run_argv`/`run_argv_must`), the `PIPELINE_*` family (`run_pipeline`/`run_pipeline_must`), `STDIN_TERMINAL` (`stdin: {inherit: true}` while mix's own stdin is a terminal — see [system](system.md#run_argv--structured-argv-execution-v0290)), `WRITE_TOO_LARGE` (`write_atomic` over its `max_bytes`), `WRITE_NOT_ATOMIC` (`write_atomic` on a target that is a mount point, e.g. a bind-mounted file — nothing was written), `WRITE_NOT_DURABLE` (`write_atomic` with `durability: "full"` replaced the file but the directory fsync failed — `details.replaced` is `true`), the `VALIDATION_*` family (`validate` and friends), and `IO_BROKEN_PIPE`/`IO_WRITE_FAILED` (`write_stdout`/`write_stderr` and their `print_raw`/`eprint_raw` aliases — see [io](io.md#a-failed-write-raises--print-included-since-0990); `print`/`printf` still discard write errors). The `SSH_*`/`HTTP_*` families are reserved and roll out as those builtins migrate (0.29–0.30); until then ssh/http failures surface as `RUNTIME_ERROR`/`USER_DIE`. Codes are stable identifiers, never reused; scripts may define their own.
- `$err.message` — the same string `$msg` binds.
- `$err.error_code` — an alias of `code`, for forwarding a refusal as
  `{error_code: $err.error_code, message: $err.message}` with a nonzero reply RC.
- `$err.details` — an operation-specific map (`nil` when the error carries none).
- `$err.cause` — a nested error map, or `nil` (used by wrapping layers).
- `$err.frames` — the call traceback, a list of `{kind, function, file, line, column}` maps, outermost-to-innermost with the failure site last. `kind` is `"script"` or `"builtin"`. Frames cover the standard call path; the numeric fast paths contribute no frames, and `column` is always `nil` today.

`PROCESS_STDIO` means `run_argv` could not set up a requested
`stdin`/`stdout`/`stderr` destination before spawning the child — opening or
creating a route file, or creating the pipe/descriptor a `stderr: "stdout"`
merge needs. `run_argv` encodes it in
the returned process_result (`ok: false`, `exit_code: nil`); `run_argv_must`
raises the same code with that result under `$err.details.result`. The child is
not spawned after this setup failure. No route is truncated until all routes
have opened; truncation itself is not transactional, so a later truncation
failure can leave an earlier route truncated. A deadline expiring while an
input FIFO waits for a writer is also `PROCESS_STDIO`; Mix wakes and reaps the
open worker before returning, so repeated failures do not leak blocked threads.

Capture abandonment is a deadline/interrupt cleanup outcome, not a
`PROCESS_IO` error. The returned captured prefix is marked truncated, and an
abandoned `stream: true` reader stops teeing before the call returns; an
already-blocked parent-stream write can delay that return. With `timeout: 0`,
normal completion waits for capture EOF and for any stdin-data writer, rather
than abandoning either worker. Late descendant output is returned untruncated;
a descendant retaining stdin without reading can make the explicit no-deadline
call wait indefinitely.

The pipeline family is distinct because a pipeline can fail in a middle stage
while its final stage exits 0. The codes split by which builtin can produce
them, exactly as `PROCESS_*` does.

**Returned in the pipeline_result** (`ok: false`, `error_code` set) by
`run_pipeline`, and raised with that same result under `$err.details.result` by
`run_pipeline_must` — these are setup/lifecycle failures, never ordinary
command failure:

- `PIPELINE_STDIO` — a requested stdin/stdout/stderr file or pipe could not be
  opened or created. Every stage's routes and every pipeline/capture pipe are
  prepared before any stage is spawned, so this code means no stage ran. No
  route is truncated until the full set has opened, but the later truncation
  pass is not transactional.
- `PIPELINE_SPAWN` — a stage could not be spawned. If earlier stages had
  already started, `.stages` contains their reaped outcomes; captured stderr
  abandoned during that cleanup is empty and marked truncated.
- `PIPELINE_IO` — writing pipeline stdin or draining captured output failed.
- `PIPELINE_INTERNAL` — process polling, waiting, or a pipeline worker failed.

**Raised only by `run_pipeline_must`.** `run_pipeline` reports these outcomes as
data — `ok`, `exit_code`, `signal`, `timed_out`, `interrupted`,
`stdout_truncated`/`stderr_truncated` — and leaves `error_code` nil:

- `PIPELINE_EXIT_NONZERO` — at least one stage exited non-zero.
- `PIPELINE_SIGNAL` — a stage was signal-killed and was not an accepted
  non-final SIGPIPE.
- `PIPELINE_TIMEOUT` — the whole-pipeline deadline expired.
- `PIPELINE_INTERRUPTED` — Ctrl-C interrupted the pipeline.
- `PIPELINE_OUTPUT_LIMIT` — a captured stream exceeded `max_output`.

`raise(code, message[, details])` raises a catchable structured error. The code
must match `[A-Z][A-Z0-9]*(_[A-Z0-9]+)*` and `details` must be a map when given.

An **uncaught** error that crossed a function or builtin boundary prints a
traceback to stderr (exit 1, as before):

```text
Traceback (most recent call last):
  at <main> (/path/job.mix:7)
  at provision (/path/job.mix:2)
  at connect (/path/job.mix:5)
  at <builtin:raise> (/path/job.mix:5)
SSH_TIMEOUT: remote operation exceeded 60 seconds
```

`mix --no-traceback script.mix` restores the legacy single-line rendering
(`Runtime error at file:line: message`); errors that never crossed a function
boundary render single-line either way, so shallow scripts and stderr scrapers
are unaffected. Deep stacks elide the middle frames in the *rendering* only —
`$err.frames` always holds the full list.

One field-name note: `$err.frames[0].function` works — `function` is accepted in
field position since 0.29.0 (`fn` reads the same field; map-literal and
strict-data keys still require quoting `"function"`).

### Errors that teach (0.79.0)

Four cheap additions turn a runtime failure from a statement of what is wrong
into a pointer at the fix. All are display/message enrichments — `$err.code`
and the traceback shape are unchanged, so catch-based scripts and scrapers see
the same structure.

- **`FUNCTION_UNDEFINED` suggests a name.** A typo resolves to the nearest
  builtin or in-scope user function (edit distance ≤ 2, tightening to ≤ 1 for
  short names): `undefined function 'lenght' — did you mean 'length'?`. The
  same applies to `NAME_UNDEFINED` for a `$variable` read, suggesting the
  nearest name in scope.
- **Deleted builtins name their replacement.** Calling a name removed by a
  release — the five pattern-first regex/grep names deleted in 0.73.0, and any
  future removal — reports the rename rather than a bare "undefined":
  `undefined function 'grep' — deleted in mix 0.73.0; use grep_lines(text, pattern)`.
  This is the same table that drives the `MIX-D3001`–`D3005` lint notes, so
  authoring-time and run-time guidance cannot drift.
- **Builtin refusals point at the manual.** A builtin's *coded* contract
  violation or refusal (a `TYPE_MISMATCH`, `OPTION_INVALID`, `VALIDATION_*`,
  … — not an arity error, not a bare `raise`/`die`) ends with a pointer to the
  page that documents it: `OPTION_INVALID hash_sha256(): unknown option 'rawr'
  (only 'raw' is accepted) (see: mix man system)`. Read the whole page with
  `mix man <topic>`.
- **The offending source line prints under the error.** An uncaught error whose
  failure site is in the top-level source (a `-c` body or the script file) shows
  that line beneath it, rustc-style — rendered from the exact bytes that ran, so
  it is never stale:

  ```text
  Runtime error at job.mix:2: undefined variable '$y' — did you mean '$x'?
    2 | print($y)
  ```

  A failure inside an imported module (a different file) prints no line rather
  than risk a stale disk read.

## try … catch — recover from a failure

```mix
try
  die("boom: something failed")
catch $e
  print("caught: " .. $e)
end
print("after")
```
```text
caught: boom: something failed
after
```

`catch $e` binds the **message string** to `$e`. The block closes with `end` (no
`do`; statements use newline or `;` separators). A `catch` clause is
**mandatory**: a bare `try … end` is a parse error.

```mix
try
  print("hi")
end
```
```text
Parse error at line 3:1: unexpected token End
```

### It also catches runtime errors

Not just `die` — any runtime error (an unbound variable, a bad builtin argument)
is caught by the same `catch`:

```mix
try
  print($nope)
catch $e
  print("caught: " .. $e)
end
```
```text
caught: undefined variable '$nope'
```

```mix
try
  sqrt("hello")
catch $e
  print("caught: " .. $e)
end
```
```text
caught: sqrt() expects a number, got string
```

### `$e` is a string, not an object

There is no `$e.message` / `$e.code` — `$e` *is* the message. Use it with `..`
concat, `contains()`, `split()`, or any [string](strings.md) builtin:

```mix
try
  die("disk full: /var")
catch $e
  if contains($e, "disk full") then
    print("handling disk-full path")
  end
end
```
```text
handling disk-full path
```

This holds even when `die` is given a non-string: the argument is **stringified**
at the raise. `die(42)` catches as the *string* `"42"` (`length($e)` is 2), and
`die({code: 7})` catches as the map's repr text — `$e["code"]` fails with *cannot
index string with string*. If you want structured error data, put it *in* the
message yourself (e.g. a JSON string) and `json_parse($e)` in the catch — Mix
won't do it for you.

### `catch $e` is a function-local binder

Inside a function, `catch $e` binds `$e` **locally** — it shadows, and cannot
clobber, a same-named caller/global variable (the same rule as loop vars and
parameters — see [functions](functions.md)):

```mix
$e = "outer"
function risky()
  try
    die("inside")
  catch $e
    print("local e: " .. $e)
  end
end
risky()
print("outer e still: " .. $e)
```
```text
local e: inside
outer e still: outer
```

### `finally` — cleanup that always runs (0.30.0)

A `finally` clause runs on **every** exit path of the `try`: normal completion, a
caught error, and a *propagating* error, `return`, `break`, or `continue`. It is
the right place for cleanup that must happen whether or not the work succeeded
(remove a temp file, unmount, release a lock). `catch` is optional when `finally`
is present — a `try … finally … end` runs the finally body, then lets the error
propagate. At least one of `catch`/`finally` must be present.

```mix
function provision($tmp)
  try
    do_work($tmp)          -- may die
    return "ok"
  finally
    remove($tmp)           -- runs on success, on die, and on the return
  end
end
```

`finally` runs after any `catch` body, on `return`/`break`/`continue` out of the
`try`, on an uncaught error, and while `exit()` unwinds towards the process
boundary. Nested cleanup runs innermost-to-outermost. Only `panic()`, SIGKILL, or
another process-level abort bypasses it.

Control replacement follows one rule: an outcome produced by `finally` overrides
the outcome that entered it. A later/inner `exit(9)` therefore replaces a pending
`exit(2)`. If `finally` raises while an exit is pending, the cleanup error wins and
is catchable by an outer `try`; the exit is not stored as `$err.cause` because an
exit request is control flow, not an error payload. When both outcomes are errors,
the displaced error remains available as `cause` (readable via
`catch $msg, $err` → `$err.cause`), so a cleanup failure never silently hides the
error it replaced.

### Nested try and re-raising

A `catch` body can `die` again; the next enclosing `try` catches it. There is no
`rethrow` keyword — just `die($e)` (or a new message):

```mix
try
  try
    die("inner")
  catch $e
    print("inner caught: " .. $e)
    die("rethrown: " .. $e)
  end
catch $outer
  print("outer caught: " .. $outer)
end
```
```text
inner caught: inner
outer caught: rethrown: inner
```

> **`return` / `break` / `continue` / `exit` are not errors.** They unwind through
> a `try` without being caught. A `return` inside a `try` body returns from the
> enclosing function; `exit()` continues through every enclosing `finally` and is
> consumed only by the process boundary.

## die — raise a catchable error

`die` is a statement that takes an expression (parentheses optional). Uncaught, it
prints the message to **stderr** and exits **1**:

```mix
print("one")
die("stop here")
print("two")
```
```text
one
stop here
exit=1
```

Both call styles work and are equivalent:

```mix
die("with parens")
die "no parens"
```

The message is any expression — build it with `..`:

```mix
$code = 42
die("exit code " .. $code)
```

Use `die` for **must-succeed** steps where you want fail-fast rather than a status
check — and wrap the section in `try` if a caller should recover:

```mix
try
  run("install -m 0755 src dst")   -- run() dies on non-zero exit
  print("installed")
catch $e
  print("install failed: " .. $e)
end
```

## run vs run_rc — the two command-failure styles

This is the most important practical distinction. See [running commands](system.md) for
the full surface; here is the error angle.

**`run(cmd)`** returns stdout as a string and **raises a catchable `die`** on a
non-zero exit — fail-fast:

```mix
try
  run("false")
catch $e
  print("run died: " .. $e)
end
```
```text
run died: run: 'false' failed (rc=1)
```

When the failed command wrote to stderr, `run`'s message appends a stderr tail:
`run: 'ls /no/such/path' failed (rc=2): ls: cannot access '/no/such/path': No
such file or directory` — so the caught `$e` usually already says *why*.

**`run_rc(cmd)`** **never raises** — it returns a map
`{rc, stdout, stderr, timed_out, interrupted}` you branch on. The exit code is
*data*, not `$?` soup:

```mix
$r = run_rc("false")
print("rc=" .. $r.rc)
if $r.rc != 0 then
  print("command failed, continuing")
end
```
```text
rc=1
command failed, continuing
```

`run_rc` also captures stderr, so you can log *why* it failed without aborting:

```mix
$r = run_rc("ls /no/such/path")
print("rc=" .. $r.rc)
print("stderr=" .. trim($r.stderr))
```
```text
rc=2
stderr=ls: cannot access '/no/such/path': No such file or directory
```

### Timeouts, Ctrl-C, and signals

Both `run` and `run_rc` take an optional trailing `{timeout: seconds}` opts map.
The default is `0` = **no deadline** (the historic contract for long builds); a
bounded call is killed at the deadline (own process group, SIGKILL path — it can
never wedge the shell). Each failure mode follows the split above — `run` raises,
`run_rc` reports:

| Event | `run` | `run_rc` |
|---|---|---|
| deadline hit | dies (catchable): `run: 'sleep 5' timed out after 1s` | returns `rc: -1, timed_out: true` |
| Ctrl-C during the child | raises `run: interrupted` | returns `rc: -2, interrupted: true` |
| child killed by a signal | dies: `run: '…' failed (rc=143)` | `rc` = shell-convention **128+sig** (SIGTERM → 143) |

```mix
$r = run_rc("sleep 30", {timeout: 5})
if $r.timed_out then
  print("gave up after 5s")
end
```

Two things to know about the sentinels: the **negative** `rc` values (`-1`
timeout, `-2` interrupt) can never collide with a real child exit (`0..255`,
including `128+sig`); and an **interrupt is a stop request, not a recoverable
error** — after Ctrl-C the interpreter winds the script down and the process
exits with status `130` (`128 + SIGINT`) for non-interactive execution and
`--result-fd`, even if a `catch` returns successfully. Plain execution on an
interactive terminal retains status `0`. Don't build recovery logic on catching
`run: interrupted` or branching on `.interrupted` (later statements may not run).

A `catch` or `finally` that catches the interrupt gets about **one second** of
cleanup. If it is still computing after that (a loop that never waits), the
interrupt becomes standing: catches cannot resume execution, and a `finally`
cannot replace the pending interrupt with `return`, `break` or `continue`.
The flag is reasserted every 20 ms until the evaluation unwinds — so a
SIGINT always ends a non-interactive `mix` (script, `-c`, a function command,
`--serve`), whatever its handlers do. Cleanup that waits on something (`sleep`,
a Bus `send`) is cut short sooner, at its first wait.

The opts map is validated loudly (and catchably): an unknown key raises
`run_rc: unknown opt "bogus" (supported: timeout)`, and a surplus argument raises
`run() expects at most 2 argument(s), got 3` — a misplaced opts map errors instead
of running unbounded.

**Choosing:** loop over many commands and keep going → `run_rc` + `.rc` branch. One
step that *must* succeed before the next → `run` inside a `try` (or let it abort).

```mix
$cmds = ["true", "false", "true"]
for each $c in $cmds
  $r = run_rc($c)
  if $r.rc == 0 then
    print($c .. " ok")
  else
    print($c .. " FAILED rc=" .. $r.rc)
  end
end
```
```text
true ok
false FAILED rc=1
true ok
```

The same split exists for SSH: **`ssh_run`** returns a map (with `.ok`,
`.exit_code`, `.timed_out`, `.interrupted`) and never raises; **`ssh_must`**
returns the stdout string and raises a catchable Mix error on any non-success —
non-zero exit, timeout, interrupt, or signal — with the host, disposition, and
exit code in the message (`ssh_must: <what> on <host> (exit_code=N): <stderr>`).
See [remote execution](remote.md) and `mix what ssh_run` / `mix what ssh_must`.

## exit — stop the process with a code

`exit(code)` requests process termination with that status. `exit()` defaults to
0. It is **not** an error and **not** catchable: execution immediately unwinds
through every active `finally` block, innermost first, then the script, `-c`, stdin,
REPL, or serve entrypoint terminates with the requested code. Ordinary statements
after the call never run:

```mix
print("before exit")
exit(3)
print("never")
```
```text
before exit
exit=3
```

`exit` is for *deliberate* control-flow termination (a CLI tool reporting a status
to its caller). For a *failure* you want a script-level recovery point to see, use
`die` instead — `die` is catchable, `exit` is not.

The same rule applies inside `catch`: `exit()` leaves the catch body, runs that
try's `finally` if present, then keeps unwinding. An `exit()` called by a `finally`
replaces an earlier pending exit; a cleanup error raised by `finally` overrides a
pending exit, as described above.

## panic — the uncatchable abort

```mix
panic("hard abort")   -- aborts via a Rust panic; NOT caught by try
```

`panic` exists for one narrow purpose: it is the hard-abort primitive that the
**Bus `--serve` handler boundary**
(SPEC 18 §3.4 — formal spec in the operator control repo) is designed to *isolate*. In
`mix --serve`, a panic raised inside an `on … end` handler is caught by the
per-handler boundary, its payload sanitized, and the supervisor keeps running — that
survival is the acceptance gate the boundary proves. **Outside a handler it aborts
the process like any Rust panic, and `try` does not catch it** — uncaught, it
prints a raw `thread 'main' panicked at …` trace to stderr (not a Mix error line)
and exits **101**, the Rust panic status. You almost never want `panic` — reach
for `die` (catchable) for ordinary failures. See [serve mode](serve.md).

## Resource caps — runaways become clean errors

The point of the caps is that a pathological script (or a hostile one in an embedded
daemon) returns a **clean error** instead of taking down the process with a native
stack overflow or OOM.

### Recursion depth

The `mix` binary caps function-call recursion at **128** (the library default for
embedders is a more conservative 16). Past it you get a catchable runtime error, not
a SIGSEGV:

```mix
function f($n)
  return f($n + 1)
end
try
  f(0)
catch $e
  print("caught: " .. $e)
end
```
```text
caught: recursion depth exceeded (limit 128)
```

Because it is a *runtime* error, you can catch it — but the right fix is almost
always to rewrite unbounded recursion as a loop or a [HOF](functions.md)
(`reduce`/`map`).

### Parser nesting depth

The parser caps expression/statement nesting at **200**. Over-deep nesting
(`((((…`, deeply nested `if`/maps) is a **parse error** — it happens before any code
runs, so it is *not* catchable:

```mix
print((((( ... 201 levels ... )))))
```
```text
Parse error at line 1:202: nesting too deep (limit 200)
```

Other bounded builtins follow the same philosophy — `repeat`/`lpad`/`rpad` reject a
result over 256 MiB, `range` over 10M elements, `http_*` a body over 64 MiB — each a
normal runtime error rather than an OOM. `substr` clamps an out-of-range
length/offset rather than panicking. The `http_*` builtins also carry a **30-second
total-request deadline by default** (override with a trailing `{timeout: N}` opts
map, `{timeout: 0}` disables) — a stalled server becomes a catchable error, not a
wedged script. See [HTTP](http.md).

## Syntax errors are not catchable

A lexer or parse error is reported before the first statement executes, so wrapping
it in `try` does nothing — the whole source fails to compile:

```mix
try
  $x =
catch $e
  print("caught: " .. $e)
end
```
```text
Parse error at line 2:7: unexpected token Newline
```

This is about **your** source. Bad syntax in a data file someone else wrote is
an ordinary runtime condition, and `load_data` raises it as a catchable
`RuntimeError` naming the path — see [data](data.md). (Before 0.36.1 it leaked
the parse error, so a config typo aborted past the `catch` with exit 1.)

Semicolons are valid executable-Mix statement separators, so compact error
handling is legal too:

```text
$ mix -c 'print("a"); print("b")'
a
b
```

A semicolon is not universally legal punctuation: it must follow a complete
statement at a real statement boundary. `print(1; 2)`, `print((1; 2))`, and
`print(1) &&; print(2)` are parse errors, and nothing runs. See the authoritative
[statement-separator contract](syntax.md).

Classification remains whole-line: `print(1); echo hi` is a Mix parse error,
not a request to execute half Mix and half shell. On a shell-dispatch line,
`echo a; echo b` keeps the shell command-list meaning. See [overview](overview.md).

## Error message anatomy

Uncaught, each error kind prints a recognisable prefix and exits 1:

| Error | Printed form |
|---|---|
| `die` | the message verbatim, e.g. `fatal` |
| runtime | `Runtime error at line N: <msg>` |
| parse | `Parse error at line N:C: <msg>` |
| lexer | `Lexer error at line N:C: <msg>` |

```text
$ mix -c 'die("fatal")'         ; echo $?    →  fatal               1
$ mix -c 'print($x)'            ; echo $?    →  Runtime error …     1
$ mix -c '$x ='                 ; echo $?    →  Parse error …       1
```

When the error comes from a script **file** (rather than `mix -c`), the runtime
form names it: `Runtime error at /path/script.mix:1: undefined variable '$nope'`.

When caught, `$e` holds only the human-readable `<msg>` part (no `Runtime error at
line N:` prefix) — as seen in the examples above (`undefined variable '$nope'`).

## Idioms

**Validate, then fail fast.**
```mix
$path = args()[0]
if is_empty($path) then
  die("usage: tool <path>")
end
```

**Try a recoverable step, fall back.**
```mix
$cfg = nil
try
  $cfg = json_parse(read_file("/etc/app/config.json"))
catch $e
  print("no config (" .. $e .. "), using defaults")
  $cfg = { port: 8080 }
end
```

**Branch on command status instead of catching.**
```mix
if run_rc("systemctl is-active some-service").rc == 0 then
  print("service up")
else
  print("service down")
end
```

**Bound a command that might hang, branch on the outcome.**
```mix
$r = run_rc("curl -s https://example.com/health", {timeout: 10})
if $r.timed_out then
  print("health check hung")
else if $r.rc != 0 then
  print("health check failed rc=" .. $r.rc)
end
```

**Aggregate failures across a batch without aborting.**
```mix
$failed = []
for each $host in ["node1", "node2"]
  $r = ssh_run($host, "uptime")
  if not $r.ok then
    push($failed, $host)
  end
end
if not is_empty($failed) then
  die("hosts unreachable: " .. join($failed, ", "))
end
```

## Gotchas

- **`catch $e` gives a string, not an object** — no `.message`/`.code`. Even `die(42)` / `die($map)` stringify at the raise. Use string ops on `$e`.
- **`try` requires `catch` and/or `finally`** — bare `try … end` is invalid.
- **`run` raises, `run_rc` does not.** Mixing them up is the usual command-handling bug: a `run(...)` whose failure you forgot to wrap aborts the whole script.
- **`run_rc`'s timeout/interrupt sentinels are negative** — `rc: -1` (timed out) and `rc: -2` (interrupted) can never collide with a real child exit; a signal-killed child is a real exit, `128+sig`.
- **Bus `send`/`emit` failures never raise.** A failed `send` sets a **negative `$rc`** (`-1` transport, `-2` timeout, `-3` no broker) and the statement returns nil; a peer error is `$rc >= 10`; `emit` is silently fire-and-forget. Delivery status is data, not an exception — see [Bus messaging](bus.md).
- **Syntax errors can't be caught** — they fail at parse time. Only `die` and runtime errors reach `catch`.
- **`exit` and `panic` are not catchable.** `exit` unwinds `finally` and then ends with your code; `panic` aborts past `finally` with the Rust panic status 101 (only meaningful behind the `--serve` handler boundary).
- **Newline or `;` separates statements** — comments still own the rest of their physical line, so a `;` inside `--`/`#` does not resume execution.
- **`return`/`break`/`continue` propagate through `try`** uncaught — they are control flow, not errors.

## See also

- [running commands](system.md) — `run` / `run_rc` / `run_stream`, the structured-return model
- [remote execution](remote.md) — `ssh_run` / `ssh_must` / `ssh_mix`, the same raise-vs-report split over SSH
- [functions](functions.md) — `return`, recursion, function-local binders (incl. `catch $e`)
- [strings](strings.md) — operating on the caught `$e` message
- [Bus messaging](bus.md) — the `$rc` band contract: send failures are data, never exceptions
- [serve mode](serve.md) — the `--serve` per-handler boundary that isolates a `panic`
- [overview](overview.md) — Mix vs shell, the `mix -c` classifier, statement separation
- [builtins index](builtins.md) — every builtin by category
- `mix what die` · `mix what exit` · `mix what panic` · `mix what run` · `mix what run_rc` — one-line live help
- [Mix on GitHub](https://github.com/markc/mixos)

---

<!-- page: https://mixos.dev/mix/expr-eval/ (source: https://mixos.dev/mix/expr-eval.md) -->

# Expression evaluation mode

Sometimes a host doesn't want to *run a Mix program* — it wants to
*evaluate one Mix expression*: a scene host resolving a binding like
`$model.a * 2`, a config layer computing a default, a template filling a
field from preset values. For that, `mixos-lib-mix` exposes
`eval_expr_string` — a synchronous entry point that evaluates **exactly
one expression** under an optional capability policy and the standard
eval limits, rejecting everything that isn't a pure expression shape
**before execution**. It landed in lib-mix 0.89.0 together with the
`send`/`emit` capability-gate fix.

`expr_mode_check(source) -> MixResult<()>` (lib-mix 0.89.1) performs the same
single-expression, static deny and depth checks without evaluation. Hosts
can reject invalid bindings at compile time without constructing an evaluator
or running builtins. Runtime errors such as division by zero remain evaluation
errors; this check does not predict values or enforce a host capability policy.

```rust
use mixos_lib_mix::{
    eval_expr_string, CategoryAllowList, EvalLimits, IndexMap, Value,
};

let mut model = IndexMap::new();
model.insert("a".to_string(), Value::Number(21.0));

let v = eval_expr_string(
    "$model.a * 2",
    &[("model", Value::map(model))],
    Some(Rc::new(CategoryAllowList::deny_all())),
    EvalLimits::default(),
)?;   // Value::Number(42.0)
```

The evaluator is built fresh per call: `policy` installs via
`set_capability_policy`, `limits` via `set_limits`, and each
`(name, value)` in `globals` via `set_global` — the same seam handler
dispatch uses for `$event`. Nothing about the caller's own evaluator (if
any) is touched.

## The single-expression rule

`source` must parse to **exactly one expression statement**. Anything
else is rejected with an error naming the offending construct:

```text
eval_expr_string: not an expression: assignment
eval_expr_string: not an expression: for loop
eval_expr_string: not an expression: emit statement
eval_expr_string: expected exactly one expression statement, found 2 statements
```

That rule alone rules out assignment, control flow, `print`, `send`,
`emit`, `sh`, `on`, `source`, and multiple statements. A `try`/`catch`
around the call is the caller's job — the errors are ordinary
`MixError`s.

## The static deny walk

Past the single-expression rule, a static walk over the expression tree
rejects the constructs that carry authority or first-class functions —
**before execution, untaken branches included** (deterministic compile
semantics: a denied construct inside a ternary's false arm still
rejects, because the walk never evaluates anything):

| Construct | Rejected as |
|---|---|
| `send …` expression / statement | `send expression` / `send statement` |
| `sh "…"` (expression or nested statement) | `sh expression` / `sh statement` |
| `$(…)` command substitution | `command substitution $()` |
| `function (…) …` lambda literal | `function literal` |
| `$f(x)` — call on a function-valued expression | `function-value call` |
| `$x.name(…)` where `name` is not a builtin | `method call` |
| `on` / `source` / `include` / `… | cmd` nested in an if-expression | named per construct |
| `for` / `for … in` / `while` / `loop` nested in an if-expression branch | `for loop` / `for-each loop` / `while loop` / `loop statement` |
| `select … end` / `address "…" … end` nested in an if-expression branch | `select statement` / `address block` |
| `export` (mutates the HOST process environment; its runtime gate is permissive with no policy installed) | `export statement` |
| `print` statement nested in an if-expression (writes to the evaluator's output sink — the host daemon's real stdout/stderr) | `print statement` |
| a coalesce default in an interpolation (`"${x ?? …}"` and heredoc bodies): the payload is parsed and executed as a full program AT RUNTIME, so the walk statically analyses it here — it must be a single expression and passes the same deny rules recursively (nested coalesces included) | `coalesce default must be a single expression…`, or the inner construct's name |
| `sleep`, `readline`, `read_stdin`, `read_stdin_bytes`, `printf`, `eprintf`, `write_stdout`, `write_stderr`, `print_raw`, `eprint_raw` — by NAME: each is Pure- or Env-classed so no installed policy stops the Pure ones, and a binding has no business blocking on time/input or writing to the host's output stream; the static deny makes those premises unconditional, whatever policy the host chose | `<name> builtin` |
| string interpolation beyond literals and Mix variables | `environment-variable interpolation in string`, `command substitution in string` |

What stays **allowed**: literals, variables, arithmetic and comparison,
`..` concat, ternary `?:`, `if … then … else … end` as an expression,
field access, indexing, list/map literals, and bareword builtin calls
(`upper(…)`, `length(…)`). Method syntax on a builtin (`$s.upper()`)
desugars to a bareword `FunctionCall` at parse time, so it is allowed —
in a **nested** position (`'X-' .. $s.upper()`). One parser quirk to
know: as the *whole* statement, `$s.upper()` is the variable-led
first-accessor form, which folds to a field access and parses the `(`
as a first-class call on the map member — a `ValueCall`, denied like
every first-class call.

Interpolation details: `"${NAME}"` is a Mix **variable** part (scope
first, process env fallback) and stays allowed; a **leading `~`** in a
double-quoted string (`"~/x"`) is an env-var part and is denied;
`$(…)` inside a *heredoc* body is a command-sub part and is denied.

The walk is depth-capped at `MAX_EXPR_DEPTH` (**256**): a deeper tree is
a clean error, never a stack overflow in the walk. (The parser's own
nesting cap bounds *parse recursion*; a left-associative operator chain
parses iteratively but still builds a deep tree, so the walk carries
its own cap.)

```text
eval_expr_string: expression nesting exceeds MAX_EXPR_DEPTH (256)
```

Ordinary builtins are **not** statically denied — they run, gated by
the installed `policy` at dispatch exactly as in a full program. With
`CategoryAllowList::deny_all()` (the documented name for
`CategoryAllowList::new(&[])` — Pure only, nothing else) every non-pure
builtin fails with `capability denied`, and — since the 0.89.0 gate —
so do the bare `send`/`emit` broker forms and all shell syntax, by
class.

## Limits: the fuel story

`EvalLimits` applies in full: `max_list_len` / `max_map_len` /
`max_string_len` are enforced as values are built (an over-cap `..`
concat is a clean `string length N exceeds limit M` error), and
`recursion_limit` bounds what recursion can even be expressed (none, in
one expression without lambdas). **Loops cannot be expressed at all**:
the loop statements are denied everywhere the walk reaches, including
inside if-expression branch bodies — the one place a `for`/`while` could
otherwise hide — and neither can the constructs that *wait*: `sleep`,
`readline` and the stdin readers are denied by name (sleep is `Pure`, so
no installed policy stops it; the readers are `Env`, stoppable by a
policy but not by `policy: None` — the static deny covers both),
`select`/`address`/`send`/`emit`/`sh`/`export` are denied by construct,
and a fresh expression evaluator has no Bus/Db/Jmap handler to pend on
(those seam builtins raise "not available"). Evaluation cost is bounded
by the size caps, never by iteration count or by *unbounded* waiting
(`flock`'s argument-bounded wait remains reachable only when the host
installs a permissive policy — its class is `FsWrite`, denied under
`deny_all()`).

The **time limit** is armed at this entry point itself and checked while
entering expressions and after evaluation completes. A timer also cancels
pending evaluation. An expression that finishes without yielding after its
deadline is refused with a `time limit exceeded` error; a ready future does
not bypass the budget. A single CPU-bound builtin cannot be interrupted
mid-call, but its late result is rejected and further expressions stop. See
[capabilities & embedding](capabilities.md) for the same caveat in full
programs.

`eval_expr_string` is **synchronous**: it drives the evaluator's async
path on a fresh current-thread runtime inside the call. Calling it from
within an async execution context **panics** (tokio refuses to block a
runtime thread) — hop to a blocking task first. A fresh runtime per
call is fine at config/scene-load rates; a host re-evaluating bindings
per frame should measure it.

## The honest boundary

The same wording as the `CapabilityPolicy` trait, because it is the
same gate: an in-process gate is a **robustness** boundary for trusted
embedded expressions, **not a containment** boundary for untrusted
code — a compromise owns the address space the gate runs in. The
single-expression rule and the deny walk are deterministic *fuel and
footgun* bounds (no runaway construction, no blocking on time or input,
no output to the host's streams, no env or shell reach — the deny table
above is the whole story), not a sandbox. What remains within a
conforming expression is pure computation over its inputs and the size
caps. Untrusted or multi-tenant code runs out-of-process under OS
isolation; see [capabilities & embedding](capabilities.md) for the
trust-split model.

## See also

- [capabilities & embedding](capabilities.md) — the classes, `CategoryAllowList`,
  the limits knobs, the trusted/untrusted split
- [Bus messaging](bus.md) — `send`/`emit` semantics and the `$rc` bands
- [shell dispatch](shell-mode.md) — `sh`, `$(…)`, pipes (all `Process`-gated)
- Source of truth: `eval_expr_string` / `MAX_EXPR_DEPTH` in
  [`evaluator.rs`](https://github.com/markc/mixos/blob/main/libs/mix/src/evaluator.rs),
  `CategoryAllowList::deny_all` in
  [`builtins.rs`](https://github.com/markc/mixos/blob/main/libs/mix/src/builtins.rs)

---

<!-- page: https://mixos.dev/mix/functions/ (source: https://mixos.dev/mix/functions.md) -->

# Functions, lambdas & modules

Mix functions come in two shapes that look almost identical but mean different things:

- **`function name(...)`** — a *statement* that registers a named function in the current scope.
- **`function(...)` / `fn(...)`** — an *expression* that evaluates to a first-class function **value** (a lambda) you can store, pass, return, or stash in a map.

Both share one tail grammar (`($params) ... end` or `($params) = expr`), one binding model (args by value, writes function-local), and one capture rule (closures see their defining scope for *reads*). Get those four facts straight and everything else follows.

> The binary is the oracle — if anything here disagrees with live behaviour, the binary wins. Page stamps are held fresh by `cargo test -p system --test man_pages` (ask `mix --version` for the current number).

## Named functions — the statement form

```mix
function add($a, $b)
  return $a + $b
end
print(add(2, 3))
```
```text
5
```

A named `function` is a **statement**: evaluating it registers `add` in scope and returns nil. The body contains newline- or `;`-separated statements closed by `end` (there is no `do`; see [control flow](control-flow.md)). Use `return` to hand a value back; a block body that never returns yields nil (more on that below).

### `fn` alias and the `= expr` short form

`fn` is a Rust-style short alias for `function` — it works everywhere `function` does, and both spellings accept both body forms (block `... end` or `= expr`, named or anonymous — all eight combinations parse). The `= expr` form is a **single-expression body**: no `return`, no `end`, the expression's value *is* the result.

```mix
fn square($x) = $x * $x
print(square(7))
```
```text
49
```

This is the form to reach for in [HOFs](#higher-order-functions): `map($xs, fn($x) = $x*2)`.

The body is one *expression* — which includes the value-producing conditionals (ternary `?:`, `if ... end` expressions, `??` — see [operators](operators.md) and [control flow](control-flow.md)), so a conditional one-liner needs no block:

```mix
$sgn = fn($x) = $x > 0 ? "pos" : "neg"
print($sgn(3))
print($sgn(-3))
```
```text
pos
neg
```

> **`fn` needs quoting as a map key.** A keyword is accepted anywhere it is unambiguously a NAME — bare map keys (`{label: 1, to: "x"}`), field access and assignment (`$m.to`, `$cfg.label = 2`). The ONE exception is `fn`: it lexes to the same token as `function`, so `{fn: 1}` and `$m.fn` are parse errors — use a quoted key (`{"fn": 1}`) and index access (`$m["fn"]`).

### Top-level functions hoist (0.63.0)

Every `function`/`fn` declared at the **direct top level of a script** is
bound before the first statement runs, so a forward call works — a script
can put its entry point first and its helpers last:

```mix
print(f())
function f()
  return 1
end
```
```text
1
```

The hoist is **top level only**. A function nested inside a block (an `if`
branch, a loop body) still binds when — and only when — its branch
executes; hoisting those would make a conditional definition
unconditional. Function *bodies* are not pre-scanned either: a nested
definition inside a body binds when its statement runs, as before. Safe by
construction: a Mix `fn` [captures nothing](#the-binding-model--by-value-local-writes)
from the enclosing scope, so an early binding cannot close over a
not-yet-defined value.

The hoist applies to every **invocation root**: a script run directly, a
[`require`](#grouping-functions-across-files--require-vs-include-vs-source)d
module's top level (the same file forward-calls identically either way), a
`source`d file, and a serve-mode `on` handler body — in a handler the
binding happens on entry, so a top-level `fn` below an early `return` is
still defined.

Redefinition: with two same-named top-level definitions, a call **before
both** sees the *last* one (the hoist binds them in order); code *between*
them still sees the earlier one, exactly as before 0.63.0 — the definition
statement re-binds when reached. This includes **prelude names**: a script
that defines its own `fn lines(…)` shadows the prelude's `lines` from the
first statement, even at call sites above the definition.

*Mutual* recursion no longer needs both definitions to precede the first
call — calls resolve at call-time, and hoisting has already bound every
top-level name:

```mix
function is_even($n)
  if $n == 0 then return true end
  return is_odd($n - 1)
end
function is_odd($n)
  if $n == 0 then return false end
  return is_even($n - 1)
end
print(is_even(10))
print(is_odd(7))
```
```text
true
true
```

### Recursion is capped at 128 frames

Recursion works, but the evaluator caps nesting at **128** calls deep (127 nested recursive calls pass, 128 fail). Exceeding it is a clean, catchable runtime error — not a stack-overflow abort:

```mix
function f($n)
  if $n == 0 then return 0 end
  return f($n - 1)
end
print(f(100000))
```
```text
Runtime error at line 3: recursion depth exceeded (limit 128)
```

For deep counts, use a loop or a [HOF](hof.md) instead of recursion.

### Default parameters

A parameter can carry a default expression, used when the caller omits that argument:

```mix
function greet($name = "world")
  return "hello " .. $name
end
print(greet())
print(greet("mix"))
```
```text
hello world
hello mix
```

A missing argument with no default binds nil. Extra arguments are silently ignored for *user-defined* functions (`f(1, 2, 3)` against `function f($a)` just binds `$a = 1`); metadata builtins warn on a surplus since 0.102.8 (below), and the always-strict families (`task_start`, the `fs_watch`/`fs_unwatch`/`fs_wait` set, the `net_watch`/`audio_watch`/`*_state` set) raise on any mismatch in every mode.

Since 0.29.0 that tolerance is a **mode**: strict arity raises a catchable `ARITY_MISMATCH` structured error — before the function body runs — whenever a call's argument count falls outside `min..=max` (min = parameters without defaults). Strict mode also enforces every builtin's contract arity from the machine metadata, so `run_stream(["true"], {}, 5)`'s silently-ignored surplus argument becomes an error. (That example read `run_stream(argv, {timeout: 5})` until 0.51.0, when run_stream gained an options map and began refusing `timeout` **by name** as `OPTION_INVALID` — in every mode, not just this one.) **Strict became the default for script/`-c`/serve modes in 0.103.0** (A1 step 3); `--compat-arity` restores the compatible binding, and the REPL keeps it unless `~/.mixrc` sets `$strict_arity = true`. `mix lint` flags statically provable mismatches in either mode.

Since 0.102.8, the compatible mode stops being *silent* about the builtin
surplus: a metadata-builtin call with an extra argument prints one stderr
warning per (builtin, count) per process — `mix: warning: pop() called with
2 argument(s), contract is pop(list) -> any — the surplus is ignored under
--compat-arity and is an error in strict mode (the default since 0.103.0)`.
A missing argument binds nil as ever, and the always-strict families (above)
keep raising in every mode. Operator-facing equivalents of the flag are
`MIX_STRICT_ARITY=1`, `$strict_arity = true` in `~/.mixrc`, and
`ssh_mix(host, src, {strict_arity: true})` — with the flip these are
explicit opt-ins over an already-strict default; the remote escape hatch is
`ssh_mix(host, src, {strict_arity: false})` (0.102.7 — see
[invocation](invocation.md)).

> **A keyword can't be a function name.** `function step(...)` and `fn to(...)` are parse errors (`expected identifier, got Step`) — and that includes non-obvious [reserved words](keywords.md) like `step`, `to`, `label`. Pick `phase`, `say_step`, etc. `$`-sigil *variable* and *parameter* names are unaffected — the sigil disambiguates, so `$step = 1` and `function f($to)` both work.

> **You can't shadow a builtin.** `function abs($x) return 999 end` parses fine, but calls still resolve to the builtin: `abs(-5)` is `5`, never `999`. A builtin always wins over a same-named Mix function — pick another name.

## Lambdas — the expression form (first-class values)

Drop the name and `function(...)` becomes an **expression** that evaluates to a function value. Store it, call it, pass it around:

```mix
$sq = function($x) return $x * $x end
print($sq(9))
```
```text
81
```

The terse form (`fn($x) = expr`) is a lambda too — anonymous, single-expression, no `end`:

```mix
$dbl = fn($x) = $x * 2
print($dbl(21))
```
```text
42
```

A lambda is an ordinary `Value`: put it in a list or map, return it from another function, hand it to a [builtin](builtins.md). That is the whole point — see [modules](#modules--a-map-of-lambdas) and [HOFs](#higher-order-functions). Stringified, a function value shows its parameter count: `"" .. $dbl` is `<function/1>`, a two-param lambda is `<function/2>`.

### Block bodies do not implicitly return

A `function ... end` **block** body does *not* return its last expression. If you want a value out of a block body, you must `return` it:

```mix
$f = function($x) $x * $x end
print("result: " .. ("" .. $f(5)))
```
```text
result: nil
```

The `= expr` short form is the opposite — it returns the expression directly. So `fn($x) = $x*$x` gives `25`, but `function($x) $x*$x end` gives `nil`. Reach for `= expr` whenever the body is one expression.

## The binding model — by value, local writes

Three rules govern how data flows in and out of a function. They are the most common source of surprise for anyone arriving from bash/python, so verify them against your own code.

### Arguments pass by value

Numbers, lists, and maps are **copied in**. Mutating a parameter — even `push()` on a list param — does not reach the caller:

```mix
function addit($p)
  push($p, 99)
  return length($p)
end
$l = [1, 2, 3]
print("inside len: " .. ("" .. addit($l)))
print("caller len: " .. ("" .. length($l)))
```
```text
inside len: 4
caller len: 3
```

Because this silently discards work, Mix **warns** (to stderr, once, when the
function is defined) about the provably-lost case — a `push($p, …)` statement
whose result is thrown away where `$p` is a parameter the body never reads again:

```text
mix: warning: in fat_snare() at line 2: push($drums, …) discards its result but
$drums is a by-value parameter never read again — the mutation is lost to the
caller (Mix lists pass by value). Return the list or use concat().
```

The warning is deliberately conservative (zero false positives): it stays silent
the moment `$p` is genuinely used — `return $p`, `length($p)`, `$p[i]`, capturing
`$y = push($p, …)`, `pop($p)`, or passing `$p` on — so `addit` above (which reads
`$p` via `length`) does **not** warn. It only fires when a push into a parameter
can have no observable effect at all.

> **Building a sequence across helpers** (e.g. accumulating MIDI events for a
> `.asc` score) is where this bites hardest — a helper that `push`es onto a
> list parameter silently drops every event onto the copy. Under by-value
> semantics, have the helper **return** its items and combine them at the call
> site with [`concat`](collections.md#concat) (`concat($a, $b, …)`
> joins lists into one new list, one level deep, O(total)):

```mix
function bar_events($b)
  return [$b * 10, $b * 10 + 1]   -- RETURN a list, never push a param
end
$track = []
for each $b in [0, 1, 2]
  $track = concat($track, bar_events($b))   -- combine at the caller
end
print("" .. $track)
```
```text
[0, 1, 10, 11, 20, 21]
```

### Writes inside a function are function-local

Any `$x = ...` *assignment* inside a function binds a **function-local** variable. It does not write through to an outer/global of the same name — and that includes `$rc`/`$result`: when those change after a `send`, it is the Bus runtime writing them natively, not a Mix assignment (see [Bus messaging](bus.md)); a literal `$rc = ...` inside a function is as local as any other write.

```mix
$g = 1
function w()
  $g = 99
end
w()
print($g)
```
```text
1
```

This includes the accumulator trap: a helper doing `$count = $count + 1` leaves the caller's `$count` untouched. A function cannot tick a shared global counter.

### Reads fall through (globals fallback)

A function may *read* an outer/global variable fine — lookups fall through to the global frame:

```mix
$g = 42
function r()
  return $g + 1
end
print(r())
```
```text
43
```

### The pass-in / return / reassign triad

Because writes are local and args are by value, the way to thread state *through* a function is the triad: **(1) pass the value in** (explicit read) → **(2) `return`** the new value (compute) → **(3) reassign at the call site** (write). There is no `global` keyword — this is the idiom by design.

```mix
function inc($n)
  return $n + 1
end
$count = 0
$count = inc($count)
$count = inc($count)
print($count)
```
```text
2
```

Return a **map** to update several values at once, then destructure at the call site. Net result: pure, self-contained functions — a helper can't accidentally read or stomp a caller's same-named variable.

## Closures — capture for reads

A lambda **captures its defining scope** for reads, so it carries state. Define a lambda where `$base` is in scope and it stays bound to `$base` even after the lambda escapes:

```mix
$base = 100
$add = function($x) return $x + $base end
print($add(5))
```
```text
105
```

This is what makes a **closure factory** work — each call to `adder` produces a lambda closed over that call's own `$n`:

```mix
function adder($n)
  return function($x) return $x + $n end
end
$add10 = adder(10)
$add100 = adder(100)
print($add10(5))
print($add100(5))
```
```text
15
105
```

A closure captures **only the variables its body actually references**, not the whole enclosing frame. So defining a key/predicate lambda inline inside a function that also holds a large value — a multi-thousand-element list, a whole generated score — costs nothing per call for the data it doesn't touch. That is what keeps `sort_by`/`map`/`filter` over big data `O(n log n)`/`O(n)` even when the lambda is written inside a heavy scope: `sort_by($track, fn($e) = $e["t"])` closes over `$e` alone, never the surrounding tracks.

### A closure can read captured state but not accumulate into it

The same local-write rule applies: a **write** to a captured/outer name binds a *local* and does **not** mutate the captured variable:

```mix
$c = 0
$bump = function() $c = $c + 1 end
$bump()
$bump()
print($c)
```
```text
0
```

So a closure can *read* shared state but can't *accumulate* into it. To carry a counter forward, thread it through the triad (`$n = $inc($n)`):

```mix
$inc = fn($x) = $x + 1
$n = 0
$n = $inc($n)
$n = $inc($n)
$n = $inc($n)
print($n)
```
```text
3
```

### Binders shadow, they don't clobber

Names a function *introduces* — a `for each $x` / `for $i = ...` loop var, a `catch $e`, a `parse ... with $a $b` target — bind in the function's own frame, so they **shadow** a same-named caller/global rather than overwriting it:

```mix
$x = "caller"
function loops()
  for each $x in [1, 2, 3]
    $unused = $x
  end
  return "done"
end
print(loops())
print($x)
```
```text
done
caller
```

## Higher-order functions

The payoff of first-class lambdas is the HOF builtins — no hand-rolled `for each ... push ... end` loops. Pass a lambda (inline or stored) as the transform:

```mix
$out = map([1, 2, 3], function($x) return $x * $x end)
print("" .. $out)
```
```text
[1, 4, 9]
```

```mix
$out = filter([1, 2, 3, 4, 5], fn($n) = $n > 2)
print("" .. $out)
```
```text
[3, 4, 5]
```

`reduce` takes the list, an **explicit init**, then `fn(acc, item)` — mind that order:

```mix
$sum = reduce([1, 2, 3, 4], 0, function($a, $b) return $a + $b end)
print($sum)
```
```text
10
```

The full HOF set (`mix what <name>` for each): `map` `filter` `reduce` `sort_by` `any` `all` `count` `min_by` `max_by` `sum_by` `group_by` `unique_by`. Each one is covered on the dedicated [hof](hof.md) page.

### Two HOF gotchas

**(1) You can't pass a named function by bare name.** A bareword is parsed as a string, not a function value:

```mix
function triple($x) return $x * 3 end
$out = map([1, 2, 3], triple)
print("" .. $out)
```
```text
Runtime error at line 2: map: expected function, got string
```

Wrap it in a lambda — `$f = function($x) return triple($x) end` — or define it as a lambda var in the first place.

**(2) A multi-statement lambda won't parse *inline* inside a HOF call.** The open call-paren breaks statement separation:

```mix
$out = map([1, 2, 3], function($x)
  $y = $x * 2
  return $y + 1
end)
print("" .. $out)
```
```text
Parse error at line 3:3: expected end of statement, got Return
```

Bind the lambda to a var first, then pass the var:

```mix
$f = function($x)
  $y = $x * 2
  return $y + 1
end
$out = map([1, 2, 3], $f)
print("" .. $out)
```
```text
[3, 5, 7]
```

A *single-expression* lambda (`function($x) return $x*$x end` or `fn($x) = ...`) is fine inline — only multi-statement bodies need the var-bind. A stored-var lambda also reads cleanly with `sort_by` and friends:

```mix
$ports = [{ port: 80 }, { port: 22 }, { port: 443 }]
$by_port = function($r) return $r["port"] end
$sorted = sort_by($ports, $by_port)
print("" .. $sorted)
```
```text
[{port: 22}, {port: 80}, {port: 443}]
```

## Modules — a map of lambdas

Mix has no module keyword, but a map of lambdas *is* a namespace. Functions are values, so you can group them:

```mix
$math = { square: function($x) return $x * $x end, cube: function($x) return $x * $x * $x end }
print($math["square"](5))
print($math["cube"](3))
```
```text
25
27
```

**Dot-call works — member-first for function members** (0.72.0; 0.27.0–0.71 dispatched name-first). `$math.square(5)` calls the map's own `square` whenever the member exists **and holds a function** — even when a free/prelude function of the same name also exists (before 0.72.0 the free name won, which made a module export named `sum` or `lines` silently unreachable via dot-call). When the map has no function-valued member of that name, the call is ordinary UFCS sugar (`$list.map($f)`, `$s.upper()` — unchanged). One residual collision to know: a member named after a **builtin** is still unreachable via dot (the desugar happens at parse time). A member also beats an **extension** (`context`, `ai`) in every mode, `--serve` included, since 0.117.0. `$math["square"](5)` calls the member unconditionally — the index form remains the collision-proof spelling:

```mix
$math = { square: function($x) return $x * $x end }
print($math.square(5))     -- 25 (member — no free 'square' exists)
print($math["square"](5))  -- 25 (index form: collision-proof)
```

Each lambda still closes over the defining scope for reads, so a module can share read-only state across its members:

```mix
$prefix = ">> "
$log = { line: function($s) return $prefix .. $s end }
print($log["line"]("hello"))
```
```text
>> hello
```

See [data structures](collections.md) for indexing details.

## Grouping functions across files — `require` vs `include` vs `source`

For libraries, split functions into their own `.mix` file and pull them in. Mix has three file-loaders with different semantics (full comparison + module semantics: [modules](modules.md)):

- **`$m = require("lib.mix")`** (0.27.0+) — evaluates the file in an **isolated scope** and returns its exports as a map (`$m.fn(...)`, `$m.var`). Cached once per file, cycle-safe, cannot clobber (or see) your scope. Use this for anything library-shaped.
- **`include "lib.mix"`** — **script-relative path**, **load-once** (re-`include` is a no-op), splices the file's fns + `$vars` INTO your scope. Use when you want the names unprefixed and own both files.
- **`source "lib.mix"`** — **CWD-relative path**, runs **every time**. Use this for re-running setup.

Given `util.mix`:

```mix
function lib_double($x)
  return $x * 2
end
print("[lib loaded]")
```

`include` runs the lib body **once** even if included twice:

```mix
include "util.mix"
include "util.mix"
print(lib_double(21))
```
```text
[lib loaded]
42
```

`source` re-runs it each time:

```mix
source "util.mix"
source "util.mix"
print(lib_double(21))
```
```text
[lib loaded]
[lib loaded]
42
```

### `include` drops names into a flat namespace

`include` injects the lib's functions straight into the caller's scope — the namespace is **flat**. A name collision across two libs **silently last-loaded-wins** (no warning). Prefix your function names, or use the module idiom to scope them.

Note `include` is **not expression-valued** — you can't capture its result:

```mix
$m = include "lib.mix"
```
```text
Parse error at line 1:6: unexpected token Include
```

So a "module library" assigns a well-known var name and the caller uses *that* after the `include`. Given `mathlib.mix`:

```mix
$mathlib = {
  add: function($a, $b) return $a + $b end,
  mul: function($a, $b) return $a * $b end
}
```

The caller:

```mix
include "mathlib.mix"
print($mathlib["add"](3, 4))
print($mathlib["mul"](3, 4))
```
```text
7
12
```

## Quick reference

| Form | Kind | Body | Returns |
|---|---|---|---|
| `function f($a) ... end` | statement (registers `f`) | block | nil unless `return` |
| `fn f($a) = expr` | statement (registers `f`) | one expression | the expression |
| `function($a) ... end` | expression (a value) | block | nil unless `return` |
| `fn($a) = expr` | expression (a value) | one expression | the expression |

`fn` ≡ `function` in every row — either keyword takes either body form, named or anonymous.

- **Sigil everywhere:** `$x`, params `$a`/`$b`. Bare `x = 1` is misparsed as a shell command.
- **Concat is `..`** (never `+`/`.`): `"hi " .. $name`.
- **Top-level `fn`s hoist** (0.63.0) — forward calls work at the script's top level; a `fn` nested in a block still binds when its branch runs. Recursion caps at **128** frames (clean runtime error).
- **A keyword can't be a function name** (`function step(...)` errors; `$step = 1` is fine) and **a builtin can't be shadowed** (calls always resolve to the builtin).
- **Args by value; writes function-local; closures capture for reads only.** Propagate state with the pass-in/return/reassign triad — there is no `global`.
- **Modules = map of lambdas, index-called** (`$mod["fn"](args)`), not dot-called.
- **`include`** = script-relative, load-once (libs); **`source`** = CWD, every-time.
- Multi-statement lambdas must be **var-bound** before going into a HOF; named functions **can't** be passed by bare name.

## See also

- [hof](hof.md) — the twelve HOF builtins in depth (`map`/`filter`/`reduce`/`sort_by`/…)
- [strings](strings.md) — `..` concat, interpolation, the `'raw'` vs `"${...}"` split
- [control flow](control-flow.md) — `if`/`for`/`while`, `end`, why there is no `do`
- [operators](operators.md) — ternary `?:` and `??`, the expressions a `= expr` body can hold
- [maps](collections.md) / [lists](collections.md) — indexing, the data behind the module idiom
- [keywords](keywords.md) — the reserved words that can't be function names
- [builtins index](builtins.md) — everything callable out of the box
- [Bus messaging](bus.md) — `send`/`on`/`emit` keywords (where `$rc`/`$result` come from)
- The [mix repo](https://github.com/markc/mixos) · [bus](https://github.com/markc/mixos) · [cos](https://github.com/markc/mixos)
- `mix help` — command overview · `mix what map` (and any builtin) — one-line signature + version

---

<!-- page: https://mixos.dev/mix/gotchas/ (source: https://mixos.dev/mix/gotchas.md) -->

# gotchas — what you will guess wrong on your first try

Mix has almost no presence in any model's training data, so a new session
extrapolates from bash, Python and JavaScript — and several of those guesses
are **silently wrong**: they run, produce a value, and mean something else.
This page is the list of them.

Read it before writing Mix. It is the one page that pays for itself in a
single session. `mix man syntax` is the mental model; this is the errata.

Every row below is executed by `cargo test -p system --test man_gotchas`,
which runs the **probe** column through `mix -c` and compares the **prints**
column. A wrong row fails the build, so the page cannot rot into confident
fiction.

## The table

A `prints` cell starting with `!` means the probe **fails**, and that text
must appear in the error.

| you will guess | Mix is | probe | prints |
|---|---|---|---|
| a bare name reads the variable | a bare word is a **string literal** — `$` is not optional, and omitting it is silent | `$x = 5; print(x)` | `x` |
| `null` (or `None`, `undefined`) is null | it is a bare word, so it is the **string** `"null"`; Mix's null is `nil` (`mix lint` warns, MIX-W2312, and `--fix` rewrites it) | `print(json_encode({a: null}))` | `{"a":"null"}` |
| `let i = 0` declares a variable | Mix has no `let`, `var` or `const`: write `$i = 0` (and `$i = $i + 1`, never a bare `i = …`) | `let i = 0` | `!$i =` |
| `"hi $name"` interpolates | only `${...}` interpolates; a bare `$name` in a string is **literal text** | `$n = "world"; print("hi $n")` | `hi $n` |
| — so use braces | `${name}` — and it is the **same rule everywhere** a string is built, heredocs included | `$n = "world"; print("hi ${n}")` | `hi world` |
| `elseif` | `elif` | `if 1 == 2 then print("a") elif 1 == 1 then print("b") end` | `b` |
| `str(x)` | `to_string(x)` | `print(to_string(5))` | `5` |
| `print(a, b)` | `print` is a **statement**, not a function, so `(a, b)` is read as an expression and fails | `print("a", "b")` | `!expected RParen` |
| — so how do I print two things | `print a, b` — no parens, joined by a space; `print(x)` only works because `(x)` is parenthesised | `print "a", "b"` | `a b` |
| `run()` returns a status | `run()` **raises** on a non-zero exit | `print(run("false"))` | `!failed (rc=1)` |
| — so how do I get the code | `run_rc()` returns `{rc, stdout, stderr, …}` | `print(run_rc("false").rc)` | `1` |
| `read_file()` returns nil when missing | it **raises**; test with `is_file()` first | `print(read_file("/no/such/file"))` | `!No such file or directory` |
| `push` mutates any list | `push` writes through the **slot**; on a nested list it is a silent **no-op** | `$m = {a: [1]}; push($m.a, 2); print($m)` | `{a: [1]}` |
| — so how | read it out, push, store it back | `$m = {a: [1]}; $i = $m.a; push($i, 2); $m["a"] = $i; print($m)` | `{a: [1, 2]}` |
| a declared `fn` name is a value | a **lambda** is a real value, but a declared `fn`'s bare name is the **string** `"f"` | `fn f($x) return $x end; $g = f; print($g)` | `f` |
| — so how do I pass one | assign a lambda: `$f = fn($x) = …`, which is a `function` and works in `map`/`filter` | `$f = fn($x) = $x + 1; print(map([1, 2], $f))` | `[2, 3]` |
| a `fn` can write an outer variable | assignment inside `fn` binds a **local**; return the value instead | `$n = 1; fn bump() $n = 99 end; bump(); print($n)` | `1` |
| `catch $e` gives an error object | `$e` is the **message string**; use `catch $msg, $err` for `$err.code` | `try raise("E_X", "boom") catch $m, $e print($e.code) end` | `E_X` |
| `raise("boom")` | `raise(CODE, MESSAGE)` — one argument is an arity error | `try raise("E_X", "boom") catch $m print($m) end` | `boom` |
| `json_decode()` | `json_parse()` (and `json_encode()` the other way) | `print(json_parse("{\"a\":1}").a)` | `1` |
| `==` compares two maps or lists | it **raises** rather than answer a useless `false` | `print([1, 2] == [1, 2])` | `!would always answer false` |
| — so how do I compare them | `deep_eq(a, b)` | `print(deep_eq([1, 2], [1, 2]))` | `true` |
| `re_replace(pattern, s, ...)` | **subject first**: `re_replace(s, pattern, replacement)` | `print(re_replace("a1b", "[0-9]", "#"))` | `a#b` |
| `sort_by` takes a direction | ascending only, with a lambda; `reverse()` for descending | `print(sort_by([3, 1, 2], fn($x) = $x))` | `[1, 2, 3]` |
| `'~/x'` expands | a **single**-quoted string is raw — no `~`, no `${...}` | `print('~/x')` | `~/x` |
| — and `"~/x"`? | a double-quoted one expands `~` to `$HOME` | `print(starts_with("~/x", "/"))` | `true` |
| `send svc-name verb` needs quoting | it does not — a tight-hyphenated bare target is read whole, like the quoted and `$var` forms | `send zz-no-such-svc ping timeout=1; print(type($result))` | `string` |
| — but `send a - b verb`? | a **space** makes it subtraction again, and a bareword is a string, so that is a type error | `send a - b ping timeout=1` | `!as number` |
| `replace()` tells you it missed | it returns the input unchanged, **silently** — check the result, or use `mix edit` from a prompt | `print(replace("abc", "zz", "!"))` | `abc` |
| `replace()` replaces the first | it replaces **all** of them | `print(replace("a a a", "a", "b"))` | `b b b` |
| `mix -c 'print(x)'` needs escaping gymnastics | it does not; a probe is one call and the binary is the oracle | `print(mix_version() != "")` | `true` |
| a provable `-c` arity/dead-mutation snippet runs | the D1 lint gate REFUSES it with exit 2 before any line runs — `--no-lint` overrides (0.103.4) | `mix -c '$m = {}; remove($m, "k")'` | `!refusing to run` |
| `is_reload_candidate()` is true while a `--serve` RELOAD is pending | it is true **only while the replacement's init body executes** — false in a plain script, at initial boot, and in every committed generation; the candidate must stay passive (no starts, no persisted writes) and commit-time work belongs in `on lifecycle.commit` | `print(is_reload_candidate())` | `false` |
| `on $svc .. ".call"` registers a verb under the `--serve` name | `on` takes a static name (that is a parse error); write `on @.call` — the unquoted `@` becomes the serve name when the handler registers, and outside `--serve` it raises `SERVE_PREFIX_OUTSIDE_SERVE` | `try on @.call end catch $m, $e print($e.code) end` | `SERVE_PREFIX_OUTSIDE_SERVE` |

## Three rules that are not a syntax trap

These cost more than any row above, and no probe can catch them.

1. **Never `sed -i`, never Python.** A one-line edit is `mix edit FILE OLD NEW`
   — exact match, refuses an absent or ambiguous needle (see
   [the mix command](cli.md)). A script is a `.mix` file. If Mix genuinely
   cannot do something, that is a **reportable gap in Mix**, not a licence to
   reach for another language.
2. **Never `ssh host 'bash -c "…"'`.** Use
   `ssh_mix(host, source, {bindings: {…}})` — it ships the source over ssh
   stdin into `mix -`, bypassing **all** shell quoting, and `bindings` passes
   values in as `$name` assignments instead of string-interpolating them.
   Quoting a remote loop by hand fails in ways that look remote and are local.
   See [remote execution](remote.md).
3. **Probe, do not extrapolate.** `mix -c '<code>'` answers in under a second
   and the binary outranks every document, including this one. `mix builtins
   NAME` gives the exact signature, `mix what NAME` the one-liner, `mix lint
   FILE` the call-contract check before you run anything non-trivial.

## See also

- [syntax & the classifier](syntax.md) — the mental model these are errata to.
- [the mix command](cli.md) — `mix edit`, `mix lint`, `mix what`, `mix man`.
- [errors & exit handling](errors.md) — the full `try`/`catch`/`raise` model.
- [collections](collections.md) — why `push` writes through a slot.

---

<!-- page: https://mixos.dev/mix/hof/ (source: https://mixos.dev/mix/hof.md) -->

# hof — higher-order functions

The `hof` builtin category — twelve functions that take a **function value** as an
argument and run it over a list: `map`, `filter`, `reduce`, `sort_by`, `any`, `all`,
`count`, `min_by`, `max_by`, `sum_by`, `group_by`, `unique_by`. They are the idiom for
transforming and querying lists in Mix — reach for one of these instead of a
hand-rolled `for each … push … end` loop whenever the body produces a value.

List them live with `mix builtins hof`; one-line help for any single name with
`mix what NAME`.

```text
$ mix builtins hof
hof builtins:
  sort_by         Return list sorted ascending by key function (stable) (v0.2.0)
  filter          Return new list of items where predicate returns truthy (v0.2.0)
  map             Return new list of transform(item) results (v0.2.0)
  reduce          Fold list left with an explicit init: reduce($xs, $init, function($a, $b) = ...) (v0.2.0)
  any             Short-circuit: true if any item matches predicate (v0.2.0)
  all             Short-circuit: true if every item matches predicate (v0.2.0)
  count           Count items where predicate returns truthy (v0.2.0)
  min_by          Return the ITEM (not the key) with minimum key-function value (v0.2.0)
  max_by          Return the ITEM with maximum key-function value (v0.2.0)
  sum_by          Sum of key(item) across all items, returns number (v0.2.0)
  group_by        Map of stringified-key → list of items (first-seen key order) (v0.2.0)
  unique_by       Dedup list by key function, first occurrence wins (v0.2.0)
```

## The lambda argument — how to pass a function

Every HOF takes a list and a [function value](functions.md). The function is *called
per element*; Mix runs it on each item and collects/folds the results. There are three
ways to supply that function, and the rules matter — getting them wrong is the most
common HOF mistake.

### 1. Terse inline lambda `fn($x) = expr` — the everyday form

A single-expression lambda needs no `return` and no `end`. This is what you reach for
99% of the time:

```mix
$xs = [1, 2, 3, 4]
print(map($xs, fn($x) = $x * $x))
```

```text
[1, 4, 9, 16]
```

`fn` is just a short alias for `function` (see [functions](functions.md)); `fn($x) = expr`
and `function($x) return expr end` are the same thing.

A **branch fits in a terse lambda** — the ternary `cond ? a : b` and the
`if … then … else … end` *expression* (see [control-flow](control-flow.md)) are both
value-producing, so no block body is needed for a simple conditional:

```mix
print(map([-1, 0, 5], fn($n) = $n > 0 ? "pos" : "nonpos"))
print(map([-1, 0, 5], fn($n) = if $n > 0 then "pos" else "nonpos" end))
```

```text
[nonpos, nonpos, pos]
[nonpos, nonpos, pos]
```

### 2. A named function CANNOT be passed by bare name

A bareword is parsed as a **string**, not a function reference — so `map($xs, triple)`
fails:

```mix
function triple($x) return $x * 3 end
print(map([1, 2, 3], triple))
```

```text
Runtime error at line 2: map: expected function, got string
```

Wrap it in a lambda (which *is* an expression that evaluates to a function value) —
inline is fine, since the wrapper is a single expression:

```mix
function triple($x) return $x * 3 end
print(map([1, 2, 3], fn($x) = triple($x)))
```

```text
[3, 6, 9]
```

### 3. A multi-statement lambda must be VAR-BOUND first

An open call-paren breaks statement separation, so a lambda with a body of more than one
statement does **not** parse inline inside `map(...)`:

```mix
print(map([1, 2], function($x)
  $y = $x * 2
  return $y
end))
```

```text
Parse error at line 3:3: expected end of statement, got Return
```

Bind it to a variable, then pass the variable:

```mix
$probe = function($x)
  $y = $x * $x
  return $y + 1
end
print(map([1, 2, 3], $probe))
```

```text
[2, 5, 10]
```

A simple branch does **not** need this — the ternary and the `if`-expression fit in a
terse `fn($x) = …` body (form 1 above). Var-binding is for bodies that genuinely need
several *statements*: sequencing intermediate assignments, a loop, `try/catch`, or a
`send` followed by reading `$rc`. A block body needs an explicit `return` — it does
not implicitly return its last value (a `function($x) $x * $x end` body returns `nil`;
see [functions](functions.md)).

### Lambdas are closures

A lambda captures the scope where it is defined, so it can read outer variables:

```mix
$factor = 10
print(map([1, 2, 3], fn($x) = $x * $factor))
```

```text
[10, 20, 30]
```

(A closure can *read* captured state but a `$x = …` write inside binds a function-local
and does not propagate out — thread state via `return`. See
[functions](functions.md) for the full by-value / return-to-escape rules.)

## map — transform every element

`map(list, fn)` returns a **new list** of `fn(item)` for each item, same length, same
order. It does not mutate the input.

```mix
print(map([1, 2, 3, 4], fn($x) = $x * $x))
print(map(["a", "b", "c"], fn($s) = $s .. "!"))
print(map([], fn($x) = $x))
```

```text
[1, 4, 9, 16]
[a!, b!, c!]
[]
```

Pull one field out of a list of maps:

```mix
$nodes = [{name: "alpha", up: true}, {name: "beta", up: false}]
print(map($nodes, fn($n) = $n["name"]))
```

```text
[alpha, beta]
```

## filter — keep the elements a predicate accepts

`filter(list, pred)` returns a new list of the items for which `pred(item)` is **truthy**
(non-nil, non-false, non-zero, non-empty). Order is preserved.

```mix
print(filter([1, 2, 3, 4, 5, 6], fn($x) = $x > 3))
```

```text
[4, 5, 6]
```

Filter maps, then map to a field — the standard "names of the down nodes" one-liner:

```mix
$nodes = [{name: "alpha", up: true}, {name: "beta", up: false}, {name: "gamma", up: true}]
$down = filter($nodes, fn($n) = not $n["up"])
print(map($down, fn($n) = $n["name"]))
```

```text
[beta]
```

## reduce — fold a list to a single value

`reduce(list, init, fn($acc, $item))` folds **left**: it starts the accumulator at the
explicit `init`, then for each item computes `$acc = fn($acc, $item)`. Note the argument
order — list, **then init**, then the combiner — and the combiner takes
`(accumulator, item)` in that order.

```mix
print(reduce([1, 2, 3, 4], 0, fn($a, $b) = $a + $b))
print(reduce([1, 2, 3, 4, 5], 1, fn($a, $b) = $a * $b))
print(reduce(["a", "b", "c"], "", fn($acc, $x) = $acc .. $x))
```

```text
10
120
abc
```

`init` is mandatory — there is no two-argument `reduce`:

```mix
print(reduce([1, 2, 3], fn($a, $b) = $a + $b))
```

```text
Runtime error at line 1: reduce: expects 3 args, got 2
```

Folding an **empty list** returns `init` unchanged (`reduce([], 42, …)` → `42`).

For a plain numeric total you usually want `sum_by` (below). Reach for `reduce` when the
accumulator type differs from the element type (building a string, a map, a running max).

## sort_by — stable sort by a key function

`sort_by(list, key_fn)` returns a new list sorted **ascending** by `key_fn(item)`. The
key is computed once per element (cached), and the sort is **stable** — items with equal
keys keep their original relative order.

```mix
print(sort_by([3, 1, 2], fn($x) = $x))
print(sort_by(["banana", "apple", "cherry"], fn($s) = $s))
print(sort_by(["ccc", "a", "bb"], fn($s) = length($s)))
```

```text
[1, 2, 3]
[apple, banana, cherry]
[a, bb, ccc]
```

Sorting a list of maps by a field is the workhorse use:

```mix
$rows = [{name: "b", port: 80}, {name: "a", port: 443}, {name: "c", port: 22}]
$sorted = sort_by($rows, fn($r) = $r["port"])
for each $r in $sorted
  print($r["name"] .. " " .. $r["port"])
end
```

```text
c 22
b 80
a 443
```

Key comparison: numbers compare numerically, strings lexicographically by codepoint,
bools `false` before `true`, `nil` sorts before everything; a genuinely mixed set of keys
falls back to string comparison so the sort stays total (it never panics). To sort
**descending**, negate a numeric key (`fn($r) = -$r["port"]`) or `reverse()` the result.

## any / all / count — predicate queries

`any(list, pred)` short-circuits to `true` on the first match; `all(list, pred)` short-circuits
to `false` on the first miss; `count(list, pred)` returns how many items match. All three
test for **truthiness**.

```mix
print(any([1, 2, 3], fn($x) = $x > 2))
print(all([2, 4, 6], fn($x) = $x > 1))
print(count([1, 2, 3, 4, 5], fn($x) = $x > 2))
```

```text
true
true
3
```

Empty-list conventions follow standard logic — `any([])` is `false` (no match exists),
`all([])` is `true` (vacuously, no counterexample):

```mix
print(any([], fn($x) = true))
print(all([], fn($x) = false))
```

```text
false
true
```

`count` with any truthy test — here, non-empty strings:

```mix
print(count(["", "x", "", "y"], fn($s) = not is_empty($s)))
```

```text
2
```

## min_by / max_by — the extreme ITEM

`min_by(list, key_fn)` and `max_by(list, key_fn)` return the **item** (not the key) whose
`key_fn` value is smallest / largest. This is the point of the `_by` suffix — you get the
whole record back, no second lookup needed.

```mix
$rows = [{n: "b", p: 80}, {n: "a", p: 443}, {n: "c", p: 22}]
$lo = min_by($rows, fn($r) = $r["p"])
$hi = max_by($rows, fn($r) = $r["p"])
print($lo["n"] .. " " .. $lo["p"])
print($hi["n"] .. " " .. $hi["p"])
```

```text
c 22
a 443
```

On a **tie**, the first item with the extreme key wins — both `min_by` and `max_by`
replace the running best only on a strictly smaller/larger key.

An empty list returns `nil`:

```mix
print(min_by([], fn($x) = $x))
```

```text
nil
```

## sum_by — numeric total of a key

`sum_by(list, key_fn)` adds up `key_fn(item)` across the list and returns a **number**.
It is the right tool for "total of a field" — clearer than a `reduce`.

```mix
$rows = [{p: 80}, {p: 443}, {p: 22}]
print(sum_by($rows, fn($r) = $r["p"]))
```

```text
545
```

The key function must return something numeric — a non-number key **raises**:

```mix
print(sum_by([{n: "x"}], fn($r) = $r["n"]))
```

```text
Runtime error at line 1: sum_by: key function returned non-number: string
```

"Numeric" follows Mix's usual coercion: a numeric **string** (`"5"`) and a bool
(`true` = 1) sum fine — `sum_by(["5", "6"], fn($x) = $x)` is `11`. Coercion is strict:
`"inf"` / `"nan"` / `"1e999"` are **not** numeric strings and raise. An empty list
sums to `0`.

## group_by — bucket by a key

`group_by(list, key_fn)` returns a **map** of `key → list of items`. The key is
**stringified** (it becomes a map key), and the buckets are in **first-seen key order**
(backed by an insertion-ordered map), so iterating the result is stable.

```mix
$people = [{name: "al", team: "red"}, {name: "bo", team: "blue"}, {name: "cy", team: "red"}]
print(group_by($people, fn($p) = $p["team"]))
```

```text
{red: [{name: al, team: red}, {name: cy, team: red}], blue: [{name: bo, team: blue}]}
```

Because the key is stringified, a numeric key works too:

```mix
print(group_by([1, 2, 3, 4, 5, 6], fn($x) = $x % 2))
```

```text
{1: [1, 3, 5], 0: [2, 4, 6]}
```

For a labelled even/odd grouping, branch with a ternary right in the terse lambda:

```mix
print(group_by([1, 2, 3, 4, 5, 6], fn($x) = ($x % 2) == 0 ? "even" : "odd"))
```

```text
{odd: [1, 3, 5], even: [2, 4, 6]}
```

An empty list groups to the empty map `{}`.

## unique_by — dedup, first occurrence wins

`unique_by(list, key_fn)` removes later items whose stringified `key_fn` value has already
been seen. The **first** occurrence of each key is kept, in original order.

```mix
print(unique_by([1, 2, 2, 3, 3, 3, 1], fn($x) = $x))
```

```text
[1, 2, 3]
```

Dedup a list of maps by a field (e.g. unique by email, keeping the first row seen —
row 3 duplicates row 1's email and is dropped):

```mix
$rows = [{id: 1, email: "a@example.com"}, {id: 2, email: "b@example.com"}, {id: 3, email: "a@example.com"}]
$uniq = unique_by($rows, fn($r) = $r["email"])
print(map($uniq, fn($r) = $r["id"]))
```

```text
[1, 2]
```

## Composing — chain them like a pipeline

HOFs return plain lists / numbers / maps, so they chain by binding each stage to a
variable. There is no pipe operator — the variable *is* the pipe.

```mix
$xs = [1, 2, 3, 4, 5, 6]
$doubled = map($xs, fn($x) = $x * 2)
$big = filter($doubled, fn($x) = $x > 5)
$total = reduce($big, 0, fn($a, $b) = $a + $b)
print($total)
```

```text
36
```

Nest a HOF inside a var-bound lambda to operate on a list of lists:

```mix
$grid = [[1, 2], [3, 4]]
$dbl_row = function($row)
  return map($row, fn($x) = $x * 2)
end
print(map($grid, $dbl_row))
```

```text
[[2, 4], [6, 8]]
```

## Notes & gotchas

- **`map`/`filter`/`sort_by`/`unique_by`/`group_by` return new collections;** they never mutate the input list. (`reduce`/`sum_by`/`count`/`any`/`all` return a scalar; `min_by`/`max_by` return an item.)
- **First argument must be a list** — passing a non-list raises (`map: expected list, got …`). To HOF over a **map**, go through `keys($m)` / `values($m)` (see [collections](collections.md)). The function argument must be a function value (`expected function, got string` is the bareword-name mistake above). Arity is strict too — a surplus argument raises (`map: expects 2 args, got 3`).
- **`reduce` takes three args** — list, **init**, combiner — and the combiner is `fn($acc, $item)` in that order. Easy to misremember as two-arg or `(item, acc)`.
- **`group_by` / `unique_by` keys are stringified.** Two keys that print the same collapse into one bucket — fine for strings/numbers/bools, but the number `1` and the string `"1"` are the SAME key: `group_by([1, "1"], fn($x) = $x)` is `{1: [1, 1]}`.
- **Truthiness** drives `filter`/`any`/`all`/`count`: a predicate returning `nil`, `false`, `0`, `""`, or `[]` counts as a miss; anything else is a hit.
- **An error inside the lambda aborts the HOF and propagates** — a `map` over a list where one element makes the body raise (say, a division by zero) produces no partial result. Catch it with `try/catch` (see [errors](errors.md)).
- Prefer a HOF over a `for each … push … end` loop for any value-producing body — it is the Mix idiom and avoids the [`push` returns nil / list-by-value](functions.md) loop footguns. Use a bare `for each` only for pure side-effects (`print`, `send`).
- These twelve live in a separate evaluator-aware registry (they call back into Mix code), but to a script they are ordinary builtins — same call syntax, same `mix what` help.

## See also

- [functions](functions.md) — `fn`/`function`, lambdas, closures, the by-value / return-to-escape rules HOF lambdas obey
- [control-flow](control-flow.md) — the ternary `?:` and `if`-expression that let a branch live in a terse lambda
- [collections](collections.md) — lists, maps, indexing, `push`/`length`/`join`, `keys`/`values`
- [math](math.md) — numeric builtins (`min`/`max`/`floor`/`round`) that pair with the `_by` family
- [strings](strings.md) — string ops for `map`/`filter` over text
- [errors](errors.md) — `try/catch` for an error raised inside a HOF lambda
- [builtins index](builtins.md) — every builtin by category

```text
mix builtins hof      list every HOF with its one-line description
mix what NAME         one-line description of a single builtin (e.g. mix what reduce)
mix help              the full categorized builtin reference
```

---

<!-- page: https://mixos.dev/mix/http/ (source: https://mixos.dev/mix/http.md) -->

# http — HTTP client builtins

## Streaming file download (0.97.0)

`http_get_file(url, path[, opts]) -> map<http_file_response>` streams GET to a
unique sibling created exclusively. For a new destination it uses mode 0666
under the process umask, matching `write_atomic`. When the destination exists,
staging starts at 0600, before any append prefix or incoming body is copied;
the target's permission bits are applied through the open descriptor only
after verification, just before publication. It hashes while writing,
syncs the completed file, publishes atomically, then syncs the directory.
The parent directory must exist. Defaults refuse an existing destination:
Linux uses `renameat2(RENAME_NOREPLACE)`, with atomic hard-link creation as
the fallback. Unsupported filesystems fail; there is no check-then-rename
fallback. `overwrite: true` permits atomic replacement of a regular file,
preserving its current permission bits. Symlink replacement is refused.

Options are `overwrite`, `append`, `expect_blake3` (64 lowercase hex digits),
`max_bytes`, `headers`, and the upload timeout/TLS options below. Redirects
are returned. Only a 200 or 204 installs a fresh file. HTTP error bodies may
be returned in `body`/`bytes` (64 MiB cap), but never become the destination.
Successful file bodies stay on disk; `body` is nil and `bytes` empty.
From 0.97.0, 200/206 downloads require identity framing with Content-Length.
Missing length or non-identity encoding returns status 0 with
`HTTP_IDENTITY_FRAMING` and leaves the destination untouched. This also rejects
ureq's transparent gzip decoding, which removes both Content-Encoding and
Content-Length. Chunked/close-delimited 200/206 bodies are deliberately refused;
blobd's lane supplies Content-Length. A body-free 204 remains supported.

`append: true` requires `expect_blake3` for the **whole final file** and an
existing regular prefix file. It copies and hashes the prefix into staging,
requests `Range: bytes=<prefix-size>-`, and accepts only a 206 with one
Content-Range starting at that size and ending at the representation's final
byte. An ignored Range, wrong range, short read or hash mismatch leaves the
prefix unchanged. Append and overwrite are mutually exclusive; append itself
authorises replacing the prefix after verification. Keep the destination
exclusive to this caller during append/overwrite. The builtin owns Range and
Accept-Encoding (requests identity); these headers cannot be overridden.

`max_bytes` applies to the final size, including the prefix, and defaults to
9007199254740991 (the exact integer limit). `bytes_written` counts downloaded
bytes written to staging; `size` includes the copied prefix. `blake3` is the
verified final digest, or nil on failure. The extra `published` boolean is
true once publication succeeds, including the rare status-0 directory-sync
failure after publication; callers must not interpret that failure as rollback.
All earlier failures remove staging and preserve the destination.

Operational failures return status 0 with `FILE_IO`, `FILE_EXISTS`,
`HTTP_RANGE`, `HTTP_HASH_MISMATCH`, `HTTP_SHORT_READ`, `HTTP_BODY_LIMIT`, or
the HTTP transport/body codes. Invalid options raise. Network and FsWrite
are unconditional; append:true or ca_file additionally requires FsRead.
The same socket inactivity and cooperative deadline limitations apply as for
uploads. Memory use for successful downloads stays bounded by a 64 KiB buffer.

## Streaming file upload (0.97.0)

`http_put_file(url, path[, opts]) -> map<http_file_response>` streams a regular
file with a fixed 64 KiB transfer buffer. Keep the source immutable during the
call. `range: {start, end}` selects inclusive byte offsets; without it the
whole file is sent, including an empty file. Content-Length is exact and an
early EOF fails with `HTTP_SHORT_READ`. Sizes and offsets must be exact Mix
integers (0 through 9007199254740991); invalid ranges raise `OPTION_INVALID`.

Options are `method` (`PUT`, `POST`, or `PATCH`, default `PUT`), `range`,
`headers`, `idle_timeout` (seconds, default 30, positive), `deadline` (seconds,
default 0 = disabled), `ssl_verify`, `ca_file`, and `ca_pem`. TLS options have
the same validation and trust roots as the buffered HTTP builtins below.
Unknown options raise. The builtin owns Content-Length and Transfer-Encoding;
setting either header raises. Redirects are disabled: a 3xx is returned.

`idle_timeout` bounds socket inactivity (and connection establishment).
`deadline` is checked cooperatively around streaming IO. It is best-effort
during blocking DNS/IO, **not a hard whole-call bound**. Both accept fractional
seconds, up to one year.

The distinct `http_file_response` has `status`, `headers`, `bytes_written`,
`size`, `blake3`, `body`, `bytes`, `final_url`, `duration_ms`, `error_code`, and
`error`, and `published` (false for uploads). For uploads, `bytes_written` counts source bytes consumed, not a
server's durable acknowledgement; `size` is the selected window size and
`blake3` is its lowercase digest (nil on failure). Response bodies are capped
at 64 MiB. Received HTTP responses retain their real status; IO/transport failures return
status 0 and an error (`FILE_IO`, `HTTP_SHORT_READ`, or the HTTP codes below).
Argument errors raise. Inspect the result even when the call does not raise.

A server can reject a large PUT/PATCH before consuming its body. If the socket
fails while ureq is still writing, the caller can receive status 0 and lose the
server's status and diagnostic body. For resumable blob uploads, recover via
HEAD and its durable offset/state rather than assuming the chunk was accepted.
Downloads refuse close-delimited 200/206 bodies without Content-Length, as
required by the identity-framing contract above.

Network **and FsRead are unconditional capabilities**, including calls without
options. Structured discovery and `mix lint` include both. The `http` Cargo
feature itself enables BLAKE3; `crypto` is not required for these transfers.

The HTTP client builtins — a small, blocking HTTP/1.1 client built on
[`ureq`](https://docs.rs/ureq). Three calls cover the whole surface:
`http_get`, `http_post`, and the any-verb `http_request`. They are
**feature-gated** (the `http` cargo feature) in `mixos-lib-mix`; the shipped
`mix` binary turns the feature on, so they are always present in the CLI. In
the builtin catalogue they list under the `system` category
(`mix builtins system`); one-line help for any name: `mix what http_get`.

> Mental model: every call **returns a map, never raises, for anything that
> happens on the network**. A successful or HTTP-error response is
> `{status, body, bytes}`; a transport failure — including a
> [timeout](#timeouts) — is `{status: 0, error}`. You branch on `status`, you
> don't wrap the call in [try/catch](errors.md). (Argument mistakes — wrong
> arity, a bad opts map, a bytes header value — do raise: they are script
> bugs, not network weather.)

```mix
$r = http_get("https://example.com")
print("status=" .. $r["status"])
print("body_len=" .. length($r["body"]))
```
```text
status=200
body_len=559
```

## The four calls

```
http_get(url, [headers], [{timeout, ssl_verify, ca_file, ca_pem}])                      -- GET
http_post(url, body, [headers], [{timeout, ssl_verify, ca_file, ca_pem}])               -- POST with a body
http_request(method, url, [body], [headers], [{timeout, ssl_verify, ca_file, ca_pem}])  -- any verb
http_post_multipart(url, fields, files, [headers], [opts])                              -- POST multipart/form-data
```

- `url` — a string (anything else is stringified via the usual coercion).
- `headers` — an optional **map** of header name → value (see [Headers](#headers)).
- `body` — a string (sent as UTF-8) or a `bytes` buffer (sent raw); see [Request bodies](#request-bodies).
- `fields` / `files` (`http_post_multipart` only, v0.103.12) — `fields` is a map of string form fields; `files` is a map of `field_name → {filename, content_type?, data: bytes|buffer}`. The multipart boundary is generated and the `Content-Type` header set accordingly — the generic webhook/file-upload slot, so a vendor upload is a script over this, never a core dependency (see [Request bodies](#request-bodies)).
- `method` (`http_request` only) — upper-cased internally, so `"get"`, `"Get"`, `"GET"` are equivalent. It must be a valid [RFC 7230](https://www.rfc-editor.org/rfc/rfc7230) token (no spaces / control bytes) or the call returns the error shape — this guards against request-line injection.
- `{timeout, ssl_verify, ca_file, ca_pem}` — an optional trailing **opts map**. `timeout` bounds the whole request (default 30 s, `{timeout: 0}` disables — see [Timeouts](#timeouts)). `ssl_verify` defaults to `true`; `ssl_verify: false` **skips TLS certificate and hostname verification** for that call (like `curl -k`) — see [Skipping TLS verification](#skipping-tls-verification).
- `ca_file` / `ca_pem` (v0.29.0) — trust a **private CA** for this call: `ca_file` reads PEM certificate(s) from a path, `ca_pem` takes them inline (string/bytes/buffer). The certificates are **ADDED to the default (Mozilla webpki) roots** — chain building and hostname verification still run in full, so this is the right way to talk to an internal endpoint with a proper private-CA-issued cert (the readiness-check case), unlike `ssl_verify: false` which proves nothing. Mutually exclusive with each other and with `ssl_verify: false`; input capped at 4 MiB; a missing/unreadable file, invalid PEM, or PEM with no certificates raises a catchable `HTTP_TLS` structured error (see [errors](errors.md)). In a capability-sandboxed embedder, `ca_file` additionally requires the `fs-read` class (declared as a conditional capability in the builtin metadata).

`http_get` takes 1–3 arguments, `http_post` 2–4, `http_request` 2–5. Too few
raises a runtime error, and — unlike the Mix-wide minimum-arity convention —
**too many also raises**, so a misplaced opts map can't be silently ignored
and leave a call unbounded:

```mix
http_get()
-- Runtime error at line 1: http_get() expects at least 1 argument(s), got 0
http_post("https://example.com")
-- Runtime error at line 1: http_post() expects at least 2 argument(s), got 1
http_get($url, {}, {}, {})
-- Runtime error at line 1: http_get() expects at most 3 argument(s), got 4
```

## The return shape

Every call resolves to one of two map shapes.

### Success / HTTP-error response

| key | type | meaning |
|---|---|---|
| `status` | number | the HTTP status code (`200`, `404`, `503`, …) |
| `body` | string \| nil | the body **decoded as UTF-8**; `nil` when the bytes are not valid UTF-8 |
| `bytes` | bytes | the **raw** response byte buffer, always present |
| `headers` | map | response headers — **lowercase** names → **list** of string values (repeated fields preserved), e.g. `$r.headers["content-type"]` is `["text/html"]` (v0.30.0) |
| `final_url` | string | the URL after any redirects (v0.30.0) |
| `duration_ms` | number | wall-clock request duration (v0.30.0) |
| `error_code` | string \| nil | `nil` on any HTTP response (incl. 4xx/5xx); an `HTTP_*` code only on a transport failure (v0.30.0) |
| `error` | string \| nil | `nil` on an HTTP response; the message on a transport failure |

The `headers`/`final_url`/`duration_ms`/`error_code` keys are **additive** —
pre-0.30 scripts reading `status`/`body`/`bytes` are unaffected.

A **4xx / 5xx is a response, not a failure** — it carries the real code plus
whatever error payload the server sent, so REST callers can read both:

```mix
$r = http_get("https://example.com/does-not-exist-xyz")
print("status=" .. $r["status"])
print("body=" .. substr($r["body"], 0, 40))
```
```text
status=404
body=<!doctype html><html lang="en"><head><ti
```

The documented success test is `status == 200` (or a `2xx` range check) — it is
unaffected by error statuses landing in `status` rather than the error shape.

### Transport failure — `{status: 0, error}`

Only a genuine transport error — DNS failure, TLS handshake, connection refused,
a [deadline expiry](#timeouts), a mid-stream read error, an invalid method, or
an over-cap body — collapses to `status == 0` with a human-readable `error`
string and **no** `body`/`bytes`:

```mix
$r = http_get("http://127.0.0.1:1/")
print("status=" .. $r["status"])
print("error=" .. $r["error"])
```
```text
status=0
error=http://127.0.0.1:1/: Connection Failed: Connect error: Connection refused (os error 111)
```

`status: 0` is the one sentinel that means "no HTTP exchange happened" — a real
server never returns code 0, so a single `if $r["status"] == 0` cleanly
separates "the network broke" from "the server answered". The canonical guard:

```mix
$r = http_get($url)
if $r["status"] == 0 then
  print("transport error: " .. $r["error"])
else
  -- $r["status"] is a real HTTP code; $r["body"]/$r["bytes"] are present
end
```

## Text vs binary — `body` and `bytes`

`bytes` always carries the raw buffer. `body` is the **UTF-8 decode** of that
buffer, or `nil` when the bytes are not valid UTF-8 — so a binary response
(image, archive, anything high-bit) does **not** silently corrupt through a
lossy decode. An *empty* body decodes to the empty string `""`, not `nil` —
`nil` strictly means "not UTF-8". Reach for `.body` for JSON/text, `.bytes`
for binary:

```mix
$r = http_get("https://www.google.com/favicon.ico")
print("status=" .. $r["status"])
print("body_is_nil=" .. ("" .. ($r["body"] == nil)))
print("bytes_present=" .. ("" .. (not is_empty($r["bytes"]))))
```
```text
status=200
body_is_nil=true
bytes_present=true
```

For a text response, `body` is a normal string and `bytes` holds the same data
as a raw buffer — write it straight to disk with `write_file` (a bytes value
is written verbatim), or pass it to a [bytes helper](data.md):

```mix
$r = http_get("https://example.com")
write_file("/tmp/example.html", $r["bytes"])
```

To measure the buffer use `bytes_len($r["bytes"])` or, since **v0.64.0**, plain
`length($r["bytes"])` — both answer the byte count. The raw body can also be
indexed, sliced, iterated and searched directly (`bytes_find`, `bytes_split`,
`bytes_starts_with`); see [io](io.md#bytes-as-a-sequence-v0640).

## Headers

The optional `headers` argument is a **map**. Keys are header names, values are
stringified the usual way. If you don't set a `User-Agent`, `ureq`'s default
(`ureq/2.12.1`) goes out — the examples here set their own because some APIs
care:

```mix
$r = http_get("https://api.github.com/zen", { "User-Agent": "mix-docs" })
print("status=" .. $r["status"])
print("body=" .. $r["body"])
```
```text
status=200
body=Encourage flow.
```

A `bytes` **value** is rejected (not stringified) so the internal `<bytes:N>`
placeholder never ships over the wire — HTTP headers are text. If you genuinely
need binary header metadata, encode it yourself:

```mix
http_get($url, { "X-Token": $raw_bytes })
-- Runtime error: http: header `X-Token` does not accept bytes; base64_encode($v) first
```

One carve-out: a **sole** map in this slot whose keys are **all** opts keys
(`timeout`, `ssl_verify`, `ca_file`, `ca_pem`) is read as the opts map, not as headers — see
[the trailing-map rule](#the-trailing-map-rule). Any real-world header map
(carrying a non-opts key like `Authorization`) is unaffected.

## Request bodies

`http_post` (and `http_request`'s optional 3rd slot) send a body. A **string**
is sent as UTF-8; a **bytes** buffer is sent raw (so a binary upload doesn't go
through string coercion). Set `Content-Type` yourself — the client does not
guess it:

```mix
$payload = "{\"hello\":\"world\"}"
$r = http_post("https://httpbin.org/post", $payload, { "Content-Type": "application/json" })
print("status=" .. $r["status"])
$j = json_parse($r["body"])
print("echoed=" .. $j["data"])
```
```text
status=200
echoed={"hello":"world"}
```

`http_request`'s body slot is **`nil`-tolerant**: an absent or `nil` 3rd
argument sends a bodyless request (the right behaviour for `GET`/`DELETE`/
`OPTIONS`):

```mix
$r = http_request("GET", "https://example.com")   -- no 3rd arg → bodyless
print("status=" .. $r["status"])
```
```text
status=200
```

`HEAD` reports the real status with an empty body — a bodyless response is
not a transport failure:

```mix
$r = http_request("HEAD", "https://example.com")
print($r["status"] .. " / body=" .. length($r["body"]) .. " bytes")
```
```text
200 / body=0 bytes
```

> A `HEAD` response mirrors the headers a `GET` would return — including a
> `Content-Encoding` — but the server omits the body. The body is skipped
> rather than drained; before this fix, a `HEAD` from a server that sends
> `Content-Encoding` (example.com, github.com, …) collapsed to `{status: 0,
> error}` because the (empty) body was still run through a decoder.

An invalid method short-circuits to the error shape (no request is sent):

```mix
$r = http_request("BAD METHOD", "https://example.com")
print($r["status"] .. " / " .. $r["error"])
```
```text
0 / http: invalid request method "BAD METHOD" (must be an RFC 7230 token)
```

## Timeouts

Every call runs under a **total-request deadline — 30 seconds by default** —
one wall-clock budget covering connect, TLS, request write, and response read
(`ureq` itself sets no timeout; before mix 0.21 a stalled server could hang
the evaluator, and a login shell, forever). Override it per call with the
trailing opts map:

```mix
$r = http_get($url, {timeout: 5})            -- 5 s deadline
$r = http_get($url, $headers, {timeout: 5})  -- headers AND a deadline
$r = http_get($url, {timeout: 0})            -- no deadline (deliberately long transfer)
```

`timeout` takes a **non-negative integer, in seconds**. A fractional,
negative, or non-number value is a loud runtime error, and so is any other
key in the opts map — a typo can't silently produce an unbounded call:

```mix
http_get($url, {}, {timeot: 5})
-- Runtime error at line 1: http_get: unknown opt "timeot" (supported: timeout)
http_get($url, {timeout: 1.5})
-- Runtime error at line 1: http_get: timeout must be a non-negative integer, got 1.5
```

A deadline expiry is a **transport failure, not a raise** — the usual
`{status: 0, error}` shape. (There is no `timed_out` key; that is a
[`run_rc`](system.md) convention.)

```mix
$r = http_get("http://127.0.0.1:8098/", {timeout: 1})   -- a hanging server
print($r["status"] .. " / " .. $r["error"])
```
```text
0 / http://127.0.0.1:8098/: Network Error: Network Error: Error encountered in the status line: timed out reading response
```

### The trailing-map rule

The opts map rides in the **last** slot, after the optional headers (and, for
`http_request`, body) slots. To keep the common case short, a **sole trailing
map whose keys are all opts keys (`timeout`, `ssl_verify`, `ca_file`, `ca_pem`) is always read as the
opts map** — never as a headers map, and never as a request body:

```mix
http_get($url, {timeout: 1})                     -- deadline, not a `timeout` header
http_get($url, {ssl_verify: false})              -- skip TLS verification
http_post($url, $body, {timeout: 1})             -- deadline, not a header
http_request("GET", $url, {timeout: 1})          -- deadline, not a body
http_request("POST", $url, $body, {timeout: 1})  -- deadline, not a header
```

To genuinely send a literal `timeout` HTTP header, spell out the opts slot —
an empty opts map keeps the 30 s default:

```mix
$r = http_get($url, {timeout: "60s"}, {})   -- sends the header `timeout: 60s`
```

A map carrying any non-opts key (e.g. `Authorization`) is a plain headers map
(or, in `http_request`'s 3rd slot, a stringified body), so real-world maps never
trip the rule.

## Skipping TLS verification

TLS is on for every `https://` URL, and a bad certificate surfaces as a
transport error (`{status: 0, error}`), not a panic. Some internal endpoints —
Proxmox VE (`:8006`), Proxmox Backup Server (`:8007`), and other appliances —
serve a **self-signed** certificate that no public CA vouches for. Rather than
pin their CA, pass `ssl_verify: false` in the opts map to skip certificate and
hostname verification for that call, exactly like `curl -k`:

```mix
$r = http_get("https://b1.example:8006/api2/json/version",
              {"Authorization": $tok}, {ssl_verify: false})
```

The TLS handshake still happens — the connection is encrypted and the peer's
signatures are checked against the ring provider's algorithms — but the
certificate-chain / hostname **trust** decision is bypassed. That removes
protection against a man-in-the-middle, so use it **only** for endpoints you
reach over a trusted path (a private/WireGuard network, localhost, an SSH
tunnel). `ssl_verify` defaults to `true`; there is no way to disable
verification globally — it is always per-call and explicit.

## The 64 MiB body cap

A response body is buffered fully into memory and **capped at 64 MiB**
(`67_108_864` bytes). The cap exists so a huge or endlessly-streaming response
can't OOM a process embedding the Mix evaluator. An over-cap body collapses to
the transport-error shape:

```text
{status: 0, error: "http: response body exceeds the 67108864 byte cap (64 MiB)"}
```

This is a hard limit, not a tunable — these builtins are for API calls and
modest fetches, not for streaming multi-gigabyte downloads. For a large file,
shell out to a streaming tool by full path (see [run](system.md)), which takes
its own `{timeout: seconds}` opts map if you want the download bounded too:

```mix
run("/usr/bin/curl -fsSL https://example.com/big.iso -o /tmp/big.iso", {timeout: 600})
```

## Parsing responses

`body` is just a string, so feed it to the [data](data.md) builtins. JSON is
the common case — `json_parse` turns the body into a map/list with dotted /
indexed field access:

```mix
$r = http_get("https://api.github.com/repos/markc/mixos",
  { "User-Agent": "mix-docs", "Accept": "application/vnd.github+json" })
if $r["status"] == 200 then
  $j = json_parse($r["body"])
  print("name=" .. $j["name"])
  print("default_branch=" .. $j["default_branch"])
end
```
```text
name=mix
default_branch=main
```

For richer extraction use `jq(...)`; for a numeric field, `to_number(...)`. See
[data](data.md) for the full parse / serialize surface (`json_parse`, `jq`,
`data_encode`, the `bytes_*` helpers).

## Worked example — a guarded JSON fetch helper

The idiom in one function — single `status == 0` transport guard, then branch
on the HTTP code, parse on success. It uses the
[pass-in / return / reassign](functions.md) discipline (no shared globals):

```mix
fn fetch_json($url)
  $r = http_get($url, { "User-Agent": "mix-docs", "Accept": "application/json" })
  if $r["status"] == 0 then
    return { ok: false, why: $r["error"] }
  end
  if $r["status"] != 200 then
    return { ok: false, why: "http " .. $r["status"] }
  end
  return { ok: true, data: json_parse($r["body"]) }
end

$res = fetch_json("https://api.github.com/zen")
if $res["ok"] then
  print("got: " .. ("" .. $res["data"]))
else
  print("failed: " .. $res["why"])
end
```

## Notes & sharp edges

- **Blocking & synchronous.** Each call blocks until the response is buffered, the deadline expires (30 s default — see [Timeouts](#timeouts)), or the body cap / a transport error trips. There is no async variant — for latency- sensitive paths, tighten `{timeout: N}` and branch on `status == 0`.
- **No automatic retries, no cookie jar, no redirect-body replay** — `ureq`'s defaults apply (redirects are followed). Add your own retry loop if you need one.
- **TLS is on for `https://`.** A bad certificate surfaces as a transport error (`status: 0`), not a panic.
- **Headers and methods are validated** to block request-line / header injection: a non-token method and a `bytes` header value are both rejected in-band (the former as `{status: 0, error}`, the latter as a runtime error).
- **Don't confuse Mix-string `$(...)` with the URL.** In a double-quoted Mix string, `${name}` interpolates but `$(...)` is literal text — build URLs with `..` concat or `${...}`, e.g. `"https://example.com/api/" .. $id`. See [strings](strings.md).

## Serving — `http_serve`, `http_recv` (v0.75.0)

The other direction, deliberately minimal. **The boundary first**: no TLS
ever, and no dynamic handlers — certificates, vhosts, and request
dispatch to code are [webd]'s job and serve-mode citizens' job. What
lives here is the pair of shapes an agent keeps needing locally:

```
http_serve(root[, {port, host, duration, index, listing, render_md,
                   requests, spa, clean_urls}])
    -> requests served (BLOCKING)
http_recv(port[, {timeout, host, max, respond}])
    -> {method, path, query, headers, body, bytes, from_host, from_port} | nil
```

**`http_serve` is the `python -m http.server` slot**: serve a directory
to a browser — docs preview, a build artifact, a report. GET and HEAD
only; anything else answers 405. `port: 0` (the default) binds an
ephemeral port and **prints the URL** before serving, so the caller
always learns where. `host` defaults to `127.0.0.1`; exposing to the LAN
is one explicit `host: "0.0.0.0"`. `duration` bounds the run in seconds
(0 = until interrupted) — an in-flight request gets at most a 10-second
read grace past it, so one slow client cannot hold the server open;
`requests` stops after N exchanges; `listing`
opts into directory indexes; `render_md` (markdown feature) serves `.md`
files as styled HTML — `http_serve("docs/mix", {render_md: true})` renders
the raw manual `.md` files (but not the site's HTML shell, whose assets
live at the site root — serve the whole `docs/` tree, not a subdirectory,
if you want the interactive site).

The boolean options (`listing`, `render_md`, `clean_urls`) take a real
`bool` only — `"false"`, `1` or `nil` raise `TYPE_MISMATCH` before the
listener binds, never a truthiness read.

> **Serving a subdirectory of a larger site?** A page that references
> root-absolute assets (`/web/style.css`) 404s them when the served root
> is a subdirectory — the assets are above it. Serve the **site root**, or
> pre-render a self-contained copy (see `docs/_build/gen-static-site.mix`
> for the pattern: each page carries its own inline CSS and needs no
> external asset, so it works from any root, `curl`, `wget`, or `file://`).

Traversal is the defended edge: the request path is percent-decoded
*first*, then the resolved file is canonicalised and must remain under
the canonicalised root — `../`, `%2e%2e%2f`, and symlinks inside the
root pointing out all answer 403/404, and the tests prove each one
against raw sockets (a polite HTTP client normalizes `../` away; an
attacker's socket does not).

**Serving a site with clean URLs, two shapes.** A static server maps
`/bus/props-core` to a file of that exact name and 404s when there isn't
one — but real sites use extensionless URLs. Two options cover the two
site shapes, and they compose (clean_urls is tried first — a specific
page beats a generic fallback):

- **`clean_urls: true`** — a would-be 404 on an extensionless path serves
  `<path>.html` when it exists (`/bus/props-core` → `/bus/props-core.html`).
  This mirrors GitHub Pages' pretty-URL behaviour, and is the fix for a
  **pre-rendered page-per-route site** — a real page or a router stub at
  every clean URL. A section page (`bus.html`) sitting beside its
  children directory (`bus/`) resolves too: `/bus` serves the page,
  `/bus/props-core` its child, and `/bus/` (trailing slash) stays a
  directory request. `http_serve("docs", {clean_urls: true})` serves the
  mixos.dev docs tree locally, fully styled, as Pages does.
- **`spa: true`** (or `spa: "shell.html"`) — a would-be 404 on an
  extensionless path serves ONE shell, so a **single-shell SPA**'s
  client-side router boots on every deep URL (`/users/42/settings` →
  the shell → the router renders). Point it at any Vite/React build.
  The shell path is checked at startup, not per request.

Both are frontend-only, and the boundary is exact: a **static SPA** —
assets from root, data from static files or a *separate* API — works
completely; `http_serve` serves the app, never runs its backend. A path
**with** an extension (`/main.css`, `/logo.png`) is never rewritten by
either option, so a genuinely missing asset stays an honest 404 instead
of silently becoming the HTML shell.

**`http_recv` catches ONE request and answers it** — the OAuth
localhost-redirect wait, the webhook test, the "curl me when the job is
done" rendezvous. It blocks up to `timeout` seconds (default 30, 0 =
forever), returns `nil` on timeout (an ordinary answer — poll again),
and hands back the full request: `body` as UTF-8 or nil, `bytes` always
the truth, headers lowercase-keyed. `respond` shapes the reply
(`{status, body, content_type, headers}`, default `200 ok`); `max` caps
the request body (default 1 MiB, refused with 413 beyond it).

```mix
-- wait for an OAuth redirect, answer the browser, extract the code
$r = http_recv(8910, {timeout: 120, respond: {body: "You can close this tab.\n"}})
if $r == nil then die "no redirect within 2 minutes" end
$code = parse_query($r["query"])["code"]
```

`http_serve` blocks until `duration`/`requests` ends it, or until
**Ctrl-C** — SIGINT stops the accept loop cleanly and the call returns
the count served so far, so an interactive `http_serve(dir)` is a normal
"serve until I stop it" command.

Both are sequential, `Connection: close`, one exchange per connection —
a browser and a script, not a load. The moment the words "certificate",
"virtual host", or "route this to a function" appear, the answer is webd.

## See also

- [data](data.md) — `json_parse`, `jq`, `data_encode`, `bytes_to_string` for parsing and serializing HTTP payloads
- [run](system.md) — shelling out (`curl`/`wget`) for streaming or oversized transfers
- [strings](strings.md) — building URLs and bodies (`..` concat, interpolation rules)
- [functions](functions.md) — the pass-in / return / reassign idiom used in the helper above
- [errors](errors.md) — why these builtins return a shape instead of raising
- [builtins index](builtins.md) — the full builtin catalogue
- [Bus messaging](bus.md) — in-mesh RPC (`send`/`emit`); HTTP is for the world *outside* the mesh
- [the manual index](README.md) — every page in this manual
- `mix what http_get` · `mix what http_post` · `mix what http_request` · `mix builtins system` · the [mix repo](https://github.com/markc/mixos)

---

<!-- page: https://mixos.dev/mix/invocation/ (source: https://mixos.dev/mix/invocation.md) -->

# Invoking Mix

`mix` is one binary with several entry modes: an interactive shell (REPL), a
script runner, a `-c` one-liner, a stdin reader, a syntax checker, a supervised
Bus daemon, and a family of one-shot meta commands (`mix help`, `mix man`,
`mix stats`, …). The same binary is also Mark's mesh **login shell**, so
`ssh host '<mix source>'` is evaluated by Mix, not bash. This page covers how to
start Mix in each mode and the rules that decide whether a `-c` / login-shell
line runs as Mix code or dispatches a shell command.

The binary is the oracle; page stamps are held fresh by `cargo test -p system --test man_pages`. Argument parsing
lives in [`mix-shell/src/lib.rs`](https://github.com/markc/mixos/blob/main/cli/mix-shell/src/lib.rs);
the shell-first classifier is in `mix-shell/src/shell.rs`.

```text
$ mix --version
mix 0.89.1 (f886d310df76, built 2026-09-21T03:14:00Z)
```

The line carries the short git sha of the build, suffixed `-dirty` when the
tree was modified at compile time, and the build time — a semver alone cannot
tell a stale binary from a fresh one. It is the shape every mixos binary
answers with, except that mix names itself `mix` rather than its crate
`mix-shell`. `mix --version --json` gives the same provenance
machine-readably (`component`, `version`, `git_sha`, `git_sha_full`,
`git_dirty`, `build_time`).

**A version query does nothing else.** It is answered before the base-env
capture, the native-session lane, Bus dispatch and the evaluation thread, so it
neither starts a session nor disturbs one: `mix --version` is truthful and
side-effect-free while other mix processes are running (0.89.1). Only `argv[1]`
is a version query for the interpreter — `mix -c 'print("--version")'` runs the
program, as before. A `--version` straight after a script path asks for the
**script's** version instead: see [`--version` for scripts](#--version-for-scripts).

## Modes at a glance

| Form | What it does |
|---|---|
| `mix` | Interactive REPL (loads `~/.mixrc`) |
| `mix script.mix [args…]` | Run a file from the OS shell; args via `args()` / `$1`, `$2`, … |
| `mix script.mix [args…]` at the REPL | Run the file in a clean child process; the REPL survives |
| `mix -c '<code>'` | Run one line of Mix **or** dispatch a shell command (shell-first classifier) |
| `mix -i -c '<code>'` | As `-c`, but load `~/.mixrc` first (aliases + PATH), like `bash -ci` |
| `mix - [args…]` | Read the whole script from **stdin** (clean byte channel) |
| `mix --check <script>` | Parse without executing — a syntax check |
| `mix lint [flags] FILE...` | Semantic analysis: undefined names, arity, must-use, stable machine-readable diagnostics (0.29.0 — see [lint](lint.md)) |
| `mix --no-prelude …` | Skip loading the standard prelude (applies to any run mode) |
| `mix --no-traceback …` | Uncaught errors print the legacy single line instead of a traceback (0.29.0 — see [errors](errors.md)) |
| `mix --strict-arity …` | Strict call arity: wrong-arity user-function/builtin calls raise catchable `ARITY_MISMATCH` instead of the compatible missing→nil / extra-ignored binding (0.29.0 — see [functions](functions.md)). **The default for script/`-c`/serve modes since 0.103.0** — `--compat-arity` restores the compatible binding, and the REPL keeps it unless `~/.mixrc` opts in (the REPL reads neither the flag nor `MIX_STRICT_ARITY` — use `$strict_arity = true` in `~/.mixrc` there). Explicit opt-ins (now redundant but harmless): `MIX_STRICT_ARITY=1`, `$strict_arity = true` in `~/.mixrc`, and `ssh_mix(host, src, {strict_arity: true})`; the remote escape hatch is `ssh_mix(host, src, {strict_arity: false})` → `--compat-arity -` on the remote (0.103.2). A mix flag placed AFTER the script/`-c` source is a script argument, never a flag — `mix` warns when a trailing argument matches one of its own flags |
| `mix --compat-arity …` | The strict-arity escape hatch (0.103.0): the compatible missing→nil / extra-ignored binding in script/`-c`/serve modes, with a one-per-(builtin,count) stderr warning on a surplus (0.102.8) |
| `mix --no-lint …` | Skip the `-c`/stdin pre-execution lint gate (0.103.4) |
| `mix --agent …` | Print the gate's soft diagnostics to stderr before running (same as `MIX_LINT=warn`; the hard set refuses regardless) (0.103.4) |
| `mix --serve <script> [--name <svc>]` | Run the script as a supervised Bus daemon citizen — see [serve](serve.md) |
| `mix --version` / `-V` | Print version + build hash, and nothing else — no session lane, no Bus (0.89.1) |
| `mix script.mix --version` / `-V` | Print the **script's** version line without running it (also `mix --serve script.mix --version`, `mix - --version`) — see [below](#--version-for-scripts) (0.95.0) |
| `mix --help` / `-h` | Usage summary |
| `mix stats [sub…]` | Window-labelled usage reports and static authorship coverage — see [stats](stats.md) |
| `mix help` / `mix what <name>` / `mix man [topic]` | Builtin/keyword reference and this manual — see [the `mix` meta-command](cli.md) |

`mix help`, `mix what`, `mix man`, `mix status`, `mix build`, … are the same
meta commands the REPL's bareword `mix` dispatcher accepts, exposed as one-shot
CLI commands: `mix man invocation` prints this page; bare `mix man` prints
[the manual index](README.md). In both contexts, meta names are checked
**before** the script-file fallback, so a script named `build`, `status`, or
`test` in the CWD is shadowed — prefix the path with `./`, for example
`mix ./build`. Full list on [the cli page](cli.md). An unknown option
(`mix --zz`) errors and exits 1; an unknown REPL meta token names the token,
notes that no such file exists, then shows the meta-command overview.

Bare `mix` with **no arguments** starts the REPL — including when stdin is a
pipe. The piped lines are then read and executed one at a time through the
shell-first classifier (with `~/.mixrc` loaded), so a pipe into bare `mix`
**does** run code — it works, but it is not the intended path. For a script use
`mix <file>` or `mix -`: a whole-program parse over a clean byte channel, no
per-line classification, no `~/.mixrc`.

All modes that evaluate Mix record best-effort usage by default and are tagged
as `interactive`, `script`, `c`, `stdin`, or `serve`. Set `MIX_STATS=off` (also
`0` or `false`) to skip collection and all stats I/O. See [usage
statistics](stats.md).

When Term supplies a native-session launch fd, Mix consumes and closes it and
scrubs `MIXOS_SESSION_FD` before startup hooks or user source. Binding and renews
run on a private resident thread; the seed has no Mix language or `mix context`
representation. Invalid bootstrap input reports the failed stage and leaves the
shell usable. Without the marker, all entry modes keep their ordinary silent
startup path.

## Running a script file

The first non-flag argument is the script path; everything after it is passed to
the script.

```mix
-- greet.mix
$all = args()
print("argc=" .. length($all))
print("first=" .. $1)
for each $a in $all
  print("arg: " .. $a)
end
```

```text
$ mix greet.mix alpha beta
argc=2
first=alpha
arg: alpha
arg: beta
```

Two ways to read arguments, both populated the same way:

- **`args()`** returns the list of script arguments (not counting the script path, and not counting any flag given to `mix` itself — `mix --strict-arity greet.mix alpha` passes one argument, not two). See [builtins](builtins.md).
- **Positional `$1`, `$2`, …** are the same arguments by index; `$0` is the script path / filename. These are the one place a bare sigil number is allowed to be unbound without raising — an out-of-range positional reads as `nil`.

`include` inside a script resolves **relative to the running file's directory**
(not the CWD), because the runner records the script path (it is also `$0`, and
error diagnostics attribute to it). The every-time, CWD-relative loader is
`source`. See [modules](functions.md).

The script's exit code is `0` on success, `1` on an uncaught error (the error
message goes to stderr). A `Ctrl-C` interrupt exits `130` (`128 + SIGINT`) in
non-interactive execution and with `--result-fd`, even if a `catch` returns
successfully; plain execution on an interactive terminal retains status `0`.

A command line ending in an odd run of backslashes may continue onto the next
physical line. Mix splices it before classification, so the same command behaves
identically here, under `-c`, and in the REPL. Even trailing runs are literal;
backslashes inside Mix strings and heredoc bodies are untouched. See
[syntax](syntax.md#explicit-line-continuation--at-end-of-line).

At the REPL or login-shell prompt, `mix FILE [args…]` launches the same script
mode as the OS-shell form in a child process. It therefore gets a **clean
scope**, `$0` is `FILE`, and the remaining words populate `args()` and `$1`,
`$2`, …; when it finishes, the existing REPL resumes. Use `source FILE` when
the file should instead execute in and modify the **current session scope**.
Meta names keep precedence over files: if `status` exists in the CWD,
`mix status` still shows status and `mix ./status` runs the file.

A script that registers `on <cmd> … end` handlers does **not** exit after its
last statement — it stays alive pumping events for those handlers. For the
supervised daemon variant (broker registration, reconnect, journald logging),
use [`--serve`](serve.md).

## `--version` for scripts

Every mixos binary AND every Mix script answers `--version` with build details
(Mark's rule, 2026-09-25). A script declares its version with one header line
in its leading comment region:

```mix
#!/usr/bin/env mix
-- version: 1.4.0
-- deploy_widget.mix — ship the widget to the fleet
```

and `mix` answers for it:

```text
$ mix deploy_widget.mix --version
deploy_widget.mix 1.4.0 (3f9a0c1d22be, modified 2026-09-25T01:14:07Z; mix 0.95.0 (a1b2c3d4e5f6))
$ mix plain.mix --version
plain.mix unversioned (9e107d9d372b, modified 2026-09-24T22:03:41Z; mix 0.95.0 (a1b2c3d4e5f6))
$ mix deploy_widget.mix --version --json
{"mix":{"dirty":false,"sha":"a1b2c3d4e5f6","version":"0.95.0"},"modified":"2026-09-25T01:14:07Z","name":"deploy_widget.mix","sha":"3f9a0c1d22be","sha256":"3f9a0c1d22be…","version":"1.4.0"}
```

The contract:

- **One line, exit 0, script not run.** The fields are the script's basename,
  its declared version (or `unversioned`), the first 12 hex digits of the
  SHA-256 of its bytes, its mtime as RFC 3339 UTC, and the interpreter's own
  `mix --version` provenance (`-dirty` suffix included). The hash is what
  proves two nodes run the same bytes; the header is what a human bumps.
- **`--json`** straight after the flag prints the same facts as one JSON
  object, the same map `script_version()` returns (`version` and `modified`
  are `null` when absent), matching `mix --version --json`. Its keys come
  out in a different order from the in-script map; JSON objects are
  unordered, so read them by name.
- **Read, never parsed.** The answer comes from the same cold position as
  `mix --version` — no session lane, no Bus, no prelude, no rc — and the file
  is only read, so a script with a syntax error still reports its version. An
  unreadable path prints the usual `Error reading '…'` and exits 1. The bytes
  and the mtime come from one open of the file, so they always describe the
  same inode.
- **Symlinks.** The name is the basename of the path as given (the link's
  own name, so `~/.local/bin/zcode` reports `zcode`); the hash and the mtime
  are the target's. The same rule holds for a running `--serve` citizen's
  `script_version()`, although serve reads the script by its canonical path.
- **The header form is exactly `-- version: X.Y.Z`** (optional `-pre` /
  `+build` suffix), and it must sit in the **leading comment region**: an
  optional `#!` shebang on line 1, then only blank lines and `--` comment
  lines, within the first 32 lines. The scan stops at the first line that is
  anything else, so a `-- version:` inside a heredoc or string further down —
  a script that generates scripts — is never taken for this file's header.
  Whitespace-tolerant (`--version:1.4.0` counts), but lowercase and the colon
  is required: `-- version 1.4.0` is prose, not a header. The first
  `-- version:` line wins; one whose value is not `X.Y.Z` makes the script
  `unversioned`, and [`mix lint`](lint.md) names that line (MIX-D3016).
- **Mix owns exactly one position: the first argument after the script
  path.** `mix script.mix --version` and `-V` there are Mix's; anywhere else
  they are ordinary script arguments — `mix script.mix x --version` runs the
  script with `args()` = `["x", "--version"]`. The interpreter flags that may
  come before the script (`-i`, `--no-prelude`, `--no-traceback`,
  `--strict-arity`) do not change this. Under `--serve` the position is the
  one right after the script path, so `mix --serve s.mix --name x --version`
  and `mix --serve s.mix --no-prelude --version` are NOT queries (serve
  refuses the stray `--version` as a usage error).
- **Opting out: `-- version-flag: script`.** A script that must answer
  `--version` itself — a wrapper that forwards argv to another program, such
  as `ctl/_bin/zcode.mix` behind `~/.local/bin/zcode` — declares this line in
  the same leading comment region. `mix` then does not take position 1: the
  script runs with `--version` in `args()` and is expected to answer the flag
  itself. Only the exact value `script` counts. `--serve` still answers for an
  opted-out script, because a daemon has no argv to hand the flag to, so
  `mix --serve SCRIPT --version` is the cold provenance route for an
  opted-out script: it only reads the file, whether or not the script is a
  citizen, and never starts it.
- **`mix --serve script.mix --version`** answers the same way and exits before
  any broker connect. **`mix - --version`** reads the script from stdin and
  names it `-`, with no `modified` field:
  `- 1.4.0 (3f9a0c1d22be; mix 0.95.0 (a1b2c3d4e5f6))`.

A running script reads the same facts as data with `script_version()`:
`{name, version, sha, sha256, modified, mix: {version, sha, dirty}}`, where
`version` is nil for an undeclared header and `modified` is nil for stdin.

- It describes the **entry script**: a `require`d module that calls it gets
  the entry script's record, not its own.
- It is **nil** in the REPL, under `-c`, and in any embedder that runs Mix
  without installing a record (the MCP `mix_execute` tool, a Rust host
  calling the evaluator directly).
- It is held **per evaluator**, so under `--serve` each RELOAD generation
  answers for its own file: a handler of the old generation still draining
  after a reload reads the old record, the new script's init and handlers
  read the new one, and a reverted reload leaves the old one untouched.
- Its `mix` block is deliberately **not** `mix_version()`'s shape. It carries
  the version string and build sha of the interpreter, which is what
  provenance needs, where `mix_version()` splits the number into
  major/minor/patch for version gates.

```mix
$v = script_version()
log("starting " .. $v.name .. " " .. ($v.version ?? "unversioned") .. " @ " .. $v.sha)
```

## `mix -c` — one-liners and the shell-first classifier

`mix -c '<code>'` runs a single line. **It is shell-first**: the same classifier
the REPL uses decides whether the line is Mix code or an external command. This
is what makes Mix usable as a login shell — `mix -c 'hostname'` dispatches a
command, `mix -c 'print(1 + 1)'` evaluates Mix.

```text
$ mix -c 'print(1 + 1)'
2
$ mix -c 'echo hello from shell'
hello from shell
```

### How the classifier decides (shell.rs `classify_input`)

A line starting with `#` or `--` is a comment (empty input). Otherwise the first
word (after skipping `KEY=VALUE` env prefixes and expanding any alias) routes
the line:

1. **Starts with `$`** → Mix code (e.g. `$x = 1`), with a shell-chain fallback.
2. **A Mix statement-keyword head** (`print`, `if`, `for`, `send`, `function`, `try`, …) → Mix, also with the shell-chain fallback. `true` / `false` / `nil` are deliberately **not** keyword heads (since 0.21.0): a bare `true` or `false` line routes to `/usr/bin/{true,false}` so `false` exits **1** like every shell, and `nil` (no external binary) falls through to the Mix parse. Inside Mix source the lexer still owns all three literals (`$x = true`).
3. **A shell builtin head** (`cd`, `pushd`, `popd`, `history`, `exit`, `which`, `type`, `jobs`, `mix`, …) → external path.
4. **A tight-hyphenated command-shaped head** (`mixos-comp`, `systemd-nspawn`) → external command before Mix can parse it as subtraction, whether or not it is on `PATH`. The rule is statement-head-only and requires an ASCII letter/`_` start with only ASCII letters/digits/`_`/`-`; spaced `a - b`, sigil/numeric subtraction, and expression-position `print(a-b)` stay Mix. Scope does not affect the decision: bare `a` is the string `"a"`, not `$a`, so `a-b` remains a command when `$a` is live.
5. **First word found on `PATH` or is a path** (`./x`, `/bin/ls`) → external command (design principle: shell-first). Routing is head-first — `&&` / `||` / `;` never force the shell path by themselves: a Mix-keyword head with a chain stays Mix (Mix has native statement chaining), an external head parses the chain on the shell path.
6. **Otherwise** → parse as Mix (function call, expression). If that fails definitively, a genuinely command-like head (`gti status`) reports the familiar "command not found" and exits 127; a Mix-shaped head — a lexer failure (`0755`), an operator, a glued call/index opener (`print(…`) — surfaces the **real lex/parse error** and exits 1. An unknown command-like semicolon list (`zqxfoo; zqxbar`) stays on the shell path even though each bare word could parse as a discarded Mix string; this preserves the pre-0.31 shell result instead of silently succeeding. A known preserved wart is that a non-keyword alphabetic head such as `not $x; print(1)` is also shell-routed and exits 127; use a Mix keyword, sigil, or parenthesized call to make the intent explicit.

Two consequences worth internalising:

```text
$ mix -c 'false' ; echo $?    # routes to /usr/bin/false — exits 1, like every shell
1
$ mix -c 'true' ; echo $?
0
$ mix -c 'print(false)'       # the boolean literal, inside Mix source
false
```

A dispatched command's exit status becomes Mix's exit code
(`mix -c '/bin/sh -c "exit 7"'` exits 7). `&&` / `||` / `;` chaining and pipes
work on the external path, and a plain foreground `cd` works inside chains
(`cd /tmp && pwd`) — `-c` also has bare `cd` (→ `$HOME`), `cd -`, and
`~`-expansion. See [the shell page](shell-mode.md) for the full dispatch
grammar (redirects, brace expansion, `$(…)` substitution).

A definitive Mix lex/parse error exits non-zero with the real diagnostic — it is
**not** silently retried as a command:

```text
$ mix -c 'print(0755)'
Lexer error at line 1:7: ambiguous leading-zero number '0755' — use a 0o (octal) / 0x (hex) / 0b (binary) prefix, or drop the leading zero(s) for decimal
$ echo $?
1
```

### The bare-name footgun

Every Mix variable needs a `$` sigil. A bare `name = value` line is read as a
shell command, not an assignment:

```text
$ mix -c 'x = 1'
mix: x: No such file or directory (os error 2)
$ echo $?
127
$ mix -c '$x = 1
print($x)'          # the $ sigil makes it Mix
1
```

See [variables](variables.md) for the sigil rules.

### Multi-statement `-c`

Mix statements may be separated by `;` or real newlines. Semicolons are the
compact one-line form:

```text
$ mix -c '$x = 5; $y = 7; print($x * $y)'
35
```

Literal newlines remain useful for a readable multi-statement body:

```text
$ mix -c '$x = 5
$y = 7
print($x * $y)'
35
```

### Positional args under `-c`

Everything after the code string is a positional `$1`, `$2`, … — even a word
starting with `-` (so flags like `--no-prelude` must come **before** `-c`).
`$0` is unset (`nil`) under `-c`.

```text
$ mix -c 'print("got " .. $1 .. " and " .. $2)' one two
got one and two
```

A bare `mix` inside a `-c` line is refused (it would otherwise launch a nested
REPL):

```text
$ mix -c 'mix'
mix: -c: bare 'mix' would start an interactive REPL — ignored
```

## `mix -i` — load `~/.mixrc` first

`-i` makes a `-c` run interactive-flavoured (≈ `bash -ci`): it sources
`~/.mixrc` first, so your aliases and the toolkit's `PATH` are in scope before
the line is classified and run. The combined spellings `-ci` and `-ic` mean the
same thing.

```text
$ mix -i -c '<line>'     # aliases expanded, ~/.mixrc PATH applied
$ mix -ci '<line>'       # same
```

Without `-i`, a plain `mix -c` has **no aliases** and does not read `~/.mixrc`
(≈ `bash -c`). `~/.mixrc` also auto-loads for the plain interactive REPL
(`mix` with no args). It does **not** load for a non-interactive `ssh host
'<mix>'` — that path is closest to `mix -c`.

## `mix -` — read a script from stdin

`mix -` reads the entire program from stdin as a clean byte channel — no shell
re-quoting, nothing written to disk. This is the residue-free way to ship a
script to a remote host (it is also the transport under the `ssh_mix` builtin —
see [remote](remote.md)).

```text
$ echo 'print("from stdin: " .. (2 * 21))' | mix -
from stdin: 42
$ echo 'print("name=" .. $1)' | mix - worldarg
name=worldarg
```

Args after `-` are the script's positionals, exactly as with a file. `$0` is set
to `"-"`. Unlike a pipe into bare `mix` (which the REPL consumes line by line
through the classifier), `mix -` parses the whole program up front.

## Running as a login shell and over SSH

When `/opt/mixos/bin/mix` is **root's login shell** on a host, `ssh host
'<cmd>'` is evaluated by Mix, not bash. The universal shell `-c` contract still
holds because the login path runs through the same shell-first classifier:

- **`ssh host hostname`** — bare command, dispatched natively (no Mix needed).
- **`ssh host 'mix status'`** — `mix` self-resolves via `current_exe`, no PATH needed for this case.
- **`ssh host '<mix source>'`** — send Mix source to get Mix behaviour, e.g. `ssh host 'print(run("hostname"))'`.

```text
$ ssh node1 'print("hostname is: " .. run("hostname"))'   # node1 runs mix as its login shell
hostname is: node1
```

(Locally, `echo '<mix source>' | mix -` runs the same script against *this* host.)

From a Mix script, drive a remote mix through the ssh builtins instead of raw
`ssh`: `ssh_run($host, $cmd)` for a one-liner, and `ssh_mix($host, $source)` —
which ships whole Mix source over ssh stdin into `/opt/mixos/bin/mix -`,
bypassing every shell-quoting layer — for anything with quoting. A remote
whose mix lives elsewhere takes the `mix_bin` option, or set
`MIX_REMOTE_BIN` locally for every call (see
[`ssh_mix`](remote.md#ssh_mixhost-source-opts--map)). The
[`ssh_mix` + heredoc headline idiom](remote.md#headline-idiom-ssh_mix--heredoc)
shows the interpolation and bindings rules.

Two PATH gotchas to remember on the remote side:

- Inside `run` / `run_rc` (which spawn `/bin/sh` with a **minimal PATH**), call binaries by **full path** — `/opt/mixos/bin/mix`, not bare `mix`. See [running commands](system.md).
- A non-interactive `ssh host '<mix>'` has **no aliases** (it's the `mix -c` path, not `mix -i`).

For Mix-as-a-shell language facts (`&&`/`||`/`;` chaining, pipes, redirects,
brace expansion, `$(…)` command substitution on a shell-dispatch line), see
[the shell page](shell-mode.md).

## `--no-prelude`

Mix loads a small standard prelude (Mix-source helpers) before running your
code; `--no-prelude` skips it. It applies to any run mode (`-c`, file, `-`,
`--serve`). Builtins are compiled in and are unaffected — only prelude-defined
helpers disappear. Give the flag **before** the code string / script path
(after them it would be read as a script argument); `--serve` also accepts it
after the script path.

```text
$ mix --no-prelude -c 'print("" .. range(1, 3))'   # range is a builtin, still works
[1, 2, 3]
```

The prelude source is `mixos-lib-mix/std/prelude.mix`, compiled into the binary.
A user override at `<base>/prelude.mix` is honoured if it exists, where `<base>`
is `$MIXOS_SRC` when that variable is set, otherwise `$MIXOS`. (Setting
`$MIXOS_SRC` *replaces* the base — `$MIXOS/prelude.mix` is then not consulted.)
Otherwise the built-in prelude is used.

## `--check` — syntax check without running

`--check` lexes and parses a script and prints `<file>: OK`, or the first
parse/lex error and exits 1. Nothing is executed.

```text
$ mix --check good.mix
good.mix: OK
$ echo $?
0
$ mix --check bad.mix
Parse error at line 3:1: expected End, got Eof
$ echo $?
1
```

Use it in CI or a pre-commit hook to catch unterminated blocks (missing `end`),
unclosed strings, and lexer errors before deploy.

## `--serve` — run a script as a supervised Bus daemon

`mix --serve <script> [--name <svc>]` runs the script as a long-lived,
**supervised** Bus citizen instead of a one-shot script. It connects to the local
broker (`noded`), registers, and runs an unconditional event pump that
dispatches your `on <cmd> … end` handlers until SIGTERM/Ctrl-C or a `QUIT`.

```text
$ mix --serve worker.mix              # Bus service name = script stem ("worker")
$ mix --serve worker.mix --name probe # explicit service name
```

Name derivation (SPEC 18 §3.1): `--name` wins; otherwise the default is the
script's file **stem**. A leading `mixos-` is stripped from either source
(`/usr/local/lib/mixos/statecache.mix` → `statecache`, and `--name mixos-foo`
canonicalises to `foo`). An anonymous serve with no derivable name is a launch
error — never a nameless citizen. Serve mode takes **no positional script args**
(a daemon has no argv); only `--name` and `--no-prelude` may follow the script
path, in any order.

It differs from a plain run in four ways: a reconnecting supervised transport (a
broker bounce is a transient drop, not a death); an **unconditional** event pump
(a plain run pumps only when the script registered handlers); an exhausted
initial connect budget that fails fast (exit non-zero) under systemd; and a
runtime-reserved verb surface — `HELP` / `INFO` / `QUIT` plus
`<svc>.props.{get,list,describe}` are answered by the runtime pre-dispatch, so
an `on` handler can never shadow them. Logging goes to **journald** (stderr
fallback off-systemd), tagged with `service = <svc>`. The full contract is on
[the serve page](serve.md); see [Bus messaging](bus.md) for `on … end` handlers
and the broker model.

## Resource note

Scripts run by the `mix` binary on the main thread get a raised recursion cap
(128 vs the library default of 16). A runaway still returns a clean error rather
than a native stack overflow. The binary does **not** sandbox its own operator —
time/collection caps stay unset for binary-run scripts.

## See also

- [variables](variables.md) — the `$` sigil and scope rules
- [strings](strings.md) — `'raw'` vs `"${…}"`, `..` concat
- [functions](functions.md) — `args()`, positionals, `include`/`source`
- [the shell page](shell-mode.md) — chaining, pipes, redirects, brace/`$(…)` expansion
- [running commands](system.md) — `run` / `run_rc` and the minimal PATH
- [remote execution](remote.md) — `ssh_run` / `ssh_must` / `ssh_mix`
- [serve](serve.md) — the full `--serve` citizen contract
- [the `mix` meta-command](cli.md) — `mix help`, `mix man`, `mix stats`, …
- [Bus messaging](bus.md) — `send` / `on … end` and `--serve` citizens
- [builtins index](builtins.md) — `args`, `range`, `run`, …
- [the manual index](README.md)
- `mix help` — full categorised builtin reference; `mix what <name>` — per-name lookup
- [Mix repo](https://github.com/markc/mixos) · [ARexx background](https://en.wikipedia.org/wiki/ARexx)

---

<!-- page: https://mixos.dev/mix/io/ (source: https://mixos.dev/mix/io.md) -->

# io — files & I/O builtins

The **io** builtin category — read, write, walk, and stat the filesystem, plus
stdin, path-string helpers, and the embedded SQLite client. Every example below
was run against **mix 0.21.2** and shows real output, except the sub-second
timestamp section, which was run against **mix 0.44.0** — the release that added
the field it demonstrates. List the category live with
`mix builtins io`; one-line help for any name with `mix what NAME`. (That listing
also shows `print` / `eprint` — those are *statements*, not builtin calls; see
[keywords](keywords.md).)

Mix's filesystem builtins are *native* `std::fs`/`std::os::unix` calls — there is
no `/bin/sh` in the loop. Reach for them instead of shelling out: `stat(p)` not
`run_rc("stat -c …")`, `chmod(p, 0o755)` not `run("chmod 755 …")`. They are
structured-return by design — `stat` hands back a map, `read_lines` a list, `walk`
a flat list of paths — so the result is data you index into, never string soup you
re-parse.

## Common semantics

- **Paths are plain strings.** A relative path resolves against the process CWD. No tilde expansion happens *inside* a builtin — `"~/x"` only expands at lex time in a double-quoted [string](strings.md) literal, so `read_file("~/.mixrc")` works because the lexer rewrites `~` to `$HOME`, but `read_file($p)` where `$p` holds a literal `"~/x"` does not.
- **Errors raise, they don't return a sentinel.** A failed `read_file` / `ls` / `mkdir` raises a catchable runtime error (the message names the call and path). Wrap a must-succeed step in `try/catch`, or pre-check with `exists` / `access` / `is_file` / `is_dir`. The exceptions are the predicates themselves (`exists`/`access`/`is_dir`/`is_file` return a `bool` for ordinary absence or denial) and `glob`, which returns an empty list for "no match", never an error.
- **Mode arguments take the VALUE, not the digits.** `chmod`/`write_new` want an octal *literal* — `0o755` (= 493), `0o600` (= 384) — or an octal *string* (`"0755"`). A bare `755` is the decimal number 755, not the mode (see [numbers](numbers.md) for why `0755` is a lex error and `0o755` is the value). That lex error is a Mix-*expression* hazard only — `0755` inside a command string handed to `run` (`run("install -m 0755 a b")`) is plain text for `/bin/sh` and works fine.
- **`stat`'s `ino`/`dev` are STRINGS.** They are `u64` and Mix numbers are f64, which loses precision above 2^53 — so they come back as text, ready to use verbatim as a dedupe key. Don't `to_number()` them.
- **Bytes vs strings.** `read_file`/`read_lines` require valid UTF-8 (they error on a bad byte); `read_file_bytes` carries the raw buffer through `Value::Bytes`. `write_file`/`append_file`/`write_new` accept exactly a string, `bytes` or `buffer` — a `bytes`/`buffer` argument is written verbatim, a string as UTF-8, and **nothing else is coerced**: a map, list, function, number, bool or nil raises `TYPE_MISMATCH` *before* the file is opened, so encode first with `json_encode`/`data_encode`/`to_string`.

## Native filesystem events

```mix
$watch = fs_watch("/srv/scenes", {
  recursive: true,
  events: ["created", "modified", "deleted", "moved"]
})
on fs.changed
  $batch = $event.args
  -- Reconcile affected paths; overflow means rescan the watched root.
  print($batch)
end
-- fs_unwatch($watch) cancels this registration and its pending changes.
```

`fs_watch(path[, opts]) -> handle` requires an existing root. The handle is an
opaque string owned by this evaluator generation; do not interpret or persist it.
Defaults: `recursive:false`, all four event kinds. Unknown options and event
names are refused. All three watch builtins require `FsRead` capability.

`fs_unwatch(handle) -> nil` removes the watch and pending changes. An already
dispatched handler may still finish; a waiting `fs_wait` wakes with cancellation.
`fs_wait(handle) -> batch` suspends outside serve mode, without polling. Dropping
the waiting evaluation does not consume an event. In `--serve`, use `on fs.changed`:
`fs_wait` is refused so there cannot be competing consumers. Expression mode
also denies `fs_wait`. In a plain script, a top-level `sleep()` dispatches native
events only for families with a registered handler. An unrelated handler (or
only `on proc.exited`) leaves filesystem batches available to `fs_wait`.

Each batch is `{watch, changes:[{path,kind,old_path?}], overflow}`. Paths are
absolute, with parent symlinks resolved during registration. Changes coalesce
per path at delivery; a write or close-write does not erase a pending `created`
or paired rename.
Coalescing that would discard a different rename origin sets overflow.
`moved` has `old_path` only when inotify supplied both endpoints. A half move
invalidates its reported path without guessing the other endpoint. Consumers
must reconcile current filesystem state, including absence. Separate writes can
produce separate batches; there is no promise of one notification per save.

The backend is Linux `notify::INotifyWatcher`, never `PollWatcher`. File roots
watch their parent directory, so atomic-save replacement remains visible.
Directory roots watch their parent too, permitting deletion and recreation of
the root while that parent survives. Recursive watches enumerate existing and
new directories on registration or structural events, never on a clock. Root
symlinks are refused; discovered directory symlinks are skipped. This is not a
security boundary against concurrent path/symlink substitution. Moving or deleting
the stable parent itself requires a new registration. Pseudo-filesystems which
do not emit inotify events cannot be observed by this API.

Per evaluator: at most 128 handles, 8192 distinct directory registrations and
4096 pending coalesced changes. All handles share one inotify instance and its
event-loop thread, one reconciliation worker and a bounded 256-record backend
queue. Overlapping handles share directory registrations; removing one handle
does not remove coverage needed by another. The instance and workers retire
after the last handle is removed or the evaluator closes its native sources.
Kernel/queue loss, directory limits or later observation failures set sticky
`overflow:true`; the bit clears only when that batch is delivered. A newly
watched directory also sets overflow because files may have appeared before its
registration. Rescan once for each overflow batch. Non-UTF-8 event paths request
a rescan rather than emitting a lossy path. Event filtering never suppresses
overflow. A failed initial registration releases everything it acquired.
If a later permission/resource failure prevents reinstalling coverage, resolve
that failure and recreate the watch; a rescan alone cannot grant missing watches.
Registration, enumeration and teardown can wait on the underlying filesystem;
there is no hard latency guarantee for a stalled filesystem.

Refusals raise; an uncaught refusal exits nonzero. The structured catch value
contains `{error_code,message}` (`code` remains an alias). Codes:

| Code | Meaning |
|---|---|
| `FS_WATCH_MISSING` | Initial root/parent is absent. |
| `FS_WATCH_PERMISSION` | Kernel denied registration or enumeration. |
| `FS_WATCH_LIMIT` | Handle/directory/kernel resource limit. |
| `FS_WATCH_UNSUPPORTED` | Platform is not Linux. |
| `FS_WATCH_SYMLINK` | Root is a symlink. |
| `FS_WATCH_OPTIONS`, `FS_WATCH_ARGUMENT` | Invalid options or path/handle type. |
| `FS_WATCH_HANDLE` | Unknown handle passed to unwatch. |
| `FS_WATCH_CANCELLED` | Wait names a removed or unknown watch. |
| `FS_WAIT_SERVE` | Blocking-consumer API used in serve mode. |
| `FS_WATCH_IO` | Other initial filesystem/backend failure. |
| `NATIVE_CLOSED` | This evaluator's native registrations have retired. |
| `NATIVE_CONSUMER` | Attempted to enter a second event pump in this evaluator. |

See [serve lifecycle](serve.md#native-events-and-generation-lifetime) for reload
and shutdown ownership. Network and audio changes have their own subscriptions
(`net_watch`, `audio_watch`) — see
[desktop status events](system.md#desktop-status-events--net_watch-audio_watch);
do not watch `/sys/class/net`, which does not emit inotify events. These examples specify the new API; the older version
claims at the top of this page do not apply to this section.

## Reading files

```
read_file(path)          -> string   (whole file; errors if not UTF-8)
read_lines(path)         -> list      (lines, trailing \n stripped, trailing empty dropped)
head(path[, n])          -> list      (first n lines, default 10 — stops reading at n)
tail(path[, n])          -> list      (last n lines, default 10 — reads backwards from EOF)
line_count(path)         -> number   (count lines by streaming; works on non-UTF-8 files)
read_file_bytes(path)    -> bytes     (raw; binary-safe)
read_file_bytes(p, max)  -> bytes     (read at most `max` bytes — header-sniff)
stdin_copy(path)         -> nil       (stream stdin to a file, flushing every chunk)
tty_mode("raw"|"cooked") -> nil       (raw/cooked terminal mode; original restored on exit)
```

```mix
write_file("/tmp/io/hello.txt", "line one\nline two\nline three\n")

print(read_file("/tmp/io/hello.txt"))
$lines = read_lines("/tmp/io/hello.txt")
print("count: " .. length($lines))
print("first: " .. $lines[0])
print("line_count: " .. line_count("/tmp/io/hello.txt"))
```

```text
line one
line two
line three

count: 3
first: line one
line_count: 3
```

`read_lines` strips each trailing newline (`\r\n` too — the `\r` is stripped
with it) and **drops the empty last line** a file ending in `\n` would otherwise
produce — so `"x\ny\n"` is two lines, not three. `line_count` streams the file
in blocks and never materializes a list — the right call when you only want the
count. It is byte-oriented (counts `\n`), so unlike the readers it works on
non-UTF-8 files too.

`head` and `tail` (v0.28.1) are the **no-slurp** twins of
`take(read_lines(p), n)` and `take(read_lines(p), -n)`: same line semantics,
same list result, but `head` stops reading after `n` lines and `tail` reads
64 KiB blocks backwards from EOF — the last 10 lines of a multi-GB log cost
kilobytes, not the file's size in RAM. `n` defaults to 10 and must be a
non-negative integer *number*; a numeric string or bool is a loud error, same
discipline as `read_file_bytes`'s cap. Reach for `read_lines`+`take` only when
you need the whole file anyway.

A missing file raises:

```mix
try
  read_file("/tmp/does-not-exist-xyz")
catch $e
  print("caught: " .. ("" .. $e))
end
```

```text
caught: read_file '/tmp/does-not-exist-xyz': No such file or directory (os error 2)
```

### Reading bytes (binary-safe)

`read_file_bytes` is the binary companion. The optional second argument caps the
read at *max* bytes via `File::take`, so you can sniff a header out of a
multi-megabyte file without slurping it all. The cap must be a real `Number`
(a numeric string or bool is rejected — a silent surprise on a read cap would be
a footgun). Pair it with the [bytes helpers](#bytes-helpers):

```mix
-- a file whose first bytes are the JPEG magic \xFF\xD8\xFF
$all = read_file_bytes("/tmp/io/img.bin")
print("full: " .. bytes_len($all))

$head = read_file_bytes("/tmp/io/img.bin", 4)
print("capped: " .. bytes_len($head))
```

```text
full: 34
capped: 4
```

To pull an ASCII header out of a not-quite-UTF-8 block, decode the capped buffer
with the explicit lossy escape hatch — `bytes_to_string($head, {lossy: true})`
(see below). For a strict-data `.mix` file, use `load_data(path)` — the
non-executing twin of [`include`](functions.md) that parses bare-key `key: value`
data without running it.

## Writing files

```
write_file(path, content)            overwrite (or create); follows symlinks
append_file(path, content)           create-if-missing, then append
write_new(path, content, mode)       atomically create; FAILS if path exists
write_atomic(path, data[, opts])     replace all-or-nothing: old OR new, never partial
```

`content` is a string, `bytes` or `buffer` — nothing else is coerced (a wrong
type raises `TYPE_MISMATCH` before the file is touched).

**FIFOs.** When the path is a named pipe, `read_file`, `write_file` and
`append_file` wait for the other end **without holding the runtime thread**
(since 0.117.0): Ctrl-C raises `interrupted`, SIGTERM takes the graceful
shutdown path, and a `--serve` citizen whose `async` handler waits on a FIFO
still answers `QUIT` and its other verbs. `read_file` returns once every
writer has closed; a write returns once the data is in the pipe. Other
builtins (`read_file_bytes`, `read_lines`, …), stuck NFS/FUSE paths and
character devices still block the thread, and only the SIGTERM backstop
bounds them. A regular file pays one extra `stat` to be told apart.

```mix
write_file("/tmp/io/log.txt", "first\n")
append_file("/tmp/io/log.txt", "second\n")
print(read_file("/tmp/io/log.txt"))
```

```text
first
second
```

### `write_new` — atomic, mode-at-creation, secret-safe

`write_new` is `O_EXCL` at the syscall level (`create_new(true)`): it **fails if
the path already exists**, with no TOCTOU window between a check and the write.
The mode is applied *at creation* via `OpenOptions::mode()`, so the file is never
briefly umask-permissioned — secret material hits disk at the configured mode
from the very first byte. This is the call for DKIM keys and similar single-shot
secrets; for ordinary mutable writes use `write_file`.

```mix
write_new("/tmp/io/secret.key", "TOPSECRET\n", 0o600)
print("perm: " .. stat("/tmp/io/secret.key")["perm"])    -- 0o600 == 384

try
  write_new("/tmp/io/secret.key", "x", 0o600)            -- already exists
catch $e
  print("second write_new: refused (exists)")
end
```

```text
perm: 384
second write_new: refused (exists)
```

> `0o600` prints as `384` because Mix numbers are decimal f64 — `0o600` is just a
> source spelling of the value 384. `stat`'s `perm` field is that same number;
> feed it straight back into `chmod`.

### `write_atomic` — replace a file all-or-nothing

`write_file` truncates first and then writes. A crash, a kill, a full disk or a
permission failure part-way leaves the target cut short, and a concurrent
reader can see a half-written file at any time. `write_atomic` is the one call
for "replace this file safely". Every reader and every crash sees either the
**old complete file** or the **new complete file**:

```mix
write_atomic("/etc/myapp/config.json", json_encode($cfg, true))
write_atomic("/srv/state.db", $bytes, {durability: "full"})
write_atomic("/home/u/.ssh/authorized_keys", $keys, {mode: 0o600})
```

1. It claims a hidden temp name beside the target, `.NAME.mixtmp-…`, with
   `O_EXCL`, so it never follows a planted symlink. Being in the same
   directory keeps the final rename on one filesystem.
2. It writes all the bytes to the temp and, if asked, `fsync`s it.
3. It `rename`s the temp over the target. That is the atomic step.

**Any failure before the rename removes the temp and leaves the target exactly
as it was.** That covers a short write, `ENOSPC`, a failed sync and a failed
rename. If the process is *killed* mid-write, nothing can run to clean up. The
target is still intact, but a stale `.NAME.mixtmp-*` file may be left beside
it, and it is safe to delete.

Durability is explicit, and the default claims none it did not request:

| `durability` | what is done | after a power loss or kernel crash |
|---|---|---|
| `"none"` (default) | temp, write, rename | no promise: the data may still be in the page cache |
| `"file"` | `fsync` the temp before the rename | old complete file or new complete file |
| `"full"` | `"file"`, then `fsync` the directory after the rename | the new file, once the call has returned |

`"none"` is still fully atomic against readers and against the *process*
dying. Only the machine dying can lose the new content. With `"full"`, a
failed directory sync raises even though the new file is already in place.
It is the one failure that happens *after* the replace, so it has its own
code, `WRITE_NOT_DURABLE`, with `$err.details.replaced == true`. Every other
failure leaves the target untouched. A gate must never "roll back" on
`WRITE_NOT_DURABLE`, because the new content is already the file. The
details also carry `directory`. The same error covers a directory you may
write and search but not read, mode `0300`: `write_atomic` works there at any
level, but such a directory cannot be fsynced, so `"full"` reports that
instead of claiming durability.

Other rules:

- **data** must be a string, bytes or a buffer. Nothing else is coerced. A
  wrong value written atomically is still a wrong value.
- **Mode.** An existing target keeps its permission bits, including
  setuid/setgid. A new file gets `write_file`'s `0o666 & ~umask`. `mode:`
  (octal number or string, as for `chmod`) sets it exactly, not masked by the
  umask. The mode is applied after the data is written, so the kernel's
  rule that a write clears setuid does not strip a requested setuid bit.
- **Access ACL.** An existing target's POSIX access ACL is copied onto the
  new file exactly. Copying only the mode bits would widen access. For example,
  a file with `group::---` and a named-user entry has its group bits showing
  the ACL mask, and a plain file with those bits would grant the whole owning
  group that access. If the ACL cannot be set, the call raises and leaves the
  target untouched. If the old file had no ACL, one inherited from the
  directory's default ACL is removed, so the replacement matches the original.
  Owner, mode and ACL are all read from one handle on the old file, so they
  always describe the same file. Without `/proc` mounted the ACL is read by
  path instead. If the name has been swapped in between, the call raises
  `WRITE_NOT_ATOMIC` and writes nothing.
- **Owner.** An existing target keeps its owner and group. The new file is a
  new inode, so root rewriting a user's file would otherwise hand it to root.
  If the owner cannot be kept, typically because you are not root, the call
  raises and leaves the target untouched. It never silently changes who owns
  a file.
- **It is a new inode.** The replacement is a different file that takes over
  the name, and that has consequences `write_file` does not have:
  - A **hard link** to the old file keeps the old content. Only this name
    moves to the new file.
  - A process that already has the file **open** keeps reading the old
    content. An **inotify** watch on the file itself follows the old inode;
    watch the directory for the rename instead.
  - Only the owner, mode and POSIX access ACL are carried over. **Other
    extended attributes are not**: an SELinux label is re-derived from policy
    and may differ, and `security.capability` (`setcap` file capabilities) is
    dropped. For a `setcap` binary or an SELinux-labelled `/etc` config, run
    `setcap`, `restorecon` or `chcon` after the replace, or use `write_file`,
    which keeps the inode.
- **Symlinks.** A symlink path replaces the file the link names and keeps the
  link. That is `write_file`'s behaviour, and it avoids turning the link into
  a regular file. A dangling link raises.
- **Concurrent changes.** The target's directory is opened once, at the
  start. Checking the target, creating the temp, the rename, cleanup and the
  directory fsync all happen relative to that open directory. Renaming or
  replacing the directory, or any parent, while the call runs cannot
  redirect the write elsewhere. If the resolved target has turned into a
  symlink by the time it is checked, the call raises and writes nothing. The
  final rename replaces whatever the name holds at that instant, and
  `rename` never follows the last component. So if another process swaps in
  a symlink between the check and the rename, the rename replaces the link
  itself: the last writer to the name wins, and the call never writes
  through the link.
- **max_bytes** bounds the write. If the data is larger, the call raises
  `WRITE_TOO_LARGE` before anything touches the disk.
- **Refusals.** A target that exists but is not a regular file, such as a
  directory, raises, and so does a path ending in `/`. A target that is a
  mount point, such as a bind-mounted file, cannot be replaced by `rename`,
  so it raises `WRITE_NOT_ATOMIC` and writes nothing. Use `write_file` there,
  which rewrites in place, non-atomically. Bad options raise `OPTION_INVALID`. A wrong argument type
  raises `TYPE_MISMATCH`.

```mix
write_atomic("/tmp/io/state", "v1\n")
write_atomic("/tmp/io/state", "v2\n", {durability: "file"})
print(read_file("/tmp/io/state"))
```

```text
v2
```

## Existence & type tests

```
exists(path[, opts])  -> bool   opts: {follow_symlinks: true|false}  (default true)
access(path, mode)     -> bool   mode: non-empty combination of r, w, x, f
is_dir(path)          -> bool
is_file(path)         -> bool   (regular file only — false for a dir or a dangling link)
```

```mix
print("" .. exists("/etc/hosts"))     -- true
print("" .. is_dir("/etc"))           -- true
print("" .. is_file("/etc/hosts"))    -- true
print("" .. is_file("/etc"))          -- false  (it's a dir)
print("" .. is_file("/no/such"))      -- false  (missing — no error)
```

```text
true
true
true
false
false
```

### Kernel permission checks — `access`

`access(path, mode)` asks the kernel whether this process can access a path
*right now*. `mode` is a non-empty string containing any combination of `r`,
`w`, and `x`, in any order. `f` means existence (`F_OK`): it may appear alone,
and is redundant when combined with another letter. A repeated letter, an empty
string, or any other character raises rather than turning a typo into a
permissive check.

```mix
if access(".git/hooks/pre-commit", "x") then
  print("the kernel will not refuse to execute this on permission grounds")
end

print("" .. access("/etc/hosts", "f"))       -- existence
print("" .. access("/no/such/path", "r"))    -- false, no catch needed
```

This is the sound answer to a question that `stat(path)["perm"]` cannot answer.
Mode bits are only part of the kernel's permission calculation: a POSIX ACL can
grant or deny a named user independently of what `0o755` appears to say.
`access` uses `faccessat(AT_FDCWD, path, mask, AT_EACCESS)`, so ACLs are honoured
and the check uses the process's **effective** uid/gid — the identity under which
this process would actually do the thing.

On Linux that is issued as the **`faccessat2(2)` syscall directly**, not through
the C library's `faccessat` wrapper, and the difference is not academic. The
older kernel call takes no flags, so glibc implements `AT_EACCESS` itself — and
where `faccessat2` is unavailable (glibc ≤ 2.32, or a kernel before Linux 5.8)
that emulation decides from `fstatat(2)` mode bits and, in the man page's own
words, *"does not take ACLs into account"*. That is exactly the arithmetic this
builtin exists to replace, so rather than fall back to it silently, `access`
**raises** on such a kernel. The answer is the kernel's or there is no answer. A
caller that genuinely wants mode arithmetic can read `stat(path)["perm"]` and own
that choice out loud.

That is deliberately *not* the same rule as POSIX `access(2)`, which uses the
**real** ids; some programs (git's hook lookup among them) use that older call.
The two agree except under a setuid or setgid binary, where real and effective
diverge. Mix is neither, and neither is a shell, a daemon, or a `sudo`ed
command, so predicting such a program's answer with this builtin is sound
wherever the two ids match — which is everywhere Mix normally runs, but is an
assumption worth naming rather than one the builtin can enforce.

On Linux `x` also accounts for a **`noexec` mount**, which no combination of
mode bits reveals: a 0755 file on a `noexec` filesystem answers `false`, exactly
as `execve` would. On a *directory*, `x` means search permission rather than
execute, so it does not answer "can programs be run from here" — for that, ask
about a file inside it.

Symlinks are followed deliberately: the question is whether the thing they
resolve to can be read, written, or executed. Ordinary negative answers return
`false`, including a missing path, a denied permission, a non-directory path
component, a symlink loop, an overlong path, a read-only filesystem on a write
query, a `w` query against a file currently being executed, and a `w` query
against an immutable file. Malformed input (including an interior NUL in the
path) and an unexpected syscall failure raise.

That last case is the one genuinely ambiguous errno: a seccomp filter or an LSM
that blocks the syscall itself also reports `EPERM`, and is reported here as an
ordinary "no". That is the safe direction — a caller asking "may I?" is better
served by a false than by an exception thrown at code that was only trying to
describe a file — but on a sandboxed system a blanket `false` from `access` is
worth reading as *"the question could not be put"* rather than as a fact about
the file.

The answer is a snapshot, not a lease: a mode change, an ACL change or a remount
between the check and the use invalidates it. For a step that must succeed,
attempt it inside `try`/`catch` and let the failure be authoritative; `access` is
for reporting, for choosing a branch, and for saying *why* something will not
work before trying it.

**`exists` answers two different questions and you have to pick.** By default it
**follows symlinks**, so it means *"can I open something here"* — and a dangling
link reads as **absent**. `exists(path, {follow_symlinks: false})` is the `lstat`
form: *"is there an entry at this name"*, which sees the link itself (v0.39.0;
same option name and default as `stat`).

```mix
symlink("nowhere", "/tmp/io/dangling")
print("" .. exists("/tmp/io/dangling"))                            -- false
print("" .. exists("/tmp/io/dangling", {follow_symlinks: false}))  -- true
```

```text
false
true
```

Use the default for *"is there a file I can read or run"*. Use the `lstat` form
for *"is this name free"*, *"is there something here I must not destroy"*, and
*"is there something here I must not silently ignore"* — those three all have to
see a dangling link, and the default hides it. (The same distinction, one layer
down, is why `write_new` is the right way to claim a pathname: see
[Claim the temp name before you write into it](#atomic-replace--rename).)

`realpath` canonicalises a path — it resolves every symlink and `.`/`..` to the absolute real path (like `readlink -f` / `realpath(3)`). The path **must exist**; a missing component, a symlink loop, or a non-UTF-8 resolved path returns `nil` (never an error), so the caller decides. It is the same canonicalisation `require`/`include` use for their per-path module cache. It is **normalisation only, not a race-free authorization primitive** — canonicalise-then-use is not atomic. For an exec/open safety check, operate on the **returned canonical path** (which has no symlinks left to re-traverse), not the original, so a symlink hop can't be repointed between the check and the use.

```
realpath(path)  -> string | nil   (absolute real path, or nil if unresolvable)
```

```mix
print("" .. realpath("/usr/bin/traceroute"))  -- e.g. /usr/bin/traceroute.db (Debian alt-link)
print("" .. realpath("/etc/../etc/hosts"))    -- /etc/hosts
print("" .. realpath("/no/such/path"))        -- nil  (missing — no error)
```

These never raise — they answer a question, so a missing path is simply `false`.
Use them to guard a read that *would* raise.

## Listing directories — `ls`, `glob`, `walk`

```
ls([dir])                     one level, names only (sorted; default ".")
glob(pattern)                 paths matching a glob (* ? and ** globstar)
walk(dir[, opts])             recursive list of paths under dir (sorted)
```

`ls` returns the **entry names** in a single directory, sorted, with no path
prefix. It raises on a missing or unreadable directory.

```mix
for each $e in ls("/tmp/io")
  print($e)
end
```

```text
a.txt
b.log
sub
```

`glob` matches a shell-style pattern and returns **full matching paths**, sorted.
`*` and `?` match within one path component; `**` is a globstar that descends
through zero or more directory levels. No match → an empty list (not an error).
A relative pattern starts from `.` (with no stray `./` prefix on results); an
absolute pattern starts from `/`.

```mix
-- top level only
for each $g in glob("/tmp/io/*.txt")
  print($g)
end
print("---")
-- recurse with **
for each $g in glob("/tmp/io/**/*.txt")
  print($g)
end
```

```text
/tmp/io/a.txt
---
/tmp/io/a.txt
/tmp/io/sub/c.txt
/tmp/io/sub/deep/d.txt
```

`walk` is the depth-first recursive walk. By default it returns **files only**;
the options map flips the defaults:

- `max_depth` (number, default unlimited) — nesting depth relative to `dir`; `max_depth: 0` returns only the direct children.
- `include_dirs` (bool, default `false`) — include directory entries too.
- `follow_symlinks` (bool, default `false`) — follow symlink dirs (loop-safe; the walker tracks visited inodes).
- `strict` (bool, default `false`) — raise instead of skipping what cannot be read (below).

The boolean options take a real `bool` only — `"false"`, `0`, `nil` and the
like raise `TYPE_MISMATCH` before traversal starts rather than being read as a
truthiness.

`max_depth` accepts a number or numeric string. If the option is present but
cannot be parsed as a number, `walk` raises `TYPE_MISMATCH`; it never silently
discards the limit and performs an unlimited traversal.

`walk` errors only on a **missing** top-level `dir`. Everything else is
best-effort: an unreadable directory is silently skipped — even the top-level
one (it exists, so the walk proceeds and simply finds nothing, returning `[]`) —
and so is an individual entry that fails to stat. One bad file deep in a subtree
shouldn't abort the whole walk.

A gate cannot tell "no matches" from "could not look" that way, so it passes
`strict: true`. Then the first directory that cannot be read (the top-level one
included, a `dir` that cannot even be stat'ed, or a `dir` that is a file) or
entry that cannot be stat'ed raises
`WALK_UNREADABLE`; `details.path` names it and `details.error` says why. An
entry or directory that vanished since it was listed, or a dangling symlink under
`follow_symlinks`, is still skipped: it was looked at, and nothing is there.

```
try
  $files = walk("/srv/repo", {strict: true})
catch $msg, $e
  if $e.code == "WALK_UNREADABLE" then
    die("cannot audit " .. $e.details.path)
  end
  raise($e.code, $msg, $e.details)
end
```

```mix
print("--- files only, full depth ---")
for each $p in walk("/tmp/io")
  print($p)
end
print("--- direct children, include dirs ---")
for each $p in walk("/tmp/io", {max_depth: 0, include_dirs: true})
  print($p)
end
```

```text
--- files only, full depth ---
/tmp/io/a.txt
/tmp/io/b.log
/tmp/io/sub/c.txt
/tmp/io/sub/deep/d.txt
--- direct children, include dirs ---
/tmp/io/a.txt
/tmp/io/b.log
/tmp/io/sub
```

The split: `ls` = one level / names, `glob` = pattern / full paths, `walk` =
recurse / full paths. Reach for `walk` over a hand-rolled `glob("**")` loop when
you need depth limits or directory entries.

## Creating directories — `mkdir`

`mkdir(path)` creates the directory **and any missing parents** (it is
`create_dir_all`, i.e. `mkdir -p`), and is idempotent — calling it on an existing
directory is a no-op, not an error.

```mix
mkdir("/tmp/io/a/b/c")
print("" .. is_dir("/tmp/io/a/b/c"))   -- true
mkdir("/tmp/io/a/b/c")                 -- again: fine, no error
print("idempotent ok")
```

```text
true
idempotent ok
```

`mkdir(path, {parents: false})` creates **only the final component** (plain
`create_dir`) and raises if the parent is missing. Reach for it when the parent
was placed deliberately and its disappearance is news: the recursive default
would quietly re-create it — and every level above it — so a script that checked
`is_dir($TMPDIR)` a moment earlier ends up manufacturing the very directory it
meant to refuse, and its cleanup removes only the leaf it knows about.

```mix
mkdir("/tmp/io/exists")
mkdir("/tmp/io/exists/leaf", {parents: false})     -- fine: the parent is there
print("" .. is_dir("/tmp/io/exists/leaf"))
try
  mkdir("/tmp/io/absent/leaf", {parents: false})
catch $e
  print("refused")
end
print("" .. exists("/tmp/io/absent"))              -- the parent was NOT created
```

```text
true
refused
false
```

The option map is checked strictly, because every way of misspelling a safety
switch would otherwise select the unsafe default in silence. `parents` is the
only key `mkdir` accepts and it must be a boolean; `{parent: false}` (singular)
and `{parents: "false"}` (a string, which is truthy) both raise rather than
recursing.

```mix
try
  mkdir("/tmp/io/x/y", {parent: false})
catch $e
  print("unknown key refused")
end
try
  mkdir("/tmp/io/x/y", {parents: "false"})
catch $e
  print("non-boolean refused")
end
print("" .. exists("/tmp/io/x"))                   -- neither call created it
```

```text
unknown key refused
non-boolean refused
false
```

## Advisory locks — `flock`, `funlock`

```
flock(path)                              exclusive, non-blocking
flock(path, {shared: true})              shared, non-blocking
flock(path, {wait: 2.5})                 wait for up to 2.5 seconds
flock(path, {create: false})             refuse a missing lock file
funlock(path)                            release this process's lock
```

`flock` opens the file, creating it with mode `0644` (subject to the process
umask) when it is missing, then takes a kernel advisory lock with `flock(2)`. An
exclusive lock opens the file read/write. A **shared** lock opens an existing
file **read-only**, so a read-only diagnostic can share-lock a lock file it
cannot write (root-owned, or on a read-only image). `create: false` never
creates the file: a missing one raises `LOCK_FILE_MISSING` and nothing is
written, which a diagnostic wants on a host where the lock file should already
exist. A directory raises either way. The default is
exclusive and non-blocking: `true` means acquired and `false` means another
process currently holds an incompatible lock. Contention is normal control flow,
not an exception. A positive `wait` retries without busy-spinning until the
deadline, then returns `false`; genuine open or locking failures raise.

```mix
$lock = "/tmp/deploy.lock"
if not flock($lock, {wait: 5}) then
  die "another deploy is running"
end

try
  print("deploy while the kernel owns the lock lifetime")
catch $e
  funlock($lock)
  die $e
end
funlock($lock)
```

The fd lives in a process-global registry under the file's canonical path, so it
stays open after `flock` returns and the kernel releases it automatically when
the process exits — including signal death. Calling `flock` again for the same
canonical path in the same process returns `true` without opening a second
retained fd. The first acquisition fixes shared versus exclusive mode until
`funlock`; a repeated call is idempotent, not an upgrade or downgrade — so
`flock(p)` followed by `flock(p, {shared: true})` answers `true` while the
held lock stays exclusive (the same rule applies to `fcntl_lock` below).

`funlock` returns `true` when it released a held fd and `false` when this process
held no lock for that path. The not-held case never raises.

These are **advisory** locks: every cooperating process must use `flock` on the
same file. Do not remove, rename, or replace a live lock file. A path can then
name a new inode while an older process still holds the old inode locked, letting
both processes proceed. Leave the lock file in place permanently; only acquire
and release its kernel lock.

### POSIX record locks — `fcntl_lock`, `fcntl_unlock` (v0.71.0)

```
fcntl_lock(path)                         exclusive, non-blocking
fcntl_lock(path, {shared: true, wait: 2.5, create: false})
fcntl_unlock(path)                       release this process's record lock
```

Linux keeps **two separate advisory-lock families** that never see each
other: `flock(2)` locks (above) and POSIX `fcntl(2)` record locks — the
family C/Rust daemons use for pidfiles and lock files (`F_SETLK`/`F_SETLKW`).
A Mix `flock()` cannot contend with a daemon's fcntl lock; `fcntl_lock()`
can. **Pick the family the other side of the coordination uses**; for
Mix-to-Mix locking either works, and `flock` is the established default.

The caller contract is identical to `flock`/`funlock` in every respect:
exclusive + non-blocking by default, contention returns `false`, real errors
raise, a shared lock opens an existing file read-only (a read lock needs only
read access), `create: false` refuses a missing file with `LOCK_FILE_MISSING`,
repeated acquisition in one process is idempotent-`true` by canonical
path, the fd lives in a process-global registry and the kernel cleans up on
exit, and the do-not-delete-a-live-lock-file rule applies unchanged. The
lock always covers the **whole file**.

One implementation detail worth knowing: these are *open-file-description*
locks (`F_OFD_SETLK`). They conflict with other processes' traditional
record locks exactly as required — but unlike traditional records they are
**not** dropped when this process opens and closes the same path elsewhere.
A traditional fcntl lock would be silently released by a mere `read_file`
of the locked path (POSIX drops a process's record locks when *any* fd for
the file closes); the OFD form removes that footgun.

## Copying & removing — `copy`, `copy_tree`, `remove`, `remove_dir`

```
copy(src, dst)          copy a single file; overwrites dst, preserves the source mode
copy_tree(src, dst)     recursive dir copy — files (mode kept) + symlinks (as symlinks);
                        creates dst and merges into an existing one
remove(path)            remove a file/symlink; no-op if already gone (rm -f)
remove_dir(path)        recursive remove of a dir + contents; no-op if gone (rm -rf)
```

`copy_tree` mirrors the parts of `cp -a` scripts actually need: it recreates the
tree, copies files with `std::fs::copy` (which carries the permission bits), and
recreates symlinks **as symlinks** (target verbatim — no dereference). `remove` and
`remove_dir` follow `rm -f` / `rm -rf` semantics: an already-missing path is a no-op,
not an error (so a "clear then rebuild" step needs no `exists()` pre-check), while a
real failure (a permission error, or `remove` aimed at a directory) still raises.

```mix
mkdir("/tmp/io/rc/sub")
write_file("/tmp/io/rc/a.mix", "-- alias file\n")
copy_tree("/tmp/io/rc", "/root/.rc")   -- e.g. bundling ~/.rc into an image rootfs
remove_dir("/tmp/io/rc")               -- rm -rf the staging copy
remove_dir("/tmp/io/rc")               -- again: fine, already gone
print("copied + cleaned")
```

```text
copied + cleaned
```

## Atomic replace — `rename`

```
rename(src, dst)        rename(2) — moves src onto dst within one filesystem
```

For an ordinary safe file replacement, use
[`write_atomic`](#write_atomic--replace-a-file-all-or-nothing). It is the
sequence below packaged with temp claiming, cleanup and durability levels.
`rename` remains the primitive when you need the steps yourself.

`rename` exists for the one guarantee `copy` cannot give: replacing an existing
`dst` is **atomic**. A concurrent reader — or a `git` about to `exec` a hook, or a
daemon re-reading its config — sees either the old file or the new one, never a
half-written one. That makes it the second half of the safe in-place update:
**write a temp file beside the target, `chmod` it, then `rename` it over the
target.** `write_file` alone truncates first, so a crash or a permission failure
mid-write leaves the target destroyed.

Errors surface verbatim rather than being papered over. `EXDEV` (a cross-filesystem
move) raises — that is a genuinely different operation with different failure
modes, and silently falling back to copy + remove would hand back the
non-atomicity the caller came here to avoid. A missing `src` raises `ENOENT`;
unlike `remove`, this is never a no-op, because renaming something that isn't
there is always a caller bug.

```mix
$live = "/tmp/io/hooks/pre-commit"
$tmp  = $live .. ".tmp"
write_file($tmp, "#!/bin/sh\nexec my-gate\n")
chmod($tmp, 0o755)
rename($tmp, $live)                    -- the swap is all-or-nothing
print(read_file($live))
```

```text
#!/bin/sh
exec my-gate
```

**Claim the temp name before you write into it.** A *fixed* staging name like
`pre-commit.tmp` is a pathname anyone can get to first, and `write_file` follows
a symlink sitting there — so `pre-commit.tmp -> pre-commit` turns the "safe"
temp write into a write straight through the live target, and the `rename` then
points the target at itself. `write_new` is `O_EXCL`: it fails on *any* existing
entry, including a dangling symlink, and never follows one. Use it to take the
name, and the rest of the sequence is honest.

```mix
write_new($tmp, "", 0o755)             -- refuses if anything is already there
write_file($tmp, $body)
rename($tmp, $live)
```

Also note `rename` reports the *client's* view. On NFS a client can be told the
rename failed after a server crash even though the server performed it, so
"raised" is not proof the old file survived; re-read the target if you must know.

## Durability — `fsync` (v0.117.0)

```
fsync(path)                      a file's data, or a directory's entries
fsync(dir, {recursive: true})    every file and directory beneath, then dir
```

A `rename`, `remove` or new file is atomic but not durable: after a power loss
it can be gone, or be there without the journal entry written just before it.
`fsync` asks the kernel to put it on disk and returns how many inodes it synced.
On a **file** it syncs the file's data and metadata. On a **directory** it syncs
the directory itself, which is what persists the entries created, renamed or
removed in it (sync the directory after a `rename` into it, and after a
`remove` from it). `recursive: true` syncs every regular file and directory
beneath, children first, then `dir` itself: a tree built with `copy_tree` is
durable when it returns. Inside the tree symlinks are never followed, and
symlinks and special files are not opened (their directory's sync persists the
entry); the `path` argument itself follows a symlink, as elsewhere.

`write_atomic(path, data, {durability: "full"})` already does this for one file
and its directory. `fsync` is the general form, without `sync -f`'s flush of the
whole filesystem. A failure raises `FSYNC_FAILED`; `details.path` names what
could not be synced (a missing path, an unreadable directory in the tree).

```
rename("/srv/app/.next", "/srv/app/current")
fsync("/srv/app")                                -- the rename is now durable
```

## Symbolic links — `symlink`, `read_link`

```
symlink(target, linkpath)   symlink(2) — creates linkpath pointing at target
read_link(path) -> string   readlink(2) — the target exactly as stored
```

Argument order is `symlink(2)`'s, **not** `ln`'s reading order: the target comes
first, the link to create second. `target` is stored verbatim and is neither
resolved nor validated, so a relative target resolves against the *link's own*
directory, and creating a dangling link is legal — both are usually the point.
`linkpath` must not exist (`EEXIST`); `remove` deletes a symlink itself rather
than what it points at.

`read_link` is not `realpath`. It hands back what the link literally says,
relative or dangling and unresolved; `realpath` answers "where does this land".
Auditing a link — *is this temp file secretly aimed at the file next to it?* —
needs the unresolved answer. It raises `EINVAL` on anything that is not a
symlink, so test first with `stat(path, {follow_symlinks: false})`, which is the
`lstat` form and the only way to `stat` the link rather than its target.

```mix
symlink("../elsewhere/absent", "/tmp/io/link")
print(read_link("/tmp/io/link"))
print(stat("/tmp/io/link", {follow_symlinks: false})["is_symlink"])
print(exists("/tmp/io/link"))          -- follows: a dangling link reads as absent
```

```text
../elsewhere/absent
true
false
```

That last line is the trap worth remembering: plain `exists` follows the link, so
a dangling symlink answers "nothing is here" while very much being something. Ask
the other question — `exists(path, {follow_symlinks: false})` — whenever you mean
"is this name taken" rather than "can I open this".

## Permissions & ownership — `chmod`, `chown`

```
chmod(path, mode)            mode as octal literal 0o755 or string "0755"
chown(path, uid, gid)        numeric uid/gid only; follows symlinks
chown(path, uid, gid, {follow_symlinks: false})   the link itself (lchown)
```

Native syscalls — don't `run("chmod …")`. Both follow symlinks (the mode/owner is
applied to the link's *target*, standard shell semantics). `chown` with
`{follow_symlinks: false}` changes the symlink itself, as `lchown(2)` does and
as `stat`/`exists` read it: a root script that makes links in another user's
tree can hand the links to that user too. It works on a dangling link, which
the following form cannot chown. (Linux has no `lchmod`, and a link's mode is
never used, so `chmod` has no such option.) `chmod`'s mode is the
**value** (`0o755`, range `0..=0o7777`); a number out of range or with a fraction
is rejected. `chown` takes numeric uid/gid only — no name resolution — and
requires real `Number` arguments (a bool or numeric string is refused, so
`chown(p, true, false)` can't silently become uid 1 / gid 0).

```mix
write_new("/tmp/io/f", "x\n", 0o600)
print("before: " .. stat("/tmp/io/f")["perm"])   -- 384  (0o600)
chmod("/tmp/io/f", 0o644)
print("after:  " .. stat("/tmp/io/f")["perm"])   -- 420  (0o644)
```

```text
before: 384
after:  420
```

| octal literal | decimal value (what `perm`/`mode` print) |
|---|---|
| `0o600` | 384 |
| `0o644` | 420 |
| `0o755` | 493 |

## Inspecting metadata — `stat`

`stat(path)` returns a map; `stat(path, {follow_symlinks: false})` is `lstat`
(reports the link itself). Fields (a frozen surface — scripts index into them):

| field | type | meaning |
|---|---|---|
| `uid` `gid` `nlink` `size` | number | owner / group / hard-link count / bytes |
| `mode` | number | full `st_mode` (type bits included) |
| `perm` | number | `mode & 0o7777` — round-trips into `chmod` |
| `ino` `dev` | **string** | inode / device (u64 → text, see semantics) |
| `ctime` `mtime` `atime` | number | epoch **seconds** (f64, whole-second) |
| `ctime_nsec` `mtime_nsec` `atime_nsec` | number | sub-second part, `0..=999999999` (v0.44.0) |
| `is_file` `is_dir` `is_symlink` | bool | type flags |

```mix
write_new("/tmp/io/k", "hello\n", 0o600)
$st = stat("/tmp/io/k")
print("size:  " .. $st["size"])
print("perm:  " .. $st["perm"])
print("ino:   " .. $st["ino"])           -- a STRING
print("file?: " .. ("" .. $st["is_file"]))
```

```text
size:  6
perm:  384
ino:   1909
file?: true
```

### "Did this file change?" needs the timestamp *pair*

Whole seconds cannot answer that question. A rewrite that puts *equal* bytes
back inside the same second is invisible to a content comparison (the bytes
match) **and** to an `mtime` comparison (the second matches) — so a tamper check
built on those two reads it as untouched. This is not hypothetical: a hook
installer was rewriting live git hooks on every run and the check stayed green.

Compare `(mtime, mtime_nsec)` together:

```mix
fn changed($path, $was)
  $now = stat($path)
  return $now["mtime"] != $was["mtime"] or $now["mtime_nsec"] != $was["mtime_nsec"]
end
```

The sub-second part is a **separate** field rather than one combined nanosecond
timestamp on purpose. Mix numbers are `f64`, exact for integers only up to
2^53; a nanosecond epoch passed that about 104 days after 1970, so a combined
value would silently round. Split, both halves are exact.

**The pair narrows the blind spot; it does not close it.** `mtime_nsec` reports
what the filesystem recorded, and timestamp granularity is a filesystem
property, not a guarantee — a filesystem that stores whole seconds reports `0`,
and even one that stores nanoseconds is not obliged to give two writes distinct
values.

Which field catches a change depends on *how* the writer writes:

- A writer that **replaces** the file — new file, then `rename()` over the old
  one, the way any careful writer updates a live file — gets a **new inode**.
  `ino`/`dev` catch that on their own, whether or not the timestamps are
  compared. This is the common case, and a check that compares only timestamps
  is doing less work than it looks like it is.
- A writer that rewrites **in place** keeps the inode, so `ino`/`dev` say
  nothing. If the new bytes differ, `size` or the content still show it. The
  case that needs the timestamps is the byte-identical one — same inode, same
  size, same bytes — where `(mtime, mtime_nsec)` is the field pair a caller
  normally compares, and only helps if the sub-second half is compared too when
  the rewrite lands inside one second. `ctime` moves as well; see below for what
  that is worth.

So compare identity *and* the timestamp pair; neither subsumes the other.

Both are still read-side signals, and neither survives a deliberate adversary:
`mtime` is writable — `utimensat` lets a file's owner set any value it likes,
including the previous one — so a change can be made and its evidence put back.

`ctime` is the exception worth knowing. It records when the *inode* last
changed, and no syscall accepts a caller-supplied value for it: a write marks
it, and the `utimensat` used to put `mtime` back marks it again, so the cover-up
signs itself. That is why "no `stat` field sees a byte-identical in-place
rewrite" would be wrong, and why `(ctime, ctime_nsec)` is worth comparing
alongside the `mtime` pair.

It is not proof, in two separate ways. It is a *timestamp*, so the granularity
paragraph above applies to it unchanged — a coarse filesystem, or two events
inside one tick, record the same pair for both, and an unchanged `ctime` is
therefore evidence of nothing having *been recorded*, not of nothing having
happened. And it is the *inode's* clock rather than the content's, so a `chmod`,
a `chown` or a new hard link moves it with no content change at all, while
anyone who can set the system clock or write the raw device moves it wherever
they like. Read it as tamper-*evidence* at best: a changed `ctime` says
something touched the inode, and does not say what.

A check that has to be sound needs evidence from the write side — the
writer announcing its intent before it writes, or an append-only log. A kernel
watch (`inotify`) is better than polling but is not proof either: it can miss
what happened before the watch was established, and its queue can overflow
(`IN_Q_OVERFLOW`) and drop events. Treat `stat` as the cheap first filter, not
the proof.

### The symlink mixed view

`stat` follows symlinks by default, but `is_symlink` is **always** derived from
`lstat`, so it flags the path itself regardless of the follow mode. When
following, the *other* fields describe the target while `is_symlink` flags the
link — a deliberate mixed view matching how callers reason about links:

```mix
-- /tmp/io/link.txt -> /tmp/io/target.txt (a regular file)
$lnk = stat("/tmp/io/link.txt", {follow_symlinks: false})   -- lstat
print("lstat:  is_symlink=" .. ("" .. $lnk["is_symlink"]) .. " is_file=" .. ("" .. $lnk["is_file"]))

$tgt = stat("/tmp/io/link.txt")                             -- follow
print("follow: is_symlink=" .. ("" .. $tgt["is_symlink"]) .. " is_file=" .. ("" .. $tgt["is_file"]))
```

```text
lstat:  is_symlink=true is_file=false
follow: is_symlink=true is_file=true
```

Use `ino`/`dev` straight as a dedupe-set key for a `walk` that should visit each
real file once — never `to_number()` them:

```mix
$seen = {}
for each $p in walk("/srv")
  $st = stat($p)
  $key = $st["ino"]
  if $seen[$key] == nil then
    $seen[$key] = true
    -- ... process $p once ...
  end
end
```

## File types — `mime_type` (v0.113.0)

```
mime_type(path[, {content}]) -> {mime, by, uncertain, exists, parents}
```

The type the desktop gives a file, from the freedesktop shared-mime-info
database (`globs2`, `magic`, `aliases` and `subclasses` under each
`$XDG_DATA_HOME` and `$XDG_DATA_DIRS` `mime` directory), decided by GLib's
rules, so it agrees with the file manager and `gio info`:

1. a directory or other non-regular file is its `inode/*` type, and an empty
   file is `application/x-zerosize`;
2. one glob match is the answer;
3. otherwise the content decides: a magic rule, or `text/plain` when it reads
   as text;
4. among several glob matches, a magic match of priority 80 or more wins,
   else the first glob type that is a subtype of the sniffed one.

- `by` says which: `stat`, `glob`, `magic`, `content` (empty, or text) or
  `fallback` (`application/octet-stream`).
- `parents` lists every supertype, nearest first, ending `text/plain` for
  `text/*` and `application/octet-stream` for anything but `inode/*`. Ask
  `contains($r.parents, "text/plain")` to know whether a type is text.
- `{content: false}` never opens the file: names only.
- A missing path is typed by its name, with `exists: false`; so is a file the
  script may not read, with `uncertain: true`.
- Symlinks are followed. The database is read once and again whenever one of
  its directories changes, so a newly installed application's types appear
  without a restart.

```mix
$r = mime_type("/etc/hosts")
print($r.mime .. " by " .. $r.by)
if contains($r.parents, "text/plain") then
  print("text")
end
```

One known limit: a database pattern using POSIX bracket classes (such as
`[[:alpha:]]`) is matched with Unicode's character predicates, not the
locale's tables, so a rare character can be typed differently from GIO. The
stock freedesktop database uses only plain ASCII ranges.

Not `xdg-mime query filetype`: outside GNOME and KDE that asks libmagic's
`file`, which names many types differently (a Markdown file is
`text/plain` there and `text/markdown` here).

## Path-string helpers (pure, no filesystem)

These operate purely on the path *string* — they never touch disk, so they work
on a path that doesn't exist.

```
basename(path)    filename component                ("/a/b/x.eml" -> "x.eml")
dirname(path)     directory component               ("/a/b/x.eml" -> "/a/b")
extname(path)     extension WITH the leading dot     ("/a/x.eml"   -> ".eml")
path_join(a, b)   join with the native separator     ("/a", "x")   -> "/a/x"
path_parts(path)  -> {dir, base, stem, ext}          (ext has NO dot)
```

```mix
$p = "/srv/mail/inbox/msg.2.eml"
print("basename: " .. basename($p))
print("dirname:  " .. dirname($p))
print("extname:  " .. extname($p))
print("join:     " .. path_join("/srv/mail", "new.eml"))

$pp = path_parts($p)
print("dir=" .. $pp["dir"] .. " base=" .. $pp["base"] .. " stem=" .. $pp["stem"] .. " ext=" .. $pp["ext"])
```

```text
basename: msg.2.eml
dirname:  /srv/mail/inbox
extname:  .eml
join:     /srv/mail/new.eml
dir=/srv/mail/inbox base=msg.2.eml stem=msg.2 ext=eml
```

> **`extname` keeps the dot, `path_parts.ext` drops it** — different consumers, a
> deliberate split. A path with no extension gives `""` from `extname`, and
> `basename` of a trailing-slash path returns the last real component
> (`basename("/srv/mail/")` → `"mail"`).

## Standard input — `readline`, `read_stdin`, `read_stdin_bytes`

```
readline([prompt])      read one line from stdin (trailing \n stripped); optional prompt
read_stdin()            read ALL of stdin to EOF as one string (strict UTF-8)
read_stdin_bytes([max]) read ALL of stdin to EOF as raw bytes (v0.65.0)
read_stdin_bytes(8192)  read at most 8192 bytes — same cap as read_file_bytes
```

`read_stdin` is the call for a pipe or a hook payload — it slurps the whole stream
to EOF. `readline` reads a single line and, if given a prompt argument, writes it
to stdout (flushed) first — the interactive-input path. Both read UTF-8 *text*
and both **raise** on a stream that will not decode, matching `read_file`.

`read_stdin_bytes` is the binary twin, and it is the only way to read a stream
that is not valid UTF-8:

```
$ printf '\x00\x01\xff\xfe binary' | mix -c 'print(read_stdin())'
Runtime error at line 1: read_stdin: stream did not contain valid UTF-8
$ printf '\x00\x01\xff\xfe binary' | mix -c 'print(bytes_len(read_stdin_bytes()))'
11
```

That is not an edge case for mail: 8-bit transfer encodings and legacy charsets
routinely produce bodies that never decode, which is why `read_stdin` alone left
Mix unable to be a mail filter. The cap is `read_file_bytes`'s — a non-negative
whole number, applied with `Read::take`, strictly a Number (a numeric string or
a bool is refused, not coerced) — so `read_stdin_bytes(8192)` sniffs a header
without slurping a stream of unknown size, and `read_stdin_bytes(0)` reads
nothing. **One deliberate difference:** an explicit `nil` means *no cap* here
(`read_stdin_bytes(nil)` reads everything, so `read_stdin_bytes($limit)` works
when `$limit` may be unset), whereas `read_file_bytes(path, nil)` raises. Nil-as-
absent is the convention `slice` and `bytes_to_string` already use for a trailing
optional argument.

It reads fd 0 with no decode step at all, so nothing can be substituted or lost;
pair it with [`write_stdout`](#byte-exact-output--write_stdout-write_stderr) for
a filter that is byte-exact end to end.

Until 0.33.0 an undecodable stream returned an **empty string** instead. That is
indistinguishable from EOF, and it is silent: a `pre-push` hook reading git's ref
list saw one non-UTF-8 ref name as no refs at all, iterated nothing, and exited 0
having checked nothing. Catch it with `try` if a caller genuinely wants to
continue past undecodable input.

```mix
-- echo 'piped line 1\npiped line 2' | mix script.mix
$in = read_stdin()
print("got " .. length($in) .. " chars")
print("first line: " .. split($in, "\n")[0])
```

Piped in (`printf 'piped input line 1\npiped input line 2\n' | mix -c '…'`):

```text
got 38 chars
first line: piped input line 1
```

For richer stdin handling see [strings](strings.md) (`split`, `trim`) — a common
pattern is `for each $line in split(read_stdin(), "\n")`.

## Byte-exact output — `write_stdout`, `write_stderr`

```
write_stdout(v, ...)   write to fd 1 as it is: no newline, no separator, flushed
write_stderr(v, ...)   the same, to fd 2
print_raw(v, ...)      ALIAS of write_stdout
eprint_raw(v, ...)     ALIAS of write_stderr
```

`print` always appends a newline and joins its arguments with a space, so before
0.65.0 there was no way to write **exactly these bytes and stop**. That is
disqualifying for any program whose stdout *is* the interface — dovecot's sieve
`execute :pipe :output "VAR"` captures stdout verbatim into a sieve variable, and
one trailing newline corrupts the variable parsing.

`printf` is not this. It also omits the trailing newline, but it takes a *format
template* (so `%` is significant and a literal one has to be escaped) and it
formats through a string, so it cannot carry a byte that is not valid UTF-8.
Reach for `printf` to lay out text and `write_stdout` to emit exact bytes.

**One family, one contract, four names.** `print_raw`/`eprint_raw` are aliases of
`write_stdout`/`write_stderr`, not variants: the same builtin under the spelling
that matches whichever family you are thinking in. If they ever behave
differently that is a bug, and a test pins the equality.

The contract is `print`'s, minus the newline and the separator:

- **`bytes` and `buffer` go out verbatim.** This is the one place `print` is
  actively wrong — it renders a bytes value as the `<bytes:N>` placeholder.
- **Every other value renders exactly as `print` renders it**, including a
  list as `[1, 2]` and a map as `{k: v}`. There is no stricter type rule to
  learn. (If you meant those numbers as bytes, that is
  [`bytes_from([...])`](#bytes-as-a-sequence-v0640).)
- **fd 1 and fd 2 as they are** — never a re-opened path. `write_file("/dev/stdout", $s)`
  issues an `openat("/dev/stdout", O_WRONLY|O_CREAT|O_TRUNC)` and therefore dies
  with `Permission denied` whenever fd 1 belongs to another user (a `runuser -u vmail`
  dry run, and every message under sieve). `write_stdout` opens nothing.
- **Flushed on every call.** The default stdout is line-buffered and this family
  exists to emit output with no newline in it, so an unflushed write would sit in
  the buffer past the moment the consumer reads. In a hot loop, build a
  [`buffer`](buffer.md) and write it once rather than writing per iteration.
- **It writes to the same sink `print` writes to.** For the `mix` binary that
  sink *is* the process's fd 1/2, which is the whole point. Inside an **embedder**
  that redirects output — webd rendering a response, a test harness capturing it
  — `write_stdout` goes to that redirected sink like `print` does, not around it
  to the real descriptor. There is deliberately no way to bypass the host's
  output policy; a program that must reach the process descriptor regardless is
  not a Mix script.

### A failed write RAISES — `print` included since 0.99.0

Since 0.99.0 (B9) `print`, `eprint`, `printf` and `eprintf` raise the same
write errors as this family: a dropped write reported as success was the
one failure mode an agent reading rc could not see, on every output path.
The error is catchable and code-distinguished:

| code | meaning |
|---|---|
| `IO_BROKEN_PIPE` | the consumer closed the pipe (`\| head -1`, a reader that exited) |
| `IO_WRITE_FAILED` | anything else — a full disk, a closed descriptor |

The `mix` binary does not change the process SIGPIPE disposition — Rust ignores
SIGPIPE at startup — so a closed pipe arrives as this error rather than as a
signal. That is a property of the *process*, not of the library: an **embedder**
whose host has restored the default SIGPIPE disposition would get signal 13
instead of a catchable error, because nothing in Mix asserts the disposition.

The quiet-exit idiom, when a filter should behave like `head` and stop:

```mix
try
  write_stdout($body)
catch $msg, $err
  if $err.code == "IO_BROKEN_PIPE" then
    exit(0)
  end
  raise($err.code, $msg)
end
```

### The filter, end to end

```mix
-- byte-for-byte: whatever arrives on fd 0 leaves on fd 1 unchanged
write_stdout(read_stdin_bytes())
```

```
$ printf '\x00\x01\xff\xfe mix \xc3\x28' > in.bin
$ mix -c 'write_stdout(read_stdin_bytes())' < in.bin > out.bin
$ cmp in.bin out.bin && echo identical
identical
```

`cmp`, not eyes: a lossy decode substitutes U+FFFD for each undecodable byte and
so *grows* the output — **11 bytes in, 17 out** for the input above, where
`write_stdout(read_stdin_bytes())` gives 11. A visual check will not catch that;
a byte comparison always will, and a digest taken over the 17 bytes is a digest
of a message that never arrived. Dropping a header line
before hashing a body is
[`slice`](#bytes-as-a-sequence-v0640) on the bytes, never a string round trip.

## Bytes helpers

The bytes type (`Value::Bytes`) carries raw 8-bit data without a UTF-8
round-trip. These convert to and from it (they live in the `system` category but
are the natural companions to `read_file_bytes`):

```
bytes_len(b)               byte length of a Value::Bytes buffer
string_to_bytes(s)         UTF-8 encode a string -> bytes
bytes_to_string(b)         decode bytes -> string (strict UTF-8; errors on bad byte)
bytes_to_string(b, {lossy: true})   from_utf8_lossy decode (bad bytes -> U+FFFD)
```

All three are **strict about their argument type** — `string_to_bytes` rejects a
non-string, `bytes_to_string`/`bytes_len` reject a non-bytes — so a `to_mix_string`
placeholder like `<bytes:N>` can never silently leak in. The `lossy` option is a
strict bool too: `{lossy: "true"}` or `{lossy: 1}` raises `TYPE_MISMATCH` rather
than being read as a truthiness.

```mix
$b = string_to_bytes("héllo")
print("byte length: " .. bytes_len($b))     -- 6 (é is 2 UTF-8 bytes)
print("round-trip:  " .. bytes_to_string($b))

-- sniff an ASCII header out of a non-UTF-8 head with the lossy escape hatch
$head = read_file_bytes("/tmp/io/img.bin", 4)
print("lossy: " .. length(bytes_to_string($head, {lossy: true})))
```

```text
byte length: 6
round-trip:  héllo
lossy: 4
```

Note `bytes_len` counts **bytes**, while `length` on a string counts **codepoints**
(`length("héllo")` is 5) — see [strings](strings.md) for the codepoint / byte /
grapheme split.

## bytes as a sequence (v0.64.0)

Before 0.64.0 a `bytes` value was something you could hold but not look
inside: `$b[3]` said *cannot index bytes with number*, `length($b)` said *len()
not supported for bytes*, `slice` refused it, and `for each` refused it. The only
way in was `bytes_to_string({lossy: true})`, which **destroys the very bytes you
are inspecting** — a lossy decode replaces every invalid sequence with U+FFFD, so
a digest taken afterwards is a digest of something that never arrived.

The generic sequence operations now accept `bytes` **and** `buffer`, in
byte units — four since 0.64.0, five more since 0.70.0:

```
$b[i]                      the byte at i as a NUMBER 0-255
length($b) / len($b)       byte count (same answer as bytes_len)
slice($b, start[, end])    a new value-semantic `bytes`
for each $x in $b          iterates NUMBERS 0-255
take($b, n) / drop($b, n)  first n / all-but-first n bytes (negative n from the
                           end, like the list forms) → a new `bytes` (v0.70.0)
reverse($b)                byte-wise → a new `bytes` (v0.70.0)
index_of($b, needle)       0-based BYTE offset, -1 absent — bytes_find's answer
                           through the generic name (v0.70.0)
contains($b, needle)       bool (v0.70.0)
```

`index_of` and `contains` take their needle in the `bytes_*` family's
vocabulary — bytes, buffer, string, or a single byte number 0-255 — and, like
`bytes_find`, **refuse an empty needle** on a bytes/buffer subject (an empty
needle is almost always an empty variable, and a trivially-true answer for it
is a silent wrong answer). ⚠ The vocabulary follows the **subject**, not the
needle: a bytes needle on a *string* subject is stringified to its
`<bytes:N>` placeholder and searched as that literal text — silently absent.
Searching a string for raw bytes means converting one side first
(`string_to_bytes($s)` or `bytes_to_string($needle)`). This is a deliberate divergence from the string
arms, where `contains($s, "")` remains `true`. That is the complete list of
generic operations bytes participates in — anything else (`sort`, `unique`,
`join`, …) still refuses bytes with a clean error.

The boundary rules are the list's, not new ones:

- **Negative indices count from the end.** `$b[-1]` is the last byte;
  `slice($b, -5, -1)` is the last five minus one.
- **An out-of-range `$b[i]` is `nil`, not a raise** — the same answer
  `[1,2][9]`, `"ab"[9]` and `buffer_get` already give. There is no
  bounds-check exception in Mix's indexing to be consistent with.
- **`slice` clamps and never raises**: `slice($b, -100, 100)` is the whole
  value, and a **reversed** range (`slice($b, 4, 1)`) is empty bytes, not a
  wrap-around and not an error.
- **Slicing a `buffer` returns an independent `bytes` snapshot**, never an
  alias — a later `buffer_push` cannot change a slice you already took.
- **`for each` is pinned at entry**: growing a `buffer` inside the loop body
  does not extend that loop, exactly as mutating a list inside `for each`
  does not.
- **Index-assignment is still refused** (`$b[0] = 65` → *cannot index-assign
  into bytes*). `bytes` is value-semantic; the mutable type is `buffer`, and
  the in-place write is [`buffer_set`](buffer.md).

The framing case this was built for — drop a leading header line from a raw
mail body without a lossy round-trip, so the digest is over the bytes that
actually arrived:

```mix
$framed = read_file_bytes("/tmp/io/body.raw")   -- "text:\n" .. raw 8-bit body
$body = slice($framed, 6)
print(bytes_to_hex($body))
```

### The `bytes_*` family

```
bytes_find(b, needle[, from])   0-based offset, -1 absent; `from` is signed+clamped
bytes_starts_with(b, prefix)    bool (an empty prefix is true)
bytes_ends_with(b, suffix)      bool (an empty suffix is true) (v0.70.0)
bytes_split(b, sep)             -> list of bytes
bytes_concat(a, b, ...)         1+ bytes/buffer/string -> one new bytes
bytes_from(list)                int 0-255 / string / bytes / buffer, flat-spliced
bytes_to_hex(b)                 lowercase hex, 2 chars per byte, no separator
bytes_from_hex(s)               strict decode: even length, [0-9a-fA-F] only
```

`needle`, `sep`, `prefix` and `suffix` may each be a `bytes`, a `buffer`, a
**string** (taken as its own UTF-8) or a **single byte number 0-255** — so
`bytes_split($b, 0)` splits on NUL, which no string separator could express.
The **subject** (argument 1) is always strict bytes/buffer.

**Scanning a `buffer` repeatedly? `freeze()` it first.** Every `bytes_*` call
(and every v0.70.0 generic-op arm) on a *buffer* subject snapshots the whole
buffer for the duration of the call — correct (the needle may alias the
subject), and invisible for one-shot calls, but a marching parse
(`bytes_find($buf, $sep, $cursor)` stepping through a large buffer) copies the
entire buffer at every step and turns a linear scan into O(n²) of memcpy.
The same loop over `freeze($buf)`'s value-semantic `bytes` borrows without
copying (measured ~3× on a 4 MB subject with short scans).

`bytes_find` uses `index_of`'s convention, **not** `pos`'s: 0-based, `-1` when
absent. ⚠ A bare `bytes_find(...)` in a condition is therefore backwards on both
branches (`-1` is truthy, `0` is falsy) — `mix lint` flags it as **MIX-W2305**.
Compare explicitly: `bytes_find($b, "\r\n\r\n") >= 0`. The optional `from` is
what keeps a scanning parser linear; the index it returns is **absolute** into
`$b`, never relative to `from`.

`bytes_split` follows `split`'s piece rules exactly — an absent separator yields
one whole piece, a leading or trailing separator yields an empty piece at that
end, and an empty input yields one empty piece. The single divergence is that an
**empty separator raises** rather than splitting between every byte.

`bytes_to_hex` is deliberately option-free (no uppercase flag, no separator) so
that `bytes_from_hex(bytes_to_hex($b))` is an exact round trip and a separated
form — one `join` away — can never be fed back in by mistake. `bytes_from_hex`
accepts either case but refuses whitespace, `:` and `-`: a lenient decoder would
silently accept a truncated digest.

```mix
$b = string_to_bytes("hello, world")
print(bytes_find($b, "world"))              -- 7
print(bytes_find($b, "l", 4))               -- 10 (absolute, not 6)
print(bytes_starts_with($b, "hell"))        -- true
$parts = bytes_split($b, ", ")
print(bytes_to_string($parts[1]))           -- world
print(bytes_to_hex(bytes_from([222, 173, 190, 239])))   -- deadbeef
```

### Naming: `byte_*` vs `bytes_*`

Two families, one letter apart, and they are **not duplicates**:

| prefix | subject | argument handling | members |
|---|---|---|---|
| `byte_*` | a **string** | coerced via `to_mix_string`, like `pos`/`substr` | `byte_length` `byte_pos` `byte_lastpos` `byte_index_of` |
| `bytes_*` | a **`bytes`/`buffer` value** | strict — a wrong type raises | `bytes_len` `bytes_to_string` `bytes_find` `bytes_starts_with` `bytes_ends_with` `bytes_split` `bytes_concat` `bytes_from` `bytes_to_hex` `bytes_from_hex` |

`byte_*` answers *"where is this, measured in UTF-8 bytes rather than
codepoints?"* about **text**. `bytes_*` operates on a **byte sequence**.

The pair that looks most like a duplicate, `byte_length` and `bytes_len`, is the
sharpest example of why the split matters:

```mix
$b = string_to_bytes("héllo")
print(bytes_len($b))        -- 6   the bytes
print(byte_length($b))      -- 9   the length of the string "<bytes:6>"
print(byte_length("héllo")) -- 6   the same 6, but only because the subject is text
```

`byte_length` stringifies its argument first, so on a `bytes` value it measures
the **`<bytes:N>` placeholder**. They agree on strings and disagree on
everything else. Neither is going away — the fleet runs both — and neither
should be "unified".

**Going forward:**

- A new operation on a `bytes`/`buffer` value is `bytes_<verb>` and must
  **reject** a non-bytes subject rather than stringify it.
- A new byte-offset operation on text is `byte_<verb>` and takes a string.
- Conversions use the direction in the name: `bytes_to_<x>` out of bytes,
  `bytes_from_<x>` into bytes. `string_to_bytes` predates that rule (it would be
  `bytes_from_string` today) and stays as-is.
- Never add a `byte_*` that takes bytes, or a `bytes_*` whose subject is text.

## SQLite — `sqlopen`, `sqlexec`, `sqlclose`

The io category includes an embedded SQLite client (feature-gated `sqlite`; the
`mix` binary turns it on). Handles are plain numbers:

The full reference, with modes and examples, is `mix man sqlopen`.

```
sqlopen(path)              open READ-ONLY; the file must exist -> numeric handle
sqlopen(path, "rwc")       open read-write, creating a missing file (WAL mode,
                           5s busy timeout); "rw" is the same mode
sqlexec(h, sql[, params])  run one statement            -> rows or {affected}
sqlclose(h)                close the handle (errors on an unknown handle)
```

`sqlexec` returns a **list of row maps** for anything that produces columns
(`SELECT`, row-returning `PRAGMA`s) and `{affected: n}` for a write — decided by
SQLite itself (`sqlite3_stmt_readonly`), not by keyword-sniffing the SQL, so
`REPLACE` and `WITH … INSERT` take the write path correctly. Column values map
NULL → `nil`, INTEGER/REAL → number, TEXT → string; a BLOB comes back as the
placeholder string `<blob N bytes>`, not bytes.

`params` binds `?` placeholders — a list binds positionally, a single non-list
value is one bind. Binds are **TYPED** (since 0.21): `nil` → NULL, bool →
INTEGER 0/1, whole number → INTEGER, fractional → REAL, string → TEXT, bytes →
BLOB; a list/map param is a loud error. (Before 0.21 every param was bound as
TEXT, so `nil` arrived as the 3-char string `"nil"`.) Always bind data — never
splice values into the SQL string.

```mix
$db = sqlopen("/tmp/io/t.db", "rw")
sqlexec($db, "CREATE TABLE t (id INTEGER, name TEXT, score REAL)")
print("insert: " .. json_encode(sqlexec($db, "INSERT INTO t VALUES (?, ?, ?)", [1, "alice", 2.5])))
print("rows:   " .. json_encode(sqlexec($db, "SELECT * FROM t WHERE id = ?", 1)))
sqlclose($db)
```

```text
insert: {"affected":1}
rows:   [{"id":1,"name":"alice","score":2.5}]
```

A write against a read-only (default) handle raises `attempt to write a readonly
database` — open with `"rw"` when you mean to mutate.

## When to shell out instead

The native builtins cover read/write/list/stat/perms. For an operation Mix has no
builtin for — `cp -a`, `rsync`, `tar`, `mv` across filesystems — call the real
tool via [`run`/`run_rc`](system.md) (both take an optional `{timeout: seconds}`
opts map since 0.21, so a hung copy can't wedge the script), remembering the
PATH is minimal inside `/bin/sh`, so use a full binary path:

```mix
$r = run_rc("/usr/bin/install -m 0755 /tmp/io/a.txt /tmp/io/b.txt")
if $r.rc != 0 then
  print("install failed: " .. $r.stderr)
end
```

## Retained directory roots (0.108.0)

`dir_open(path)` retains a native root directory and returns a numeric handle
owned by the evaluator. `dir_rename(handle, source, destination)` moves a
regular file or directory between relative names beneath that root, atomically
refusing an existing destination. `dir_close(handle)` closes it; evaluator
retirement also closes remaining handles.

```mix
$root = dir_open("/srv/scenes")
try
  dir_rename($root, "panel", ".recovery/panel-backup")
finally
  dir_close($root)
end
```

The destination parent must already exist. Absolute operands, dot or dotdot
components, empty components, backslashes and control characters are refused.
Root and parent resolution follows no symlinks or magic links; parents cannot
cross mounts. A final symlink or special source is refused, including a source
swapped after the initial type check. A parent moved outside the retained root
is denied by the kernel at rename time.

This requires Linux `openat2`, `renameat2` and Landlock ABI 2 with the
[disconnected-directory erratum 3 fix](https://docs.kernel.org/userspace-api/landlock.html#landlock-errata).
Unsupported kernels raise `DIR_UNSUPPORTED`; there is no unrestricted fallback.
Each rename confines a fresh worker thread; it does not confine the evaluator's
other threads. Opening and closing require FsRead; renaming requires FsWrite.

A root replaced at its original pathname before an operation raises
`DIR_ROOT_REPLACED`. That pathname check is not atomic with rename: if the root
itself moves afterwards, containment remains anchored to its retained inode.
The API does not promise that the original pathname remains unchanged, nor
does it confine other path-based filesystem builtins.

Other structured failures are `DIR_INVALID_HANDLE`, `DIR_INVALID_PATH`,
`DIR_OPEN_FAILED` and `DIR_RENAME_FAILED`. Existing destinations are never
overwritten, including dangling symlinks. Handles are local to their evaluator;
closing an unknown or already closed handle raises.

## See also

```
mix builtins io       list every io builtin with its one-line description
mix what NAME         one-line description of a single builtin (e.g. mix what stat)
mix help              the full categorized builtin reference
```

- [strings](strings.md) — codepoint vs byte vs grapheme; `split`, `trim`, `~` expansion
- [numbers](numbers.md) — why `0o755` is the mode value and `0755` is a lex error
- [running-commands](system.md) — `run`/`run_rc`/`run_stream` for shelling out
- [data](data.md) — `json_parse`, `load_data`, `data_encode` for structured files
- [modules](functions.md) — `source` / `include` for loading `.mix` code (vs `load_data` for inert data)
- [capabilities](capabilities.md) — the FsRead/FsWrite gating an embedder can apply to these builtins
- [builtins index](builtins.md) · [mix repo](https://github.com/markc/mixos)

---

<!-- page: https://mixos.dev/mix/job-control/ (source: https://mixos.dev/mix/job-control.md) -->

# Interactive job control

Available in Mix 0.84.0.

Interactive Mix shell commands use one process group per job, including all
pipeline stages. The shell transfers its controlling terminal to foreground
jobs and reclaims it on completion or suspension. `jobs` lists tracked jobs;
`fg N` foregrounds and continues job N; `bg N` continues it without terminal
ownership. Omitting N selects the most recent live job. A background pipeline
returns to the prompt after launch, without waiting for its stages to finish.
`jobs` includes a session-local launch command ID allocated before spawning,
distinct from its job-table ID, and displays arguments after glob expansion.
The `&` notification prints the last pipeline member's PID.

Job management is selected by the interactive entry point, and requires tty
stdin plus a controlling terminal. Setup errors produce one warning and
start the shell with noninteractive execution policy. Foreground admission
is bounded if an orphaned process group cannot stop. The shutdown mode
snapshot is seeded after cold-start terminal repair, before the monitor
starts handling HUP. Declined admission does not take the parent's terminal.
Scripts, `-c` (including SSH commands),
serve mode, redirected stdin and sessions without a controlling terminal
retain their noninteractive launch policy. Captured `run_argv` and
`run_pipeline` retain their separate capture/cancellation process groups.
Noninteractive `a | b &` still waits for upstream `a` before returning;
changing that legacy behaviour is deferred by design. Each managed command
also pays for a fork and an extra exec of the Mix trampoline before target
exec; pipelines pay that overhead per stage.
The shell's job-control signal handlers reset on exec. SIGTTOU is blocked
only around terminal handoff and restoration, so captured children do not
inherit shell-only ignored signals or a handoff-time signal mask.

Sourced shell input in an interactive shell shares its job controller. A
stopped foreground command inside source currently waits for external
continuation: returning to a restricted prompt while preserving evaluation
requires the later async host seam. `run_stream` and evaluator-owned legacy
shell/substitution paths are not integrated in this round. Bus publication,
remote admission and request cancellation are separate stages.
During an unmanaged inherited-stdio wait, Ctrl+Z stops Mix itself with its
child so an outer shell can `fg` the group. The shell suppresses SIGTSTP
only while a managed job holds the foreground terminal. A restricted
job-management prompt for suspended evaluation remains deferred.
SIGTSTP and SIGTTIN use an atomic one-shot disposition reset and reinstall
the known handler after resume. SIGTTIN always takes the default stop path,
so background terminal reads stop the shell rather than spinning on EINTR.
The managed-foreground flag changes only after successful terminal transfers;
a failed reclaim leaves it set.

From Mix 0.109.2, a foreground job reaped during SIGHUP shutdown cannot
return to another prompt. The evaluator waits for the job monitor's exit
instead of re-entering the editor and overwriting restored terminal modes.
The monitor owns the final restoration, owned-child sweep and exit status 129.

On normal shell exit or SIGHUP, Mix sends HUP followed by CONT to its owned
live jobs and allows 500 ms for exit/reaping. Survivors are reported; there
is no forced-kill escalation or guarantee about deliberately detached
descendants. Foreground terminal modes are restored even if a child exits
leaving raw mode enabled. Stopped jobs retain their own modes for `fg`.
Fresh jobs that exit normally retain cooked-mode changes (ICANON and ISIG still enabled), so
commands such as `stty tostop` remain effective. Stops, signal exits and raw
mode leakage restore the saved shell baseline. A resumed stopped job also
restores that baseline when it completes. Mix cannot infer whether an
arbitrary cooked-mode change was deliberate; this is the explicit policy.

The launch barrier runs in a private Mix trampoline **after** its first exec.
It executes `/proc/self/exe`, so open shells keep launching commands after
an installation replaces or unlinks their original executable. The fleet is
Linux; if `/proc/self/exe` is absent, or on another platform, launches fall
back to the executable path resolved at interactive admission. That fallback
restores only pre-replacement behaviour, not the unlink guarantee.
This lets Rust's spawn acknowledgement complete before the barrier waits.
Only after all children share their job group and the foreground terminal
has transferred does Mix release target execution. A second close-on-exec
pipe reports target-exec failures and one-byte trampoline failure reasons.
Acknowledgement waits observe member stops and have a 30-second deadline,
used only as a pathological-wedge backstop so cold or network-paged binaries
have time to launch. A target that stops itself before acknowledgement is
aborted deliberately: preserving that pre-ack job would risk wedging the
shell. This trades that narrow self-stop case for a recoverable prompt.
Failed launches reclaim the terminal first, send TERM/CONT, allow 500 ms,
then send KILL/CONT and allow another 500 ms. Survivors are reported and
remain registered for eventual reaping; an uninterruptible child cannot
hold the prompt indefinitely.
The survivor diagnostic in `abort_launch` is deliberately printed under the
jobs-state lock; this is accepted because the terminal has already been
reclaimed before abort cleanup.

The process monitor is the sole consumer of registered child statuses,
including stopped/continued states. SIGCHLD wakes it independently of REPL
input or evaluator progress. It never waits for arbitrary child PIDs.
`process_alive(pid)` requires a positive whole-number PID. It may reap an
exited unmanaged child (including a legacy `spawn` child), but only probes
controller-owned job PIDs with signal 0. Registered native-task PIDs share
that no-reap ownership seam from Mix 0.109.1, including pending cleanup after
an Unknown report. A managed zombie can briefly report alive until its owner
reaps it; the builtin never steals its status after registration. Task admission
is published after registration; this does not claim protection before the
task's initial exec.
The internal no-reap markers are reference counted so retirement after a
numeric PID is reused cannot erase a newer owner's registration. Each owner
balances its own registration; this does not prevent kernel PID reuse.
Audio-watch cleanup retires its marker exactly once: the worker or destructor
that takes and reaps the child owns that retirement.
Signal 0 returning `EPERM` counts as alive, including for another user's
process. This reports existence, not permission to signal that process.

---

<!-- page: https://mixos.dev/mix/keywords/ (source: https://mixos.dev/mix/keywords.md) -->

# Reserved words

Mix's keyword lexemes, held to the lexer by
`cargo test -p mix keyword_set_matches_lexer` (the lib's
`KEYWORDS` list and the lexer match arms must agree, and
`cargo test -p system --test man_pages` holds this table to the same
set). Since 0.21 the old reserved-word footgun is retired: a keyword is
accepted anywhere it is unambiguously a **name** (bare map keys, `.field`
access, strict-data keys, `send` kwargs, `parse … with` delimiters) — see
*Keywords as names* below. What remains reserved: a keyword cannot be a
**function name** or fill any other bare-identifier slot.

## The full set

The lexer reserves **48 words** across **47 token kinds** (`fn` and
`function` share one token):

| Group | Lexemes |
|---|---|
| Conditionals & matching | `if` `then` `else` `elif` `end` `select` `when` `otherwise` |
| Loops | `for` `each` `in` `to` `step` `while` `loop` `break` `continue` `label` — plus the legacy terminators `next` (for) and `done` (while/loop/on) |
| Functions | `function` `fn` `return` |
| Errors | `try` `catch` `finally` `die` |
| Template parsing | `parse` `with` |
| Bus messaging | `send` `address` `emit` `on` |
| Output | `print` `eprint` |
| Shell & loading | `export` `alias` `source` `include` `sh` |
| Operators & literals | `and` `or` `not` `eq` `ne` `true` `false` `nil` |

`mix keywords` prints the complete set and `mix what NAME` resolves every
one — no "core list" subset remains. All of them are equally reserved: each
fails identically as an identifier
(`function step($x)` → `Parse error … expected identifier, got Step`).

## What is (and isn't) restricted

- **Function names** — no keyword may name a function: `function step(...)`, `fn parse(...)`, even `function eq(...)` are parse errors. Pick another name (`phase`, not `step`).
- **Other bare-identifier slots** — same rule: a loop label must be a plain identifier (`while true label outer` works, `label to` is a parse error).
- **`$`-sigil variables are unaffected.** The sigil is its own namespace — the lexer reads the name after `$` raw, so `$to = 1`, `$step = 5`, `$if = 1`, and even `$fn = 1` all work, as do keyword-named parameters (`function f($to)`).
- **Contextual barewords are not reserved** — e.g. `async` (from `on <cmd> async … end`) is a valid function name.
- **Builtins are a separate rule, not keywords.** Defining a user function with a builtin's name is accepted without error, but calls dispatch to the builtin — the user function is silently unreachable (`function trim($x) … end` then `trim(" a ")` still runs the builtin).

## Keywords as names (0.21+)

A keyword is accepted wherever it is unambiguously a name:

```mix
$m = {label: 1, to: "x", on: true, parse: 2}   -- bare map keys
print($m.to)                                    -- field access -> x
$m.label = 5                                    -- field assignment
$v = data_parse("{to: 1, on: true}")            -- strict-data keys, unquoted
send maild mailbox.move to=$dest                -- send/emit/address kwargs
send ced ced.select anchor=0                    -- dotted Bus verb segments (0.96.2)
on edit.select; reply("ok"); end                -- ... and `on` handler names
parse $s with $a to $b                          -- literal delimiter word
```

- **`parse … with` exception:** the block/branch terminator set — `end` `else` `catch` `finally` `when` `otherwise` `done` `next` — still ends an inline `parse` statement, so those eight can't be delimiter words.
- **The one name exception is `fn`:** it lexes to the same token as `function`, so the original spelling is unrecoverable. `{fn: 1}` and `$m.fn` are parse errors (`expected identifier, got Function`) — use a quoted key `{"fn": 1}` and index access `$m["fn"]`.
- The operator lexemes `eq`/`ne` also work as bare keys and fields (`{eq: 1}`, `$m.eq`).
- Grammar adjacency holds: `for $i = $m.to to 7` parses — dot-field consumption never crosses the following keyword.

Most keywords are covered in [syntax](syntax.md),
[control flow](control-flow.md), [functions](functions.md),
[operators](operators.md), [errors](errors.md), [Bus messaging](bus.md) and
[data](data.md) (strict-data keys).

## See also

- [syntax](syntax.md) · [functions](functions.md) · [builtins index](builtins.md) · `mix keywords`

---

<!-- page: https://mixos.dev/mix/lib/ (source: https://mixos.dev/mix/lib/README.md) -->

# Mix language library

`mix` is the embeddable Rust implementation of the Mix language at
[`libs/mix`](https://github.com/markc/mixos/tree/main/libs/mix). It tokenises,
parses, analyses and evaluates Mix source, exposes the Mix value and error
models, and supplies host interfaces for Bus and other mediated services.
Bus-facing behaviour enters through injected traits, so embedders can use
the evaluator without moving protocol or daemon dependencies into this crate.

The Cargo package and Rust library are both named `mix`. The shell is the
separate `mix-shell` library, and the `system` package builds its executable.

## Synopsis

```rust
use mix::{MixResult, run_capturing};

async fn evaluate() -> MixResult<()> {
    let (_value, stdout, stderr) =
        run_capturing("print(1 + 2)\n").await?;

    assert_eq!(stdout, "3\n");
    assert!(stderr.is_empty());
    Ok(())
}
```

For strict Mix data:

```rust
use mix::{MixResult, parse_data};

fn load_data() -> MixResult<String> {
    let value = parse_data(r#"{service: "alpha", retries: 3}"#)?;
    value.to_mix_data_string()
}
```

## Entry points

| Item | Purpose |
|---|---|
| `run(source)` | Tokenises, parses, and evaluates Mix source with a new default `Evaluator`. |
| `run_capturing(source)` | Evaluates source and returns the result value plus captured stdout and stderr. |
| `parse_data(source)` | Parses only the literal-data subset and returns a `Value`. |
| `parse_data_file(path)` | Reads a Mix data file and applies `parse_data`. |
| `Lexer::tokenize` | Converts source text into spanned tokens. |
| `Parser::parse_program` | Converts tokens into a statement AST. |
| `Parser::parse_data` | Parses tokens under strict-data rules. |
| `analyzer::analyze` | Produces conservative semantic diagnostics and a capability inventory. |
| `Evaluator::execute` | Executes parsed statements in a configured evaluator. |

`parse_data` accepts scalar literals, lists, maps, and nested combinations. It rejects variable reads, calls, messaging, shell execution, interpolation, control flow, and arithmetic with `MixError::StrictDataViolation`.

`Value::to_mix_data_string` and `Value::to_mix_data_string_pretty` emit strict-data text that can be parsed again. Human-oriented `Value::write_mix` output is a separate format and is not the strict-data round-trip path.

## Evaluator

`Evaluator` is the configurable interpreter host. `Evaluator::new` uses normal process output; `Evaluator::with_output` accepts separate `Write` sinks. `SharedBuf` provides an in-memory sink for captured bytes.

The evaluator supports:

- async native extensions through `ExtFn`, `sync_ext`, and `Evaluator::register`;
- global injection and lookup through `set_global` and `get_global`;
- source identity, tracing, usage statistics, and prelude loading;
- compatible or strict function arity through `ArityMode`;
- recursion, wall-clock, list, map, and string limits through `EvalLimits`;
- builtin authority checks through `CapabilityPolicy`;
- Bus, database, JMAP, delegated Bus-call, shell, and serve-runtime host traits;
- direct event dispatch and an incoming Bus event pump.

The default capability policy is permissive. `CategoryAllowList` allows pure builtins plus selected `CapabilityClass` values: `fs-read`, `fs-write`, `network`, `process`, `env`, `db`, `jmap`, and `bus`.

The capability policy is an in-process robustness boundary for trusted embedded scripts. It is not process isolation for untrusted code.

`EvalLimits` checks wall-clock time at statement polls. A single blocking builtin cannot be interrupted in the middle of its blocking operation.

## Host seams

`BusHandler` connects language-level messaging to a host. It covers request/reply sends, fire-and-forget emits, port checks, incoming events, service registration, topic subscription, correlated replies, and reconnect requests.

`BusCallHandler` backs the scoped `bus_call(verb, args)` builtin. The host chooses the reachable verbs and supplies trusted delegation context; the script supplies only the verb and arguments.

`DbHandler` backs `db_query` and `db_exec` with positional bind values. Queries return lists of row maps. Executions return a map containing affected-row and last-insert information.

`JmapHandler` backs JMAP method batches and blob uploads without exposing network credentials or an arbitrary destination to the script.

`ShellHandler` classifies, validates, and executes shell lines when a host enables mixed `source` handling. Without a registered handler, sourced files retain strict Mix semantics.

`ServeRuntime` handles runtime-reserved Bus verbs before author-defined handlers. It returns `ReservedOutcome` values containing a Bus return code, response body, and graceful-quit flag.

The evaluator and its boxed host futures use single-threaded `Rc` and `RefCell` state. Host implementations are therefore not required to return `Send` futures.

## Values and errors

`Value` represents strings, numbers, booleans, lists, maps, functions, raw bytes, mutable byte buffers, and `nil`. Lists, maps, and raw bytes use reference-counted copy-on-write storage. Buffers use shared reference semantics, so mutations are visible through aliases.

`MixError` covers lexing, parsing, strict-data, and runtime failures. `MixResult<T>` is the crate result alias. Structured runtime errors use stable codes, optional details, source spans, and traceback frames through `ErrorInfo`.

`IndexMap` is re-exported so embedders can construct the ordered map used by `Value::Map` without coupling to a separate `indexmap` version.

## Builtin discovery and policy

`builtins` contains the builtin registry and dispatch implementation. `builtins_hof` contains async higher-order builtins that can call back into Mix functions.

Every builtin has a `BuiltinInfo` and `BuiltinContract`. The contract records arguments, return shape, effect flags, operational-failure behaviour, conditional capabilities, and any non-contiguous accepted arities. `BuiltinInfo::signature` derives a human-readable signature from this metadata.

`capability_category`, `conditional_capabilities`, `conditional_cap_engaged`, and `builtin_info_of` expose the registry to embedders. `CategoryAllowList` is the supplied class-based policy.

## Modules

| Module | Surface |
|---|---|
| `analyzer` | Semantic diagnostics, analyzer configuration, and script capability inventory. |
| `ast` | Expression, statement, function-body, operator, and assignment-path nodes. |
| `builtin_info` | Builtin metadata, contracts, type shapes, effects, and signature rendering. |
| `builtins` | Core builtin dispatch, metadata tables, capability classes, and helpers. |
| `builtins_hof` | Higher-order builtin registry with evaluator callbacks. |
| `error` | Source spans, structured error information, traceback frames, and `MixError`. |
| `evaluator` | Interpreter, limits, extensions, host traits, event handling, and output capture. |
| `interrupt` | Process-wide SIGINT cooperation for evaluator and blocking builtin polling. |
| `lexer` | Source tokenizer. |
| `parser` | Program and strict-data parser. |
| `scope` | Variables, functions, call frames, and scope storage. |
| `stats` | Session and language-usage counters. |
| `token` | Tokens, spanned tokens, and interpolated string parts. |
| `value` | Runtime value representation and Mix data serialisation. |
| `json` | JSON conversion when the `json` feature is enabled. |
| `jq` | Embedded jq-compatible filtering when the `json` feature is enabled. |
| `serde_de` | Serde deserialisation from `Value` when the `serde` feature is enabled. |
| `serde_ser` | Serde serialisation to `Value` and `.conf.mix` text when `serde` is enabled. |

## Cargo features

The default feature set is empty. Tokio remains an unconditional dependency because evaluator task, synchronisation, timer, and macro APIs are part of the core implementation.

| Feature | Adds |
|---|---|
| `default` | No optional features. |
| `json` | JSON conversion, JSON and JSONL builtins, jq filtering, and JSON-backed stats helpers. |
| `regex` | `re_match`, `re_find`, `re_replace`, and `re_split` (subject first); without it `grep_lines` falls back to a per-line substring test. The pattern-first regex_* names were deleted in 0.73.0. |
| `markdown` | Safe CommonMark and GFM rendering through `markdown`; raw HTML is escaped and dangerous URL schemes are neutralised. |
| `toml` | `toml_parse` and `toml_encode`. |
| `serde` | Serde `Deserializer` and `Serializer` bridges for `Value` and strict `.conf.mix` text. |
| `datetime` | Date parsing and formatting, ISO timestamps, duration formatting, and relative time. |
| `url` | Structured URL parsing through `url_parse`. |
| `crypto` | Base64, BLAKE3, SHA-256, HMAC-SHA-256, constant-time comparison, file hashing, and UUID generation. |
| `http` | HTTP GET, POST, and general request builtins with web roots and optional PEM CA loading. |
| `sqlite` | Direct SQLite open, execute, and close builtins. |
| `tokio-sleep` | Backwards-compatible feature alias; it adds no dependency or code gate. |
| `dkim` | RSA-2048 and Ed25519 DKIM key generation plus DNS TXT record text. |
| `datastar` | Datastar element patches, signal patches, and SSE serialisation; also enables `json`. |
| `xml` | Strict XML parsing in simple or full-fidelity tree mode. It is not an HTML parser. |

## Analysis

The semantic analyzer sits between parsing and evaluation and can be used without the command-line frontend. It reports definitely undefined variables and callables, arity mismatches, duplicate declarations, unreachable statements, discarded must-use results, and statically resolvable `require` failures.

`AnalyzerConfig` declares host-provided globals and functions. `Analysis` returns diagnostics plus the capability classes used by the script. The analyzer favours very low false-positive rates for dynamic language constructs.

## Testing support

The crate contains unit and integration coverage for parsing, evaluation, strict data, limits, capabilities, host seams, structured errors, and optional builtins.

The nested `fuzz` workspace supplies `fuzz_lex` and `fuzz_parse` libFuzzer targets. It runs on demand with a nightly Rust toolchain and is not part of the parent workspace's normal test gate.

## Package limits

This package defines no binary target, command-line subcommands, command-line configuration, daemon process, or standalone configuration loader. Those surfaces belong to hosts that embed `mixos_mix`.

---

<!-- page: https://mixos.dev/mix/lint/ (source: https://mixos.dev/mix/lint.md) -->

# mix lint — semantic analysis

`mix --check` is a syntax check: it lexes and parses, nothing more. It happily
passes a script that reads an undefined variable, calls a function that exists
nowhere, or hands `substr` one argument. `mix lint` (0.29.0) is the semantic
layer: it builds the scope universe, resolves every call against the builtin
contract metadata and the file's own definitions, and reports machine-readable
diagnostics with **stable codes** — designed for an agent to consume without
parsing prose, and biased hard toward zero false positives on Mix's dynamic
seams.

```text
mix lint [--json | --data] [--deny-warnings] [--require-version] [--fix]
         [--allow-global NAME]... [--allow-function NAME]...
         FILE...
```

- Exit codes: `0` no errors (warnings allowed unless `--deny-warnings`); `1` one or more errors, or any warning under `--deny-warnings`; `2` invalid usage, unreadable input, or internal failure. **Notes never affect the exit code** — a file whose only findings are notes exits `0` even under `--deny-warnings` (0.63.0; pinned by CLI tests, because `--deny-warnings` is a live fleet deploy gate).
- Diagnostics go to **stdout**; CLI errors go to **stderr**. `--deny-warnings` changes only the exit decision, never a severity.
- `--require-version` (0.95.0) reports `MIX-D3016` (a script with no `-- version:` header) as a **warning** instead of a note — the one flag that moves a severity, and only for that code. Pair it with `--deny-warnings` to make a missing header fail a gate.
- `-` reads stdin (at most once); relative `require()` paths from stdin resolve against the current directory.
- `--allow-global NAME` / `--allow-function NAME` declare names an embedder or environment provides (repeatable). A file can declare its own with a [`-- lint: globals` pragma](#in-file-pragmas-01170).
- `--fix` (0.117.0) applies each finding's **quick fix** to the file and lints the result again, so the report shows what is left; it prints `applied N fix(es)` to stderr. Only mechanical rewrites carry one (today `MIX-W2312`, bareword `null` → `nil`), and each edit is checked against the text at its position before it is made. Stdin is never rewritten.
- The `mix` binary's shell extensions (`ai`, `ai_diagnose`, `context`) are known callables: calling one is never `MIX-E1102`, and defining a function with one of those names is `MIX-W2313`.
- If script parsing fails, lint tries the same strict-data parser as `load_data()`.
  A successful fallback exits cleanly and prints `validated as strict data (not
  as a script)`. If both parsers fail, an explicit top-level `key:` shape (or a
  conventional strict-data suffix as a tiebreak) gets the data error;
  otherwise the original script error is preserved.

## The rules (v1)

Codes are permanent — never reused, never repurposed — from three
namespaces: `MIX-E1xxx` errors, `MIX-W2xxx` warnings (born warnings), and
`MIX-D3xxx` **deprecations and release-transition advisories** (0.63.0) —
a severity-*independent* namespace: a deprecation starts at severity
`note` and may later be promoted to `warning` with the **code unchanged**
(only the wire `severity` field moves), so tooling that suppresses or
greps by code keeps working across the promotion.

### Notes (severity `note`, 0.63.0)

Rendered with a `note:` prefix, sorted after errors and warnings, counted
in their own summary field, and **never** gating. Current D-codes:

| code | what it flags |
|---|---|
| `MIX-D3001`–`D3005` | the five pattern-first legacy names `regex_match regex_find regex_replace regex_split grep` — use the subject-first `re_match re_find re_replace re_split grep_lines`. **The legacy names were DELETED in release B (0.73.0)** after the fleet-wide inventory read zero, so a surviving call also gets `MIX-E1102` (undefined function) and fails at runtime; these notes stay as the pointer to the replacement |
| ~~`MIX-D3006`~~ | **RETIRED in 0.68.0.** Watch note for the map-binding flip, which has landed: a two-variable loop over a MAP now binds (key, value). Code permanently spent, never reused |
| ~~`MIX-D3007`~~ | **RETIRED in 0.68.0.** Watch note for the equality flip, which has landed: `==`/`!=` with a map or list on **both** sides now raises `TYPE_ERROR` naming `deep_eq`. The shipped rule is narrower than this note's "either operand" wording — a collection compared to a *scalar* still answers, so `$m[$k] == nil` keeps working. Code permanently spent, never reused |
| `MIX-D3012` | an **`ssh_mix` body that could not be analysed** (0.69.0) — a non-literal second argument (a variable, a concatenation, an interpolated string, a `read_file`), or a literal that does not parse as Mix. Says so explicitly rather than passing silently, because an unreadable body counted as clean is exactly how an inventory reads zero while live sites exist |
| `MIX-D3008`–`D3011` | the REXX-style `pos lastpos byte_pos byte_lastpos` family, declared legacy — with a sharper message when composed as `substr(.., pos(..))` in one expression (the 1-based/0-based off-by-one). These stay notes until their own fleet count reads zero; they are NOT deleted in release B |
| `MIX-D3014` | **`write_file()` of an unchecked `replace()` result** (0.90.0) — the edit-a-file idiom with nothing anywhere in the file that could have noticed the needle was absent. `replace()` returns the subject unchanged when it misses, so the input is written straight back and the run reports success. Use `replace_must()`/`re_replace_must()`, which raise `NEEDLE_ABSENT` (and assert the site count with `{count: n}`). Conservative: only a `write_file` whose written value is a replace call or a variable the same straight-line block assigned from one, and any guard spelling anywhere in the file (`contains`, `pos`, `index_of`, `count_of`, `re_match`, a `_must` twin) silences it for the whole file |
| `MIX-D3013` | a **hand-rolled padding loop** (0.74.0) — `while len($o) < $n … $o = $o .. " "` — pointing at `lpad`/`rpad` (and the display-cell `lpad_w`/`rpad_w`). Four independent sessions wrote this loop while the builtins sat in the binary; the note is the discoverability fix that reaches the author at authoring time. Narrow by design: only a `<`/`<=` comparison of `len`/`length` of the same variable the body self-appends a string literal to |
| `MIX-D3016` | a **script with no `-- version: X.Y.Z` header** in its leading comment region (within the first 32 lines) (0.95.0), so [`mix SCRIPT --version`](invocation.md#--version-for-scripts) and `script_version()` can only say `unversioned` — every binary and every Mix script answers `--version` (Mark, 2026-09-25). Emitted by the lint driver, only for files **run as scripts**, decided by a deliberately simple heuristic over the path *as given*, in this order: (1) line 1 is a `#!` shebang — a script; (2) a `lib`, `_lib`, `tests` or `test` directory component — never reported: a library is loaded by `require`, and a test script must stay header-less, because a header would make it the entry script whose record `script_version()` returns; (3) a `bin`, `_bin`, `scripts` or `build` directory component — a script; (4) a serve citizen — a top-level `on <verb>` handler at column 0, or `--serve` mentioned in the leading comment region. `mix lint deploy.mix` from inside `_bin/` has no directory component, so lint from the repo root. Known false positive, Wontfix: a library under an absolute `/…/bin/…` path with no `lib` component is reported. The mirror holds too: any `/…/lib/…` or `/…/tests/…` ancestor in an absolute path exempts a script beneath it. Only the leading comment region counts as the header (see [invocation](invocation.md#--version-for-scripts)), so a `-- version:` inside a heredoc does not satisfy it. A header line whose value is not `X.Y.Z` is reported on its own line, since the runtime treats it as absent. A note by default; `--require-version` makes it a warning, code unchanged |
| `MIX-D3017` | an **unprovable variable read inside an `ssh_mix` body with dynamic bindings** — the name is bound nowhere in the body, but the call's opts are unreadable so `bindings`/`env` may supply it at runtime, and it is NOT an error. Fires only when the name is one edit away from something the body DOES bind (a parameter or local), where the typo is the likelier explanation: `'$pott' … did you mean '$port'?` One edit is one edit — an adjacent transposition (`$prot`) is TWO under plain Levenshtein, and the short-name budget stays at one so unrelated dynamic bindings keep their silence. A name with no near neighbour is an ordinary dynamic binding and stays silent |
| `MIX-D3018` | **`ssh_mix` opts are not a statically readable map** — the injected names are unknown, so undefined-**variable** checks stand down for that body (dynamic bindings may supply any free DATA name). The boundary is split, not blanket: undefined-**function** checks still run (strict-data bindings cannot create a callable, so a function name the body does not define is undefined no matter what the opts hold). A variable bound exactly once to a map literal IS resolved (`$o = {bindings: {…}}`), so the fleet opts-variable shape keeps full checks |
| `MIX-D3019` | a **`-- lint:` suppression that matches nothing** (0.117.0) — an `ignore CODE` whose next statement no longer reports CODE, or an `ignore-file CODE` in a file that reports none. Reported at the pragma's line so stale suppressions get deleted. See [in-file pragmas](#in-file-pragmas-01170) |
| `MIX-D3015` | a **bare `$NAME` in a double-quoted string** (0.90.0) where `NAME` is bound in the same file. Double quotes interpolate `${NAME}` only; the bare form is literal BY DESIGN, which is the opposite of bash — four occurrences in one file passed lint and all four failed at runtime. `\$NAME` and a single-quoted `'…'` string are the two clean spellings and neither is reported. The lexer drops the whole batch for a MULTI-LINE string and for one whose spelling contains `\"`: both mark NESTED source (an `ssh_mix` body, a `mix -c` program), where a bare `$rc` is the inner program's variable and correctly literal. A **note** where the heredoc twin `MIX-W2402` is a warning, and the asymmetry is measured — over 785 fleet scripts W2402 costs 4 findings and this one an order of magnitude more even after those exclusions, so a warning would fail `--deny-warnings` on scripts that are not wrong. D3xxx is the promotable namespace precisely so that can change once the residue is worked off |

Member-call spellings are covered too: a builtin-named `.name(` desugars
to the same call at parse time.

```text
MIX-E1001  lexical error                    MIX-E1301  duplicate function parameter
MIX-E1002  script parse error               MIX-E1302  duplicate function definition in one scope
MIX-E1003  strict-data parse error          MIX-E1303  function name shadows a builtin
MIX-E1101  undefined variable               MIX-E1401  require() target missing/unreadable
MIX-E1102  undefined function               MIX-E1402  require() target invalid Mix
MIX-E1201  builtin arity mismatch           MIX-E1501  dead mutation (write is lost)
MIX-E1203  literal contradicts contract type
MIX-E1202  user-function arity mismatch     MIX-E1502  discarded pure transform
                                            MIX-E1503  fn name stored as a value (--agent)
                                            MIX-E1504  assignment from nil-returning builtin (--agent)
                                            MIX-E1505  constant-truthy condition (--agent)
                                            MIX-E1506  write to an outer variable in fn (--agent)
                                            MIX-E1507  shell command written as a bare string
                                            MIX-E1508  assign-back of an in-place mutator
                                            MIX-E1601  malformed `-- lint:` pragma
                                            MIX-W2101  unreachable statement
                                            MIX-W2201  discarded must-use result
                                            MIX-W2301  `+` on a proven list/map raises
                                            MIX-W2302  used implicit-nil function result
                                            MIX-W2303  assignment operand in hand-built chain AST
                                            MIX-W2304  unknown builtin-result key
                                            MIX-W2305  -1-sentinel builtin as a truth value
                                            MIX-W2306  escaped quotes in ssh command source
                                            MIX-W2307  send result never checked
                                            MIX-W2309  builtin-named map member unreachable via dot-call
                                            MIX-W2310  proven-missing lookup on a literal collection
                                            MIX-W2311  fmt/sprintf surplus operands
                                            MIX-W2312  bareword null/None/undefined is a string
                                            MIX-W2313  function name collides with a shell extension
                                            MIX-W2314  require() export: wrong argument count
                                            MIX-W2315  require() module has no such export
                                            MIX-W2401  source/include defeats analysis
                                            MIX-W2402  bare bound variable in heredoc
                                            MIX-W2405  unknown escape kept literally
```

`MIX-W2403` is **retired** (0.90.0), never reused: the builtin-shadowing
definition check was promoted from warning to error and therefore had to
move, since a code's letter fixes its severity permanently. It is now
`MIX-E1303`.

- **MIX-E1003** means the source was recognisably intended as strict data but
  failed the literal-data grammar. It is distinct from a broken executable
  script (`MIX-E1002`). A valid data file under any filename is recognised by
  content; the suffix is only a tiebreak when neither grammar succeeds.
- **MIX-E1101** flags a `$name` read only when the name is bound **nowhere in its visible universe** — function bodies see params + their own binders + everything bound anywhere at file level (Mix has no block scoping and no read-before-assign rule, so lexical order is deliberately ignored). `${name}` interpolation is never flagged (it falls back to the process environment), nor are `$1`-style positionals or the runtime-injected `rc` / `result` / `status` / `event` / `_`.
- **MIX-E1102** resolves bareword calls against builtins, HOFs, evaluator special forms, every `function` definition in the file, the embedded prelude, `--allow-function` names, AND any assigned variable (a bareword call can dispatch to a function-valued variable). Calls inside `address ... end` blocks are sends and are never flagged; `MethodCall`/`ValueCall` are dynamic dispatch and are skipped. The hint carries the **same "did you mean" the runtime prints** for that name. One suggester serves both, so lint (where an agent looks first) and the failing run cannot disagree. It checks, in order: the deleted-name pointers (`regex_match` → `re_match(s, pattern)`), then the **form table** for the foreign get/set/find whose answer is Mix syntax, not a builtin name (`get` → `$m[key]` / `get_or`/`require_key`; `set` → `$m[key] = value`; `find` → `index_of`/`filter`, semantics as in [collections](collections.md) — range inclusive, `sort` numeric-then-lexicographic, `filter` list-first), then a **foreign-name synonym table** for the names a python/bash/JS habit reaches for first (`json_decode`/`json_loads` → `json_parse`, `json_dumps` → `json_encode`, `str` → `to_string`, `trim_end`/`rstrip` → `rtrim`, `len_bytes` → `byte_length`, `getenv` → `env`, …), and only then edit distance. The order matters: `json_encode` is the nearest spelling of `json_decode` and means the opposite. A user-defined `fn get/set/find` is a known callable and never reaches the suggester.
- **MIX-E1201** checks calls against the structured contract metadata (`mix builtins --json`), including non-contiguous exact-arity sets — `random(1)` is an error, `random()`/`random(min, max)` are not. The contract is the documented surface; some older builtins tolerate surplus arguments at runtime, and lint is deliberately stricter (`mix --strict-arity` makes the runtime agree).
- **MIX-E1203** (0.103.3) flags a literal argument whose type cannot satisfy the contract's declared shape — `mkdir({a: 1})`, `exists([1, 2])`, `len(3)`. The runtime raises TYPE_MISMATCH on the same call (0.103.1), so the rule makes lint agree with the runtime; a wrong-typed path/target literal is a side effect on the wrong target. Variables and expressions are not judged — only a literal proves the type. A literal `nil` is judged too: it satisfies only a shape that declares it (`any_of(…, nil)` for the optional args that treat nil as omission, or `any`), so `write_file(nil, "x")` is flagged exactly as the runtime refuses it.
- **MIX-E1501** flags a discarded `push`/`pop`/`shift` whose first argument is **not a bare variable** — `push($m["a"], $v)`, `push($m.a, $v)`, `$m["a"].push($v)`. These builtins mutate through the variable slot, so given any other expression they append to a temporary copy and the write is **lost in silence**. It is an ERROR, not a warning: the statement does nothing while reading as though it did. The fix **differs by builtin**: `push` returns the appended list, so assign it back (`$m["a"] = push($m["a"], $v)`); `pop`/`shift` return the **removed element**, not the list, so assigning that back replaces the list with the element (data corruption) — hoist first instead (`$l = $m[$k]; $x = pop($l); $m[$k] = $l`). For maps of maps, write the [nested assignment](collections.md) directly. A by-value **parameter** is a bare variable, so that case stays with its own definition-time dead-push warning and is not double-reported.
- **MIX-E1502** flags a discarded `delete` / `merge` — both are **pure** (they return a new container and change nothing in place), so a bare call is a no-op. Assign it back: `$m = delete($m, "k")`.
- **MIX-E1503–E1506** are the `--agent` profile (run `mix lint --agent`, or `MIX_LINT=agent`): a function name stored as a value (`$f = bump` binds the *string*), an assignment from a nil-returning builtin (`$n = write_file(...)` binds nil), a constant-truthy condition (`if "false"`, a bare process-result map — `while true` is exempt), and a `fn` body writing an outer variable (which silently creates a local). Ordinary lint and the fleet's `--deny-warnings` gates run without them.
- **MIX-W2201** fires when an operation whose failure signal lives in its RETURN VALUE (`effects.must_use`: `run_rc`, `run_argv`, `run_pipeline`, `run_parallel`, `ssh_run`, `ssh_exec`, `ssh_mix`, `http_*`, `kill`, `run_stream`) is a bare expression statement — the bug class where a failed remote step silently vanishes. Bind the result and branch on it; some have a fail-fast twin that raises (`run_argv`→`run_argv_must`, `run_pipeline`→`run_pipeline_must`, `ssh_run`→`ssh_must`). The last statement of a block is exempt (it may be the block's value).
- **MIX-W2301** warns that `+` is not defined for lists or maps. Since 0.90.0
  the runtime **raises** `TYPE_ERROR` there rather than silently stringifying,
  so this fires ahead of the run for a list/map **literal** operand, or a
  variable proven by straight-line analysis to hold a directly assigned one —
  which is the only gate there is on an `ssh_mix` body, or on a branch a local
  run never takes. Use `concat(a, b)` for lists, `merge(a, b)` for maps,
  `push(list, value)` to append, `..` to build text. It stays a *warning*, not
  an error: the proven-value facts are straight-line, so a reassigned variable
  can make the prediction wrong.
- **MIX-W2302** warns when the result of a uniquely defined named function is
  consumed, its block body's final statement is a bare expression, and the
  body contains no value-returning `return`. Block functions implicitly return
  `nil`; add `return`. A discarded call is quiet, as are mixed-return bodies,
  terminating final expressions, and calls whose name can be redirected
  through a variable.
- **MIX-W2303** is defence-in-depth for Rust embedders that construct the public
  AST directly and pass it to `analyze()`: it warns if any operand of a
  hand-built `StmtKind::Chain` is an assignment. Ordinary Mix source cannot
  reach this warning because the parser rejects the same shape first as
  `MIX-E1002`. The code remains reserved for this public-API path and is not
  repurposed.
- **MIX-W2304** checks a literal field/index key against the builtin's
  documented result-map fields from `mix builtins --json`. It works on a
  direct builtin call or a variable proven by straight-line assignment to
  hold that result. The message names the declared shape and says what the
  read does: `process_result (from run_argv()) has no field 'code' — reading
  it is silently nil`. The hint is a did-you-mean (0.117.0): the bash, Python
  and Node spellings map to the field they mean first (`code`, `rc`,
  `status`, `returncode` → `exit_code`; `status_code` → `status`;
  `success` → `ok`; `output` → `stdout`), then a field ending in `_key`,
  then the nearest by edit distance, so `$r.rc` no longer suggests `ok`.
  Dynamic keys, generic maps and result shapes without declared fields are
  deliberately silent, and the runtime is unchanged: a missing field reads
  `nil`.
- **MIX-W2305** flags `index_of()` / `byte_index_of()` / `bytes_find()` (added
  v0.64.0) used **bare as a truth
  value**. They return `-1` for "not found" and `0` for "found at the first
  position", and Mix treats `0` as falsy and every non-zero number — `-1`
  included — as truthy. So a bare call in a condition is wrong on *both*
  branches:

  ```mix
  if index_of("abc", "z") then …   -- -1 is TRUTHY  → absent reads as present
  if index_of("abc", "a") then …   --  0 is FALSY   → found-at-0 reads as absent
  ```

  Compare explicitly (`index_of(..) >= 0`), or use `contains()` for the yes/no
  question — **except for `byte_find`/`bytes_find`**, whose bytes subject
  `contains()` rejects, so those take the `>= 0` comparison only. Their 1-based
  twins — `pos`, `lastpos`, `byte_pos`,
  `byte_lastpos` — are **safe** in the same position because their not-found
  sentinel is `0` and therefore falsy; that asymmetry is exactly what makes
  the trap easy to walk into, and why the rule exists. Fires in `if`/`elif`,
  `while`, `break if`/`continue if`, expression-position `if`, the ternary
  condition, and through `not`/`and`/`or`. Any explicit comparison is already
  correct code and stays silent.
- **MIX-W2306** flags a literal command passed to `ssh_run` or `ssh_must` when
  its source spelling contains `\"`. That escape is the high-signal mark of
  nested Mix source which the remote shell will parse again. Ship the source
  verbatim with [`ssh_mix` + a heredoc](remote.md#headline-idiom-ssh_mix--heredoc).
  Simple command strings, computed commands, `ssh_exec`, `ssh_mix`, and
  single-quoted strings containing ordinary `"` stay quiet.
- **MIX-W2311** warns on a direct, unshadowed [`fmt()`/`sprintf()`](strings.md#sprintf--c-compatible-formatting-v0710)
  call whose template is a string literal that parses cleanly under the
  runtime grammar, when the call provides more operands than the template
  consumes — `fmt("%s", 1, 2)` provides two operands for one placeholder,
  and both builtins **silently ignore** the surplus (they are variadic, so
  the generic arity gate cannot see it). `%%` consumes nothing; a `*` width
  and a `sprintf` `.*` precision consume one operand each, so `fmt("%*s",
  5, "x")` is exact and stays quiet. Invalid or unknown templates (which
  would raise at runtime), dynamically built templates, deficits (the
  runtime's own "not enough arguments" error), and calls a user function,
  variable, `address` block or `source`/`include` could shadow are silent
  too.
- **MIX-W2312** (0.117.0) warns on a bareword `null`, `None`, `undefined`,
  `NULL` or `nullptr` used as a value. Mix's only null is `nil`; every other
  bareword is a string literal, so `{open: null}` sends `{"open":"null"}`
  and `if $x == None` compares against text. A map key (`{null: 1}`), a
  field (`$x.null`), a call name, a statement head, a Bus command word and a
  quoted `"null"` stay silent. Where the word is surely a value (a call
  argument, a list element, a map value, the right side of `$x =`, an
  operand of a comparison or `??`, a `return` operand) the finding carries a
  quick fix to `nil` (`mix lint --fix`); anywhere else, such as
  `print("a") && null` where `null` may call a `fn null()`, it warns without
  one. There is no runtime alias, by decision: the language
  keeps one null. Like D3015 it needs the source text.
- **MIX-W2313** (0.117.0) warns at the definition of a function named after
  one of the `mix` binary's shell extensions (`ai`, `ai_diagnose`,
  `context`). An extension beats a user function at a bareword call, so
  `context()` runs the shell's extension. A member call on a `require()`
  exports map (`$m.context()`) does reach the function, in every mode.
- **MIX-W2314 / MIX-W2315** (0.117.0) are warnings while the check is new,
  so a false positive can never fail a `mix lint` gate; the call they flag
  fails at run time, and they may become errors with the type work. They
  check member calls into a module
  bound once to a literal path, `$m = require("./lib.mix")`, against what
  the module exports: its top-level functions (with their arity) and
  `$vars`, minus `_`-private names. `$m.helper(1)` for a two-parameter
  `helper` is W2314; `$m.nosuch(2)` is W2315, with the nearest export as a
  did-you-mean. W2315 stays silent when anything else can answer the call
  (an exported `$var` that may hold a function, a function this file
  defines, the prelude, an extension, an enclosing `address` block) — except
  for a statement `$m.nosuch()`, which calls the field value and has no UFCS
  fallback. An
  export bound once to a literal `require()` resolves too, next to its own
  module (`$a.b.fn()`), and a require cycle cannot loop the check. Both
  stand down silently for a dynamic path, a rebound `$m` (or one that is
  also a parameter), a module whose top-level `return` replaces the
  auto-export or that uses `source`/`include`, and a file that does.
- **MIX-E1601** (0.117.0) refuses a malformed [`-- lint:` pragma](#in-file-pragmas-01170): a bare `ignore` or `ignore-file`, an unknown code or directive, a `globals` with no valid names.
- **MIX-W2401**: one `source`/`include` anywhere disables the undefined-name checks for the whole file (the loaded file can define anything) — reported once so you know analysis is degraded. Prefer `require()`: it is isolated, statically resolvable, and E1401/E1402 verify literal-path modules parse.
- **MIX-W2402** warns when a heredoc literal contains bare `$NAME` and `NAME` is bound somewhere in the same visible universe. Heredocs interpolate `${NAME}`, not `$NAME`, so the bare form often means a generated config was silently corrupted. It does not fire for `${NAME}`, `$(` command substitution, explicitly escaped `\$NAME`, all-digit names such as `$1`, unknown names, or ordinary double-quoted strings. The warning is lint-only: bare `$NAME` still evaluates to literal `$NAME`, and intentional literal output requires no change. In a heredoc that ships as an `ssh_mix` body it stays silent for the names the **remote** program owns: the call's `bindings`/`env` keys and whatever the body binds itself. There, bare is exactly right, and `${NAME}` would splice the local value into the remote source. Any other bound name still warns.
- **MIX-E1303** (0.90.0; was `MIX-W2403` from 0.74.0) errors at the *definition* of a function whose name is a builtin: the builtin wins at every call site (a builtin-named dot-call even desugars at parse time), so the definition is unreachable by name. The worst shape this produces is a script that keeps running while its own function quietly stops being called, and every release that adds a builtin name arms it again for older scripts. It was a warning on the theory that a compat shim for an older mix is legitimate authoring; the fleet refuted that — two sites across 785 scripts, neither a shim: one a hand-rolled `ends_with` duplicating the builtin, the other an `fn mix_version()` in a pre-commit hook written to report a *named* interpreter's version and silently answering with the running one's, a live wrong answer that sat behind a warning for sixteen releases. Lint is also the only gate an `ssh_mix` body passes through, and a warning stops nothing by default. The builtin still wins at a call site; the fix is to rename. Since 0.118.0 the **runtime refuses the definition** as well (`FN_SHADOWS_BUILTIN`), before the first statement for a top-level `fn`: `mix --check` is syntax-only, so a script that skipped `mix lint` used to run on and fail far from the cause (`fn run($argv)` died as `run(): argument 1 (cmd) must be string`). Since 0.118.0 the name set also includes the higher-order builtins (`count`, `map`, `filter`, `sort_by`, …), which slipped past this check before. Since 0.91.0 the check also covers the evaluator's inline forms that sit outside the builtin table's dispatch gate — `serve_name`, `printf` and its stdio siblings, and the Bus forms `quit`, `reply`, `subscribe` and the rest — which beat a same-named function just the same: `fn quit() return 1 end; print(quit())` printed `nil` with no diagnostic before. Since 0.92.0 the runtime agrees in operand position too: the binary-operator fast path used to call a user `fn printf` for `printf("B") .. "|"` while a bare `printf("B")` called the builtin; now the builtin wins in both.
- **MIX-W2405** warns when a double-quoted literal contains a backslash escape the lexer does not recognise, so the backslash is kept: `"isn\x27t"` printed `isn\x27t` and nothing said so, which is how a `replace()` wrote that into a committed journal entry. 0.90.0 added `\xHH` (exactly two hex digits), `\0` and `\a \b \f \v`, so what remains is genuinely unrecognised — including `\x` with fewer than two hex digits and `\'`. A deliberate backslash is `\\`, so the warning has a clean escape. An unbraced `\u` is **exempt**: that literal is documented design (it protects embedded JSON and `C:\users`). Single-quoted strings and heredocs keep their own rules and are not scanned.
- **MIX-D3015** and **MIX-W2405** ask how a literal was *spelled*, which the token stream deliberately forgets (`'$sp/x'` and `"$sp/x"` lex to the same token). They therefore need the source text: `mix lint` supplies it, and so does the nested analysis of an `ssh_mix` body, but an embedder calling `analyze()` without setting `AnalyzerConfig::source` simply does not get these two rules.

## In-file pragmas (0.117.0)

A comment starting `-- lint:` (or `# lint:`) tells lint something the code
cannot, so the knowledge lives with the file instead of in a per-invocation
flag. There are three, and they have no runtime effect:

```mix
-- lint: globals sha, target
-- lint: ignore MIX-W2402
-- lint: ignore-file MIX-D3015
```

The first declares names injected by `ssh_mix` bindings, an embedder or a
`source`; the second suppresses MIX-W2402 on the next line of code only;
the third suppresses MIX-D3015 everywhere in the file.

- `globals` is the in-file `--allow-global`: each name counts as bound, so a
  remote body whose caller binds `$sha` lints clean on its own.
- `ignore` covers the **next line holding code** and nothing more (eslint's
  `disable-next-line`): blank and comment lines between are skipped, every
  statement on that line is covered, and a finding on a later line of the
  same statement is not, so put the pragma right above the line that reports
  the code. Most findings carry their statement's first line; a few (such as
  `MIX-W2312`) carry the line of the offending word. Written after code on
  the same line, `ignore` covers that line.
- Every suppression names its code (several may be listed, comma- or
  space-separated; the `MIX-` prefix and case are optional). A bare
  `-- lint: ignore` is **refused** (`MIX-E1601`), as is an unknown code or
  directive, so a typo cannot silently disable a check.
- A suppression that matches nothing is reported as the note `MIX-D3019` at
  the pragma's line, so stale ones get cleaned up. Notes never gate.
- The text after a `|` on a line is shell text for the external command, so
  `print(1) | echo -- lint: ignore` holds no pragma.
- Pragmas are read from comments only: a `-- lint:` line inside a string or
  heredoc (generated Mix source) belongs to that source, not to this file.
  They apply to the analyzer's findings, not to the lexer/parser errors
  (`MIX-E1001`–`E1003`) or the driver's `MIX-D3016`, and an embedder that
  calls `analyze()` without the source text gets none.

## `mix explain MIX-XXXX` — the offline diagnostics explainer

Every human-readable lint run that reports anything ends with one trailer line:

```text
explain any code with: mix explain MIX-XXXX
```

`mix explain MIX-W2305` (the `MIX-` prefix is optional, case-insensitive — `mix
explain w2305` works too) prints the code's full story — what it flags, why the
rule exists, the shape it catches, and the fix — from a registry embedded in the
binary, so an agent that hits a code it has never seen gets the whole rationale
in one call without leaving the terminal or reaching the network. An unknown but
code-shaped argument lists the known codes rather than failing blankly; a
non-code argument (`mix explain round`) falls through to the AI builtin
explainer. The registry is the same prose as this page; a build-time test
asserts every code the analyzer can emit has a record, so a new diagnostic
cannot ship without its explanation.

## Machine output

`--json` uses D3 schema 3: parsed `functions` metadata is added to schema 2.
Every existing key keeps its meaning, including `"note"` severity and
`summary.notes` introduced in schema 2:

```json
{
  "schema_version": 3,
  "tool": "mix lint",
  "mix_version": "0.63.0",
  "files": ["worker.mix"],
  "strict_data_files": [],
  "diagnostics": [{
    "code": "MIX-E1101", "severity": "error", "file": "worker.mix",
    "line": 412, "column": null,
    "message": "undefined variable '$DOMAIN' (assigned nowhere in this file)",
    "hint": "assign it, use env(\"DOMAIN\") for environment values, or declare an injected name with `-- lint: globals DOMAIN` (or pass --allow-global DOMAIN)",
    "fix": null
  }],
  "capabilities": ["fs-read", "network", "process"],
  "handlers": [],
  "functions": [],
  "summary": {"errors": 1, "warnings": 0, "notes": 0, "denied_warnings": false}
}
```

`fix` (0.117.0, additive) is `null`, or the quick fix `--fix` would apply:
`{"line": 1, "column": 6, "replace": "null", "with": "nil"}` (1-based line
and character column).

`--data` emits the same report as strict-data Mix source (parse with
`data_parse`). `line`/`column` are 1-based or `null`. Most diagnostics are
statement-level and carry a `null` column. Lexical and parse errors generally do
carry one — the assignment-chain error, for instance, points at the offending
`&&`/`||`.

`capabilities` is the inventory of capability classes the script's calls
exercise — data, not warnings.
`strict_data_files` lists inputs validated by the strict-data fallback rather
than by the script analyzer.

`handlers` (introduced in schema 2) lists each `on <command>`
declaration the parser built, across every input file, in source order:
`{"command": "ping.one", "file": "ping.mix", "line": 2}`. `file` is the path as
given, or `"-"` for stdin. The field is always present: it is
`[]` for strict-data inputs, for a file that failed to parse, and for a script
with no `on` statement. Duplicate declarations are kept.

`handlers` is structural evidence only. It comes from the native AST, so an `on`
counts wherever the parser places it (top level, a `fn` body, a block lambda, an
`if` branch or a control block). It does not prove that the handler runs or is
reachable. Text inside comments, quoted strings and heredocs is never a
declaration. Bodies of `ssh_mix` remote programs are not included either,
because they are literal payloads, not local source. Lint never executes the
file to collect them.

`functions` lists named `fn`/`function` definitions as
`{"name": "esc", "file": "lib.mix", "line": 4}`. It uses the same AST walker
and file attribution as `handlers`, keeps nested and duplicate declarations,
and excludes comments, strings, heredocs and remote programs. It is always
present, including an empty list for strict data or a parse failure. Like
handler metadata, it records declarations rather than proving reachability.
Embedders can derive external function names from declared context files;
`services/webd/vhosts/embed.conf.mix` is the webd source gate's declaration.

## Remote bodies — lint sees inside `ssh_mix` (0.69.0)

[`ssh_mix(host, source[, opts])`](remote.md) ships its **second argument** to
a remote `mix -`. That argument is Mix source, and since 0.69.0 lint treats it
as such: when it is a **literal** it is parsed and analysed, and its
diagnostics are reported against the enclosing file with a
`[inside ssh_mix body]` prefix and the line mapped into the outer file.

A literal is a plain string, an all-literal heredoc written inline (the
[headline idiom](remote.md#headline-idiom-ssh_mix--heredoc)), or a variable
whose **sole** binding anywhere in the file is one of those. The last is the
fleet shape: the program bound once, shipped from a loop over hosts.

```mix
$probe = <<END
print(length($base))
END
for $h in $hosts do
  $r = ssh_mix($h, $probe, {bindings: {base: $base}})
end
```

"Sole" is strict. A second assignment, a loop variable or a parameter of the
same name anywhere in the file makes the value unknowable, and the body is
reported as unanalysable instead. The binding must also be visible at the
call: at top level, in the same function, or in an enclosing function reached
through lambdas (a lambda is a closure; a named nested `fn` is not). Findings in a bound heredoc point at the
heredoc's own lines. A heredoc shipped by several calls reports each finding
once. Calls are found at any depth: in loops, branches, functions and lambdas.

```
deploy_thing.mix:283: MIX-D3001 note: [inside ssh_mix body] `regex_match` is
  pattern-first legacy: use `re_match(s, pattern)` (subject first)
```

Before this, a deploy script's entire remote half was one opaque string —
invisible to lint and, more consequentially, to every **inventory built from
lint**. That is not a hypothetical: the `MIX-D3006` inventory that gated
0.68.0's map-binding flip reported *zero* sites for `deploy_vhost.mix`,
locally and on 27/27 fleet nodes, while line 283 of that file is a
two-variable loop over a map living inside such a body.

**A body that cannot be analysed says so** — `MIX-D3012`, for a non-literal
argument (a variable not bound once to a literal, concatenation,
interpolation, `read_file`) or a literal
that does not parse as Mix. This is the rule that matters more than the
analysis: an unreadable body silently counted as clean is precisely how an
inventory reads zero while live sites exist.

A body interpolating `${name}` is reported by name. That splice puts the
**local** value into the remote source text, which is the classic remote bug;
pass the value through `bindings` and write it bare instead.

**Names resolve against the body's own universe.** A remote body is a
separate program. It sees its own binders, the builtins and prelude, and the
names the call injects: the keys of `bindings` and of `env`, both prepended to
the shipped source as assignments. It does **not** see the enclosing file's
functions or variables. So a bare `$base` passed as a binding is clean, while
`$notbound`, or a call to a helper defined only in the outer file, is
`MIX-E1101`/`MIX-E1102` with the body prefix.

The injected names are read from the opts argument when it is a map literal,
or a variable bound **exactly once** to one (`$o = {bindings: {…}}` — the same
sole-definition rule as the body itself, so the fleet opts-variable shape
keeps full checks). When they cannot be read — a call, a concatenation, a
multi-bound name — the boundary is **split, not blanket** (`MIX-D3018` at the
call): dynamic bindings may supply any free DATA variable, so
undefined-**variable** checks stand down (a read one edit away from a name the
body binds still gets the `MIX-D3017` typo note), but a function name cannot
ride in through strict-data bindings, so undefined-**function** checks and
arity checks keep running. The enclosing file keeps all of its own name
checks. Everything else — legacy-name notes,
arity, the truthiness trap — applies normally, and **errors from inside a
body gate exactly as they would anywhere else**.

**Diagnostics map onto the enclosing file's real lines.** `mix lint` reads
the source text, and the lexer records — while decoding each literal — which
physical line every decoded line was written on. So a double-quoted body
whose lines are `\n` ESCAPES reports everything on the one line the literal
physically occupies, a physically multi-line literal and a heredoc map
line-for-line (a `\n` escape inside a heredoc lands on the escape's line,
not an invented one), and a parse/lex error inside a body is mapped by the
error's own inner line.

Which opener a body is paired with is decided by the **parser**, not by
matching text. With the source at hand, lint re-parses the file with
literal-origin recording on: the parser records, in source order, one entry
per literal *expression* it builds, and pairs those entries positionally
with the same tree's literal expressions, verifying variant and decoded
text per pair. Map keys (bare or quoted), `parse` delimiters and `on`
names/doc-strings are not expressions, so identical text there can never
steal a body's opener — a body opened on its own physical line reports
there. If the recording and the tree disagree anywhere, the whole mapping
is refused: a mapping can be missing, but it is never misattached.

An embedder calling `analyze()` without `AnalyzerConfig::source` gets the
documented linear estimate instead (`first_line + N - 1`, exact for the
`$x = ssh_mix($HOST, '` and `$p = <<END` shapes), never invented accuracy.

`ssh_mix` and `ssh_mix_many` carry remote Mix source this way. `run`
accepts shell command text; `run_argv` and `run_pipeline` execute argv
specifications. Lint does not infer embedded source from those process
arguments. `--serve` runs a script file, which lint can inspect directly.

## What lint deliberately does NOT do (v1)

- Straight-line facts do not cross branches, loops, function-call boundaries,
  `source`/`include`, or function frames. This deliberately misses lists and
  builtin-result maps produced indirectly, returned by helpers, assigned in a
  branch, or reached through a dynamic key. Suspicious `nil` coercion into
  paths/hostnames remains out of scope. `MIX-W2302` also stays silent for a
  mixed-return function even when one fallthrough path may still yield `nil`.
  Shell-vs-argv advice remains out of scope — use
  [`validate`](data.md) at boundaries for the nil class today.
- No reachability model for `E1102`/`E1101` beyond the universe rules above.
- Dynamic `require(expr)` paths, extension calls, and Bus dispatch are never hard errors.

## See also

- [invocation](invocation.md) — `mix --check` (syntax only), `--strict-arity`
- [errors](errors.md) — the structured errors the flagged code will raise at runtime
- [builtins](builtins.md) — the contract metadata lint checks against

---

<!-- page: https://mixos.dev/mix/math/ (source: https://mixos.dev/mix/math.md) -->

# math — numeric builtins

The `math` builtin category (27 functions, added in mix 0.19.0) — pure numeric
functions over Mix's f64 numbers. List them live with `mix builtins math`;
one-line help for any single name with `mix what NAME`.

## Common semantics

All math builtins share the same rules:

- **Argument coercion** — like the rest of Mix, a numeric **string** or a **bool** is accepted and coerced (`sqrt("16")` → `4`, `abs(true)` → `1`). A genuinely non-numeric argument **raises** a runtime error (`sqrt("hello")` → error, `abs(nil)` → error).
- **Numeric-string coercion is strict** (0.21.0): a non-finite *spelling* is not a numeric string — `abs("inf")`, `abs("nan")`, and `abs("1e999")` all raise. Non-finite number *values* still flow through (next rule).
- **NaN / infinity propagate, they do not error.** Out-of-domain results follow IEEE-754: `sqrt(-1)` → `NaN`, `ln(0)` → `-inf`, `log10(-5)` → `NaN`. Mix prints these as `NaN`, `inf`, `-inf`.
- **There are no `NaN` / `inf` literals.** A bareword `NaN` or `inf` in source is a *string*, not a number (and per the strict rule above it won't coerce). Produce non-finites through arithmetic — `sqrt(-1)` for NaN, `ln(0)` for `-inf` — or the overflowing literal `1e999`, which is the f64 `inf`.
- **Whole results print integer-clean.** `round(2.5)` prints `3`, not `3.0` (Mix formats a whole f64 without a trailing `.0` — see [numbers](numbers.md)).
- **Extra arguments are ignored** by the math family (minimum-arity): `sqrt(9, "x")` → `3`, `pi(1)` → `3.141592653589793`. (This is no longer universal across builtins — since 0.21.0 `run`/`run_rc`/`http_*` reject surplus arguments loudly.)

## Rounding

```
round(x)         round to the nearest integer, half away from zero
round(x, n)      round to n decimal places
floor(x[, n])    round down  toward -inf
ceil(x[, n])     round up    toward +inf
trunc(x[, n])    truncate toward zero (drop the fraction)
```

`round` breaks ties away from zero: `round(2.5)` → `3`, `round(-2.5)` → `-3`.

The optional second argument is the number of **decimal places**. A **negative**
`n` rounds to the tens / hundreds / … place:

```
round(3.14159, 2)   -> 3.14
floor(3.999, 2)     -> 3.99
ceil(3.001, 2)      -> 3.01
trunc(3.789, 1)     -> 3.7
round(1234, -2)     -> 1200
round(1250, -2)     -> 1300
```

Details of the places argument:

- A **fractional** `n` is truncated toward zero: `round(3.14159, 2.9)` rounds to 2 places → `3.14`. Internally `n` is clamped to ±308 (the largest finite power of ten).
- A **non-finite** `n` is rejected: `round(1.9, sqrt(-1))` → error (`round() decimal-places argument must be finite, got NaN`).
- A **non-finite `x`** has no fraction to round and is returned unchanged: `round(sqrt(-1))` → `NaN`, `round(ln(0), 2)` → `-inf`.
- Coarse rounding stays correct across the whole f64 range: `round(5e19, -20)` → `100000000000000000000` (1e20 — whole numbers print full-width; Mix never prints e-notation). Scientific-notation *literals* like `5e19` are valid input since 0.20.5 — see [numbers](numbers.md).

## Sign & magnitude

```
abs(x)     absolute value
sign(x)    -1, 0, or 1   (±0 -> 0; NaN -> NaN)
```

```
abs(-7)    -> 7
sign(-3)   -> -1
sign(0)    -> 0
```

## Bitwise (v0.46.0)

```
band(a, b)   bitwise AND
bor(a, b)    bitwise OR
bxor(a, b)   bitwise exclusive-OR
bnot(x)      one's complement, 64-bit two's complement  (bnot(0) -> -1)
bshl(x, n)   shift left by n bits    (n in 0..63)
bshr(x, n)   arithmetic shift right  (sign bit replicated)
```

```
band(0o755, 0o111)  -> 73     -- an execute bit is set
band(0o644, 0o111)  -> 0      -- none is
bxor(6, 3)          -> 5
bshr(-8, 1)         -> -4     -- arithmetic, not logical
```

The everyday use is permission bits, where asking about *some* bits is the only
correct question — a filesystem may add a setgid or group bit of its own, so an
equality test against a whole mode reports a chmod that landed as one that did
not:

```mix
if band(stat($p)["perm"], 0o111) != 0 then
  print("something can execute it — ask access($p, \"x\") whether YOU can")
end
```

Mix numbers are `f64`, so these operate on **exact integers within ±2^53** —
the range an `f64` carries without loss. A fraction, an infinity, a NaN, a
magnitude outside that range, or a shift count outside `0..63` **raises**. So
does a `bshl` whose result would leave the range, *including* one that would
leave 64 bits entirely (`bshl(0x10000000000000, 12)` raises rather than
answering `0` — v0.46.1; 0.46.0 wrapped first and then range-checked the
wreckage). Nothing here truncates, wraps, or rounds silently: an operation on
bits the caller cannot see the number of is not an answer worth returning.

## Powers, roots & exponential

```
sqrt(x)            square root          (negative -> NaN)
cbrt(x)            cube root            (defined for negatives: cbrt(-27) -> -3)
pow(base, exp)     base raised to exp   (pow(2, 10) -> 1024)
exp(x)             e raised to x
```

## Logarithms

```
ln(x)              natural log, base e  (ln(0) -> -inf, ln(neg) -> NaN)
log10(x)           base-10 log          (log10(1000) -> 3)
log2(x)            base-2 log           (log2(8) -> 3)
log(x, base)       log of x in an arbitrary base  (log(81, 3) -> 4)
```

## Bounds

```
min(a, b, ...)     smallest of the arguments
min(list)          smallest element of a single list argument
max(a, b, ...)     largest of the arguments
max(list)          largest element of a single list argument
clamp(x, lo, hi)   constrain x to [lo, hi]
```

`min` / `max` are **variadic or take a single list** — `max(3, 1, 2)` and
`max([3, 1, 2])` both give `3` (a single scalar is fine too: `max(7)` → `7`).
They mirror the `<` / `>` [operator ordering](operators.md):

- **Numeric** when *every* argument coerces to a number — including numeric strings, so `min("5", "10")` → `5` (numeric comparison, and the result is normalized to a number). A stray `NaN` is **skipped** like `f64::min`/`max`: `max(1, sqrt(-1), 5)` → `5`; an all-`NaN` set stays `NaN`.
- **Lexicographic by codepoint** when every argument is a string and they don't all coerce: `max("apple", "banana")` → `"banana"`, `max("apple", "5")` → `"apple"` (`a` is codepoint 97, `5` is 53). The winning string is returned unchanged.
- A genuinely mixed set errors: `min(1, "abc")` → `min() needs all-numeric or all-string arguments (cannot compare a mix)`.
- An empty list errors: `max([])` → `max() of an empty list`.

`clamp` returns `lo` if `x < lo`, `hi` if `x > hi`, else `x`. It **errors** if
`lo > hi` (`clamp() lower bound 10 exceeds upper bound 0`) and if either bound
is `NaN` (a NaN bound would silently defeat the range check — `NaN > x` is
always false). `±inf` bounds are fine — `clamp($x, 0, 1e999)` ≡ `max($x, 0)`.
A `NaN` value of `x` is returned unchanged.

```
min(3, 1, 2)        -> 1
max([5, 2, 9])      -> 9
clamp(42, 0, 10)    -> 10
clamp(-3, 0, 10)    -> 0
```

## Distance

```
hypot(x, y)    sqrt(x*x + y*y), computed without intermediate overflow
```

```
hypot(3, 4)    -> 5
```

## Trigonometry (radians)

```
sin(x)  cos(x)  tan(x)
asin(x)  acos(x)  atan(x)      asin/acos domain is [-1, 1], else NaN
atan2(y, x)                    angle of the point (x, y), in radians
```

```
sin(0)            -> 0
cos(0)            -> 1
atan2(1, 1)       -> 0.7853981633974483   (pi/4)
```

## Constants

```
pi()    the constant pi  (3.141592653589793)
e()     Euler's number e (2.718281828459045)
```

These are zero-argument functions — call them with parentheses. Combine with the
trig functions, e.g. degrees → radians is `deg * pi() / 180`.

`e()` coexists cleanly with scientific-notation literals (`1e6`, `2e-3`,
added in 0.20.5): the lexer only consumes an `e`/`E` when a digit follows, so
`2 * e()` is never eaten as the start of `2e…` — it evaluates to
`5.43656365691809`.

## Randomness

```
random()          a float in [0.0, 1.0)
random(min, max)  an integer in [min, max] INCLUSIVE  (e.g. random(1, 6) = a d6)
```

`random()` (added in 0.23.0) has two forms and, unlike the minimum-arity math
family above, is **strict about arity** — it accepts exactly 0 or 2 arguments and
rejects 1 or 3+ loudly (`random() expects 0 args (float [0,1)) or 2 args (int min,
max)`). The two-argument form requires **integer** bounds (a fractional bound like
`random(1.5, 3)` errors), `min <= max` (`random(6, 1)` errors), and both endpoints
are reachable (the range is inclusive of `max`). Bounds must be within `±(2^53 − 1)`
— Mix numbers are f64, so an integer past that ceiling isn't exactly
representable and is rejected rather than returned lossily. 2^53 itself is
refused since 0.59.0: it is also what 2^53 + 1 rounds to, so accepting it
would accept an aliased bound the caller never wrote.

```
random()          -> 0.6009269054001612
random(1, 6)      -> 3            (1..=6, each equally likely)
random(5, 5)      -> 5            (a single-point range is fine)
random(-3, -1)    -> -2           (negative ranges work)
```

`random` is drawn from the **thread-local RNG** (auto-seeded from OS entropy) — fast
enough for tight loops, but **non-deterministic and NOT cryptographically strong**.
For anything security-sensitive (passwords, tokens) use
[`random_password`](system.md) or `uuid`, which draw from a cryptographically
secure RNG (`random_password` uses `OsRng`; `uuid` uses `getrandom`).

## Notes

`min`, `max`, `abs` and `clamp` replaced the old `prelude.mix` shims of the same
names — **a builtin shadows any same-named Mix function**, so defining your own
`function abs($x)` has no effect on `abs(-7)`. They preserve the value/ordering
the shims selected, with two refinements: a numeric result is **normalized to a
number** (a numeric-string or bool argument no longer round-trips with its
original type — `abs("5")` → `5`, not `"5"`), and `clamp` errors on an inverted
`lo > hi` range or a `NaN` bound instead of returning a meaningless value.

Every math builtin is capability class **`Pure`** — no host authority, always
allowed even in a sandboxed embedding (see [capabilities](capabilities.md)).

Division and modulo are *operators*, not math builtins: `5 / 0` and `5 % 0`
both raise a runtime error (modulo-by-zero became loud in 0.20.5) — see
[operators](operators.md).

## See also

- [numbers](numbers.md) — the f64 model, integer-clean printing, radix and scientific-notation literals, numeric strings and `to_number`
- [operators](operators.md) — arithmetic, `%`, and the `<` / `>` ordering rule that `min`/`max` mirror
- [builtins](builtins.md) — the full categorized builtin index
- [capabilities](capabilities.md) — the `Pure` class every math builtin carries
- `mix builtins math` lists every math builtin with its one-line description; `mix what NAME` gives one-line help for a single name; `mix help` is the full categorized reference

---

<!-- page: https://mixos.dev/mix/mix-bench/ (source: https://mixos.dev/mix/mix-bench/README.md) -->

# Mix regression tests

The former standalone `mix-bench` Cargo package is not in the current
MixOS workspace. This page keeps its existing documentation address so
older links resolve, but its old package name, sibling-directory lookup
and score command do not describe a tool that can be built here.

The current regression suites live with the components they exercise:

| Source | Coverage | Cargo package |
| --- | --- | --- |
| `libs/mix/src` and `libs/mix/tests` | Lexer, parser, evaluator, builtins, strict data and language regression scripts | `mix` |
| `cli/mix-shell/src` and `cli/mix-shell/tests` | Shell library and lint coverage | `mix-shell` |
| `cli/system/tests` | Shipped executable, native sessions, processes, manuals and shell integration | `system` |

In the designated Rust build environment, run the relevant suites with:

```text
cargo test --locked -p mix -p mix-shell -p system
```

These are correctness tests, not a replacement performance score. Check
the current manifests and test sources when selecting a workload.

See the [language library](../lib/README.md),
[shell library](../../mix-shell/README.md) and
[system executable](../../system/README.md).

---

<!-- page: https://mixos.dev/mix/mix-shell/ (source: https://mixos.dev/mix/mix-shell/README.md) -->

# mix-shell

`mix-shell` is the library behind the `mix` executable: the interactive shell,
script runner, command dispatcher, linter, and supervised Bus citizen host for
Mix programs. The executable itself is built by `cli/system`, the system
binary, which runs the shell when started as `mix`.
In the `bus <- mix <- cos` dependency chain it occupies the Mix layer: it
depends on Bus protocol, client, logging, build-information, and property
crates, and on the `mixos-lib-mix` language runtime, but it does not depend on
the Cos daemon layer.

## Synopsis

```text
mix
mix script.mix [args...]
mix -c 'CODE' [args...]
mix -i -c 'CODE' [args...]
mix - [args...]
mix --check script.mix
mix lint [OPTIONS] FILE...
mix --serve script.mix [--name SERVICE] [--no-prelude]
```

The Cargo package produces one binary named `mix`. It does not expose a Rust
library target. References to `mixos_mix` in its source name the
`mixos-lib-mix` dependency, not this package.

See [Command-line interface](cli.md) for modes, options, subcommands, files,
and environment variables. See [Serve mode](serve-mode.md) for the supervised
Bus runtime and its reserved verbs.

## What it provides

- An interactive readline shell with history, completion, aliases, job
  control, directory stacks, and a Mix-or-shell input classifier.
- A `.mix` script runner with positional arguments, traceback rendering,
  strict-arity selection, interrupt handling, and an optional standard
  prelude.
- A `-c` mode that applies the same classifier as the REPL, so the input may be
  Mix source or an external command line.
- Shell execution for pipelines, redirections, environment prefixes,
  expansions, command substitution, background jobs, and `&&`, `||`, and `;`
  command lists.
- Reference and introspection commands for help, manuals, builtins, keywords,
  operators, runtime state, and Bus services.
- `mix lint`, a semantic-analysis CLI with human, JSON, and strict-data output.
- Usage statistics stored under the XDG state directory, with JSON rotation
  and optional SQLite queries.
- Bus adapters for transient scripts and supervised `--serve` citizens.
- Runtime-owned `HELP`, `INFO`, `QUIT`, and L1 property verbs for every served
  citizen.

## Execution modes

| Mode | Entry point | Behaviour |
|---|---|---|
| Interactive | `mix` | Starts the REPL, loads the prelude and `~/.mixrc`, and maintains history and jobs. |
| Script | `mix FILE` | Parses and executes a file, then runs its event pump when handlers are registered. |
| Command | `mix -c CODE` | Classifies and runs Mix code, a Mix function command, or an external command line. |
| Configured command | `mix -i -c CODE` | Loads `~/.mixrc` before classification and execution. |
| Standard input | `mix -` | Reads Mix source from standard input; bare piped input does not execute implicitly. |
| Check | `mix --check FILE` | Lexes and parses without evaluating. |
| Lint | `mix lint ...` | Lexes, parses, and performs semantic analysis. |
| Serve | `mix --serve FILE` | Registers a named citizen and runs a permanent supervised Bus event pump. |

The REPL, `-c`, file, and serve evaluators use a recursion limit of 128. Time
and collection limits remain unset. The process runs evaluation on a dedicated
64 MiB stack.

## Module map

| Module | Responsibility |
|---|---|
| `main` | Process entry, option parsing, script execution, syntax checking, and serve lifecycle. |
| `bus` | Transient and supervised implementations of the language runtime's `BusHandler`. |
| `completion` | Readline completion for variables, aliases, Mix words, subcommands, and commands on `PATH`. |
| `mixos_paths` | Cached resolution of source, configuration, and binary directories. |
| `exec` | Shell tokenisation, expansion, pipelines, redirection, command lists, process launch, and `cd`. |
| `jobs` | REPL background-job tracking and foreground selection. |
| `lint` | `mix lint` argument parsing, report formatting, and analyser invocation. |
| `meta` | Help, manuals, introspection, build, diagnostics, mesh, AI, and orchestration commands. |
| `node_config` | Read-only broker URL resolution from `node.conf.mix`. |
| `repl` | Interactive loop, history, prompt, tracing, directory stack, jobs, and `.mixrc` loading. |
| `serve_runtime` | Reserved Bus verbs and the lifecycle property tree for served citizens. |
| `shell` | REPL and `-c` classification between Mix, functions, builtins, and external commands. |
| `shell_handler` | Per-line shell fallback for files loaded through `source`. |
| `stats_io` | XDG state paths, the append-only JSONL statistics store, its cache and ops, and stats reports. |

These modules are private implementation modules of the binary.

## Bus integration

Normal REPL and script execution use `MixAmpHandler`. It checks a local port
socket first for simple target names, then lazily probes the configured broker.
The handler supports request/reply calls, fire-and-forget emits, port checks,
incoming events, registration, topic subscription, replies, and an explicit
reconnect.

The first failed broker probe marks the process as a host on which the broker
was never present. Calls then report Bus unavailable without repeatedly
probing, emits remain no-ops, and port checks return false. A connection that
was established and later fails is reported as a mesh error. Calling
`bus_reconnect()` resets the transient handler for a fresh probe.

Serve mode uses `MixServeHandler` instead. It keeps one supervised broker
connection and registered identity, reconnects after transient broker loss,
and replays its topic subscriptions. It does not use the local-socket shortcut.

## Cargo surface

The package declares no Cargo features. It ships one binary flavour with Bus
client and citizen support always enabled.

The `mixos-lib-mix` dependency enables its JSON, regular-expression, TOML,
date/time, URL, cryptography, HTTP, SQLite, Tokio sleep, DKIM, serde, Markdown,
Datastar, and XML capabilities. Other direct dependencies provide:

| Group | Crates |
|---|---|
| Bus | `mixos-lib-bus`, `mixos-lib-client`, `mixos-lib-buildinfo`, `mixos-lib-props-core`, `mixos-lib-log` |
| Interactive shell | `rustyline`, `dirs`, `libc` |
| Async runtime | `tokio`, `tokio-util` |
| Data and utilities | `serde`, `serde_json`, `glob`, `indexmap`, `chrono`, `ureq`, `tracing` |
| Tests | `proptest` |

`mixos-lib-props-core` is built with its `bus` feature and without default
features. `mixos-lib-client` is built with its `native` feature.

## Build information

The build script emits the repository revision, dirty state, and build time.
Serve mode supplies that provenance when it registers the citizen. `INFO`
reports the `mix` package version because a served script has no separate
binary version.

## Limits

- The package has no embeddable library API; use `mixos-lib-mix` to embed the
  language.
- The local node configuration reader is deliberately narrow and read-only.
- Serve mode provides property conformance through L1. It does not provide
  runtime-owned property watch, mutation, or world aggregation.
- Serve-mode log filtering is configured through `RUST_LOG` and a restart; the
  package does not include the Cos-side mutable property store.

---

<!-- page: https://mixos.dev/mix/mix-shell/cli/ (source: https://mixos.dev/mix/mix-shell/cli.md) -->

# Command-line interface

The `mix` command is the shell of the `mix-shell` package, built into the
system binary by `cli/system`. The command is an
interactive shell, a Mix program runner, a shell-compatible `-c` dispatcher,
and a collection of reference, diagnostic, and maintenance subcommands.

## Usage

```text
mix
mix [GLOBAL-OPTIONS] FILE [ARG...]
mix [GLOBAL-OPTIONS] -c CODE [ARG...]
mix -i -c CODE [ARG...]
mix [GLOBAL-OPTIONS] - [ARG...]
mix --check FILE
mix lint [LINT-OPTIONS] FILE...
mix SUBCOMMAND [ARG...]
mix --serve FILE [--name SERVICE] [--no-prelude]
```

Global options precede a script path. Arguments after a normal script path,
`-c` code string, or `-` are positional arguments for the Mix program.

## Primary options

| Option | Effect |
|---|---|
| `-h`, `--help` | Prints the capability overview. |
| `-V`, `--version` | Prints the `mix` version line. |
| `--builtins` | Prints the full builtin catalogue. |
| `--no-prelude` | Skips the standard prelude in script, command, or serve evaluation. |
| `--no-traceback` | Uses legacy single-line rendering for uncaught file and command-mode errors. |
| `--strict-arity` | Makes wrong-arity function and builtin calls raise `ARITY_MISMATCH`. |
| `--check FILE` | Lexes and parses a file without executing it. |
| `-c CODE` | Runs one classified command line. |
| `-i` | When used with `-c`, loads `~/.mixrc` before running the code. |
| `-ci`, `-ic` | Combined spellings of `-i -c`. |
| `--serve FILE` | Starts the supervised Bus citizen mode described in [Serve mode](serve-mode.md). |

Without `--strict-arity`, missing arguments bind to `nil` and extra arguments
are ignored. Tracebacks remain the default when an error crosses a function or
builtin boundary.

## Script arguments

For a file, `$0` is the script path and `$1`, `$2`, and later variables hold
the remaining arguments. For `mix -`, `$0` is `-`. Command mode assigns its
arguments from `$1`; it does not set a script filename.

`include` resolves relative content using the active script file. The
standard-input form has no temporary remote file and is executed only when the
explicit `-` operand is present.

## Command mode

`mix -c CODE` uses the REPL classifier rather than assuming that `CODE` is Mix
source. It may execute:

- Mix statements or expressions.
- A simple bareword call to a user-defined Mix function.
- An external command, pipeline, redirection, background launch, or command
  list.
- The in-process `cd` and `exit` builtins.

The exit status of an external command becomes the `mix` exit status. Spawn
failure returns 127. A signal result is converted to `128 + signal` on Unix.
Mix parse or runtime errors return 1.

`-i` sources `~/.mixrc` before classification, making its aliases, functions,
and `PATH` changes available. Command mode otherwise loads the prelude but does
not load the rc file.

## Interactive shell

The REPL loads the prelude, then loads a regular-file `~/.mixrc` when `HOME` is
available. It stores readline history in `~/.mix_history`.

Input classification follows this broad order:

1. Expand the first-word alias.
2. Route Mix keywords and variable-led forms to the Mix parser.
3. Route a simple call whose head names a Mix function to that function.
4. Route shell builtins and commands found on `PATH` to shell execution.
5. Surface a Mix parse error or command-not-found result for the remaining
   input.

The shell recognises pipelines, file-descriptor redirections, environment
prefixes, variable and tilde expansion, brace and glob expansion, command
substitution, background `&`, and `&&`, `||`, and `;` lists. Expansions cannot
inject new structural command-list operators.

REPL shell builtins are `cd`, `pushd`, `popd`, `history`, `exit`, `which`,
`type`, `unalias`, `jobs`, `fg`, `bg`, and `mix`. Files executed by `source`
support `cd` and `exit`; stateful REPL-only builtins are rejected there.

`time LINE` and `mix time LINE` time either Mix or shell input in the REPL.
`trace`, `history`, and `reload` are also REPL-only meta-command surfaces.

## One-shot subcommands

The following names are recognised before the command attempts to open a
same-named script. Use an explicit path such as `./build` for a script that
collides with a subcommand name.

| Group | Commands |
|---|---|
| Session inspection | `vars`, `aliases`, `functions`, `all`, `type`, `config`, `status`, `context`, `snapshot` |
| Reference | `help`, `tutorial`, `examples`, `man`, `keywords`, `builtins`, `what`, `syntax`, `operators`, `diff` |
| Project maintenance | `build`, `clean`, `update`, `test`, `self` |
| Validation | `check`, `lint` |
| Bus discovery | `mesh`, `ports`, `ping` |
| AI integration | `fix`, `extend`, `review`, `explain`, `evolve`, `dogfood`, `fuzz`, `teach`, `ask`, `chat` |
| Service tools | `deploy`, `health`, `logs` |
| Claude port tools | `claude-start`, `claude-stop`, `claude-status` |
| Automation | `watch` |
| Usage data | `stats` |

One-shot session inspection uses a fresh evaluator. It therefore has no user
variables, aliases, or functions unless the command itself loads them.

`builtins` accepts `--json`, `--data`, `--names`, one builtin name, or one
category. `syntax` opens the variables manual page and `operators` opens the
operators page.

The AI commands and the `ai`, `ai_diagnose`, and `context` extension functions
invoke an external Claude command-line program. Build and maintenance commands
invoke tools such as Cargo and Git. Service commands invoke local service and
logging tools.

## Lint

```text
mix lint [--json | --data] [--deny-warnings]
         [--allow-global NAME]... [--allow-function NAME]...
         FILE...
```

`-` reads standard input and may appear once. Human diagnostics and structured
reports go to standard output. Usage and internal errors go to standard error.

| Status | Meaning |
|---|---|
| 0 | No errors; warnings are allowed unless denied. |
| 1 | Error diagnostics, or warnings with `--deny-warnings`. |
| 2 | Invalid usage, unreadable input, or internal analyser failure. |

JSON and strict-data reports include schema version 1, tool and Mix versions,
input files, diagnostics, capabilities, and an error/warning summary.

## Statistics

`mix stats` reports tracked builtins, functions, aliases, external commands,
keywords, meta-commands, errors, and sessions. Its subcommands are:

```text
builtins functions aliases commands keywords meta errors sessions
never all raw reset clear week query trend since help
```

Each run appends one record to `runs/YYYY-MM-DD.jsonl` under the stats
directory; reports aggregate the raw days, using an advisory per-day cache.
`query` loads the store into an in-memory SQLite database with the tables of
the old `mix.db`.

## Files and environment

| Name | Purpose |
|---|---|
| `~/.mixrc` | Interactive and `-i -c` startup file. |
| `~/.mix_history` | Readline history. |
| `node.conf.mix` | Read-only broker address input; see [Serve mode](serve-mode.md). |
| `MIXOS_NODE_CONFIG` | Overrides the node configuration file path. |
| `MIXOS_SRC` | Overrides the MixOS source/documentation root used by project and manual commands. |
| `MIXOS_ETC` | Overrides the MixOS configuration directory. |
| `MIXOS_BIN` | Overrides the install directory used by `mix build`. |
| `MIXOS_MAN_SOURCE` | Selects `auto` or `local` manual resolution. |
| `MIXOS_MAN_URL` | Overrides the canonical manual base URL. |
| `XDG_CACHE_HOME` | Sets the manual cache root; it must be absolute to be used as an XDG path. |
| `XDG_STATE_HOME` | Sets the usage-statistics root; it must be absolute. |
| `MIX_STATS=0` | Disables statistics for the process. |
| `MIX_DEBUG` | Enables warnings for statistics path and persistence failures. |
| `HOME` | Supplies rc, history, cache, state, and user-mode defaults. |
| `PATH` | Supplies external-command discovery and completion. |
| `RUST_LOG` | Overrides serve-mode log filtering. |

Manual pages are fetched in automatic mode, cached for 24 hours, and fall back
to a local checkout or stale cache when the network request fails. Local mode
does not fetch from the network.

---

<!-- page: https://mixos.dev/mix/mix-shell/serve-mode/ (source: https://mixos.dev/mix/mix-shell/serve-mode.md) -->

# Serve mode

`mix --serve` runs a Mix script as a long-lived, supervised Bus citizen. The
runtime registers one service identity, executes the script's initialisation
body, and then runs an unconditional event pump for author-defined `on`
handlers and runtime-reserved verbs.

## Synopsis

```text
mix [--no-prelude] [--strict-arity] \
  --serve citizen.mix [--name alpha] [--no-prelude]
```

After the script path, serve mode accepts only `--name SERVICE` and
`--no-prelude`. It does not pass positional arguments to a served script.
`$0` is set to the script path.

## Service identity

`--name` takes precedence. Without it, the service name is the script's file
stem:

```text
citizen.mix        -> citizen
alpha.worker.mix   -> alpha.worker
```

A leading `mixos-` prefix is removed from either the explicit name or derived
file stem. Empty names and names beginning with `.` are rejected before the
broker connection. The broker performs the remaining identifier validation.

The registered provenance contains the `mix` package, version, repository
revision, dirty state, build time, and a current RFC 3339 timestamp.

## Startup

Serve mode performs these operations in order:

1. Initialises structured logging.
2. Reads, lexes, and parses the script.
3. Resolves the broker URL.
4. Establishes a supervised connection and registers the service name.
5. Constructs an evaluator with the serve Bus handler and reserved runtime.
6. Loads the prelude unless disabled.
7. Executes the initialisation body and enters the event pump.

An unreadable script, lexer or parser failure, logging failure, runtime creation
failure, exhausted initial connection budget, or initialisation error exits
non-zero. Initial broker connection failure is fatal; it does not enter a
background retry loop before the first registration succeeds.

## Supervision

`MixServeHandler` wraps one `SupervisedClient`. All requests, emits, replies,
registrations, and topic operations use that connection. Serve mode does not
route simple names through the transient local-port shortcut.

After registration, a broker interruption is treated as transient. The client
reconnects, re-registers the service, and replays its topic-subscription
registry. Its incoming receiver survives those reconnects. A terminal receiver
close ends the event pump.

Calling `bus_reconnect()` is unnecessary in serve mode; the supervised client
owns recovery.

## Runtime-reserved verbs

The runtime checks reserved verbs before author handlers. A script cannot
shadow them.

| Command | Arguments | Result |
|---|---|---|
| `HELP` | None | JSON array of accepted commands. |
| `INFO` | None | JSON object containing `name`, `version`, and `description`. |
| `QUIT` | None | Replies with status 0 and `{}`, then starts graceful shutdown. |
| `SERVICE.props.get` | Optional `path` | Returns the root property snapshot or one value. |
| `SERVICE.props.list` | None | Returns all defined lifecycle leaf paths. |
| `SERVICE.props.describe` | Required `path` | Returns type and property metadata for one path. |

Replace `SERVICE` with the registered name. For example:

```text
alpha.props.get
alpha.props.list
alpha.props.describe
```

`HELP` lists the six runtime commands first. It then appends sorted,
deduplicated author-handler command names. Author handlers that collide with a
reserved name are omitted because they are unreachable.

`INFO.version` is the `mix` runtime version. A served script does not provide a
separate executable version.

For property commands, a successfully parsed Bus `args` header takes
precedence. When the header is absent or cannot be parsed, the runtime parses
the request body as JSON. An empty request selects the root snapshot.

## Lifecycle properties

The property tree is read-only and reports L1 conformance.

| Path | Type | Value |
|---|---|---|
| `lifecycle.started_at` | string | RFC 3339 process start time. |
| `lifecycle.uptime_s` | number | Live seconds since process start; marked transient. |
| `lifecycle.mode` | string | `serving`. |
| `lifecycle.health` | string | `ok`. |
| `lifecycle.props_level` | string | `L1`. |

The runtime uses the shared Bus property encoder with sensitive-value redaction
enabled.

`props.watch`, `props.set`, and `props.delete` are not runtime-reserved. The
runtime does not provide L2 watches, property mutation, or world aggregation.
An author may define handlers with those names as domain behaviour.

## Author handlers

The script defines domain commands with Mix `on` handlers. The event pump
receives the Bus command, headers, and body through the supervised connection.
The evaluator supplies replies through the same connection and preserves
application return codes separately from transport failures.

Request-style sends await a reply. Map arguments use Bus header/body routing
when a `body` key is present or the command is a property command. Emits are
fire-and-forget and use header/body routing for map arguments.

Application error return codes remain application results. A transport failure
raises a mesh-unavailable runtime error.

## Broker configuration

The broker URL is resolved from the first applicable source:

1. The file named by `MIXOS_NODE_CONFIG`.
2. `node.conf.mix` under the resolved MixOS configuration directory.
3. The system `node.conf.mix`, unless `MIXOS_ETC` explicitly isolates the
   configuration directory.

The reader consumes only these strict-data fields:

```text
wg_ip: "192.0.2.5"
noded: { port: 4200 }
```

Unknown fields and sections are ignored. An absent `wg_ip` uses loopback. An
absent `noded.port` uses 4200. When no file exists, or the selected file cannot
be read or parsed, the URL falls back to the loopback broker on port 4200.

The first existing file is authoritative. A parse failure does not continue to
a later candidate. The resolver never writes or migrates node configuration,
and it does not read a legacy TOML format.

## Logging

Serve mode uses the shared logging core with a journald-first preset. It enables
standard error when no journal socket is available and also for a foreground
run attached to a terminal. Structured entries carry the registered service
name. `RUST_LOG` overrides the default filter.

There is no live property-backed log-filter mutation in this package. Change
`RUST_LOG` and restart the citizen to change filtering.

## Shutdown

SIGTERM, Ctrl-C, `QUIT`, and a terminal event-pump close converge on one
shutdown path:

1. Stop accepting new inbound work.
2. Deregister from the broker with a five-second bound.
3. Drain in-flight asynchronous handler tasks.
4. Abort remaining tasks and synthesise shutdown replies when the connection
   can still deliver them.
5. Exit.

A clean interrupt, `QUIT`, or clean pump end returns status 0 when
deregistration succeeds or the connection is already gone. Script failure,
deregistration failure, or expiration of the deregistration bound returns a
non-zero status.

---

<!-- page: https://mixos.dev/mix/modules/ (source: https://mixos.dev/mix/modules.md) -->

# modules — require, include, source

Three ways to pull another `.mix` file into a running script, on a spectrum
from **isolated** to **splice-into-my-scope**:

| | `require(path)` | `include "path"` | `source "path"` |
|---|---|---|---|
| Form | expression (builtin, returns a value) | statement | statement |
| Caller's scope | **untouched** — exports come back as a value | file's fns + `$vars` land in the caller's scope | same as include |
| Runs | once per canonical path (cached) | once per canonical path (deduped, returns nil on repeat) | every time |
| Path resolution | script-relative, then CWD | script-relative, then CWD | CWD only |
| Parse failure | hard error | hard error | may fall back to per-line shell (`.mixrc`-style) |
| Capability | `fs-read` | `fs-read` | `fs-read` |

> **Script-relative follows symlinks** (0.74.0): the entry script's path is
> canonicalised before its directory is taken, so the symlinked-launcher
> pattern (`~/.local/bin/x -> repo/_bin/x.mix`) resolves `../_lib/…`
> against the repo the script lives in. Before this, every such launcher
> silently depended on being run from the right CWD.

`require` is the module loader: it evaluates the file in a **fresh, fully
isolated scope** and hands back its exports — the caller's variables and
functions cannot be clobbered, and the module cannot see them. `include` is
the trusting opposite: a splice that shares helper functions into your scope.
`source` is shell-style config loading.

## require in one example

```mix
-- strutil.mix ------------------------------------
$version = "1.0"
$_sep = "-"                          -- '_' prefix: private, not exported
function _squash($s)                 -- private helper
  return replace($s, "  ", " ")
end
function slugify($s)
  return lower(replace(_squash($s), " ", $_sep))
end

-- main.mix ---------------------------------------
$str = require("strutil.mix")
print($str.version)                  -- 1.0
print($str.slugify("Hello  World"))  -- hello-world
$f = $str.slugify                    -- extract-then-call works too
print($f("A B"))                     -- a-b
```

## What gets exported

- By default: a **map** of every top-level function and `$var`, minus names starting with `_` (private by convention), the implicit frame names (`rc`, `result`, `status`, `event`), and prelude functions the module didn't redefine.
- A top-level `return <expr>` **replaces** auto-export entirely — the file can return a map, a single function, a number, anything (Lua-style). Only an explicit `return` does this; an incidental value in the last statement does not.
- A side-effect-only module exports `{}` — `require` doubles as "run this file exactly once".

## Module semantics

- **Cached once per canonical path.** The module body runs on the first `require`; later requires (any relative spelling, symlinks included) return a fresh copy of the cached exports without re-running the body. Mutating the returned map never affects the cache. Exception: an exported `Buffer` is reference-semantic as always — every require-hit shares it.
- **Cycles are hard errors** (`a.mix -> b.mix -> a.mix` reports the chain), as is nesting deeper than 64 requires. A require that fails (missing file, parse error, runtime error) caches nothing — fix the module and require again.
- **Exported functions keep working**: they can call the module's other functions (including `_`-privates) and read the module's top-level `$vars`. Those vars are injected **by value per call** — writes inside a call don't persist to the next call. Module-level mutable state is not a thing; return state to the caller instead.
- **Nested `require` is module-relative**: a module requiring `"sibling.mix"` resolves next to itself, transitively.
- **What a module sees**: builtins, HOFs, the prelude (iff the program loaded it), extensions, `env()`/`args()`/process state, and further `require`s. It does NOT see the caller's `$vars`, functions, `~/.mixrc`, or an enclosing `address` block. It runs under the caller's capability policy and eval limits — `require` is not a sandbox escape.
- A free name in a module function that is **not** a module top-level resolves against the *requiring program's* globals at call time, like any named function. Define what you use at the module top level.
- `alias` and `export NAME=` at module top level affect the shared program state (documented, allowed); registering an `on` handler from a module is an **error**.

## Calling exports — precedence

`$m.foo(args)` dispatches **member-first** since 0.72.0: when `$m` has a
**function-valued** member `foo`, that member is called (the flip that made
exports named `sum`/`lines` reachable via dot-call — from 0.27.0 to 0.71 a
free/prelude name won instead and the prelude ran on the stringified map).
When no such member exists, the call is the usual UFCS sugar (`$list.map($f)`,
`$s.upper()`), then an address-block send. The member wins in **every**
mode, `--serve` included (0.117.0): before that a serve citizen's
`$r.context({})` ran the mix shell's `context()` extension instead of the
module's export. One collision survives:

- An export named after a **builtin** must still be called via the index form (`$m["keys"](...)`) — a builtin-named dot-call desugars at parse time, before the member can be seen.

A bare `context()` in the module itself still runs the extension, which
beats a user function at a bareword call; `mix lint` reports a function
named after a shell extension (`ai`, `ai_diagnose`, `context`) as
`MIX-W2313`.

`mix lint` reads a module bound once to a literal path
(`$m = require("./lib.mix")`) and checks member calls against its exports:
`MIX-W2314` for the wrong number of arguments, `MIX-W2315` for a name the
module does not export. It stands down for a dynamic path, a rebound `$m`,
and a module whose top-level `return` or `source`/`include` decides its
exports.

The index form `$m["foo"](...)` calls the member unconditionally and remains
the collision-proof spelling.

`$m.foo` (no call) extracts the function value; `$f = $m.foo` then `$f(x)`
always calls the member, collisions or not.

Also new with require: a **Function-valued variable is callable bareword** —
`$b = function() ... end` then `b()` — wherever no builtin/named function of
that name exists.

## When to use which

- Reach for **`require`** for anything library-shaped: namespaced helpers, shared constants, run-once setup. It is the only loader safe against name collisions in both directions.
- Reach for **`include`** when you *want* the file's functions unprefixed in your scope (a project's helper set) and you own both files.
- Reach for **`source`** for `.mixrc`-style config that may mix Mix with bareword shell lines and must re-run each time.

---

<!-- page: https://mixos.dev/mix/numbers/ (source: https://mixos.dev/mix/numbers.md) -->

# Numbers

Mix has **one numeric type: a 64-bit IEEE-754 double (`f64`)**. There is no separate integer type — `5`, `5.0`, `1e6`, `0xFF`, and `0o755` are all the same `Number` value under the hood. What makes Mix *feel* like it has integers is the printer: a number that is exactly representable as an `i64` is written without a decimal point (`5`, not `5.0`). This page covers that f64 model, integer-clean formatting, the `0o`/`0x`/`0b` radix literals (and why a bare leading zero is a lexer error), scientific-notation literals, strict numeric-string coercion, `NaN`/`inf` behaviour, the ordering rules, and how whole numbers cross serialization boundaries as integers.

For the numeric *functions* (`round`, `floor`, `sqrt`, `pow`, `abs`, …) see [math](math.md). For the comparison and arithmetic *operators* see [operators](operators.md).

> One-line model: **every number is an f64; it prints as an integer when it round-trips through `i64`; `0o`/`0x`/`0b` and `1e6` are sugar for the same f64; a bare leading zero is rejected.**

## One type: f64

```mix
print(2 + 2)        -- 4
print(10 / 2)       -- 5      (whole result, prints clean)
print(7 / 2)        -- 3.5    (fractional, prints with a point)
print(10 / 4)       -- 2.5
print(2.5)          -- 2.5
print(1.0)          -- 1      (1.0 round-trips through i64 → printed as 1)
print(-5)           -- -5
print(17 % 5)       -- 2      (modulo)
```
```text
4
5
3.5
2.5
2.5
1
-5
2
```

Because the type is f64, integer division is *not* a separate operation — `/` is always float division and `10 / 2` happens to land on a whole number. There is no `//` floor-division operator; use [`floor`](math.md) if you want it.

### f64 caveats apply

Mix inherits every IEEE-754 wrinkle. Fractions are binary, so the classic rounding error is visible:

```mix
print(0.1 + 0.2)    -- not exactly 0.3
```
```text
0.30000000000000004
```

Integers stay exact only up to **2^53** (`9_007_199_254_740_992`). Past that, even whole numbers lose precision:

```mix
print(9007199254740992)   -- 2^53, exact
print(9007199254740993)   -- 2^53 + 1, rounds back down
```
```text
9007199254740992
9007199254740992
```

That 2^53 boundary is why [`stat`](builtins.md) returns inode/device numbers as **strings**, not numbers — a u64 inode above 2^53 would lose its low bits as an f64.

Division **and modulo** by zero are runtime errors (not `inf`/`NaN`), but a math function can still produce a non-finite value:

```mix
print(1 / 0)        -- runtime error
```
```text
Runtime error at line 1: division by zero
```
```mix
print(5 % 0)        -- runtime error too (0.21+; it used to return NaN silently)
```
```text
Runtime error at line 1: modulo by zero
```
```mix
print(sqrt(-1))     -- NaN (from math, not an error)
print(ln(0))        -- -inf
print(exp(1000))    -- inf (overflow)
```
```text
NaN
-inf
inf
```

Once a non-finite value exists it **propagates** through arithmetic per IEEE-754 (`exp(1000) + 1` is `inf`, `1 / exp(1000)` is `0`) and prints as `NaN` / `inf` / `-inf`. Comparisons involving a `NaN` *value* follow IEEE-754 too — they are `false`, not errors:

```mix
print(sqrt(-1) == sqrt(-1))   -- false (NaN is never equal to anything)
print(sqrt(-1) < 5)           -- false (any ordering against NaN is false)
```
```text
false
false
```

## Integer-clean printing

When Mix renders a number — via `print`, `${...}` interpolation, `..` concatenation, or inside a list/map — it uses an **i64 round-trip gate**: if `(n as i64) as f64 == n`, it prints the i64 form (no decimal point); otherwise it prints the full f64 (`value.rs::write_mix`). The gate is the exact i64 cast, not merely "is it integral", so a value too big for i64 (like `1e20`) still prints in f64 form instead of silently saturating. (One pinhole: exactly 2^63 passes the gate through the saturating cast and prints as `9223372036854775807` — one below the true f64 value. Anything past 2^53 is approximate territory anyway.)

Output is always plain decimal — the printer never uses exponent form, even for values you *wrote* in scientific notation: `print(1e20)` gives `100000000000000000000`, `print(1e-10)` gives `0.0000000001`.

```mix
print(4.0 / 2.0)          -- 2     (whole → integer form)
print(3.0 * 3.0)          -- 9
$n = 5
print("count is ${n}")    -- interpolation: clean
print("id-" .. $n)        -- concat: clean
$f = 2.5
print("val ${f}")         -- fractional stays fractional
```
```text
2
9
count is 5
id-5
val 2.5
```

Every render path shares this gate, so a number looks the same whether you `print` it, splice it into a string, or nest it in a structure.

## Radix literals — `0o` / `0x` / `0b`

For file modes and bitmasks, write the value in its natural base. All three prefixes are pure sugar that lex to the same f64 (`lexer.rs::lex_radix_number`):

| Prefix | Base | Example | Value |
|---|---|---|---|
| `0o` / `0O` | octal | `0o755` | 493 |
| `0x` / `0X` | hex | `0xFF` | 255 |
| `0b` / `0B` | binary | `0b101` | 5 |

```mix
print(0o755)            -- 493
print(0xFF)             -- 255
print(0b101)            -- 5
print(0o755 == 493)     -- true  (it IS the f64 493)
```
```text
493
255
5
true
```

`_` digit separators are allowed anywhere in the body for readability — in decimals too:

```mix
print(1_000_000)        -- 1000000
print(0xFF_FF)          -- 65535
print(0b1010_1010)      -- 170
```
```text
1000000
65535
170
```

Radix literals are checked at lex time. A digit out of range, an empty body, or a value past 2^53 is a clear lexer error rather than a silently-split or silently-rounded token:

```mix
print(0o78)             -- 8 is not an octal digit
```
```text
Lexer error at line 1:7: '8' is not a valid octal digit in a 0o literal
```
```mix
print(0xG)              -- no hex digit
print(0x)               -- empty body
print(0x20000000000001) -- past 2^53
```
```text
Lexer error at line 1:7: 'G' is not a valid hex digit in a 0x literal
Lexer error at line 1:7: 0x literal has no digits
Lexer error at line 1:7: 0x20000000000001 exceeds the exact-integer range (2^53); Mix numbers are f64
```

The token boundary is precise: only an *alphanumeric* follower is a bad digit. An operator, `.`, space, or `)` is a legitimate end of the literal — `0xFF+1`, `0o7 .. "x"`, and `0b101)` all lex fine.

Use these for [native `chmod`/`write_new`](builtins.md), where the mode is the f64 *value*: `chmod($path, 0o755)`, `write_new($path, $body, 0o600)`.

### No bitwise operators

Mix has **no** `&` / `|` / `^` / `<<` / `>>` operators and no bitwise builtins. `^` is not a power operator either — the power operator is [`**`](operators.md) (or the [`pow`](math.md) builtin). A bare `&` is a lexer error nudging you toward `&&`:

```mix
print(2 ^ 10)           -- '^' is not an operator
```
```text
Lexer error at line 1:9: unexpected character '^'
```
```mix
print(2 ** 10)          -- ** is the power operator (real powf)
print(pow(2, 10))       -- same thing as a builtin
```
```text
1024
1024
```

## The bare-leading-zero trap

A decimal integer **must not** start with a redundant `0`. Rust's f64 parser would silently read `0755` as `755`, which is a footgun for a substrate whose daily work is octal file modes. Mix rejects it at lex time and tells you the fix (`lexer.rs::lex_number`):

```mix
print(0755)
```
```text
Lexer error at line 1:7: ambiguous leading-zero number '0755' — use a 0o (octal) / 0x (hex) / 0b (binary) prefix, or drop the leading zero(s) for decimal
```

This is a **Mix-expression** hazard, not a shell one. When `0755` is a *string* (an argument in a shell-out), nothing is lexed as a number, so `run("install -m 0755 a b")` is fine. The error only fires when `0755` would be a Mix *number* literal.

Plain `0` and genuine fractions are unaffected — the rule looks only at the integer part:

```mix
print(0)        -- 0
print(0.5)      -- 0.5
print(0.05)     -- 0.05
```
```text
0
0.5
0.05
```

## Scientific-notation literals

The lexer accepts an `[eE][+-]?digits` exponent on a decimal literal (0.20.5+; earlier versions parse-errored on `1e3`). It is sugar for the same f64 — `_` separators work in the exponent too:

```mix
print(1e6)          -- 1000000
print(1.5e3)        -- 1500
print(2e-3)         -- 0.002
print(1E3)          -- 1000
print(1e+2)         -- 100
print(1e1_0)        -- exponent 10
```
```text
1000000
1500
0.002
1000
100
10000000000
```

Two deliberate edges:

- The `e`/`E` is only consumed when a digit (after an optional sign) actually follows, so the [`e()`](math.md) Euler-constant builtin is never eaten — `2 * e()` is `5.43656…`, and a bare `2e` lexes as `2` followed by the token `e`.
- The exponent is checked *after* the leading-zero rule, which sees only the mantissa: `0e5` is a valid `0`, but `07e2` is still the ambiguous-leading-zero lexer error (see above).

Radix literals take no exponent — `0x1e3` is just hex digits (`483`).

## Coercion and numeric strings

`to_number(s)` converts a value to an f64, or returns `nil` on failure (`value.rs::to_number`):

```mix
print(to_number("42"))     -- 42
print(to_number("3.14"))   -- 3.14
print(to_number("1e3"))    -- 1000 (exponent strings parse)
print(to_number("  7 "))   -- 7    (whitespace trimmed)
print(to_number(true))     -- 1    (bools coerce: true→1, false→0)
print(to_number("abc"))    -- nil  (not a number)
print(to_number("0xFF"))   -- nil  (radix prefixes are SOURCE syntax, not parseable at runtime)
```
```text
42
3.14
1000
7
1
nil
nil
```

`to_number` parses a *decimal* string (sign, fraction, exponent). `"abc"` and `"0xFF"` both fail (the f64 parser doesn't accept a `0x` prefix), so guard for `nil` if the input is untrusted.

**String coercion is strict about non-finites** (0.21+). Rust's f64 parser happens to accept the words `"inf"` / `"infinity"` / `"nan"` (any case), but those are not Mix numeric strings — and an overflowing spelling like `"1e999"` is unrepresentable:

```mix
print(to_number("inf"))    -- nil
print(to_number("nan"))    -- nil
print(to_number("1e999"))  -- nil (overflows f64)
print(is_number("inf"))    -- false (is_number agrees with to_number)
print(is_number("1e3"))    -- true
```
```text
nil
nil
nil
false
true
```

Only *string* coercion is strict. A non-finite number **value** passes through untouched — `to_number(sqrt(-1))` is `NaN`, and `is_number(sqrt(-1))` is `true` (it *is* a number; math keeps propagating IEEE-754 non-finites).

Arithmetic operators auto-coerce a numeric *string* operand, so light shell-style input just works:

```mix
print("5" + 3)             -- 8   (string "5" coerces to 5)
```
```text
8
```

`to_number` itself returns `nil` on failure because it is the explicit probe.
Builtins and numeric language forms that require a number do not turn that
failure into `0`: they accept the same numeric strings and bools, but a supplied
unparseable value raises `TYPE_MISMATCH`. Since 0.55.0 this is consistent across
string positions/counts, `range`, numeric `for`, date/format helpers, `sleep`,
`exit(code)`, and arithmetic `/`/`%` operands.

Equality treats a number and its numeric-string form as equal, and `5 == 5.0` is true because they are the same f64:

```mix
print("5" == 5)            -- true
print(5 == 5.0)            -- true
```
```text
true
true
```

## Ordering rules

The comparison operators `< > <= >=` follow a two-step rule (see [operators](operators.md) for the full table):

1. **If *both* operands coerce to numbers** (numbers, or numeric strings like `"5"`), compare **numerically**.
2. Else, **if both are strings**, compare **lexicographically by codepoint**.
3. Otherwise — a string-vs-number mix where the string isn't numeric — raise an error.

```mix
print("5" < "10")     -- true  (both numeric → 5 < 10, NOT string order)
print(5 < 10)         -- true
print("apple" < "banana")  -- true  (both non-numeric strings → lexicographic)
print("5" < "abc")    -- true  ("5" < "abc" lexicographically; not both numeric)
print(5 >= 5)         -- true
print(3 != 4)         -- true
```
```text
true
true
true
true
true
true
```

The footgun bash brings is the *opposite* of Mix here: `"5" < "10"` is **numeric** (true), because both strings coerce. You only fall back to string ordering when at least one side won't coerce to a number. A genuine type clash errors rather than guessing:

```mix
print(5 < "abc")
```
```text
Runtime error at line 1: cannot compare 'abc' as number
```

## Modulo sign

`%` follows the f64 remainder (the result takes the sign of the **dividend**, like C/Rust `%`, *not* Python's floored modulo):

```mix
print(-7 % 3)     -- -1   (sign of -7)
print(7 % -3)     -- 1    (sign of 7)
print(5.5 % 2)    -- 1.5  (works on non-integers too)
```
```text
-1
1
1.5
```

A zero divisor is a runtime error (`modulo by zero`), matching `/` — see the caveats section above.

## Serialization: whole numbers travel as integers

Because the one type is f64, every serialization boundary decides whether a whole value leaves as an *integer* or a *float*. Mix consistently picks **integer for whole numbers**, so a peer field typed `usize`/`i64` accepts it:

- **[`json_encode`](data.md)** — a finite whole number in `[-2^63, 2^63)` encodes as a JSON integer; anything else (fractional, or ≥ 2^63) encodes as a JSON float (`json.rs::mix_to_json`). The upper bound is exclusive because `i64::MAX as f64` rounds up to exactly 2^63 — an f64 of 2^63 encodes as the real `9.223372036854776e+18` instead of silently saturating.
- **[`sqlexec`](builtins.md) binds** — the same rule, typed: a whole finite number binds as SQLite `INTEGER`, fractional/non-finite as `REAL` (nil→`NULL`, bool→`0`/`1`, string→`TEXT`, bytes→`BLOB`).
- **[Bus `send` args](bus.md)** — a whole number within ±2^53 serializes as a JSON integer (`limit=2` reaches the peer as `2`, not `2.0`); fractional values stay floats.

```mix
print(json_encode(2))            -- 2 (integer, not 2.0)
print(json_encode(2.5))          -- 2.5
print(json_encode([1, 2.5, 3]))  -- [1,2.5,3]
```
```text
2
2.5
[1,2.5,3]
```

### Non-finite numbers refuse to serialize

`print` happily shows `NaN`/`inf`, but the serializers are **loud** about a non-finite number anywhere in the value — there is no JSON or strict-data representation for it:

- **`json_encode`** raises a catchable error (0.21+; it used to encode `0` silently): `json_encode: non-finite number NaN has no JSON representation (JSON has no NaN/Infinity)`.
- **[`data_encode`](data.md)** and the strict-data writers refuse likewise (`value.rs::write_mix_data`): `data_encode: Data serialize error: non-finite number NaN has no strict-data representation`.

Keep generated config values finite, or `try`/`catch` the encode ([errors](errors.md)).

## See also

- [math](math.md) — `round` / `floor` / `ceil` / `trunc` (each takes an optional decimal-places arg; negative rounds to tens/hundreds), `abs`, `sqrt`, `pow`, `min`/`max`/`clamp`, trig, `pi()`/`e()` — all propagate `NaN`/`inf` instead of erroring
- [operators](operators.md) — arithmetic incl. `**` power, the full comparison/ordering table, `and`/`or`/`not`
- [strings](strings.md) — `..` concatenation, `${...}` interpolation, codepoint counting
- [builtins index](builtins.md) — `to_number`, `chmod` / `write_new` (mode is the f64 value), `stat` (ino/dev as strings), `sqlexec` typed binds
- [data](data.md) — `json_encode` / `data_encode` serialization (both reject non-finite numbers)
- [bus](bus.md) — `send` arg serialization (whole numbers as JSON integers)
- The repo: <https://github.com/markc/mixos>
- `mix help` for the topic list; `mix what to_number` (or `round`, `pow`, …) for a one-line builtin reference

---

<!-- page: https://mixos.dev/mix/operators/ (source: https://mixos.dev/mix/operators.md) -->

# operators — arithmetic, concat, comparison & boolean

Every operator Mix's expression grammar knows, with verified precedence and the
exact coercion rules. Statements use newline or `;` separators, every
variable is `$`-sigil, and string concatenation is **`..`** — not `+`, not `.`.
The binary is the oracle; page stamps are held fresh by `cargo test -p system --test man_pages`.

## Precedence & associativity

From the parser (`parse_binary_rhs`, `parser.rs`). **All binary operators are
left-associative** — including `**`. Higher number = binds tighter.

| Prec | Operators | Meaning |
|---|---|---|
| 0 | `? :` | ternary conditional (short-circuit, **right-associative**) |
| 1 | `or` | logical OR (short-circuit) |
| 2 | `and` | logical AND (short-circuit) |
| 3 | `==` `!=` `<` `>` `<=` `>=` `eq` `ne` | comparison (no chaining) |
| 4 | `??` | nil-coalesce (short-circuit) |
| 5 | `..` | string concatenation |
| 6 | `+` `-` | add / subtract (or `+` string-fallback) |
| 7 | `*` `/` `%` | multiply / divide / modulo |
| 8 | `**` | power |

Unary `-` (negate) and `not` / `!` (logical not) bind tighter than every binary
operator. Parenthesise to override.

`&&` and `||` are **statement-chain operators**, and `;` is a statement
separator rather than an expression operator, so none appears in this table.
An assignment cannot be any operand of a **Mix-classified** chain: use `and` /
`or` inside an assigned logical expression, or put shell-style conditional
execution in a separate statement. This rejects both `$ok = $a.ok && $b.ok` and
`print("gate") && $ok = false`, and neither line's operands run.
A line keeps bash semantics instead only when the classifier routes it to the
shell *and* the Mix parse gives out before reaching the assignment — a
path-shaped head, a redirect, an env prefix. Neither half is enough alone:
`print(1); echo hi` fails to parse yet stays a Mix error, and `true && $x =
false || cmd` has a shell-command head yet parses far enough to be rejected.
See `mix man syntax` for the exact boundary.

`;` is the loosest hard boundary. A Mix chain operand can be a pipeline, but
after `|` the raw external command tail owns any later `&&`/`||` until newline
or `;`; there is no symmetric pipeline/chain precedence rule. See the
authoritative [statement-separator contract](syntax.md).

**What a chain tests is `$rc`.** After the left statement runs, `&&` executes
its right side only when `$rc` reads as success and `||` only when it reads as
failure, where (since 0.60.0):

- **absent `$rc` is success** — pure Mix statements like `print` never set it,
  so a cold `print(...) && next` runs its right side. Mind the scope corner:
  when **no global `$rc` exists yet**, an rc-setting statement inside a
  function writes a *function-local* `$rc` that dies with the call, so
  `p() && next` can read absent — and run `next` — off a failure that
  happened inside `p()`. (Once a global `$rc` exists, in-function setters
  update it and the gate sees it.) Chain on rc-setting statements directly,
  or return the rc from the function, rather than chaining on a call that
  buries them;
- a **finite whole Number** compares against `0` (`0` = success; anything
  else, including the negative Bus transport bands, = failure);
- **anything else raises**: a non-Number `$rc` (string — numeric strings
  included — bool, nil, list, map) is `TYPE_MISMATCH`, and a non-finite or
  fractional Number is `VALUE_OUT_OF_RANGE`, both catchable as normal errors.
  Before 0.60.0 the gate cast through `to_number().unwrap_or(0)`, which
  fabricated an **arbitrary verdict** from every corrupt shape, never an
  error: anything whose coerced-then-truncated value was `0` read as
  *success* — non-coercible values and unparseable strings (`"inf"`
  included), `false`, NaN, fractions inside `(-1, 1)` and the numeric
  strings `"0"`/`"0.5"` — so `&&` ran a destructive right side; while
  `true`, `Number` infinities and anything truncating to non-zero read as
  *failure*, so `||` did. Raising stops both.

```mix
print(2 + 3 * 4)          -- * before +
print((2 + 3) * 4)        -- parens win
print("sum=" .. 2 + 3)    -- + (prec 6) before .. (prec 5)
print(1 + 2 == 3)         -- arith before comparison
```
```text
14
20
sum=5
true
```

**`**` is left-associative** (unlike maths convention and unlike Python):

```mix
print(2 ** 3 ** 2)        -- (2**3)**2 = 64, NOT 2**(3**2) = 512
print(-2 ** 2)            -- unary minus binds tighter: (-2)**2 = 4
```
```text
64
4
```

Comparisons **do not chain** — they are left-associative at the same precedence,
so `1 < 2 == true` parses as `(1 < 2) == true`:

```mix
print(1 < 2 == true)      -- (true) == true
```
```text
true
```

`and` (prec 2) binds tighter than `or` (prec 1):

```mix
print(true or false and false)   -- true or (false and false)
```
```text
true
```

## Arithmetic: `+` `-` `*` `/` `%` `**`

Mix numbers are **f64** (see [numbers](numbers.md) / [math](math.md)). Operands are
coerced with `to_number`: a numeric **string** or a **bool** is accepted
(`true` → 1, `false` → 0); a non-numeric value **raises** a runtime error.
Numeric strings include scientific notation (`"1e3" + 1` → `1001`), but the
coercion is **strict**: `"inf"`, `"nan"`, and overflow spellings like `"1e999"`
are *not* numeric strings — they behave as ordinary text (so `"inf" + 1`
falls back to concat, and `"nan" < 5` errors).

```mix
print(7 + 3)
print(7 - 3)
print(7 * 3)
print(7 / 3)
print(7 % 3)
print(2 ** 10)
```
```text
10
4
21
2.3333333333333335
1
1024
```

`**` is real `powf`, so fractional and negative exponents work; bools coerce:

```mix
print(9 ** 0.5)           -- square root via power
print(true + true)        -- 1 + 1
print(true * 5)
```
```text
3
2
5
```

**Modulo** follows Rust's `%` (truncated; the result takes the sign of the
dividend) and works on floats:

```mix
print(-7 % 3)
print(7 % -3)
print(7.5 % 2)
```
```text
-1
1
1.5
```

**Division and modulo by zero raise** — catchable runtime errors, not
`NaN`/`inf` (`%` by zero returned `NaN` before 0.20.5; both error now):

```mix
print(5 / 0)
```
```text
Runtime error at line 1: division by zero
```
```mix
print(5 % 0)
```
```text
Runtime error at line 1: modulo by zero
```

Wrap a risky divide in [try/catch](errors.md) if the divisor might be zero. (Note:
the `math` builtins like `ln(0)` *do* return `-inf` per IEEE-754 — only the `/`
and `%` operators hard-error. See [math](math.md).)

A genuinely non-numeric operand to `-` `*` `/` `%` `**` raises:

```mix
print("ab" * 3)           -- no string-repeat operator
```
```text
Runtime error at line 1: cannot use 'ab' as number
```

Numeric strings still coerce (`"8" / "2"` → `4`). In 0.55.0, `/` and `%`
were brought into line with the other arithmetic operators: an unparseable
right operand now reports that operand as non-numeric, rather than being
silently treated as zero and misreported as division/modulo by zero; an
unparseable left operand no longer becomes a plausible numeric `0` result.

There is **no string `*` repeat and no list `+` merge** — use the
[`repeat()`](builtins.md) builtin for strings and [`push()`](collections.md) /
[`concat`-style helpers](collections.md) for lists.

### `+` has a **scalar** string fallback — prefer `..` for text

`+` first tries to coerce **both** sides to numbers. If both succeed it adds; only
when at least one side is a non-numeric **scalar** (string, bool, nil) does it fall
back to string concatenation. This makes `+` ambiguous on data of unknown type —
**always use `..` for text**:

```mix
print("5" + 3)            -- both numeric -> 8
print("5" + "10")         -- both numeric strings -> 15, NOT "510"
print("a" + "b")          -- not numeric -> string concat
print("inf" + 1)          -- "inf" is NOT a numeric string -> concat
```
```text
8
15
ab
inf1
```

That `"5" + "10"` → `15` surprise is exactly why the concat operator is separate.

### `+` on a list, map, bytes, buffer or function **raises** (0.90.0)

The fallback is scalars only. Give `+` a container or a function value on
**either** side and it raises `TYPE_ERROR` naming the builtin that does what
you meant:

```mix
print(["a"] + ["b"])
print({a: 1} + {b: 2})
print([1] + 2)
```
```text
Runtime error: `+` is not defined for list and list — it does not join lists. Use concat(a, b) to join, push(list, value) to append
Runtime error: `+` is not defined for map and map — it does not merge maps. Use merge(a, b)
Runtime error: `+` is not defined for list and number — `+` takes numbers or strings. Use `..` to build text, concat(a, b) for lists, merge(a, b) for maps
```

Before 0.90.0 each of those produced a *string* (`[a][b]`, `{a: 1}{b: 2}`, `[1]2`)
with rc 0, and nothing failed until far from the cause — a helper that built
`["runuser", …, $db] + $argv` and handed the result to `run_argv` was the filing
case. Note this is deliberately wider than the [`==` rule](#equality---):
**either** operand being a container is enough, because `+` has no counterpart to
the `$map[$key] == nil` key-absence idiom that rule has to protect.

`nil` is still a scalar: `nil + 1` is `"nil1"`. That is its own trap, but it is
not this one, and moving it would break absent-key-into-a-message lines whose
behaviour depends on the data.

Indexing a container and adding the **element** is unaffected — the operand there
is a scalar:

```mix
$tally["pass"] = $tally["pass"] + 1   -- fine: the element is a number
```

`mix lint` flags the statically provable shapes ahead of the run as
[MIX-W2301](lint.md) — the only gate there is on an `ssh_mix` body, or on a
branch the local run never takes.

## Concatenation: `..`

`..` always converts **both** operands to their Mix string form and joins them.
It never does arithmetic — this is the unambiguous way to build text. (In `"…"`
strings, `${name}` interpolation is the other path; a bare `$name` is literal. See
[strings](strings.md).)

```mix
$name = "world"
print("hello " .. $name)
print("x" .. 1 .. "y")    -- numbers stringify
print(1 .. 2)             -- "12", NOT 3
```
```text
hello world
x1y
12
```

**`..` is not a range operator** (unlike Rust/Ruby): `1 .. 5` is the *string*
`"15"`, never a sequence. Use the `range()` [builtin](builtins.md) or a
`for` loop for numeric sequences.

`..` is the workhorse for assembling messages, paths, and Bus targets:

```mix
$node = "node1"
$addr = "noded." .. $node .. ".bus"
print($addr)
```
```text
noded.node1.bus
```

When `..` ends a physical line, the expression continues on the following line.
Comments and blank lines may separate the operator from its right operand:

```mix
$message = "prefix: " .. -- trailing concat requests more input

  "body"
```

Only the trailing form is continuation syntax. A line beginning with `..` is
not joined to the previous statement, so `../tool` remains a relative command
path and `source ../file.mix` / `include ../file.mix` retain their path grammar.
No other binary operator gains newline continuation; use `\` for the general
case. A `;` after `..` remains a parse error, not a continuation boundary.

## Comparison: `==` `!=` `<` `>` `<=` `>=`

### Equality `==` / `!=`

Value equality with **one cross-type rule**: a `Number` compared to a `String`
coerces the string to a number and compares numerically (when it parses);
otherwise unequal. Same-type compares structurally. No `Number`↔`Bool` coercion.

```mix
print(2 == 2.0)           -- numbers
print(5 == "5")           -- string coerces to number
print(5 == "5.0")         -- still numeric: 5.0 == 5.0
print(1 == true)          -- NO number/bool coercion -> false
print(nil == nil)
print(3 != 4)
```
```text
true
true
true
false
true
true
```

**`==` / `!=` with a map or list on BOTH sides raises `TYPE_ERROR`** (0.68.0).
Use **`deep_eq(a, b)`** for structural comparison:

```mix
print(deep_eq([1, 2], [1, 2]))   -- true
print([1, 2] == [1, 2])          -- raises TYPE_ERROR, naming deep_eq
```
```text
true
```

Until 0.68.0 the comparison answered — always, whatever the contents: `false`
for `==`, `true` for `!=`. That is a constant wearing a comparison's clothes,
which is why it now raises rather than quietly misleading.

Only **both**-collection comparisons raise. A collection against a **scalar**
still answers, because that is a genuine type difference and `false` is
truthful — which keeps the key-absence idiom working:

```mix
$reg = {}
print($reg["k"] == nil)   -- true
$reg.k = [1, 2]
print($reg["k"] == nil)   -- false  (present; the value is a list)
print([1, 2] == "text")   -- false
```

See [collections](collections.md#list--list-raises-0680--use-deep_eq) for the
full rule, including which builtins are and are not affected.

### Ordering `<` `>` `<=` `>=` — numeric-first, lexicographic fallback

The rule (`num_cmp` in `evaluator.rs`):

1. If **both** operands coerce to numbers (numbers, or numeric strings like `"5"`), compare **numerically**.
2. Else if **both** are strings, compare **lexicographically by Unicode codepoint** (byte order for valid UTF-8 — byte-exact, no case-fold, no normalization).
3. Otherwise (a non-numeric string vs a number) → **runtime error**.

```mix
print(5 < 10)             -- numeric
print("5" < "10")         -- both numeric strings -> NUMERIC -> true
print("apple" < "banana") -- both strings -> lexicographic
print("Zebra" < "apple")  -- 'Z' (0x5A) < 'a' (0x61) -> true
print("abc" <= "abc")
print("5" < "abc")        -- not both numeric, both strings -> lexicographic
```
```text
true
true
true
true
true
true
```

Note `"5" < "10"` stays **numeric** (→ `true`), the opposite of a naive
string compare. The lexicographic path is handy for character-class tests:

```mix
$ch = "m"
print($ch >= "a" and $ch <= "z")   -- is it a lowercase letter?
```
```text
true
```

A non-numeric string against a number is genuinely incomparable and **errors**:

```mix
print(5 < "abc")
```
```text
Runtime error at line 1: cannot compare 'abc' as number
```

## String equality keywords: `eq` / `ne`

`eq` and `ne` compare the **rendered Mix string forms** of both operands
(`to_mix_string()`) — no numeric coercion. Use them when you want a *textual*
match regardless of type, and `==` when you want value/numeric equality. The
difference shows on numbers that print differently:

```mix
print(5 eq "5")           -- "5" eq "5" -> true
print("5" eq 5)           -- symmetric
print(5 eq "5.0")         -- "5" eq "5.0" -> DIFFERENT text -> false
print(5 == "5.0")         -- numeric: 5.0 == 5.0 -> true
print("a" ne "b")
```
```text
true          <- 5 eq "5"
true          <- "5" eq 5   (symmetric)
false         <- 5 eq "5.0"  (different printed text: "5" vs "5.0")
true          <- 5 == "5.0"  (numeric: 5.0 == 5.0)
true          <- "a" ne "b"
```

Rule of thumb: **`==` for "same value", `eq` for "same printed text".**

## Boolean: `and` `or` `not` (and `!`)

`and` / `or` **short-circuit** and **return the deciding operand value itself**,
not a coerced bool — like Lua/Python, not C:

- `a or b` → `a` if `a` is truthy, else `b`.
- `a and b` → `a` if `a` is falsy, else `b`.

```mix
print(0 or "fallback")    -- 0 is falsy -> right side
print("first" or "second")-- left truthy -> left, right not evaluated
print(1 and "kept")       -- left truthy -> right side
print("" and "skipped")   -- left falsy ("") -> left, prints empty
```
```text
fallback
first
kept

```

This makes `or` a clean default-picker and `and` a guard. (`not` / `!` is the only
one that *always* yields a real bool — see below.)

### `not` / `!` and truthiness

`not x` (keyword) and `!x` (symbol) both return a real `Bool` — the logical
negation of `x`'s truthiness. **Truthiness** (`is_truthy`):

| Value | Truthy? |
|---|---|
| `nil` | false |
| `false` / `true` | as-is |
| `0` (number) | false; any other number true |
| `""` **and `"0"`** | false; any other string true |
| `[]` / `{}` empty | false; non-empty true |
| function | always true |

Note the two string traps: an **empty string and the string `"0"` are both
falsy**.

```mix
print(not true)
print(not 0)
print(not "")             -- empty string -> falsy -> not -> true
print(not "0")            -- the string "0" is ALSO falsy
print(not "x")            -- non-empty -> truthy -> false
print(not nil)
print(not [])             -- empty list falsy
print(not [1])
```
```text
false
true
true
true
false
true
true
false
```

## Nil-coalesce: `??`

`a ?? b` is **nil-coalesce, not falsy-coalesce** — it short-circuits on **nil
only**: it returns `a` unless `a` is `nil`, in which case it returns `b`. Unlike
`or`, a falsy-but-non-nil left (`0`, `""`, `false`) is kept. Use it to supply a
default for a possibly-unset value; use `? :` for a real condition.

```mix
$x = nil
print($x ?? "default")    -- nil -> right side
print(0 ?? "default")     -- 0 is not nil -> kept
print("" ?? "default")    -- "" is not nil -> kept
print(false ?? "x")       -- false is not nil -> kept
```
```text
default
0

false
```

Contrast with `or`, which *would* replace `0`, `""`, and `false` because they
are falsy.

**Precedence trap with `..`:** concat (prec 5) binds *tighter* than `??`
(prec 4), so `"x = " .. $v ?? "d"` parses as `("x = " .. $v) ?? "d"` — the
concat result is never nil, so the default **never fires** (you get `x = nil`).
Parenthesise the coalesce inside a concat:

```mix
$v = nil
print("x = " .. $v ?? "d")    -- ("x = " .. $v) ?? "d" -> default dead
print("x = " .. ($v ?? "d"))  -- what you meant
```
```text
x = nil
x = d
```

The other direction reads naturally: `??` binds tighter than comparison, so
`$a ?? 0 < 5` is `($a ?? 0) < 5`.

## Ternary: `cond ? a : b`

The C-style conditional expression (since 0.20.0). It evaluates `cond`, then
**only the taken branch** — `a` if `cond` is truthy, else `b`. It is the
**loosest-binding** operator (looser than `or`) and **right-associative**, so a
chain is an else-if ladder: `a ? b : c ? d : e` is `a ? b : (c ? d : e)`.

```mix
$n = 2
print($n > 0 ? "pos" : "neg")              -- basic
print($n == 1 ? "one" : $n == 2 ? "two" : "many")  -- right-assoc chain
```
```text
pos
two
```

**Prefer `? :` over the `cond and a or b` idiom.** Because Mix is broadly falsy
(`""`, `0`, `false`, `nil`, `[]`), `cond and a or b` silently returns `b` whenever
the *middle* operand `a` is falsy — `$ok and false or "x"` wrongly yields `"x"`,
while `$ok ? false : "x"` correctly yields `false`.

It is single-line at statement top level (a newline before `?` ends the statement
first — use an [`if` expression](control-flow.md) for a multi-line conditional
value), but like any expression it may span newlines inside `(...)`/`[...]`/`{...}`.

A ternary works as a bare statement too, including variable-led (`$c ? "y" : "n"`),
but both branches must be **expressions** — `print` is a *statement* keyword, so
`$c ? print("y") : print("n")` is a parse error. For side-effecting branches use
an [`if` statement](control-flow.md).

## Quick reference

```text
+  -  *  /  %  **      arithmetic  (f64; coerces numeric strings/bools; / or % by 0 errors)
..                     string concat (always stringifies both sides)  <-- use for text
+                      string-concat FALLBACK only when not both numeric (avoid for text);
                       a list/map/bytes/buffer/function operand RAISES (0.90.0)
== !=                  value equality (Number<->String coerces; List/Map always !=)
<  >  <=  >=           ordering: numeric-first, else lexicographic strings, else error
eq ne                  textual equality on the printed Mix string forms
and or                 short-circuit; RETURN the deciding operand (not a bool)
not  !                 logical negation -> always a real Bool
??                     nil-coalesce: left unless left is nil (keeps falsy non-nil)
cond ? a : b           ternary: cond truthy -> a else b (loosest, right-assoc, short-circuit)
-x                     numeric negate;  not x / !x  logical not
```

No operator chains comparisons (`a < b < c` is `(a<b) < c`), and there is no
string-`*`-repeat, list-`+`-merge, or `++`/`--`. Reach for the
[builtins](builtins.md) (`repeat`, `min`, `max`) instead. For a conditional value
use the ternary `cond ? a : b` above or an [`if` expression](control-flow.md).

## See also

- [numbers](numbers.md) — f64 model, integer-clean printing, radix literals
- [math](math.md) — numeric builtins (`sqrt`, `pow`, `round`, IEEE-754 `inf`/`NaN`)
- [strings](strings.md) — `'raw'` vs `"${interp}"`, codepoint vs byte ops
- [control-flow](control-flow.md) — `if` / `while` / `for each`, where truthiness is used
- [errors](errors.md) — `try`/`catch` for division-by-zero and coercion errors
- [variables](variables.md) — the `$` sigil and scope
- [lists](collections.md) — why `List == List` is false; element comparison
- The source: [`evaluator.rs`](https://github.com/markc/mixos/blob/main/libs/mix/src/evaluator.rs) (`eval_binop`, `num_cmp`) and [`parser.rs`](https://github.com/markc/mixos/blob/main/libs/mix/src/parser.rs) (`parse_binary_rhs` precedence table)
- `mix help` for the topic list; `mix what NAME` for one-line builtin help

---

<!-- page: https://mixos.dev/mix/overview/ (source: https://mixos.dev/mix/overview.md) -->

# Mix — overview

**Mix** is an [ARexx](https://en.wikipedia.org/wiki/ARexx)-inspired, Bus-native
shell and scripting language, implemented in pure Rust. It is the orchestration
control surface for the [mixos](https://github.com/markc/mixos) substrate: one
language that covers one-off glue, daily shell work, and distributed mesh
coordination — with network messaging built into the grammar rather than bolted
on with external clients.

This page is the orientation. It says what Mix is, why it exists, where it came
from, and then hands you off to the rest of the manual.

> **One-line mental model.** Mix is a Bus-native shell where every variable is
> `$`-sigil, concatenation is `..`, statements use newline or `;` separators,
> blocks close with `end`, and command results come back as **structured maps —
> not string soup**. It is not "a better bash"; network messaging
> (`send` / `emit` / `on … end`) is part of the language.

## A taste

```mix
$name = "world"
print("hello, " .. $name)        -- concat is .. (never + or .)
print("hello, ${name}")          -- ${...} interpolates a var; bare $name is literal

-- square a list with a terse lambda (no return, no end)
print(map([1, 2, 3], fn($x) = $x * $x))

-- talk to a mesh service in one line — no SDK, no socket wiring
send noded noded.ping             -- assumes a local Bus broker is present
print("ping rc=" .. $rc)
```

```text
hello, world
hello, world
[1, 4, 9]
ping rc=0
```

> `${...}` performs a **variable** lookup (scope → env → nil), not arbitrary
> expression evaluation — `${name}` works, `${env("USER")}` does not. For a
> function result, concatenate: `"user: " .. env("USER")`. The `send` line does a
> real RPC (filling `$result`/`$rc`) on a host with a Bus broker; on a
> broker-less host it is still non-fatal — `$rc` reads `-3` ("Bus unavailable")
> and the script continues. See [strings](strings.md) and
> [Bus messaging](bus.md).

That last block is the differentiator: `send` is a keyword. On a host with a Bus
broker it does a real RPC and fills `$result` / `$rc` — and `$rc` is always a
**number** with signed bands: `0` delivered and accepted, `1..9` delivered with a
warning, `>= 10` a broker/app error, negative a local failure. On a host without
a broker the same script still runs — `send` is non-fatal (`$rc == -3`), `emit`
is silently dropped — and it lights up unchanged when a broker appears (more in
[Bus messaging](bus.md)).

## What Mix is

- **A Bus-native shell + scripting language.** `send`, `emit`, `address`, and `on … end` are language keywords that reach peer services over the [Bus](https://github.com/markc/mixos) mesh. No client library, no boilerplate — remote orchestration reads like a local script. See [Bus messaging](bus.md).
- **A real scripting language.** First-class functions and terse lambdas, higher-order builtins (`map` / `filter` / `reduce` / `sort_by` / …), structured values (string, number, bool, bytes, list, map), `try`/`catch`, closures. See [functions](functions.md) and the [builtins index](builtins.md).
- **A shell.** It runs external commands, has a REPL with meta-commands (`mix status`, `mix help`, `mix what NAME`), and serves as a daily-driver login shell (`chsh -s /opt/mixos/bin/mix`). Command results are **structured** — `run_rc("cmd")` returns `{rc, stdout, stderr, timed_out, interrupted}`, not exit-code soup. See [running commands](system.md), the [shell](shell-mode.md) page, and [the `mix` meta-command](cli.md).
- **A structured-data format.** Strict-data `.*.mix` files (`.conf.mix`, `.spec.mix`, …) are parsed without executing anything — the substrate's config/state format. See [data & serialization](data.md).
- **A Bus citizen.** `mix --serve service.mix` runs a script as a supervised, mesh-registered daemon. A script with one `on` handler is a complete service. See [serving as a citizen](serve.md).

Mix is **pure Rust** — no Lua, no embedded VM from another stack. Lexer → parser
→ evaluator all live in the `mixos-lib-mix` crate.

## Why it exists

Controlling systems across many machines normally means stitching together a
stack of separate tools: shell scripts, SSH, Ansible, REST/gRPC clients, message
queues, and hand-rolled networking glue. Each layer is its own wiring, its own
failure mode, its own mental overhead.

Mix collapses that stack. Network communication is a *core part of the language*,
so coordinating remote machines and services feels like writing a plain local
script:

- **Built-in networking.** `send` / `address` / `emit` / `on` are keywords, not library calls — one line reaches a peer over the mesh.
- **Less boilerplate.** No repeated wiring for sockets, retries, serialization, queues, or service-to-service messaging.
- **Structured returns.** Command and RPC results are maps you index (`$r.rc`, `$result.pong`), not strings you re-parse with `awk`.
- **Rust-based safety.** Memory safety and safer concurrency than the older automation tools it replaces.

There is a second, deeper reason. Mix is the **agent-operable control surface**
for an AI-first computing substrate: a language legible enough that an AI agent
can read a system's state as structured data, modify it through structured
channels, and drive the whole mesh from a script. The same property that makes
remote orchestration terse for a human makes it tractable for an agent.

## Where it came from

The lineage is **ARexx** (1987, AmigaOS): every application exposed a named,
addressable message port, and one REXX script could orchestrate across all of
them. Mix updates that model for a WireGuard mesh and Rust-native daemons —
every service is a Bus-addressable port, one Mix script orchestrates across the
mesh.

Mix was created inside the **mixos** project as its scripting language and
shell. An earlier sketch built the same role on Lua (via `mlua`); that approach
was **deprecated and fully removed** once the pure-Rust interpreter reached
parity. Mix now occupies that role exclusively across the mixos stack.

It ships as two crates that version in lockstep (a third workspace member,
`mix-bench`, is a development-only benchmark harness):

| Crate | What it is |
|---|---|
| **`mixos-lib-mix`** | The interpreter library — lexer, parser, evaluator, builtins, value model. Pure Rust, no internal deps; feature-gated capabilities (`json`, `regex`, `toml`, `datetime`, `url`, `crypto`, `http`, `sqlite`, `dkim`, `markdown`, `datastar`). |
| **`mix-shell`** | The shell behind the `mix` binary (built by `cli/system`) — REPL, shell layer, Bus wiring, the `--serve` supervised-citizen runtime, and the `mix man`/`help`/`what` meta-commands. |

A standalone `mix` install runs as a normal scripting shell. When a Bus broker
(`noded`, from the [cos](https://github.com/markc/mixos) repo) later appears
on the host, the **same binary** becomes mesh-viable on next invocation — no
reinstall, no recompile, no script edits. A runtime lazy-probe decides
bare-vs-mesh at execution time.

## How to run it

```sh
mix                          # interactive REPL
mix script.mix arg1 arg2     # run a file; args land in $1, $2, args()
mix -c '<source>'            # one-liner (`;` or real newlines separate statements)
mix - < script.mix           # read a script from stdin (clean over ssh)
mix --check script.mix       # parse without executing (syntax check)
mix --serve service.mix      # run as a supervised Bus citizen
```

```sh
mix -c 'print("hi, " .. env("USER"))'
```

```text
hi, user
```

A minimal `service.mix` that *is* a complete mesh service:

```mix
on noded.ping
  reply("pong")
end
```

See [invocation & CLI](invocation.md) for every mode and flag, and
[serving as a citizen](serve.md) for the `--serve` runtime.

## The five things to get right first

Mix has near-zero presence in model training data, so anyone (human or agent)
extrapolating from bash/Python trips on the same five edges. Get these right and
most of the surprises disappear:

1. **Every variable is `$`-sigil.** `$x = 1`, not `x = 1` — a bare name is misread as a shell command. See [variables & scope](variables.md).
2. **Concatenation is `..`**, never `+` or `.`: `"a" .. $x .. "b"`. (`+` *adds* when both sides look numeric — `"5" + "5"` is `10`, not `"55"` — and `.` is field access.)
3. **Statements use newline or `;`.** Prefer newlines in files; use `;` for compact `mix -c` / generated source. On shell-dispatch lines the same glyph remains the shell command-list operator; classification is whole-line, never mixed. See [syntax](syntax.md).
4. **`${...}` interpolates, bare `$name` is literal** inside double quotes; `'single quotes'` are fully raw; `$(...)` is literal in a Mix string. See [strings](strings.md).
5. **`run` / `run_rc` spawn `/bin/sh` with a minimal `PATH`** — inside scripts, call binaries by full path (`/opt/mixos/bin/mix`, never bare `mix`). See [running commands](system.md).

Close behind those five: blocks close with `end` (there is no `do` keyword);
`push()` mutates in place and returns `nil`; and `pos()` is 1-based (0 = not
found) while arrays and `substr` are 0-based. See
[control flow](control-flow.md) and [collections](collections.md).

```mix
$xs = [10, 20]
push($xs, 30)              -- statement form: push mutates, returns nil
print($xs)                 -- [10, 20, 30]   (NOT $xs = push(...) — that nils $xs)
print(length("café"))      -- 4   (codepoints, not bytes)
```

```text
[10, 20, 30]
4
```

## Map of the manual

A guided tour — read in roughly this order, or jump straight to what you need.

**Language core**

- [syntax & the classifier](syntax.md) — tokens, the newline rule, comments, and when a line runs as Mix versus dispatches to the shell.
- [variables & scope](variables.md) — the `$` sigil, `$1`/`$N` args, `$rc`, `$result`, `$event`, scope rules, function-local binding.
- [strings](strings.md) — `'raw'` vs `"${...}"`, `..` concat, codepoint vs byte vs grapheme ops, unicode escapes, padding/wrapping.
- [numbers](numbers.md) — the f64 model, `0o`/`0x`/`0b` radix literals, integer-clean printing, numeric coercion.
- [operators](operators.md) — `..`, arithmetic, comparison/ordering, `and`/`or`/ `not`, the `? :` ternary, `??` nil-coalesce, `&&`/`||` statement chaining.
- [control flow](control-flow.md) — `if`/`else`, `for $x in` (a.k.a. `for each`), `while`, `select`, the `end` rule, if-as-expression, inline single-statement bodies.
- [functions](functions.md) — `function`/`fn`, the terse `fn($x) = expr` lambda, first-class values, closures, the pass-in/return/reassign triad, modules.
- [collections](collections.md) — lists & maps, indexing (mixed base!), negative indices, `push`/`keys`/`merge`, slicing.
- [higher-order functions](hof.md) — `map`/`filter`/`reduce`/`sort_by`/ `group_by`/…, the lambda-passing rules.
- [errors](errors.md) — `try`/`catch`, `die`, `exit`, the uncatchable `panic`, how command failures surface.

**Builtins & I/O**

- [builtins index](builtins.md) — the categorized reference (`mix help`).
- [math](math.md) — numeric builtins: rounding, powers/roots, logs, `min`/`max`/ `clamp`, trig, `pi()`/`e()`.
- [running commands](system.md) — `run` / `run_rc` / `run_stream`, structured returns, wall-clock timeouts, the shell-dispatch vs Mix-statement split, `$(...)` and brace expansion.
- [files & I/O](io.md) — `read_file`/`write_file`, `glob`, `stat`/`chmod`/ `chown`, path helpers.
- [data & serialization](data.md) — `json_parse`/`jq`, `data_encode`, TOML, strict-data `.*.mix`.
- [regular expressions](regex.md) — `re_match`/`re_find`/`re_replace`/`re_split`/`grep_lines` (subject first).
- [dates & time](datetime.md) — timestamps as plain numbers, formatting, parsing, durations.
- [http](http.md) — `http_get`/`http_post`/`http_request`, the 30-second default deadline.
- [datastar](datastar.md) — the `ds_*` Datastar SSE event-framing builtins.

**Distributed & mesh**

- [Bus messaging](bus.md) — `send` / `emit` / `address` / `on … end`, `$result`, the `$rc` signed bands, static `.bus` addressing, graceful no-broker degradation.
- [remote / SSH](remote.md) — the headline `ssh_mix` + heredoc idiom for remote
  Mix source, plus `ssh_run` / `ssh_must`, structured returns, env transports,
  and the mix-as-login-shell path.
- [serving as a citizen](serve.md) — `mix --serve`, the supervised runtime, writing a mesh service.
- [capabilities & embedding](capabilities.md) — the capability classes and the sandbox model daemons embed Mix with.

**Tooling**

- [invocation & CLI](invocation.md) — every run mode and flag.
- [the mix meta-command](cli.md) — `mix help`/`man`/`builtins`/`what`/`status`/ `trace`/… from the REPL or the OS shell.
- [shell](shell-mode.md) — shell-dispatch mode: pipes, `&&`/`||`, brace expansion, `$(...)`, redirects; the daily-driver login shell and `~/.mixrc`.
- [keywords](keywords.md) — the reserved words, keywords-as-names.

When this manual and the live binary disagree, **the binary wins** — probe it
with `mix -c '<code>'` and trust what it prints. The full topic list lives in
[the manual index](README.md).

## Related projects

- **[bus](https://github.com/markc/mixos)** — the MixOS Agent Bus (the Bus) library family Mix consumes for `send` / `call` / topic subscription.
- **[cos](https://github.com/markc/mixos)** — the mixos daemon family: ships `noded` (the broker `--serve` connects to) plus mail, web, DNS, the knowledge indexer, and the display compositor.
- **[Datastar](https://data-star.dev)** — the hypermedia framework the `ds_*` builtins frame SSE events for (server-side reactive UI from Mix).
- **[ARexx background](https://en.wikipedia.org/wiki/ARexx)** — the message-port scripting model Mix descends from.

## See also

```
mix man               this manual's index (README.md)
mix man TOPIC         read a manual page in the terminal
mix help              the full categorized builtin reference
mix builtins [CAT]    list builtins, optionally by category
mix what NAME         one-line description of a builtin or keyword
mix keywords          list the reserved words
```

Pages: [the manual index](README.md) · [invocation](invocation.md) ·
[cli](cli.md) · [syntax](syntax.md) · [variables](variables.md) ·
[strings](strings.md) · [numbers](numbers.md) · [operators](operators.md) ·
[control flow](control-flow.md) · [functions](functions.md) ·
[collections](collections.md) · [hof](hof.md) · [errors](errors.md) ·
[math](math.md) · [io](io.md) · [running commands](system.md) ·
[data](data.md) · [regex](regex.md) · [datetime](datetime.md) ·
[http](http.md) · [datastar](datastar.md) · [Bus messaging](bus.md) ·
[remote / SSH](remote.md) · [serving as a citizen](serve.md) ·
[capabilities](capabilities.md) · [shell](shell-mode.md) ·
[keywords](keywords.md) · [builtins index](builtins.md)

---

<!-- page: https://mixos.dev/mix/owned-editor/ (source: https://mixos.dev/mix/owned-editor.md) -->

# Owned interactive editor (preview)

Set `MIX_EDITOR=owned` in the environment before starting an interactive Mix
session to select the owned editor. The default remains rustyline. Redirected
input or output uses the existing fallback. Failure to open the owned terminal
writer (including unavailable `/proc/self/fd`) warns and falls back to rustyline.
This preview does not change Mix's
command classification, evaluator, continuation rules or job-control policy.

The evaluator builds the prompt and an owned completion snapshot; one editor
thread owns terminal input, incremental UTF-8 decoding, bracketed paste, editing
state and raw modes. Its `poll()` includes a control socket and a signal wake
socket. Only escape disambiguation uses an input-loop timer. Completion filesystem work runs
off the input thread, with bounded candidates and generation/revision checks.

Enter restores terminal modes and attempts to disable bracketed paste before returning the
line for evaluation. No next prompt starts speculatively. The job controller
continues to own process groups and foreground-terminal transfer. Ctrl+Z at an
editor prompt restores modes before invoking the controller's existing shell
stop behaviour; resume preserves the draft. HUP asks the editor to restore its
protocols before the controller exits.

External SIGTSTP uses the same cooperative cooked-mode stop path. After `bg`,
the editor stays cooked without tty reads until a later SIGCONT finds it in the
foreground. Output uses a separate nonblocking tty description with bounded
writes between control polls. Termios restoration precedes best-effort protocol
cleanup. Pending output and protocol cleanup share a single 250 ms drain deadline;
suspension/shutdown acknowledgement never waits indefinitely for output. This
preserves partial escape sequences and queued finish movement when the tty drains
within the deadline. On expiry or output failure, a tear is accepted and the
terminal emulator may need a reset. Each incomplete cleanup increments the
process-local `OUTPUT_TEARS` diagnostic counter, exposed by control inspection as
`output_tears`; recording it requires no write to the blocked tty.
HUP waits for completed cleanup, including after an input-loop failure.
Registration waits for already-committed default stops before permitting raw
entry, and teardown honours any stop claimed after the input loop ended. The
cooperative-stop flag denotes an editor thread's presence, including cooked
waiting phases. Foreground loss during activation leaves the draft cooked and
waiting for a later continue/foreground wake, rather than failing the session.

The internal generation-tagged protocol supports prompt activation, empty-primary
prompt reservation, resume and shutdown. Admission refuses drafts, continuation,
paste, search and completion. A separate local lifecycle pause preserves drafts
and partial decoder bytes; it grants no evaluation permission. Both paths restore
modes before acknowledgement, and restoration errors never grant terminal use.
Restricted profiles accept only job-management syntax and discard completion and
history supplied for an ordinary prompt. This round does not expose remote
evaluation or provide the parked-evaluator host.

Implemented keys include grapheme-aware left/right/delete/backspace, Home/End,
Ctrl+A/E/B/F, Alt+B/F, history Up/Down and Ctrl+P/N, Ctrl+R reverse search,
Ctrl+K/U/W kill, Ctrl+Y yank, Alt+Y yank-pop, Ctrl+_ undo, Alt+R/Alt+_ redo,
Ctrl+S forward search, Tab completion/cycling, Ctrl+C and
Ctrl+D. Enter leaves search with its selected match; Escape or Ctrl+G restores
the previous draft. Bracketed paste is a single undoable edit; paste payloads
over 64 KiB are rejected after consuming their closing marker, with a one-line
diagnostic on a fresh line and the draft preserved. Prompt bytes are reserved in
the buffer budget so paste cannot exceed the renderer's combined input limit. Input buffers,
snapshots, prompt text and render layouts have explicit limits.

History continues to use `.mix_history` and rustyline's `#V2` multiline encoding,
with the last 100 entries and consecutive duplicate suppression. History files
are loaded with a 16 MiB limit; incomplete, oversized or invalid-UTF-8 loads warn
and permanently refuse saving to that destination for the adapter's lifetime.
Loading a different file, or later successfully loading the same file, cannot
clear that refusal. The original file cannot be overwritten by a loaded prefix.
Completion uses the same variables, aliases,
command names and subcommand sources as the legacy path, plus the captured cwd
and home for paths. Prefix filtering precedes the 4096-result/1 MiB result cap,
including directory enumeration. Command names share a cached owned snapshot
using the legacy PATH-scan lifetime, invalidated when aliases change.
Refreshing PATH commands by filesystem staleness remains declined for this round:
the cache lifetime deliberately matches rustyline.

Prompt SGR colour is retained; cursor-control and terminal-protocol escapes are
stripped. Resize reflows the logical buffer; buffers taller than the terminal
use a viewport containing the cursor. Full editing/search/completion UI parity,
terminal-emulator visual acceptance and real SSH coverage remain promotion gates
before changing the default or removing rustyline.

Per-keystroke O(buffer) reflow is accepted and bounded; optimisation is deferred.
Search Enter selects without submitting; its parity divergence remains deliberate.
An explicit search indicator remains a promotion-gate parity item.
Trailing partial UTF-8 keeps admission Busy until completed under the one-timer rule.
Attachment-backed session generations are deferred to stage D; the current local session tag is 1.

The `owned_editor_pty` integration family covers actual PTY input and handoff,
Unicode editing, multiline history, completion, silent resize, EOF/HUP and nested
shell stop/fg. The legacy job-control family remains an independent regression
gate. No production deployment is part of this preview.

CI and local PTY gates **must** run serially: `openpty` cannot atomically set
CLOEXEC, so concurrent fixture forks could inherit descriptors before duplication
and closure. From the Cargo workspace, run:

```text
cargo test -p system --test owned_editor_pty -- --test-threads=1
cargo test -p system --test job_control_pty -- --test-threads=1
```

Apply `--test-threads=1` to broader test invocations which include these binaries
as well. The output gates cover both an undrained master with bounded cleanup and
a partial write drained before the deadline, plus viewport-bounded submission.

---

<!-- page: https://mixos.dev/mix/regex/ (source: https://mixos.dev/mix/regex.md) -->

# Regular expressions

Mix ships six regex builtins — `re_match`, `re_find`, `re_replace`,
`re_replace_must`, `re_split`, `grep_lines` — built on the Rust
[`regex`](https://docs.rs/regex) crate, all taking their **subject first**
like every literal-string builtin. The `mix` binary compiles with the
`regex` feature **on**, so they're always available; a library build
without that feature won't have the five `re_*` (and `grep_lines` falls
back to a literal substring test per line). The plain string ops `replace`
/ `split` / `contains` are **always present** (not feature-gated) and treat
their needle **literally** — `split("a1b22c", "[0-9]+")` does not split —
so reach for them first when the needle is a fixed substring.

> **History.** From 0.2.0 to 0.72.0 the family was pattern-first
> (`regex_match(pattern, s)`, plus `grep`), which silently inverted at
> swapped call sites — both arguments are strings, so a swapped call is a
> plausible "no", never an error; it overwrote two journals with regex
> text on one occasion. The subject-first `re_*` names landed in 0.63.0,
> every caller in the fleet was migrated, and the five legacy names were
> **deleted in release B (0.73.0)** once the fleet-wide inventory read
> zero. A surviving legacy call now fails loudly: `MIX-E1102` at lint
> time, `undefined function` at runtime.

The flavor is **RE2-style**: linear-time matching, full Unicode support, but
**no backreferences and no look-around** (a deliberate trade for guaranteed
linear time — see [Limitations](#limitations)). Patterns and replacements are
ordinary [strings](strings.md), so the quoting rules there apply directly and
bite hard — read [Quoting traps](#quoting-traps) before you write a `$`-bearing
pattern.

> One-line mental model: **a regex is just a string argument**; matches come
> back as structured maps (`{match, start, end, groups}`), not as magic `$~`
> globals.

```mix
print(re_match("abc123", "[0-9]+"))
print(re_find("a1 b22 c333", "[0-9]+"))
print(re_replace("hello world", "[aeiou]", "_"))
print(re_split("a, b ,c,  d", "\\s*,\\s*"))
```
```text
true
[{match: 1, start: 1, end: 2}, {match: 22, start: 4, end: 6}, {match: 333, start: 8, end: 11}]
h_ll_ w_rld
[a, b, c, d]
```

## The family

| Call | Returns | Notes |
|---|---|---|
| `re_match(s, pattern)` | **bool** | true if `pattern` matches *anywhere* in `s` (not anchored) |
| `re_find(s, pattern)` | **list of maps** | every non-overlapping match, `{match, start, end[, groups]}` — **codepoint** offsets, so `start`/`end` compose with `substr`/`slice`/`index_of`; `[]` when none |
| `re_replace(s, pattern, repl)` | **string** | replaces **all** matches; `$1`/`${name}` backrefs in `repl` |
| `re_replace_must(s, pattern, repl[, {count, path}])` | **string** | same, but **raises** `NEEDLE_ABSENT` when nothing matched and `NEEDLE_COUNT` when `count` disagrees — the form for editing a file (0.90.0) |
| `re_split(s, pattern)` | **list of strings** | splits on each match; keeps empty leading/trailing parts |
| `grep_lines(text, pattern)` | **list of strings** | the lines of `text` matching `pattern`; `[]` when none |

All of them **raise a catchable runtime error** on an invalid pattern (see
[Errors](#errors-and-validation)). Since 0.117.0 they share a small cache of
compiled patterns, keyed by the exact pattern string (inline flags such as
`(?i)` included): a loop that calls `re_match` with the same pattern on every
line reuses one compile while the pattern stays cached. The cache holds at most
32 patterns and 64 KiB of pattern text, evicting the least recently used. A
pattern over 4 KiB, or one that compiles to more than a small size limit (a
Unicode repetition such as `\w{60}`), is never cached and compiles on every
call, as before. Invalid patterns are not cached either, so they raise the same
error on every call. Caching changes speed only, never what matches. There is
still no Mix-visible compiled-pattern value.

Arity is checked as a **minimum**: a missing argument raises, but surplus
arguments are **silently ignored** (`re_match("abc", "b", "extra")` →
`true`). Non-string arguments are coerced with the standard string coercion —
`re_match("x420", 42)` matches the pattern `42` → `true`.

### re_match — does it match?

`re_match` is a predicate. The pattern is **unanchored** — it matches if it
occurs anywhere — so add `^` / `$` yourself to anchor.

```mix
print(re_match("abc123", "[0-9]+"))   -- substring match -> true
print(re_match("abc123", "^[0-9]+$")) -- fully anchored  -> false
print(re_match("abcd", "^abc$"))      -- anchored        -> false
print(re_match("HELLO", "(?i)hello")) -- inline flag     -> true
```
```text
true
false
false
true
```

Use it straight in an `if` ([control flow](control-flow.md)):

```mix
$email = "joe@example.com"
if re_match($email, "^[^@]+@[^@]+\\.[^@]+$") then
  print("looks like an address")
else
  print("rejected")
end
```
```text
looks like an address
```

### re_find — every match, with offsets and captures

`re_find` returns a **list of maps**, one per non-overlapping match, left to
right. Each map always has `match`, `start`, `end`; if the pattern has capture
groups it also gets a `groups` list (group 1.. — group 0 is `match`).

```mix
print(re_find("a1 b22 c333", "[0-9]+"))
```
```text
[{match: 1, start: 1, end: 2}, {match: 22, start: 4, end: 6}, {match: 333, start: 8, end: 11}]
```

With capture groups, `groups` carries each `(...)` in order:

```mix
print(re_find("joe@acme jane@corp", "(\\w+)@(\\w+)"))
```
```text
[{match: joe@acme, start: 0, end: 8, groups: [joe, acme]}, {match: jane@corp, start: 9, end: 18, groups: [jane, corp]}]
```

An optional group that didn't participate comes back as `nil` in `groups`
(verified — the second match has no `px`):

```mix
$r = re_find("10px 20", "(\\d+)(px)?")
print($r)
```
```text
[{match: 10px, start: 0, end: 4, groups: [10, px]}, {match: 20, start: 5, end: 7, groups: [20, nil]}]
```

Field access is the usual map syntax — `["match"]` or `.start`
([collections](collections.md)):

```mix
$m = re_find("id=42", "[0-9]+")
print($m[0]["match"])
print($m[0].start)
```
```text
42
3
```

> **`start`/`end` are CODEPOINT indices** — the same unit `substr`, `slice`
> and `index_of` count in, so `substr($s, $m[0].start, 1)` is always the
> first matched character, non-ASCII included. (The deleted legacy
> `regex_find` answered in raw UTF-8 *byte* offsets, which silently broke
> that composition on any input with an `é` in it.)

```mix
print(re_find("café über", "über"))
-- "café " is 5 CODEPOINTS (é is one), so "über" starts at 5
```
```text
[{match: über, start: 5, end: 9}]
```

No match → an **empty list**, never `nil`. Test with `is_empty` or `length`:

```mix
$r = re_find("abc", "z+")
print($r)
if is_empty($r) then
  print("no match")
end
```
```text
[]
no match
```

### re_replace — substitute all matches

`re_replace(s, pattern, replacement)` replaces **every** match (it's
`replace_all` under the hood) and returns the new string. The replacement
supports the crate's backreference syntax: **`$1` … `$N`** for numbered groups
and **`${name}`** for named groups.

```mix
print(re_replace("hello world", "[aeiou]", "_"))
print(re_replace("joe@acme", "(\\w+)@(\\w+)", "$2.$1"))
print(re_replace("The theory", "(?i)the", "X"))
```
```text
h_ll_ w_rld
acme.joe
X Xory
```

Note the last one: `(?i)the` matched both the standalone `The` **and** the
`the` inside `theory` — `re_replace` is unanchored and global, so use `\b`
word boundaries when you mean whole words.

**Named groups** use `(?P<name>...)` — or the shorter `(?<name>...)` — in the
pattern and `${name}` in the replacement. But `${name}` is exactly what a Mix
double-quoted string interpolates, so **single-quote the replacement** (or it's
eaten before the regex sees it — see [Quoting traps](#quoting-traps)):

```mix
print(re_replace('joe@acme', '(?P<user>\w+)@(?P<host>\w+)', '${host}/${user}'))
```
```text
acme/joe
```

To insert a **literal `$`**, double it: `$$`.

Two more replacement-parser rules (both verified):

- **Group names parse greedily.** `$1x` reads as one reference to the (nonexistent) group *named* `1x` — `re_replace('10', '(\d+)', '$1x')` returns `""`, not `10x`. Brace the number whenever a word character follows: `'${1}x'` → `10x`. (`'$2.$1'` works only because `.` isn't a word char.)
- **An unknown group substitutes the empty string**, never an error — a typoed backref silently deletes the match.

**A pattern that matches nothing is also silent** — `re_replace` hands back the
subject unchanged, so in a read-modify-write file edit the input is written
straight back and the run reports success. `re_replace_must` (0.90.0) is the same
call that raises instead:

```mix
write_file($p, re_replace_must(read_file($p), "(?m)^version = .*$", $new, {count: 1, path: $p}))
```

Note the `(?m)` — without it `^`/`$` anchor to the whole text, not each line,
so a line-oriented pattern over a file's contents matches nothing. Before
`re_replace_must` that was a silent no-op that wrote the file back unchanged;
now it is a `NEEDLE_ABSENT` that names the file.

`NEEDLE_ABSENT` when nothing matched, `NEEDLE_COUNT` when `{count: n}` disagrees
with how many matches there were. `mix lint` flags the unguarded chain as
[MIX-D3014](lint.md).

### re_split — split on a pattern

`re_split(s, pattern)` splits `s` at each match and returns the pieces
as a list. Empty leading/trailing/adjacent pieces are **kept** (unlike a naive
trim), and a pattern that never matches yields the whole string as one element.

```mix
print(re_split("a, b ,c,  d", "\\s*,\\s*"))  -- comma + flexible spaces
print(re_split("ax12by34cz", "[0-9]+"))      -- split on digit runs
print(re_split(",a,,b,", ","))               -- empties preserved
print(re_split("no-commas", ","))            -- no match -> whole string
print(re_split("abc", ""))                   -- empty match at every boundary
```
```text
[a, b, c, d]
[ax, by, cz]
[, a, , b, ]
[no-commas]
[, a, b, c, ]
```

### grep_lines — regex line filter (always present)

`grep_lines(text, pattern)` returns the **lines** of `text` that match
`pattern`, as a list of strings (`[]` when none). Unlike the `re_*` four it
is **not** feature-gated — but when the `regex` feature is on (always, in
the `mix` binary) the pattern is a full regex with the same syntax and the
same invalid-pattern error; a library build without the feature falls back
to a literal substring test per line.

```mix
$t = "alpha\nbeta\ngamma\nbravo"
print(grep_lines($t, "^b"))
```
```text
[beta, bravo]
```

## Syntax flavor

The patterns are Rust-`regex` syntax — see the
[full grammar](https://docs.rs/regex/latest/regex/#syntax). The common pieces:

| Construct | Meaning |
|---|---|
| `.` `*` `+` `?` `{n}` `{n,m}` | any-char, repetition (greedy; add `?` for lazy: `+?`) |
| `[...]` `[^...]` | character class / negated class |
| `\d \w \s` (+ `\D \W \S`) | digit / word / whitespace classes (**Unicode-aware**) |
| `\b \B` | word / non-word boundary |
| `^` `$` | start / end (of text; of line with the `m` flag) |
| `(...)` | capturing group |
| `(?:...)` | non-capturing group |
| `(?P<name>...)` / `(?<name>...)` | named capturing group (both spellings work) |
| `(?i)` `(?m)` `(?s)` `(?x)` | inline flags: ignore-case, multiline, dot-all, verbose |
| `a\|b` | alternation |

Inline flag groups also scope: `(?i:abc)` is case-insensitive only inside.

`\d`/`\w` are **Unicode by default**, so accented letters count as word chars
(offsets in codepoints — `é` is one):

```mix
print(re_find("café über", "\\w+"))
```
```text
[{match: café, start: 0, end: 4}, {match: über, start: 5, end: 9}]
```

Matching is codepoint-exact with **no Unicode normalization**: precomposed `é`
(U+00E9) does not match decomposed `e` + combining acute —
`re_match("e\u{0301}", "é")` → `false` — so normalize first when inputs mix
forms (same rule as the plain byte-exact string ops, [strings](strings.md)).
Case-insensitive `(?i)` *does* full Unicode case-folding: `(?i)é` matches `É`.

Multiline `^`/`$` (the `(?m)` flag) anchor per line:

```mix
print(re_find("alpha\nbeta\ngamma", '(?m)^\w+'))
```
```text
[{match: alpha, start: 0, end: 5}, {match: beta, start: 6, end: 10}, {match: gamma, start: 11, end: 16}]
```

## Quoting traps

This is where most regex bugs in Mix come from. A pattern is a string, and Mix
string rules ([strings](strings.md)) run **before** the regex crate sees a
single byte.

**1. Backslashes.** In a `"double-quoted"` Mix string you escape each backslash:
`"\\d"` is the two characters `\d` that the regex wants. In a `'single-quoted'`
string a backslash is **literal**, so `'\d'` is already `\d` — single quotes are
usually the cleaner choice for a regex.

```mix
print(re_match("x42", "\\d+"))   -- double quotes: \\ -> \
print(re_match("x42", '\d+'))    -- single quotes: \ literal, same result
```
```text
true
true
```

**2. `${...}` in double quotes interpolates.** A double-quoted `"${host}"` is a
scope/env lookup that resolves to `nil` if unset — *before* the regex engine
runs. This silently corrupts a named-group replacement:

```mix
-- WRONG: "${host}" interpolates to nil at string-build time
print(re_replace('joe@acme', '(?P<u>\w+)@(?P<h>\w+)', "${h}/${u}"))
-- RIGHT: single quotes keep ${h}/${u} literal for the regex crate
print(re_replace('joe@acme', '(?P<u>\w+)@(?P<h>\w+)', '${h}/${u}'))
```
```text
nil/nil
acme/joe
```

A **bare** `$1` (no braces) is *literal* in a double-quoted Mix string, so
numbered backrefs happen to survive double quotes — but `${name}` does not.
**Rule of thumb: single-quote regex patterns and replacements** and you sidestep
both traps. (`$(...)` is also literal in a Mix string — it does not run a
command here.)

## Errors and validation

An invalid pattern, or an unsupported construct, raises a **catchable** runtime
error and exits non-zero from `-c`:

```mix
print(re_match("x", "[unterminated"))
```
```text
Runtime error at line 1: invalid regex '[unterminated': regex parse error:
    [unterminated
    ^
error: unclosed character class
```

**Long or multi-line patterns get a truncated diagnostic** (0.63.0). A
pattern over 80 characters — almost always a **swapped call** that passed
the *subject* as the pattern — is echoed truncated with only the regex
engine's final `error:` line, plus a hint naming the usual cause, instead
of printing the whole document back:

```text
Runtime error at line 2: invalid regex 'line of roster text line of …' (8020 chars, truncated): error: repetition quantifier expects a valid decimal
  (in the re_* family the SUBJECT comes first and the PATTERN second — a
  swapped argument order is the usual cause of a huge pattern: see mix man regex)
```

A swapped call where both compile is *silent* (`re_match($pattern, $text)`
is just a "no") — but subject-first matches every other string builtin, so
the muscle memory that writes `replace($s, …)` writes `re_replace($s, …)`
correctly too. That consistency is what retired the legacy family's trap.

Wrap user-supplied patterns in `try`/`catch` so a bad pattern doesn't abort the
script ([errors](errors.md)):

```mix
try
  print(re_match($text, $user_pattern))
catch $e
  print("bad pattern: " .. ("" .. $e))
end
```

Wrong arity is a runtime error too:

```mix
print(re_match("a"))
```
```text
Runtime error at line 1: re_match() expects at least 2 argument(s), got 1
```

## Limitations

The Rust `regex` crate guarantees linear-time matching by **not** supporting
features that require backtracking. Both raise a compile error, not a silent
mismatch:

```mix
print(re_match("aa", "(a)\\1"))         -- backreference
print(re_match("foobar", "foo(?=bar)")) -- lookahead
```
```text
Runtime error at line 1: invalid regex '(a)\1': regex parse error:
    (a)\1
       ^^
error: backreferences are not supported
```
```text
Runtime error at line 1: invalid regex 'foo(?=bar)': regex parse error:
    foo(?=bar)
       ^^^
error: look-around, including look-ahead and look-behind, is not supported
```

If you reach for a backreference, usually a non-regex approach works:
`contains`/`split`/`replace`/`starts_with` for fixed substrings (byte-exact, no
pattern compile), or extract groups with `re_find` then compare in Mix code.

There is also no compiled-pattern value type; the shared compile cache (see
[The family](#the-family)) means a repeated pattern is usually compiled
once, but a pattern evicted by more than 32 others, or too big to cache,
compiles again. A script that builds a new pattern on every iteration still
compiles every time,
and for a tight inner loop one `re_find` over the whole input still beats a
per-element `re_match`, because each call costs an interpreter round trip.

## Recipes

**Extract numbers and sum them** — `re_find` + the [HOF](hof.md) builtins
`map`/`reduce`:

```mix
$ms = re_find('a1 b22 c333', '\d+')
$nums = map($ms, fn($m) = to_number($m["match"]))
print($nums)
print(reduce($nums, 0, fn($a, $b) = $a + $b))
```
```text
[1, 22, 333]
356
```

**Parse `key=value` lines** with named groups:

```mix
$ms = re_find('host=node1 port=8443 tls=on', '(?P<k>\w+)=(?P<v>\S+)')
$out = map($ms, fn($m) = $m["groups"][0] .. " -> " .. $m["groups"][1])
print(join($out, "\n"))
```
```text
host -> node1
port -> 8443
tls -> on
```

**Normalize whitespace** — collapse any run of spaces/tabs/newlines to one space:

```mix
print(re_replace("  too    much\twhitespace ", '\s+', " "))
```
```text
 too much whitespace 
```

**Redact something that looks like a secret** before logging:

```mix
print(re_replace("user=joe token=abc123 ok", '(?i)(token|password)=\S+', "$1=***"))
```
```text
user=joe token=*** ok
```

## See also

- [strings](strings.md) — quoting (`'raw'` vs `"${...}"`), codepoint vs byte ops; read this *first* for regex patterns
- [collections](collections.md) — the `{match, start, end, groups}` maps and `groups` lists `re_find` returns
- [functions](functions.md) / [hof](hof.md) — lambdas and `map`/`filter`/`reduce` for processing match lists
- [control-flow](control-flow.md), [errors](errors.md) — `if`/`try`/`catch` around match predicates and bad patterns
- [builtins](builtins.md) — full builtin index; [the manual index](README.md)
- Rust [`regex` crate syntax reference](https://docs.rs/regex/latest/regex/#syntax) — the authoritative pattern grammar (RE2-style)
- [RE2 design notes](https://github.com/google/re2/wiki/WhyRE2) — why linear-time matching means no backreferences/look-around
- `mix help` for the builtin overview; `mix what re_match` (etc.) for the one-line signatures

---

<!-- page: https://mixos.dev/mix/remote/ (source: https://mixos.dev/mix/remote.md) -->

# Remote execution (SSH)

Mix runs commands on other machines through four builtins that wrap the system `ssh` binary: **`ssh_run`** (structured result, never raises), **`ssh_must`** (returns stdout or dies), **`ssh_mix`** (runs Mix *source* on a remote node over the ssh stdin channel — zero quoting pain), and **`ssh_exec`** (runs an argv list on a remote node with truthful argv semantics via the remote run_argv, v0.30.0). The first two are the remote-host analogue of [`run_rc`/`run`](system.md) — same result-as-data philosophy, same "non-zero exit is data, not an exception" stance — extended with ssh-specific fields and a built-in wall-clock timeout.

All four wrap the real `ssh` client via `std::process::Command`. There is **no** native SSH client inside Mix: host alias resolution, `~/.ssh/config`, identity files, ports, `ProxyJump`, agents, hardware keys, and certificates are all `ssh`'s job. Mix passes the host string straight through (after validating it — see §"Host validation") and lets `ssh` resolve it. By convention pass an ssh **alias** (a bare host name from `~/.ssh/config`) rather than a raw IP.

The far-end Mix process records its ordinary `stdin`, `c`, or `script` mode;
there is no special remote tag. Set `MIX_STATS=off` in the remote environment
when fleet execution must perform no collection or stats I/O. See [usage
statistics](stats.md).

> All examples here use placeholder hosts (`alpha`, `node1`, or `192.0.2.x`
> from RFC 5737). In real use, substitute an alias from your `~/.ssh/config`.

## Headline idiom: `ssh_mix` + heredoc

For multi-line remote Mix, pass a heredoc directly as the `source` argument to
`ssh_mix`. The bytes travel over ssh stdin into `/opt/mixos/bin/mix -` (or the
[`mix_bin`](#ssh_mixhost-source-opts--map) you name); no
shell parses the source on the way.

```mix
$r = ssh_mix("alpha", <<EOF
$h = run_argv_must(["hostname"])
print("remote host: " .. trim($h))
EOF
)
print($r["stdout"])
```

Actual output:

```text
remote host: alpha
```

### Heredoc interpolation: bare is remote, braced is local

This is the safety rule that makes the form useful. A bare `$name` in a
heredoc passes through **literally**, so the remote Mix interpreter resolves
it. Only `${name}` interpolates locally before the source is sent.

```mix
$local = "LOCAL"
$r = ssh_mix("alpha", <<EOF
$who = "REMOTE"
print("bare=" .. $who)
print("braced=${local}")
EOF
)
print($r["stdout"])
```

Actual output:

```text
bare=REMOTE
braced=LOCAL
```

### Pass local values with `bindings`

Use the `bindings` option when local data belongs in the remote program.
`ssh_mix(host, source, {bindings: {path: $target}})` strict-data-encodes each
value and prepends a real `$name = value` assignment. The value remains data;
it cannot break out into shipped source.

```mix
$target = "/srv/app dir; still-data"
$r = ssh_mix("alpha", <<EOF
print("path=" .. $path)
EOF
, {bindings: {path: $target}})
print($r["stdout"])
```

Actual output:

```text
path=/srv/app dir; still-data
```

The result map always has these eleven keys:

```text
stdout  stderr  exit_code  ok  duration_ms  host
timed_out  interrupted  utf8_lossy
stdout_truncated  stderr_truncated
```

The exit-status key is **`exit_code`**, not `rc`. Reading `$r["rc"]` yields
`nil` silently, so branch on `$r["ok"]` or inspect `$r["exit_code"]`.

### Why not `ssh_run` for Mix source?

`ssh_run` sends a command string for the remote shell to parse. Nesting Mix in
that string creates escape ladders:

```mix
ssh_run("alpha", "print(run(\"/opt/mixos/bin/mix -c 'print(which(\\\"sh\\\"))'\"))")
```

The heredoc form ships the intended program directly:

```mix
ssh_mix("alpha", <<EOF
print(which("sh"))
EOF
)
```

Use `ssh_run` for an actual remote-shell snippet; use `ssh_mix` + heredoc for
remote Mix source.

```mix
$r = ssh_run("node1", "uptime")
if $r.ok then
  print($r.stdout)
else
  print("failed (" .. ("" .. $r.exit_code) .. "): " .. $r.stderr)
end
```

---

## `ssh_run(host, command[, opts])` → map

Runs `command` on `host` and returns a result map. **Never raises** on a remote failure — branch on `.ok` (or `.exit_code`). The only errors it raises are *local argument* errors (bad host, bad opts), surfaced before any ssh is spawned.

### Signature

```mix
ssh_run(host, command)            -- command: a string (a remote-shell snippet)
ssh_run(host, commands)           -- commands: a list of strings, joined with " && "
ssh_run(host, command, opts)      -- opts: a map (see below)
```

| Arg | Type | Notes |
|---|---|---|
| `host` | string | An ssh alias (`node1`), `user@host`, or `user@host` with a `Port` from `~/.ssh/config`. Validated (§"Host validation"), then resolved by `ssh`, never parsed by Mix. |
| `command` / `commands` | string \| list of strings | Each element is a **remote-shell snippet** (it reaches the remote shell verbatim — §"Quoting"). A list is joined with literal ` && `; an empty list is an error. |
| `opts` | map | Optional. Unknown keys are rejected. See §"Options". |

### Host validation

The host string must be non-empty, contain no NUL bytes, and **must not begin with `-`**. A dash-leading host would let `ssh` parse it as an option — `-oProxyCommand=<cmd>` executes an arbitrary *local* command before any connection (a local RCE whenever the host value is config- or agent-derived). Defense in depth: the builtin rejects a leading-dash host up front, *and* the constructed argv always places a literal `--` (end of options) immediately before the host so ssh can never read it as an option. `ssh_must` and `ssh_mix` funnel through the same guards.

```mix
ssh_run("-oProxyCommand=touch /tmp/pwned", "echo hi")
-- Runtime error: ssh_run: host must not begin with '-' (got "-oProxyCommand=touch /tmp/pwned")
```

### Return map

```mix
{
  stdout:      "...",   -- trimmed (trailing newline stripped); never nil
  stderr:      "...",   -- trimmed; never nil
  exit_code:   0,       -- integer; 0 = success
  ok:          true,    -- convenience: exit_code == 0 (a real bool)
  duration_ms: 142,     -- wall-clock from spawn to exit
  host:        "node1", -- echoed back, handy for logging
  stdout_truncated: false, -- true if local stdout capture is incomplete
  stderr_truncated: false, -- true if local stderr capture is incomplete
  timed_out:   false,   -- true if killed by opts.timeout
  interrupted: false,   -- true if killed by Ctrl-C
  utf8_lossy:  false    -- true if a pipe held invalid UTF-8 (replaced with U+FFFD)
}
```

`exit_code` carries sentinels for local outcomes that aren't a real remote exit status:

| `exit_code` | Meaning |
|---|---|
| `0` | success (`ok == true`) |
| `255` | ssh-level failure (couldn't connect, auth failed, host-key refused) |
| `-1` | local **timeout** fired (`timed_out == true`) |
| `-2` | **interrupted** by Ctrl-C (`interrupted == true`) |
| `-3` | exited with no code and no signal (non-Unix fallback / unclassifiable edge) |
| `128 + signo` | remote command killed by a signal |
| other | the remote command's own exit status |

Note the field is named `exit_code`, **not** `rc` (which is what [`run_rc`](system.md) uses) — so the two result maps are deliberately not interchangeable, and a remote `exit_code` doesn't get confused with a local `rc` when both appear in the same script.

### Verified: failure is data, not an exception

A connection failure comes back as an ordinary map — the script keeps running.

```mix
$r = ssh_run("192.0.2.1", "echo hi", { connect_timeout: 2, timeout: 4 })
print("ok="        .. ("" .. $r.ok))
print("exit_code=" .. ("" .. $r.exit_code))
print("timed_out=" .. ("" .. $r.timed_out))
print("host="      .. $r.host)
print("stdout=["   .. $r.stdout .. "]")
print("stderr=["   .. $r.stderr .. "]")
```

```text
ok=false
exit_code=255
timed_out=false
host=192.0.2.1
stdout=[]
stderr=[ssh: connect to host 192.0.2.1 port 22: Connection timed out]
```

The full key set (every call returns all eleven):

```text
stdout
stderr
exit_code
ok
duration_ms
host
timed_out
interrupted
utf8_lossy
stdout_truncated
stderr_truncated
```

### The `.ok` predicate — there is no `ssh_ok` / `ssh_try`

Mix ships exactly four SSH builtins: `ssh_run`, `ssh_must`, `ssh_mix`, and `ssh_exec`. Don't reach for `ssh_ok` or `ssh_try` — they don't exist. For a boolean test, use `ssh_run(...).ok`:

```mix
if ssh_run("node1", "systemctl is-active nginx").ok then
  print("nginx is up")
end
```

For fail-fast, use `ssh_must` (below).

---

## `ssh_must(host, command[, opts])` → stdout string (or dies)

Same arguments as `ssh_run`. On success (`ok == true`) it returns the command's **stdout string**. On *any* non-success — non-zero exit, timeout, interrupt, or signal-kill — it raises a catchable `RuntimeError` whose message names the host, the disposition, the `exit_code`, and the first 512 bytes of stderr.

```mix
$kernel = ssh_must("node1", "uname -r")
print("remote kernel: " .. $kernel)
```

Verified failure message (unreachable host):

```mix
$out = ssh_must("192.0.2.1", "echo hi", { connect_timeout: 2, timeout: 4 })
print($out)
```

```text
Runtime error at line 1: ssh_must: failed on 192.0.2.1 (exit_code=255): ssh: connect to host 192.0.2.1 port 22: Connection timed out
```

The disposition word is `failed`, `timed out`, or `interrupted` depending on `timed_out`/`interrupted`. Catch it like any other raising builtin:

```mix
try
  $v = ssh_must("node1", "test -f /etc/myapp.conf")
  print("config present")
catch $e
  print("config missing or host down: " .. ("" .. $e))
end
```

**Pick the right one:** `ssh_must` when failure is genuinely fatal and a `try`/`catch` would just be noise; `ssh_run` whenever you need finer control than "succeed or abort" — e.g. a `test -f` that returns 1 for "absent" is a perfectly valid answer, not an error.

---

## `ssh_mix(host, source[, opts])` → map

Runs Mix **source** on a remote node with zero quoting pain. It ships `source` over ssh's **stdin** byte-channel into `/opt/mixos/bin/mix -`, so the source never becomes an argv word and bypasses *every* shell-quoting layer — the local shell, ssh, and the remote login-shell classifier. Arbitrary quotes, `$`, backslashes, and newlines survive intact. It is the discoverable, first-class form of the `ssh_run(host, "mix -", { stdin: $source })` idiom.

Start with the [headline `ssh_mix` + heredoc pattern](#headline-idiom-ssh_mix--heredoc)
above. This section supplies the remaining option and decoding contract.

> **`mix lint` reads the body (0.69.0).** Because `source` is Mix source,
> lint parses it when it is a **literal** — a string, an inline heredoc, or a
> variable bound exactly once to either — and reports its diagnostics
> against your file, prefixed `[inside ssh_mix body]`, at mapped line numbers.
> A double-quoted body whose lines are `\n` escapes reports everything on
> the one physical line the literal occupies; a physically multi-line
> literal and a heredoc map line-for-line. Names in the body resolve
> against the body itself, the builtins, and the call's `bindings`/`env`
> keys — the opts argument is read statically when it is a map literal or
> a variable bound exactly once to one. When the opts cannot be read, only
> undefined-**variable** checks stand down (`MIX-D3018`): a function name
> cannot ride in through strict-data bindings, so undefined-function
> checks still run. A body lint cannot read — any other variable, a
> concatenation, an interpolated string, a `read_file`, or a literal that
> does not parse — is reported as **`MIX-D3012`** rather than passing
> silently. Prefer a literal and the [`bindings`](#options-map) option
> over interpolation: it is both safer (no injection through string
> building) and the only form lint can check. See
> [lint](lint.md#remote-bodies--lint-sees-inside-ssh_mix-0690).

```mix
$r = ssh_mix("node1",
             "print(data_encode({host: hostname(), kernel: trim(run(\"uname -r\"))}))",
             { decode: "data", timeout: 5 })
if $r.ok then print($r.value.kernel) end
```

For source stored in a file, pass caller values separately with `bindings`:

```mix
$job = {action: "inspect", paths: ["/srv/a", "/srv/b"]}
$source = read_file("remote-job.mix")
$r = ssh_mix("example.com", $source, {
  bindings: {job: $job, dry_run: true},
  decode: "data"
})
```

- **Returns the same map as `ssh_run`** (all eleven keys). With `decode`, a twelfth key `value` is added on success.
- **`max_output` bounds local capture**, independently for stdout and stderr. A truncated stdout **refuses to decode**: `decode: "data"` (or `"json"`) raises rather than parsing partial data, because a truncated prefix of valid output can itself parse as a smaller, *wrong* value (`12345` capped mid-number decodes as `12`). To work with partial output, omit `decode`, check `stdout_truncated`/`stderr_truncated`, and parse what you need yourself. The limit does not change a remote `run_argv` limit.
- **`decode: "data"` or `decode: "json"`** parses the trimmed stdout into `.value` (via `data_parse` / `json_parse`) — the common "get a structured value back from the remote" case. Pair it with [`data_encode`](data.md) on the remote side, as above. `decode: "json"` needs the `json` feature (the `mix` binary has it; a bare library build without it errors — use `decode: "data"`). On failure (`ok == false`) no `value` key is added — check `.ok` first.
- **`bindings` is a typed data channel:** it is a map from names to strict-data-encodable Mix values. Each key must match `[A-Za-z_][A-Za-z0-9_]*`; each value is strict-data-encoded locally and prepended to the shipped source as a `$name = value` assignment. Strings, numbers, bools, `nil`, lists, and maps retain their types, including nested values. Bytes and buffers have no strict-data representation and raise `OPTION_INVALID` locally; encode binary data explicitly (for example with base64) and decode it remotely.
- **No binding name is reserved.** Names such as `args` and `argv` are legal. Bindings run first, so the caller source may legally rebind any of them; this is convenience and injection safety, not isolation.
- **Order of the prepended prefix is `env` exports, then `bindings`, then your source.** A binding of the same name therefore shadows the exported **variable** but not the exported **environment**: with `{env: {FOO: "x"}, bindings: {FOO: "y"}}` the remote sees `$FOO == "y"` while `env("FOO") == "x"` and any child process still inherits `FOO=x`. Your source can rebind either. Give them distinct names unless you mean exactly that.
- **Accepts every `ssh_run` opt except two:** `stdin` (the source *is* the stdin — passing it is an error) and `env_transport` (not applicable — see below).
- **`env` works and is secret-safe:** the values are translated into hidden `export KEY = "value"` lines (strict-data-escaped) *prepended to the shipped source*, so they travel on stdin and never touch `ps` argv on either end.
- **The remote binary is configurable** (0.116.0). In order: the **`mix_bin`** option, else the **local** environment variable **`MIX_REMOTE_BIN`** (an empty value counts as unset), else the default **`/opt/mixos/bin/mix`** (the canonical MixOS install dir; it was the legacy `/opt/mixos/bin/mix` up to 0.116.0, so pass `mix_bin` or set `MIX_REMOTE_BIN` for a not-yet-migrated host). The same resolution serves every builtin that drives a remote mix: `ssh_mix`, `ssh_mix_many`, `ssh_exec` (which also keeps its older name `remote_mix`), `ssh_run`'s default `env_transport: "mix"`, and `send_mail`'s `host` hop. The value lands in the remote command string, so it must be an absolute path (`/opt/mixos/bin/mix`) or a bare name the remote PATH resolves (`mix`), using only `[A-Za-z0-9_./+-]`; anything else (a space, `;`, `$`, a leading `-`, a relative path) raises `OPTION_INVALID` locally before ssh runs. Prefer a full path: a bare `mix` is often not on the remote's non-interactive PATH. `ssh_mix` is for nodes with mix installed, not arbitrary POSIX hosts.

  ```mix
  $r = ssh_mix("node1", "print(1+1)", {mix_bin: "/opt/mixos/bin/mix"})
  -- or once for the whole script's environment:  MIX_REMOTE_BIN=/opt/mixos/bin/mix mix script.mix
  ```
- **Inherits every `ssh_run` host guard** (empty, NUL, leading-dash — verified: a `-oProxyCommand=` host is rejected through `ssh_mix` too, before any spawn).
- **`timeout` is in SECONDS**, like every ssh/run timeout opt (§"Options"). The Bus `send … timeout=2000` form is the only millisecond surface in Mix — `timeout: 5000` here is 83 minutes, not 5 seconds.

For source maintained as a separate program, use [`read_file`](io.md). For
inline multi-line work, prefer the headline heredoc form. Note the stdin
channel is *consumed by the program itself*: `ssh_mix` ships source fine but
cannot also feed stdin to a `run()` that the remote script calls (see §"stdin
caveat").

Verified argument errors (raised locally, before any ssh):

```mix
ssh_mix("node1")
-- Runtime error: ssh_mix: expected 2 or 3 args (host, source, [opts]), got 1

ssh_mix("node1", "print(1)", { stdin: "x" })
-- Runtime error: ssh_mix: `stdin` opt is not allowed — the source argument is the stdin

ssh_mix("node1", "print(1)", { env_transport: "mix" })
-- Runtime error: ssh_mix: `env_transport` is not applicable — ssh_mix always ships env
--   as hidden `export` lines inside the stdin source

ssh_mix("node1", "print(1)", { decode: "xml" })
-- Runtime error: ssh_mix: decode must be "data" or "json", got String("xml")

ssh_mix("example.com", "print(1)", { bindings: {"bad-name": 1} })
-- OPTION_INVALID: ssh_mix: invalid bindings key "bad-name"
--   (must match [A-Za-z_][A-Za-z0-9_]*)
```

---

## `ssh_mix_many(hosts, source[, opts])` → map host → result

`ssh_mix` on many hosts at once, through a bounded worker pool. Every host gets
the same `source`, `bindings`, `env` and `decode`. The result is a **map keyed
by host, in input order**, and each value is **exactly** the map `ssh_mix`
would have returned for that host, so per-host handling code ports unchanged.

```mix
$hosts = ["alpha", "beta", "gamma"]
$r = ssh_mix_many($hosts, <<EOF
print(data_encode({host: hostname(), files: length(ls($path))}))
EOF
, {bindings: {path: "/srv"}, decode: "data", timeout: 10, max: 8})
for each $h, $res in $r
  if $res.ok then
    print($h .. ": " .. $res.value.files .. " entries")
  else
    print($h .. ": FAILED " .. ($res.decode_error ?? $res.stderr))
  end
end
```

- **opts are `ssh_mix`'s opts plus `max`** — concurrency, default 8, at most
  256 live workers (a larger `max` still runs every host, just no more than
  256 at once). These are the same numbers as `run_parallel`; the loop is its
  own, with per-host error semantics.
- **Everything is validated before anything runs.** The options go through
  `ssh_mix`'s own checks once, even for an empty host list, and every host is
  checked, so a bad option, a bad binding or a bad host (empty, leading `-`,
  NUL) raises locally with no ssh spawned. Only a host error names the host.
  A wrong argument type (hosts not a list, source not a string, opts not a
  map, wrong arity) raises `TYPE_MISMATCH`.
- **After that, one host's failure is data in its own map, never a raise.**
  An unreachable host, a nonzero exit and a timeout come back as `ok: false`
  exactly as `ssh_mix` reports them. A local failure to run ssh for one host
  (a spawn or pipe error, such as running out of file descriptors at a high
  `max`) comes back as `ok: false` with `error_code` (`PROCESS_SPAWN`,
  `PROCESS_STDIO`, …) and `error`, and the other hosts keep their answers.
- **Ctrl-C stops the batch.** Workers check for an interrupt before taking a
  host and again before starting ssh, so no new host starts after it. Hosts
  already running end as `interrupted: true`, as with `ssh_mix`. Hosts never
  started come back as `ok: false, interrupted: true` with nothing run.
- **There is no whole-call deadline.** `timeout` bounds each host. The worst
  case for the call is about `ceil(hosts / max)` × (`timeout` +
  `connect_timeout`).
- **`decode` is judged per host.** Where `ssh_mix` *raises* — a stdout
  truncated by `max_output`, or stdout that does not parse — the fan-out
  records the refusal on that host alone: `ok: false`, a `decode_error`
  string, and no `value`. `exit_code` still shows what the remote did. A raise
  here would throw away every other host's answer, which is the failure a
  fan-out exists to avoid.
- **`hosts` must be unique strings.** Results are keyed by host, so a
  duplicate raises rather than silently overwriting the first answer.
- **`timeout: 0` is refused.** With no deadline one hung host would hold the
  whole batch, because the call waits for every worker.
- **`mix lint` reads the body** exactly as it does for `ssh_mix`, including
  the `bindings`/`env` names.

This is the sugar over `run_parallel` + hand-built `["ssh", host, "/opt/mixos/bin/mix", "-"]`
jobs: those lose `bindings`, `decode` and the `host`/`ok` result shape.

---

## `ssh_exec(host, argv[, opts])` → map (v0.30.0)

The remote analogue of [`run_argv`](system.md): run an **argv list** on a remote
node with truthful, injection-inert argv semantics. OpenSSH only accepts a remote
command *string*, so a naive `ssh host <argv joined>` can't promise argv-inertness
across the wire. `ssh_exec` instead ships a strict-data Mix **driver** over the ssh
stdin channel that reconstructs the argv + options as data and invokes the remote
`run_argv` — no shell, no quoting, on either end.

```mix
$r = ssh_exec("hypervisor.example.net", ["pct", "start", "" .. $vmid], {timeout: 60})
if not $r.ok then
  eprint("start failed on " .. $r.host .. ": " .. $r.stderr)
end
```

The result is the full [`run_argv` process_result](system.md) map (`ok`,
`exit_code`, `stdout`, `stderr`, `timed_out`, `signal`, `duration_ms`,
truncation/lossy flags, …) plus **`host`**. Options split into two groups:

- **Remote `run_argv` options** — `timeout` (the remote command deadline,
  default 30 s, `0` = unbounded which also lifts the auto transport ceiling),
  `cwd`, `env`, `clear_env`, `max_output`, plus the protocol-safe stdio routes
  below — are encoded into the driver and applied to the remote `run_argv`
  call. `env`/`stdin` never appear in argv on either end.
- **SSH transport options** — `connect_timeout`, `transport_timeout` (the ssh wall-clock deadline, default = remote `timeout` + `connect_timeout` + 5 s), `batch`, `strict_host_key`, `multiplex`, `extra_ssh_args`, and `mix_bin` (the remote binary path; older name `remote_mix`, still accepted; resolved and validated exactly as for [`ssh_mix`](#ssh_mixhost-source-opts--map): `mix_bin` > local `MIX_REMOTE_BIN` > `/opt/mixos/bin/mix`).

The remote stdio allowlist is deliberately narrower than local `run_argv`:

- `stdout`: `"capture"`, `"null"`, or `{file: path, append?, mode?}`;
- `stderr`: `"capture"`, `"null"`, `"stdout"`, or the same file map;
- `stdin`: `nil`, a string, `{file: path}`, or `{null: true}` — exactly the local
  grammar minus binary. Bytes/buffer cannot cross the strict-data driver and
  raise `OPTION_INVALID`.

`stdout: "inherit"`, `stderr: "inherit"`, and `stream: true` raise
`OPTION_INVALID` **locally, before ssh is opened**. Inherited remote stdout would
interleave child bytes with ssh_exec's one strict-data result envelope; inherited
remote stderr lands in the outer ssh stderr that the success decoder discards;
and live teeing has the same envelope problem.

There is **no** `stdin: "inherit"` route to reject, here or locally: a stdin
string is always data, including the seven bytes `inherit`, and `nil` always
means closed stdin. The ssh stdin channel carries the driver, and the driver
carries whatever stdin you asked for as data — so the same value means the same
thing on both sides of the hop. A path inside any `{file: ...}` route is
resolved and opened on the **remote host**, not the machine calling `ssh_exec`.
The remote command deadline starts before that open. A FIFO input with no
writer reaches the deadline as remote `PROCESS_STDIO`; a FIFO output with no
reader fails immediately as remote `PROCESS_STDIO`. Neither case spawns the
requested command.

Two limits the allowlist cannot enforce for you:

- **A remote-version floor.** Routing options are forwarded to the remote
  `run_argv`; a remote old enough to have `run_argv` but not stdio routing
  rejects them inside the driver, which comes back as `SSH_PROTOCOL` with the
  remote's message. That is truthful but generic — deploy a current `mix` to a
  host before routing remote stdio on it.
- **An explicit path can still reach the envelope.** `{file: "/dev/stdout"}` or
  `{file: "/proc/self/fd/1"}` names the driver's own stdout, so the child's
  bytes are interleaved with the strict-data reply and the call comes back
  `SSH_PROTOCOL` instead of a result. Nothing *option-shaped* slips past the
  allowlist; a path that deliberately aliases the channel is your choice, and
  it fails loudly rather than silently.

Failure modes are encoded in the result, never raised (argv/option *validation*
does raise, locally, before any ssh):

- transport failure → `error_code` `SSH_TIMEOUT` / `SSH_INTERRUPTED` / `SSH_TRANSPORT`, `exit_code: nil`;
- an undecodable remote reply → `SSH_PROTOCOL`;
- a remote binary **older than 0.29** (no `run_argv`) → `ok:false`, `error_code: "SSH_REMOTE_UNSUPPORTED"`, and the command is **not run** — `ssh_exec` refuses to silently change injection/capture/timeout guarantees rather than fall back to a shell.

`ssh_exec` inherits every `ssh_run` host guard (empty / NUL / leading-dash
rejected). Use it for structured remote steps where you'd reach for `run_argv`
locally; `ssh_mix` remains the path for arbitrary multi-step remote Mix programs.

---

## Options map

Every key is optional; unknown keys raise an error. `ssh_mix` takes the same map minus `stdin`/`env_transport`, plus its own `decode` and `bindings`; see its section above for the typed binding contract.

| Key | Type | Default | Effect |
|---|---|---|---|
| `timeout` | int (**seconds**) | `30` | Hard wall-clock deadline. `0` disables it. On expiry: SIGKILL the process group, `timed_out = true`, `exit_code = -1`. |
| `connect_timeout` | int (seconds) | `10` | Passed as ssh's `-o ConnectTimeout=`. Bounds the connect phase only. |
| `max_output` | positive int (bytes) | unbounded | Maximum bytes retained locally per stream, before UTF-8 conversion and trailing whitespace trimming. Must be a whole number from 1 through the smaller of 2^53−1 and the platform's `usize::MAX`; zero, negatives and non-numbers are rejected. Excess bytes are drained and discarded; `stdout_truncated` / `stderr_truncated` identifies each incomplete capture. |
| `multiplex` | bool | `false` | Connection reuse via `ControlMaster=auto` / `ControlPath=$HOME/.ssh/cm-%C` / `ControlPersist=60s`. See the caveat below. |
| `batch` | bool | `true` | `-o BatchMode=yes` — never prompt for a password/passphrase; fail instead. Keep it on for unattended scripts. |
| `strict_host_key` | string | `"accept-new"` | `-o StrictHostKeyChecking=`. One of `yes`, `no`, `accept-new`, `ask`. |
| `env` | map | `{}` | Remote env vars. Keys must match `[A-Za-z_][A-Za-z0-9_]*`; values may be string/number/bool (whole numbers inside i64 render as integers; since 0.59.0 a whole number at or above 2^63, or below −2^63, renders as its own shortest round-trip decimal instead of saturating to an i64 extreme, which is a different number; −2^63 itself is exactly representable and renders as the integer). **How the values travel is `env_transport`'s job** — by default they go over ssh stdin inside a driver, never in `ps` argv. See §"Remote env". |
| `env_transport` | string | `"mix"` | `"mix"` \| `"sh"` \| `"argv"` — the transport for `env` values. Inert when `env` is empty. See §"Remote env". |
| `cwd` | string | — | Prepends `cd '<cwd>' && ` to the remote command (quoted for you). |
| `stdin` | string | — | Fed to the remote command's stdin over the local ssh pipe. May contain NULs (binary payloads). Conflicts with `env` under the secure transports (§"Remote env"). |
| `extra_ssh_args` | list of strings | `[]` | Extra argv inserted before the host: `["-p", "2222"]`, `["-J", "jump"]`, `["-o", "IdentitiesOnly=yes"]`. Always followed by the `--` host guard. |
| `mix_bin` | string | local `MIX_REMOTE_BIN`, else `/opt/mixos/bin/mix` | The remote mix binary for `env_transport: "mix"` (and for `ssh_mix`, which always pipes into it). Absolute path or bare name, `[A-Za-z0-9_./+-]` only; see [`ssh_mix`](#ssh_mixhost-source-opts--map). (0.116.0) |

Omitting `max_output` preserves unbounded local capture. The truncation flags
are also true when capture is abandoned at a deadline, even without a limit.
Truncation does not change `ok` or `exit_code`; `ssh_must` still returns stdout
on a zero exit status, so use `ssh_run` to inspect capture completeness.

Two deliberate edges. `max_output: 0` is **rejected** here, although `run_argv`
treats 0 as unbounded — an SSH capture bound exists to be a bound, and "omit
the key" already spells unbounded; the divergence is loud (a local raise), not
silent. And a cap that cuts inside a multibyte UTF-8 sequence leaves an invalid
final byte, so the lossy decode inserts U+FFFD and `utf8_lossy` reads true —
beside `stdout_truncated: true` that usually means local truncation damage,
not invalid remote output.

### Verified option errors (raised locally, before any ssh)

```mix
ssh_run("node1", "echo hi", { foo: 1 })
-- Runtime error: ssh_run: unknown opts key "foo" (allowed: timeout, max_output, connect_timeout,
--   multiplex, batch, strict_host_key, env, env_transport, cwd, stdin, extra_ssh_args, mix_bin)

ssh_run("node1", "echo hi", { timeout: "soon" })
-- Runtime error: ssh_run: timeout must be a non-negative integer

ssh_run("node1", "echo hi", { strict_host_key: "maybe" })
-- Runtime error: ssh_run: strict_host_key "maybe" not in ["yes", "no", "accept-new", "ask"]

ssh_run("node1", "echo hi", { env_transport: "ftp" })
-- Runtime error: ssh_run: env_transport "ftp" not in ["mix", "sh", "argv"]

ssh_run("node1", "echo hi", { env: { K: "v" }, stdin: "x" })
-- Runtime error: ssh_run: `env` and `stdin` conflict — the secure env driver owns stdin;
--   pass env_transport: "argv" to combine them (env values then appear in ps argv on both ends)

ssh_mix("node1", "print(1)", { mix_bin: "mix; rm" })
-- OPTION_INVALID: ssh_mix: mix_bin "mix; rm" contains ';', which is not allowed (want an absolute
--   path like "/opt/mixos/bin/mix" or a bare name like "mix", using only [A-Za-z0-9_./+-])

ssh_run("", "echo hi")
-- Runtime error: ssh_run: host must not be empty

ssh_run("node1", [])
-- Runtime error: ssh_run: commands list is empty

ssh_run("node1")
-- Runtime error: ssh_run: expected 2 or 3 args (host, command, [opts]), got 1
```

### The built-in timeout — don't wrap ssh in your own

`ssh_run` enforces a wall-clock deadline itself, so you never need `timeout 5 ssh ...`. On expiry it SIGKILLs the whole ssh process group (so descendant helpers can't keep the output pipes open and drag the wall clock toward the *remote* command's lifetime). Ctrl-C is gentler: SIGTERM to the group, up to 2 s of cooperative grace, then SIGKILL — reported as `interrupted = true`, `exit_code = -2`.

**Every ssh/run `timeout` opt is in SECONDS** (so are `run`/`run_rc`/`http_*` — see [system.md](system.md)). The Bus `send … timeout=2000` form is the only millisecond surface in Mix.

```mix
$r = ssh_run("192.0.2.2", "sleep 30", { connect_timeout: 30, timeout: 1 })
print("ok="          .. ("" .. $r.ok))
print("exit_code="   .. ("" .. $r.exit_code))
print("timed_out="   .. ("" .. $r.timed_out))
print("under 3s? "   .. ("" .. ($r.duration_ms < 3000)))
```

```text
ok=false
exit_code=-1
timed_out=true
under 3s? true
```

> **`multiplex: true` weakens cancellation, not the local wall-clock bound.** A persisted mux master from a previous call lives in a different process group, so Mix cannot kill it or prove that the remote command stopped. Mix still returns at the local deadline: after a short drain window it abandons capture descriptors retained by the master and reports the timeout. The payoff is speed, at the cost of possible remote work continuing after the result. The `multiplex: false` default passes `ControlPath=none`, so the fresh ssh client and its helpers normally die with the process group.

---

## Remote env without the ps leak (`env` + `env_transport`)

Naively, remote env means prefixing `export K='v'; ` onto the command string — which makes the value one argv element of the local `ssh` *and* of the remote shell, so a secret is visible in `ps` output **on both ends**. That is now the opt-in legacy path, not the default. `env_transport` selects how `env` values travel (it is inert when `env` is empty):

| Transport | Mechanism | Visible in `ps`? | For |
|---|---|---|---|
| `"mix"` (default) | A generated Mix driver ships over ssh **stdin** into `<mix_bin> -`: strict-data-escaped `export` lines, then `exit(run_stream(["sh", "-c", <command>]))`. | **No** — local `ps` shows only `ssh … <mix_bin> -`; remote `ps` shows `sh -c <command>` (the command, never the env). | Every mixos-managed node, regardless of login shell. Requires mix on the remote at the `mix_bin` option, else local `MIX_REMOTE_BIN`, else `/opt/mixos/bin/mix` (see [`ssh_mix`](#ssh_mixhost-source-opts--map)). |
| `"sh"` | A POSIX driver (`export K='v'` lines + the command) ships over stdin into `sh -s`. | **No** — the script travels on stdin. | Arbitrary **non-mixos** POSIX hosts. **Broken on mix-login-shell nodes** — the remote `sh -s` misroutes through the Mix classifier. |
| `"argv"` | The legacy `export K='v'; ` command-string prefix. | **Yes, on both ends.** | Compatibility only. Never for secrets. |

```mix
ssh_run("node1", "deploy.sh", { env: { API_TOKEN: $secret } })
-- the token travels inside the stdin driver; `ps` on either end never shows it
```

Three consequences to know:

1. **The secure transports own stdin.** `env` + `stdin` together conflict loudly (verified error above) unless you explicitly pass `env_transport: "argv"`, which restores the combinable-but-visible legacy shape.
2. **With `env` set under a secure transport, the command runs under POSIX `sh`, not the remote login shell.** On a mix-login-shell node, a no-env snippet is evaluated by the remote *Mix* classifier; the same snippet with `env` set runs via `sh -c`. Write POSIX shell in the snippet when you pass `env`.
3. **`ssh_mix` handles env its own way** — always as hidden `export KEY = "value"` lines prepended to the shipped source (stdin, never argv), which is why it rejects `env_transport` as not applicable.

The legacy `"argv"` shape, for reference (values `shell_quote`-d, but still argv-visible):

```mix
ssh_run("node1", "make build", {
  cwd: "/srv/project with spaces",
  env: { CI: true, BUILD_TAG: "v1.2.3" },
  env_transport: "argv"
})
-- remote command becomes:
--   export CI='true'; export BUILD_TAG='v1.2.3'; cd '/srv/project with spaces' && make build
```

(`export` rather than the `K=v cmd` one-shot syntax, so every command in a ` && `-joined chain sees the variable, not just the first.)

---

## Quoting — the footgun this design removes

Each `command` element reaches the **remote shell verbatim** — Mix does **not** wrap it in quotes. That's deliberate: you write normal shell, including pipes, redirects, and globs, and they run remotely.

```mix
ssh_run("node1", "grep -c error /var/log/app.log | tr -d '\\n'")
```

The danger is *interpolated data*. If you splice an untrusted value straight into the snippet, you've built a remote-shell-injection hole. Use [`shell_quote`](builtins.md) on every interpolated value:

```mix
$name = "weird; rm -rf /"            -- hostile input
$cmd  = "ls -la " .. shell_quote($name)
$r    = ssh_run("node1", $cmd)
-- the snippet becomes:  ls -la 'weird; rm -rf /'   → one literal argument, no injection
```

When you pass a **list**, the elements are joined with ` && ` *unquoted* — same rule, you `shell_quote` interpolated pieces inside each element:

```mix
ssh_run("node1", [
  "mkdir -p " .. shell_quote($dir),
  "cd " .. shell_quote($dir),
  "tar xzf -"
], { stdin: $archive_bytes })
```

The `cwd` option *is* quoted for you (via `shell_quote` internally), and `env` values never need caller quoting on any transport — they're the safe path for a remote working dir or environment without hand-rolling shell:

```mix
ssh_run("node1", "make build", { cwd: "/srv/project with spaces" })
-- remote command becomes:  cd '/srv/project with spaces' && make build
```

For threading a *Mix value* (a map/list, not a shell string) to a remote Mix interpreter safely, see [`data_encode`](data.md) — it produces inert Mix source the remote lexer rebuilds, never shell commands. And for shipping whole Mix *programs*, `ssh_mix` sidesteps quoting entirely (the source travels as stdin bytes, not argv).

---

## When the remote login shell is Mix

If a host runs `/opt/mixos/bin/mix` as the login shell, then the snippet you send is evaluated by **Mix**, not by a POSIX shell. Two distinct modes:

- **Send Mix source for Mix behaviour.** The remote evaluates it as a Mix program.

```mix
ssh_run("node1", "print(run(\"hostname\"))")          -- runs Mix on the far side
```

- **Send a bare command for native dispatch.** Mix's shell-first classifier dispatches it like a normal command.

```mix
ssh_run("node1", "hostname")                            -- dispatches natively
ssh_run("node1", "mix status")                          -- bare `mix` self-resolves remotely
```

Things to remember on a Mix-shell host:

1. **For anything with quoting, prefer `ssh_mix`.** A one-liner as above is fine inline; the moment the payload has nested quotes, `$`, or newlines, ship it as source over stdin instead of fighting three quoting layers.
2. **No aliases on the non-interactive path.** `~/.mixrc` (aliases, PATH tweaks, prompt) loads only for *interactive* logins. `ssh_run` is non-interactive, so the remote sees no `~/.mixrc` — call binaries by full path (`/opt/mixos/bin/...`), don't rely on a remote alias.
3. **Watch your local quoting.** The snippet is a Mix *string* on your side first. Prefer `'single quotes'` for the snippet so a `${...}` or `..` inside it isn't eaten by *local* interpolation, then escape only the inner double quotes you need.
4. **POSIX subshell grouping `( … )` doesn't survive the remote classifier** — a remote `(cmd; cmd) | sort` hits the same shell-dispatch limits as a local one (see [shell-mode.md](shell-mode.md)). Wrap it: `ssh_run("node1", "run_rc(\"(cmd; cmd) | sort\")")`.

See [the Bus page](bus.md) for the usually-better alternative on a meshed host: a static `.bus` address (`send noded.node1.bus noded.info`) routes to the remote broker directly — no ssh, no shell at all.

---

## Transferring files: scp via internal-sftp

`ssh_run` runs commands; it does not move files. For that, shell out to `scp`/`sftp` (the genuinely-right external tool — these aren't primitives that belong in Mix):

```mix
$rc = run_rc("scp /local/path/build.tar.gz node1:/srv/app/")
if $rc.rc != 0 then
  print("upload failed: " .. $rc.stderr)
end
```

> On a host whose login shell is Mix, plain scp/sftp needs the sshd config to enable the SFTP subsystem explicitly (`Subsystem sftp internal-sftp`) — otherwise the transfer has no server to talk to even though `ssh_run` works fine. That's a server-side setup detail, not a Mix one.

### stdin caveat

Stdin you write into a Mix-shell host's session does **not** reach a child spawned by the remote's `run`/`run_rc`. So for "push these bytes into a remote process", prefer one of:

- the **`stdin` option** on `ssh_run` (feeds the remote command's own stdin over the ssh pipe), or
- having the remote **pull** the data, or
- **scp** the file then act on it.

`ssh_mix` is the other side of this coin: there, stdin becomes the remote mix **program** itself — it ships *source* intact, but that same channel can't also feed stdin to a `run()` the remote script calls.

```mix
-- stdin option: pipe a payload to a remote filter
$r = ssh_run("node1", "wc -l", { stdin: $multiline_text })
print("remote line count: " .. $r.stdout)
```

---

## Patterns

### Fan out across a host list, collect results

For Mix source on many nodes at once, use
[`ssh_mix_many`](#ssh_mix_manyhosts-source-opts--map-host--result): one
concurrent call, results keyed by host. The serial form below still suits a
shell command per host.

A multi-statement lambda must be **bound to a var** before it's passed to a HOF (it won't parse inline) — see [functions](functions.md). For a large sweep, add `multiplex: true` to reuse connections per host — accepting the softer timeout bound.

```mix
$hosts = ["node1", "node2", "node3"]
$check = function($h)
  $r = ssh_run($h, "systemctl is-active nginx", { timeout: 5 })
  return { host: $h, up: $r.ok, detail: $r.stdout }
end
$status = map($hosts, $check)
for each $s in $status
  print($s.host .. ": " .. (if $s.up then "up" else "DOWN (" .. $s.detail .. ")" end))
end
```

### Structured value back from a remote node

```mix
$r = ssh_mix("node1", "print(data_encode({disk: trim(run(\"df -h / | tail -1\"))}))",
             { decode: "data", timeout: 5 })
if $r.ok then print($r.value.disk) end
```

### Deploy step that must succeed

```mix
ssh_must("node1", "install -m 0755 /tmp/app /opt/app/bin/app")
ssh_must("node1", "systemctl restart app")
print("deployed")
-- either line raises (aborting the script) the moment the remote step fails
```

### Custom port / jump host without touching ~/.ssh/config

```mix
ssh_run("user@example.com", "uptime", { extra_ssh_args: ["-p", "2222"] })
ssh_run("backend1",         "uptime", { extra_ssh_args: ["-J", "bastion.example.com"] })
```

### Detect non-UTF-8 output

```mix
$r = ssh_run("node1", "cat /some/binary")
if $r.utf8_lossy then
  print("warning: remote output had invalid UTF-8 (replaced with U+FFFD)")
end
```

---

## Local vs remote — which builtin

| You want… | Use |
|---|---|
| run a command **locally**, branch on exit code | [`run_rc`](system.md) → `{rc, stdout, stderr, timed_out, interrupted}` |
| run **locally**, raise on failure | [`run`](system.md) → stdout string |
| run **locally** with live/inherited stdio (interactive, `ssh -t`) | [`run_stream`](system.md) → exit code |
| run on a **remote** host, branch on outcome | **`ssh_run`** → result map |
| run on a **remote** host, raise on failure | **`ssh_must`** → stdout string |
| run Mix **source** on a remote node, no quoting | **`ssh_mix`** → result map (+ `.value` with `decode:`) |
| run the same Mix **source** on **many** nodes concurrently | **`ssh_mix_many`** → map host → `ssh_mix` result |
| message a **meshed** node's broker (no shell) | [`send` / `address`](bus.md) |

---

## See also

- [system.md](system.md) — local `run` / `run_rc` / `run_stream`, the structured-return model `ssh_run` extends, and their (seconds-based) timeouts
- [builtins.md](builtins.md) — full builtins index, including `shell_quote`, `data_encode`
- [strings.md](strings.md) — single- vs double-quote rules (matters for snippet quoting)
- [functions.md](functions.md) — lambdas + HOFs for fan-out across hosts
- [shell-mode.md](shell-mode.md) — the shell-dispatch classifier a mix-login-shell node applies to your snippet
- [bus.md](bus.md) — the no-ssh alternative on a meshed host: `send`/`emit`/`address`
- [data.md](data.md) — `data_encode`/`data_parse` for safely shipping Mix *values* to and from a remote interpreter
- [OpenSSH `ssh_config(5)`](https://man.openbsd.org/ssh_config) — host aliases, `ProxyJump`, identities that `ssh_run` inherits
- `mix help` · `mix what ssh_run` · `mix what ssh_must` · `mix what ssh_mix` — terminal quick reference

---

<!-- page: https://mixos.dev/mix/serve/ (source: https://mixos.dev/mix/serve.md) -->

# Serving as a Bus citizen

**`mix --serve service.mix` turns a Mix script into a supervised, mesh-registered
Bus daemon.** Write the `on` handlers; the runtime supplies the rest — broker
registration, reconnect with backoff, the standard `HELP`/`INFO`/`QUIT` verbs, a
lifecycle property tree, per-handler fault isolation, and graceful shutdown. A
script with **one** `on <cmd> … end` handler is a complete service.

This is the AmigaOS "application with an ARexx port" model made native: a
long-lived, addressable Mix process that *is* a service. The full normative
contract is **SPEC 18** (the Mix Citizen Runtime); this page is the operational
view — what the flag does, what the runtime injects, and how a citizen behaves.

## Native events and generation lifetime

`on fs.changed`, `on proc.exited`, `on net.changed`, `on audio.changed` and
`on bus.connected` use the ordinary event
envelope: payloads are in **`$event.args`**, with `command`, `headers` and `body`
available as usual. Plain handlers remain serial; async handlers use the
existing concurrent scheduling and drain rules. Native notifications also enter
the existing top-level yield points. No native source uses a polling loop or a
timer to discover change; an idle pump parks on readiness notifications.

Filesystem watches, net/audio watches and managed children belong to an
evaluator generation.
Workers exchange owned Rust records with a bounded registry; Mix values are
created only on the evaluation thread. Reload builds a separate candidate
registry. A failed candidate is drained and closed, leaving the old watches and
managed children intact. On successful reload, old handlers drain before their
registrations retire. The candidate's buffered events remain for its pump.
Candidate handlers can also run at top-level yield points during initialisation;
discarding a failed candidate does not undo its file writes or outgoing messages.
Shutdown likewise stops admission, drains handlers, then closes native sources.
Unwatch cancels buffered work, not a handler already dispatched.

The legacy `spawn(...,{die_with_parent:true})` lifetime rule still applies when
`exit_event` is absent. With `exit_event:true`, children use generation ownership:
there can be old and candidate processes alive during candidate initialisation.
Do not have them contend for an exclusive resource without an application-level
handover. Registry retirement SIGKILLs the managed process group and also signals
the leader through its retained pidfd before reaping it, even if the leader has
left that group. Scripts needing a graceful stop should send their own stop request before
retirement. When a leader exits naturally, remaining members of that group are
also ended before the leader is reaped. Descendants that deliberately leave the
group are outside this guarantee.

Completed child monitors are pruned when checking native-source liveness.
A plain script's event pump exits once its last managed child exit is delivered
and no filesystem watches or Bus handler remain; no explicit `quit()` is needed.

```mix
$pid = spawn(["worker", "scene.mix"], {exit_event: true, tag: "scene:12"})
on proc.exited
  $exit = $event.args  -- {pid,tag,exit_code,signal}
  -- Compare the tag with the active generation before deciding to restart.
  print($exit)
end
on bus.connected
  print($event.args.generation)
  -- Refresh snapshots after subscriptions have been restored.
end
```

See [filesystem events](io.md#native-filesystem-events),
[managed spawn](system.md#managed-child-exit-events),
[network and audio events](system.md#desktop-status-events--net_watch-audio_watch), and
[connection events](bus.md#connection-events).

## First, "substrate"

**The substrate is MixOS itself** — the agent-operable computing environment,
not any one app on it: the message Bus (the broker `noded`), the services
running on it, and the WireGuard mesh that joins nodes into one fabric. The word
is chosen over "OS" or "desktop" on purpose — it is meant to be *legible,
modifiable, and reconstructible* by an AI agent, the ground the system is built
on rather than a feature bolted onto one. **Citizens (below) are the live
services the substrate is made of.**

## What "citizen" means in MixOS

A **citizen** is a process that is a first-class, named member of the MixOS
substrate — not a throwaway script but a resident participant on the Bus. A plain
`mix script.mix` run is anonymous and one-shot: nothing can address it and it
exits when the script ends. Turning it into a citizen (`mix --serve`) gives it a
name, a lifetime, and a seat at the table — it becomes something the rest of the
system, and the whole mesh, can talk to. Concretely, a citizen has:

- **Identity** — a registered Bus service name others address it by (`send
  <name> …`). There is no anonymous citizen.
- **Addressability** — any process, agent, or mesh node can reach it by that
  name, from this machine or across the WireGuard mesh.
- **Residency + supervision** — it is long-lived and stays registered. A broker
  (`noded`) restart is a transient drop it reconnects and re-registers
  through, not a death.
- **Participation** — it receives verbs (`on`), `reply`s, `send`s, `emit`s, and
  `subscribe`s to topics: a full member of the message fabric, not just a caller.
- **A public surface it did not write** — the runtime injects `HELP`, `INFO`,
  `QUIT`, and `<svc>.props.{get,list,describe}`, so every citizen is
  introspectable and controllable by the same verbs.
- **Trust** — a citizen is a *full-capability, trusted* process (see
  [capabilities](capabilities.md)), not a sandbox for untrusted code.
- **Provenance** — its binary (`mix-shell`) and version show in `noded.list`, so
  a fleet of agents can see exactly what is running and where.

In short: a citizen is the MixOS substrate's unit of **live, addressable,
agent-operable service**. The rest of this page is how you make one and how it
behaves.

> **Most examples here need a live broker** (`noded`, from the
> [cos repo](https://github.com/markc/mixos)). Where one is running, the output
> shown is **real**, captured from a live `statecache` citizen on a dev node.
> Examples that *start* a daemon (the `mix --serve …` invocations) are
> illustrative of the command shape — you can't paste them into a terminal and
> see output without a broker and a unit. The language facts (the `on`/`reply`
> model, `$result`/`$rc`, the reserved verbs, service-name derivation) are exact,
> and the no-broker and parse paths are verified standalone.

For the messaging primitives themselves — `send`, `emit`, `address`, `on`,
`reply`, topic pub/sub, `$result`/`$rc` — see [Bus messaging](bus.md). This page
assumes them and focuses on the **serve runtime**.

---

## What `mix --serve` does

```text
mix --serve <script.mix> [--name <svc>] [--no-prelude]
```

Compared with a plain `mix <script>` run, serve mode differs in three
load-bearing ways:

1. **It registers a service name** with the local broker and stays addressable under it. A plain script run has no name and nothing can `send` to it.
2. **It is supervised.** A `noded` restart is a transient drop the citizen reconnects / re-registers / re-subscribes through — not a process death. A plain script's broker connection is one-shot.
3. **The event pump is unconditional and non-terminating.** A resident daemon, not a script with an optional event tail. It exits only on a fatal terminal (the supervised receiver going away for good), `SIGTERM`/Ctrl-C, or the `QUIT` universal.

Serve evaluation is recorded with mode `serve` and the script basename only.
For fleet services, set `MIX_STATS=off` to disable collection and all stats I/O;
see [usage statistics](stats.md).

The lifecycle on start:

```text
read + parse script   →  connect to broker  →  register <svc>
                                            →  run the script top-level ONCE (init)
                                            →  enter the event pump (resident)
```

The top-level body runs **exactly once** as initialization: open resources,
`subscribe` to topics, register `on` handlers. Then the runtime registers the
service name and pumps inbound Bus into your handlers until shutdown.

If the script fails to **lex or parse**, `--serve` logs the error and exits
non-zero before any broker contact — so a syntax check is cheap and offline:

```text
$ mix --check service.mix
service.mix: OK
```

---

## One handler is a whole service

There is no service scaffolding to write — no main loop, no registration call, no
manifest. A file with a single `on` handler, run under `--serve`, is a complete,
addressable citizen:

```mix
-- echo.mix  — run with:  mix --serve echo.mix
on echo.ping
  reply("pong")
end
```

```text
$ mix --serve echo.mix          # registers Bus service "echo"
```

From any other Mix process on the node:

```mix
send echo echo.ping
print("" .. $result)
```

```text
pong
```

That tiny script also answers `HELP`, `INFO`, `QUIT`, and
`echo.props.{get,list,describe}` — none of which appear in the file. The runtime
injects them (see [Reserved verbs](#reserved-verbs--what-the-runtime-injects)).

---

## Service-name derivation

The Bus service name is the `<svc>` the citizen registers under and the target
others `send` to. It comes from `--name`, falling back to the **script's file
stem**:

```text
mix --serve worker.mix                 # service name = "worker"  (stem)
mix --serve worker.mix --name probe    # service name = "probe"   (--name wins)
mix --serve /usr/local/lib/mixos/statecache.mix   # → "statecache"
```

Two normalization rules apply (from `derive_serve_name` in `main.rs`):

- **A leading `mixos-` is stripped** from either source. The system user is `mixos-<svc>` but the Bus namespace uses the bare `<svc>` token, so a script (or `--name`) accidentally named after the POSIX user still yields the canonical Bus identity: `mixos-statecache.mix` → `statecache`, `--name mixos-foo` → `foo`. Surrounding whitespace is trimmed.
- **An anonymous citizen is rejected.** If no name can be derived — an empty path, a root path, a dotfile-only stem (`.foo`, whose `file_stem()` is the whole `.`-led name), or a `--name` that resolves empty or to a leading dot — `--serve` is a launch error and exits non-zero. There is no nameless citizen.

```text
$ mix --serve            # no script path
mix: --serve requires a script path
Usage: mix --serve <script> [--name <svc>]

$ mix --serve worker.mix junk      # serve mode takes no positional script args
mix: unexpected argument after --serve script: 'junk'
Usage: mix --serve <script> [--name <svc>]
```

Only `--name <svc>` and `--no-prelude` may follow the script path, in any order; a
daemon has no argv, so positional script args are a usage error.

**The script reads its own name with `serve_name()`** (0.91.0) — the derived name
above, after normalization, or `nil` outside `--serve`. Never hard-code it: anything
the citizen publishes that routes traffic back to it (a scene document's click
target, a reply topic, a registration record) must carry the name it actually
registered under, or a second instance started with another `--name` silently
routes its traffic to the first.

```mix
$me = serve_name() ?? "quoin-panel"   -- nil in a plain script / the REPL
publish("scene.update", json_encode({owner: $me, target: $me .. ".click"}))
```

```text
mix --serve quoin-panel.mix                        # serve_name() = "quoin-panel"
mix --serve quoin-panel.mix --name quoin-panel-n   # serve_name() = "quoin-panel-n"
```

**`on @.verb` registers a verb under that name** (0.112.0). The unquoted `@`
is the whole first segment of the handler name; when the `on` statement runs,
`@` is replaced by the serve name. One generic script then serves any
instance:

```mix
on @.call desc "Forward a call to the bridged program"
  reply(json_encode({served_by: serve_name()}))
end
```

```text
mix --serve bridge.mix --name photo   # answers photo.call, HELP lists photo.call
mix --serve bridge.mix --name other   # answers other.call
```

Dispatch, `HELP` and every handler listing see the resolved name. Two `on`
statements that resolve to the same name append handlers, exactly like two
literal ones. Outside `mix --serve` (a plain script, `-c`, the REPL) there is
no name to substitute, and the statement raises the catchable
`SERVE_PREFIX_OUTSIDE_SERVE`. Every segment after `@.` must be a bare name (a
letter or `_`, then letters, digits or `_`), quoted or not. These are parse
errors: `on a.@.b`, `on @`, `on @x.y`, a quoted `on "@.call"` (a literal can't
look like the placeholder), a quoted segment that isn't a bare name
(`on @."a.b"`, `on @.""`), and `@` in an expression. Positions that read raw
source text rather than tokens take `@` as an ordinary character: a bareword
`source`/`include` path (`source ./foo@bar.mix`) and the command text after
`|` (`print(1) | cat @foo`).

---

## The handler model

Inbound Bus messages dispatch to matching `on <cmd> … end` handlers. The
`<cmd>` matches the **inner command/verb** the sender used — not the service
name or topic — so a request `send statecache statecache.get` fires
`on statecache.get`. The full grammar (the `$event` map, `reply(...)`,
`async`/Class C, `subscribe`) is in [Bus messaging](bus.md); the essentials for a
citizen:

```mix
on statecache.get desc "Read the cached value back to the caller"
  reply($value)                 -- rc defaults to 0
end

on config.current               -- a topic delivery: update state, no reply
  $value = $event.body
end
```

### Doc-strings — a citizen self-describes at the handler site

`on <cmd> desc "what this verb does" [async]` (mix ≥ 0.87.1; `desc` and
`async` compose in either order) attaches a **doc-string** to the handler.
The runtime surfaces it verbatim as that verb's `description` in the `HELP`
reply, so GUIs, discovery tools, and agents all read the text the author
wrote where the handler lives — no separately-maintained manifest. Handlers
without one show the generic `Author-defined handler`.

`desc` is a contextual marker (like `async`), consumed only when a
**non-empty static** string literal follows it — an empty or whitespace-only
`desc ""` is refused with a parse error rather than rendering a blank HELP
description. The doc is static metadata that never evaluates:
in double quotes only `${…}` interpolates, so a bare `$var` inside a doc
stays literal text, and `desc "${var}"` is a parse error (as that adjacent
pair always was). A body statement that merely *uses* the name `desc` (on
its own line) is untouched. With multiple handlers registered on one
command, the first documented one wins. An older mix **rejects** a
doc-annotated script at parse time — loudly, not with a silent misparse — so
deploy the runtime before the scripts.

### `reply()` answers a request

`reply(body)` or `reply(rc, body)` answers the in-flight request. A non-zero `rc`
(`0..=255`) is an **application error** carried to the caller's `$rc`/`$result` —
distinct from a transport failure. `reply` is only valid inside a handler
servicing a request; calling it for a topic delivery (which has no caller) is a
hard error. `rc` 15 and 16 are the runtime's own (`HANDLER_FAULT` and
`HANDLER_CANCELLED`, see [handler fault isolation](#handler-fault-isolation-the-per-request-boundary));
pick another `rc >= 10` for your own refusals, and treat `error_code` as the
authoritative signal.

```mix
on do.validate
  if is_empty($event.body) then
    reply(10, "missing input")   -- caller sees $rc = 10
  else
    reply(0, "ok")
  end
end
```

### `quit()` self-terminates the citizen gracefully

`quit()` requests the **same graceful shutdown** as the `QUIT` universal (SPEC 18
§3.5) — deregister from the broker, then exit `0` — but self-initiated from
inside the script rather than driven by an inbound verb. It is the primitive for
a **one-shot / ephemeral citizen**: register, do a job that needs the event pump
(open a dialog, await a topic delivery, drive one interaction), then retire
itself. It takes no meaningful arguments and returns `nil` — like the `QUIT`
universal it has no exit-code channel (graceful serve shutdown is always exit
`0`), so any argument passed is accepted and ignored rather than an error. Use
`exit(n)` when the citizen must return an exact status: it immediately unwinds
the current handler/init body through active `finally` blocks, then enters the
same bounded deregister-and-drain shutdown path before the process exits with
`n`.

```mix
on dialogs.<handle>.state          -- a props.changed delivery
  if $event.args.new == "resolved" then
    $r = send interact "interact.dialog-result" handle=$h owner_token=$t
    -- …use $r…
    quit()                         -- job done: deregister + exit 0
  end
end
```

`quit()` does **not** abort the current handler: it sets a shutdown request that
the event pump observes at the top of its next loop turn, so statements after
`quit()` in the same handler still run to completion. For a synchronous (Class S)
handler or the init body the pump stops as soon as that code returns. An `async`
(Class C) handler runs as a spawned task while the pump is parked waiting for the
next message, so `quit()` there also **wakes the pump immediately** — it does not
wait for another inbound message to arrive. An idle citizen therefore stops
promptly on a Class C `quit()`, not only when the next event happens to come in.
In-flight handlers get the same bounded grace to finish as any graceful stop.
Prefer `quit()` for an ordinary clean citizen shutdown: it lets the current
handler finish its remaining statements and always exits `0`. Use `exit(n)` when
the current execution must stop immediately (apart from `finally`) or a specific
status must reach systemd. Exit requests from both synchronous and spawned async
handlers wake the event pump; the runtime then deregisters and drains before
returning the exact requested code.

### Outbound `send` from a handler uses `$result` / `$rc`

A handler can itself call other citizens. The reply lands in `$result`, the status
in `$rc`, exactly as in any Mix code:

```mix
on aggregate.report
  send dnsd dnsd.stats
  if $rc == 0 then
    reply($result)
  else
    reply(10, "upstream failed")
  end
end
```

If a handler makes a **slow / remote** downstream `send` and the citizen serves
concurrent callers, mark it `async` (Class C) so the dispatch yields at each
`send`/`reply`/`sleep_ms` and other callers interleave instead of
head-of-line-blocking:

```mix
on aggregate.report async
  send slow.upstream fetch.data        -- yields here; peers interleave
  reply($result)
end
```

Plain handlers are **Class S** (run-to-completion, one at a time) — the default,
and correct for fast handlers and sole-caller orchestration drivers. See
[Bus messaging → async handlers](bus.md#async-handlers-class-c) for the Class S vs
Class C rules and the **synchronous-cycle deadlock** prohibition (`async` does not
legalise an A→B→A cycle).

---

## Handler fault isolation (the per-request boundary)

A panic, a `die`, or any uncaught error inside one `on` handler **does not kill
the citizen**. The runtime catches it at the per-request boundary, logs the real
error, sends an error reply to the caller if the inbound message was a request
expecting one, and continues the pump. One malformed request must not deny
service to every other caller — this is a contract, not best-effort.

```mix
on risky.op
  $n = to_number($event.body)   -- a bad body raises here…
  reply("doubled: " .. ("" .. ($n * 2)))
end
-- …the citizen logs it, replies an error to THIS caller, keeps serving others.
```

**What the caller sees vs. what you debug with.** The caller's reply is a
**fixed** `rc=15` with the body
`{"error": "internal handler error", "error_code": "HANDLER_FAULT"}`. That is in
the application-error band, so the usual `$rc >= 10` check catches it; on an
ordinary send `$result` is `internal handler error`, and on every route
`$reply.error_code == "HANDLER_FAULT"` (see [Reading `$rc`](bus.md#reading-rc-ok-vs-application-error-vs-transport-failure)).
Before mix 0.94.0 this reply was `rc=1`, which the Bus contract reads as
delivered-with-warning *success*: a caller testing `$rc >= 10` took a crashed
handler for a working one.

```mix
send risky risky.op body="not a number"
if $rc >= 10 and $reply.error_code == "HANDLER_FAULT" then
  print("the citizen's handler crashed; its log has the real error")
end
```

The real error message is deliberately **not** put on the wire (it can carry
request data or Trojan-Source bytes, and a peer in the mesh is not
automatically trusted). The real error — with the command, handler index, and
the failing line — is **logged instead**, and that's where you debug:

- **Interactive** (`mix --serve foo.mix` in a terminal): faults print straight
  to the terminal, e.g. `ERROR … Handler body errored … command=risky.op
  error=Runtime error at line 2: …`.
- **Under systemd** (the citizen has no terminal): the fault goes to journald —
  `journalctl -t mix-shell -f` (filter further on the `service = <svc>` field).

You can still handle errors yourself with [`try … catch`](errors.md) to send a
tailored reply; the runtime boundary is the backstop for anything you don't catch.

---

## Reserved verbs — what the runtime injects

Every serve citizen answers a fixed set of verbs the author does **not** write and
**cannot override** (SPEC 18 §7-Q4: *runtime wins*). They are intercepted
*pre-dispatch*, so an author `on HELP …` or `on <svc>.props.get …` handler is
unreachable — and is filtered out of `HELP` rather than advertised as a shadow
that never fires.

| Verb | Level | What it returns |
|---|---|---|
| `HELP` | L0 | `[{name, description, args}]` — reserved verbs first, then the author's commands (sorted, deduped; `description` is the handler's doc-string when one was written) |
| `INFO` | L0 | the `{name, version, description}` triple |
| `QUIT` | L0 | replies `rc:0`, then triggers the §3.5 graceful shutdown |
| `RELOAD` | L0 | hot-reload (mix ≥ 0.88.0): re-parses the script; `rc:0 {reloading: true}` = accepted and parsed (the swap then commits, or reverts if the new init fails at runtime — poll `lifecycle.generation` to confirm), or `rc:10 {error}` and the citizen is untouched — see below |
| `<svc>.props.get` | L1 | a lifecycle property snapshot (root, or an optional `path=`) |
| `<svc>.props.list` | L1 | all defined property paths |
| `<svc>.props.describe` | L1 | the schema entry for a path |

This is the same Ch07 L0 + L1 daemon conformance a Rust daemon owes — a Mix
citizen is exactly as legible as a compiled one. The props surface reuses the
same `mixos_props` encoder the Rust daemons use, so a citizen's `props.get`
output is byte-consistent with theirs.

**Live** (captured from a running `statecache` citizen):

```mix
send statecache HELP
print("" .. $result)
```

```text
[{args: [], description: List all commands this service accepts, name: HELP}, {args: [], description: Service identity and capabilities, name: INFO}, {args: [], description: Graceful shutdown: deregister, then exit 0 (SPEC 18 §3.5), name: QUIT}, {args: [path?], description: Property snapshot at an optional path (root if absent), name: statecache.props.get}, {args: [], description: All defined property paths, name: statecache.props.list}, {args: [path], description: Schema entry (type, mutability, sensitivity) for a path, name: statecache.props.describe}, {args: [], description: Author-defined handler, name: statecache.get}, {args: [], description: Author-defined handler, name: world.statecache.probe}]
```

```mix
send statecache INFO
print("" .. $result)
```

```text
{description: Mix supervised Bus citizen (SPEC 18 Phase 1 runtime), name: statecache, version: 0.21.2}
```

> `INFO.version` is the **`mix` runtime version** running the citizen, not a
> version of the script — a citizen's identity is "this mix build plus this
> script." Above it reads `0.18.1` (the deployed serve binary on that node), which
> need not match a newer `mix --version` you may have locally.

### The lifecycle property tree

The L1 `props.*` surface exposes a runtime-owned lifecycle tree. Five leaves,
queryable like any mixos daemon's properties:

```mix
send statecache statecache.props.get
print("" .. $result)
```

```text
{lifecycle: {health: ok, mode: serving, props_level: L1, started_at: 2026-06-16T07:28:17.231260663+00:00, uptime_s: 10388}}
```

```mix
send statecache statecache.props.list
print("" .. $result)
```

```text
[lifecycle.started_at, lifecycle.uptime_s, lifecycle.mode, lifecycle.health, lifecycle.props_level]
```

A single leaf, by `path=`:

```mix
send statecache statecache.props.get path="lifecycle.uptime_s"
print("uptime_s = " .. ("" .. $result))
```

```text
uptime_s = 10388
```

`props.describe` returns the schema entry — note `uptime_s` is **transient** (it's
recomputed live from the monotonic clock on every `props.get`, never cached):

```mix
send statecache statecache.props.describe path="lifecycle.uptime_s"
print("" .. $result)
```

```text
{description: Seconds since process start., mutable: false, path: lifecycle.uptime_s, sensitive: false, transient: true, type: number}
```

| Leaf | Type | Meaning |
|---|---|---|
| `lifecycle.started_at` | string | RFC 3339 process start time |
| `lifecycle.uptime_s` | number | seconds since start (live, transient) |
| `lifecycle.mode` | string | operating mode — `serving` |
| `lifecycle.health` | string | coarse health — `ok` |
| `lifecycle.props_level` | string | conformance level — `L1` |

> `props.watch` (L2) and `props.set` / `props.delete` (SPEC 12) are **not**
> reserved — an author *may* implement them with ordinary `on` handlers, so they
> fall through to your code rather than being intercepted.

---

## Build provenance — discoverable in `noded.list`

A Mix citizen has no binary of its own; its provenance **is** the `mix` build that
runs it. At registration the runtime sends a `RegisterProvenance` body, so a
`noded.list` query reports which `mix` build runs the citizen — the version-
discovery contract for a fleet of agents asking "what runs where." The body is
built once at process start and re-sent on every reconnect, so `started_at` stays
the true process start.

```mix
send noded noded.list
for each $s in $result
  if $s["name"] == "statecache" then
    print("" .. $s)
  end
end
```

```text
{binary: mix-shell, build_time: 2026-06-15T03:06:09Z, git_dirty: false, git_sha: 2877eef19cf5, name: statecache, pid: 1352, registered_at: 2026-06-16T07:28:17Z, schema_version: 1, started_at: 2026-06-16T07:28:17Z, version: 0.21.2}
```

Note `binary: mix-shell` — the citizen is named `statecache`, but its provenance
points at the `mix` runtime that hosts it.

---

## Hot-reload — `RELOAD` (load-beside-swap)

`send <svc> RELOAD` (mix ≥ 0.88.0) asks a citizen to re-read its own script
and swap to it **without ever leaving the Bus** — the broker connection and
service registration survive; only the evaluator (handlers + globals) is
replaced. The contract is load-beside-swap, in Quickshell's sense:

1. The runtime **re-reads and parses** the script first. A parse failure
   answers `rc:10 {error}` and the running citizen is completely untouched —
   a broken edit is a refused reload, never a dead service.
2. On a clean parse it answers `rc:0 {reloading: true}`, then builds a
   **fresh evaluator beside the running one** (same wiring: prelude, limits,
   reserved-verb surface) and executes the new top-level.
3. New top-level succeeds → the new evaluator takes over the pump; the old
   one is drained (in-flight async handlers get the shutdown discipline) and
   dropped. It **fails at runtime** → the failure is logged loudly and the
   OLD evaluator resumes, its state intact.

This is what makes it safe for an agent to edit a live citizen: the worst a
bad edit can do is a logged revert. Things to know:

- **State does not carry over.** The new top-level re-initializes its
  globals. State that must survive a reload belongs in the substrate
  (props, statecache) — that is the persistent-state model, not process
  memory.
- **A request in flight across the swap gets a terminal reply, not
  silence.** When the old generation is retired its pending requests are
  answered with `rc=16` and `error_code` `HANDLER_CANCELLED` (the connection
  is live, so the caller is never left hanging to its own timeout; before mix
  0.94.0 this reply was `rc=2`, which read as success). The reply says the
  handler was cancelled before replying, not that it did nothing: any side
  effects it made before that point stand. SIGTERM/Ctrl-C during a
  reload's init still shuts the citizen down cleanly, and a new init body
  that fails after admitting traffic has its spawned handlers cancelled
  before the old generation resumes.
- **The script path is resolved to an absolute path at startup**, so a
  citizen whose init `chdir`s still reloads its own file.
- **`rc:0` means "accepted and parsed", not "this exact revision is now
  serving"** — a runtime failure in the new init reverts, having already
  acknowledged. **`INFO`/`HELP` cannot confirm a swap** (the version is the
  mix version, and a body-only handler edit changes neither). Poll
  **`<svc>.props.get lifecycle.generation`**: it starts at 0 and advances by
  exactly one per committed swap, with `lifecycle.script_loaded_at` stamping
  when the live generation loaded. `lifecycle.uptime_s`/`started_at` keep
  reporting the PROCESS, so a reloaded citizen is not mistaken for a
  crash+restart.
- **The not-yet-committed generation serves live traffic during its init.**
  A top-level `sleep()` dispatches events, so a new init body that runs
  before it commits (or before it fails) can already answer requests — a
  revert un-registers its handlers and cancels its async tasks, but it
  cannot un-answer a request the rejected code already replied to, nor undo
  its substrate side effects (props writes, `subscribe`, file writes,
  spawned externals). "Resumes with state intact" is a guarantee about the
  evaluator, not the substrate: keep a reloadable citizen's init idempotent,
  and do irreversible work in a handler, not at top level.
- The `rc:0` reply races the swap by design: a follow-up sent immediately
  queues at the broker and is answered by whichever evaluator holds the
  pump. To observe which generation went live, poll `lifecycle.generation`
  (above) — not `HELP`/`INFO`, which cannot tell a swap from a revert.
- Topic subscriptions made by the old top-level persist on the shared
  connection; a re-subscribing new top-level may duplicate delivery
  (v1 limitation — avoid reloading citizens that `subscribe`, or make
  subscription idempotent on the handler side).
- Like every reserved verb, an author `on RELOAD` handler is unreachable
  and filtered from `HELP`.

### Post-commit handover — `is_reload_candidate()` and `lifecycle.commit`

For a citizen that owns children (a loader), "swap on success" alone is not
a handover: the old generation's children must be retired BEFORE the new
generation starts its own, and a failed candidate must leave them running.
The runtime provides three pieces, and a loader adopts them together:

- **`is_reload_candidate()`** is true only while the replacement's top-level
  executes (false at initial boot, in plain scripts, and in every committed
  generation). The candidate must prepare passive state — read and
  validate, no starts, no spawns, no stopping old behaviour, no persisted
  writes. A raise reverts to the old evaluator, its state and children
  intact.
- **Children are retired before the new behaviour starts.** Managed
  children (`spawn {exit_event:true}`) live in their evaluator's registry:
  a failed candidate does not terminate the old generation's, and the
  committed swap kills and reaps them synchronously before the new pump
  starts. Legacy `die_with_parent` children (without `exit_event`) are
  retired per evaluator generation: the committed swap sweeps every owner
  except the new evaluator's, and a discarded candidate sweeps exactly its
  own. A candidate that spawns such a helper at init therefore cannot take
  the old helper's port until the swap commits — move init-time spawns
  into the commit hook, or use `exit_event:true`.
- **`on lifecycle.commit`** runs exactly once per committed swap. The serve
  driver queues it locally after the old evaluator's drain, the child
  reaping and the `lifecycle.generation` bump; the pump dispatches it
  independent of the broker connection, so it survives broker loss. The
  event carries the committed generation as `$event.args.generation`. It
  is a runtime-native hook: a wire-delivered `lifecycle.commit` is refused
  (`rc 10`) before any author handler and is filtered from `HELP`, so an
  external caller cannot run commit behaviour ahead of or behind the real
  commit. A raising hook is an isolated handler fault — recorded in
  `lifecycle.handler_faults`, the citizen keeps serving, and recovery is
  the loader's own business (durable intent plus its restart/reconnect
  reconciliation). A shutdown that lands between the queue and the
  dispatch drops the event with the evaluator; the loader re-derives it
  from durable state on the next boot. There is no rollback after
  retirement: once the swap commits, the old generation is gone.

## Supervision, reconnect, and shutdown

Serve mode wraps the pump in a supervised client, so the citizen behaves like a
proper daemon across broker churn:

- **Reconnect with backoff.** On transport loss the runtime re-enters `connect → register → pump` with bounded exponential backoff + jitter, then **re-registers** the service name and **re-subscribes every topic** the script subscribed to (init-body *and* handler-body — the full set, replayed by the runtime, not the author). Broker-side registration and subscriptions do not survive a transport drop and are not silently assumed to.
- **No outbound queue while disconnected.** An outbound `send` while disconnected fails fast with a typed transport error — an outage is surfaced to the caller, never absorbed behind a buffer.
- **Initial-connect budget is fatal.** If the *first* connect+register budget is exhausted (no reachable broker at start), `--serve` exits non-zero so a misconfigured citizen fails fast under systemd rather than spinning silently.
- **Graceful shutdown.** `SIGTERM` (the systemd stop signal), Ctrl-C, the Ch02 `QUIT` universal, and the self-initiated `quit()` builtin all converge on **one** path: stop accepting new requests, let in-flight handlers a bounded grace to finish, **deregister** the service name (bounded so a wedged broker can't hang exit), then exit `0`. If the grace is exceeded or deregister fails, the process exits non-zero so systemd records an unclean stop and the broker registry doesn't retain a dead name. `QUIT` is **not** a no-op — it drives this exact sequence.

```mix
send statecache QUIT       -- replies rc:0, then the citizen deregisters and exits 0
```

Logs go to **journald** under systemd. When `mix --serve` runs **interactively**
(stderr is a terminal) they also go straight to that terminal, so a foreground
dev run shows startup, faults, and pump activity without a `journalctl` window;
they fall back to stderr too when there's no journal socket at all. Every
serve/supervisor line carries a structured `service = <svc>` field, so the
process name `mix-shell` never obscures which citizen logged. Tail a citizen's
logs with `journalctl` filtered on that field.

Independently of logging, every fatal or reverted serve outcome also prints one
line to **stderr**: `mix --serve <svc>: <what>: <error>`. That covers an
unreadable script, lex and parse errors, a refused initial connect or
registration (for example a service name the broker rejects: names are 2–31
characters, `[a-z][a-z0-9-]*`), an uncaught init error, and a reverted
`RELOAD`. A citizen launched by another program (stderr redirected to a file,
no terminal, no journal capture) therefore never exits 1 silently.

---

## Running under systemd

A resident citizen is a normal SPEC-10 daemon: a `sysusers.d` `u mixos-<svc>`
entry in the citizen UID band and a unit whose `ExecStart` runs the script under
`--serve`. The shape is identical to `mixos-{noded,maild,webd}.service`:

```ini
# /etc/systemd/system/mixos-statecache.service  (illustrative)
[Unit]
Description=statecache Mix citizen
After=noded.service

[Service]
ExecStart=/opt/mixos/bin/mix --serve /usr/local/lib/mixos/statecache.mix
User=mixos-statecache
Group=mixos-statecache
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

The `mix` binary never `setuid`s itself — identity is assigned by systemd via
`User=`/`Group=`. Restart policy, ordering (`After=noded.service`), and
resource limits are unit-file concerns; the serve runtime provides only the
in-process behaviour systemd can't (registration, reconnect, handler isolation,
graceful deregister).

---

## A complete state-holder citizen

The canonical Phase-1 reference shape: subscribe one topic, hold the last value as
in-process state, answer a query with it. This single file is a full citizen.

```mix
-- statecache.mix
--   mix --serve statecache.mix          (Bus service name "statecache")
$value = "(none)"

subscribe("config.current")              -- init: register topic interest

on config.current                        -- topic delivery updates state
  $value = $event.body
end

on statecache.get                        -- request reads it back
  reply($value)
end
```

It needs no `HELP`/`INFO`/`QUIT`/`props.*` handler — those are injected. Across a
broker bounce, the runtime re-registers `statecache` *and* re-subscribes
`config.current`, so a value published after the bounce is reflected in the next
`statecache.get`.

> A *transient* `mix statecache.mix` (no `--serve`) would run the init body, hit
> the end of the script with handlers registered, and pump events for that one
> connection — but it has no service name, no supervision, and dies when
> interrupted. Use `--serve` for anything resident.

---

## No broker present

The serve *entry point* needs a broker (the initial-connect budget is fatal), but
the underlying Bus forms degrade predictably on a bare host — relevant when you
develop a citizen script before a broker exists. See
[Bus messaging → no broker](bus.md#no-broker--graceful-degradation) for the full
state machine; in brief:

- **Never had a broker:** `send` returns `nil`, `emit` no-ops, `port_exists` is `false` — no error. The same binary becomes mesh-viable the instant a broker appears, with **no recompile**.
- **Had a broker, lost it:** `send`/`emit`/`port_exists` **raise** `mesh unavailable: …` — an outage is loud, never silently absorbed.
- **`subscribe`/`reply`** raise in both cases (a citizen must not believe it subscribed or replied when it didn't).

So you can `mix --check service.mix` and even dry-run the init logic offline; the
resident `--serve` daemon is what requires the broker to be up.

---

## Quick reference

| Thing | Value |
|---|---|
| Start a citizen | `mix --serve <script> [--name <svc>] [--no-prelude]` |
| Service name | `--name`, else the script file stem; leading `mixos-` stripped; the script reads it with `serve_name()` |
| Verb under the serve name | `on @.verb` registers `<svc>.verb`; outside `--serve` it raises `SERVE_PREFIX_OUTSIDE_SERVE` |
| Anonymous serve | a launch error — no nameless citizen |
| Init | top-level body runs **once**, then the pump runs forever |
| Reserved (injected) | `HELP`, `INFO`, `QUIT`, `<svc>.props.{get,list,describe}` |
| Author can override reserved? | **No** — runtime wins (pre-dispatch intercept) |
| Handler fault | caught per-request, logged, `rc=15` `HANDLER_FAULT` reply, pump continues |
| Slow downstream + concurrent callers | mark the handler `async` (Class C) |
| Sync cycle A→B→A | prohibited — deadlocks; break with `emit` + topic reply |
| Shutdown | `SIGTERM` / Ctrl-C / `QUIT` → deregister → exit 0 |
| Logs | journald, structured `service = <svc>` field (stderr fallback) |
| Provenance | `binary: mix-shell` + `mix` version, visible in `noded.list` |
| Normative spec | SPEC 18 (Mix Citizen Runtime) |

## Citizens as adapters — bridging the Bus to anything

A citizen's `on` handlers don't have to *implement* a service — they can
**translate**. An adapter citizen speaks the Bus on one side and some foreign
control surface on the other, and its whole job is to map between them. This is
the AmigaOS ARexx model in full: ARexx let a script receive a message on an
application's port and turn it into whatever that application understood; a Mix
citizen receives a Bus verb and turns it into a D-Bus call, a shell command, an
HTTP request, or a `send` to another node.

The shape is tiny. A KDE Plasma workspace adapter, in full:

```mix
-- desktop-workspace.mix — run: mix --serve desktop-workspace.mix --name desktop
fn kwin(m)
  -- qdbus6 is an external tool, not a builtin — shelling out is correct.
  return trim(run("qdbus6 org.kde.KWin /KWin org.kde.KWin." .. m))
end

-- Multi-segment verbs must be QUOTED in `on` (a bare handler verb takes one dot).
on "desktop.workspace.next"
  kwin("nextDesktop")
  reply(json_encode({ok: true, desktop: kwin("currentDesktop")}))
end

on "desktop.workspace.prev"
  kwin("previousDesktop")
  reply(json_encode({ok: true, desktop: kwin("currentDesktop")}))
end
```

Now `send desktop desktop.workspace.next` from **any** process on the node
switches the desktop. The Bus verb is the request; `run("qdbus6 …")` is the
translation. Why this is more than a convenience:

- **The verb is the stable interface; the adapter is swappable.** Everything
  upstream — a keybinding, an agent, another citizen — only knows the verb
  `desktop.workspace.next`. *How* it is carried out is hidden behind the adapter.
  Swap the host desktop for a compositor that answers the verb natively and the
  adapter simply retires — nothing upstream changes. The vocabulary is portable;
  the adapter absorbs the host difference.
- **It bridges to any host.** The same shape wraps GNOME's D-Bus, a media player,
  `notify-send`, a REST endpoint, `systemctl`, or the tools on another mesh node.
  The Bus presents one clean verb vocabulary; a small Mix adapter per host
  translates it into that host's native language.
- **The whole glue layer is editable Mix, not compiled daemons.** Because an
  adapter is a `--serve` script, you write one in minutes, `mix --check` it
  offline, and reload it without rebuilding or restarting anything else. Reserve
  compiled code for the performance- or kernel-adjacent core; make the adapters,
  launchers, and per-key actions Mix.

Two idioms complete the pattern:

- **Launch things** with `spawn(cmd)` (detached, via `/bin/sh -c`, returns a PID)
  or `run_argv(argv)` (foreground, an argv list). An app launcher is barely a
  file: `on "launch.editor" spawn("my-editor") end`. Run such a citizen in the
  **user's** session — GUI programs need the caller's `WAYLAND_DISPLAY` /
  `DBUS_SESSION_BUS_ADDRESS`, so never launch them from a root daemon; a
  root daemon should `send` the verb and let a session citizen do the launching.
- **Fan out** with topics: a citizen can `subscribe` to an event topic and
  translate each delivery, so one publisher drives many adapters without knowing
  any of them — the ARexx broadcast, mesh-wide.

The result: the Bus becomes a universal remote for the machine — and for the
mesh — with the translation layer written in the same small language you script
everything else in. A verb in; a real-world effect out; the bridge is a handful
of lines of Mix.

## See also

- [Bus messaging](bus.md) — `send` / `emit` / `address` / `on` / `reply`, topic pub/sub, `$result`/`$rc`, the no-broker state machine, `async`/Class C
- [invocation & CLI](invocation.md) — every `mix` entry mode, including the `--serve` flag summary and `--check`
- [capabilities & embedding](capabilities.md) — the trust model; a citizen is a *trusted, full-capability* process, not a sandbox for untrusted code
- [errors](errors.md) — `try … catch`, `die`, and how runaways become clean errors inside a handler
- [functions](functions.md) — handler bodies, lambdas, and the pass-in / return / reassign idiom for threading state
- The [cos repo](https://github.com/markc/mixos) — `noded`, the Bus broker
- The [mix repo](https://github.com/markc/mixos) — [AGENTS.md](https://github.com/markc/mixos/blob/main/AGENTS.md) is the agent orientation sheet; this manual is the language reference
- `mix help` · `mix what send` · `mix what emit` · `mix what address` (`mix what` covers the Bus keywords; `on`/`reply` are handler forms it does not index)

---

<!-- page: https://mixos.dev/mix/shell-mode/ (source: https://mixos.dev/mix/shell-mode.md) -->

# shell-mode — shell-dispatch mode

Mix is both a scripting language **and** a login shell. When you hand it a line
that looks like a command rather than Mix code — `git status`, `ls -la | wc -l`,
`make && ./run` — it dispatches that line to the system the way a shell does:
`&&` / `||` / `;` chaining, `|` pipes, brace expansion, `$(...)` command
substitution, redirects. This is **shell-dispatch mode**, the shell half of the
`mix -c` / login-shell contract.

The whole point: a node that runs `/opt/mixos/bin/mix` as root's login shell
must still honour the universal `sh -c` contract — `ssh host 'hostname'` and
`ssh host 'systemctl restart foo'` have to *just work*, while `print(1 + 1)` and
every other Mix statement still evaluate as [Mix](overview.md). One classifier
decides per line which world you are in.

Since 0.31, `;` also separates **Mix statements** on a line classified as Mix
(`$x = 1; print($x)`). Classification is still whole-line: shell-dispatch gives
the glyph the command-list semantics documented here; executable Mix gives it
the hard statement-boundary semantics documented in [syntax](syntax.md).
It never switches languages midway. In particular, Mix permits `&&`/`||`
continuation across a physical newline, but `;` always ends that chain.

> **One sentence to carry:** shell-dispatch handles **one command, a pipeline,
> or a `&&`/`||`/`;` chain** with bash-style brace expansion, `$(...)`, and
> redirects — it is *not* a full shell scripting language (no `for`/`while`/`if`
> shell constructs, no functions — those are [Mix](control-flow.md)).

The two-context split is the thing to internalise: `$(...)` and `{a,b}` are
**LIVE** on a shell-dispatch line but **LITERAL** inside a Mix string. See
[The two-context split](#the-two-context-split) below.

## Where shell-dispatch happens

Interactive sessions can opt into the [owned editor preview](owned-editor.md)
with `MIX_EDITOR=owned`. Rustyline remains the default; both editors feed the
same shell-dispatch and evaluation paths.

Three entry points run the same classifier (`shell::classify_input`) and the
same executor (`exec.rs`):

```
mix -c '<line>'         one-shot:  classify <line>, dispatch or evaluate
mix -i -c '<line>'      as -c, but load ~/.mixrc first (aliases + PATH)
<the REPL prompt>        every line you type interactively
ssh host '<line>'        if mix is root's login shell there, host runs it as -c
```

An ordinary `.mix` script remains whole-file Mix. The narrow exception is an
explicitly continued command line: its physical lines are spliced first, then
the complete logical line is classified through the same shell-first path. This
makes `echo one \` followed by `two` agree in a file, `-c`, and the REPL without
turning every bareword in every script into a command.

A login-shell node makes the last one transparent — `ssh host 'uptime'` is
evaluated by mix, dispatches `uptime` to the system, and returns its output and
exit code. Send Mix *source* when you want Mix behaviour; send a bare command
when you want shell dispatch.

> Two *other* paths run commands but are **not normally** this classifier: the
> [`run()` / `run_rc()`](system.md) builtins always spawn `/bin/sh -c`
> (POSIX sh — no brace expansion there), and a `.mix` script file is parsed
> whole as Mix unless the explicit-command-continuation exception above applies.
> Backslashes inside a `run`/`sh` argument string stay untouched and belong to
> that real shell.

`source` first tries to parse the entire file as Mix, then falls back to
classifying it line by line when that parse fails. An explicitly continued
logical line classified as shell also forces this fallback, even if the
half-joined text could have parsed as Mix arithmetic. Consequently, a file
containing argument-less bareword command lists such as `ls; pwd` can parse as
discarded Mix string expressions and do nothing; add command arguments to force
the shell fallback, or write explicit Mix calls in a pure-Mix file. This is a
known compatibility edge of whole-file-first sourcing.

## The classifier — shell or Mix?

Each line is classified **shell-first** by its first word:

| First word is… | Goes to |
|---|---|
| a [Mix keyword](keywords.md) head (`print`, `if`, `for`, `send`, `try`, …) | Mix (with a shell-chain fallback) |
| a `$`-led line (`$x = 1`) | Mix (with a shell-chain fallback) |
| a shell builtin (`cd`, `exit`, `which`, `mix`, …) | shell dispatch |
| a **defined [function](functions.md)** invoked bareword (`sc restart nginx`) | Mix — a command-style call `sc("restart", "nginx")` |
| a tight-hyphenated command head (`mixos-comp`, `systemd-nspawn`) | shell dispatch, even when missing from `$PATH`; a missing command reports its complete name |
| found on `$PATH`, or an absolute/relative path | shell dispatch |
| none of the above, but parses as a Mix expression | Mix |
| none of the above and a command-like head | shell dispatch (so you get the familiar `No such file or directory`, exit 127) |

The exact keyword-head set routed to Mix: `if` `for` `while` `loop` `function`
`fn` `return` `select` `print` `eprint` `die` `try` `parse` `export` `alias`
`break` `continue` `send` `address` `emit` `source` `sh` `label`. Note what is
**not** in it: `true`, `false` and `nil` (see the next section).

### Bareword function dispatch — bash parity for your toolkit

A line whose head is a **currently-defined Mix function** dispatches as a
command-style call, so a ported bash toolkit works with no parens:

```text
$ sc restart nginx          -- runs sc("restart", "nginx")
$ health                    -- zero-arg call, no parens
$ newpw 20                  -- newpw("20")
```

The function check sits **after** Mix keywords and shell builtins but **before**
the `$PATH` probe, so a defined function **shadows a same-named binary** — matching
bash's `alias → keyword → builtin → function → PATH` order. Only a *simple*
command qualifies: plain word arguments, quotes (`'…'` / `"…"`) group and are
stripped, and there is **no variable or glob expansion** — bareword args are
**literal** (use the paren form `sc("restart", $svc)` when you need
interpolation). Anything with a pipe, redirect, `&&`/`||`/`;` chain, `$(…)`
substitution, or a `KEY=val` env prefix falls through to normal shell dispatch,
so a function in a pipeline is still the shell's job. Inside a `.mix` **script**
(the whole-file parse path) there is no shell classifier — call functions the
Mix way, `sc("restart", "nginx")`.

A function is "defined" only when it is in scope at classify time: interactive
`mix -i` (which loads `~/.mixrc` and the `~/.rc` toolkit) and `mix -i -c '…'`
see them; a bare `mix -c '…'` (no rc) does not, so there the same line stays a
shell command.

A line the classifier hands to Mix that then fails to lex/parse reports the
**real** lexer/parser error and exits 1 — `mix -c 'print(0755)'` prints the
leading-zero lex error, not "No such file". A genuine shell typo (`gti status`)
still gets `mix: gti: No such file or directory` and exit 127, and real
commands keep dispatching.

The tight-hyphen rule applies only to a command-shaped **statement head**: an
ASCII letter/`_` start, at least one unspaced `-`, an ASCII letter/digit/`_` end,
and no other characters. It does not reach into `print(a-b)`, assignments, or
parenthesised expressions; `a - b`, `$a-$b`, `$x-1`, and `1-2` are subtraction.
Scope does not affect the result: bare `a` is the string `"a"`, not `$a`, so
head `a-b` is a command even when `$a` is live. Exact earlier heads retain
precedence, so `mix not-a-command` is still a `mix` meta-command invocation.

```mix
print(1 + 1)        -- Mix: prints 2
```

```text
2
```

```mix
echo hi             -- shell dispatch: echo is on PATH
```

```text
hi
```

### Gotcha: a bare `true` / `false` runs the shell binary

Inside a Mix expression, `true`, `false`, and `nil` are literals (`$x = false`,
`if $a == nil`, `[true, false]`). But as a bare **line head** `true` and `false`
route to shell dispatch and run the `/usr/bin/true` / `/usr/bin/false` binaries —
so `false` exits **1** like in every other shell, honouring the universal shell
idiom:

```text
$ mix -c 'false'; echo "rc=$?"
rc=1
$ mix -c 'true'; echo "rc=$?"
rc=0
```

This is deliberate: forcing a bare `false` to the Mix literal made it exit `0`,
which broke `cmd || false`-style scripts. `nil` has no external binary, so a bare
`nil` still falls through to the Mix parse. In a `&&`/`||`/`;` chain they behave
like the shell too:

```text
$ mix -c 'true && echo chained'
chained
$ mix -c 'false || echo fallback'
fallback
```

## Chaining — `&&`, `||`, `;` (shell-dispatch lines)

bash semantics, evaluated left to right:

```text
$ mix -c 'echo one ; echo two'
one
two
$ mix -c 'mkdir -p /tmp/d && echo made'
made
$ mix -c 'test -f /nope || echo missing'
missing
```

- `;` — run unconditionally (sequence).
- `&&` — run only if the previous command **succeeded** (exit 0).
- `||` — run only if the previous command **failed** (non-zero).

The chain's exit code is the **last command actually executed**. A skipped
command carries the prior success/failure forward, exactly like bash.

A short-circuited branch is **never expanded or run** — a `$(...)` inside it has
no side effect:

```text
$ mix -c 'false && /bin/touch /tmp/pwn'
$ test -f /tmp/pwn && echo EXISTS || echo absent
absent
```

A single trailing `;` is allowed (`echo a ;`). A **leading or interior** empty
piece (`&& echo x`, `echo a ;; echo b`) is an error. (Note: a `&&`-led line is
tried as Mix first, so `mix -c '&& echo x'` surfaces a Mix parse error, not the
shell empty-piece error — start a chain with a real command.)

That empty-piece rule is shell-specific. On a line already classified as Mix,
leading/trailing/repeated semicolons are harmless empty statements:
`; print(1);;` prints `1`.

## Pipes — `|`

```text
$ mix -c 'printf "b\na\nc\n" | sort'
a
b
c
$ mix -c 'ls /etc | wc -l > /tmp/count.txt'
```

Each pipe segment is its own program; stdout of one feeds stdin of the next.
The pipeline's exit code is its **last** segment's. Pipes bind tighter than the
chain operators, so `a | b && c | d` is `(a | b) && (c | d)`.

## Background — trailing `&`

A `&` at the very **end** of a line backgrounds the whole pipeline and returns
immediately (exit 0):

```text
$ mix -c '/bin/sleep 5 &'; echo "rc=$?"
rc=0
```

A `&` that is *not* at the end is **not** a job separator (Mix has no mid-line
`&` job control like bash). To background one command and continue, split with
`;`:

```text
$ mix -c '/bin/sleep 5 & ; echo launched'
launched
```

In a one-shot `mix -c`, a backgrounded child is re-parented to init when the
process exits. In the long-lived REPL it goes into the job table (`jobs`,
`fg`, `bg`).

## Brace expansion

bash-5.3 brace expansion, expanded **before** variable/`$(...)` resolution
(like bash). Alternation `{a,b,c}` and sequences `{x..y[..step]}`:

```text
$ mix -c 'echo file.{txt,md,rs}'
file.txt file.md file.rs
$ mix -c 'echo {1..5}'
1 2 3 4 5
$ mix -c 'echo {a..e}'
a b c d e
$ mix -c 'echo {1..10..2}'
1 3 5 7 9
$ mix -c 'echo {a,b{1,2}}'
a b1 b2
```

**Sign-aware zero padding** — an explicit leading zero on an endpoint pads every
element to the widest endpoint's width:

```text
$ mix -c 'echo {01..03}'
01 02 03
$ mix -c 'echo {-03..3..2}'
-03 -01 001 003
```

Other bash-5.3 rules that hold: nesting (`{a,b{1,2}}`), reverse ranges
(`{5..1}`), the increment's absolute value is used and `0` means `1`. A group
that is **not** a valid brace expression stays **literal**:

```text
$ mix -c 'echo {a}'
{a}
$ mix -c 'echo a{}b'
a{}b
```

So `find . -exec {} \;` is safe — the `{}` is invalid as a group and passes
through untouched.

**Hardening (never a partial expansion):** a word expanding past ~10 000
results, or groups nested/chained past 64 deep, is left **completely
unexpanded** rather than partially expanded. The injection invariant holds —
braces are structural only in **raw literal text**: a quoted/escaped `{`, a
`${X}`, and anything a variable's *value* contains never expand.

## `$(...)` command substitution

Runs the inner command via `/bin/sh -c`, splices its stdout into the line with
trailing newlines stripped:

```text
$ mix -c 'echo today is $(date +%A)'
today is Monday
$ mix -c 'echo got-$(echo X)'
got-X
```

**Unlike bash, the result is ONE word** — it is *not* re-split on whitespace.
This is a deliberate safety difference:

```text
$ mix -c 'echo [$(echo a b c)]'
[a b c]
```

(In bash, `echo [$(echo a b c)]` would re-split into three words. Mix keeps the
captured output intact as a single argument — closer to a quoted `"$(...)"`.)

Things that **stay literal** on a shell-dispatch line:

```text
$ mix -c 'echo $((1+2))'          # arithmetic $(( )) is NOT command substitution
$((1+2))
$ mix -c "echo '\$(echo X)'"      # single-quoted is fully literal
$(echo X)
```

An inner `|` / `;` / `&&` belongs to the **substitution**, not the outer line:
`echo $(ls | wc -l)` runs `ls | wc -l` inside the `$(...)` and splices the
count. A lazy detail: a `$(...)` is run **only** when its chain piece is
selected for execution (see the short-circuit example above).

## Redirects

In parse order, like bash:

```
>  file     1> file    redirect stdout (truncate)
>> file     1>> file   redirect stdout (append)
<  file                redirect stdin
2> file                redirect stderr (truncate)
2>> file               redirect stderr (append)
2>&1                   fd 2 := fd 1   (stderr to wherever stdout points)
1>&2  / >&2            fd 1 := fd 2   (stdout to stderr; >&2 is the common idiom)
>&1                    1>&1 — stdout onto itself, a no-op
&> file     &>> file   both streams to file  (≡ >file 2>&1 / >>file 2>&1)
```

```text
$ mix -c 'echo hi > /tmp/out.txt'; cat /tmp/out.txt
hi
$ mix -c 'echo l1 > /tmp/log'; mix -c 'echo l2 >> /tmp/log'; cat /tmp/log
l1
l2
$ mix -c 'ls /nope 2>&1' | head -1
ls: cannot access '/nope': No such file or directory
$ mix -c 'ls /nope &> /tmp/both.txt'; cat /tmp/both.txt
ls: cannot access '/nope': No such file or directory
```

Ordering matters exactly like a shell: `>f 2>&1` sends both streams to `f`,
while the unusual `2>&1 >f` keeps stderr on the original stdout.

Mix dups **only fds 1 and 2**. An unsupported fd target (`>&3`, `>&-`, `3>&1`)
is a clear **error**, never a silent junk file:

```text
$ mix -c 'echo hi >&3'
unsupported fd in redirect '1>&3' — Mix dups only fds 1 and 2
```

A bare `&` is a word-breaking metacharacter only immediately before `>`
(`cmd arg&>out` redirects, no stray `arg&`); a lone `&` mid-word is literal, and
a trailing `&` is background.

## `mix` meta-commands under plumbing (interactive REPL)

A bare `mix <sub>` line at the REPL is a **meta-command**: it runs in-process
so it can read this shell's live state (`mix vars`, `mix history`, `mix trace
on`, live `mix stats` counters). In-process output prints straight to the
terminal, so plumbing on the line — a pipe tail, any redirect, a background
`&`, or an env prefix — cannot be honoured by that path.

Since 0.61.1 a plumbed `mix …` line is therefore **not intercepted**:

- **Stateless subcommands** (`stats`, `builtins`, `man`, `keywords`, `help`,
  `version`, `config`, `what`, …) run as a normal external pipeline, so
  `mix stats never | wc -l`, `mix stats never >> log`, and
  `mix builtins --json | jq .` all work. Live stats are flushed to disk first,
  so the external `mix stats` child reads current data including this session.
- **Live-state subcommands** (`history`, `vars`, `aliases`, `functions`,
  `all`, `type`, `status`, `context`, `snapshot`, `ask`, `chat`, `trace`,
  `diagnose`, `reload`, `build`, `update`, and bare `mix`) are **refused
  loudly** with exit status 2 — an external child would silently answer from
  different state. `mix stats reset` / `mix stats clear` are refused under
  plumbing for the same reason: they mutate the persisted store under an
  invariant that spans this shell's live counters.

```text
alpha ~ mix history | wc -l
mix history: runs inside the interactive shell — pipes, redirects and & are not supported; run it bare
```

Before 0.61.1 the plumbing was silently dropped: `mix stats never | wc -l`
printed the report and never ran `wc`; `mix stats never > x` created nothing.

All of the above applies to a **single-pipeline** line. A `;`/`&&`/`||`
**chain** is a different intake with no meta-command interception (shell
builtins like `cd` still run in-process there): `mix vars; echo hi` answers
`vars` from a fresh external child (empty), with no refusal and no stats
flush. Don't put live-state meta-commands — or the mutating
`mix stats reset` / `mix stats clear` — in chains.

## Variables and the injection invariant

On a shell-dispatch line, `$NAME` / `${NAME}` resolve from the Mix scope, then
the environment:

```text
$ X=hello mix -c '/bin/echo "got: $X"'
got: hello
```

The structural decisions — where the operators, redirects, `name=`
assignments, fd prefixes, and brace groups are — are fixed from the **literal
line text** in a pass that never sees a value. So a variable's value can
**never** inject syntax: it is always a single data word, never a `;`, a `&&`,
a redirect, or an extra argument.

```text
$ X='a; echo PWNED' mix -c '/bin/echo "[$X]"'
[a; echo PWNED]
```

The `;` inside `$X` is data, not a command separator. The same holds for
`$(...)` results — captured stdout is spliced as data and never re-parsed for
operators.

A leading `name=value` (literal key only) sets an env var for that command,
bash-style:

```text
$ mix -c 'FOO=bar /bin/sh -c "echo \$FOO"'
bar
```

## In-process builtins under `-c`

A handful of builtins are handled **in-process** rather than spawned. `cd` is
intercepted as a lone command **and** in a single-segment foreground
`&&`/`||`/`;` chain, so it changes the directory instead of failing to spawn a
nonexistent `cd` binary:

```text
$ mix -c 'cd /tmp && pwd'; echo "rc=$?"      # cd in a chain: in-process
/tmp
rc=0
$ mix -c 'cd /nope && pwd'; echo "rc=$?"     # failing target: rc=1, not 127
cd: /nope: No such file or directory (os error 2)
rc=1
```

The narrow exceptions still spawn (and fail) so a redirect or env prefix is never
silently dropped — a **piped**, **backgrounded**, **redirected**, or
**env-prefixed** `cd`:

```text
$ mix -c 'cd /tmp | cat'; echo "rc=$?"       # piped cd: spawns, fails
mix: cd: No such file or directory (os error 2)
rc=127
```

`exit` is intercepted only as a **lone** command; in a chain it spawns like any
external program and fails. Note the shell-layer `exit N` parses N as a plain
i32 (an unparseable N — including a fractional one — silently exits `0`, and
the OS truncates a status above 255), while the *language* builtin `exit(n)`
validates `0..=255` and raises `VALUE_OUT_OF_RANGE` outside it (since 0.59.0)
— a known language/shell-layer divergence, queued for its own fix. The bare `mix` head is self-resolved to the running
binary (so `mix --version` re-enters this executable regardless of PATH), and a
bare `mix` with no subcommand under `-c` is refused (it would start a nested
REPL). The REPL-only builtins (`jobs`, `fg`, `bg`, `pushd`, `popd`, `history`,
`unalias`) have no meaning under `-c`.

```text
$ mix -c 'mix --version'
mix 0.21.2
```

## The two-context split

The single most important rule. The **same characters** mean different things
depending on whether they are on a shell-dispatch line or inside a **Mix
string**:

| Construct | On a shell-dispatch line | Inside a Mix `"string"` |
|---|---|---|
| `$(cmd)` | **runs** `cmd`, splices stdout (one word) | **literal text** `$(cmd)` |
| `{a,b}` / `{1..5}` | **brace-expands** | **literal text** (a `{...}` in Mix source is a map literal or literal text) |
| `$((1+2))` | literal (arithmetic, unsupported) | literal text |
| `${NAME}` | env/scope interpolation | scope→env interpolation |
| bare `$name` | env/scope interpolation | **literal text** (the opposite of bash) |

```text
$ mix -c 'print("{1..3}")'        # Mix string: braces are literal
{1..3}
$ mix -c 'print("$(echo hi)")'    # Mix string: $(...) is literal
$(echo hi)
$ mix -c 'echo {1..3}'            # shell line: braces expand
1 2 3
```

The trap: you reach for `$(...)` or `{a,b}` inside a Mix double-quoted string
and nothing happens — they are inert data there. To splice a command's output
**in Mix code**, use [`run()` / `run_rc()`](system.md) and `..`
concat:

```mix
$count = trim(run("ls /etc | wc -l"))
print("etc has " .. $count .. " entries")
```

Two narrow exceptions where `$(...)` *does* substitute in Mix source: a
**heredoc** body, and the standalone `$(cmd)` **expression** (see
[strings](strings.md)). And in a `run()` / `ssh_run()` command **string**, a
`$(...)` passes through to the *target* shell that runs the command (local for
`run`, remote for `ssh_run`). For multi-line remote Mix or nested quotes, skip
that extra parse with the
[`ssh_mix` + heredoc idiom](remote.md#headline-idiom-ssh_mix--heredoc).

## Timing — the `time` modifier

`time` is a **modifier**, not a command — exactly as in bash, where `time` is a
shell keyword and not a program. Mix resolves it before dispatch, so it wraps
whatever the rest of the line turns out to be: an external command, a pipeline,
a chain, a bareword function, or Mix code.

```text
$ time shwho example.org
...
Elapsed: 412.181ms

$ time sum([1, 2, 3, 4, 5])
15
Elapsed: 0.012ms

$ time ls | wc -l
18
Elapsed: 1.251ms
```

The elapsed line goes to **stderr**, so a timed command's stdout stays clean for
a pipe or a redirect. The timed command's exit code is passed through unchanged.
Sub-second runs report milliseconds; longer ones promote to `1.500s` / `1m5.000s`.

`time` is resolved **before alias expansion**, so the wrapped head still expands
— `time ll` times `ls -l`. A bare `time` with nothing to run reports usage and
exits 2.

Being resolved before dispatch, the modifier **shadows every other `time`**: a
`time` binary on PATH (GNU `/usr/bin/time` — reach it by full path, as Mix has no
`command` builtin), an `alias time = …`, and a user-defined Mix `function time`.
Bash's keyword shadows a PATH `time` the same way. Rename any Mix function you
want to keep callable bareword; a paren call is unaffected.

`time()` — with parens — is the unrelated [`time()` builtin](datetime.md)
returning a Unix timestamp, not the modifier: only a bare `time` HEAD followed by
something to run is stripped. `timeout 5 cmd` is likewise untouched (the head must
be exactly `time`).

`mix time EXPR` is the same modifier under its older spelling, kept working.

The modifier lives in the shell-dispatch layer, so it is available at the prompt,
under `-c`, and over ssh (`ssh host 'time shwho example.org'`) — but NOT in a
`.mix` script (parsed as Mix, not dispatched line-by-line) and NOT in a sourced
line or `~/.mixrc`. To time a region of a script, subtract two
[`time()`](datetime.md) reads, or use the `duration_ms` field that
[`run_argv()`](system.md) already returns.

Two lines report no elapsed. A backgrounded command (`time sleep 5 &`) returns at
spawn, so there is no runtime to measure — it says `backgrounded (&) — not timed`
rather than print the spawn latency as if it were the duration. And an `exit()`
mid-line (or a `mix build` that re-execs) never returns, so nothing survives to
report; bash does print a timing for `time exit`, Mix does not.

`time;`, `time&` and `time|` have nothing to run and report usage.

## What shell-dispatch is NOT

Shell-dispatch handles a command, a pipeline, or a chain — **not** shell control
flow. There is no `for`/`while`/`if`/`case` shell syntax, no shell functions, no
`$?` (use the structured return of [`run_rc()`](system.md)). Those
constructs are [Mix](control-flow.md):

```text
$ mix -c 'for x in $(echo a b c); do echo "[$x]"; done'
mix: for: No such file or directory (os error 2)
mix: do: No such file or directory (os error 2)
mix: done: No such file or directory (os error 2)
```

Mix saw `for` as a keyword, tried to parse Mix, and `do` is not even a Mix
keyword — so it fell back to the shell path and tried to *run* `for` / `do` /
`done` as programs. Write it as a Mix loop instead:

```mix
for each $x in split(trim(run("echo a b c")), " ")
  print("[" .. $x .. "]")
end
```

```text
[a]
[b]
[c]
```

When in doubt: a PATH/bare command head → shell dispatch; a `$`/Mix-keyword/call
head → Mix. Operators later on the line—including `;`—do not override the
head-first classifier.

## Aliases (`-i` only)

`~/.mixrc` aliases and PATH load for **interactive** logins (`mix -i`,
`mix -i -c`, the REPL) — **not** a plain `mix -c`. So a non-interactive
`ssh host '<line>'` runs with no aliases. Aliases are expanded on the first word
before classification, so an alias expanding to a chain (`u = "sudo apt update
&& sudo apt upgrade"`) lands on the shell path correctly.

## Terminal output mode (interactive REPL)

The interactive REPL owns the terminal's output post-processing: before every
prompt it re-asserts `OPOST | ONLCR` on stdout, so a bare `\n` from an external
command always arrives as CR-NL and lines start at column 0. This repairs an
inherited raw tty (Mix started as a login shell on a terminal left with `ONLCR`
off) or a foreground child that exited without restoring it — the classic
"staircase", where each line steps rightward, can't persist across a prompt.

Consequence: a `stty -onlcr` you run at the Mix prompt does **not** stick — Mix
re-enables CR-NL output on the next prompt. Mix touches only those two output
bits; input flags, control characters, flow control and every other `stty`
setting are left alone. Non-interactive modes (`mix -c`, scripts, `mix --serve`)
never touch the tty.

## See also

```
mix help              the full categorized builtin reference
mix what run          one-line help for the run() builtin
mix keywords          every Mix keyword (so you know what the classifier reserves)
```

- [overview](overview.md) — the language at a glance
- [running-commands](system.md) — `run` / `run_rc` (via `/bin/sh`, structured returns), `run_argv` / `run_stream` (argv lists, no shell)
- [strings](strings.md) — `'raw'` vs `"${...}"`, heredocs, the literal-`$(...)` rule
- [keywords](keywords.md) — Mix keywords the classifier routes to Mix
- [control-flow](control-flow.md) — `if` / `for each` / `while` (the Mix replacements for shell control flow)
- [bus](bus.md) — `send` / `emit` / `on … end`, the Bus-native side of the language
- [The Mix repo](https://github.com/markc/mixos) — [AGENTS.md](https://github.com/markc/mixos/blob/main/AGENTS.md) is the agent orientation sheet on top of this manual

---

<!-- page: https://mixos.dev/mix/sqlopen/ (source: https://mixos.dev/mix/sqlopen.md) -->

# sqlopen — SQLite files: sqlopen, sqlexec, sqlclose

Mix has an embedded SQLite client (the `sqlite` feature; the `mix` binary
turns it on), so a script can create, query and update a database file
without the `sqlite3` CLI. Handles are plain numbers. These builtins are
`FsWrite`: they are arbitrary filesystem authority. A host that hands a
script one store should use the scoped `Db` seam (`db_query`) instead
(`mix man capabilities`).

```
sqlopen(path[, mode])      open a database             -> numeric handle
sqlexec(h, sql[, params])  run one statement           -> rows or {affected}
sqlclose(h)                close the handle (an unknown handle raises)
```

## Modes

| `mode` | Opens | A missing file |
|---|---|---|
| omitted, or `"ro"` | read-only | raises `SQL_NO_DATABASE`; nothing is created |
| `"rwc"` | read-write, WAL journal, 5 s busy timeout | is created |
| `"rw"` | the same as `"rwc"` | is created |

The default is **read-only**, so a script that only reads a database (a
secrets store, another program's state) cannot change it, or its journal
mode, by accident. A write through a read-only handle raises. To create a
database, say so with `"rwc"`. Any other mode, including `nil`, `"RW"` and
`""`, raises `OPTION_INVALID`; before 0.117.0 an unknown mode silently
opened read-only, which is why `sqlopen(path, "rwc")` used to fail on a new
file with only `unable to open database file`.

Opening read-write sets `PRAGMA journal_mode=WAL`, which is persistent: the
file stays in WAL mode and gets `-wal` and `-shm` siblings while it is open.
Open another program's database read-only unless the script owns it.

`":memory:"` is a private in-memory database that lives as long as the
handle. Open it with `"rw"`, since a read-only one can never hold a table.

```mix
$path = "/tmp/sqlopen-demo.db"
$db = sqlopen($path, "rwc")
sqlexec($db, "CREATE TABLE IF NOT EXISTS seen (id TEXT PRIMARY KEY, at INTEGER)")
sqlexec($db, "INSERT OR IGNORE INTO seen VALUES (?, ?)", ["msg-1", 1760000000])
sqlclose($db)

$ro = sqlopen($path)
print(json_encode(sqlexec($ro, "SELECT id FROM seen")))
sqlclose($ro)
```

```text
[{"id":"msg-1"}]
```

## Results and parameters

`sqlexec` returns a **list of row maps** for anything that produces columns
(`SELECT`, row-returning `PRAGMA`s) and `{affected: n}` for a write. SQLite
decides which (`sqlite3_stmt_readonly`), so `REPLACE` and `WITH … INSERT`
take the write path. Column values map NULL to `nil`, INTEGER and REAL to a
number, and TEXT to a string. A BLOB comes back as the placeholder string
`<blob N bytes>`, not as bytes.

`params` binds `?` placeholders: a list binds positionally, and a single
non-list value is one bind. Binds are typed: `nil` is NULL, a bool is
INTEGER 0/1, a whole number is INTEGER, a fractional one is REAL, a string
is TEXT and bytes are a BLOB. A list or map param raises. Always bind data;
never splice values into the SQL string.

## Errors

| Code | When |
|---|---|
| `SQL_NO_DATABASE` | a read-only open of a path that does not exist |
| `OPTION_INVALID` | a mode other than `"ro"`, `"rw"` or `"rwc"` |
| (runtime error) | SQLite refused the open or the statement; the message is SQLite's |

## See also

- [io](io.md): the rest of the filesystem builtins.
- [data](data.md): how Mix values cross serialization boundaries.

---

<!-- page: https://mixos.dev/mix/stats/ (source: https://mixos.dev/mix/stats.md) -->

# Usage statistics

`mix stats` records how Mix is used and reports either dynamic usage or static
authorship coverage. Recording is best-effort: a missing, read-only, corrupt,
or busy state store never changes program output or exit status.

## Collection modes

| Invocation | Mode | Script label |
|---|---|---|
| interactive REPL | `interactive` | none |
| `mix file.mix` | `script` | basename only |
| `mix -c CODE` | `c` | none |
| `mix -` | `stdin` | none |
| `mix --serve file.mix` | `serve` | basename only |

Calls in functions, callbacks, handlers, `source`, and `include` retain the
top-level mode and script label. Paths are never stored. Basenames are truncated
to 96 Unicode characters; each weekly document keeps at most 128 distinct
labels and merges overflow into `(other)`.

The standard prelude and `~/.mixrc` load before collection is attached, so
bootstrap code does not pollute the invoking program's figures. Remote ssh
execution needs no special mode: the far-end process records its normal
`script`, `c`, or `stdin` invocation.

Enabled collection is not free. Exact statement/function counts make recursive
functions use the canonical evaluator path instead of the native sync-recursion
fast path, and tracked calls perform builtin membership lookup. This can be
measurable in tight recursive or call-heavy workloads; use `MIX_STATS=off` when
that cost matters.

## Disable collection

Set `MIX_STATS=off`; `0` and `false` are synonyms, ignoring ASCII case and
surrounding whitespace. This is the documented setting for remote and mesh
servers:

```text
MIX_STATS=off mix -c 'print("unrecorded")'
```

The setting is read once per process. When disabled, Mix allocates no collector
and opens no state file, database, or lock. Every runtime tracking hook first
checks the same cached boolean and returns before borrowing collector state,
formatting errors, or scanning builtin names. `mix stats`, including `coverage`,
prints a disabled message without reading its target.

## Storage and concurrency

State lives under `$XDG_STATE_HOME/mix`, falling back to
`$HOME/.local/state/mix`. One-shot runs accumulate counters in memory and flush
once after evaluation, including after `exit(code)` and ordinary uncaught
errors. Long-lived processes retain daily UTC buckets so a run crossing
midnight or an ISO-week boundary is split truthfully.

The store is JSONL. A finished run appends one record, its counters by day
plus its run record, to `runs/YYYY-MM-DD.jsonl`, named for the UTC day it was
written. That is all a run does with the store: one `write(2)` on an
`O_APPEND` file, with no lock, no read, no listing and no retry. Each record
starts and ends with a newline, so a record a crash or a short write cut short
cannot swallow the next one; readers skip blank and unparseable lines, and a
complete record that lost only its final newline still counts once. A short or
failed write drops that run's counters. Raw files are history: nothing ever
rewrites, truncates or deletes them. A file's name says only where a record
was written: its buckets and runs carry their own dates, and reports filter
by those.

Every record carries a random `batch` id, and readers keep one copy of each
batch per day file (the dedupe does not reach across files). A REPL
`mix stats` pipeline flushes its live counters mid-session and may retry: the
retry repeats the same record into the same file. It hands the counters back
to the session only when every attempt is known to have written nothing; if an
attempt may have landed (an I/O error after the write), they are dropped
rather than risk being counted twice. A short write is never retried. A
`--serve` generation retiring at RELOAD is finished, so it is recorded like a
run's exit, once.

`cache/YYYY-MM-DD.json` holds an advisory aggregate per day, with the dates
its records touch, written only by `mix stats` commands, only for days before
today, and only when the command gets `cache.lock` (a busy lock just skips
it; runs never touch it). Each entry names the raw file it summarises by
device, inode, length, mtime and ctime, all taken from the descriptor that
was read, and is fully validated when read. If the raw file no longer matches,
because a late run, a clock rolled back or anything else changed it, the
entry is ignored and the day is read from the raw file. Deleting `cache/`
loses nothing.

`clear` and `reset` append an operation to `ops.jsonl` instead of rewriting
anything, and apply only to the JSONL store. An operation is anchored to
storage positions, not to a clock: it records the length of every raw file
when it was issued and applies to exactly the records whose JSON ends within
those lengths; anything stored later, in any file, is after it. Operations
take `ops.lock` (runs never do), so two at once take turns, and one refuses if
another holds it for two seconds. Repeated operations on the same target
(clears of one name, resets of one week) collapse into one when read, which
bounds how many a report applies; every report still reads all of
`ops.jsonl`.

Weekly documents from the previous store (`current.json`, `YYYY-WNN.json`) are
read in place, with that store's own rules, including the fingerprints that
stop an interrupted rotation from counting a week twice. They are never moved,
rewritten or quarantined, and their writers' lock, `stats.lock`, is never
taken: a binary from before the JSONL store may still be running and writing
them, and it drops a write if that lock stays busy. Since it writes only those
files while new binaries write only JSONL, the totals add up exactly during a
mixed rollout. The documents are read as a validated snapshot: if one changes
while it is read (an older binary rotating or rewriting it), the read is
repeated, and if it never settles the report says the legacy store was busy.
`clear` and `reset` refuse, recording nothing, while any of these documents
exists: an older binary may still be writing them, so they cannot be cleared
exactly. They age out of week windows. The check runs when the operation
starts and again once it holds `ops.lock`; it is a point-in-time check, not
proof that no older binary will write one later. `mix.db` held only what the documents
carried and is ignored.

Reports stream: they read each day line by line, use the cache where it still
matches (and skip a day whose cached dates miss the window), and keep run
records only for reports that list them (`sessions`, `raw`, `query`). Run IDs
include 128 bits of random entropy. `mix stats` commands that get the lock
also remove atomic-write temporary files more than an hour old. Details of
skipped records are printed only when `MIX_DEBUG` is set; nothing in
collection ever changes a run's output or exit status.

The store is required to be on a responsive local filesystem: appends rely on
local `O_APPEND` semantics (a single write lands whole or is short, never
interleaved), and a stalled NFS/FUSE mount can stall a flush.

In script, `-c`, stdin, and serve modes, SIGINT and SIGTERM take the normal
flush path. The interactive REPL stays alive on Ctrl-C and later flushes on EOF,
`exit`, or ordinary shutdown, but an OS SIGTERM uses the terminal process's
default termination and may lose its in-memory batch. `SIGKILL`, a panic, or
power loss can also lose the in-memory batch; stats are intentionally
best-effort.

If legacy history remains under `$MIXOS_SRC/_stats`, report commands print a
migration or acknowledgement command. History is never moved automatically.

## Reports and windows

Every usage report prints its window in the first line. The default window is
the current ISO week, and `overview` and `never` use the exact same snapshot.

```text
mix stats                 current-week overview
mix stats builtins       current-week builtin calls
mix stats functions      current-week user-function calls
mix stats aliases        current-week alias expansions
mix stats commands       current-week external commands
mix stats keywords       current-week canonical keyword executions
mix stats meta           current-week meta commands
mix stats errors         current-week errors
mix stats sessions       current-week completed runs
mix stats never          current-week builtins and keywords with zero use
mix stats modes          current-week per-mode breakdown
mix stats scripts [N]    top scripts; N defaults to 10 and is bounded to 1–100
mix stats raw            current-week JSON snapshot
mix stats week YYYY-WNN  one ISO week
mix stats since DATE     buckets on or after YYYY-MM-DD
mix stats all            everything recorded
mix stats trend NAME     last 30 recorded days
mix stats query SQL      all-time SQL over an in-memory database
```

At the interactive REPL, a bare `mix stats …` line runs in-process and reports
this session's live counters. Since 0.61.1 a piped or redirected line
(`mix stats never | wc -l`, `mix stats never >> log`) runs as a real external
pipeline instead — live stats are flushed to disk first, so the child reads
current data including this session. Before 0.61.1 the plumbing was silently
dropped. See `mix man shell-mode` § "`mix` meta-commands under plumbing".

`clear NAME` removes a name from every counter category of everything stored
before it. `reset` removes the current week's buckets and runs stored before
it; older days stay, and a live REPL retains older pending buckets. Both are
appended operations, anchored to storage positions and applied at read time;
neither rewrites stored data, and runs recorded later keep their counts. Both
refuse while the old weekly documents exist (see Storage and concurrency). Week
and date arguments must use canonical `YYYY-WNN` and `YYYY-MM-DD` forms. `query`
loads everything recorded into an in-memory SQLite database with the tables the
old on-disk `mix.db` had (`usage`, `usage_context`, `runs`, `sessions`,
`stats_meta`), so existing queries keep working.

The canonical tracked keyword vocabulary is:

```text
if for while loop function return select print eprint parse die
try catch finally export alias break continue send address emit on
source include sh
```

Structural delimiters such as `then`, `end`, `done`, and `each` are not usage
events.

## Static authorship coverage

```text
mix stats coverage DIR
```

Coverage follows the root path explicitly named by the user, then recursively
scans sorted `.mix` files without following symlinks encountered below that
root. It tokenises and parses with Mix's real lexer and parser, then walks the
AST. Builtin call sites inside strings, heredocs, or comments cannot be mistaken
for code. Nested calls, higher-order builtins, and builtin method syntax are
counted. Calls through a function-valued expression are reported as “dynamic
calls not classifiable” and are never guessed.

The command reports used and never-authored builtins and canonical keywords.
If any selected file is unreadable or fails to lex or parse, diagnostics are
printed and the command exits non-zero without emitting a misleading coverage
report. Coverage performs no persistence writes.

---

<!-- page: https://mixos.dev/mix/strings/ (source: https://mixos.dev/mix/strings.md) -->

# Strings

Mix has two string literal forms, `..` for concatenation, and a deliberately
**codepoint-based** core with explicit byte and grapheme twins. This page covers
the lexer rules (what interpolates, what stays literal, the escapes) and the
string-category [builtins](builtins.md). Every example below was run on **Mix
0.21.2**; the output shown is real.

> Mental model: `"double"` interpolates `${...}` and expands a leading `~`;
> `'single'` is fully raw; `..` joins; `length`/`pos`/`substr` count **Unicode
> codepoints**, with `byte_*` and `grapheme_*` twins when you need the other units.

## The two literal forms

```mix
$name = "world"
print("hello ${name}")          -- ${...} interpolates
print("hello $name")            -- bare $name is LITERAL (unlike bash!)
print('raw ${name} $(date)')    -- single-quote: nothing interpolates
```
```text
hello world
hello $name
raw ${name} $(date)
```

The split mirrors bash's quoting, with one trap that bites everyone:

| Form | Interpolates `${x}` | Bare `$x` | `$(...)` | leading `~` | Escapes |
|---|---|---|---|---|---|
| `"double"` | yes (scope → env) | **literal text** | **literal text** | expands to `$HOME` | `\n \t \r \e \a \b \f \v \0 \xHH \" \\ \$ \~ \u{…}` |
| `'single'` | no | literal | literal | literal | only `\'` and `\\` |

**Only `${...}` interpolates** inside double quotes. A bare `$name` is the literal
three-or-more characters `$name` — the opposite of bash, and the single most common
error an agent makes here. When unsure, prefer `..` concat (below) over
interpolation.

`$(...)` and `$((...))` are **literal text** inside a Mix string — the old
build-time command-substitution footgun was removed. To splice a command's output,
use [`run`/`run_rc`](system.md) plus `..`. (Two exceptions still substitute: a
[heredoc](#heredocs) body, and the standalone `$(cmd)` expression — neither is a
plain string literal.)

Know the two contexts. The literal rule above is about **Mix string literals**. In
a `run`/`run_rc`/`ssh_run` *command string*, a literal `$(...)` passes through to
the target shell — so it substitutes in the `/bin/sh` that actually runs the
command: local for `run`/`run_rc`, the **remote** shell for `ssh_run`:

```mix
print(run("echo $(echo passthru)"))   -- /bin/sh does the substitution
```
```text
passthru
```

And on a *shell-dispatch* line (`mix -c`'s shell branch, the login shell), `$(...)`
**is** command substitution — see [shell mode](shell-mode.md).

### Interpolation walks scope, then env

`${X}` looks up the name in the local scope first, then the process environment:

```mix
print("val=${MYVAR}")
```
```text
# run as:  MYVAR=fromenv mix -c '...'
val=fromenv
```

A name unbound in **both** scope and env is a **runtime error** — the same as
reading a bare `$X`, so a typo is caught loudly rather than silently splicing
text:

```mix
print("[${NOPE_NOT_SET}]")
```
```text
Runtime error: undefined variable '$NOPE_NOT_SET' in interpolation (use ${NOPE_NOT_SET ?? default} for a fallback)
```

A variable whose **value** is nil is bound, so it still renders the literal
`nil` (`$x = nil` → `${x}` → `nil`); likewise a missing map key in a dotted path
(`${a.b}` → `nil`), matching `$a.b`.

**A bare `$name` is literal — this is the opposite of bash.** Only `${name}`
interpolates, so `read_file("$sp/prompt.md")` opens a file called
`$sp/prompt.md`. The rule is deliberate (it lets a string carry shell text and
nested Mix source untouched), but it is also the first thing anyone arriving from
bash gets wrong, so `mix lint` reports it as [MIX-D3015](lint.md) when the name is
bound in the same file:

```mix
$sp = "/tmp/x"
print("$sp/a")      -- literal:  $sp/a      (MIX-D3015)
print("${sp}/a")    -- /tmp/x/a
print('$sp/a')      -- literal, and says so
print("\$sp/a")     -- literal, and says so
```

`\$name` and single quotes are the two ways to mean it, and neither is reported.

### Defaults — `${x ?? default}` and `${x ?: default}`

Supply a fallback with the same coalescing operators Mix uses in expressions.
The default is any Mix expression, evaluated **only** when the fallback fires:

```mix
print("[${NOPE ?? "none"}]")     -- unbound → the default (no error)
$x = nil
print("[${x ?? $home}]")          -- nil value → default may be a variable…
print("[${x ?? upper("hi")}]")    -- …or any expression
```
```text
[none]
[/home/you]
[HI]
```

- `??` fires on **nil only** (an unbound name or a nil value). `${e ?? "x"}`
  where `$e` is `""` keeps the empty string — `??` does not treat it as missing.
- `?:` fires on any **falsy** value (`nil`, `""`, `0`, `false`, `[]`) — use it
  when you want bash's `${x:-…}` "empty also falls back" behaviour.
- Limitation: a default cannot contain a literal `}` (the scanner ends at the
  first `}`) — bind it to a variable first.

For an explicit, unambiguous environment read use `env("X")` (see
[builtins](builtins.md)); for scope-only data prefer `..` concat.

## Concatenation is `..`

Join with `..` — never `+` (that's numeric addition, see [numbers](numbers.md)) and
never `.` (that's map/field access). Non-string operands are stringified:

```mix
$x = 42
print("answer is " .. $x .. "!")
```
```text
answer is 42!
```

`..` is the most robust way to build strings — it sidesteps the bare-`$name`
interpolation trap entirely:

```mix
$user = "ada"
print("hi " .. $user)           -- always works
print("hi $user")               -- literal "hi $user" — usually NOT what you meant
```
```text
hi ada
hi $user
```

## Escapes and `\u{XXXX}`

Double-quoted strings honour `\n \t \r`, `\e` (ESC), `\a \b \f \v` (BEL, BS, FF, VT),
`\0` (NUL), `\" \\ \$ \~`, the two-hex-digit `\xHH`, and the braced unicode escape
`\u{XXXX}` (1–6 hex digits):

```mix
print("tab\there")
print("price: \$5")             -- \$ for a literal dollar
print("\u{2764} love")          -- U+2764 HEAVY BLACK HEART
print("strip BOM:[\u{FEFF}]")   -- zero-width no-break space
```
```text
tab	here
price: $5
❤ love
strip BOM:[]
```

`\u{…}` is **braced-only**: a bare `\u` with no `{` stays literal, so a Windows path
`"C:\users"` or an embedded JSON `\uXXXX` is unchanged. Single-quoted strings keep
`\u{…}` literal too. A surrogate or out-of-range codepoint is a loud lex error
(`\u{D800} is not a valid unicode codepoint`), never a silent pass-through.

### `\xHH`, `\0` and the control escapes (0.90.0)

`\xHH` takes **exactly two hex digits** and its value is the **codepoint** U+00HH —
never a raw byte. A Mix string is UTF-8, so `"\xff"` is U+00FF (one character, two
bytes on the wire), not the byte `0xFF`. For bytes, use `bytes_from_hex` /
`bytes_from`, which keep a different spelling on purpose.

```mix
print("isn\x27t")
print("\x41\x42")
print(len("a\0b"))          -- \0 is NUL, a real character
print("\a" == chr(7))       -- BEL; \b \f \v are BS, FF, VT
```
```text
isn't
AB
3
true
```

`\0` is NUL **exactly**, never the start of an octal escape: octal is ambiguous
next to digits, so `"\012"` is NUL followed by the text `12`. Octal and `\U` are
deliberately absent — `\u{…}` covers what they would have been for.

Fewer than two hex digits is **not** a lex error: `"\x4"` stays the three
characters `\x4`, so a regex pattern meaning the engine's own `\x` never becomes a
hard failure of the whole file. `mix lint` reports it as
[MIX-W2405](lint.md) instead.

Before 0.90.0 all of these were kept literally, which is how a `replace()` once
wrote `isn\x27t` into a committed journal entry with no gate noticing.

### Unrecognised escapes are still literal — and now linted

Any **unrecognised** escape keeps the backslash literally: `"\d"` is the two
characters `\d`, not an error. That is deliberate (it protects regex patterns and
Windows paths), but it is also how a habit from another language becomes silently
wrong output, so `mix lint` flags it as [MIX-W2405](lint.md). A deliberate
backslash is written `\\`, which never warns. Strip a BOM with the real codepoint:
`replace($s, "\u{FEFF}", "")`.

## Leading `~` expansion

A `~` at the **very start** of a double-quoted string expands to `$HOME` at
runtime, and only when the `~` is followed by `/` or ends the string — i.e.
exactly `"~"` and `"~/..."`. Mid-string `~` is always literal (so DNS-zone tokens
like `"~example.com"` survive), and `'~/...'` in single quotes does not expand:

```mix
print("~/.config")
```
```text
/home/user/.config
```

Use `"\~"` for a literal leading tilde. `~user` is not supported — `"~root/x"`
stays the literal text `~root/x` (no expansion, no error); only the running
user's home expands.

**Trap — tilde strings as *text*, not paths.** The expansion is lexical, so it
fires on any double-quoted literal, including one you meant as a search needle.
`replace($s, "~/example/x", "~/new/x")` looks for the literal `/home/you/example/x` and
silently matches nothing against file text that says `~/example/x` — no error, no
change. The same applies to `contains`, `starts_with`, `split`, `index`, and to
`"~" .. "/x"` (the bare `"~"` already expanded). For literal-tilde text use single
quotes, and `grep_lines` the result after a rewrite:

```mix
$s = "see ~/example/x"
print(replace($s, "~/example/x", "Z"))     -- needle became /home/you/example/x: no match
print(replace($s, '~/example/x', "Z"))     -- single quotes: literal needle
```
```text
see ~/example/x
see Z
```

## Heredocs

`<<TAG ... TAG` is a multi-line literal whose body **does** interpolate `${...}`
(scope → env, like double quotes) and, in this context, `$(...)` command
substitution:

```mix
$who = "team"
$body = <<END
Dear ${who},
welcome.
END
print($body)
```
```text
Dear team,
welcome.
```

The rules, precisely:

- The tag is ASCII letters/digits/`_`. The closing tag must sit alone on its line (surrounding whitespace is allowed); the newline before it is stripped.
- A bare `$name` in the body stays **literal**, exactly as in double quotes — only `${...}` interpolates.
- `$(cmd)` runs via `/bin/sh` and splices its stdout — the one string context where Mix itself substitutes a command.
- Escapes `\n \t \r \e \\ \$` work (`\$` suppresses interpolation: `\${not_a_var}`); **`\u{…}` is NOT processed** in a heredoc body — it stays literal. Any other `\x` stays literal too.

## Codepoint, byte, grapheme — pick the right unit

This is the design decision to internalise. The core string ops — `length`/`len`,
`pos`, `lastpos`, the string overload of `index_of` — count **Unicode codepoints**,
so they compose with `substr`/`reverse`/`$s[i]` (also codepoint-based). When you
need raw bytes or user-perceived characters, reach for the explicit twin family.
(The pre-0.8.0 byte value of `length` lives on as `byte_length`.)

```mix
print(length("café"))           -- codepoints: c a f é
print(byte_length("café"))      -- raw UTF-8 bytes (é is 2)
print(grapheme_count("café"))   -- user-perceived chars
print(display_width("日本語"))   -- terminal cells (CJK = 2 each)
print(pos("é", "café"))         -- 1-based codepoint position
```
```text
4
5
4
6
4
```

`length`/`len` on a **list or map** is the element count, not a string length.

The three boundaries, in one table:

| Want | Builtins | Unit |
|---|---|---|
| codepoints (default) | `length`/`len`, `pos`, `lastpos`, `index_of`, `substr`, `reverse`, `left`, `right` | Unicode scalar values |
| raw bytes | `byte_length`, `byte_pos`, `byte_lastpos`, `byte_index_of` | UTF-8 bytes |
| user-perceived chars | `grapheme_count`, `grapheme_substr`, `grapheme_reverse` | grapheme clusters (UAX #29) |
| terminal columns | `display_width`, `lpad_w`, `rpad_w`, `word_wrap_w` | display cells (UAX #11) |

All four rows are operations on **text**. Operations on a raw `bytes`/`buffer`
*value* are a different family, `bytes_*` — see
[io](io.md#naming-byte_-vs-bytes_). The two are easy to confuse and are not
interchangeable: `byte_length($some_bytes)` stringifies its argument first and
so measures the `<bytes:N>` placeholder, not the bytes.

### `ord` / `chr` — codepoint ↔ character (0.90.0)

`ord(s)` is the Unicode codepoint of the **first character**; `chr(n)` is the
one-character string for a codepoint. They are the runtime twins of the `\u{…}`
literal escape, and the only way to *ask* what a string holds —
`bytes_to_hex(string_to_bytes($s))` answers in UTF-8 bytes, which is a different
question.

```mix
print(ord("A"))
print(ord("é"))          -- the CODEPOINT 233, not the first byte 0xC3
print(chr(10084))
print(chr(0x27))         -- the runtime twin of "\u{27}"
```
```text
65
233
❤
'
```

`ord("")` raises: `0` is NUL, a real codepoint that `chr` round-trips, so it cannot
also mean "absent". `chr` takes the `\u{…}` validity rule exactly — a surrogate
(`chr(0xD800)`), anything above `0x10FFFF`, and a fractional or negative argument
all raise rather than saturate to a plausible wrong character.

### `normalize` — canonical equivalence (0.92.0)

Two strings can display identically and still differ: `é` is either one
codepoint (precomposed, U+00E9) or two (`e` + COMBINING ACUTE, U+0301). macOS
filenames arrive decomposed (NFD), most typed text is composed (NFC), so `==`,
hashes and dedup keys disagree. `normalize(s[, form])` brings both to one form —
`"NFC"` (the default), `"NFD"`, `"NFKC"` or `"NFKD"`, case-insensitive; any other
form raises `VALUE_ERROR`.

```mix
$d = "e" .. chr(769)          -- decomposed: e + combining acute
$c = chr(233)                 -- precomposed é
print($d == $c)
print(normalize($d) == $c)
print(normalize(chr(64257), "NFKC"))   -- the fi ligature, compatibility-folded
```
```text
false
true
fi
```

The `K` forms also fold *compatibility* characters — ligatures, fullwidth
letters, superscripts — so they lose information; use them for search and
matching keys, and plain NFC for storage. Emoji, skin-tone modifiers, flags and
ZWJ sequences pass through every form unchanged.
A plain `substr`/`reverse` is codepoint-based and **splits** an emoji ZWJ sequence or
combining cluster; the `grapheme_*` ops keep it whole:

```mix
print(reverse("a👍🏽b"))          -- codepoint reverse splits the skin-tone modifier
print(grapheme_reverse("a👍🏽b")) -- grapheme reverse keeps it whole
```
```text
b🏽👍a
b👍🏽a
```

A decomposed `e` + combining acute is 2 codepoints but 1 grapheme and 1 display cell:

```mix
$d = "e\u{0301}"                -- e + U+0301 COMBINING ACUTE
print(length($d))
print(grapheme_count($d))
print(display_width($d))
```
```text
2
1
1
```

The spread gets dramatic with ZWJ sequences — a 👨‍👩‍👧 family emoji is **1 grapheme,
5 codepoints, 18 bytes**:

```mix
$f = "👨‍👩‍👧"
print(grapheme_count($f))
print(length($f))
print(byte_length($f))
```
```text
1
5
18
```

### Indexing bases differ — a footgun

- `substr`, array indexing, list `index_of`, `slice` are **0-based**. (`left`/`right` take a *count*, not an index — `left("hello", 2)` → `"he"` — so they have no base.)
- `pos` and `lastpos` are **1-based**, returning **0 when not found**.
- An empty needle gives `pos == 1`.

```mix
print(substr("hello world", 0, 5))   -- 0-based, length 5
print(substr("hello world", 6))      -- no len → to the end
print(pos("world", "hello world"))   -- 1-based
print(pos("xyz", "hello world"))     -- not found → 0
print(lastpos("o", "hello world"))   -- 1-based last
```
```text
hello
world
7
0
8
```

`substr` clamps a start past the end to empty and never panics on an oversized
length. The byte twins keep their codepoint counterparts' base conventions:
`byte_pos`/`byte_lastpos` are 1-based with `0` = not found (like `pos`/`lastpos`),
while `byte_index_of` follows the `index_of` convention (0-based, `-1` when not
found). Watch the arg order: `index_of`/`byte_index_of` take
`(haystack, needle)`, `pos`/`byte_pos` take `(needle, haystack)`.

## Case, search, edit

```mix
print(upper("hello"))
print(lower("HELLO"))
print(contains("hello", "ell"))
print(starts_with("hello", "he"))
print(ends_with("hello", "lo"))
print(replace("aaa", "a", "b"))       -- replaces ALL occurrences
```
```text
HELLO
hello
true
true
true
bbb
```

`contains` also works on a list (membership, not substring):

```mix
print(contains([1,2,3], 2))
```
```text
true
```

> **Match ops are byte-exact** — `contains`/`starts_with`/`ends_with`/`split`/`join`/
> `replace`/`template` do **no** Unicode normalization and **no** case-folding. A
> precomposed `é` (U+00E9) will not match a decomposed `e`+`◌́`. Normalize first if
> you need NFC-insensitive matching.

`upper`/`lower` do full Unicode case mapping (`upper("café")` → `"CAFÉ"`); the
byte-exact rule is about *matching*, not casing. For word extraction there are the
ARexx-flavoured `words($s)` (count whitespace-delimited words) and `word($s, n)`
(Nth word, 1-based); for pattern matching see [regex](regex.md).

### Editing a file? Use `replace_must` (0.90.0)

`replace()` returns the subject **unchanged** when the needle is absent. That is
the right contract for a transform and the wrong one for an *edit*: in the
read-modify-write idiom a missed needle writes the input straight back and reports
success.

```mix
$s = read_file($p)
write_file($p, replace_must($s, "old", "new", {count: 1, path: $p}))
```

`replace_must(s, old, new[, {count, path}])` raises `NEEDLE_ABSENT` when `old` does
not occur, and `NEEDLE_COUNT` when `count` is given and the number of occurrences
differs — so an edit that was meant to hit one site and would have rewritten two
fails instead of shipping. `path` only names the file in the message, which is most
of the diagnosis when the edit runs in a loop over several files.
`re_replace_must(s, pattern, replacement[, {count, path}])` is the regex twin.

`replace()` and `re_replace()` are unchanged — `mix lint` flags the unguarded
write-back chain as [MIX-D3014](lint.md).

## Ordering and equality

The comparison operators `<` `>` `<=` `>=` pick their mode from **both** operands:

1. If both coerce to numbers — real numbers, or numeric strings like `"5"` — the comparison is **numeric**. So `"5" < "10"` is `true` (not a bash-style string surprise).
2. Otherwise, if both are strings, the comparison is **lexicographic by codepoint**: `"apple" < "banana"`, `"Z" < "a"` (uppercase sorts before lowercase), and the classic range test `$ch >= "a" and $ch <= "z"` all work. `"5" < "abc"` is a string-vs-string compare (lexicographic → `true`).
3. A number against a **non-numeric** string is a runtime error, not a silent coercion.

```mix
print("5" < "10")     -- both numeric strings → numeric compare
print("apple" < "banana")
print("Z" < "a")      -- codepoint order: U+005A < U+0061
```
```text
true
true
true
```

```mix
print(5 < "abc")
```
```text
Runtime error at line 1: cannot compare 'abc' as number
```

`==`/`!=` never error: a number and a numeric string compare **equal by value**
(`"5" == 5` is `true`), but two strings compare as text (`"5" == "05"` is
`false`, `"abc" == 5` is `false`). Full operator detail in
[operators](operators.md).

## Split, join, slice

`split` defaults to a space delimiter; `join` to a space separator:

```mix
$parts = split("a,b,c", ",")
print(join($parts, " | "))
print(length(split("one two three")))   -- default delim = space
```
```text
a | b | c
3
```

For substring-by-position use `substr`/`grapheme_substr`; for a sublist use `slice`
(0-based, half-open `[start, end)`, see [builtins](builtins.md)):

```mix
print(join(slice([10,20,30,40], 1, 3), ","))
```
```text
20,30
```

## The delimiter family — `before`/`after`/`split_once` (0.63.0)

The helpers a script reaches for on line 3, replacing every
`substr($s, pos(..) ± n)` computation. All subject-first. **Contract:**
absent delimiter → `nil` (never `""` and never the whole string — `""` is
a *real* result, the delimiter at the edge); empty delimiter raises.

```mix
print(after("key=value", "="))          -- value
print(before("key=value", "="))         -- key
print(after_last("/a/b/base.txt", "/")) -- base.txt   (basename)
print(after_last("base.txt", "."))      -- txt        (extension)
$kv = split_once("k=v=w", "=")          -- [head, tail] at the FIRST =
print($kv[0] .. " / " .. $kv[1])        -- k / v=w    (rsplit_once: LAST)
print(between("a <b> c", "<", ">"))     -- b
print(after("no-equals", "=") or "dflt")-- dflt  (nil-coalesce a default)
```

`before_last` mirrors `before` at the last occurrence. Absence is `nil`,
so `if after($s, "=") == nil` is the "not found" test — an empty capture
and a missing delimiter never blur.

**Prefix/suffix forms** return the subject **unchanged** when there is
nothing to strip ("nothing to do" is an answer, not a failure):
`strip_prefix(s, p)`, `strip_suffix(s, x)`, `replace_first(s, old, new)`
(first occurrence only; empty `old` mirrors `replace()`), and
`count_of(s, needle)` (non-overlapping; 0 for an empty needle).

**Lines, fields, chars** (0.63.0 — `lines`/`chars` were prelude
functions, now native): `lines(s)` splits on `\n`, strips one trailing
`\r` per line (CRLF-safe) and drops exactly one trailing empty element
(the final newline) — `lines("a\nb\n")` is `["a", "b"]`, `lines("")` is
`[]`, `"a\n\n"` keeps its real empty line. `fields(s)` splits on
whitespace *runs* like awk (no empties; `word(s, n)` is the 1-based
single-field form). `chars(s)` yields codepoints as 1-char strings.
`last_index_of(s, v)` is the 0-based codepoint twin of `lastpos()` (args
reversed, -1 when absent — same condition warning as `index_of`).

## Trim, pad, repeat, reverse

`trim`/`strip` take an optional **charset** — a *set* of codepoints to
strip (PHP-style), honoured since 0.63.0 (before that the second argument
was silently ignored — the call "worked" and did nothing). One-sided:
`ltrim`/`rtrim`, same optional charset:

```mix
print(trim("xxhelloxx", "x"))     -- hello
print(ltrim("zyxabczyx", "xyz"))  -- abczyx
print(rtrim("zyxabczyx", "xyz"))  -- zyxabc
```

```mix
print("[" .. trim("  hi  ") .. "]")    -- strip is an alias for trim
print("[" .. lpad("7", 4) .. "]")      -- right-align in width 4
print("[" .. rpad("7", 4) .. "]")      -- left-align in width 4
print(repeat("ab", 3))
print(reverse("hello"))
```
```text
[hi]
[   7]
[7   ]
ababab
olleh
```

`lpad`/`rpad` pad by **codepoint count**, which misaligns a column of CJK/emoji (a
wide glyph counts as 1 there but renders as 2 cells). The `%Ns` width of
[`fmt`/`printf`](builtins.md) pads by codepoints too (`fmt("%6s", "日本")` adds
four spaces, not two). Use `lpad_w`/`rpad_w` to pad by **display cells**:

```mix
print("[" .. rpad("日本", 6) .. "]")    -- codepoint pad: 2 chars → +4 spaces
print("[" .. rpad_w("日本", 6) .. "]")  -- cell pad: width 4 → +2 spaces
```
```text
[日本    ]
[日本  ]
```

### Padding with something other than a space

All four padders take an **optional third argument: the fill character** (v0.54.0).
It defaults to a space, so existing two-argument calls are unchanged.

```mix
print(lpad("7", 4, "0"))        -- zero-pad a number-as-text
print(rpad("Name", 10, "."))    -- dot leader
print(lpad_w("日本", 6, "."))   -- fill by display cells
```
```text
0007
Name......
..日本
```

The fill must be **exactly one character**, and for the `_w` variants exactly one
**display cell** — a wide fill would overshoot the target by a cell per pad
character, which defeats the point of padding by width. Both raise a runtime
error naming the offending value rather than silently mis-aligning:

```text
lpad: fill must be exactly one character, got "ab" (2 chars)
lpad_w: fill must be exactly 1 display cell wide, got '漢' (2 cells)
```

Padding is **saturating** — content already at or beyond the width is returned
unchanged, never truncated.

To zero-pad a **number**, prefer `fmt`'s `%0Nd`, which keeps the sign to the left
of the zeros (`fmt("%05d", -42)` → `-0042`). Reach for `lpad(s, n, "0")` when the
value is already a string, since `%0Ns` is undefined for strings in C and is
ignored here.

`repeat`/`lpad`/`rpad` cap a result at 256 MiB and raise a normal runtime error
rather than OOM on a hostile count/width. Since 0.59.0 the cap bounds the
**bytes the padding would build** — a multibyte fill counts at its UTF-8 width
and the original string is included in the sum — so the error fires before the
allocation it names, not after a 4-byte fill has built four times the
advertised limit. (For a width within the cap, a string already at or past that width passes
through unchanged, whatever its size — the cap meters what padding
constructs, not what you already had. A width beyond the cap errors before
anything is examined.)

Every numeric position/count/width argument in this page uses Mix numeric
coercion: a number or numeric string works (`left("abcdef", "2")` is `ab`, as
is `left("abcdef", 2)`). A supplied value that cannot be parsed as a number now
raises `TYPE_MISMATCH`, naming the builtin, 1-based argument position, value,
and type. It never silently becomes zero or the omitted default. This applies
to `left`, `right`, `substr`, `grapheme_substr`, `repeat`, `lpad`, `rpad`,
`lpad_w`, `rpad_w`, `word`, `word_wrap`, and `word_wrap_w`:

```mix
print(substr("abcdef", "2x"))
```

```text
TYPE_MISMATCH: substr(): argument 2 must be a number, got "2x" (string)
```

## sprintf — C-compatible formatting (v0.71.0)

`fmt()` is the Mix-native formatter for everyday alignment; **`sprintf()`**
exists for the byte-exact cases: generating fixtures, protocol fields, or
log lines that a C/Rust program will compare byte-for-byte.

```
sprintf(fmt, ...args) -> string
```

- **Conversions:** `%d %i %u %o %x %X %f %F %e %E %g %G %s %c %%`.
- **Flags** `- + 0 #` and space; **width** and **precision**, both taking
  `*` (from the next argument; a negative `*` width left-justifies, a
  negative `*` precision is treated as omitted — C's rules).
- **Length modifiers** (`hh h l ll L q j z t`) are parsed and **ignored**:
  Mix numbers are one type, and the integer conversions behave as the
  64-bit (`ll`) forms — `sprintf("%u", -1)` is `18446744073709551615`, the
  64-bit two's-complement, and a C reference must use `%llu` to match.
- **Float output matches glibc `printf` byte-for-byte** (fixture-tested:
  `%.0f` of `2.5` is `2` and of `3.5` is `4` — both round the exact binary
  value ties-to-even; `%g` picks its style from the *rounded* value, so
  `%.3g` of `999999.5` is `1e+06`). `inf`/`nan` come out as glibc prints
  them: lowercase for `%f %e %g`, upper for `%F %E %G`, space-padded even
  under the `0` flag.
- Integer conversions require a **whole number** in the exact-integer
  range (±2⁵³−1 — Mix numbers are f64, so a positive value C could print
  as a full u64 is unreachable above that); anything else raises rather
  than truncating. Unknown conversions and missing arguments raise too,
  and POSIX positional arguments (`%1$d`) are not supported — the `$`
  surfaces as an unknown-conversion error.
- **Lint MIX-W2311** covers the surplus side, which the runtime accepts:
  a direct `fmt()`/`sprintf()` call whose template is a string literal
  that parses cleanly, but whose argument list is longer than the
  template consumes, warns — `fmt("%s", 1, 2)` provides two operands for
  one placeholder and the extra is silently ignored. `%%` consumes
  nothing; a `*` width (and a `.*` precision here) consumes one operand
  each, so `sprintf("%*.*f", 4, 2, 1.5)` is exact. Invalid or dynamic
  templates, deficits, and calls a user function, variable or `address`
  block could shadow stay silent.

Two documented divergences, both about Unicode: `%s` pads by **codepoints**
(C pads by bytes — identical for the ASCII output of numeric conversions,
which is what the parity claim covers), and `%.Ns` truncates to at most N
**bytes without splitting a codepoint**, so the result is always valid
UTF-8. `%c` takes a Unicode scalar value, not a C `int` cast to a byte.

```mix
print(sprintf("%08.3f|%+d|%#llx", 3.14159, 42, 255))   -- 0003.142|+42|0xff
print(sprintf("%e", 12345.6789))                       -- 1.234568e+04
print(sprintf("%.*f", 2, 2.5))                         -- 2.50
```

## Templates and wrapping

`template` substitutes single-brace `{key}` placeholders from a map (distinct from
`${...}` interpolation, and from the `%s`/`%d` of [`fmt`/`printf`](builtins.md)):

```mix
$m = { name: "Ada", role: "dev" }
print(template("{name} is a {role}", $m))
```
```text
Ada is a dev
```

`template` is **single-pass**: a substituted value is emitted verbatim and never
rescanned, so untrusted data containing `{other_key}` cannot inject a second
substitution (`template("{a}", {a: "{b}", b: "X"})` → `{b}`), and the output does
not depend on map iteration order. A placeholder with no matching key stays
literal (`template("{missing}", {})` → `{missing}`).

`word_wrap` greedily wraps to a codepoint budget (`word_wrap_w` to a display-cell
budget):

```mix
print(word_wrap("the quick brown fox jumps", 10))
```
```text
the quick
brown fox
jumps
```

## Quoting for shells and SQL

When a string must cross into a shell command or a SQL literal, escape it natively
rather than hand-rolling quotes:

```mix
print(shell_quote("it's a test"))     -- safe single-quote wrap for POSIX sh
print(sql_quote("O'Brien"))           -- doubles ' (MySQL/MariaDB-safe)
```
```text
'it'\''s a test'
O''Brien
```

`sql_quote` doubles `'` **and escapes `\`** (`sql_quote("a\\b")` → `a\\b`) and
strips NUL bytes — MySQL/MariaDB-safe. It is also safe for SQLite, where a
literal backslash arrives doubled; for exact bytes use `sqlexec` parameter binds
instead of quoting (see [system](system.md)) — binds are typed (nil → NULL,
whole number → INTEGER, string → TEXT, bytes → BLOB), so the value never passes
through a quoted literal at all.

`sanitize` makes untrusted bytes safe for a one-line diagnostic — collapsing line
breaks to spaces and replacing C0/C1 controls and Trojan-Source bidi/zero-width
characters with `?`:

```mix
print(sanitize("line1\nline2\ttab"))
```
```text
line1 line2?tab
```

For HTML output use `html_escape`; for Bus/SSE framing see [Bus messaging](bus.md)
and the [Datastar](https://data-star.dev) `ds_*` builtins. To embed a value as
re-parseable Mix source, use `data_encode` (see [builtins](builtins.md)).

## Mail headers — `rfc2047_decode` / `rfc2047_encode` (0.67.0)

A mail header may only carry ASCII, so anything else travels as RFC 2047
**encoded-words**: `=?charset?B-or-Q?data?=`. A `Subject:` read raw comes back
as `=?utf-8?B?Q2Fmw6k=?=`, which is exactly the unreadable output a report
exists to prevent.

```
rfc2047_decode(header)             -> plain string
rfc2047_encode(text[, {encoding}]) -> header value ("B" default, or "Q")
```

```mix
print(rfc2047_decode("=?utf-8?B?SGVsbG8gV29ybGQ=?="))
print(rfc2047_decode("=?ISO-8859-1?Q?caf=E9?="))
print(rfc2047_decode("Re: =?utf-8?B?dGVzdA==?= (fwd)"))
print(rfc2047_encode("plain ascii subject"))
print(rfc2047_encode("café"))
```
```text
Hello World
café
Re: test (fwd)
plain ascii subject
=?UTF-8?B?Y2Fmw6k=?=
```

**Decoding.** The charset token is honoured — `utf-8`, `us-ascii` and
`iso-8859-1` (with the usual aliases, and RFC 2231's `*language` suffix
stripped) decode properly; **any other charset falls back to UTF-8 with U+FFFD
substitution**, so a `koi8-r` header is legible-ish rather than exact. Adjacent
encoded-words are joined at the **byte** level and the whitespace between them
is dropped, per RFC 2047 §6.2 — which is not cosmetic: a long non-ASCII subject
is folded by splitting it into several words, and a multi-byte character
straddling that split only survives if the bytes are joined before decoding.
Anything that is not a well-formed encoded-word is passed through **literally**,
never dropped; a visible `=?utf-8?X?…?=` beats a silently lost subject line.

**Encoding.** Plain ASCII is returned **unchanged** (§5 permits an encoded-word
only where one is needed), unless it contains a literal `=?`, which would
otherwise be misread by the receiving decoder. Output is always UTF-8 — the
right answer for modern mail, and not a choice worth offering. `B` (base64) is
the default; `{encoding: "Q"}` is more readable when the text is mostly ASCII.
Each emitted word stays within §2's 75-character limit and splits on
**character** boundaries, because an encoded-word must be independently
decodable — a 4-byte emoji may never straddle two words.

This pair was promoted from a deployed nospam report script, with **three**
changes the original could not justify:

1. it decoded every charset as UTF-8-lossy — right for the one mailbox it
   served, wrong in general;
2. it joined adjacent words as decoded *strings* rather than bytes, so a
   character split across the fold became two replacement characters;
3. on a malformed word it either emitted the raw payload with the wrapper
   stripped (presenting undecoded bytes as though they had been decoded) or
   abandoned the whole scan, leaving every later word in the header encoded.

Everything the original got right is unchanged, including the false-terminator
handling that is the reason this was promoted rather than rewritten. All three
changes are pinned by tests.

## Gotchas recap

- `"double"` interpolates **only** `${...}`; a bare `$name` is literal text.
- `'single'` is fully raw — nothing interpolates, `~` does not expand.
- `$(...)` is literal inside a Mix string (use `run`/`run_rc` + `..` to splice output) — but it *does* substitute in a heredoc body, as a standalone expression, and it passes through to the target shell in a `run`/`ssh_run` command string.
- Concatenate with `..`, never `+` or `.`.
- `length`/`pos`/`substr`/`reverse` are **codepoints**; use `byte_*` for bytes, `grapheme_*` for emoji/combining, `display_width`/`*_w` for terminal columns. `length`/`len` on a list/map is the element count.
- `pos`/`lastpos`/`byte_pos`/`byte_lastpos` are **1-based, 0 = not found**; `substr`/arrays/`index_of`/`byte_index_of`/`slice` are **0-based** (`index_of` returns `-1` when not found).
- `replace` replaces **all** occurrences; match ops are byte-exact (no case-fold, no normalization).
- `<`/`>` compare **numerically** when both sides coerce to numbers (`"5" < "10"` is `true`), **lexicographically by codepoint** when both are strings; a number vs a non-numeric string is a runtime error.
- `lpad`/`rpad`/`%Ns` pad by codepoints — `lpad_w`/`rpad_w` for cell-exact columns.
- `${X}` unbound in scope **and** env is a runtime error (like a bare `$X`); a nil *value* still renders `nil`. Supply a fallback with `${X ?? default}` (nil-only) or `${X ?: default}` (any falsy).

## See also

- [numbers](numbers.md) — the f64 numeric type, `+`/`%`/`**`, radix literals
- [operators](operators.md) — `..` concat, `==`/`<` ordering, `??` nil-coalesce
- [regex](regex.md) — `re_match`/`re_find`/`re_replace`/`re_split`/`grep_lines`
- [syntax](syntax.md) — the lexer, comments, and the shell/Mix classifier
- [functions](functions.md) — lambdas and HOFs for transforming string lists
- [builtins index](builtins.md) — the full string/byte/grapheme/`_w` builtin set
- [running commands](system.md) — `run`/`run_rc` for splicing command output
- [shell mode](shell-mode.md) — where `$(...)` *is* command substitution
- [Bus messaging](bus.md) — `send`/`emit`, `ds_*` SSE framing, `html_escape`
- `mix help` — list all builtins · `mix what NAME` — describe one (e.g. `mix what grapheme_substr`)

---

<!-- page: https://mixos.dev/mix/syntax/ (source: https://mixos.dev/mix/syntax.md) -->

# syntax — lexical structure & the shell/Mix classifier

How Mix reads source: what a token is, how statements end, and the one rule that
trips up everyone coming from bash or Python — **when a line is run as Mix code
versus dispatched to the shell**. Verified against the live binary (the version
stamp is checked by `cargo test -p system --test man_pages`; ask
`mix --version` for the number).

> Mental model: Mix is a Bus-native shell where every variable carries a `$`
> sigil, concatenation is `..`, and statements are separated by a **newline or
> `;`**. At a `mix -c` one-liner or the interactive REPL, a *shell-first
> classifier* decides per input whether to evaluate it as Mix or hand it to the
> shell. That single decision explains why `$x = 1` works but `x = 1` runs a
> command called `x`.

## The five things to get right first

1. **Every variable has a `$` sigil** — `$x = 1`, never `x = 1`. A bare `x = 1` is read as a shell command (run the program `x` with args `=` and `1`).
2. **Concatenation is `..`** — `"a" .. $x`, never `.` (that's field access). `+` happens to also join strings today, but `..` is the canonical form.
3. **Statements end at a newline or `;`.** Newlines are the readable script style; `;` is the compact `mix -c` / generated-source form.
4. **`--` and `#` start a line comment.** No block comments (`/* */`).
5. **Blocks close with `end`.** No `do` keyword.

```mix
$x = 1
print($x)
```
```text
1
```

```mix
x = 1
```
```text
mix: x: No such file or directory (os error 2)
```

The second snippet isn't a Mix error at all — the classifier saw a bareword head
(`x`) and dispatched the line to the shell, which tried to exec a program named
`x`. See [the classifier](#the-shellmix-classifier) below.

## Comments

Two line-comment forms, identical behaviour: `--` (ARexx/Lua/Haskell flavour) and
`#` (shell flavour). Both run to the end of the line. There are **no block
comments** — `/* ... */` is not recognised.

Comments own the rest of their **physical line**. A semicolon inside a comment
does not resume execution: `print(1); -- note; print(2)` prints only `1`.

```mix
-- a full-line comment
$y = 2  -- a trailing comment
# also a comment, shell-style
print($y)
```
```text
2
```

Non-ASCII inside a comment is fine for the lexer, but keep comments ASCII as a
house convention.

> **`mix -c` gotcha — a leading comment line swallows the whole input.** The
> classifier trims the input and, if it *starts* with `#` or `--`, treats the
> entire `-c` argument as an empty (comment-only) line — it does **not** strip
> the first line and run the rest. So this prints nothing:
>
```text
$ mix -c '# header
print(42)'
(no output)
```
>
> Put the comment *after* the first real statement, or run from a file / stdin
> (`mix script.mix`, `mix -`), where the input is parsed as source rather than
> classified as one `-c` command. A leading comment in a script is normal.

## Statement separators — newline and `;`

This section is the authoritative `;` contract for **executable Mix**. A
semicolon is a real lexer token and the parser accepts it as a statement
separator only where a complete statement may end. It is not text substitution
for a newline and it is not an expression operator.

Use a physical newline for normal script layout and `;` when several complete
statements genuinely need to share a line — most often in `mix -c`, the REPL,
generated source, or remote Mix source:

```mix
$a = 1; $b = 2; print($a + $b)
```
```text
3
```

### Where `;` is legal

| Context | Legal? | Example / rule |
|---|---:|---|
| between top-level statements | yes | `$a = 1; print($a)` |
| after a block header or clause | yes | `if true then; print(1); else; print(0); end` |
| between statements in a function, loop, `try`, handler, or `address` body | yes | `function f(); print(1); return 2; end` |
| leading, trailing, or repeated at a statement boundary | yes, no-op | `; print(1);;` |
| inside strings, heredoc bodies, or comments | literal text | `print("a;b")`; a comment still owns its physical line |
| inside an ordinary expression container | no | calls, parentheses, lists, and maps use one expression or `,`, not `;` |
| in strict-data (`data_parse`, `load_data`, config files) | no | use newline or `,`; see [data](data.md) |

Semicolons remain visible inside `()` / `[]` / `{}`, so a nested construct with
a real statement body — an expression-position `if` or function literal — may
use them:

```mix
print(if true then; $x = 1; $x + 1; else; 0; end)  -- valid: prints 2
print((function($n); return $n + 1; end)(4))       -- valid: prints 5

print(1; 2)             -- parse error: call arguments need `,`
print((1; 2))           -- parse error: parentheses hold one expression
print([1; 2])           -- parse error: list items need `,`
print({a: 1; b: 2})     -- parse error: map entries need `,`
```

The diagnostic for the rejected forms says that `;` separates Mix statements
only. In a script/stdin source, or with a Mix-keyword head such as `print` under
`-c`/the REPL, parsing finishes before evaluation, so nothing before the error
runs. A malformed **`$`-led** `-c`/REPL input can instead trigger the historical
whole-input shell fallback; use the keyword-led forms above when checking a
diagnostic. The classifier section later on this page explains that fallback.

### Precedence and hard-boundary rule

As a statement separator, `;` binds looser than Mix statement chains and ends
the complete construct to its left:

```mix
print("a") && print("b"); print("c")
-- parsed as: (print("a") && print("b")); print("c")

print("x") | tr x y; print("z") -- `;` also ends the raw external pipeline tail
```

There is no general “pipeline before `&&`/`||`” rule in executable Mix. After a
Mix `|`, everything through newline, `;`, or end-of-input is the raw external
command tail; an `&&`/`||` there belongs to that external shell. In the other
direction, a Mix statement-chain operand may itself start a pipeline:

```mix
print("a") && print("b") | cat; print("c")
-- Mix chain first; the right operand's external tail is `cat`; `;` then starts `c`
```

Unlike a physical newline, a semicolon is a **hard** chain boundary. Mix permits
an existing `&&` / `||` chain to continue across a newline on either side of the
operator, but never across `;`:

```mix
print("a")
&& print("b")            -- valid newline continuation

print("a"); && print("b") -- parse error
print("a") &&; print("b") -- parse error
```

The lexer also suppresses newlines — but deliberately retains semicolon tokens —
inside ordinary grouping, as described below.

### Mix versus shell meaning

The separator does **not** mix the two languages. A line is classified once and
the whole line must be valid Mix or valid shell. Use `sh`, `run_argv`, or
`run_rc` for an external operation inside a Mix sequence; `print(1); echo hi`
is a Mix parse error, not “run one Mix statement then one shell command”. On an
external-command line, `;` keeps its shell command-list meaning:

```text
$ mix -c 'echo one; echo two'
one
two
```

The distinction matters for empty pieces: leading/trailing/repeated semicolons
are harmless only after the input has been classified as Mix. Shell-dispatch
accepts a single trailing `;`, but rejects a repeated/interior empty piece such
as `echo a;; echo b`. A leading `; echo x` is tried as Mix first and surfaces a
Mix parse error rather than a shell empty-piece error. See [shell mode](shell-mode.md)
for command-list classification, unknown-command preservation, and the
whole-file-first `source` caveat.

### Newlines are suppressed inside `(` `[` `{`

While the lexer is inside an open paren, bracket, or brace, newlines are
swallowed — so list/map literals and call arguments wrap freely across lines
without a continuation marker:

```mix
$nums = [
  1,
  2,
  3
]
print(length($nums))
```

```text
3
```

### Explicit line continuation: `\` at end of line

Outside a string or heredoc body, end a physical line with a backslash to
continue onto the next physical line. This works for Mix expressions and for
shell-dispatch commands in script files, `mix -c`, and the REPL:

```mix
$total = 1 + \
2 + \
3
print($total)
```
```text
6
```

```text
$ mix -c 'echo one \
two'
one two
```

The splice happens **before shell/Mix classification**, so the classifier sees
one complete logical line. This matters for operator-shaped command arguments:
`ls -d \` followed by `/tmp` stays an `ls` command instead of becoming the Mix
arithmetic expression `ls - d / tmp`.

Trailing backslashes are counted. Odd means continuation: the final backslash
and physical newline are removed, while preceding even pairs remain for the
normal parser. Thus `\` continues, `\\` is a literal backslash, and `\\\` is
one literal backslash plus continuation.

A continuation marker at EOF is typed incomplete input. The REPL retains its
accumulator; a file or `-c` invocation exits non-zero. Backslashes inside Mix
single/double-quoted strings and heredoc bodies are not continuation markers,
so Windows-style strings such as `"C:\\path"` and command text passed through
`run` or `sh` keep their existing shell-owned escaping.

### Concat continuation: trailing `..`

The concat operator also continues its expression when `..` ends a physical
line. Blank lines and comment-only lines may appear before the right operand:

```mix
$message = "a long prefix: " .. -- explain the next fragment

  "middle" ..
  " and suffix"
print($message)
```

This is deliberately **trailing-only**. A `..` at the start of a line does not
reattach to the previous statement, and `../path` keeps its existing relative
path meaning in shell commands and in `source` / `include`. A semicolon remains
a hard statement boundary. Use trailing `\` for general continuation after any
other operator; no other binary operator gains this newline rule.

## Blocks close with `end` — no `do`

Every compound form (`if`, `for`, `while`, `function`/`fn`, `on`, `try`) is closed
by `end`. There is **no `do` keyword**: since 0.98.0 `do` is reserved and
**refused with a parse error** — `unexpected do — Mix has no do keyword;
blocks close with end`. Before 0.98.0 a stray `do` was silently absorbed
as a bare-identifier no-op — the bash reflex ran, and meant nothing. (A few
legacy terminators — `next` for loops, `done` for `while`/`loop`/`on` — still
parse with a deprecation warning; `if` and `function`/`fn` accept **only** `end`.
Prefer `end` everywhere.) Full grammar of each block lives in
[control flow](control-flow.md) and [functions](functions.md).

```mix
$n = 3
if $n > 0 then
  print("positive")
end
```
```text
positive
```

## Tokens the lexer produces

### Numbers — f64, with radix literals

Mix has a single numeric type (f64). Decimal, plus `0x` hex / `0o` octal / `0b`
binary integer literals (sugar for the f64 value — handy for file modes and
bitmasks). Underscores are allowed as digit separators. Scientific notation is
accepted: `[eE][+-]?digits` — `1e6`, `1.5e3`, `2e-3`, `1E3`. The `e`/`E` is only
consumed when a digit follows, so the Euler builtin in `2 * e()` is never eaten.

```mix
print(0o755)
print(0xFF)
print(0b101)
print(1e6)
print(2e-3)
```
```text
493
255
5
1000000
0.002
```

A **bare leading-zero integer is a lex error** — `0755` is rejected so a file
mode can't silently become decimal `755`. The error is surfaced, not masked:

```mix
0755
```
```text
Lexer error at line 1:1: ambiguous leading-zero number '0755' — use a 0o (octal) / 0x (hex) / 0b (binary) prefix, or drop the leading zero(s) for decimal
```

Plain `0`, and genuine fractions like `0.5`, are unaffected, and `0e5` is a
valid `0` — but `07e2` still errors (the leading-zero check runs before the
exponent). This is a *Mix number-literal* hazard only: inside a shell-out the
arg is a string, so `run("install -m 0755 a b")` is fine. Full numeric
semantics live in [numbers](numbers.md).

### Strings — `'raw'` vs `"interpolated"`

Two forms, bash-style. Full coverage in [strings](strings.md); the lexical facts:

- `'single'` is **fully raw** — no interpolation, no `~` expansion (only `\'` and `\\` escapes).
- `"double"` interpolates **`${name}`** (scope → env), expands a **leading `~`** to `$HOME`, and honours `\n \t \r \e \\ \" \$ \~` and `\u{XXXX}` escapes.
- In double quotes a **bare `$name` is literal text** (the opposite of bash), and **`$(...)` is literal** — the build-time-substitution footgun was removed.

```mix
$name = "Ada"
print("hi $name")
print("hi ${name}")
print('hi ${name}')
print("~/code")               -- a LEADING ~ expands to $HOME
print("home is ~/code")       -- a mid-string ~ stays literal
```
```text
hi $name
hi Ada
hi ${name}
/home/user/code
home is ~/code
```

### Variables — the `$` sigil

A variable token is `$` followed by `[A-Za-z0-9_]+`. Reading an **unbound** sigil
raises a runtime error (positional `$1`/`$2` script args are exempt):

```mix
print($undefined)
```
```text
Runtime error at line 1: undefined variable '$undefined'
```

### Operators & delimiters

```text
arithmetic   +  -  *  /  %  **            (** is power: 2 ** 10 -> 1024)
concat       ..                            ("a" .. $x)
compare      ==  !=  <  <=  >  >=  eq  ne  (eq/ne are keyword string-equality ops)
logical      and  or  not                  (keywords, not && / ! in expressions)
nil-coalesce ??                            ($x ?? "default")
ternary      ?  :                          ($n > 0 ? "pos" : "neg")
field/index  .  []                         ($m.key  /  $m["key"])
grouping     (  )   [  ]   {  }
statement    ;                              (hard statement boundary; see above)
misc         :  ,  =  ~                     (: in maps, = assignment, ~ path tilde)
```

`??` returns its right side when the left is `nil`:

```mix
$x = nil
print($x ?? "default")
```
```text
default
```

`**` is power; `..` is concat (not a range). A lone `?` is the ternary
`cond ? a : b` token (see [operators](operators.md) for precedence and the
if-expression form). A lone `&` is a lex error *with a hint*:

```mix
print(1 & 2)
```
```text
Lexer error at line 1:9: unexpected '&', did you mean '&&'?
```

### Heredocs — `<<TAG`

`<<TAG` opens a heredoc; the body runs to a line containing only `TAG`. Unlike a
double-quoted string, a heredoc body **does** interpolate `${var}` *and* run
`$(command)` substitution. See [strings](strings.md) for the full treatment.

### Keywords — reserved as identifiers, usable as names

Identifiers matching a keyword become that keyword token. The complete set is
printed by `mix keywords` and each resolves via `mix what NAME` — the binary
is the oracle, and the manual's table ([keywords](keywords.md)) is held to the
same lexer set by the build, so the list is never enumerated here where it
could rot.

Keywords **cannot** be function names or bare user identifiers:

```mix
function step($x) return $x end
```
```text
Parse error at line 1:10: expected identifier, got Step
```

But since 0.21 a keyword **is accepted anywhere it is unambiguously a NAME** —
the old "quote every reserved-word key" footgun is retired:

- **Bare map keys**: `{ label: 1, to: "x", on: true, parse: 2 }` parses.
- **Field access & assignment**: `$m.to`, `$r.label`, `$cfg.to = 1`. An assignment target may chain accessors freely since 0.33.0 — `$cfg.server.host = "x"`, `$m[$u]["k"] = 1`, `$l[0][1] = 9` (see `mix man collections`).
- **Strict-data `.conf.mix` keys**: a key named `to`/`in`/`on`/`label` needs no quoting.
- **`send`/`emit`/`address` kwargs**: `send maild mailbox.move to=$dest` parses (keyword + `=` is a named arg).
- **`parse … with` delimiter words**: `parse $s with $a to $b` uses the literal word `to` as the delimiter — EXCEPT the block/branch terminator set (`end` `else` `catch` `when` `otherwise` `done` `next`), which still ends an inline `parse` statement first.
- **Sigil variables were never restricted**: `$to`, `$label`, even `$fn` are ordinary variables — the lexer reads the name after `$` as a variable token, never a keyword.

```mix
$m = { label: 1, to: "x" }
print($m.to)
$m.label = 9
print($m.label)
```
```text
x
9
```

**The one exception is `fn`** — it lexes to the *same token* as `function`, so
the original spelling is unrecoverable and a bare `fn` key/field still errors.
Quote the key and use index access:

```mix
$m = { fn: 1 }
```
```text
Parse error at line 1:8: expected identifier, got Function
```

```mix
$m = { "fn": 1 }
print($m["fn"])
```
```text
1
```

### Parser nesting cap — depth 200

The parser caps recursive nesting (parens, deep `if` chains, nested maps/lists)
at **depth 200**, matching the evaluator's recursion cap — a pathological
`((((…` input gets a clean parse error, never a stack-overflow abort:

```text
$ mix -c 'print((((( … 205 deep … )))))'
Parse error at line 1:202: nesting too deep (limit 200)
```

### Asking the lexer: `mix_tokens()`

A tool that reads Mix source (a gate, a highlighter, a refactoring script)
asks Mix how the source tokenises instead of re-deriving the rules above.
`mix_tokens(source[, {comments: true}])` runs the real lexer and returns one
map per token, `{kind, text, line, col}`, in source order. Nothing is run.

```mix
for $t in mix_tokens('$x = "a ${b}" -- note', {comments: true})
  print($t.kind .. " " .. $t.text)
end
-- variable $x
-- operator =
-- interp_string "a ${b}"
-- comment -- note
```

- `kind` is `number`, `string` (a quoted literal), `word` (a bare word),
  `interp_string`, `heredoc`, `variable`, `command_sub`, `keyword`,
  `operator`, `punct`, `newline`, or `comment`. Comments come back only with
  `comments: true`; the parser never sees them.
- `text` is the exact source span: a string keeps its quotes, a heredoc
  runs from `<<TAG` to its terminator line (a `--` comment after the tag is
  part of it, not a separate `comment` token).
- `line` and `col` are 1-based, `col` counted in characters.
- Newlines inside `(`, `[` and `{` are not tokens, as above.
- Source that does not lex raises `MIX_SOURCE_LEX`, with `details.line` and
  `details.col`.

There is no AST builtin yet; for the handlers a file declares, read
`mix lint --json FILE` (its `handlers` list comes from the parsed AST).

## The shell/Mix classifier

At a `mix -c '<line>'` one-liner, the interactive REPL, and a mix login shell, Mix
follows the universal shell `-c` contract: it is **shell-first**. Each input is
classified once into one of: **Mix code**, **external command**, **empty**,
**incomplete**, or **parse-error**. The decision rests almost entirely on the
**first word** (after alias expansion and after skipping any leading `KEY=VALUE`
env prefixes).

The order of checks (from `shell.rs`):

1. **Empty / comment** — blank, or trimmed input starting with `#` or `--` → *empty*, runs nothing.
2. **`$`-led line** → **Mix** (with a shell-chain fallback). A line beginning with `$` is your variable work.
3. **First word is a Mix keyword** (`if for while loop function fn return select print eprint die try parse export alias break continue send address emit source sh label`) → **Mix**. Note `true`/`false`/`nil` are deliberately **not** in this list: as a line *head* they are shell commands, so a bare `false` at the prompt runs `/usr/bin/false` and exits **1** like every shell. The lexer still owns the literals inside Mix source (`$x = true`, `if $a == nil`); `nil` has no external binary, so it falls through to the Mix parse anyway.
4. **First word is a REPL shell builtin** (`cd pushd popd history exit which type unalias jobs fg bg mix`) → **external command**. (A plain foreground `cd` also works inside `&&`/`||`/`;` chains — `cd /tmp && pwd` is intercepted in-process; see [shell-mode](shell-mode.md).)
5. **First word is a tight-hyphenated command shape** (`mixos-comp`, `systemd-nspawn`, `weston-simple-dmabuf-egl`) → **external command**, whether or not it is on `$PATH`. This applies only to the statement head: it must start with an ASCII letter or `_`, contain a `-` with no surrounding whitespace, end with an ASCII letter/digit/`_`, and otherwise contain only ASCII letters/digits/`_`/`-`.
6. **First word is found on `$PATH` or is a path** (`/`, `./`, `~/…`) → **external command** (the shell-first principle). If the head is a real program but the command line is malformed (e.g. a bad redirect), the shell tokenizer's error is surfaced.
7. **Otherwise** → try to parse as **Mix**. If that parse succeeds it's Mix code; if it fails, a tie-break decides whether to surface the real Mix lex/parse error or report "command not found".

So the `$` sigil isn't decoration — it is what routes assignment to the Mix
evaluator instead of the shell:

```mix
$greeting = "hi there"
print($greeting)
```
```text
hi there
```

A parenthesized call is unambiguously Mix:

```mix
print(1 + 1)
```
```text
2
```

A bareword head that lives on `$PATH` is a shell command:

```text
$ mix -c 'echo hello from shell'
hello from shell
```

A tight hyphen keeps a command name whole before the Mix parser can read it as
subtraction. PATH membership is not required, so a typo still names the complete
command and exits 127:

```text
$ mix -c 'mixos-comp --nested'       # runs one command named mixos-comp
$ mix -c 'alpha-no-such-command'
mix: alpha-no-such-command: No such file or directory (os error 2)
```

The rule is deliberately statement-head-only. Whitespace or an expression
marker makes subtraction explicit, so all of these stay Mix:

```mix
a - b
$a - $b
1 - 2
$x-1
$a-$b
print(alpha-beta)       -- hyphen is inside a call, not the line head
```

Scope never changes this decision. Bare `alpha` is the string `"alpha"`, not a
reference to `$alpha`, so `alpha-beta` is a command even when `$alpha` is live.
Working variable subtraction is sigil-led (`$alpha-$beta`) and stays Mix.
Earlier exact head rules still win, so `mix not-a-command` remains the `mix`
meta-command with one hyphenated argument, not a command named
`not-a-command`.

There is one other position where a tight hyphen is read whole rather than as
subtraction, for the same reason: the TARGET of
[`send`/`emit`/`address`](bus.md), where hyphenated Bus service names
(`comp-nested`, `desktop-vt1`) are the norm. The shape there is this one plus
`.`, for dotted names. The name in an [`on`](bus.md) header follows the same
rule (0.113.1). It is a target-position rule, not a second
statement-head rule — everything in the list above is unaffected.

A `KEY=VALUE` prefix is skipped to find the real head — this is an *external
command* with an env var set for it:

```text
$ mix -c 'FOO=bar printenv FOO'
bar
```

### The tie-break: real Mix error vs "command not found"

After the tight-hyphen check, when the head is **not** on `$PATH` and the Mix
parse **fails**, Mix inspects the head's shape (only the first word — a later
character can't flip the verdict):

- A **bareword / path-like** head (`gti status`, `./build`, `foo:bar`) is a command target → reports the familiar command-not-found:

```text
$ mix -c 'gti status'
mix: gti: No such file or directory (os error 2)
```

- A **Mix-expression** head (a number, an operator, a `$`, or a call/index opener like `print(`) was meant as Mix → surfaces the real lex/parse error instead of masking it as a missing binary:

```text
$ mix -c 'print(0755)'
Lexer error at line 1:7: ambiguous leading-zero number '0755' — use a 0o (octal) / 0x (hex) / 0b (binary) prefix, or drop the leading zero(s) for decimal
```

This is why `print(0755)` tells you about the bad number rather than "No such
file `print(0755)`".

### Shell chaining vs Mix chaining

`&&` / `||` / `;` on an **external-command** line are shell operators (command
lists) — `true`/`false` heads are external commands, so `true && echo yes` and
`false || echo fallback` are plain shell chains. On a **Mix-keyword or `$`-led**
line, Mix's own grammar owns `&&` / `||` and `;`, so a valid Mix
chain stays Mix. A keyword/`$` head that *fails* Mix parse **and** is a genuine
multi-command shell list normally falls back to the shell (e.g.
`send oops ; echo hi` runs as a two-command shell list); definitive language
errors such as an assignment-led chain do not. Mix-keyword heads never
reach the command-not-found tie-break — they route through the Mix-then-shell
path, so a keyword-led line that fails both surfaces its Mix error
(`print(1); echo hi` reports a Mix parse error, not "command not found").

In a **Mix-classified** chain, an assignment cannot be any operand of `&&` or
`||`, whether first, middle or last. Since these are statement-chain operators,
accepting `$ok = $a.ok && $b.ok` would assign only `$a.ok`, while
`print("gate") && $ok = false || print("fallback")` can conceal the falsy
assignment behind a successful statement chain. Mix rejects every such shape as
`MIX-E1002`, and the line's own operands never run. Use `and` / `or` inside the
assigned expression for logical values, or split the assignment and command
chain into two statements if shell-style conditional execution was intended.
This applies to variable, field, index and nested-path assignments, to the
value-binding `export x = v`, `alias n = c` and terse `function f() = expr`
forms, and to all of them inside nested statement bodies. The forms that bind
no `=` expression stay legal operands: `alias` in its query and list forms, and
the block-bodied `function f() … end`.

Once a line is rejected it stays rejected: the error never falls back to shell
execution under `mix -c`, `source`, or `~/.mixrc` loading.

The qualifier "Mix-classified" is load-bearing. Two conditions must **both**
hold before a line carrying an assignment keeps shell semantics:

1. the classifier routes the line to the shell — either straight off the head
   (a path, a name on `PATH`, a shell builtin), or through one of the
   fallbacks that reconsider a line whose Mix parse failed and which is
   structurally a shell command list (a shell redirect; an env prefix in
   front of a keyword head like `export`); and
2. the Mix parse never reaches the assignment, so the typed
   assignment-chain error is never constructed.

Where both hold, the line behaves as `bash` does with it: `$x = false` is
three shell words whose `$x` expands, the failed `=` command is reported on
stderr, and `||` fires. That covers a path-shaped head (`/usr/bin/true && $x =
false || cmd` fails the Mix parse at `unexpected token Slash`), a shell
redirect (`zqxfoo > /dev/null; $x = false || cmd`), and an env prefix
(`FOO=bar export x = false || cmd`). Adding a redirect or an env prefix to an
otherwise-rejected line therefore turns it from a Mix error into a shell
command list — a consequence of where the parse gives out, not a guarantee
that assignments are honoured there.

Neither condition is sufficient alone. **Failing to parse as Mix does not by
itself send a line to the shell**: `print(1); echo hi` and `$x = (((` are both
parse errors that stay Mix errors, because a call head and a `$` head are
never routed to the shell. And a head being a shell command is not enough
either — `true && $x = false || cmd` has a head that is both a `PATH` binary
and a valid Mix literal, so the parse reaches the assignment and condition 2
fails. Once the parser has typed this error no head rule may reclassify the
line; the same holds for a tight-hyphenated head (`zqx-foo && …`) and for
`cd`. Those head rules still decide every line that does *not* carry a
rejected assignment, so `mixos-comp --nested` and `true && cmd` remain shell
as before. In a mixed sourced file, earlier shell lines execute normally
before a later line's rejection aborts the `source`.

One asymmetry predates this rule and is unchanged by it: the tight-hyphen head
discriminator exists only in the `mix -c`/REPL classifier. A `source`d file
reads `mixos-comp --nested` as the subtraction `"mixos" - "comp"` (the
option becomes a comment) and fails with `cannot use 'mixos' as number` —
whether the file parses whole or falls back to per-line handling. Give such a
head its full path (`/usr/bin/mixos-comp --nested`). Quoting it does **not**
work: `"mixos-comp" --nested` is a discarded string followed by a comment, so
the command silently never runs.

```mix
$ok = $a.ok and $b.ok       -- logical value: valid
$value = primary() ?? fallback() -- nil fallback: valid
$ok = $a.ok && $b.ok        -- parse error: assignment cannot be chained
print("gate") && $ok = false -- same parse error; nothing prints
```

```text
$ mix -c 'true && echo yes'
yes
$ mix -c 'false || echo fallback'
fallback
```

The full set of shell-dispatch syntax — pipes, redirects, `$(...)` command
substitution, brace expansion — is documented in [shell-mode](shell-mode.md).
Those apply only on a line the classifier routed to the shell; inside Mix *source*
they are inert (`$(...)` is literal text, `{a,b}` is a map/string) — except
inside a heredoc body, which does interpolate `$(...)`.

### Running scripts vs one-liners

- `mix script.mix` / `mix -` (stdin) — normally a whole-file Mix **script** (`echo hi` remains a Mix parse error). An explicitly continued command line is the narrow exception: its physical lines are assembled, then the complete logical line enters the strict classifier fallback.
- `mix -c '<line>'` — a one-liner: the **whole argument** is classified as one unit (hence the leading-comment gotcha above). Use `;` or real newlines for multiple Mix statements.
- `mix -i -c '<line>'` — interactive flavour: loads `~/.mixrc` (aliases + PATH) before classifying, so an aliased head resolves.

See [invocation](invocation.md) for the full launch matrix.

## See also

- [strings](strings.md) — `'raw'` vs `"interp"`, `${...}`, `~`, `\u{}`, heredocs
- [shell-mode](shell-mode.md) — shell-dispatch syntax: pipes, redirects, `$(...)`, brace expansion, `&&`/`||`/`;`
- [keywords](keywords.md) — what each reserved word does
- [numbers](numbers.md) — f64 semantics, radix and scientific literals
- [variables](variables.md) — sigils, scope, the unbound-read rule
- [control flow](control-flow.md) · [functions](functions.md) — the `end`-closed block forms
- [operators](operators.md) — precedence, ternary `? :`, comparison/ordering, `??`, `..`
- [invocation](invocation.md) — `mix file` / `-c` / `-` / `-i`
- [Bus messaging](bus.md) — the `send` / `emit` / `address` / `on` keywords
- [builtins index](builtins.md)

```text
mix keywords          list the reserved words
mix help              the full categorized builtin reference
mix what NAME         one-line description of a builtin or keyword
```

The source of truth is the lexer and parser in the public
[mix repo](https://github.com/markc/mixos/tree/main/libs/mix/src).

---

<!-- page: https://mixos.dev/mix/system/ (source: https://mixos.dev/mix/system.md) -->

# system — processes, environment & system primitives

The `system` builtin category — run external commands, inspect and mutate the
process/OS environment, and produce the small security/identity primitives
(quoting, hashing, UUIDs, passwords) that glue scripting to the outside world.
List them live with `mix builtins system`; one-line help for any single name
with `mix what NAME`.

Mix is an [Bus-native shell](bus.md): for **mesh** work prefer `send` / `emit`
over shelling out, and for **remote** work prefer [`ssh_run` / `ssh_must` /
`ssh_mix`](remote.md) over hand-built `ssh` command strings. In particular,
use the [`ssh_mix` + heredoc headline idiom](remote.md#headline-idiom-ssh_mix--heredoc)
for multi-line remote Mix or anything with nested quotes. This page covers
the *local* surface — launching processes and reading the machine. The category
listing also shows families documented on their own pages: the `ssh_*` builtins
([remote](remote.md)), `http_*` ([http](http.md)), the date/time helpers
([datetime](datetime.md)), `dns_lookup` ([builtins index](builtins.md); its
fuller sibling `dns_query` is covered below), and
`panic` ([errors](errors.md)).

## The structured-return win

The headline difference from bash: a command's result is **structured data**, not
`$?`-soup you re-parse. The local runners have explicit contracts:

```
run("cmd" [, {timeout: s}])        -> stdout STRING (trailing whitespace stripped); RAISES a catchable die on non-zero exit; /bin/sh
run_rc("cmd" [, {timeout: s}])     -> map {rc, stdout, stderr, timed_out, interrupted}; NEVER raises — branch on .rc; /bin/sh
run_argv(argv [, opts])            -> full process_result map; argv direct (NO shell), structured stdio routing, captured streams bounded, optional live tee; NEVER raises on command failure (v0.29.0; stream v0.47.0)
run_argv_must(argv [, opts])       -> stdout STRING (untrimmed); RAISES PROCESS_* structured errors with the result map in $err.details.result (v0.29.0)
run_pipeline(stages [, opts])      -> distinct pipeline_result map with per-stage outcomes; argv direct (NO shell); NEVER raises on ordinary pipeline failure
run_pipeline_must(stages [, opts]) -> final stdout STRING (untrimmed); RAISES PIPELINE_* with the pipeline_result in $err.details.result
run_stream(argv [, {env, clear_env, cwd}]) -> exit-code NUMBER; inherited stdio (live stream, no /bin/sh); opts v0.51.0
run_parallel(jobs [, {max, timeout}]) -> LIST of process_result maps in input order; runs many run_argv jobs concurrently with a bounded pool; one job's failure is DATA, never a raise (v0.82.0)
```

Pick by intent: **`run_argv` is the default for operational code** — injection-inert
argv, captured output, a real deadline, and one consistent result shape;
`run_argv_must` for a must-succeed step in argv form; `run`/`run_rc` when you
genuinely want `/bin/sh` semantics (pipes, globs) in the command string;
`run_stream` when the child must own the terminal (live progress, an interactive
prompt); `run_argv(..., {stream: true})` when output must be both visible live and
captured for the result. The capturing runners give the child `/dev/null`-style
stdin by default — a child that prompts gets instant EOF, so an interactive
command needs `run_stream` (or `run_argv`'s `stdin:` option for pre-supplied
input). Tee mode does not give the child a terminal or inherited stdin.

### run_argv — structured argv execution (v0.29.0)

`run_argv(argv, [opts])` runs an argv **list** directly (no shell anywhere),
routes stdin/stdout/stderr explicitly, enforces a deadline, and returns one
consistent map:

```mix
$r = run_argv(["pct", "start", "" .. $vmid], {timeout: 60})
if not $r.ok then
  eprint("start failed (exit " .. $r.exit_code .. "): " .. $r.stderr)
end
```

The result map always contains, in order: `ok` (true only for exit 0 with no
timeout/interrupt/signal/spawn error), `exit_code` (number, or `nil` when the
child didn't exit normally), `stdout`, `stderr` (lossy UTF-8, **untrimmed**),
`timed_out`, `interrupted`, `signal` (number or `nil`), `duration_ms`,
`stdout_truncated`, `stderr_truncated`, `utf8_lossy`, `error_code`, `error`
(both `nil` unless process setup/lifecycle itself failed — `PROCESS_STDIO` /
`PROCESS_SPAWN` / `PROCESS_IO` / `PROCESS_INTERNAL`; an ordinary non-zero exit is NOT an error
here and never raises).

Options (unknown keys are a hard `OPTION_INVALID` error):

- `timeout`: seconds, default **30**, `0` disables, fractional ok. The clock
  starts before file routes are opened, so it bounds setup as well as the child
  and capture drains. With `timeout: 0`, Mix waits for every captured stream to
  reach EOF; it does not abandon a reader merely because the direct child has
  exited. Note `run`/`run_rc` default to no deadline.
- `grace`: seconds, default **0**, fractional ok — what happens AT the
  deadline. `0` SIGKILLs the child's process group at once (the historic hard
  kill). A positive grace sends SIGTERM to the group, then waits until the
  **whole group** is gone or `grace` runs out, then SIGKILLs whatever is
  left. The grace covers the group, not only the child. In
  `sh -c "pg_dump app | gzip > f"`, `sh` may die at once, but `pg_dump` and
  `gzip` still get the full grace to finish. A descendant that ignores SIGTERM
  is killed at the grace deadline, never left running. The same escalation
  applies when the child has already exited but a descendant still holds a
  captured stream open at the deadline. The call can therefore take up to
  `timeout + grace`. The result still reports `timed_out: true`, and `signal`
  says how the child ended: `15` if it obeyed SIGTERM, `9` if it had to be
  killed. `grace` with `timeout: 0` raises
  `OPTION_INVALID`, because without a deadline it would do nothing.

  ```mix
  $r = run_argv(["pg_dump", "app"], {timeout: 600, grace: 10,
                                     stdout: {file: "/srv/app.sql"}})
  if $r.timed_out then
    eprint("dump cut off at the deadline (signal " .. $r.signal .. ")")
  end
  ```
- `stdin`: `nil` or `{null: true}` closes stdin; string/bytes/buffer supplies
  those bytes; `{file: path}` opens a local file for the child to read.
  `{inherit: true}` hands the child mix's own stdin, but **only when that
  stdin is not a terminal**, such as a pipe or a redirected file:

  ```mix
  -- producer | mix filter.mix
  $r = run_argv(["sort", "-u"], {stdin: {inherit: true}})
  ```

  When mix's stdin is a terminal, `{inherit: true}` raises `STDIN_TERMINAL`
  before anything spawns. run_argv puts its child in a new process group, so it
  is not the terminal's foreground group, and a terminal read would stop it
  with `SIGTTIN`. The call would then hang until its deadline. That is why
  there is no string form either: `stdin: "inherit"` is ordinary stdin data,
  the seven bytes `inherit`. Use `run_stream` when a child must own the
  terminal and its stdin. The same rule applies to stage 0 of `run_pipeline`
  and to `run_parallel` jobs. At most one `run_parallel` job may inherit
  stdin. Inheriting stdin makes sense for a script run as `mix script.mix`
  or `mix -`, where stdin is data. A bare REPL fed through a pipe reads its
  own input lines from that same stdin, so an inheriting child there would
  compete with the REPL for the lines of the script. Two or more raise `OPTION_INVALID` before any job runs, because
  concurrent readers of one pipe would race for its bytes. With
  `timeout: 0`, Mix also waits for a stdin-data writer to finish after the
  direct child exits. A descendant which retains the read end without consuming
  the data can therefore make the call wait indefinitely; that is the explicit
  no-deadline contract, and the writer is not detached as a leaked thread.
- `stdout`: `"capture"` (default), `"inherit"`, `"null"`, or
  `{file: path, append?: bool, mode?: number}`.
- `stderr`: `"capture"` (default), `"inherit"`, `"null"`, `"stdout"`
  (the `2>&1` merge), or the same file map.
- `cwd`, `env` (map overlaid on the inherited environment; keys
  `[A-Za-z_][A-Za-z0-9_]*`, values string/number/bool — a **nil** value
  REMOVES the variable from the child, the `env -u` form), and `clear_env`
  (bool — start from an empty environment) retain their existing meanings.
  Removals apply AFTER sets, so a key both set and unset ends unset.
  This also applies to `run_argv_must`, `run_parallel` jobs and each
  `run_pipeline` stage, including captured and routed output.
- `max_output`: bytes **per captured stream**, default 8 MiB, `0` disables.
  Excess is drained and discarded — the child is never blocked or killed by the
  cap, and the captured stream's truncation flag is set. The same flag is true
  when a deadline forces Mix to abandon a capture before EOF; in that case the
  returned bytes are the partial prefix received before abandonment.
- `stream`: bool, default `false`; when true, captured stdout chunks are also
  written to the parent's stdout and captured stderr chunks to the parent's
  stderr as they arrive, with a flush after each chunk. Streaming continues
  after `max_output` truncates capture. `stream: true` with
  `stdout: "inherit"` is rejected as `OPTION_INVALID`: the child already owns
  that stream, so teeing it is meaningless.

File output defaults to mode `0o600`, `append: false`, and therefore truncates an
existing file. `mode` is the creation mode (subject to the process umask). All
local file routes are opened **before** the child is spawned. An open/create
failure returns the normal failure-shaped process_result with `ok: false`,
`exit_code: nil`, and `error_code: "PROCESS_STDIO"`; it never raises from
`run_argv`, and the child is not run.

On Unix, an output FIFO is opened non-blocking during setup and restored to
blocking mode for the child. With no reader its open fails immediately with
`ENXIO`, reported as `PROCESS_STDIO` (not `timed_out`). An input FIFO retains
normal wait-for-writer open semantics, but that wait is performed by a bounded
worker. Mix anchors the FIFO inode with a descriptor before starting the worker;
reaching the call deadline wakes that same inode and reaps the worker even if
the pathname was concurrently renamed, unlinked, or replaced, then returns
`PROCESS_STDIO` with no child spawned. The wake open is non-blocking. Repeated
no-writer deadlines therefore do not accumulate blocked FIFO-open threads.
Pipeline routes use the same rules and return `PIPELINE_STDIO`.

Every route is opened first and a non-append route is truncated only once the
whole set has opened, so a bad `stderr` path cannot leave the `stdout` path's
existing file emptied on the way to reporting `PROCESS_STDIO`. (The guarantee
is "nothing is truncated until everything has opened", not a transaction: if the
truncation of one route then fails — an immutable file opens but will not
shorten — an already-truncated earlier route stays truncated.) A route pointing
at a symlink is followed, as `>` would; a route pointing at a non-regular target
(`/dev/null`, a character device) is written to, never truncated.

A non-captured stdout/stderr route always leaves that result field as `""` and
its `*_truncated` flag false. `max_output` does not apply to inherited, null, or
file-routed streams; Mix never silently caps them. With `stderr: "stdout"`, both
child streams go to the selected stdout destination, the combined bytes count
against stdout's cap when stdout is captured, and result `.stderr` stays `""`
with `stderr_truncated: false`.

With `stream: true`, a non-consuming parent stdout or stderr can block its drain
worker and delay return past `timeout`; the child is still killed at the
deadline. The tee-enabled check and parent-stream write are one critical
section. Before abandoning a reader Mix disables teeing under that same lock,
so an in-flight write finishes before return and later chunks from an escaped
descendant are suppressed. The captured prefix is returned with its truncation
flag set.

Kill discipline matches the whole family: the child runs in its own process
group; a timeout SIGKILLs the group immediately; Ctrl-C sends SIGTERM, waits up
to 2s, then SIGKILLs.

`run_argv_must(argv, [opts])` accepts the same options and routing rules, and
returns `$r.stdout` unchanged when `ok` and
neither stream was truncated; otherwise it raises a structured error
(`PROCESS_EXIT_NONZERO`, `PROCESS_TIMEOUT`, `PROCESS_SIGNAL`,
`PROCESS_INTERRUPTED`, `PROCESS_OUTPUT_LIMIT`, or the setup/lifecycle code,
including `PROCESS_STDIO`)
carrying the complete result map in `$err.details.result` — catch with
`catch $msg, $err` (see [errors](errors.md)).

### run_pipeline — structured shell-free pipelines

`run_pipeline(stages, [opts])` runs one or more argv stages directly and connects
stage `i` stdout to stage `i + 1` stdin. It does not invoke `/bin/sh`, parse a
command string, or reinterpret argv characters:

```mix
$r = run_pipeline([
  ["sha256sum", "/srv/image.raw"],
  ["cut", "-d ", "-f1"]
], {timeout: 60})
if $r.ok then
  print(trim($r.stdout))
else
  eprint("pipeline failed: " .. $r.stderr)
end
```

A stage is either an argv list or a map:

```mix
[
  {argv: ["producer"], cwd: "/srv/input", env: {MODE: "raw"}, stdin: {file: "/srv/request"}},
  {argv: ["filter"], clear_env: true, env: {LANG: "C"}, stderr: "inherit"},
  {argv: ["consumer"], stdout: {file: "/srv/result", mode: 0o600}}
]
```

Every stage map requires `argv`. All stages accept `cwd`, `env`, `clear_env`, and
`stderr`. Only the first accepts `stdin`; only the last accepts `stdout` (a
one-stage pipeline is both first and last). These values use the exact
[`run_argv`](#run_argv--structured-argv-execution-v0290) grammar and validation:
stdin data/null/file, stdout capture/inherit/null/file, and stderr
capture/inherit/null/stdout/file. A misplaced route, unknown key, or invalid
option raises `OPTION_INVALID` before spawning; malformed stages/argv raise
`TYPE_MISMATCH`. An empty pipeline is invalid. A one-stage pipeline has the same
execution and familiar result fields as `run_argv`, plus its one-element
`.stages` list.

The distinct `pipeline_result` map always contains, in order:
`ok`, `exit_code`, `stdout`, `stderr`, `timed_out`, `interrupted`, `signal`,
`duration_ms`, `stdout_truncated`, `stderr_truncated`, `utf8_lossy`,
`error_code`, `error`, `stages`, `status`, `failed_stage`, `summary`.

- `exit_code` and `signal` describe the **last** stage. They do not alone decide
  overall success: a middle-stage failure makes `.ok` false even when the last
  stage exits 0.
- `stdout` is the last stage's captured stdout, untrimmed. It is `""` when the
  last stage routes stdout elsewhere.
- `stderr` concatenates captured stage stderr in stage order. Routed/merged
  stderr is absent from this aggregate.
- `stderr_truncated` and `utf8_lossy` are aggregate flags. `stdout_truncated`
  applies to final stdout. A truncation flag also records a capture abandoned
  at the deadline before EOF, not only bytes discarded by `max_output`.
- `error_code` / `error` are normally `nil`. Setup/lifecycle failures use
  `PIPELINE_STDIO`, `PIPELINE_SPAWN`, `PIPELINE_IO`, or `PIPELINE_INTERNAL` and
  are returned as `ok: false`; ordinary non-zero exits and signals remain data.
  A later-stage `PIPELINE_SPAWN` is the unavoidable partial-run case:
  `.stages` contains only stages already started and reaped. Their captured
  stderr is abandoned during emergency cleanup and marked truncated.

Each `.stages[i]` map contains, in order: `index`, `argv`, `ok`, `exit_code`,
`signal`, `duration_ms`, `stderr`, `stderr_truncated`, `utf8_lossy`,
`accepted_signal`, `status`, `broken_pipe`. Stage stderr is untrimmed.
`accepted_signal` records the SIGPIPE policy below; it is false for ordinary
exits and rejected signals.

#### Why each stage ended — `status`, `failed_stage`, `summary`

Gates branch on these fields, never on stderr or `summary` text. A stage's
`status` is the first of these that applies:

| stage `status` | meaning |
|---|---|
| `ok` | exited 0 |
| `timeout` / `interrupted` | still running when the deadline / Ctrl-C made Mix signal its group — the death is Mix's, not the stage's |
| `broken_pipe` | killed by SIGPIPE: its reader closed (also set when `allow_signal` accepted it — `.ok` carries the acceptance, `status` the fact) |
| `signal` | killed by any other signal (`.signal` names it) |
| `exit_nonzero` | exited with a non-zero code (`.exit_code`) |
| `setup_error` | started, then killed because a later stage could not be set up |

`broken_pipe` (bool) is true whenever SIGPIPE killed the stage. SIGPIPE is the
only evidence of a closed reader that a stage cannot forge: a program that
ignores SIGPIPE and exits non-zero on `EPIPE` reports `exit_nonzero`.

The pipeline's `status` is `setup_error` (with `error_code`), else
`interrupted`, else `timeout`, else `ok` when `.ok` is true, else the status of
`failed_stage`. `failed_stage` is the **rightmost** stage whose `ok` is false —
`set -o pipefail`'s rule — or `nil`. Rightmost because a downstream stage that
exits early leaves its writer with a broken pipe: in `yes | sh -c 'exit 3'` the
cause is stage 1 (`exit_nonzero`) and stage 0's `broken_pipe` is the symptom.
For `PIPELINE_SPAWN` it is the stage that could not start; other setup errors
name no stage.

`summary` is a one-line human rendering with no durations, so it is stable
across runs:

```
ok (2 stages)
ok (2 stages; stage[0] yes broken pipe accepted)
stage[1] sh exited 3
stage[0] sh killed by signal 15
stage[0] yes: broken pipe (its reader closed)
timed out (deadline 300 ms); killed stage[1] sleep
```

A captured stream that truncated appends ` [output truncated]`.

```mix
$r = run_pipeline([["producer"], ["filter"], ["consumer"]], {timeout: 60})
if $r.status == "timeout" then
  eprint("slow: " .. $r.summary)
elif $r.status != "ok" then
  $s = $r.stages[$r.failed_stage]
  eprint("stage " .. $s.index .. " " .. $s.status .. ": " .. $s.stderr)
end
```

Pipeline options (unknown keys raise `OPTION_INVALID`):

- `timeout`: one wall-clock deadline in seconds for the **whole pipeline**,
  starting before route and pipe setup; default 30, `0` disables, fractional
  values are accepted. A route open that reaches the deadline returns
  `PIPELINE_STDIO` before any stage runs. Process enforcement polls
  at 50 ms, exactly as `run_argv` does, so a pipeline that finishes inside the
  first poll of an unreachably short deadline is reported as a normal
  completion, not a timeout. A deadline bounds a wedge; it is not a stopwatch.
- `max_output`: bytes per captured stream, default 8 MiB, `0` disables. It caps
  final stdout and each captured stage stderr independently; excess is drained
  and flagged, not allowed to block a child.
- `allow_signal`: bool, **default `false`**. By default every stage must exit
  normally with code 0, so any signal death — SIGPIPE included — makes `.ok`
  false. Set `allow_signal: true` to accept a **non-final** stage killed by
  SIGPIPE when every downstream stage succeeded, which is what the ordinary
  early-reader idiom needs:

  ```mix
  $r = run_pipeline([["yes"], ["head", "-1"]], {allow_signal: true})
  ```

  The default is `false` because **the signal is all Mix can see**. A stage that
  kills itself with SIGPIPE for a fatal reason of its own is indistinguishable
  from one whose reader simply closed early, so accepting it by default reports
  this as success:

  ```mix
  run_pipeline([["yes"], ["sh", "-c", "printf fatal >&2; kill -PIPE $$"], ["true"]])
  ```

  The middle stage announced a fatal condition and killed itself, every
  downstream stage exited 0, and `.ok` would have been `true`. Reporting that as
  success is the silent-wrong-answer class this surface exists to remove, so the
  honest answer is the default and the ergonomic one is opt-in. This matches
  `set -o pipefail`, which likewise reports 141 for `yes | head -1`.

  Per-stage `.accepted_signal` records where an acceptance was applied.

Every stage's file routes and every inter-stage/data/capture pipe are prepared
before **any** stage is spawned. Non-append routes are truncated only after the
full set has opened. A later open or pipe-creation failure therefore returns
`PIPELINE_STDIO` with no stage run; the truncation pass itself is not a
transaction if one truncation succeeds and a later one fails.

Every stage leads its own process group. The pipeline owns one deadline: expiry
SIGKILLs every stage group, including descendants, and sets `timed_out: true`.
Ctrl-C sends SIGTERM to every group, allows the same two-second grace as
`run_argv`, then SIGKILLs survivors. A descendant that deliberately escapes its
stage group can retain a captured descriptor; Mix waits only a short bounded
drain window, then returns the captured prefix with the relevant truncation
flag true rather than waiting indefinitely for EOF. When `timeout: 0` disables
the deadline, capture instead waits for EOF and is never abandoned merely
because every direct stage has exited. A supplied stdin-data writer is likewise
joined: a descendant which holds its read end without consuming can make an
explicit no-deadline pipeline wait indefinitely, but cannot leave a detached
native writer thread behind.

`run_pipeline_must(stages, [opts])` accepts the same forms. It returns final
stdout unchanged only when the aggregate `.ok` is true and no captured stream
was truncated. Otherwise it raises `PIPELINE_EXIT_NONZERO`, `PIPELINE_TIMEOUT`,
`PIPELINE_SIGNAL`, `PIPELINE_INTERRUPTED`, `PIPELINE_OUTPUT_LIMIT`, or the
setup/lifecycle code above. The complete pipeline_result is always available as
`$err.details.result`. A stage failure is raised from that result's own
`status` and `failed_stage`, so the raise and the result always agree. A
`signal` or `broken_pipe` status gives `PIPELINE_SIGNAL`, anything else gives
`PIPELINE_EXIT_NONZERO`, and the message names `failed_stage`. For
`yes | sh -c 'exit 3'` that is `PIPELINE_EXIT_NONZERO` for stage 1, not
stage 0's broken pipe.

### run — stdout string, fail-fast

`run(cmd)` runs `cmd` through `/bin/sh -c`, returns its stdout as a string with
**trailing** whitespace stripped (leading whitespace is preserved), and on a
non-zero exit (or signal kill) **raises a catchable `die`** carrying the
command excerpt, the exit status, and a tail of stderr.

```mix
$out = run("echo hello world")
print($out)
print("len: " .. length($out))
```
```text
hello world
len: 11
```

The die on failure — wrap a must-succeed step in [`try`/`catch`](errors.md):

```mix
try
  run("false")
catch $e
  print("caught: " .. ("" .. $e))
end
```
```text
caught: run: 'false' failed (rc=1)
```

The die message includes a stderr tail when there is one (`run: 'cmd' failed
(rc=2): <stderr tail>`, last 200 characters). A signal-killed child reports the
shell convention `rc = 128 + signo` — SIGTERM shows as `failed (rc=143)`, not a
separate `signal=N` form. The excerpt and tail are run through
[`sanitize`](#sanitize) so a hostile command/stderr can't smuggle control
characters into your logs.

### run_rc — the {rc, stdout, stderr, timed_out, interrupted} map

`run_rc(cmd)` runs the same way but **never raises** — it returns a map so you
branch on the exit code yourself. `stdout` and `stderr` are both stripped of
trailing whitespace. The `timed_out` / `interrupted` bools are always present
(`false` on a normal exit) — see [Timeouts](#timeouts) below.

```mix
$r = run_rc("ls /nonexistent-xyz")
print("rc=" .. $r.rc)
print("stderr=" .. $r.stderr)
```
```text
rc=2
stderr=ls: cannot access '/nonexistent-xyz': No such file or directory
```

The idiomatic exit-code branch — the structured-return payoff:

```mix
$r = run_rc("systemctl is-active some-service")
if $r.rc != 0 then
  print("not running")
else
  print("active: " .. $r.stdout)
end
```

`rc` is the real exit code as a number. A signal-killed child reports
`128 + signo` (SIGTERM → `143`); `-1` means the `timeout` deadline fired and
`-2` means Ctrl-C interrupted the wait (see below) — never confuse those with a
child's own exit code. Trailing newlines are stripped, so a one-line tool's
`stdout` is clean to compare or concatenate:

```mix
$r = run_rc("printf 'a\nb\n\n'")
print("[" .. $r.stdout .. "]")
```
```text
[a
b]
```

### Timeouts

`run` and `run_rc` take an optional second argument — an opts map with a single
`timeout` key, in **whole seconds** (every ssh/run timeout in Mix is seconds; the
Bus `send … timeout=2000` form is the only millisecond surface). The default is
`0` = **no deadline** — the historic contract, so a long build never gets cut
off by surprise. With a deadline set, a hung child can never wedge the shell:

```mix
$r = run_rc("sleep 5", {timeout: 1})
print("rc=" .. $r.rc .. " timed_out=" .. ("" .. $r.timed_out))
```
```text
rc=-1 timed_out=true
```

```mix
try
  run("sleep 5", {timeout: 1})
catch $e
  print("caught: " .. ("" .. $e))
end
```
```text
caught: run: 'sleep 5' timed out after 1s
```

The full status contract:

| Outcome | `run` | `run_rc` |
|---|---|---|
| normal exit | stdout string / die on non-zero | `rc` = exit code |
| deadline fired | dies (catchable): `timed out after Ns` | `rc: -1, timed_out: true` |
| Ctrl-C during the wait | raises `run: interrupted` | `rc: -2, interrupted: true` |
| child signal-killed | dies: `failed (rc=128+sig)` | `rc` = `128 + signo` (SIGTERM → 143) |

Kill mechanics (the same machinery as [`ssh_run`](remote.md)): the child is
spawned in its **own process group**, so the kill reaches every descendant — an
`ssh` helper or forked worker can't keep the pipes open past the deadline. A
timeout SIGKILLs the group immediately (`run_argv` can opt into SIGTERM first
with `grace`); a Ctrl-C sends SIGTERM, waits a 2-second grace, then SIGKILLs.
Every SIGTERM path waits for the whole group to empty, bounded by its grace,
then SIGKILLs the group. A descendant that honours SIGTERM can finish its
cleanup; one that ignores it is killed at the deadline, not orphaned. On Linux
the child is reaped only after that, so its zombie keeps the group id
reserved and every signal reaches the right group. "The group has emptied"
is read from `/proc`, and any record Mix cannot read counts as still alive.
A member hidden from `/proc` entirely, by another pid namespace or
`hidepid=2` for another user's processes, cannot be counted. There the grace
may end early, but the SIGKILL still reaches the whole group. An interrupt that lands on the same poll as the deadline
wins the tie — it's reported as the cause.

The opts map is validated **loudly** — a mistake can't silently leave a call
unbounded:

```text
run_rc("echo hi", {bogus: 1})       -> Runtime error: run_rc: unknown opt "bogus" (supported: timeout)
run_rc("echo", {timeout: 1.5})      -> Runtime error: run_rc: timeout must be a non-negative integer, got 1.5
run_rc("echo", "notamap")           -> Runtime error: run_rc: opts must be a map like {timeout: 30}, got string
run_rc("echo", {timeout: 1}, "x")   -> Runtime error: run_rc() expects at most 2 argument(s), got 3
```

`run_stream` takes **no** timeout opt; it blocks until the child exits, which is
the point of handing it the terminal. Since v0.51.0 it *has* an options map, so
`{timeout: 5}` is no longer a silently-ignored surplus argument — it raises
`OPTION_INVALID` naming `run_argv` as the runner that honours a deadline (as do
`stdin`, `stdout`, `stderr`, `max_output` and `stream`). `spawn` doesn't need one — it returns
immediately and you `kill()` the PID yourself. The `http_*` builtins have their
own deadline (default 30 s) — see [http](http.md).

### run_stream — live stdio, argv list, no shell

`run_stream(argv_list)` runs an **argv list directly** — no `/bin/sh`, so no
word-splitting, globbing, quoting, or operator interpretation. Each list element
is one argument verbatim, which makes user values **injection-inert by
construction**. It inherits the parent's stdin/stdout/stderr (output streams live
as it happens) and returns the **exit code** as a number.

```mix
$code = run_stream(["echo", "streamed", "live"])
print("exit code: " .. $code)
```
```text
streamed live
exit code: 0
```

Use it for a foreground one-shot where the child should own the terminal — live
progress (a build, a long copy) or an interactive prompt (a password, an `apt`
confirmation) — *provided the command allocates a pty itself*, e.g.
`run_stream(["ssh", "-t", $host, $cmd])`. A signal-killed child reports
`128 + signo` (the shell convention).

It is strict about its argument: a non-list, an empty list, or a non-string
element all raise rather than silently stringifying:

```mix
try
  run_stream("ls")
catch $e
  print("caught: " .. ("" .. $e))
end
```
```text
caught: run_stream: argument must be a list of strings, got string
```

Because it blocks the evaluator until the child exits, keep it out of a hot
`on … async` [event handler](bus.md) — there it stalls dispatch like `run`/`run_rc`
would, and there's no terminal for interactivity anyway.

#### run_stream options — env, clear_env, cwd (v0.51.0)

The optional second argument is `{env, clear_env, cwd}`, with **exactly** the
semantics [`run_argv`](#run_argv--structured-argv-execution-v0290) gives those
three keys — same name validation (`[A-Za-z_][A-Za-z0-9_]*`), same NUL
rejection, same `OPTION_INVALID` code, all checked *before* the child is
spawned. The order is clear-then-layer, so `{clear_env: true, env: {…}}` means
"exactly these":

```mix
$code = run_stream(["npm", "install"], {
  cwd: "/srv/app",
  env: {NODE_ENV: "production", CI: "1"}
})
```

Values reach the child through `execve`, not a shell — spaces, globs and a
literal `$HOME` in a value survive verbatim.

Use it instead of prefixing the argv with coreutils `env`. That old workaround
still runs, but it puts every value in the child's `ps` argv, where any user on
the box can read it — the option does not, which makes it the route for a token
or password handed to an interactive child. The `export` statement keeps a
value out of argv as well — it is the mechanism behind [`ssh_run`](remote.md)'s
default `mix` env transport and `ssh_mix` — but it mutates this process's
environment: the variable stays set for the rest of the run, and every child
spawned after it inherits the value unless that child clears or overrides it.
The option is scoped to the single call.

⚠️ On a mix older than 0.51.0 the map is **not** an error — default compatible
arity silently ignores a surplus argument, so the child runs with the inherited
environment, the inherited cwd, and no sign that anything was dropped. That is
a fail-*open* version boundary. A caller that may meet a mixed-version fleet
should install the new binary everywhere before the caller, run under
`--strict-arity` (where the old contract's arity raises `ARITY_MISMATCH`), or
probe the option behaviourally: spawn `["/bin/sh", "-c", "test x$SENTINEL =
xVALUE"]` with the sentinel in `env` and check the exit code before trusting
the real run. Prove the sentinel is *absent* from the parent first — an
inherited value passes the probe on the very binary the probe exists to catch.

The four `run_argv`-only keys are refused **by name** rather than ignored:
`timeout` (this runner blocks until the child exits), `stdin` (it inherits the
parent's), and `max_output` / `stream` (it captures nothing). Each error names
`run_argv` as the runner that does honour the key.

⚠️ A bare `argv[0]` is resolved against the **child's** `PATH`, not the
parent's — so `env: {PATH: "/nonexistent"}` makes `run_stream(["sh", …])` fail
to spawn, even though `sh` is on yours. (`clear_env: true` alone leaves no
`PATH` at all, and the C library's default path still finds `/bin/sh` on Linux —
but that is the platform's fallback, not a guarantee.) Pass an absolute
`argv[0]` whenever you touch `PATH` or clear the environment; see
[the minimal-PATH rule](#-the-minimal-path-rule). Pass one under `cwd` too — a
*relative* `argv[0]` is resolved in a directory the OS deliberately leaves
platform-specific, so `run_stream(["./build.sh"], {cwd: "/srv/app"})` is not
portable; spell it `/srv/app/build.sh`.

### run_parallel — process-level fan-out (v0.82.0)

`run_parallel(jobs [, {max, timeout}])` runs many `run_argv` jobs at once through
a bounded worker pool and returns a **list of `process_result` maps in input
order** — each map is exactly what the same `run_argv` call would return, so
existing result-handling code ports unchanged. One job's ordinary failure
(nonzero exit, timeout, a spawn error) is **data in its map, never a raise**.

```mix
-- Fan a health check across a fleet; collect every result.
$hosts = ["alpha", "beta", "gamma"]
$jobs = map($hosts, fn($h) = ["ssh", $h, "uptime"])
$results = run_parallel($jobs, {max: 8, timeout: 10})
for each $i in range(0, len($hosts) - 1)   -- range is INCLUSIVE: len-1, never len
  $r = $results[$i]
  print($hosts[$i] .. ": " .. ($r.ok ? trim($r.stdout) : "DOWN (" .. $r.exit_code .. ")"))
end
```

A job is either an **argv list** (`["ssh", $h, "uptime"]`) or a **`{argv, …}`
map** carrying the same per-job options `run_argv` accepts (`stdin`, `cwd`,
`env`, `clear_env`, `stdout`, `stderr`, `max_output`, `timeout`). `max` bounds
concurrency (default 8, **hard-capped at 256** live workers — a larger `max`
still runs every job, just no more than 256 at once); a top-level `timeout`
(seconds) overrides every job's own. A job may **not** disable its deadline
(`timeout: 0` is refused): one never-exiting job would park a worker forever and,
because the call waits for all workers, hostage the whole batch. A parse error in
**any** job fails the whole call before a single process spawns, exactly as
`run_argv` validates before spawning.

**This is PROCESS-level fan-out, not in-language concurrency.** The evaluator is
single-threaded by construction and Mix `Value`s are never shared across
threads: `run_parallel` parses every job to plain owned data first, and the
worker threads touch only process plumbing (argv, pipes, exit codes), marshalling
results back on the caller's thread. There is deliberately **no** `parallel(list,
fn)` that runs Mix functions concurrently — that would mean rebuilding the value
model, and it is not planned. A fleet sweep that walked N nodes serially becomes
one `run_parallel` of N ssh jobs; for Mix source, [`ssh_mix_many`](remote.md#ssh_mix_manyhosts-source-opts--map-host--result)
is the same pool with `ssh_mix`'s `bindings`, `decode` and result shape kept. A job's
`stream` flag is ignored (a parallel live tee would interleave into garbage).

### send_mail — report mail through the local MTA

`send_mail(msg [, {host, sendmail, timeout, mix_bin}])` is the last step of every nightly
report: render a plain-text message and hand it to the MTA. It replaces the
hand-written `.eml` file, the `run_argv(["/usr/sbin/sendmail", "-t", "-f", $from],
{stdin: {file: …}})` and the cleanup.

```mix
$r = send_mail({
  to: ["ops@example.com", "Audit <audit@example.com>"],
  from: "Reports <reports@example.com>",
  subject: "Weekly spam report",
  body: $report
})
if !$r.ok then
  eprint("mail failed: " .. $r.exit_code .. " " .. $r.stderr)
end
```

- **`msg`** needs `to` (a string or a list of strings), `from`, `subject` and
  `body`. `headers` is an optional map of extra headers. Any other key raises.
  There is no `cc` or `bcc` key: put `Cc` and `Bcc` in `headers`.
- **The message is built for you**: `From`, `To`, `Subject`, `Date` (UTC),
  `Message-ID`, `MIME-Version: 1.0` and `Content-Type: text/plain;
  charset=utf-8`. A CRLF body is normalised to LF.
- **Line limits are kept.** A long header (a long subject, forty recipients)
  is folded at whitespace so lines stay within 78 characters; a header with
  an unbreakable run over 998 characters raises. An ASCII body whose lines
  all fit in 998 bytes goes as `7bit`. A non-ASCII body, or one with a longer
  line (a JSON or CSV dump), goes as `quoted-printable`, so no MTA can split
  or mangle it.
- **A non-ASCII subject is RFC 2047-encoded** (as [`rfc2047_encode`](strings.md)
  does it). Every other header value must be ASCII, and a CR, LF or NUL in
  any header raises. There is no way to inject a second header through a
  value.
- **`headers` adds headers, or replaces a generated `Date`, `Message-ID` or
  `MIME-Version`.** `From`, `To` and `Subject` come only from `msg`, and
  `Content-Type` and `Content-Transfer-Encoding` only from `send_mail`, which
  encodes the body itself. Naming any of those five in `headers` raises. A
  label of your own would describe other bytes than the ones sent: a
  quoted-printable body labelled `8bit` reads as literal `=C3=BC`. The body is
  always `text/plain; charset=utf-8`.
- **Delivery is `sendmail -t -i -f <envelope>`** with the message on stdin,
  never a network SMTP client. `-t` takes the recipients from the headers, so
  a `Bcc` header works and is stripped by the MTA. `-i` keeps a line holding
  a lone `.` as body text.
- **`from` is exactly one mailbox**: `a@example.com` or
  `Display Name <a@example.com>`, where the display name is plain words or one
  `"quoted string"`. The envelope sender is that address. A comment, a second
  mailbox and the null sender `<>` raise rather than guess. An address
  without `@` (a local user such as `root`) is sent as it is, and the
  `Message-ID` domain then falls back to `localhost`.
- **Which sendmail**: the first `sendmail` on `PATH`, then `/usr/sbin/sendmail`,
  then `/usr/lib/sendmail`. The `sendmail` option names one explicitly.
- **`host` sends from another host** — the one with a working MTA — through
  [`ssh_exec`](remote.md). The message is still built locally; only the
  sendmail run is remote, with `/usr/sbin/sendmail` as the default there. The
  result carries `host` as `ssh_exec`'s does, and only then. **`mix_bin`**
  (with `host` only) names the remote mix binary the hop runs, resolved as
  for [`ssh_mix`](remote.md): `mix_bin`, else local `MIX_REMOTE_BIN`, else
  `/opt/mixos/bin/mix`.
- **The result is `run_argv`'s `process_result` plus `message_id`**. `ok`
  means the MTA accepted the message for submission, not that it was
  delivered. An MTA that refuses the message, or a sendmail that is not
  there, is DATA: `ok: false` with `exit_code`, `stderr` and `error_code`.
- **Bad input raises before anything runs**: `OPTION_INVALID` for a bad
  `msg` field or option, `TYPE_MISMATCH` for a `msg` that is not a map or the
  wrong number of arguments, and with `host`, `ssh_exec`'s own validation
  errors.
- **`timeout`** is in seconds, as for `run_argv` (default 30).

Mail that a filter must recognise should use one fixed `from` for every
report, with the envelope matching it, which `send_mail` does by
construction.

### Which runner?

| Need | Use |
|---|---|
| stdout string, abort on failure | `run` |
| inspect a non-zero exit code as data | `run_rc` |
| live output / interactive child / inject-safe argv | `run_stream` |
| run Mix source on another node | [`ssh_mix` + heredoc](remote.md#headline-idiom-ssh_mix--heredoc) |
| run a shell snippet on another node | [`ssh_run` / `ssh_must`](remote.md) |
| talk to a local/mesh Bus broker | [`send` / `emit`](bus.md) |

## What the command string sees

`run`/`run_rc` hand the whole command string to `/bin/sh -c`, so POSIX-sh
syntax inside it just works — and three constructs behave differently there
than on a [shell-dispatch line](shell-mode.md):

- **Subshell `( … )` / brace-group `{ …; }` grouping**: shell dispatch (the REPL / `mix -c` shell branch) does **not** support POSIX command grouping — a bare `(echo a; echo b) | sort` at the prompt fails because a *leading* `(` classifies the line as Mix, where `echo a` is not a valid parenthesized expression (and ordinary expression parentheses do not permit `;` either); a mid-line group gets word-split. The fix is not a `.sh` file — hand the whole pipeline to `/bin/sh` as one Mix line:

  ```mix
  $r = run_rc("(echo b; echo a) | sort")   -- {rc, stdout, stderr}; group runs in /bin/sh
  print($r.stdout)
  print(run("(cd /tmp; pwd) | tr a-z A-Z"))
  ```
  ```text
  a
  b
  /TMP
  ```

  On a mix-login-shell node a remote `(…; …)` hits the *remote* classifier the
  same way. Ship multi-line Mix without nested escaping via
  [`ssh_mix` + heredoc](remote.md#headline-idiom-ssh_mix--heredoc).

- **`$(...)` command substitution**: literal in a double-quoted Mix [string](strings.md), but it **passes through** in a `run`/`run_rc` command string — it substitutes in the `/bin/sh` that actually runs the command (local here; the *remote* shell for `ssh_run`).

- **Brace expansion `{a,b}` / `{1..5}`**: a shell-dispatch feature, **not** a `/bin/sh` one — braces in a `run`/`run_rc` command string pass through to POSIX sh, which does no brace expansion. Use a dispatch line or a Mix loop when you need it.

## ⚠️ The minimal-PATH rule

`run`, `run_rc`, and `spawn` go through `/bin/sh` with whatever PATH the parent
process had — non-interactively that is **minimal**, and `~/.mixrc` aliases are
*not* loaded (those only apply to interactive `mix -i`). The safe habit:
**call binaries by full path** inside scripts.

```mix
-- fragile: bare name may not be on /bin/sh's PATH non-interactively
run("mix --version")

-- robust: absolute path always resolves
print(run("/opt/mixos/bin/mix --version"))
```
```text
mix 0.21.2
```

`run_stream` takes the program name as `argv[0]` and resolves it against PATH the
same way — full-path that too if you can't guarantee the environment. The rule
of thumb: **inside scripts, always full-path** (`/opt/mixos/bin/...`). The one
context where a bare `mix` *does* resolve is as the ssh command itself
(`ssh host 'mix status'`) — the login-shell mix self-resolves via its own
executable path, no PATH needed ([remote](remote.md)).

## Background processes — spawn, kill, process_alive

`spawn` starts a background process and returns its **PID** as a number. It does
not wait, reap, or supervise — it owns nothing after it returns (that is
`run_argv`'s / a supervisor's job). It has **two forms**, chosen by the first
argument's type.

**Shell form — `spawn(cmd[, stdout_path[, stderr_path]])`**, a string command
run via `/bin/sh -c` with stdin from `/dev/null`. Stdio routing by arity:

- 1 arg — both stdout and stderr → `/dev/null`
- 2 args — stdout → file (truncated), stderr → `/dev/null`
- 3 args — stdout → file1, stderr → file2; pass the **same path** for both to merge them into one combined log (like bash `&>file`)

```mix
$p = spawn("echo logged-line", "/tmp/spawn.log")
sleep(0.2)
print(run("cat /tmp/spawn.log"))
```
```text
logged-line
```

All three shell-form arguments are strings and **none is coerced** (strict since
v0.52.0) — `spawn` needs loud validation most, because it is the only runner
with nowhere to put a failure: it returns a **PID, not a result map**, so a child
that dies on its first line looks exactly like one that worked. A non-string
raises `TYPE_MISMATCH` at argument validation, before any stdio file is opened
(so a NUL in `stderr_path` can no longer truncate the `stdout_path` file on the
way to failing).

**Argv form — `spawn(argv[, {detach, die_with_parent, exit_event, tag, cwd, env, clear_env, stdout, stderr}])`**
(v0.89.0), a **list** of strings run **directly, with no shell** — so no
word-splitting, glob expansion, or quoting surprises. This is the launcher /
daemon slot: the job that used to force `run("setsid app &")` through `sh`.

```mix
spawn(["bterm", "--profile", "work"])                 -- argv, no shell
spawn(["mydaemon"], {detach: true})                   -- new session (setsid),
                                                      --   survives the caller,
                                                      --   drops the terminal
spawn(["worker"], {cwd: "/srv/app", env: {ROLE: "bg"},
                   stdout: {file: "/var/log/worker.log", append: true}})
```

- `detach: true` → the child is put in a **new session** (`setsid`): it has no
  controlling terminal and its own session, so a terminal hangup or the caller
  exiting does not take it down — the daemon shape, stronger than the shell
  form's `&`. (Session separation, not immortality: a service-cgroup teardown
  or an explicit signal still reaches it.) Since v0.92.0 it is also
  **double-forked**: the child is reparented to init (or the nearest
  subreaper), which reaps it — so a long-lived caller such as a `mix --serve`
  launcher citizen is never left holding zombies, and "owns nothing after it
  returns" is literally true. The returned PID is the real (grandchild)
  process, and it still leads its own session. Because init reaps it, the pid
  is FREE as soon as the child exits and the kernel may hand it to an unrelated
  process: a later `kill($pid)` or `process_alive($pid)` can hit a stranger.
  A live pid only says SOME process holds that number, and a pidfile alone
  says no more — a stale one names whoever holds that pid now. To stop a
  detached daemon later, check a pidfile together with the process start time
  (field 22 of `/proc/<pid>/stat`, recorded when the pid was written), or ask a
  Bus verb the child itself answers, rather than trusting a bare pid. Default `false` (a plain child
  in the caller's session, which stays the caller's to reap).
- `die_with_parent: true` (Linux), without `exit_event`, → the opposite slot. The child **ends with
  this mix process**, for a helper that must not outlive the script or
  `--serve` citizen that started it:

  ```mix
  $pid = spawn(["goose", "serve", "--port", "7070"], {die_with_parent: true})
  ```

  The child leads its own process group. Two mechanisms end it:
  - **Graceful exit.** This covers the script ending, `exit()`, a `--serve`
    citizen's QUIT or SIGTERM drain, and a REPL restart. Mix sends SIGTERM to
    the child's whole process group, waits up to 2 s for the group to empty,
    then SIGKILLs whatever is left. The child gets its chance to clean up, and its own
    children go too.
  - **`--serve` RELOAD.** The old generation's owned children are ended the
    same way *before* the new script's init runs. An init that starts its
    helper again therefore never races a leftover one for the same port. If
    the reload then reverts, because the new init failed, the old script
    resumes without those children. Anything the failed init had already
    spawned with `die_with_parent` is ended too, so a failed reload leaks no
    helpers.
  - **Hangup of the interactive shell.** When the terminal goes away, the
    job-control shutdown sweeps owned children the same graceful way before
    it exits.
  - **Crash, or a signal mix does not handle.** If mix is SIGKILLed, panics
    or is OOM-killed, the kernel SIGKILLs the child (`PR_SET_PDEATHSIG`). The
    same happens when a plain `mix script.mix` or a non-interactive mix
    receives SIGTERM, SIGHUP or SIGQUIT, because those still end mix at once
    by default. That path reaches the child only, not its descendants, and
    gives it no chance to clean up. A `--serve` citizen is different: its
    SIGTERM is a graceful drain, so the sweep runs. A script that must clean
    up its helper's own children on SIGTERM should run as a `--serve`
    citizen or be stopped with Ctrl-C, which ends the evaluation normally and
    so reaches the sweep.

  `detach` together with `die_with_parent` raises `OPTION_INVALID`, because
  they contradict each other. Mix itself is the only thing that reaps an
  owned child. `process_alive` answers for it without freeing its pid, so
  the group id cannot be recycled while it is registered. A finished child
  whose group has emptied is reaped at the next `process_alive` or `spawn`.
  One whose descendants are still running is kept as a zombie until the
  sweep ends them. PDEATHSIG is keyed to the thread that called
  `spawn`, and the ownership registry is process-wide. So the option works
  only on a thread whose host owns it. The `mix` binary evaluates on one
  thread that lives until exit and sweeps before it ends. Elsewhere, for
  example webd, mixos-mcp or mixos-claud evaluating on pooled `spawn_blocking`
  threads, `die_with_parent` raises `OPTION_INVALID`. An embedder that does
  own a long-lived evaluation thread opts in by calling
  `builtins::owned_spawns::enable()` on it. That call returns `false`, and
  changes nothing, if another thread enabled first; only the first thread is
  ever the host. The embedder must also call `sweep()` on that
  same thread before it exits. Off Linux the option raises
  `OPTION_INVALID`. Default `false`: a plain spawn child is untouched by mix's
  exit. With `exit_event:true`, use the generation lifetime below instead.
- `cwd` / `env` / `clear_env` behave exactly as in [`run_argv`](#run_argv--structured-argv-execution-v0290)
  (clear-then-layer: `{clear_env: true, env: {…}}` starts from empty).
- `stdout` / `stderr` reuse `run_argv`'s routing, minus capture: `"null"`
  (default), `"inherit"`, or a `{file, append?, mode?}` map — and
  `stderr: "stdout"` to merge. **`"capture"` is refused**: capturing means
  waiting, which is `run_argv`'s job. A file-open failure means the child is
  **not** spawned.
- argv must be a non-empty list of strings, none coerced; a non-string element
  or an empty list raises `TYPE_MISMATCH`.

```text
spawn(["true"], {stdout: "capture"})  -> OPTION_INVALID: stdout cannot be "capture"
spawn(["echo", 42])                   -> TYPE_MISMATCH: argv[1] must be a string
spawn(7)                              -> TYPE_MISMATCH: cmd must be a string
```

A NUL byte in any string argument is rejected at validation, before any stdio
file is opened. The error *code* follows where the argument is validated: the
shell form's positional command and path args, and the argv form's argv
elements, are `TYPE_MISMATCH`; the argv form's option values — `cwd`, `env`,
and a file route's `{file: …}` path — are `OPTION_INVALID`. `std` would reject a
NUL at spawn anyway, but catching it early keeps a late failure from truncating
a good log on the way down.

### Managed child exit events

`spawn(argv, {exit_event:true, tag:"scene:12"}) -> pid` starts a managed Linux
child. `tag` is an optional string of at most 4096 bytes (default `""`), copied
unchanged into `on proc.exited`'s `$event.args`:
`{pid,tag,exit_code,signal}`. Normal exit supplies an exit code and nil signal;
signal death supplies nil exit code and the signal number. An unexpected reap
failure has both nil and additional `{error_code:"PROC_REAP",message}` fields.
Use tags to reject exits from stale application generations.

Mix owns the child and is its sole reaper. A pidfd and a cancellation descriptor
wake the monitor; it does not poll process state. Up to 128 managed children and
undelivered exits can be admitted per evaluator. `detach:true` is incompatible;
`die_with_parent:true` additionally applies the existing Linux parent-death
protection. The [generation lifetime](serve.md#native-events-and-generation-lifetime)
governs reload, shutdown and descendant cleanup. Managed retirement does not
deliver a terminal event to another evaluator generation.

`kill($pid, signal)` and `process_alive($pid)` use the registered pidfd while the
child is retained, without competing for its exit status. After the exit has
been delivered and the slot reclaimed, the numeric PID is no longer an owned
identity: discard it. Negative PID/group operations keep their existing raw
meaning. Do not reap managed children from an embedding application's SIGCHLD
handler or another thread. `PROC_LIMIT`, `PROC_UNSUPPORTED` (including kernels
without pidfd support), and `PROC_MONITOR` are catchable setup refusals; invalid
options use `OPTION_INVALID`. A failed monitor setup kills and reaps the child.
Teardown waits for the kernel to complete reaping; an uninterruptible kernel I/O
wait can delay it despite SIGKILL.

### Signalling and liveness

`kill(pid[, signal])` sends `signal` (default `15` = SIGTERM) and returns a bool
(`true` if the syscall succeeded). **Both arguments are whole numbers and
neither is coerced** (strict since v0.52.0) — the same rule as `spawn`, and for
a sharper reason:

```text
kill(false)          -- 0.51.0: to_number(false) is 0, and kill(0, sig) signals
                     --   EVERY process in the caller's own process group — the
                     --   script and its siblings — while returning true
                     -- 0.52.0: raises TYPE_MISMATCH
kill($p, "SIGKILL")  -- 0.51.0: the signal silently fell back to SIGTERM, so the
                     --   caller believed SIGKILL had been sent
                     -- 0.52.0: raises TYPE_MISMATCH
kill($p, 9.5)        -- 0.51.0: truncated to 9; 0.52.0: raises (a typo, not a request)
```

A pid arriving as `false` from a failed lookup is exactly how that first line
happens in practice. Signal *names* are not accepted — pass the number (`9` for
SIGKILL); `kill(-$pgid, sig)` still addresses a process group deliberately.

`process_alive(pid)` is a liveness probe
(signal-0 test) returning a bool; it first does a non-blocking `waitpid(WNOHANG)`
to reap a zombie child of *this* process before checking — so a `spawn`ed child
that has already exited reports `false`, not a stale "alive" from a `<defunct>`
slot.

```mix
$p = spawn("sleep 30")
print("alive: " .. ("" .. process_alive($p)))
print("killed: " .. ("" .. kill($p)))
```
```text
alive: true
killed: true
```

A signal to a non-existent PID is harmless and reports the failure honestly:

```mix
print("" .. kill(999999))
print("" .. process_alive(999999))
```
```text
false
false
```

`kill(pid, 9)` sends SIGKILL; pass any signal number you need.

## Desktop status events — net_watch, audio_watch

A status applet needs to know when the network or the volume changes. Reading
`/sys/class/net/*/operstate` on a timer, or running `wpctl get-volume` every
minute, is polling: late when something changes and wasted work when nothing
does. These builtins subscribe instead. They share the
[native-event](serve.md#native-events-and-generation-lifetime) machinery of
`fs_watch` and managed `spawn`: opaque evaluator-owned handles, coalesced
batches in `$event.args`, sticky overflow, cancellation on unwatch, retirement
with the evaluator generation, and no clock anywhere.

```mix
$net = net_watch()
$audio = audio_watch({runtime_dir: env("XDG_RUNTIME_DIR")})

fn network_summary()
  $up = false
  for each $link in net_state().links
    if $link.up and not $link.loopback then $up = true end
  end
  return $up
end

on net.changed
  -- The batch says what moved; net_state() says what is true now.
  print("network up: " .. to_string(network_summary()))
end
on audio.changed
  if type($event.args.closed) == "map" then
    print("audio source ended: " .. $event.args.closed.message)
  else
    $vol = audio_state({runtime_dir: env("XDG_RUNTIME_DIR")})
    print($vol.ok ? to_string($vol.level) .. "%" .. ($vol.muted ? " muted" : "") : "no sink")
  end
end
```

**Events are hints, state is truth.** A batch tells a behaviour *that* something
changed and roughly what; the model is rebuilt from `net_state()` /
`audio_state()`. Always re-read on `overflow:true`.

### Network: `net_watch([opts]) -> handle`

One rtnetlink socket per handle, subscribed to `RTMGRP_LINK`,
`RTMGRP_IPV4_IFADDR` and `RTMGRP_IPV6_IFADDR`, read by a thread blocked in
poll(2) with no timeout. `opts.events` narrows it to `["link"]` or `["addr"]`.
Each wake drains every queued datagram into **one** `net.changed` batch:

```
{watch, overflow, closed?, changes: [
  {kind: "link", ifname, index, up, operstate, loopback, wireless, removed},
  {kind: "addr", ifname, index, up, family: "inet"|"inet6", address, prefix, removed}
]}
```

- `up` on a link is *operationally* up: operstate `up`, or — for drivers that
  report `unknown`, such as `lo` and WireGuard — `IFF_UP` and `IFF_RUNNING`
  together. On an address it means present (`false` with `removed:true`).
- Records coalesce per link index and per address within a batch: a link that
  flaps down and up in one burst arrives once, with its last state.
- Announcements that change nothing are dropped — wireless drivers re-announce
  the link on every scan, IPv6 re-announces addresses on every lifetime refresh.
- A kernel overrun (`ENOBUFS`), a truncated or malformed message sets
  `overflow:true`; the next repeat is then delivered rather than suppressed.

`net_state() -> {links, addresses}` is the same information from a netlink dump
(`links[]`: `ifname, index, up, operstate, loopback, wireless`; `addresses[]`:
`ifname, index, family, address, prefix`). A dump the kernel marks interrupted is
retried; three in a row raise `NET_STATE_INCONSISTENT`. The whole call, retries
included, answers within 2 s or raises `NET_STATE_IO`. Like `audio_state()` it
blocks the evaluator while it waits, so a serve citizen calls both from an
`async` handler (a `task_start` task), not from a sync request path. Only a
dump reply carrying the request's sequence number is read.

If the subscription socket itself fails (a poll error, or a receive error other
than an overrun), the handle delivers one batch with
`closed: {error_code: "NET_WATCH_IO", message}` and `overflow:true`, then stays
silent: unwatch it and subscribe again when you choose to.

The socket is raw libc: three fixed headers and a few attributes do not justify
linking a netlink crate into every Mix build. `net_*` are **Env** class
(read-only observation of the host).

### Audio: `audio_watch([opts]) -> handle`

PipeWire publishes changes through its pulse-compatible server, and
`pactl subscribe` prints one line per change and otherwise blocks. Each handle
owns one such child: its stdout is read by a thread blocked in read(2), and each
read becomes one `audio.changed` batch:

```
{watch, overflow, closed?, changes: [{facility, kind, index}]}
```

`facility` is `sink`, `source`, `server`, `card` by default (`opts.facilities`
may name any of `sink source sink-input source-output module client sample-cache
server card`); `client` is left out by default because every pulse client
connecting would otherwise be an event. `kind` is `new`, `change` or `remove`;
`index` is nil for `server`. Changes coalesce per facility and index.

The volume itself is `audio_state([opts]) -> {ok, volume, level, muted, reason?}`:
one `wpctl get-volume @DEFAULT_AUDIO_SINK@` with a 2 s deadline. `level` is
`round(volume * 100)`. No default sink, a `wpctl` that is missing or cannot
start, unreadable output or a timeout is `ok:false` with a `reason`, not an
error. The deadline holds on every path,
including a kernel without `pidfd_open`. Call it once per batch: a burst of
notices costs one read.

**Why a child and not a library.** No PipeWire client crate is in the
workspace, and libpipewire would bring a C library and its main loop into every
Mix build. A long-lived subscription child is an event stream — the process is
idle until the server has news — so this is not polling. Its lifecycle is owned:
the child runs in its own process group with `LC_ALL=C` (the parser reads
English) and `XDG_RUNTIME_DIR` from `opts.runtime_dir` when given; unwatch or
evaluator retirement SIGKILLs the group and reaps it. If `pactl` exits by itself
(PipeWire restarted, no server yet), the handle delivers one batch with
`closed: {error_code: "AUDIO_SOURCE_EXITED", message, exit_code}` and
`overflow:true`, then stays silent: unwatch it and subscribe again when you
choose to (a behaviour typically retries after a delay from an async handler).
If the Mix process itself is SIGKILLed, the `mix` binary's children carry
`PR_SET_PDEATHSIG(SIGKILL)` and die with it; in an embedder that has not made
its evaluator thread the owned-children host, `pactl` ends at its next write.
`AUDIO_UNAVAILABLE` (no `pactl`) will not change by retrying; treat it as final.
`audio_*` are **Process** class (they run programs).

### Limits and refusals

At most 16 net and audio handles together per evaluator, and 1024 distinct
pending records per handle (beyond that the batch sets overflow). A top-level
`sleep()` in a plain script dispatches these only when `on net.changed` /
`on audio.changed` is registered. All six builtins are denied in expression
mode. Refusals raise with `{error_code, message}`:

| Code | Meaning |
|---|---|
| `NET_WATCH_OPTIONS`, `AUDIO_OPTIONS` | Invalid options. |
| `NET_WATCH_ARGUMENT`, `AUDIO_WATCH_ARGUMENT` | Handle is not a string. |
| `NET_WATCH_HANDLE`, `AUDIO_WATCH_HANDLE` | Unknown, retired, or other-family handle. |
| `NET_WATCH_LIMIT`, `AUDIO_WATCH_LIMIT` | 16-handle limit reached. |
| `NET_WATCH_IO`, `NET_STATE_IO` | Netlink socket or dump failure. |
| `NET_STATE_INCONSISTENT` | Dump interrupted three times running. |
| `AUDIO_UNAVAILABLE` | `pactl` not on PATH. |
| `AUDIO_WATCH_IO` | Could not start or reap the `pactl` child. (`audio_state` never raises: a `wpctl` that cannot start or be read is `ok:false` with a reason.) |
| `*_UNSUPPORTED` | Platform is not Linux. |
| `NATIVE_CLOSED` | This evaluator's native registrations have retired. |

## Environment, identity & the working directory

```
env("NAME")     environment variable value ("" if unset — never raises)
env("NAME", d)  value, or default d when NAME is unset OR empty
args()          list of script arguments
pid()           this process's PID (number)
uid()           this process's EFFECTIVE user id (number)
gid()           this process's EFFECTIVE group id (number)
groups()        every group id this process is in (sorted list of numbers)
hostname()      the system hostname (from /etc/hostname)
cwd()           current working directory
chdir(path)     change the working directory (raises on failure)
platform()      {os, arch} map
which("cmd")    the PATH entry joined with cmd if EXECUTABLE, else nil
has_builtin(n)  does THIS mix have the named builtin? -> bool (v0.78.0)
mix_version()   {major, minor, patch, string} — the runtime version (v0.78.0)
script_version() the entry script's provenance map, nil outside a script (v0.95.0)
script_path()   the entry script's absolute path, fixed at start; nil outside a file
exit([code])    unwind finally, then terminate with status code (default 0)
sleep(secs)     suspend for secs seconds (fractional ok; async-aware)
```

`has_builtin(name)` and `mix_version()` are the **portability pair** — for
a script that must run across a mixed-version fleet, or a compat shim.
`mix builtins NAME` exits 0 for *any* name and cannot tell you whether a
builtin exists, so `has_builtin` is the real yes/no:

```mix
if not has_builtin("ws_connect") then die("this needs mix >= 0.74") end
$v = mix_version()
if $v.major == 0 and $v.minor < 78 then die("needs mix >= 0.78.0") end
```

A feature-gated builtin missing from *this* build still reads `true` from
`has_builtin` (the binary knows the name — calling it raises "requires the
X feature"); that is the honest answer, distinct from a name the binary
has never heard of.

`script_version()` is the script-side twin of `mix_version()`: the running
entry script's `{name, version, sha, sha256, modified, mix: {version, sha,
dirty}}` — the facts `mix SCRIPT --version` prints, as data, so a script can
log its own provenance. `version` comes from the `-- version: X.Y.Z` header
(nil when absent); the map is nil in the REPL and under `-c`. See
[`--version` for scripts](invocation.md#--version-for-scripts).

`script_path()` answers the question `$0` leaves open: where the running
script lives on disk. It is `realpath($0)` — symlinks resolved, absolute —
worked out **once, when the script starts**, before any of its code runs.
So a relative script name is resolved against the directory the script was
started in: a `chdir()` later in the script does not move the answer. A
symlinked entry answers with its **target**, not the link, the same as
`realpath($0)`, so a script finds its siblings in the real tree. The answer
is not re-checked later: a file deleted after start still reports its path.
It is **nil** under `mix -c`, in the REPL, for `mix -` (stdin), and when the
path cannot be resolved at start. It always describes the **entry script**:
a `require`d module calling it, even during its own top-level init, gets the
entry script's path, not its own. `mix --serve` resolves its script the same
way, once, at start.
There is no `module_path()`; a module's own location is not a lexical fact
the evaluator tracks, so a `require`d module must take its directory from
the entry script or from its caller.

```mix
-- where am I?
$data = path_join(dirname(script_path()), "data.mix")
```

`env` reads an environment variable, returning `""` (not nil, no raise) when
unset — distinct from the string-interpolation `${NAME}` form, which walks
scope → env → literal-nil. Use `env(...)` when you want an explicit env read.

A **second argument is a default**: `env("NAME", d)` returns `d` when `NAME` is
unset *or* set-but-empty (shell `${VAR:-default}` semantics) — the common "env
or fallback" need in config code, where the plain `""`-for-unset return would
otherwise defeat a `??` (nil-coalesce) default. The default is returned
**verbatim** (any value), so `env("PORT", 8080)` yields the number `8080`. The
one-arg form is unchanged.

```mix
print(env("FOO"))
print("missing=[" .. env("NOPE_XYZ") .. "]")
print(env("NOPE_XYZ", "fallback"))
print(env("PORT", 8080))
```
```text
bar
missing=[]
fallback
8080
```
*(run as `FOO=bar mix script.mix`)*

`args()` is the script's positional arguments — exactly the same list `$1`,
`$2`, … are indexed from, so the two can never disagree. It is what the runner
parsed, not a slice off the process command line: flags to `mix` itself are not
in it, wherever they appear, and under `-c` the program text is not in it
either. An embedded interpreter that was never given script arguments returns
`[]`. Reach for [`getopt`](builtins.md) when you want flag parsing.

```mix
-- script.mix:
print("" .. args())
```
```text
[alpha, beta]
```
*(run as `mix script.mix alpha beta`)*

`uid()` / `gid()` are the **effective** ids (`geteuid`/`getegid`) — normally the
identity filesystem access is checked against, so they are what a `stat()` map's
`uid`/`gid` should be compared with when a script is deciding whether a path is
its own. Strictly, Linux checks the *filesystem* ids, `fsuid`/`fsgid`; they track
the effective ids unless a process deliberately changes them with `setfsuid(2)`,
which a Mix script has no way to do — so for Mix code the two are the same
answer, and for a Mix interpreter embedded in something that does call it, they
are not.

```mix
$st = stat("/etc/hostname", {follow_symlinks: false})
print("mine=" .. ("" .. ($st.uid == uid())))
print("root-owned=" .. ("" .. ($st.uid == 0)))
```
```text
mine=false
root-owned=true
```
*(as a non-root user)*

Without these the only way to learn your own uid was to create a file and stat
it — and that probe is a liability, not a measurement: the write follows
symlinks, so another user who wins the race gets a file of their choosing
truncated under your identity, and the uid that comes back is *theirs*. Ask the
kernel instead. Under `sudo` these report the target identity, not the invoking
one; there is deliberately no real-uid form, because the effective id — with the
`fsuid` caveat above — is the one a file access is checked against, and the real
id is not.

`groups()` is the **whole** group membership — the `getgroups(2)` supplementary
set plus the effective gid, sorted, with no duplicates. (POSIX permits
`getgroups` to leave the effective gid out; this always includes it, so a caller
never has to add it back. The kernel may also report the same gid twice; the
duplicate is removed here, so the result is a set in the ordinary sense.)

`getgroups(2)` is a measure-then-fill pair, so the set can change underneath it.
Mix cannot call `setgroups`, which means this needs another thread in an
embedder — which is exactly the case that matters, since the daemons embed this
interpreter. A set that *shrinks* is truncated to what was returned; a set that
*grows* makes the fill call fail, and `groups()` re-measures and retries rather
than reporting "cannot tell", because the answer is available and only the first
measurement was stale. The retry is bounded at four attempts: a group set that
will not hold still for four reads raises instead of returning a guess.

It exists because `gid()` alone cannot answer the question scripts actually ask
of it. Unix picks **one** permission class and does not fall through: owner if
the uid matches, else group if you are in the file's group, else other. So for a
file owned by someone else, `gid()` tells you only whether its group is your
*effective* one — and a file grouped under any of your other groups gets the
group bits applied while a `gid()`-only check reaches for the other bits and
gets the answer wrong in either direction. Mode `0701` in a group you belong to
is **not** executable by you, whatever the other bit says.

```mix
$st = stat("/usr/bin/passwd", {follow_symlinks: false})
$mine = false
for each $g in groups()
  if $g == $st.gid then
    $mine = true
  end
end
print("in its group=" .. ("" .. $mine))
print("groups=" .. ("" .. len(groups())))
```
```text
in its group=false
groups=3
```

`platform()` returns a **map**, not a bare string — `os` (`linux`, `macos`,
`windows`, …) and `arch` (`x86_64`, `aarch64`, …):

```mix
$p = platform()
print("os=" .. $p.os)
print("arch=" .. $p.arch)
```
```text
os=linux
arch=x86_64
```

`which` searches PATH for an executable, returning the matching path or `nil`
(absolute whenever PATH's entries are, which is the normal case — but it is the
PATH entry joined with `cmd`, so a relative or empty entry yields a relative
answer):

```mix
print(which("sh"))
print("missing: " .. ("" .. which("definitely-not-a-real-binary-xyz")))
```
```text
/usr/bin/sh
missing: nil
```

**It answers "can I run this?", not "does this exist?"** (since v0.52.0). A PATH
entry comes back only when it is a regular file *and* the kernel says this
process may execute it — asked with the same ACL-aware `faccessat2(2)` check
[`access`](io.md#kernel-permission-checks--access) uses, never from `stat().perm` arithmetic. Before 0.52.0 the
test was `is_file()`, so a non-executable file on PATH was reported as a
command and the caller's very next `run_argv` failed to spawn it — a probe
whose job is to prevent that failure causing it instead.

Both halves are load-bearing: `X_OK` is true for a *searchable directory*, so a
PATH entry holding a directory named `git` would come back as the git binary if
the regular-file test were dropped. And `cmd` is a string, not coerced —
`which(["git"])` raises `TYPE_MISMATCH` rather than searching for a file named
`[git]`.

The consequence worth knowing: on a PATH you do not control, `which` can now
return `nil` where it used to return a path. That is the honest answer — the
old one was a spawn failure deferred by one line.

`cwd` / `chdir` read and set the working directory; `chdir` raises a catchable
error if the path doesn't exist:

```mix
chdir("/tmp")
print(cwd())
```
```text
/tmp
```

`sleep` suspends for the given seconds (fractional allowed). Under the Bus
[`--serve`](bus.md) runtime it is async-aware — a sleep with registered handlers
yields to the dispatch loop rather than blocking the OS thread:

```mix
print("before")
sleep(0.2)
print("after")
```
```text
before
after
```

The duration may be a number or numeric string (`sleep("0.2")`). A supplied
value that cannot be parsed as a number raises `TYPE_MISMATCH`; it no longer
silently becomes a zero-second sleep.

`exit([code])` stops ordinary execution, unwinds every active `finally` block
innermost-first, then terminates with the given status (default `0`):

```mix
print("exiting")
exit(3)
```
```text
exiting
```
*(process exit status is `3`)*

The optional status may be a number or numeric string. `exit()` still defaults
to status `0`; a supplied non-numeric value raises `TYPE_MISMATCH` instead of
silently exiting successfully.

## Safe interpolation — shell_quote, sql_quote, sanitize

When you *must* compose a string for an external shell or SQL statement, quote
the untrusted parts. These are the inert-by-construction helpers — but prefer
`run_stream`'s argv list (no shell at all) or a parameterised query whenever you
can.

### shell_quote

`shell_quote(s)` single-quote-wraps `s` for a POSIX shell (equivalent to PHP
`escapeshellarg`): the result is inert under shell parsing, with internal `'`
rendered as `'\''` (close, escape, reopen).

```mix
print(shell_quote("it's a file"))
```
```text
'it'\''s a file'
```

```mix
$name = "rm -rf /; echo pwned"
print(run("echo " .. shell_quote($name)))
```
```text
rm -rf /; echo pwned
```

### sql_quote

`sql_quote(s)` escapes a string for interpolation **inside** a SQL string literal:
it doubles every `'` *and* escapes `\` → `\\` (safe under MySQL/MariaDB's default
sql_mode, the documented target — quote-doubling alone is injectable there), and
strips NUL bytes. It does **not** add the outer quotes — you compose those.

```mix
print(sql_quote("O'Brien"))
```
```text
O''Brien
```

It stays safe for SQLite/Postgres standard mode (where `\` is literal — the
trade-off is a literal backslash arrives doubled). For exact-byte SQLite
literals, use a real binding (`sqlexec()` placeholders), not string composition.

### sanitize

`sanitize(s)` makes untrusted bytes safe for **one-line diagnostics**: line
breaks (including U+2028/U+2029) collapse to spaces, and C0/C1 controls plus
Trojan-Source-class characters (bidi overrides, zero-width spoofing, BOM) become
`?`. Printable Unicode is kept intact. This is what `run`'s die message uses on
the command excerpt and stderr tail.

```mix
$s = "line1\nline2\ttab"
print(sanitize($s))
```
```text
line1 line2?tab
```

Reach for it before logging anything that came from a network peer, a filename, a
header, or another process's output.

## Identity & crypto primitives

```
uuid()                 random UUID v4 string
random_password([len]) alphanumeric password (default 16, no O/o, class-diverse)
hash_sha256(s[, {raw:true}])  SHA-256 digest of a string/bytes/buffer value
hash_blake3(s[, {raw:true}])  BLAKE3 digest
hash_md5(s[, {raw:true}])     MD5 digest    -- BROKEN hash, legacy interop only
hash_sha1(s[, {raw:true}])    SHA-1 digest  -- BROKEN hash, legacy interop only
hmac_sha256(key, msg[, {raw:true}])  HMAC-SHA256 (RFC 2104) — webhook signatures
jwt_rs256_sign(claims_json, private_pem[, header_json])  compact RS256 JWT
constant_time_eq(a, b) timing-safe equality — compare MACs/secrets with this, not ==
hash_file(p[, algo][, {raw:true}])   streaming digest of a FILE
                       algo: "sha256" (default) "blake3" "md5" "sha1"
                       (all of the above: lowercase hex, or bytes with raw:true)
base64_encode(v)       base64 of a string or bytes buffer
base64_decode(s)       decode base64 -> a bytes buffer
password_hash(pw[, cost])   bcrypt "$2b$…" hash; cost 4-31, default 12 (v0.71.0)
password_hash(pw, {scheme: "sha512-crypt"[, rounds]})
                        "$6$…" SHA512-crypt hash; rounds 1000..999999999,
                        default 5000 (v0.102.6). The salt is 16 chars; default
                        rounds emit the implicit glibc form "$6$salt$hash"
password_verify(pw, hash)   check against a bcrypt OR SHA-crypt hash -> bool;
                        accepts $6$/$5$ and the Dovecot {SHA512-CRYPT} prefix
                        (v0.71.0, sha-crypt v0.102.6)
```

`password_hash`/`password_verify` exist for **account passwords written over
the Bus**: a raw `props.set` of `maild.accounts.password` stores the field
verbatim (only the `account add` CLI hashed it), so the hashing has to happen
client-side — which used to mean shelling out to PHP (bcrypt) or `mkpasswd
-m sha512crypt` (Dovecot passdbs, whose `{SHA512-CRYPT}$6$…` records are
what the sha512-crypt scheme and the verify prefixes interop with). Three
deliberate edges: input over **72 bytes raises** on the bcrypt side (bcrypt's
own truncation limit, surfaced instead of silently applied — hash a digest of
longer secrets); a **malformed hash raises** in `password_verify` rather than
answering `false` (a corrupt stored hash is a config fault, and "wrong
password" would misdirect the operator), and so does a `$6$` hash whose salt
is longer than 16 chars, because glibc and Dovecot can never verify one; and
the general-purpose digests
above are **not** password hashes — `hash_sha256` has no work factor.

Every `hash_*` call takes the same trailing options map, and the only option is
**`{raw: true}`** (v0.66.0): return the digest as raw `bytes` instead of
lowercase hex. `hash_sha256($x, {raw:true})` is 32 bytes, `hash_md5` 16,
`hash_sha1` 20, `hash_blake3` 32, and `hmac_sha256` 32 — which lets a MAC be
compared with `constant_time_eq` without a hex round trip:

```mix
$mac = hmac_sha256($secret, $payload, {raw: true})
if constant_time_eq($mac, base64_decode($header)) then
  print("signature ok")
end
```

Before 0.66.0 a second argument was **silently ignored**:
`hash_sha256("abc", {raw:true})` returned the hex string and said nothing. That
is fixed, and so is the class of bug behind it — an unknown option key or a
non-map option now raises `OPTION_INVALID` rather than being discarded.

`raw` is a **strict** boolean, unlike `bytes_to_string`'s `lossy`, which accepts
any truthy value. The difference is deliberate: `raw` selects the *return type*,
so `{raw: "false"}` — a string that a config file or an argument might easily
produce — would hand back bytes and fail somewhere far from the cause.
`{raw: "false"}` raises; only `true` and `false` are accepted.

### ⚠ MD5 and SHA-1 are broken — legacy interop only

`hash_md5` and `hash_sha1` exist to talk to formats and tools that already chose
those algorithms: `Content-MD5` headers, mail dedup keys, git object ids, older
ETags and vendor APIs, and checksums you need to compare against an existing
`md5sum`/`sha1sum` output. Mix computes them so a script does not have to fork
coreutils, not because they are fit for anything new.

**They must never carry a security decision.** MD5 has had practical collisions
since 2004 and SHA-1 since 2017 (SHAttered), so neither can establish that two
inputs are the same, that a document is unmodified by an adversary, or that a
signature is valid. For anything of that kind use `hash_sha256` or `hash_blake3`,
and for authentication `hmac_sha256` with `constant_time_eq`. Note that Mix
classifies both as capability-`Pure` — that means "touches no host authority",
which is not the same as "safe"; the sandbox has no opinion about your choice of
hash.

The digests are the standard ones and interoperate exactly:

```
$ printf 'The quick brown fox jumps over the lazy dog' > /tmp/fox
$ mix -c 'print(hash_md5(read_file("/tmp/fox")))'
9e107d9d372bb6826bd81d3542a419d6
$ md5sum /tmp/fox
9e107d9d372bb6826bd81d3542a419d6  /tmp/fox
```

`hash_file` streams with a fixed 64 KiB working set whatever the file's size, so
it is the right call for anything large — `hash_sha256(read_file_bytes($p))`
holds the whole file in memory to compute the same answer.

`uuid()` is a fresh random v4 each call:

```mix
print(uuid())
```
```text
0a5fcc5b-ad60-4e8e-9e61-b52f14a067e7
```

`random_password([len])` generates an alphanumeric password from OS entropy
(`OsRng`), defaulting to length 16. It **guarantees** at least one upper, one
lower, and one digit, and excludes the confusable `O`/`o`. `len` must be an
integer in `3..=1024`; out of range raises.

```mix
print(random_password())
print(length(random_password()))
print(random_password(8))
```
```text
qALPecswZfH3YkP0
16
ZDv4WBFl
```

`hash_sha256` / `hash_blake3` return the lowercase hex digest of the input
(string or bytes buffer):

```mix
print(hash_sha256("hello"))
print(hash_blake3("hello"))
```
```text
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
ea8f163db38682925e4491c5e58d4bb3506ef8c14eb78a86e908c5624a67200f
```

`hmac_sha256(key, msg)` is the keyed twin (RFC 2104): the hex HMAC-SHA256 of
`msg` under `key` (both accept string/bytes/buffer). Its everyday job is
verifying webhook signatures — e.g. Stripe's `Stripe-Signature` `v1` value is
`hmac_sha256(endpoint_secret, timestamp .. "." .. payload)`:

```mix
print(hmac_sha256("Jefe", "what do ya want for nothing?"))
```
```text
5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843
```

Compare a computed MAC against a received signature with
`jwt_rs256_sign(claims_json, private_pem[, header_json])` signs a compact
JWT with an RSA private key in PKCS8 or PKCS1 PEM form (crypto feature).
The RSA modulus must be at least 2048 bits. The first PEM item must be the
private key; certificate-first bundles are refused.
Pass JSON objects as strings, typically from `json_encode`. The default
header is `{"alg":"RS256","typ":"JWT"}`. A supplied header keeps its
extra fields such as `kid`; a missing `alg` is filled with `RS256`, and
any other algorithm is refused. Explicit nil means the default header.
Input JSON is parsed and re-encoded, so duplicate object keys collapse to
the final value. Each input is limited to 256 KiB. Malformed or non-object
JSON raises `JWT_CLAIMS_INVALID` / `JWT_HEADER_INVALID`; unsupported or
invalid keys raise `JWT_KEY_INVALID`, and signing failure raises
`JWT_SIGN_FAILED`. These errors do not echo input values.

The primitive signs only: scripts choose claims, expiry and audience,
exchange tokens and call any provider. Keep keys in files or bindings,
rather than source literals. For example:

```mix
$claims = json_encode({iss: $issuer, aud: $audience, iat: time(), exp: time() + 3600})
$jwt = jwt_rs256_sign($claims, read_file($key_file))
```

Compare MACs with `constant_time_eq(a, b)`, never `==` — plain equality short-circuits on the
first differing byte, a timing oracle. `constant_time_eq` scans the full
length unconditionally (a length mismatch returns false immediately; MAC
lengths are public):

```mix
print(constant_time_eq(hmac_sha256("Jefe", "payload"), hmac_sha256("Jefe", "payload")))
print(constant_time_eq("deadbeef", "deadbee5"))
```
```text
true
false
```

`hash_file(path[, algo])` hashes a **file** the same way, but reads it as a
64 KiB-chunked stream — so a multi-hundred-MB artifact (a release image, a
rootfs tarball) is digested with bounded memory instead of
`hash_sha256(read_file(path))` slurping the whole file into a string (which
also rejects non-UTF-8). `algo` defaults to `"sha256"`; `"blake3"`, `"md5"` and
`"sha1"` are the others (the last two added in v0.66.0 — read the warning
above before reaching for either). It takes the same trailing `{raw: true}`
as the in-memory family. The sha256 output is byte-identical to `hash_sha256` over the
same bytes, so it verifies against any `sha256sum`. Capability: **FsRead** (it
opens a path). This is the factory's "name every release artifact + its
digest, then sign the manifest" primitive.

```mix
print(hash_file("/srv/mixos-factory/releases/2026-07-06-001/rootfs.tar.gz"))
print(hash_file("./image.raw", "blake3"))
```

`base64_encode` accepts a string **or** a `Value::Bytes` buffer (it encodes the
raw bytes, not a placeholder). `base64_decode` returns **raw bytes** — since
v0.64.0 those can be indexed, sliced, iterated and searched directly (see
[io](io.md#bytes-as-a-sequence-v0640)), or wrap in
`bytes_to_string` (strict UTF-8; pass `{lossy:true}` to tolerate non-UTF-8) to
read it back as text. The pair round-trips:

```mix
$enc = base64_encode("hello mix")
print($enc)
print(bytes_to_string(base64_decode($enc)))
```
```text
aGVsbG8gbWl4
hello mix
```

These (and `base64_*`, `uuid`) are behind the `crypto` feature, which the `mix`
binary always enables.

## DNS queries — `dns_query` (v0.117.0)

```
dns_query(name, type[, {server, port, timeout, tcp, recurse}])  -> result map
```

`dns_lookup(host)` asks the system resolver for addresses and nothing else.
`dns_query` asks **one server one question** and returns the whole answer, so
a script can tell an authoritative answer (`aa: true`) from a cached one, or
an out-of-zone `REFUSED` from `NXDOMAIN`, without `dig`. The wire format is
hickory-proto (pure Rust, the `dns` feature); no libresolv.

- `type` is a record type name, case-insensitive: `A`, `AAAA`, `MX`, `TXT`,
  `SRV`, `NS`, `SOA`, `PTR`, `CNAME`, `CAA` and the rest. `PTR` of an IP
  address asks its reverse name, as `dig -x` does.
- `name` is always fully qualified: there is no search list.
- `server` is an address or a host name (default: the first `nameserver` in
  `/etc/resolv.conf`, else `127.0.0.1`), `port` defaults to 53, `timeout` to
  5 seconds for the whole query (resolving a server host name, a TCP retry
  and a slowly delivered reply all count against it), and `recurse` (default `true`) sets the RD
  flag. `tcp: true` forces TCP; a truncated UDP answer is retried over TCP
  on its own.

A reply, whatever its rcode, is `ok: true`:

```
{ok: true, rcode: "NOERROR", aa: true, ra: false, tc: false,
 answers: [{name: "mail.example.com.", type: "AAAA", ttl: 300, data: "2001:db8::25"}],
 authority: [], additional: [], server: "192.0.2.53", port: 53,
 transport: "udp", duration_ms: 3}
```

`rcode` is dig's name (`NOERROR`, `NXDOMAIN`, `SERVFAIL`, `REFUSED`, ...).
Each record's `data` is its zone-file text (`10 mail.example.com.` for an MX;
a TXT record's strings joined). Names end in a dot.

No reply is an operational failure, returned rather than raised, as
`ssh_exec` does: `{ok: false, error_code, error, server, duration_ms}` with
`error_code` one of `DNS_TIMEOUT`, `DNS_UNREACHABLE` (ICMP port unreachable,
connection refused), `DNS_PROTOCOL` (only malformed replies), `DNS_IO` or
`DNS_SERVER` (the server name did not resolve). A reply with another id is
ignored, not taken as the answer. A bad argument (an unknown type or option,
an invalid name) raises.

```mix
-- Which servers answer for mail.example.com with authority?
for each $ns in ["192.0.2.53", "198.51.100.53"]
  $r = dns_query("mail.example.com", "AAAA", {server: $ns, recurse: false})
  if not $r.ok then
    print($ns .. ": " .. $r.error_code)
  else
    print($ns .. ": " .. $r.rcode .. " aa=" .. $r.aa)
  end
end
```

## UDP datagrams — `udp_send`, `udp_recv` (v0.71.0)

```
udp_send(host, port, payload)   -> bytes sent; payload string/bytes/buffer, verbatim
udp_recv(port[, opts])          -> {bytes, text, from_host, from_port} | nil on timeout
                                   opts: timeout (secs, default 30, 0 = forever),
                                         host (bind addr, default "0.0.0.0"),
                                         max  (read cap, default 65535)
```

One datagram in, one out — deliberately **not** a socket API: there is no
handle to hold, leak, or close. Before these, a unicast SSDP NOTIFY meant
`run_argv(["nc", "-u", …], {stdin: $pkt})`. `udp_send` resolves the host and
reports the byte count the kernel accepted (UDP being UDP, that is *sent*,
never *delivered*). `udp_recv` binds, waits for **one** datagram, and
returns `nil` on timeout — an ordinary answer for a datagram wait, not an
error. `text` is the payload decoded as UTF-8 or `nil`; `bytes` always
carries the truth. A datagram longer than `max` is truncated to it —
`recvfrom(2)`'s own contract — and the default `max` of 65535 can never
truncate, because no UDP payload exceeds it.

```mix
$notify = "NOTIFY * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\n\r\n"
udp_send("192.0.2.20", 1900, $notify)     -- unicast SSDP to the TV

$got = udp_recv(9999, {timeout: 5})
if $got != nil then
  print("from " .. $got["from_host"] .. ": " .. ($got["text"] or "<binary>"))
end
```

## WebSocket client — `ws_connect`, `ws_send`, `ws_recv`, `ws_close` (v0.74.0)

```
ws_connect(url[, opts])   -> numeric handle; opts: insecure (skip TLS verify),
                             headers (map), timeout (secs, default 30, connect+handshake)
ws_send(h, payload)       -> nil; string -> text frame, bytes/buffer -> binary
ws_recv(h[, timeout])     -> string | bytes | nil on timeout (default 30, 0 = forever)
ws_close(h)               -> true when live, false when unknown (never raises for that)
```

A synchronous client with **recv-driven control flow** — the shape every
stateful request/response protocol needs: send `register`, wait for the
`registered` frame, then issue requests and parse each response (an
`alertId` echoed back in a `closeAlert`, a pairing prompt to wait out).
A blind `(cat msgs; sleep) | websocat` pipeline only handles
fire-and-forget; this is the difference that turned the LG SSAP TV driver
from a bash FIFO coprocess into a plain Mix loop. Home-Assistant-style
device control and Grafana live are the same shape.

The contracts worth knowing:

- **`insecure: true`** skips TLS certificate verification — for the
  self-signed device endpoint (`wss://tv:3001/`), never for services with
  real certificates.
- **`ws_recv` returns `nil` on timeout** — an ordinary answer; poll
  again. Ping/pong never surface (answered internally). A **peer close
  RAISES** (catchable) and retires the handle: "no more frames, ever"
  must not be confusable with "no frame yet".
- A closed/raised handle is **retired** — further calls say
  `unknown ws handle` rather than repeating the close error.
- Handles are process-global numbers (the `sqlopen` pattern); the kernel
  reaps the sockets at exit, `ws_close` is the tidy path. One user per
  handle: a handle is checked out of the registry for the duration of a
  call, so a concurrent call on the SAME handle answers `unknown ws
  handle` rather than queueing.
- `ws_send` writes under the connect timeout: a very large frame on a
  slow link can raise mid-flush with bytes still buffered — the next send
  on that handle continues the partial frame (no framing corruption).

```mix
$h = ws_connect("wss://192.0.2.20:3001/", {insecure: true})
ws_send($h, json_encode({type: "register", payload: $manifest}))
loop
  $frame = ws_recv($h, 5)
  if $frame == nil then continue end          -- quiet: keep waiting
  $msg = json_parse($frame)
  if $msg["type"] == "registered" then break end
end
ws_send($h, json_encode({type: "request", uri: "ssap://api/getServiceList"}))
print(ws_recv($h, 10))
ws_close($h)
```

## Raw TCP client — `tcp_connect`, `tcp_send`, `tcp_recv`, `tcp_recv_line`, `tcp_close` (v0.78.0)

```
tcp_connect(host, port[, {timeout, tls, insecure}]) -> handle
tcp_send(h, payload[, {timeout}])       -> bytes sent (string/bytes/buffer)
tcp_recv(h[, {timeout, max}])           -> bytes | nil on timeout
tcp_recv_line(h[, {timeout, max}])      -> string (LF+CR stripped) | nil
tcp_close(h)                            -> bool
```

The stream-socket primitive for a line-or-binary protocol that UDP, WS
and HTTP don't cover — an SMTP/IMAP probe, a redis `PING`, memcached
stats, a banner grab. `tls: true` wraps the connection (ring-pinned
rustls, webpki roots); `insecure: true` skips certificate verification
for a self-signed endpoint. Handles are process-global numbers like
`sqlopen`/`ws_*`, one user per handle, reaped by the kernel on drop.

`tcp_recv` returns whatever bytes are available (up to `max`, buffered
bytes first) — **bytes, not a string**, because a stream has no message
boundary; `nil` on timeout is an ordinary answer (poll again), and a peer
**close RAISES** and retires the handle. `tcp_recv_line` is the
line-protocol form: it buffers across reads and returns one line with its
`\n` (and a trailing `\r`) stripped, so a caller speaking SMTP or redis
never hand-rolls a `\r\n` scanner over accumulated bytes. `max` caps the
line length (refused past it, so a peer that never sends a newline can't
grow the buffer without bound).

```mix
$h = tcp_connect("mx.example.com", 25, {timeout: 10})
print(tcp_recv_line($h, {timeout: 10}))          -- 220 banner
tcp_send($h, "EHLO probe.local\r\n")
loop
  $line = tcp_recv_line($h, {timeout: 5})
  if $line == nil then break end
  print($line)
  if not starts_with($line, "250-") then break end -- 250<space> = last line
end
tcp_close($h)
```

**Send deadline (v0.112.1).** Without options, `tcp_send` writes the
whole payload with each write bounded by the socket's 30 s write timeout,
so a reader that drains a few bytes at a time can stretch one send far
past 30 s. `tcp_send(h, payload, {timeout: 5})` instead bounds the WHOLE
send by one deadline, computed once (seconds; `0` waits forever, like
`tcp_recv`): writes are non-blocking and the wait for room happens on the
async runtime, so SIGTERM and Ctrl-C end it too. The deadline is checked
before every write, so a peer that keeps draining without ever filling
the socket cannot carry the send past it. On expiry it raises
`TCP_SEND_TIMEOUT` with `details: {written, total}` and retires the
handle, because a partly written message leaves the stream unusable.
Bytes already written stay written; the peer may have received part of
the payload. Ctrl-C in a plain script raises `TCP_SEND_INTERRUPTED` the
same way. On a `tcp_on` handle the timeout becomes the send's receipt
deadline (`0` keeps the source's 30 s bound), and expiry raises
`TCP_SEND_TIMEOUT` with `details: {total}` (the reader thread does not
report how much it wrote).

```mix
try
  tcp_send($h, $frame, {timeout: 2})
catch $msg, $err
  if $err.code == "TCP_SEND_TIMEOUT" then
    print("peer stalled after " .. $err.details.written .. " bytes")
  end
end
```

On unix a numeric `tcp_recv`/`tcp_recv_line` (and `ws_recv`) waits on the
async runtime rather than in a blocking read, the way `sleep()` does, so
SIGTERM and Ctrl-C end the wait at once (v0.112.1; before, a SIGTERM
waited for the read's timeout). Data already buffered is returned first,
however short the timeout, while traffic that delivers nothing (WebSocket
control frames, part of a line) still counts against it: a timed-out
`tcp_recv_line` returns nil and keeps the partial line for the next call.
Options, results and errors are those of
the blocking form. A pending read in a Class S handler still holds the
handler's turn for its duration, so `{timeout: 0}` in a `--serve`
citizen can still stall other handlers.

## Raw TCP server — `tcp_listen`, `tcp_accept`, `tcp_local_addr` (v0.112.0)

```
tcp_listen(host, port[, {backlog}])     -> listener handle
tcp_accept(listener[, {timeout}])       -> connected handle | nil on timeout
tcp_local_addr(handle)                  -> {host, port}
tcp_close(listener)                     -> bool
```

The listening half of the client above, so a script can be a small TCP
service (a fake line-JSON app for a test, a local control port) without
`socat`. `tcp_listen` binds and listens. `host` is required and there is
no default: `"127.0.0.1"` is the normal choice, and a non-loopback
address (`"0.0.0.0"`, `"::"`, a LAN IP) works only when you name it.
Port `0` takes an ephemeral port, and `tcp_local_addr` says which one.
`backlog` (default 128, 1 to 4096) bounds the connections the kernel
queues before `tcp_accept` takes them.

`tcp_accept` waits for one connection and returns an ordinary connected
handle: `tcp_send`, `tcp_recv`, `tcp_recv_line`, `tcp_on` and `tcp_close`
all work on it. `nil` on timeout (default 30 s, `0` waits forever) is an
ordinary answer and the listener stays usable. Listeners take their
numbers from `tcp_connect`'s counter, so a number is never both: a
connection verb given a listener raises `TCP_LISTENER`, and `tcp_accept`
given a connection raises `TCP_ACCEPT_HANDLE`. `tcp_close` on a listener
stops listening at once and returns `true`; `false` means it was already
closed.

```mix
-- A line-JSON echo server: one client at a time, plain blocking style.
$l = tcp_listen("127.0.0.1", 0)
$addr = tcp_local_addr($l)
print("listening on " .. $addr.host .. ":" .. $addr.port)
loop
  $c = tcp_accept($l, {timeout: 0})
  loop
    try
      $line = tcp_recv_line($c, {timeout: 30})
    catch $msg, $err
      break                                     -- the client hung up
    end
    if $line == nil then break end              -- idle client: drop it
    $req = json_parse($line)
    tcp_send($c, json_encode({ok: true, echo: $req}) .. "\n")
  end
  tcp_close($c)
end
```

Errors are structured; read `$err.code` from `catch $msg, $err`:

| Code | Raised when |
|---|---|
| `TCP_LISTEN_ADDR_IN_USE` | another socket already listens on the address |
| `TCP_LISTEN_PERMISSION` | the bind needs privilege (a port below 1024) |
| `TCP_LISTEN_ADDR_UNAVAILABLE` | `host` is not an address of this machine |
| `TCP_LISTEN_ADDRESS` | `host` does not resolve |
| `TCP_LISTEN_ARGUMENT` | a bad host, port or option |
| `TCP_LISTEN_FAILED` | any other bind or listen failure |
| `TCP_ACCEPT_HANDLE` | an unknown listener, or a connection handle |
| `TCP_ACCEPT_ARGUMENT` | a bad option |
| `TCP_ACCEPT_FAILED` | accept(2) failed on the listener |
| `TCP_HANDLE_LIMIT` | 1024 live server-side sockets: every listener and accepted connection holds a slot until it closes. The limit is server-side only; `tcp_connect` is not counted or limited |
| `TCP_LISTENER` | a connection verb was given a listener |

**Serve mode and Class C.** On unix every numeric `tcp_accept` waits on
the async runtime, like `sleep()`: SIGTERM and Ctrl-C end it at once, and
plain and Class S waits also recheck the interrupt flag every 250 ms. A
Class S handler still holds its turn while it waits. In a Class C async
body the numeric form waits on native readiness with the read permit
released, so other handlers keep running. For a `--serve` citizen the
event form is usually the better fit: `tcp_on($listener, "app.conn")`
moves the listener into a reader thread and delivers one event per
accepted connection (see Socket subscriptions below). A subscribed
listener refuses numeric `tcp_accept` (`SOCKET_SUBSCRIBED`) and
`tcp_close`; end it with `tcp_unwatch`.

**Ownership.** A listener, and every connection `tcp_accept` or a
subscribed listener hands out, belongs to the evaluator generation that
made it: retiring the generation (a `--serve` reload or shutdown, or the
evaluator going away) closes them, including one that is out in a Class C
`tcp_recv` at that moment (it closes when the read returns). `tcp_connect` handles keep their
process-wide lifetime. A reload's candidate runs while the old
generation still holds its listeners, so it cannot bind the same fixed
port (`TCP_LISTEN_ADDR_IN_USE`): a served listener should bind port `0`
and publish its port. Handing a fixed port across a reload is not
supported yet.

## Unix sockets — `unix_connect` (v0.115.0)

```
unix_connect(path[, {timeout, frame}])  -> handle (tcp_connect's handle space)
```

A client for a local unix-domain stream socket: systemd's Varlink
services (`/run/systemd/resolve/io.systemd.Resolve`, networkd's
`io.systemd.Network`) and other local services that speak a framed
protocol. The handle is an ordinary connected handle, so `tcp_send`,
`tcp_recv`, `tcp_recv_line`, `tcp_on` and `tcp_close` work on it unchanged.
`tcp_local_addr` refuses (`TCP_LOCAL_ADDR`): a unix socket has no TCP
address.

- `path` is an absolute filesystem path of at most 107 bytes. Abstract
  sockets are not offered.
- `timeout` (seconds, default 30) bounds the connect and each write.
  A listener whose backlog is full fails at once (`UNIX_CONNECT_BUSY`)
  instead of blocking the evaluator.
- `frame: "nul"` makes a "line" a NUL-terminated frame. `tcp_recv_line`
  returns the next frame without its NUL (no CR is stripped), and
  `tcp_on(h, cmd, {frame: "line"})` delivers one event per frame. Sends
  are verbatim: end each request with `chr(0)` yourself. The default,
  `frame: "line"`, keeps LF lines as `tcp_connect` does.

```mix
-- One Varlink call to systemd-resolved: NUL-framed JSON.
$h = unix_connect("/run/systemd/resolve/io.systemd.Resolve", {frame: "nul", timeout: 5})
tcp_send($h, json_encode({method: "io.systemd.Resolve.ResolveHostname",
  parameters: {name: "example.org"}}) .. chr(0))
$reply = json_parse(tcp_recv_line($h, {timeout: 5}))
tcp_close($h)
print(json_encode($reply.parameters.addresses))
```

| Code | Raised when |
|---|---|
| `UNIX_CONNECT_NOT_FOUND` | no socket file at `path` |
| `UNIX_CONNECT_PERMISSION` | the socket file's mode refuses this user |
| `UNIX_CONNECT_REFUSED` | a socket file with nothing listening behind it |
| `UNIX_CONNECT_BUSY` | the listener's backlog is full |
| `UNIX_CONNECT_TIMEOUT` | the connect did not finish within `timeout` |
| `UNIX_CONNECT_ARGUMENT` | a bad path or option |
| `UNIX_CONNECT` | any other connect failure |

A frame longer than `max` raises and retires the handle, whether or not its
NUL has arrived; from 0.115.0 an over-long LF line does the same. Ownership is `tcp_connect`'s: the handle lives for
the process until `tcp_close`.

Both UDP builtins above, all four `ws_*`, and the `tcp_*` family are **Network**-class (below), like `http_*` and `dns_lookup` —
and like those, the wait happens inline on the evaluator's thread. In a
`--serve` citizen that means a pending `udp_recv` blocks the whole event pump
for its duration; **never** pass `{timeout: 0}` there — unlike an HTTP call,
where the wait rides an in-flight request, a datagram wait with no sender is
unbounded and nothing can interrupt it.

## Socket subscriptions — `ws_on`, `tcp_on`, `ws_unwatch`, `tcp_unwatch` (v0.107.0)

```
ws_on(handle, command)                      -> source id ("ws:N")
tcp_on(handle, command[, opts])             -> source id ("tcp:N")
  opts: {frame: "line" | "bytes" (default), max: line length (default 65536)}
ws_recv(source[, timeout])                  -> string | bytes | nil (Class C)
tcp_recv(source[, {timeout, max}])          -> bytes | nil (Class C)
tcp_recv_line(source[, {timeout}])          -> string | nil (Class C)
tcp_on(listener, command)                   -> source id ("tcp:N") (v0.112.0)
tcp_accept(source[, {timeout}])             -> handle | nil (Class C)
ws_unwatch(source) / tcp_unwatch(source)    -> nil
```

The event-stream shape of the clients above. `ws_on`/`tcp_on` **move** an
existing `ws_connect`/`tcp_connect` handle into a reader thread owned by
the evaluator generation, and return a string source id. The reader is
the connection's **single owner** (tungstenite's TLS state is never
shared or raced), so numeric `ws_recv`/`ws_close`/`tcp_recv`/
`tcp_recv_line`/`tcp_close` on the subscribed handle refuse
deterministically (`handle N is a ws_on subscription — …`). Numeric
`ws_send`/`tcp_send` **keep working**: they route through the owner
thread's bounded command endpoint (a Send-safe channel + wake socketpair
registered at subscribe time, removed when the source retires), and
await a completion receipt. In a Class C body the send yields through
the class-C yield while waiting; in Class S / plain evaluation it blocks
bounded by the owner's send deadline. The owner writes non-blocking with
partial state retained (nothing is re-sent or dropped), arms `POLLOUT`
only while bytes are owed, and the wake socketpair is a control wakeup —
a send never cancels the subscription. Admission is bounded across a
send's **entire lifetime** — 64 ops and 64 MiB of payload per source,
counting queued + in-flight + parked behind a cancelled caller (the
reservation releases only when the receipt is answered or the command
is retired): a full queue raises `SOCKET_SEND_BUSY` at admission, and a
retiring source answers every outstanding receipt with
`SOCKET_SEND_CLOSED`. The 30 s receipt deadline is stamped **at
admission** (never restamped per queued hop) and checked absolutely
every poll loop — continuous incoming data or wake traffic cannot
stretch or starve it. A send that cannot finish in time fails its
receipt; if any byte may have reached the wire the source hard-closes
with one terminal event (`SOCKET_SEND_TIMEOUT`) — bytes are never
silently dropped, duplicated or re-sent.

**Events.** Frames arrive as events under the caller-chosen `command`
(1–64 chars of `[a-zA-Z0-9._:-]`, e.g. `ticker.frame`):

```json
{"watch": "ws:1", "frame": {"kind": "text", "data": "…"}}
{"watch": "ws:1", "frame": {"kind": "binary", "data": {"hex": "…"}}}
{"watch": "tcp:2", "frame": {"kind": "bytes", "data": {"hex": "…"}}}
{"watch": "tcp:2", "frame": {"kind": "line", "data": "…"}}
{"watch": "ws:1", "closed": {"reason": "connection closed by peer"}}
{"watch": "tcp:3", "accepted": {"handle": 7, "peer": {"host": "127.0.0.1", "port": 50122}}}
```

WS message boundaries and text/binary kinds survive. `tcp_on` defaults to
`frame: "bytes"` — ordered raw chunks of at most 64 KiB; `frame: "line"`
splits on LF (one trailing CR stripped) with `max` bounding a line.

**Listeners (v0.112.0).** `tcp_on` on a `tcp_listen` listener takes no
options. The reader parks in `poll(2)` on the listener and accepts each
connection as it arrives: the connection becomes a plain connected
handle, owned by the generation, and arrives as one `accepted` event in
order. The handler then reads it, or subscribes it with its own `tcp_on`:

```mix
$l = tcp_listen("127.0.0.1", 0)
tcp_on($l, "app.conn")
on app.conn
  if $event.args.accepted != nil then
    tcp_on($event.args.accepted.handle, "app.line", {frame: "line"})
  end
end
on app.line
  if $event.args.frame != nil then
    print($event.args.frame.data)
  end
end
```

Outside serve mode, `tcp_accept("tcp:3")` takes the next accepted handle
from the source (Class C, like the recv forms). Accepted connections that
are never delivered, because the source was unwatched or retired with
records still queued, are closed rather than left open with no name. At
1024 live server-side sockets the reader stops accepting and closes the listener
with one terminal event (`closed: {"reason": "handle_limit"}`); a queue
overflow closes it with `reason: "overflow"`, as for a connection.

**Ordering and overflow.** Records are an ordered, per-source FIFO bounded
by 4096 frames and 64 MiB of payload per evaluator (across all its
sources). When the bound is hit the reader **hard-closes the socket** and
publishes exactly **one** terminal event (`closed: {"reason": "overflow"}`)
— a frame is never silently dropped. A peer close (or a line over `max`
with no newline) also publishes exactly one terminal; afterwards the
source retires and a further recv raises `SOCKET_WATCH_HANDLE`.

**Class C recv.** `ws_recv("ws:1"[, timeout])` (and the tcp forms) park on
the source's FIFO through the evaluator's class-C yield — the read permit
is released while waiting, so other verbs keep their latency targets.
`nil` on timeout keeps the source usable (poll again); the terminal event
raises `SOCKET_CLOSED` and retires it. At most one recv parks per source;
a second refuses (`SOCKET_BUSY`). A mismatched verb refuses
(`SOCKET_KIND`). Because this form reads the FIFO the event pump also
consumes, recv on a *source* is refused in serve mode
(`SOCKET_RECV_SERVE`) — use `on <command>` there.

**Numeric Class C pull.** In a Class C async body (a read permit is
held), `ws_recv(handle[, timeout])` / `tcp_recv` / `tcp_recv_line` on a
**plain** numeric handle run as a pull instead of the sync builtin's
blocking read: the connection leaves the registry for the duration of
one call (at most one waiter per handle — ws and tcp handles count ids
independently, so the same number is two different connections; a
second concurrent recv on the same one refuses `SOCKET_BUSY`, a
subscribed handle `SOCKET_SUBSCRIBED`),
the socket goes non-blocking, and readiness/read `WouldBlock` are
awaited in a cancel-safe loop under the call's deadline — never via
periodic polls. Read state (TLS/frame buffers, `tcp_recv_line`'s
read-ahead) stays inside the connection across `WouldBlock`. `nil` on
timeout and a cancelled wait both return the connection to the registry
with its blocking mode and timeouts restored — the source stays usable
and a failed generation's resource survives for the next one; a peer
close or error raises (`SOCKET_CLOSED`) and retires the handle, exactly
like the sync path. Pull frames never enter the subscription FIFO, so
the event pump cannot steal them, and the numeric pull therefore also
works in serve mode. Plain and Class S numeric recv use the same pull
(v0.112.1), keeping the blocking form's options and error messages and
adding an interrupt-flag recheck every 250 ms, so SIGTERM and Ctrl-C end
the wait as they end `sleep()`. The pull's AsyncFd readiness await
is unix-only: on other targets the Class C interception falls through
to the sync builtin (honest Class S blocking semantics), never a
silently claimed yield.

**Ownership.** Sources belong to the evaluator generation:
`close_native_events`/generation teardown cancels, joins and retires every
source, and a failed `--serve` reload leaves the old generation's
subscriptions intact. `ws_unwatch`/`tcp_unwatch` cancel and join the
reader, drop queued frames, wake a parked recv with `SOCKET_WATCH_HANDLE`,
and emit **no** terminal event (an explicit close is not a peer close);
queued-but-unrun sends are answered with `SOCKET_SEND_CLOSED`, never
silently dropped. The reader parks in `poll(2)` on (socket, cancellation
pipe, command pipe) with an infinite deadline — no timer, so an idle
subscription costs ~zero context switches; a poll timeout exists only
while a send is pending. The socket is non-blocking, so cancellation
wins at the next poll wake (mid-frame TLS state survives in the stream
buffers).

**Limits and acceptance.** 16 sources per evaluator; max WS message 16 MiB
(connect-time cap); subscriptions Linux only (`SOCKET_UNSUPPORTED`
elsewhere, matching the pidfd-owned children). The numeric Class C pull
needs the unix AsyncFd await: off-unix the interception falls through
to the sync builtin — honest Class S blocking, never a silently claimed
yield. A busy subscription's in-flight read drains
in bounded read/write batches before rechecking cancellation and absolute
deadlines. Automatic WebSocket control writes also have a 30-second bound;
a peer that leaves a pong blocked cannot retain an owed write indefinitely.
The loopback acceptance tests execute the builtins
end-to-end through the real evaluator: the ~2 s delayed numeric recv with
a concurrent handler tick (the pull yields the read permit — the tick
lands while the recv is parked), same-connection send after subscribing
with the FIFO intact, timeout-then-reuse, a second same-handle waiter
refusing, close-while-parked retiring, and a cancelled pull leaving the
handle intact for the next generation. The *strict* "other verbs stay
under 1 ms while a recv is parked" acceptance and the 5 s idle
context-switch measurement remain explicit external acceptance, measured
by the coordinator's fixture rather than asserted here; they are never
weakened by these changes. Binary frames in event bodies are hex-encoded
— `from_hex()` on the way back.

## Capability classes

Each system builtin carries a [capability class](capabilities.md) used by the
[`--serve`](bus.md) sandbox's `check_capability` gate: `env` / `pid` /
`hostname` / `cwd` / `platform` / `which` / `net_watch` / `net_unwatch` /
`net_state` are **Env** (read-only inspection);
`run` / `run_rc` / `run_stream` / `spawn` / `kill` / `process_alive` / `chdir` /
`audio_watch` / `audio_unwatch` / `audio_state` / `exit` (and `panic` — see [errors](errors.md)) are **Process** (they touch the
OS process table or filesystem CWD); `shell_quote` / `sql_quote` / `sanitize` /
`random_password` / `uuid` / hashes / `base64_*` are **Pure**. An embedding
daemon can deny the Process class to run untrusted Mix without it spawning
subprocesses.

## See also

- [strings](strings.md) — concat, interpolation, the byte/codepoint/grapheme split
- [errors](errors.md) — `try`/`catch`, the `die` raised by `run`, `panic`
- [Bus messaging](bus.md) — `send` / `emit` / `on … end`; prefer mesh IPC over shelling out
- [ssh](remote.md) — `ssh_run` / `ssh_must` / `ssh_mix` for remote commands
- [shell mode](shell-mode.md) — the dispatch layer: chains, pipes, redirects, brace expansion
- [capabilities](capabilities.md) — the `--serve` sandbox classes in full
- [builtins index](builtins.md) — `getopt`, `read_file`, `stat`, `chmod`, the full set

```
mix builtins system   list every system builtin with its one-line description
mix what NAME         one-line description of a single builtin (e.g. mix what run_rc)
mix help              the full categorized builtin reference
```

---

<!-- page: https://mixos.dev/mix/tar/ (source: https://mixos.dev/mix/tar.md) -->

# tar — archives in-language: tar_list, tar_unpack, tar_pack

Archives are read and written by the language itself, so a verified artifact
can be unpacked without an external `tar` or `zstd`. Inside a MixOS machine
there is no such tool at all: `/bin/sh` is mix. On other hosts the same
builtins avoid depending on a distribution's import tooling. A signed
manifest pins a digest, `hash_file` compares against it, and `tar_unpack`
consumes the SAME verified file. No C codec ships in the binary: zstd is the
pure-Rust RFC 8878 implementation (structured-zstd), and gzip framing is
flate2 over its Rust backend.

One-line help for each builtin is `mix builtins tar_list` (or `tar_unpack`,
`tar_pack`).

## Codecs and the artifact profile

`codec` is explicit on every entry point: `"zstd"` (default), `"gzip"`,
`"none"`. The builtin decoder is the universal reader, so the artifact
profile below is a contract that any encoder must satisfy:

- **one tar, one zstd frame** — `tar_unpack`/`tar_list` drain the stream to
  true EOF: the zstd content checksum (XXH64, verified whenever the frame
  carries one; `tar_pack` always writes it) / gzip CRC are verified there,
  any non-zero decoded bytes after the tar end are refused, and raw input
  left unconsumed (a concatenated second zstd frame) is refused. Gzip is
  read **member after member**, as RFC 1952 allows (`pigz`, or `cat a.gz
  b.gz`): a tar split across several members unpacks, every member's CRC
  is checked, and an empty trailing member is harmless. A second whole tar
  in a later member is still non-zero data after the first tar's end and is
  refused. Trailing bytes that are not a gzip member, including zeros, raise
  `ARCHIVE_STREAM_CORRUPT`;
- **no dictionaries**;
- zstd levels are `1..=22` (default 7). Level 22 is the largest the builtin
  packs, because its 2^27 (128 MiB) window is exactly the decoder's ceiling.
  An artifact produced by an external zstd must not use `--long` beyond that
  window, and must decode with `tar_list` before it is trusted.

For artifacts that people unpack with stock tools, use `codec:"gzip"`
(`tar -xzf` works everywhere). Gzip levels clamp to 9.

## The builtins

| Call | Result |
|---|---|
| `tar_list(path[, opts])` | list of `{name,size,mode,uid,gid,kind,mtime}` — streaming, nothing extracted, stream verified; `kind` is `file`, `dir`, `symlink`, `hardlink`, `metadata` (a PAX global header) or `other` |
| `tar_unpack(path, dest[, opts])` | receipt `{files,dirs,symlinks,hardlinks,metadata,bytes,xattrs_restored,entries,implicit_dirs,trailing_padding,codec,warnings}` |
| `tar_pack(source, path[, opts])` | receipt `{files,dirs,symlinks,bytes,capabilities,codec,level}` |

`opts` keys are validated strictly — unknown keys raise.

## tar_unpack is safe by default, and staged

- `dest` **must not exist** (a dangling symlink there counts). A bare name
  such as `"out"` means the current directory. Extraction happens in a
  private `0700` staging sibling with an unpredictable name, held by
  descriptor from creation to commit: every member is created relative to
  it, one `O_NOFOLLOW` component at a time, so a staging name swapped in a
  writable parent cannot redirect a write. It is renamed into place only
  after the whole stream verifies, with `RENAME_NOREPLACE`, so anything that
  appears at `dest` in the meantime is never replaced. A kernel or
  filesystem without `RENAME_NOREPLACE` makes the commit fail closed: the
  unpack raises and the staging tree is rolled back. Failures restore
  traversable/writable staging-directory modes before removing the tree
  through the same descriptor. A cleanup failure is reported alongside the
  original error, with the staging name, rather than silently discarded.
- **`dest`'s parent must have no untrusted writer.** It must be owned by the
  caller's effective uid or by root, and must not be writable by group or
  other unless it has the sticky bit (as `/tmp`, where only an entry's owner
  may rename or remove it). Anything else is refused before staging is
  created, with nothing written. Another writer there could swap the staging
  directory between its creation and its use, or between the final identity
  check and the rename; refusing such a parent closes those windows. The new
  staging directory is also checked to be the caller's own, `0700` and
  empty before anything is extracted into it.
- Member names are validated on the *resolved* path (GNU longname and PAX
  smuggling land there): no absolute paths, no `..` components, UTF-8
  only (invalid bytes raise — the extractor never guesses what got
  extracted). A leading `./` is accepted and dropped, so GNU tar's
  `tar -C dir .` and `./name` archives unpack (hardlink targets too). A bare
  `./` (or `.`) entry names the extraction root: it must be a directory, and
  only its mode, owner and mtime are applied, to `dest` itself. `tar_list`
  shows it as `.`.
- Device, fifo and unknown entry types are **refused**. GNU sparse entries
  are refused by both the lister and extractor. A PAX global header (the
  first record `git archive` writes) is archive metadata: it is counted in
  the receipt's `metadata` and nothing is extracted for it.
- A corrupt or truncated stream (zstd frame checksum, gzip CRC or a cut-off
  stream, including an empty input or truncated zstd header) raises the
  structured code `ARCHIVE_STREAM_CORRUPT`. Match the code
  in the optional second `catch` binding, not the message text.
- Symlink targets must be relative and stay inside `dest`, judged from the
  link's own directory: `demo/lib/alias -> ../bin/demo` is fine,
  `demo/x -> ../../y` escapes and is refused. `..` may only lead the target
  (`../../a/b`), never follow a name (`a/../b` is refused): a `..` applied to
  a directory that is really a symlink would climb from wherever that link
  points. A target may end at another symlink, but never pass through one,
  in either order: a link whose target walks through an existing symlink is
  refused, and so is a symlink created where an earlier link's target walks.
  `tar_pack` applies the same rules, so a tree it packs always unpacks.
  A leading `./` and interior `.` components are dropped from the written
  target; a target of only `.` is written as `.`. Nothing is ever extracted
  *through* a symlink the archive created. Hardlinks may only target an
  earlier **regular file** (hardlink-to-hardlink is refused).
- `numeric_owner` restores uid/gid through the entry's descriptor, never
  following a link. It defaults to **true for root and false for everyone
  else**, as GNU tar does (`--same-owner` / `--no-same-owner`): an ordinary
  user's files keep their own uid and gid, because a non-root chown could
  still hand a file to any group the caller belongs to, and the archive
  should not choose which. With `numeric_owner:true`, a non-root caller gets
  the capability limit silently (the owner is skipped) rather than an
  error. Any other owner failure (an unmapped uid in a user namespace, a
  root-squashing filesystem) is listed in the receipt's `warnings`. When an
  entry does not end up with the owner the archive named (not restored, or
  restoring it failed), its setuid/setgid bits and `security.capability`
  are dropped (also listed in `warnings`): a special bit is only ever kept
  on the owner the archive named. Mode and mtime failures raise.
- Modes are restored as the archive gives them, as GNU tar does for root:
  a `0777` directory or `0666` file stays world-writable. Unpack untrusted
  archives into a tree whose modes you then check, or repack them.
- `xattrs` (default true) restores `SCHILY.xattr.*` records by hand, and by
  default ONLY the `user.*` namespace. `security.capability` also needs
  `keep_special_bits:true` (a capability is a privilege grant exactly like
  a suid bit, and suid/sgid are stripped from modes by the same rule).
  Every other namespace, `trusted.*`, POSIX ACLs (`system.posix_acl_*`,
  which can grant any user write access) and the rest of `security.*`
  (SELinux labels, IMA), needs `privileged_xattrs:true`. Restored xattrs are
  applied last, after owner and mode, because chown and data writes clear
  `security.capability`.
- `max_xattr_bytes` (default 16 MiB, at most 1 GiB) bounds the admitted
  xattr names and values held for the whole archive until the post-pass
  applies them; one archive of many small records cannot exhaust memory.
- Directory and symlink metadata (mode, mtime, owner) is applied in a
  children-first post-pass, so directory mtimes stick. A `./` root entry's
  metadata is applied after the commit, through the descriptor of what is
  now `dest`: until then the staging directory stays the caller's own and
  `0700`, so an archive-named owner can never rename it in a sticky parent,
  and a restrictive root mode cannot lock the caller out of the post-pass.
  The tree is already in place by then, so a failure there is a `warnings`
  entry rather than an error. When several `./` entries appear, the last
  one wins.
- Limits: `max_entries` (200k, counting both members and every parent
  directory created implicitly for a member whose directory the archive
  does not list; the receipt's `implicit_dirs` reports those),
  `max_bytes` (64 GiB of file bytes),
  `max_name` (4096), and `max_stream_bytes` (16 GiB). The last bounds the
  **decoded** stream, including headers, metadata, file data and all trailing
  zero padding, across parsing and final verification. An entry's declared
  size must fit the remaining `max_bytes` before its file is created, and
  copying also enforces that remaining budget.
- Each GNU longname, GNU longlink or PAX extension payload is limited to
  **64 KiB**, independently of `max_stream_bytes`, before buffering. GNU
  name/link payloads additionally obey `max_name` plus one terminating NUL.
  Once `max_entries` is reached, the next extension header is refused before
  reading its body. `tar_list` accepts `max_entries`, `max_name` and
  `max_stream_bytes` too.

## tar_pack

Deterministic (sorted, parents-first) walk of a source **directory**:
numeric owner, mtime and mode are preserved, and suid/sgid are stripped
unless `keep_special_bits:true`. Only that same opt-in captures
`security.capability` into a `SCHILY.xattr` PAX record, so capability
round-trips require opting in at both ends (root-only to apply on unpack).
The source directory must not be a symlink. Directory traversal retains
opened directory descriptors; children are opened with `O_NOFOLLOW`, with
metadata and capabilities read from the opened file. Queued directories
remain pinned if their pathnames are replaced. A detected inode replacement
between classification and opening raises. Device and fifo members are
refused. The output file is created new (`0600`) and is never overwritten.
An output inside the source directory is refused before it is created, and
the walk also refuses the output's own inode if it reaches it another way.
A file whose size changes while it is packed raises rather than writing a
header that disagrees with its data. Two packs of an unchanged tree are
byte-identical.

## Round-trip

```
tar_pack("/var/tmp/stage", "/var/tmp/app.tar.zst", {codec:"zstd", level:11})
$receipt = tar_unpack("/var/tmp/app.tar.zst", "/var/tmp/app")
-- receipt.xattrs_restored counts applied records; capabilities only when
-- keep_special_bits was set on BOTH ends.
```

---

<!-- page: https://mixos.dev/mix/variables/ (source: https://mixos.dev/mix/variables.md) -->

# variables — sigils, assignment & scope

Every Mix variable carries a `$` sigil. There is no separate declaration —
assignment **is** the declaration. Reading an unbound variable raises a runtime
error; the `$` sigil is also how Mix tells a variable apart from a bare command
word at the shell-first classifier. This page covers the sigil, assignment,
reading (bound and unbound), `${...}` string interpolation, the `env()` builtin,
positional `$1`/`$2` script arguments, and the one rule that trips up everyone
coming from bash or Python — **assignment inside a function does not write
through to a global**.

Related: [strings](strings.md) for the full quoting/interpolation rules,
[functions](functions.md) for the deep function-scope detail, and
[control flow](control-flow.md) for loop variables.

## The `$` sigil is mandatory

Read and write a variable with a leading `$`:

```mix
$x = 42
print($x)            -- 42
print($x + 8)        -- 50
```

```text
42
50
```

A **bare** `x = 1` is *not* a Mix assignment — the classifier is shell-first, so
it tries to run a command named `x`:

```text
$ mix -c 'x = 1'
mix: x: No such file or directory (os error 2)
```

The fix is always the same: write `$x = 1`. This is the single most common
first error. The sigil is what makes `$x = 1` parse as Mix rather than dispatch
to the shell.

### Variable names

A name after the `$` is ASCII letters, digits and underscores. Names are
**case-sensitive** — `$Foo` and `$foo` are different variables:

```text
$ mix -c '$Foo = 1
print($foo)'
Runtime error at line 2: undefined variable '$foo'
```

Because the sigil already marks the word as a variable, **keyword lexemes are
fine as variable names** — `$to`, `$end`, `$step`, even `$fn` all bind and read
normally. Un-sigiled name positions still reject keywords: `function step()` is
a parse error (`expected identifier, got Step`). See [keywords](keywords.md).

## Assignment, concatenation & reassignment

Assignment creates the variable in the current scope if new, or updates it in
place if it already exists in a visible scope:

```mix
$n = 1
$n = $n + 1
$n = $n + 1
print($n)            -- 3
```

```text
3
```

**Concatenation is `..`, never `+` or `.`** — `+` is numeric addition, and `.`
is field access:

```mix
$name = "world"
print("hello " .. $name)
```

```text
hello world
```

Statements are separated by a newline or `;`. Prefer newlines in script files;
the compact `mix -c '$x = 1; print($x)'` form is equivalent.

### Indexed & field assignment

Assignment also targets list elements and map fields:

```mix
$l = [1, 2, 3]
$l[0] = 9            -- lists are 0-indexed
$l[-1] = 7           -- a negative index writes from the end
print($l)

$m = { host: "a" }
$m.host = "b"        -- field assignment
$m.to = "kw"         -- keyword field names are fine
$m["port"] = 80      -- index assignment creates the key
print($m)
```

```text
[9, 2, 7]
{host: b, to: kw, port: 80}
```

Writes are **loud** where reads are forgiving: an out-of-range list *write*
(`$l[5] = 9` on a 1-element list → "list index 5 out of range") and an
index-assign into a scalar (`$s[0] = "H"` on a string → "cannot index-assign
into string") both raise, while the corresponding *reads* (`$l[5]`,
`$m["nope"]`) return `nil`. The asymmetry is deliberate — a lost write is data
loss, a missing read is often just a probe. Full indexing rules:
[collections](collections.md).

## Reading an unbound variable raises

Mix has no implicit `nil` for an unread name. Touching one that was never
assigned is a hard `RuntimeError`:

```text
$ mix -c 'print($nope)'
Runtime error at line 1: undefined variable '$nope'
```

This is deliberate — a typo in a variable name fails loudly instead of silently
reading empty. If you genuinely need a "maybe-set" variable (e.g. for an
`if $x == nil` guard), **pre-initialise it to `nil` first**:

```mix
$maybe = nil
if $maybe == nil then
  print("was nil")
end
```

```text
was nil
```

**All-digit names** (`$0`, `$1`, `$2`, … — the positional script arguments) are
the one exception — an unset positional reads as `nil` rather than raising (see
[Positional arguments](#positional-arguments)).

## `${...}` string interpolation — scope → env → nil

Inside **double quotes**, `${name}` interpolates. The lookup walks
**scope first, then the process environment, then literal `nil`**:

```mix
$user = "alice"
print("hi ${user}")          -- scope hit
```

```text
hi alice
```

```text
$ GREETING=howdy mix -c 'print("env says: ${GREETING}")'
env says: howdy
```

A scope binding always wins over an environment variable of the same name — the
env fallback only fires when the name is **truly unbound in scope**. A variable
bound to `nil` is still a scope hit, so it shadows the env:

```text
$ ZED=fromenv mix -c '$ZED = nil
print("[${ZED}]")'
[nil]

$ ZED=fromenv mix -c 'print("[${ZED}]")'
[fromenv]
```

An entirely unknown name interpolates as the text `nil`:

```text
$ mix -c 'print("[${missing}]")'
[nil]
```

### A bare `$name` in double quotes is LITERAL

This is the opposite of bash, and a prime trap. Only `${...}` (with braces)
interpolates; a bare `$name` is literal text:

```mix
$name = "bob"
print("literal $name here")
```

```text
literal $name here
```

To emit a literal `$` next to braces, escape it: `"\$5"` → `$5`. When in doubt,
prefer `..` concatenation over interpolation — `"hi " .. $name` is unambiguous.

`${...}` is **string-only syntax** — it is not a general expression form.
`print(${x})` outside a string is a lexer error:

```text
$ mix -c '$x = 9
print(${x})'
Lexer error at line 2:7: expected variable name after '$'
```

### Dotted paths interpolate into maps

`${map.field}` walks a map by dotted path inside the interpolation:

```mix
$cfg = { host: "node1", port: 8080 }
print("connect ${cfg.host}:${cfg.port}")
```

```text
connect node1:8080
```

A missing map, or a missing key on a bound map (`${cfg.missing}`), interpolates
as the text `nil`, same as an entirely unknown name.

### `'single quotes'` are fully raw

Single-quoted strings interpolate **nothing** — no `${...}`, no `~`, no escapes
beyond `\'` and `\\`. Use them when you want the literal characters:

```text
$ mix -c "\$x = 9
print('raw \${x} \$x')"
raw ${x} $x
```

See [strings](strings.md) for the complete quoting matrix.

## `env()` — explicit environment read

`${X}` consults the environment only as a *fallback* after scope. When you want
to read the environment unconditionally — ignoring any same-named Mix variable —
call the `env()` builtin. A missing variable returns the **empty string** (it
never raises):

```text
$ MYVAR=hello mix -c 'print(env("MYVAR"))
print("[" .. env("NOSUCH") .. "]")'
hello
[]
```

| Form | Looks up | Missing → | Same-named Mix var |
|---|---|---|---|
| `"${X}"` | scope, then env | `nil` text | scope **wins** |
| `env("X")` | env only | `""` (empty string) | ignored |

## Positional arguments

When you run a script file, its path lands in `$0` and the command-line
arguments in `$1`, `$2`, … as strings:

```mix
-- pos.mix
print("script: " .. $0)
print("first: " .. $1)
print("second: " .. $2)
```

```text
$ mix pos.mix apple banana
script: pos.mix
first: apple
second: banana
```

An unset positional reads as `nil` (not an error — the one exception to the
unbound-raises rule). The exemption is by **name shape**: any all-digit name
reads `nil` when unset — `$15` is `nil` even when only two args were passed,
and `$0` is `nil` under `mix -c` (no script file):

```text
$ mix -c 'print($1)'
nil
```

Positionals interpolate in double quotes like any other name —
`"first is ${1}"` → `first is apple`.

For the whole argument vector as a list, use the `args()` builtin — the same
arguments the positionals index, so `args()[0]` is `$1`:

```mix
-- argv.mix
print(args())
print(length(args()))
```

```text
$ mix argv.mix one two three
[one, two, three]
3
```

`args()` pairs with `getopt(args(), spec)` for flag parsing — see
[builtins index](builtins.md).

## Scope: top level vs functions

At the **top level** there is one global frame. A variable assigned anywhere at
the top level is visible everywhere after it, and a loop variable still holds its
last value after the loop ends:

```mix
for each $x in [1, 2, 3]
  $last = $x
end
print($last)
```

```text
3
```

### Assignment in a function does NOT write through to a global

A function gets its **own frame**. It can *read* an outer/global variable
(reads fall through to the global frame), but **any `$x = …` assignment inside a
function binds a function-local** — it never updates the outer variable:

```mix
$g = 1
function bump()
  $g = 99           -- binds a LOCAL $g, does NOT touch the global
end
bump()
print($g)           -- still 1
```

```text
1
```

Reading through to an outer variable works fine:

```mix
$base = 100
function show()
  print($base)      -- reads the global
end
show()
```

```text
100
```

This holds for accumulator patterns — a helper doing `$count = $count + 1`
leaves the caller's `$count` unchanged — and for `$rc` / `$result` too: on a
`send` the Bus runtime writes them **into the current frame**, so a `send`
inside a function updates them for that function's body only. The caller's
`$rc` is untouched (and still unbound at the top level if no top-level `send`
has run). There is **no `global` keyword** by design.

### Binders shadow inside a function

Names a function *introduces* — a `for each $x` / `for $i = …` loop variable, a
`catch $e`, a `parse … with $a $b` target — bind in the function's own frame,
**shadowing** a same-named caller/global variable rather than clobbering it:

```mix
$x = "outer"
function f()
  for each $x in [1, 2, 3]
    $y = $x           -- $x is function-local here
  end
end
f()
print($x)             -- still "outer"
```

```text
outer
```

The same holds for `catch $e` and `parse "one two" with $a $b` inside a
function — the outer `$e` / `$a` read unchanged after the call. At the **top
level** there is no shadowing: everything is one global frame, so a top-level
loop variable overwrites a same-named global and persists after the loop.

### The pass-in / return / reassign triad

To propagate state out of a function, thread it through three steps:
**(1) pass the value in** (explicit read), **(2) `return`** the new value, and
**(3) reassign at the call site** (the write):

```mix
$g = 5
function inc($n)
  return $n + 1
end
$g = inc($g)        -- pass in, return, reassign
print($g)           -- 6
```

```text
6
```

Return a map to update several values at once. Parameters pass **by value**
(a number/list/map is copied in), so mutating a parameter inside the function
never reaches the caller either — the `return` + reassign is always the channel.
Lambdas and closures follow the same rules (a closure *captures* its defining
scope for reads, but a write still binds a local). The full function-scope
detail — closures, captures, recursion, HOF lambdas — lives in
[functions](functions.md).

## Quick reference

| Thing | Rule | Example |
|---|---|---|
| Sigil | every variable is `$name` | `$x = 1` |
| Bare name | misparsed as a shell command | `x = 1` → "No such file" |
| Names | ASCII letters/digits/`_`, case-sensitive | `$Foo` ≠ `$foo` |
| Keyword names | fine with the sigil | `$to = 1`, `$end = 2` |
| Concat | `..` (not `+` or `.`) | `"a " .. $x` |
| Unbound read | raises `RuntimeError` | `$nope` → error |
| Unbound positional | all-digit names read as `nil` | `$1` (unset) → `nil` |
| `${X}` in `"..."` | scope → env → `nil` text | `"${user}"` |
| Bare `$X` in `"..."` | **literal** text | `"$user"` → `$user` |
| `'...'` | fully raw, no interpolation | `'${x}'` → `${x}` |
| `env("X")` | env only, missing → `""` | `env("HOME")` |
| Indexed write | loud on out-of-range; the read is `nil` | `$l[5] = 9` → error |
| Assign in function | binds a **local**, never the global | use return + reassign |
| Binders in function | shadow, never clobber the outer var | loop var, `catch $e` |

## See also

- [strings](strings.md) — quoting, `${...}` vs `$name`, escapes, `~` expansion
- [functions](functions.md) — function-local binding, closures, the triad in depth
- [control flow](control-flow.md) — loops and the variables they bind
- [collections](collections.md) — lists/maps, indexing, the read-`nil` / write-error asymmetry
- [keywords](keywords.md) — reserved words and where they are allowed as names
- [builtins index](builtins.md) — `env`, `args`, `getopt`, and the rest
- [Bus messaging](bus.md) — `$result` / `$rc` after a `send`

```
mix help              the full categorized builtin reference
mix what env          one-line description of env() (or any name)
mix what args         one-line description of args()
mix keywords          list the reserved words
```

---

<!-- page: https://mixos.dev/mixos-mcp/ (source: https://mixos.dev/mixos-mcp/README.md) -->

# mixos-mcp

`mixos-mcp` is an MCP stdio server for agents. Install the binary at
`/opt/mixos/bin/mixos-mcp` and register the MCP server as `mixos`.
It ships in the server prefix archive. Its package, binary and component
are the [single naming exception](../docs/decisions/2026-10-19-mcp-program-name.md).

## Connection

The server starts without a Bus connection. The first Bus tool connects
using `libs/bus`. `MIXOS_NODED_URL` overrides the node configuration URL;
otherwise the native client's node config discovery applies, including
`MIXOS_NODE_CONFIG`, `MIXOS_ETC` and the user/system defaults.

Set `MIXOS_BROKER_ACCOUNT` to the broker's operating-system account and
`MIXOS_BUS_SOCKET` to the session's Unix socket. With either set, verified
Unix ingress is required and connection failures never fall back to TCP.
Without an explicit socket, the node config or MixOS runtime directory
provides the endpoint. Without either variable, the native WebSocket client
uses the discovered URL. Calls are never replayed after reconnecting.

```json
{
  "mcpServers": {
    "mixos": {
      "command": "/opt/mixos/bin/mixos-mcp",
      "env": {
        "MIXOS_NODED_URL": "ws://192.0.2.10:4200/ws",
        "MIXOS_BROKER_ACCOUNT": "user",
        "MIXOS_BUS_SOCKET": "/run/mixos/session/4/noded/bus.sock"
      }
    }
  }
}
```

## Tools

Each name below is exposed as `mcp__mixos__<name>` in Claude Code.

- `bus_call`, `bus_list_services`, `bus_node_info`, `bus_list_peers`, `noded_ping`
- `term_list`, `term_snapshot`, `term_type`, `term_tab`, `term_pane`
- `log_tail`, `log_search`
- `app_describe`, `app_commands`, `app_execute`
- `desktop_windows`, `desktop_window_wait`
- `context_search`, `index_workspace`, `knowledge_digest`, `knowledge_brief`
- `skills_retrieve`, `skills_store`, `skills_refine`, `skills_graduate`,
  `skills_list`, `skills_delete`
- `docs_feedback`, `journal_feedback`, `memory_feedback`, `journal_supersede`
- `mix_execute`, `mcp_status`

### Application commands

`app_describe {service}` calls `app.describe` on that Bus service.
`app_commands {service}` calls `<service>.commands`. Its `result` contains
the application's command rows unchanged: `id`, `label`, `menu`, `shortcut`,
`more` (when present), `enabled` and `checked`, plus any further metadata.

`app_execute {service, id, params?}` calls `<service>.execute` once with
`{id}` or `{id, params}`. `service` is a Bus service name such as
`"busviewer"`, `id` is a dotted command id such as `"file.refresh"`, and
`params` is an optional JSON object. Parameters are forwarded unchanged as
a sibling of `id`; the application owns validation and may refuse unsupported
parameters. Successful calls return `{service, command, result}`; application
error messages from the Bus client pass through unchanged as tool errors.
The same error-text pass-through and prefix removal apply to `app_describe`,
`desktop_windows` and `desktop_window_wait` through their shared native helper.

Retired tools: `app_actions_list`, `app_action_invoke`, `app_controls_list`,
`app_control_get`, `app_control_set` and `app_control_wait` have been removed
without aliases. Use `app_commands` and `app_execute` for registry commands,
and `app_describe` to discover an application's state verbs. These retired
tool names must not be reused.

### Knowledge tools

Knowledge tools retain their ranking, indexing, feedback and skill-learning
behaviour. By default they send `indexd.<action>` requests to `indexd` on
the selected Bus. An absent backend returns an explicit tool error.
Skill refinement also needs a configured LLM backend. Settings are MixOS strict-data files:
`knowledge.conf.mix`, `domains.conf.mix`, `skills.conf.mix` and `llm.conf.mix`.
LLM Bus providers use the same broker. `api_key_cmd` is Mix source, executed
by `/opt/mixos/bin/mix -c`.

### Host indexd from a desk

When a desk cannot reach the host's Bus, select SSH in
`$MIXOS_ETC/knowledge.conf.mix` (normally `~/.config/mixos/knowledge.conf.mix`):

```text
indexd: {
    transport: "ssh",
    target: "indexd",
    ssh_host: "user@host.example",
    ssh_command: ["/opt/mixos/bin/indexd", "bridge"],
    call_timeout_secs: 120
}
```

Install indexd on the host and configure key-based SSH access for the desk's
user. The client runs `ssh -T -o BatchMode=yes -o ServerAliveInterval=30`
with the configured host and command. The host command runs in the remote
login shell; use trusted command arguments. `indexd bridge` uses the host's
local Bus; `target` selects the address only in Bus mode.

One bridge is shared by knowledge tools for the MCP server's lifetime,
with one request in flight at a time. Each call has a deadline, including
queueing and retries. A broken pipe, exited child or bridge transport failure
gets one restart and retry; an application error is returned immediately.
A timeout discards the child and returns an error without replaying the call.
A retried mutation may already have executed, so retry is not an exactly-once
guarantee. Normal MCP shutdown closes stdin and reaps the bridge.
Restart the MCP server after changing transport settings.

Missing settings default to `transport: "bus"`, `target: "indexd"`, the
command above, an empty `ssh_host` and a 120-second call deadline. SSH mode
requires `ssh_host`. When a Bus route is available, select
`transport: "bus", target: "indexd.host.example.bus"` instead. Presence is
checked with `indexd.stats` at the configured target, including routed targets.

The default client domain map expands the user's home for `~/Projects/mixos`
(`mixos`), `~/.mix` (`mix`), `~/.ns` (`ns`) and `~/.mc` (`mc`). Custom
`domains.conf.mix` maps override these defaults. `index_workspace` expands
only a leading `~` or `~/`, resolves the workspace to an absolute path, and
sends absolute file paths and content to indexd.

Terminal tools preserve explicit pane selection and instance checks. Native
application tools require an exact service and semantic target. Read-only
tools do not invoke mutations; arbitrary `bus_call` and `mix_execute` can.
Mix execution runs in an isolated worker with bounded output.

## Logging and tests

Stdout is reserved for MCP. Logs go to stderr, journald and
`~/.local/log/mixos/mixos-mcp.log`. Arguments and results are redacted by
default; `RUST_LOG=mixos_mcp=trace` explicitly enables full arguments.
`--version --json` reports build provenance without starting MCP or the Bus.

Package tests cover parameter translation, target guards, output schemas,
redaction and provider decoding. The stdio integration test uses the real
fixture broker, including verified Unix ingress and lazy reconnection.
An in-process fake application checks command listing, execute request bodies
with and without parameters, and unchanged application error messages.
It also checks configured knowledge targets, paginated re-indexing and
absolute file metadata. SSH client tests use a local Mix fake bridge through
a test-only command hook; no SSH connection or indexd process is required.

---

<!-- page: https://mixos.dev/mixtrayd/ (source: https://mixos.dev/mixtrayd/README.md) -->

# mixtrayd

`mixtrayd` is the data service behind the MixOS tray popup, `mixtray`. It
registers on the noded Bus as `mixtrayd` and answers one verb,
`mixtrayd.snapshot`, with four tabs of state:

| Tab | Source |
|---|---|
| COS | systemd `ActiveState` for the MixOS units (system and user managers) |
| BUS | the services noded has registered (`noded.list`) and mesh peers (`noded.peers`) |
| MIX | the installed `mix` binary and its version |
| SSH | host files in `~/.ssh/hosts/`, their trash, keys in `~/.ssh/keys/`, and probe results |

Each tab carries its own `error` field, so one failing source does not blank
the others. The daemon polls nothing: it reads its sources when a snapshot is
asked for.

## Live updates

The daemon subscribes to systemd's unit signals on the system and user buses
and watches `~/.ssh/config`, `~/.ssh/hosts/` and `~/.ssh/keys/`. It keeps a
revision that moves whenever a COS unit changes, one of those files changes,
or an SSH probe starts or finishes. Every snapshot
carries the revision it was read at. `mixtrayd.wait` takes a revision and
answers with a new snapshot as soon as the revision moves past it, or after
45 seconds, inside the Bus client's 60-second call limit. While the popup is
open it keeps one wait running and starts the next as each one returns, so a
unit's state changes on screen as systemd reports it.

## Control

The COS tab can start, stop and restart a unit through the `mixtrayd.control`
verb. A system unit goes through hostd's `unit.control` verb: hostd is root,
and its grant `mixtray-units` names the only units this daemon may act on, so
no sudo or polkit prompt is involved. The daemon refuses `hostd.service` and
its own unit, and it marks each unit it can control in the snapshot.

Every control action is recorded as a hostd receipt, and `hostd.undo` refuses
it, since a restart has no undo.

## SSH hosts

Each host is one file in `~/.ssh/hosts/`, named after its alias and holding a
single `Host` line, which `~/.ssh/config` pulls in with
`Include ~/.ssh/hosts/*`. Dotfiles in that directory are shared snippets, not
hosts. The `mixtrayd.ssh` verb takes an `action`:

| Action | Fields | Effect |
|---|---|---|
| `probe` | `ids` (empty for every usable host) | runs `ssh ALIAS true` in batch mode, four at a time, 10 s each |
| `create` | `name`, `hostname`, `port`, `user`, `key` | writes a new owner-only host file using `~/.ssh/keys/KEY`; never overwrites one |
| `trash` | `id` | renames the file `.trashed-ID` |
| `restore` | `id` | renames it back, refusing to replace a live host |
| `purge` | `id` | deletes a trashed host; a live host must be trashed first |

The popup handles Connect (an `ssh ALIAS` terminal) and Edit (the host file)
itself, since those run in the desktop session, not the daemon's.

## Use

```
mixtrayd serve                   # the daemon (the default)
mixtrayd snapshot                # print one snapshot from the running daemon
mixtrayd wait REVISION           # print the next snapshot once a COS unit changes
mixtrayd control UNIT ACTION     # start, stop or restart one controllable unit
mixtrayd ssh probe [ID...]       # test every usable host, or the ones named
mixtrayd ssh create NAME HOSTNAME PORT USER KEY
mixtrayd ssh trash|restore|purge ID
mixtrayd --version
```

## Not yet

- MIX scripts, runs and trash have no MixOS source yet, so the MIX tab
  reports only the binary.

---

<!-- page: https://mixos.dev/monitor/ (source: https://mixos.dev/monitor/README.md) -->

# Monitor

Monitor is the task manager. It shows what [monitord](../monitord/README.md)
reports, for this node or for any node on the mesh: the processes, and graphs
of CPU, memory, each disk and each network interface over the last minute.
It reads nothing from the system itself, so a node with no desktop can be
watched from one that has one. The reasons are in the
[monitord and Monitor decision](../docs/decisions/2026-10-16-monitord-and-monitor.md).

## The window

- **Processes:** every process, sorted by any column (click a header; click
  it again to reverse), filtered by name or command line, or shown as a tree
  with parents above their children. CPU is a share of the whole machine:
  one busy core of eight is 12.5.
- **Performance:** CPU, memory, each disk and each network interface down
  the side, each with a small graph. The chosen one fills the rest: a
  minute's graph and its figures. CPU adds a graph for every logical
  processor; a disk adds its read and write rates and its filesystems; an
  interface its receive and send rates.
- **Node:** the chooser in the tool bar lists this node and the mesh peers.
  Choosing one reads that node's monitord as `monitord.<node>.bus`. The
  graphs start full: Monitor asks monitord for the last minute first.

Monitor reads once a second. Pause (Ctrl+P) holds the readings still;
Refresh (Ctrl+R) reads once.

## End task and Kill

End task (Delete) asks the selected process to finish (SIGTERM). Kill
(Shift+Delete) stops it at once (SIGKILL). Both act only on this node's
processes, as the person running Monitor, and the kernel decides whether
they may: the same as `kill` in a terminal. They are off while another node
is shown. Acting on another node, or as another user, is
[hostd](../hostd/README.md)'s job.

## Agents

Everything in the window is a command or a verb, under `monitor`:

| Verb | Body | Does |
|---|---|---|
| `monitor.info` | — | The window's state: node, page, section, sort, filter, selection, and the latest readings |
| `monitor.rows` | — | The process rows in the order shown |
| `monitor.node` | `node` (a name, or null for this node) | Watch another node |
| `monitor.tab` | `tab` (`processes` or `performance`) | Show a page |
| `monitor.section` | `section` (`cpu`, `memory`, `disk:<name>`, `net:<name>`) | Show one performance section |
| `monitor.sort` | `column`, optional `reverse` | Sort the table |
| `monitor.filter` | `text` | Filter the table |
| `monitor.tree` | `on` | Tree or flat |
| `monitor.select` | `pid` (or null) | Select a row |
| `monitor.refresh` | — | Read the node now |
| `monitor.commands`, `monitor.execute` | `id` | List and run commands (`process.end`, `view.pause`, ...) |
| `monitor.dialog`, `monitor.theme`, `monitor.show`, `monitor.quit`, `monitor.ping` | | As every MixOS app |

The window's drive verbs (`monitor.ui.*`, `monitor.window*`) are the
toolkit's, described in [driving an app](../docs/drive.md).

```mix
send monitor monitor.node node=beta
send monitor monitor.sort column=memory
send monitor monitor.rows
```

## Running it

```text
monitor [--node NAME] [--noded-url URL] [--service NAME]
```

A second launch raises the first window. `--node` starts on a mesh node
instead of this one.

## Testing

```text
cargo test -p monitor -p vitals
```

The engine (`vitals`) is tested without a window or a Bus. The window is
checked by offscreen snapshots (`apps/monitor/tests/snapshots/`); run with
`UPDATE_SNAPSHOTS=1` to redraw them, and look at the images before
committing. The snapshot suite also times the representative workload, a
2,000-process table and a 64-core grid, and prints it.

---

<!-- page: https://mixos.dev/monitord/ (source: https://mixos.dev/monitord/README.md) -->

# The system monitor service

`monitord` runs once on every MixOS host, as its own unprivileged user. It
samples the system every second, keeps history, and answers questions about
the host on the Bus. It only reads. The reasons are in the
[monitord decision](../docs/decisions/2026-10-16-monitord-and-monitor.md).

Monitor, the task manager window, draws what monitord serves. Agents and
scripts ask it directly.

## Asking it

On the Bus, the service is `monitord`. Any node's monitord is reachable
over the mesh as `monitord.<node>.bus`:

```mix
send monitord monitord.snapshot
print($reply.cpu.busy)

send monitord.alpha.bus monitord.processes sort=memory limit=5
```

Every verb is a query: it changes nothing. A refusal comes back with `rc`
10 and a body whose `status` says why: `bad_request`, `not_found`,
`unknown_verb`, `failed` or `busy`.

| Verb | Body | Returns |
|---|---|---|
| `monitord.status` | — | Version, uptime, sample interval, whether the process sampler is running, and the history database's size and retention |
| `monitord.snapshot` | — | The system now (below) |
| `monitord.processes` | `sort`, `reverse`, `limit`, `filter`, `user`, `tree`, `kernel_threads` | The process table |
| `monitord.process` | `pid` | One process in full |
| `monitord.series` | — | The history series held: `live` and `stored` |
| `monitord.history` | `series`, `from` or `since`, `to`, `max_points` | Points for each series |

Unknown body fields are refused, so a typo is an error, not a silent
default.

### `monitord.snapshot`

Rates and percentages are over the last sample interval (`interval_s`).
Sizes are bytes; rates are per second.

- `host`, `ts` (Unix seconds), `uptime_s`, `boot_time`.
- `cpu`: `model`, `cores`, and `busy`, `user`, `system`, `iowait`, `steal`
  in percent; `per_core`, a list of the same per CPU with `mhz`;
  `context_switches_ps`, `forks_ps`.
- `memory`: `total`, `available`, `used` (`total - available`), `free`,
  `cached`, `buffers`, `shared`, `dirty`. `swap`: `total`, `used`, `free`.
- `load`: `one`, `five`, `fifteen`, `runnable`, `tasks`.
- `pressure`: for `cpu`, `memory` and `io`, the share of time tasks
  stalled (`some`, and `full` where the kernel reports it), each as
  `avg10`, `avg60`, `avg300`. Absent on kernels without PSI.
- `tasks`: `total`, `running`, `blocked`.
- `disks`: each whole disk with `model`, `rotational`, `read_bps`,
  `write_bps`, `reads_ps`, `writes_ps` and `busy` (percent of the interval
  with I/O in flight). Loop and RAM devices are left out.
- `filesystems`: each real filesystem once per device, with `mount`,
  `device`, `kind`, `total`, `used`, `available`.
- `net`: each interface but loopback, with `state`, `physical`,
  `speed_mbps`, `rx_bps`, `tx_bps` and the running totals.

A value monitord can't know is `null`, never zero.

### `monitord.processes`

```text
{"sort":"cpu", "limit":100, "filter":"firefox", "user":"alice", "tree":false}
```

- `sort` is `cpu` (the default), `memory`, `io`, `pid`, `name` or `user`.
  Numbers sort largest first and names A to Z; `reverse` flips it.
- `limit` defaults to 100; 0 means every row.
- `filter` matches the name or command line, ignoring case.
- `tree` puts parents before children, siblings in sort order, each row
  with its `depth`. A filter keeps a match's ancestors, so the tree still
  joins up.
- The kernel's own threads are left out unless `kernel_threads` is true.

The reply has `total` (rows that matched), `count` (rows returned) and
`rows`. Each row has `pid`, `ppid`, `name`, `cmdline`, `user`, `uid`,
`state`, `cpu`, `memory` (resident), `virtual_memory`, `threads`, `nice`,
`priority`, `started_at`, `read_bps`, `write_bps`, `unit` (the systemd
service or scope) and `kernel_thread`.

`cpu` is a share of the whole machine, as Task Manager shows it: one busy
core of eight is 12.5.

The process table is sampled only while someone reads it. A call keeps the
sampler running for 30 seconds. The first call after a quiet spell takes
two scans 0.3 s apart, so it answers in about a third of a second.

monitord runs unprivileged, so another user's I/O counters, open files and
working directory are unreadable to it. Those fields are `null`.

### `monitord.process`

`{"pid": 1234}` returns the table's fields plus `exe`, `cwd`, the whole
`cmdline`, `cpu_time_s`, `memory_peak`, `swap`, `read_bytes`,
`write_bytes`, `open_files`, `voluntary_switches`,
`involuntary_switches`, `cgroup` and `children`.

### `monitord.history`

```text
{"series":["cpu.busy","net.*"], "since":3600, "max_points":600}
```

- `series` is one name or a list. A name ending in `*` matches a prefix:
  `cpu.core.*` is every core.
- Give `from` (Unix seconds) or `since` (seconds back from `to`); the
  default is the last ten minutes. `to` defaults to now.
- Each point is `[time, average, minimum, maximum]`. Points are merged into
  buckets of `step_s` seconds so a series has at most `max_points` (default
  600).
- `tier` says where the points came from:

| Tier | Resolution | Kept | Series |
|---|---|---|---|
| `live` | every sample | 10 minutes | all, per core included |
| `minute` | 1 minute | 7 days | system-wide |
| `hour` | 1 hour | 1 year | system-wide |

The series are `cpu.busy`, `cpu.user`, `cpu.system`, `cpu.iowait`,
`cpu.steal`, `mem.used`, `mem.available`, `mem.cached`, `swap.used`,
`load.1`, `load.5`, `load.15`, `psi.<cpu|memory|io>.<some|full>`,
`disk.<name>.<read|write|busy>` and `net.<name>.<rx|tx>`, plus, in memory
only, `cpu.core.<n>.busy` and `cpu.core.<n>.mhz`.

### The summary topic

Every 5 seconds monitord publishes a small retained summary on
`monitord.summary`: host, CPU busy and core count, memory, swap, load, total
network and disk rates, the 10-second pressure figures and the task count.
A mesh dashboard subscribes to it instead of polling every node.

## The command line

The same binary works with no daemon running. It reads the kernel itself,
so it answers on a node's console or over ssh either way:

```text
monitord snapshot            the system now, sampled over half a second
monitord ps --sort memory    the process table (--tree, --user, --filter, --all)
monitord history cpu.busy --since 86400    stored history from the database
monitord signal 1234 TERM    send a signal, as you
monitord renice 1234 10      change a nice value, as you
```

`--json` prints what the matching verb returns. `signal` and `renice` run as
the person who typed them, and the kernel decides whether they may. No Bus
verb signals or renices anything: acting across users or nodes is
[hostd](../hostd/README.md)'s job.

## Running it

`monitord.service` runs `/opt/mixos/bin/monitord serve` as the user
`monitord`, with no capabilities and a strict sandbox. The history
database is `/var/lib/monitord/history.db`; it is a cache, and deleting it
loses history and nothing else.

`serve` takes:

- `--interval-ms` (default 1000);
- `--db PATH` or `--no-db`;
- `--minute-days` (default 7) and `--hour-days` (default 365);
- `--no-bus`, to sample and record without joining the Bus.

When the broker is down, monitord keeps sampling and recording, and joins
when it comes back.

## Testing

```text
cargo test -p monitord
```

The kernel readers take the text of each file, and the verb tests run
against a fixture `/proc` and `/sys` tree, so no test needs a real host or
a broker.

---

<!-- page: https://mixos.dev/noded/ (source: https://mixos.dev/noded/README.md) -->

# Native node broker

`noded` is MixOS's ABP broker. Services register with it, discover other
services and exchange commands or topic events. Communication between nodes
uses ABP peer connections between brokers.

Native applications connect to the broker's configured Unix endpoint.
Credential checks and native session proofs identify the caller; a service
name alone does not confer authority. Mesh admission verifies signed
inventory and an unchanged cross-version admission transcript. Mesh peers
use the same frozen ABP wire and signed-inventory admission contract as
existing nodes.

The broker does not require a D-Bus session. Run `noded --version` to
inspect the package version and build provenance. noded is one of the
personalities of the [system](../system/README.md) binary.

## Configuration

Configuration is strict data in `node.conf.mix`, resolved beneath `MIXOS` or
an explicit `MIXOS_ETC`. Isolated roots never fall back to host
configuration. Set `MIXOS` to an isolated runtime root and supply
`etc/node.conf.mix`, for example:

```text
node: "example"
noded: { port: 4200, unix_socket: "/run/mixos/noded/bus.sock" }
```

## Running it

Run `noded serve`; `--no-monitor --no-log` disables its optional observation
clients. The Unix broker endpoint verifies peer credentials before
accepting native session proofs. The operating system supervises the
process; application requests and node-to-node control use ABP.

## Tests

Tests cover broker verbs, scope isolation, replay refusal, authority
reload, mesh admission and recovery. Run
`cargo test -p noded -p bus -p config -p props -p mesh -p mesh-trust` on a
configured build worker.

## Provenance

This source was transplanted from the noded, mesh and mesh-trust
components of MixOS at `e0297242305f3a3c3de09f1ca01e8faa771768da`.
Cryptographic domain bytes remain unchanged. Version 0.18.3 adds the
structured registration-rejection body (additive only; see the
[changelog](https://github.com/markc/mixos/blob/main/services/noded/CHANGELOG.md));
the Bus contracts otherwise match 0.18.2.

The source is
[`services/noded`](https://github.com/markc/mixos/tree/main/services/noded).

---

<!-- page: https://mixos.dev/notifyd/ (source: https://mixos.dev/notifyd/README.md) -->

# Notifications

`notifyd` is the desk's notification service. Anything on the Bus can post a
notification: an app saying a job is done, or an agent asking "is this okay?"
with Yes and No buttons. The desk shows it as a toast in the top right corner
and lists it on the Notifications page of the right-hand panel. When the
human presses a button, closes it, or lets it time out, notifyd records that
outcome and publishes it, so the sender finds out without anyone switching to
a dedicated app.

One notifyd runs per desk session (`notifyd@N`), under the Bus name `notify`.

## Posting a notification

```text
send notify notify.send body='{"summary":"Build finished","source":"cbc"}'
```

The reply comes back at once with the new notification's id:
`{"id": 7, "status": "open"}`. Nothing waits for the human.

To ask a question, add up to four buttons, and optionally a timeout:

```text
send notify notify.send body='{"summary":"Deploy to staging?","actions":[{"id":"yes","label":"Yes"},{"id":"no","label":"No"}],"timeout_ms":300000}'
```

## Hearing the answer

Every change is published on the topic `notify.changed`. The inner command
says what happened, and the body is the notification as `notify.get` shows
it:

| Inner command | When |
|---|---|
| `notification.created` | a notification was posted |
| `notification.answered` | the human pressed a button; `outcome.action` is its id |
| `notification.closed` | any other outcome: `dismissed`, `expired` or `closed` |

Subscribe before you send, so the answer cannot arrive before you are
listening, and match on the id the send returned. If you were disconnected,
`notify.get {id}` tells you the outcome afterwards.

An expired question was not answered. Treat it as "no answer", never as yes.

## Verbs

| Verb | Body | Reply |
|---|---|---|
| `notify.send` | `summary`, and optionally `body`, `app`, `source`, `actions` (`[{id, label}]`), `timeout_ms`, `request_id`, `thread` | `{id, status}` |
| `notify.get` | `{id}` | the notification, with `outcome` once it has one |
| `notify.list` | `{all?}` | open notifications, oldest first; `all: true` includes answered ones |
| `notify.action` | `{id, action}` | the human pressed a button (the toast calls this) |
| `notify.dismiss` | `{id}` | the human closed it without choosing |
| `notify.close` | `{id}` | the sender, or the Notifications page, withdrew it |
| `notify.close_all` | `{}` | closes every open notification without buttons; questions stay |

Each notification gets exactly one outcome. The first one wins, and a later
button press or timeout is refused with `ALREADY_ANSWERED`.

`notify.action`, `notify.dismiss`, `notify.close` and `notify.close_all`
settle a notification, so notifyd takes them only from callers on this node
(the broker's `broker_origin` stamp). A peer across the mesh can post and read
notifications but never answer or withdraw one for the person. That matters
for questions such as portald's screen-share consent.

Errors come back as `{error_code, message}`: rc 10 `USAGE` (a bad body),
rc 13 `FORBIDDEN` (not a local caller), rc 14 `NOT_FOUND`,
rc 15 `ALREADY_ANSWERED`, rc 16 `TOO_MANY_OPEN`.

## Limits

A summary is at most 120 characters, a body 500, and a button label 32. A
notification has at most four buttons. At most eight questions can wait for an
answer at once; the ninth is refused until one is answered. notifyd keeps the
last 200 notifications, and never drops one that is still open.

## State

Notifications are kept in one JSON file, rewritten atomically on every change:
`~/.local/state/mixos/notifyd/state.json`, or `$MIXOS_NOTIFYD_STATE`. After a
restart, open notifications stay open and their timeouts carry on; notifyd
never answers on the human's behalf. A state file it cannot read is moved
aside, never overwritten.

---

<!-- page: https://mixos.dev/portald/ (source: https://mixos.dev/portald/README.md) -->

# The desktop portal

Applications on MixOS ask the desktop for its appearance (dark or light mode,
contrast and accent colour) through the XDG Settings portal, and for a screen
to share through the XDG ScreenCast portal. `portald` is the MixOS
implementation of both. It owns `org.freedesktop.portal.Desktop` on the session
bus, answers the `org.freedesktop.appearance` namespace and, when started with
`--screencast`, serves monitor sources from the compositor.

Values come from the settings authority, `settingsd`. The portal never writes
settings. Before authority or cache data is available, it serves the documented
defaults.

## Where the values come from

```text
settingsd  --(retained topic: settingsd.desktop.changed.<profile>)-->  portald
portald    --settings.appearance.get (one bounded read)------------->  settingsd
```

The shared settings Consumer processes the initial connection and later
generations, subscribes, and reads the projection with `settings.appearance.get`.
The reply includes its atomic snapshot evidence. The Consumer checks that
evidence, and the projection must match its binding and identity. Authenticated
retained deliveries trigger fresh reads, including after settingsd restarts.

A projection carries the schema version, the binding (instance and profile), an
incarnation, a revision, the design revision, `mode`, `contrast` and an sRGB
`accent`. A projection is refused when it is older than the held one within the
same incarnation. A new incarnation is adopted. A repeat of the held identity
changes nothing and emits no signal.

## What applications see

Interface `org.freedesktop.portal.Settings`, version 2, at
`/org/freedesktop/portal/desktop` on `org.freedesktop.portal.Desktop`.

| Key | Type | Values |
|---|---|---|
| `color-scheme` | `u` | 1 dark, 2 light |
| `contrast` | `u` | 0 normal, 1 high |
| `accent-color` | `(ddd)` | sRGB, each component 0 to 1 |

Methods:

- `ReadOne(namespace, key)` returns the value with one variant layer.
- `Read(namespace, key)` returns the value wrapped in one extra layer. This is
  the deprecated form, kept for older clients.
- `ReadAll(globs)` returns `a{sa{sv}}`, matched against namespace globs.
  An empty array or any empty filter returns all namespaces. At most 64 filters
  of 256 bytes each are accepted; larger requests return
  `org.freedesktop.portal.Error.InvalidArgument`. Matching uses bounded iteration.

An unserved key returns `org.freedesktop.portal.Error.NotFound`. The
`accent-color` key is absent until a projection with an accent has been adopted.
`SettingChanged(namespace, key, value)` is emitted only for keys whose value
actually changed.

Example, from a shell with `busctl`:

```sh
busctl --user call org.freedesktop.portal.Desktop /org/freedesktop/portal/desktop \
  org.freedesktop.portal.Settings ReadOne ss org.freedesktop.appearance color-scheme
```

## Screen sharing

Interface `org.freedesktop.portal.ScreenCast`, version 5, on the same object.
Video calls and browsers use it to share the screen: Zoom, Firefox and
Chromium `getDisplayMedia()`, OBS.

```text
compd   --zwlr_screencopy_manager_v1 (shm, damage copies)-->  portald
portald --PipeWire Video/Source node (BGRx, default ceiling 30 fps)--> the caller
```

| Property | Value |
|---|---|
| `AvailableSourceTypes` | 1: monitors only |
| `AvailableCursorModes` | 1 hidden, 2 embedded |
| `version` | 5 |

A caller runs `CreateSession`, `SelectSources`, `Start`, then
`OpenPipeWireRemote`. Each of the first three returns a request path at once and
answers later with a `Response` signal addressed to the caller, as the portal
specification describes. Request and session paths are derived from the
caller's unique name and its `handle_token` / `session_handle_token`, so a
caller can subscribe before it calls. `Start` answers with one stream:

| Key | Meaning |
|---|---|
| node id | the PipeWire node to connect to |
| `position`, `size` | the output in compositor (logical) coordinates |
| `source_type` | 1, monitor |
| `id` | the output name, such as `HDMI-A-1` |

Frames are captured at the output's mode size with `copy_with_damage`, so a
static screen costs nothing. The newest frame is sent again after a second
without a new one, and as soon as a consumer attaches. The node is a
`Video/Source` named `portald-screencast`, which is what the session manager
links capture streams to.

Sessions belong to the connection that created them. Another caller cannot
select, start or close them (`NotFound`, `AccessDenied`). A session ends when
its owner calls `Session.Close`, when the owner leaves the bus, or when capture
stops on its own (then `Closed` is emitted). `Start` answers 2 when there is
nothing to capture, for example no compositor or no output with a mode.

### Consent

Nothing is captured until the request is granted, in this order:

1. **Policy.** `--screencast-consent allow` grants everything. Use it only for
   headless and test sessions. The default is `prompt`.
2. **A standing grant** that covers the caller's app (its process name, as in
   `/proc/<pid>/comm`, so at most 15 bytes). This is how automation shares
   the screen with nobody at the desk. A process name says which app is
   asking but does not prove it, since any local process can set its own: a
   named grant is a convenience for a trusted, unsandboxed session, not an
   access control. A caller whose name cannot be read is covered only by a
   grant for any app.
3. **The person.** portald posts a notifyd question, "Share your screen?", with
   Allow and Deny. The request waits as a pending prompt until the button is
   pressed, an agent answers it over the Bus, or 60 seconds pass (up to 65
   when the question could not be posted). A timeout, Deny
   or a closed question all answer the app with 1 (cancelled). If the app
   closes the request or its session, or leaves the bus, while it waits, the
   question is taken down and nothing is captured. At most 4 requests wait at
   once, one per caller; more are denied straight away. Without notifyd the
   request still waits, and can only be answered over the Bus.

| Verb | Body | Does |
|---|---|---|
| `portald.screencast.pending` | `{}` | lists waiting requests (`request`, `app`, `owner`, `output`, `notification`), the grants, and the policy |
| `portald.screencast.answer` | `{request, allow}` | decides a waiting request, as if the person pressed the button; withdraws the question |
| `portald.screencast.grant` | `{app?, count?, ttl_ms?}` | covers the next `count` (default 1, at most 100) Starts by `app` (any app when absent) for `ttl_ms` (default 5 minutes, at most an hour); at most 16 grants |
| `portald.screencast.revoke` | `{id?}` | withdraws one grant, or all of them |

These verbs answer **callers on this node only**. A request with
`broker_origin` other than `local` is refused with rc 13 `FORBIDDEN`, because a
grant hands over the whole screen. notifyd holds the same line for the
buttons: `notify.action`, `notify.dismiss`, `notify.close` and
`notify.close_all` are refused for callers off this node, so no mesh peer can
press Allow either. Every grant, answer and decision is logged with the
caller.

The trust model, plainly: consent keeps the screen from other nodes and from
an app that shares by accident. It is not a wall between local processes:
any process on this node that can reach the Bus (`local` means this node,
not this session) can answer or grant, and any
Wayland client of this desk can already capture the screen through compd, so
an app that wants to approve its own share can. Sandboxed apps, where that
would matter, are out of scope for now.

To share the screen from a script with nobody at the desk:

```text
send portald portald.screencast.grant body='{"app":"obs","count":1,"ttl_ms":60000}'
```

Then start the share in the app. To drive the prompt instead, read
`portald.screencast.pending` and answer the request it lists.

This is a first cut, scoped to the trusted, unsandboxed session:

- **One stream per session:** the first output with a current mode.
  `multiple` is accepted and ignored.
- **No window sources and no restore tokens.** `persist_mode` is accepted and
  ignored.
- **shm frames,** copied twice per frame. DMA-BUF is later work.
- **The remote is unrestricted.** `OpenPipeWireRemote` returns a plain
  connection to the session's PipeWire, not one limited to the cast node.

## Startup and failure

- Startup takes the bus name immediately with a valid cache for the requested
  binding, or defaults (dark, normal contrast, no accent). Authority reads run
  asynchronously and never delay name acquisition. A production process test
  requires a complete Read reply within 250 ms of launch, with a silent authority.
- The name is requested without queueing. If another portal already owns it,
  this instance exits. It does not wait in line.
- A failed read backs off from 250 ms, doubling to a 30 s ceiling, and resets on
  success. The last-good values keep being served while the authority is down.
- The supervised transport keeps retrying through initial broker failure.
- The cache is `<instance>/<profile>/appearance.json` under the state directory,
  capped at 64 KiB and written by atomic rename. Mismatched bindings are rejected;
  the old unpartitioned cache is ignored. It seeds the next cold start and is
  never sent back to settingsd.

## Running it

The unit is `portald@.service`, owned by `services/portald/units/`. It is part of
`session@<instance>.target` and wants `noded@<instance>` and
`settingsd@<instance>`. It runs as `mixos` with the session environment file, so
it keeps `DBUS_SESSION_BUS_ADDRESS`. The unit passes `--screencast`.

```text
portald serve --instance <name> [--profile default] [--state-dir DIR] [--screencast]
    [--screencast-consent prompt|allow] [--screencast-max-framerate 30]
```

It needs `DBUS_SESSION_BUS_ADDRESS`. `--state-dir` defaults to
`$STATE_DIRECTORY`, which systemd sets from `StateDirectory=portald`. With
`--screencast` it also needs `WAYLAND_DISPLAY` and `XDG_RUNTIME_DIR` for the
compositor, and `PIPEWIRE_RUNTIME_DIR` / `PIPEWIRE_REMOTE` (or
`XDG_RUNTIME_DIR`) for PipeWire. The binary links the system `libpipewire-0.3`.

`--screencast-max-framerate N` sets the frame-rate ceiling offered to cast
consumers, from 1 through 120 Hz; invalid values are refused with
`SCREENCAST_MAX_FRAMERATE`. The default stays 30. A headless desk may pass 60
in a unit drop-in; its own PipeWire and compositor refresh must support it.

## Status for agents

`HELP` returns the verb manifest. The bus verb `portald.status` is read-only. It reports the origin of the held
values (defaults, cache or settingsd), whether the name is owned, the identity
of the held projection, the last fault and the counters. Its
`settings_generation` reports the Consumer's connection generation, or null
while disconnected. It is registered in
`docs/docs/spec/bus/verbs.conf.mix`.

## Tests

The source is
[`services/portald`](https://github.com/markc/mixos/tree/main/services/portald).

```text
cargo test --locked -p portald
```

Unit tests cover value mapping, iterative matching and acceptance.
`tests/portal.rs` runs a private `dbus-daemon` and checks version 2, Read
and ReadOne nesting, empty and adversarial ReadAll filters, NotFound,
changed-only signals, cache isolation and single ownership. It launches the
production binary against a silent authority and requires a complete Read
reply within 250 ms, including cached startup and profile switching.

`tests/screencast.rs` runs the ScreenCast contract on a private `dbus-daemon`
with no compositor: properties, the request and session paths, the Responses,
refused source types and cursor modes, ownership, `Start` answering 2 with
nothing to capture, `Close`, and sessions retired when their owner leaves.
Capture itself needs compd and PipeWire. On a desktop session,
`cargo run -p portald --example screencast_probe` drives one session and holds
it so a consumer can attach, for example
`gst-launch-1.0 pipewiresrc target-object=<serial> ! videoconvert ! autovideosink`.

Native tests embed the real noded via [test-broker](../test-broker/README.md)
and run the production settingsd loop. They cover initial fetch, live
update without reconnect, settingsd restart at unchanged revision, and
broker recovery after the initial attempt budget is exhausted. These tests
run by default; the build cluster needs `dbus-daemon` and the pinned Rust
dependencies.

## Not yet

- The FileChooser portal and its chooser application.
- A first-class accent field. Accent currently comes from the design's resolved
  accent, held in settingsd outside the sealed snapshot, and will move into the
  settings contract when that is decided.
- Sandboxed callers and D-Bus activation.
- For ScreenCast: window sources, several streams per
  session, restore tokens, DMA-BUF frames and a permission-limited PipeWire
  remote.

The contract, with its status, is in [docs/docs/spec/portal](../docs/spec/portal/README.md).

---

<!-- page: https://mixos.dev/prefs/ (source: https://mixos.dev/prefs/README.md) -->

# Prefs

Prefs holds MixOS's preference editors in one window: an expandable tree
on the left, the selected section on the right. Appearance contains Themes,
Fonts, Wallpapers and Terminal; Applications contains MixOS Desktop, MixOS Server and
Creative; App Settings contains Email. The sidebar can be resized. The name is a nod to the
Prefs drawer of AmigaOS, where each setting had its own small editor.

## Applications

Each Applications section shows its followed apps, from the [releases
service](../releasesd/README.md): each app's installed version, the latest release,
when it was published, and its status (up to date, update available, not
installed, not checked, or check failed).

- **Check for updates** (Ctrl+Shift+R) asks GitHub about every followed app.
- **Update group** installs newer releases for installed apps in the selected group.
- Select an app to see its latest **release notes**, then:
  - **Install or update** (Ctrl+I) installs it, or updates it if it is
    installed;
  - **Roll back** returns to the previous version;
  - **Remove…** asks first; Cancel is the default, so Enter never removes.
- **Refresh** (Ctrl+R) reads the list again without asking GitHub.

MixOS's `mixos-desktop` and `mixos-server` catalogue entries have their own
sections. A catalogue entry's optional `category` selects `mixos-desktop`,
`mixos-server`, `creative` or `other`; application names and publishers remain
catalogue data. The catalogue's top-level `categories` map can label a group,
for example `categories: {creative: "Graphics"}`.
Unrecognised catalogue entries remain accessible under an additional **Other**
section. Changing groups clears the previous selection and its release notes;
selecting an app through the Bus opens its group automatically.

One operation runs at a time; the status bar says what is happening and how
it ended. Installs are per user, verified against the checksums each release
publishes, and the previous version is kept for rolling back: see
[Application releases](../releasesd/README.md).

If the releases service is not running, the editor says so instead of an
empty list. You follow apps by listing them in
`~/.config/mixos/releases.mx`.

## Appearance

**Appearance → Themes** sets the session's look through the settings service
(settingsd): the **colour scheme** (each shown with its accent), the
**style** (the scheme's own, or Plain, Pro, Studio or Classic), **light or
dark**, **contrast**, and the **window frame**: a title bar drawn by the app
or by the system, and which side the app's window buttons sit on.

Each change applies to the whole session as you make it, as in GNOME's
settings: the apps that follow the session look (Prefs itself, BusViewer,
and the portal's clients) change with it. Only the setting you changed is
written. Changes made quickly one after another are sent in turn, never
lost.

If settingsd refuses a change, Prefs keeps it and says so: **Apply**
(Ctrl+S) tries again and **Revert** drops it. If the appearance is changed
elsewhere at the same moment (another window, or an agent), Prefs follows
it on every setting you did not touch. If it changed one you did, Prefs
names it and applies nothing until you choose **Keep my changes** or
**Revert**. Every change is checked against the revision you were shown, so
it never lands on a change you have not seen. If its answer is
lost, Prefs asks settingsd for the change's receipt before anything else is
applied (**Check again** asks now); if settingsd no longer holds one, the
session's current state decides what the status line says.

**Appearance → Fonts** shows the interface, heading and monospace faces currently
installed on the window, with previews. Font family and size selection is not
available yet; these faces follow the session design.

**Appearance → Terminal** holds the terminal's font, layout, cursor, focus ring,
mouse and environment settings, plus Reset terminal. Each change uses
settingsd and applies as it is made. Themes contains only the session theme
controls. See the [terminal settings](../docs/spec/settings/README.md#terminal) for
the defaults and ranges.

## App Settings → Email

**App Settings** holds settings that belong to one application, kept in
the settings service like the session's look. It is separate from
Applications, which installs apps. Its first section is **Email**, the
[email app](../email/README.md)'s accounts and mail options (`email.*` in
settingsd; see the [email settings](../docs/spec/settings/README.md)).

- **Accounts** lists the accounts in the order Email's folder tree shows
  them, marking the default and any that are disabled. **Add account**
  opens a blank form; **Move up** and **Move down** reorder; **Make
  default** picks the account new mail is sent from (with none, the first
  enabled account); **Remove…** asks first, and Cancel is the default.
- The selected account's form holds its **name**, **JMAP URL** (https,
  no trailing slash), **login email**, an optional **CA bundle** (an
  absolute PEM path; blank trusts the system roots) and a **signature**.
  Typing stays in the form until **Save**; **Revert** drops it. Each field
  is checked by the settings service's own rules first, and a field it
  would refuse is named under the field and nothing is sent. **Enabled**
  applies at once.
- **Mail** holds messages per page (10 to 500), marking messages read when
  opened, and asking before deleting them; each applies at once. **Reset
  email settings…** asks first, then puts every email setting back to its
  default, which means no accounts.

Each change is one write to settingsd carrying the whole account list,
and the default account in the same write when the change touches it
(removing the default account clears it). Every write is checked against
the revision shown, as on the Appearance panel. If settingsd refuses one,
the status line gives its reason and the panel keeps showing what
settingsd holds; your typing stays in the form.

**Passwords never go to the settings service**, whose settings every Bus
client can read, and Prefs neither keeps nor shows them. **Set password**
hands the typed password to Email itself (`email.account.password.set`),
which keeps it in its own private file, and empties the field; the field
gets the password back only if Email refuses it. If Email is not running,
Prefs starts it (`apps.launch`) and waits up to about 16 seconds for it to
come onto the Bus. Under the field, Prefs says whether Email holds a
password for the account, as Email reports it (`email.accounts`), or that
this is unknown because Email is not running. **Connect now** asks Email
to connect the account (`email.account.connect`). **Forget password…**
asks first (Cancel is the default), then has Email delete the password it
keeps; it is the only time Prefs sends an empty password, and it starts
Email if needed, as Set password does. **Remove…** goes through Email
when it may be running (`email.account.remove`): Email removes the account
from settingsd and forgets its password itself, and refuses while the
account is still being migrated from its old configuration
(`MIGRATION_PENDING`, shown as Email gives it). When Email is not running,
Prefs removes the account from settingsd directly and, once settingsd shows
it gone, asks a running Email to forget the password; Prefs does not start
Email for this, and if Email is away or refuses, the status line says the
password may still be held. An account still being migrated comes back
when Email next starts, by design.
An Email too old to know these verbs is reported as such, not retried.

```mix
-- What Prefs shows: accounts (with has_password), default, mail options.
send prefs prefs.email

-- Add an account; the answer carries its new id.
send prefs prefs.email.set body='{"op":"add","name":"Work","url":"https://mail.example.com","email":"admin@example.com"}'

-- Change one field, make it the default, move it, disable it.
send prefs prefs.email.set body='{"op":"update","id":"acct-0f3a2b1c9d8e","signature":"-- Admin"}'
send prefs prefs.email.set body='{"op":"default","id":"acct-0f3a2b1c9d8e"}'
send prefs prefs.email.set body='{"op":"move","id":"acct-0f3a2b1c9d8e","direction":"up"}'
send prefs prefs.email.set body='{"op":"enable","id":"acct-0f3a2b1c9d8e","enabled":false}'

-- A mail option.
send prefs prefs.email.set body='{"path":"email.mail.page_size","value":50}'

-- Hand a password to Email (answered once Email has), or forget it.
send prefs prefs.email.password body='{"id":"acct-0f3a2b1c9d8e","password":"…"}'
send prefs prefs.email.password body='{"id":"acct-0f3a2b1c9d8e","forget":true}'
```

`prefs.email.set` takes `op` `add`, `update`, `remove`, `move`, `default`
or `enable`, or `path` and `value` for a mail option. Over the Bus,
`remove` removes at once: the confirmation belongs to the window. A field
the settings service would refuse is answered with `ARGUMENT`, naming it.
For scripts that do not need Prefs open, call `settings.apply` on the
`email.*` paths directly, and `email.account.password.set` on Email.

## For agents

Prefs answers on the Bus as `prefs`. `prefs.info` reports the whole state;
`prefs.apps` the rows, selection and notes; `prefs.appearance` the session
look, the expected look while a change settles, any held or conflicting
edits and the revision read; `prefs.appearance.set`
changes it at once (`scheme`, `style` with `own` for the scheme's own, `mode`,
`contrast`, `decorations`, `caption_side`); `prefs.select {app}` and
`prefs.section {name}` selects `themes`, `fonts`, `wallpapers`, `terminal`, `mixos-desktop`,
`mixos-server`, `creative`, `other` or `email` and expands its parent. `prefs.panel {name}`
remains compatible, opening the default Themes, Creative or Email section
(`applications`, `appearance`, `app-settings`). `prefs.email`,
`prefs.email.set` and `prefs.email.password` are described under App
Settings → Email above.
`prefs.execute {id}` runs any command a button
or menu would (`apps.check`, `apps.install`, `appearance.apply`,
`appearance.revert`, …), and `prefs.commands` lists them with their
enablement. The window is drivable like every MixOS app
(`prefs.ui.*`, `prefs.window`). The verbs are registered in
`docs/docs/spec/bus/verbs.conf.mix`.

For scripted work, call the services directly (`releases.*`,
`settings.*`): Prefs is their window, not a second implementation.

## Wallpaper

In **Appearance → Wallpapers**, choose the default or an output, then Theme,
Colour or Image. Colour accepts a picker or `#RRGGBB`. Browse opens the native
image browser at the installed wallpaper folder, or Pictures in your home
folder. It lists PNG/JPEG files and folders without blocking the window.
Changes stay in Prefs until **Apply wallpaper**. **Revert wallpaper** drops
them; **Refresh wallpaper** reads the current state again.

An output's **Use default** removes just that override. Editing the default
preserves every output override. Images currently crop to fill; fit controls
and slideshows will follow when backdrop supports them.

Backdrop must be running on the same session Bus. A refusal shows its reason,
keeps the draft and leaves the last good wallpaper in place. Prefs checks for
intervening changes before sending the whole document; conflicts require
Revert and a fresh edit. This check is best effort: backdrop does not yet
provide an atomic compare-and-set operation. A lost reply is checked by a
state read, never automatically resent.

Wallpaper and browser state are included in `prefs.info`, wallpaper state in
`prefs.appearance`. Commands `wallpaper.apply`, `wallpaper.revert`,
`wallpaper.refresh` and `wallpaper.browse` are available through
`prefs.execute`; the normal `prefs.ui.*` verbs drive the controls and browser.

## Running and testing

Run with `prefs [--noded-url URL]`; a second launch raises the first window
(`prefs.show`). The Bus connection is [citizen](../citizen/README.md).

The source is [`apps/prefs`](https://github.com/markc/mixos/tree/main/apps/prefs):

| Path | What |
|---|---|
| `crates/preferences` | the headless engine: panels, rows, notes, one operation at a time, the `prefs.*` verbs |
| `crates/preferences/src/appearance.rs` | the Appearance panel: the look, its draft, fenced applies, receipts for lost replies |
| `crates/preferences/src/email.rs` | App Settings → Email: account changes planned and checked, fenced applies, passwords handed to Email |
| `src/commands.rs` | every action as a registered command (menus, buttons, shortcuts, `prefs.execute`) |
| `src/view.rs` | the egui rendering; returns what the person did |
| `src/shell.rs` | events in, effects out, in order; drained shutdown |
| `i18n/en/prefs.ftl` | the strings |

Test with `cargo test -p preferences -p prefs`. Regenerate the snapshots
with `UPDATE_SNAPSHOTS=1` and look at the images before committing them.

---

<!-- page: https://mixos.dev/props/ (source: https://mixos.dev/props/README.md) -->

# props

Shared property read types, revisions and optional namespace storage.
[noded](../noded/README.md), Mix and [editd](../editd/README.md) use the read
surface. Services can add durable domain records through the same library
and native Bus. [logging](../logging/README.md)'s opt-in bridge uses the
SQLite store and router for its `log` namespace; the substrate also supplies
the storage and routing API needed by the forthcoming mail service port.

| Feature | Adds |
| --- | --- |
| default (empty) | Pure read types, redaction, diff and in-memory revision writes |
| `bus` | Read dispatch and native publication envelopes |
| `store` | Namespace schemas, capabilities, hooks, lifecycle, audit HMAC, `PropertyStore`, `MemoryStore` and `Runtime` |
| `sqlite` | `store` plus `SqliteStore`, `SqliteTableMapping` and `JsonValuesMapping` |
| `router` | `bus` and `store` plus `PropsRouter`, `SubscribeGranter` and per-namespace event dispatch |

Choose `sqlite` and `router` together for durable service namespaces.
Services supply their own domain-table mapping, authorisation policy,
subscription granter and publisher. The library opens no second transport.
The [property contract](../docs/spec/props/README.md) defines the wire
surface, error vocabulary and persisted table ownership; the
[ownership decision](../docs/decisions/2026-10-18-property-store-in-props.md)
explains the boundary with desktop settings.

Read-surface transplant provenance: commit
`e0297242305f3a3c3de09f1ca01e8faa771768da`, MIT OR Apache-2.0.

The source is [`libs/props`](https://github.com/markc/mixos/tree/main/libs/props).

---

<!-- page: https://mixos.dev/releasesd/ (source: https://mixos.dev/releasesd/README.md) -->

# Application releases

Many good Linux applications ship as a GitHub release: a tarball per
platform, a checksum file, release notes. `releasesd` makes those first-class
on MixOS. You list the repositories you follow; it tells you when a new
release is out, installs it for you (never system-wide), checks it against
the checksums the release publishes, and keeps the previous version so you
can step back.

It works the same from the command line, from the Bus (so agents and the
settings panel can drive it), and on any Linux, not only MixOS.

## The catalogue

Your catalogue is `~/.config/mixos/releases.mx`. Until you write one,
releasesd follows MixOS itself: `mixos-desktop` (the compositor and the
apps) and `mixos-server` (`mix` and the headless services). This shows the
latest published version and permits a **per-user** install. It does not
replace the system's `/opt/mixos` tree or activate a running desk. Your own
catalogue replaces that list, so keep those entries if you want to follow
MixOS releases:

```text
{
  schema: 1,
  apps: [
    {name: "mixos-desktop", repo: "markc/mixos"},
    {name: "mixos-server", repo: "markc/mixos"},
    {name: "example", repo: "owner/example"}
  ]
}
```

`name` is how you refer to the app and the directory it installs into;
`repo` is the GitHub `owner/name`. If a release has several Linux tarballs,
add `asset:` with a regular expression that picks the right one. To start an
app through a launcher of your own, give `exec_wrapper:` its command as a
list, for example `["/usr/local/bin/launch", "example"]`. The app's menu
entry then runs `launch example -- <the app's own command>`. The full schema
is in the [releases contract](../docs/spec/releases/README.md).

## Everyday use

```sh
mix releases.mix check            # ask GitHub what's new
mix releases.mix                  # installed vs latest, no network
mix releases.mix install example  # latest release; or: install example v1.2.0
mix releases.mix notes example    # what changed
mix releases.mix update           # every installed app that has a newer release
mix releases.mix rollback example # back to the previous version
mix releases.mix remove example
```

(`releases.mix` lives with the service in `/opt/mixos/lib/releasesd/`;
`mix tools/component_install.mix releasesd` puts it there from a checkout.)

`check` uses conditional requests, so asking again costs almost nothing. It
uses `GITHUB_TOKEN`, or your `gh` login if you have one; without either,
GitHub allows 60 requests an hour.

## What an install does

1. Picks the release's `linux-<arch>.tar.gz` (not the AppImage, Flatpak,
   deb or rpm: the tarball needs nothing from the system and unpacks as a
   ready prefix).
2. Verifies it. Every checksum the release publishes must match: GitHub's
   own digest of the file, and the release's `SHA256SUMS` file if there is
   one. If the release publishes neither, or anything differs, nothing is
   installed.
3. Unpacks it to `~/.local/opt/<name>/<version>` and points
   `~/.local/opt/<name>/current` at it.
4. Links its programs into `~/.local/bin`, and its desktop entry, icons and
   file types into `~/.local/share`, so it appears in the launcher and opens
   its files. The entry's command is rewritten to run the installed binary
   through `current`, so an update or rollback needs no relinking.
5. Keeps the previous version for `rollback`; older ones are removed.

It never overwrites a file it didn't create. If something of yours is
already at `~/.local/bin/example`, the install leaves it alone and says so.

## MixOS system updates

An operator updates the canonical `/opt/mixos` tree from the published
`release.manifest.mx` and matching archives with `tools/gold_release.mix`.
The installer checks the trusted manifest digest, archive and binary hashes,
architecture and glibc floor. `plan` shows the changes; `apply` records a
receipt and backups; `rollback --receipt ID` restores the previous files.
It needs one deliberate privileged invocation and does not restart a desk.
Shared desks see the host tree through their mount; isolated desks need a
verified copy followed by their own restart. Prefs does not yet drive this
system update path.

## On the Bus

The session runs the service as `releases`:

```sh
send releases releases.check
send releases releases.install body='{"app": "example"}' timeout=600
```

The verbs, bodies and replies are in the [releases contract](../docs/spec/releases/README.md).
After any change it asks the application registry to rescan, so the
launcher updates by itself.

## Sharing one install with a container

An install can be linked into a second place, such as a MixOS session in a
container that sees your `~/.local/opt` through a read-only bind mount at
the same path. `releases.mix link` writes only the desktop entries, icons and
file types into that session's data directory (`MIXOS_RELEASES_SHARE`), with
its own record of what it made. Nothing is downloaded twice, and an update on
the host reaches the container at once. When the container sees the files at
another path, `MIXOS_RELEASES_VIEW` says where.

## Source and tests

`releasesd` is a Mix component
([decision](../docs/decisions/2026-10-10-mix-components.md)): no Cargo
package, identity in `component.mx`. The source is
[`services/releasesd`](https://github.com/markc/mixos/tree/main/services/releasesd):

| Path | What |
|---|---|
| `scripts/lib/releases.mix` | all of the logic, as a module |
| `scripts/releasesd.mix` | the Bus service (`mix --serve … --name releases`) |
| `scripts/releases.mix` | the command line, same logic in-process |
| `units/releasesd@.service` | the session unit |
| `tests/releases_test.mix` | offline: validation, verification, install, rollback, links |
| `tests/releasesd_test.mix` | every verb over a private broker and a stand-in API |

Run the tests from the checkout root. The offline test needs `bsdtar` for
two hostile fixtures (the service itself unpacks with Mix's `tar_unpack`); the Bus test
needs a `noded`, by default `/opt/mixos/bin/noded`, or `--noded <path>`:

```sh
mix services/releasesd/tests/releases_test.mix
mix services/releasesd/tests/releasesd_test.mix
```

The verbs are registered in `docs/docs/spec/bus/verbs.conf.mix`.

---

<!-- page: https://mixos.dev/scene/ (source: https://mixos.dev/scene/README.md) -->

# scene

The Mix Scenes document core, with no renderer and no interpreter. A scene
is a `---` envelope of headers followed by one ```` ```mix ```` fence
holding a strict-data map of nodes:

````text
---
scene: 1
name: about-panel
citizen: about-citizen
model: {"title":"About"}
---
```mix
root: {widget: "column", gap: 8, children: ["title"]}
title: {widget: "text", text: "= $model.title", size: 18, bold: true}
```
````

The crate provides:

- `parse` to a `SceneDocument`, `lint` for every diagnostic (codes in
  `ALL_CODES`), `resolve` to a `ResolvedScene` with defaults filled and
  bindings evaluated, `diff` between two resolved trees, `describe` for a
  family's ports, and `to_source` to write a document back out;
- `bindings`: `= expression` ports compiled once (`compile`), re-evaluated
  on a model patch (`reevaluate`) and instantiated per list row
  (`template_instantiate_with`);
- `evaluator`: the `Evaluator` trait the bindings go through, implemented
  by `ExprEvaluator` over the [expr](../expr/README.md) crate and used by
  default;
- `fixtures`: the test documents, exported for hosts' tests.

The node fence is parsed by [strict](../strict/README.md) and never
executed. A binding may read `$model` anywhere and `$item` inside a list
template; calls, assignments, statements and shell or Bus forms are refused
at compile time with `binding-policy`.

Window declarations accept `kind:"edge"`, `kind:"dialog"` and
`kind:"toast"`. Toasts are pointer-only overlays in compd, with optional
`w`, `h`, `title` and `chrome` (false by default). The host clamps their
geometry and manages visibility through its
[toast verbs](../compd/README.md#toast-scenes).

Test: `cargo test -p scene`.

The source is [`libs/scene`](https://github.com/markc/mixos/tree/main/libs/scene).

---

<!-- page: https://mixos.dev/screenshot/ (source: https://mixos.dev/screenshot/README.md) -->

# Screenshot

Screenshot takes a picture of the screen, a window or a region you drag
out, lets you mark it up, and saves it where you and your agents can find
it. Every mark stays editable until you save: the captured pixels are never
changed, and what is saved is exactly what you see.

## Taking a screenshot

| Key | Takes |
|---|---|
| **Print** | a region: drag out a rectangle with the crosshair; a click or Enter takes the whole screen, Escape cancels |
| **Shift+Print** | the whole screen |
| **Alt+Print** | the window you were working in |

The keys work everywhere on the desktop. They open Screenshot, or hand the
shot to the one already open, and Screenshot hides itself while it takes the
picture. If the window holds annotations you have not saved, it comes
forward and asks first. Nothing you drew is ever thrown away by a key press.

In the window, **Take screenshot** (Ctrl+N) takes another shot in the mode
the toolbar shows: region, full screen or window. For a window shot, choose
the window from the list beside the mode buttons; opening the list reads
the windows again. With more than one display, the same place offers the
**output**: the one under the pointer, or a named one (also
**Capture › Output**). The **Capture** menu also has a delay (3, 5 or 10
seconds) and **Include pointer**, which is off unless you turn it on.
For a region, the status line says "Drag to select an area · Esc to
cancel" as the window hides; compd then outlines the screen until you
drag. A left drag selects, Escape or the right button cancels, and a click
without a drag keeps the selection waiting. If you select nothing before
compd's limit, the window comes back saying "Nothing was selected".
Whatever happens, a shot you asked for brings the window back on top and
focused.
Escape or **Capture › Cancel** stops a shot that is waiting out its delay.
A second Print while a shot is being taken is answered "already being
taken" in the window's status line.

## Marking it up

The tool bar on the left holds the tools. Each has a key you press with
nothing else held:

| Tool | Key | Does |
|---|---|---|
| Select and move | V | click an annotation to select it; drag it to move it |
| Crop | C | drag out the part to keep (Edit › Reset crop undoes it) |
| Arrow | A | drag from the tail to the point |
| Line | L | drag |
| Rectangle | R | drag a box |
| Ellipse | E | drag a box |
| Pen | P | draw freehand |
| Highlighter | H | draw a translucent stroke |
| Redact | X | drag a box; it is filled solid, so nothing shows through |
| Text | T | type the text in the bar at the top, then click or drag |
| Numbered marker | N | click; markers count up 1, 2, 3… |

The bar at the top sets the **ink** (red, amber, green, teal, black or
white), the **stroke width**, and for text and markers the **text size**.
Changing the ink or width while an annotation is selected changes that
annotation too. In a narrow window, the controls that don't fit are left
out of the bar; **Annotate** still has them all.

Widths and text sizes are what you see: a Medium line is the same
thickness on screen whether the shot is a 4K screen shown scaled down or a
small region shown full size. Each annotation keeps the size it was drawn
at in the image's own pixels, so zooming later makes it bigger or smaller
with the picture, and changing only the ink never changes its width. To
an agent, `width` and `size` are in the image's pixels (up to 512 and 1024).

Delete or Backspace removes the selected annotation, and Escape deselects
it. Undo is Ctrl+Z and
Redo is Ctrl+Shift+Z or Ctrl+Y. Ctrl with + and − zooms, Ctrl+0 fits the
picture to the window, the wheel scrolls, and a middle-button drag pans.

## Saving

Once there is a picture, **Copy** and **Save** buttons sit at the right
end of the bar at the top; Save's tip names the folder it saves to.

- **Save** (Ctrl+S) writes the picture straight into
  **Pictures/Screenshots**, no questions asked, as
  `20261012_193927.png` (the local date and time you saved, as
  `YYYYMMDD_HHMMSS`, the form KDE's Spectacle can be set to use). If that
  name is taken, the new file gets `_2`, `_3` and so on
  (`20261012_193927_2.png`).
  Screenshot never overwrites a file. The status line then says
  "Saved to ~/Pictures/Screenshots/…" with the file's name.
- **Save As…** (Ctrl+Shift+S) asks for a path, proposing the name Save
  would use in Pictures/Screenshots (created if missing). It refuses one
  that already exists.
- **Copy image** (Ctrl+C) puts the marked-up picture on the clipboard.

The Pictures folder is the one your desktop names
(`XDG_PICTURES_DIR` in `~/.config/user-dirs.dirs`), or `~/Pictures`.
Saved PNGs are created like any file an application saves: your umask
decides who else may read them.

The raw shot compd takes is kept, until you save, in Screenshot's own
private folder (`~/.local/state/mixos/apps/screenshot/captures`, readable
only by you). It is deleted once the shot is saved, replaced by another,
or closed, and when a capture is cancelled or fails. On start, Screenshot
also prunes that folder to the newest 20 raw shots and nothing older than
7 days. The window and headless instances share that folder.

## Handing a shot to an agent

You don't need to tell an agent where a shot is. Press Print, mark it up,
press Ctrl+S, and ask the agent to look at your latest screenshot. The
agent finds it in two ways:

- **`screenshot.recent`** lists the newest saved shots: path, size,
  whether they carry annotations, and when each was saved.
- **`screenshot.saved`** is published on every save with the same fields,
  for an agent that is listening.

```mix
-- The newest saved screenshot's path.
$body = json_encode({limit: 1})
send screenshot screenshot.recent body=$body
if $rc != 0 then raise("SCREENSHOT", to_string($result)) end
$recent = if type($result) == "string" then json_parse($result) else $result end
print $recent.shots[0].path
```

The answer names the folder too:
`{folder, shots: [{path, width, height, annotated, saved_at}]}`, newest
first.

## For agents

Screenshot answers on the Bus as `screenshot` (schema `screenshot.v1`).

| Verb | Arguments | Answer |
|---|---|---|
| `screenshot.ping`, `screenshot.info` | | liveness and the compositor served (`comp`); the document, its source and last save, the capture, the job and the UI state |
| `screenshot.capture` | `mode` (`screen`, `window`, `region`), `output`, `window` `{id, generation}`, `cursor`, `delay` (0–10) | a new document, once it is ready; any answer, refusals included, carries `restore_failed: true` if the window could not be shown again; refused while unsaved annotations exist |
| `screenshot.take` | `mode`, `window`, `comp` | as Print Screen: starts at once, or brings the window forward and asks about unsaved work at once; refused (`COMPOSITOR`) when `comp` names another compositor |
| `screenshot.cancel` | | cancels a capture during its delay |
| `screenshot.open` | `path` | opens an image; refused while unsaved annotations exist |
| `screenshot.annotate` (deprecated) | `kind`, `points`, `colour`, `width`, and `text`, `size`, `number` for text and markers | the document plus the new annotation's `id` |
| `screenshot.move`, `screenshot.delete` (deprecated) | `id` (and `dx`, `dy`) | the document |
| `screenshot.crop` (deprecated) | `crop` `{x, y, width, height}`, or null | the document |
| `screenshot.undo`, `screenshot.redo` (deprecated) | | the document, including when history is empty |
| `screenshot.save` | | saves into the screenshots folder as `YYYYMMDD_HHMMSS.png` (`_2`, `_3`… when taken); publishes `screenshot.saved` |
| `screenshot.export` | `path` | Save As to a new file |
| `screenshot.recent` | `limit` (1–100) | the newest saved shots |
| `screenshot.select` | `tool`, `mode`, `window`, `output` | the UI state |
| `screenshot.commands` | | every command with parameter schemas, labels, shortcuts and enablement |
| `screenshot.execute` | `id`, optional `params` | runs a command; answers `{executed, result, status, dialog, job}` |
| `screenshot.theme` | `scheme`, `mode` | this window's look |
| `screenshot.show`, `screenshot.quit` | | brings the window forward; closes it (refused with unsaved work) |

Coordinates are pixels of the captured image, whatever the zoom. Like any
program you run, an agent on the Bus acts as you: `screenshot.open` reads
any image you can read, and `screenshot.export` writes a new PNG wherever
you can write (never over an existing file). An agent
is refused rather than allowed to discard a person's unsaved annotations
(`UNSAVED`), and is refused while a dialog is open (`DIALOG`) or another job
runs (`BUSY`).

### Parameterised document edits

The headless `annotation` engine owns `edit.annotate` (the Shape body),
`edit.move {id, dx, dy}`, `edit.delete {id}`, `edit.crop {crop}` (null resets),
and nullary `edit.undo` / `edit.redo`. Dispatch through
`screenshot.execute {id, params}`; its reply includes the command's `result`
alongside status, dialog and job. Annotate returns document info plus the
new object's `id`; the other edits return document info. Unknown fields in
the execute body are refused with `ARGUMENT`.

Pointer strokes, text, number markers, completed object drags, crops, menus,
shortcuts and Bus calls all reach the same `command::Registry::execute`.
A drag commits on release, making one undo step and one executed event.
Delete selection is the nullary shell command `edit.delete_selected`; it
dispatches `edit.delete` with the selected id. Keymap overrides that named
the old nullary `edit.delete` must move to `edit.delete_selected`.
Uncrop dispatches `edit.crop`. The shell's dialog/job checks compose with
the engine's enablement.

The six `screenshot.annotate`, `screenshot.move`, `screenshot.delete`,
`screenshot.crop`, `screenshot.undo` and `screenshot.redo` verbs remain
deprecated aliases of execute and preserve their old reply bodies and
argument error codes at document limits. Alias undo/redo with empty history
return the document without executing or publishing an event; the command
and `screenshot.execute` remain disabled. Undo/redo use the shared
`command::History`; its byte budget counts undo and redo snapshots. Raster
workers receive a fresh history without old edits.

The window is drivable like every MixOS app, including its menus: see
[driving an app](../docs/drive.md) (`screenshot.ui.*`, `screenshot.window`). The
verbs are registered in `docs/docs/spec/bus/verbs.conf.mix`. Each command run
from a menu, a key, the toolbar or `screenshot.execute` is published on
`screenshot.command.executed` v2 with accepted `params` and returned `result`,
including successful edits reached by hand or through the deprecated aliases
([executed commands](../docs/decisions/2026-10-11-executed-commands.md)).
Edit › Delete and Edit › Uncrop each publish two executed events: first the
inner `edit.delete` / `edit.crop` with parameters, then the nullary wrapper
`edit.delete_selected` / `edit.uncrop`. The wrapper records the gesture;
the inner command records the document edit.

`screenshot --headless` runs the same verbs with no window, for agents and
tests, registered under the headless names above so Print Screen never
lands in an instance nobody can see. It never asks anything: work that would need a
question is refused.

## From the command line

```
screenshot [IMAGE]                 open the window (or bring it forward)
screenshot --capture region        take a shot, as Print does
screenshot --capture window --window ID:GEN
screenshot --headless              the Bus service alone (screenshot-headless)
screenshot --comp comp-nested      capture through another compositor
```

There is one window, and one headless instance, per compositor:

| Compositor | Window | Headless |
|---|---|---|
| `comp` (the desktop's own) | `screenshot` | `screenshot-headless` |
| another, e.g. `comp-nested` | `screenshot-comp-nested` | `screenshot-headless-comp-nested` |
| a name too long to fit | `screenshot--<8 hex>` | `screenshot-headless--<8 hex>` |

The hex is a stable hash of the compositor's name; a service name is at
most 31 bytes, and a window name never starts with `screenshot-headless`.
A second launch, or Print Screen in a compositor, hands its request to
that compositor's window, so a shot is always taken through the
compositor whose key was pressed; before handing over, the launch checks
that the running instance serves the same compositor (`comp` in
`screenshot.ping`) and refuses otherwise, and the request itself names the
compositor so the receiver refuses it too. A running window from an older
build that does not report `comp` refuses every hand-over: close it and
launch again. `--comp` and `--service` take Bus
service names: 2 to 31 of a-z, 0-9 and `-`, starting with a letter.

An agent's capture (`screenshot.capture`) hides the window and shows it
again without taking the focus or switching workspace; a person's capture
brings the window forward. Showing the window again is retried for a few
seconds; if it still fails, the shot is kept, the answer carries
`restore_failed: true` and the status line says so. Bring the window back
with Print Screen, `screenshot.show` or the taskbar; nothing restores it
later on its own.

## Source and tests

The source is
[`apps/screenshot`](https://github.com/markc/mixos/tree/main/apps/screenshot)
(app id `dev.mixos.screenshot`):

- `crates/annotation`: the headless engine (document, painter, viewport,
  screenshots folder, ledger).
- `src/`: the egui shell (`app` state and rules, `commands` registry,
  `capture` over compd, `jobs`, `view`, `shell`, `headless`). The instance
  names per compositor are in `src/names.rs`.

Test it on a build worker:

```
cargo test -p screenshot -p annotation
```

`tests/native_bus.rs` runs the headless binary against an in-process
broker and a fixture compositor; `tests/snapshot.rs` renders the window
offscreen (regenerate with `UPDATE_SNAPSHOTS=1` and look at the images);
`tests/registry.rs` checks the verb registry.

## Notes

- Copy image goes through the desktop's X11 clipboard (XWayland), so
  native Wayland applications may not see it yet. Save, then paste the
  file, is the reliable path for now.
- Screenshot replaces Cap, the earlier screenshot app; see the
  [decision](../docs/decisions/2026-10-12-screenshot.md).

## Changes from Cap

- Print, Shift+Print and Alt+Print take shots from anywhere.
- Ctrl+S saves straight into Pictures/Screenshots; agents find saves with
  `screenshot.recent` and `screenshot.saved`.
- Stroke width and text size are steps (thin to heavy, small to huge)
  rather than free values; numbered markers are discs.
- Open and Save As take a typed path rather than a file browser.
- The pointer is left out of shots unless you include it, for people and
  agents alike.
- A region selection may take up to 70 seconds (Cap allowed 38).
- Raw shots are deleted when no longer needed, and the folder is pruned.

---

<!-- page: https://mixos.dev/settings/ (source: https://mixos.dev/settings/README.md) -->

# settings

Headless desktop settings types, validation and resolution, and the shared
consumer. Shared by the authority ([settingsd](../settingsd/README.md)) and
the app and compositor adapters. Library API: 0.3.0; the authority wire and
schema contract remains 0.1.0, schema 1.

See [the settings contract](../docs/spec/settings/README.md). The source is
[`libs/settings`](https://github.com/markc/mixos/tree/main/libs/settings).

## The consumer

`consumer::Consumer` owns ordering, bounded bootstrap buffering, one active
subscribe/read job, pending-only recovery and fenced staged/application
state. `domains::ChangePlan` compares one effective context for paint,
text, layout, resource and motion work; shell hosts opt into shell
geometry. Provenance and source/revision metadata alone do not cause
rendering work. Construct apps with `Consumer::for_app(binding, "ced")` and
shell hosts with `Consumer::for_shell(binding)`. `context()` returns the
canonical projection key (`app:ced` or `desktop`); adapters use it without
repeating key construction.

## Native execution

The optional `native` feature executes actions over an **existing**
`bus::native_client::SupervisedClient`. It does not connect, spawn a task or
take the incoming receiver. The host multiplexes work futures with its
current incoming lane and connection state, feeding the sampled connection
generation even when a state watch coalesces a disconnect/reconnect. Feed
queue loss through `lost()` before using further queued data. There is one
pending retry deadline, from 250 ms capped at 30 seconds; remove it after
success/disconnect and never arm an idle timer. Unsupported, wrong-target
and protocol refusals await a new event or explicit refresh rather than
automatically retrying unchanged bad data. `retry_deadline()` is absolute
and remains fixed during malformed-event storms; `retry_delay()` returns
its remaining duration, not a new per-event delay. Inspect `is_confirmed()`
to distinguish fresh authority evidence from preserved usable data during
loss/recovery. Captured read baselines expose same-incarnation rollback
while allowing an older read that legitimately raced a newer event. Cancel
an old executor future when `current_work()` changes or disappears;
superseded work must not become a second active host job. Reconcile the
pending timer from `retry_deadline()` after every engine input and
completion, including successful RPC replies: a delivery anomaly may have
scheduled recovery while that otherwise successful read was in flight.
Timer scheduling follows engine state, not just the last RPC result.

## Bootstrap and fallback

Each native call has a one-second bound. Pass the same initial deadline to
`native::execute_until` for subscribe and read to bound their combined
bootstrap to one second before presenting a labelled fallback; complete
cancelled work as a timeout so the engine can recover. After that deadline
the host may capture `fallback_request()` and run `Request::prepare` on its
worker, passing a loaded cache candidate and a resource readiness callback.
Retained bootstrap data is tried first, then cache, then embedded defaults.
Every candidate must pass the callback for all references used by its
context/host. If none is usable, preparation returns diagnostics.
`complete_fallback` fences the completion before producing the usual UI
stage; the usual synchronous pre-swap check and acknowledgement still
apply. Resource loading and real renderer integration remain host work.

## Applying a change

Readback advances `current()`, not `applied()`. Prepare every changed
resource before entering the renderer loop. Check `is_current(update)`
immediately before the synchronous swap, then activate and
`acknowledge(update)` with no intervening await; a stale completion must
never mutate the renderer. Failed activation preserves last-good applied
data. Identical render inputs advance evidence without a swap. Neither
readback nor application proves a presented frame. Profiles and contexts
are immutable for one consumer lifetime. A host rebind cancels its old
work, retires the old subscription via `unsubscribe_topic`, and creates a
new consumer; unique consumer tickets reject completions from retired
hosts.

`presentation_kind()` labels installed data as Current, Retained, Cached,
LastGood or Embedded. Fallback never enters `current()` or supplies
mutation fences. Embedded/cached fallback cannot be saved as
authority-derived data. An unchanged fresh authority projection promotes
evidence without a swap. `fault()` reports authority/current-resource
faults; `fallback_fault()` reports fallback preparation/activation failure.
A usable fallback clears its own fault while preserving an ongoing
authority outage or unavailable live resources.

## The presentation cache

The optional `cache` feature provides bounded presentation-cache I/O over
`config::atomic` ([config](../config/README.md)). The caller supplies an
existing absolute directory inside its isolated session; no paths are
created and no host preferences are touched. Reads reject symlinks in every
path component, non-regular files and oversized data. A versioned,
digest-bound envelope also binds instance/profile, context, shell
capability and interpretation; the whole projection must match a current
recompilation. An unavailable old pinned package source is refused
visibly. JSON parsing preserves floating-point round trips for exact
projection checks. Digests detect corruption; they do not authenticate
local files. Local cache never supplies authority evidence, even when its
data is valid.

`cache_target()` captures the immutable producer/binding/context/capability
descriptor for `load_for` and `Writer::open_for`; the private producer fence
does not enter the persistent filename. `Save::same_capture` allows bounded
worker deduplication. `Request::prepare_with_cache` loads lazily after
retained resource validation and preserves load failures in its prepared
diagnostics.

Capture `cache_save()` only after activation (or unchanged evidence
advancement), then submit it to the host's one serial `cache::Writer` off
the UI loop. Captures carry immutable applied data and an activation
serial. A stable advisory lock excludes duplicate writers; superseded saves
cannot replace newer attempts. The latest failed save can retry, while
post-rename sync failure reports `cache_write_ambiguous`. Do not delete
corrupt or ambiguous data automatically. Retire the writer when retiring
its producer consumer. The held directory inode is the I/O boundary;
renaming it cannot redirect a write elsewhere, but may make the cache
unavailable under the new path. That is a fallback/cache miss, never an
authority rollback. Cache failure does not change applied renderer state.

---

<!-- page: https://mixos.dev/settingsd/ (source: https://mixos.dev/settingsd/README.md) -->

# settingsd

The headless native ABP desktop settings authority, contract 0.1.0. An
established profile has one writer and durable whole-document settings and
operation receipts. Native publication is retained and owner-stamped by
[noded](../noded/README.md). [Ced](../ced/README.md) and
[compd](../compd/README.md)'s scene-host consume shared appearance jobs on
their existing Bus lifetimes. Full desktop integration, panel geometry and
native frame acceptance remain in development.

See [the settings contract](../docs/spec/settings/README.md). Clients use
the [settings](../settings/README.md) library. The source is
[`services/settingsd`](https://github.com/markc/mixos/tree/main/services/settingsd).

## Running it

```text
settingsd init --instance example
settingsd seed --allow-create --instance example
settingsd serve --instance example
```

Init explicitly initialises new state. An installer can explicitly seed a
first-run session profile with `--allow-create`. Plain seed validates an
existing profile unchanged and refuses a wholly missing root; a retained
writer lock prevents seed from recreating an established missing primary,
including without a backup. Serve fails for a missing or unsupported
established store. Both accept `--profile` and `--root` for an explicit
binding or test directory. Use an isolated broker when testing.

## Profiles and upgrades

Profiles pin their initial package design source. Reload checks a content
digest; a binary upgrade cannot change effective settings within the same
revision. An effective interpretation digest fences compiler drift for
explicit migration. The accepted record's format (`store::FORMAT`, now 2)
is that migration: an older record whose seal verifies as stored is
re-derived and re-sealed on open by `Accepted::upgrade`, whose doc comment
says how to add the next field.

Present corrupt primary data can restore a validated backup under a new
incarnation. A missing primary fails visibly, including when a backup
exists. I/O faults and intact unsupported documents fail without automatic
rollback.

## The unit

The packaged unit binds the instance to its machine hostname; its
session/VT number is a supervision attribute and never a second instance
identity. The session target wants and upholds the authority. The unit
validates with plain seed before serving, and application and compositor
startup does not wait for settings readiness. An image must provision its
service account's writable `MIXOS_ETC/settings` root and explicitly seed
once during first installation. Automatic startup never receives
`--allow-create`, so lost mounts or directories do not silently become new
default profiles.

## Tests

Worker tests: `cargo test -p settingsd`. The native ABP gate and the
compositor fixtures arrive with the desktop test harness.

---

<!-- page: https://mixos.dev/strict/ (source: https://mixos.dev/strict/README.md) -->

# strict

The MixOS strict-data format: the grammar of `*.conf.mix` and `*.data.mix`
files. A document is a JSON-shaped tree (nil, bool, number, string, list,
map) with bare keys, optional top-level braces, `#` / `--` comments and
trailing commas. It is loaded as data and never executed: anything that
could run (a variable, a call, a command substitution, interpolation, a
semicolon) is refused with a line-numbered error naming the construct.

The crate has no dependency on the Mix language. It provides:

- `parse` / `parse_file` to a `Value` tree;
- `from_str` / `from_value` / `from_file` into a `#[derive(Deserialize)]`
  type, and `to_string` / `to_string_pretty` / `to_value` back out;
- `encode` / `encode_pretty` for a `Value`, in text that reads back
  unchanged;
- `to_json` / `from_json` for consumers that work on `serde_json::Value`.

Build and test with `cargo test -p strict`. The grammar tests live in
`tests/grammar.rs`, the serde bridge in `tests/serde_bridge.rs`.

The source is [`libs/strict`](https://github.com/markc/mixos/tree/main/libs/strict).

---

<!-- page: https://mixos.dev/syntax/ (source: https://mixos.dev/syntax/README.md) -->

# syntax

Deterministic syntax highlighting for MixOS text editors. It wraps `lsh`
from Microsoft Edit (msedit): a small compiler from `*.lsh` language
definitions to bytecode, and a line-oriented runtime that turns each line
into highlight spans. The two upstream crates, `lsh` and `stdext`, are
vendored with documented patches under
[`vendor/msedit`](https://github.com/markc/mixos/tree/main/vendor/msedit)
(MIT, from microsoft/edit at `826b4c0`).

It is a core library (`kind = "lib"`, `layer = "core"`) with no Bus
contract. Its one direct user is [`editor-model`](../editor-model/README.md)
([`libs/editor-model/src/highlight.rs`](https://github.com/markc/mixos/blob/main/libs/editor-model/src/highlight.rs)),
which maps its highlight kinds to colour classes for the
[editor](../editor/README.md) widget, and so for [ced](../ced/README.md).
Mix source is highlighted by the Mix lexer, not by this crate.

The source is [`libs/syntax`](https://github.com/markc/mixos/tree/main/libs/syntax).

## Concepts

- **Bytes, not graphemes.** lsh works on bytes, so a text store may hand
  over chunks that split a grapheme cluster.
- **Line numbers are 1-based** everywhere in the API.
- **Lines of 32 KiB or more are left plain** (`MAX_LINE_LEN`, as upstream).
  Unlike upstream, the highlighter still advances to the real end of such a
  line, so later line numbers stay correct.
- **A checkpoint every 1024 lines** (`cache::INTERVAL`, pinned in every
  build profile; upstream uses 16 in debug builds). A random seek costs at
  most one interval of parsing.
- **No build script and no mutable statics.** The compiled definitions in
  `src/defs.rs` are generated once and committed.

## API

- `language_for_path(&Path)`, `language_by_id("rust")`,
  `language_by_name("Markdown")` (ASCII-case-insensitive): look up a
  `&'static Language`.
- `LineSource`: the trait a text store implements. `read_forward(offset)`
  returns the contiguous bytes from `offset` to some chunk boundary (empty at
  the end); the highlighter assembles lines that span chunks. The optional
  `indexed_line_end(line)` lets a store with a line index skip over-long
  lines without reading them. `&[u8]` and `str` implement it.
- `highlighter::Highlighter`: parses one line at a time from the top.
  `parse_next_line(&mut Vec<Span>)` fills the spans of the next line;
  `snapshot()` and `restore()` save and resume a `HighlighterState`.
- `highlighter::Span { start, kind }`: `kind` applies from `start` (an
  absolute byte offset in the source) to the next span or the end of the
  line.
- `cache::Cache`: checkpointed random access. `parse_line(h, line, out)`
  resumes from the nearest checkpoint; `invalidate_from(line)` drops the
  states an edit at `line` makes stale; `advance(h, target, max_lines)`
  time-slices a cold seek with a per-call line budget and returns true once
  `target` is reachable; `reach()` is the furthest line reachable without
  parsing. The cache also keeps a frontier, so a budget below one interval
  still makes progress from frame to frame.
- `defs::HighlightKind`: `Comment`, `String`, `KeywordControl`,
  `StorageType`, the `Markup*` kinds and the rest. `defs::LANGUAGES` and
  `defs::FILE_ASSOCIATIONS` are the generated tables. `syntax::runtime`
  re-exports the vendored `Language` and `Highlight` types.

## Languages

C, C++, C#, Diff, F#, Git commit and rebase messages, Go, ignore files,
Java, JavaScript, JSON, LSH, Lua, Markdown, Odin, PowerShell, properties,
Python, Ruby, Rust, shell script, TOML, XML and YAML: one per definition
file in
[`vendor/msedit/lsh/definitions`](https://github.com/markc/mixos/tree/main/vendor/msedit/lsh/definitions).

## Example

From the tests:

```rust
use syntax::highlighter::Highlighter;

let text = "fn main() {\n    // hello\n}\n";
let src = text.as_bytes();
let rust = syntax::language_by_id("rust").expect("lsh defines rust");
let mut h = Highlighter::new(&src, rust);
let mut spans = Vec::new();
h.parse_next_line(&mut spans); // line 1
h.parse_next_line(&mut spans); // line 2: a Comment span starts at the "//"
```

An editor keeps one `Cache` per buffer, builds a fresh `Highlighter` over
its text each frame (a highlighter borrows the text), calls `cache.advance`
with a line budget for lines not yet reached, and calls
`cache.invalidate_from(line)` after each edit.

## Regenerating the definitions

`src/defs.rs` is written by the `gen` example, the same generator msedit
runs from its build script, with two changes: the compiler's IR dump is left
out (it prints node addresses, so it differs on every run) and
`HighlightKind` also derives `Hash`.

```sh
cargo run --release -p syntax --example gen            # writes src/defs.rs
cargo run --release -p syntax --example gen -- --stdout
```

The lsh compiler panics on patterns it does not support, so it runs only
here and in the tests (`syntax::compiler`, hidden from the docs), never
inside an editor. The crate has no features.

## Source layout

| Path | What |
|---|---|
| `src/lib.rs` | Language lookup, `LineSource`, the hidden `compiler` module |
| `src/highlighter.rs` | `Highlighter`, `HighlighterState`, `Span`, `MAX_LINE_LEN` |
| `src/cache.rs` | `Cache` and `INTERVAL` |
| `src/defs.rs` | Generated bytecode, strings, charsets and language tables |
| `examples/gen.rs` | The generator for `src/defs.rs` |

## Tests

- `tests/defs_fresh.rs`: the committed `src/defs.rs` matches a fresh
  generation byte for byte; two generations in one process agree; every
  file association points into `LANGUAGES`, and the lookups work.
- `tests/highlighter.rs`: spans are absolute and ordered; any chunk size
  gives the same spans as one slice; `INTERVAL` stays 1024; over-long lines
  are plain and keep later line numbers, with and without a line index;
  reading past the end is empty; `advance` makes progress below one interval
  per call; and a proptest checks that random seeks, also after an edit and
  `invalidate_from`, equal a linear parse. An ignored benchmark times
  over-long lines with and without a line index.

---

<!-- page: https://mixos.dev/system/ (source: https://mixos.dev/system/README.md) -->

# system

The system binary, `mix`: the Mix shell and its enabled headless daemon
personalities in one file
([decision](../docs/decisions/2026-10-12-one-system-binary.md)).

The default Cargo features include `noded`, `monitord`, `maild`, `webd` and
`dnsd`; each is optional. Services such as `settingsd`, `hostd`, `portald`
and `compd` still build their own executables. The one-system-binary
decision describes the architecture; the features in
[`cli/system/Cargo.toml`](https://github.com/markc/mixos/blob/main/cli/system/Cargo.toml)
and dispatcher are the current personality inventory.

The binary picks a personality from the basename of argv[0]. Started as
`mix` it is the shell ([mix-shell](../mix-shell/README.md),
`mix_shell::main`); started through a symlink named `noded` it is the node
daemon ([noded](../noded/README.md), `noded::main`). Each daemon still runs
as its own process, under its own unit and journal identity. This package
holds only the dispatcher and the global allocator (mimalloc); each
component keeps its own crate, tests, version and units.

```text
cargo build --locked --profile release-fast -p system --bin mix
                                              # target/release-fast/mix
mix --personalities                            # each personality and its component version
ln -s mix noded                                # noded, as its own process
```

An unknown name exits 2 and prints the personalities. A login shell's
`-mix` is the shell.

The Mix language is documented in the [Mix manual](../mix/README.md).

## Tests

`cargo test -p system` runs the identity test (`tests/personalities.rs`) and
the shell's process-level tests, which moved here from `cli/mix-shell` so
they test the shipped binary. Their scripts moved with them
(`tests/scripts`); the manual they check is the site source
([`docs/mix`](../mix/README.md)), and the source guards read
`cli/mix-shell/src`.

The source is [`cli/system`](https://github.com/markc/mixos/tree/main/cli/system).

---

<!-- page: https://mixos.dev/term/ (source: https://mixos.dev/term/README.md) -->

# Terminal

`term` is the MixOS terminal (app id `dev.mixos.term`): tabs, split panes,
and a grid drawn on the GPU. It is an egui shell (see
[AGENTS.md](https://github.com/markc/mixos/blob/main/AGENTS.md) §4.1) around
two private crates:

- `crates/term-core`: the engine. PTYs, the VT grid, tabs and panes,
  selection, mouse reporting, configuration, the native session and the
  `term.*` Bus verbs.
- `crates/term-render`: the grid on the GPU. A glyph atlas and instanced
  cells drawn by an egui-wgpu paint callback per pane. The CPU raster in
  term-core is its test oracle.

The shell adds the window: the toolkit title bar and menus, the tab strip,
pane borders on whole physical pixels, the keyboard and input method, the
pointer (selection, mouse reporting, middle-click paste of the primary
selection), the clipboard, and font zoom. Every action is a command on the
toolkit registry, published on `term.command.executed`.

The source is [`apps/term`](https://github.com/markc/mixos/tree/main/apps/term).

## Bus

The window registers `term` (or `term-<pid>` when another instance holds
it) and answers:

- the terminal's verbs, served by term-core (`HELP` lists them):
  `term.session`, `term.tabs`, `term.tab.*`, `term.panes`, `term.pane.*`,
  `term.snapshot`, `term.scroll`, `term.type`, `term.props.watch`;
- the window's own: `term.commands`, `term.execute`, `app.describe`, and the
  toolkit drive verbs (`term.ui.*`, `term.window`, `term.window.state`).

`term --headless` serves the terminal's verbs with no window.

## Configuration

The desktop profile's `terminal.*` settings, held by
[settingsd](../settingsd/README.md) and edited in [Prefs](../prefs/README.md):
font family, size and weight, padding, border width, history lines, scroll
speed, cursor shape and blink, the focus ring, copy on select, and `TERM`.
The window follows them as they change; Ctrl+plus and minus write
`terminal.font.size` back 400 ms after the last zoom key. Ctrl+0 returns to
the profile size without writing, except to correct a write already in
flight. An unsaved zoom stays pending in memory until another zoom key or a
successful settings read; a validation refusal discards it. Failures
schedule no retry timers. History lines and `TERM` apply to tabs and panes
opened afterwards. Without settingsd the defaults stand, and zoom stays the
window's own. `TERM_FONT_PX` sets the size until settingsd answers, and
`TERM_SPIKE_FONT` overrides the font file; `term --print-config` prints the
startup values.

## Keys

`term --help` lists them. Tabs: Ctrl+Shift+T/W, Ctrl+PageUp/PageDown.
Panes: Ctrl+Shift+E/O split, Ctrl+Shift+X close, Ctrl+Shift+arrows,
Tab/Shift+Tab or Ctrl+Tab between split panes. Clipboard: Ctrl+Shift+C/V,
Shift+Insert. Font: Ctrl+plus/minus/0 and Ctrl+wheel. History:
Shift+PageUp/PageDown/Home/End. Alt is Meta (ESC before the key; Alt+cursor
keys send xterm's CSI 1;3 sequences). Right-hand modifier chords are the
person's own on MixOS and are not bound.

## Building and testing

On an authorised build worker at a pushed commit:

```
cargo test --locked -p term-core -p term-render -p term
cargo build --locked --profile release-fast -p term
```

`tests/window.rs` takes an offscreen snapshot of the window with two tabs
and a split; regenerate it with `UPDATE_SNAPSHOTS=1` and look at it. The
PTY tests need the Mix binary at `/opt/mixos/bin/mix`.

---

<!-- page: https://mixos.dev/test-broker/ (source: https://mixos.dev/test-broker/README.md) -->

# test-broker

Development fixture for the Term-to-Mix native session acceptance tests.
It includes the actual [noded](../noded/README.md) modules from their owning
service and a copy of Term's sealed-FD implementation
(`src/session_fd.rs`, from term-core; it returns to term-core when Term is
ported to egui). It has no broker copy or simulated session transport. The
fixture controls an isolated broker runtime, verified Unix ingress, restart
and pause boundaries.

The source is [`libs/test-broker`](https://github.com/markc/mixos/tree/main/libs/test-broker).

---

<!-- page: https://mixos.dev/thumbs/ (source: https://mixos.dev/thumbs/README.md) -->

# thumbs

File thumbnails the way the freedesktop desktops make them. A thumbnail
lives in the shared cache (`$XDG_CACHE_HOME/thumbnails`, the Thumbnail
Managing Standard), so one made by another file manager shows at once, and
the reverse. A missing one is made by a thumbnailer installed on the system
(a `.thumbnailer` entry, the contract GNOME, COSMIC and glycin share). It
runs as a plain argv in its own process group under a timeout, and its
output is checked before it is cached. Thumbnailers reach every format the
system knows, and keep decoders MixOS cannot ship under its licences
(FFmpeg-backed video, for one) in their own process.

The crate is headless: no toolkit, no pixels. Showing a cached thumbnail is
`toolkit::thumbnail`'s part.

- `Pool<K>` makes thumbnails off the caller's thread. Each `Request` has a
  `lane` (a new request replaces the one waiting in its lane) and a
  `Ticket` (a shared generation counter: bump it when the view moves on,
  and its requests are dropped or their runs killed). Replies go to the
  callback given to `Pool::new`, which also names the app the cache is
  written as.
- `generate::Generator` makes one thumbnail. Everything that touches the
  file before its thumbnailer runs happens on a probe thread under a
  deadline, so a hung filesystem strands a thread, never a worker.
- `mounts` refuses network, FUSE and automounted files from the mount table
  before anything touches them.
- `cache`, `png` and `registry` are the cache, the few PNG facts it needs,
  and the installed thumbnailers.

Users: [DOpus](../dopus/README.md) (the Properties preview). Build and test
with `cargo test -p thumbs`.

The source is [`libs/thumbs`](https://github.com/markc/mixos/tree/main/libs/thumbs).

## Known limits

- Output is checked structurally, never decoded (no decoders here), so a
  well-formed PNG with corrupt image data is cached as ready. The display
  side shows the type icon for it until the file changes.
- There is no way to withdraw one lane's waiting request short of making
  its ticket stale. A folder view that scrolls will want one; it can be
  added without changing what exists.
- The PNG and mountinfo parsers have unit tests but no fuzz targets yet.

---

<!-- page: https://mixos.dev/toolkit/ (source: https://mixos.dev/toolkit/README.md) -->

# Toolkit

`toolkit` is the library every MixOS egui application is built on. It is
the shell layer of the
[egui applications decision](../docs/decisions/2026-10-09-egui-applications.md)
(see [AGENTS.md](https://github.com/markc/mixos/blob/main/AGENTS.md) §4.1).
An app keeps its behaviour in a headless engine and its UI state in one
serialisable struct. The toolkit draws the window around that state and
routes every action through one command registry.

The UI-free registry and Fluent `Strings` now live in
[`command`](../command/README.md). Toolkit keeps the egui adapter and its
existing nullary command API, with the moved data types re-exported.
Core and toolkit `describe()` emit stored chords in the keymaps grammar
(`Ctrl+=`, `ArrowLeft`, or short forms), ordered Ctrl, Alt, Shift. Executed
events use the command 0.2.0 v2 body with bounded params and result, and the
legacy wrapper maps authorisation refusals to `CommandError::Denied`.

It gives each app:

- the resolved [design](../design/README.md) as an egui style, plus the
  embedded Inter and JetBrains Mono faces and the Lucide icons;
- the client-side title bar, menu bars and menus, and the View › Theme
  submenu;
- the chrome components (bars, buttons, panels, tabs, fields, toggles,
  combos, sliders, canvas scrollbars, tooltips, dialogs), drawn to the
  chrome specification in each chrome scheme;
- the command registry, which generates menus, shortcuts, the palette and
  the Bus surface, and records every executed command;
- the drive verbs, the UI-level Bus verbs that every app shares;
- Fluent string catalogues, a key-chord grammar, and thumbnail decoding.

The source is
[`libs/toolkit`](https://github.com/markc/mixos/tree/main/libs/toolkit).

## Who uses it

The apps [term](../term/README.md), [ced](../ced/README.md),
[dopus](../dopus/README.md), [prefs](../prefs/README.md),
[screenshot](../screenshot/README.md), [backdrop](../backdrop/README.md)
and busviewer; the [editor](../editor/README.md) library; and four of
[compd](../compd/README.md)'s crates (`decor`, `ui`, `scene-host`,
`world`). backdrop is the only one that turns on the `layer` feature.

## Starting an app

Call `toolkit::install(ctx, &theme)` once on the egui context. It installs
the image loaders the icons need and applies the theme's style and fonts.
`Theme::load()` reads the shared `theme.conf.mix` from the MixOS etc
directory (`$MIXOS_ETC`, else `$MIXOS/etc`, else `/etc/mixos` for root,
else `$XDG_CONFIG_HOME/mixos`). It falls back to the embedded design, and
says why on stderr, when the file is missing or unusable.

A minimal window, condensed from `tests/snapshot.rs`:

```rust
use toolkit::command::{Command, Registry, always};
use toolkit::{Icon, Strings, Theme, icons};

#[derive(Default)]
struct Demo { refreshed: u32 }

let mut commands = Registry::new();
commands.add(Command {
    id: "bus.refresh",           // stable, never reused once published
    label: "cmd-refresh",        // Fluent key
    menu: Some("menu-bus"),      // Fluent key of the top-level menu
    submenu: None,
    group: 0,
    shortcut: Some(egui::KeyboardShortcut::new(egui::Modifiers::COMMAND, egui::Key::R)),
    icon: Some(Icon::RefreshCw),
    enabled: always,
    run: |s: &mut Demo| s.refreshed += 1,
});

let theme = Theme::load();
toolkit::install(ctx, &theme);
let strings = Strings::new(include_str!("../i18n/en/demo.ftl"));
let stroke = icons::stroke_width(&theme);

// each frame:
let _ = toolkit::titlebar::show(ui, "Demo", Some(Icon::Server), stroke,
                                &commands, &state, &strings);
```

## Main pieces

### Theme and look

- `theme`: `Theme` holds a resolved design together with the context it
  was compiled for (scheme, style, mode, contrast) and its framing
  (server- or client-side decorations, caption side). Build one with
  `Theme::embedded()`, `for_context`, `from_source` (a full design
  document or a selection-only file) or `load()`. Then adjust it with
  `with_choice`, `framed` and `with_overlay`.
- `session_look`: turns the desktop profile's appearance, as
  [settingsd](../settingsd/README.md) holds it, into a `Theme`. It is pure,
  with no Bus and no I/O. An appearance that names a design this build
  does not know leaves the app's session theme in place.
- `theme_menu`: the View › Theme submenu, added with
  `Registry::theme_menu`. It covers the hue schemes (Ocean, Crimson, Stone,
  Forest, Sunset, Mono), the chrome schemes (Pro, Studio, Classic), modes,
  styles and framing. Command ids are `view.theme.<scheme>`,
  `view.mode.*`, `view.style.*`, `view.decorations.*` and
  `view.captions.*`, and each axis can follow the session.
- `style`: maps a hue scheme's design onto egui's `Style`. The module docs
  give the field-by-field mapping table.
- `chrome`: the colours and geometry of the title bar and menus. For the
  chrome schemes (`pro`, `studio`, `classic`) it supplies the whole egui
  style, taken from the design's chrome family. Components read
  `Chrome::style` and `Chrome::metrics` and never ask which scheme they are
  drawing, so a new style needs only design data. See the
  [chrome family decision](../docs/decisions/2026-10-09-chrome-family-and-schemes.md).
- `fonts`: the embedded faces. Weight is a design token: each typography
  role names a weight, and the static Inter file of that weight is the one
  installed. Monospace is JetBrains Mono.
- `icons`: Lucide icons, from unmodified upstream SVGs. The `Icon` enum
  names them. Stroke width comes from the design metric
  `icon.stroke_width`, and colour comes from the widget's text colour at
  draw time. See the
  [icons and type decision](../docs/decisions/2026-10-09-icons-and-type.md).

### Window chrome and components

- `titlebar`: the client-side title bar. From the left it holds the app
  mark, the registry's menus, the centred title, an optional right-hand
  group of controls, and the minimize, maximize and close buttons. Captions
  can be on the left instead. A window opened with `titlebar::viewport` is
  undecorated. Only the free gap between the menus and the buttons drags
  the window. Call `titlebar::edges` last in the frame to add the resize
  zones. Under server-side decorations the row becomes a plain menu bar.
- `menu`: menu bars and menus drawn by the toolkit, not by egui's
  `MenuBar`. One highlight is shared by pointer and keyboard, a menu opens
  on press, and press-drag-release runs an item. `Nav` holds the open menu
  and its highlights as pure data and is tested without egui.
- `bars`, `button`, `panel`, `tabs`, `field`, `toggle`, `combo`, `slider`,
  `canvas`, `tooltip`, `dialog`: the chrome components (options, status
  and tool bars, icon rail, push and icon buttons, dock panel groups,
  document tabs, value, text and search fields, checkboxes and switches,
  combo boxes, sliders, canvas scrollbars, tooltip wording, and modal
  dialogs).
- `markdown`: Markdown drawn natively. `Document::parse(&str)` turns
  CommonMark with GFM tables, strikethrough and task lists into plain data
  (pulldown-cmark, parser only), so an app parses once and keeps the
  document in its state. `markdown::show(ui, &document)` draws it every
  frame from the theme: heading sizes stepped from the `Heading` style,
  code in the monospace face on the field surface (scrolled sideways,
  never wrapped), quotes after a rule, lists with read-only task boxes,
  striped tables, rules and links. Each text run is one selectable label.
  Links go to `Context::open_url` only for http, https and mailto
  (`markdown::openable`), with the address on hover, and `show` returns
  the link clicked. Images are never fetched (the alt text links to
  them) and raw HTML shows as text. `markdown::looks_like_markdown(&str)`
  is a conservative test for plain text written as Markdown: one fence,
  table or pair of headings, or two distinct signals among a heading, a
  list, bold or emphasis, inline code, a link and a non-reply quote,
  scanned outside quoted lines and the signature. The email reader uses
  both.

### Commands

- `command`: `Command<S>` is one action, with an id, a label key, a menu
  and submenu, a group, a shortcut, an icon, an `enabled` rule and a `run`
  handler over the app's state `S`. A handler only changes state. Work that
  leaves the process, such as a Bus call or a file write, is queued on the
  state for the app's effect loop. `Registry<S>` provides `add`,
  `add_choice`, `add_toggle`, `execute(id, state, origin)`, `describe`,
  `menus` and `model`, `shortcuts`, `search`, `shortcut_grid` and `rebind`.
  The UI, the command line and Bus verbs all dispatch by id.
- `executed`: every run is recorded with its `Origin` (`menu`, `shortcut`,
  `palette`, `ui`, `bus`, `macro`) and given a per-process sequence number.
  It goes into a bounded `Journal` that counts the runs it drops.
  `Registry::take_executed` hands the records to the app's Bus connection,
  which publishes them on `<app>.command.executed`
  ([decision](../docs/decisions/2026-10-11-executed-commands.md)).
- `keymap`: the chord grammar (`Ctrl`, `Alt`, `Shift`, then one key, joined
  by `+`). `Registry::rebind` applies the person's bindings from the
  desktop profile.

### Drive verbs

`drive` lets an agent do in the window anything a person can.
`drive::install(ctx, app)` turns on AccessKit, keeps each pass's widget
tree, and injects queued pointer and key events through egui's input hook,
the same path real input takes. The app registers these verbs under its own
prefix (`<app>.ui.tree` and so on):

`ui.tree`, `ui.click`, `ui.pointer`, `ui.scroll`, `ui.key`, `ui.type`,
`ui.menu`, `ui.menu.list`, `ui.menu.open`, `ui.menu.close`, `ui.capture`,
`window`, `window.state`

The app forwards each request, with the prefix removed, to
`drive::request` from inside a frame. It sends back whatever `request`, or
`drive::logic` (called once per frame), returns. It holds later commands
while `drive::pending` is true, and calls `drive::finish` before closing.
Reads answer at once. Input verbs run one at a time, one step per pass,
and answer one pass after their last step. At most 32 input requests can
be queued. The [driving guide](../docs/drive.md) shows them in use.

### Strings, thumbnails, layer surfaces

- `strings`: `Strings::new(ftl)` wraps an app's Fluent catalogue
  (`i18n/en/<app>.ftl`). It provides `get`, `with` (with arguments) and
  `has`. A missing key renders as the key itself, so a gap shows on screen
  instead of a blank. The toolkit's own labels, such as window buttons and
  the Theme menu, are in `i18n/en/toolkit.ftl`.
- `thumbnail`: decodes cached thumbnail PNGs within explicit size limits
  on a `Decoder` thread, ready to upload as textures. Making the
  thumbnails is the job of [thumbs](../thumbs/README.md).
- `layer` (feature `layer`): egui programs on wlr-layer-shell surfaces,
  such as wallpapers, desktops and docks. `layer::run(options, program)`
  creates one surface per output (`Outputs::Each`), or a single surface
  the compositor places. Each surface has its own egui context and draws
  through wgpu's GL backend on its `wl_surface`. It follows fractional
  scale and takes pointer, scroll and optional keyboard input. It redraws
  only when something changes, so an idle surface costs nothing.

## Features and dependencies

The default build has no features. `layer` adds smithay-client-toolkit
0.19.2 (the version eframe's winit already links), wayland-backend, wgpu,
egui-wgpu and xkbcommon. Workspace dependencies: `assets`, `config`,
`design`, `settings` (data types only, no Bus) and `thumbs`.

## Assets and licences

`assets/fonts/` holds static Inter (Light, Regular, Medium, SemiBold) and
JetBrains Mono (Light, Regular, Medium) faces with their OFL texts.
`assets/icons/` holds the Lucide SVGs with `LICENSE-lucide.txt`, and
mixos.dev uses the same icons. `assets/licenses.conf.mix` pins each notice
by SHA-256. This includes the notices for egui's own fallback fonts, which
are in `assets/fonts/fallbacks/`.
`scripts/install_licenses.mix` installs them under
`<share>/licenses/toolkit` (default share `/opt/mixos/share`). `--check`
validates only the sources, and `--verify` checks an installed tree. See
the [bundled font licences decision](../docs/decisions/2026-10-13-bundled-font-licences.md).

## Source layout

| Path | What |
|---|---|
| `src/lib.rs` | module list and `install` |
| `src/theme.rs`, `theme_menu.rs`, `session_look.rs`, `style.rs`, `chrome.rs` | the look |
| `src/fonts.rs`, `icons.rs` | embedded faces and Lucide icons |
| `src/titlebar.rs`, `menu.rs` | window chrome |
| `src/bars.rs` … `src/dialog.rs` | chrome components |
| `src/command.rs`, `executed.rs`, `keymap.rs` | commands, executed records, chords |
| `src/drive.rs` | the drive verbs |
| `src/strings.rs`, `thumbnail.rs` | Fluent strings, thumbnail decoding |
| `src/layer.rs`, `src/layer/` | layer-shell surfaces (feature `layer`) |
| `i18n/en/toolkit.ftl` | the toolkit's own strings |
| `assets/`, `scripts/install_licenses.mix` | fonts, icons, licence notices |

## Testing

Unit tests sit in the modules; for example `menu::Nav` is tested as plain
data. The integration tests in `tests/` drive real frames through
`egui_kittest`:

- `components.rs`, `menu.rs`, `titlebar.rs`, `chrome.rs`: component, menu
  and title-bar behaviour under pointer and keyboard;
- `drive.rs`: the drive verbs, requested inside frames the way an app's
  shell requests them;
- `snapshot.rs`, `components_snapshot.rs`: offscreen wgpu snapshots across
  schemes and modes, compared with `tests/snapshots/*.png`. Regenerate them
  with `UPDATE_SNAPSHOTS=1`, and look at the images before committing;
- `spec_renders.rs`: when `CHROME_RENDER_DIR` is set, it renders the
  chrome scenes for an out-of-tree comparison against the chrome
  specification's evidence. When it is unset, it does nothing;
- `asset_licenses_test.mix`: install, drift and verify checks for the
  licence installer.

On an authorised build worker at a pushed commit:

```
cargo test --locked -p toolkit
cargo test --locked -p toolkit --features layer
```

---

<!-- page: https://mixos.dev/toolkit/style-guide/ (source: https://mixos.dev/toolkit/style-guide.md) -->

# MixOS GUI app style guide

---

## 1. The three rules

1. **One look per window context.** Install the theme once per egui
   context (one for a single-window app). Read everything back from the
   context. Thread nothing.
2. **Tokens and widgets, never literals.** A length is a token. A colour is
   a role. A control is a toolkit widget.
3. **The look is on the Bus.** Every app answers `<app>.look`, publishes
   `<app>.look.changed`, runs `view.look.preview` and `view.theme.set`, and
   follows the session's tunables through settingsd without a restart and
   without polling.

## 2. Crates and dependencies

An app is two crates: an engine crate under `apps/<app>/crates/<name>` that
knows nothing about egui, and the egui shell crate `apps/<app>`. The shell
crate's `Cargo.toml` lists, as busviewer's does:

```toml
[dependencies]
eframe.workspace = true      # the window
egui.workspace = true        # labels and layouts the toolkit does not wrap
toolkit.workspace = true     # theme, chrome, widgets, commands, drive verbs
settings.workspace = true    # the session look follower
citizen.workspace = true     # the Bus connection
bus = { workspace = true, features = ["native"] }   # the native client citizen is built on
futures.workspace = true     # the connection's delivery stream
serde_json.workspace = true  # verb bodies

[dev-dependencies]
egui_kittest.workspace = true  # offscreen snapshots and accessibility queries
```

The toolkit does not re-export egui or eframe. The engine crate depends on
none of these; the layering table (`apps/layers.conf.mix`) refuses egui,
eframe, egui-wgpu, winit and rfd in its closure. A nested GUI crate (a
renderer that draws into a texture) is held to this guide and its gate like
the shell.

## 3. The minimal app

The full example is `libs/toolkit/examples/guide_app.rs`. Its shape, which
every shipped app shares:

- **Start:** `citizen::start_with_topics(app, service, url, topics)` with
  the settings summary topic gives the Bus handle and a stream of
  deliveries; `Theme::load()` gives the theme file or the embedded design;
  `toolkit::install(ctx, &theme)` and `drive::install(ctx, app)` are called
  once in the eframe creator; the app's strings are `Strings::new` over its
  embedded Fluent catalogue.
- **Forwarder:** one thread drains the delivery stream into the shell's
  inbox and calls `ctx.request_repaint()` for every event, so an idle
  window wakes for a settings hint, a Bus command or a disconnection.
- **`App::logic`** (eframe's per-frame hook before drawing) drains the
  inbox: `Connected`, `Changed` and a summary `Topic` hint ask the follower
  for a read; `Disconnected` resets the follower (so the next connection
  reads afresh and gets an identity-bearing look even at an unchanged
  revision), voids retries and clears the authority and any preview;
  `Command` is served (`<app>.look` and `<app>.execute` through the look
  layer, then the shipped drive layer's `request`, whose queued answers come
  back from `drive::logic` each frame); a read's answer goes to `looked`,
  whose returned `next` read is sent exactly as returned; a transient fault
  arms one bounded retry.
- **`install_theme`** is the only place the look changes: the follower's
  inputs for this app (or the theme file) with the window's own choice laid
  over, installed on the context; every call bumps the window's look
  generation and publishes `<app>.look.changed`; it clears a preview,
  except when it is the arrival of the window's pinned source, which keeps
  the preview. Before installing, it checks the window's final token pair
  against the design's constraints; a violating pair is not installed, the
  last valid look stays, and `<app>.look` reports the violation.
- **`App::ui`** draws the title bar on the root `Ui` with
  `toolkit::titlebar::show` (no stroke argument; it reads the context) and
  the content inside `egui::Frame::central_panel`.

**What the lifecycle guarantees.** The first read happens at start; every
later read is caused by a summary delivery, a connection event or a
retry; a delivery is never trusted on its own; an older revision never
replaces a newer one (the follower checks); without settingsd the theme
file stands. There is no timer.

**Which design the app draws.** The profile's pinned design source. When
the summary's source digest (BLAKE3 of the source bytes,
`settings::source_digest`) equals that of the design the binary carries,
the app compiles that; otherwise it fetches the pinned source once with
`settings.source`, verifies it with the same digest, caches it per user in
a private directory it has checked it owns, and compiles it for the
window's own axes, drawing the embedded design until it arrives. A reply
activates only for a window that still wants that digest, resolving the
window's current inputs and keeping its current preview; a late or
superseded one only fills the cache. One fetched source serves every
window and light region of the app without another fetch. `<app>.look`
reports which was compiled and the acquisition state. A profile with its
own design source is therefore an ordinary profile: the session look,
tunes and previews apply. An app connects to the broker over the local
Unix endpoint when one is named, which is what lets the compositor
attribute its windows; over TCP it works the same but its windows draw the
session look under server decorations.

**Reading the look in view code.**

| need | read |
|---|---|
| a colour | `Chrome::of(ui.ctx()).palette.<role>` |
| a chrome length | `Chrome::of(ui.ctx()).metrics.<name>` |
| a style form (cards or strips, switch or checkbox, bevels) | `Chrome::of(ui.ctx()).style.<token>` |
| the icon stroke | `toolkit::icons::stroke_of(ui.ctx())`, or just use `IconButton` |
| a gap | `toolkit::space::of(ui.ctx()).md` (xs, sm, md, lg, xl) |
| field radius, padding and focus | `toolkit::field::Style::of(ui.ctx())`, or just use the field widgets |
| dim or faint text | `toolkit::text::dim(s)`, `toolkit::text::faint(s)`, `toolkit::text::role(s, role)` |
| a behaviour value (double-click time, scrub rate, hit tolerance) | `Chrome::of(ui.ctx()).style.<token>` |

Never pass any of these into a function as a parameter.

Desktop icons share the context's canonical 1.5 stroke on the 24-unit
icon grid. Use `icons::image_of` or the toolkit icon widgets. Older test
fixtures that passed 2.0 explicitly use the canonical default too. The
existing `appearance.icon_stroke` session choice remains supported.

Local style overlays are fallible: handle `Theme::with_overlay` and
`Theme::with_choice` errors before installing a look. A refused overlay
must leave the installed look intact. `canvas_dot_pitch` accepts 4 to
1000 points, preventing zero or impractically dense drawing loops.
For a colour tunable with a numeric range, the bounds apply to each
normalised colour component. The value itself remains a hexadecimal
colour; `icon_mask` requires every channel to be at least 0.1.

```rust
fn view(ui: &mut egui::Ui, engine: &Engine) {
    let space = toolkit::space::of(ui.ctx());
    let p = Chrome::of(ui.ctx()).palette;
    ui.label(format!("Count: {}", engine.count));
    ui.add_space(space.md);
    ui.add(toolkit::button::IconButton::new(Icon::Settings).tooltip("Settings"));
    ui.add(toolkit::text::dim("dim text"));
    let _ = p.accent;                               // read where you paint
}
```

## 4. Which toolkit widget for each need

| need | use | not |
|---|---|---|
| a text input, one line | `field::text(ui, &mut s, hint, width)` | `egui::TextEdit::singleline` |
| a search box | `field::search(...)` | a text edit with an icon beside it |
| a multi-line editor | `field::multiline(...)` | `egui::TextEdit::multiline` |
| a number with a unit, scrubbing, arithmetic | `field::ValueField::new(&mut v, range).unit("px")` | `egui::DragValue`, `egui::Slider` |
| a labelled form | `form::Form` rows (§5) | `egui::Grid` |
| a default or secondary action | `PushButton::primary(label)`, `PushButton::secondary(label)` | `ui.button`, `egui::Button::new` |
| an icon button | `IconButton::new(Icon::X).tooltip(...)` | `ImageButton` |
| a link with an icon | `button::Link` | a hyperlink label |
| an on/off | `toggle::Toggle` | `ui.checkbox` |
| a list of choices | `combo::show` | `egui::ComboBox` |
| a slider or a slider row | `slider::Slider`, `slider::row` | `egui::Slider` |
| a scrolling region | `scroll::Area::vertical(id).show(ui, ...)` | `egui::ScrollArea` (any constructor) |
| a table | `datatable::DataTable` | `egui_extras::TableBuilder` |
| a dock group with tabs | `panel::group`, `panel::group_with_actions` | a `Frame` with a header |
| a section heading | `panel::section_label` | a bold label |
| a bar | `bars::options`, `bars::status`, `bars::tools`, `bars::rail` | a `TopBottomPanel` with a fill |
| a hairline or divider | `bars::hairline`, `bars::divider` | `ui.separator()` |
| a modal | `dialog::Dialog` with `Choice`s | `egui::Window` |
| a tooltip | `.tooltip(...)`, `tooltip::text` | ad-hoc `on_hover_text` wording |
| menus, context menus, the Theme menu | the registry's `menu_bar`, `menus`, `context_menu`, `theme_menu::register` | `egui::menu`, a theme verb |
| a selectable row | `toolkit::selectable` | `selectable_label` |
| dim, faint or coloured text | `toolkit::text::{dim, faint, role}` | `RichText::color`, `::font`, `::size` |
| rendered markdown | `markdown::View` | your own layout |
| a document canvas with scroll bars | `canvas::surround`, `canvas::scrollbars` | your own |
| a prose region that may be light | `content::surface(ui, &content, ...)` | `ui.set_style`, `style_mut` |
| a thumbnail | `thumbnail::Decoder` | your own decoder |

A plain `ui.label` is fine. **When no widget fits,** write it in the
toolkit, not the app: read its colours and lengths from `Chrome`, name the
spec section, snapshot it, then use it.

## 5. The form row

Labels outside the field in one right-aligned column as wide as the widest
label the form can show; `form_label_gap` to the field; trailing controls
right to left `form_trailing_gap` apart; the field takes the remainder;
rows `form_row_gap` apart; the label's id is the field's accessible name.

```rust
let form = toolkit::form::Form::new(ui, &["From", "To", "Cc", "Subject"]);
form.row(ui, "To", |ui, label_id| {
    ui.with_layout(egui::Layout::right_to_left(egui::Align::Center), |ui| {
        if ui.add(IconButton::new(Icon::Copy).tooltip(cc_hint)).clicked() { /* ... */ }
        field::text(ui, &mut to, "", ui.available_width()).labelled_by(label_id)
    })
});
```

A row taller than a field uses `row_of` with its height.

## 6. Spacing

| token | shipped | use for |
|---|---|---|
| `xs` | 2 | hairline clearance, icon to its text |
| `sm` | 4 | between related controls in a row |
| `md` | 8 | between groups in a row, panel inner padding |
| `lg` | 16 | between sections |
| `xl` | 24 | one control height; dialog outer margin |

`ui.add_space(space.md)` is the approved form; the gate refuses a literal
argument, not the method. An app never sets `item_spacing`,
`button_padding` or `interact_size`, and never calls `spacing_mut`,
`visuals_mut`, `style_mut` or any `Context` style setter.

A `const` is allowed only for content geometry (a column width, a thumbnail
edge, a glyph size in a custom painter), named in capitals, commented, and
listed in the app's `style-allow.conf.mix` with the reason.

## 7. Scroll areas

```rust
toolkit::scroll::Area::vertical("messages")      // the id salt: stable, unique in the window
    .max_height(h)
    .stick_to_bottom(true)
    .show(ui, |ui| { /* rows */ });
```

Also `Area::horizontal`, `Area::both`, `.min_scrolled_height`,
`.scroll_to(rect)`. It wraps egui's scroll area, so drag, page click,
wheel, keyboard, nesting and two-axis behaviour are egui's; the toolkit
supplies the defaults (no auto-shrink) and the style's bar: thin floating
bars 4 pt at rest and 10 pt when hot, or solid 6 pt in a bevelled style,
the handle in the state's text colour at the resting opacity, the track
only while hot, all from tokens. Clippy refuses every `egui::ScrollArea`
constructor by path.

## 8. Icons

Lucide, from the toolkit's `Icon` enum. A new icon is added to the toolkit
(copy its SVG from the pinned Lucide release into
`libs/toolkit/assets/icons/`, list it in `icons.rs`), never embedded in the
app. Icons take the stroke installed on the context and the colour of the
text around them. Sizes: `IconButton` is the `icon_button` token (28) with
the icon at 52 %; an inline icon uses `space.lg` or an allowlisted content
constant through `paint_icon`.

## 9. Menus, context menus, the palette, the Theme menu

Every action is a registry command with a stable id, a label key, a menu
path, an optional default chord and typed parameters. The toolkit generates
the menu bar, menus, context menus and palette from the registry. Right-click
rows are 24 pt and flush. The View › Theme submenu is
`toolkit::theme_menu::register`: its rows are commands, and
`view.theme.set {scheme?, style?, mode?, decorations?, captions?}` is the
same choice for agents. An app writes no theme verb of its own. The
window's choice reaches the compositor too: a server-decorated window's
title bar is drawn from the window's own look, attributed through the
broker's record of the app's connection. A multi-window app's extra
windows are matched by their toplevel tag once the toolkit sets one; until
then they draw the session look under server decorations.

## 10. Dialogs

`dialog::Dialog::new(id, title)` with `Choice`s carrying a `Role` so button
order, Enter and Esc follow the platform rule. Wide dialogs use `.width`;
resizable ones `.resizable(default, min)`. A destructive prompt opens with
its default focused and ringed.

## 11. Content regions

Chrome is what the toolkit paints from `Chrome`. Content is what the person
reads or edits. Content keeps its own colours on purpose, but it is on the
look:

- a prose region drawn with `content::surface` takes the person's content
  settings (padding, font, light). A region with `light: true` draws **the
  installed window's** design, scheme, style and overlays (tunes and
  preview included) with only the mode forced to light; one with
  `light: false` inherits the window as it is;
- an editor palette is built from the region's theme
  (`editor::Palette::from_theme`), never from literals;
- a terminal grid draws the `terminal.colors` settings over the design's
  colour table for the session's scheme and mode, with the running
  program's palette changes over them until it resets them, and explicit
  RGB cells as sent.

`<app>.look` reports every content region under `regions`: a prose or
editor region with the palette and font it draws with; a terminal region
with its design defaults, the settings entries, the runtime overrides in
force, the effective palette and its cursor rule.

## 12. What is forbidden in an app (and what checks it)

Clippy, by resolved path (an alias or a `use` cannot dodge it), and
`tools/style_gate.mix`, for literals and shapes, refuse these in every
egui-dependent crate under `apps/`, tests excluded:

| refused | use instead |
|---|---|
| `egui::TextEdit::singleline`, `::multiline` | `field::text`, `field::multiline`, `field::search` |
| `egui::ScrollArea::vertical`, `::horizontal`, `::both`, `::new` | `toolkit::scroll::Area` |
| `egui::Grid::new` | `toolkit::form`, `datatable` |
| `egui::Ui::button`, `egui::Button::new` | `PushButton`, `IconButton`, `Link` |
| `egui::Ui::checkbox` | `toggle::Toggle` |
| `egui::ComboBox::from_id_salt`, `::from_label` | `combo::show` |
| `egui::Slider::new`, `egui::DragValue::new` | `slider::Slider`, `field::ValueField` |
| `egui::Ui::style_mut`, `set_style`, `spacing_mut`, `visuals_mut`; `egui::Context::set_style`, `set_global_style`, `set_visuals`, `set_fonts`, `global_style_mut`, `all_styles_mut`, `style_mut_of`, `set_style_of` | `toolkit::install`; `content::surface` for a region |
| `egui::RichText::font`, `::size`, `::color` | `toolkit::text::{dim, faint, role}`; the heading style |
| `toolkit::icons::stroke_width`, `Chrome::for_theme`, `style::apply`, `chrome::install` | `icons::stroke_of(ctx)`, `Chrome::of(ctx)`, `toolkit::install` |
| `ui.add_space(<number>)`; `vec2(<number>, <number>)` or `Vec2::splat(<number>)` as spacing | the `space` tokens |
| any assignment to `item_spacing`, `button_padding`, `interact_size` | nothing: the style owns them |
| `Color32::from_rgb`, `from_gray`, `from_hex`, `from_rgba_*`, `WHITE`, `BLACK` | a `Chrome` role |
| a `stroke: f32`, `theme: &Theme`, `chrome: &Chrome` or `palette:` parameter on a view function | read from the context |
| an unlisted `const NAME: f32` | list it with a reason, or use a token |
| `#[allow(...)]` or `#[expect(...)]` on a `disallowed_*` lint inside an app | there is none; use the replacement |
| `selectable_label`, `selectable_value` | `toolkit::selectable` |

Each refusal prints the file, the line and the replacement. The example
app and the snippets in §3 to §7 are the gate's passing fixture; one
adversarial fixture exists per refusal. The gate runs with the other
repository gates and in CI.

## 13. What the app exposes on the Bus for its look

The toolkit provides these; the app lists them in `app.describe` with its
drive verbs and registers them in the verb registry:

- `<app>.look` (query; `{context?}` for apps with several contexts): the
  authority identity (binding, incarnation, revision, source digest, or
  null while settingsd is missing), the window's look `generation`, which
  source was compiled and how it was obtained, the axes with sources
  (`session`, `app`, `window`), every style token and chrome role with
  `value`, `default`, `source` (`design`, `design-default`, `legacy`,
  `session`, `app`, `preview`, `accessibility`) and `shadowed`, each role's
  owning egui slots, each colour's `checked` flag, the fonts actually drawn,
  `tune.unknown`, the preview state, and `regions`.
- `<app>.look.changed` (topic): published on every install with the
  window's context and generation. The compositor follows it for
  server-decorated title bars.
- `view.look.preview` (command, intent): params
  `{tune: {"style.field_radius": 3}, expect: {incarnation, revision, generation}}`
  overlay this window only; `{tune: {}}` clears; refused `stale_preview`
  unless all three fence values match what the window draws now; at most
  4096 bytes; cleared by every look change except the arrival of the
  window's pinned design source, which keeps the preview and re-applies it
  over the refined look. Run through `<app>.execute`, journaled like any
  command.
- `view.theme.set` (command, intent): the window's own axis choice.

To change the session for every app, a caller writes settingsd:
`settings.validate` to try, `settings.apply` with
`"tune.style.field_radius": 4` (fenced on the current revision; `null`
resets; `"tune": null` resets all), `settings.reset`, or Prefs'
`prefs.appearance.set`. Per app: `"apps.<id>.tune.<family>.<name>"`.
Terminal colours, session scope only: `"terminal.colors.ansi.1": "#ff0000"`,
`"terminal.colors.foreground"`, `.background`, `.cursor`. Style and chrome
tunes have session, app and window scope; terminal colours have session
scope. A relation between two tokens (a resize corner at least as large as
the edge) is a constraint checked on the final layered values and refused
with both sides named. Every running app follows within one summary
delivery, under any design source. Undo is the
caller's held before-values applied as an inverse fenced on the accepted
receipt's incarnation and revision; a `conflict` means someone else wrote
in between.

## 14. Snapshots and tests

- Every view has an offscreen snapshot in the app's `tests/`, rendered in at
  least Studio dark and one light scheme. Look at the image.
- Rows are found by accessible name, never by position.
- A registry test checks the verbs the app describes are the ones it
  registers, including `<app>.look` and the `<app>.look.changed` topic.
- A theme-follow test feeds a look delivery with a `tune` and asserts
  `Chrome::of(ctx)` changed; one with `ui.reduced_motion` asserts the
  animation time is zero; one with a stale preview fence asserts refusal;
  one with a pinned source digest that differs asserts the embedded design
  first and the acquired source after; the lifecycle tests the example app
  carries run against the shell.

## 15. Review checklist

- [ ] `toolkit::install` is the only look installer; no view function takes
      a stroke, theme, chrome or palette parameter.
- [ ] The shell follows the example app's lifecycle: forwarder wakes on
      every event, the follower's returned read is the one sent, a
      disconnect resets the follower and clears authority and preview, a
      fault retries once, a differing source digest is acquired.
- [ ] No raw egui widget or style setter from §12; clippy and the gate are
      green with no lint exception inside the app.
- [ ] No spacing literal; every `const` is allowlisted with a reason.
- [ ] No colour literal; coloured text goes through `toolkit::text`.
- [ ] Forms use `toolkit::form`; labels are the fields' accessible names.
- [ ] Scrolling uses `toolkit::scroll::Area` with a stable id salt.
- [ ] Icons come from `Icon`; new ones were added to the toolkit.
- [ ] Every action is a registry command; menus and the Theme menu come
      from the registry; no app theme verb.
- [ ] `<app>.look`, `<app>.look.changed`, `view.look.preview` and
      `view.theme.set` are described and registered.
- [ ] Content regions use `content::surface` and are reported under
      `regions`.
- [ ] Snapshots exist for the changed view in a dark and a light scheme, and
      were looked at.
- [ ] Nothing names a host, an operator path or a reference application.

---

---

<!-- page: https://mixos.dev/toolsd/ (source: https://mixos.dev/toolsd/README.md) -->

# Tool runs

webd's admin panel has a tools modal: look up a domain's whois record, query
DNS, trace a route, or run `shwho` (a whois and DNS summary). webd itself
cannot run programs. Its embedded Mix sandbox denies process execution
outright, so the panel only *queues* a run, and `toolsd` runs it.

## How a run flows

1. The panel posts a run. webd checks the caller's role against the tool
   registry, validates the parameters, and stores the run in its own queue
   (the `tools.` schema beside the site's CMS database).
2. webd calls the authority-free Bus verb `toolsd.wake`. It takes no
   arguments and names no tool; it only asks toolsd to go and look.
3. The wake citizen starts the drain unit, `toolsd-drain.service`.
4. The drain claims the next run from webd over HTTPS with its own secret,
   checks the role and parameters **again** against the same registry, runs
   the tool with a fixed argv, a minimal environment and a timeout, and
   streams or reports the output back.
5. The panel polls webd and shows the output as it arrives.

A timer runs the drain every five minutes as a backstop, for a wake that
arrived while a drain was finishing, or for a burst larger than one drain
takes.

## Two identities

| Unit | User | Holds | May do |
|---|---|---|---|
| `toolsd.service` | `toolsd-wake` | nothing | start `toolsd-drain.service`, through one polkit rule |
| `toolsd-drain.service` | `toolsd` | the tools claim secret | claim and report tool runs; run the registered tools |

The split exists because running a tool blocks. A 30 second whois inside
the Bus citizen would stall every other caller, so the work happens in a
separate short-lived process. The wake identity holds no credential at all,
which is what lets webd call it.

## What the drain may reach

The drain unit denies every private and management address range and
re-allows only the local resolver stub (`127.0.0.53`) and the webd it claims
from. Public addresses stay reachable, because whois talks to registry
servers directly. So code running as `toolsd` cannot probe the mesh or the
hypervisors.

## Installing

| Source | Installed as |
|---|---|
| `services/toolsd/scripts/` | `/opt/mixos/lib/toolsd/` (root-owned, not writable) |
| `services/webd/vhosts/apps/tools_registry.mix` | `/opt/mixos/lib/toolsd/lib/tools_registry.mix` |
| `services/toolsd/units/*.service`, `*.timer` | `/etc/systemd/system/` |
| `services/toolsd/units/toolsd.tmpfiles.conf` | `/etc/tmpfiles.d/toolsd.conf` |
| `services/toolsd/units/49-toolsd-wake.rules` | `/etc/polkit-1/rules.d/` |

The registry is the same file webd uses, so both ends check against one
list. `tools/shwho.mix` must be `root:root 0444` under root-owned parents:
the drain checks its owner and mode before every run.

Each host also needs:

- the system users `toolsd` and `toolsd-wake`;
- `/etc/mixos/toolsd/env` with `TOOLS_BASE_URL` (the webd vhost to claim
  from, for example `https://admin.example.com`) and `TOOLS_CA_FILE` (the
  certificate chain to verify it with);
- `/etc/mixos/toolsd/secret`, `0400 root`, matching the vhost's tools
  secret;
- a drop-in, `/etc/systemd/system/toolsd-drain.service.d/webd.conf`, with
  `IPAddressAllow=<webd address>/32`.

Then enable `toolsd.service` and `toolsd-drain.timer`.

## Adding a tool

A tool needs an entry in `tools_registry.mix` (its label, minimum role,
timeout, output cap and parameter types) and an argv template in
`scripts/lib/tools_exec.mix`. The argv template exists only on the toolsd
side; webd knows tool names and parameters, never command lines.

---

<!-- page: https://mixos.dev/webd/ (source: https://mixos.dev/webd/README.md) -->

# webd

The MixOS web service serves per-host static files, CMS SQLite APIs,
embedded trusted Mix HTTP handlers, mail proxy routes and file shares.
It registers as `webd` on the native Bus. The server profile uses
`/opt/mixos/bin/webd serve --db-path /var/lib/mixos/webd/web.db`.

Node configuration is read through config's native directory rules.
`webd.vhost` supplies hostnames, document roots, optional CMS databases,
manual TLS identities or Let's Encrypt HTTP-01 ACME settings. Explicit
listeners assign hosts to interfaces; the legacy default uses the node IP.
Production issuance requires the accepted Subscriber Agreement URL.

The shipped `vhosts/` Mix handlers and `examples/mix-cms/` remain alongside
the service. Configure document roots and credentials explicitly; example
values are documentation, not deployment configuration. Session cookies,
environment variables and data paths use MixOS names.

Build and test with `cargo test --locked -p webd`. `webd --version` emits
MixOS build provenance. Units, sysusers and tmpfiles fragments are in
`services/webd/units/`; they are not installed by building the service.
The deployment identity is user `webd`, UID 502, unit `webd.service`.

State includes CMS and props SQLite/WAL data, session revocations and
sealing keys, ACME accounts/certificates, and uploads. A deployment needs
a single writer, counts/hashes and native HTTP/TLS/CMS acceptance checks,
plus a rehearsed rollback preserving writes. This source transplant
performs no deployment or data migration.

Source: [services/webd](https://github.com/markc/mixos/tree/main/services/webd).

## Source gate limitation

The Rust suite passes, including the service's registry comparison. The
repository-wide verb source gate currently treats embedded HTTP template
fragments as standalone programs. It reports undefined prelude functions
and request globals. With those symbols declared to the native linter,
`vhosts/apps/sw.mix:182,193,220,294` and
`vhosts/widgets/treeview.mix:200` still report arity errors: these templates
intentionally rely on nil-padded optional trailing arguments. The source
comments document that contract. The templates and gate are retained;
the source entry gate has not passed. A context-aware lint integration is
required before declaring the complete transplant entry bar satisfied.

No deployment, live ACME issuance or production-data rollback rehearsal
has been performed by this source port.

---

<!-- page: https://mixos.dev/bridged/changelog/ (source: https://mixos.dev/bridged/changelog.md) -->

# bridged Bus contract

> Mirrored from [`services/bridged/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/bridged/CHANGELOG.md), where releases update it. The component's page is [bridged](README.md). This page describes the current `main` branch of MixOS.

## 0.2.0

- Additive: `auth: "key"` (instance config 0.2.0). The first line is
  `params.key`, the secret is the 64-hex content of `token_file`, read on every
  connect before any bytes are sent. A missing, unreadable or unusable key is
  rc 11 with no connection; the retry after `backoff_s` reads it again.
  `status` works before the key exists and never shows it. Token and none
  modes are unchanged. Bus verbs and registry classes are unchanged.

## 0.1.0

First version. A Bus bridge to an external application's line-delimited JSON
control channel, one instance per application (`bridged@<app>`), answering
`<app>.call`, `.commands`, `.execute`, `.inspect`, `.screenshot` and
`.status` with rc 0 (the app's result), 10 (the app's error), 11 (connect,
auth, transport or timeout) or 12 (a bad request).

- Instance config 0.1.0 (`docs/spec/bridge/`): `<etc>/bridge/<app>.conf.mix`,
  `<etc>` = `$MIXOS_ETC` or `/etc/mixos`, or `$BRIDGED_CONFIG`; keys `host`
  (loopback only), `port`, `auth` (`token` or `none`), `token_file`,
  `timeout_s`, `connect_timeout_s`, `backoff_s`, `max_line`, `instance`.
- Start checks, also as `mix bridged.mix --check <app>`: the Bus service-name
  rule, and no name that a registered verb already starts with (read from the
  installed verb registry, failing closed). A refusal exits 2 with
  `RUNTIME`, `NAME_INVALID`, `NAME_RESERVED`, `REGISTRY`, `CONFIG` or
  `TOKEN`.
- The name may not start with `mixos-` (mix --serve strips it) or be one of
  the broker's (`noded`, `noded-*`, the session-name shape).
- The token is redacted from every error, result and `last_error`; the token
  file must be `0600`. `localhost` connects as `127.0.0.1`.
- A reply without a boolean `ok` drops the connection (rc 11, then backoff).
- The unit runs `bridged.mix --start <app>`: the start checks in process,
  then `mix --serve` as a child (Mix has no exec), exiting with the child's
  code. A documented refusal exits 2 and is never restarted
  (`RestartPreventExitStatus=2`); an unexpected start error exits 3, and it,
  a crash or a broken install is a rate-limited failure. A clean stop exits
  143 (`SuccessExitStatus=143`). Run `--start` under the unit: outside
  systemd it has no parent-death protection. `BRIDGED_MIX` and the `.env`
  file must be administrator-controlled.
- Writes draw on the same transport budget as connect and reads
  (`timeout_s`): every `tcp_send` gets the time left as `{timeout}`, and a
  send that runs out is rc 11 with the connection dropped. Local encoding
  and scheduling cannot be interrupted and can run past it. Requires Mix >=
  0.112.1; an older Mix is refused at start
  (`RUNTIME`).
- `max_line` bounds both directions exactly: an encoded request over it is
  refused with rc 12 before the connection is touched; a reply line over it
  is rc 11 with the connection dropped, even when it arrives whole in one
  read.
- The unit is sandboxed (no capabilities or new privileges, read-only file
  system with private `/tmp`, loopback-only IP by `IPAddressAllow=localhost`
  and `IPAddressDeny=any`; a non-loopback Bus needs a drop-in).
  `systemd-analyze security` exposure 4.0 (OK).
- Documented residuals: loopback port squatting after the app dies (a
  unix-socket channel would close it), a direct `mix --serve` briefly holding
  a refused name, and the reverse name collision being the verb-registry
  gate's to refuse.
- The six verbs are declared in `docs/spec/bus/verbs.conf.mix` as the
  `bridged` instance family (`<app>.<verb>`, `members: "instances"`), in the
  registry's schema 3. Installing the registry is a separate deployed
  prerequisite, and this entry does not claim a live installation.
- The bridge tests run in `tools/mix_tests.mix`. Their mix binary is
  `BRIDGED_MIX`, else `MIXOS_TEST_MIX`, else `/opt/mixos/bin/mix`; the Bus
  test's noded is `--noded`, else `MIXOS_TEST_NODED`, else the installed one.
- The over-`max_line` reply test asserts rc 11 and the `transport:` prefix,
  not the wording of Mix's line-limit error, which the current Mix changed.

Ported from a private prototype (a serve citizen and its core, version
0.3.0), with the instance-config path rule, the serve-name guard and the
`--check` mode added, and its tests moved from a socat stand-in to one
written in Mix on `tcp_listen`.

---

<!-- page: https://mixos.dev/command/changelog/ (source: https://mixos.dev/command/changelog.md) -->

> Mirrored from [`libs/command/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/libs/command/CHANGELOG.md), where releases update it. The component's page is [command](README.md). This page describes the current `main` branch of MixOS.

<!-- SPDX-License-Identifier: MIT OR Apache-2.0 -->
# Changelog

## 0.3.0 — 2026-10-21

- Add bounded transactional `History<D>` snapshots, explicit coalescing,
  undo/redo labels and saved checkpoints for application engines.
- Count retained redo snapshots as well as undo in the history byte budget.
- Route Screenshot document edits through parameterised commands. The
  `screenshot.execute` body rejects unknown fields (`deny_unknown_fields`).
- Rename Screenshot's nullary Delete selection command from `edit.delete`
  to `edit.delete_selected`; keymap overrides naming the old command must
  move to `edit.delete_selected`. `edit.delete {id}` now deletes one object.

## 0.2.0 — 2026-10-21

- Emit only v2 executed bodies, with accepted params and returned result;
  independently replace compact values above 4096 bytes with bytes and SHA-256.
- Add the strict, schema-bearing `ExecuteRequest` body for `<app>.execute`.
- Return `Denied` on authorisation refusal before checking enablement.
- Canonicalise modifiers as Ctrl, Alt, Shift and report stored chord spelling
  through toolkit's `<app>.commands` adapter.

## 0.1.0 — 2026-10-20

- Extract the registry, Fluent strings and v1 executed journal from toolkit.
- Add parameter schemas, results, typed refusals, authorisation and classes.
- Preserve toolkit's nullary tables through its egui adapter.

---

<!-- page: https://mixos.dev/compd/changelog/ (source: https://mixos.dev/compd/changelog.md) -->

# Changelog

> Mirrored from [`services/compd/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/compd/CHANGELOG.md), where releases update it. The component's page is [compd](README.md). This page describes the current `main` branch of MixOS.

## 0.2.0

- The user keys belong to the user. compd enforces the rule itself, ahead
  of its own bindings, because on a MixOS VT it reads the keyboard itself.
  The user keys are bare F1–F12 and Right Ctrl, Right Alt or Right Shift with
  an arrow, matched side-exact with inputd's classifier and press-latched
  disposition. A user key fires the session user's binding, or goes to the
  focused client when the user bound it `passthrough`; otherwise it is
  swallowed, and no client sees its press, repeat or release. Under a
  session lock every user key is swallowed and nothing fires.
  - The bindings are read from keymap.v1 (`inputd/keymap.json` in the
    user's MixOS config dir, or `$MIXOS_USER_KEYMAP`) and reloaded when the
    file changes. A bad file keeps the last good keymap, and a missing one
    binds nothing.
  - A `comp.*` verb runs as its Bus request does. Any other verb is sent to
    its service fire-and-forget, with the row's args as the body.
    `repeat: allow` rows repeat at the seat's rate while held.
  - `bindings.user` lists the rows.
  - compd ships no user-key binding. The opt-in bare-F9 Bus key can no
    longer fire.
- `comp.region.select` 0.2.0: a click (under 4 logical px of travel, with
  no drag on the way) and Enter or keypad Enter now select the whole output
  under the pointer, answering exactly as a drag from corner to corner does;
  a click used to re-arm the selection. A drag stays a drag even if it
  returns to its start. The overlay dims the output (clear inside a drag),
  outlines the selection in the theme's focus-ring colour and shows a hint
  ("Drag to select an area · Click or Enter for the whole screen · Esc to
  cancel"), only on the selected output, in the session look (followed on
  every change); a selected reply waits for a frame of that output without
  the overlay.
- While a `comp.region.select` run holds the seat the cursor is a
  crosshair (the theme's `crosshair`, else `cross` or `tcross`, else the
  arrow); the normal cursor is back on the frame that ends the run, however
  it ends, so the clean frame never shows the crosshair. A cursor's hotspot
  is now read after its shape is chosen, so a change of shape lands in place
  on its first frame.
- The capture panels (the setup chooser, region border and dim, Stop
  buttons and the Continue, Save, Encoding and error dialogs) draw in the
  session theme, followed on every change like the region overlay, with
  the embedded theme until the shell delivers one. Open panels repaint at
  once.
- Workspaces: `comp.workspaces.list`, `comp.workspaces.set_count {count,
  persist}` and `comp.workspace.rename {index, name, persist}`, and the
  `comp.workspace.changed` topic. The count and names persist in
  `preferences.json` (`workspaces_count`, `workspace_names`) and compd
  starts with them. `workspaces.list` rows carry `name`.
- The pointer moves at the same logical speed at every output scale: a
  relative delta is multiplied by the output scale as well as
  `cursor_sensitivity`, so a scale-2.5 output no longer needs a sensitivity
  of 2.5.

- compd's own UI is egui: capture overlays and dialogs, the frame-rate
  overlay, notifications and the Mix Scenes shell are egui programs painted
  with egui-wgpu into textures on compd's own EGL context, on the same MixOS
  look the apps draw with (`toolkit`).
- Mix Scenes are laid out as flexbox with taffy, as Quoin lays them out;
  `shell.scene.layout` reports the rectangles each node was drawn and
  hit-tested at.
- The session look follows settingsd through the shared consumer on the scene
  host's own connection (compact schema-2 deliveries, offline cache), and
  window decorations take their themes from the same look.
- A UI surface off screen is suspended: its animations stop waking the
  compositor until it is shown again.
- The whole `comp.*` verb catalogue is registered, and a registry test keeps
  it exact.
- Window titles are shaped with cosmic-text over the apps' embedded faces, so
  they match the apps' type and need no fonts installed.

---

<!-- page: https://mixos.dev/editd/changelog/ (source: https://mixos.dev/editd/changelog.md) -->

# editd Bus contract

> Mirrored from [`services/editd/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/editd/CHANGELOG.md), where releases update it. The component's page is [editd](README.md). This page describes the current `main` branch of MixOS.

## 0.2.0

Transplant the `edit.*` buffer contract and retained golden fixtures from
the predecessor repository at revision
`e0297242305f3a3c3de09f1ca01e8faa771768da`. Resolve broker discovery and recovery directories through the isolated MixOS environment.

---

<!-- page: https://mixos.dev/hostd/changelog/ (source: https://mixos.dev/hostd/changelog.md) -->

# hostd contract changes

> Mirrored from [`services/hostd/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/hostd/CHANGELOG.md), where releases update it. The component's page is [hostd](README.md). This page describes the current `main` branch of MixOS.

## 0.1.0 (draft)

- Read verbs `host.info`, `net.state`, `hostd.status`, `hostd.receipt` on the
  local socket and the Bus; retained `hostd.info` topic.
- Control verbs `hostd.freeze` (root on the host, or a grant) and
  `hostd.thaw` (root on the host only; also lifts grant suspensions), local
  only.
- Write verbs `net.link.apply` and `hostd.undo`, local only, behind standing
  grants in `/etc/hostd/policy.mx` (schema 1): caller by uid and verified
  cgroup, verb families, argument allow-lists, expiry, per-caller rate with a
  grant-wide cap. Receipts, health-checked rollback, and a circuit breaker
  that suspends a grant after two rollbacks in a row.
- Local socket: NUL-framed JSON, kernel caller identity read per request,
  per-uid connection cap, connection lifetime, read and write deadlines.
- `hostd.status` adds `held_grants`: each grant the caller holds, in full.
- Write verb `net.wg.apply`: networkd-native WireGuard, key made and kept by
  hostd (0640 root:systemd-network, never returned), the handshake dead-man
  check. The unit gains `CAP_CHOWN` and `CAP_NET_ADMIN` for it.
- Write verbs `net.wifi.scan` and `net.wifi.connect` through iwd: no files,
  the passphrase only through a one-connect agent, put back by forgetting
  and reconnecting.

---

<!-- page: https://mixos.dev/inputd/changelog/ (source: https://mixos.dev/inputd/changelog.md) -->

# inputd contract changes

> Mirrored from [`services/inputd/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/inputd/CHANGELOG.md), where releases update it. The component's page is [inputd](README.md). This page describes the current `main` branch of MixOS.

## 0.5.0 (draft)

The broker enters MixOS. The wire is unchanged: Bus service `inputd`, the
`input.*` verbs and their bodies, and the keymap.v1 file
(`{"version":1,"physical":[...]}`); a keymap written by the earlier broker
loads unchanged.

- **The user keys are the user's.** Bare F1–F12, and Right Ctrl, Right Alt
  or Right Shift (any of them, nothing else) with an arrow, are swallowed
  on press, repeat and release unless the person binds them or marks them
  passthrough. The shipped keymap binds none of them: its only rows are the
  system-reserved `Ctrl+Alt+P` scene-editor chord. The earlier shipped
  F-key, Right Ctrl arrow and Right Shift passthrough rows are gone; a
  person who wants them binds them.
- **Press-latched disposition.** Each key is decided once, at its press,
  and holds that decision to its release, whatever the modifiers or the
  keymap do meanwhile. A repeat or release whose press was not seen under
  the current grab is dropped.
- **`--vt N[,M...]`.** The grab is held only while one of those VTs is
  active, followed by `poll(2)` on `/sys/class/tty/tty0/active`. On
  switch-away every key held on the re-emitter is released there, then the
  grab is dropped; on switch-to the grab is retaken, with bounded backoff
  while another holder has it. Without `--vt` the grab is held always.
- **The grab is taken only with no key down,** so no key is left held in
  the compositor; inputd waits ungrabbed until the keyboard is quiet.
- **Dropped events (`SYN_DROPPED`) are recovered:** the key state is
  re-read, every key passed on is released, and keys still held are
  swallowed until their release. While a modifier is held that way, keys
  that would go to the apps are held back too, so none goes out without
  its modifier.
- A frame written to the re-emitter is always ended with a report, on
  recovery and on switch-away, so no release is left buffered.
- While waiting for a quiet keyboard, inputd retries on the grab backoff
  schedule (to 2 s) as well as at each report.
- `input.mode` refuses a malformed body; only an empty body or `{}`
  toggles.
- The re-emitter is `inputd virtual keyboard`, created once at start; the
  injector is `inputd virtual pointer`.
- The keymap is `keymap.json` in the state directory
  (`/var/lib/mixos/inputd/`), or `--keymap PATH`.
- The mesh lock is `MIXOS_MESH_OPEN=0`.

---

<!-- page: https://mixos.dev/maild/changelog/ (source: https://mixos.dev/maild/changelog.md) -->

# Changelog

> Mirrored from [`services/maild/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/maild/CHANGELOG.md), where releases update it. The component's page is [maild](README.md). This page describes the current `main` branch of MixOS.

## 0.1.1 — 2026-10-18

- Port the JMAP, SMTP, IMAP, CalDAV and CardDAV daemon and its authentication,
  rules and Bayesian crates onto the shared MixOS libraries and private mds.
- Register 43 maild Bus verbs and preserve property-store and storage contracts.
- Retain mail-parser 0.11.5's 64-level nesting safeguard and its direct tests.
- Use MixOS config paths, build and fixture variables, delegation envelopes,
  blob headers, protocol banners and DAV sync-token namespace.
- Add the system-binary personality, server packaging, maild@.service and the
  maild sysusers declaration. No separate metadata-store operator CLI is shipped.
- Preserve all source tests and document the six inherited ignores; add two
  repository registry consistency checks.

---

<!-- page: https://mixos.dev/mesh-sign/changelog/ (source: https://mixos.dev/mesh-sign/changelog.md) -->

# Changelog

> Mirrored from [`cli/mesh-sign/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/cli/mesh-sign/CHANGELOG.md), where releases update it. The component's page is [mesh-sign](README.md). This page describes the current `main` branch of MixOS.

## Unreleased — ported into MixOS

- Moved from the predecessor repository into MixOS as `cli/mesh-sign`
  (package and binary `mesh-sign`). Behaviour is unchanged.
- The verify report keeps its `cosmix-mesh-sign.verify.v1` format string: it
  is a frozen wire constant.
- Reads the authored inventory with `mix::parse_data_file` (the MixOS
  equivalent of the predecessor's `load_mix_data`).
- The shared canonicaliser and verifier come from `services/noded/crates/mesh-trust`.
- `wg-gen` and `wg-pubkey` use only the key part of the WireGuard code
  (X25519, standard base64, clamping), on `curve25519-dalek`. The rest of
  the predecessor's WireGuard library is not ported.

## 0.7.3 — 2026-08-16

- Refuse signing when an active Bus member carries a `noded_port` outside the
  shared strict JSON-integer `1..=65535` contract.
- Include each resolved ActiveBus `noded_port` in `verify --json` routing-view
  output, including the default 4200 for inventories that omit it.

## 0.7.2 — 2026-08-16

- Refuse inventories whose member names are not valid SPEC 01 §4.1 Bus labels
  before signing, using the shared fleet-wide label grammar.

## 0.7.1 — 2026-08-15

- Add `sign --recovery-generation <N>` to stamp the current recovery floor on
  a normal payload without setting `recovery:true`.
- Refuse recovery-generation values beyond Mix's exact-integer range and make
  `--recovery-generation` mutually exclusive with `--recovery`.
- Report both effective and payload-carried recovery generations in JSON and
  human output, and warn that `--recovery` cannot check fleet epoch history.
- Warn when normal signing emits a legacy generation-silent payload, and note
  on human verification that such a payload was checked only against the
  command's synthetic generation-zero state.

---

<!-- page: https://mixos.dev/mix/changelog/ (source: https://mixos.dev/mix/changelog.md) -->

# Changelog

> Mirrored from [`libs/mix/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/libs/mix/CHANGELOG.md), where releases update it. The component's page is [mix](README.md). This page describes the current `main` branch of MixOS.

## Unreleased

### Changed

- A `fn` or `function` named after a builtin is refused at its definition
  with `FN_SHADOWS_BUILTIN`. A top-level definition (in a script or a
  `require`d module) is refused before the first statement runs; a nested
  one when control reaches it. The builtin always won at the call site, so
  the function could never be called by name, and `mix --check` does not run
  lint: a script defining `fn run($argv)` ran on and failed with
  `run(): argument 1 (cmd) must be string`. `--serve` extension names such
  as `context` are not refused (lint still warns, MIX-W2313). A sweep of
  about 24,000 definitions across the hub, the MixOS tree and the installed
  scenes found no live script affected.

### Fixed

- MIX-E1303 now covers the higher-order builtins (`count`, `map`, `filter`,
  `sort_by`, …). `fn count($x)` linted clean and was silently dead. Lint and
  runtime share one name set, `builtins::is_reserved_callable`.

## 0.117.0 — 2026-10-21

### Added

- `analyzer::Analysis.functions` reports named function declarations with
  `name`, `file` and `line`, including nested and duplicate definitions but
  excluding quoted and remote source. `mix lint --json` and `--data` expose
  this list in schema 3; every existing key and diagnostic retains its meaning.
- `mix lint` reads in-file pragmas: `-- lint: globals a, b` declares
  injected names, `-- lint: ignore CODE` suppresses CODE on the next line
  holding code (or on its own line when written after code) and
  `-- lint: ignore-file CODE` suppresses it file-wide. A bare or unknown
  pragma is MIX-E1601; a suppression that matches nothing is the note
  MIX-D3019. An `ssh_mix` body reads its own pragmas.
- MIX-W2312: a bareword `null`, `None`, `undefined`, `NULL` or `nullptr`
  used as a value is the string "null"; the warning carries a quick fix to
  `nil` where the word is surely a value. `mix lint --fix` applies quick
  fixes; `--json` reports each as `fix`. `Diagnostic` gains a `fix` field.
- MIX-W2313: a function named after one of the `mix` binary's shell
  extensions (`ai`, `ai_diagnose`, `context`). Lint now knows those
  extensions (`MIX_SHELL_EXTENSIONS`, `AnalyzerConfig::extensions`), so
  calling one is no longer MIX-E1102.
- MIX-W2314 / MIX-W2315: member calls into a module bound once to a literal
  `require()` path are checked against its exports, for arity and for a
  missing name. Warnings in this release, while the check is new.
- The parser names the fix for `let i = 0`, `var`/`const`, and a bareword
  `i = …` ("Mix has no `let`: write `$i = …`").
- Add the `archive` feature with the `tar_list`, `tar_unpack` and `tar_pack`
  builtins. Archives use zstd (default), gzip or no codec. `tar_unpack`
  validates every member, extracts into a staging directory and renames it
  into place only after the stream verifies. See `mix man tar`.
- Harden archive builtins: count trailing padding against the shared decoded
  stream budget, reject oversized declared files before creation and bound
  copying, cap GNU/PAX metadata payloads before buffering, and refuse unread
  gzip input or additional members. Packing captures capabilities only with
  `keep_special_bits:true` and walks pinned directory/file descriptors without
  following replacement symlinks. Rollback restores directory access and
  reports cleanup failures. Empty/truncated zstd headers now raise
  `ARCHIVE_STREAM_CORRUPT`. GNU sparse entries are refused; `tar_list` also
  accepts `max_entries`. Each fix has targeted archive regression coverage.
- Archive review fixes. `tar_unpack` restores only `user.*` xattrs by
  default: `security.capability` needs `keep_special_bits:true`, and
  `trusted.*`, POSIX ACLs (`system.*`) and the rest of `security.*` need the
  new `privileged_xattrs:true`. Retained xattr bytes are bounded across the
  archive by the new `max_xattr_bytes` (16 MiB). Staging has an unpredictable
  name and is held by descriptor; members are created one O_NOFOLLOW
  component at a time relative to it, and the commit refuses to replace
  anything that appeared at `dest` (RENAME_NOREPLACE). Owner, mode and mtime
  failures are no longer discarded: an owner that cannot be applied is listed
  in the receipt's new `warnings`, and then its setuid/setgid bits and
  capability are dropped; mode and mtime failures raise. PAX global headers
  (`git archive`) are accepted as metadata (receipt `metadata`, list kind
  `"metadata"`). A bare relative dest or output name means the current
  directory. `tar_pack` refuses an output inside its source and raises when
  a file changes size while it is packed.
- Archive review, round 2. `tar_unpack` refuses a dest parent that another
  user could write (group/other-writable without the sticky bit, or owned by
  neither the caller nor root) before creating anything, and checks the new
  staging directory is the caller's, `0700` and empty. Without
  `RENAME_NOREPLACE` the commit now fails closed and rolls back. Implicitly
  created parent directories count against `max_entries` (receipt
  `implicit_dirs`). zstd content checksums are verified on unpack and list,
  and `tar_pack` now writes one.
- `analyzer::Analysis` carries `handlers`: one `HandlerDeclaration` (`command`,
  `file`, `line`) per `on <command>` statement in the parsed AST, in source
  order, with duplicates kept. `analyze()` collects them with the existing
  statement walker. Remote `ssh_mix` bodies are not included. `mix lint --json`
  and `--data` report the same list as an additive `handlers` field. The data
  is structural: it does not prove that a handler runs or is reachable.
- `mix_tokens(source[, {comments: true}])` returns the real lexer's token
  stream as `[{kind, text, line, col}]`, with the exact source text of each
  token and, on request, the `#` and `--` comments. A tool that reads Mix
  source no longer re-derives the grammar. Source that does not lex raises
  `MIX_SOURCE_LEX` with `details {line, col}`. Backed by the new
  `Lexer::source_tokens`. See `mix man syntax`.
- `fsync(path[, {recursive}])` makes a file, a directory (its entries, after a
  `rename` or `remove`) or a whole tree durable, without `sync -f`'s flush of
  the whole filesystem. It returns the number of inodes synced; a failure
  raises `FSYNC_FAILED` naming the path.
- `dns_query(name, type[, {server, port, timeout, tcp, recurse}])` asks one
  DNS server one question and returns the rcode, the `aa`/`ra`/`tc` flags and
  every section with TTLs. Timeouts and unreachable servers come back as
  `{ok: false, error_code}`. It is the new `dns` feature (hickory-proto, the
  version mail-auth already uses); the `mix` binary turns it on.
- `walk(dir, {strict: true})` raises `WALK_UNREADABLE`, naming the first
  directory it cannot read or entry it cannot stat, instead of skipping it.
- `chown(path, uid, gid, {follow_symlinks: false})` changes a symlink itself
  (`lchown`).
- `flock` and `fcntl_lock` take `create: false`, which refuses a missing lock
  file with `LOCK_FILE_MISSING` and creates nothing.
- `tar_unpack` and `tar_list` accept GNU tar's `./` member prefix (`tar -C
  dir .`); a `./` directory entry's metadata is applied to `dest`. Relative
  symlinks may climb with leading `..` while they stay inside `dest`, judged
  from the link's own directory (`demo/lib/alias -> ../bin/demo`). Gzip input
  may have several members, as `pigz` and `cat a.gz b.gz` write.
- `mix man sqlopen` documents the SQLite builtins and their modes.

### Changed

- `tar_unpack`'s `numeric_owner` now defaults to `true` only for root, as GNU
  tar does. An ordinary user's unpacked files keep their own uid and gid; a
  non-root chown could still give a file any of the caller's groups. Pass
  `numeric_owner: true` for the old behaviour. A setuid/setgid bit or
  capability is now kept only where the file ends up with the owner the
  archive named, also when owners are not restored.
- A symlink target may no longer pass through another symlink the archive
  creates, in either order, and `..` may only lead a target: `a/../b` is
  refused.
- A shared `flock` or `fcntl_lock` opens an existing file read-only, so it no
  longer needs write access to the lock file.
- `sqlopen` raises `OPTION_INVALID` for a mode other than `"ro"`, `"rw"` or
  `"rwc"` (`"rwc"` is new: read-write, creating the file, the same as `"rw"`).
  An unknown mode used to open read-only, so `"rwc"` could not create a
  database. A read-only open of a missing file raises `SQL_NO_DATABASE`
  naming `"rwc"`.
- A member call `$m.name(...)` on a map holding a function member calls
  that member in every mode, `--serve` included; an extension (the shell's
  `context()`) no longer wins there.
- MIX-W2304 names the result shape and suggests the field a bash, Python or
  Node spelling means (`code`, `rc`, `status` → `exit_code`).
- The default remote mix binary is now `/opt/mixos/bin/mix` (was the legacy
  install path's mix). It applies to `ssh_mix`, `ssh_mix_many`, `ssh_exec`,
  `ssh_run`'s `env_transport: "mix"` and `send_mail`'s `host` hop whenever
  neither `mix_bin` nor `MIX_REMOTE_BIN` is set. For a host still on
  the old install path, pass `mix_bin` or set `MIX_REMOTE_BIN` to its mix.

### Fixed

- A `send` after a failed Bus connection retries within its timeout,
  re-reading `MIXOS_NODED_URL` and node configuration. Without `timeout=`,
  each lane's connect is bounded by 5 seconds (up to 10 seconds if both the
  verified Unix and anonymous TCP lanes stall). A stale probe cannot
  replace a newer connection, and reconnecting does not hold the state lock.
- SIGINT still ends a non-interactive evaluation when a `catch` keeps
  computing: after a cleanup grace the interrupt becomes standing. Nested
  catches and `finally` control flow cannot swallow it. A served citizen
  keeps its graceful deregistration and exit status 0.
- `read_file`, `write_file` and `append_file` yield while waiting on a FIFO,
  so served citizens still answer other verbs and `QUIT`. Reads honour the
  string limit, and the FIFO path keeps the normal builtin arity rules.
- `fs_watch` recovery (after a lost or overflowed event stream) re-arms each
  directory watch in place instead of unwatching and watching it again, so a
  change that lands during the repair (the close-write of a save racing the
  overflow) is still reported.
- `mix lint` no longer reports MIX-E1101 for a variable assigned in a piped
  statement (`$v = 1 | cat`).
- `mix lint` MIX-W2307 (send result never checked) now counts a status read
  inside an `if` condition, a map value, a nested call argument or a string
  interpolation. A correctly checked send no longer warns.
- MIX-W2307 treats every writer of `$rc`, `$result` and `$reply` as an
  overwrite: `publish()`, `sh`, `$(...)`, pipes to external commands, user
  assignments, address-block calls and calls to functions that send. A send
  followed by one of these, and no read before it, now warns.
- MIX-W2307 is conservative by construction: a construct whose effect on the
  status the analyser cannot prove absent counts as an overwrite. A call is
  proven non-writing only for a function defined in the file whose body and
  parameter defaults do not write, or for one of the pure builtins (no I/O,
  process, bus, network, clock or function-valued argument). Any other builtin,
  value call (`$f()`), method call, `include` or `source`, and any name
  defined nowhere in the file, now overwrites. A name that is also bound as a
  variable or parameter is a barrier, because a callable binding runs before a
  named function. A bare word that names a function is a call. A function that
  can `exit`, `panic`, `die` or fail uncaught ends its caller's path, so a read
  after that call does not discharge a send. String and heredoc `${...}`
  fallbacks (`${x ?? sh "..."}`) are analysed as the program they are, and an
  index is evaluated before its object. This can add warnings for code that is
  correct but calls a non-pure builtin between a send and its check.

## 0.116.0

### Added

- The remote mix binary is configurable. Every builtin that drives a
  remote mix (`ssh_mix`, `ssh_mix_many`, `ssh_exec`, `ssh_run`'s
  `env_transport: "mix"`, `send_mail`'s `host` hop) resolves it in one
  place: the `mix_bin` option, else the local env var `MIX_REMOTE_BIN`
  (empty counts as unset), else the old install path's mix, the unchanged
  default. The value is interpolated into the remote command string, so
  it must be an absolute path or a bare name using only `[A-Za-z0-9_./+-]`;
  anything else raises `OPTION_INVALID` locally before ssh runs. A host with
  mix only at `/opt/mixos/bin/mix` used to fail with exit 127.

### Changed

- `ssh_exec`'s `remote_mix` option is now validated the same way (it was
  interpolated unchecked) and is an alias of `mix_bin`; passing both
  raises.

## 0.115.0

### Added

- `unix_connect(path[, {timeout, frame}])`: a client for a local
  unix-domain stream socket, in `tcp_connect`'s handle space, so
  `tcp_send`, `tcp_recv`, `tcp_recv_line`, `tcp_on` and `tcp_close` take it.
  The connect is bounded by `timeout` and fails at once on a full backlog
  (`UNIX_CONNECT_BUSY`). `frame: "nul"` makes a line a NUL-terminated
  frame, the framing of systemd's Varlink services and of hostd, for
  `tcp_recv_line` and `tcp_on {frame: "line"}` alike. Refusals carry
  `UNIX_CONNECT_*` codes. `mix man system` documents it.

### Changed

- One frame splitter serves `tcp_recv_line` (blocking and Class C) and
  `tcp_on` line mode, keyed to the connection's delimiter. One trailing CR
  is still stripped from an LF line.

### Fixed

- `max` now caps a complete line too. A line longer than `max` whose
  terminator arrived in the same read used to be delivered, so whether it
  was refused depended on packet timing. All three paths (`tcp_recv_line`
  blocking and Class C, `tcp_on` line mode) now refuse it the same way.

## 0.114.0

### Changed

- Released with mix-shell 0.114.0, whose usage-statistics store is now an
  append-only JSONL store (`mix man stats`). The language and its builtins
  are unchanged.

## 0.113.1

### Fixed

- An `on` header reads a hyphenated name whole, like a `send` target:
  `on dopus-test.command.executed` handles that topic. Before, the header
  stopped at the hyphen, so the handler registered as `dopus` with
  `-test.command.executed` as its body: it parsed, linted clean and never
  fired. Leading-zero segments (`on svc-01.ping`) lex as part of the name,
  as they do after `send`.

## 0.113.0

### Added

- `mime_type(path[, {content}])`: a file's type from the freedesktop
  shared-mime-info database, decided by GLib's rules, so it agrees with
  `gio info` and the file manager (checked against GIO on 5,047 files).
  Returns `{mime, by, uncertain, exists, parents}`. Behind the new `mime`
  feature, through the new `mimedb` crate. `mix man io` documents it.

## 0.112.1

### Added

- `tcp_send(handle, payload[, {timeout}])`: one deadline bounds the whole
  send, however many partial writes a slow reader forces (seconds, 0 = wait
  forever). On expiry it raises `TCP_SEND_TIMEOUT` with
  `details: {written, total}` and retires the handle; bytes already written
  stay written. The wait honours SIGTERM and Ctrl-C. On a `tcp_on` handle
  the timeout is the receipt deadline. Without the option `tcp_send` is
  unchanged.

### Fixed

- SIGTERM now ends a blocking `tcp_accept`, `tcp_recv`, `tcp_recv_line` or
  `ws_recv` at once, as it ends `sleep()`. On unix these numeric waits now
  wait on the async runtime instead of blocking the evaluator's thread, so
  the shell's SIGTERM and Ctrl-C handling can cancel them. Before, a script
  looping on `tcp_accept($l, {timeout: 0.05})` ignored SIGTERM until the
  15 s backstop forced it out. Options, results and error messages are
  unchanged.
- A receive returns data already buffered before it judges the deadline, so
  a very short timeout no longer returns nil while a line sits in the buffer.
  Traffic that delivers nothing (a WebSocket Pong flood, a line trickled with
  no newline) now counts against the deadline and the interrupt flag, so a
  finite timeout ends on time and SIGTERM still ends an untimed wait.
- A very large receive timeout in a Class C `tcp_recv`/`ws_recv` waits
  forever instead of overflowing the deadline.

## 0.112.0

### Added

- Server-side TCP. `tcp_listen(host, port[, {backlog}])` binds and listens
  and returns a listener handle; `host` is required (`"127.0.0.1"` is the
  normal choice) and port 0 takes an ephemeral port. `tcp_local_addr(handle)`
  returns `{host, port}` for a listener or connection.
  `tcp_accept(listener[, {timeout}])` returns an ordinary connected handle,
  or nil on timeout; in a Class C body it waits on native readiness.
  `tcp_on` on a listener delivers one `accepted: {handle, peer}` event per
  connection, and `tcp_accept(source)` reads that source outside serve mode.
  `tcp_close` closes a listener. Listeners and the connections they accept
  belong to the evaluator generation and close when it retires. Errors
  carry stable codes (`TCP_LISTEN_ADDR_IN_USE`, `TCP_LISTEN_PERMISSION`,
  `TCP_LISTEN_ADDR_UNAVAILABLE`, `TCP_LISTEN_ADDRESS`, `TCP_LISTEN_ARGUMENT`,
  `TCP_ACCEPT_HANDLE`, `TCP_HANDLE_LIMIT`, `TCP_LISTENER`).
- The handle limit is server-side: at most 1024 listeners and accepted
  connections are live at once, each holding a slot until it closes, and
  `tcp_listen` and `tcp_accept` refuse with `TCP_HANDLE_LIMIT` past it.
  `tcp_connect` is not limited and behaves as before.
- A blocking `tcp_accept` wakes promptly on Ctrl-C through a SIGINT wake
  socket that `interrupt::init` installs, and rechecks the interrupt flag at
  least every 250 ms, so no waiter misses it.
- `on @.verb` registers a handler under the serve name: the unquoted `@` is
  replaced by the `--serve` name (the value `serve_name()` returns) when the
  handler registers, so one generic script run as `--name photo` answers
  `photo.verb` and a second instance as `--name other` answers `other.verb`.
  Dispatch, HELP and handler listings show the resolved name; the AST keeps
  `@.verb`. Outside `mix --serve` the statement raises
  `SERVE_PREFIX_OUTSIDE_SERVE`. Each segment after `@.` must be a bare name,
  quoted or not. `on a.@.b`, `on @`, `on @x.y`, a quoted `on "@.x"`, a quoted
  segment that isn't a bare name (`on @."a.b"`) and `@` in an expression are
  parse errors (an unquoted `@` was a lexer error before). Positions that read
  raw source text now accept `@` as an ordinary character where it used to
  fail lexing: a bareword `source`/`include` path (`source ./foo@bar.mix`) and
  the command after `|` (`print(1) | cat @foo`).

### Fixed

- HTTP 1xx, 204 and 304 responses are bodyless on every method, not only
  HEAD. A conditional GET answered 304 with `Content-Encoding: gzip` no longer
  fails with `HTTP_BODY`, so ETag polling works.

## 0.111.0

### Added

- `script_path()` returns the entry script's absolute, symlink-resolved path,
  the same answer as `realpath($0)`, fixed when the script starts (a later
  `chdir()`, including one in the prelude, does not move it). It is nil under
  `mix -c`, in the REPL, for `mix -` and when the path cannot be resolved at
  start. A `require`d module, even during its top-level init, gets the entry
  script's path.

### Fixed

- Lambdas created inside a served `on` handler keep the handler's local
  variables when they run later (they faulted with `undefined variable`). A
  module first required inside a handler still reads its globals live.
- `password_hash` sha512-crypt output is now verifiable by glibc `crypt(3)` and
  Dovecot.
- `chr()` and `ord()` structured error codes are pinned by tests.

## 0.109.1

Initial MixOS transplant of the current language library and regression corpus.
Language syntax, builtin contracts and evaluator behaviour retain the source
version. Environment and project roots use MixOS names. SSH helpers retain the
installed Mix path used by existing predecessor nodes during the migration.

---

<!-- page: https://mixos.dev/mix-shell/changelog/ (source: https://mixos.dev/mix-shell/changelog.md) -->

# Changelog

> Mirrored from [`cli/mix-shell/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/cli/mix-shell/CHANGELOG.md), where releases update it. The component's page is [mix-shell](README.md). This page describes the current `main` branch of MixOS.

## 0.117.0

### Changed

- `mix man` reads the manual built into the binary: every `docs/mix/*.md`
  page is packed into one zstd frame at build time, so a binary copied alone,
  with no checkout and no network, has its whole manual. With no
  `MIXOS_MAN_*` variable set the built-in page wins (it documents exactly this
  binary), then files on disk, then the online copy. `MIXOS_MAN_SOURCE=local`
  puts files on disk first, then the built-in manual, and never uses the
  network. `MIXOS_MAN_SOURCE=auto` or `MIXOS_MAN_URL` keeps the online-first
  order, with the built-in manual before a stale cached copy. `mix doctor`
  and `mix apropos` count and search the built-in pages. The compiled-in
  path to the build checkout's `docs/mix` is no longer a lookup candidate.

### Fixed

- A foreground job stopped (^Z) just after its exec is now stopped, not
  reported as "job stopped before exec acknowledgement" and aborted. The
  launch checked for the stop before reading the exec acknowledgement that
  was already waiting. This was the intermittent failure of the
  `owned_editor_pty` test
  `foreground_job_ctrl_z_fg_and_nested_editor_stop_preserve_draft`.

## 0.116.0

### Added

- Released with mix 0.116.0: the remote mix binary for `ssh_mix` and the
  other remote-mix builtins comes from the `mix_bin` option, else
  `MIX_REMOTE_BIN`, else the old install path's mix (`mix man remote`).

## 0.115.0

### Added

- Released with mix 0.115.0: `unix_connect()` opens a local unix-domain
  stream socket, with NUL-terminated frames for Varlink and hostd
  (`mix man system`).

## 0.114.0

### Changed

- Usage statistics are an append-only JSONL store. A run's exit appends one
  record to `runs/YYYY-MM-DD.jsonl` with a single write and does nothing
  else, so recording costs nothing measurable: `mix -c 1` went from 151 ms
  to 52 ms on a host with a busy history, the same as with stats off. Raw
  day files are never rewritten; `cache/` holds disposable per-day
  aggregates checked against the exact raw file; reports filter by each
  bucket's own date. `mix stats query` runs SQL over the old `mix.db` tables
  built in memory, so on a large history it now takes about a second.
- `clear` and `reset` append an operation anchored to storage positions, not
  a clock, under `ops.lock`. They refuse while the old weekly documents
  (`current.json`, `YYYY-WNN.json`) exist; those are read in place, never
  moved, and their `stats.lock` is never taken, so an older mix still writing
  them keeps working. `mix man stats` documents the store.

### Fixed

- A session task no longer inherits file descriptors the shell itself
  inherited without close-on-exec.

## 0.113.1

### Fixed

- Built on mix 0.113.1: `on dopus-test.command.executed` (a hyphenated
  handler name) now fires; before, it parsed and never did. `mix man bus`
  documents it.

## 0.113.0

### Added

- Built on mix 0.113.0 with the `mime` feature: `mime_type()` names a
  file's type as the desktop does. `mix man io` documents it.

## 0.112.1

### Fixed

- Built on mix 0.112.1: SIGTERM and Ctrl-C end a blocking `tcp_accept`,
  `tcp_recv`, `tcp_recv_line` or `ws_recv` at once, `tcp_send` takes a
  whole-send `{timeout}` (`TCP_SEND_TIMEOUT`), and receives serve buffered
  data first while traffic that delivers nothing counts against the
  deadline. `mix man system` documents them.

## 0.112.0

### Added

- Built on mix 0.112.0: server-side TCP (`tcp_listen`, `tcp_accept`,
  `tcp_local_addr`, `tcp_on` on a listener) and `on @.verb`, which registers
  a handler under the `--serve` name so one generic script serves any
  instance. `mix man serve` and `mix man system` document both.

### Fixed

- The serve reload lifecycle test's TERM-ignoring fixture creates the trace
  file itself. The citizen spawned it before the first trace line existed,
  so a fast start panicked on open and the grace test timed out.

## 0.111.0

### Fixed

- An interrupted run exits with status 130 (128+SIGINT) derived from the signal
  actually received, never from error text: an ordinary error whose message
  mentions `interrupted` now fails with its own diagnostic instead of exiting 0.
- SIGINT/SIGTERM are honoured during `--serve` startup (stalled broker
  registration, CPU-bound preludes, reloads) and during `-c`, script and
  `.mixrc` prelude loading. A caught interrupt cannot end in success, and
  `--result-fd` always reports it as an error frame.
- `script_path()` is resolved before the prelude runs in script and serve modes.

## 0.109.4

Initial MixOS shell transplant. Language semantics retain the source version.
Application transport is native ABP through noded. Runtime directories use the
shared config rule; installed manuals are available offline. Cross-process
native-session handoff bytes retain the frozen compatibility contract.

---

<!-- page: https://mixos.dev/mixos-mcp/changelog/ (source: https://mixos.dev/mixos-mcp/changelog.md) -->

# Changelog

> Mirrored from [`cli/mixos-mcp/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/cli/mixos-mcp/CHANGELOG.md), where releases update it. The component's page is [mixos-mcp](README.md). This page describes the current `main` branch of MixOS.

## Unreleased

- Replace the unserved application action/control tools with `app_commands`
  and `app_execute`, using the application's registry Bus verbs. Forward optional
  command parameters unchanged and preserve application error messages.
- Error-text pass-through without the old `application rc=` prefix also applies
  to `app_describe`, `desktop_windows` and `desktop_window_wait` through their
  shared native helper.
- The indexd Bus-mode call timeout is now 120 seconds by default, previously
  the Bus library's 60 seconds. SSH bridge requests carry the configured timeout.
- Retry bridge failures once before delivery for every verb; after delivery,
  retry only idempotent verbs. Feedback and timeouts report an unknown outcome.

---

<!-- page: https://mixos.dev/monitord/changelog/ (source: https://mixos.dev/monitord/changelog.md) -->

# monitord contract changes

> Mirrored from [`services/monitord/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/monitord/CHANGELOG.md), where releases update it. The component's page is [monitord](README.md). This page describes the current `main` branch of MixOS.

## 0.1.0 (draft)

- Read verbs `monitord.status`, `monitord.snapshot`, `monitord.processes`,
  `monitord.process`, `monitord.series` and `monitord.history`, all
  queries.
- Retained topic `monitord.summary`, every 5 s.
- History: every sample for 10 minutes in memory; minute rollups for 7 days
  and hour rollups for a year in SQLite (`/var/lib/monitord/history.db`,
  schema 1).
- Command line: `serve`, `snapshot`, `ps`, `history`, and the local actions
  `signal` and `renice`, which run as the caller.

---

<!-- page: https://mixos.dev/noded/changelog/ (source: https://mixos.dev/noded/changelog.md) -->

# noded changes

> Mirrored from [`services/noded/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/noded/CHANGELOG.md), where releases update it. The component's page is [noded](README.md). This page describes the current `main` branch of MixOS.

## 0.18.3

Add a structured rejection body to the different-channel `noded.register`
collision refusal: `{"schema": "noded.registration-rejection.v1",
"error_code": "NAME_TAKEN", "message": …}` alongside the unchanged `rc=10`
reply and `error` header. The body is additive only — ABP framing, return
codes, admission refusals and session transcript bytes are untouched — and
lets clients classify a collision without matching diagnostic text. The bus
client decodes it through a bounded typed envelope whose classification is
pinned by noded and bus tests.

## 0.18.2

Transplant the native broker, session authority and mesh routing to the MixOS
workspace. Preserve ABP verbs, admission domains and session transcript bytes.
Use strict MixOS configuration and owned shutdown signalling.

---

<!-- page: https://mixos.dev/settings/changelog/ (source: https://mixos.dev/settings/changelog.md) -->

# settings contract changes

> Mirrored from [`libs/settings/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/libs/settings/CHANGELOG.md), where releases update it. The component's page is [settings](README.md). This page describes the current `main` branch of MixOS.

## Unreleased

Additive, store format unchanged: the mail options `email.mail.quote_on_reply`
(boolean, default true) and `email.mail.reply_position` (`"above"` or `"below"`,
default `"above"`), which the email app's Reply now reads instead of fixed
values. Omitted at their defaults, so existing profiles are unchanged.

## 0.8.0

Additive, store format unchanged (3):

- `Desktop.email` (`email::Email`): the email app's JMAP accounts
  (`email.accounts`, replaced whole, in tree order: id, name, url, email,
  ca_path, enabled, signature), `email.default_account` and the mail options
  `email.mail.page_size` (10–500, default 100), `mark_read_on_open` and
  `confirm_delete` (both default true). Omitted at its defaults, so older
  profiles keep their seals; it does not touch `Effective`. A profile that
  sets any of it will not load in a 0.7.0 build: reset `email` first.
- Nothing in it is secret: an account has no password field and every
  record refuses unknown keys, so `settings.apply` refuses an account that
  carries `password`.
- `Summary.email` and `Followed::Look.email` carry it to followers;
  `email::from_snapshot`, `email::from_summary` and `Email::from_account`
  read it; `email::mint_account_id` mints a new unique `acct-` id.
- `settings.describe` lists each `email.*` path; `email` alone resets or
  replaces the whole group.

## 0.7.0

Additive, store format unchanged (3):

- `Desktop.terminal` (`terminal::Terminal`): the term's preferences under
  `terminal.*` (font family/size/weight, padding, scrollback lines, scroll
  speed, border width, cursor shape/blink, focus ring/strength, copy on
  select, `TERM`). Every default reproduces the term before the group
  existed except padding (8 px instead of 1 px) and the focus ring: its
  default, `accent` at strength 0.25, draws the focused pane's border as the
  card border moved a quarter toward the theme accent, where the term drew
  it halfway before. That change is intentional (a subtler tinted ring);
  `neutral` remains available, and `accent` with strength 0.5
  gives the old look. Omitted at its defaults (and each value within it), so older
  profiles keep their seals. It does not touch `Effective`, as `keymaps`
  does not. A profile that sets any of it will not load in a 0.6.0 build:
  reset `terminal` first.
- `Summary.terminal` and `Followed::Look.terminal` carry it to followers.
- `settings.describe` lists each `terminal.*` field with its range and
  default; `terminal` alone resets or replaces the whole group.
- `terminal: null` resets the whole terminal group, as advertised.
- Correct the scroll speed unit: rows per wheel line, scaled by speed/40;
  touchpad travel counts in cell heights at that scale. Default 40 keeps
  the existing one-row-per-wheel-line behaviour; it is not a pixel distance.

## 0.6.0

Additive, store format 3 ([decision](https://github.com/markc/mixos/blob/main/docs/docs/decisions/2026-10-14-session-icon-stroke-and-type.md)):

- `Appearance` and `Effective` gain four optional session choices:
  `icon_stroke` (1.0 to 3.0 in quarter steps), `font_family`,
  `font_weight` (100 to 900 in steps of 100) and `mono_family`. Each is
  omitted when unset, so profiles without them keep their digests.
- `ChangePlan`: `icon_stroke` is a paint change; the font choices are
  resource and text changes.
- `CompactEffective` carries the same fields.
- The store writes format 3. A format-2 build refuses a profile that sets
  any of them; reset them first with `settings.reset` or a null value.

Rust API change: `Followed::Look.appearance` is now `Box<Appearance>` to keep
follower events compact as font settings grow. Borrowed callers use deref
coercion; callers that take ownership unwrap with `*appearance`.

## 0.5.0

Authority verbs 0.3.0 (additive): snapshot schema 2
([decision](https://github.com/markc/mixos/blob/main/docs/docs/decisions/2026-10-11-settings-snapshot-schema-2.md)).

- `compact`: `CompactSnapshot` (schema 2) sends each distinct design
  projection once under `designs`, keyed by digest; each context's `design`
  names one. `encode` builds it; `decode` reads schema 1 or 2 into the same
  in-memory `Snapshot`, so consumers, reducer, cache and effective digests
  are unchanged. A dangling or unnamed design is refused.
- `compact_topic(profile)` / `COMPACT_TOPIC_PREFIX`: the retained schema 2
  topic, `settingsd.desktop.compact.<profile>`, published between the
  schema 1 topic and the summary.
- **Breaking:** `ReadRequest.schema` (1 by default and never serialised;
  2 for the compact form) on `settings.get` and `settings.appearance.get`.
  Another schema is refused with `unsupported_schema`.
- `native` follows the compact topic and reads schema 2. Consumers on the
  schema 1 topic are not affected.
- `describe()` lists the snapshot schemas and the compact topic.

## 0.4.0

Authority verbs 0.2.0 (additive), snapshot schema still 1
([decision](https://github.com/markc/mixos/blob/main/docs/docs/decisions/2026-10-11-settings-summary-reads.md)):

- `Summary` (schema 1): binding, incarnation, revision, design revision,
  source digest, appearance names and `custom_source`; never projections or
  a custom source. `summary_topic(profile)` /
  `SUMMARY_TOPIC_PREFIX` name its retained topic,
  `settingsd.desktop.summary.<profile>`, published beside the snapshot topic.
- `ReadRequest.view` (`View::Full`, the default and never serialised, or
  `View::Summary`) selects `settings.get`'s answer.
- `follow::Follower` subscribes to the summary topic and reads the summary
  view. **Breaking:** `Followed::Look` gains `custom_source`, and its
  `appearance.source` is always `None`.
- `describe()` lists the read views and both topics.

The cache interpretation includes the library version, so caches written by
0.3.x fall back visibly once.

## 0.3.5

Add the appearance keys `appearance.style` (null, the default, takes the
scheme's own style; else plain, pro, studio or classic),
`appearance.decorations` (csd, the default, or ssd) and
`appearance.caption_side` (right, the default, or left). They resolve into
every effective context; a style change is a paint and layout change and a
decorations or caption-side change a layout change. Older desktops and
snapshots load with the defaults. Authority verbs/schema remain 0.1.0/1.

## 0.3.4

Expose the public snapshot identity of an activated cache capture so hosts can
report fenced persistence receipts without copying its projection or private
producer serial. Authority verbs/schema remain 0.1.0/1. The cache interpretation
includes the library version; older caches fall back visibly without affecting
authority history.

## 0.3.3

Add immutable cache targets for borrowed workers, capture deduplication and
producer-fenced writer opening. Add lazy persistent fallback loading after
retained resource validation, preserving load diagnostics when embedded works.
Authority verbs/schema remain 0.1.0/1. Older presentation caches are rejected
because the cache interpretation includes this library version.

## 0.3.2

Expose shared consumer evidence with separate accepted and applied identities,
connection generation, confirmation, presentation kind and faults. Readback
never claims frame presentation or broker participant registration. Authority
verbs and snapshot schema remain 0.1.0 and 1.

## 0.3.1

Split authenticated native delivery decoding from UI consumer handling, retaining
binding/generation fences in the decoded value. Add shared session binding and
capture identity predicates for coalesced resource scheduling. Authority wire
contract/schema remain 0.1.0/1. The cache interpretation includes this crate's
version, so older local presentation caches are rejected and embedded defaults
remain available; authority persistence is unaffected.

## 0.3.0

Add shared retained/cache/embedded fallback preparation with host resource
validation, immutable stage fencing and explicit presentation labels. Persisted
data never seeds authority ordering or mutation fences. Optional cache I/O
uses bounded no-follow directory-relative reads and atomic replacement, with
schema/target/capability/digest checks plus complete projection recompilation.
Applied-generation captures and one locked serial writer reject stale saves;
ambiguous post-rename failure remains visible. Exact JSON float round trips
preserve compiler projection comparison. The authority wire/schema stay
0.1.0/1. Real resource loading, GUI/first-map timing and artifact integration
remain pending.
Keep fallback preparation/activation faults separate from authority/current
resource faults, and detect unsupported cache headers before strict body parsing.

## 0.2.0

Add transport-neutral consumer and render-domain change plan, with an optional
native executor over an app-owned supervised connection. Bound work/buffering,
coalesce queue-loss recovery, fence connection/consumer/renderer completions,
and advance unchanged render evidence without a redraw. Retired confirmation
candidates are deduplicated within a bounded history. No owned runtime or
renderer dependency. Authority wire contract/schema remain 0.1.0/1.
Use canonical app/shell constructors, captured read baselines/tickets and one
absolute recovery deadline. Malformed-event storms cannot bypass the deadline;
same-incarnation rollback is distinct from a read racing a newer publication.
DTO additions require explicit render/evidence classification at compile time.
Persisted fallback cache, artifact/resource preparation and GUI activation are
still pending; this API does not advertise their completion.

## 0.1.0

Initial binding/revision/receipt/snapshot types, independent design read
projection, validated batch vocabulary and ordering/work-ticket reducer.
Renderer transport/bootstrap adapters remain pending.
Before initial release: report confirmed same-revision contradictions and
validate authored app enum values before accessibility precedence.

---

<!-- page: https://mixos.dev/settingsd/changelog/ (source: https://mixos.dev/settingsd/changelog.md) -->

# settingsd contract changes

> Mirrored from [`services/settingsd/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/services/settingsd/CHANGELOG.md), where releases update it. The component's page is [settingsd](README.md). This page describes the current `main` branch of MixOS.

## 0.1.0

Serve describe/get/validate/apply/reset/status through native ABP; durable
changed/no-op receipts, target/revision fencing, exclusive writer, recoverable
replacement and complete scoped retained publication. Package the service unit.
Before initial release: add explicit idempotent first-run session seed, preserving
established missing-primary failure, and session wants/upholds wiring without
making GUI startup wait for authority readiness. Authority verbs/schema unchanged.
First creation requires installer-only --allow-create; the automatic unit uses
plain seed and cannot recreate a wholly lost profile directory or mount.

Before initial release: pin package source and verify stored content digest;
bind storage to the held directory/lock; fence validation; add bounded pending
publication retries and preserve missing-store failure visibility.
Fence effective compiler interpretation; distinguish intact unsupported/I/O
failures from corruption; keep pending publication backoff capped at 30 seconds
until success. Inline capacity refusal has a distinct snapshot_too_large status.

---

<!-- page: https://mixos.dev/term/changelog/ (source: https://mixos.dev/term/changelog.md) -->

# Terminal Bus contract

> Mirrored from [`apps/term/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/apps/term/CHANGELOG.md), where releases update it. The component's page is [term](README.md). This page describes the current `main` branch of MixOS.

## 0.4.0

The window is egui on wgpu, its grid drawn on the GPU by `term-render`.
The terminal's own verbs (`term.session`, `term.tabs`, `term.tab.*`,
`term.panes`, `term.pane.*`, `term.snapshot`, `term.scroll`, `term.type`,
`term.props.watch`, INFO and HELP) are unchanged.

Added: `term.commands` and `term.execute` (every window action by command
id), `app.describe`, the toolkit drive verbs (`term.ui.*`, `term.window`,
`term.window.state`), and `term.command.executed`, published for every
command run with how it was reached.

Alt is Meta: ESC before the key (readline's Alt+b/f/., Alt+Backspace,
Alt+Enter), and Alt+cursor keys send xterm's CSI 1;3 sequences.
Ctrl+[ and the other control punctuation send their control codes.

Program (OSC) titles now reach the tab strip without a `term.props.watch`
watcher. Right Shift with Left/Right no longer changes tab: right-hand
modifier chords are the person's own keys on MixOS.

## 0.3.5

Shared the native application bootstrap and task worker. PTY ownership
and ordered teardown stay in the terminal. The native session contract is
unchanged.

## 0.3.4

The terminal frontend and native session verbs entered the tree. The
cross-process session constants and the child-only descriptor handoff keep
their bytes.

---

<!-- page: https://mixos.dev/toolkit/changelog/ (source: https://mixos.dev/toolkit/changelog.md) -->

> Mirrored from [`libs/toolkit/CHANGELOG.md`](https://github.com/markc/mixos/blob/main/libs/toolkit/CHANGELOG.md), where releases update it. The component's page is [toolkit](README.md). This page describes the current `main` branch of MixOS.

<!-- SPDX-License-Identifier: MIT OR Apache-2.0 -->
# Changelog

## Unreleased — 2026-10-21

- Publish command contract 0.2.0 executed bodies (v2, bounded params and result).
- Map authorisation refusals to legacy `CommandError::Denied`.
- Report stored shortcut and `more` chords in the keymaps grammar, with
  Ctrl, Alt, Shift modifier order, through both command adapters.

---

<!-- page: https://mixos.dev/docs/desktop/ (source: https://mixos.dev/docs/desktop.md) -->

# Desktop components

The components a MixOS desktop installs, generated from each component's declared
install profiles. A component in more than one profile is listed on each page. Every
component, with its kind and source, is in the [component index](components.md); see also
the [server](server.md) list. This page describes the current `main` branch of MixOS.

## Core components

On every MixOS system.

- [mixos-mcp](../mixos-mcp/README.md) (cli): MCP stdio access to the native MixOS Bus.
- [monitord](../monitord/README.md) (service): How monitord samples a host's CPU, memory, disks, network and processes, keeps history in memory and SQLite, and answers read verbs on the Bus, so any node's load can be read from anywhere on the…

## Desktop components

- [indexd](../indexd/README.md) (service): Local semantic search over the MixOS Bus, with an ssh bridge and an in-process CLI.
- [monitor](../monitor/README.md) (app): Monitor is the MixOS task manager, showing the processes and performance that monitord reports for this node or any node on the mesh, with End task and Kill for this node's processes.

## Unclassified

Apps, services and command-line components that do not declare install profiles
yet. They are listed on both this page and the server page until they do.

- [backdrop](../backdrop/README.md) (app): The MixOS desktop background — drawn by its own program on the compositor's background layer, on every output, at native and fractional scale.
- [blobd](../blobd/README.md) (service): The node blob store: content-addressed bytes kept in mds, with owner pins, quotas and garbage collection. The MixOS port of blobd, with the store, the Bus citizen, the byte lane and the cross-node…
- [bridged](../bridged/README.md) (service): How bridged puts an external application with a line-delimited JSON control channel on the Bus, one instance per application, and what that exposes.
- [busviewer](../busviewer/README.md) (app): BusViewer is the MixOS desktop app that lists the services and verbs on this node's Bus, shows each verb's description and the mesh peers, and calls one verb once with a JSON body.
- [ced](../ced/README.md) (app): The MixOS Editor, a desktop text editor over the edit Bus service, where people and agents edit the same document at once and see each other's carets, selections and changes live.
- [compd](../compd/README.md) (service): The MixOS Wayland compositor, which owns scanout, rendering, input and capture, and serves the comp Bus service with its workspaces, verbs, topics and props tree.
- [dopus](../dopus/README.md) (app): MixOS's twin-pane file manager — two folder trees side by side, Places and Properties sidebars, drag and drop between panes, menus and keys for every action, and a Bus surface for agents that reads…
- [editd](../editd/README.md) (service): The edit service, which holds shared text buffers that people and agents edit together, with revision checks, per-origin undo, anchors, atomic save, external-change detection and recovery.
- [email](../email/README.md) (app)
- [hostd](../hostd/README.md) (service): How hostd answers questions about the host and carries out privileged host changes through closed, typed verbs behind standing grants, receipts and rollback, so agents never need sudo.
- [inputd](../inputd/README.md) (service): How inputd turns keys into Bus verbs below the compositor, keeps the user keys for the person, and holds its keyboard grab only while its own VT is active.
- [mesh-sign](../mesh-sign/README.md) (cli): Signs and verifies the mesh inventory, the trust root of a MixOS mesh.
- [mix-shell](../mix-shell/README.md) (cli): The Mix shell library, holding the interactive line editor, the command classifier, the native-session bootstrap and the Bus citizen runtime that the mix binary runs.
- [mixtrayd](../mixtrayd/README.md) (service)
- [noded](../noded/README.md) (service): The MixOS Bus broker, which handles service registration, discovery, routing, subscriptions, authenticated local session grants and mesh peering between nodes.
- [notifyd](../notifyd/README.md) (service): How notifyd keeps the desk's notifications, shows them as toasts and in the Notifications page, and tells an agent or app which button the human pressed.
- [portald](../portald/README.md) (service): How portald serves the XDG Settings and ScreenCast portals on the session bus, where the appearance values and screen frames come from, and how applications and agents use them.
- [prefs](../prefs/README.md) (app): MixOS's preferences window — a sidebar of editors: Applications follows, installs, updates, rolls back and removes upstream releases; Appearance sets the session's colour scheme, style, mode,…
- [releasesd](../releasesd/README.md) (service): How releasesd follows upstream application releases on GitHub and installs their Linux builds per user, verified, with rollback, from the command line or the Bus.
- [screenshot](../screenshot/README.md) (app): MixOS's screenshot app — Print Screen for a region, Shift+Print for the screen, Alt+Print for a window; arrows, boxes, pens, highlighter, text, numbered markers, crop and redaction that stay…
- [settingsd](../settingsd/README.md) (service): The headless desktop settings authority, the one writer for a session profile's settings, with durable receipts and retained change publication on the Bus.
- [system](../system/README.md) (cli): The system package builds the mix shell executable with optional noded, monitord, maild, webd and dnsd personalities selected by the name it is started under.
- [term](../term/README.md) (app): The MixOS terminal, with tabs, split panes and a GPU-drawn grid, driven by the session settings and fully scriptable over the Bus.

---

<!-- page: https://mixos.dev/docs/server/ (source: https://mixos.dev/docs/server.md) -->

# Server components

The components a MixOS server installs, generated from each component's declared
install profiles. A component in more than one profile is listed on each page. Every
component, with its kind and source, is in the [component index](components.md); see also
the [desktop](desktop.md) list. This page describes the current `main` branch of MixOS.

## Core components

On every MixOS system.

- [mixos-mcp](../mixos-mcp/README.md) (cli): MCP stdio access to the native MixOS Bus.
- [monitord](../monitord/README.md) (service): How monitord samples a host's CPU, memory, disks, network and processes, keeps history in memory and SQLite, and answers read verbs on the Bus, so any node's load can be read from anywhere on the…

## Server components

- [dnsd](../dnsd/README.md) (service): authoritative mesh DNS for the zones in zones.mix
- [maild](../maild/README.md) (service): JMAP, SMTP, IMAP and DAV mail service
- [toolsd](../toolsd/README.md) (service): Runs the tools webd's admin panel queues (whois, dig, traceroute, shwho) as an unprivileged drain, outside webd's sandbox.
- [webd](../webd/README.md) (service): Virtual hosts, CMS routes, embedded Mix handlers and ACME for the MixOS web service.

## Unclassified

Apps, services and command-line components that do not declare install profiles
yet. They are listed on both this page and the desktop page until they do.

- [backdrop](../backdrop/README.md) (app): The MixOS desktop background — drawn by its own program on the compositor's background layer, on every output, at native and fractional scale.
- [blobd](../blobd/README.md) (service): The node blob store: content-addressed bytes kept in mds, with owner pins, quotas and garbage collection. The MixOS port of blobd, with the store, the Bus citizen, the byte lane and the cross-node…
- [bridged](../bridged/README.md) (service): How bridged puts an external application with a line-delimited JSON control channel on the Bus, one instance per application, and what that exposes.
- [busviewer](../busviewer/README.md) (app): BusViewer is the MixOS desktop app that lists the services and verbs on this node's Bus, shows each verb's description and the mesh peers, and calls one verb once with a JSON body.
- [ced](../ced/README.md) (app): The MixOS Editor, a desktop text editor over the edit Bus service, where people and agents edit the same document at once and see each other's carets, selections and changes live.
- [compd](../compd/README.md) (service): The MixOS Wayland compositor, which owns scanout, rendering, input and capture, and serves the comp Bus service with its workspaces, verbs, topics and props tree.
- [dopus](../dopus/README.md) (app): MixOS's twin-pane file manager — two folder trees side by side, Places and Properties sidebars, drag and drop between panes, menus and keys for every action, and a Bus surface for agents that reads…
- [editd](../editd/README.md) (service): The edit service, which holds shared text buffers that people and agents edit together, with revision checks, per-origin undo, anchors, atomic save, external-change detection and recovery.
- [email](../email/README.md) (app)
- [hostd](../hostd/README.md) (service): How hostd answers questions about the host and carries out privileged host changes through closed, typed verbs behind standing grants, receipts and rollback, so agents never need sudo.
- [inputd](../inputd/README.md) (service): How inputd turns keys into Bus verbs below the compositor, keeps the user keys for the person, and holds its keyboard grab only while its own VT is active.
- [mesh-sign](../mesh-sign/README.md) (cli): Signs and verifies the mesh inventory, the trust root of a MixOS mesh.
- [mix-shell](../mix-shell/README.md) (cli): The Mix shell library, holding the interactive line editor, the command classifier, the native-session bootstrap and the Bus citizen runtime that the mix binary runs.
- [mixtrayd](../mixtrayd/README.md) (service)
- [noded](../noded/README.md) (service): The MixOS Bus broker, which handles service registration, discovery, routing, subscriptions, authenticated local session grants and mesh peering between nodes.
- [notifyd](../notifyd/README.md) (service): How notifyd keeps the desk's notifications, shows them as toasts and in the Notifications page, and tells an agent or app which button the human pressed.
- [portald](../portald/README.md) (service): How portald serves the XDG Settings and ScreenCast portals on the session bus, where the appearance values and screen frames come from, and how applications and agents use them.
- [prefs](../prefs/README.md) (app): MixOS's preferences window — a sidebar of editors: Applications follows, installs, updates, rolls back and removes upstream releases; Appearance sets the session's colour scheme, style, mode,…
- [releasesd](../releasesd/README.md) (service): How releasesd follows upstream application releases on GitHub and installs their Linux builds per user, verified, with rollback, from the command line or the Bus.
- [screenshot](../screenshot/README.md) (app): MixOS's screenshot app — Print Screen for a region, Shift+Print for the screen, Alt+Print for a window; arrows, boxes, pens, highlighter, text, numbered markers, crop and redaction that stay…
- [settingsd](../settingsd/README.md) (service): The headless desktop settings authority, the one writer for a session profile's settings, with durable receipts and retained change publication on the Bus.
- [system](../system/README.md) (cli): The system package builds the mix shell executable with optional noded, monitord, maild, webd and dnsd personalities selected by the name it is started under.
- [term](../term/README.md) (app): The MixOS terminal, with tabs, split panes and a GPU-drawn grid, driven by the session settings and fully scriptable over the Bus.