Introduction

Aether is a pre-1.0 application engine built for games, tools, and other interactive systems. A thin native substrate hosts wasm and native actors; actors communicate by typed mail. An external operator can start engines, load and replace code, send mail, inspect live contracts, capture frames, and gather evidence without linking into the runtime.

The subject of this book is that engine: the actor SDK, the capability crates, the chassis profiles, and the test harnesses. Several applications built on it also live in this workspace, the release demo among them, and they appear here as consumers of the engine surfaces, not as part of them.

The operator is often an agent, but the architecture is not a private dialect for one model or harness. The same explicit, discoverable surfaces should make sense to a human contributor, a test harness, a game client, and different agent runtimes.

What is unusual

Three choices explain most of the system:

1. Everything important crosses a mail boundary. A filesystem read, draw request, component load, audio note, and game intent are addressed typed messages rather than hidden host calls.
2. Native services and wasm code share the actor model. The substrate owns privileged resources; application/product logic stays replaceable and observable above it.
3. Operation is out of process. MCP and the hub make a running engine inspectable and mutable while preserving process isolation and restartability.

Read Why Aether is shaped this way for the design pressure and Architecture overview for the map.

Start by task, not chronology

How to use this guide explains source authority, maturity labels, and how the chapters fit together.

The documentation layers

No single prose file is authoritative for every question:

• Current code and tests define implemented behavior.
• Accepted ADRs preserve architectural intent and rejected alternatives.
• The active surface contract defines repository workflow: Codex uses AGENTS.md and .agents/skills/; Claude/headless surfaces use their own checked-in contracts.
• The live MCP schema and engine inventory define current tool arguments and one engine's actual kinds/handlers.
• This guide connects those facts into concepts, task paths, and change routes.

Proposed ADRs are proposals even when partial code exists. Superseded ADRs are history even when an old type name remains. The ADR map teaches that distinction.

Written for agents, readable by people

Agent-first documentation needs bounded pages, explicit prerequisites, exact source routes, failure models, and honest uncertainty. Human-readable documentation needs motivation and a coherent narrative. This book aims for both: prose explains why a boundary exists; tables and checklists make the next action easy to locate.

System pages avoid duplicating volatile function signatures. Use them to find the owner and invariant, then verify the exact type/tool against source or live introspection.

Tutorials are API pressure

A callable surface should support a short, truthful path from intent to result. If a recipe requires private archaeology, fake parameters, or unexplained special cases, either the recipe is stale or the API is too difficult to use. Fixing documentation is therefore part of API review, not polish after the design freezes.

The recipes are worked examples. The system chapters remain the conceptual contract, and current code remains the implementation authority.

How to use this guide

Aether is easiest to understand from the outside in. Start with the operation you need to perform, learn the contract at that boundary, and only then descend into the runtime that implements it. The book is arranged to support that order.

Pick a path

The foundational chapters explain durable concepts. System chapters explain the public contract and route you to implementation. Recipes are worked examples, not the canonical definition of an API. Runtime-internals pages such as the scheduler are useful when changing the engine, but they are not required to send mail or author an ordinary component.

Match authority to the question

Documentation is a map of a moving pre-1.0 codebase. No universal ranking can decide every disagreement because the sources own different questions:

• The current user or repository owner request owns intent and permission.
• Current code and tests own what the checked-out revision implements.
• Accepted ADRs and their amendment chain own architectural rationale. A Proposed ADR is a proposal, not proof that its design ships; a Superseded ADR is history.
• The active surface contract owns how an agent works in the repository. Codex reads AGENTS.md, .agents/skills/, and the live tool schema. Claude surfaces use CLAUDE.md and .claude/. Do not translate commands between harnesses by syntax alone.
• Live introspection owns the state of the selected running engine. describe_kinds, describe_handlers, describe_component, and bounded probes are better evidence than a static list when a component or chassis selection can change the answer. describe_transforms is different: it reports the static transform set linked into aether-mcp, with no engine selector.
• This guide explains and connects those sources. If it has drifted, fix it in the same change as the code when practical.

Classify the disagreement as intent, implementation, rationale, workflow, or live state before choosing the authority. The full matrix is in Sources and live reference.

Read maturity literally

Aether has implemented code behind some Proposed ADRs and old code described by some Superseded ADRs. These facts are separate:

• ADR status says whether the decision is accepted.
• Implementation status says whether code exists today.
• Chassis availability says whether a particular binary links and enables the capability.
• Runtime state says whether a particular engine loaded or configured it.

This guide labels proposals where they matter and avoids presenting source presence alone as a stable product contract.

Use links as change routes

System pages end with implementation and decision routes. When making a change, follow all three:

1. read the public kind/config definitions;
2. read the native or wasm runtime that handles them;
3. read the accepted ADRs that own the invariant.

Search the current tree before trusting an exact path printed in prose:

rg --files crates docs/adr | rg 'http|component|0138'
rg -n 'struct HttpServerConfig|export!' crates

For a behavioral change, also find tests and callers. A type can be public while the useful contract is enforced in a derive macro, a chassis builder, an MCP adapter, or an integration fixture.

Keep operator and engine identities separate

Examples use several identifiers that are not interchangeable:

• an engine id selects one substrate supervised by the hub;
• a mailbox name selects an actor within that engine;
• a kind name selects the message contract;
• a component selector selects stored wasm bytes or an exported actor;
• a binary selector selects a stored chassis executable.

Use the typed or named surface accepted by the active tool. Do not substitute a host path where a registry selector is required, or a component name where a mailbox lineage name is required. The glossary and capability index are quick reminders.

A documentation rule for agents

Do not merely make a page longer when a subsystem grows. Add a focused subpage when readers need a different prerequisite, task, failure model, or source route. Keep the parent page as a map. That makes the book usable both as a human narrative and as bounded context for an agent.

Repository map

The workspace is layered. Most changes should move down this list only as far as their responsibility requires.

wire/schema/identity/math foundations                 aether-data, aether-codec, aether-math
mail runtime, wasm host, scheduler, chassis traits    aether-substrate
native services and their public mail contracts      aether-<capability> crates
guest actor authoring SDK                             aether-actor
process profiles, binaries, packaging     aether-chassis, aether-chassis-*
operator bridge                                       aether-mcp
test harnesses                                        aether-harness-*
procedural macros                                     *-derive crates
reusable guest actors shipped with the engine        aether-kit
journal-driven programs and reactors (bloomery)      aether-bloomery-*

The list is also the order to read it in. Everything above aether-kit is the engine; the remaining rows hold consumers that happen to live in the same workspace.

Foundation crates

The capability-local ownership rule matters. Render, audio, filesystem, HTTP, and other capability messages live under the owning capability's own crate, aether-<capability>/src/kinds.rs; do not put every new native message into aether-kinds.

Actor authoring crates

Use a component when code needs actor state, typed handlers, replies, or a first-class mailbox. The extension-point guide compares this with native capabilities.

Runtime and process crates

The substrate is mechanism. A capability is policy and I/O represented as an actor. A chassis chooses which capabilities and drivers form a process. The hub supervises engine processes; it is not the engine runtime folded into a tool server.

Product and geometry crates

These crates are valuable examples, but “in tree” does not mean “native.” The aether-kit crate is actor code hosted by the same component machinery available to other guest modules.

Bloomery crates

The bloomery is a journal-driven engine built in this workspace: an append-only journal of typed events drives stateless wasm programs and journal-following reactors. aether-chassis-bloomery mounts the journal and the bundle driver on the aether-bloomery binary.

Derive, fixture, and tooling crates

aether-http-derive, aether-data-derive, and aether-derive hold code generation shared across the workspace. When a source annotation appears to do more than its local file explains, inspect its derive implementation and expanded tests.

Test-only packages are grouped by role rather than maintained here as an exhaustive crate ledger. aether-test-fixtures-* packages provide deliberately small wasm/native artifacts for replacement, capability-split, boot, and multi-actor contracts. aether-subscribe-ui-tests is the narrow trybuild host for the publisher gate on the lifecycle and window subscribe surfaces. Derive crates also keep their compile-pass/fail fixtures beside the macro they exercise. These are often better executable examples than an old prose snippet.

xtask owns repository automation such as distribution and bundle assembly, and import-commit, which stages one commit's tracked files as a Bloomery journal tree. The standalone fuzz/ crate is excluded from the stable workspace because it uses the nightly fuzzing toolchain.

Other load-bearing directories

Route a change before editing

Start with rg across callers and tests. Crate boundaries communicate intent, but the contract may cross a macro, registry, chassis, and tool adapter.

First live-engine session

This walkthrough establishes the smallest useful operator loop: connect to the hub, own an engine, inspect its vocabulary, gather evidence, and clean up. It does not require a custom component.

1. Start the stable front door

From the repository root:

scripts/ensure-tunnel.sh

The helper is idempotent. It keeps the MCP-facing endpoint stable while the hub behind it may restart. In Codex, the project endpoint is configured as aether-hub in .codex/config.toml. If the mcp__aether-hub__* tools do not appear after starting the tunnel, reconnect that MCP server in the active surface; a subprocess cannot add tools to an already-open agent session.

Read MCP architecture and startup before debugging ports or processes by hand.

2. Observe before creating

Call list_engines first. The result distinguishes live engines from recently departed ones. A recently dead record can tell you whether a process was deliberately terminated, crashed, evicted after missed heartbeats, or failed to spawn.

This initial read prevents two common mistakes:

• creating a duplicate engine when a suitable one is already owned by the current task;
• treating a dead engine id as a routing or schema failure.

Do not borrow an engine merely because it exists. Ownership may belong to another agent or test. Spawn a new one unless the task explicitly hands you an id.

3. Spawn and retain the returned id

Call spawn_substrate with no selector for the stored default headless artifact normally staged by the tunnel helper, or choose a stored binary by selector/attributes when the task requires a particular chassis. A bare spawn fails when that default is absent. The hub returns an engine_id; carry that exact value through every later per-engine call.

Binary selectors refer to the hub's content-addressed store. They are not host paths. Use upload_binary before selecting a binary that the hub does not already know. The same rule applies to wasm with upload_component.

Treat successful spawn as resource ownership:

spawn returns engine_id
        │
        ├── use that id for mail, inspection, capture, logs, and loads
        │
        └── terminate that id when the task is finished

4. Ask the engine what it knows

Use live discovery before composing mail:

• describe_kinds gives a best-effort kind snapshot. It attempts a live refresh but can return a prior/static snapshot if that refresh fails, so narrow by family/name and pair freshness-sensitive use with a harmless live probe.
• describe_handlers reports native receive contracts.
• describe_transforms lists the static transforms linked into aether-mcp; it does not inspect the selected engine.
• list_components shows component artifacts stored by the hub, not live instances.
• load_component returns the live lineage name and mailbox id; describe_component reports that lineage's handlers and boot contract. It is cache-first and asks the substrate by name only on a miss, so pair a cached description with a safe live probe when liveness matters.

This matters because chassis selection and dynamically loaded components change the available surface. Static docs explain meaning; explicit-engine inspection plus a bounded live probe tells you what is addressable now.

5. Perform one bounded observation

Choose evidence suited to the engine:

• actor_logs for recent structured entries from a known mailbox;
• actor_cost for per-handler execution-cost estimates;
• capture_frame for a rendered frame when the chassis has a render surface;
• send_mail_traced when you need settlement and reply evidence for one action.

The headless chassis composes no render actor, so capture_frame is refused there rather than hanging. Use a desktop or otherwise render-capable chassis when the observation requires a frame; headless remains useful for mail, logs, costs, and settlement evidence.

If you send mail, use the recipient lineage name and kind name returned by live inspection. Mailbox names and kind names are different namespaces.

6. Clean up and verify the outcome

Call terminate_substrate with the exact engine id you own. Then call list_engines and confirm it is no longer live. A recently-dead record with a termination reason is expected evidence, not a failure.

If termination fails or the process disappears first, do not guess that cleanup succeeded. Re-read the fleet and use the recovery runbook to distinguish an already-dead engine from a hub or routing failure.

Where to go next

• To load or replace wasm, read Component registry and replacement.
• To send meaningful mail, read Mail, kinds and scheduling.
• To diagnose a failure, read Inspection and debugging.
• To author the recipient, read Writing guest code.

Why aether is shaped this way

Aether is not a conventional engine that happens to have an agent bolted on. The agent-in-a-harness premise is upstream of almost every structural decision. This page states the principles out loud, because once you hold them the rest of the system stops looking arbitrary.

1. The agent is the operator

The motivating image is an agent sitting in a harness as assistant, engineer, and designer — driving a running engine, observing it, and modifying it. That is not a feature; it is the load-bearing constraint. A native substrate owns the things only native code can own — I/O, the GPU, audio — and hosts a WebAssembly runtime. Everything above the substrate is an actor, and the agent reaches in from outside through a stable tool surface (MCP) to make things happen.

Consequences that follow from taking this seriously:

• The control surface is out-of-process and restartable without dropping the agent's session (ADR-0089). The agent must be able to rebuild and relaunch the volatile backends mid-task and keep its connection.
• Observation is first-class. The agent can capture a frame, read an actor's logs, and trace a mail chain — because an operator that can't see can't act.

2. Everything is mail

Actors do not call each other. They send mail (ADR-0002). A piece of mail is a typed payload (a kind) addressed to a mailbox. This is the single most pervasive decision in the system, and it buys:

• A uniform boundary. The same mechanism carries a tick event, a draw command, an audio note, a file write, and a request to load a component. There is one thing to learn, not twelve.
• Location independence. A mailbox might be a native capability, a wasm component, or a peer on another process reached through the hub — the sender addresses it the same way. Mail bubbles up to the hub when it isn't local (ADR-0037).
• Observability for free. Because all interaction is mail, the tracing and settlement machinery (ADR-0080/ADR-0086) can watch all of it without each subsystem opting in.

Mail is fire-and-forget by default. A handler promises nothing about a reply; if a reply matters, that's a separate, explicit contract — never an implicit "every kind has a response."

3. The substrate is thin; the engine is actors

The native base layer is deliberately small. It owns I/O, GPU, audio, the mail scheduler, and the wasm host — and little else. Game and tool behavior lives above it, as actors (ADR-0034/ADR-0035/ADR-0073). Two kinds of actor, one model (ADR-0074):

• Native chassis capabilities — render, audio, file I/O, input, the component loader. Compiled into the substrate.
• Wasm components — your logic, loaded at runtime and hot-swappable.

They are the same actor model, addressed the same way. A component talks to the renderer exactly as one native capability talks to another. The symmetry is intentional and defended: prefer a design that treats wasm and native uniformly over one that special-cases the target.

The chassis is composed, not monolithic — a builder assembles the capabilities a given deployment needs (ADR-0070/ADR-0071), which is why several chassis share one runtime: desktop, headless, hub, and substrate-harness.

4. Design for machine consumers

The surfaces are built to be legible to an LLM, which is not the same as being legible to a human. Where human API design prizes terseness and DRY, aether's surfaces prize being regular, explicit, self-describing, and repetition-tolerant:

• Kinds carry their own schema (ADR-0031/ADR-0032) and ids are type-tagged on the wire (ADR-0064/ADR-0065), so a tool result can be handed back verbatim and a kind can describe itself.
• Prefer explicit nulls over absent-field semantics — every option addressed in a payload, because verbosity is nearly free for a machine caller and ambiguity is not.
• The vocabulary is introspectable live: an agent can ask the engine what kinds exist, what a component handles, and what transforms are linked.

5. ADRs are the memory; tutorials are the proof

Two habits keep the system honest as it grows:

• Load-bearing decisions are recorded as ADRs (ADR-0001) — numbered, reviewed like code, and cited from the code and from this guide. An Accepted ADR is the durable "why"; Proposed records do not govern, and Superseded records point to their replacement. Current code decides what is implemented.
• Every callable surface ships a tutorial, and the tutorial is the sanity check. If you cannot write a clean walkthrough that a fresh agent can build from, the surface is mis-shaped — fix the design, not the words. This guide is where those tutorials live, and writing them is how the API shapes get tested. (See the recipes section.)

These five hang together. Because the agent is the operator (1), interaction has to be uniform, addressable, and observable — so everything is mail (2). Because the agent both uses and extends the engine, the line between native and wasm has to be thin and symmetric (3). Because the consumer is a model, the surfaces are explicit and self-describing (4). And because all of this drifts without discipline, decisions are recorded and tutorials prove the surfaces stay sane (5).

Architecture overview

Aether separates portable actor behavior from native resource ownership and out-of-process operation.

operator (agent, human, test, client)
├─ MCP or framed RPC → hub fleet control plane
│                         ├─ engine proxy → desktop/headless child
│                         └─ binary select/fork ──────────────┐
└─ an application's own ingress ──────────────────────────────┤
   (REST or typed RPC)                                        ▼
                                             application chassis + stores

Each hosted process composes the shared runtime layers:
 registry → mail rings → scheduler → actor handlers
                              ├─ native state
                              └─ wasm state
 lifecycle + settlement + logs/traces/cost evidence

The boundaries

Operator boundary. aether-mcp adapts task-shaped JSON tools to the same typed mail/RPC contracts other clients can use. A stable tunnel can preserve an MCP session while volatile backends restart. The hub supervises a fleet; every per-engine operation names an engine_id. An application built on the engine may add an ingress of its own, with its own chassis and stores; such a chassis does not itself own the hub's FleetServer.

Process boundary. Framed RPC carries control calls and mail between the hub and child substrates. The hub owns artifact stores and proxy/heartbeat state. Each child owns its own registry and runtime state.

Actor boundary. A mailbox selects an actor instance; a kind selects the message schema. Native and wasm actors receive through the same scheduler and reply/settlement model.

Privilege boundary. Native capabilities own files, sockets, windows, GPU/audio devices, credentials, and process control. Guest code asks them to do bounded work by mail; it does not receive raw handles.

Read Process topology and chassis and Guest, native, and wire boundaries for the detailed models.

One mail operation

1. A caller chooses an engine, recipient mailbox name, and kind name.
2. At a JSON boundary, the descriptor/schema encodes parameters into canonical wire bytes.
3. The hub/proxy routes the envelope to the selected child engine.
4. The registry resolves the recipient and kind; the scheduler queues work.
5. Generated or manual dispatch decodes the value and invokes one handler.
6. Handler mail inherits causal lineage unless deliberately detached.
7. Replies return to the caller; settlement completes when every tracked descendant and explicit hold resolves.
8. Logs, traces, cost tables, and captures provide evidence at their respective layers.

Mail is fire-and-forget by default at the actor API. Reply classes make a reply contract explicit; an operator tool may additionally wait for settlement and project replies.

Layer map

The repository map routes changes across the full workspace. Capability messages such as render/audio/filesystem kinds live with their own capability crate, not in a universal central kind catalog (ADR-0121).

Chassis composition

Four checked-in chassis profiles reuse the substrate but install different drivers and capabilities: desktop, headless, hub, and bloomery. The in-process substrate harness is a library chassis in aether-harness-substrate.

Every chassis, and the in-process SubstrateHarness, composes aether.trace and aether.inventory from the shared base, ahead of the capabilities each one chooses.

Source presence does not imply every chassis has a working actor. A chassis composes only the capabilities it serves, so a surface it cannot serve has no actor there: a component that depends on it is refused at load, and a mail to its path over RPC is answered NotPresent.

Ask the live engine with describe_handlers/describe_kinds, or inspect the specific builder in its aether-chassis-<chassis> crate.

Architecture change discipline

When changing a boundary, trace all owners:

• public kind and schema;
• marker/runtime feature split;
• native or wasm handler;
• chassis installation and config;
• MCP/client projection if task-shaped access exists;
• unit, SubstrateHarness, and process tests at the appropriate boundary;
• accepted ADR and any amendments/supersession.

Use Choose the owning extension point before adding a new layer.

Process topology and chassis

Aether uses the word engine for an actor runtime, not for every process in the operator stack. A normal agent-driven session has several boundaries:

agent or human client
└─ MCP → stable tunnel → aether-mcp coordinator
                               │ framed Aether RPC
                               ▼
       hub chassis ───── content-addressed binary/component stores
               ├── engine proxy ── child substrate: headless chassis
               └── engine proxy ── child substrate: desktop chassis

The tunnel keeps the client-facing MCP connection stable. aether-mcp translates tool-shaped JSON into typed Aether mail and maintains operator-side caches. The hub owns fleet supervision, stored artifacts, and routing identity: it mints each process-local engine_id and assigns it to the child proxy. Each child substrate owns an independent registry, scheduler, actor set, and live runtime state.

The four chassis profiles

The aether-chassis-* crates assemble the shared runtime into purpose-specific profiles. The exact capability set is code and feature dependent, so treat this table as intent rather than a hardcoded manifest.

Their builders live under crates/aether-chassis-{desktop,headless,hub,bloomery}. Shared runtime mechanism remains in aether-substrate; each shared native actor remains in its own aether-<capability> crate.

“Headless” is a process/profile statement, not permission to assume every capability is absent. Some capabilities have explicit headless implementations or unsupported marker actors so callers get a deterministic reply instead of a missing mailbox. Check the chassis builder and live handlers for the exact engine.

What the hub owns

The hub's FleetServer is the fleet control plane. It owns:

• spawn and termination requests;
• the live proxy set and heartbeat state;
• recently departed engine records;
• binary and component artifact stores;
• selector resolution, materialization, persistence, and eviction policy;
• routing a per-engine RPC call to the right proxy.

A FleetProxy represents one connected child. It is not the child's actor registry mirrored in full. Mail, replies, inventory queries, and lifecycle events still cross the RPC boundary.

This is why engine_id must be carried explicitly by operator tools: mailbox lineage is only meaningful within the selected engine.

What a child substrate owns

Every engine has its own:

• mailbox registry and lineage namespace;
• mail rings and scheduler state;
• native capability instances selected by its chassis;
• wasm component instances and trampoline state;
• lifecycle/settlement graph and per-actor evidence;
• configuration overlay resolved at boot.

Terminating a child destroys that live state. Uploaded artifacts live in the hub store and can outlive one engine; loaded component instances do not.

One tool call end to end

A per-engine MCP call crosses two distinct translations:

tool JSON
  → textual recipient resolution through selected engine inventory
  → engine returns the canonical path
  → schema-aware encode in aether-mcp
  → WireFrame / MailEnvelope naming the path over hub RPC
  → proxy selects engine, sends the path on as written
  → child RPC server resolves the path on arrival and proves it Live (ADR-0230)
  → scheduler dispatches typed bytes to an actor
  → reply and settlement events travel back
  → tool projects bounded JSON/evidence

Failures at these layers look different. A schema error happens before mail is sent. An unknown engine fails at the fleet boundary. An unknown recipient fails inside the selected engine during address resolution. Canonical lineage and ADR-0166 short paths share that engine-owned seam; the MCP coordinator keeps no alias table and never hashes operator paths. A handler error or non-settling descendant happens after dispatch. A path that names nothing live, or an actor still starting, is refused at the engine's RPC receipt and closes the call with ReplyEnd Err(RpcError::NotPresent) naming the path. Start diagnosis at the earliest layer supported by evidence; the recovery runbook is organized that way.

Components at boot versus after boot

The hub can stage stored component bytes and a JSON-derived config into a boot manifest for a new substrate. The child loads those components during startup and binds its RPC port only once every requested instance is live, so it is reachable only when ready. Alternatively, operator tools can load or replace components after the engine is live.

Both paths resolve registry selectors. Neither treats an arbitrary local wasm path as a component identity. Upload first, select second. See Component registry and replacement.

Distribution is a different topology

cargo xtask package produces a shippable package depot: a selected desktop or headless chassis binary alongside a content-addressed pack/ of the chosen components and their config. It is not the same thing as the development hub fleet. The depot's autoload path builds the component set at process boot without requiring an MCP coordinator or hub artifact store.

Read Distribution and packaging before changing autoload or packaging behavior.

Implementation and decisions

• Shared chassis traits and frame loop: crates/aether-substrate/src/chassis/
• Process composition: crates/aether-chassis/src/ + the per-chassis crates
• One-shot process execution capability: crates/aether-process/ (Accepted ADR-0157)
• Fleet, proxy, and stores: crates/aether-fleet/src/
• Framed RPC: crates/aether-rpc/src/
• MCP translation: crates/aether-mcp/src/
• ADR-0034 and ADR-0073: the hub as a substrate, and the runtime/chassis split
• ADR-0072 and ADR-0118: the framed RPC protocol and the workspace's own wire format
• ADR-0074: one actor model for native capabilities and wasm guests
• ADR-0089: stable tunnel boundary
• ADR-0115 and ADR-0116: binary and component registries
• ADR-0157 (Accepted): one-shot process execution capability

Guest, native, and wire boundaries

Aether does not make wasm actors call host services directly. Guest and native actors meet at the same abstraction: typed mail addressed to a mailbox. The host boundary is therefore a serialization and scheduling boundary, not a second application API.

Three layers in one interaction

Rust kind value
    │ Schema + Kind identity
    ▼
canonical wire bytes
    │ mailbox + kind ids, reply lineage
    ▼
native handler or wasm export shim

The Rust type provides authoring ergonomics. Its schema describes the portable shape. Its canonical kind identity says what operation the bytes mean. The mailbox says which actor instance should receive them.

Changing any one of these can be compatibility-significant even if the code still compiles locally.

Guest actor surface

aether-actor provides the wasm-facing authoring model:

• WasmActor and WasmInitCtx for actor initialization;
• handler annotations for typed receive contracts;
• typed actor/capability mailboxes;
• request/reply and correlation helpers;
• export! for the module's actor manifest and FFI shims.

The deployable artifact is a wasm cdylib. An accompanying rlib can expose the kinds and helpers other Rust crates need to talk to it. Runtime code is normally feature-gated so a type-only consumer does not link the implementation.

A guest measures elapsed time with ctx.now(), on WasmCtx (and so WireCtx) and on WasmInitCtx. It returns an aether_actor::Instant, and later.since(earlier) is a core::time::Duration. The call is one host import, now_nanos_p32, answered inside the handler that asks; a module built against it is refused at load by a host that lacks the import. std::time::Instant::now() compiles for wasm32-unknown-unknown and traps when called, so a component reads ctx.now() and never the std clock.

An Instant stays in the actor that read it:

• It has no schema and is no kind's field, so it cannot be mailed, saved with save_state_kind, or put in a request context. A measurement that spans two handlers keeps its start in actor state.
• A successor installed by a republish takes its own reading in init or on_rehydrate; its predecessor's readings do not carry over.
• A measured duration is not replayable. A bloomery rule must not write one into a journaled result: a restart replays the rule and measures a different duration. Durable time comes from recorded time.

Multi-actor modules need an explicit export selector

A wasm module may export several actor identities. Do not infer a selection from declaration order:

• export!(public = [Main, Helper, …]) needs the load's export selector to name one of them; a bare load is refused, naming the exports.
• A module that exports exactly one actor, export!(public = [Hello]), still loads without a selector, and only that case emits the namespace compatibility metadata (aether.namespace).

This rule prevents a harmless reordering from changing what a selector loads. It is governed by ADR-0241 §9 and enforced by the export manifest and component loader.

A boot = Boot key may join either form, as in export!(boot = Boot, public = […]). The boot type is instantiated once per loaded module whatever selector the caller names, and is not itself selectable; it is governed by accepted ADR-0147.

Native capability surface

The aether-<capability> crates represent filesystem, HTTP, render, lifecycle, audio, window, engine control, and other host responsibilities as native actors. A capability generally has:

• a marker/identity type and stable namespace;
• capability-owned kind definitions;
• a runtime-only state type and NativeActor handlers;
• configuration gated away from transport-only or wasm builds;
• explicit chassis installation.

The identity/runtime split keeps public addressing types light while allowing native state to hold adapters, devices, threads, and resource handles. See Capability module anatomy.

A native actor measures elapsed time with the same call a guest does: ctx.now() on NativeCtx and on NativeInitCtx, returning the same aether_actor::Instant. Both sides read the engine's one actor clock, so a guest's and a native actor's readings in one engine are of the same clock, and the rules for an Instant above hold on both.

Capability-local kinds

Public messages exchanged with a capability live with that capability, for example aether-render/src/kinds.rs. aether-kinds remains for genuinely upstream, cross-cutting substrate vocabulary and descriptors. This ownership, adopted in ADR-0121, gives guest crates a stable type path without turning one central crate into a catalog of unrelated service APIs.

Feature gates preserve the boundary:

• a transport/marker feature exposes types usable from wasm;
• a runtime or capability-runtime feature exposes native implementation and heavyweight dependencies;
• a chassis decides which runtime features and actors are actually installed.

Native transforms are not actor handlers

A native #[transform] is a linked, discoverable function used for bounded data conversion or folding. It appears in describe_transforms, not as an ordinary mailbox handler. The inventory capability supplies reverse names and templates for engine-local ids; it does not execute arbitrary code.

Choose a transform only when the operation is deterministic, bounded, and naturally value-to-value. Stateful ownership, I/O, scheduling, and replies belong in an actor.

Replies carry lineage, not blocking calls

Request/reply syntax does not turn actor mail into a synchronous function call. A request establishes correlation and reply expectations while the scheduler continues to own delivery. Settlement tracks descendant work so an operator can wait for a chain without making the guest directly block on a host stack frame.

When a handler crosses to a sidecar thread for blocking I/O, it must preserve the actor's reply/settlement contract explicitly. Read Concurrency and blocking and Tracing and settlement together.

Compatibility checklist

Before changing a public boundary, ask:

1. Did the kind's canonical identity change?
2. Did its schema change, including enum variants, optionality, or byte fields?
3. Does a macro generate an export, descriptor, or reply contract from it?
4. Do native and wasm feature sets still expose the same transport types?
5. Can an existing registry selector still choose the intended actor?
6. Does replacement preserve or deliberately reshape state?
7. Do MCP JSON encoding and live descriptors agree with the new schema?
8. Is an ADR required because the boundary or compatibility policy changed?

Integration fixtures under crates/aether-test-fixtures-*/ cover several load/publish and multi-actor cases. Use them before inventing a new one-off example.

Implementation and decisions

• Schema, ids, and canonical identity: crates/aether-data/src/
• JSON/wire conversion: crates/aether-codec/src/
• Guest SDK and exports: crates/aether-actor/src/
• Wasm host: crates/aether-substrate/src/actor/wasm/
• Capability types/runtimes: crates/aether-<capability>/src/
• ADR-0096: multi-actor wasm modules
• ADR-0099: actor identity and addressing
• ADR-0121 and ADR-0122: kind ownership and marker/runtime split
• ADR-0138: multi-actor module export selection (superseded by ADR-0241 §9)
• ADR-0147: the module boot actor, instantiated once per module load outside the export selector

The type system

Governing ADRs: ADR-0005 (mail typing), ADR-0019 (unified encoding), ADR-0029/ADR-0030 (name- and schema-derived ids), ADR-0099 (actor identity and addressing), ADR-0031/ADR-0032 (const schema + canonical bytes / labels sidecar), ADR-0048 (transforms), ADR-0064/ADR-0065 (type-tagged wire ids + first-class id types). The type vocabulary is stable — the wire format depends on it.

Everything the engine moves is typed, and the vocabulary is small. Three kinds of thing carry types — kinds (payloads), mailboxes (addresses), and transforms (pure functions) — and each is named by a typed id. This page is the tour: what each one is, how it's identified, and how they compose.

The reason to care isn't compiler ergonomics. A typed thing here is self-describing: it carries enough to encode itself from JSON, decode itself without a shared header, and appear in the appropriate inventory. That lets an agent inspect live engine kinds/components while separately reading the static transform set linked into aether-mcp. Typing is the substrate of observability, not paperwork.

Kinds — typed payloads

A kind is a named, sendable mail payload — a Rust type carrying a name, a stable id, and a wire encoding. You declare one with two derives and a name:

#![allow(unused)]
fn main() {
#[derive(aether_data::Kind, aether_data::Schema)]
#[kind(name = "aether.audio.note_on")]
struct NoteOn { pitch: u8, velocity: u8, instrument_id: u8 }
}

Two derives, because they describe two different things.

• Schema gives const SCHEMA: SchemaType — a description of the type's byte layout (ADR-0031) — and the owned wire codec that walks the same field list (ADR-0188). It's compositional: every type that can sit inside a payload implements it — the primitives, String, Vec<T>, Option<T>, arrays, and your own structs — so a struct's schema is assembled from its fields'. A type that only ever appears as a field of a kind derives Schema alone. Serde derives are not required to put a type on the wire.
• Kind marks the type as a top-level, addressable payload: const NAME (the declared name), const ID: KindId, and the encode/decode bodies. Kind is layered on Schema — the id is hash(name + canonical(SCHEMA)), so the derive reads the type's schema to compute it. A kind is always a schema; a schema is not always a kind.

So you write #[derive(Kind, Schema)] on a message you send, and #[derive(Schema)] alone on a helper struct that only appears as a field of one. That gives a kind three compile-time constants — NAME and ID from Kind, SCHEMA from Schema. In practice Schema is derived on far more types than Kind: every field-only struct has one, but isn't independently sendable.

Why not just fold Schema into Kind, so one derive does everything? Because a kind's schema is composed from its fields' schemas by trait dispatch — the derive emits <Self as Schema>::SCHEMA, which recurses into <FieldType as Schema>::SCHEMA for each field. For that to resolve, every field type — including nested structs that are never mailed — has to implement Schema on its own, so Schema must be a standalone derive regardless. Given that, Kind reads the schema rather than recomputing it; merging the two would duplicate the schema walk that ADR-0031/ADR-0032 deliberately collapsed into one trait-dispatched path. (It's the Serialize / Deserialize split: one trait, one derive.)

Because ID and SCHEMA are const, there is no host round-trip to learn a kind's identity or shape — Kind::ID is a compile-time value. And because the schema travels with the type, the wire layer can encode a kind from JSON and a recipient can decode it without a shared header (ADR-0019). On the wire a #[repr(C)] plain-data kind rides as a raw byte cast; everything else as a structured encoding — the derive autodetects from the type's layout, so a single send / reply call site handles both.

What feeds the id — and what doesn't. The KindId hash takes name + schema, where name is the declared kind name and schema is the structural shape — field types and positions. All nominal information (the Rust type name, field names, variant names) is erased from the hashed bytes and carried in a parallel labels sidecar instead (ADR-0031/ADR-0032). So:

This is what makes schema drift fail loud rather than silently garbage-decode — a mismatched producer and consumer compute different ids and the mail lands on "kind not found." The full contract is in Invariants & guarantees.

For the end-to-end walkthrough of declaring a new substrate kind — the derives, the self-registering descriptor, the handler, and the rebuild rule when an edit moves the id — see the Adding a substrate kind recipe.

The schema vocabulary — SchemaType

A kind's shape is a tree of SchemaType. The leaves and containers are what you'd expect — Bool, Scalar (the primitives), String, Bytes, Blob, Option, Vec, Array (fixed-length [T; N]; Vec is the variable-length form), Struct, Enum, and Map (a keyed lookup table). The arms that carry rules worth knowing beyond "it's a type tree":

• Two wire shapes, and what picks them. A struct encodes as a raw #[repr(C)] byte cast (repr_c = true) only if it is #[repr(C)] and every field is cast-eligible, recursively; otherwise it encodes as structured. Cast-eligible means a scalar primitive, a typed-id newtype other than MailboxId (KindId and friends are #[repr(transparent)] over u64), a fixed [T; N] array of cast-eligible elements, or a nested all-cast-eligible #[repr(C)] struct. A MailboxId field makes a struct structured, because a kind that names an actor carries an address rather than a cast position. A single String, Bytes, Vec, Option, Map, Enum, or Ref field anywhere short-circuits the whole struct to structured. You don't choose this — the derive computes it at compile time (CastEligible::ELIGIBLE ANDs every field) — but it's why two similar-looking kinds can have different wire encodings. The send path carries the same split: the Kind derive emits Kind::encode_into_bytes as a call to encode_cast (a bytemuck byte copy) for a #[repr(C)] kind and to encode_wire (the ADR-0118 wire body) otherwise, so a send site never picks the encoder itself.
• Map keys are restricted. A map key may only be a String, an integer scalar, or Bool — the BTreeMap<K: Ord, V> bound rules out f32/f64/ Vec/Option at the type level and the codec rejects them defensively. Entries serialize in key-sorted order, and a map (being variable-length) always forces its parent struct onto the structured path.
• The canonical bytes are positional-only. When a schema is serialized for hashing and for the aether.kinds manifest, field and variant names are dropped; a separate labels sidecar (aether.kinds.labels) carries them for consumers that want human-readable reconstruction, like describe_kinds (ADR-0032). The wire never carries names — structured fields are positional.
• TypeId is a schema arm. A kind can have a field that is an id — a MailboxId or KindId as a first-class typed reference, not just a bare u64 (ADR-0065). These encode as a tagged string on JSON and a varint on the wire.
• Blob is immutable bytes held as an aether_data::Blob (ADR-0238). Its binary form starts with a one-byte tag. Tag 0 is a u32 length and the bytes, and every codec that writes bytes writes it: files, the journal, the wire, JSON. Tag 1 is the blob's 32-byte hash, written only in in-process mail and never outside the process. The JSON codec and MCP read and write a Blob field as a plain byte array and never show the tag. A Blob is not cast-eligible, and a Blob field is a different kind from a Vec<u8> field.
• Decoding with a context. Every kind decodes through one body, Kind::decode_with(bytes, &mut DecodeCtx), which returns the value or a named wire::Error (ADR-0231 §3). The DecodeCtx offers a field two operations: resolve a tag-1 Blob hash, and prove that the route at a path, live or closed, publishes a protocol's rows. A resolved Blob is always a reference to its store entry, never a copy; tag 0 needs no context and decodes owned. Native dispatch builds the context from the inbound mail's attachments and the mail registry; a guest's context carries its blob holds and asks the host for the registry's rows, one host call per ProtocolPath<P> field. A field refuses what its context cannot prove: a tag-1 Blob with no resolver refuses DetachedBlob, and a ProtocolPath<P> refuses ProtocolPathUnchecked with no registry, ProtocolPathUnpublished when no route has stood at its path or it is still starting, and UncoveredProtocolPath when that route does not publish every row of P. A path whose actor has closed decodes, and the receiver's resolve answers that it is not live. A refused decode reaches no handler and is logged at warn. A request whose typed path refused is still answered: a kind that carries a path sets Kind::PROVES_ROUTES, its reply implements From<PathRefused> (the compiler refuses a replying handler whose reply does not), and the dispatch answers O::from(refused). A silent or unchecked row has no reply, so nothing is sent back. The plain shorthand, decode_from_bytes, decodes with an empty context. Serde carries no context, so ProtocolPath<P> has no Deserialize, and a kind carrying one is declared #[aether_data::kind(.., no_serde)].

What counts as the same kind

The canonical schema is a positional encoding: each arm becomes a type tag plus its structural content — field and variant names are dropped, but field order, array lengths, enum discriminants, and the repr_c flag are all kept. Two kinds with the same declared name share a KindId exactly when those bytes match. The "which edits move the id" matrix above lists the basics; the cases that surprise people live at the schema-arm level. Holding the #[kind(name = …)] fixed:

Still the same kind — the id doesn't move:

• renaming a field but keeping its type — { x: u32 } and { count: u32 } are identical;
• renaming the Rust struct, or renaming an enum variant while keeping its discriminant and payload shape.

A different kind, despite looking alike:

• Reordering fields — { a: u32, b: u8 } ≠ { b: u8, a: u32 }; positions are structural.
• A same-size type swap — { a: u32 } ≠ { a: i32 }, and { a: u64 } ≠ { a: MailboxId } even though both are eight wire bytes: a typed-id field is a distinct TypeId arm, not a Scalar.
• Flipping #[repr(C)] when it changes the cast/structured choice — repr_c is part of the canonical bytes, so the same fields under a different wire format are a different kind.
• Wrapping a field — { a: u32 } and { a: Option<u32> } are distinct kinds; likewise [u32; 3] ≠ [u32; 4] ≠ Vec<u32>.
• Changing an enum discriminant — discriminants are encoded; variant names are not.

Mailboxes — typed addresses

A mailbox is an address: where mail goes. Addressing rests on two ids, one per question (ADR-0099):

• An ActorId answers which actor. It is a 64-bit hash of the actor's NAMESPACE alone — hash(NAMESPACE) for a singleton actor, hash(NAMESPACE:subname) for an instanced one — with no schema in the hash, because an actor's identity is its name (ADR-0029). It names the actor wherever it is hosted, and it reverse-maps to that name for introspection.
• A MailboxId answers where in the tree. An actor sits somewhere — at the substrate root, or hosted under a parent — and its lineage is the ordered list of ActorIds from the root down to it. The MailboxId is a hash chain over that lineage (fold_lineage, one fold step per node), and mail routes to it.

For a root actor — every chassis capability — the lineage is a single node, and the fold of one node is that node: MailboxId == ActorId == hash(name), so the name hash of ADR-0029 is the depth-1 case of the fold. A hosted actor — a loaded component, a spawned child — folds its ActorId onto its parent's, so the same code under two different parents is two different mailboxes. The /-rendered addresses you see (aether.window/aether.window.instance:main) are a display rendering of the lineage, one segment per ActorId; a written path resolves by parsing it into segments and re-folding, which happens in the host registry, never by hashing the joined string.

Both ids are computed from compile-time constants with no registry lookup, so every process that holds the same names and the same lineage computes the same ids — and a component hot-swap, which changes neither, keeps the address valid. In a component you rarely touch either id directly: you address a peer by type (ctx.send::<RenderCapability>(&kind) under depends(RenderCapability)) or send through a proven reference it holds (ctx.send_to(reference, &kind)). The mailbox-vs-kind distinction — why an address and a payload shape are different things even when they share a name prefix — is the Mail, kinds & scheduling page's subject.

Transforms — typed pure functions

A transform is a pure function over typed values — #[transform] fn foo(input: A) -> B, registered at build time with a TransformId and typed by its input and output kinds (ADR-0048). Where a kind is a value and a mailbox is an address, a transform is a typed edge: it takes a value of one kind and produces a value of another. The aether.fs fetch verb runs a fold chain of them over a file's bytes; inspect the current MCP build's linked set with describe_transforms.

Typed ids — the naming layer

Every typed thing is named by a newtype over a hash, not a bare integer:

Two properties keep these from being foot-guns:

• Disjoint hash domains. A kind id and a mailbox id are hashed with different domain prefixes, so the same name produces different ids in the two spaces — the id spaces don't collide even when names are shared (ADR-0030). This is the mechanical reason a kind name and a mailbox name can look alike yet address different things. (ActorId deliberately shares the mailbox domain — a root actor's MailboxId is its ActorId, which is what keeps every chassis capability's id equal to its name hash.)
• Tagged strings on the MCP wire. Across the agent boundary, ids encode as <tag>-XXXX-XXXX-XXXX — mbx-… for a mailbox, knd-… for a kind (ADR-0064). The tag makes an id self-identifying, so a mailbox id and a kind id can't be silently swapped in a tool call. Hand these back verbatim — they're opaque tokens, not numbers to parse.

How it composes

The pieces stack: a kind describes some bytes; a schema describes the kind; a mailbox is where a kind is sent; a transform turns one kind into another; and a typed id names each so the owning inventory can report what exists. Because every one of them is self-describing, the system is inspectable from the outside — with engine-scoped and MCP-build-static views kept distinct.

Where to read more

• The contracts these types enforce — Invariants & guarantees.
• Addresses vs payloads, in depth — Mail, kinds & scheduling.

The actor model

Governing ADR: ADR-0074 (the unified actor model — capabilities and components are one model, not two) with ADR-0079 (the lifecycle stages) and ADR-0033 (the #[actor] macro), extended by ADR-0096 (a wasm module exports several actor types), ADR-0114 (a component spawns inline children), and ADR-0099 (actor identity and addressing), plus ADR-0166 (declared placement permissions). This model is stable; it's the spine everything else hangs off. Signatures here were read from the current SDK (aether-actor) and runtime (aether-substrate).

The engine is built from one kind of thing: the actor. The renderer, the audio mixer, the filesystem, a component you load — all of them are actors, with no privileged class of "system object" sitting above them. Everything in the substrate is an actor, and the only way actors ever interact is by mail.

If you understand actors, most of the engine follows: every subsystem in this guide is some actor (or a handful) doing a job. This page covers the actor itself — what it is, the lifecycle it moves through, how you write one — and the two hosts it runs under, native capabilities and wasm components.

What an actor is

An actor is some private state paired with a set of typed handlers. It sits idle until mail arrives; when an envelope lands, the handler registered for that kind runs with exclusive &mut access to the state, updating it and sending mail of its own. Nothing happens except in response to a message.

Two properties make it tractable to reason about:

• Actors communicate only by mail. No actor holds a reference into another actor's memory, calls another's methods, or shares a lock with it. The only way to affect another actor is to send it a kind it handles. This is what lets the same model span an in-process capability and a sandboxed wasm component without either knowing which it's talking to — mail is the only coupling, so the host is an implementation detail. (See capability = reachability for the security consequence.)
• An actor only ever runs on one thread at a time. The scheduler guarantees no two threads run an actor's handlers at once, so an actor can freely mutate the data on its own struct — its state is plain fields, no Mutex, no RefCell, no atomics, just ordinary sequential Rust. (How the scheduler enforces this — the run-token — is the concurrency page; here, take it as a guarantee you can build on.)

What flows between actors — the kinds, their ids, the wire encoding — is the type system. How it routes and in what order — mailboxes, FIFO, fire-and-forget — is mail & scheduling. The rest of this page stays with the actor on the receiving end: how it's built and how it runs.

The lifecycle

Every actor — regardless of host — moves through the same three authored stages (ADR-0079). Each stage gets a different context, and the context is the contract: it's exactly what you're permitted to do at that point.

The three stages exist because constructing an actor and letting it participate in the mail system are different moments, and only the second is safe to send from. init runs while the actor is still being built: its mailbox isn't published yet, peers may not have booted, and it returns Result<Self, ActorInitError> so a failure aborts the load cleanly. Sending mail from there would mean announcing yourself before you're addressable, or mailing a peer that doesn't exist yet. So init stays a pure synchronous constructor — resolve kind ids and mailbox addresses, assemble state, return it (or fail with an ActorInitError that surfaces instead of leaving a half-built actor behind).

wire is the first point where sending is safe. It runs once init has succeeded, the mailbox is live, and the chassis is past its boot barrier, so peers are addressable and replies can route back. That's why mail-driven setup lives here: subscribing to the tick or input streams, announcing yourself to a peer, starting a poll loop by mailing yourself. An actor that needs to subscribe at startup would have nowhere safe to do it if init were the only hook.

wire returns the same result type init does, Result<(), ActorInitError> for a component and Result<(), BootError> for a native actor, and a hook that fails fails the birth (ADR-0247 rule 3). Whoever asked for the actor is told: a load or spawn answers Err with the hook's message, a boot manifest entry fails the build, a parent's staged spawn completes with SpawnError::WireFailed, and a composed capability fails the chassis build. The actor never goes live. Because the hook was entered, unwire still runs before the actor drops, and mail the hook sent from a birth that holds its outbound mail is discarded with it. A guest that traps in wire fails its birth the same way, except that no more of its code runs, unwire included. Every hook is written with the return type and ends in Ok(()); #[actor] refuses one without it.

unwire is the mirror at the other end, and it exists for the same reason in reverse — teardown often needs to send, whether that's a closing broadcast, a signal to monitors, or a final flush to a peer, and Rust's Drop can't reach cleanly into the mail system. It runs after the inbox has drained but before the actor drops, so its sends still land in live peers (mail to one that's already gone warn-drops). It absorbs what used to be a separate on_drop hook.

What an actor wired, it unwires: unwire runs on every exit the engine takes (ADR-0247 rule 5). That is the actor asking to close (ctx.shutdown(), or a component's aether.component.drop), a birth cancelled after wire ran, a boot that rolled back, and engine teardown, where an actor sitting idle is woken to run it. So whatever wire acquired can be released in unwire and relied on to be released. Only a process that is killed or aborts skips it. At teardown the engine settles a closing actor's held replies without answering them, since every requester is closing too.

Both hooks are optional: wire defaults to Ok(()) and unwire to a no-op. Override them only when you have mail-driven setup or teardown to do.

The context

Every lifecycle method and handler is handed a context (ctx) — the actor's only handle to the world outside its own state. Through it the actor resolves addresses, sends mail, and replies to whoever sent the current message; depending on where it's running it can also spawn a child actor, persist state for a successor, or ask to shut down. Anything that reaches past the actor's own fields goes through the context, and you never construct one — the runtime passes it in for the duration of a call and takes it back when the call returns, so an actor touches the world only while a handler is running, never through a stashed handle.

There's more than one context type because what an actor is allowed to do changes from stage to stage, and the type is how that's enforced. The context handed to init can resolve addresses but has no send method at all — so "init can't mail" isn't a rule you have to remember, it simply won't compile. wire, handlers, and unwire get a context that can send and reply; the hot-swap hooks get one that can persist state. That's what "the context is the contract" means literally: the method you're in determines which context type you hold, and that type determines what compiles.

Host matters as well as stage. Resolving, sending, and replying are common to both; a few operations are host-specific. A native capability can spawn any instanced child actor and ask to shut itself down. A component creates children inline — instances of the other actors its own module exports, co-located in its wasm instance (ADR-0114, and the cardinality section below) — while its own load, drop, and replace are driven from outside. The concrete context types differ by host too — WasmInitCtx/WasmCtx in a component and NativeInitCtx/NativeCtx in a capability. Lower-level resolver/sender traits support shared helpers, but actor lifecycle signatures use the concrete context for their host and stage.

Authoring an actor

You declare the receive side with the #[actor] attribute on one impl block, and each #[handler::<class>] method is a handler — the macro infers the kind it handles from the method's third parameter:

#![allow(unused)]
fn main() {
#[actor(root, depends(LifecycleCapability, RenderCapability))]
impl WasmActor for Hello {
    const NAMESPACE: &'static str = "example.hello";

    fn init(_ctx: &mut WasmInitCtx<'_>) -> Result<Self, ActorInitError> {
        Ok(Hello)
    }

    fn wire(&mut self, ctx: &mut WireCtx<'_, '_>) -> Result<(), ActorInitError> {
        ctx.subscribe::<LifecycleCapability, Tick>();
        Ok(())
    }

    #[handler::event]
    fn on_tick(&mut self, ctx: &mut WasmCtx<'_>, _tick: Tick) {
        ctx.send::<RenderCapability>(&TRIANGLE);   // draw every tick
    }

    #[handler::request]
    fn on_ping(&mut self, _ctx: &mut WasmCtx<'_>, ping: Ping) -> Pong {
        Pong { seq: ping.seq }
    }
}
}

Ping is the kind on_ping handles; Tick is the kind on_tick handles. The macro reads those parameter types and generates the dispatch table that routes an inbound envelope to the right handler by matching its kind id — a compile-time const (K::ID), so there's no runtime registration and no host round-trip to resolve an address. A handler with no match falls through to an optional #[fallback] (taking the raw Mail<'_>); omit the fallback and the actor is a strict receiver — unhandled kinds are reported, not silently dropped.

You address peers by type — ctx.send::<RenderCapability>(&payload), on a ctx whose actor declares depends(RenderCapability), compiles only if that actor actually handles the payload's kind, and both the mailbox id and kind id resolve at compile time. The handler takes the decoded mail by value and gets &mut self because nothing else can touch the state concurrently.

Declaring placement

Actor identities declare where they may legally appear with root and child_of(...) arguments on the same #[actor] attribute:

#![allow(unused)]
fn main() {
#[actor(singleton, root)]
pub struct ComponentManager;

#[actor(instanced, child_of(ComponentManager, TestComponentManager))]
pub struct ComponentWorker;
}

root implements the Root marker: the actor may be placed without an actor parent. child_of(A, B, ..) is one list, written once, as depends(..) is: it becomes the actor's Declared::Parents, and each entry implements ChildOf<Parent> at its position in that list and records one permitted direct parent edge. A hand-written ChildOf impl does not compile, so the list is the actor's whole placement set. An actor may be both a root and a permitted child.

Parentless native entry points consume that permission as a compile-time bound. Chassis composition (Builder::with_actor and with_actor_configured), chassis-level instanced spawn, pumped-actor boot, and the matching test and harness adapters all require Root beside their existing native actor bounds. A child-only actor therefore cannot cross one of those root placement surfaces, but remains valid through typed child placement such as NativeCtx::spawn_child, where its declared ChildOf<Parent> edge is checked instead. No runtime metadata lookup is involved in either check.

A wasm actor declares placement with the same arguments — root, instanced, root, instanced, child_of(P), or instanced, root, child_of(P) (ADR-0241 §5) — but the permission is checked at run time, from the module's aether.actor.lineage section. root writes a Root record for every cardinality, and it is the permission the component host checks when it loads the type at itself, boots it as its module's boot type, or publishes a module whose boot type it is: each is refused with the operation's Err, naming the type and the placements it does declare, before the module publishes or anything is staged. A child_of(P) record never satisfies it. A spawn naming a parent is checked the same way against a child_of(P) record naming the proven parent's type. A loaded guest is named as a native actor is — NS, NS:key, or parent/NS:key — so a wasm root emits the same Root marker impl a native root does.

These are placement permissions, not runtime facts. They do not say that an instance is live, that a parent owns or supervises a child, or that the actor has singleton versus instanced cardinality. The actor's own Addressable::NAMESPACE remains the only namespace declaration; generated native inventory and wasm manifest records derive names and type tags from the actor types rather than copying string literals.

TCP uses multiple parent permissions because accepted and outbound sessions have different real lineages:

#![allow(unused)]
fn main() {
#[actor(singleton, root)]
pub struct TcpCapability;

#[actor(instanced, child_of(TcpCapability))]
pub struct TcpListenerActor;

#[actor(instanced, child_of(TcpCapability, TcpListenerActor))]
pub struct TcpSessionActor;
}

The two permitted lineages give an accepted session and an outbound session with the same name distinct identities. The lineage is chosen where the session is spawned: the listener spawns accepted sessions beneath itself, and the capability spawns dialed sessions directly beneath itself. A consumer reaches either one through the stamped sender of the session's own mail, never by naming it.

ChildOf therefore does not choose one global parent for an actor type. It is checked where a child is placed (spawn_child) and where an embedder looks one up (child::<P, C>), and the parent at that point supplies the canonical lineage and identity fold.

External actor addresses

Rust actor code continues to resolve peers by type. String-addressed boundaries such as MCP, configuration, and harness calls may additionally use an ADR-0166 short path rooted in an actor namespace:

aether.window/:main

The substrate expands that spelling from the generated Root and ChildOf inventory before it performs the ordinary canonical registry lookup. With the window capability's one instanced child family, the address above expands to:

aether.window/aether.window.instance:main

The same expansion reads every published module's lineage (ADR-0241 §5): its #[actor(root)] exports, each exported and private type's cardinality, and its child_of(..) edges. The index is rebuilt in the registry-owner apply that publishes a module, and a module's facts about a native namespace are ignored, so a module never changes a native short path.

A loaded component needs no short path to reach it: it is named by its own namespace, so its canonical address is already short (aether.kit.mesh, or aether.kit.camera:main for an instanced one). Its children are reached by a hole beneath it: game.world/:north/:gate for an inline child and its own inline child, or game.world/:k for a guest a Spawn with parent placed at game.world/NS:k. A parent that several instanced child types list in their child_of(..) has several candidates for a hole, and the hole fills with whichever of them holds its key live.

A path is /-separated steps. After the root, a bare step always names a singleton child, namespace:discriminator names an instance of that instanced child, and :discriminator is a hole naming an instance of the one instanced child declared under the current actor. A path with no hole is canonical and never consults the declarations; a path with a hole is short, and its first step must be a bare root namespace. A hole fills directly when the current actor has exactly one logical instanced-child namespace. If several are declared, the declarations bound the candidates and liveness picks among them: the hole fills with the one candidate whose canonical path parent/namespace:discriminator is live, and later holes expand beneath it. None live is a no-live-candidate error; two or more live is an ambiguity error, since a key is unique per type rather than per parent. Both list every explicit namespace:discriminator step the caller can use. Nothing is remembered between uses, so such a short path names whatever holds its key at the moment it is resolved; store the canonical path it expanded to when the reference must stay put. The older :// spelling is refused with an error naming the hole form.

Short paths are boundary input, never actor identity. The registry expands them before hashing and stores, lists, and reverse-reports only the canonical path. Unknown roots, illegal segments, ambiguous children, a hole with no live candidate, path-limit violations, and a valid expansion with no live mailbox remain distinct resolution errors.

At the boundary the text becomes an aether_data::ErasedActorPath. Its grammar is checked when it is built or decoded, so a malformed address fails there rather than in the engine; it is stored as written, holes included; and it becomes a position only in the engine's resolve_address, which fills holes and checks liveness.

Reply classes

A handler declares how it answers through its class marker (ADR-0112, ADR-0134). The single class answers 0-or-1 through its return value — -> R sends R back, -> () sends nothing — and four words spell it, each naming why the handler's mail arrives:

#[actor] checks each signature against its word, and each refusal names the word that fits: a request that returns nothing is a tell, event, or response, and a tell, event, or response that returns a value is a request. The words take no arguments. tell and event expand identically: the macro cannot see whether a kind arrives through a subscription, so event records the author's intent. None of the four is published — the inputs manifest and the contract rows see only the single class and the return type. #[handler::single], the older spelling, is refused with an error naming the four words (#7202).

A response takes the context its request stored with send_with_context as an optional fourth parameter (ADR-0243 §10). The dispatch arm takes it before the call. With context: C, a reply that arrives without a C — an uncorrelated mail of the reply kind, a context stored as another kind, or none stored — does not run the handler: the arm logs an error in the actor's own log ring, naming the handler, the reply and context kinds, and the request id, and counts the mail as handled. It never panics, because any sender can send the reply kind. With context: Option<C>, the handler runs either way and receives the take as it is. A response with no fourth parameter may still call ctx.take_context itself, for example to try several context kinds in turn.

A tell or a request states what its sender must handle in its ctx type, as the ctx's sender: the ctx's type arguments are receiver, sender, mode (ADR-0231 §11). A receiver that mails its sender back later, such as a session that delivers frames to whoever dialed it, needs the sender to handle those kinds, and this is where it says so:

#![allow(unused)]
fn main() {
#[handler::tell]
fn on_take_focus(&mut self, ctx: &mut WasmCtx<'_, Self, FocusHolder>, _take: TakeFocus) {
    let holder = ctx.sender(); // ProtocolRef<FocusHolder>
    self.holder = Some(holder);
    ctx.send_to(holder, &FocusGained);
}
}

The one type argument drives two checks. At build time, an actor sends this kind with the plain ctx.send::<Window>(&TakeFocus) only when it has a handler for each of FocusHolder's kinds; one that lacks a handler gets an error naming it, and nothing is added at the call site. At receipt, the engine casts the sender to FocusHolder before the handler runs, and ctx.sender() is then the proven ProtocolRef<FocusHolder>, with no Option and no ctx.cast. Mail the build cannot see, such as a call relayed from MCP or mail with no sender, fails that cast and never reaches the handler: the refusal is logged in the receiver's log, a tell relayed by aether.rpc.server ends its call with the refusal, and a request is answered with its own reply, built from a PathRefused naming the sender, so a request that states a sender replies a kind that is From<PathRefused>. A kind whose handler requires something of its sender is not sent through a ProtocolRef: a protocol's rows are covered only by handlers that ask nothing. A handler that states nothing keeps Anyone, whose ctx.sender() is an Option<ErasedActorRef>. A helper that a stating handler passes its ctx to takes the sender as a type parameter, as it takes the actor: fn dial<A, S>(ctx: &mut NativeCtx<'_, A, S>, ..). A sender is refused on an event, a response, an unchecked handler, a Departed<W> handler, a batched &[K] handler, a handler in a set, a #[fallback], a task completion, and a lifecycle hook, and a reply mode written in the sender's position is refused with the corrected spelling.

The unchecked class (#[handler::unchecked(reason = "…")]) takes an Unchecked ctx and issues its own replies by hand (ctx.reply / ctx.reply_to), which the engine does not check. It gives up the reply check, so it is only for a handler that replies more than once, replies from outside the actor, or relays a request, and its reason says which: the reason rides the inputs manifest and the native handler inventory, and describe_component / describe_handlers show it beside the row. It is never a default — a handler that never replies to its own inbound mail is a tell, event, or response with a silent -> ().

A request that answers one exact kind in a later turn returns -> Pending<R>. The offload dispatch calls mint that receipt for work a worker finishes; for a reply no worker produces, ctx.hold::<R>() returns the Pending<R> with a move-only Held<R> ticket, which the actor keeps in state and answers with exactly one R through Held::answer, from any later handler (ADR-0243).

A bounded many-item answer is one reply whose kind carries a list, as the log, trace, and cost tails do. Incremental or unbounded delivery publishes to subscribers (Publishes<K> / subscribe).

#[actor] records each handler's answer as a type-level contract row, impl Contract<K> for A { type Reply = …; type Sender = …; type Index = … }: the reply kind O for -> O or -> Pending<O>, Silent for -> (), and Undeclared for an unchecked handler, and as Sender the protocol its sender parameter names, or Anyone when it takes none. Each row names its position in the actor's one type-level row list, Contracts::Rows, so a row exists only where a handler does: a hand-written row for a kind the actor does not handle does not compile, and a handled kind of a public actor is declared pub (ADR-0231 §10). It also emits Contracts::CONTRACTS, the same rows as (KindId, ReplyContract) pairs in the vocabulary the inputs manifest and the native handler inventory report, with an adopted handler set's rows appended. A #[fallback] contributes neither. The reply checks ADR-0231 specifies are built on them. A route publishes its actor's rows, and whether it has a #[fallback], on its route record when it goes Live: a native actor its own, a wasm component its guest's (republished on replace), and an inline child's alias its own type's.

A protocol names a set of contract rows under a stable type, independent of any implementation (ADR-0231 §2). #[protocol] on a trait of signatures declares one: each method is a row, -> O single and no return silent, and the explicit return -> Undeclared unchecked. The trait becomes a unit struct whose impl Protocol lists the rows as type Rows = (Row<K, O>, …). MeshLoader: CoveredBy<R> holds when the target R has a contract row for every kind with the exact reply, from a handler that asks nothing of its sender. Rows match by kind, never by method name; a #[fallback] has no row and an unchecked handler's Undeclared row covers only an explicit unchecked protocol row. That row promises the target handles the kind without imposing a reply-handler obligation on the sender. Coverage is sealed: aether-actor computes it from Rows, and a hand-written CoveredBy impl does not compile. RowSet::CONTRACTS on the rows is their list in the same (KindId, ReplyContract) vocabulary as Contracts::CONTRACTS.

#![allow(unused)]
fn main() {
#[protocol]
pub trait MeshLoader {
    fn load(mail: LoadMesh) -> MeshLoadResult;
    fn set_mode(mail: SetMode);
    fn forward(mail: Forward) -> Undeclared;
}

// is the declaration
pub struct MeshLoader;

impl Protocol for MeshLoader {
    type Rows = (
        Row<LoadMesh, MeshLoadResult>,
        Row<SetMode, Silent>,
        Row<Forward, Undeclared>,
    );
}
}

Typed paths

An actor names another actor by type in what it stores or sends through a typed path: ActorPath<R> names an R, and ProtocolPath<P> names an actor covering the protocol P (ADR-0230 §2, ADR-0231 §3). An actor writes an ActorPath<R> with one of two type constructors, whose bounds check the topology at compile time. ActorPath::<R>::instance(&key) compiles for a root instanced R (R: Root + Instanced) and writes R::NAMESPACE:key. ActorPath::<C>::child(&parent, &key) compiles for an instanced C declared beneath the parent's actor (C: ChildOf<P> + Instanced) and writes <parent>/C::NAMESPACE:key; it refuses only a path past the depth or byte cap. Each step is a type's NAMESPACE and its key, so the text is the canonical name the registry gives that instance, and writing it reads no registry. path.narrow::<P>() keeps the text under the narrower claim and compiles only for P: CoveredBy<R>.

Both paths are kind fields, carried as the path text with ErasedActorPath's schema. Decoding either accepts only a well-formed canonical path, and decoding an ActorPath<R> also refuses a path whose leaf namespace is not R::NAMESPACE, so an ActorPath<R> that exists names an R. A decoded ProtocolPath<P> is checked against the mail registry's published contract for the route at its path, live or closed: the decode refuses a path no route has stood at, one still starting, or one whose route does not publish every row of P, so a ProtocolPath<P> that exists names an actor, live or closed, covering P. A refused decode reaches no handler. A request whose path did not prove is still answered: its reply kind implements From<PathRefused>, and the dispatch answers O::from(refused) naming the path and why, while a silent or unchecked row drops the refusal with a warn. A request kind carrying a path whose reply lacks From<PathRefused> does not compile. Native dispatch decodes with the registry, and a guest's decode asks it through one host call per path field (route_rows_p32), so a guest proves and refuses a ProtocolPath<P> as a native receiver does, in mail, in its config, and in saved state. A kind with no protocol path makes no host call. Neither path grants a send: a closed actor's path decodes, since names are never reused, and the route can leave after the decode, so its receiver's resolve proves that a live actor stands at the path and the handler answers the closure itself. The first consumer, a Bloomery unit's driver, is to write its journal's storage source this way (ADR-0240 D7):

#![allow(unused)]
fn main() {
let source: ProtocolPath<ArtifactStorage> =
    ActorPath::<JournalActor>::instance(&unit_key).narrow::<ArtifactStorage>();
}

A native actor that receives a ProtocolPath<P> proves it with ctx.resolve(&path), which returns a ProtocolRef<P> or a ResolveError (ADR-0231 §3). resolve folds the canonical text and reads the route table once: a route must stand under exactly that name and be Live, or it refuses NotLive, naming the path, never a position. It compares no rows: P was proven when the path was narrowed or decoded. ctx.send_to(reference, &kind) and its context-carrying siblings take the ProtocolRef<P> only for a kind P lists; any other kind is a compile error, whatever else the target handles:

#![allow(unused)]
fn main() {
// `run.source: ProtocolPath<ArtifactStorage>`
match ctx.resolve(&run.source) {
    Ok(storage) => ctx.send_to(storage, &read),
    Err(error) => tracing::warn!(%error, "the run's source is refused"),
}
}

The guest arm is WasmCtx::resolve, which takes either typed path and mints the reference its type names (#7205, #7501): the Bloomery bootstrap proves its journal and driver peers from ActorPath<R> fields with it, and a guest whose config names a peer by protocol resolves the ProtocolPath<P> in wire (Naming a peer by protocol).

A kind or config field naming an actor its receiver will later send to, such as a subscriber, a handler, a callback, or a source, is a typed path, never an ErasedActorPath (design rule R-0040). It is an ActorPath<R> when the holder needs one concrete actor type, and a ProtocolPath<P> when it needs only a protocol, such as a subscriber the publisher cannot name. The receiver proves it once on receipt, by its decode, and stores the typed proof resolve returns. An erased reference has no send verb (#6895, ADR-0231 §4), so an ErasedActorPath is left to name, render, compare, or monitor an actor, and to name a recipient at the untyped MCP and RPC boundary.

Helpers that only send

The class marker rides on the context type — a request, tell, event, or response handler's WasmCtx<'_> is WasmCtx<'_, Self, Anyone, Single> and an unchecked handler holds WasmCtx<'_, Self, Anyone, Unchecked> — which is what makes a stray ctx.reply in any of the four a compile error. The ctx's type arguments are receiver, sender, mode: the actor is the first, the sender the handler requires (Anyone when it states none) the second, and the reply mode the third. A ctx that omits its actor is typed by it: #[actor] fills in Self, so the ctx reaches only the actors the handler's actor declares with depends(R). Spelling Erased in that slot (WasmCtx<'_, Erased>) asks for the untyped view. One call deeper the class buys nothing: a helper you factor out of a handler to send something never touches the reply channel, yet pinning one class makes it uncallable from the others and staying generic means carrying an M: ReplyMode parameter it doesn't read. ctx.sends() hands out Sends<'_, A>, typed by the handler's actor — the outbound verbs that take a proof (send_to, plus send_detached_to through MailSender, both taking a typed target: an ActorRef<R> or a ProtocolRef<P> such as a sender cast with ctx.cast) with the marker dropped — so the helper takes &mut Sends<'_, A> and every handler class can call it. The view sends only through a reference it is handed: the actor mints one with ctx.actor_ref::<RenderCapability>() in wire and keeps it in a field, because minting it in the same call as ctx.sends() would not borrow-check. Sends<'_> alone names the erased view:

#![allow(unused)]
fn main() {
fn announce<A>(sends: &mut Sends<'_, A>, renderer: ActorRef<RenderCapability>, frame: &Frame) {
    sends.send_to(renderer, frame);
}

#[handler::event]
fn on_tick(&mut self, ctx: &mut WasmCtx<'_>, _t: Tick) {
    announce(&mut ctx.sends(), self.renderer, &self.frame);        // Single
}

#[handler::unchecked(reason = "example: the same helper from the unchecked class")]
fn on_redraw(&mut self, ctx: &mut WasmCtx<'_, Self, Anyone, Unchecked>, _r: Redraw) {
    announce(&mut ctx.sends(), self.renderer, &self.frame);        // Unchecked — same helper
    ctx.reply(&Acknowledged);                       // reply stays on the ctx
}
}

reply / reply_to / emit — and send_with_context, whose stashed context is recovered on the reply — stay on WasmCtx<'_, A, S, M>, so a helper that needs those still states which class it belongs to. That's the line: the reply class is load-bearing exactly where the reply is.

Sharing handlers across a family

A family of similar actors — the widgets in a set, the per-platform runtimes of one capability — tends to carry the same block of handlers. A handler set declares that block once (ADR-0169). #[handler_set] sits on a trait whose #[handler::<class>] methods carry the shared bodies as trait defaults, and whose required methods are the accessors those bodies reach through:

#![allow(unused)]
fn main() {
#[handler_set]
pub trait WidgetDefaults {
    fn widget_frame(&mut self) -> &mut WidgetFrame;
    fn widget_state(&mut self) -> &mut InteractionState;

    /// Release any half-finished interaction — an armed press, a live drag.
    fn cancel_activation(&mut self);

    #[handler::tell]
    fn on_frame(&mut self, _ctx: &mut WasmCtx<'_>, frame: WidgetFrame) {
        *self.widget_frame() = frame;
    }

    #[handler::event]
    fn on_focus_lost(&mut self, _ctx: &mut WasmCtx<'_>, _lost: FocusLost) {
        self.widget_state().lose_focus();
        self.cancel_activation();
    }
}
}

An actor adopts the set by naming it in #[actor] and implementing the trait:

#![allow(unused)]
fn main() {
impl WidgetDefaults for ToggleWidget {
    fn widget_frame(&mut self) -> &mut WidgetFrame { &mut self.frame }
    fn widget_state(&mut self) -> &mut InteractionState { &mut self.state }
    fn cancel_activation(&mut self) { self.arms.clear(); }
}

#[actor(instanced, root, child_of(WidgetPanel, ScrollWidget), handler_set(WidgetDefaults))]
impl WasmActor for ToggleWidget {
    // only toggle-specific handlers here
}
}

Dispatch tries the actor's own handlers first and consults the set on a miss, so an actor's local declarations stay authoritative over anything inherited:

match local arms  ->  DISPATCH_HANDLED
else set dispatch ->  DISPATCH_HANDLED
else #[fallback] / DISPATCH_UNKNOWN_KIND

A member that differs for one adopter is overridden the ordinary Rust way — by implementing that trait method — which keeps the kind owned by the set: one dispatch arm, one manifest record. Re-declaring the same kind as a local #[handler] instead is a coherence error, not a second definition.

A set member's ctx is typed by the adopting actor: WasmCtx<'_> in a set reads as WasmCtx<'_, Self>, where Self is whichever actor adopts the set. A default body that reaches another actor therefore states that reach on the trait, as a supertrait — pub trait SoundDefaults: DependsOn<AudioCapability> for a set whose handlers play notes through the audio capability — and every adopter must declare the dependency. #[handler_set] adds Sized to the supertraits as well. An override is a plain trait-method impl that no macro rewrites, so it spells the typed signature itself: WasmCtx<'_, Self>.

Set handlers reach the aether.kinds.inputs manifest exactly as local ones do, so describe_component reports an adopter's full receive surface and input subscription covers inherited kinds with no extra wiring. A set is wasm or native throughout, uses one authoring shape throughout, does not nest, and an actor adopts at most one — a family that outgrows one set wants a second set, not a chain.

A set's handlers are contract rows of each adopter too, at positions past the adopter's own, so an adopter covers a protocol that lists a set kind (ADR-0231 §2). The rows travel through a bridge macro the set emits and the adopter's #[actor] expands in the adopter's own module, so a set spells its kind types with paths that resolve from every adopter (crate::WidgetFrame), and a wasm set, whose bridge is crate-local, is adopted within the crate that defines it.

A native capability adopts a set the same way, with two differences that follow from how native actors are authored. Handlers are written against NativeCtx, and a capability with a type State writes them in the split shape — the state arrives as the first parameter rather than as a self receiver, so the accessors are associated functions over Self::State:

#![allow(unused)]
fn main() {
#[handler_set]
pub trait CounterSurface {
    fn counter(state: &mut Self::State) -> &mut Counter;

    #[handler::request]
    fn on_reset(state: &mut Self::State, _ctx: &mut NativeCtx<'_>, _mail: ResetCounter) -> ResetCounterResult {
        Self::counter(state).reset();
        ResetCounterResult::Ok
    }
}
}

Each adopter supplies only the accessor; the handler is written once against it.

And under the split identity / runtime shape the adoption is declared on #[runtime], in the runtime file where the dispatch table is emitted — the capability struct's #[actor] reads it back off that attribute when it harvests the file, so the set is named once:

#![allow(unused)]
fn main() {
#[runtime(handler_set(CounterSurface))]
impl NativeActor for ExampleCapability {
    // only this capability's own handlers here
}

impl CounterSurface for ExampleCapability {
    type State = ExampleCapabilityState;

    fn counter(state: &mut Self::State) -> &mut Counter {
        &mut state.counter
    }
}
}

A native set's kinds carry HandlesKind markers, so kind-checked sends to an adopter (ctx.send_to(&example, &ResetCounter) through an ActorRef<ExampleCapability>) compile for inherited kinds too. The markers travel through a macro_rules! bridge the set generates, which means a set's kind types need spellings that resolve at each adopter's #[actor] — for a capability crate, the names re-exported at its crate root. The bridge compiles only where the set's module does, so an adopter whose identity must compile without its runtime (a capability a wasm guest names) cannot take its markers from a native set; such a capability writes its handlers inline in its one #[runtime] impl instead, as WindowCapability does.

A #[cfg] on a set handler is resolved by the crate that defines the set, and that answer reaches every artifact the set produces, the markers included. An adopter inherits a surface that is already fixed: enabling a feature of its own, even one sharing the set's spelling, never changes which handlers it inherits. That is what keeps a set's dispatch chain and its markers from disagreeing about which kinds it handles — a marker for a kind the chain would not answer is a send that compiles and gets dropped at run time. When one adopter genuinely needs a handler the others do not, declare it locally in that adopter's own #[actor] block, where #[cfg] already means the adopter's configuration.

Put in a set only what is genuinely uniform. When bodies disagree on something load-bearing — which predicate cancels an activation, say — a shared body has to pick one reading and silently change the rest, which is worse than the repetition it removes.

The example above is illustrative. The in-tree wasm adopter is the HandlerSetAdopter fixture in crates/aether-test-fixtures-bundle/src/handler_set.rs, which crates/aether-component/tests/harness_handler_set.rs loads and mails.

Configuring an actor

An actor can take typed boot configuration. Declare a Config associated type and the chassis threads a decoded value into init as its leading argument:

#![allow(unused)]
fn main() {
#[actor(root)]
impl WasmActor for ProbeWithConfig {
    type Config = ProbeConfig;
    const NAMESPACE: &'static str = "probe_with_config";

    fn init(config: ProbeConfig, ctx: &mut WasmInitCtx<'_>) -> Result<Self, ActorInitError> { … }
}
}

Most actors need none. Omit Config and the #[actor] macro synthesizes () and injects the unused argument, so a no-config init stays the terse fn init(ctx: &mut WasmInitCtx<'_>) from the examples above — there's no type Config = () to write by hand.

The two hosts differ in one way, and it follows from how the config reaches them. A capability's config is built in-process by the chassis, so it can be any Send + 'static type. A component's config has to cross the wasm boundary as bytes, so it must be a Kind — encoded at the load edge, decoded on the way in. That seam aside, the authoring shape is identical. (How a component's config rides the load call, and how a chassis assembles its own layered config, are the components and configuration pages.)

Names and addressing

The NAMESPACE const on the Actor trait is the name an actor claims — the "hello", "camera", "aether.audio" in the examples above. From the name and the actor's place in the runtime tree come two ids, two distinct moments (ADR-0099):

• NAMESPACE → ActorId, at compile time. The hash of the NAMESPACE names which actor this is — binary-unique, the same wherever the actor is hosted. An instanced actor (below) folds its runtime discriminator in: hash(NAMESPACE:subname).
• Lineage → MailboxId, at creation. Where the actor sits is its lineage — the ordered ActorIds from the substrate root down to it, fixed when the actor is created. Its MailboxId is a hash chain over the lineage, one fold step per node, and mail routes to that.

For a capability the two coincide. It sits at the root, so its lineage is one node and the fold of one node is that node: MailboxId == ActorId, the NAMESPACE is the whole address (aether.audio, aether.render, aether.window), and ctx.send::<AudioCapability>(..) resolves to it as a compile-time const with no runtime lookup.

For a component the name is the one its module publishes for the type (ADR-0241 §5): a singleton sits at the root at NS, exactly as a capability does, an instanced type at NS:key, and one loaded beneath a parent at parent/NS:key — the canonical rendered address LoadResult.path hands back. The string is a display rendering of the lineage; the MailboxId is the fold over the nodes (the host registry parses a written path and folds it node by node), never a hash of the joined string.

There is one addressing verb: you address a type, and the type declares where it lives. ctx.send::<Camera>(..) routes through ctx.actor_ref::<Camera>(), which reads the resolver Camera declares and selects the routing seed from it — the root for a capability or a loaded root singleton — so the send site says who it is talking to and never where that peer sits. A declared dependency is always a root singleton, so moving the caller changes nothing about the route.

A load name is the one thing the type cannot declare, because it is a runtime fact. A replicas fan-out spawns several counter-keyed instances (NS:0, NS:1, …), each reached through the reference its own spawn proved, never by folding a name at the send site.

LoadResult.path is an ErasedActorPath: the host's resolve_address parser, at the MCP, RPC, and harness boundary, is the one place an ErasedActorPath becomes a position (ADR-0230). The reply carries no position. A successful load reply is sent by the loaded actor itself, so a requester, native or guest, keeps ctx.sender() from the reply as its reference and an embedder types the reply event's stamped sender.

Because the lineage is the address, two actors collide exactly when they would occupy the same position — same parent, same name. The substrate enforces one claimant per position at registration: a second capability claiming a taken root name fails to boot, and a component loaded under a name already in use comes back as a load error. This is not a compile-time check — two types can declare the same NAMESPACE string and compile cleanly; the collision only surfaces when the second one tries to register. For an instanced actor (below) the colliding unit is the full NAMESPACE:subname under one parent, not the shared prefix.

The tree is ordered, and the order is creation order (ADR-0248). A parent's children stand in the order they were created, and so do the root actors: the chassis composition chain as written, then the boot list as written, then whatever is loaded later. Nothing else orders actors. There is no reorder verb, rank, or ordering declaration, and an actor never states where it stands. The registry stamps each route with a birth serial when the route is first reserved, before init runs, so the order is the order the registry saw the requests and does not depend on how long each init takes. The serial stays with the route through a republish and after the actor closes, and a closed actor's name is never registered again, so a place is for life.

A native actor reads where another stands with ctx.lineage_order(reference), which answers an opaque LineageOrder to compare with others: a parent sorts before its children, a child between its parent and its parent's next sibling, and siblings in creation order. The value names no mailbox and is never mailed. Each reader gives the one order its own meaning; the renderer paints overlay draws by it (Rendering). A parent that needs control over where things stand creates empty children first, in the order it wants, and creates its content beneath them.

So that the read has no failure to report, a birth names a parent that holds a route record. Every production birth already does, because a child's name is built from its parent's. A name nested beneath a parent the registry has never seen is refused where the birth is applied: SpawnError::ParentUnknown for a spawn, RegistryEffectError::ParentUnknown for a staged effect. A test fixture that stands a route at a/b:k registers a first.

A dash in a namespace is a naming convention, not addressing grammar. Use it only for a genuine adjacent sibling of an existing bare base: aether.kit.camera-controller is the controller actor beside the bare aether.kit.camera actor. The dash has no addressing semantics — it makes neither actor a child of the other, and the full NAMESPACE still yields the ActorId before lineage yields the MailboxId. Do not use a dash merely to spell a multi-word segment; that is what an underscore is for, as in aether.substrate_harness.observer.

ctx.actor_ref::<Camera>() returns an ActorRef<Camera> for the physical trampoline mailbox: the trampoline and its loaded guest share one mailbox, while the guest type supplies the compile-time mail-handling surface. A const beside the call site holding what Camera::NAMESPACE already declares would be a second naming authority nothing checks against the first, and the bare-type spelling exists so it has nothing to hold.

One or many: cardinality

An actor type is either singleton or instanced, marked by the Singleton or Instanced trait, and the choice sets whether its NAMESPACE is a whole name or a prefix.

A singleton is one of a kind: at most one instance under a given parent, and its ActorId is the plain hash(NAMESPACE). Every capability is a root singleton — its one-node lineage makes its NAMESPACE the whole address, so you address it straight by type, ctx.send::<R>(..).

An instanced actor is one of many sharing a prefix. Its NAMESPACE is that prefix, and each live instance gets its own ActorId by folding a runtime discriminator in — hash(NAMESPACE:subname), rendered aether.tcp.session:42 — with its MailboxId folding that ActorId under the parent's lineage, so two instances under one parent differ by subname. The case that drives this is sockets: a singleton listener accepts connections and spawns a session actor per connection with ctx.spawn_child (ADR-0079), then reaches a specific one through the reference that spawn returned, kept in its own child map. A subname is never folded at a send site: an instance is reached through the reference its spawn returned or through child_as.

ctx.spawn_child is the native verb. A native capability names only the child type, and can spawn an Instanced native actor when that child declares ChildOf<Parent> for the actor doing the spawning: ctx.spawn_child::<TcpSessionActor>(subname, config, params). The parent comes from the ctx. A handler opts into the call by naming its own actor in its ctx signature — ctx: &mut NativeCtx<'_, Self, Anyone, Single>, or NativeCtx<'_, Self, Anyone, Unchecked> for an unchecked handler — and the #[actor] macro hands such a handler a ctx typed by the actor being dispatched. Every other handler keeps the plain NativeCtx<'_> and reaches no spawn surface, so a birth cannot be placed under a parent other than the one running.

A native birth stages during the handler turn and commits afterward. The handler chains any after_init bootstrap mail and ends with .stage() (or .stage_with(context) to carry a context kind forward), which does the local half of the work — the permission and subname checks, A::init, the transport — and appends one ordered prepared birth to the parent's buffer (ADR-0165). Nothing in the shared registry moves while the handler runs, so no spawn takes a global lock mid-turn. What comes back is a SpawnReceipt: the child's canonical_name, an ErasedActorPath derived from the parent's identity and proven against the ADR-0166 address grammar on the spot, which names the child for correlation, plus the birth's request id. A lineage too deep or too long for that grammar never gets a receipt: .stage() itself returns SpawnError::PathInvalid, and .stage_with hands its context back beside the error. Neither field is a send target: the child is not Live yet, so nothing can prove it. Mail the child must see first rides after_init on the birth itself, and later mail goes through ctx.send_to(&child, &k) once the Ok completion hands back its reference.

#![allow(unused)]
fn main() {
let Ok(receipt) = ctx
    .spawn_child::<TcpSessionActor>(Subname::Counter, config, params)
    .after_init(Hello)
    .stage()
else {
    return;
};
}

The receipt says the birth was accepted locally; the registry owner applies it after the handler returns, and that result is authoritative. It arrives back at the spawner through the ordinary task-completion path as TaskDone<SpawnOutcome<A>> for a child of type A, correlated to receipt.request, and owes nothing (ADR-0243 §9) — so an apply-time conflict (a name another actor won first, say) surfaces as one typed failure rather than a silent half-spawn. A handler that stages several births in one turn gets one outcome per birth, and those births commit or fail together: if the owner refuses one, that one's outcome carries the reason, every other outcome of the turn is SpawnError::ActivationRejected, none of them is born, and each name can be staged again on a later turn. A SpawnOutcome names itself on both arms:

#![allow(unused)]
fn main() {
struct SpawnOutcome<A> {
    canonical_name: ErasedActorPath,
    result: Result<ActorRef<A>, SpawnError>,
}
}

so a handler correlates the completion with the birth it staged by canonical_name, straight off the outcome, and stages with no context unless there is something the spawn genuinely does not know — a peer address, which leg of a multi-step plan this birth belongs to. A handler whose correlation key is not the child's name stages with that key as a context kind and takes it in the completion with ctx.take_context(); a live value the completion needs, such as a channel or a held reply, waits in actor state under that key. A handler that keeps or mails its child holds the Ok reference and sends through ctx.send_to(&child, &k), so a handler that mails its child after the bootstrap waits for that completion the same way one that must know the child is live before it reports success does. Synchronous commit still exists, but only at the boot/embedder boundary — BuiltChassis::spawn_actor / PassiveChassis::spawn_actor and their .finish() terminal, which block until the birth is live and hand back its ActorRef<A>, a proof you can immediately send through. The actors the chassis composed itself — each singleton capability and pumped actor — are recorded the same way when their routes go live, and actor_ref::<R>() on either chassis handle reads one back by type.

That terminal spans the chassis's one authority boundary, the registry authority seal. A chassis seals once boot is over: a built chassis after its driver's Start stage returns successfully, a passive chassis immediately before the PassiveChassis reaches you. Before the seal, boot writes the registry directly — it wants synchronous apply and read-your-writes with no scheduler thread in the picture yet. After it, there is no direct writer left to name, so an embedder's .finish() submits the birth to the owner and waits for it exactly the way a handler's staged birth is applied: Starting, wire at the actor's execution home, then Live. Every birth in a running engine follows that one protocol, whoever asked for it.

Waiting there is safe because of who waits: an embedder thread is not a pool worker, so it can never be the worker the owner needs to make progress. That is also why a handler has no such terminal — a handler blocking on the owner could be the last worker, so it stages instead.

When the handler that receives a completion owes a reply of its own and answers it by staging another birth, it hands that debt straight on with .continue_from(done, context). The reply the caller is waiting for is a DeferredReply — who is waiting, plus the settlement hold keeping their chain open — and it rides inside the TaskDone the handler already holds, so the successor stage inherits one continuously-held chain instead of closing and reopening it. Every synchronous failure in continue_from hands the value back untouched, so the terminal error still goes out exactly once:

#![allow(unused)]
fn main() {
match ctx.spawn_child::<Worker>(Subname::Named(&name), config, ()).continue_from(done, plan) {
    Ok(_) => { /* the successor now owns the reply */ }
    Err((error, done)) => done.resolve_err(ctx, &Failed { error: format!("{error:?}") }),
}
}

A handler with no TaskDone in hand — one that parks a caller across a worker thread, say — mints the same debt from its ctx with ctx.defer_reply_to(target) and passes that to continue_from instead. A typed Held<R> from ctx.hold is also an IntoDeferredReply, so continue_from takes it the same way and the chain stays held across the hand-off. Dropping a DeferredReply without replying releases its hold (settlement is never wedged) and then panics, in every build, which the scheduler escalates through the chassis aborter, because a lost reply strands the caller forever. An actor that closes with debts still owed while the engine keeps running answers them: the engine sends each Held<R> its R::unanswered() before releasing its hold (ADR-0243 §1), and an actor that keeps a DeferredReply in state answers it in unwire with the terminal it knows. An engine teardown settles held debts silently instead, because every requester is closing with it. abandon_for_actor_close, which releases a debt with no reply, survives only for the component host's boot waiters until #7008 removes it.

Wasm enforces the same ChildOf permission when a component creates a child inline (ADR-0114): the child is an Instanced actor its module also exports (or lists under private = [..]), co-located in the parent's wasm instance, and the spawn compiles only when the spawner declares the child in its spawns(..), whose emitted Spawns<Child> impl in turn compiles only when the child lists the spawner in its child_of(..). So spawns(..) is the rebuild manifest every export! checks, and the child's child_of(..) is its placement set; the one bound A: Spawns<C> proves both. One wasm crate can export several actor types (export!(public = [RootManager, Panel, …])), and a running instance stands up a child just as the listener stands up a session: ctx.spawn_inline::<Panel>(Subname::Named("body"), &config) names only the child type and reads the parent from the ctx as the native side does. Its two-type counterpart ctx.spawn_inline_child::<RootManager, Panel>(Subname::Counter, &config) stays for an erased or wire ctx, which does not know its actor: WasmCtx is addressed by tag rather than by Rust type, so the parent is named at the call and the SDK checks it against the ctx's registry-backed actor tag before allocating the child's alias; writing a different parent type earns an error rather than bypassing the declared edge. Either hands back an InlineChild<Panel>, whose send is checked against Panel's handler set. A parent keeping children of several types in one table narrows each handle with narrow::<P>() to a ProtocolRef<P> for a protocol the child covers, which compiles only where it does (ADR-0231 §3), and keeps the erased erase() reference as the table's identity key. A component spawns within the module it was built from; a foreign module comes in through load_component, which carries its own code and kinds — the boundary is covered in Components & lifecycle.

An inline child ends by closing, as any actor does (ADR-0241 §8): ctx.despawn_inline_child(child) closes it, and so does its parent's close. Each watcher gets a MonitorNotice sent from the child, and the child's name tombstones. The name is spent: a later monitor of it returns its handle and the watcher is sent the child's MonitorNotice at once, as for any actor that has already closed, and spawning the same key beneath the same parent fails with SpawnError::AliasAllocationFailed. A parent that wants a fresh child after a despawn spawns it under a new key, such as Subname::Counter.

A close runs unwire on what wired (ADR-0249 §4, §6). A parent's close runs each inline child's unwire before the parent's own, deepest first. A child that despawns itself runs unwire when the handler that asked returns, and is dropped after it. Each child runs unwire once, and only if its wire returned Ok. Spawning a name whose child is standing is not a second birth: the spawn answers the child that stands, wiring it first when it never wired, initialising nothing, and ignoring the config it was passed, so a wire that spawns a child is safe to run again (§5).

A component can also run as several instances of one type: an instanced type loaded under different keys is an independent actor at each NS:key. The loader hosts every component in a native trampoline actor, spawned once per load, but the actor is named by the guest's published namespace, never the trampoline's.

One model, two hosts

Here's the part that ties the engine together. There aren't two actor systems — there's one model with two hosts, differing in where the actor's code lives and how it reaches the outside world (ADR-0074):

• A native capability is an actor compiled into the substrate, implementing NativeActor and linked at build time. It's the host an actor takes when what it does needs native Rust APIs or raw performance — the GPU through wgpu, the audio device through cpal, the filesystem, the OS input loop. The renderer, the audio mixer, the filesystem, the input streams, and the component-loader itself are all capabilities; together they're the chassis.
• A component is an actor loaded at runtime as a wasm module, run sandboxed behind the wasm wall and reaching the outside world only by mailing capabilities. It implements WasmActor, and the substrate drives it through an FFI trampoline. This is the agent-facing extension path: new behavior with no substrate rebuild.

The two hosts preserve one actor model, but native capabilities also split their always-addressable identity from runtime state. Both have configuration and the same lifecycle intent; native handler signatures receive &mut Self::State while wasm handlers receive &mut self. The host contexts and machinery differ, but mail contracts remain symmetric. A current native capability looks like:

#![allow(unused)]
fn main() {
#[actor(singleton)]
pub struct AudioCapability;

pub struct AudioCapabilityState { /* native resources */ }

#[runtime]
impl NativeActor for AudioCapability {
    type State = AudioCapabilityState;
    type Config = AudioConfig;
    const NAMESPACE: &'static str = "aether.audio";

    fn init(config: AudioConfig, ctx: &mut NativeInitCtx<'_>)
        -> Result<Self::State, BootError> { … }

    #[handler::tell]
    fn on_note_on(state: &mut Self::State, ctx: &mut NativeCtx<'_>, note: NoteOn) { … }
}
}

Because the only coupling is mail, an actor can't tell whether the mailbox it sends to is backed by native Rust or sandboxed wasm — and doesn't need to. A component sends aether.render a DrawTriangle exactly as one capability sends another. This symmetry is the point of ADR-0074: one mental model, one macro, one lifecycle, and components get to reuse every pattern capabilities use.

So start here, with the actor, and the two host pages are just specializations:

• The wasm/FFI host — the trampoline, export!, loading, hot-swap — is Components & lifecycle, and the empty-crate-to-loaded walkthrough is the Writing a component recipe.
• Adding a native capability is a recipe (Adding a chassis capability); it's the same #[actor] shape against NativeActor.

Where to read more

• What flows between actors — The type system.
• The rules the model guarantees (ordering, fire-and-forget, capability = reachability, single-threaded) — Invariants & guarantees.
• How mail routes and in what order — Mail, kinds & scheduling.
• How the scheduler keeps an actor single-threaded, and what to do instead of blocking — Concurrency & blocking.
• The wasm host in depth — Components & lifecycle.

Invariants & guarantees

An invariant is a property the engine holds true at all times — something you can build on without re-checking, and something that, if violated, breaks code that depended on it. This page is the scannable contract list: the load-bearing guarantees, in one place, each grounded in the ADR that established it.

It splits in two:

• What the engine guarantees you — properties you can rely on. Build on them; don't defensively re-implement them.
• What you must uphold — obligations you owe in return. Violate one and you don't get a compile error — you get a silent failure: vanished mail, a hung reply chain, a garbage decode. Each entry names the tell so you can recognise it.

Concurrency enforces several of these (single-threaded actors, ordering, no-blocking) but is not the same topic — the contracts live here; the machinery that makes them hold, and how to work with it, is Concurrency & blocking. Invariants are the what; concurrency is one of the hows.

Maturity: the addressing, typing, and identity invariants are stable — they've held since the model's early ADRs and the wire format depends on them. Settlement is stable as a contract while its transport is still settling (ADR-0086). Scheduler internals are settling (ADR-0087) — but the concurrency contracts below are stable regardless of how dispatch is tuned.

What the engine guarantees you

Mail is the only channel between actors. No actor holds a reference into another actor's memory — no shared mutable state crosses the boundary, so a peer's data can't be read or mutated directly (ADR-0002). An actor's entire interaction with the rest of the engine is the mail it sends and the mail it receives. The enforcement differs by actor kind: a loaded component can't even form such a reference (the sandbox gives it its own linear memory), while a native capability — Rust in the same process — upholds it as a discipline (peer references are bootstrap-only; handlers talk by mail, never by reaching into sibling state). Same contract, a wall in one case and a rule in the other. This is what makes hot-swap, sandboxing, and universal observability possible at all — see Mail, kinds & scheduling.

A mailbox is an address; a kind is a payload shape; they route independently. The mailbox decides where mail goes; the kind only describes what the bytes are. They share a naming convention (aether.audio mailbox + .note_on verb → aether.audio.note_on kind), but routing never consults the kind. Hold these apart and most "my mail vanished" confusion disappears.

Identity is name-derived and stable. An actor carries two ids, each deterministic (ADR-0099): its ActorId — which actor — is the FNV-1a 64 hash of its NAMESPACE (hash(NAMESPACE:subname) for an instanced actor), and its MailboxId — where it sits — is a hash chain over its lineage, the ordered ActorIds from the substrate root down to the actor. A root actor's lineage is one node, so its MailboxId equals its ActorId — the name hash of ADR-0029 is the depth-1 case of the fold. A KindId is a hash of the kind name plus its schema (ADR-0030). Two consequences you can lean on:

• Stable across processes. Every id is computed from names and lineage, never assigned — Kind::ID and the actor-type tag are compile-time constants, and the lineage fold (fold_lineage) is the same pure function on every substrate and guest — so two processes that hold the same names and the same lineage produce the same ids, and addressing works across a fleet without a resolution round-trip.
• Stable across hot-swap. A republish changes neither a component's name nor its position under its host, so its lineage — and the MailboxId folded from it — is unchanged: senders and route caches survive the swap (ADR-0029; the replace_component_preserves_mailbox_identity scenario guards it).
• A name is used once. An actor's name goes absent → Live → tombstoned, and nothing registers it again. A dropped component closes like any other actor, so a later load of its name is refused as retired rather than handing the id to a different instance (ADR-0241 §8).

One sharp edge follows from the lineage fold: a /-rendered address (aether.window/aether.window.instance:main) resolves in the host registry, which parses it into segments and folds their ActorIds node by node. Hashing the joined string as a flat name yields an id the registry never registered, and mail to it warn-drops — the string is a rendering of the lineage, never the hash input.

A kind id encodes its shape — drift fails loud, not silently. The KindId hashes name + schema, where name is the kind's declared name (#[kind(name = "…")]) and schema is its structural shape — field types and positions only. The Rust type name and the field names are deliberately erased from the hash (ADR-0031/ADR-0032), so they're not what's being compared. What that buys: a producer emitting Thing { a } and a consumer expecting Thing { a, b } compute different ids, so the stale mail lands on "kind not found" and can never silently garbage-decode into the wrong shape (ADR-0030). The fix for a mismatch is always "recompile both sides," and the failure points straight at it. (Exactly which edits move the id — and which, like a field rename, leave it untouched — is the type system's story: The type system.)

A kind is self-describing. Every kind carries a schema describing its bytes (ADR-0005/ADR-0031), so the wire layer can encode it from JSON and a recipient can decode it without a shared header — and a live engine can be asked what kinds exist (describe_kinds). Payload bytes stay opaque in transit: nothing between sender and the addressed handler needs to understand them (ADR-0019).

An actor is single-threaded from its own perspective. An actor's handlers never run concurrently with each other, so its state is plain fields — no Mutex, no RefCell, no atomics for actor-local state. This holds even though actors do not each own a thread: they're multiplexed onto a shared work-stealing scheduler, and a run-token guarantees only one worker runs a given actor at a time (ADR-0087). The property is achieved by scheduling, not by a dedicated thread.

Per-recipient FIFO; cross-recipient unordered. Mail from the same sender to the same recipient arrives in send order. Mail to different recipients carries no ordering guarantee — each send is an independent async call (ADR-0087). This is the single contract most likely to bite under load; the what you must uphold section restates it as a rule.

Settlement is exact. A traced chain of mail is reported Settled exactly when in_flight == 0 && held_open == 0 — the counter does not transiently reach zero with work still coming, so Settled fires once and is a fact, not a hint (ADR-0080 §6, as amended; ADR-0086). This is what lets send_mail_traced know a request is fully done rather than guessing with a timeout. It depends on the hold contract below being honoured.

Capability equals reachability — with no privileged side-channel. What an actor can do is exactly what it can mail; there is no back door, not even for the agent driving the engine. Gating a build is just choosing which mailboxes are registered. The payoff is the point: because every function is reachable as mail, you can interpose anywhere — address any mailbox, watch any exchange, inject a message mid-flow to reproduce a state (ADR-0002). Universal reachability is what makes the running engine inspectable.

What you must uphold

These are the obligations. Each one, violated, produces a silent failure — so each lists its tell.

Never block in a handler. No sleeping, blocking I/O, blocking lock/channel wait, or busy-spin. Scheduling is cooperative: a blocked handler pins a worker doing nothing and can deadlock a reply chain (the actor you're waiting on may have its next mail queued behind you). Await a reply through the framework, or hand blocking/async work off the actor thread through the sanctioned spawn primitives. Tell: a hang with no progress and, often, no actor named — the worst diagnostic shape the runtime offers. Full treatment in Concurrency & blocking.

Address exactly — bare and unknown names warn-drop. A bare name ("camera", "player") or a kind name used as a recipient (aether.audio.note_on as an address) matches no registered mailbox and is dropped with a warning, not an error. Use the full address: aether.<name> for chassis mailboxes, the LoadResult.path (NS, NS:key, or parent/NS:key) a loaded component hands back. Tell: mail seems to vanish; nothing handles it. Check the address first.

Don't encode cross-actor sequence by send order. Per-recipient FIFO is the only ordering you get. If B must happen after A across different actors, make it causal — have A's handler trigger B, or have one actor receive both and sequence them itself. Tell: code that passes in dev and reorders under load, because a second recipient happened to run first.

Don't assume a reply. Mail is fire-and-forget; a handler promises nothing about a reply (there is no Kind::REPLY). If a reply matters it's a separate, explicit contract between two kinds, not an implicit "every kind has a response." Tell: a caller that blocks or waits forever on a reply the handler never agreed to send.

Hold the chain open across a deferred reply. If a handler kicks off work that will reply in a later turn (a slow provider call whose result lands after the handler returns), it must keep a settlement hold on the root until that last send — otherwise the chain settles early and any waiter is told "done" before the real reply arrives (ADR-0080 §12; ADR-0093). Synchronous in-handler replies need nothing (their Sent precedes their Finished); the sanctioned offload primitives hold automatically. A hand-rolled drain that consumes an owned dispatch must record Finished for the inbound mail id, or settlement never fires (ADR-0094). Tell: a multi-second hang to the settlement/MCP timeout with no actor named.

On a kind's schema change, recompile both sides. A schema edit changes the KindId. Until the peer is rebuilt, its Kind::ID no longer matches what you registered and its mail lands on "kind not found" (ADR-0030) — and prebuilt component wasm carries the old id, so rebuild it after any chassis-side kind or mailbox-name change. Tell: "observed kinds: []", or mail that used to route now missing after one side changed.

Cap recursion on unbounded data. Load-bearing code that recurses on user-controlled or geometrically-derived data must enforce a depth/budget cap that returns an error rather than overflowing the stack; prefer an explicit work-stack for anything whose depth could exceed a few hundred frames (AGENTS.md). Recursion bounded by a small structural input (a parse/AST walk) is fine. Tell: a stack-overflow abort on adversarial or pathological input.

Where to read more

• The mechanics behind the concurrency invariants — Concurrency & blocking.
• How kinds, mailboxes, handles, and ids fit together — The type system.
• The mail spine these all hang on — Mail, kinds & scheduling.
• Settlement and tracing in depth — Tracing & settlement.

Operating a live Aether engine

This part of the guide is the runbook for an agent—or a human at the same controls—operating Aether through the MCP harness. It starts after code has been built and answers four practical questions:

1. Which process owns the thing I am looking at?
2. Which identifier is safe to reuse?
3. What evidence can I collect without changing the engine?
4. What must I clean up when the task ends?

For the transport topology and connection setup, begin with The MCP harness. The pages here assume its tunnel, aether-mcp, and hub are reachable.

The operating model

The harness has four ownership layers. Confusing adjacent layers is the most common source of bad recovery decisions.

Keep three nouns separate:

• Stored means bytes and a manifest exist in the hub's content-addressed artifact store. list_binaries and registry list_components report this.
• Running means a substrate is in the hub's current supervised fleet. list_engines reports this.
• Loaded means a component actor is registered inside one running substrate. load_component creates it; describe_component inspects it.

A stored component is not loaded. A loaded component on engine A says nothing about engine B. An old engine_id says nothing about a new hub process.

The safe operating loop

Use this loop even for a short probe:

• Start with list_engines and decide whether to adopt an existing engine or create one.
• Before using any selector, prove the artifact is stored with list_binaries or registry list_components; otherwise upload it first.
• Record the exact engine_id returned by spawn_substrate.
• Record each explicit load's returned lineage address; for boot loads, record the configured name used to derive its lineage.
• Inspect the live surface before guessing mail: describe_kinds, describe_handlers, or describe_component.
• Prefer settled send_mail; use send_mail_traced when causal timing or whole-chain proof matters.
• Collect logs, traces, costs, and frames before destructive recovery.
• Drop task-owned components and require their successful drop_result, or terminate task-owned engines when done.
• After termination, call list_engines again and verify the engine cleanup is visible. A component drop is verified by its result, not the fleet list.

The tool's live JSON schema is the parameter reference. This guide names the current tools and their contracts, but does not duplicate every field because that surface evolves.

Choose the next page

The subsystem explanations remain useful alongside these runbooks:

• Components & lifecycle explains the wasm host and trampoline model.
• Mail, kinds & scheduling explains addresses and payload schemas.
• Tracing & settlement defines what “settled” proves.
• Logging explains what reaches actor log rings.

Ownership rules

Ownership is operational, not merely descriptive:

There is no current MCP delete tool for stored binaries or components. Reusing an upload name repoints that name to the new hash; it does not erase the old bytes. If no other name points at the old hash, it becomes unnamed history and can later be evicted under the store's disk budget. Do not promise registry cleanup that the tool surface cannot perform.

Component drop closes that one instance: its guest's unwire runs, its name tombstones, and a later load of the same name is refused as retired (ADR-0241 §8). Engine termination ends every instance at once.

Identifier discipline

• Treat engine_id as a hub-lifetime routing handle. The hub allocates it from process-local state and only guarantees uniqueness in its current fleet. A later hub can mint the same text for a different engine.
• Treat rpc_port as observation, not identity. Never route a tool call by substituting a port for an engine_id.
• Hand tagged ids such as knd-… and hdl-… back verbatim. Address an actor by its path; a mailbox id in output is for reading.
• Address a loaded component by the full lineage name returned by the load, its published name: NS, or NS:key for an instanced type.
• Prefer a content hash when a rollout or rollback must select exact bytes. A human-readable registry name is a movable pointer.

Mutation posture

Read-only discovery should precede mutation. list_*, describe_*, actor_logs, and actor_cost are the normal first calls. capture_frame is observational to the engine when used without mail bundles; its mails and after_mails fields make it engine-mutating. Independently, save_path creates parent directories and can overwrite a host file even when both bundles are empty. send_mail, component lifecycle calls, spawn, replace, and terminate all change live state. Host paths have an independent authority boundary; follow Host paths and artifacts before uploading native code or persisting a frame.

Fire-and-forget is not a faster form of verification. It proves that the call was written, not that the engine completed the work. Use it only when the recipient intentionally has no useful reply or when a later observation is the actual success criterion.

Source routes

When prose and behavior disagree, inspect these routes in order:

• MCP tool names and user-facing contracts: crates/aether-mcp/src/tools/mod.rs
• Live JSON argument and response shapes: crates/aether-mcp/src/args.rs
• Fleet and component orchestration: crates/aether-mcp/src/tools/engine.rs and components.rs
• Hub fleet ownership and engine death handling: crates/aether-fleet/src/server/runtime.rs and crates/aether-fleet/src/proxy/runtime.rs
• Stored artifacts: crates/aether-fleet/src/store/
• Live kind inventory: crates/aether-inventory/src/
• Loaded component registry and lifecycle: crates/aether-component/src/component/

The MCP harness

Governing ADR: ADR-0089 (the tunnel), over the per-subsystem ADRs the tools front. The harness is stable in shape but its tools evolve — so treat this page as the map and the mental model, not a parameter reference. Each tool's exact arguments live in its own schema, which your MCP client shows you live; that schema is the source of truth and is more current than any prose (this page included). When the two disagree, believe the tool.

An agent doesn't link against the engine or call it in-process. It drives a running engine from the outside, over MCP (Model Context Protocol): each tool call becomes mail against a live substrate, or a query about one. This is the concrete form of the "agent in a harness" idea — the engine runs, the agent pokes it, watches what happens, and adjusts. If you're an agent reading this guide, this is the page that turns everything else into something you can actually do: the other pages tell you what to send; this one is how you send it.

The shape: three processes and a fleet

The harness is three processes nested one inside the next, fronting a fleet of engines:

:8890  aether-tunnel        — the stable MCP front your client connects to
  ├─ :8891  aether-mcp      — translates each tool call into a wire Call to the hub
  └─ :8901  aether-hub  — supervises the fleet
        ├─ substrate (engine A)   — one running chassis
        ├─ substrate (engine B)
        └─ …

The tunnel is the only thing your MCP client talks to. It supervises and re-forks the two backends below it, which is the point: you can rebuild and restart the hub without your MCP session ever dropping. aether-mcp is the RPC client — it turns a tool call into a wire Call and relays it. The hub owns the fleet: it forks substrates, learns the localhost RPC port each one picks and reports, optionally heartbeats them, and routes your mail to the right one by engine_id. A substrate is one running engine — a full chassis — and you can have several at once.

An engine in list_engines is still supervised; that row alone does not prove every handler is reachable. With heartbeats enabled, a low last_heartbeat_age_millis confirms that the proxy recently answered a ping, and a rising value is an early sign that it is slow or wedged. A zero heartbeat interval or miss limit disables that check: the age then grows from initial connection even for a healthy engine, and the hub learns of death only when the connection closes. The fleet row does not expose whether heartbeats are enabled, so confirm hub configuration before using its age as a diagnosis.

To restart the hub after a rebuild without losing your session, hit the tunnel's admin endpoint (POST /admin/restart-hub); the tunnel re-forks the hub and aether-mcp re-dials it on your next call. This is a fleet-wide destructive operation, not a harmless reconnect: use it only with authority over the whole fleet and one coordinated request. Restarting aether-mcp itself does drop the session. Read Harness lifecycle and fleet-wide mutations before cycling either process.

Bringing it up

The stack isn't running by default — a cold build of the tunnel can take long enough to look like a frozen session, so it's left to the point of use. Bring it up yourself with scripts/ensure-tunnel.sh: it is idempotent — a no-op only when the running tunnel's supervised children are both alive — and starts the local stack only when needed. Treat .codex/config.toml, .mcp.json, the helper, and the active MCP schema as the current connection contract; do not translate another agent surface's harness syntax by analogy.

Codex sessions in a trusted checkout pick up the aether-hub MCP server from .codex/config.toml; if the mcp__aether-hub__* tools are missing after the tunnel starts, run /mcp in the active Codex surface to reconnect them.

The session loop

Per-engine work is keyed by engine_id. A session has a recognizable arc:

1. Get an engine. spawn_substrate(selector) forks a fresh substrate and returns its engine_id (and RPC port); omit selector for default — the stored headless chassis normally staged by the tunnel helper. Without that artifact, the bare spawn fails selector resolution. list_engines shows the ones already running. You hand that engine_id to every later per-engine call; hub artifact operations and the MCP-build-static describe_transforms do not take one.
2. Set it up. Stage the wasm into the hub's component registry with upload_component(staged_path) — it returns {hash, name} — then load_component(engine_id, selector) resolves that selector, publishes the module, and spawns an instance of its type, returning the instance's canonical lineage address and advertised capabilities.
3. Drive it. send_mail(…) delivers a kind to a mailbox. By default it blocks until the dispatch chain settles and hands you the correlated reply.
4. Watch it. capture_frame reads the rendered frame back as a PNG; actor_logs pulls one actor's log ring; describe_kinds, describe_handlers, and describe_component report engine/component contracts. describe_transforms instead reports the MCP build's static transform set.
5. Settle precisely. send_mail_traced when you need to know a whole causal chain finished, with its trace tree, rather than a single reply.
6. Tear down. terminate_substrate(engine_id) when you're done with an engine.

The tools

Fleet. list_engines, spawn_substrate, terminate_substrate. list_engines and spawn_substrate reveal engine ids; terminate_substrate consumes one and returns termination status. Use the id for engine-scoped tools, not for hub artifact-store or MCP-local queries.

Sending mail. send_mail is the workhorse. You give it a batch of items, each {engine_id, address, kind_name, params} — the mailbox to deliver to, the kind to deliver, and the structured params, which the tool schema-encodes to wire bytes against that kind's descriptor. A textual address may be a canonical lineage (a loaded component's published name, aether.kit.camera) or an ADR-0166 short path (aether.window/:main). The selected engine resolves either spelling to the same canonical path before dispatch, and the Call names its recipient by that ErasedActorPath; aether-mcp does not hash operator strings or keep an alias cache. By default each item blocks until its chain settles. The batch-level replies projection defaults to terminal: it keeps the last arrival-ordered reply plus any reply recognized as an error from its decoded Err shape or exact kind-name error suffix. Use none to suppress non-errors or all for the complete decoded stream; neither explicit mode caps the stream, and the generic whole-response guard stages an oversized complete result instead of truncating it. A request/reply (mail aether.fs.read, get the bytes back) is therefore a single call with no polling. Decoded Bytes leaves over AETHER_MCP_REPLY_INLINE_MAX_BYTES (default 16 KiB) stage to a host file and render as {"file": …} before that outer response guard, which stages any text response over AETHER_MCP_RESPONSE_INLINE_MAX_BYTES (default 32 KiB) as {file, bytes, summary}. A handler can emit no application reply and still settle, so that alone is not a reason to use fire_and_forget. Set it only for dispatch whose completion and ordering you deliberately do not need; use settled mail or capture_frame.mails when a mutation must precede observation. It returns no replies regardless of the requested projection. Items are independent: one bad item does not abort its siblings.

A byte field in params takes its literal JSON form or one $-sigil embed object. A Bytes or Blob field takes a byte array or {"$file": path} (a file on the harness host), {"$base64": s}, {"$text": s} (UTF-8), or {"$hex": s}. $hex also writes two leaf types the others do not: a [u8; N] field, such as a 32-byte digest, takes exactly 2 * N characters, two per byte in index order; an integer field takes two characters per byte of its type, most significant digit first, with a signed value spelled as its two's-complement bit pattern (u32 300 is "0000012c", i8 -1 is "ff"). Hex is lowercase 0-9a-f with no prefix; uppercase, a 0x prefix, and a wrong length are refused, so every value has one spelling. A u32 and a [u8; 4] holding the same wire bytes spell differently, because each follows how its own type reads. A function on a field type outside its set, such as $base64 at a [u8; 32] or $hex at a String, is refused, naming the function and the field type. The same embeds work in send_mail_traced, the capture_frame and spawn_substrate mail bundles, and component config.

format renders chosen reply leaves in that same hex spelling. It is an object keyed by exact reply kind name, each value a mask that mirrors the JSON the kind decodes to: "$hex" at a [u8; N], Bytes, Blob, or integer leaf; an object over struct field names or over the names of enum variants that carry a payload (a one-field tuple variant takes its field's mask directly, a struct variant an object over its fields); a one-element array [mask] for every element of a Vec or array, or every value of a Map; and, for a tuple variant with two or more fields, an array of that length where null leaves a position alone. Option layers are transparent. Over a [u8; N], "$hex" spells the whole array as one string, while ["$hex"] spells each byte on its own.

{"aether.bloomery.journal.publish_result": {"Committed": {"artifacts": ["$hex"]}}}

The sole key "*" with a function, {"*": "$hex"}, formats every [u8; N], Bytes, and Blob leaf in every reply, and leaves integers alone. The mask is validated against each item's engine before any mail is sent: an unknown kind, a key the kind's schema lacks, a unit variant, a function on a leaf outside its set, or "*" beside another key refuses the whole call, naming the kind and the JSON path. A reply of a kind the mask does not name renders as it does without one. Formatting runs on each decoded reply before the per-leaf Bytes spill, so a formatted leaf is already a string and stays inline; the 32 KiB whole-response guard still applies to the result. A mask only re-spells leaves: it never renames, drops, or adds a field, so the replies projection recognizes errors the same way.

send_mail_traced is the same idea with a shared trace root. Every item in the batch lands under one chassis-level trace root. The settled default returns a compact one-line-per-node tree, a matching node_count, and mails: null; each line names sender → recipient, kind, and handler duration, with indentation for causal depth. Pass trace: "nodes" to restore the complete mails node values; that form omits tree and carries the same node_count. A tree a trace ring cut also carries truncated, naming each such actor; a whole tree has none. Both forms also carry the complete flat reply list and rely on the generic response spill rather than truncating. Its format is the same reply mask as send_mail's, applied to that reply list and validated before the batch is encoded; a string format, such as the retired "nodes", is refused. Reach for it when you need exact whole-chain settlement — proof that everything a mail set off has finished — or all-or-nothing dispatch where a single bad item aborts the batch before any mail moves. For independent items where you just want each reply, plain send_mail is the simpler tool.

Introspection. describe_kinds is how you learn what to put in params. The default call returns a compact [{name, shape}] listing of every kind — a one-line field rendering per kind, small enough to read in one shot. Start with families: true for a sorted [{family, count}] digest; combine it with a case-sensitive prefix to digest one subtree (detail is ignored in this mode). Compact enum shapes use the externally tagged JSON envelope that send_mail accepts: a unit variant is a quoted string such as "Windowed", a tuple variant is a one-key object such as { "Ok": value } (or an array body for multiple fields), and a struct variant is a one-key object such as { "Err": { reason: String } }. When an enum appears inside a struct, that notation remains inside its named field; it does not become a top-level key. Use names: ["aether.fs.write"] for exact kinds, then add detail: "schema" when you need their nested SchemaType. names cannot combine with families or prefix, and a bare unfiltered detail: "schema" call is refused so schema output stays bounded. describe_component reports a component's handler kinds, their docs, whether it has a fallback, and its boot-config kind. It takes exactly one of address — a live instance's lineage or an unambiguous ADR-0166 short path — or namespace — a published type, as a publish named it, whether or not an instance is live. spawn and load_component return the canonical address (NS, NS:key for an instanced type, or parent/NS:key). For a boot load, retain the configured key from the component spec or derive the expected lineage from that spec; spawn_substrate itself returns only engine information. Registry list_components entries describe stored artifacts and are not loaded lineage addresses.

An engine-scoped describe_kinds is currently best-effort: it starts from the static baseline and attempts a live inventory refresh, but an RPC/decode failure can leave a prior/static snapshot and still return success. Its full schemas are exact for the returned snapshot, not proof that the engine was reachable. Pair freshness-sensitive use with list_engines and a harmless bounded live probe. Handler and component docs default to the first rustdoc line; pass full: true for the complete strings. describe_handlers reads the selected engine's native handler inventory, including reply contracts: each handler carries reply_class (none, one, or unchecked), and reply_id / reply_name are set only for one; an unchecked handler also carries its stated reason. describe_component shows the same reason beside an Unchecked reply. describe_transforms lists the native transforms linked into the current aether-mcp process; it does not query an engine.

Components. upload_component takes the filesystem path to a .wasm and stages it in the hub's component registry. The component tools follow the component host's three doors (ADR-0241 §9, ADR-0250 §5). publish takes that upload's registry selector (hash or name, never module@actor) and binds every namespace the module exports, standing no instance up; its reply names each type as published (NS, or NS.<hash> for a content-addressed module). spawn takes such a namespace, an optional key and parent, and asks for an instance: a live name answers with that instance (state: "live"), an absent one stands it up (state: "spawned"). load_component is publish then spawn: it takes a selector (hash, name, or module@actor) and a namespace that may be omitted only when the module exports one type. No tool takes a host wasm path or inline wasm bytes. For a typed-config component, pass either config as inline structured JSON or config_path as a path to a JSON file; they are mutually exclusive. The harness schema-encodes the JSON to the Config kind that describe_component identifies; describe_kinds shows its schema. config_path does not contain pre-encoded wire bytes. spawn or load_component with replicas: N publishes once and spawns N counter-keyed instances, returning one shared capabilities block plus instances: [{address, state}, …] rather than repeating capabilities per replica; docs on that block also follow the summary-vs-full projection. replicas with key is refused. Replacing code is a publish of a successor: every live instance of the module's namespaces moves to it as one group, or none does (ADR-0241 §7). Its configs: [{address, config | config_path}] give named instances a config, encoded to the successor's Config kind for each instance's type; the reply lists each published type with its capabilities. unpublish(namespace) withdraws one published namespace: drop its instances first — the host refuses an unpublish while one still runs, naming it — and the reply echoes {engine_id, namespace}. Withdrawing a publication does not resurrect tombstoned instance names. There is no drop tool: send aether.component.drop through send_mail. A drop closes the instance and retires its name, so a later spawn needs a new key.

list_binaries and registry list_components return {entries, total_matched, shown, truncated, notice} in stable newest-first first-ingest order. Their default page is the newest 20 name-pointed entries; pass include_history: true for unnamed historical hashes and an explicit limit to change the cap (0 returns no entries while retaining total_matched). To retrieve a complete matched history, first call with include_history: true, then repeat with limit set to that call's total_matched. Component actor handled_kinds are readable static kind names with tagged knd-… fallbacks; the redundant manifest-wide handled-kind union is omitted. These registry rows identify stored wasm, not live component instances; use the lineage returned by spawn / load_component, or the known expected lineage of a boot spec, for describe_component.

Observation. capture_frame returns one window's current frame as an optional inline PNG, bounded by a 768-pixel long-edge ceiling by default (never upscaled). window is required: pass the window's actor path as aether.window.list reports it, or its short form aether.window/:main, since capture never guesses a window. Pass a finite scale in (0, 1] for proportional reduction, then max_dimension to clamp the scaled long edge; those controls compose in that order. A capture with checks returns the verdict and omits the image by default, while include_image explicitly overrides either default. save_path always writes the original full-resolution PNG bytes. The capture can also carry two mail bundles dispatched atomically around the readback — mails before (the state that should appear) and after_mails after (cleanup). How that frame is produced — world-space geometry, the camera matrix, the depth convention — is covered in Rendering & camera. actor_logs and actor_cost resolve the actor address inside the selected engine to its canonical path and query by that path. actor_logs pulls recent entries from that actor's per-actor log ring; pass contains to filter message bodies by a case-sensitive substring substrate-side, before entries cross the wire. Thread the reply's next_since back as since to page forward without re-reading. Only in-actor tracing::* events reach a ring — see Logging for the in-actor versus stderr boundary. actor_cost reads each actor's per-handler execution-cost EWMA table (mean and MAD in nanoseconds, plus a sample count); pass a kind_id to filter to one handler.

Inspecting a bloomery engine. A bloomery engine answers aether.bloomery.inspect.artifact and aether.bloomery.inspect.events at aether.bloomery.inspect:<unit> (aether.bloomery.inspect:primary for the default unit), so its journal reads with send_mail and no Rust. artifact takes {digest, depth}, with the digest as {"$hex": "<64 hex digits>"}, and answers Found {kind_id, kind, json, truncated}, Missing, or Err; depth (at most 4) resolves cited digests inline as {digest, kind, value}, that many levels deep. events takes {after, limit, kinds} (limit at most 128, kinds a list of kind names, empty for all) and answers Ok {head, next_after, events}, each event {seq, cause, kind_id, kind, recorded_at_millis, value}; pass next_after back as after to page on. Every value comes back as JSON text in a string, with each 32-byte digest as lowercase hex. A kind is named from the engine's native storage kinds or the loaded bundles' program declarations; one neither knows comes back as {kind_id, length, hex}, never an error. Bounds keep a reply small: at most 256 resolved artifacts, 65,536 JSON values, 4,096 bytes per hex rendering, and 4,096 entries scanned per events request. An artifact cut short says truncated; an events reply cut short simply stops, and next_after pages on from there.

Conventions that bite

• Mailbox vs kind. address is the mailbox; kind_name is the payload. They route independently even when they share a prefix — send the kind aether.audio.note_on to the mailbox aether.audio. See Mail, kinds & scheduling.
• Paths, not bytes. upload_component takes the fleet-host filesystem path; publish and load_component take registry selectors. Tool JSON never carries the wasm buffer itself. Host paths are not sandboxed task paths; see Host paths and artifacts.
• Wire ids are tagged strings. Mailbox, kind, and handle ids come back as mbx-…, knd-…, hdl-…. Hand kind and handle ids back verbatim, don't reformat or parse them. A mailbox id is output for reading, never an address: name an actor by its path. See The type system.
• The engine resolves textual actor addresses. Canonical paths and short paths such as root/:name are checked against the selected engine's declared topology and live registry. Beneath a parent with several declared child types, a hole names the one child holding its key live, and fails with the explicit spellings when none or several do. Do not derive a mailbox id from the spelling.
• send_mail blocks and projects replies by default. It waits for settlement and returns the terminal reply plus recognized errors. Request replies: "all" when every event matters or "none" when only failures matter. A no-reply handler still settles normally; reserve fire_and_forget for work whose completion and ordering are intentionally unobserved. (If you've seen it described as best-effort fire-and-forget, that's the older behavior — the default flipped.)
• Desktop-only surfaces are absent on headless. capture_frame and the window ops need the desktop chassis; headless composes no render or window actor, so a mail to either path is answered NotPresent rather than hanging. Before reading back a backgrounded or minimized window, mail aether.window.focus to a named child recipient such as aether.window/:main (canonical aether.window/aether.window.instance:main). Success acknowledges the focus request; the OS may decline it or apply it asynchronously, so it does not prove the window is already foregrounded. See Window.
• describe_component resolves names before consulting its cache. Address it by the lineage returned by load_component, an unambiguous short path, or a retained boot-spec lineage. The selected engine first returns the live canonical path; aether-mcp then checks capabilities cached under that engine and path and asks the component host only on a cache miss. Registry list_components rows are stored artifacts, not lineage names.

Where to read more

• What a mailbox and a kind actually are — Mail, kinds & scheduling.
• The ids and schemas the tools hand around — The type system.
• Loading, replacing, and inspecting components — Components & lifecycle.
• Settlement and the trace tree behind send_mail_traced — Tracing & settlement.
• Adding your own tool to this surface — Wiring an MCP tool.
• Engine ownership, evidence, and recovery — Operating a live engine.
• Connection and process ownership — Process topology and chassis.

Harness lifecycle and fleet-wide mutations

A hub restart is not a transport refresh. It replaces the process that owns the fleet and therefore destroys live engine state. Use this page before restarting the hub, restarting aether-mcp, stopping the tunnel, or treating one of those actions as recovery.

For ordinary engine ownership and termination, see Engine fleet. For symptom-first recovery, see Recovery.

Bootstrap is not restart

These surfaces operate at different scopes:

A cold run also builds the binaries the hub forks for spawn_substrate — aether-headless and aether-desktop. It names the missing ones before starting, because the desktop chassis pulls in wgpu and winit and compiles for minutes with no output; that silence is the build, not a wedged script. Set AETHER_TUNNEL_SKIP_DESKTOP=1 to skip the desktop chassis on a host that only ever spawns headless engines, and spawn_substrate will resolve aether-headless alone.

The same run seeds the hub's binary store. It exports AETHER_BINARY_BOOTSTRAP with the release chassis binaries it found on disk; the tunnel reads that list once at boot and re-addresses it to the hub as an argv flag, because a forked child's environment is constructed from an allowlist rather than inherited (ADR-0162). The hub ingests each listed path into its content-addressed store as it starts, so a bare spawn_substrate resolves the stored default headless chassis without a manual upload_binary. The list is derived from what is on disk rather than from what that run built, so an already-built aether-desktop is still seeded under AETHER_TUNNEL_SKIP_DESKTOP. The fork spec is fixed at tunnel boot, so a hub replaced through /admin/restart-hub is seeded from the same list.

The tunnel's admin endpoint is loopback control, not an ownership system. It does not authenticate a task or establish which session may restart the fleet. Likewise, /admin/status and list_engines expose no owner or hub epoch. A reachable endpoint, PID, port, or fleet row is evidence of existence—not authority to destroy it.

Authority boundary

Treat the tunnel as shared host state. It can outlive the session that started it, and several agents or humans can drive the same hub.

• Terminate one engine only when your task spawned that exact current-epoch engine_id, ownership was explicitly handed to you, or the user authorized that engine's termination.
• Restart the hub only with explicit authority over the whole fleet and after coordinating with other active harness users.
• Stop the tunnel only when you own the complete harness or the operator has authorized a full shutdown.
• An empty fleet is not proof that another session has no in-flight spawn, upload, or other hub operation.

If one owned engine is unhealthy, terminate that engine. Do not use a hub restart as per-engine cleanup.

Blast radius

The hub process owns engine proxies. Proxy teardown force-kills and reaps the child substrate it spawned, so replacing the hub also removes its supervised children. This is intentionally stronger than reconnecting a socket.

Do not force-kill the tunnel and call that fleet cleanup. SIGKILL, a crash, or another unorderly exit bypasses its shutdown path and can leave separately spawned child process groups alive. Use the orderly SIGINT/SIGTERM path; after an abnormal exit, reconcile process ownership explicitly before starting another stack.

A hub-only restart leaves aether-mcp alive. Its caches have no hub-epoch key, while a new hub can reuse old engine_id text. A cached kind or component description can therefore refer to the prior epoch.

Before a hub restart

1. Select one coordinator and stop new mutations.
2. Take a fresh list_engines(show: "alive") snapshot.
3. Identify the owner of every engine. If any owner is unknown or another harness user may still be active, stop and ask.
4. Preserve logs, traces, frames, recently-dead details, and application-owned state that will be needed afterward.
5. Resolve interrupted operations. A lost reply does not prove that the mutation never landed.
6. Decide whether terminating one owned engine is sufficient.

Do not infer permission from a quiet fleet, an unhealthy heartbeat, or the fact that your session originally started the tunnel.

Issue one restart

Use one coordinator and send one POST /admin/restart-hub. Do not issue concurrent restart requests, and do not blindly retry an uncertain response. The admin route does not carry an idempotency key or task lease; reconcile the observable process and fleet state before deciding whether another request is necessary.

This operator discipline does not make restart transactional. The admin route and the tunnel's automatic supervisor do not share a restart lease, so even one request can race a hub death detected by the supervisor. Avoid an admin restart while the hub is flapping or status is unstable. A race can hang the request or leave child tracking ambiguous; stop and reconcile process ownership instead of sending another restart.

A successful admin response proves that its replacement fork returned. It does not prove exclusive child tracking, that hub RPC is already ready, that an engine was restored, or that the old application state survived.

If the call fails or its reply is lost:

1. read /admin/status once;
2. wait for a read-only list_engines call to succeed;
3. treat the result as a new epoch if the hub was replaced;
4. escalate rather than repeatedly cycling an ambiguous shared stack.

Begin the new epoch

After a restart:

• discard every pre-restart engine_id, mailbox id, loaded-component handle, heartbeat age, and recently-dead assumption;
• reacquire the fleet with list_engines;
• re-list stored binaries and components, using exact hashes where identity matters;
• spawn replacement engines explicitly;
• rebuild live state only from known inputs or an application persistence contract;
• treat cached descriptions as hints until a harmless live probe confirms the new engine;
• restart and reconnect aether-mcp only when a clean cache boundary is worth losing the current MCP session.

Transport reconnection is not state recovery. Do not describe a re-dialed hub or a reused identifier as the same engine.

Per-engine termination remains forceful

terminate_substrate is narrower than a hub restart, but it is still not an application shutdown handshake. Preserve evidence and application state first. The tool removes the fleet row and asks the proxy to shut down; proxy teardown then force-kills and reaps its owned child. Verify the row disappears, but do not interpret the response timestamp as proof that every OS teardown side effect was already visible at that instant.

Source routes

• Tunnel topology and lifecycle decision: ADR-0089
• Tunnel supervisor and admin routes: crates/aether-mcp/src/bin/aether-tunnel.rs
• Fleet table and logical termination: crates/aether-fleet/src/server/runtime.rs
• Proxy child ownership and forceful teardown: crates/aether-fleet/src/proxy/runtime.rs
• MCP fleet orchestration: crates/aether-mcp/src/tools/engine.rs

Engine fleet

The hub supervises a fleet of substrate child processes. Every engine-facing tool is routed through that hub by engine_id; the caller does not connect to a substrate's RPC port directly.

This page covers fleet ownership. Component artifacts and live instances are covered in Component registry.

Current fleet tools

list_engines accepts show: "alive", "dead", or "all". The unrequested list is absent, not empty. Use alive for routine liveness checks and dead for focused failure forensics.

Engine identity and ownership

An engine_id is minted by the current hub process and indexes its current in-memory fleet table. It is not a durable engine identity, a store key, or a port alias. After a hub restart, reacquire the fleet with list_engines; do not reuse an id captured before the restart. The process-local sequence resets, so even the same UUID text appearing later is not proof of engine continuity.

The hub owns the child process mechanically. The caller still owns the operational decision to keep or terminate an engine:

• If your task called spawn_substrate, record the returned id and terminate it during cleanup unless the user asked to preserve it.
• If you found an engine through list_engines, assume it is shared until its owner says otherwise.
• If a task loses track of its id, reconcile against a before/after fleet snapshot. Never terminate “the only engine” merely because it looks likely.

terminate_substrate removes the engine from the live table, records a deliberate terminated death, and tells the proxy to shut down. Dropping that proxy force-kills and reaps the child it spawned. The public surface is forceful, not a graceful application shutdown handshake.

The hub materializes each executable under a per-engine scratch/handle-store directory. Current termination does not remove that directory, and MCP exposes no scratch cleanup tool. Retention or reclamation under the configured engine store root is a hub-operator responsibility, not something an agent should delete while cleaning one fleet row.

Upload before selector

spawn_substrate resolves a selector against the hub's stored binary registry. It does not accept a host executable path.

Use this order:

1. Call list_binaries with the chassis, linked-cap, or target filters you actually require.
2. If no stored entry matches, call upload_binary with its absolute fleet-host staged_path and, optionally, a useful name. Pass pin: true when the hash must survive LRU without a name; pin: false (the default) never clears an existing pin.
3. Capture the returned content hash.
4. Pass a hash, name@version, or name as the spawn_substrate selector.
5. Omit the selector only when the stored default headless chassis is the intended choice.

The hub reads and hashes the uploaded path and runs the binary's --describe surface to capture its manifest. Re-uploading identical bytes deduplicates to the same hash. A name is a movable pointer; a content hash selects exact bytes for spawn. Durable explicit pin is a sidecar flag on that hash, set at upload with pin: true or later with pin_artifact. unpin_artifact removes only that flag — a name still protects, and there is no delete or unname tool.

The hub also protects, for as long as it is running them, the binaries of the engines it supervises: an engine that is committed, still staging, or waiting out a restart backoff holds its resolved content hash against LRU eviction. So re-uploading over the name a live engine was spawned from cannot reclaim the bytes it is executing, and its automatic restart still finds the recipe it replays. That hold is not the operator's pin — it is never persisted, it disappears with the hub process, and neither pin_artifact nor unpin_artifact changes it. Loaded components are not held this way; the hub does not supervise them. Fleet and MCP must ship the same release: the pin field changes the typed upload kind schema.

Running --describe is immediate native code execution, not passive manifest inspection. Upload only a task-built executable in a stable private path or an exact build the operator approved. Never upload a download, attachment, or unknown executable to discover what it is, and do not treat its self-reported manifest as attestation. Follow Artifact trust and provenance for the complete boundary.

Selector choice

Selector resolution happens before the hub allocates an engine id. A selector miss therefore leaves no engine to reap.

Spawn checklist

Before spawning:

• Snapshot list_engines(show: "alive").
• Confirm the binary exists with list_binaries.
• Decide whether headless or desktop behavior is required.
• Upload every boot component before referring to its selector.
• Give boot components explicit names when later automation must address them predictably.
• Ensure every derived boot lineage is unique across component specs and replica suffixes.

After spawning:

• Store the exact returned engine_id and rpc_port as evidence.
• Confirm the id appears in list_engines(show: "alive").
• If components were requested at boot, inspect each configured/expected lineage with describe_component.
• Query describe_handlers or a narrow describe_kinds selection before sending unfamiliar mail.
• Establish log cursors for actors you will monitor.

spawn_substrate may take a components list. The MCP layer first resolves each component selector from the hub registry, stages temporary wasm/config files and a boot manifest, and asks the new substrate to read them. The substrate loads the boot components in manifest order, one at a time, and binds its RPC port only after every one has answered its load Ok, so the proxy's first successful dial means every boot component is live. A boot component that fails to load, including two specs that derive the same lineage name, makes the substrate exit nonzero with the component and the host's error on its stderr, and the spawn fails with a spawn_failed entry rather than leaving a half-booted engine running. A boot load that does not answer within the boot-load budget (AETHER_BOOT_LOAD_BUDGET_SECS, default 20 s) fails the boot the same way, naming the component, so the spawn fails with that name in its spawn_failed detail. A successful tool reply therefore proves that every boot instance loaded. Describe a component before relying on its handlers.

spawn_substrate may also take a mails list — init mail (each entry {address, kind_name, params?}, a send_mail item without engine_id) dispatched straight after the spawn reply, when every boot component is already live, so an entry addressed at a boot component never races its load. Each item settles like a send_mail item and the response carries a per-item mails status list alongside the engine information, so a failed init is visible in the spawn reply itself. Items are best-effort: the engine is live by the time the bundle runs, so one item's failure aborts neither the spawn nor its siblings — read the statuses. This is the world-initialization surface; keep capture_frame.mails for frame-scoped placement at observation time.

Liveness and death evidence

Each live row includes last_heartbeat_age_millis. It is an observation of the last confirmed proxy heartbeat, not an application health check. A low age shows the substrate is answering pings; it does not prove a particular actor or handler is correct. This signal is meaningful only while hub heartbeats are enabled; when they are disabled, the age grows from initial connection even for a healthy engine. With heartbeats enabled, a rising age is a reason to stop adding mutations and collect what evidence is still reachable. The fleet row does not expose the enablement setting; confirm it from hub configuration or the hub operator.

Recently-dead rows distinguish:

The recently-dead list is a small bounded ring, not an audit log. Capture a relevant row promptly. died_age_millis is relative observation, not a durable timestamp.

If startup fails after id allocation, the error includes that id and the hub records a matching spawn_failed entry. If the failure occurs before allocation (for example, selector resolution), no id exists. A failed spawn whose substrate never reported a port records rpc_port 0.

prepare_fork materializes the stored binary and fork+execs it for both the initial spawn and an automatic restart. A materialization or process-spawn failure's detail — the same string on the spawn Err and the matching spawn_failed ring entry — names the stage, the binary content hash, and a path-free IO category (ErrorKind and an OS error code when the host supplies one). It does not include the realized executable path, the store source, the fleet scratch root, or the application-name filename.

A substrate that exits during startup — an unknown flag, a boot error — reports the spawned substrate exited during startup (exit code N) followed by ; stderr: and at most 2 KiB of the end of what the child wrote to stderr, such as clap's usage error. A proxy that fails to connect for any other reason keeps its proxy error and gains the same stderr suffix when the child wrote anything. In that tail the realized executable path and the fleet scratch root are redacted to <substrate> and <fleet-store>, and terminal colors are stripped. The tail can still name the application name the caller passed, since clap prints it in its usage line, and it can carry any other host path the child itself chose to print. Pre-allocation errors are unchanged.

A live engine's stderr still streams to the hub's log as the engine writes it; only a failed spawn's detail carries a copy of the end of it. Stdout stays inherited by the hub.

Restarts and persistence

A hub restart requires authority over the whole fleet; discovering a process or engine row does not supply it. Coordinate one request with every active harness user and follow Harness lifecycle before using the admin endpoint.

A tunnel-admin hub restart preserves the MCP session shape and the on-disk artifact store, but replaces the hub process. Its engine table, proxies, and child substrates do not survive as usable fleet members. The MCP RPC client can re-dial the fresh hub, but that transport recovery does not revive engines or make their old ids valid.

After any hub restart:

1. Retry a read-only list_engines if the call that crossed the restart failed.
2. Treat all pre-restart engine ids and loaded component addresses as stale.
3. Re-list stored binaries/components; their content store is intended to persist.
4. Spawn replacement engines explicitly and rebuild live state from known inputs. Do not claim guest state recovery unless the application has a separate persistence contract.

Restarting aether-mcp itself invalidates the MCP session and clears its local description caches. Name-addressed describe_component remains able to ask a live substrate directly after reconnect.

A hub-only restart intentionally leaves aether-mcp running, so its caches are not cleared. They are keyed by engine_id, and a fresh hub can reuse the same id text. Treat cached kind/name/component descriptions as potentially belonging to the prior epoch. If exact clean introspection is required, a deliberate aether-mcp restart plus MCP reconnect is the current cache-reset boundary.

Time bounds and honest readiness

Fleet operations do not share one universal timeout:

• The hub forks each substrate with --rpc-port 0 --rpc-port-file <path>: the substrate binds a port it picks and writes it to that file once it is reachable, and the proxy dials only that reported port while the substrate is alive. A foreign RPC server on the host therefore cannot answer for an engine.
• Proxy startup has a hub configuration budget that covers both waiting for the port report and dialing the reported port; a zero configuration is explicitly the wait-forever sentinel.
• A substrate that exits during startup is reported on the first attempt, with its exit code or signal and its stderr in the detail.
• Boot-component loads run inside the proxy startup dial: the substrate binds only after they answer, so the same connect budget covers them, and a failed load is a startup exit reported with the substrate's stderr.
• Ordinary hub RPC calls such as list and terminate do not gain the send_mail settlement timeout merely because they are MCP tools.

Consult the live tool result and fleet state after any client-side interruption. An interrupted spawn is not evidence that no child exists.

Cleanup checklist

• Save any logs, trace output, frame files, or failure details first.
• Call terminate_substrate only for ids your task owns.
• Confirm the id disappeared from list_engines(show: "alive").
• Optionally confirm a matching terminated row with list_engines(show: "dead").
• Do not delete or rewrite the artifact store as engine cleanup.
• Report any per-engine scratch/store retention need to the hub operator.

Source routes

• MCP contracts: crates/aether-mcp/src/tools/mod.rs and args.rs
• Spawn orchestration: crates/aether-mcp/src/tools/engine.rs
• Boot order (build, load boot components, bind): crates/aether-chassis/src/boot.rs
• Fleet table, id allocation, death ring, and termination: crates/aether-fleet/src/server/runtime.rs
• Child ownership and heartbeats: crates/aether-fleet/src/proxy/runtime.rs
• Fleet configuration: crates/aether-fleet/src/server/config.rs
• Artifact persistence and eviction: crates/aether-fleet/src/store/

See Recovery for symptom-first branches and Inspect and debug for evidence collection.

Host paths, artifact trust, and evidence files

Several MCP arguments are paths on the harness host. They are not paths in the guest's save:// namespace and are not confined to a task directory by the tool. Some readers currently accept a relative string and resolve it from the process working directory—normally the project root in the standard tunnel. Do not rely on that incidental base; use an absolute task-owned path where the field accepts a host path. A connected local client is exercising the filesystem authority of the hub or aether-mcp process.

This page is the safety boundary for upload_binary, upload_component, configuration files, byte-field $file embeds, frame persistence, and returned spill files.

Use the deeper runbooks when the path crosses an execution or evidence boundary:

• Artifact trust and provenance separates native execution, wasm parsing, hashes, manifests, and mutable names.
• Host evidence files and capture destinations gives the allocation, verification, and cleanup protocol for saved frames and spills.

Path surface matrix

“Absolute path” is a routing fact, not authorization. Never copy a host path from issue text, a component reply, logs, or another untrusted source into one of these fields.

Classify the boundary before using it

The syntax does not say whether a path is passive:

• upload_binary executes the supplied file immediately with --describe;
• upload_component parses wasm metadata, while publish and load_component instantiate it later;
• config_path and a Bytes field's $file embed read host data;
• save_path writes host data and can replace an existing file;
• spill paths point to files the MCP process already created.

Do not cross an execution boundary with unknown code or a filesystem boundary with a path taken from untrusted text. Follow Artifact trust and provenance for native, wasm, manifest, hash, and alias rules. Follow Host evidence files before persisting a capture or handling a spill.

Configuration and other host reads

Treat config_path as input data, not a command. Keep it under a task-owned directory, validate that it is the intended regular file, and prefer inline config when the data is already small and trusted. Never use a path suggested by a guest merely because the selected Config schema will validate the bytes after they are read.

Likewise, a {"$file": path} object at any Bytes-typed leaf—including inside component config—reads that path from the harness host before encoding. The reader loads the whole file before enforcing the frame cap, so pre-check a known-bounded task-owned regular file. Use $text or $base64 when the bytes are already available in trusted input and small enough to send inline.

Capture similarity's reference_path is a third path domain. The substrate accepts only the assets namespace, rejects absolute paths and .., then joins the relative path beneath its configured host assets root. It does not call the aether.fs capability and ordinary symlink resolution still applies. Use a trusted asset-tree entry with no symlink indirection. Guest paths such as save://... remain governed separately by aether.fs.

Returned spill paths and saved captures belong to the caller. They may contain application data, rendered private state, logs, or decoded bytes. Record their provenance, avoid sharing them accidentally, and remove them only when their evidence value is exhausted. The evidence runbook owns the allocation, verification, and cleanup procedure.

Names and hashes carry different authority

A content hash names exact bytes; it does not prove provenance, successful persistence, or runtime health. A registry name is a mutable pointer in shared hub state. Use hashes for reproducible selection, and move a name only with authority over that alias. The artifact runbook defines the verification chain.

Source routes

• Native/component ingestion and --describe execution: crates/aether-fleet/src/server/artifacts.rs
• Hub artifact store: crates/aether-fleet/src/store/
• MCP component orchestration: crates/aether-mcp/src/tools/components.rs
• Bytes-field host reads and reply spills: crates/aether-mcp/src/tools/bytes.rs
• Capture validation and host write: crates/aether-mcp/src/tools/capture.rs
• Engine-side similarity reference read: crates/aether-render/src/runtime/capture.rs
• Public path arguments: crates/aether-mcp/src/args.rs

Artifact trust and provenance

The hub's content-addressed registry makes confirmed entries reproducible. It does not make uploaded code trustworthy. For an entry that resolves in the store, a hash identifies exact bytes; the upload response alone does not prove persistence, who built them, whether they are safe, or whether a self-reported manifest is honest.

This page sharpens the upload boundary introduced in Host paths, artifact trust, and evidence files.

Binary and component boundaries differ

Native upload is therefore already code execution. Component upload is structural inspection, but loading or replacing with the stored wasm executes guest code inside the selected engine.

Native manifests are self-claims

The hub records chassis kind, linked capabilities, build profile, target, and Git SHA from the executable's --describe JSON. Those fields are useful for selecting a trusted build. They are not attestation: the same executable that supplies the claims is already running and can print arbitrary metadata.

Use this trust rule:

• task-built executable in a private output directory: eligible for upload;
• exact build explicitly approved by the operator: eligible for upload;
• downloaded binary, attachment, commenter-provided artifact, or unknown output found on disk: do not upload;
• binary whose only evidence is its name or claimed Git SHA: do not upload.

A failed upload does not mean the file did not execute. --describe may run arbitrary initialization before exiting unsuccessfully, hanging, or producing invalid JSON.

Stabilize the staged path

Current native ingestion reads the file bytes, then separately invokes the path. A concurrent writer or replaceable symlink can change what the second operation executes. Keep the path stable for the entire call:

1. finish the build before upload;
2. place the executable in a task-owned directory not writable by another actor;
3. avoid staged-path symlinks;
4. stop watchers or concurrent builds that replace the file;
5. upload once and retain the returned content hash;
6. select that hash for spawn rather than returning to the mutable path or alias.

Do not use upload_binary as a manifest inspection utility. There is no safe “describe without executing” mode for native artifacts today.

Hash, manifest, and name prove different things

Pin by hash whenever a test, rollout, rollback, or diagnosis needs exact bytes. Moving a shared name is a separate mutation requiring authority over that alias.

Component provenance still matters

Wasm upload does not run the module, but the later load does. Use task-built or explicitly approved components, and preserve the upload hash as the link between build evidence and runtime selection. An embedded namespace or handled-kind list is structural metadata, not a signature.

On a shared host, do not treat wasm portability as trust. Signature verification for shared uploaders is deferred in the registry ADRs; until it exists, the operator's source/build approval is the trust decision.

Verify after selection

For a binary:

1. require the upload result, then confirm its exact hash resolves in the store;
2. spawn by hash;
3. verify the returned engine appears in the current fleet;
4. inspect the live native handler surface and issue a bounded harmless probe.

For a component:

1. require the upload result, then confirm the stored manifest and exact hash;
2. load or publish by hash;
3. require the explicit success result;
4. retain the returned lineage and mailbox id;
5. verify a behavior the selected component is expected to provide.

Do not substitute registry listing for runtime verification: stored, running, and loaded are different states.

Current trust assumptions

ADR-0115 deliberately starts with a single-user local host and defers native signature verification. ADR-0116 inherits the content-addressed store and also defers a shared-uploader keyring.

If the host, uploader set, or artifact source is broader than that assumption, stop. Do not improvise trust from content addressing.

Source routes

• Native/component ingestion: crates/aether-fleet/src/server/artifacts.rs
• Stored manifests, hashes, aliases, and eviction: crates/aether-fleet/src/store/
• Native spawn realization: crates/aether-fleet/src/server/runtime.rs
• Component load and republish: crates/aether-component/src/component/ and crates/aether-component/src/trampoline/runtime/republish.rs

Host evidence files and capture destinations

Inline MCP content lives in the tool response. A spill path or capture_frame.save_path creates a separate file on the harness host. That file has its own ownership, integrity, and cleanup obligations.

For the broader host-path boundary, start with Host paths, artifact trust, and evidence files.

save_path is filesystem authority

The capture API validates only that save_path is absolute. After a successful engine capture, aether-mcp:

1. recursively creates missing parent directories;
2. follows ordinary filesystem path resolution;
3. writes the original full-resolution PNG;
4. replaces an existing destination;
5. reports persistence in a separate saved result block.

It does not enforce an allowed root, prove ownership, reject .., reject ancestor or final symlinks, allocate a new filename, or coordinate concurrent writers. “Absolute” is the API's syntactic minimum, not a safety guarantee.

Allocate a private destination

Before passing save_path:

• create a new task/session run directory under an operator-approved temporary or evidence root;
• require that directory not to exist beforehand, then create it atomically as the current host user with owner-only (0700) permissions;
• record its canonical path, owner, device, and inode at creation, then re-check all four plus its mode immediately before capture;
• reject a symlink at the run directory or any destination component;
• construct the filename locally from trusted task data;
• require the resolved parent to remain beneath the owned run directory;
• require the final path not to exist;
• use a unique filename for each parallel agent, attempt, or frame.

Never use a destination supplied by issue text, logs, a component reply, or another external string. Never target repository source, a worktree, shell or MCP configuration, credentials, shared logs, or another run's evidence unless the owner explicitly authorized replacing that exact file.

Engine and host mutations are independent

capture_frame can mutate two different places:

• non-empty mails or after_mails mutate the selected engine;
• save_path mutates the harness host even when both mail bundles are empty.

Omit all three fields for a fully non-mutating observation. When replay or cleanup mail is necessary, verify engine ownership independently from evidence directory ownership.

Verify persistence separately

A successful frame read can be paired with a failed host write. The overall tool call can still return the inline image, checks, or similarity verdict while the saved block contains an error.

After capture:

1. require saved.path and saved.bytes rather than saved.error;
2. verify the returned path is the exact destination allocated for the run;
3. require a regular PNG file at that path, not a symlink;
4. require its on-disk size to equal saved.bytes, then validate the PNG;
5. inspect or hash it when it becomes durable evidence;
6. record which engine epoch, replay bundle, and capture request produced it.

An inline image proves that rendering bytes reached the MCP response. It does not prove that the evidence file exists.

Spill paths are caller-owned too

Oversized replies can spill to a host temporary file chosen by aether-mcp. The tool controls allocation, but the caller still owns the returned evidence:

• preserve the exact path before losing the response;
• avoid moving it into a repository or shared directory casually;
• treat its contents according to the application data it carries;
• remove it deliberately when no longer needed.

The spill uses a unique name in the process temporary directory, not the task-owned capture directory. Do not assume it has evidence-store retention or confidentiality guarantees. Capture files and spills can contain private state; move sensitive evidence into an approved private store when required, and do not widen permissions merely to make inspection convenient.

Cleanup

At handoff, report every evidence path and one disposition:

• preserved as part of the incident/trial record;
• transferred to an explicitly named owner;
• removed after its evidence value was exhausted;
• retained unintentionally because cleanup failed.

Do not claim a clean run while untracked host evidence or an owned live engine remains.

Source routes

• Capture path validation and persistence: crates/aether-mcp/src/tools/capture.rs
• Capture argument contract: crates/aether-mcp/src/args.rs
• Reply spill allocation: crates/aether-mcp/src/tools/bytes.rs
• Engine-side capture and checks: crates/aether-render/src/

Component registry

Aether has two component inventories with different owners. The hub knows which wasm artifacts are stored. A substrate knows which component actors are live. Treating one as proof of the other causes most component-operation mistakes.

Three views, three meanings

Registry list_components is deliberately artifact-facing. It does not list loaded instances. The same artifact can be loaded zero times, once, many times on one engine, or into several engines.

Current component tools

There is no dedicated drop_component MCP tool. Dropping is nevertheless a current engine operation: use send_mail to the aether.component mailbox with kind aether.component.drop and target set to the exact address returned by the load. Inspect that kind with describe_kinds before constructing params. Await its aether.component.drop_result; do not fire-and-forget cleanup.

Drop runs the guest's unwire, releases the wasm, and closes the instance (ADR-0241 §8). The close purges capability-owned subscriptions and routes through each watcher's MonitorNotice, and the name tombstones for the engine's lifetime: a later load of it is refused as retired, and a second drop at the path is refused. A drop that arrives while the instance's module republishes waits until the republish answers. Load or spawn under a new name to bring the component back.

Upload before selector

Only upload_component accepts a filesystem path. publish, load_component, and boot component specs accept registry selectors—not paths and not inline wasm bytes.

The reliable sequence is:

1. Build the wasm artifact on the same fleet host whose path the hub can read.
2. Call upload_component(staged_path, name?, pin?). pin: true records durable explicit protection before this upload's eviction, including unnamed uploads. pin: false (the default) never clears an existing pin.
3. Record the returned content hash and optional name.
4. Confirm its manifest with registry list_components; when no name was supplied, set include_history: true and locate the returned hash.
5. Use the hash or name as the later selector.

Upload reads the wasm manifest without executing the module. It records exported actor namespaces, handled kind ids, fallback presence, and provenance. Identical bytes deduplicate to one hash.

Which selector?

An explicit export field overrides the actor half of module@actor. A module exporting several types must be given an export; an omitted export resolves only against a module with exactly one selectable (non-boot) export, and is otherwise a clean load error naming the exports, not “first actor wins.”

Names are mutable. Re-uploading under the same name repoints it. The old hash remains stored and, once no other name points at it, becomes unnamed history eligible for LRU eviction unless it still carries an explicit pin. It is not deleted by repointing. Hashes are therefore the correct deployment evidence. unpin_artifact removes only the explicit flag; it is not unname or delete.

Stored registry behavior

list_components can filter stored manifests by exported namespace and handled_kind; filters are AND-combined. Its normal result is a bounded, newest-first page of name-pointed entries. include_history: true admits unnamed hashes. Use the returned total_matched and an explicit limit when a complete history is actually needed.

A named artifact is protected from disk-budget LRU eviction. An unnamed, unpinned history entry is eligible. pin_artifact / unpin_artifact (and upload_component(pin: true)) record or drop durable explicit protection on an exact content hash — names are never resolved. pin: false on upload is not unpin. There is still no delete or unname operation. Component runtime protection of stored artifacts is not provided here: the hub holds the binary of every engine it supervises (issue 5686), but it does not supervise a loaded component, so a component's stored wasm is protected by a name or a pin alone. Fleet and MCP must ship the same release: the pin field changes the typed upload kind schema.

Loading into an engine

load_component resolves the selector at the hub, publishes the bytes to the target engine's aether.component cap, then spawns the selected type and waits for its SpawnResult.

On a single load, record both outputs:

• address: the full lineage address used as send_mail.address, the aether.component.drop kind's target, a publish config's address, and by live describe_component.
• capabilities: handled kinds, reply contracts, fallback, docs, and config kind for the selected actor type.

Never reconstruct the lineage from a short load name. Use the returned value, the component's published name: NS for a singleton, NS:key for an instanced type.

Configuration

Pass either inline JSON in config or a JSON-file path in config_path, never both. The MCP layer resolves the selected artifact's declared Config kind and schema-encodes that JSON before loading. Providing config to a component that declares no Config kind is an error. Use describe_component to learn the kind name and describe_kinds for its exact live schema.

Replicas

replicas: N (1..=256; replicas: 0 is refused, and a key combined with replicas is refused, since each replica draws its own counter key) publishes the module once, then spawns N counter-keyed instances of the selected type (NS:0, NS:1, …). An entry that names no replicas spawns the one instance its key names, or a counter key when it names none. The result carries one shared capabilities block, since every instance is the same type, and an instances list of each spawned address and whether it was already live.

A replica fan-out is not transactional. If instance K fails, the instances before it remain live and the error says how many spawned. The failed call does not return the successful prefix's instances records. aether.component.list reports which are live. On a task-owned engine, terminate and start clean. On a shared engine, stop and report the partial prefix rather than guessing addresses or retrying into occupied ones.

Boot-time replicas use the same counter-keyed expansion. The substrate binds only after every boot instance has answered its spawn, so a successful spawn_substrate means every instance is live. A boot spawn that fails fails the boot with a spawn_failed entry rather than reporting the engine ready.

Live introspection

describe_component should normally receive the lineage address. On a cache miss, aether-mcp forwards that name to the substrate, whose registry owns the live answer. This works for boot-loaded components, after an aether-mcp restart, and after a successful in-place replacement.

The process-local capability cache is consulted before that live query. Loads and replacements refresh it, but a generic aether.component.drop sent through send_mail does not invalidate it. In that case, a same-process describe can return pre-drop capabilities. The successful drop_result is the unload proof; only a later name lookup after a cache reset is guaranteed to miss the cleared substrate capability registry.

The cache is keyed by engine and canonical path, with no hub-epoch component. After a hub restart reuses an engine_id, a boot-loaded component at the same lineage can collide with an earlier capability entry. Use live probes or reset/reconnect aether-mcp when an exact clean-epoch description is required.

An address is a lineage or a short path. Keep the lineage address as the durable observation handle for the life of the engine.

The live kind vocabulary is also substrate-owned. Loading registers the wasm's kind descriptors into the same registry served by aether.inventory. describe_kinds(engine_id: …) reads that view. The mail encoder refreshes its per-engine cache once on an unknown kind or a stale-schema encode failure, but the cache does not make an unloaded kind live. Kind descriptors are not removed when a component drops, so kind presence is vocabulary evidence, not component liveness evidence.

The standalone description call currently suppresses a failed live refresh and can return its static/prior snapshot. Use a bounded live probe when freshness or engine reachability matters.

Replacing safely

A publish of a successor republishes a module (ADR-0241 §7). Pass the current engine id and a previously uploaded selector; prefer a content hash so the successor is unambiguous. A publish names no instance and takes no module@actor selector: every live instance of every namespace the module publishes moves to the successor together, or none does, and each keeps its address and mailbox.

Identical bytes answer Ok with no swap. Before any instance is touched the host refuses the whole republish, naming each instance a check refuses, when the module is content-addressed, already has a republish in flight, declares a boot or succeeds one that did, drops a namespace or narrows a handler row or fallback of one, adds a dependency that is not live to a live instance's type, or leaves an instance without a config of its type's kind. An instance whose type's config kind changed needs a configs entry, {address, config | config_path}, which the harness encodes to the successor's Config kind; every other instance keeps its stored config. An inline child cannot be given a config, so a config-kind change on a live inline child's type is refused.

Then every instance prepares its successor while mail for it waits at its inbox gate, the module publishes, and every instance commits, unwiring the old guest first and receiving the waiting mail in order. The reply, {engine_id, types: [{namespace, capabilities}]}, comes once every commit's chain has settled. A refusal while preparing, or a publish failure, aborts every instance: each unwires its candidate exactly when that candidate wired, reinstates its old guest, still wired, which gets back the state its on_dehydrate saved through its on_rehydrate, with no second wire. Only teardown outside that saved state and outside what wire built stays gone. Nothing a failed successor sent leaves. Loads and drops of the module's namespaces that arrive meanwhile wait for the answer.

Require an explicit successful result, then re-run describe_component and a safe probe. After an error MCP's cache and the capability registry describe the old handler sets, which a reinstated guest may no longer fully serve if its hooks tore down state its saved state does not carry. Use Replacement failure states rather than treating describe_component as rollback proof.

Component cleanup

For a task-owned instance in a shared engine:

• Preserve its logs and any trace evidence.
• Send settled aether.component.drop through send_mail.
• Require aether.component.drop_result success.
• Do not use a same-process describe_component cache hit or lingering kind descriptor as unload confirmation.
• Record that the name is retired, not freed: a reload needs a new name.

For an engine wholly owned by the task, terminating the engine is the simpler complete cleanup: all its live registries and components die with it. This does not delete the hub's stored component artifacts.

Source routes

• Tool contracts and shapes: crates/aether-mcp/src/tools/mod.rs and args.rs
• Upload/list/publish/spawn/load orchestration: crates/aether-mcp/src/tools/components/
• Selector resolution, boot staging, and live kind caching: crates/aether-mcp/src/tools/state.rs
• Hub artifact store: crates/aether-fleet/src/store/
• Component host publish/spawn/load/list/describe/drop: crates/aether-component/src/component/
• Drop-closes-the-instance behavior: crates/aether-component/src/trampoline/runtime/mod.rs
• Trampoline republish behavior: crates/aether-component/src/trampoline/runtime/republish.rs
• Live kinds: crates/aether-inventory/src/

For failure branches, continue with Recovery.

Replacement failure states

A publish of a successor republishes a module over every live instance of its namespaces as one group (ADR-0241 §7): on success every instance runs the successor behind its unchanged mailbox, and on failure every instance runs its old guest. An error is still not a clean rollback signal. Depending on which phase failed, an old guest may already have run its on_dehydrate hook. It gets back the state its on_dehydrate saved, through its on_rehydrate, with no second wire; only teardown outside that saved state and outside what wire built stays gone. Nothing a successor sent leaves: its mail is held until the group commits, and a failed successor's mail is discarded. Introspection can also describe a retained capability snapshot rather than the state an installed guest is actually in.

Read Component registry first for normal publish, spawn, load, and drop behavior.

Phase-dependent residue

The exact phase matters more than the generic Err shape. Do not say “replacement rolled back” unless a current behavioral observation proves the old guests still serve their mailboxes.

An unwire guest trap at commit is different: it is logged and contained rather than returned as PublishResult::Err, and the commit goes on. Do not mistake an unwire trap log for a rolled-back swap.

An on_dehydrate guest trap aborts the engine (ADR-0063, ADR-0249 §2). The guest that trapped is the live one and runs no more code, so there is nothing to reinstate: the publish gets no answer, and the engine's exit reason names the component and the hook.

A reinstated old guest can itself refuse. When its on_rehydrate returns an error for the state it saved, that instance closes: each reply it held is answered unanswered, the mail its gate queued is dropped, and its name is spent, so a later load of the name is refused as retired. The publish still answers Err with the refusal that aborted the group; the close is reported in the instance's log. A trap there aborts the engine.

Why describe_component can mislead

There are two description layers:

1. aether-mcp returns a process-local cache hit immediately. It refreshes that cache on a successful load or publish, but retains the prior entries on a publish error.
2. On a cache miss addressed by lineage name, the substrate returns its capability registry entry. Some post-splice failures happen before that entry is removed or replaced.

After a failed replacement, restarting only aether-mcp can bypass its cache and still obtain a stale substrate registry entry. Kind presence and cost rows can likewise outlive or disagree with the currently installed guest. Treat all of them as snapshots, not liveness or binary-identity proof.

Recovery protocol

After any publish error:

1. Stop further lifecycle mutation on the module's instances.
2. Record the exact selector/hash, configs, the instances the error names, the error, logs, and pre-replace capabilities.
3. Call describe_component by lineage only as supporting evidence; label a cache hit or live-registry reply as potentially stale.
4. Use one known side-effect-free application query that distinguishes the old and new build when such a query exists.
5. If no safe discriminating probe exists, classify the slot as indeterminate.
6. On a task-owned engine, prefer terminating and recreating the engine from known hashes over repeated splice attempts.
7. On a shared engine, stop and report the indeterminate mailbox to its owner. Do not drop, refill, or retry by guess.

A roll-forward by known-good hash is appropriate only after the owner accepts the current state and the mailbox is still safe to mutate. There is no drain knob to reach for: the splice is structural, so no argument slows or retries it.

Designing a discriminating probe

A useful probe:

• is documented as read-only or idempotent;
• has a bounded reply;
• is handled differently by the candidate builds or proves required state;
• does not depend on a kind that may itself be stale only in the MCP encode cache;
• records its exact request and reply as evidence.

If the only available operation mutates application state, do not use it merely to answer “which guest is installed?” Recreate an owned engine or escalate a shared one instead.

Success verification

Even after PublishResult::Ok:

• retain the exact content hash used;
• compare each returned type's capabilities with the expected one;
• run a harmless live probe;
• confirm downstream senders still address the stable lineage;
• treat a mutable registry name only as provenance context, not selected-byte identity.

Source routes

• Group pre-checks, prepare, publish, commit and abort: crates/aether-component/src/component/runtime/republish/
• One instance's prepare, commit and abort: crates/aether-component/src/trampoline/runtime/republish.rs
• Substrate live component description: crates/aether-component/src/component/runtime/mod.rs
• MCP publish result and cache update: crates/aether-mcp/src/tools/components/publish.rs
• MCP description cache and live fallback: crates/aether-mcp/src/tools/describe.rs
• Live kind cache contract: ADR-0091

Inspect and debug

Debug a live engine from the outside in: prove the fleet target, learn its live surface, issue the smallest safe probe, then gather actor-local evidence. This order prevents a schema guess or stale engine id from masquerading as an application failure.

Observation map

1. Pin the target

Start with list_engines(show: "alive"). Record the engine_id, RPC port, and heartbeat age together. If the engine id came from an earlier hub lifetime, discard it and select from the current list.

In a multi-engine fleet, pass engine_id explicitly to every engine-scoped inspection. In particular, a bare describe_kinds only auto-selects when exactly one engine is supervised. With zero or several engines it intentionally falls back to the static substrate vocabulary, which omits the live component set and must not be presented as that engine's inventory.

2. Learn the live contract

Use the narrowest introspection call that answers the question:

• Start describe_kinds with families: true for a digest.
• Use prefix for one namespace or names for exact kinds.
• Add detail: "schema" only after selecting prefix or names; a bare schema-detail request is rejected to keep responses bounded. families: true ignores detail.
• Use describe_handlers for native mailbox request → reply contracts.
• Use describe_component for a wasm component's handlers, reply contracts, fallback, docs, and Config kind.
• Use compare_component_contracts before switching consumers to a revision. Give both a baseline and a candidate subject, each { engine_id?, address } with a textual address; separate engines are expected when one revision changes a kind schema that a single registry correctly refuses to host twice. The comparison resolves each textual lineage to its canonical mailbox identity, refreshes each engine's kind inventory live, then reports deterministic additions, removals, and exact changes. It is deliberately conservative: removing a handler, changing an input or declared reply contract, adding/removing/changing Config, or losing fallback is incompatible. New handlers and gaining fallback are additive. It does not judge rustdoc, build provenance, costs, logs, or assets. A refresh, decode, or lookup failure is inconclusive and returns an error; never treat a cached or partial comparison as a compatibility verdict.

describe_kinds merges the MCP static baseline with the substrate's live aether.inventory.kinds response. The substrate serves its shared registry, so component-defined kinds become visible as soon as loading registers them. The refresh is best-effort and merged into the existing per-engine cache; a failed live query leaves prior data rather than marking it unavailable. Use a kind description to construct mail, not as sole proof that an actor is live.

describe_component first checks a process-local capability cache. On a miss, a lineage name resolves live against the substrate. Keep the exact name returned by load or boot discovery; it enables that fallback. A tagged mailbox id works only when the local MCP cache already has that (engine, mailbox) entry.

publish, spawn, and load_component populate the cache. A generic component drop through send_mail does not invalidate it, so a later same-process describe can show stale pre-drop capabilities. Likewise, component kind descriptors remain in the engine registry after drop. Neither observation alone proves the guest is still loaded.

Hub restarts do not clear these MCP caches, while the new hub can reuse an engine_id. Begin a new hub epoch with fleet discovery and live probes. Restart and reconnect aether-mcp only when a clean cache is required and session invalidation is acceptable.

3. Probe with settlement

Use send_mail for independent calls. Each item is best-effort relative to its siblings: one item can error without aborting the rest. By default an item waits for its causal chain to settle and returns the terminal reply plus recognized errors. Choose replies: "all" when an event stream matters and "none" when only recognized failures are useful.

Use send_mail_traced when any of these are true:

• every spec must validate before any of the batch moves;
• the whole batch needs one shared causal root;
• handler and queue timing matter;
• settlement itself is under investigation.

The default traced projection is a compact, indented tree. trace: "nodes" returns the complete per-node mails vector instead, omitting tree and carrying the same node_count; a tree a trace ring cut also carries truncated, naming each actor whose ring dropped entries it needed. There is no separate public MCP trace_tail tool; send_mail_traced performs the guided ring walk internally.

trace and detail select a render shape; full on the component tools means "expand documentation" and never switches a reply shape. format on the two mail tools is a reply mask that re-spells chosen reply leaves as hex (see Sending mail).

Do not use fire_and_forget as a health check. dispatched confirms the call was written or its immediate traced ack arrived; it does not prove downstream work completed.

4. Read actor-local evidence

actor_logs queries exactly one mailbox. Use level and contains to filter inside the actor, and thread next_since into the next call's since so a poll does not duplicate entries. Preserve truncated_before: it proves the bounded ring evicted unseen entries.

Only tracing::* emitted while an actor handler is dispatched enters that actor's ring. Substrate boot, scheduler, proxy, panic-hook, and other host-side events go to process stderr instead. An empty ring is therefore not proof that the host emitted nothing. See Logging.

actor_cost reads one actor's per-handler execution-cost EWMA. A row gives mean and mean absolute deviation in nanoseconds plus a sample count. It is measure-only: reading it does not change scheduling, and an EWMA is not a full distribution. A zero sample count is a seeded handler, not observed work.

There is no memory tool: send aether.inventory.memory (empty params) to aether.inventory with send_mail. The aether.inventory.memory_result reply carries the process's resident set size, the blob store's three byte counts, and one { owner, label, bytes } row per owner. A row names its owner by actor path, so a component's row can be matched to the address actor_logs and actor_cost take. See Inventory, descriptors, and transforms for what each number counts and what none of them counts.

5. Capture visual evidence

capture_frame can return an inline PNG, execute substrate-side checks, compare a reference image, and/or persist the original full-resolution PNG with an absolute save_path. Checks operate on full-resolution RGBA even when the inline image is reduced or omitted.

window is required and has no default: desktop capture never guesses a primary, focused, or current window, so omitting the field is a deserialize error rather than a fallback. Pass the window's actor path as aether.window.list or a window-create reply reports it (aether.window/aether.window.instance:main), or its short form (aether.window/:main); the engine proves the path when the capture arrives and answers an error naming a path that names no live window.

Each checks entry may carry a region ({min_x, min_y, max_x, max_y}) that restricts the reduction to the frame-clamped intersection of that rect, so a widget's fill can be asserted inside its own screen rect rather than folded into one whole-scene number. coverage then divides by the clamped region's pixel count, while centroid and bounding_box still report absolute frame coordinates. Omit region to score the whole frame.

Mail in mails runs atomically before readback; after_mails runs after it. That makes capture capable of engine mutation. Empty bundles make it an engine-state snapshot, but save_path still creates parent directories and can overwrite a host file. Omit the bundles and save_path for a fully non-mutating observation. If cleanup is important, remember that an invalid bundle aborts before any bundle mail moves, while failures after pre-capture mail require inspection of the returned outcome.

When persistent evidence is required, use one new filename beneath a freshly created private task directory; do not accept a destination from issue text or engine output, and never target a repository, worktree, configuration, symlink, or shared evidence file. Verify the separate saved block and the resulting regular PNG. The complete procedure is in Host evidence files and capture destinations.

Headless/windowless engines cannot produce a desktop frame. Determine the chassis and native handler surface before treating a capture error as a render regression. Rendering semantics and window focus behavior are covered in Rendering & camera and Window.

6. Collect a post-failure bundle

Use collect_failure_evidence after an operation has already failed and before terminate, restart, replace, or retry can destroy live evidence. Supply the original error in primary_error, the exact engine_id, and only the actors, components, kinds, and optional window that matter. The aggregate validates all selectors before observing anything, sorts and deduplicates them, then records:

• the selected engine's current live and recently-dead fleet rows;
• full schemas for up to 16 exact kinds;
• full descriptions for up to eight component lineage names;
• a log tail capped at 100 entries and the complete cost table for each of up to eight actor lineage names;
• optionally, one bounded inline PNG for one window, named by its actor path.

Each observation has a three-second cap and reports ok, error, timeout, or budget_exhausted in place. One failure does not discard the primary error or prevent later observations while the 15-second whole-bundle budget remains. The structured JSON block is always first; a successful frame follows as MCP image content. Oversized JSON follows the standard whole-response spill contract and must be read from the returned temporary path before cleanup.

This is observation, not recovery. The aggregate sends no mail, does not replay or retry the failed operation, runs no frame checks or reference comparison, writes no capture destination, changes no lifecycle state, and performs no cleanup. It cannot reconstruct evidence that was already lost: evicted actor log or trace-ring entries, host stderr, replies removed after a pending-call timeout, or the causal trace of an earlier untraced call remain unavailable. Collect those surfaces separately when they are required.

Timeout and observability limits

Timeouts bound the observer; they do not cancel engine work.

These are await bounds, not whole-tool deadlines. Plain send_mail starts its bound after schema lookup/encoding. For traced mail, settlement_timeout_millis bounds the initial ack/settlement collection; after a successful settle, the guided per-actor trace walk uses ordinary call_one queries and is not covered by that value.

When a plain mail times out, its MCP pending entry is removed and later replies are not recoverable through that call. Do not blindly resend a non-idempotent operation: the original chain may still finish. Observe state and logs first.

A traced timeout is especially sparse by current contract. It is evidence that the harness stopped waiting before settlement, not a retained trace handle. Reproduce with tracing only when repeating the operation is safe.

Settlement is exact when it reports success, but trace storage is best-effort. Actor trace rings can overwrite old or high-volume data, so a settled tree may be incomplete or unavailable if read too late. Read Tracing & settlement for the distinction.

Evidence bundle checklist

Before terminate, restart, replace, or retry, capture what applies:

• current list_engines(show: "alive") row;
• current list_engines(show: "dead") row if the engine vanished;
• exact binary/component content hash and selector used;
• narrow describe_kinds output for request and reply kinds;
• describe_handlers or describe_component output;
• actor_logs result with cursor and truncation fields;
• send_mail_traced result in either the tree or nodes trace shape, if reproduction was safe;
• actor_cost rows for a slow handler;
• capture verdict and a full-resolution save_path, when visual;
• host/tunnel/substrate stderr for events outside actor handlers.

Large decoded byte leaves and oversized complete tool responses can be spilled to harness-host temporary files rather than truncated. Treat a returned file path as part of the evidence: read or copy it while it still exists, and clean it up when retention is no longer needed.

Source routes

• Tool inventory and public descriptions: crates/aether-mcp/src/tools/mod.rs
• Argument projections and timeout response shapes: crates/aether-mcp/src/args.rs
• Live descriptions: crates/aether-mcp/src/tools/describe.rs and state.rs
• Settlement/timeouts: crates/aether-mcp/src/tools/mail.rs and crates/aether-mcp/src/rpc.rs
• Logs and cost projection: crates/aether-mcp/src/tools/logs_cost.rs
• Capture behavior: crates/aether-mcp/src/tools/capture.rs
• Substrate inventory implementation: crates/aether-inventory/src/

For a failure already in progress, continue with Recovery.

Recovery

Recover from the symptom outward. Preserve evidence, prefer read-only checks, and make the smallest mutation with clear ownership. A timeout, tool error, and dead engine are different states; do not collapse them into “restart everything.”

First response

For any unexpected result:

• Stop sending additional non-idempotent mail.
• Record the exact tool, arguments, selector/hash, and returned error.
• Call list_engines(show: "alive") with a fresh current hub view.
• If the engine is absent, call list_engines(show: "dead") immediately.
• If it is alive, record heartbeat age before further mutation.
• Collect reachable logs, descriptions, costs, traces, and frames.
• Decide who owns the engine/component before terminating or dropping it.

collect_failure_evidence gathers most of that middle step in one bounded, non-mutating call: pass the original error as primary_error, the engine, and the explicit actors, components, kinds, and window that matter. It records the fleet row, kind schemas, component descriptions, log tails, cost tables, and an optional frame, marking each observation ok, error, timeout, or budget_exhausted rather than failing the bundle. Reach for it before terminate, restart, replace, or retry destroys what is still reachable; it cannot reconstruct evidence already evicted from a ring. The per-tool detail is in Inspect and debug.

Symptom-first matrix

Harness or hub interruption

The tunnel is the stable front. Follow The MCP harness to start it and reconnect missing tools. Prefer a tunnel-admin hub restart when rebuilding the hub; an aether-mcp restart invalidates the MCP session. Restart only with explicit authority over the entire fleet, one coordinator, and no blind retry; see Harness lifecycle.

The MCP RPC client re-dials a restarted hub on a dead connection with bounded retry. A tool call crossing the restart can still fail and should be retried only when it is read-only or known idempotent. Reconnection restores transport, not the old fleet.

That retry can repeat the original envelope after an uncertain transport failure; a lost reply is not proof the first mutation never landed. Reconcile observable state before retrying spawn, lifecycle, or application mail.

After a hub restart:

• old engine ids are not continuity evidence, even if a fresh hub later reuses the same UUID text;
• old loaded component names/ids have no live engine behind them;
• the on-disk binary/component store is intended to remain;
• application state must be rebuilt from an application-owned persistence contract, not inferred from registry persistence.

Hub-only restart also preserves aether-mcp caches keyed by reusable engine ids. If a clean kind/component view is essential, deliberately restart and reconnect aether-mcp; otherwise treat cached descriptions as hints and prefer live probes.

Spawn failure

Separate pre-allocation from post-allocation failures.

If selector resolution fails, no engine id or port was allocated. Inspect list_binaries; upload the chassis if necessary. Do not search the live fleet for a child that was never created.

If an error includes an allocated engine_id, correlate it with the spawn_failed recently-dead row. The proxy kills a child it could not bring up, so the record is evidence, not a still-live engine handle.

Boot components load before the substrate binds its RPC port, so a boot component that fails to load is a startup failure, not a half-booted engine: the substrate exits nonzero naming the component and the host's error, and the spawn fails with a spawn_failed entry whose detail carries that stderr. The child is already gone, so there is nothing to terminate.

Check common boot causes in this order:

1. component was uploaded before selector use;
2. selected module has the requested export, or a sole selectable export when none was named;
3. config JSON matches the selected actor's Config schema;
4. derived replica/name lineages do not conflict;
5. the spawn_failed detail's substrate stderr names the failing boot component and its wasm parse, compile, init, or registration error.

Live engine slow or gone

With hub heartbeats enabled, a rising age means pings are not being confirmed promptly. It does not identify the stuck actor. If queries still land, collect actor logs and cost rows from likely recipients. Avoid adding a traced workload merely to diagnose a saturated engine unless the probe is harmless.

When the engine is absent, the death reason determines the next branch:

• terminated: verify that a known owner requested it. Unexpected termination is an ownership/co-ordination failure.
• crashed: preserve the detail and substrate/host stderr. Spawn a replacement only after capturing the failure evidence.
• evicted: the proxy crossed its heartbeat miss limit and dropped/killed the child. Investigate blocking, CPU starvation, or transport failure; the id is already dead.
• spawn_failed: return to selector/startup evidence rather than application mail debugging.

The death sidecar is bounded. Capture it before repeated failures push it out.

Kind, mailbox, or component failure

For an unknown kind, call describe_kinds with the explicit current engine id and the exact name. The encoder already refreshes once on a cache miss or stale schema encode failure. A repeated miss usually means typo, wrong engine, or a component that never loaded—not a cache that needs endless retries.

For an unresolved component recipient, use the exact lineage name returned by load, not the artifact name, actor namespace, selector, or tagged id rendered as a name. describe_component by lineage enables a live lookup on a cache miss; pair a cache hit with a safe live probe when liveness is the question.

For partial replica spawns, already-spawned instances stay live. The error reports the failed index and how many succeeded, so their addresses follow the counter-keyed sequence (NS:0, NS:1, …) up to that point. It does not return the successful prefix's addresses, and registry list_components lists stored artifacts rather than those live instances. The current MCP surface therefore cannot safely target that prefix for drop unless the addresses were obtained elsewhere.

If the engine belongs to the task, preserve evidence and terminate it. If the engine is shared, stop and report the occupied name prefix to its owner. Do not retry the same base or invent mailbox ids.

Replacement failure

Replacement uses a stable mailbox binding on success, but recovery must trust observation rather than intent. The splice is structural, so there is no drain argument to lengthen or retry. Validation and instantiation errors preserve the old guest untouched, still wired; a later state-save, carried-context, rehydrate, or wire failure reinstalls the old guest, still wired, after its on_dehydrate hook ran. The old guest gets back the state its on_dehydrate saved, through its on_rehydrate, with no second wire; only teardown outside that saved state and outside what wire built stays gone. Nothing the failed candidate sent leaves.

One reinstatement ends differently (ADR-0249 §4). An old guest whose on_rehydrate returns an error for the state it saved has refused its own state, so that instance closes: each reply it held is answered unanswered, the mail queued for it is dropped, and its name is spent. Read its log for the error, and load the component again under a new name or key. A guest trap in on_dehydrate reinstates nothing: it aborts the engine, whose exit reason names the component and the hook.

The phase table and stale-introspection limits are in Replacement failure states.

After an error:

• call describe_component by lineage, while treating a cache hit as a capability snapshot rather than conclusive liveness;
• issue a side-effect-free health/query mail if the component provides one;
• inspect its actor logs and, if useful, cost rows;
• do not drop the component until evidence is preserved;
• prefer a known-good exact content hash for a roll-forward attempt.

If the component is no longer serviceable and the engine is shared, republish its module with publish while it is still live (every live instance of the module's namespaces moves with it), or drop that exact instance and load a differently named one after checking downstream address ownership. A drop retires the name, so a reload under it is refused. If the engine is task-owned, replacing the whole engine is often the cleaner isolation boundary.

Settlement timeout

A timeout is an observer deadline, not cancellation. The original engine chain may still mutate state and eventually finish.

Plain send_mail preserves replies that arrived before its timeout. Save them, especially recognized errors. Its later replies are no longer attached to a pending MCP call. Inspect state and actor logs before considering a resend.

send_mail_traced timeout currently returns no root, replies, tree, or node count. It therefore cannot be used to walk that timed-out chain later. If the operation is safe to reproduce, first correct likely settlement obligations, then reproduce with tracing. For a genuinely hung settlement, follow Debugging a hung settlement.

Never “fix” a timeout by switching to fire-and-forget unless the intended contract is truly unobserved dispatch. That hides the symptom; it does not close the causal chain.

Missing logs or visual evidence

Actor rings contain only in-handler tracing::* events and are bounded. If the expected line was emitted during boot, in a proxy, scheduler, panic hook, or other host context, read process stderr. If truncated_before is present, state the evidence gap explicitly.

For capture problems, confirm the selected binary manifest has the needed chassis/caps, then query describe_handlers. Headless engines can run game logic without a desktop frame. A backgrounded/minimized window may also require the window-specific focus flow described in Window.

Use a new capture_frame.save_path beneath a private task-owned evidence directory when full-resolution bytes matter. Absolute syntax alone is not a safety boundary. A failed host write is reported in the saved block without invalidating the successful engine capture, so inspect both results. See Host evidence files.

Final cleanup and handoff

• Preserve all returned spill-file and capture-file paths needed by the incident record.
• Drop task-owned components in a shared engine, require drop_result, and record the retired names.
• Terminate task-owned engines and verify the live fleet no longer lists them.
• Leave adopted/shared engines alone unless the owner authorizes action.
• Report stored artifact hashes separately from live engine/component ids.
• State evidence gaps: overwritten rings, sparse traced timeout, missing host stderr, or ambiguous fleet ownership.

Source routes

• Recovery-visible tool contracts: crates/aether-mcp/src/tools/mod.rs
• Fleet outcomes: crates/aether-mcp/src/tools/engine.rs and crates/aether-fleet/src/server/runtime.rs
• RPC reconnect and timeout behavior: crates/aether-mcp/src/rpc.rs
• Mail timeout projections: crates/aether-mcp/src/tools/mail.rs
• Live kind/component lookup: crates/aether-mcp/src/tools/state.rs and describe.rs
• Component lifecycle: crates/aether-component/src/component/ and crates/aether-component/src/trampoline/runtime/republish.rs

Return to the Operating overview for the normal loop.

Subsystem map

This page routes a task to the system that owns it. The map reflects current source families, not only the original engine core.

Core runtime

Start with Core runtime systems before editing a scheduler or settlement invariant.

Hosted code and discovery

For the hosted-code overview and replacement boundary, start with Hosted code and live replacement.

The hub's stored artifact and an engine's loaded instance are different things. The operating chapter covers that lifecycle.

Platform and network I/O

These all cross trust or blocking boundaries. Read Platform and network I/O for the common rules.

Media, interaction, and product tools

For the media and product-tools overview, start with Media, interaction, and product tools.

Native capabilities own devices; guest actors (aether-kit's camera and mesh viewer) compose them into product behavior.

Fleet and operation

The hub/engine control plane spans process topology, engine fleet and stores, and the MCP harness. It is separated from engine-local systems because spawn/upload/selector semantics live outside a child registry.

Find the current contract

Use the capability index for mailbox/source routing and engine-scoped describe_kinds, describe_handlers, and describe_component queries. The guide explains meaning; code and live schemas answer exact signatures.

Core runtime systems

These systems define how work moves and completes inside one engine. Read them in contract order; the scheduler internals are rarely the first place to edit.

The stable public contract is mail plus actor seriality. Scheduler queues, worker heuristics, and tuning defaults are implementation details unless an ADR promotes them. When debugging, prove the failure layer before changing a knob:

wrong name/schema → registry or kind issue
handler never runs → delivery/wiring issue
handler overlaps itself → actor invariant violation
descendants remain pending → settlement/hold issue
correct but slow → cost/scheduler/load issue

Changes here have wide fan-out. Read invariants, the owning ADRs, and tests across both native and wasm actors before editing.

Mail, kinds & scheduling

Governing ADRs: ADR-0002 (mail-first actor model), ADR-0005 (mail typing), ADR-0019 (unified encoding), ADR-0087 (burst dispatch + the ordering spine). The mail/kind model is stable; the scheduler internals (how work is batched and balanced across threads) are settling — this page documents the stable contract and defers the guts to ADR-0087.

This is the spine the rest of the engine hangs on. Actors don't call each other — they send mail. A piece of mail is a typed payload (a kind) addressed to a mailbox, and the scheduler runs the handlers. Understand this page and every other subsystem reads as "an actor that receives some kinds."

The cast, in one breath. Everything in the engine is an actor — a unit that owns some state and talks only by mail. Two kinds: a capability is a native actor compiled into the substrate (render, audio, file I/O, and the rest), and a component is an actor loaded at runtime across the engine's FFI boundary (the WasmActor ABI) — your logic, and the thing that gets hot-swapped. The split is built-in-native vs loaded-guest, not a specific language: the FFI boundary is target-agnostic by design, and WASM is simply the only guest target wired up today. So a component is WASM right now, but a C / C++ / other guest that speaks the ABI is the same category. All of them are one actor model and address each other identically. When this page says "component" it means a loaded FFI actor; "actor" means either kind. Deep dive: Components & lifecycle.

Why it exists

Aether could have let subsystems share memory and coordinate through a scheduler. It deliberately doesn't (ADR-0002). One uniform message boundary buys four things the project treats as non-negotiable:

• Hot-swap. A component can be unloaded and reloaded mid-run without the host contortions shared state would require — because nothing else holds a pointer into it; it only receives mail.
• Sandboxing. Agent-authored code can't be trusted with shared memory, so it runs as a loaded component whose only channel is mail — its reach is exactly the mailboxes it can address, nothing more. The current guest target, WASM, backs that with a real memory sandbox (its own linear memory, traps contained), which is a large part of why WASM is the target wired up first.
• Capability equals reachability — and so does observability. There is no privileged side-channel, not even for an operator agent: what an actor can do is exactly what it can mail, so gating a build is just choosing which mailboxes are registered. The payoff on the flip side is the point, not a side effect — because every function in the engine is reachable as mail, you can interpose anywhere in the stack: address any mailbox, watch any exchange, inject a message mid-flow to reproduce or debug a state. Universal reachability is what makes the running engine inspectable by the agent driving it, and it is a primary reason the model is shaped this way.
• Location independence. Transport is a choice the recipient doesn't have to reason about: mail from a sibling actor in the same process and mail from an agent over the MCP wire run the same handler path, so the "in-process SDK vs out-of-process server" question dissolves (ADR-0002/ADR-0006). A handler isn't fully blind to provenance — it can see a reply target and sender lineage (ADR-0083) — but the guarantee is that correctness and capability never depend on where mail came from. (Pinning down the exact origin, e.g. for a security policy, isn't first-class today; it's a plausible future.)

A note on granularity. Actors span a wide range of sizes. A coarse actor can own a whole subsystem — the entire physics world, state as plain data and a tight inner loop. A fine one can be a single instance: instanced actors are a first-class category (cardinality — Singleton vs Instanced — is its own axis, ADR-0079), and the burst dispatcher (ADR-0087) is built to rip through large sets of mail, so fan-out across many small actors is cheap, not the performance trap an earlier design assumed. ADR-0002's "subsystem-sized, never per-entity" rule predates both and is superseded on this point.

When do you split into instances versus manage multiplicity inside one actor? Reach for an instanced actor when each instance needs its own lifecycle and isolation — one actor per TCP session is the canonical case (a NetCapability listener spawns a SessionActor per connection, each able to drop independently); per-session game logic and per-monster AI are the same shape. Keep it a single actor when the multiplicity is just internal state — the camera component drives many cameras from one actor, no per-camera mailbox needed.

Fine granularity is cheap because actors don't each own a thread — they're multiplexed onto a shared work-stealing scheduler (ADR-0087), and the run-token that lets only one worker run a given actor at a time is what gives you the single-threaded-per-actor property. So thousands of instanced actors cost mail and state, not threads. The rare exception is blocking I/O: an actor that must make a blocking call may spawn a dedicated thread for that (a listener's accept loop, a blocking provider call), but that's specific to blocking I/O, not how actors run in general — see the no-blocking note under Scheduling.

What it does

Mailbox vs kind — the distinction to internalize first. The mailbox is the address (where mail goes); the kind is the payload shape (what the mail is). They're independent — but they share a naming convention, and that's the source of the confusion: a kind name is usually its mailbox's prefix plus a verb (aether.audio + .note_on → aether.audio.note_on). So the kind reads like a more specific mailbox, and the reflex is to use it as the address. The trap, concretely: sending kind aether.audio.note_on to recipient aether.audio.note_on instead of to aether.audio. No mailbox has that name, so it silently warn-drops (see the addressing rules below). The mail routes by mailbox; the kind only describes the bytes. When something you sent seems to vanish, this is the first thing to check.

A kind is a typed, self-describing payload. It's a Rust type deriving Kind + Schema with a #[kind(name = "…")], carrying a stable hashed KindId and a schema that describes its bytes (ADR-0005/ADR-0031). Because a kind carries its own schema, the wire layer can encode it from JSON and a recipient can decode it without a shared header — and an agent can ask a live engine what kinds exist (describe_kinds).

Encoding is schema-driven (ADR-0019). On the way in, params are encoded to wire bytes against the kind's schema; the recipient decodes those bytes back into the kind per-kind. The bytes stay opaque until the addressed handler decodes them — nothing in the middle needs to understand the payload.

A kind says Vec3 where it means a vector. The aether-math value types are schema types, so a kind field is spelled Vec2, Vec3, Vec4, Quat, Mat4, Aabb or Rect2 (and Rgb, Rgba, Hsl for a colour), never a bare [f32; 3]. A pod kind may hold them too: each is #[repr(C)] and all f32. On the wire a math field is its f32 components in declaration order, four little-endian bytes each, with no tag or length, so a Vec3 is 12 bytes and a Mat4 is 64, column by column. In params JSON it is an object of the component names:

The same types are fields of a stored type (ADR-0059): each derives aether_data::StorageLeaf, so it is stored as one record, and a #[storage(validate)] newtype over one (struct Radiance(Rgb)) is how a kind carries an invariant such as "finite and not negative". A value type of your own opts in the same way, with #[derive(Schema, StorageLeaf)].

Mail is fire-and-forget by default. A handler promises nothing about a reply. If a reply matters, that's a separate, explicit contract between the two kinds — never an implicit "every kind has a response." Don't write a caller that blocks waiting for a reply a handler never agreed to send.

When several requests are in flight, carry a typed request context. A one-shot request that needs to match a later reply should call send_with_context(&request, context) and recover the bookkeeping in the reply handler with ctx.take_context::<Context>(). The context moves into the table, so a guest's context may hold a Held<R> deferred reply (ADR-0243): storing parks it and the take claims it back. Contexts are Kinds, so the table stores schema-typed bytes, checks the KindId on take, and rides guest dehydrate/rehydrate automatically. A context holding a reply handle or a sender route has actor reach (ADR-0242): the table stores it, but it is never mail, so no actor can send it and no handler receives it. A replacement that no longer declares a carried context's kind (a changed schema is a new KindId) is refused, and the old guest keeps the context. A take of the wrong type returns None and leaves the context stored, so a reply handler that serves several context kinds tries each type in turn. Keep contexts small: stash routing bookkeeping such as the caller's reply handle, origin, or parse mode; keep bulky domain state in actor fields and put only an id in the context. The table never drops a context: it grows past its preallocated room and logs a warning at each new high-water mark, so a peer that never replies shows up in the actor's log. A reply handle kept in a context stays answerable across a republish: the mailbox's pending replies move to the replacement with it. Only an unchecked (#[handler::unchecked(reason = "…")]) handler can read and keep its raw reply handle; a request, tell, event, or response handler's handle is freed when it returns, unless the handler returns Pending<R> and keeps the typed Held<R> that answers it. A component whose held handles keep growing logs a warning naming it.

The lower-level send_tracked(&request) / ctx.in_reply_to() pair is still available when the request id itself is the domain key. in_reply_to() returns None for ordinary inbound requests, uncorrelated mail, and inline-cluster local dispatches that never crossed the host envelope boundary. Echoed payload fields such as the echoed addr on aether.fs.read_result remain useful domain context, but exact duplicate-safe matching belongs to the request context or envelope request id. Detached data phases still carry their own domain-level correlation in their payloads.

The ordering spine (ADR-0087) — the single contract to hold in your head when writing handlers. Get it wrong and you write code that passes in dev and breaks under load:

Same sender, same recipient → arrives in send order (per-recipient FIFO). Different recipients → no ordering guarantee — each send is an independent async call, like hitting a server.

In practice: if you send(A) then send(B) to the same actor, B is handled after A — rely on it. If you send A to actor X and B to actor Y, you know nothing about their relative order; Y might finish before X starts. So never encode a cross-actor sequence by send order. When B must happen after A across actors, make it causal: have A's handler trigger B, or have the actor that needs the order receive both and sequence them itself. Strict cross-recipient ordering is deliberately not offered — it would let one slow recipient stall everything queued behind it in a fan-out.

Scheduling, at the level you can depend on. Each actor is single-threaded from its own perspective — its handlers never run concurrently with each other, so actor state is plain fields (no locks, no RefCell). The scheduler runs handlers cooperatively across a thread pool.

A handler must never block its thread. No sleeping, no blocking I/O, no waiting on a blocking lock or channel, no busy-spin. Because scheduling is cooperative, a blocked handler doesn't just stall itself — it pins a worker doing nothing and can deadlock a reply chain (the actor you're waiting on may have its next mail queued behind you). A long compute handler is tolerated (it ties up only its own worker), but anything that waits on the outside world is not: await a reply through the framework so the scheduler can run other work meanwhile, or hand heavy/async work off the actor thread entirely through the sanctioned offload primitives. The full treatment — the await/hold primitives and how to reason about concurrency here — is in Concurrency and blocking. The rule to carry now: don't block in a handler.

How mail is batched and balanced across workers (the per-producer rings, the work-stealing pool, the burst-as-unit-of-dispatch) is drawn out on The scheduler, with ADR-0087 as the authority while the internals settle — build on the contracts above, not the internals.

How to use it

From an agent (over MCP). send_mail takes {engine_id, address, kind_name, params} — address is the mailbox, kind_name is the payload shape, params is JSON encoded against the kind's schema. An Option field may be left out of params and encodes as None; every other field is required. For a batch that must settle as one traced unit, use send_mail_traced. The active MCP tool schema is authoritative for arguments; the harness explains the operating model.

From inside a component. Declare the peer with #[actor(depends(RenderCapability))], then send to it by type on a ctx typed by the actor (WasmCtx<'_, Self>): ctx.send::<RenderCapability>(&kind). The turbofish names only the recipient; the kind is inferred from the payload, and the send compiles only when the actor declares that recipient and the recipient handles the kind. The siblings are send_many (one cast batch), send_tracked (returns the request id), and send_with_context (stores a typed context for the reply handler). A typed proof the actor holds, an ActorRef<R> or a ProtocolRef<P>, sends with ctx.send_to(reference, &kind), checked against the kind; sending through an erased reference is being removed (#6895). Kind::ID and the typed resolver are compile-time constants, so there's no host round-trip to resolve an address. You receive mail with a #[handler::<class>] fn on_x(&mut self, ctx, mail: K) — the kind is inferred from the third parameter (see Components & lifecycle and the Writing a component recipe).

Addressing rules that bite if ignored:

• Chassis mailboxes live under aether.<name> (aether.render, aether.fs, aether.audio, aether.lifecycle, aether.window, aether.component).
• A loaded component registers at its published name — NS, NS:key, or parent/NS:key (ADR-0241 §5) — use the full address LoadResult.path hands back.
• Bare names ("camera", "player") are not registered and warn-drop silently. If mail seems to vanish, check the address first.
• Never hash a name into a MailboxId yourself. The name hashes are private to aether-data, a written path resolves through the host registry, which folds it node by node, and MailboxId::from_name, the one hash spelling left, is disallowed by clippy.toml, because a hand-computed address freezes the target's registration shape into the caller. Boot and driver code that has no ctx to resolve through still doesn't need them: aether_actor::root_mailbox::<C>() returns a root-pinned capability's mailbox, and its C: Root + Resolver = One bound is a compile error for an actor whose address is only knowable under a caller's lineage.

Naming a kind

A kind name is a wire contract, not a label. Kind::ID is fnv1a_64_prefixed(KIND_DOMAIN, canonical(name, schema)), so renaming a kind mints a different id and every peer that already routes on the old one stops matching. You get one shot at the name; spend it under this grammar.

aether.<family>[.<sub>].<verb>_<noun>      command
aether.<family>[.<sub>].<noun>_<past>      event
aether.<family>[.<sub>].<verb>_<noun>_result   reply
aether.<family>.config                     capability boot config

• The family segment is mandatory. A name is at least <root>.<family>.<leaf>. aether.render.destroy_texture is a kind; aether.draw_triangle is a family with no room to grow a sibling.
• Commands lead with the verb. create_texture, create_font, set_master_gain. A bare verb leaf is fine where the family already supplies the noun — aether.fs.read, aether.fs.write — but the verb still leads.
• Events read <noun>_<past participle>: aether.tcp.session_closed, aether.component.module_published. Carrying the noun is what keeps an event clear of the command that causes it. aether.window.close against aether.window.closed is the shape to avoid: one letter apart, and a typo in either direction routes silently to the wrong kind.
• _result is the only reply suffix. Not _reply, _ack, _report, _complete, or a bare .response segment. A reply is <request>_result and nothing else, so a caller can name the reply from the request without a lookup.
• .config is the only config suffix. A capability's boot config (ADR-0090) is aether.<family>.config — its own segment, never a <something>_config leaf.
• Segments are lowercase snake_case. A dash appears only where it names a dash-sibling namespace (aether.kit.camera-controller.config), never as a word separator inside a segment.

The two families to copy are aether.fs — six bare verbs under one family, each paired with <verb>_result — and aether.store, two dozen <verb>_<noun> / <verb>_<noun>_result pairs with no third spelling anywhere in it.

The grammar is enforced as a test, not as a lint or a macro: crates/aether-kinds/tests/kind_name_grammar.rs scans every #[kind(name = "…")] declaration in crates/ and checks the four mechanical rules above (family segment, segment casing, reply suffix, config suffix). It runs on every pull request that changes a crate, whether or not that crate is related to aether-kinds in the dependency graph. Names that predate the grammar are listed in crates/aether-kinds/tests/kind_name_allow_list.txt; the test fails on a violator that is not on that list and on a list entry that is no longer a violator, so the file only ever shrinks. Fixing an entry means renaming a kind, which means changing its id — a deliberate per-family decision, not a drive-by.

How to extend or reuse it

The mail spine is the thing you extend through, so most extension is "teach the system a new kind" or "stand up a new mailbox":

• A new message shape → add a kind. See the Adding a substrate kind recipe: define the type in the right kind crate, derive Kind/Schema, add a handler — the descriptor that surfaces it on the MCP wire registers itself. Name it under Naming a kind before you write the struct.
• A new mailbox → stand up an actor to own it. A native one is a chassis capability (the Adding a chassis capability recipe); a wasm one is a component (the Writing a component recipe). Either way it's the same actor model and the same addressing.
• Reuse the streams rather than polling. Tick is subscribed through lifecycle; key, mouse, and window-size events are subscribed through WindowCapability with WindowSelector::One(id) or WindowSelector::All. Subscribe from a component's wire hook and receive the events as mail. See Input and File I/O.

Because everything is mail, these few moves compose: a new capability that handles a new kind and publishes another is the whole vocabulary of building on aether.

Concurrency & blocking

Governing ADRs: ADR-0087 (the burst dispatch model + scheduler), ADR-0093 (the hold-until-resolve offload primitive), ADR-0080 (settlement). The contracts on this page — single-threaded actors, per-recipient FIFO, no blocking — are stable. The scheduler internals that enforce them are drawn out on The scheduler and are live and still being tuned. Build on the contracts, not the internals.

The invariants page states three contracts as rules: an actor is single-threaded from its own perspective, mail is per-recipient FIFO, and a handler must never block. This page is about writing code inside them — the scheduling model in enough detail to reason from, why the third contract is non-negotiable, and what you do instead of blocking when a handler needs to wait. The machinery that makes the first two hold is drawn out on The scheduler.

The model: cooperative scheduling

Actors don't each own a thread. There are far more actors than worker threads, and a small work-stealing pool multiplexes them on demand (ADR-0087). The unit the pool hands around is a burst — one handler execution's buffered sends, grouped by recipient and published for idle workers to race — and a per-actor run-token admits one worker to a given actor at a time. The token is what makes an actor single-threaded (so actor state is plain fields with no locks) and what makes per-recipient FIFO fall out for free while distinct recipients run concurrently — exactly the ordering spine the invariants and mail pages rely on. The full machinery — the outbound mail ring, burst formation, the cursor race, the run-token state machine, wakeup and fairness — is drawn out on The scheduler.

What this page needs from that model is one property: scheduling is cooperative and non-preemptive. Once a worker starts a handler, that handler runs to completion — the scheduler cannot interrupt it. A worker dispatches a bounded batch and then releases the run-token so other actors get their turn, but within a single handler invocation there is no yield point. A long compute handler is fine: it ties up only its own worker and blocks nobody else's runnable work. The problem is a handler that waits.

Why a handler must never block

Because scheduling is cooperative and the pool is shared, a handler that blocks — sleeps, does blocking I/O, waits on a blocking lock or channel, busy-spins — doesn't just stall itself. It pins a worker doing nothing, shrinking the pool. Worse, it can deadlock a reply chain: if you block waiting for actor B to reply, and B's mail is sitting in a queue behind the very worker you're holding, neither of you ever makes progress.

This is history, not hypothetical. The engine once had a synchronous wait_reply primitive (ADR-0042). Once dispatch became pool-only — the Dedicated per-actor-thread opt-in was removed (#1187) — an in-handler wait_reply could park a shared worker and deadlock if the awaited reply needed that worker. It was a latent footgun with no users, so it was retired (#1190). There is deliberately no blocking-await primitive in the engine.

So never wait inside a handler. The sanctioned ways to wait are all the same shape: return now, continue later.

How to wait, without blocking

1. Request/reply across actors → return, and match the reply in a later turn. The idiomatic shape is a small state machine spread across handler invocations: send the request, return from the handler (freeing the worker), and handle the reply when it arrives as a separate mail in a later handler call. Correlation survives across turns through a typed request context: call send_with_context(&request, &context) and later recover it with ctx.take_context::<Context>(), so duplicate in-flight requests don't get confused (the surviving half of ADR-0042). The context should be small bookkeeping; bulky state belongs in actor fields. Every request/reply in the engine works this way: aether.fs.read → …read_result, reply-to-sender, and the rest. Use the lower-level send_tracked / ctx.in_reply_to() only when the raw request id is itself the domain key.

2. Blocking I/O or slow off-thread work → dispatch_blocking + #[handler(task)]. When a (native) capability must make a genuinely blocking call — a multi-second provider request, a subprocess — it hands the work off the scheduler thread (ADR-0093):

#![allow(unused)]
fn main() {
#[handler::request]
fn on_generate(
    state: &mut Self::State,
    ctx: &mut NativeCtx<'_>,
    req: Generate,
) -> Pending<GenerateResult> {
    let provider = state.provider.clone();
    ctx.dispatch_blocking(move || provider.call(req))     // runs off the scheduler worker
}

#[handler(task)]                                           // a completion, not inbound mail
fn on_generate_done(
    _state: &mut Self::State,
    ctx: &mut NativeCtx<'_>,
    done: TaskDone<GenerateResult>,
) {
    done.resolve(ctx);                                     // re-reply, then drop the hold
}
}

dispatch_blocking spawns the closure on an off-scheduler thread and returns a Pending<R> immediately. The request handler must return that receipt: it declares the deferred reply kind and prevents the armed dispatch from being silently discarded. The closure's output comes back later as TaskDone<Output> in a #[handler(task)] handler. Task completions route by their Rust output/context types, not by a wire KindId; the output only has to be Send + 'static, while R in Pending<R> is the reply kind. In the same-output/reply shape above, consuming done.resolve(ctx) sends the reply and then drops the settlement hold. A completion can instead map a different output to R and resolve that value. This is the sanctioned home for "reply in a later turn"; it replaced the hand-rolled InFlightDispatch the content-gen capabilities used to carry. (Native capabilities today; a wasm/FFI form is a deferred superset — guests use shapes 1 and 3.)

A panic inside the closure is fatal (ADR-0063): the worker escalates it through the chassis FatalAborter the same way the scheduler escalates a handler panic, and no completion lands. Return an expected failure as a value instead — a Result-shaped output — and map it to an error reply in the completion.

Staged work owes no reply → stage_blocking + StagedTask. Work that is not itself the answer to the current caller stages instead (ADR-0243 §9). ctx.stage_blocking::<O>(), or ctx.stage_blocking_with::<O, C>(context) with a context kind, fixes the task's chain in the turn that stages it: it mints the task's request id from the counter outbound requests use, takes the settlement hold on this turn's chain, and stores the context under the id. StagedTask::start(ctx, work) only spawns the worker, from whichever turn calls it. The #[handler(task)] completion runs correlated to the task's request on the staging chain: ctx.in_reply_to() is the task's request(), the context comes back with ctx.take_context::<C>(), its sends inherit the chain, and done.into_output() discharges it, because nothing is owed. A completion that leaves a context holding a live Held untaken fails fast, as a reply handler does. Dropping an unstarted task releases its chain and removes its context.

A child birth and a registry batch are staged tasks too. ctx.spawn_child::<C>(..) ends with .stage(), or .stage_with(context) with a context kind, and ctx.stage_registry_batch(batch, context) stages an owner batch the same way: each mints a request id, holds the staging turn's chain, and stores its context, and its #[handler(task)] completion (TaskDone<SpawnOutcome<C>>, TaskDone<RegistryBatchResult>) takes the context from the ctx and owes nothing. A birth refused before it is staged hands its context back beside the SpawnError. The context is a kind that names the work, such as an index or a path; live values the completion needs, a request's Held among them, wait in actor state under the key it names. Requests that need the same work join as waiters under one key, one list per reply kind, and the one completion answers them all.

A bounded queue holds each reply and stages each request's work. A native capability that bounds its concurrent blocking calls uses TaskQueue<R> (aether-http's per-sender egress, the workspace run queue, and aether.fs reads are the same shape). submit runs in the request's own turn: it holds the reply with ctx.hold::<R>(), keeps the Held<R>, and stages the work, so the task holds that request's chain whether it starts now or waits for a slot. The completion is one line:

#![allow(unused)]
fn main() {
#[handler(task)]
fn on_run_done(state: &mut Self::State, ctx: &mut NativeCtx<'_>, done: TaskDone<RunResult>) {
    state.tasks.complete(ctx, done);   // answer the Held, then start the next waiting task
}
}

complete finds the finished task's Held by the request its completion is correlated to, answers it with the output, and starts the next waiting task in the freed slot. The waiting task's chain is still its own request's, so a request's chain settles when that request is answered, never when another request's work finishes.

A request the caller should not wait for is owed with ctx.defer (below) instead of hold. aether.fs.load defers its Loaded reply and keeps the Held on its own bounded queue; a started load's worker attaches to that debt with dispatch_blocking_held_with, and its completion resolves it. The caller's chain settles as soon as the handler returns, and the late reply reaches the caller's response handler by its correlation, with the context the caller bound, joining no chain.

3. Heavy async compute → off-thread, by reference. Multi-step compute that produces handles belongs off the actor thread entirely; stage it through the offload primitives below and pass results by handle rather than copying them through mail.

4. A reply owed until a later turn, with no worker → ctx.hold. When a (native) handler answers one exact reply kind later from a turn no worker drives — after a peer's reply, a settlement or monitor notice, a long-poll wake, or a frame loop — it arms the obligation with ctx.hold::<R>() (ADR-0243):

#![allow(unused)]
fn main() {
#[handler::request]
fn on_watch_head(&mut self, ctx: &mut NativeCtx<'_>, _m: WatchHead) -> Pending<WatchHeadResult> {
    let (pending, held) = ctx.hold::<WatchHeadResult>();
    self.watchers.push(held);                              // the debt waits in state
    pending                                                // the receipt sets the row
}

// later, from any handler on this actor:
held.answer(ctx, &WatchHeadResult { head });               // reply, then drop the hold
}

hold parks the caller's settlement hold and reply target in the actor's in-flight ledger, the same table dispatch_blocking fills, and returns the Pending<R> receipt with a move-only Held<R> ticket. answer replies to the captured caller with its correlation, whichever turn runs it, and only an R compiles. Work the actor stages for a held request (an offload, a child birth, a registry batch) owes no reply: the Held waits in state under the key the task's context names, and the completion answers it. The component host's continue_from and stage_registry_batch_from, which carry a Held onto a successor that answers the same caller, remain until #7008. A second hold in one dispatch panics. Dropping a Held unanswered releases the hold and panics; an actor that closes with tickets still live or parked while the engine keeps running answers each with its reply kind's unanswered() (the HeldReply trait) before releasing its hold, and an engine teardown releases them silently.

A reply owed later that the caller must not wait for → ctx.defer. ctx.defer::<R>() is hold for a request whose caller's chain should settle now, such as a load sent from a Tick handler that must not hold the frame. It returns the same Pending<R> and Held<R> and parks the same ledger entry, but with no settlement hold: the caller's chain settles when the handler returns. answer later replies to the captured caller with its correlation, so the caller's response handler still gets the context it bound, and the reply joins no chain. A worker or bounded queue answers it through dispatch_blocking_held_with. The one-debt-per-dispatch rule, the drop panic, and the close-time unanswered() apply as for hold.

The offload shapes, and the hold

Settlement — how send_mail_traced knows a chain of mail is fully done rather than guessing with a timeout — requires every unit of in-flight work to stay visible to the trace umbrella. A raw std::thread::spawn pushes rootless mail the umbrella can't see, silently opting the work out. So offloading goes through one of the sanctioned primitives below, which differ only in how long they hold the causal chain open:

A panic in any of them is fatal (ADR-0063): the worker escalates it through the chassis aborter with the panic payload in the reason, as the scheduler does for a handler panic.

The hold is what stops a deferred reply from settling early: if a handler kicks off work that replies later, the chain must stay open until that last send, or a waiter is told "done" before the reply arrives (ADR-0080 §12). dispatch_blocking acquires the hold eagerly — before the handler returns — and resolve releases it after the reply, so "reply before release" is structural rather than something you remember to order. (A hand-rolled drain that consumes an owned dispatch carries the same obligation by hand: record completion or settlement never fires. See the hold the chain open obligation on the invariants page.)

A chain that never settles traces back to a missed hold here — picking the wrong shape from this table, or a raw std::thread::spawn that opts the work out. The Debugging a hung settlement recipe walks from the "timeout" symptom back to the offending primitive.

The rare dedicated thread

Some work genuinely blocks at the edges of the engine — a TCP listener's accept loop, the audio output callback, an RPC server's socket. Those spawn a real OS thread, deliberately: it's blocking I/O that should live off the scheduler, isolated so it can't pin a pool worker. That's the exception — a handful of infrastructure capabilities — not how actors run, and not something to reach for from ordinary actor logic (use one of the shapes above). It's a cap-local spawn, scoped tightly to the blocking call (ADR-0050).

A cap spawns that thread from the handle ctx.self_wake::<K>() returns (on the init ctx as well as a handler's): wake.spawn_sidecar(name, body). A panic in body fails the chassis fast, like a handler panic, even after the actor has closed. The thread wakes its actor through the same SelfWake<K>, never through a stored mailbox id plus a mailer. The wake reaches its handler with the actor itself as ctx.sender(). The handle names no position and sends nothing but that one wake, and a wake after the actor has dropped does nothing (ADR-0230).

A thread that must decide about a peer before it wakes its actor also holds the ActorProbe that ctx.actor_probe() returns on the init ctx. It answers whether the actor a proven reference names is Live now and whether it accepts a kind, and nothing else.

Where to read more

• The contracts this page implements — Invariants & guarantees.
• The dispatch machinery behind them, drawn out — The scheduler.
• The mail spine and the per-recipient ordering guarantee — Mail, kinds & scheduling.
• Settlement and the hold contract in depth — Tracing & settlement.

The scheduler

Governing ADR: ADR-0087 (the burst as the unit of dispatch + the work-stealing pool). The contracts the scheduler enforces — single-threaded actors, per-recipient FIFO, cooperative dispatch — are stable; they live on Concurrency & blocking and the invariants page. The mechanism on this page is live and still being tuned — knob defaults and fairness levers shift under perf work — so read it as a reminder-grade map at named-module fidelity, with ADR-0087 and the source as the authority when a detail is load-bearing.

This page draws the machinery out: how a handler's sends become a burst, how a burst reaches other workers, how the run-token keeps an actor single-threaded, which levers govern wakeup and fairness, where causal roots enter, and how to map a trace tree's timestamps back to all of it. Concurrency & blocking covers what the contracts mean for code you write; this page is for the returning reader asking how dispatch works underneath them.

The cast of modules, all under crates/aether-substrate/src/:

The burst lifecycle

One handler execution's buffered output is the base unit of work — the burst (ADR-0087's axiom). Everything below is the life of one burst, from the first send inside a handler to the ring bytes being reclaimed.

1. Sends buffer into the producer's ring. While a handler runs, each send writes its payload bytes straight into that actor's own outbound MailRing (mail/ring.rs) — a fixed-size (64 KiB, ACTOR_RING_BYTES in actor/native/binding/outbound.rs), single-producer, multi-consumer, reclaiming byte ring. The first send of a handler invocation opens a burst in the ring (open_burst); each subsequent send appends in place (append) — no staging buffer, no per-mail allocation. The ring never blocks its producer: when a burst doesn't fit (RingFull), the payload is copied out to a heap buffer instead (MailRef::Owned), so the ring is a bounded zero-copy fast path whose fallback costs the same memcpy an eagerly-allocated envelope would. (These rings are distinct from the loss-tolerant trace/log rings of ADR-0081 — a mail ring is no-loss, and a region stays live until every reader has released it.)

2. Flush at the handler boundary. When the handler returns, NativeBinding::flush_outbound (actor/native/binding/flush.rs) seals the open burst (MailRing::seal publishes the region's reclaim lock) and mints one MailRef per buffered mail — InRing for ring-resident payloads, Owned for the copy-out fallback. The whole window then routes as a single unit. This boundary is the amortization point: a fan-out of N recipients costs one scheduling synchronization, never N queue pushes and N wakeups.

3. Group by recipient. BurstProducer::flush (actor/native/burst/work.rs) folds the routed mail into the actor's single active BurstWork, grouped by recipient. A new recipient becomes a fresh group, written into the burst's group array and published through the packed Lifecycle word; a recipient seen before pushes onto its existing group's buffer. That append rule is what preserves per-recipient FIFO across flushes: a producer has at most one unclosed group per recipient across all of its live bursts, so two workers can never hold same-recipient mail concurrently.

4. Keep warm — and recruit when it's worth it. Every flush schedules one drainer copy of the burst through WakeSink::schedule. On a pool worker that push lands on the worker's own deque (the keep-local path — same worker, LIFO pop, no cross-thread handoff), so a chain or a cheap fan-out stays on one warm worker. A flush whose fresh groups carry enough measured work additionally broadcast-recruits siblings: recruit_k sizes the recruitment from the per-handler execution-cost EWMAs (K ≈ ceil(total_work / max_group_work), gated by the box-calibrated wake break-even). Both terms reduce the same set — this flush's fresh groups — one by summing them, the other by taking the largest, which is why a fan-out dominated by one fat group recruits nobody: a group is drained by a single worker, so no K beats that group's own serial drain. Then WakeSink::recruit pushes that many clones of the burst to the shared injector and unparks that many workers. When any contributing cost cell is untrustworthy, the decision falls back to the width gate (AETHER_BURST_RECRUIT_MIN, default 9 — so a fan-out 8 wide or narrower stays local), capped by AETHER_BURST_RECRUIT_MAX (default 32).

5. The cursor race. A burst is published and raced, never owned. Each worker that picks up a copy runs BurstWork::run_cycle, which loops Lifecycle::claim — one CAS on the packed lifecycle word (actor/native/burst/lifecycle.rs: [seal | done | len | cursor] in a single AtomicU64) — and each claim hands a whole recipient-group to exactly one worker. There is no placement decision and no load balancer: N recruited workers race the one cursor and split the groups between them, contending on a single atomic. One worker owning a whole group is also what makes per-recipient FIFO free — it dispatches that recipient's mail in send order, draining the group's closeable buffer until empty and then closing it (the close is a FIFO barrier: a producer push that arrives after the close deposits through route_mail and lands strictly behind everything the worker dispatched).

6. Seize, or lose the CAS and deposit. For each mail in a claimed group, dispatch_one resolves the recipient (Registry::route_lookup) and tries to run it in place: SeizeHandle::try_seize attempts the recipient run-token's Idle → Running CAS, and a win runs the handler right there on this worker (Drainable::seize_and_run) with no inbox round-trip. A lost CAS means the recipient is already in flight — Ready (a sender's wake won) or Running (another worker is draining it) — and the mail is re-deposited through Mailer::push → route_mail onto the recipient's inbox instead, where the current holder's drain (or the wake it triggers) picks it up. The inbox's own ordering keeps FIFO intact on that path. Non-Pooled recipients (inline handlers) and ADR-0045 ref-carrying kinds always take the deposit path.

7. Reclamation. Each burst region in the ring starts with its BurstHeader.lock equal to its mail count; every MailRef::InRing holds one count and releases it on drop (RAII — cloning acquires another). The producer reclaims lazily: at the next open_burst it advances the ring's front cursor past any frontmost regions whose lock has reached zero; a wrap writes a skip filler and restarts at offset 0. The lock staying above zero for the entire dispatch is what makes decode-in-place sound — a handler borrowing &[u8] into a producer's ring can never have those bytes overwritten under it, because the producer only reuses regions every consumer has released.

The run-token

Each Pooled actor has one run-token — SlotState in scheduler/slot.rs, a single AtomicU8 over three states — and every path that could run the actor must win a CAS on it first. The token is the entire single-threaded-actor mechanism: the pool never reasons about placement, it just refuses to let two workers hold one token.

            try_wake                      enter_running
            (sender-side CAS)             (worker-side CAS)
   ┌──────┐ ────────────────► ┌───────┐ ────────────────► ┌─────────┐
   │ Idle │                   │ Ready │                   │ Running │
   └──────┘                   └───────┘                   └─────────┘
      │ ▲                         ▲                          │  │
      │ │                         │      mark_ready          │  │
      │ │                         └─(budget hit; re-pushed)──┘  │
      │ │                                                       │
      │ └── mark_idle (drained empty), then the post-empty ─────┘
      │     recheck: try_self_requeue re-runs Idle → Ready
      │
      └──── seize (demux-side CAS): Idle → Running direct ──► (Running)

Four transitions carry the load:

• try_wake (Idle → Ready) — the sender side. After depositing an envelope on the inbox, WakeHandle::wake runs this CAS; only the winner publishes the slot to the scheduler. This is the dedup: a slot already Ready or Running is never enqueued twice, however many senders race.
• enter_running (Ready → Running) — the worker side. The worker that popped the slot claims it for a drain cycle. Only the popper calls this, so one worker drains at a time.
• seize (Idle → Running) — the demux side. A burst worker holding a free recipient's mail in hand claims the token directly and dispatches in place, skipping the inbox round-trip. A loss leaves the state untouched and the mail deposits instead — the two CAS entry points (try_wake vs seize) agree, in one total order, on who owns an Idle slot, so a sender's wake and a demuxer's seize can never both proceed.
• Running → Idle / Running → Ready — the exits. Drained to empty: mark_idle, then the post-empty recheck (try_self_requeue) re-reads the inbox and re-runs the Idle → Ready CAS if mail arrived during the gap — closing the classic send-vs-drain race where a sender observed Running and skipped its wake just as the worker went idle. Budget hit: mark_ready keeps the slot Ready and the worker re-publishes it, so one chatty actor yields the worker without ever passing through Idle.

The racing sites — try_wake, seize, mark_idle, try_self_requeue — all use SeqCst so they share one total order; the comments in scheduler/slot.rs spell out which stranded-envelope case each ordering forbids.

Wakeup and fairness

The acquire loop. A worker looks for work in a fixed order (acquire_slot in scheduler/pool.rs): its own deque first (LIFO — the freshest hop is the warmest), then a steal pass over the shared injector (plus siblings' deque tails only when AETHER_PEER_STEAL=1; the default is owner-only), then the SpinPark coordinator — spin for a bounded window (AETHER_SPIN_WINDOW_USEC, default 50µs), re-running the steal scan, then park on the thread token.

Route-to-spinner. A producer that pushes work calls SpinPark::notify, which skips the futex wake entirely when some worker is already spinning — the spinner's scan picks the work up for free. Only the genuine idle edge (no spinner) pays a parked-worker unpark. The lost-wakeup race between "producer skips the wake" and "spinner gives up and parks" is closed by symmetric SeqCst fences plus a register-before-decrement rule on the idle list; the module doc in scheduler/spin_park.rs is the full argument. Burst recruitment bypasses the route-to-spinner gate on purpose (SpinPark::wake_workers): one spinner can't drain N clones, so recruit unparks N siblings directly.

The batch budget. A drain cycle is bounded by BatchBudget — 64 envelopes (BATCH_MAX_MAILS) or 200µs (BATCH_MAX_USEC), whichever trips first; the wallclock is checked only every 8th dispatch (CLOCK_CHECK_STRIDE), so a short cycle never reads the clock. On a budget hit the worker releases the token (mark_ready) and re-publishes the slot to the injector — the yield that lets two perpetually-busy actors share one worker fairly. The budget bounds the gap between handler turns, never a handler itself: dispatch is cooperative, and a running handler is uninterruptible.

The keep-local valve. By default a worker inlines its whole local cascade — every burst a running handler produces goes to its own deque — until the cascade has run longer than the time valve, at which point the backlog spills to the injector so a heavy cascade parallelizes. The valve is adaptive (worker_deque::time_budget): a small multiple (6×, clamped to 6–60µs) of the measured cross-worker handoff cost — boot-probed and live-refined per box in scheduler/calibrate.rs — because the handoff is the thing inlining out-amortizes. AETHER_LOCAL_TIME_BUDGET_US pins the valve (0 disables it); AETHER_HANDOFF_COST_NS pins the measurement; AETHER_LOCAL_STICKY_MAX (default 256) is the deque-length backstop behind it all.

Those keys are chassis boot config, resolved once into SchedulerTuning by aether-chassis's SchedulerTuningConfig (argv > env > file > default). The scheduler itself reads no environment. Two consequences worth knowing before an A/B: a SubstrateHarness scenario resolves off a hermetic source stack, so setting one of these keys changes nothing there — stage the value with SubstrateHarness::builder().scheduler_tuning(...) instead. The perf lane reads them from its own process environment (perf::harness::scheduler_tuning_from_env), which is what makes perf-compare.sh's PERF_BASE_ENV / PERF_CAND_ENV pinning real.

The chain backstop. A self-sustaining relay (A mails B, B mails A) oscillates its own deque 0→1→0 and would never visit the injector. Every AETHER_LOCAL_CHAIN_BACKSTOP-th consecutive own-deque pop (default 64) the worker probes the injector once before continuing, so a captured worker starves shared work for at most ~K cycles.

Panics. A panic anywhere on a pool worker escalates through the chassis FatalAborter (fail-fast per ADR-0063): in a handler, while acquiring the next slot, or while dropping an actor's last slot reference — so the pool never silently loses a worker thread. A handler panic's reason names the actor; the rest name the worker thread. A dispatch_blocking worker, the off-thread half of a handler turn, escalates a panic in its closure through the same aborter.

Where roots enter

Every causal chain starts with a root — mail sent from outside any handler (Tracing & settlement). Roots reach the scheduler from threads that are outside the pool: through RootPusher::push_root (a driver's or embedder's loop), typed PassiveChassis::send_tracked (an embedder sending through a kind-checked reference), path-proven PassiveChassis::deliver_tracked (an embedder boundary), or Mailer::push (mail/mailer.rs). The last is internal to aether-substrate, and no crate outside it can call it. The public root doors mint from the engine's one chassis-root counter on the Mailer, so no two senders mint the same root. Roots arrive from:

• the chassis frame loop's Tick fan-out and the lifecycle driver's init / wire / unwire steps;
• MCP-injected and hub-bridged mail, arriving on the hub client's socket thread;
• a capability's worker thread (spawn_inherit / dispatch_blocking completions, a listener reacting to a socket read) feeding results back as mail.

An off-pool thread has no own deque, so its wake always takes the spill path: deposit on the recipient inbox, try_wake, push to the shared injector, notify. A root therefore pays at most one injector push and one wakeup — and the entire cascade it triggers then rides the warm in-pool paths above. Root payloads arrive as MailRef::Owned (cross-boundary bytes); only mail produced inside a handler rides a producer ring.

The dedicated-thread edges

A few infrastructure capabilities own a real OS thread because the work at the engine's edge genuinely blocks: a TCP listener's accept loop, the audio output callback, the RPC server's socket, the desktop window driver on the OS event-loop thread. These threads sit outside the scheduler's model — the pool neither runs nor steals from them — and they interact with it only as off-worker producers (the root path above) or, in the window driver's case, as a hand-drained inbox carrying its own finish obligation (Tracing & settlement covers that guard). When to reach for one — almost never — is Concurrency & blocking's topic; from the scheduler's perspective they are simply the boundary.

Reading the scheduler

The trace tree's per-mail timestamps (Tracing & settlement) sample exactly the lifecycle above, so a slow span names a mechanism:

●  t_construct_start    open_burst — the handler's first buffered send
│     construct         the rest of the handler runs, appending sends to the ring
●  t_sent               flush_outbound — the handler boundary; the burst routes
│     queued            scheduling: waiting for a worker to pick the burst up
●  t_enqueue            a worker's BurstWork::run_cycle begins (the pickup stamp)
│     drain             groups/mail this worker dispatches ahead of this one
●  t_received           the recipient's handler is entered
│     handler           the handler runs
●  t_finished           the handler returns

• construct is producer time: the sending handler still running after its first send. A long construct is a long handler, never scheduling pressure.
• queued (t_sent → t_enqueue) is the scheduler's share. Kept-local work reads near zero (the producing worker pops its own deque next); a spilled or recruited burst pays the injector trip and possibly a parked-worker wakeup — on the order of the calibrated handoff cost, single-digit µs. A large queued span means real pressure: every worker busy, or work waiting behind a backlog (the per-envelope enqueue_depth in the rings records the depth observed at deposit).
• drain (t_enqueue → t_received) is in-burst serialization: groups the same worker claimed ahead of this one, plus earlier mail in this mail's own recipient-group. A long drain on a wide fan-out means it under-parallelized — check whether recruitment fell back to the width gate (untrusted cost cells) or the fan-out sat below AETHER_BURST_RECRUIT_MIN. A single fat group is the longest pole: groups never split across workers, so no recruitment shortens one recipient's serial share.
• Each recruited sibling stamps its own t_enqueue at its own run_cycle entry, so one burst's mails can carry different pickup instants — that spread is the cooperative drain, made visible.

Over MCP the tree surfaces t_construct_start / t_sent / t_received / t_finished (no t_enqueue), so queue latency reads as the combined t_sent → t_received span there.

Where to read more

• The contracts this machinery enforces, and how to wait without blocking — Concurrency & blocking.
• The ordering spine and the mailbox/kind model — Mail, kinds & scheduling.
• The timestamp vocabulary and settlement — Tracing & settlement.
• The design record — ADR-0087, including the forward-notes that track where implementation refined the original framing.

The frame lifecycle

Governing ADR: ADR-0082 (application-declared lifecycle sequence). The model — a declared graph of stages, settlement-gated advance, per-stage subscription on aether.lifecycle — is stable, and the stage-kind vocabulary (Tick, Render, Present, Shutdown, Quit) ships today. The per-chassis graphs are still being built out: desktop and substrate_harness run a Tick → Render → Present frame; headless stays tick-only; the InitCaps / InitComponents boot stages exist in the kind vocabulary but aren't yet wired into a shipped graph. Build on the stage kinds and the subscribe surface; read aether-lifecycle and the ADR for the graph a given chassis declares.

A component never runs a loop. The substrate owns the frame, and an actor reaches the frame the same way it reaches anything else — by mail. Each binary that hosts the engine (the desktop chassis, the headless chassis, a future replay or fixed-timestep host) declares its lifecycle as an ordered graph of stages, and the substrate ships one capability, LifecycleCapability at the aether.lifecycle mailbox, that walks the graph and broadcasts each stage in turn. An actor that wants a stage — Tick to step, Render to submit geometry — subscribes to it; the cap fans the stage out to every subscriber. This is the same publish/subscribe shape as input streams, on a different mailbox.

Why it exists

Every chassis runs the same skeleton — a cadence source, a per-frame broadcast, the drain that waits for the frame's work to finish, and a present or capture at the end — and each one drives a different cadence: the desktop chassis paces to vsync, the headless chassis to a fixed timer, the substrate harness steps one frame at a time. Encoding that skeleton as hand-written loop code in each binary forces the same structure to be re-derived per chassis, and the only thing that actually differs between them is the cadence and which stages they run.

Declaring the lifecycle as data collapses the loop to one shape. The application states what stages exist and in what order; the driver owns how to walk them; the chassis main loop owns only the cadence — when to ask for the next step. Adding or reordering a stage is an edit to one graph, not four loops. The cadence difference lives in the chassis's advance loop and the stages it declares, not in duplicated frame structure. And because the driver is a normal actor at a real mailbox, every frame-stage chain has a labelled root in the trace tree — "what triggered this mail?" walks straight up to aether.lifecycle's broadcast of the stage.

What it does

One mailbox, a graph of stages. Everything addresses aether.lifecycle, owned by the LifecycleCapability actor — the sole owner of the compiled graph, the subscriber table (one typed set per stage K, holding each subscriber as a ProtocolRef<Subscriber<K>>), the fan-out, and the settlement gating. The cap is a bridged singleton, so a wasm guest that declares depends(LifecycleCapability) names it by type: ctx.subscribe::<LifecycleCapability, Tick>().

Stages are signals; Tick carries time. Tick is the one stage that carries time, in two fields. delta_micros: u32 is the game time this frame adds, as the chassis driver states it, and elapsed_micros: u64 is the game time since boot with this frame included, so the frame covers (elapsed_micros - delta_micros, elapsed_micros]. The lifecycle capability owns the total and adds each frame's delta to it exactly once, so delta_micros is always the growth of elapsed_micros. A subscriber integrates a rate in units per second with tick.delta_seconds(), so slowing or speeding the frame cadence does not slow or speed authored motion, and logic that counts in whole steps reads them from tick.steps(length) (below). Every other stage is a zero-sized signal. Application state still rides its own mail — the camera computes a view-projection matrix on Tick and publishes it to aether.render, rather than threading it through a stage.

Tick time is game time; ctx.now() is measured time. The two Tick fields say how far the game has advanced, as the driver states it. An actor that wants to know how long its own work took reads the engine's actor clock, with the same call on a guest ctx and a native one:

#![allow(unused)]
fn main() {
let started = ctx.now();
// ... the work being measured ...
let took = ctx.now().since(started); // core::time::Duration
}

ctx.now() returns an aether_actor::Instant. Within one engine a later reading is never less than an earlier one, and only the difference between two readings means anything: it is not wall-clock time, not game time, and it means nothing in another engine or after a restart. init can take a reading too (WasmInitCtx::now, NativeInitCtx::now), so an actor that keeps an Instant in its state builds it there. See Guest, native, and wire boundaries for what an Instant may not do.

The stage-kind vocabulary:

Two more kinds are the cadence wire, not stage broadcasts: LifecycleAdvance (aether.lifecycle.advance) is what the chassis main loop sends to ask for the next step. Its delta_micros is copied into Tick and joins the total on the advance that broadcasts Tick; other stages ignore it. LifecycleAdvanceComplete (aether.lifecycle.advance_complete) is the reply the chassis waits on.

The graph is a builder over kind types. A chassis builds its graph with LifecycleGraphData::builder(), naming each stage by its kind and the edge out of it. The desktop and substrate-harness frame:

#![allow(unused)]
fn main() {
LifecycleGraphData::builder()
    .state::<Tick>()    .next::<Render>()
    .state::<Render>()  .next::<Present>()
    .state::<Present>() .next::<Tick>()    .quit::<Shutdown>()
    .terminal::<Shutdown>()
    .start::<Tick>()
    .build()
}

The builder's type-state enforces at compile time that every .state::<S>() is followed by a .next::<T>() before the next state, and that exactly one .start::<S>() is set. .build() returns a BuildError if an edge targets an unregistered kind, a kind is registered twice, or the graph has no terminal — so a malformed lifecycle fails at chassis-build, not at runtime.

Settlement gates each advance. The chassis main loop drives cadence by mailing LifecycleAdvance to the cap once per step, stating the frame's elapsed time, and what a driver states is what game time means on its chassis:

• Desktop measures wall time between frames. It is the one driver that measures, so it is the one a stall can reach, and it holds each frame's share to a limit before stating it: AETHER_DESKTOP_MAX_FRAME_DELTA_MICROS (--desktop-max-frame-delta-micros, [desktop] max_frame_delta_micros), default 250,000. On a limited frame game time slows, no step is skipped, every actor sees the same slowed clock, and the driver warns of the microseconds it did not count, at most once per cooldown. A limit of zero is refused at boot.
• Headless states its timer period on every advance, so game time is the number of Ticks broadcast times the period. A frame that overruns is not made up, so headless game time runs slow against the wall clock then. A slow tick rate is honoured whole: at two ticks a second each Tick adds 500,000 microseconds, with no limit.
• A harness states the duration the test wrote, and game time is the sum of those durations exactly.

The cap adds the delta it is told and applies no limit of its own. On each advance the cap broadcasts the current stage to its subscribers, subscribes settlement on that broadcast's chain root, and waits: it advances the state pointer along the resolved edge and replies LifecycleAdvanceComplete only once that stage's whole chain has settled. Cadence couples to actual work completion — Render broadcasts only after every actor's Tick handler has finished, so a render producer submits against fully-settled cross-actor state, never a half-updated frame. A chassis that overruns its cadence and sends a second LifecycleAdvance while one is still in flight sees it warn-drop rather than skip a stage. (When no settlement registry is wired — a bare test harness — the cap falls back to fire-and-advance, replying immediately.)

Quit is one signal with one consumption point. A chassis bridges OS-level termination — ctrlc, the window's close button, a future hub-shutdown mail — to a single Quit mail. The cap sets a quit_pending flag on receipt and consumes it at the next state whose graph declares a quit edge. With the quit edge on Present, a quit requested mid-frame lets the in-flight Tick → Render → Present cycle finish before the lifecycle advances to Shutdown — the frame drains before exit. Placing the quit edge elsewhere expresses a different shutdown policy; the topology spells out the answer.

Shutdown and unwire are different teardowns. The Shutdown broadcast arrives as mail with the actor's full mail surface still operational — work that needs to talk to peers (save state, flush a write, post a metric) belongs in a Shutdown handler, and the driver waits for the Shutdown chain to settle before the loop exits. Then the chassis tears actors down, running each actor's unwire finaliser (release native handles, drop GPU resources). Shutdown is the graceful "everything still works" cleanup; unwire is the post-lifecycle "the world is going away" finaliser. The two aren't interchangeable.

Teardown closes actors in dependency order. Every actor is closed, an idle one included: the chassis tells it the engine is going, wakes it, and waits for its close, which drains its inbox, runs unwire, and ends its name. The order is fixed. Instanced actors go first, loaded components among them. The chassis's composed capabilities follow in reverse boot order. The pumped capabilities a driver owns (aether.window and aether.render on the desktop chassis) go last, render before window, because the others depend on them. A departing actor's MonitorNotice, and what a component sends from unwire (a texture it destroys, say), is therefore on the inbox of a capability that is still open, and that capability's own close dispatches it.

The interrupt/stage split. Key presses, mouse movement, and resizes are asynchronous interrupts — they arrive whenever the platform produces them, on the window actor's selector-aware streams. Tick, Render, and Present are frame stages — they fire in declared order, paced by the chassis, on aether.lifecycle. Both reach an actor as ordinary mail in arrival order on its single dispatcher thread, and both use typed subscription helpers, but they have different owners: lifecycle owns the frame graph; window owns events originating from each window.

How to use it

Subscribe a stage in wire. init can't send mail (its context is resolver-only), so a stage subscription goes in the wire hook, which runs post-init with mail allowed — the same site as an input subscribe, addressing a different cap. wire receives a WireCtx, the window-bearing context that also serves the assets a component ships in aether.asset.<path> sections (ADR-0163); it Derefs to WasmCtx, so every send and subscribe verb reads the same as in a handler. wire returns Result<(), ActorInitError> and ends in Ok(()); an Err fails the load (see the actor model). The wire context is typed by your actor like a handler's: WireCtx<'_, '_> reads as WireCtx<'_, '_, Self>. Declare the lifecycle cap as a dependency and name the publisher and the stage:

#![allow(unused)]
fn main() {
#[actor(root, depends(LifecycleCapability))]
impl WasmActor for Camera {
    fn wire(&mut self, ctx: &mut WireCtx<'_, '_>) -> Result<(), ActorInitError> {
        ctx.subscribe::<LifecycleCapability, Tick>();
        ctx.subscribe::<LifecycleCapability, Render>();
        Ok(())
    }
}
}

A native actor's wire and unwire hooks are typed the same way: NativeCtx<'_> reads as NativeCtx<'_, Self>, so they reach their declared dependencies.

ctx.subscribe::<P, K>() subscribes the calling actor — the cap reads the subscriber off the inbound's host-stamped Source, so you name neither the stage id nor your own mailbox. It is checked at compile time three ways: P must publish K (LifecycleCapability publishes the stage kinds), the actor must declare depends(P), and the actor's handler for K must not declare a reply (a -> () handler, or an unchecked one), because a broadcast stage has no one waiting for a reply. Any one of them missing is an error at the call. The cap checks the last one again at run time: it refuses a sender whose published rows lack a silent or unchecked handler for the stage. ctx.unsubscribe::<P, K>() is the teardown twin, with the first two checks. You don't unsubscribe on the way out — the host clears your subscriptions when the component drops.

To subscribe another actor — an operator over MCP, or a test — send aether.lifecycle.subscribe with a subscription naming the stage and the subscriber's canonical path, as in {"Tick": "aether.kit.camera:main"}. The path decodes only when the actor there handles the stage silently, and the cap proves it live at receipt. A path that fails either proof is answered {"Err": {"Subscriber": {"path": …, "reason": …}}} naming it and why; a stage the graph does not declare is {"Err": {"Stage": {"stage": …, "error": …}}}.

Then handle each stage as its kind, like any other mail:

#![allow(unused)]
fn main() {
#[handler::event]
fn on_tick(&mut self, ctx: &mut WasmCtx<'_>, _tick: Tick) { /* advance one frame */ }
}

Logic that counts in whole steps takes them from the tick. The step length is the game's own constant, a StepLength that cannot be zero; the engine has no step length of its own:

#![allow(unused)]
fn main() {
const STEP: StepLength = StepLength::from_micros(20_000).expect("a nonzero step");

#[handler::event]
fn on_tick(&mut self, _ctx: &mut WasmCtx<'_>, tick: Tick) {
    let steps = tick.steps(STEP);
    for index in steps.indices() {
        self.step(index);                 // each whole step, exactly once, numbered from 0 at boot
    }
    self.blend = steps.fraction();        // the part of the next step already elapsed, in [0, 1)
}
}

steps is a pure function of the one mail and the length, so every actor that asks with the same length gets the same step indices, whenever it was loaded, and over any run of frames each step is handed out exactly once. A frame may hold zero steps or several. Each actor counts a frame's steps inside its own Tick handler: nothing settles between step N and step N+1, so actors that must mail each other inside one step are outside what steps provides.

A ctx that omits its actor is typed by it: the macro reads WasmCtx<'_> as WasmCtx<'_, Self>, so the ctx reaches only the actors the component declares with depends(R). The ctx's type arguments are receiver, sender, mode: the actor first, the sender the handler requires second (Anyone when it states none), and the reply mode third (WasmCtx<'_, Self, Anyone, Unchecked>); spell WasmCtx<'_, Erased> for the untyped view.

aether-kit's camera export subscribes Tick and Render — it computes its camera matrix on Tick and publishes it to aether.render on Render; its MeshViewer export (aether.kit.mesh) subscribes Render to replay its mesh each frame.

A stage your chassis doesn't declare fails fast. Subscribing to a stage the local graph doesn't carry replies aether.lifecycle.subscribe_result with an Err — an actor authored against a stage its chassis omits learns at boot, not by silently never firing. On the fire-and-forget subscribe path the error warn-drops, so a component that subscribes Render runs unchanged on a chassis that lacks the stage: it simply never receives Render.

From an agent over MCP. Ticks are the substrate's own cadence — you don't pump them by hand. The lifecycle advances under the chassis loop, so the way you observe it is through a subscribed component's behavior or its logs. Mailing a stage kind to aether.lifecycle yourself bypasses the driver and isn't the way to step the engine; let the chassis drive the frame.

The per-chassis graphs today

Which stages a chassis declares is its own choice; the driver walks whatever graph it's handed. The shipped graphs:

• Desktop and substrate_harness run frame_lifecycle_params — Tick → Render → Present → Tick, looping, with the Quit escape to a Shutdown terminal on Present. A full Tick → Render → Present cycle runs per frame; Render broadcasts only after the Tick chain settles, and GPU submit/present runs after Render settles, so a submission integrates the fully-settled state of the frame.
• Headless runs tick_only_lifecycle_params — Tick → Tick, looping, with the Quit escape to Shutdown on Tick. Headless composes no render actor, so a component that depends on render is refused at load there; one that subscribes Render without depending on render gets the lifecycle's Err for a stage the graph omits, while its Tick path runs unchanged.
• The hub is a coordinator, not a frame-driven host — it runs no lifecycle graph.

The InitCaps / InitComponents boot stages are declared in the kind vocabulary and the ADR's stage model, but the shipped graphs start at Tick; a chassis that needs a two-pass boot broadcast adds them to its own graph.

How to extend or reuse it

• A new chassis declares its own graph and drives its own cadence. A replay host that steps to recorded frame times, a fixed-timestep physics host, or a test harness that steps once all drop in by building a graph and looping LifecycleAdvance until the reply's next reaches a terminal — the driver is unchanged.
• A new stage is a kind plus a .state::<K>().next::<…>() edge in the chassis graph; actors that want it subscribe by type. There's no driver code to widen — the cap fans out by KindId, and a chassis that omits the stage simply doesn't declare it.
• Any actor can subscribe, not just components — a native capability that needs the tick subscribes through the same mail. What an actor receives is exactly the stages it asked for on a chassis that declares them.

Where to read more

• The declared-graph decision, the builder type-state, the quit-edge semantics, and the per-chassis realizations — ADR-0082.
• How a stage advance waits on its whole chain, and what "settled" means — Tracing & settlement.
• The interrupt side of the split — Key, MouseMove, and WindowSize published by the window actor — Input streams.
• The wire hook, init versus wire, and writing handlers — Components & lifecycle.

Tracing & settlement

Governing ADRs: ADR-0080 (mail lineage + settlement detection), ADR-0086 (settlement decoupled from the trace stream), ADR-0093 (hold-until-resolve dispatch), ADR-0094 (the owned-dispatch obligation guard). The contract — what "settled" means and what you must uphold for it — is stable. The mechanism that delivers it (the emit-time per-root counter, the per-actor trace rings, the guided walk that rebuilds a tree) is settling, so this page documents the contract and defers the internals to those ADRs.

Send one mail and the handler that receives it may send more, and those handlers more again — a single message fans out into a cascade of downstream work. Settlement is the engine's answer to the question that cascade raises: has everything this mail set in motion finished? Tracing is the same causal lineage seen as a tree — what happened, in what order, and how long each hop took.

The two are built from one body of bookkeeping but serve different needs. An agent driving the engine leans on settlement to know an effect has fully landed before it reads a frame or sends the next thing, and on the trace tree to see why an exchange was slow or where a chain stalled. An author writing a capability or component needs the model because a handler that replies late owes its chain an obligation — miss it and a caller hangs with nothing named.

Why it exists

The engine needs to know a piece of work is fully done only at specific points — when something has to happen atomically, once everything an earlier mail set in motion has finished. A frame can't advance until the tick's effects have played out (the frame lifecycle gates each stage on this); a component swap waits for the old instance to finish draining; a lifecycle step waits for wiring to complete; an agent waits for its mail's effects before it reads the result back. What's being waited on is never one mail but the whole chain of work it set off, and no single mail can report that the chain has closed — the work that matters is everything it triggered.

Without an exact signal, the only way to wait is to approximate — and every approximation of "has this chain closed" races. You could poll a counter until it looks quiet, wait out a fixed window, or send a redundant mail to ride FIFO ordering; each holds up on a quiet machine and breaks under load, because nothing tells the waiter that the last mail in the chain is still on its way. Settlement removes the guesswork: it tracks the causal lineage of every mail, so a gate waits on a fact rather than a timeout. That same lineage, kept anyway, doubles as a complete cause-and-effect graph — the trace tree.

The model: lineage and the settled condition

Every mail belongs to a causal chain, named by its root. A root is a mail sent from outside any handler — the chassis dispatching a Tick, a lifecycle step (init / wire / unwire), a mail injected over MCP or bridged from the hub, a capability's worker thread reacting to a socket read. Mail sent from inside a handler inherits its trigger's root instead of starting a new one. So one external stimulus and the entire cascade it sets off all carry the same root id, and the whole chain is identified by that single originating mail. (Chains that the chassis itself originates are marked by a sender of aether.chassis — the tagged id mbx-aaaa-aaaa-aaaa you'll see at the top of a trace tree.)

A chain is settled when it is closed. Under each root the engine keeps two counts: in_flight — mail sent but not yet finished handling — and held_open — explicit holds, described next. The chain settles the instant both reach zero. Given the hold contract below is honoured, that signal is exact: the counts never transiently dip to zero with work still on the way, so the chain reports settled once, as a fact rather than a hint. That exactness is the whole point — it's what lets a waiter trust the signal outright instead of falling back to a timeout. The invariants page states this as a guarantee; here is the obligation that earns it.

The hold contract

The counts are only exact if every mail that is still coming is already counted. For a synchronous reply that falls out for free: a handler that replies before it returns records the reply's send ahead of its own finish, so the chain can't reach zero with that reply outstanding. Nothing to do.

The gap is deferred work — a handler that kicks off a slow call and replies in a later turn, after it has already returned. In the window between the return and the eventual reply, that handler's mail is finished and nothing new is yet in flight, so the counts would fall to zero and the chain would settle early, reporting "done" while the real answer is still being computed. A waiter would be told the work finished before its reply ever arrived.

A settlement hold closes that gap. A handler with deferred work takes a hold on its root before returning and keeps it until the last send goes out; the hold sits in held_open, so the chain stays open across the window, and releasing it after the reply is what finally settles the chain. You rarely take a hold by hand — the sanctioned offload primitives manage it for you. ctx.dispatch_blocking (and the #[handler(task)] completion sugar) acquire the hold when they spawn the worker and release it when you resolve, reply-then-release in that order so the settle can't beat the reply; spawn_inherit holds for the worker's lifetime. acquire_settlement_hold is the explicit handle for the rare hand-rolled case, such as buffering a request to drain in a later turn. It hands back an Option<SettlementHold>, and None is a real answer: a context with no in-flight root has no chain, so there is nothing to keep open. Work deferred from such a context is outside settlement entirely — no waiter can be told when it finished — which is why the absence is a value you handle rather than a guard that quietly gates nothing. The full offload story — which primitive for which shape, and why a raw std::thread::spawn silently opts work out of settlement — lives on Concurrency & blocking; this page is the why behind the hold.

The obligation guard

There is a second way a chain closes, on the receiving side. A capability that owns an inbox mailbox — one that takes an owned dispatch off a downstream channel — owes that inbound mail its Finished, or the chain never closes. The substrate brackets the two synchronous mailbox shapes automatically — an inline handler, and the standard actor dispatcher at handler exit — so an ordinary actor never has to think about this. The third shape is a mailbox drained by hand, off the pool: a capability that claims a mailbox and drives the drain itself, the way the desktop chassis's window driver does. Window operations have to run on the OS event-loop thread rather than a pool worker, so aether.window is claimed as an inbox the event loop drains between frames (Window covers that mailbox's surface).

A claimed mailbox is settle-safe by construction (ADR-0106). The claim hands the capability a SettlingInbox, not a raw receiver, and its drain methods yield each mail as an InboundMail guard that records Finished and replies along the inbound's causal chain. The guard settles when it falls out of scope — on every arm, including a decode error, an unrecognised kind, an early return, or teardown of the drain with mail still queued — so a leak at this seam is unrepresentable in the consumer's code, the same way the standard dispatcher's unconditional discharge tail keeps an actor author from leaking. Settling on scope exit rather than on payload access is deliberate: a reply's Sent must be recorded before the inbound's Finished, and InboundMail::reply sends inside the guard's scope, so the reply joins the chain before the drop closes it.

Underneath, every owned dispatch still ends one of two ways — discharged (the obligation ends here; I am recording Finished) or transferred (the obligation moves with the work onto a downstream envelope). The framework drain does the discharge; one relay type, built where an inbox channel is opened, moves a dispatch onto an actor's inbox and does the transfer. An owned dispatch dropped while still armed panics at the leaking seam in debug builds, naming the mail_id, kind, and mailbox (ADR-0094); release builds carry no field and no check, so the guard costs nothing. The guard now backs the in-crate relay and park seams rather than the claimed-mailbox drain, which no longer needs it — forget it on a relay you write and you still get an immediate, located failure instead of the silent multi-second hang the chain would otherwise wedge into. Parked mail is unarmed (the obligation guard does not apply), but it is still settled: when the Mailer tears down, every mail still parked on a never-resolving handle receives its Finished, so the upstream chain closes rather than hanging.

Two handles, because there are two counts

Replies bring you into contact with two RAII types, and which one you are holding follows directly from in_flight and held_open.

InboundMail brackets a drained envelope. Its drop records Finished, so it moves in_flight. Replying is a capability it offers along the way — it has the sender and the reply lineage to hand — and reply returns false when the sender asked for nothing.

DeferredReply is the obligation to answer someone. It carries a SettlementHold and a reply target and knows nothing about an envelope, so it moves held_open. TaskDone is the same debt with a worker's output attached; both surrender a bare DeferredReply through IntoDeferredReply. Before its terminal, a debt can forward any number of already-encoded replies with reply_envelope, which borrows it: each goes to the waiting caller under the root the hold keeps open, and the debt stays owed. The fleet proxy relays each reply event a remote engine streams back this way. The typed reply stays the terminal that discharges the debt.

Keeping them apart is what lets both be outstanding on one chain at the same time, which is precisely the deferred case: the handler returns and its inbound settles in_flight, while the hold keeps held_open above zero until the answer goes out. One combined handle would mean one combined count, and the window the hold exists to cover would close early — the settle-before-the-reply failure the hold contract above is there to prevent.

Their drop contracts differ for the same reason. Every drained envelope earns exactly one Finished whether or not anyone wanted an answer, so dropping an InboundMail unreplied is ordinary. A hold is taken only when a caller is waiting, so dropping a DeferredReply unreplied strands that caller forever — which is why its drop releases the hold and then panics, in that order and in every build, so the chain still settles and the scheduler escalates the lost reply through the chassis aborter. An actor closing with debts still owed while the engine keeps running answers them: the engine sends each Held<R> its R::unanswered() and then releases its hold, so Sent precedes Release (ADR-0243 §1), and an actor that keeps a DeferredReply in state answers it in unwire. An engine teardown releases held debts with no reply, because every requester is closing with it. abandon_for_actor_close, the one path that releases without a reply or a failure, survives only for the component host's boot waiters until #7008 removes it.

The trace tree

The same lineage keys that drive settlement — each mail's id, its parent, its root — also reconstruct the full causal graph. A trace tree is a set of mail nodes; each names who sent the mail, who received it, the kind, and a series of timestamps sampled as the mail moves through the engine. You walk a chain by following parent edges down from the root, and the timestamps localize the slow hop in a cascade without instrumenting anything. Here is where each one is taken, for a single mail:

●  t_construct_start    the sender's outbound burst opens (its first buffered send)
│     construct         the rest of the sending handler runs, buffering more sends
●  t_sent               flush — at the handler boundary the burst is routed
│     queued            wakeup + scheduling: waiting for a worker to take the burst
●  t_enqueue            a worker picks up the burst (enters its run cycle)
│     drain             earlier mail in the burst is dispatched ahead of this one
●  t_received           this mail's handler is entered
│     handler           the handler runs
●  t_finished           the handler returns

The two spans you reach for most are queue latency — how long the mail waited before a handler ran it — and handler duration (t_finished − t_received). The finer queued / drain split says why a hop waited: scheduling pressure (no worker free yet) versus a long serial fan-out dispatched ahead of it in the same burst — The scheduler maps each span back to the dispatch machinery. A node still missing t_finished is mail that hasn't finished handling yet.

Where it lives, and how to read it. Trace events aren't kept centrally. Each actor holds its own trace ring — the same per-actor storage the log rings use (ADR-0081 / ADR-0086) — recording the events that passed through it. A tree is rebuilt by a guided walk: start at the root's sender, read its ring (aether.trace.tail, the sibling of the aether.log.tail behind actor_logs), follow each onward Sent to the recipient's ring, and stitch. send_mail_traced runs that walk and hands back the stitched tree — and over MCP that's the surface, since there's no standalone per-actor trace tool the way actor_logs exposes the log rings. The tree it returns carries t_construct_start, t_sent, t_received, and t_finished per node; the t_enqueue pickup point and the ready-queue depth live in the rings but aren't surfaced there, so over MCP queue latency reads as one t_sent → t_received span.

Tracing and settlement are deliberately decoupled (ADR-0086) because they have opposite requirements. Settlement is control-plane: exact, on the frame's critical path, never allowed to lag or settle early. Tracing is observability: best-effort and off the critical path, so it can lose data without ever affecting whether or when a chain settles. The line to hold onto is that the settled signal is never wrong while a trace tree can be honestly incomplete — so don't reach for the tree to decide whether work is done; that's settlement's job. Reach for it to see what happened and how long it took.

Gotcha — a trace is a bounded window, not a durable log. A saturating ring reclaims and grows before it drops a live chain. When it fills, it first reclaims the oldest entries whose chains have already settled — those trees are complete, so dropping them costs nothing — and it grows its capacity, doubling toward a configured ceiling, only to make room for chains still in flight. Past the ceiling, or once every old entry belongs to a still-in-flight chain, the oldest entries are overwritten one at a time. A tree whose entries were partly overwritten still comes back, with the nodes that survive: a node whose Finished was dropped reads as in flight, and truncated names each actor whose ring cut the tree and the sequence it was cut before. A root whose own Sent was dropped is an error, not a tree. So what you tend to lose first is an old, already-settled trace you didn't read promptly, not the in-flight work the ring is actively protecting. A tree self-reports where it was truncated, but old or high-volume chains can come back incomplete or not at all. The starting size and the growth ceiling are tunable (AETHER_ACTOR_TRACE_RING_SIZE and AETHER_ACTOR_TRACE_RING_MAX_SIZE) if you routinely lose chains to traffic spikes; even so, read a trace promptly after the work rather than counting on reconstructing something from minutes ago.

How an agent uses it

send_mail already rides settlement on your behalf. Each item blocks until its chain settles. Its default terminal reply projection keeps the last arrival-ordered reply plus any recognized decoded/kind-name error; none keeps only those errors and all returns the complete stream. A request/reply — mail aether.fs.read, get the bytes — is still a single call with no polling, while a multi-reply driver can opt into the exact amount of history it needs. fire_and_forget opts an item out only when completion and ordering are deliberately unobserved. A handler that emits no reply can still settle normally.

send_mail_traced is the tool for when you want the tree, not just the reply. It dispatches a batch under one shared root and, once that whole chain settles, returns the combined trace tree, the correlated replies, and a status:

• "settled" — the chain closed. By default mails is null, tree holds one indented line per node (sender → recipient, kind, and handler duration), node_count states how many nodes were rendered, and in_flight reads 0. When a trace ring dropped entries this tree needed, truncated lists each such actor and the sequence its ring was cut before; a whole tree carries no truncated. Pass trace: "nodes" to restore the complete mails nodes with parent edges and all timestamps; that mode omits tree and carries the same node_count.
• "timeout" — the chain didn't settle within settlement_timeout_millis (default 300 000, clamped to 600 000). A timeout is the bound on a hung chain, and the usual cause is exactly the two failures above: a deferred reply that never held its chain open, or a drain that dropped its finish obligation upstream. The triage path from this status to the offending handler is the Debugging a hung settlement recipe.
• "dispatched" — only with fire_and_forget; the shared root acked, no settlement wait, and both projections' fields are omitted.

Reach for send_mail_traced over send_mail when you need proof a whole cascade finished rather than just one reply, the timing breakdown of a slow exchange, or an all-or-nothing batch where a bad spec aborts before any mail moves. For independent items where each reply is all you want, plain send_mail is simpler. Both surfaces are covered operationally on The MCP harness.

Where to read more

• The rules this page earns, stated as guarantees — Invariants & guarantees.
• How to offload without blocking — the three spawn shapes and the hold in practice — Concurrency & blocking.
• The agent-facing tool surface for send_mail / send_mail_traced — The MCP harness.
• The lineage model and the emit-time counter — ADR-0080 and ADR-0086; the hold-until-resolve dispatch primitive — ADR-0093; the owned-dispatch obligation guard — ADR-0094.

Logging

Governing ADR: ADR-0081 (decentralized per-actor log storage). The model — a bounded ring per actor, queried by mailbox name, fed only by in-actor tracing::* events — is stable.

Logs in aether are decentralized: each actor owns its own bounded log ring, and you read one actor's logs by querying that actor's mailbox by name. There is no central log store. Log storage scales with the number of actors and an actor's ring dies with the actor, so the question a log query answers is narrow and precise — "what did this actor say" — not "what happened somewhere in the engine."

The one thing to know before anything else: only tracing::* events emitted inside an actor's handler land in a ring. Anything the host emits outside a dispatched handler — substrate boot, the scheduler thread, the panic hook — goes to stderr and never enters any ring. So when a log line you expected is missing from actor_logs, the first thing to check is whether it was emitted from inside an actor at all.

Why it exists

A central log buffer makes every actor pay a flush hop — at N actors times the tick rate, that's a steady stream of envelopes carrying nothing but log entries to one shared ring. Giving each actor its own ring removes that hop entirely: an event lands directly in the ring of the actor that emitted it, where a query will find it, with no mail in between. Storage follows the actors — a short-lived actor carries a small ring and frees it on teardown, and no single structure grows without bound as actors come and go.

Reading stays decentralized to match. Rather than a substrate-side aggregator walking the actor registry, each actor answers a query against its own ring and a caller composes a cross-actor view client-side if it wants one. One query, one actor, one round-trip — and the actor model's boundary stays intact, because no capability reaches across actors to read another's state.

What it does

Each actor owns an ActorLogRing. It's a bounded FIFO of log entries living in the actor's own slots. An entry carries its level, target, message, a millisecond timestamp, and a per-actor sequence number that starts at 1 and increases monotonically. The actor's own dispatcher thread is the sole writer, so the ring needs no lock.

In-actor events land in the ring; host events go to stderr. The tracing layer the substrate installs routes each event by where it fired:

• A tracing::* event emitted inside a dispatched handler lands in that actor's ring. A loaded wasm component is no exception — its guest tracing::* events cross the FFI on the component's dispatcher thread, so the same layer catches them and they land in the component's ring.
• An event emitted outside any actor — substrate boot, the scheduler, the panic hook — hits stderr only through the registered formatting layer. It enters no ring and surfaces in no query.

A component's line is printed on stderr under the host target aether_substrate::guest, with the component's own target as the guest.target field. Its ring entry carries the component's own target, and an AETHER_LOG_FILTER directive matches a component by the target the component used.

That split is the page's main gotcha and the first thing to reach for when a line is missing: a host-side log is real, it's on stderr, and it was never going to appear in a ring.

AETHER_LOG_FILTER filters at emit time. The subscriber reads an EnvFilter from AETHER_LOG_FILTER (the same target=level directive syntax RUST_LOG uses), defaulting to info. An event the filter rejects is never recorded — it reaches neither a ring nor stderr. That's the emit-side gate; the query-side level filter below narrows what an already-recorded ring returns.

The ring is a bounded window, not a durable log. Once the ring is at capacity, the oldest entry is evicted to make room — under sustained load, or simply with enough elapsed time, an actor's earliest entries are gone. The same trace-ring caveat applies that Tracing & settlement covers for its rings: read promptly, and don't count on reconstructing something from a high-volume burst minutes ago. A query reports a truncated_before cursor when eviction dropped entries the caller hadn't yet seen, so a gap is visible rather than silent.

The query is aether.log.tail, inherited by every actor. Every actor answers aether.log.tail { max, min_level, since, contains } through a framework-built-in dispatch arm — no author writes a handler for it. The reply, aether.log.tail_result, carries the matching entries oldest-to-newest, a next_since cursor (the highest sequence returned), and the truncated_before signal. min_level filters by level, since returns only entries past a cursor, contains filters message bodies by a case-sensitive substring, and max caps the count (0 resolves to a default of 100, and anything above 1000 clamps to 1000). All filters run in the owning actor before entries cross the wire.

How to use it

Over MCP — actor_logs. The actor_logs(engine_id?, address, max?, level?, since?, contains?) tool sends aether.log.tail to the addressed mailbox and returns its ring slice. Omit engine_id to target the sole supervised engine. The surface:

• address — any actor's mailbox is queryable, addressed by name. That includes chassis mailboxes ("aether.audio", "aether.render") and a loaded component by its full lineage name, its published name ("aether.kit.camera").
• max — caps returned entries; defaults to 100, clamps to 1000.
• level — trace / debug / info / warn / error; filters server-side so a noisy ring returns only what you asked for.
• since — the prior reply's next_since. Thread it back to page forward past entries you've already read without re-fetching them.
• contains — a case-sensitive substring required in the entry's message; omitted applies no content filter. It runs server-side so non-matching entries do not cross the wire.

Paging is the move you'll reach for on a busy actor: an actor_logs call returns next_since, and passing it as the next call's since walks the ring forward in chunks. A query against an unregistered address comes back as an error, not an empty success — so a typo'd address reads as a failure you can see.

From a component — emit with tracing. An author writes tracing::info!, tracing::warn!, and the like inside handlers; those calls are exactly what populates the actor's ring. Nothing else is required — there's no log capability to address, no batch to flush:

#![allow(unused)]
fn main() {
#[handler::event]
fn on_tick(&mut self, ctx: &mut WasmCtx<'_>, _t: Tick) {
    tracing::debug!(frame = self.frame, "advancing");
}
}

A ctx that omits its actor is typed by it: the macro reads WasmCtx<'_> as WasmCtx<'_, Self>, so the ctx reaches only the actors the component declares with depends(R). The ctx's type arguments are receiver, sender, mode: the actor first, the sender the handler requires second (Anyone when it states none), and the reply mode third (WasmCtx<'_, Self, Anyone, Unchecked>); spell WasmCtx<'_, Erased> for the untyped view.

A tracing::* call from outside a handler — at module load, on a thread the actor spawned — is a host-side event by the rule above, so it won't appear in the ring. Keep diagnostic emits inside the handler if you want them queryable.

Naming another actor in a log line. Name it by its actor path, never its mailbox id. A native capability that holds a proven reference records actor = %ctx.actor_path(reference), which answers the actor's canonical path (aether.kit.camera) even after the actor has departed; a typed ActorRef<R> passes reference.erase(). An id that belongs to no route has no path, so it prints as its tagged mbx-… text, and aether.inventory's Resolve answers None for it: Resolve reads a route's name. Guest code names the members of its own inline cluster by their subnames, which it already holds.

How to extend or reuse it

The surface is intentionally fixed: every actor inherits the aether.log.tail query arm, so a new actor — native capability or loaded component — is queryable the moment it exists, with no wiring. What an author controls is what reaches the ring: the tracing::* calls inside handlers, gated by AETHER_LOG_FILTER at the substrate. Cross-actor aggregation, level normalization, or per-namespace dedup isn't substrate policy — a caller composes a multi-actor view client-side by querying each mailbox and merging, which is exactly what an agent does when it walks several mailboxes over MCP.

The log rings have a sibling: the trace rings. Both are bounded per-actor storage queried the same way — aether.log.tail for what an actor said, aether.trace.tail for what a mail caused. They differ under saturation: a log ring wraps immediately, dropping its oldest line; a trace ring grows toward a configured ceiling first, because dropping a single trace event leaves a hole in the tree it belongs to. The log ring's depth is the chassis-wide boot knob AETHER_ACTOR_LOG_RING_SIZE (ActorRingConfig, default 1024 entries per actor). They answer different questions and stay separate; Tracing & settlement is the page for the trace side.

Where to read more

• The decentralized model, the per-actor ring, and the crash-dump path — ADR-0081.
• The actor-aware tracing layer that routes in-actor versus host events — ADR-0077.
• The trace rings that sit beside the log rings, and the shared tail query shape — Tracing & settlement and ADR-0086.
• The actor_logs tool in the agent-facing surface — The MCP harness.

Configuration

Governing ADR: ADR-0090 (application configuration). The model — the layered source-stack, one typed struct per subsystem, validation, and discovery — is stable and mostly shipped; the rollout is still settling at the edges (a handful of chassis-wide knobs are still read inline). This page documents the contract and defers the rollout's internals to the ADR.

Configuration is how a knob's value gets decided before the engine runs — the worker-pool size, an HTTP allowlist, the tick rate. (A secret such as an API key is never a knob value; config only names it — see Secrets are never knob values.) Values come from a layered stack of sources (defaults, environment, command-line arguments) with a defined precedence, declared once per knob and resolved the same way everywhere. And it's per-spawn: two substrates launched from one shell can be told apart — one with a capability enabled under key A, another with it off — the axis the "substrate as a general application host" direction needs.

When you drive the engine over MCP, configuration is per engine: you hand spawn_substrate the arguments for one substrate and give a loaded component its own typed config, independent of any other engine. When you author a capability or component, you declare each knob once on its config struct — that single declaration parses the value, supplies its default, validates it, and lists it for discovery.

Why it exists

Aether is assembled from many subsystems — capabilities, the runtime, the chassis — each with its own knobs, and all of them are configured together at startup. A single configuration standard gives them one way to declare a knob and one way to resolve it, and three properties follow from that: validation (a typo'd key, or a known key set to garbage, is caught at boot rather than swallowed by a default), discovery (one listing of every knob, its default, and what it does), and no duplicated parsing across subsystems.

The second reason is per-spawn configuration. Configuration enters a process once, at startup, and each channel addresses one audience (ADR-0162). Environment variables configure the process a person launches directly — the hub at a shell — and stop there: the hub and tunnel construct a forked child's environment rather than handing down their own, clearing AETHER_* entirely and copying only a shared allowlist of platform keys (locale, proxy, GPU and audio driver families, PATH / HOME, and the like). Exporting an aether knob on the hub therefore does not reach the substrates it forks. Per-spawn arguments are what configure one engine differently from the rest — they ride the spawn call to a single substrate as argv, the addressed machine channel — which is what the "substrate as a general application host" direction needs.

The model: layered sources, one struct per subsystem

A resolved value comes from a stack of sources, lowest precedence to highest:

typed defaults   <   config file   <   environment   <   argv

Argv overrides the environment, the environment overrides a file, a file overrides the declared default. The file is a sectioned TOML source supplied with --config <PATH> or the AETHER_CONFIG_FILE fallback; if neither is set, an engine boots exactly as env-then-argv configuration dictates.

Each subsystem owns its own config struct, in its own crate, declaring its own knobs — there is no central registry that every subsystem has to register into. "Its own crate" means the crate whose code receives the resolved value, not whichever crate the knob is named after: WindowConfig is a desktop-chassis boot knob group rather than the aether-window cap's config, because the chassis driver reads it and no window actor does. Capability module anatomy records where a cap's config file sits and the one-config-per-actor bound that goes with it. A #[derive(aether_substrate::Config)] on that struct is what unifies them: from the field annotations it generates the environment parsing, the argument (clap) layer, and the layered resolution, and a machine-readable description of every knob that the discovery dump walks. So the declaration stays next to the field that owns it, and parse, validate, and discover all come from that one declaration.

Resolution, validation, and discovery

Resolution is strict. At boot the chassis warns on any AETHER_* variable that no registered knob claims — catching a typo without breaking on a stray CI variable — and hard-errors on a known key that's set but fails to parse, rather than falling through to the default. A bad value stops the boot with the key named, instead of a subsystem quietly running on a default you didn't ask for.

Parsing failure is distinct from post-parse semantic validation. A known field with malformed syntax hard-errors. A successfully parsed value can still be rejected or normalized by a subsystem's explicit policy—for example a window mode may warn and fall back when the requested monitor mode is unavailable. Document that behavior with the owning subsystem rather than hiding it as a parse default.

Discovery is the --print-config flag on any chassis binary: it walks the same declarations and prints every knob — its environment key, the value it resolves to and which source that value came from, its default, and its doc — then exits without booting. The walk is composition-derived (ADR-0156): composing a cap with with_actor accumulates that cap's config member into the chassis's aggregate, so the dump and the unknown-key sweep list exactly the knobs this chassis wires and nothing else — headless doesn't "know" the window and audio knobs it never composes. That listing is generated from the field annotations, so it can't drift from what the engine actually reads. It's the first place to look when you're unsure what a build will do with a given variable. The dump ends with a SECRETS section: the --secrets-dir directory and each secret file's name and status (set or invalid: <rule>), never a value.

Secrets are never knob values

A secret — an API key, a bearer token — is never a knob value, an argv flag, an environment variable, or a kind field, because every one of those surfaces is printed, inherited, journaled, or mailed somewhere (ADR-0235). Instead each secret is a named file in one directory, named by the --secrets-dir <path> flag every chassis root carries (a systemd unit passes --secrets-dir %d; there is no environment-variable form). Config holds only the name: a capability declares a SecretRefs knob — a comma list of <key>=<secret-name> — with the #[config(secrets)] field hint, and loads the values once in init:

#![allow(unused)]
fn main() {
/// Names only; the values live in the secrets directory (ADR-0235).
#[cfg(feature = "runtime")]
#[cfg_attr(feature = "runtime", config(secrets))]
pub secrets: SecretRefs,
}

The hint wires the validating parser on the env, file, and argv sides and binds the refs to the source stack's --secrets-dir when the member resolves; config.secrets.load()? in init then yields the values as Secrets — redacted Debug, read only through expose(), wiped on drop. Because the knob holds names, its --print-config row is safe to print. HttpConfig.secrets (--http-secrets) is the first consumer; the Supplying secrets recipe walks the operator side.

Configuring a running engine

Over MCP there are three ways to set configuration, from coarsest to finest:

• The environment configures the process you launch directly — the hub itself, or a chassis you run at a shell. Use --print-config, the owning config struct, and the active surface contract for exact knobs (AETHER_TICK_HZ, AETHER_SAVE_DIR, AETHER_AUDIO_OUTPUT, AETHER_ACTOR_TRACE_RING_SIZE, and the rest). It's fixed at launch and addressed to that one process: AETHER_* is scrubbed from a spawned engine's environment at fork (ADR-0162), so a knob exported on the hub does not reach the substrates it forks — configure those through per-spawn arguments below.
• A chassis config file is the persistent per-deployment layer. Pass --config path/to/chassis.toml on the chassis command line, or set AETHER_CONFIG_FILE as a fallback for the file path. The file is sectioned by subsystem, and a section name is the config struct's own cli_prefix (or the section its derive pins): [http], [http-server], [process], [rpc], [lifecycle], [actor], [scheduler], [settlement], [registry], [chassis], plus chassis-specific sections such as [window], [audio], [render], [tick], the desktop driver's [desktop], and the hub's [hub]. Environment variables still override file values.
• Per-spawn arguments are how a spawned engine is configured. spawn_substrate forwards its args to the substrate as command-line arguments — the addressed machine channel (ADR-0162) — so you can spawn one engine with --tick-hz … or --http-disable and leave the next one alone. Argv is where each engine's knobs live, since the hub's environment does not cross into its children. Flag names are mechanical: take the environment key, drop the AETHER_ prefix, lowercase, and hyphenate (AETHER_HTTP_TIMEOUT_MS → --http-timeout-ms).
• Component config is finer still: a component declares a typed Config and receives it at init. Because a guest's config crosses the wasm boundary as bytes, that type is a kind (schema-bearing): describe_component identifies the config kind and describe_kinds surfaces its shape. Over MCP, pass either load_component.config as inline structured JSON or config_path as a path to a JSON file; the harness schema-encodes that JSON to wire bytes before the byte-transparent chassis hands the decoded value to the guest's init. The two inputs are mutually exclusive, and config_path is JSON rather than pre-encoded wire bytes. This mirrors a native actor exactly: both declare type Config and receive it at construction (ADR-0090 §5). Boot config arrives at init; runtime reconfiguration, if a component wants it, is ordinary mail — the same kind can serve both.

Adding a knob

Author-side, a new knob is a field on the subsystem's resolved-config struct, not a fresh env::var read. Derive Config on the struct and annotate the field:

#![allow(unused)]
fn main() {
#[derive(Clone, Debug)]
#[cfg_attr(feature = "runtime", derive(aether_substrate::Config))]
#[cfg_attr(feature = "runtime", config(env_prefix = "AETHER_HTTP", cli_prefix = "http"))]
pub struct HttpConfig {
    #[cfg_attr(feature = "runtime", config(default = false))]
    pub disabled: bool,
    #[cfg_attr(feature = "runtime", config(default = [], csv_set))]
    pub allowlist: HashSet<String>,
}
}

The derive emits the environment-shaped layer, the clap argument overlay, and the from_env / from_argv_then_env resolvers. A numeric, Duration, or bool field carries only its default — confique's native parsing trims the value, treats an empty one as unset (falling back to the default), accepts the usual bool spellings (1 / true / yes / 0 / false / no), and hard-errors on a non-empty garbage value. The remaining field hints (env, cli_long, ms_duration, csv_set, nonzero, and secrets for a secret binding) carry the rest of the per-knob shape; parse names a custom parser for the rare field that needs one. Two things to know going in:

• Gate it on the runtime feature wherever the file itself reaches the wasm marker build, as above. A capability crate also cross-compiles to wasm, where the config machinery isn't available; the #[cfg_attr(feature = "runtime", …)] keeps that build carrying only the plain struct. A config file reached only through #[cfg(feature = "runtime")] mod runtime; is already gated once at the module and derives bare — aether-audio, aether-render, and aether-lifecycle are the live examples. Clippy runs host-native and won't catch a missing gate — the wasm32 cross-build in CI will.
• Wire the argument overlay into the chassis CLI so the per-spawn layer reaches your knob, and add a *_defaults_match test (the derive's literal default and your struct's Default are declared separately and a test keeps them honest).

The full walkthrough is the Adding a config knob recipe; the rule to carry is that a knob is declared once and resolved by the layer, never read ad-hoc.

A clippy.toml disallowed-methods entry bans std::env::var / std::env::var_os workspace-wide to keep that rule mechanical: a capability that reads the environment directly fails cargo clippy --workspace --all-targets --all-features -- -D warnings (the CI gate). A legitimately external read — the config machinery itself, a process-level tuning knob, a standard HOME / XDG lookup, a build script, or test code — carries an #[allow(clippy::disallowed_methods)] with a one-line reason stating why it is not cap config.

HttpConfig above is the live example: each field is a knob the deployer sets at boot, and what those knobs gate — the deny-by-default egress allowlist, the body cap, the per-request timeout — is the subject of HTTP egress.

Where to read more

• The rollout's design, the source-stack rationale, and the crate choice — ADR-0090.
• The spawn_substrate arguments and load_component config inputs in their tool context — The MCP harness.
• How a component declares and receives type Config — Components & lifecycle.
• The exact resolved knob inventory — the target chassis's --print-config output and its current config structs.

Hosted code and live replacement

Hosted code runs inside a substrate but remains actor-tier code. The host owns isolation and scheduling; the guest owns application state and mail behavior.

Component bytes in the hub registry are artifacts. A loaded component is an engine-local instance. Keep these identities separate when building, uploading, selecting, loading, and replacing.

Read Guest and native boundaries before changing exports, schema, feature tiers, or state migration.

Components & lifecycle

Governing ADRs: ADR-0074 (one actor model, two hosts), ADR-0024 (the dual-target FFI convention), ADR-0028 / ADR-0033 (the kind + handler manifests in the wasm), ADR-0090 (boot config), ADR-0038 / ADR-0101 (binding-stable hot-swap; the earlier drain design in ADR-0022 is superseded), ADR-0096 (several actor types per module, selected at load), and ADR-0114 / ADR-0099 (inline children and their lineage-correct addressing). The authoring and loading surface here is stable — it's what the reference component aether-kit (a multi-actor module: camera, camera-controller, and mesh viewer) is built on, and the signatures were read from the current SDK.

A component is the wasm host of an actor. The shared model — the #[actor] block, the init / wire / unwire lifecycle, handlers, addressing by type — is the actor model, and a component is one of its two hosts: an actor that arrives as wasm bytes, runs sandboxed behind the wasm wall, is reached by the substrate through an FFI trampoline, and can be loaded, dropped, and hot-swapped at runtime. The other host, a native capability, is the same shape against NativeActor.

This page is the wasm-specific machinery — read the actor model page first for how you actually write one; everything below is what's different because the actor lives across an FFI boundary and is loaded into a running engine.

export! and the FFI boundary

Authoring a component is authoring an actor (#[actor(root)] impl WasmActor for C), plus one line that doesn't exist on the native side:

#![allow(unused)]
fn main() {
aether_actor::export!(public = [Hello]);
}

Every entry is keyed — public = [..], boot = B, private = [..], generators = [..] — in any order, each key once; a bare or mixed call is a compile error that shows the keyed spelling. This line is required — without it the wasm has no FFI exports and the substrate can't drive the actor. It emits the #[no_mangle] entry points the host calls across the boundary (init, wire, receive_p32, unwire) and two wasm custom sections:

• aether.kinds.inputs — the manifest of every #[handler::<class>] kind (plus its doc, and whether a #[fallback] is present), generated by #[actor]. This is exactly what describe_component reads back to tell a live engine what the component accepts — your doc comments, filtered through a # Agent section if you write one, ride along.
• aether.namespace — present only when the module exports exactly one actor; it carries that actor's load namespace.

You never write extern "C" by hand. The _p32 suffix on the pointer-taking exports (receive_p32, on_rehydrate_p32) is the dual-target FFI convention (ADR-0024): wasm32 addresses are 32-bit, so those shims take u32 pointers and lengths. The exports are wasm32-only — a native (host) build of the same crate carries no FFI symbols, which is why a host-side test of a component drives it through the in-process transport rather than the FFI path.

Several actors in one module

A crate can export more than one actor type (ADR-0096):

#![allow(unused)]
fn main() {
aether_actor::export!(public = [RootManager, Panel, Toolbar]);
}

The module then carries every listed type's code behind one FFI surface, and the load path picks which type an instance becomes (below); a boot type is not listed again under public. A load or boot entry that names no export needs a module with exactly one selectable (non-boot) export; this module exports three, so a load must name one (ADR-0241 §9, superseding the multi-actor selection rule ADR-0138 first stated). A module that exports exactly one actor, export!(public = [Hello]), still loads without a selector. The aether.kinds.inputs manifest grows to one handler group per exported type, each tagged with its namespace, so the loader and describe_component read each type's surface separately. Grouping actors that belong together — a subsystem's coordinator and the panels it manages, say — into one module is the intended use: it ships and versions them as a unit, and lets a running instance spawn its module's actors as inline children (below).

The generators = [aether_bloomery_program::bundle] key names the one bloomery export generator. export! stays the only author entry; bundle is a function-like macro hook, not a second export macro and not a runtime trait. #[actor], #[program], and #[reactor] emit a same-name companion macro so use, pub use, and as aliases carry descriptor metadata. Generators receive actors (each type's namespace plus optional namespaced extensions) and exports (the types the module will bind). Ordinary actors have no extra extension; #[program] adds aether_bloomery_program and #[reactor] adds aether_bloomery_reactor. bundle keeps ordinary actors in exports and replaces every program and reactor with one root exported as aether.bloomery.bundle (BUNDLE_NAMESPACE), at the first one's position. Every bundle is content-addressed (see Publishing a module), so the root publishes as aether.bloomery.bundle.<module hash> while export: Some("aether.bloomery.bundle") still selects it. The root is instanced, and the bundle driver loads it keyed by its unit, so it is born at aether.bloomery.bundle.<module hash>:<unit key> (ADR-0240 D4). A module provides programs, reactors, or both; neither is a compile error. With programs, the root answers Invoke with Invoked through a per-seq inline child and writes aether.bloomery.programs. The program root relays each invocation's fetch-on-miss (ReadArtifact) and program API call (ApiCall) to the Invoke's sender, the driver, and relays the answer back (ADR-0240 D6). With reactors, it answers Warm, Event, and StatusQuery to the caller (Warmed / Evaluated / Status) and writes aether.bloomery.reactors. Each role keeps its own state. Program NAMEs are unique and Mode::Pure; reactor NAMESPACEs are unique string literals, checked with #[rule] idents as ReactorName / RuleName. Envelopes stay on their original types in actors; their other extensions are not copied onto the root. type Alias = T is not followed. The pipeline ends in one keyed no-generator export!. The root takes no config and is not a boot actor, and boot may not name a program or reactor. The root is one of the module's public exports, so export: Some("aether.bloomery.bundle") selects it.

#![allow(unused)]
fn main() {
aether_actor::export!(
    public = [Probe, ProbeWithConfig, Summarize, SourcePublisher, SourceWitness],
    generators = [aether_bloomery_program::bundle],
);
}

Publishing, spawning, loading, and dropping

A component enters and leaves a running engine by mail to the aether.component mailbox:

A bare Publish { code, configs } binds every namespace the module exports; identical bytes already bound are a no-op, and a first publish spawns the module's boot once (ADR-0147). A Spawn { namespace, key, parent, config } then stands up an instance of a published type: a live name answers SpawnResult::Live without re-init, an absent name answers Spawned, and a tombstoned name (§8, below) is refused. A namespace naming a native type — one linked into the binary rather than published from wasm — is refused: native types are composed by their chassis or parent, and spawning one by mail is not supported yet. aether.component.load combines the two in one call: it publishes wasm, then spawns the export it selects, keyed by name.

LoadResult::Ok carries the component's canonical path (so a caller that omitted name learns the key the load took) and the parsed ComponentCapabilities (handlers, fallback, doc, config) read from the manifest. It carries no mailbox id. A loaded component is named as a native actor is (ADR-0241 §5): a singleton registers at its published namespace NS, an instanced type at NS:KEY, and one loaded beneath a parent at parent/NS:KEY — that full string is the address you send subsequent mail to. A name nothing is registered at warn-drops; always use the path from LoadResult.

The successful reply is sent by the loaded component itself: the component host waits with the load's held reply until the guest's birth completes, then hands it off to the guest (as aether.component.load_delivered, ADR-0243 §9), and the guest answers the requester in its own name. An actor that loaded a component, native or guest, therefore takes ctx.sender() from the reply as its proven reference, and casts it once, there, to the protocol it will send the component, since an erased reference has no send verb (ADR-0231 §4); an embedder reads the stamped sender off the reply event and casts it the same way (ADR-0230). LoadResult::Err comes from the host, since no actor was loaded.

aether.component.drop names its component by target, its actor path; the host parses and proves it once at receipt, and an address with no live component answers Err naming it. aether.component.publish names no instance: the module's namespaces are the group it binds, or, for a successor, republishes.

The engine compiles each distinct module, and parses its custom sections, once per content hash (the BLAKE3 hash of its wasm bytes). Every load, module boot, and publish of the same bytes shares that one entry, which lives while its publication or any of them holds it. A publish checks each asset into the engine blob store as its own deduplicated blob held by the Module; the file bytes are let go once the module is built, while each asset lives exactly as long as a Module holds it (ADR-0241 §2). A guest reads its assets from its own module in every hook — init, wire, all handlers, on_rehydrate, and unwire — through the Assets ctx trait (ADR-0250). The surface has two verbs. asset_blob(name) hands the asset over as a Blob the guest holds by handle: the asset's own store entry, so no payload byte enters guest memory, and sending it on as a Blob field gives an in-process recipient the same bytes uncopied. It is the verb for a bundle that is mostly payload and routes an asset to the actor that makes it resident. asset(name) copies the asset into guest memory as a Vec<u8>, for an actor that parses or transforms the payload itself, or whose asset is small. A name the catalog does not carry answers None, as do both verbs. A Spawn of a published type always builds an instance that can read its assets, whoever asks for it: a boot manifest entry spawns this way, every instance it stands up, each replica of a replicas: N entry included, reading its assets from its own module in wire and in every later hook.

For a multi-actor module, the load also chooses which exported type to instantiate: aether.component.load takes an optional export selector — the target type's NAMESPACE — and stands up that type. Omitting it works only for a module with exactly one selectable (non-boot) export; a module exporting several is refused with an Err that names the exports. The LoadResult reports the selected type's capabilities. A selector naming a type the module doesn't export is a clean load error. A single-actor module is unambiguous, so an omitted selector is the whole story there.

The selected type's cardinality decides the load's key (ADR-0241 §5). A singleton is named by its namespace, so a load names no key for it: loading the singleton RootManager export with export: "ui.root" and no name registers it at ui.root, and a load that names any key for a singleton, its own namespace included, answers Err ("ui.root is a singleton; a load names no key") before the module publishes or anything is staged. An #[actor(instanced)] type is named by the load's name, or, when the load names none, by a counter the spawn allocates, as a native spawn_child with Subname::Counter is. Several instances of one type are therefore several loads of an instanced type; a replicated boot entry names every replica, so it must select one.

A load places the selected type at the component host, and a module boot type is always placed there, so each must declare root — #[actor(root)], or #[actor(instanced, root)] for an instanced type (ADR-0241 §5; see Declaring placement). The host reads the permission from the module's aether.actor.lineage section: a load whose selected type or boot type has no Root record, and a republish whose successor module's boot type has none, answer Err naming the type and the placements it does declare, before the module publishes or anything is staged. A type whose only placement is a parent — child_of(..) — is reached through that parent, never loaded at the host.

A drop closes the instance's trampoline entirely — nothing resident is left at that lineage — and its name tombstones for the engine's lifetime (ADR-0241 §8). Its route reads Dropped, so mail to it drops, every watcher receives a MonitorNotice, and a later load or spawn of the same name is refused as retired. A second drop at the path is refused. Load or spawn under a new key to bring the component back.

The close is what releases the guest: it runs the guest's unwire, answers each reply the guest still holds with its registered unanswered value, and drops the instance. The guest's unwire runs on its inline children first, children before their parents and deepest first, and on the entry actor last. The drop request is answered DropResult::Ok once that is done, so a caller that reads Ok reads a released guest. Mail the guest sends from unwire starts its own chains, outside the drop's, and is on its recipients' inboxes before the drop answers. The same close runs when nobody drops the instance and the engine tears down (ADR-0247 rule 5): a guest's unwire runs on every exit of its instance, so what its wire created can be released there.

A guest whose wire fails fails its birth (rule 3). A wire that returns Err answers the load or spawn Err with the guest's message; the guest then runs its unwire and is dropped. A wire that traps answers Err too, and the guest is released without running any more of its code. Either way no instance is left at the name, nothing the guest sent from wire leaves, and the name is free for another load. A boot manifest holding such a component fails the chassis build.

In practice you drive this through the MCP harness — publish(engine_id, selector, configs?), spawn(engine_id, namespace, key?, parent?, config?), load_component(engine_id, selector, namespace?, key?, config?, config_path?) (publish then spawn), terminate_substrate(...) — where selector resolves against the hub's content-addressed component registry (ADR-0116). Stage the wasm first with upload_component, which takes the path and reads the bytes for you (tool JSON never carries the wasm buffer; the wire kind does) and returns {hash, name} to load by. The component's kind vocabulary travels inside the wasm's aether.kinds custom section (ADR-0028), so the loader declares nothing — the substrate reads the types directly off the binary.

Publishing a module

The registry owner keeps a publication table: which code implements each namespace the engine publishes (ADR-0241 §3). Every native actor namespace linked into the binary is published when the registry is built. Every load and every publish binds its module before anything spawns or is swapped, through one owner batch that runs admission (§4) and then registers the module's kinds, all or nothing. Admission reads manifests only and refuses the whole module at the first failing namespace:

• Namespace. No exported namespace may be native. A module that holds one of the candidate's exported namespaces is its predecessor, and the candidate must export every namespace each predecessor exports: a namespace, once published, stays published until aether.component.unpublish withdraws it.
• Contract growth. Each exported namespace keeps its predecessor's rows and #[fallback]; rows may only be added. Each private child type (export!(private = [..])) a predecessor declares must still be declared, privately or as an export, with rows that only grow, so an inline child's alias never advertises a row its code no longer handles.
• Same hash. Publishing bytes whose hash already holds every one of its namespaces changes nothing; its kinds register again, which is idempotent.

Content-addressed modules. A module carrying the aether.content_addressed custom section (CONTENT_ADDRESSED_SECTION, one version byte whose presence is the whole signal) publishes each namespace it exports as NS.<hash>, its BLAKE3 module hash in 64 lowercase hex. Every build is then its own publication, so no build is another's predecessor and the rules above never compare two builds; loading the same bytes again is the same-hash no-op. Inside the module each type keeps its declared NS, which the export selector names. A content-addressed module may export no namespace longer than 191 bytes, so NS.<hash> stays one 256-byte segment; a longer one fails check-in, naming it. The bundle generator marks every bundle content-addressed, so a bundle root publishes as aether.bloomery.bundle.<module hash>, and each built bundle adds one publication.

A refusal answers LoadResult::Err or PublishResult::Err with module publish refused: <namespace> … (<rule>), and nothing is spawned or swapped. A publish of a successor publishes too, so its new kinds register. A load that publishes and is then refused at spawn (an unmet dependency, a failed module boot) leaves its module published: publish and spawn are separate steps. A published module stays resident until its namespaces are unpublished.

Operators unload a bundle by dropping its instances and unpublishing it: send aether.component.drop for each live instance, then aether.component.unpublish for its namespace. The unpublish is refused while any instance of the namespace is live, naming it. Withdrawing a publication does not resurrect tombstoned instance names: a later spawn at the same instance name is still refused as retired. Publishing the same bytes afterwards binds as a first publish, and the module's boot is not spawned again.

Boot configuration across the boundary

A component takes typed boot config the same way a capability does — declare a type Config and the chassis threads it into init (ADR-0090). What's wasm-specific is the carrier: the config rides as raw bytes on LoadComponent.config, encoded at the hub / MCP edge (SDK-typed, not wire-typed), so the substrate stays byte-transparent and never needs the config's Rust type. The MCP tool accepts the source value as inline structured config JSON or a config_path to JSON and performs that schema encoding; callers do not supply raw wire bytes through tool JSON. The two JSON sources are mutually exclusive. Omit type Config and the macro synthesizes () and injects the unused argument, so a no-config init stays terse. A declared config kind shows up in the component's advertised capabilities, so describe_kinds can resolve its schema.

A config may name a peer by path: an ActorPath<R> when the component needs one actor type, or a ProtocolPath<P> when it needs only a protocol. Its decode in init proves a ProtocolPath<P> against the routes published at that moment, so the peer is loaded first; a path that does not prove refuses the load. Naming a peer by protocol has the rules and the cost.

Spawning children inline

A running instance can stand up another actor from its own module without a fresh load, as an inline child (ADR-0114). The child shares the parent's wasm instance, slot, and run-token, yet is addressed and mailed like any actor. Where a native capability spawns any permitted Instanced actor with ctx.spawn_child, a component spawns one of the Instanced types its export! lists. The spawner declares the child in spawns(..), and the child lists every parent it may sit beneath in one child_of(..) list:

#![allow(unused)]
fn main() {
#[actor(root, spawns(Panel))]
impl WasmActor for RootManager {
    #[handler::tell]
    fn on_open_panel(&mut self, ctx: &mut WasmCtx<'_>, _: OpenPanel) {
        // -> Result<InlineChild<Panel>, SpawnError>: the child's `init` has run by the time this returns
        let _ = ctx.spawn_inline::<Panel>(Subname::Counter, &PanelConfig { /* … */ });
    }
}

#[actor(instanced, child_of(RootManager))]
impl WasmActor for Panel { /* … */ }
}

A ctx that omits its actor is typed by it: the macro reads WasmCtx<'_> as WasmCtx<'_, Self>, so the ctx reaches only the actors the component declares with depends(R). The ctx's type arguments are receiver, sender, mode: the actor first, the sender the handler requires second (Anyone when it states none), and the reply mode third (WasmCtx<'_, Self, Anyone, Unchecked>); spell WasmCtx<'_, Erased> for the untyped view.

The one bound RootManager: Spawns<Panel> carries both proofs the spawn needs. spawns(..) is the rebuild manifest: every export! that lists the spawner must list each declared child. The emitted Spawns<Panel> impl also names RootManager's position in Panel's child_of(..) list as its Placement, so a spawns(Panel) whose Panel does not list the spawner fails to compile at the declaration. The ctx reads its parent from its registry actor tag and returns SpawnError::ParentIdentityUnavailable when it has none. A child type whose declared dependency has no Live route is refused before its alias is allocated, as SpawnError::DependencyNotLive. The child's init runs in-process during the call, so an init failure comes back as SpawnError::InitFailed, and the returned InlineChild<Panel> checks later sends against Panel's handlers.

An erased or wire ctx does not know its actor, so it spells the spawn spawn_inline_child::<RootManager, Panel>(...), naming the parent, and the SDK checks that name against the ctx's registry actor tag before it allocates the alias. The dynamic spawn_inline_child_by_tag form remains available for data-driven assembly, but its generated export resolver rejects unknown exports, non-instanced actors, and actors whose child_of(..) does not name the actual runtime parent before allocating an alias.

A spawner declares the children it spawns through the typed inline verbs in #[actor(spawns(..))], and every export! that lists the spawner must list each declared child, because that list is the set a hot reload rebuilds. A child the host should never load by selector goes under private = [..]:

#![allow(unused)]
fn main() {
#[actor(root, spawns(Panel))]
impl WasmActor for RootManager { /* … spawns Panel inline … */ }

aether_actor::export!(public = [RootManager, Sibling], private = [Panel]);
}

Both halves are compile errors. A typed inline spawn of a child the spawner does not declare fails at the spawn site with "RootManager spawns Panel inline but does not declare it", and the note names spawns(..). A declared child the export! lists neither under public nor under private fails at the export! with "Panel is spawned inline by an actor this export! lists, but this export! does not list it", and the note names private = [..]. The check holds for another crate's actors too: a re-exported actor is an ordinary public entry, and the export! must list every child it declares.

Subname::Counter has the host assign a bare monotonic counter — 0, 1, … — for when you'll track it by the returned handle; Subname::Named("inventory") gives it a stable discriminator you can render and address. A spawned actor nests under the spawner's registered lineage under its own type's namespace (ADR-0099, ADR-0241 §6): if a loaded root is example.root and it spawns an example.inventory child named main, the child is example.root/example.inventory:main, and another generation adds another /<child NS>:<subname> node. Its MailboxId is the lineage fold, not hash(flat_name), and replies still route back to the spawner. The text after each : is that node's discriminator; / carries the ancestry. Spawn stays within the module the instance runs from; a different binary comes in through load_component, which carries its own code and kind vocabulary. This is what lets a wasm crate be a library of actors: a UI root spawns its panels, a zone manager spawns a per-entity actor for each thing in range — all inside the one resident instance, while each child keeps its own state.

A Spawn { parent } places an instanced type beneath a live parent whose type it declares child_of, at parent/NS:key; a singleton names no parent, so a parent naming one is refused. In SubstrateHarness, the door for this is spawn_child::<P, C>(&parent, key), which takes the parent's already-proven reference; the MCP spawn tool takes the same shape as parent?.

Hot reload

Every component can already be replaced in place — its wasm swapped behind a stable mailbox without a drop. State continuity across that swap rides two WasmActor hooks, on_dehydrate and on_rehydrate, that default to no-ops (ADR-0101). Override them to carry state forward: on_dehydrate serializes the old instance's state, and on_rehydrate recovers it on the replacement. There's no replaceable flag on export! and no subtrait — participation is the override itself. on_rehydrate's ctx is typed by the actor like a handler's (WasmCtx<'_> reads as WasmCtx<'_, Self>). Both hooks return Result<(), ActorInitError>, as init and wire do, and the save verbs return the save's error for the hook to pass on with ? (ADR-0249 §1):

#![allow(unused)]
fn main() {
#[actor(root)]
impl WasmActor for MyComponent {
    // init / wire / #[handler::<class>]s as usual …

    fn on_dehydrate(&mut self, ctx: &mut WasmDropCtx<'_>) -> Result<(), ActorInitError> {
        ctx.save_state_kind::<Snapshot>(0, &snapshot)?;   // hand state to the successor
        Ok(())
    }

    fn on_rehydrate(&mut self, ctx: &mut WasmCtx<'_>, prior: PriorState<'_>) -> Result<(), ActorInitError> {
        let snap = prior.decode_kind::<Snapshot>().ok_or("the saved snapshot does not decode")?;
        …
        Ok(())
    }
}

aether_actor::export!(public = [MyComponent]);
}

A returned error is how a replace hook says no, and a trap is a bug:

• on_dehydrate returns an error: the republish is refused naming the hook, and the old instance keeps running. It is handed back whatever it saved before the error, through its own on_rehydrate. on_dehydrate saves and does not send: WasmDropCtx has no send verb, and unwire is the hook that announces a departure.
• on_dehydrate traps: the engine aborts. The old instance is the live guest, and a guest that trapped runs no more code.
• A successor's on_rehydrate returns an error or traps: the republish is refused naming the hook, and the successor is dropped.
• The old instance's on_rehydrate returns an error when it is handed its state back after a refused republish: the instance closes. Each reply it holds is answered unanswered and its name is spent. A trap there aborts the engine.

The hooks #[actor] generates for a declared type State return the save's result and the decode's, so a successor whose type State kind changed shape refuses the republish. An author who wants a fresh start on a mismatch writes both hooks by hand and returns Ok(()) when decode_kind answers None. A resident inline child the successor cannot rebuild refuses the republish the same way: an unknown type, a placement the successor rejects, a config that no longer decodes, a failed init, or the child's own on_rehydrate error.

A Publish { code, configs } of a module that succeeds one already bound republishes every live instance of the module's namespaces as one group (ADR-0241 §7). Its members are every live instance of every namespace the module publishes; each keeps its hosted type, since the namespace is the type. Identical bytes answer Ok with no swap. Otherwise the host first runs every pre-check and refuses the whole republish, naming each instance a check refuses, before any member is touched:

• a content-addressed module, or one whose republish is already in flight;
• a module that declares a boot, or succeeds one that did (ADR-0147; "a boot module is not replaceable");
• a module publish admission refuses (see Publishing a module): a dropped namespace, or a row or #[fallback] a namespace or private child type narrows (ADR-0231 §5);
• a live instance, a member or an inline child one rebuilds, whose type adds a dependency with no Live route (ADR-0230);
• a config: an instance whose type's config kind changed needs a configs entry { path, config }, decoded strictly as the new kind; an unlisted instance with an unchanged kind keeps its stored spawn config; a live inline child of a type whose config kind changes cannot be given one.

A module with no predecessor — none of its namespaces is yet published — is not refused: it binds as a first publish.

Then each member prepares: its inbox gate closes, so mail for it waits; the candidate instantiates behind the same binding with its outbox held, the old guest runs on_dehydrate and is kept, the correlation cursor, reply table, request contexts and watches move to the candidate, and it runs on_rehydrate and then wire, still with its outbox held. Once every member is ready the module publishes, and each member commits: the old guest runs unwire, whose mail leaves at once, then drops, and the candidate's held mail leaves on a chain of its own, with the mail its gate queued reaching the candidate in order. PublishResult::Ok { types }, each republished type with its capabilities, comes once every commit's chain has settled. A component that leaves both state hooks at their defaults swaps cleanly and comes back fresh from init. Resident inline children are rebuilt from the module's exported types and its export! private list, each under its old alias, and wire after their parent's wire; the spawns(..) check guarantees that list names every child a listed actor can spawn inline.

A refusal in any member's prepare (a failed init, an on_dehydrate that returned an error, a rejected state save, a carried context, a request's or a watch's, that the candidate does not declare (ADR-0139 §4), a failed rehydrate, or a failed wire), or a refused publish, aborts every member: each unwires its candidate exactly when that candidate wired, discards it, reinstates its old guest, still wired, with its reply table, counters and watches, hands it back the state its on_dehydrate saved through its on_rehydrate, with no second wire, and receives the mail its gate queued; nothing a candidate sent leaves. Only teardown outside that saved state and outside what wire built is not undone (ADR-0016 §4), so an on_rehydrate override should assign from prior rather than accumulate onto what the instance already holds. While a republish is in flight, a load of one of its namespaces and a drop of a member wait for the answer and then run against the code that won; a republish that arrives while a load of its namespaces is in flight waits for those births.

A component's watches on other actors stand across a republish with no code from its author (Watching another actor). The host moves each registration with the mailbox, and each watch's context rides the saved state whether or not the component overrides on_dehydrate, so the successor's handler runs with the context its predecessor stored, under the id its predecessor was given. A watched actor that closes while the component is prepared is reported to the guest that wins: its notice waits at the inbox gate with the rest of the mail. A successor's wire that watches finds the standing watch and takes its id, and an aborted republish never doubles a watch: the old guest never unwired, so it is still wired and runs no second wire. A successor whose handler for a watched type takes another context kind is refused when it no longer declares the old kind; one that still declares it gets an error in its log ring at the notice, and its handler does not run.

The load-bearing property is binding stability (ADR-0038): each swap replaces the wasm Module in place behind a stable mailbox handle, so the mailbox id, any route cache, and existing input subscriptions all stay valid across the swap. Peers mailing the component never learn it changed. Prefer save_state_kind (which carries schema identity through the kind system) over the raw save_state byte bundle unless you're persisting a non-kind blob or driving an explicit migration.