Cosmix Specification Suite

Reading guide for the Cosmix protocol and design specifications. Chapters are ordered bottom-to-top through the stack — start at Chapter 01 (the wire protocol that everything speaks) and work up to Chapter 06 (the design system that governs what users see).

The Stack

Cosmix is a sovereign intelligence stack: mesh networking, mail, file sync, desktop rendering, and AI inference — all Rust, all speaking one protocol. The architecture draws from AmigaOS, where a single ROM held the kernel, graphics, windowing, and scripting bus in one coherent package. Cosmix recreates that coherence across Linux process boundaries.

The Amiga Mapping

AmigaOS Kickstart put Exec (kernel + message passing), Intuition (windows + gadgets), graphics.library (drawing), and layers.library (overlapping regions) in one ROM, one address space. Crucially, Intuition was simultaneously the compositor, the window manager, and the widget toolkit — because they shared memory structures (RastPort, Window, Screen, Layer) rather than communicating over IPC.

Linux + Wayland necessarily separates these concerns by process boundary. You cannot have a single-address-space Intuition. What you can have is two cooperating components that together provide Intuition's functionality, unified by shared vocabulary and a clean protocol at the boundary.

The Intuition Split

Intuition maps to two cosmix components:

• cosmix-shell — the window-management half. Surface placement, stacking, focus policy, workspace semantics, global shortcuts, modal/popover semantics, input routing to surfaces. Speaks postcard to the compositor (hot path) and AMP to applications (orchestration).

• cosmix-deskd — the widget-toolkit half. Panel content rendering, widget state, hit-testing, widget-level events, text layout, the visual system. Speaks AMP to applications. Does not speak directly to the compositor.

The user experience of Intuition-like coherence is achieved through: 1. Shared vocabulary — both agree on what a "panel" is, what layers mean 2. Consistent visual system — same design tokens, typography, color palette 3. Unified event flow — apps don't know which component handled what 4. AMP as the app-facing protocol — the split is invisible to applications

The Protocols

• Wayland — standard Linux display protocol between compositor and its clients. Third-party apps and (currently) deskd speak Wayland to the compositor. cosmix does not define or extend Wayland.
• AMP (human-readable markdown frontmatter) — everything applications touch. Commands, events, UI declarations, data updates. Debuggable with cat.
• postcard (binary, Rust-to-Rust) — planned for Phase B/C. Compact binary serde (varint-encoded, no field names, ~60ns serialize) for the hot path between compositor and shell (60-165Hz pointer motion, frame callbacks, surface damage). Requires both sides to share Rust type definitions — unsuitable for cross-language or application-facing use. Also the planned transport for bulk Rust-to-Rust data transfer between mesh nodes (file sync blocks, binary replication) over WireGuard TCP, replacing the need for WebRTC data channels. Applications never see postcard.
• WebRTC (via str0m) — planned, parked until calld. Media streams (audio/video) for voice/video calls between mesh nodes. AMP handles signaling (SDP/ICE exchange); WebRTC handles the media plane. calld is the only planned WebRTC consumer — WebRTC's complexity (ICE/DTLS/SCTP) exists to solve NAT traversal and encryption, both of which WireGuard already provides. For binary data transfer, postcard over WireGuard TCP is simpler (no ICE negotiation, no double encryption, instant connection establishment).

Encryption Layering

WireGuard provides network-layer encryption across the mesh. Cosmix-native protocols (AMP, postcard) rely on this exclusively — no per-protocol TLS, no certificate management, no key exchange. The WG /24 subnet is the trust domain and WireGuard membership is the credential.

Third-party wrapped services may add redundant encryption. For example, syncthing's BEP mandates TLS 1.2+ with mutual certificate auth (the device ID is the certificate hash). Running syncthing over WireGuard means double encryption — WG at the network layer, TLS at the application layer. The performance cost is negligible (AES-NI), but the architectural redundancy is one motivation for an eventual native sync engine using postcard over raw TCP on WireGuard, where exactly one encryption layer handles transport security.

Protocol Boundary Table

The rule: if an application could ever need to send or receive it, it's AMP. If it's internal plumbing between cosmix's own Rust components, it's postcard. If it's real-time media, it's WebRTC.

What the Shell Owns

cosmix-shell is the Intuition window management half:

• Surface placement policy — where new surfaces go, what size, which workspace
• Stacking and focus policy — which surface is on top, keyboard focus rules
• Workspace semantics — how many, how users move between them
• Global keyboard shortcuts — Super+Tab, workspace switches, launcher
• Panel placement — tray, status bar, docks
• Modal and popover semantics — what is modal to what
• Input routing — compositor says "pointer at X,Y"; shell says "route to surface S" (in Phase B on cosmic-comp, input routing is handled natively by the compositor; cosmix-shell only sees what layer-shell protocol grants it)

What the Display Service Owns

cosmix-deskd is the Intuition widget toolkit half:

• Panel content rendering — given a ui.panel message, paint pixels
• Widget state — scroll positions, selection, column widths, focus-within-panel
• Hit-testing — which widget did the user click?
• Widget-level events — mouse click at X,Y → select on widget files
• Text layout, color rendering, the visual system
• Internal interactions — scrolling, drag-resize, column-resize (don't escape the panel)

The display service speaks AMP to applications and does not speak directly to the compositor. It receives input events from the shell (or currently from winit, which mediates the same flow via Wayland).

The Rust Ecosystem

Phasing

Phase B is the key insight. Before replacing the compositor, cosmix-shell can run as a privileged application using Wayland layer-shell protocols to implement cosmix-specific window management on top of cosmic-comp. This is what status bars, notification daemons, and launchers do on various Wayland compositors. It can coexist with cosmic-comp indefinitely, and teaches exactly what cosmix-comp must provide when the time comes.

Phase ordering discipline: build the shell before the compositor. Writing the compositor first means guessing at what the shell needs. Writing the shell first, on cosmic-comp, teaches you exactly what cosmix-comp must provide.

Design Discipline

• winit is transitional. Panel lifecycle and input event flow should feel like cosmix abstractions with winit as implementation detail. Features that depend on winit's specific model will need unwinding in Phase B/C.

• Sketch the shell↔display service protocol early. Before cosmix-shell exists, sketch what AMP messages between shell and deskd look like: panel creation, workspace changes, surface geometry, focus changes. This prevents accidentally baking winit assumptions into deskd.

• Fixed widget registry is correct. Amiga Boopsi (later Intuition) added extensible widget classes. cosmix goes the opposite direction: no runtime widget extensibility, all extensibility at the app level via AMP. This is right for mesh-addressable UIs where the renderer must be deterministic across nodes.

The Unavoidable IPC Cost

Amiga Intuition was fast partly because window management, rendering, and event dispatch were function calls in one address space. cosmix accepts the cost Wayland imposes — every pointer event crosses at least one process boundary. The mitigation is the postcard-vs-AMP split: binary serde for the hot path, human-readable text for orchestration. The target is "fast enough that users don't notice the difference," which is achievable on modern hardware.

Glossary

Terms used across the spec suite. Defined once here; chapters reference this section rather than re-defining.

Chapter Format

All chapters use YAML frontmatter — --- delimited key: value headers followed by a markdown body. This is structurally identical to AMP wire format: a spec document is a valid AMP message (the frontmatter fields parse as AMP headers, the document body parses as the AMP body). The three-reader principle applied to the specs themselves.

Required fields:

---
title: <chapter title>
chapter: <number>
version: <semver or semver-draft>
status: stable | draft
date: <last meaningful update, YYYY-MM-DD>
supersedes: <filename or none>      # optional
amends: <filename>                  # optional — for spec deltas
companion: <filename>               # optional — for paired specs
---

Specs reference each other by chapter filename (e.g., 05_amp-display-protocol.md), not by date-prefixed names.

Chapters

Reading Order

Start here: Chapter 01 defines the AMP message format — the single wire protocol that every cosmix component speaks. This is the Exec of the stack: understand it and you understand how everything communicates.

Then: Chapter 02 (command naming conventions) and Chapter 03 (reactive pub/sub) extend the protocol with standard patterns. These are the shared libraries that all services use.

Scripting: Chapter 04 defines Mix, a systems scripting language in the ARexx tradition. Mix works as a standalone shell (filesystem, HTTP, JSON, regex, crypto, process management) and gains AMP mesh messaging (send, address, emit) when a hub is available. Like ARexx, the language is useful in both contexts.

Display: Chapters 05 and 06 define how processes declare user interfaces and how the display service renders them. Chapter 05 is the protocol specification (wire format, commands, widget types). Chapter 06 is the design system (the "Intuition" — visual language, interaction model, composition patterns).

Planned Chapters

These chapters don't exist yet. "Planned" means the component exists and could be documented now. "Deferred" means the component doesn't exist yet and the chapter will be written alongside it.

Historical Note

The spec suite was reorganized on 2026-04-18 from date-prefixed filenames (e.g., 2026-03-09-amp-v04-cosmix-specification.md) to numbered chapters. Chapters are versioned by content, not by date. Historical discussions in _doc/ and _journal/ may reference the older filenames — those references describe what was true at the time and are not updated retroactively.

AMP — Cosmix Wire Protocol Specification

Every app is a service. Every service speaks AMP. Every node is reachable. One protocol, one language, one wire format — from Unix socket to mesh.

1. What AMP Is

On the Amiga, ARexx was built into the OS. Every serious application exposed an ARexx port — a named endpoint that accepted commands and returned results. A three-line script could tell a paint program to render an image, a word processor to insert the filename, and a file manager to move it to a folder. No APIs to learn, no SDKs to install — just send commands to named ports in a common language.

AMP (AppMesh Protocol) recreates this for the cosmix desktop, extended to span multiple machines over WireGuard. Every application — desktop renderer, mail server, file sync daemon, or AI inference pipeline — registers as a service on the hub. Mix is the scripting language. Rust is the engine. AMP is the wire format everywhere — hub WebSockets, mesh peering, and log files.

Why Mix

• ARexx reborn — Mix is an ARexx-inspired language with native AMP keywords (send, address, emit). A three-line Mix script orchestrates mesh services the same way a three-line ARexx script orchestrated Amiga apps.
• Pure Rust — the interpreter (cosmix-lib-mix) compiles into every cosmix binary. No external runtime, no FFI, no subprocess.
• Hot-reloadable — edit a script, run it again. No compilation step.
• 115 builtins — JSON, regex, TOML, HTTP, crypto, filesystem, process management. Enough to build real tools without reaching for Rust.
• Shell-capable — Mix is the daily-driver shell (~/.local/bin/mix), not just a scripting language. Interactive REPL, job control, PATH search.

Why Rust (everything else)

• One language for everything — desktop renderer (cosmix-deskd), mail server (cosmix-maild), node daemon (cosmix-noded), file sync (cosmix-syncd), AI inference (cosmix-agentd). Single-binary deployments everywhere.
• Memory safety guaranteed — the compiler catches the bugs that crash C programs and corrupt data in Go programs.
• Performance — zero-cost abstractions, no garbage collector, no runtime. A Rust AMP parser is as fast as a hand-written C parser.
• Type safety end-to-end — the same AmpMessage struct serialises to a WebSocket frame, a hub route, and a log file.

2. Design Principle: Three-Reader Format

Every AMP message must be simultaneously useful to three readers:

1. Machines — deterministic header parsing for routing, dispatch, and filtering. A router reads to:, from:, command: and forwards. No understanding required.
2. Humans — cat, grep, render in any markdown viewer. A developer debugging at 2am reads the message and knows what happened.
3. AI agents — natural language comprehension without schema definitions. An agent reads the full message — headers and body — and reasons about it as text.

This is not a nice-to-have. It is the core constraint that drives every format decision in AMP.

Why this matters

Traditional protocols serve one reader well and force the others through translation layers:

An AI agent consuming an AMP event stream pays ~60% fewer tokens than the equivalent JSON-RPC representation, while gaining MORE context, not less. The markdown body is the format LLMs were trained on billions of tokens of. An agent doesn't need a tool definition to understand:

---
amp: 1
type: event
from: maild.cosmix.cachyos.amp
command: email.received
---
# New email received
From: **alice@example.com**
Subject: Invoice Q2-2026
Mailbox: Inbox
Size: 4.2 KB

It reads it, understands it, and can generate a response in the same format.

The boundary rule

Headers route. Bodies reason. A dumb router must never need to parse the body. An agent should never need to understand headers to reason about content. The same message works for a stateless forwarder (parse three headers, dispatch) AND a reasoning agent (read everything, think about it).

AI agents as mesh nodes

An AI agent connected to the mesh via WebSocket is a first-class participant:

• No tool definition maintenance — when a new port appears on the mesh, the agent discovers it through HELP commands (which return AMP messages). No JSON schema to update.
• Self-describing commands — command: search, args: {"query": "invoices"}, from: cosmix-mail.cosmix.mko.amp tells the agent what this does.
• Multi-agent coordination becomes conversation — two agents on different nodes exchanging AMP messages are passing structured text to each other. Headers handle routing; bodies handle reasoning.

3. AMP Everywhere: One Protocol, All Transports

v0.4's defining change: AMP is no longer reserved for mesh communication. Every byte that crosses a cosmix boundary — local Unix socket, mesh WebSocket, log file — uses AMP framing. There is no "internal format" vs "wire format" distinction. There is only AMP.

Why not length-prefixed JSON for local sockets?

The v0.3 spec assumed local IPC would use a simpler binary-framed JSON format, with AMP reserved for mesh traffic. This created two parsers, two serialisers, two test suites, two mental models, and a translation layer at the mesh boundary. v0.4 eliminates this:

The ---\n delimiter is 4 bytes, same as a 32-bit length prefix. But it's self-describing (you can see it in a hex dump), resyncable on error, and requires no byte-order convention.

Body delimiter safety. Since AMP bodies may contain markdown, and markdown horizontal rules (--- on their own line) collide with the ---\n delimiter, AMP uses a two-line end-of-message marker: ---\nEOM\n. A --- line in the body is safe — only the exact sequence ---\n followed by EOM\n terminates a message. See §5.2 for details.

The transport matrix

One parser. One serialiser. One test suite. One mental model.

4. The AMP Address

AMP uses DNS-native addressing. Addresses read left-to-right from most-specific to least-specific:

[port].[app].[node].amp

Examples:

maild.cosmix.cachyos.amp           → mail server on cachyos
deskd.cosmix.cachyos.amp           → display service on cachyos
noded.cosmix.cachyos.amp           → hub on cachyos
maild.cosmix.mko.amp               → mail server on mko
webd.cosmix.mko.amp                → web server on mko

• .amp is the mesh TLD
• Node names (cachyos, mko, mmc) are subdomains under .amp
• cosmix is the application namespace (always cosmix for this ecosystem)
• Service names (maild, deskd, noded) are the leaf — the actual service endpoint

Local shorthand: maild alone implies .cosmix.<local-node>.amp when running locally. The hub resolves short names to local service connections.

Remote addressing: maild@mko (or maild.cosmix.mko.amp in full form) tells the hub to route through the mesh to the mko node. If mko is not in the WireGuard mesh, resolution fails with error code 20.

5. The AMP Message

AMP messages use markdown frontmatter as the wire format — --- delimited headers with an optional freeform body, terminated by ---\nEOM\n. The encoding is UTF-8. Every AMP message is stored as a .amp.md file.

5.1 Grammar

message = "---\n" headers "---\n" body "---\n" "EOM\n"
headers = *(key ": " value "\n")
body    = *UTF-8  (may be empty)

Every message begins with ---\n, the header block ends with ---\n, the body continues until ---\nEOM\n (on a stream) or until EOF (in a file or single-message context where ---\nEOM\n may be omitted).

Why ---\nEOM\n and not just ---\n? AMP bodies are often markdown. Markdown horizontal rules (--- on their own line) are common in real content. A single ---\n delimiter would collide with any markdown body containing a horizontal rule. The two-line sequence ---\nEOM\n is unambiguous — a --- line in the body is safe; only --- immediately followed by EOM on the next line terminates the message.

5.2 Stream Framing

On a persistent connection (WebSocket, Unix socket), messages are concatenated:

---\n headers ---\n body ---\nEOM\n ---\n headers ---\n body ---\nEOM\n ...

The parser state machine:

1. Read until ---\n → start of a new message
2. Read lines until the next ---\n → these are headers
3. Enter body mode. Read lines until ---\n appears: a. Peek at the next line — if it is EOM, yield the complete message b. Otherwise, the --- is body content (e.g., a markdown horizontal rule); continue reading body
4. After yielding, return to step 1

Empty message (heartbeat/ACK) on the wire:

---\n---\n---\nEOM\n

That is: opening ---, empty header block closed by ---, empty body closed by ---\nEOM\n. Three --- lines plus EOM.

Single-message context. When parsing a single message from a file or a WebSocket text frame, the trailing ---\nEOM\n may be absent. The parser treats EOF as an implicit end-of-message. The ---\nEOM\n terminator is required only on persistent streams where multiple messages are concatenated.

Resync on error: If the parser loses state (partial read, corrupted bytes), scan forward for \nEOM\n and resume at the next ---\n after it. This is impossible with length-prefixed framing — a corrupted length field means every subsequent message is misaligned.

5.3 The Four Shapes

One format, one parser, four message shapes:

All four are delimited by --- and parsed identically.

5.4 Format Examples

Shape 1 — Full message (headers + body):

---
amp: 1
type: event
id: 0192b3a4-7c8d-0123-4567-890abcdef012
from: maild.cosmix.cachyos.amp
command: posted
---
# Status posted
Content: **Hello from the mesh!**
Visibility: public
URL: `https://mastodon.social/@user/123456`

Shape 2 — Command (headers only):

---
amp: 1
type: request
id: 0192b3a4-5e6f-7890-abcd-ef1234567890
from: script.cosmix.cachyos.amp
to: cosmix-mail.cosmix.cachyos.amp
command: status
ttl: 30
---

Shape 3 — Command with args:

---
amp: 1
type: request
id: 0192b3a4-5e6f-7890-abcd-ef1234567891
from: script.cosmix.cachyos.amp
to: maild.cosmix.cachyos.amp
command: email.query
args: {"filter": {"text": "invoice"}, "limit": 10}
ttl: 30
---

Shape 4 — Data (minimal envelope):

---
json: {"level": 0.72, "peak": 0.91, "channel": "left"}
---

Shape 5 — Response with structured body:

---
amp: 1
type: response
reply-to: 0192b3a4-5e6f-7890-abcd-ef1234567890
from: cosmix-mail.cosmix.cachyos.amp
command: status
---
{"unread": 3, "total": 1247, "folders": ["inbox", "sent", "drafts"]}

Shape 6 — Error response:

---
amp: 1
type: response
reply-to: 0192b3a4-5e6f-7890-abcd-ef1234567890
from: maild.cosmix.cachyos.amp
command: email.query
rc: 10
error: Account not found
---

Empty message (heartbeat/ACK):

---
---
---
EOM

5.5 Header Fields

* Required for full messages and commands. Data-only messages (json: shape) may omit routing headers when the transport already provides context — i.e., on an established WebSocket session where from: is implied by the connection identity and to: is implied by the subscription or session context. The hub does not route json:-only messages; they are point-to-point on an existing connection. If a data message needs routing, add from: and to: headers.

5.6 Return Codes

Following the ARexx convention:

Return codes appear in the rc: header of response messages. Absence of rc: implies success (rc=0).

5.7 Standard Commands

Every AMP service SHOULD support these commands:

Services extend this vocabulary with domain-specific commands (e.g., account.list, email.query for maild; share.list, peer.add for syncd). See 02_amp-command-vocabulary.md for naming conventions.

6. Parsing

Headers are flat key: value strings — no YAML parser needed. Two keys (args and json) carry inline JSON, decoded with serde_json. The parser is identical for all shapes and all transports.

6.1 Rust Reference Parser

use std::collections::HashMap;

pub struct AmpMessage<'a> {
    pub headers: HashMap<&'a str, &'a str>,
    pub body: &'a str,
}

pub fn amp_parse(raw: &str) -> AmpMessage<'_> {
    let content = raw.strip_prefix("---\n").unwrap_or(raw);
    let (fm, body) = content.split_once("\n---\n").unwrap_or((content, ""));
    let mut headers = HashMap::new();
    for line in fm.lines() {
        if let Some((k, v)) = line.split_once(": ") {
            headers.insert(k.trim(), v.trim());
        }
    }
    AmpMessage { headers, body }
}

pub fn amp_serialize(headers: &[(&str, &str)], body: &str) -> String {
    let mut out = String::from("---\n");
    for (k, v) in headers {
        out.push_str(k);
        out.push_str(": ");
        out.push_str(v);
        out.push('\n');
    }
    out.push_str("---\n");
    if !body.is_empty() {
        out.push_str(body);
        if !body.ends_with('\n') {
            out.push('\n');
        }
    }
    out.push_str("---\nEOM\n");
    out
}

6.2 Mix AMP Keywords

Mix scripts don't parse AMP manually — the interpreter has native AMP keywords:

-- Send a command to a service via the hub
send "maild" "account.list"

-- Address a service for multiple commands
address "deskd"
  send "ui.panel" id="main" title="Hello" body="# Welcome"
  send "ui.style" target="main" bg="#1a1a2e"

-- Emit an event (publish to any subscribers)
emit "status" command="updated" body="System healthy"

Under the hood, send "maild" "account.list" generates:

---
command: account.list
to: maild
from: script
---

The hub routes the message, and the response arrives as the return value of send.

6.3 Stream Parser (Rust, async)

For persistent connections, a streaming parser that yields messages as they arrive. The key invariant: a --- line in the body is only an end-of-message marker when the next line is EOM.

use tokio::io::{AsyncBufReadExt, BufReader};

pub async fn amp_stream<R: tokio::io::AsyncRead + Unpin>(
    reader: R,
) -> impl futures::Stream<Item = String> {
    let mut lines = BufReader::new(reader).lines();
    async_stream::stream! {
        let mut buf = String::new();
        let mut in_message = false;
        let mut in_body = false;
        let mut pending_sep = false; // saw `---` in body, waiting for next line

        while let Ok(Some(line)) = lines.next_line().await {
            if pending_sep {
                pending_sep = false;
                if line == "EOM" {
                    // End of message — yield and reset
                    yield buf.clone();
                    in_message = false;
                    in_body = false;
                    buf.clear();
                    continue;
                }
                // The `---` was body content (e.g. markdown horizontal rule)
                buf.push_str("---\n");
                buf.push_str(&line);
                buf.push('\n');
                continue;
            }

            if line == "---" {
                if !in_message {
                    in_message = true;
                    in_body = false;
                    buf.clear();
                    buf.push_str("---\n");
                } else if !in_body {
                    in_body = true;
                    buf.push_str("---\n");
                } else {
                    // In body — might be end-of-message or body content
                    pending_sep = true;
                }
            } else if in_message {
                buf.push_str(&line);
                buf.push('\n');
            }
        }
        // Yield trailing message on EOF (single-message context)
        if in_message && !buf.is_empty() {
            yield buf;
        }
    }
}

7. The Cosmix Stack

Every component in the cosmix stack speaks AMP natively. The hub (cosmix-noded) is the central router — all services connect to it via WebSocket and exchange AMP messages through it.

7.1 Component Map

7.2 Desktop Apps (AMP Display Protocol)

Desktop applications are Mix scripts that send ui.panel commands to cosmix-deskd via the hub. The display service renders markdown + widget properties into native UI (winit + wgpu + taffy). User interactions flow back as AMP events:

-- dopus.mix — dual-pane file manager
emit "display" ui.panel id="dopus" title="Directory Opus" width=1200 height=800 body=<<MD
```splitpane id=main direction=horizontal split=0.4
## Left Pane
| Name | Size |
|------|------|
| Documents/ | — |
| Pictures/ | — |
---
## Right Pane
| Name | Size |
|------|------|
| report.pdf | 4.2 KB |

on ui.event -- handle file selection, navigation, etc. done

The app owns all state. The display service is stateless — it draws what it
receives and reports interactions. See `05_amp-display-protocol.md` for the
full protocol specification.

### 7.3 Mix Scripting (the ARexx experience)

```mix
-- mail-summary.mix
$status = send "maild" "account.list"
$accounts = from_json($status)

each $accounts as $acct do
  say $acct.email .. ": " .. $acct.unread .. " unread"
done

Under the hood, send "maild" "account.list" generates:

---
command: account.list
to: maild
from: script
---

The hub routes the message to the maild service, which responds:

---
command: account.list
rc: 0
---
[{"email": "mark@example.com", "unread": 3}]

7.4 Web API (cosmix-webd)

cosmix-webd serves HTTP and WebSocket endpoints, bridging browser clients to the AMP mesh:

Browser → WebSocket → cosmix-webd → hub → target service

The same AMP commands accessible from Mix scripts and desktop apps are available to authenticated browser sessions.

7.5 Mail (cosmix-maild)

cosmix-maild is a complete JMAP (RFC 8620/8621) + SMTP mail server in a single Rust binary. It registers on the hub and exposes mail operations as AMP commands:

---
command: email.query
to: maild
args: {"filter": {"text": "invoice"}, "limit": 10}
---

7.6 Mesh (cosmix-noded + WireGuard)

cosmix-noded peers with other nodes over WireGuard WebSocket connections, forwarding AMP messages between meshes:

Mix script → hub (local noded) → WireGuard WS → remote noded → remote service

The message is AMP the entire way. No format translation at any boundary.

8. Transport Layers

Transport is an implementation detail — callers address services, not transports. AMP separates two planes:

• Control plane (AMP) — commands, events, heartbeats, discovery, text data
• Data plane (WebRTC) — binary streams: audio, video, screen share, file transfer

Applications never see postcard. The postcard binary protocol exists only at the compositor↔shell boundary for latency-critical paths (60-165Hz pointer events, frame callbacks). All application-facing communication uses AMP. See 00_index.md §Three Protocols for the full topology.

8.1 Control Plane

Local path (hot path for scripting):

Mix script → hub WS → AMP route → service WS → command handler → AMP response

Mesh path (cross-node):

Mix script → hub → WireGuard WS → remote hub → remote service

Browser path (web access):

Browser → webd WS → AMP frame → hub → service → AMP response → webd WS → browser

8.2 Data Plane (WebRTC)

Binary streams use WebRTC data channels, negotiated via AMP signalling on the control plane:

Signalling flow — WebRTC connections bootstrap over the existing AMP WebSocket:

1. Browser sends AMP request: command: webrtc-offer with SDP in body
2. Server responds: SDP answer + ICE candidates in AMP response body
3. WebRTC data channel opens — binary streams flow directly
4. AMP control plane continues alongside on WebSocket

This keeps AMP clean (text-only, human-readable, debuggable) while WebRTC handles binary heavy-lifting.

9. Service Discovery and Lifecycle

9.1 Service Registration

When a service starts, it connects to the hub (cosmix-noded) via WebSocket and sends a hub.register message declaring its name and capabilities:

---
command: hub.register
args: {"name": "maild", "version": "0.1.0"}
---

The hub adds the service to its routing table. All subsequent messages addressed to that service name are forwarded over the WebSocket connection.

9.2 Service Heartbeat

The hub sends periodic hub.ping messages. Services must respond within the configured timeout or be deregistered:

---
command: hub.ping
---

Response:

---
command: hub.ping
rc: 0
---

9.3 Service Discovery by Scripts

-- List all registered services
$services = send "hub" "hub.list"
say $services

-- Send to a specific service
$result = send "maild" "account.list"

9.4 Mesh Service Discovery

When cosmix-noded peers with a remote node over WireGuard, it exchanges service lists. Remote services are addressable by node name:

-- Local service (hub routes locally)
$status = send "maild" "account.list"

-- Remote service (hub routes via mesh)
$status = send "maild@mko" "account.list"

10. The Mesh

10.1 Nodes

All nodes connected via WireGuard mesh. All services are Rust single binaries managed by systemd. All mesh services bind to WireGuard IPs only (172.16.2.x), never 0.0.0.0.

10.2 Node Tiers

Mesh nodes run cosmix-noded and route traffic for browser clients. A browser connects to cosmix-webd which bridges to the hub. The WireGuard /24 subnet is the trust domain — no per-message auth within the mesh.

10.3 Mesh Heartbeat

cosmix-noded exchanges heartbeat AMP messages between peered nodes:

---
command: hub.ping
from: noded
---

Response includes service list and capabilities for fleet discovery.

11. Security

11.1 Transport Security

11.2 Service ACLs

The WireGuard /24 subnet is the trust domain. All services within the mesh trust each other implicitly — the WG key exchange is the authentication. Per-service ACLs are a future extension for when the mesh grows beyond a single-operator deployment.

11.3 No Secrets in AMP

AMP messages are designed to be loggable and debuggable. Secrets (API keys, tokens, passwords) must NEVER appear in AMP headers or bodies. Use reference tokens or session IDs instead.

12. Design Rationale

12.1 Why --- Frontmatter, Not JSON

The 5-byte overhead per message buys human readability, AI comprehension, and markdown bodies. For high-throughput data streams, the json: shape is nearly as compact as raw JSON with framing included.

12.2 Why Flat Headers, Not YAML

YAML parsing is complex, error-prone, and has well-documented security issues (billion laughs, type coercion, anchors). AMP headers look like YAML but are intentionally restricted to flat key: value — no indentation, no nesting, no type coercion. A correct AMP header parser is ~15 lines of code in any language.

12.3 Why args as Inline JSON

Command arguments need structure (nested objects, arrays, typed values). Headers need flatness (one line per field). Inline JSON in the args: field gives both: the header line is flat, the value is structured. Both Rust (serde_json) and Mix (from_json/to_json builtins) parse JSON natively.

12.4 Why Not MCP/JSON-RPC

MCP (Model Context Protocol) is purpose-built for AI tool calling. AMP is purpose-built for app-to-app orchestration where AI agents are first-class participants but not the only participants. Key differences:

• MCP requires tool definitions (JSON schemas) upfront. AMP ports are self-describing via HELP.
• MCP messages are opaque to humans without tooling. AMP messages are cat-able.
• MCP is request-response only. AMP supports events, streams, and broadcasts.
• MCP has no addressing model. AMP has DNS-native mesh addressing.

AMP and MCP can coexist: a cosmix MCP server can bridge AI tool calls to AMP port commands.

13. What Exists Today (as of 2026-04-18)

13.1 Working

13.2 In Progress

13.3 Planned

14. Architecture Layers

AMP is the foundation layer — every cosmix component speaks it. The full stack mapping (from Amiga ROM to Intuition-equivalent desktop) is defined in 00_index.md, which is the authoritative reference for how the layers compose and the phasing roadmap for building them.

15. Technical Decisions Summary

Document created: 2026-03-09, rewritten 2026-04-18 Status: Protocol specification v0.5 — active development Supersedes: AMP v0.4 (2026-03-09), v0.3 (2026-03-02)

AMP Standard Command Vocabulary

This chapter defines how AMP commands are named, what universal commands every service must implement, and how scripts discover a service's capabilities. It is the naming-convention reference for the entire stack — every command in every chapter follows these rules.

1. Command Naming Convention

<service>.<verb>[-<noun>]

• service — the hub registration name (maild, syncd, deskd, hub)
• verb — what to do (get, set, open, list, close)
• noun — optional target within the service (path, content, status)

Rules:

• Hyphen-separated for multi-word nouns: get-content, not getContent
• Lowercase only. No underscores in command names.
• Verbs are drawn from the standard vocabulary (§2) where possible
• Service-specific verbs are permitted when standard verbs don't fit
• The service prefix is required in all commands. account.list is correct; list-accounts is wrong.

Examples:

Note on display commands: Commands prefixed ui.* and menu.* are display-surface introspection commands handled by the display service. They follow the same naming convention but are specified in 05_amp-display-protocol.md §3.11 rather than here.

2. Standard Verb Vocabulary

These verbs have consistent semantics across all cosmix services. Use them before inventing service-specific verbs.

Content verbs

Lifecycle verbs

Mutation verbs

When standard verbs don't fit: use a domain-specific verb and document it in the service's command reference. Example: syncd.conflict.resolve uses resolve because none of the standard verbs capture the semantics of conflict resolution.

3. Universal Service Commands

Every AMP service SHOULD support these commands. They are the minimum surface that enables ARexx-style discovery and scripting. Chapter 01 §5.7 introduces these; this section provides full signatures.

Notes:

• HELP is the discovery entry point. Scripts call HELP first to learn what a service can do. The response is a JSON array of command descriptors.
• INFO provides metadata for fleet inventory and version tracking.
• QUIT requests graceful shutdown. The service should clean up, flush state, and disconnect from the hub. systemd will restart it if configured to.
• ACTIVATE, OPEN, SAVE, SAVEAS, CLOSE from Chapter 01 §5.7 are optional — they apply to services with a user-visible surface (display panels) but not to headless daemons.

4. Hub Commands

The hub (cosmix-noded) exposes its own command surface for service management and mesh discovery.

Topic broker commands (topic.*) are specified in 03_amp-topic-pubsub.md — they are hub extensions, not universal service commands.

5. Return Code Conventions

AMP return codes follow the ARexx convention. See Chapter 01 §5.6 for the authoritative definition:

Absence of rc: in a response implies rc: 0.

6. Extension Guidance

When adding commands to a new or existing service:

1. Name it correctly. service.verb-noun form, standard verbs first.
2. Document it in HELP. Every command must appear in the service's HELP response with a description and expected args.
3. Use standard return codes. Don't invent new codes; the 0/5/10/20 range is sufficient.
4. Args are JSON objects. Use args: header for command parameters, not positional encoding.
5. Bodies are for content. Structured data goes in args: or json:. Bodies are for markdown, prose, or large payloads.
6. Don't duplicate display commands. If your service needs widget introspection, those commands are in 05_amp-display-protocol.md §3.11. Don't reinvent ui.list or ui.get.

Document created: 2026-03-29, rewritten 2026-04-18 Supersedes: AMP Command Vocabulary v0.1 (partial command registry)

AMP Topic Pub/Sub

This document introduces a topic pub/sub primitive in the hub (cosmix-noded) and the amendments to 05_amp-display-protocol.md required to support it. The primitive enables reactive dashboards where a producer publishes state once and zero-or-more viewers receive current and future updates. The motivating use case is sysmon.mix auto-refreshing without a per-viewer process.

The design follows the MQTT retained-message and NATS JetStream KV watcher patterns, both of which have run the same "named channel with cached latest value replayed on subscribe" semantics in production for years. This is not a novel primitive; it is a deliberate reimplementation of a well-understood one in AMP framing.

1. Summary of changes

All new behavior is additive. A renderer or process that implements only the pre-delta spec remains conformant; it simply cannot participate in topic pub/sub.

2. Amendments to existing sections

2.1 Amendment to § 0.3 — Design Principles

Append to Principle 6 ("Process owns state, display owns pixels"), after the sentence "The hub routes messages between them but owns no application state.":

The hub MAY cache opaque topic payloads (§ 3.11) as a routing optimization. Such a cache holds the verbatim bytes of the most recent publish per topic and is used solely to replay the latest value to new subscribers. The hub never parses, interprets, or diffs these payloads. This is the routing-buffer analogue of MQTT retained messages: bytes in, bytes out, addressed by topic name. It is not application state because the hub has no view into what the bytes mean — it cannot answer any question about them beyond "did one exist, and if so, what were its bytes."

Rationale: without this clarification, a strict reading of Principle 6 forbids any form of replay cache in the hub, forcing pub/sub to be implemented as a separate daemon or via a producer-pull model that breaks the "fresh subscriber sees current state immediately" property. The opacity constraint preserves the principle's intent (hub can't reason about app data) while admitting a 25-year-old industry pattern.

2.2 Amendment to § 0.4 — State Ownership

In the responsibility table, modify the Hub column of the Panel registry row from:

Tracks which panel IDs exist (for routing, wildcards, orphan detection)

to:

Tracks which panel IDs exist (for routing, wildcards, orphan detection). MAY additionally maintain an opaque topic snapshot cache (§ 3.11) keyed by topic name. Cached payloads are treated as bytes, not application state.

No other rows change.

2.3 Amendment to § 3.1 — ui.panel

Insert a new row in the Optional headers (behavior) table, after the collect_values row:

Add a new sub-section 3.1.2 subscribe header lifecycle after the grid layout sub-section:

When a ui.panel message includes the subscribe header, the display service establishes a topic binding for the panel. The binding lives for the lifetime of the panel and is managed entirely by the display service — the process owning the panel does not need to issue explicit topic.subscribe / topic.unsubscribe calls.

On panel creation (first ui.panel with a given id): - If subscribe is present and non-empty, the display service issues topic.subscribe name=<value> to the hub. - If subscribe is present and empty, it is treated as absent — no subscription. - If subscribe is absent, no subscription is created.

On panel update (subsequent ui.panel with an existing id): - If subscribe is absent, the existing binding (if any) is preserved. This matches the general ui.panel update rule that absent headers preserve stored values. - If subscribe is present and equals the current binding, no action. - If subscribe is present and differs from the current binding (including transition from unbound to bound), the display service MUST atomically: issue topic.unsubscribe for the old binding (if any), issue topic.subscribe for the new binding, and update the stored binding. The swap MUST be atomic from the perspective of subsequent topic deliveries — no delivery on the old binding may arrive after the new subscription is established. - If subscribe is present and empty, the existing binding (if any) is removed: issue topic.unsubscribe, clear the stored binding. This is the ui.panel "empty string clears header" rule applied to subscriptions.

On panel removal (ui.remove, orphan timeout, or TTL expiry), the display service MUST issue topic.unsubscribe for any active binding before removing the panel.

The subscribe header is purely sugar over the topic.subscribe / topic.unsubscribe commands in § 3.11. A process MAY issue those commands directly instead of (or in addition to) using the header.

2.4 Amendment to § 10.3 — Orphan Handling

Append a new sub-section 10.3.1 Topic snapshot lifetime after the orphan handling bullets:

Topic snapshots (§ 3.11) are tied to producer presence with a grace period matching the panel orphan timeout:

• When a peer that has published to topic T disconnects, the hub marks the snapshot for T as stale. Subsequent subscribers receive the stale snapshot with a topic_stale: true header on the first delivery (see § 3.11).
• If the same peer reconnects (identified by registered service name) and publishes to T before the orphan timeout elapses, the stale flag is cleared. Brief producer restarts are invisible to subscribers.
• If the orphan timeout elapses without a new publish, the hub MAY purge the snapshot. New subscribers after purge receive no replay; they see only future publishes (if any).
• Anonymous publishers (no registered service name) cannot be matched across reconnects. Their snapshots are considered stale the instant the publishing connection closes and are purged at the next orphan-timeout sweep.

The default orphan timeout from § 10.3 (60 seconds) applies unchanged. Implementations MAY expose a separate topic-snapshot-TTL configuration knob but SHOULD default it to the orphan timeout for consistency.

2.5 Amendment to § 14 — Conformance Levels

Append a new sub-section 14.4 Hub extensions after § 14.3:

The topic.* command family (§ 3.11) is a hub extension and does not affect renderer conformance levels. A renderer is unaware of the broker: it sees only messages that arrive through normal routing, regardless of whether those messages originated from a direct send or from a broker fan-out. The single renderer-facing feature is the subscribe header on ui.panel (§ 3.1.2), which a renderer MAY implement at any conformance level. A renderer that does not implement the subscribe header MUST ignore it (per the general "ignore unknown headers" rule) — panels continue to render, they simply do not auto-update from a topic.

A hub implementation either supports topic.* or it does not. A hub that does not support topic.* MUST respond to topic.* commands with RC 10 and the error body {"error": "topic_not_supported"}. Processes detect broker availability by reading the extensions field of the hub.ping response (§ 2.6) — capability discovery belongs in the handshake, not in the operation. A process that cannot reach the hub at all receives no response; a process that reaches a hub without broker support sees extensions.topic absent from the ping response and SHOULD NOT issue topic.* commands.

No changes to § 14.1 levels table or § 14.2 renderer classification.

2.6 Amendment to hub.ping — Capability advertisement

hub.ping is a pre-existing hub-internal command used for liveness checks and handshake timing. It is not defined in the display protocol spec proper because it operates below the ui.* layer, but its response shape is observable to any process that issues it. This amendment adds a single field to the hub.ping response body without changing its headers or semantics.

Change: The hub.ping response body, previously empty or containing implementation-defined liveness metadata, MUST now include an extensions map describing the hub's supported command families and their versions.

Response body addition:

{
  "extensions": {
    "core": "1.0",
    "topic": "1.0"
  }
}

Semantics:

• core is always present and carries the hub's implemented version of the AMP display protocol spec (§ 0.1). v1 hubs report "1.0".
• Each additional key names a hub extension and carries its version string. topic is the first such extension; future extensions (stream, presence, etc.) will appear alongside it.
• Versions are independent per extension. A hub MAY support core: 1.0 and topic: 1.1 simultaneously. Clients SHOULD compare versions via semver semantics.
• An extension's absence means the hub does not implement it. Clients MUST NOT assume an extension exists; they MUST check before issuing commands from that extension.
• Additional keys beyond extensions MAY appear in the ping response for implementation-defined liveness data (latency hints, peer counts, etc.). Clients MUST ignore unknown keys per the general "ignore unknown headers/fields" rule.

Backwards compatibility: The extensions field is strictly additive. Pre-delta hubs that return an empty or implementation-defined body continue to work with clients that don't look at extensions. Clients that do look for extensions and find it absent MUST treat this as "core only, no extensions" — the safe-degradation default.

Rationale: Capability discovery via error-on-use (call topic.list, check for RC 10) is the kind of pattern that accretes startup-latency debugging cost as the extension set grows. Discovery belongs in the handshake. Versioning per-extension rather than a single monolithic spec version lets topic.* evolve independently of the core ui. protocol — important because the broker is likely to grow features (federation, claim-producer, wildcards) on a faster cadence than the stable ui. surface.

3. New § 3.11 — topic.* — Hub Topic Broker

The topic.* command family is a hub extension that provides named data channels with cached-latest semantics. It is separate from the ui.subscribe / ui.unsubscribe commands in §§ 3.9–3.10, which route filtered ui.event messages for behavior attachment. Topics carry arbitrary payloads, most commonly ui.batch messages for reactive panel updates; event filters carry structured events for script handlers.

3.11.1 Concepts

A topic is a flat string name identifying a data channel. Names are free-form UTF-8 with the exception that names beginning with $ are reserved for hub-internal use (e.g. $stats.publish_rate, $peers); publishes to reserved names from non-broker peers MUST be rejected with RC 10.

A snapshot is the most recent published payload for a topic, cached by the hub. Caching is latest-wins: each publish replaces the previous snapshot. Snapshots are opaque to the broker — the hub stores bytes and forwards bytes.

A subscription is a (topic name, subscriber peer) pair registered in the hub. When a topic is published to, the hub fans out the payload to every current subscriber. When a peer subscribes, the hub immediately replays the cached snapshot (if one exists).

A sequence number is a monotonically increasing per-topic u64 counter, incremented on each publish and attached to every delivery as the topic_seq header. Subscribers use it for gap detection and debugging multi-producer races.

Reserved header names. The broker injects the following headers into each delivery. Producers SHOULD NOT include these headers in publish payloads; if present, the broker silently overwrites them (RC 0, no error). Future versions MAY tighten this to outright rejection.

Per § 1.2, header names are case-sensitive and lowercase with underscores. The reservation covers only the exact lowercase forms listed above; mixed-case variants (Topic, TOPIC_SEQ) are not valid AMP headers at all and are rejected by the wire format itself. The broker MUST overwrite any reserved header present in an incoming publish payload. Future versions MAY tighten this to outright rejection (RC 10) if pre-seeding turns out to be a vector for anything.

Anonymous publisher identity. Processes that connect to the hub without registering a service name (the default for Mix scripts using connect_anonymous) are assigned a synthesized, connection-scoped identity at WebSocket establishment time:

anon-<hex_nonce>-<unix_seconds>

Example: anon-a4f8c2e1-1744243200. The hex nonce is a random u32 preventing collision among concurrent anonymous connections; the Unix timestamp makes log-grepping a dead producer trivial. This identity is stored in the peer record alongside the outbound channel and used as the last_publisher value for any TopicEntry the peer publishes to. It is visible in topic.list responses and in hub.tap stream frames.

Synthesized identities are hub-local: they are valid only on the hub that minted them, MUST NOT be federated across mesh bridges, and MUST NOT be persisted across hub restarts. A client that disconnects and reconnects receives a fresh identity; the hub treats the new connection as an unrelated publisher. Snapshot cleanup on disconnect proceeds through the existing reverse index — the synthesized identity is the key.

With this identity in place, topic.active / topic.idle notifications (§ 3.11.8) work for the full lifetime of a long-running anonymous producer. Notifications addressed to a dead connection's identity are dropped at the routing layer, not misdelivered to a later anonymous connection — the nonce makes cross-connection collisions impossible by construction.

3.11.2 topic.publish — Publish a snapshot

Replaces the topic's cached snapshot and fans the payload out to all current subscribers.

Direction: Process → hub Type: request (expects RC response)

Required headers:

Optional headers:

Body: A complete, serialized AMP message (including its own --- header frame but without a trailing ---\nEOM\n terminator). The broker treats the body as opaque bytes. The most common payload is a ui.batch message (§ 3.8) carrying ui.update / ui.data sub-messages, but the body MAY be any AMP message.

Nesting constraint: The inner AMP message's body MUST NOT contain the sequence ---\nEOM\n, which would be interpreted as the outer message's terminator by the stream parser (01_amp-wire-protocol.md §5.2). In practice this means topic.publish payloads cannot themselves nest further AMP messages — nesting depth is limited to one level. This is sufficient for all v1 use cases (ui.batch bodies are JSON, not nested AMP).

Maximum payload size: 1 MiB (provisional). This bounds worst-case per-peer buffer memory: 256 (channel capacity) × 1 MiB = 256 MiB per slow subscriber. In practice, ui.batch payloads for reactive dashboards are well under 100 KiB. The limit may be tightened in future versions based on production data. Publishes exceeding this limit are rejected with RC 10 and an error body of {"error": "payload_too_large", "limit": 1048576}.

Response: RC 0 with {"seq": N, "delivered": M} where N is the new sequence number for this topic and M is the number of subscribers the payload was fanned out to. On error, RC 10 with {"error": "..."}.

Fan-out semantics: The broker parses the outer topic.publish wrapper, extracts the body (which is itself an AMP message), injects two routing headers into the inner message — topic: <name> and topic_seq: <seq> — and additionally topic_stale: true if the producer was marked stale per § 10.3.1. The annotated inner message is then sent to each subscriber through normal per-peer routing. The broker does NOT introduce a new command type; subscribers see the inner message's original command header (typically ui.batch) and dispatch through their existing handlers. The annotated inner message becomes the new cached snapshot (if retain is true).

retain: false edge cases. When retain is false and no subscribers exist, the publish is a no-op: the payload is neither cached nor delivered anywhere. The response still returns RC 0 with {"seq": N, "delivered": 0} so producers can detect the condition if they care. The sequence number is incremented on every publish regardless of retain — it counts publishes, not snapshots — so subscribers that join mid-stream and see a mix of retained and non-retained publishes can still use topic_seq for gap detection without special-casing retention state.

Join-after-non-retained publish: A subscriber that joins after the most recent publish was retain: false receives the most recent retained snapshot (if one exists), with its original topic_seq. If no retained snapshot exists, no replay occurs and the subscribe response returns seq: 0. The gap between the replayed snapshot's seq and the next delivery's seq reflects the non-retained publishes that occurred in between — this is expected and not an error condition.

Header injection is a security property, not an implementation convenience. The broker MUST inject the routing headers (topic, topic_seq, topic_stale, topic_op) after accepting the publish and allocating the sequence number — never by passing through producer-supplied values. A producer MUST NOT pre-seed these headers to influence ordering, staleness, or delivery framing; any such headers present in the incoming inner message are unconditionally overwritten by the broker's values. This matters today for debugging (a producer cannot fake sequence gaps to confuse gap-detection tooling) and matters tomorrow for cross-mesh federation (a peer on a federated topic cannot spoof sequence numbers to cause subscribers on other meshes to skip messages). Implementations MUST treat producer-supplied routing headers as adversarial input even though the v1 trust domain (WireGuard /24, 05_amp-display-protocol.md § 15.1) does not assume an active attacker — the property costs nothing to enforce and is load-bearing for future versions.

Example:

---
command: topic.publish
name: sysmon.metrics
---
---
command: ui.batch
---
[
  {"command": "ui.update", "headers": {"target": "sysmon"}, "body": "# cachyos\n\n**Load:** 0.88 0.93 0.90"},
  {"command": "ui.data", "headers": {"target": "proc-table"}, "body": "[{\"id\":\"1\",\"pid\":\"1234\",\"name\":\"cosmix-indexd\",\"cpu\":\"12.3\",\"mem\":\"4.1\",\"state\":\"S\"}]"},
  {"command": "ui.data", "headers": {"target": "disk-table"}, "body": "[]"}
---
EOM

Note: the inner message (ui.batch) does NOT have its own ---\nEOM\n terminator — the outer message's ---\nEOM\n terminates the entire publish. The inner --- delimiters (header frame) are body content of the outer message.

A subscriber of sysmon.metrics will receive the inner message with routing headers injected:

---
command: ui.batch
topic: sysmon.metrics
topic_seq: 42
---
[ ... same JSON body ... ]
---
EOM

The delivered message is a standalone AMP message (with its own ---\nEOM\n terminator) and dispatches through the existing ui.batch handler unchanged.

3.11.3 topic.subscribe — Subscribe to a topic

Registers the calling peer as a subscriber to the named topic. If a snapshot exists, the hub replays it to the caller immediately as a normal fan-out delivery (same format as § 3.11.2).

Direction: Process → hub Type: request

Required headers:

Body: empty.

Response: RC 0 with {"subscription_id": "...", "replayed": bool, "seq": N}. replayed is true if the caller received a snapshot replay; seq is the sequence number of the replayed snapshot, or 0 if none existed. On error (reserved-name violation, etc.), RC 10.

The subscription_id is a diagnostic token for logging and tooling (hub.tap stream frames include it). It has no operational use in v1 — subscribers do not need to reference it in subsequent commands. Future versions may use it for subscription-scoped features (e.g., delivery limits, per-subscription filters).

Idempotency: Subscriptions are keyed by (peer, topic). A peer that subscribes to a topic it is already subscribed to receives the existing subscription_id and no duplicate delivery is fanned out on subsequent publishes. The operation is idempotent. This matches the implicit assumption in § 3.1.2 that a ui.panel update with an unchanged subscribe header is a no-op, and collapses the ambiguity in subscriber_count — the returned value unambiguously counts distinct peers, not subscription records.

3.11.4 topic.unsubscribe — Unsubscribe from a topic

Removes the caller's subscription to the named topic.

Direction: Process → hub Type: request

Required headers:

Body: empty.

Response: RC 0. A peer that unsubscribes from a topic it was not subscribed to still receives RC 0 (idempotent).

3.11.5 topic.subscriber_count — Query subscriber count

Returns the number of current subscribers to a topic. Used by producers to back off when nobody is watching.

Direction: Process → hub Type: request

Required headers: command: topic.subscriber_count, name: <topic>.

Response: RC 0 with {"count": N}. Absent topics return {"count": 0}.

3.11.6 topic.list — List topics

Returns metadata for all topics currently known to the broker. Intended for debugging and tooling.

Direction: Process → hub Type: request

Required headers: command: topic.list.

Optional headers: prefix: <string> to filter by topic name prefix (simple string match, not a glob).

Response: RC 0 with a JSON array of topic records:

[
  {
    "name": "sysmon.metrics",
    "subscribers": 2,
    "has_snapshot": true,
    "snapshot_seq": 42,
    "snapshot_size": 1284,
    "last_publisher": "sysmon",
    "stale": false
  }
]

3.11.7 topic.clear — Explicit snapshot removal

Removes the cached snapshot for a topic. Used by producers at shutdown to prevent stale replay to future subscribers.

Direction: Process → hub Type: request

Required headers: command: topic.clear, name: <topic>.

Optional headers: notify (bool, default true) — if true, the broker fans out a final delivery to current subscribers with a topic_op: delete header and an empty body. If false, subscribers are not notified.

Response: RC 0. Clearing an absent topic is idempotent.

Consumer-side behavior: A subscriber receiving a delivery with topic_op: delete SHOULD treat it as "the producer has invalidated its state" but MUST NOT automatically remove any panels bound to the topic. The panel's current rendered state is preserved — the producer owns that decision, not the broker. Consumers that want to signal invalidation visually (e.g. dim the panel) may do so.

3.11.8 topic.active / topic.idle — Subscriber-count transitions (hub → producer)

These are hub-emitted notifications, not commands a process calls. The hub sends topic.active to the last-known publisher of a topic when the subscriber count transitions from 0 to >0, and topic.idle when it transitions from >0 to 0. The last-known publisher is determined by the from header of the most recent topic.publish; anonymous publishers do not receive these notifications.

Direction: Hub → process Type: notification (no response expected)

Headers: command: topic.active (or topic.idle), name: <topic>, subscribers: <N>.

Body: empty.

Producer behavior: Producers MAY ignore these messages. A producer that honors them can implement back-off: stop publishing on topic.idle, resume on topic.active. With the synthesized anonymous identity from § 3.11.1, a long-running anonymous Mix producer does receive these notifications for the full lifetime of its connection — the "anonymous producers get no notifications" limitation from the first draft of this delta no longer applies.

Racing producers are best-effort. Under the documented racing-producers caveat (§ 5), topic.active / topic.idle fire only to the single most recent publisher as tracked by TopicEntry.last_publisher. Other live publishers racing on the same topic will not be informed of subscriber-count changes and will continue publishing at full rate regardless of viewer presence. This is a deliberate v1 scope decision: tracking a set of recent publishers per topic is plumbing the racing-producer caveat itself is already asking users to avoid. Producers requiring reliable back-off under contention should wait for topic.claim_producer in a future version, at which point at most one publisher per topic is live by construction and this ambiguity disappears.

3.11.9 Error codes

Reserved future error string. When a future version tightens reserved-routing-header handling from silent overwrite to rejection (per § 3.11.2), the error body will be {"error": "reserved_header"}. Implementations MUST NOT reuse this error string for any other condition in v1, so that client-side tests asserting against the error surface remain forward-compatible.

4. Design rationale

4.1 Payload opacity and the three-reader model

The broker treats topic payloads as opaque bytes. This is the property that lets the "hub owns no application state" principle survive the amendment in § 2.1. But opacity has a second, subtler payoff specific to the AMP three-layer model (Principle 1 of § 0.3: plain text, machine-parseable, AI-comprehensible).

Because the payload is an AMP message and the broker doesn't touch it, the same bytes serve three different readers:

1. Human tailing the topic (mix sub sysmon.metrics) sees the inner AMP message in its plain-text form and can grep / read it directly.
2. Display service parses the inner message's command header and dispatches through its existing widget rendering path.
3. AI process (e.g. a Claude instance subscribed to the topic via cosmix-mcp) reads the markdown body as native LLM context and can reason about system state.

No format translation, no separate "human view" vs "machine view," no schema bridges. MQTT retained messages are opaque bytes; NATS KV values are opaque bytes; Phoenix PubSub payloads are opaque Erlang terms. None of them have this property because none of them made the protocol itself three-reader by construction. This is the ARexx message-port-as-universal-substrate design paying off, and it is worth preserving even if a future optimization (e.g. binary payloads for throughput) might seem attractive.

4.2 Why not unify topic.subscribe with ui.subscribe?

ui.subscribe (§ 3.9) filters the ui.event stream by (source_panel, action) — a structured predicate over a specific message family. topic.subscribe addresses via flat topic name — a lookup in a named channel space with cached-latest semantics. Collapsing them into one wire primitive either makes the predicate form accommodate flat names as a degenerate case (awkward), or makes the flat-name form accommodate predicates (awkward in the other direction). Phoenix reached the same split: PubSub (topic broadcast) and Presence (stateful distribution) are separate APIs because the data models differ.

The two families share an implementation registry in the hub (one subscription table, one reverse index, one disconnect-cleanup path). On the wire they are distinct because their addressing semantics are genuinely different. Spec users see two primitives with two purposes; implementers see one registry with two projections.

4.3 Why cache in the hub instead of pulling from the producer?

The alternative is: the hub stores only "who produces topic X," and on subscribe, the hub asks the producer to re-send the latest. This keeps the hub stateless but:

• Adds a round-trip on every subscribe.
• Fails when the producer is briefly offline during a viewer's reconnect.
• Cannot serve viewers that opened before any publisher was running.
• Makes the stale=true edge case impossible to detect (stale vs. never-published are indistinguishable).

MQTT and NATS both cache retained/latest values in the broker for the same reasons. The amendment in § 2.1 acknowledges this is a routing-layer buffer, not application state.

4.4 Why bounded per-peer channels?

Unbounded mpsc::Sender buffers let a slow subscriber consume memory without bound. Under normal routing this is unlikely (point-to-point messages are bursty but bounded by sender rates); under topic fan-out it is much more likely (a producer at 10 Hz multiplied across N slow subscribers). Bounded channels with drop-oldest convert an unbounded failure mode into a lost-message one. Since the topic snapshot is the source of truth, a subscriber that missed intermediate deliveries can catch up by re-reading the cache on reconnect; no data is permanently lost. MQTT QoS 0 drops on backpressure. NATS detects slow consumers and forcibly disconnects them. This plan does the latter: drop-oldest until a per-peer drop count threshold, then force-disconnect with an RC 20 "slow consumer" tap event.

5. Non-goals for v1

Each of these is additive to the wire format and can be introduced in a later version without breaking v1 consumers:

• Cross-mesh topic federation. A topic published on node A is not automatically visible on node B. Topic federation will reuse the existing mesh bridge in noded when added.
• Per-widget topic binding. The subscribe header on ui.panel binds an entire panel to one topic. Future versions may add a widget-level subscribe attribute for widgets that want to consume different topics within one panel.
• Manifest-driven producer auto-spawn. In v1, the user runs producer scripts manually. A later version may add a topic manifest in settings.toml mapping topic names to launcher commands so the hub can spawn a producer on first subscribe.
• Topic ACLs. The WireGuard /24 trust domain (05_amp-display-protocol.md § 15.1) covers v1. ACLs on topics (who may publish, who may subscribe) will be added when the first multi-tenant use case arrives.
• Versioned / append-only streams. Snapshots are latest-wins. Topics with history (event sourcing, audit logs) will be a separate primitive (stream.*, TBD) rather than a generalization of topics.
• Claim-single-producer lock. Two producers publishing to the same topic race; last-write-wins on the snapshot. The sequence number makes the race debuggable but does not prevent it. A topic.claim_producer lock may be added later.
• Wildcards in subscriptions. Subscribers name one topic. No sysmon.* wildcards in v1.
• Snapshot persistence across hub restart. Snapshots live in memory only. A hub restart clears them. Consumers re-subscribe and wait for the next publish.

6. Implementation phasing

This section is informative — it is not part of the spec but is included so implementers can scope the work.

Phase A0 — Bounded per-peer channels (hygiene) - Convert hub.rs peer outbound channels from UnboundedSender<String> to a bounded channel (capacity 256) with drop-oldest + slow-consumer disconnect. - Surface per-peer drop counters via hub.tap. - Regression-test existing routing under the new bounds. - No protocol changes.

Phase A — Broker core - New subscription.rs module in cosmix-noded with a SubscriptionBroker struct holding a single registry usable by both topic.* and the future ui.subscribe implementation. - topic.* command handlers per § 3.11. - Snapshot cache with 1 MiB cap, sequence numbers, $-prefix reservation, topic.clear support, and the stale-producer grace period from § 10.3.1. - Hub-emitted topic.active / topic.idle on subscriber-count transitions. - Stub ui.subscribe / ui.unsubscribe that write into the shared registry but return RC 5 (warning) with a body noting that event routing is not yet wired. This validates the shared-registry claim and reserves the command names. - Unit tests covering: publish/subscribe/replay, unsubscribe, disconnect cleanup, sequence monotonicity, snapshot cap, reserved-name rejection, clear + notify, stale flag transitions, multi-subscriber fan-out. - Manual verification via wsamp: no consumer code required.

Phase B — lib-display protocol types - PanelProps.subscribe: Option<String> field and parser. - No new command types required on the consumer side (the whole point of § 3.11.2's fan-out semantics).

Phase C — deskd subscription lifecycle - topic_bindings: HashMap<PanelId, String> in App. - handle_panel auto-subscribes on subscribe header per § 3.1.2. - WindowEvent::CloseRequested, ui.remove, TTL expiry, and orphan timeout all auto-unsubscribe. - Incoming ui.batch (or any command) with a topic header is dispatched normally; the topic header may optionally be used to verify the binding is still active and drop late deliveries for unbound panels.

Phase D — sysmon.mix rewrite - Extract gather logic into a function. - Open panel once with subscribe: sysmon.metrics. - Loop: build a ui.batch body, publish via topic.publish name=sysmon.metrics, sleep 2s. - Running the same script twice produces two racing producers; documented as a known v1 caveat.

7. Resolutions to initial open questions

The first draft of this delta flagged three open questions. All three are resolved in the body above; this section records the decisions and their rationales so future readers can reconstruct why the wire looks the way it does.

Header naming: kept unprefixed, reserved by name. The reserved headers topic, topic_seq, topic_stale, topic_op live in the general AMP header namespace rather than behind a prefix like x_topic_*. Resolution in § 3.11.1. Rationale: RFC 6648 retired the X- convention in HTTP precisely because it created a permanent split between "real" and "experimental" headers that outlived the experiment — once X-Forwarded-For became universal, the X- told you nothing useful and couldn't be removed without breaking the internet. AMP is young enough to learn this for free. Case-sensitivity is not a dodge: per § 1.2 headers are lowercase-with-underscores at the wire level, so Topic and TOPIC_SEQ are not valid AMP headers at all and need no separate reservation. The reservation covers only the exact lowercase forms. Future versions MAY tighten overwrite-on-collision to reject-with-RC-10 if pre-seeding turns out to be a problem vector.

Anonymous publisher identity: synthesized per connection. Anonymous publishers receive a anon-<hex_nonce>-<unix_seconds> identity at connection time. Resolution in § 3.11.1. Rationale: the "anonymous means no notifications, full stop" alternative kills the topic.active / topic.idle back-off mechanism for the 90% case (Mix scripts running for hours or days are the common producer shape), defeating the purpose of wiring it up as a no-op in v1. The connection-scoped nonce makes cross-connection misdelivery impossible by construction — a notification addressed to a dead connection's identity is dropped at the routing layer, not misrouted to a later anonymous connection that happens to connect to the same topic. Identities are hub-local by explicit mandate: they MUST NOT be federated or persisted, which keeps the failure mode "brief producer restart loses back-off context" rather than "synthesized identity somehow leaks between meshes."

Hub-extension discovery: via hub.ping extensions map. Capability discovery is advertised in the hub.ping response as a versioned extensions map ({"core": "1.0", "topic": "1.0"}). Resolution in § 2.6. Rationale: error-on-use discovery accretes startup-latency debugging cost ("why does the first publish take 80ms? oh, we're probing for broker support"). Discovery belongs in the handshake. Versioning per-extension rather than a single monolithic spec version lets topic.* evolve on a faster cadence than the stable ui.* surface — important because the broker is the place features will grow first (federation, claim-producer, wildcards). The extensions field is strictly additive to hub.ping: pre-delta hubs keep working, pre-delta clients keep working, and new clients reading a missing field fall back to "core only, no extensions" — the safe-degradation default per Principle 5 of § 0.3.

No open questions remain. Phase A0 (bounded channels in hub.rs) is cleared to start.

Mix Language Reference

Mix is a scripting language designed for systems work — filesystem operations, process management, HTTP, structured data handling — with first-class AMP mesh messaging when running in a cosmix environment. In non-cosmix environments, AMP operations (send, emit, address, on) raise a clear runtime error; the rest of the language works identically. The amp_available() builtin lets scripts detect the environment and branch when needed.

The language is defined by its reference implementation in cosmix-lib-mix. There is one interpreter, shippable standalone as mix or compiled into cosmix binaries. This chapter documents what that implementation actually accepts, not an abstract specification. When this document and the source disagree, the source wins.

Source of truth: src/crates/cosmix-lib-mix/src/{lexer,parser,ast,evaluator}.rs. Doc claims cite file.rs:line for any non-obvious behaviour.

Scope: This chapter covers the Mix language itself — syntax, operators, control flow, scoping, and patterns. The standard library (currently 115 builtins in builtins.rs) is documented inline where relevant but a comprehensive builtin reference is planned as Chapter 04a. AMP-specific keywords are documented in §AMP below; everything else is available in any environment.

Quick reference for writing Mix scripts correctly on the first try. Read this before writing new Mix code — especially if you're coming from ARexx, Lua, or shell, because Mix differs from all three in ways that are easy to get wrong.

v0.2.3 shipped — v0.2.x series complete. All six phases of the stdlib-and-ergonomics plan have landed: anonymous functions + HOF list helpers (Phases 1–2), fmt/printf (Phase 3), recursive glob/walk/path_parts (Phase 4), terminator unification — end everywhere (Phase 5), and JSONL helpers read_lines/read_json/ read_jsonl (Phase 6). Deferred to v0.3: destructuring assignment, lexical closures converging named-and-anonymous semantics, catchable exit, two-registry HOF unification.

Quick gotcha list

Top-of-doc shortlist. If you only read this section, you'll avoid the common traps:

1. Concatenation is .. (not ||). || is the statement-chain operator (run-if-failure), same as shell. String concat in expressions uses ...
2. Command-line args are positional: $1, $2, ... (ARexx/shell style). There is no upper bound — $1 through $N for as many args as the script was invoked with. args() returns the same args as a list (use it when you need length() or iteration).
3. on blocks use on event.name (unquoted) and close with end. Example: on dbview.page ... end. on is statement-position only — it registers a global handler and is not legal inside function bodies.
4. send/emit/address are ordinary statements — they work at script top level, inside on handlers, and inside function bodies. Reuse via library helpers (e.g. src/apps/lib/ui.mix) is a style choice, not a requirement. (Earlier doc revisions claimed a top-level restriction; that was never enforced by the parser or evaluator. See evaluator.rs:1074–1088 and call_function at 1644.)
5. String interpolation does NOT recurse. If $var = "hello" and $template = "${var}", then "${template}" produces the literal string ${var}, not hello. This matters when passing complex strings through heredocs.
6. Heredoc interpolation expands ${var} eagerly — one pass only.
7. $var.field dot access in strings walks the full chain: "host: ${cfg.host}" and "timeout: ${cfg.db.opts.timeout}" both resolve identically to their expression-position counterparts ($cfg.host, $cfg.db.opts.timeout). Each step honours the Value::Map * fallback. Mid-chain non-map values yield nil. (Shipped in Phase 0 of v0.2.0; earlier v0.1.0 revisions only honoured the first dot.)
8. Comparison operators have asymmetric coercion. ==/!= cross-type-coerce string↔number via parse-as-f64 (value.rs:79–96), so "5" == 5 is true. But </>/<=/>= route through num_cmp (evaluator.rs:2022) which errors on any value that doesn't parse as a number — including nil. So nil > -1 is a runtime error, not false. eq/ne are strict string comparisons with no coercion.
9. Keywords and/or for expressions, &&/|| for statement chaining. They are NOT interchangeable.
10. All blocks close with end (since v0.2.2). Legacy done/next still parse with deprecation warnings — removal planned for v0.3. See table below.
11. Event fields live in $event["headers"], not top-level $event. $event has only three keys: command, headers, body.
12. Value::Map field access falls back to the * key. $cfg.host returns the map's "*" value if "host" isn't set (evaluator.rs:1547). This is a deliberate defaults pattern — set $cfg.* = "default" and unknown lookups return that. Surprising the first time you see it.

Block terminators

v0.2.2: every block closes with end. The legacy done / next forms for while / loop / for / for each / on still parse but emit a deprecation warning to stderr. Plan to remove the legacy forms one release cycle from now (target: v0.3).

Migration: new scripts should use end universally. Existing scripts will keep working but should be migrated when next touched. A Mix script that does the line-level rewrite is in the tree:

mix _bin/mix_migrate_terminators.mix path/to/script.mix [...]

The migration script only rewrites bare done / next lines (trimmed content equals the keyword) — it won't touch keywords in strings or mid-line comments. Always run under version control so you can diff the result.

Lexical elements

Variables

• $name — identifier starting with $, then [a-zA-Z_][a-zA-Z0-9_]*
• $1..$9 — positional command-line arguments. Return nil when not provided.
• $_ — result of pipe LHS in pipe expressions
• $event — only available inside on handlers, read-only, map with command/headers/body keys
• $rc — return code from most recent AMP send statement

String literals

Single-quoted '...' — no interpolation. Escapes: \' and \\ only.

$literal = 'This is ${not} interpolated'

Double-quoted "..." — interpolation enabled.

$greeting = "Hello, ${name}!"
$cmd_output = "Today is $(date +%Y-%m-%d)"

Escapes: \n \t \r \e \" \\ \$ (\$ produces literal $, preventing interpolation).

Heredoc <<TAG ... TAG — multiline, interpolation enabled.

$body = <<MD
# Title

Content line with ${variable} interpolated.
MD

Closing tag must be on its own line, exact match. Trailing newline is removed automatically.

Comments

Both # and -- run to end of line. No block comments.

Keywords (case-sensitive)

Control: if then else end for each in to step next while done loop break continue
Functions: function return
Case: select when otherwise
Logic: and or not true false nil
Parse: parse with
AMP: send address emit on
Errors: try catch die
Env: export alias source sh
I/O: print eprint

Operators

Precedence low to high (parser.rs:908-947):

Unary: - (negation), not or ! (logical NOT).

Statement-level chain operators (NOT expression operators):

• stmt && other — run other only if $rc == 0 after stmt
• stmt || other — run other only if $rc != 0 after stmt
• stmt | external_cmd — pipe stmt stdout to external command

These are the operators that caused dbview bugs: || is run-if-failure (like shell), not concat. Use .. for string concatenation.

Statements

Assignment

$var = expression
$obj.field = value
$arr[0] = value
$obj.* = value      -- sets all fields of a map

Conditionals

if condition then
    body
else if other_cond then
    body
else
    body
end

select $value
when "a" then
    body
when "b" then
    body
otherwise
    default_body
end

Loops

for $i = 1 to 10 step 2
    print $i
next

for each $item in $list
    print $item
next

for each $i, $item in $list   -- with index
    print $i, $item
next

while $condition
    body
done

loop
    body
    break if $done
done

break [label] [if cond] and continue [label] [if cond] support optional conditions and loop labels.

Functions

function name($arg1, $arg2)
    body
    return $value
end

Expression form:

function double($x) = $x * 2

Parameters can have defaults: function greet($name, $greeting = "Hello").

Anonymous functions (v0.2.0)

function is also valid in expression position with no name, producing a first-class function value that can be stored in a variable, passed as an argument, or returned from another function. Both body forms work:

$double = function($x) = $x * 2
print $double(5)                        -- 10

$inc = function($x)
    return $x + 1
end
print $inc(4)                           -- 5

type($double) returns "function". Functions compare as never-equal (identity comparison at the Mix level is deliberately disabled — it's rarely useful and tends to encourage bugs).

Calling a function value uses the same $var(args) syntax as calling a named function, but dispatched through the value in scope rather than a bareword function name:

-- $sort_by is the function VALUE in a variable (whatever that means
-- for your script — maybe built by a factory). Dispatches via scope.
$sort_by($items, $key_fn)

Bareword calls like sort_by($items, $key_fn) still dispatch through the builtin / user-function tables as before.

Closure semantics (v0.2.0)

Two-tier rule:

Top-level lambdas (constructed at script top level) see globals live at call time. Mutating a global after capture is visible to the lambda:

$t = 5
$gt = function($x) = $x > $t
$t = 100
print $gt(50)                           -- false (uses current $t, not 5)

Inner-frame lambdas (constructed inside a named function) see a frozen snapshot of the enclosing function's frame. This is capture-by-value, taken at the moment the function(...) expression evaluates. It's how closures over a caller's parameters work:

function make_adder($n)
    return function($x) = $x + $n    -- $n captured by value
end

$plus40 = make_adder(40)
print $plus40(2)                        -- 42 (even though make_adder has returned)

The divergence between "top-level = live" and "inner-frame = frozen" is acknowledged and narrower than the v0.1.0 state (where inner lambdas saw nothing useful at all). v0.3 will converge both named and anonymous functions on a single rule; until then, inner-frame lambdas are capture-by-value and cannot observe later mutations to the captured frame.

Named functions continue to see globals live and cannot capture enclosing function locals — the captures slot is only populated for anonymous function(...) expressions.

Event handlers (on)

on hub.ping
    print "received:", $event["body"]
done

on dbview.page
    $page = to_number($event["page"])
    -- handle page change
done

• No quotes around the event name. Dotted identifiers work: dbview.page, hub.ping.
• Closes with done, not end.
• $event is a map with exactly three keys:
• $event["command"] → the full command string (e.g. "dbview.sort")
• $event["headers"] → map of AMP headers. All user-defined event fields live here (e.g. $event["headers"]["column"])
• $event["body"] → raw body string (if any)
• Event fields are in headers, not top-level. A common mistake: $event["column"] is nil. The correct access is $event["headers"]["column"], or destructure first: $h = $event["headers"] then $h["column"].
• Handlers serialize — only one runs at a time. Slow handlers block the event loop.

AMP messaging (send, emit, address)

-- Statement form
send "target" command.name arg1 arg2 key=value

-- Expression form: assign result
$result = send "hub" hub.ping

-- Fire-and-forget (no $rc)
emit "display" ui.panel id="main" body=$content

-- Multiple sends to same target
address "display"
    ui.status target="main" body="Ready"
    ui.data target="list" body=$json
end

send/emit/address are ordinary statements and work in any statement position, including inside function bodies. Wrapping them in helpers is a style choice for reuse, not a workaround for a parser restriction:

-- This is fine — define and call a helper directly.
function panel($id, $title, $body)
    emit "display" ui.panel id=$id title=$title body=$body
end

panel("main", "My Panel", $body)

Library files in src/apps/lib/ exist to share these helpers across scripts via source, not because top-level is required.

Two real constraints to remember:

• on IS statement-position only — it registers a global event handler and is not legal inside a function body. Define handlers at script top level.
• Closures do not capture enclosing function frames (v0.1.0). A function defined inside another function sees globals + its own params only — not the outer function's locals. v0.2.0 will likely add capture-by-value at construction time for inner-frame lambdas; named functions may keep live-binding lookup. Plan tracks this.

Error handling

try
    $result = risky_op()
catch $err
    print "failed:", $err
end

die "fatal: " .. $reason

Parse statement

parse "host:port" with $host ":" $port

Captures $host = "host" and $port = "port" using literal delimiters.

Source, sh, export, alias

source "path/to/lib.mix"              -- run another mix file in current scope
sh "ls -la /tmp"                       -- statement form, inherits stdio
$output = sh "ls -la /tmp"             -- expression form, captures stdout
export PATH = "/usr/local/bin:${PATH}"
alias ll = "ls -la"

Expressions

Literals

• Numbers: 42, 3.14, 1_000_000 (underscores as separators), always f64
• Strings: 'single', "double", <<HEREDOC...HEREDOC
• Booleans: true, false
• Nil: nil
• Lists: [1, 2, 3], ["a", "b"] — trailing comma allowed
• Maps: {host: "localhost", port: 8080} — keys are bare identifiers or strings, colon separator

Function calls

length($list)
sqlexec($db, $sql, [$id])
$list.length()          -- method form, desugars to length($list)
func()[0]               -- postfix chaining

Field / index access

$config.host
$config["host"]
$list[0]
$list[$i + 1]
$list[-1]                -- negative indices count from the end (v0.2.0)
$s[-1]                   -- same for strings (unicode-safe, returns a char)

Out-of-bounds index returns nil silently — index expressions never raise. Use length($xs) if you need to check bounds explicitly.

Send / sh in expression position

$info = send "hub" hub.info
$files = sh "ls /tmp"

Command substitution in strings

"today is $(date +%F)"
$result = $(whoami)

Balanced parens are tracked, so $(echo (foo)) works.

String interpolation details

Variable expansion in double-quoted strings and heredocs:

• ${name} — variable lookup
• ${cfg.host} — single-level dot access for maps
• ${cfg.db.opts.timeout} — chained dot access; walks the full path. Each step looks the field up against the current Value::Map, falling back to the * key if present (evaluator.rs Expr::InterpolatedString arm). A non-map intermediate value yields nil for the rest of the chain. Resolves identically to expression-position $cfg.db.opts.timeout.
• $(cmd) — command substitution
• \$ — literal $ (prevents interpolation)
• Undefined variables interpolate as nil

No recursive expansion. This is the trap:

$var = "hello"
$template = "${var} world"
$result = "${template}"      -- prints "${var} world", not "hello world"

Interpolation happens once at expression evaluation time. Once a string is stored in a variable, its content is literal text — even if that text contains ${...}, it won't expand when re-interpolated.

Practical implication: when building markdown bodies with JSON inside, prefer building the full string with .. concatenation over nesting variables in heredocs. The heredoc form works if all variables are simple scalars, but it's easy to forget one case and produce malformed output.

Truthiness

• Falsy: nil, false, "", 0, "0", empty list [], empty map {}
• Truthy: everything else

Command-line arguments

-- Positional (ARexx/shell style)
$cmd = $1
$arg = $2
if $1 == nil then
    print "usage: script <cmd>"
    exit(1)
end

-- Or as a list
$argv = args()
print length($argv), "arguments"

args() skips the binary name and script path — it returns just the user-provided args.

No cap on positional indexes. $1 through $N work for any N the script was invoked with. The lexer accepts $<digits> (lexer.rs:595–619) and main.rs:64 binds every script arg as (i+1).to_string(). Out-of-range positions return nil, not an error (evaluator.rs:1192–1195).

Common patterns

Building markdown for a widget with JSON content

Use .. concatenation when the value contains ${}-like characters (JSON):

$col_defs = '[{"key":"name","label":"Name"}]'
$dt = "~~~datatable id=data page_size=" .. $page_size .. " total_rows=" .. $total
$body = "# " .. $title .. "\n\n" .. $dt .. "\ncolumns: " .. $col_defs .. "\n~~~"

Loading a library

-- Resolve absolute path so scripts work from any CWD
$_cos = env("COSMIX_SRC")
if $_cos == "" then
    $_cos = env("HOME") .. "/.cos"
end
source "${_cos}/src/apps/lib/ui.mix"

Event loop keep-alive

-- At end of a GUI script, sleep forever; on handlers still fire
sleep(86400)

Functional list helpers (v0.2.0)

All 12 higher-order helpers take a function value as their last argument. Lambdas are the idiomatic source:

-- Transform
$doubled = map($xs, function($x) = $x * 2)
$odds = filter($xs, function($x) = $x % 2 == 1)
$sum = reduce($xs, 0, function($acc, $x) = $acc + $x)

-- Sort. Key function returns the sort key (number or string).
-- Descending: negate a numeric key, or build a reversed string.
$by_score_desc = sort_by($users, function($u) = 0 - $u.score)

-- Top-N: chain sort_by with slicing
$top10 = take(sort_by($users, function($u) = 0 - $u.score), 10)

-- Folds
print any($xs, function($x) = $x > 100)
print all($xs, function($x) = $x > 0)
print count($xs, function($x) = $x % 2 == 0)

-- _by family returns the ITEM, not the key
$worst = min_by($users, function($u) = $u.score)
$total = sum_by($users, function($u) = $u.score)

-- Grouping / dedup
$by_role = group_by($users, function($u) = $u.role)
$by_email = unique_by($users, function($u) = $u.email)

Pure list helpers (no function argument):

slice($xs, 1, 4)         -- sublist [1, 4) — end exclusive
slice($xs, -3, nil)      -- last three — nil end means "to end"
take($xs, 5)             -- first 5 (or last 5 with take($xs, -5))
drop($xs, 5)             -- skip first 5 (or drop last 5 with drop($xs, -5))
zip($keys, $vals)        -- list of [k, v] pairs

slice, take, drop all clamp on out-of-range boundaries rather than erroring — slice($xs, -100, 100) on a 3-element list returns the whole list. slice also works on strings (unicode-safe).

Reading structured files (v0.2.3)

Three helpers avoid the read_file + parse pattern scripts were writing by hand:

-- Line-oriented text: trailing newline stripped, empty trailing
-- line dropped so callers don't filter it out.
$lines = read_lines("/var/log/auth.log")
print length($lines), "lines"

-- Single-record JSON file → Mix value directly
$cfg = read_json("/etc/cosmix/config.json")
print $cfg.listen

-- JSON-lines (jsonl): one record per line → list
-- Strict by default: a single malformed line aborts the read.
$events = read_jsonl("/srv/mail/msg/alice/.spamlite-stats.jsonl")
print length($events)

-- Lenient mode: silently skip malformed lines. Use when log rotation
-- can leave a truncated tail and you'd rather lose one record than
-- fail the whole aggregation.
$clean = read_jsonl("/srv/rotating/events.jsonl", {skip_errors: true})

Strict-by-default for read_jsonl is deliberate: the canonical use case is aggregating stats across dozens of files, and silently dropping bad lines would make aggregate numbers unreliable without telling the script author. Lenient mode is the explicit escape hatch for known-noisy inputs.

Filesystem ergonomics (v0.2.1)

Recursive glob, walk, and path_parts:

-- Single-component (unchanged from v0.1.0)
glob("*.txt")                           -- files in CWD
glob("/var/log/*.gz")                   -- one wildcard component

-- Multi-component and recursive (v0.2.1)
glob("/srv/*/msg/*/.spamlite-stats.jsonl")   -- * in any component
glob("src/**/*.rs")                           -- ** = zero-or-more dirs

-- Enumerate every file under a tree
walk("/srv/mail")                       -- files only, sorted
walk("/srv/mail", {max_depth: 2})       -- cap depth (0 = direct children)
walk("/srv/mail", {include_dirs: true}) -- add dirs to the list
walk("/srv/mail", {follow_symlinks: true})  -- with loop protection

-- Decompose a path
path_parts("/home/user/report.tar.gz")
-- → {dir: "/home/user", base: "report.tar.gz", stem: "report.tar", ext: "gz"}

glob rules: - * and ? work in any path component, not just the last. - ** matches zero or more directory levels (think shell globstar). - Leading / → absolute pattern; otherwise relative to CWD. - Results are sorted lexicographically and ./foo normalizes to foo. - Nonexistent intermediate components silently return an empty list.

walk rules: - Returns a flat list of paths, sorted lexicographically. - Unreadable subdirectories are skipped silently — a single bad file in a deep tree doesn't abort the walk. The top-level $dir errors only if it doesn't exist. - max_depth: 0 means "direct children only, don't descend." None (omit the key) means unlimited. - Symlink loop protection only activates with follow_symlinks: true; uses (dev, inode) tracking on Unix.

path_parts rules: - Pure, no filesystem access. Works on nonexistent paths. - ext is WITHOUT the leading dot. extname keeps the dot — they're different consumers (ext for comparison, extname for reconstruction). - stem is everything before the last dot: path_parts("foo.tar.gz").stem returns "foo.tar", not "foo".

Formatted output (v0.2.0)

Three functions share the same minimal format grammar:

fmt("hello %s", "world")         -- returns "hello world"
printf("count=%d\n", 42)         -- writes to stdout, returns nil
eprintf("error: %s\n", $msg)     -- writes to stderr, returns nil

No {}-style templates — Mix already has ${...} interpolation; a second template syntax would confuse scripts. No %x/%o/%e/%g — add them if a real script needs them.

Unknown specifiers and too-few-args errors raise RuntimeError rather than substituting silently, so typos surface loudly. printf does not add a trailing newline — include \n explicitly, like C.

The canonical tabular-output pattern:

for each $u in $users
    printf("%-12s %5d %5d\n", $u.name, $u.fn, $u.fp)
next

.. concatenation already coerces every value through to_mix_string (so "count=" .. 5 works), which means printf is sugar for readability rather than an escape from a broken behaviour. Prefer printf for tabular output where alignment matters; prefer ${} interpolation or .. concat for simple string building.

Differences from ARexx / Lua / shell

From ARexx

• Concat is .., not ||. || is the run-if-failure chain operator.
• Variables need $ prefix. Bare identifiers are function names or keywords.
• Strings don't auto-concatenate: "a" "b" is a parse error; use "a" .. "b".

From Lua

• Maps use {key: value} with colon (not =).
• No metatables, no local scope (all vars in current function frame).
• end closes every block (since v0.2.2). Legacy done/next still parse with deprecation warnings; removal planned for v0.3.

From shell

• $var in expressions is OK; ${var} only works inside strings.
• No glob expansion: *.txt is literal. Use glob("*.txt").
• No word splitting: "a b c" is one string, not three. Use split(x, " ").
• &&/||/| are statement-level only.
• Errors don't abort the script — use try/catch or die.

Mix Outside Cosmix

Mix works as a standalone shell and scripting language without the cosmix stack. The interpreter detects at startup whether an AMP hub is available (via COSMIX_HUB env var or local socket probe). The detection result is stored in the interpreter context and exposed via amp_available().

Environment detection

if amp_available() then
    send "maild" "account.list"
else
    print "No AMP hub — reading from file"
    $accounts = read_file("/tmp/accounts.json")
end

AMP keyword behaviour without a hub

Scripts that don't use AMP keywords run identically in both environments. The 115 builtins (filesystem, HTTP, JSON, regex, crypto, process management) are all available without a hub.

The ARexx precedent

ARexx was the Amiga's scripting language but also worked as a general-purpose language — standalone REXX scripts that did nothing Amiga-specific ran fine. The ARexx port system was the standout feature, but the language existed in both contexts. Mix follows the same model: a useful shell on its own, with mesh messaging as a capability that activates when a hub is present.

Distribution

The mix binary is a single statically-linked Rust executable. It can be distributed independently of the cosmix stack. The AMP wire-format library (cosmix-lib-amp) is linked but dormant without a hub connection. Binary size overhead for the AMP code is minimal (~1000 lines of Rust).

Known sharp edges

1. Heredoc + JSON / ${...} content: if the value contains literal ${...} sequences that should not expand, prefer explicit .. concat. Heredocs interpolate eagerly and there's no opt-out per-segment.
2. Comparison asymmetry: == cross-type-coerces (so "5" == 5 is true), but </> error on coerce failure (so nil > -1 raises a runtime error rather than returning false). This is value.rs:79 vs evaluator.rs:2022 — two code paths, two rules. If you might compare nil, guard with ?? or an explicit if $x == nil.
3. Mid-chain non-map in interpolation yields nil: ${cfg.host.foo} returns nil if $cfg.host is a string, not an error. Same rule as expression-position field access. The chain walks as far as it can on Value::Map, then short-circuits to nil.
4. Value::Map falls back to *: $cfg.unknown_key returns the value of $cfg.* if set. Convenient as a defaults pattern, surprising if you forgot you set *.
5. exit(N) is not catchable: builtin_exit (builtins.rs:745) calls std::process::exit directly. It bypasses try/catch, skips Rust-side cleanup, and kills the host process if Mix is embedded. Use die "msg" (catchable, raises MixError::DieError) when you want intercept-able termination. v0.3 will convert exit to a catchable error variant.
6. Named functions vs anonymous lambdas capture differently (v0.2.0): Named function foo(...) definitions still see globals + their own params only — they do not capture an enclosing function's locals. Anonymous function(...) expressions built inside a named function capture that frame by value (frozen snapshot). Top-level $f = function(...) sees globals live — no capture needed. The divergence is deliberate for v0.2.0 and is acknowledged in the plan's Q2. v0.3 will converge both forms on a single lexical-closure rule.
7. args() vs $N: both work, but $1 is idiomatic for command scripts. args() is better when you need length() or iteration.

See also

• src/crates/cosmix-lib-mix/src/parser.rs — authoritative grammar
• src/crates/cosmix-lib-mix/src/builtins.rs — all 115 builtins (future Ch 04a)
• src/apps/sshm.mix — complete example of a Mix GUI app
• src/apps/lib/ui.mix — library of panel/data/status helpers
• mix/dbview — SQLite viewer using the datatable features
• src/_doc/2026-03-29-mix-language-plan.md — original design doc (historical)
• src/_doc/2026-04-11-mix-structured-pipelines.md — planned pipeline syntax (historical)

AMP Display Protocol Specification

0. Preamble

0.1 Scope

This specification defines the AMP Display Protocol — the rules by which processes declare user interfaces via AMP messages and display services render them. It covers message formats, command vocabulary, content mapping, property semantics, scripted behavior, widget types, composition, theming, transport tiers, and security.

A conformant display service (renderer) can be implemented from this document alone. A conformant process (UI producer) can generate valid display messages from this document alone.

0.2 The Three-Layer Model

The AMP Display Protocol separates UI into three orthogonal layers, each carried as plain text within the same AMP message:

All three are plain text. All three travel over the same AMP transport (Unix socket, WebSocket, SMTP). The display service receives one AMP message and extracts all three layers from it.

Unlike the web platform, where HTML, CSS, and JavaScript evolved independently over 30 years with different authors, transport mechanisms, and mental models, these three layers are designed together on a unified message format. There is no loading order, no cascade, no cross-origin policy — one message, three layers, one parse.

0.3 Design Principles

1. Plain text everywhere. Every message is human-readable (cat, grep, markdown viewers work directly). Every message is machine-parseable (deterministic header extraction). Every message is AI-comprehensible (markdown is native LLM format).

2. Protocol over framework. The protocol defines how UI is declared. Renderers are swappable implementations. Apps are processes that speak the protocol, not binaries linked against a widget library.

3. Fixed widget set. The 22 widget types defined in this spec are the complete vocabulary. No runtime extensibility, no plugin widgets, no code shipping. New widget types require a protocol version bump.

4. Headers route, bodies reason. Routers parse only headers. Display services parse headers + body. Scripts reason over events. The same message serves all three readers at different depths.

5. Graceful degradation. A ui.panel message renders as a native window on a desktop, as HTML in a browser, as styled text in a terminal, and as readable plain text in a non-cosmix email client. Fidelity varies; readability is preserved.

6. AMP at every app-facing boundary. All communication that applications send or receive uses AMP — text, human-readable, language-agnostic. Internal display infrastructure (widget-to-widget within the same panel, shell↔deskd in Phase B) may use function calls or postcard for performance, but applications never see these. See 00_index.md "Protocol Boundary Table" for the full matrix.

7. Process owns state, display owns pixels. The process is the single source of truth for all application state — data models, widget IDs, panel hierarchy, and mutation logic. The display service has no application state: it draws what it receives and reports user interactions, but does not generate IDs, manage data models, diff content, or reconcile updates. (It does maintain rendering state — the current panel tree, widget input values, scroll positions, focus — but this is derived entirely from incoming messages, never invented.) The hub routes messages between them but owns no application state. There is no virtual DOM, no reconciliation engine, no framework-managed component lifecycle. Every mutation is an explicit message from the process. This is the Tk/ARexx model, not the browser model.

0.4 State Ownership

The three participants in the display protocol have distinct, non-overlapping responsibilities:

ID allocation rules:

• Panel IDs: assigned by the process in the id header of ui.panel. The process chooses semantic, stable names (mail-sidebar, file-browser, compose).
• Widget IDs: assigned by the process in the id property of code block declarations (~~~textinput id=to).
• Data item IDs: assigned by the process (or its upstream data service) in the id field of JSON data objects. For example, maild generates email IDs; the process passes them through in ui.data.

No component of the system auto-generates IDs. If a process does not assign an id, the panel/widget/item cannot be targeted by subsequent commands.

Recovery model: If a process disconnects, its panels become orphaned (Section 10.3). When the process restarts, it sends fresh ui.panel messages — full state reconstruction from the process, not recovery from the display service. There is no "reconnect and diff against what's currently rendered."

0.5 Terminology

0.6 Notation

This specification uses RFC 2119 keywords: MUST, MUST NOT, SHOULD, SHOULD NOT, MAY.

Header names are shown in monospace. Message examples use the AMP wire format with --- delimiters.

1. Wire Format

1.1 Message Structure

Every AMP message consists of two parts: headers (a sorted key-value map) and a body (UTF-8 text). The wire format uses markdown frontmatter delimiters:

---
key1: value1
key2: value2
---
body content here

The opening ---\n begins headers. Each subsequent line until the closing ---\n is a header in key: value format. Everything after the closing delimiter is the body. The body is terminated by end-of-stream or the next message's opening ---\n.

1.2 Header Syntax

• Headers are key: value pairs, one per line.
• Keys are case-sensitive, lowercase, using underscores or hyphens (text_color, reply-to).
• Values are UTF-8 strings. Leading whitespace after : is trimmed.
• Header order is deterministic (lexicographic by key) for consistent serialization.
• Duplicate keys: last value wins (but producers SHOULD NOT emit duplicates).

1.3 Body

• UTF-8 encoded text.
• Trailing whitespace is trimmed by parsers.
• May be empty (command-only messages).
• For ui.panel messages, the body is GFM markdown.
• For ui.data messages, the body is JSON.
• For ui.style and ui.theme messages, the body is key: value pairs.
• Body termination and framing follow the Chapter 01 v0.5 wire format. Messages are terminated by the ---\nEOM\n end-of-message marker. Markdown horizontal rules (---) in the body are unambiguous because the parser requires both ---\n and EOM\n in sequence to terminate a message. Panel body content MUST NOT contain the literal sequence ---\nEOM\n (the AMP stream terminator). In practice, markdown bodies never do. See 01_amp-wire-protocol.md §5.1–5.2 for the grammar and stream framing rules.

1.4 Message Shapes

The empty message (---\n---\n---\nEOM\n) is the minimum valid AMP message. It carries no headers and no body. It serves as heartbeat on idle connections and as a natural separator in concatenated message streams. See 01_amp-wire-protocol.md §5.1 for the wire grammar.

1.5 Message Types

The type header identifies the message role:

Display protocol messages (ui.panel, ui.style, etc.) are typically event type — fire-and-forget from process to display service. ui.event messages from display to process are also event type. ui.subscribe is request type (expects acknowledgment).

1.6 Return Codes

1.7 Stream Framing

Stream framing, the parsing algorithm, transport-level message boundaries, and error recovery are defined in 01_amp-wire-protocol.md §5.1–5.2. This chapter does not restate those rules — Chapter 01 is authoritative for all wire-format concerns.

Key points for display protocol implementors:

• Messages are terminated by the ---\nEOM\n two-line marker (Ch01 v0.5).
• Markdown horizontal rules (---) in ui.panel bodies are unambiguous.
• On WebSocket transports, one text frame = one complete AMP message.
• On SMTP transports, the MIME boundary delimits the text/x-amp-panel part.

1.8 Required Headers

For non-empty messages, the following headers SHOULD be present:

The command header is REQUIRED for all display protocol messages.

Note: msg_id is message identity (request/response correlation, deduplication, logging). id on ui.panel is panel identity (targeting, hierarchy, lifecycle). These are distinct concepts and MUST NOT be conflated. A single ui.panel message may have both: msg_id for transport and id for the panel it creates.

2. Addressing

2.1 AMP Address Format

Addresses use a DNS-style dot-separated hierarchy with a .amp suffix:

node.amp                    — node level (2 segments)
app.node.amp                — app on a node (3 segments)
port.app.node.amp           — specific endpoint (4 segments)
widget-id.app.node.amp      — widget within an app (4 segments)

Segment count is fixed at each level. Internal hierarchy within a segment uses hyphens: file-menu-save-as.edit.cachyos.amp.

Local shorthand: when addressing within the same node, the node and .amp suffix MAY be omitted. cosmix-mail is equivalent to cosmix-mail.local-node.amp.

2.2 Panel IDs

Panel IDs are strings that uniquely identify a panel within the hub's scope.

• IDs MUST be unique across the hub at any given time.
• IDs SHOULD be semantic and stable: mail-compose, file-browser, statusbar.
• IDs MUST NOT contain whitespace or the * wildcard character.
• Dot-separated prefixes MAY be used for logical grouping: mail.sidebar, mail.compose, mail.list.

2.3 Widget IDs

Widgets within a panel are identified by the id property in their code block declaration:

```textinput id=to placeholder="To..."
```

Widget IDs are scoped to their parent panel. The fully-qualified widget reference is widget-id.panel-id (for local) or widget-id.app.node.amp (for mesh).

Routing clarification: The mesh form (widget-id.app.node.amp) is a logical reference for documentation and Mix scripts, not a hub-routable endpoint. The hub routes messages to processes based on the application address (app.node.amp). Widget resolution within a panel is performed internally by the display service using the target or source header. Mix scripts address widgets via ui.event headers, not by sending directly to a four-segment widget address.

2.4 Wildcard Targeting

The target header in ui.style messages supports glob-style wildcards:

Wildcards expand at the hub level. The display service receives individual targeted messages.

Implementation note: Wildcard expansion requires the hub to maintain a registry of all active panel IDs. This makes the hub stateful for display routing — it tracks panel creation and removal, not just connection routing. The hub already maintains process/port registries; the panel registry is a natural extension.

3. Display Protocol Commands

All display protocol commands use the ui. prefix. Commands are divided into two categories: display commands (process → display service) and interaction commands (display service → process or process → hub).

3.1 ui.panel — Create or Update Panel

Creates a new panel or updates an existing one. This is the primary display command.

Direction: Process → display service Semantics: If the id does not exist, create a new panel. If it exists, update it.

Required headers:

Optional headers (window):

Phase B migration: Window-management headers (position, layer, decorations, sticky, parent: desktop) are handled by cosmix-deskd in Phase A. In Phase B, these concerns migrate to a dedicated cosmix-shell command surface. Applications SHOULD treat these headers as layout hints, not contracts. A conformant renderer MAY ignore window-management headers in constrained environments (TUI, nested child-panel, federated display).

Optional headers (layout):

Optional headers (style):

Optional headers (behavior):

Optional headers (federation):

Body: GFM markdown content. See Section 4.

3.1.1 Grid Template Layout

When layout: grid is set, the grid_template header defines named regions with explicit sizes. This allows a single panel to express complex spatial layouts without spawning child panels for every region.

Syntax: Pipe-separated track definitions. Each track is name size:

grid_template: sidebar 250px | content 1fr | details 300px

Track sizes:

Rows: By default, grid_template defines columns. For row definitions, use grid_rows:

grid_template: sidebar 250px | content 1fr
grid_rows: header 3rem | body 1fr | footer 2rem

Child placement: Child panels or markdown sections are placed into named grid areas by setting grid_area: name on the child panel:

---
command: ui.panel
id: mail-app
layout: grid
grid_template: sidebar 250px | content 1fr
grid_rows: toolbar 3rem | body 1fr | status 2rem
---

---
command: ui.panel
id: mail-sidebar
parent: mail-app
grid_area: sidebar
---
# Mailboxes
- Inbox (3)
- Sent

---
command: ui.panel
id: mail-toolbar
parent: mail-app
grid_area: toolbar
---
[Compose](mail.compose) [Refresh](mail.refresh)

When grid_template is set without child panels using grid_area, the grid auto-places children in order (first child → first cell, etc.), matching CSS Grid auto-placement behavior. If a child specifies a grid_area name that does not exist in the parent's grid_template, that child falls into the auto-placement flow as if grid_area were not set.

When to use grid vs child panels:

Grid reduces panel count for static layouts. Child panels remain the right choice when regions have independent lifecycles (created/removed at different times, different processes owning different regions).

Update semantics: When ui.panel targets an existing ID: - The body is replaced entirely. - Headers present in the update message override the stored values. - Headers absent from the update message are preserved from the original. - To clear a header, set it to an empty string.

Example:

---
command: ui.panel
id: mail-compose
parent: desktop
layout: column
width: 40%
height: 60%
title: Compose
decorations: close,minimize
---
# New Message

~~~textinput id=to placeholder="To..."
~~~

~~~textinput id=subject placeholder="Subject"
~~~

---

~~~textarea id=body rows=15
~~~

---

[Send](mail.send) [Attach](mail.attach) [Discard](mail.discard)

3.2 ui.style — Restyle Panel or Widget

Changes style properties of an existing panel or widget without replacing content.

Direction: Process → display service

Required headers:

Body: key: value pairs, one per line. Keys are style property names from the property registry (Section 5). Values support var(name) references.

Example:

---
command: ui.style
target: file-browser
---
background: var(surface-dim)
border_color: var(primary)
border_width: 2

3.3 ui.remove — Remove Panel

Destroys a panel and frees its resources. All child panels are removed recursively (depth-first).

Direction: Process → display service

Required headers:

Body: Empty.

Cascade: When a panel is removed, all panels with parent equal to the removed panel's id are also removed, recursively. Events in flight for removed panels are silently dropped.

3.4 ui.event — User Interaction

Sent by the display service when the user interacts with a panel or widget. This is the primary feedback channel from display to process.

Direction: Display service → process

Required headers:

Body: key: value pairs describing the event:

Additional keys MAY be present depending on the widget type. See Section 6 for per-widget event payloads.

Example:

---
command: ui.event
source: file-browser
---
action: select
widget: file-list
row: 0
item: notes-md
value: notes.md

3.5 ui.theme — Set Theme Variables

Sets or switches the active theme. All var(name) references across all panels resolve against the current theme.

Direction: Process → display service

Optional headers:

Body: key: value pairs mapping variable names to values. See Section 9 for standard variable names.

Example:

---
command: ui.theme
name: midnight
---
primary: #6366f1
primary-dim: #4f46e5
background: #0f0f1a
surface: #1a1a2e
surface-dim: #12122a
text: #e0e0e0
text-secondary: #999999
border: #333355
error: #ef4444
warning: #f59e0b
success: #10b981

3.6 ui.data — Push Data to Widget

Sends data to a data-driven widget (VirtualList, DataTable). See Section 12 for full data binding semantics.

Direction: Process → display service

Required headers:

Optional headers:

Body: JSON. Format depends on action:

Every data object MUST contain an id field (string) for incremental operations.

Example (full replace):

---
command: ui.data
target: mailbox-list
---
[
  {"id": "inbox", "name": "Inbox", "unread": 3, "icon": "inbox"},
  {"id": "sent", "name": "Sent", "unread": 0, "icon": "send"},
  {"id": "trash", "name": "Trash", "unread": 0, "icon": "trash-2"}
]

Example (insert at position):

---
command: ui.data
target: mailbox-list
action: insert
index: 1
---
{"id": "drafts", "name": "Drafts", "unread": 1, "icon": "file-text"}

3.7 ui.template — Set Data Template

Defines a markdown template for rendering data items in a data-driven widget. The template is stamped once per data item with {field} interpolation. See Section 12.

Direction: Process → display service

Required headers:

Body: Markdown with {field} placeholders. Each placeholder is replaced with the corresponding field value from the data object.

Example:

---
command: ui.template
target: mailbox-list
---
- ![{icon}](lucide:{icon}) **{name}** ({unread})

3.8 ui.batch — Atomic Multi-Command

Executes multiple display commands atomically. The display service applies all commands before rendering a frame — no partial updates are visible to the user.

Direction: Process → display service

Required headers:

Body: JSON array of command objects. Each object has command (string), headers (object), and optional body (string).

Design note: This is the only display command with a JSON body (all others use markdown or key-value pairs). JSON is chosen here because batch commands must be parsed atomically — concatenated AMP messages would require the renderer to buffer and group them, defeating the atomicity guarantee. The trade-off against the "cat and grep" principle is accepted for this single command.

Example:

---
command: ui.batch
---
[
  {
    "command": "ui.style",
    "headers": {"target": "sidebar"},
    "body": "width: 250\nbackground: var(surface-dim)"
  },
  {
    "command": "ui.style",
    "headers": {"target": "content"},
    "body": "width: 100%"
  }
]

3.9 ui.subscribe — Register Event Filter

Registers a process to receive ui.event messages matching a filter. This is the hub-level primitive that enables Mix's on keyword (Section 7).

Direction: Process → hub

Required headers:

Body: key: value filter criteria:

Response: RC 0 with subscription ID.

Semantics: After subscription, the hub routes matching ui.event messages to the subscribing process. Multiple subscriptions from the same process are allowed.

Example:

---
command: ui.subscribe
type: request
msg_id: sub-001
---
source: file-browser
action: select

3.10 ui.unsubscribe — Deregister Event Filter

Removes a previously registered event subscription.

Direction: Process → hub

Required headers:

Body: Empty.

3.11 Widget and Menu Introspection

These commands enable ARexx-style discovery and scripting of the display surface. A script can enumerate widgets, read their state, and invoke them without hardcoding IDs — the same discover-then-script pattern used on the Amiga. These are handled by the display service, not individual apps.

Widget introspection

Menu introspection

Lifecycle

Discovery flow for scripts

A script targeting an unknown panel should:

1. hub.list → get registered services
2. menu.list → discover menu items and their IDs
3. ui.list → discover interactive widgets and their current state
4. ui.get → read specific widget values before acting
5. Then invoke/set as needed

This is the ARexx pattern: discover first, script second. Never hardcode widget IDs without verifying they exist via ui.list.

4. Layer 1 — Markdown Content

4.1 Parser

The markdown body of a ui.panel message is parsed as GitHub Flavored Markdown (GFM) using the following extensions:

• Strikethrough (~~text~~)
• Task lists (- [x] item)
• Tables (| col | col |)

Parsers MUST use these extensions. Parsers MUST NOT add custom syntax beyond the code-block-as-widget convention defined below.

4.2 Element Mapping

Every GFM element maps to a visual widget in the rendered panel:

4.3 Code Blocks as Widget Declarations

Fenced code blocks (backtick ``` or tilde ~~~) with a language hint declare interactive widgets when the hint matches a known widget type (Section 6):

```textinput id=to placeholder="To..." value="alice@example.com"
```

Parsing rules:

1. Extract the first word of the language hint as the widget type name.
2. Look up the name in the widget type registry (Section 6). If not found, render as a plain code block.
3. Parse remaining words as key=value properties. Quoted values (key="multi word") preserve spaces.
4. The code block content (lines between the fences) is the widget's initial value/content.

Example with content:

```textarea id=body rows=10
Default text content goes here.
It can span multiple lines.
```

4.4 ~~~mix Code Blocks — Behavior Attachment

A fenced code block with language hint mix declares an inline script:

~~~mix
on ui.event from "my-panel" action "submit"
  $name = $event.name
  send "greeting-service" greet name=$name
end
~~~

Rules:

1. ~~~mix blocks MUST NOT be rendered as visible content.
2. The display service MUST extract ~~~mix blocks and forward them to the script execution service (Section 7).
3. Multiple ~~~mix blocks in a single panel body are concatenated in order.
4. ~~~mix blocks in federated panels (source_peer is set) MUST be stripped silently.

4.5 Links as Actions

Markdown links are action buttons. The URL component is an action URI (Section 8):

[Send](mail.send)
[Reply](mail.reply:msg-id-123)
[Delete](mail.delete:msg-id-123?confirm=true)
[Open Settings](ui.panel:settings)
[Visit Site](xdg-open:https://example.com)

When the user clicks a link, the display service dispatches the action URI. For AMP commands, this emits an AMP message. For xdg-open, this opens the URL in the system browser. See Section 8 for the complete scheme.

4.6 Images as Icons

Image syntax references icons or loads images:

![inbox](lucide:inbox)              — Lucide icon by name
![avatar](https://example.com/a.jpg) — Remote image
![screenshot](/tmp/capture.png)      — Local file

The lucide: prefix resolves to the Lucide icon set. Renderers SHOULD support at minimum the Lucide icon set. Unknown icon names render as a placeholder.

5. Layer 2 — AMP Header Properties

5.1 Size Units

Size values in headers (width, height, gap, padding, etc.) accept these units:

Bare numbers without a unit suffix are interpreted as pixels for width/height and rem for gap/padding/border_radius/font_size.

5.2 Color Values

Color values in headers and style bodies accept:

Named colors (e.g., red, blue) are NOT supported. Use hex values.

5.3 Variable References

The var(name) syntax resolves a value from the current theme (Section 9):

background: var(surface)
text_color: var(text-secondary)
border_color: var(primary)

Resolution is flat — one lookup, no cascade, no fallback chain. If the variable is not defined in the current theme, the renderer SHOULD use a sensible default (black for text, white for background, transparent for borders).

5.4 Property Categories

All properties that appear in ui.panel headers or ui.style bodies are defined in Section 3.1. This section serves as a cross-reference index.

Window properties: id, parent, title, width, height, position, decorations, layer, sticky, ttl Layout properties: layout, gap, padding, align, scrollable, overflow Style properties: background, text_color, border_color, border_width, border_radius, font_size, opacity Behavior properties: script Federation properties: source_peer, permissions

5.5 The script Header

The script header on a ui.panel message attaches a Mix script to the panel:

---
command: ui.panel
id: file-browser
script: ~/.config/cosmix/scripts/file-browser.mx
---
# Files
...

The value is a file path or URI. The script is loaded and executed when the panel is created, and terminated when the panel is removed. See Section 7 for full lifecycle semantics.

6. Widget Type Registry

This section defines the 22 widget types recognized by the display protocol (plus the tooltip cross-cutting property). For each widget type: accepted properties, emitted events, code block syntax, and degradation behavior.

6.1 Display Widgets

6.1.1 Label

A text display element.

Aliases: label Code block: ~~~label id=status with text content. Degradation: Rendered as plain text.

Events: None. Labels are non-interactive.

6.1.2 Icon

An icon from the Lucide icon set or a custom SVG.

Aliases: icon Code block: ~~~icon id=status name=check-circle Degradation: Rendered as [icon-name] text.

Events: None.

6.1.3 Image

Displays a raster image (PNG, JPEG, WebP) or SVG.

Aliases: image, img Code block: ~~~image id=avatar src=/path/to/image.png Degradation: Rendered as [alt-text].

Events: None.

Security: For federated panels (source_peer set), src values MUST be validated. Local file paths (/path/to/..., ~/..., file://) MUST be rejected — federated panels may only reference blob IDs or HTTPS URLs. Renderers MUST NOT resolve relative paths against the local filesystem for federated content.

6.1.4 Markdown

A sub-document rendered as markdown. Enables nested markdown content within imperatively-created widget trees.

Aliases: markdown, md Code block: ~~~markdown with markdown content. Degradation: Rendered as plain text (markdown is already readable).

Events: Action link clicks within the markdown are dispatched as ui.event with the action URI. Same behavior as panel-level markdown.

6.2 Layout Widgets

6.2.1 Container

A layout container that holds other widgets. Uses flexbox semantics via taffy.

Aliases: container, div Code block: ~~~container id=toolbar layout=row gap=0.5 Degradation: Contents rendered sequentially.

Events: None. Containers are structural.

6.2.2 ScrollContainer

A container with scrollable overflow.

Aliases: scroll, scrollcontainer Code block: ~~~scroll id=content direction=vertical Degradation: Contents rendered sequentially.

Events:

6.2.3 Tabs

A tabbed container with tab bar and content switching.

Aliases: tabs Code block: ~~~tabs id=mail-tabs active=inbox tabs="Inbox,Sent,Drafts" Degradation: All tab contents rendered sequentially with tab names as headings.

Events:

6.2.4 SplitPane

A container with two children separated by a draggable divider.

Aliases: splitpane, split Code block: ~~~split id=main direction=horizontal ratio=30:70 Degradation: Both panes rendered sequentially.

Events:

6.3 Input Widgets

6.3.1 Button

A clickable button.

Aliases: button, btn Code block: ~~~button id=send label="Send Message" variant=primary Degradation: Rendered as [label] text.

Events:

6.3.2 TextInput

A single-line text input field.

Aliases: textinput, input Code block: ~~~textinput id=email placeholder="Email" value="user@example.com" Degradation: Rendered as [value] or [placeholder] text.

Events:

6.3.3 TextArea

A multi-line text input. Implementation complexity: very hard (cosmic-text integration for cursor, selection, wrapping, IME). Renderers handle local text buffering, cursor, selection, and IME state; ui.event with action: input SHOULD be debounced or emitted on blur/submit to avoid per-keystroke protocol overhead.

Aliases: textarea Code block: ~~~textarea id=body rows=10 with initial content. Degradation: Rendered as indented text block.

Events:

6.3.4 Dropdown

A selection dropdown (single-select).

Aliases: dropdown, select Code block: ~~~dropdown id=priority options="Low,Normal,High" value="Normal" Degradation: Rendered as [value] text.

Events:

6.3.5 Checkbox

A boolean checkbox with label.

Aliases: checkbox Code block: ~~~checkbox id=agree label="I agree" checked=true Degradation: Rendered as [x] or [ ] with label.

Events:

6.3.6 Toggle

A slide-switch toggle (on/off).

Aliases: toggle, switch Code block: ~~~toggle id=dark_mode label="Dark mode" checked=true Degradation: Rendered as (on) or (off) with label.

Events:

6.3.7 RadioGroup

A mutually exclusive set of options (only one can be selected).

Aliases: radiogroup, radio Code block: ~~~radio id=priority options="Low,Normal,High" value="Normal" Degradation: Rendered as (x) selected / ( ) unselected text list.

Events:

6.3.8 Slider

A range slider for numeric values.

Aliases: slider, range Code block: ~~~slider id=opacity min=0 max=100 value=80 step=1 Degradation: Rendered as [value] text.

Events:

6.3.9 Progress

A progress bar or indeterminate spinner.

Aliases: progress Code block: ~~~progress id=upload value=65 max=100 label="Uploading..." Degradation: Rendered as [65%] or [loading...] text.

Events: None. Progress bars are display-only.

Updates: Use ui.set to update value (widget state): send "ui" set target="upload" value="75". Use ui.style to update variant and label (presentation). The distinction: value is data the widget tracks, variant/label are how it looks.

6.4 Data Widgets

6.4.1 VirtualList

A scrollable list that only renders visible items (windowed/virtualized rendering). For large datasets. Uses ui.template for item rendering and ui.data for data.

Aliases: virtuallist, vlist Code block: ~~~vlist id=email-list item_height=2.5 Degradation: First N items rendered as list items (N = renderer discretion).

Events:

Data format: JSON array of objects. Each object MUST have an id field. For indented/tree lists, objects MAY have a depth field (integer, 0-based) and expandable field (bool).

[
  {"id": "inbox", "name": "Inbox", "unread": 3, "icon": "inbox"},
  {"id": "sent", "name": "Sent", "unread": 0, "icon": "send"}
]

Template: Markdown with {field} interpolation. Rendered once per item.

- ![{icon}](lucide:{icon}) **{name}** ({unread})

6.4.2 DataTable

A tabular data display with column headers, sorting, and virtual scrolling.

Aliases: datatable, table Code block: ~~~datatable id=files columns="Name,Size,Modified" sortable=true Degradation: Rendered as a GFM markdown table (first N rows).

Events:

Data format: JSON array of objects. Keys correspond to column keys.

[
  {"id": "notes-md", "name": "notes.md", "size": "2.1 KB", "modified": "2026-04-06"},
  {"id": "report-pdf", "name": "report.pdf", "size": "145 KB", "modified": "2026-04-05"}
]