Status note (2026-08-05): The 2026-04-25 reconsideration is resolved. The renderer-engine re-investigation completed with live evidence: the display stack is Bevy 0.19 (ECS/wgpu) rendering on a Smithay 0.7 protocol core, shipped as cosmix-comp (0.12.1 at cos 50bf6e9) with TTY first light and session-revocation containment proven on hardware (rungs D-3, D-3.1). The former pre-commitments — the cosmix-shell/display-backend split, taffy/cosmic-text, "shell before compositor", postcard as the shell hot path — are superseded where they conflict with the North Star below; 00b-architecture-vision is retained as historical exploration only.

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 through the display chapters. Every chapter, and every decision revisited under one, is now measured against the North Star first.

---

The North Star

Take GNOME's coherence, KDE's architecture, Windows' snap, COSMIC's tiling toggle, niri's spatial canvas, and macOS's motion — bind them with SSD frames and a compositor-drawn palette that is also the agent — and let the ECS scene and the bus do what no incumbent can: make the desktop's every opinion animated, addressable, and replaceable without recompiling.

That sentence is the destination. Everything below it is the map: the decided stack, the three planes, eight principles with their decision tests, and the default desktop those principles produce. New specs, new rungs, and revisited past decisions cite this section the way code cites a type — a proposal that fails a decision test is either reworked or must amend the North Star explicitly (version-bumped, journaled), never silently ignored.

Decided stack

• Compositor: cosmix-comp — Smithay =0.7.0 protocol frontend (calloop thread) with Bevy =0.19.0 / wgpu =29.0.4 rendering via cosmix-wgpu-dmabuf (zero-copy client-buffer import, KMS direct display). Exact pins are policy, not accident.
• Toolkit: CTK (desktop/ctk) — Bevy ui/feathers-based, AMP-citizen widgets, one theme system (.mix overlays), Lucide icons. Native apps draw themselves. (The language-agnostic AMP Display Protocol declarative lane was retired with Ch01b/05 on 2026-08-16 — ui.* left ABP at the control-plane pivot; scripts and agents drive webd instead.)
• Bus: the cosmix bus (protocol name AMP, Ch01) brokered per-node by cosmix-noded, meshed over WireGuard, with SPEC 12 property surfaces and Ch03 topics.
• Evidence culture: work lands as rungs — small, journaled, live-evidence-backed increments (the discipline that produced D-3/D-3.1).

The three planes

Principles and their decision tests

1. The protocol plane is the sole source of truth; renderers are views. Test: does this proposal make anything outside the protocol plane authoritative? Then rework it.
2. The bus is never in the frame path. Bounded queues, own task; comp runs flawlessly with no broker at all. Test: can a slow, flooded, or absent broker cost a frame? Then rework it.
3. Power is a measured budget. Reactive scheduling everywhere — reactive WinitSettings default in every CTK app, demand-driven pump in comp: render only on damage or live animation, skip commits when the scene is static. Idle watts and wakeups/sec are standing journal numbers no rung may regress. Test: what does this cost at idle, on battery, measured?
4. Mechanism in the compositor, policy on the bus. Window placement, tiling, workspace behaviour, frames' look — policy is data and services (a tiling engine is a bus citizen issuing comp.move), hot-swappable without recompiling. Test: is this opinion compiled in where a service could hold it instead?
5. Trusted tier vs furniture tier. UI lives in comp only if it must be unspoofable (consent prompts, lock, SSD frames, the palette) — and the trusted tier stays small and renderer-agnostic in its data model, so any future engine can draw a degraded version. Everything else (panels, launcher, notifications) is a layer-shell CTK client: crash-isolated, independently released, indifferent to which engine paints the scene. Test: must this be unspoofable? If not, it's a client.
6. Adopt standard protocols wholesale; add value above them. xdg-decoration (answer ServerSide; tolerate CSD guests), wlr-layer-shell, portals, XWayland. The bus is the layer above the floor, never a replacement for the floor. Test: does a standard protocol already do this for a thousand guest apps?
7. Opinionated default, cheap dissent. One coherent desktop out of the box (GNOME's lesson); every deviation a config value or policy service, not a settings maze (KDE's warning). Test: does this add a knob where a better default would do — or hardcode what should be a knob on the bus?
8. Evidence before expansion. Every phase lands as rungs with live runs, journaled numbers, and tests both feature ways. Failure stays honest (exit codes, detach reasons) until machinery makes it survivable (today: bounded exit and fast restart; demote-instead-of-exit arrives only if the utility-renderer tripwire ever admits one). Test: what is the live evidence, and where is it journaled?

The default desktop (what the principles produce)

Server-side decorations whose frames are bus surfaces (agent indicators, unsaved-work state). Floating windows with Windows-grade snap ergonomics and COSMIC's per-workspace tiling toggle — both mere layout policies writing the same ECS transforms. Workspaces are the canvas model (v0.4.2): each output is a camera over a bounded, elastic 2D canvas — the X virtual root and the Amiga's draggable screens, modernized. Workspaces aren't containers; they're camera bookmarks: named, screen-sized places the camera settles onto magnetically, so keybind users experience ordinary discrete workspaces while the canvas allows free X-Y panning edge to edge (inertial Super+drag and 2D gestures; dwell-gated edge-push optional and default-off, because screen edges are load-bearing). Places spawn at the frontier and garbage-collect when empty (dynamic, GNOME-style); layout policy is per-place; the plane is bounded because spatial memory needs edges. Zoom is the unifier: zoom out far enough and the canvas is the overview, live thumbnails included, because it is a camera move over a scene that already exists. Every coordinate is addressable — camera pose as settable comp.props, places as semantic bus addresses (comp.camera.goto place:mail), place.entered/camera.moved topics for pagers and agents — and ext-workspace-v1 projects places as flat workspaces for guest pagers and portals. macOS-grade motion as physical continuity, interruptible mid-flight, with reduce-motion a single policy toggle. And one summonable, compositor-drawn command surface with three depths — app launch, typed bus verbs, natural language into agentd — the palette that is also the agent: trusted-tier, unspoofable, the place where the mesh becomes visible to a person who will never learn what a bus is.

Roadmap phases (rung groups, not leaps)

0. Finish the current arc: Rung F (compositor-handled Ctrl+Alt+Fn), E-5 residuals. 1. Power floor (reactive everywhere; demand-driven pump; standing idle measurements). 2. Bus in the core (comp-port: register → read-only props/topics → gated verbs) — deliberately early, because comp.props telemetry (frame timing, wedge counts, idle watts) is the evidence the tripwires below read. 3. Scenic buildout — the Bevy-first push: client windows composited into the scene, SSD frames, snap + per-place tiling, the canvas + places + overview, furniture as layer-shell clients, toolkit growth (datatable first). 4. Agentic desktop (agentd × comp verbs × interactd consent — configuration, not construction, if 1–3 land as specified).

Tripwires (what admits an alternate engine — evidence, not schedule)

Alternate render engines and the scanout bypass are not phases. Each is built only when its tripwire fires, from the working baseline, through the seams principle 1 preserves:

• Utility/software renderer — journaled wedge frequency above ~1/month on supported hardware; or a Bevy upgrade stalled beyond a few weeks with a fix required on the desktop; or a real VM/headless deployment need.
• Direct scanout (bypass) — measured fullscreen video/gaming power or latency numbers that composition cannot meet. (dmabuf-feedback v4 is re-sendable, so scanout tranches can be added later without breaking any client — deferral costs nothing.)
• Deeper power work beyond the demand-driven pump — idle battery draw still above target after Phase 1's reactive work lands and is measured.

Seams that make this possible (kept warm at near-zero cost, per principle 1): the presentation layer remains the sole KMS commit owner and does not fuse into Bevy internals; SSD frame model, hit regions, and input live in protocol-plane data any renderer could draw; window layout lives in protocol records, mirrored — never solely owned — by ECS components.

Revisit queue (past decisions to re-read under this section)

• 00b-architecture-vision — Amiga/Intuition mapping and Phase A/B/C: historical; salvage the taste, discard the crate choices.
• Postcard shell↔compositor hot path — superseded: the scenic renderer is in-process; furniture speaks Wayland + bus (see Protocol Boundary).
• "Build the shell before the compositor" — inverted by events; the compositor exists and furniture ships as its clients.
• Ch05 display protocol — retired 2026-08-16 (ui.* left ABP at the control-plane pivot); the language-agnostic lane for scripts and agents is webd. Ch06 survives as the display-model chapter (the design-system contract is Ch19).
• Naming: AMP → cosmix bus is in progress; chapters keep "AMP" for the wire protocol until regenerated, prose should prefer "cosmix bus" for the system (broker + mesh + verbs + topics) as of this version.

---

Glossary

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

Trust gradients — four DISTINCT ladders (don't conflate)

The suite has four "level"-shaped scales that look alike but are orthogonal axes; an Ln in one is unrelated to an Ln/Tn in another. Always qualify which one you mean:

(Reconciliation item from the 2026-06-05 spec audit: these were drifting into looking like one ladder. Until renamed, cite the home + axis.)

---

Architecture vision (historical)

The former display-stack narrative — the Amiga/Intuition mapping, the cosmix-shell ↔ display-backend split, phasing (A/B/C), taffy/cosmic-text crate choices, and the postcard/WebRTC hot-path plans — lives in 2026-06-05-00b-architecture-vision.md and is now historical: superseded by the North Star above wherever the two disagree. It remains worth reading for the Intuition-derived design taste that survives into Ch06 and CTK.

---

Protocol Boundary

Two layers, decided independently. Application protocol is what processes speak — almost always AMP (the cosmix bus wire format), with rare exceptions for things that aren't application traffic at all (shared-memory function calls, real-time media, and the display hot path, which is Wayland). Transport is what carries the bytes underneath — chosen per workload from the working set, with candidates flagged for evaluation. AMP frames are portable across transports; swapping transports does not change the application protocol.

For the workload-classification view and candidate-evaluation criteria, see _spec/2026-03-24-01-bus-wire-protocol.md §8.

The rule: if an application could ever need to send or receive it, the application protocol is AMP. Transport is then chosen per workload. Real-time media, Wayland's buffer/input hot path, and in-process render seams are below the AMP layer; bulk binary is application-adjacent (orchestrated via AMP, content moved via a binary transport).

---

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 | retired    # retired: kept verbatim as dated history
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., 2026-04-07-05-amp-display-protocol.md), not by date-prefixed names.

---

Chapters

Chapters 14, 15 and 17 are reserved for not-yet-written infrastructure/display chapters (see Planned Chapters below); Chapter 16 was drafted 2026-08-05 alongside the shipped cosmix-comp; Chapter 19 was commissioned by Mark 2026-08-09 with the Resolved Design Graph adoption (_decisions/2026-08-09-resolved-design-graph-adopted.md). Chapter 13 (Mesh Architecture) was drafted 2026-06-02 from a measured testbed. Chapter 18 was drafted ahead of them because it specifies an existing runtime surface (Mix scripts as AMP daemons) rather than a deferred component. Decided (SPEC 18 §10.1): Chapter 18 stays at 18 and is not renumbered. Slot 15 ("Daemon Infrastructure") is not back-filled with this content; the 13–17 band's disposition is downstream of authoring 13–17, not a slot SPEC 18 pre-claims or vacates now.

Reading Order

Start here: Chapter 00's North Star (above), then Chapter 01 — 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 bus messaging (send, address, emit) when a broker is available. Like ARexx, the language is useful in both contexts.

Display: the live display stack is the cosmix-comp compositor (chapter 16) plus the CTK toolkit (the 2026-07-30 Bevy+CTK decision; CTK's widget surface is out of chapter 16's scope); native CTK apps draw themselves. Chapters 01b and 05 — the ABP ui.* display protocol — are retired (2026-08-16; ui.* left ABP at the control-plane pivot) and kept as dated history. Chapter 06 remains the display-model "Intuition" chapter (visual language, interaction model, composition patterns), shared with the North Star's tiers; the accepted design-system contract is chapter 19.

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.

On 2026-08-05 this index was refactored (v0.4.0) to carry the North Star: the renderer reconsideration opened 2026-04-25 closed with the Bevy/Smithay decision proven live in cosmix-comp, and the index's role widened from navigation to the standing gate every new and revisited decision passes through.

Later the same day, v0.4.1 became the first exercise of the North Star's own amendment mechanism: the render plane changed from a scheduled dual path (scenic + utility + scanout bypass) to Bevy-first with tripwire-admitted alternates — all render effort concentrates on the scenic engine; alternate engines are built only when journaled evidence (wedge rate, stalled upgrade, measured power) demands them, through seams principle 1 keeps warm. Decided by Mark, 2026-08-05.

v0.4.2 (same day) replaced the niri-inspired "zoomable strip" workspace wording with the canvas model: per-output bounded 2D canvases, free X-Y panning, and workspaces re-founded as places — camera bookmarks with per-place layout policy, addressable over the bus, projected to guests as ext-workspace-v1 workspaces. Restores the X-virtual-root / Amiga-screens spatial lineage on modern machinery; lands within roadmap phase 3. Decided by Mark, 2026-08-05.